skit: SyntaxKit codegen CLI for v0.0.5

.github/workflows/SyntaxKit.yml

@@ -65,7 +65,7 @@ jobs:
         run: |
           if [[ "${{ steps.check.outputs.full }}" == "true" ]]; then
             echo 'ubuntu-os=["noble","jammy"]' >> "$GITHUB_OUTPUT"
-            echo 'ubuntu-swift=[{"version":"6.0"},{"version":"6.1"},{"version":"6.2"},{"version":"6.3"}]' >> "$GITHUB_OUTPUT"
+            echo 'ubuntu-swift=[{"version":"6.1"},{"version":"6.2"},{"version":"6.3"}]' >> "$GITHUB_OUTPUT"
             echo 'ubuntu-type=["","wasm","wasm-embedded"]' >> "$GITHUB_OUTPUT"
           else
             echo 'ubuntu-os=["noble"]' >> "$GITHUB_OUTPUT"
@@ -79,15 +79,12 @@ jobs:
     runs-on: ubuntu-latest
     container: ${{ matrix.swift.nightly && format('swiftlang/swift:nightly-{0}-{1}', matrix.swift.version, matrix.os) || format('swift:{0}-{1}', matrix.swift.version, matrix.os) }}
     strategy:
+      fail-fast: false
       matrix:
         os: ${{ fromJSON(needs.configure.outputs.ubuntu-os) }}
         swift: ${{ fromJSON(needs.configure.outputs.ubuntu-swift) }}
         type: ${{ fromJSON(needs.configure.outputs.ubuntu-type) }}
         exclude:
-          - swift: {version: "6.0"}
-            type: wasm
-          - swift: {version: "6.0"}
-            type: wasm-embedded
           - swift: {version: "6.1"}
             type: wasm
           - swift: {version: "6.1"}
@@ -298,7 +295,7 @@ jobs:
         swift:
           - version: "6.2"
           - version: "6.3"
-        android-api-level: [33, 34, 35, 36]
+        android-api-level: [33, 34, 35]
     steps:
       - uses: actions/checkout@v6
       - name: Free disk space

.github/workflows/swift-source-compat.yml

@@ -16,7 +16,6 @@ jobs:
       fail-fast: false
       matrix:
         container:
-          - swift:6.0
           - swift:6.1
           - swift:6.2
           - swift:6.3

.gitignore

@@ -78,6 +78,7 @@ playground.xcworkspace
 .swiftpm
 
 .build/
+.build-linux/
 
 # CocoaPods
 # We recommend against adding the Pods directory to your .gitignore. However

.vscode/launch.json

@@ -19,6 +19,26 @@
             "preLaunchTask": "swift: Build Release skit",
             "target": "skit",
             "configuration": "release"
+        },
+        {
+            "type": "swift",
+            "request": "launch",
+            "args": [],
+            "cwd": "${workspaceFolder:SyntaxKit}",
+            "name": "Debug skitrun",
+            "target": "skitrun",
+            "configuration": "debug",
+            "preLaunchTask": "swift: Build Debug skitrun"
+        },
+        {
+            "type": "swift",
+            "request": "launch",
+            "args": [],
+            "cwd": "${workspaceFolder:SyntaxKit}",
+            "name": "Release skitrun",
+            "target": "skitrun",
+            "configuration": "release",
+            "preLaunchTask": "swift: Build Release skitrun"
         }
     ]
 }

CLAUDE.md

@@ -75,6 +75,16 @@ Sources/SyntaxKit/
 4. Run `./Scripts/lint.sh` to ensure code quality
 5. Run `swift test` to verify functionality
 
+### Coding Conventions
+- **No global functions or variables.** Every function and `let`/`var` must be
+  nested inside a type (`struct`/`enum`/`class`) or an `extension`. This includes
+  declarations that look indented only because they sit inside a `#if … #endif`
+  conditional-compilation block (e.g. `Sources/skit/Runner.swift`) — those are
+  still file-scope globals and must be moved into a type. This is not currently
+  enforced by SwiftLint: a `custom_rules` regex can't reliably distinguish a
+  global nested in `#if` from a legitimate type member, so it needs an
+  AST-aware (SwiftSyntax) check to enforce. Until then, follow the rule by hand.
+
 ### Package Dependencies
 - **SwiftSyntax** (601.0.1+) - Apple's Swift syntax parser
 - **SwiftOperators** - Operator handling
