Build and check Swift snippets by nickpdemarco · Pull Request #42 · stlab/better-code

nickpdemarco · 2026-02-03T21:25:25Z

This PR adds support for checking Swift examples, copying the Rust-mdbook experience as much as possible: lines beginning with # will be omitted from the book output, but are used to compile the examples. Additionally, as a preprocessor step, all { ... } blocks are replaced with { fatalError() }.

# let a = [1, 2, 3]
# let x = 1
var i = 0
while (i != a.count && a[i] != x) {
  i += 1
}

A block marked with swift,ignore will not be built.

The examples can be checked with mdbook build. Several examples were slightly changed to pass the check. Without the two # lines above, the following error is emitted.

$ mdbook build better-code 
2026-02-03 16:23:39 [INFO] (mdbook::book): Book building has started
2026-02-03 16:23:39 [INFO] (mdbook::book): Running the html backend
2026-02-03 16:23:40 [INFO] (mdbook::book): Running the swift-test backend
2026-02-03 16:23:40 [INFO] (mdbook::renderer): Invoking the "swift-test" renderer
============================================================
Swift Code Example Testing
============================================================

Results: 19 passed, 1 failed, 20 total

------------------------------------------------------------
FAILURES:
------------------------------------------------------------

FAIL: chapter-2-contracts.md:238
/var/folders/zm/ll4504dd6dgbvy20y9ls2_hr0000gq/T/tmpwu0wf27f.swift:2:13: error: cannot find 'a' in scope
1 | var i = 0
2 | while (i != a.count && a[i] != x) {
  |             `- error: cannot find 'a' in scope
3 |   i += 1
4 | }

/var/folders/zm/ll4504dd6dgbvy20y9ls2_hr0000gq/T/tmpwu0wf27f.swift:2:24: error: cannot find 'a' in scope
1 | var i = 0
2 | while (i != a.count && a[i] != x) {
  |                        `- error: cannot find 'a' in scope
3 |   i += 1
4 | }

