# Swift coding rules (canonical) The canonical, scrubbed Swift coding rules. This is the **Swift domain**: the language- and platform-specific craft of writing Swift well. It sits on top of a vendored **core spine** of cross-cutting engineering discipline (see [`core/`](core/)). Each file here is one Swift rule area. `CONVENTIONS.md` is the short overview; this repository is the full set, with the cross-cutting discipline vendored under [`core/`](core/). Examples use a sample tile-based static site generator named Tiledown (the `TileKit` library plus the `tile-down` executable); replace the example names with your project's when you adopt these. ## The core spine The cross-cutting engineering discipline that governs *how* work is done and reported, independent of language or domain, lives in [`core/`](core/). The Swift rules here do not duplicate it; they build on it. Read the core spine first: - `core/no-shortcuts-first-principles.md` - the core ethic: no shortcuts, derive from first principles, hold to Knuth's standard of care. - `core/proof-discipline.md` - framing a correctness claim as separately provable layers, each with an explicit epistemic status. - `core/round-trip-transformation.md` - any two-way transform (parse/print, encode/decode) is one invertible description, proven by the round-trip law. - `core/first-principles-analysis.md` - depth target for analysis, plus measurement discipline (every number traceable to a command). - `core/verification.md` - no "done" without fresh command output. - `core/testing-discipline.md` - real tests on every change; a build is not a test. - `core/systematic-debugging.md` - reproduce, isolate, explain, then fix. - `core/brainstorming.md` and `core/writing-plans.md` - design and planning gates before non-trivial work. - `core/commits.md`, `core/git-discipline.md` - Conventional Commits; issues, labels, branches, PRs, remotes. - `core/file-naming.md`, `core/folder-grouping.md` - filename conventions and when to flatten one-file folders. - `core/rules.md`, `core/self-improve.md` - authoring rules for an agent, and when a recurring correction should become one. ## Where an app starts Before any UI framework is named, an app starts at its business rules and the domain that enforces them. - [business-rules-and-constraints.md](business-rules-and-constraints.md) - MANDATORY, the first artifact: the business rules written as explicit checkable statements, plus the constraints that bound them (which external REST services and their contracts, what compliance, which auth model), defined up front. - [domain-first.md](domain-first.md) - MANDATORY: an app starts at the domain and business rules, framework-free and headless-provable; the UI framework is the last, reversible, and plural choice, never the first decision. ## Language and platform craft (engine, today) - [code-style.md](code-style.md) - namespacing discipline, file naming, one-type-per-file. - [namespacing.md](namespacing.md) - caseless `enum` vs `struct` vs `class` for namespace anchors. - [dependency-injection.md](dependency-injection.md) - no singletons, inject every collaborator through `init`, protocol seams. - [concurrency.md](concurrency.md) - Swift 6 strict concurrency: `Sendable`, actors, `@MainActor`. - [cross-platform.md](cross-platform.md) - the same sources build on Apple platforms and Linux (and Windows where noted); guard platform-divergent code behind a protocol seam. - [linux-server.md](linux-server.md) - server-side operational rules for the `serve` command and any networking. - [testing.md](testing.md) - Swift Testing, `@Test` / `#expect`, test isolation. - [formatting-and-linting.md](formatting-and-linting.md) - SwiftFormat and SwiftLint, enforced by a pre-commit hook and again in CI. - [documentation.md](documentation.md) - DocC catalogs and `///` requirements. - [documentation-search.md](documentation-search.md) - verify API facts against an authoritative documentation index, not from memory: query it with keywords and read the results for Apple-API facts; it is a search engine, not an agent. - [framework-policy.md](framework-policy.md) - stay inside Apple's own SDKs and the Swift-native ecosystem; Linux falls back to C or C++ only. ## Packages - [package-structure.md](package-structure.md) - workspace and package layout: one `Package.swift` under `Packages/`, many targets, `Apps/` for app targets. - [package-architecture.md](package-architecture.md) - single-responsibility targets with unidirectional dependencies. - [package-import-contract.md](package-import-contract.md) - per-target allowed imports; applies now, the engine and CLI are already two targets. - [shared-protocols.md](shared-protocols.md) - the cross-target protocol seam. - [openapi-generated.md](openapi-generated.md) - rules for code generated from an OpenAPI document and the hand-written code that surrounds it. ## ExtremePackaging The granular packaging doctrine lives under [`exp/`](exp/): a monorepo split into many single-responsibility SPM packages with explicit, unidirectional dependencies, for isolated compilation, parallel builds, and per-package testability. The two core files are loaded on every Swift session; the rest load on demand. - [exp/critical-rules.md](exp/critical-rules.md) - core: the five rules that gate every package decision (single responsibility, explicit deps, granularity, naming, layer architecture). - [exp/when-to-create.md](exp/when-to-create.md) - core: the decision tree and DO/DON'T list for when a new package is warranted. - [exp/implementation-patterns.md](exp/implementation-patterns.md) - patterns for foundation, feature, middleware, API, component, and font packages, and for aggregators. - [exp/dependency-management.md](exp/dependency-management.md) - cross-package dependencies, platform-conditional code, avoiding cycles. - [exp/package-swift.md](exp/package-swift.md) - the closure-with-local-variables pattern for the `deps`, `allProducts`, and `targets` arrays. - [exp/common-mistakes.md](exp/common-mistakes.md) - anti-patterns paired with the canonical fix, for code review of `Package.swift` changes. - [exp/app-target.md](exp/app-target.md) - adding or modifying an app target (SwiftUI, UIKit, AppKit entry points). - [exp/testing.md](exp/testing.md) - the per-package test target and cross-package test doubles (architecture angle; full rules in [testing.md](testing.md)). - [exp/migration.md](exp/migration.md) - extracting code into a new package or splitting a large one. - [exp/build-performance.md](exp/build-performance.md) - the build-time rationale behind the granularity. - [exp/verification.md](exp/verification.md) - the final checklist before an ExtremePackaging change is considered done. ## Parsing and validation - [parsing-rules.md](parsing-rules.md) - parse first, validate second; the OpenAPIKit parsing idiom over any structured input. - [validation-rules.md](validation-rules.md) - composable `Validation` values, never imperative if-trees; every public type is validated or excluded with a reason, enforced mechanically. ## UI The UI rules live under [`ui/`](ui/). Any code with UI keeps the renderer thin over a framework-free model, and tests the flows from a shared scenario corpus. - [ui/pre-ui-layer.md](ui/pre-ui-layer.md) - MANDATORY: all display state and behavior in a framework-free, value-typed model (Domain + Surface); one `perform(Intent)` write channel; renderers are the only UI import, gated mechanically. - [ui/three-renderers.md](ui/three-renderers.md) - build the same UI in all three Apple SDKs (SwiftUI, UIKit, AppKit) over the one model: the architecture's payoff and a comparison instrument for which framework behaves best in a scenario. - [ui/swiftui-views.md](ui/swiftui-views.md) - the SwiftUI renderer: view architecture and identity. - [ui/uikit-views.md](ui/uikit-views.md) - the UIKit renderer: `UIViewController`/`UIView` adapters, diffable data sources, re-pull on the change signal. - [ui/appkit-views.md](ui/appkit-views.md) - the AppKit renderer: `NSViewController`/`NSView` adapters, `withObservationTracking`, programmatic menus. - [ui/view-models.md](ui/view-models.md) - view-model responsibilities and patterns. - [ui/components.md](ui/components.md) - the component system. - [ui/colors.md](ui/colors.md) - the color system. - [ui/fonts.md](ui/fonts.md) - font registration in SPM packages. - [ui/pom.md](ui/pom.md) - Page Object Model for UI tests: screens behind page objects, identifiers from one shared source. - [ui/flowspec.md](ui/flowspec.md) - declarative UI scenarios driven by [FlowSpec](https://github.com/mihaelamj/FlowSpec): one flow, many renderers, replayed headless and on-device.