@@ -93,8 +103,8 @@ Sources/SyntaxKit/
 2. **skit Executable** - Command-line tool for parsing Swift code to JSON
 
 ### Platform Support
-- Swift 6.0+ required
-- Xcode 16.0+ for development
+- Swift 6.1+ required
+- Xcode 16.3+ for development
 
 ### Testing
 - Uses modern Swift Testing framework (`@Test` syntax)

Docs/skit.md

@@ -0,0 +1,177 @@
+# `skit` — a SyntaxKit CLI for config-driven Swift codegen
+
+`skit` is a small CLI that takes a SyntaxKit DSL file as input and writes Swift source out the other side. The vision: pure data — JSON, YAML, your own format — drives a manifest written in the SyntaxKit DSL, and `skit` materializes it into idiomatic Swift you check in alongside everything else. Less hand-maintenance, fewer drift bugs.
+
+This doc walks through how `skit` is built. Two verbs, one wrap-and-spawn pipeline, an output cache, and a careful toolchain story underneath. Where there are sharp edges, this doc names them.
+
+## Two verbs
+
+```
+skit run Input.swift          # SyntaxKit DSL → Swift source on stdout
+skit run Input.swift -o Out.swift
+skit run InputDir/ -o OutDir/ # walk **/*.swift and mirror rendered output
+skit parse < Input.swift      # Swift source → JSON syntax tree
+```
+
+`run` is the default subcommand. `skit Input.swift` is shorthand for `skit run Input.swift`. `parse` is a one-shot for the inverse direction (Swift source → SwiftSyntax tree as JSON) — useful for tooling that wants to introspect existing code.
+
+The remainder of this doc is about `run`, which is where the interesting design decisions live.
+
+## How `skit run` works
+
+A `.swift` input file looks like a SyntaxKit DSL expression at the top level:
+
+```swift
+// Models.swift
+Struct("Person") {
+    Variable(.let, name: "name", type: "String")
+    Variable(.let, name: "age", type: "Int")
+}
+```
+
+The input is not a complete Swift program. It has no `@main`, no `print`, no `let root = …`. `skit run` adds the boilerplate by wrapping the input in a `Group { … }` builder and a top-level `print` that renders the result:
+
+```swift
+// What `skit run` writes to a temp file before spawning `swift`:
+import SyntaxKit
+
+let __skit_root = Group {
+#sourceLocation(file: "/path/to/Models.swift", line: 3)
+Struct("Person") {
+    Variable(.let, name: "name", type: "String")
+    Variable(.let, name: "age", type: "Int")
+}
+#sourceLocation()
+}
+
+print(__skit_root.generateCode())
+```
+
+`skit` then spawns `swift` (the script-mode interpreter, not `swiftc`) on this wrapped file, captures stdout, and writes the result to the user's chosen output target.
+
+Three things deserve a closer look:
+
+**Imports get hoisted.** The wrapper has to start with `import SyntaxKit` so the DSL types are available. Any additional `import`s the user writes need to live at the top of the file, not inside `Group { … }`. `skit` parses the input with SwiftSyntax, peels off the leading `import` declarations, and lifts them into the wrapper preamble. Anything else (declarations, expressions, top-level types) stays in the body.
+
+**`#sourceLocation` keeps diagnostics readable.** When the spawned `swift` emits a compile error, it reports a line number in the wrapped temp file, which is meaningless to the user. The `#sourceLocation` directive remaps body diagnostics back to the original input path and line. Errors in the wrapper preamble (the `import` block, the `Group { … }` opening) still reference the temp file — `skit` rewrites occurrences of the temp path in stderr to the input path as a fallback, so users see something coherent.
+
+**`swift` runs in script mode.** Running `swift Input.swift` invokes the Swift interpreter rather than going through `swiftc` + `ld`. Cold-start is around 700ms on macOS; warm spawns are around 110ms. The CLI's hot path leans into this — for batch input via `skit run InputDir/`, we spawn one `swift` per input file in parallel up to the active core count.
+
+## Output cache
+
+One layer, keyed by content hash. Lives under `~/Library/Caches/com.brightdigit.SyntaxKit/outputs/<sha>/output.swift` on macOS, `$XDG_CACHE_HOME/syntaxkit/outputs/<sha>/output.swift` (or `~/.cache/syntaxkit/outputs/<sha>/output.swift`) on Linux. On hit, `skit` skips the `swift` spawn for an input entirely.
+
+The fully-rendered output of an input gets cached by a hash of (input bytes, libSyntaxKit stamp, swift version, sorted `SKIT_*`/`SYNTAXKIT_*` env vars). On hit, total wall time is around 0.14s, dominated by hash + file read. Cold miss matches the warm script-mode baseline (~0.5s).
+
+`--no-cache` skips the cache.
+
+## Toolchain stamping
+
+Pre-compiled Swift modules (`SyntaxKit.swiftmodule`) are tightly coupled to the compiler that built them. Even patch-level differences fail to load:
+
+```
+error: module compiled with Swift 6.3 cannot be imported by the Swift 6.3.2 compiler
+```
+
+If `skit`'s bundled `lib/SyntaxKit.swiftmodule` doesn't match the user's `swift`, the spawned interpreter emits exactly this diagnostic and refuses to compile the wrapped input. The user is left staring at a cryptic message that doesn't name the actual problem.
+
+`skit` mitigates this by recording the build toolchain at bundle time. `Scripts/build-skit.sh` writes `lib/swift-version.txt` containing the output of `swift --version`. On startup, `skit run` reads the stamp and compares it to a freshly-captured local `swift --version`. Three paths:
+
+- **Match.** Proceed silently.
+- **Mismatch.** Print a clear error naming both versions and the rebuild command, exit 2. Skip with `--no-toolchain-check`.
+- **Missing stamp.** Print a one-line note and proceed. Older bundles built before this check existed shouldn't break.
+
+The comparison is exact-string match. Patch-level drift broke the originating bug, so anything less strict would just defer the failure to the cryptic message we're trying to avoid.
+
+**What this doesn't do**: it doesn't fix the mismatch, just surfaces it. The fix is to re-run the release script with the user's current toolchain. The auto-rebuild path — bundle SyntaxKit sources alongside the prebuilt module and recompile transparently when the stamp doesn't match — is tracked as [issue #157](https://github.com/brightdigit/SyntaxKit/issues/157).
+
+## Timeout watchdog
+
+The spawned `swift` is the only unbounded piece of `skit run`'s hot path. The wrap step is microseconds. The output cache hits or misses in milliseconds. But the spawn itself runs *user code* — and that code is allowed to be arbitrarily slow, recursive, or stuck.
+
+`skit run` defaults to a 60s per-input timeout. On expiry it sends `SIGTERM`, gives a 5s grace, then `SIGKILL`. The wrapped input exits with code 124 — POSIX `timeout(1)`'s convention. `--timeout <s>` overrides the default; `--timeout 0` disables the watchdog entirely (useful for debugging genuinely long codegen).
+
+The implementation is `DispatchSemaphore.wait(timeout: deadline)` paired with a `process.terminationHandler` that signals on child exit. The Linux Foundation `Process.waitUntilExit()` hangs on already-exited children on some configurations, which is why `skit` uses the semaphore-based wait everywhere. Same story for pipe drains — sequential reads after the child exits can deadlock when either pipe (~64 KB buffer on Linux) fills before exit, so both pipes drain concurrently via `DispatchGroup`.
+
+## Sharp edges
+
+### `if`-in-`Group` crashes the Swift type-checker — [#158](https://github.com/brightdigit/SyntaxKit/issues/158)
+
+`CodeBlockBuilderResult` declares all the methods needed for `if`/`else` in a result builder (`buildEither`, `buildOptional`, `buildArray`), but using them surfaces a Swift type-checker bug:
+
+```swift
+let _ = Group {
+    if true {                    // ← error: failed to produce diagnostic for expression
+        Struct("A") { … }
+    }
+}
+```
+
+This is a Swift compiler bug, not a `skit` bug. The workaround is to hoist the conditional into a plain Swift function that uses **plain Swift `if`/`else`** (not a `Group { if … }` body) to return one of two `CodeBlock`s:
+
+```swift
+func optionalDebugField(_ include: Bool) -> any CodeBlock {
+    if include {
+        return Variable(.let, name: "debug", type: "Bool")
+    } else {
+        return Group {}   // empty Group as the "no-op" branch — there's no
+                           // public EmptyCodeBlock type
+    }
+}
+
+Struct("Config") {
+    Variable(.let, name: "name", type: "String")
+    optionalDebugField(buildIsDebug)
+}
+```
+
+The helper function itself can't use `Group { if … }` either — same crash. Plain Swift control flow only.
+
+### `@main` and top-level decl attributes don't work
+
+`@main` and other decl attributes (like top-level `@available`) at the start of the input fail to compile. The wrapper places the user's body inside `Group { … }`, where these attributes try to bind to a function-call expression rather than a declaration. Examples:
+
+```swift
+@main                    // ❌ error: expected declaration
+Struct("Person") { … }
+
+@available(iOS 17, *)    // ❌ error: expected declaration
+Struct("ModernView") { … }
+```
+
+The DSL has its own mechanism for attribute attachment — call `.attribute("Published")`, `.attribute("available", arguments: ["iOS 17", "*"])` on the `Variable`/`Struct`/etc. — which renders the attribute in the *output*, not on the DSL expression itself. That's the path users should take.
+
+### Comments don't carry through
+
+Swift comments in the input file (`// MARK: - Models`, block comments, inline `//` after a DSL line) don't render to the output. The input's comments are *only* for the input's author. To emit a comment in the rendered code, attach it to a `CodeBlock` via `.comment { Line(.doc, "…") }`.
+
+### `#if os(...)` is gen-time, not output
+
+A `#if os(macOS) … #endif` block in the input is evaluated when the wrapped file compiles, controlling whether the enclosed DSL expressions are part of the builder. It does *not* emit a `#if os(macOS)` directive into the rendered Swift output. If you want compile-time-conditional output, emit the `#if` lines as raw text via `VariableExp("#if os(macOS)")` (or write a small helper).
+
+## Platform notes
+
+**macOS** is the primary target. The build and release flows live in `Scripts/`; the bundle is portable across machines with the same Swift version.
+
+**Linux** is verified on `swift:6.0-jammy/aarch64`. One adjustment compared to macOS: the Mach-O `install_name` rewrite in `Scripts/build-skit.sh` is skipped — GNU `ld` doesn't accept the flag. The `-rpath` injection (which is what actually locates the dylib at runtime) works on both platforms.
+
+The Foundation.Process workarounds described earlier are Linux-driven. `Process.waitUntilExit()` blocks indefinitely on already-exited children on `swift:6.0-jammy/aarch64` — `skit` uses `DispatchSemaphore` everywhere a child wait is needed, and drains stdout/stderr pipes concurrently to avoid deadlocks when either pipe buffer fills.
+
+**Windows** is not supported.
+
+## What's deferred
+
+A few things were considered for v1 and explicitly punted:
+
+- **Auto-rebuild on toolchain mismatch** — [#157](https://github.com/brightdigit/SyntaxKit/issues/157). Today the user gets a clear error and a rebuild command; tomorrow `skit` should rebuild `libSyntaxKit` from bundled sources transparently and cache the result per Swift version. The stamp-and-detect path shipped in this release is the foundation; the rebuild fallback is the natural next step.
+- **Multi-file output from a single input** — out of scope. The folder mode handles N-inputs → N-outputs; if you need fan-out from one logical generator, split it into multiple input files.
+- **Sandboxing the spawned `swift`** — out of scope. The threat model is "you ran your own code", same as `swift Input.swift` by hand.
+- **HTTP / web-server form** — out of scope for the CLI. A long-lived server could share a warm interpreter and the caches across requests, but that's a different shape with its own isolation questions. Revisit later.
+
+## Reference
+
+- [`Sources/skit/README.md`](../Sources/skit/README.md) — per-target quick reference (flag table).
+- [`Scripts/build-skit.sh`](../Scripts/build-skit.sh) — release-bundle builder (use `--debug` for the fast iteration variant).
+- [`Docs/research/tuist-manifest-pipeline.md`](research/tuist-manifest-pipeline.md) — the manifest-pipeline pattern this CLI borrows from.
+- [Issue #154](https://github.com/brightdigit/SyntaxKit/issues/154) — original tracking issue.
+- [Issue #157](https://github.com/brightdigit/SyntaxKit/issues/157), [Issue #158](https://github.com/brightdigit/SyntaxKit/issues/158) — follow-ups.

Examples/Completed/attributes/dsl.swift

@@ -1,7 +1,10 @@
 Class("Foo") {
-    Variable(.var, name: "bar", type: "String", defaultValue: "bar").attribute("Published")
+    Variable(.var, name: "bar", type: "String", equals: "bar").attribute("Published")
     Function("bar") {
-        print("bar")
+        Call("print") {
+            ParameterExp(unlabeled: Literal.string("bar"))
+        }
     }.attribute("available", arguments: ["iOS 17.0", "*"])
     Function("baz") {
-}.attribute("objc")}.attribute("objc")
+    }.attribute("objc")
+}

Examples/Completed/blackjack/dsl.swift

@@ -1,7 +1,7 @@
 import SyntaxKit
 
 // Example of generating a BlackjackCard struct with a nested Suit enum
-let structExample = Struct("BlackjackCard") {
+Struct("BlackjackCard") {
     Enum("Suit") {
         EnumCase("spades").equals("♠")
         EnumCase("hearts").equals("♡")
@@ -28,29 +28,29 @@ let structExample = Struct("BlackjackCard") {
             Variable(.let, name: "first", type: "Int")
             Variable(.let, name: "second", type: "Int?")
         }
-        ComputedProperty("values") {
+        ComputedProperty("values", type: "Values") {
             Switch("self") {
                 SwitchCase(".ace") {
-                    Return{
+                    Return {
                         Init("Values") {
-                            Parameter(name: "first", value: "1")
-                            Parameter(name: "second", value: "11")
+                            ParameterExp(name: "first", value: "1")
+                            ParameterExp(name: "second", value: "11")
                         }
                     }
                 }
                 SwitchCase(".jack", ".queen", ".king") {
-                    Return{
+                    Return {
                         Init("Values") {
-                            Parameter(name: "first", value: "10")
-                            Parameter(name: "second", value: "nil")
+                            ParameterExp(name: "first", value: "10")
+                            ParameterExp(name: "second", value: "nil")
                         }
                     }
                 }
                 Default {
-                    Return{
+                    Return {
                         Init("Values") {
-                            Parameter(name: "first", value: "self.rawValue")
-                            Parameter(name: "second", value: "nil")
+                            ParameterExp(name: "first", value: "self.rawValue")
+                            ParameterExp(name: "second", value: "nil")
                         }
                     }
                 }
@@ -62,17 +62,14 @@ let structExample = Struct("BlackjackCard") {
     Variable(.let, name: "rank", type: "Rank")
     Variable(.let, name: "suit", type: "Suit")
 
-    ComputedProperty("description") {
-        VariableDecl(.var, name: "output", equals: "suit is \(suit.rawValue),")
-        PlusAssign("output", " value is \(rank.values.first)")
+    ComputedProperty("description", type: "String") {
+        Variable(.var, name: "output", equals: "suit is \\(suit.rawValue),")
+        PlusAssign("output", " value is \\(rank.values.first)")
         If(Let("second", "rank.values.second"), then: {
-            PlusAssign("output", " or \(second)")
+            PlusAssign("output", " or \\(second)")
         })
         Return {
             VariableExp("output")
         }
     }
 }
-
-// Generate and print the code
-print(structExample.generateCode())