/var/folders/zm/ll4504dd6dgbvy20y9ls2_hr0000gq/T/tmpwu0wf27f.swift:2:32: error: cannot find 'x' in scope
1 | var i = 0
2 | while (i != a.count && a[i] != x) {
  |                                `- error: cannot find 'x' in scope
3 |   i += 1
4 | }

============================================================
2026-02-03 16:23:44 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2026-02-03 16:23:44 [ERROR] (mdbook::utils): Error: Rendering failed
2026-02-03 16:23:44 [ERROR] (mdbook::utils):    Caused By: The "swift-test" renderer failed

dabrahams · 2026-02-04T00:40:16Z

SwiftyLab/setup-swift is the reliable Swift installation action we've been using for Hylo, FWIW.

sean-parent · 2026-02-04T06:19:10Z

better-code/book.toml

+# Preprocessor to hide `# ` lines in Swift code blocks (like mdbook does for Rust)
+# Only strips lines for HTML output; swift-test backend sees the full code
+[preprocessor.swift-hidden]
+command = "python3 scripts/mdbook-swift-hidden.py"


Can you use the built-in mdbook support?

[output.html.code.hidelines] swift = "#"

Swift has # directives so might need a different character

It seems to work! Huge simplification, thanks for pointing that out.

better-code/book.toml

scripts/mdbook-swift-hidden.py

dabrahams · 2026-02-04T16:17:12Z

I got partway through reading the actual code which began to smell sloppy, and when I reached the point that it decided there was a case it wasn't going to support, and it would just exit with success (the output is not HTML), that was an almost certain sign that this was generated with AI and not carefully reviewed. Please forgive me if I've gotten that wrong, but Everything we check in here, even tooling should uphold the principles of better code. that includes real meaningful contract documentation for example.

nickpdemarco · 2026-02-04T18:33:26Z

Thanks for that feedback @dabrahams - I'll take a closer look and address what you've mentioned. In hindsight I should have made this a draft PR; it wasn't my intention to request a review, just share progress.

better-code/src/chapter-2-contracts.md

dabrahams · 2026-02-11T23:54:31Z

better-code/src/chapter-2-contracts.md

  ///   manager of any other employee.
-  public remove(_ e: EmployeeID)
-
-  ...


I'm not attached to the ellipsis, but do we /have/ to drop it? Something like this tool ought to be able to skip them.

No, we don't have to drop it. I could add support for simply removing those. Would it be sufficient to remove all lines that contain only whitespace and ... exactly?

better-code/src/chapter-2-contracts.md

dabrahams · 2026-02-12T00:00:49Z

better-code/src/chapter-2-contracts.md

 collection type:

 ```swift
+# struct DynamicArray<Element> {}


Not PR-related: is it a problem that we're using DynamicArray here and MyArray elsewhere?

better-code/src/chapter-2-contracts.md

dabrahams · 2026-02-12T00:04:17Z

better-code/src/chapter-2-contracts.md


 ```swift
-extension Collection {
+extension Collection where Element: Hashable {


Is this AI slop?

No. Returning Set<Element> requires the Element to be Hashable.

FAIL: chapter-2-contracts.md:1382 /var/folders/zm/ll4504dd6dgbvy20y9ls2_hr0000gq/T/tmpoeblzo53.swift:2:54: error: type 'Self.Element' does not conform to protocol 'Hashable' 1 | extension Collection { 2 | func bucketed(per bucket: (Element)->Int) -> [Int: Set<Element>] { [:] } | `- error: type 'Self.Element' does not conform to protocol 'Hashable' 3 | } 4 | (0..<10).bucketed { $0 % 2 } ============================================================

scripts/mdbook-swift-test.py

dabrahams · 2026-02-12T00:12:09Z

scripts/mdbook-swift-test.py

+
+
+@dataclass(frozen=True)
+class TestResult:


I don't think this should exist. You should instead propagate exceptions.

I disagree. Propagating exceptions would make it difficult to collect the test failures and present all of them at once. A propagated-exception model would encourage the caller to bail on the first test failure, but it's useful to users to see all of their failures in one place (so they don't have to needlessly rebuild). To support something like that with an exception propagation model, we'd need a cumbersome try/catch/append at the call site.

scripts/mdbook-swift-test.py

dabrahams · 2026-02-12T00:19:49Z

scripts/mdbook-swift-test.py

+    """Yields Swift code blocks from markdown content."""
+    for m in FENCE.finditer(content):
+        lang, ignore = parse_attributes(m.group(1))
+        if lang == "swift":


If we're only handling swift why is FENCE matching everything and why is parse_attributes returning a language.

First, creating a regex to match both swift,ignore and ignore,swift (which seemed useful to support) was needlessly complex. Second, it's entirely possible we'll want to add support for other languages (e.g. Dafny, already referenced in this chapter), so the added regex complexity didn't seem worth it.

scripts/mdbook-swift-test.py

dabrahams

I feel like I'm still reviewing AI-generated nonsense here. I'm not going further until you tell me I'm wrong, in which case we should probably have teams call to look at the code together and talk it over.

nickpdemarco · 2026-02-12T17:34:51Z

Thanks for your feedback @dabrahams. I've resolved or addressed the issues you've expressed so far.

nickpdemarco · 2026-02-12T18:45:33Z

better-code/src/chapter-2-contracts.md

  // Returns the `i`th element.
  @requires(i >= 0 && i < self.count)
-  fun getNth(i: Integer): T
+  fun getNth(i: Integer) -> T


Wait, @dabrahams is this swift or hylo? I'm seeing fun and : T which makes me unsure.

Add swift example checking to , fix broken examples, add to CI

607cd08

sean-parent approved these changes Feb 4, 2026

View reviewed changes

dabrahams requested changes Feb 4, 2026

View reviewed changes

use swift@v3

bcbaf31

nickpdemarco added 3 commits February 11, 2026 17:26

Simplify and docuemnt implementation

b455b0c

Remove obsolete comment

8c04b1e

Consistent spacing

a7496fb

dabrahams reviewed Feb 11, 2026

View reviewed changes

better-code/src/chapter-2-contracts.md Show resolved Hide resolved

dabrahams reviewed Feb 11, 2026

View reviewed changes

better-code/src/chapter-2-contracts.md Outdated Show resolved Hide resolved