PureYAML/docs/rules-swift/README.md

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/).

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/. 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/. 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 - 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 - 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 - namespacing discipline, file naming, one-type-per-file.
• namespacing.md - caseless enum vs struct vs class for namespace anchors.
• dependency-injection.md - no singletons, inject every collaborator through init, protocol seams.
• concurrency.md - Swift 6 strict concurrency: Sendable, actors, @MainActor.
• 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 - server-side operational rules for the serve command and any networking.
• testing.md - Swift Testing, @Test / #expect, test isolation.
• formatting-and-linting.md - SwiftFormat and SwiftLint, enforced by a pre-commit hook and again in CI.
• documentation.md - DocC catalogs and /// requirements.
• 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 - stay inside Apple's own SDKs and the Swift-native ecosystem; Linux falls back to C or C++ only.

Packages

• package-structure.md - workspace and package layout: one Package.swift under Packages/, many targets, Apps/ for app targets.
• package-architecture.md - single-responsibility targets with unidirectional dependencies.
• package-import-contract.md - per-target allowed imports; applies now, the engine and CLI are already two targets.
• shared-protocols.md - the cross-target protocol seam.
• 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/: 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 - core: the five rules that gate every package decision (single responsibility, explicit deps, granularity, naming, layer architecture).
• 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 - patterns for foundation, feature, middleware, API, component, and font packages, and for aggregators.
• exp/dependency-management.md - cross-package dependencies, platform-conditional code, avoiding cycles.
• exp/package-swift.md - the closure-with-local-variables pattern for the deps, allProducts, and targets arrays.
• exp/common-mistakes.md - anti-patterns paired with the canonical fix, for code review of Package.swift changes.
• exp/app-target.md - adding or modifying an app target (SwiftUI, UIKit, AppKit entry points).
• exp/testing.md - the per-package test target and cross-package test doubles (architecture angle; full rules in testing.md).
• exp/migration.md - extracting code into a new package or splitting a large one.
• exp/build-performance.md - the build-time rationale behind the granularity.
• exp/verification.md - the final checklist before an ExtremePackaging change is considered done.

Parsing and validation

• parsing-rules.md - parse first, validate second; the OpenAPIKit parsing idiom over any structured input.
• validation-rules.md - composable Validation<Subject> values, never imperative if-trees; every public type is validated or excluded with a reason, enforced mechanically.

UI

The UI rules live under 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 - 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 - 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 - the SwiftUI renderer: view architecture and identity.
• ui/uikit-views.md - the UIKit renderer: UIViewController/UIView adapters, diffable data sources, re-pull on the change signal.
• ui/appkit-views.md - the AppKit renderer: NSViewController/NSView adapters, withObservationTracking, programmatic menus.
• ui/view-models.md - view-model responsibilities and patterns.
• ui/components.md - the component system.
• ui/colors.md - the color system.
• ui/fonts.md - font registration in SPM packages.
• ui/pom.md - Page Object Model for UI tests: screens behind page objects, identifiers from one shared source.
• ui/flowspec.md - declarative UI scenarios driven by FlowSpec: one flow, many renderers, replayed headless and on-device.