fix(ci): prepare 0.1.0 release

This commit is contained in:
Mihaela Mihaljevic 2026-06-05 21:20:20 +02:00
parent 68883f2104
commit 3a90df095d
13 changed files with 177 additions and 198 deletions

View File

@ -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

View File

@ -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.

View File

@ -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:

View File

@ -85,7 +85,7 @@ extension PureYAML.Tagged.Constructor {
var kind: PureYAML.Tagged.NodeKind
var build: @Sendable (
PureYAML.Tagged.Node,
PureYAML.Tagged.ConstructionContext<Value>,
PureYAML.Tagged.ConstructionContext<Value>
) throws -> Value
}

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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"))

View File

@ -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.

View File

@ -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(<Framework>)` 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 |

View File

@ -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

View File

@ -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.

View File

@ -0,0 +1,6 @@
Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"
swift --version
swift build
swift test