diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 05923af..13408d9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,6 +1,6 @@ name: CI -# PureYAML is a root Swift package. CI must prove macOS, Linux, and WASM. +# PureYAML is a root Swift package. CI must prove macOS, Linux, Windows, and WASM. on: push: @@ -46,6 +46,20 @@ jobs: - name: Build and test run: bash scripts/check-linux.sh + windows: + name: Windows + runs-on: windows-latest + timeout-minutes: 45 + steps: + - uses: actions/checkout@v4 + - name: Setup Swift + uses: SwiftyLab/setup-swift@v1.12.0 + with: + swift-version: "6.3.2" + - name: Build and test + shell: pwsh + run: ./scripts/check-windows.ps1 + wasm: name: WASM runs-on: ubuntu-latest diff --git a/CHANGELOG.md b/CHANGELOG.md index 6048ef9..5780a0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,139 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Added - -- Add `PureYAML.parseStream(_:)` for multi-document YAML streams, including - explicit empty documents, document-end markers, and trailing comments before a - following document start. -- Add `PureYAML.Stream.Document`, document-indexed stream validation issues, and - stream validation APIs that preserve document indexes without changing - document-local validation paths. -- Add stream dumping for `[PureYAML.Stream.Document]` with deterministic - explicit document starts and existing emitter option support. -- Add merge-key expansion for plain `<<` and explicit `!!merge` keys, including - scalar merge mappings, sequence-of-mapping merge values, local override - behavior, and exact errors for invalid merge values. -- Add `PureYAML.parseTagged(_:)` and `PureYAML.parseTaggedStream(_:)` for - tag-preserving node trees, plus tagged validation rules for unsupported - built-in tags and tags applied to the wrong node kind. -- Add `PureYAML.Tagged.Constructor` for caller-owned tagged construction with - exact missing-handler and kind-mismatch errors, recursive path context, and an - explicit model-value fallback that preserves mapping order and duplicates - while erasing tags. -- Add first-class complex mapping keys through `Model.Pair.keyNode`, including - parsing, deterministic validation paths, duplicate-key checks, and block/flow - dumping for sequence and mapping keys. -- Add a real-world YAML fixture corpus with representative assertions for - short, medium, and very large documents, including OpenAPI and Kubernetes - examples. -- Add deliberately failing YAML fixtures that demonstrate exact validation - diagnostics, strict failures, and non-strict warning returns. -- Add non-throwing single-source and batch validation reports with exact parse - and validation diagnostics, optional warning-as-failure status, and Markdown, - YAML, and JSON rendering for application-owned report files. -- Add diagnostic-first validation reports, a raw-source preflight scanner, and - `Validation.ReportError` so production tools can return structured JSON or - YAML error bodies for damaged YAML without claiming parsed artifacts exist. - -### Changed - -- Tokenize YAML document start and end markers so scanner, event-parser, and - stream tests can pin exact document-boundary behavior. -- Harden block mapping and multiline plain-scalar parsing around nested - sequences, compact mapping entries, explicit complex keys, tagged keys, and - lower-column mapping siblings. -- Keep quoted `"<<":` and explicitly string-tagged `!!str <<` keys as ordinary - string keys while merge syntax is expanded during parsing. -- Keep Foundation-backed tags such as `!!timestamp` and `!!binary` as ordinary - model values in `parse(_:)`; callers that need tag diagnostics can use the - tagged parser and validator explicitly. -- Preserve anchors and tags on mapping values and sequence items whose actual - node starts on the following indented line. -- Harden real-world parsing for empty documents, indented root fragments, - JSON-style flow mapping pairs, and tab-indented files encountered in corpus - validation. -- Emit empty block collections as `[]` and `{}` so dumped YAML round-trips - without turning empty arrays or mappings into null values. +Nothing yet. ## [0.1.0] - 2026-06-05 ### Added -- Bootstrap PureYAML as a root Swift package with no external dependencies. -- Add the first pure-Swift YAML model, parser, and dumper milestone. -- Add tests for block mappings, block sequences, common scalars, comments, and - dump/parse round trips. -- Add path-aware YAML validation with duplicate-key checks, custom rules, and - warning collection. -- Add the internal parse event model with marks, scalar styles, collection - styles, alias events, anchor/tag metadata, and golden event tests for current - parser behavior. -- Add the internal UTF-8 reader and scanner token layer with tests for - comments, indentation, block entries, mapping indicators, flow delimiters, - quoted scalars, block scalar headers, anchors, aliases, tags, and source - marks. -- Add the internal scanner-token event parser for block collections, flow - collections, aliases, anchors, tags, and line/column parser failures. -- Add the internal event composer and wire public parsing through - scanner-token events into `PureYAML.Model.Value`, including flow collections, - block scalars, anchors, aliases, and duplicate-key validation coverage. -- Add YAML directive and document-marker scanning, tag-handle expansion, and - explicit built-in scalar tag composition for strings, integers, floats, - booleans, and nulls. -- Expand tests into focused parsing, dumping, model, validation, and parse-error - suites. -- Add macOS, Linux, and WASM verification gates and CI jobs, plus a local Linux - check that can run through Claw Mini's Lima VM. -- Add a single full local verification script and wire pre-push through the - macOS, Claw Mini Linux, and WASM gate sequence. -- Harden the changelog gate so local verification also sees unstaged source - edits, not only committed or staged changes. -- Add emitter options with a selectable scalar policy for quoted strings or - conservative plain-string output. -- Add opt-in literal block scalar emission for safe multiline strings, including - `|-` parsing support for stripped final newlines. -- Add opt-in flow collection emission for compact mapping and sequence output. -- Add emitter corpus tests and document the current emitter policy. -- Add Yams and CYaml attribution without copying their implementation into - `Sources/`. -- Add validation-rule predicates, a boolean validation-rule initializer, and - validator authoring rules. -- Add scalar typed Decodable and Encodable conversion APIs with exact - path-aware errors. -- Add unambiguous bracket-quoted validation paths for punctuation-heavy keys. -- Add keyed typed Decodable and Encodable conversion for mapping-backed structs. -- Validate YAML values before typed decoding so duplicate keys are rejected - deterministically. -- Add unkeyed typed Decodable and Encodable conversion for sequences, including - nested sequences and sequence properties on keyed structs. -- Add a fixture-backed sequence typed-conversion test corpus and a - forbidden-pattern verification gate for package, source, and test contracts. -- Add broader Codable compatibility coverage for dynamic mapping keys, nested - container round trips, keyed super coders, default `super` coders, and - deterministic unsupported-shape errors. -- Add an explicit research-compatibility rule requiring parser, emitter, - validation, and typed conversion work to start from PureYAMLResearch behavior - without copying implementation code. -- Add a fixture-backed scalar and explicit-tag compatibility corpus with exact - success, string-preservation, unsupported-spelling, and invalid-tag errors. -- Add a fixture-backed collection and anchor compatibility corpus with exact - parsed values, parse errors, duplicate-key validation diagnostics, and pinned - unsupported merge-key behavior. -- Add executable unsupported-gap fixtures for multi-document streams, complex - mapping keys, unsupported directives, unsupported built-in tags, merge-key - fallback behavior, and direct value-tree validation. -- Add fixture-backed literal block emission coverage for newly supported - multiline content and exact quoted fallbacks. -- Add downstream-shaped document fixtures for API-style documents, service - configuration decoding, and unsupported merge-key fallback behavior. -- Add usage and migration documentation that states tested APIs, support - boundaries, unsupported YAML behavior, and cross-platform verification gates. +- Bootstrap PureYAML as a root Swift package with one `PureYAML` library product, + no external SwiftPM dependencies, no C sources, no generated parser targets, + and no Foundation requirement in the library target. +- Add the core pure-Swift YAML model with ordered mappings, sequences, scalars, + duplicate-key preservation, and first-class complex mapping keys through + `Model.Pair.keyNode`. +- Add parser support for block mappings, block sequences, comments, flow + collections, quoted strings, literal and folded block scalars, anchors, + aliases, YAML directives, document markers, merge keys, complex mapping keys, + multi-document streams, and selected explicit built-in scalar tags. +- Add deterministic YAML dumping with block output by default, optional flow + collections, conservative plain scalars, conservative literal block scalars, + complex mapping key dumping, and multi-document stream dumping. +- Add tag-preserving parsing with `PureYAML.parseTagged(_:)` and + `PureYAML.parseTaggedStream(_:)`, plus tagged validation rules for unsupported + built-in tags and tags applied to the wrong node kind. +- Add `PureYAML.Tagged.Constructor` for caller-owned tagged construction with + exact missing-handler and kind-mismatch errors, recursive path context, and a + model-value fallback that preserves mapping order and duplicate keys. +- Add path-aware validation with duplicate-key checks, custom rules, rule + predicates, strict and non-strict behavior, warning collection, stream + document indexes, deterministic validation paths, and direct value-tree + validation for states ordinary loaders may collapse. +- Add diagnostic-first validation reports, raw-source preflight scanning, + `Validation.ReportError`, and Markdown, YAML, and JSON report rendering for + application-owned files or error bodies. +- Add scalar, keyed, unkeyed, nested, dynamic-key, dictionary-like, and + super-coder `Codable` conversion APIs with exact path-aware errors. +- Add fixture-backed compatibility coverage for scalar spellings, explicit tags, + collections, anchors, unsupported YAML gaps, literal block emission, downstream + documents, and deliberately failing validation fixtures. +- Add a real-world YAML fixture corpus with representative short, medium, large, + and very large documents, including OpenAPI, Kubernetes, GitHub Actions, Docker + Compose, Prometheus, and cert-manager YAML. +- Add macOS, Linux, Windows, and WASM verification gates, hosted CI, a full + local verification script, a pre-push hook, usage documentation, migration + boundaries, attribution, and release notes. ### Changed -- Lower the package tools version to Swift 6.1 for hosted macOS CI compatibility - and install Linux Swift toolchain prerequisites for the WASM CI job. +- Lower the package tools version to Swift 6.1 for hosted macOS CI compatibility. - Harden duplicate-key validation to use set membership while preserving exact diagnostics. - Make validation rules immutable after construction. @@ -147,7 +61,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 written in a different order than they were requested. - Make keyed default `superEncoder()` and `superDecoder()` use the standard `super` mapping key instead of the current mapping. -- Resolve Yams-compatible plain scalar spellings for `yes`/`no` booleans, - radix-prefixed integers, numeric separators, and `.inf`/`.nan` floats. +- Resolve Yams-compatible plain scalar spellings for `yes` and `no` booleans, + radix-prefixed integers, numeric separators, and `.inf` and `.nan` floats. - Broaden opt-in literal block emission while preserving exact parser round-trips for every emitted block scalar. +- Harden block mapping, multiline plain-scalar parsing, merge expansion, tagged + parsing, lower-column mapping siblings, indented root fragments, JSON-style + flow mapping pairs, tab-indented corpus files, and empty collection emission. diff --git a/README.md b/README.md index 67a921c..306d8f2 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,18 @@ # PureYAML -[![CI](https://img.shields.io/github/actions/workflow/status/mihaelamj/PureYAML/ci.yml?branch=main&label=macOS%20Linux%20WASM)](https://github.com/mihaelamj/PureYAML/actions/workflows/ci.yml) +[![CI](https://img.shields.io/github/actions/workflow/status/mihaelamj/PureYAML/ci.yml?branch=main&label=macOS%20Linux%20Windows%20WASM)](https://github.com/mihaelamj/PureYAML/actions/workflows/ci.yml) PureYAML is a dependency-free YAML package written entirely in Swift. -The goal is a Linux- and WebAssembly-compatible replacement for the YAML pieces -that currently force packages such as OpenAPIDoctor through C-backed parsers. -The package is intentionally strict about portability: +The goal is a Linux-, Windows-, and WebAssembly-compatible replacement for the +YAML pieces that currently force packages such as OpenAPIDoctor through +C-backed parsers. The package is intentionally strict about portability: - no external SwiftPM dependencies - no bundled C sources - no Foundation requirement in the library target - root Swift package layout -- macOS, Linux, and WASI build gates +- macOS, Linux, Windows, and WASI build gates ## Roadmap @@ -41,15 +41,15 @@ Parser Replacement Roadmap #8 is complete in main. ## Status -This repository has completed readiness for the first tagged release, version -0.1.0. Current main includes block mappings, block sequences, ordered mappings, -common scalars, quoted strings, comments, flow collections, literal and folded -block scalars, anchors, aliases, YAML directives, document markers, explicit -built-in scalar tags, merge-key expansion, complex mapping keys, +The current release is 0.1.0. It includes block mappings, block sequences, +ordered mappings, common scalars, quoted strings, comments, flow collections, +literal and folded block scalars, anchors, aliases, YAML directives, document +markers, explicit built-in scalar tags, merge-key expansion, complex mapping keys, multi-document stream parsing, and a matching dumper with block and flow output policies, including multi-document stream dumping with explicit document starts. It also includes path-aware validation for structural YAML checks such as -duplicate mapping keys, plus stream validation that preserves document indexes. +duplicate mapping keys, stream validation that preserves document indexes, and +diagnostic-first validation reports for damaged YAML input. Callers that need explicit tag metadata can use `PureYAML.parseTagged(_:)` or `PureYAML.parseTaggedStream(_:)` and run tagged validation over the preserved source-shaped node tree. @@ -79,8 +79,8 @@ but it does not copy their implementation into `Sources/`. See cross-platform gates. - [Migration and support boundaries](docs/MIGRATION.md): what PureYAML can replace today and which YAML features are deliberately unsupported. -- [Release process](docs/RELEASE.md): 0.1.0 checklist, verification commands, - tag commands, and release-publishing steps. +- [Release process](docs/RELEASE.md): verification commands, tag commands, and + release-publishing steps. ## Usage @@ -248,7 +248,8 @@ PureYAML must stay dependency-free and portable. Before merging changes: - Swift tools version: 6.1 - Package products: `PureYAML` - SwiftPM dependencies: none -- Hosted CI matrix: macOS build and test, Linux build and test, WASM build +- Hosted CI matrix: macOS build and test, Linux build and test, Windows build + and test, WASM build ```sh bash scripts/check-all.sh @@ -271,8 +272,7 @@ bash scripts/check-wasm.sh ``` The pre-push hook runs `scripts/check-all.sh` so local pushes exercise macOS, -Claw Mini Linux, and WASM before hosted CI repeats the macOS, Linux, and WASM -matrix. +Claw Mini Linux, and WASM before hosted CI repeats those gates and adds Windows. `scripts/check-wasm.sh` expects a Swift toolchain with a matching Swift Wasm SDK. For Swift 6.3.2, install the SDK with: diff --git a/Sources/Tagged/Tagged.Constructor.swift b/Sources/Tagged/Tagged.Constructor.swift index cd41e08..2751aea 100644 --- a/Sources/Tagged/Tagged.Constructor.swift +++ b/Sources/Tagged/Tagged.Constructor.swift @@ -85,7 +85,7 @@ extension PureYAML.Tagged.Constructor { var kind: PureYAML.Tagged.NodeKind var build: @Sendable ( PureYAML.Tagged.Node, - PureYAML.Tagged.ConstructionContext, + PureYAML.Tagged.ConstructionContext ) throws -> Value } diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index bc60216..3a804f8 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -117,7 +117,7 @@ explicit fallback value tree. This avoids silent compatibility drift. typed decoding when duplicate-key visibility matters. 5. Prefer typed `Codable` for known schemas and `PureYAML.Model.Value` for inspection, migration tooling, or unsupported-shape triage. -6. Run macOS, Linux, and WASM gates before publishing the migration. +6. Run macOS, Linux, Windows, and WASM gates before publishing the migration. ## When Not to Migrate Yet diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 83697d1..3d33fbf 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -1,15 +1,15 @@ # Release Process -PureYAML versioning is driven by Git tags. The current release target is 0.1.0. -Do not publish the tag until #32 records final local and hosted verification. +PureYAML versioning is driven by Git tags. The current release is 0.1.0. -## 0.1.0 Candidate +## 0.1.0 Release - Swift tools version: 6.1 - Product: `PureYAML` - SwiftPM dependencies: none - Source targets: Swift only, no C targets and no generated parser targets -- Hosted CI matrix: macOS build and test, Linux build and test, WASM build +- Hosted CI matrix: macOS build and test, Linux build and test, Windows build + and test, WASM build - Release notes file: `docs/releases/pureyaml-0-1-0.md` ## Local Verification @@ -37,8 +37,8 @@ bash scripts/check-linux.sh bash scripts/check-wasm.sh ``` -The Linux check must exercise build and tests. The WASM check must build the -library target with the configured Swift Wasm SDK. +The Linux and Windows checks must exercise build and tests. The WASM check must +build the library target with the configured Swift Wasm SDK. ## Hosted Verification @@ -54,12 +54,12 @@ The passing run must include all CI jobs: - macOS - Linux +- Windows - WASM ## Tag and Publish -Only run these commands after the local gates pass, hosted CI passes, and #32 is -updated with the final evidence. +Only run these commands after the local gates pass and hosted CI passes. ```sh git status --short --branch @@ -85,5 +85,5 @@ gh release view 0.1.0 --repo mihaelamj/PureYAML runtime files. - Any Swift source imports Foundation in the library target. - The changelog does not have a dated 0.1.0 section. -- The release notes omit the known deferred issues. -- macOS, Linux, or WASM CI is red or still running. +- The release notes omit known deferred issues. +- macOS, Linux, Windows, or WASM CI is red or still running. diff --git a/docs/USAGE.md b/docs/USAGE.md index 9842ebe..8f2c739 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -5,14 +5,13 @@ and typed-converting the YAML subset currently covered by the test corpus. ## Installation -The first release target is 0.1.0. After the tag is published, depend on the -tagged package version: +Depend on the tagged package version: ```swift .package(url: "https://github.com/mihaelamj/PureYAML.git", .upToNextMinor(from: "0.1.0")) ``` -Until that tag exists, use the `main` branch: +For unreleased development snapshots, use the `main` branch: ```swift .package(url: "https://github.com/mihaelamj/PureYAML.git", branch: "main") @@ -351,8 +350,9 @@ bash scripts/check-wasm.sh `scripts/check-all.sh` includes style, namespacing, forbidden-pattern, changelog, roadmap, SwiftFormat, SwiftLint, host build, host tests, Linux build -and test, and WASM build checks. The explicit Linux and WASM scripts are useful -when recording release or migration evidence. +and test, Windows build and test in hosted CI, and WASM build checks. The +explicit Linux and WASM scripts are useful when recording release or migration +evidence. ## Support Boundaries diff --git a/docs/releases/pureyaml-0-1-0.md b/docs/releases/pureyaml-0-1-0.md index 9c94b92..de0ef5b 100644 --- a/docs/releases/pureyaml-0-1-0.md +++ b/docs/releases/pureyaml-0-1-0.md @@ -9,50 +9,59 @@ entirely in Swift. - No external SwiftPM dependencies. - No C sources, generated parser targets, JavaScript tooling, or Foundation requirement in the library target. -- Pure Swift YAML model with ordered mappings, sequences, scalars, and duplicate - key preservation. +- Pure Swift YAML model with ordered mappings, sequences, scalars, complex + mapping keys, and duplicate-key preservation. - Parser support for block mappings, block sequences, flow collections, quoted strings, comments, literal and folded block scalars, anchors, aliases, YAML - directives, document markers, and selected explicit built-in scalar tags. + directives, document markers, merge keys, complex mapping keys, multi-document + streams, and selected explicit built-in scalar tags. +- Tag-preserving parsing and validation for callers that need explicit YAML tag + metadata before project-owned construction. +- `PureYAML.Tagged.Constructor` for caller-owned tagged construction policies. - Deterministic YAML dumper with block output by default, optional flow - collections, conservative plain scalars, and conservative literal block - scalars. + collections, conservative plain scalars, conservative literal block scalars, + complex key dumping, and multi-document stream dumping. - Path-aware validation with exact duplicate-key diagnostics, strict and - non-strict modes, warning collection, custom rules, rule predicates, and - direct value-tree validation for states ordinary loaders may collapse. + non-strict modes, warning collection, custom rules, rule predicates, stream + issue indexing, and direct value-tree validation for states ordinary loaders + may collapse. +- Diagnostic-first validation reports for damaged YAML, including raw-source + preflight diagnostics and `Validation.ReportError` for application-owned JSON + or YAML error bodies. - Typed `Codable` conversion for scalar, keyed, unkeyed, nested, dynamic-key, dictionary-like, and super-coder cases. -- Compatibility and downstream-shaped fixture coverage, including explicit - unsupported-gap tests. -- Local and hosted macOS, Linux, and WASM gates. +- Real-world fixture coverage, including OpenAPI, Kubernetes, GitHub Actions, + Docker Compose, Prometheus, and cert-manager YAML. +- Local and hosted macOS, Linux, Windows, and WASM gates. ## Support Boundary This is not a full YAML 1.2 implementation. The release intentionally ships a -tested subset with exact errors or exact fallback value trees for known gaps. +tested subset with exact errors, validation reports, or fallback value trees for +known gaps. Known deferred work is tracked in: -- #33: multi-document YAML streams -- #34: merge keys and complex mapping keys -- #35: tag-specific YAML types -- #36: fixture-backed validator corpus expansion -- #37: arbitrary `Any` load and dump API decision +- #41: real YAML file fixture corpus expansion. +- #42: strict and compatibility parsing modes with validation reports. +- #43: streaming scanner/parser path for humongous YAML files. +- #44: humongous real-world YAML specs as a first-class validation gate. ## Verification -The 0.1.0 release process requires #32 to record: +The 0.1.0 release process requires: - `bash scripts/check-all.sh` - hosted macOS CI - hosted Linux CI +- hosted Windows CI - hosted WASM CI The full gate includes style, namespacing, forbidden-pattern, changelog, roadmap, SwiftFormat, SwiftLint, host build, host tests, Linux build and test, -and WASM build checks. +Windows build and test, and WASM build checks. -## Installation After Tagging +## Installation ```swift .package(url: "https://github.com/mihaelamj/PureYAML.git", .upToNextMinor(from: "0.1.0")) diff --git a/docs/rules/README.md b/docs/rules/README.md index ea84aeb..cec54d4 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -17,7 +17,7 @@ Project-specific overrides: - Tests live in `Tests/PureYAMLTests`. - `Package.swift` must keep `dependencies: []`. - Public API must live under the `PureYAML` namespace tree. -- The package must build on macOS, Linux, and WASI. +- The package must build on macOS, Linux, Windows, and WASI. The broader rule files are retained for detailed guidance. When they include generic examples, apply the PureYAML-specific overrides above. diff --git a/docs/rules/cross-platform.md b/docs/rules/cross-platform.md index df27dc8..5aed5f0 100644 --- a/docs/rules/cross-platform.md +++ b/docs/rules/cross-platform.md @@ -1,26 +1,43 @@ -# Cross-platform Swift (Apple + Linux + Windows) +# Cross-platform Swift (Apple + Linux + Windows + WASI) -How to structure PureYAML's Swift so the same sources build and run on Apple platforms, Linux, and Windows without silent breakage. +How to structure PureYAML's Swift so the same sources build and run on Apple +platforms, Linux, Windows, and WASI without silent breakage. -Load on demand. Triggers: `canImport`, `Linux`, `FoundationNetworking`, `Darwin`, `Glibc`, `swift-system`, `swift-foundation`, cross-platform, manifest, `.when(platforms:)`, `os(Linux)`, `os(iOS)`, `os(macOS)`, `os(visionOS)`, `os(tvOS)`, Vapor, AsyncHTTPClient, Hummingbird. +Load on demand. Triggers: `canImport`, `Linux`, `Windows`, `WASI`, +`FoundationNetworking`, `Darwin`, `Glibc`, `WinSDK`, `swift-system`, +`swift-foundation`, cross-platform, manifest, `.when(platforms:)`, `os(Linux)`, +`os(Windows)`, `os(WASI)`, `os(iOS)`, `os(macOS)`, `os(visionOS)`, `os(tvOS)`. -Grounded in Swift Evolution and `swiftlang/swift-foundation`. The PureYAML engine targets macOS and Linux (a server-style Apple + Linux split), so it falls under Topology 2/3 below. Subprocess and shell-out are available on both macOS and Linux; the engine may use them. +Grounded in Swift Evolution and `swiftlang/swift-foundation`. The PureYAML +engine targets macOS, Linux, Windows, and WASI, so it falls under Topology 3 +below. The library target must not require platform-specific subprocesses, +shell-outs, C sources, generated parsers, JavaScript tooling, or Foundation. -## Linux portability and the platform seam (mandatory) +## Cross-platform portability and platform seams (mandatory) -The engine targets macOS and Linux. Two obligations follow: +The engine targets macOS, Linux, Windows, and WASI. Three obligations follow: 1. Guard every platform-divergent line, preferring `#if canImport()` over `#if os(...)` so future platforms inherit the right branch. -2. Check Linux availability before adding a dependency. Many Apple frameworks, and the packages that wrap them, do not build on Linux. +2. Check Linux, Windows, and WASI availability before adding any dependency, + framework import, filesystem behavior, or runtime assumption. +3. Keep the core library dependency-free. If a platform-specific feature ever + becomes necessary, put it behind a protocol seam outside the parser core. -When the same functionality needs a different implementation per platform, abstract it behind a protocol seam; do not branch at call sites. Define a foundation-only protocol (see [shared-protocols.md](shared-protocols.md)), implement it once per platform (a macOS target using the Apple package, a Linux target using a Linux-available package), and let the composition root wire the correct one (see [dependency-injection.md](dependency-injection.md)). The core depends only on the protocol. +When the same functionality needs a different implementation per platform, +abstract it behind a protocol seam; do not branch at call sites. Define a +dependency-free protocol (see [shared-protocols.md](shared-protocols.md)), +implement it once per platform, and let the composition root wire the correct +one (see [dependency-injection.md](dependency-injection.md)). The core depends +only on the protocol. ```swift -public protocol ClockService: Sendable { var now: Date { get } } +public protocol PlatformNameService: Sendable { var name: String { get } } #if canImport(Darwin) -let clock: any ClockService = DarwinClock() +let platform: any PlatformNameService = DarwinPlatformNameService() +#elseif os(Windows) +let platform: any PlatformNameService = WindowsPlatformNameService() #else -let clock: any ClockService = LinuxClock() +let platform: any PlatformNameService = PortablePlatformNameService() #endif ``` @@ -30,7 +47,12 @@ The rest of this rule depends on which topology your target is in. Mixing them s 1. **Apple-only.** iOS, macOS, plus optional visionOS/tvOS/watchOS. UI-heavy, SwiftUI or UIKit/AppKit primary. No Linux build, no server-side targets. 2. **Apple clients + Linux server (split package).** UI lives on Apple, one or more server products build to Linux. The Linux-buildable surface is narrow (typically a single server product). Apple-only stuff is wrapped in conditional product/target arrays in `Package.swift`. -3. **Cross-platform library or CLI.** Runs identically on Apple + Linux + Windows. No UI. Probably uses URLSession-via-FoundationNetworking, Darwin/Glibc conditionals, swift-system. The PureYAML engine lives here (macOS + Linux): both platforms support subprocess and shell-out, so the engine may spawn subprocesses when needed. +3. **Cross-platform library or CLI.** Runs identically on Apple + Linux + + Windows. No UI. Probably uses URLSession-via-FoundationNetworking, + Darwin/Glibc/WinSDK conditionals, swift-system. The PureYAML engine lives + here, with the stricter rule that the library target must also build for + WASI and therefore cannot rely on process spawning or platform filesystem + behavior. A "Linux UI" topology technically exists but is not production-grade. Do not try to render SwiftUI on Linux; if a server needs UI, ship HTTP responses (templates, JSON for an SPA), not native widgets. @@ -90,7 +112,7 @@ Avoid spreading platform conditioning across both Layer A and Layer C for the sa ## UI cross-platform patterns -These patterns (Patterns 1-7 and Pattern 13: iOS-only SwiftUI modifiers, UIKit/AppKit app shells, the forward-compat SDK shim, and the `@available(iOS ...)` examples) describe the planned native Apple UI app, NOT the PureYAML engine. The engine targets macOS + Linux and has no UI. Apply these only in the app tier. +These patterns (Patterns 1-7 and Pattern 13: iOS-only SwiftUI modifiers, UIKit/AppKit app shells, the forward-compat SDK shim, and the `@available(iOS ...)` examples) describe the planned native Apple UI app, NOT the PureYAML engine. The engine targets macOS, Linux, Windows, and WASI, and has no UI. Apply these only in the app tier. Linux UI is out of scope (no SwiftUI on Linux). @@ -465,7 +487,12 @@ Run only the test suites known to be Linux-buildable; gate the others with `#if If your repo ships an Apple-clients-plus-Linux-server split: -1. **Declare Apple platforms in `platforms:`**. There is no stable Linux entry in the SPM platforms enum; Linux support is implicit when the package builds on a Linux toolchain. For the engine (macOS + Linux), declare macOS only: `platforms: [.macOS(.v15)]`. A repo that also ships an Apple UI app tier adds `.iOS(.v18)` for that tier. +1. **Declare Apple platforms in `platforms:`**. There is no stable Linux, + Windows, or WASI entry in the SPM platforms enum; non-Apple support is + implicit when the package builds on those toolchains. For the engine, avoid + Apple-only platform declarations unless an Apple API genuinely requires a + minimum OS. A repo that also ships an Apple UI app tier adds `.iOS(.v18)` for + that tier. 2. **Document the Linux-buildable surface.** In the repo's `README.md` / `AGENTS.md`, name the products that build to Linux: e.g. "On Linux, build the server product only: `swift build --product tiledownserver`." Otherwise a new developer running `swift build` on Linux hits confusing errors from Apple-only targets. @@ -534,5 +561,5 @@ The `#else` arm is reserved for platforms you genuinely do not run on; every pla | C interop | `import Darwin` | `import Darwin` on Apple, none on server | `swift-system` or canImport(Darwin)/Glibc | | Logging | `os.log` directly | `canImport(os)` + `print` fallback or `swift-log` | `swift-log` or `canImport(os)` + fallback | | Tests | Swift Testing | Swift Testing, Linux-buildable suites separate | Swift Testing | -| CI | macOS only | macOS + Linux Docker job for the Linux product | macOS + Linux + (Windows) | +| CI | macOS only | macOS + Linux Docker job for the Linux product | macOS + Linux + Windows + WASI | | Linux UI | n/a | server-side: HTTP responses, not native widgets | n/a | diff --git a/docs/rules/linux-server.md b/docs/rules/linux-server.md index 51bdf3b..61f1afc 100644 --- a/docs/rules/linux-server.md +++ b/docs/rules/linux-server.md @@ -15,7 +15,10 @@ If your target runs on Linux in production (server, CLI binary, container worklo If the answer is "Apple-only iOS/macOS app, no Linux," skip this file; load `cross-platform.md` for the Apple-cross-platform patterns instead. -Note: the PureYAML engine targets macOS and Linux. Both support subprocess and shell-out, so the engine may spawn subprocesses. As a design preference, keep server-only concerns (this file's HTTP/database/signal patterns) in dedicated CLI/server targets rather than the core, so the core stays focused; this is an organizational choice, not a platform limitation. +Note: the PureYAML engine targets macOS, Linux, Windows, and WASI. The core +library must not require subprocesses, shell-outs, C sources, generated parsers, +JavaScript tooling, or Foundation. Keep server-only concerns from this file in +dedicated CLI/server targets rather than the parser core. ## 1. HTTP: AsyncHTTPClient, not URLSession diff --git a/docs/rules/verification.md b/docs/rules/verification.md index 9edcbae..342ca49 100644 --- a/docs/rules/verification.md +++ b/docs/rules/verification.md @@ -5,7 +5,7 @@ relevant gates. ## Required Gate -Run this before committing or reporting completion: +Run this local gate before committing or reporting completion: ```sh bash scripts/check-style.sh @@ -20,6 +20,8 @@ bash scripts/check-linux.sh bash scripts/check-wasm.sh ``` +Hosted CI must also pass the Windows job, which runs `scripts/check-windows.ps1`. + ## Claims and Evidence | Claim | Required evidence | @@ -32,6 +34,7 @@ bash scripts/check-wasm.sh | Builds on macOS | `swift build` exits 0 | | Tests pass | `swift test` exits 0 and reports zero failures | | Linux compatible | `bash scripts/check-linux.sh` exits 0 | +| Windows compatible | hosted `scripts/check-windows.ps1` exits 0 | | WASI compatible | `bash scripts/check-wasm.sh` exits 0 | If a tool is unavailable, say so explicitly and do not claim that gate passed. diff --git a/scripts/check-windows.ps1 b/scripts/check-windows.ps1 new file mode 100644 index 0000000..be099cb --- /dev/null +++ b/scripts/check-windows.ps1 @@ -0,0 +1,6 @@ +Set-StrictMode -Version Latest +$ErrorActionPreference = "Stop" + +swift --version +swift build +swift test