fix(ci): prepare 0.1.0 release
This commit is contained in:
parent
68883f2104
commit
3a90df095d
16
.github/workflows/ci.yml
vendored
16
.github/workflows/ci.yml
vendored
@ -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
|
||||
|
||||
171
CHANGELOG.md
171
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.
|
||||
|
||||
32
README.md
32
README.md
@ -1,18 +1,18 @@
|
||||
# PureYAML
|
||||
|
||||
[](https://github.com/mihaelamj/PureYAML/actions/workflows/ci.yml)
|
||||
[](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:
|
||||
|
||||
@ -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
|
||||
}
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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"))
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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 |
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
6
scripts/check-windows.ps1
Normal file
6
scripts/check-windows.ps1
Normal file
@ -0,0 +1,6 @@
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
swift --version
|
||||
swift build
|
||||
swift test
|
||||
Loading…
Reference in New Issue
Block a user