Mihaela Mihaljevic
c7ef8abfd9
Adopt the rules-swift pin-and-codify strategy in snapshot mode (third_party/rules-swift @97dc70f + sha256), add codified gates, a conformance audit ledger, and .github/workflows/rules-swift.yml (corpus-pin integrity required, full gate report mode). Remove the docs/rules mirror it supersedes (repo-specific files kept under docs/). Style and leak gates exclude the vendored corpus.
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# Agent Guide
|
|
|
|
Guidance for anyone writing code in PureXML.
|
|
|
|
> Working in **Google Antigravity** (Gemini)? Start with `GEMINI.md` (always-on
|
|
> rules) and `docs/onboarding-antigravity.md` (the full, literal, step-by-step
|
|
> procedure for the schema-conformance work).
|
|
|
|
## Rule Loading
|
|
|
|
At the start of a session, read this file and the applicable rules under
|
|
`third_party/rules-swift/` for the area being touched. Confirm by replying with
|
|
`rules-loaded` and name the files you loaded.
|
|
|
|
The canonical upstream Swift rule set is vendored at
|
|
`third_party/rules-swift/`, a pinned snapshot recorded in
|
|
`docs/rules-swift-corpus.sha256` and audited in `docs/rules-swift-audit.md`.
|
|
That checkout is the canon this repo is measured against; keep the
|
|
PureXML-specific constraints in this file as stronger project overrides.
|
|
|
|
For code changes, load at minimum:
|
|
|
|
- `third_party/rules-swift/code-style.md`
|
|
- `third_party/rules-swift/namespacing.md`
|
|
- `third_party/rules-swift/cross-platform.md`
|
|
- `third_party/rules-swift/testing.md`
|
|
- `third_party/rules-swift/core/verification.md`
|
|
- `third_party/rules-swift/core/commits.md`
|
|
- `docs/research-first.md` (when stuck: read the research repo and the literature before guessing)
|
|
- `third_party/rules-swift/core/no-shortcuts-first-principles.md`
|
|
- `third_party/rules-swift/core/proof-discipline.md` (when making correctness or conformance claims)
|
|
- `third_party/rules-swift/parsing-rules.md` (when changing parser behavior)
|
|
- `third_party/rules-swift/validation-rules.md` (when changing validation behavior)
|
|
|
|
Run the local gates before hand-off:
|
|
|
|
```sh
|
|
scripts/check-rules-swift.sh
|
|
scripts/check-local-gate.sh
|
|
```
|
|
|
|
Install hooks once per clone:
|
|
|
|
```sh
|
|
scripts/install-hooks.sh
|
|
```
|
|
|
|
## What PureXML Is
|
|
|
|
PureXML is a dependency-free XML package written entirely in Swift.
|
|
|
|
The package must stay:
|
|
|
|
- pure Swift
|
|
- root Swift package layout, with `Package.swift` at repository root
|
|
- dependency-free
|
|
- Linux-compatible
|
|
- WebAssembly/WASI-compatible
|
|
- namespaced under `PureXML`
|
|
|
|
The private `PureXMLResearch` repo is for studying reference XML implementations
|
|
(libxml2/`expat`, Foundation's `XMLParser`, and the W3C XML 1.0 conformance
|
|
suite). Do not copy C code or upstream parser source into this public package.
|
|
Keep attribution in `ATTRIBUTION.md` accurate when compatibility work references
|
|
those projects.
|
|
|
|
Compatibility work must start from that research source. Before changing parser,
|
|
emitter, validation, or typed conversion behavior, inspect the matching
|
|
PureXMLResearch source or fixture and use it only to define behavior and tests.
|
|
|
|
## Namespace Rules
|
|
|
|
Every public type lives under the `PureXML` namespace tree and mirrors its
|
|
folder:
|
|
|
|
- `Sources/Model/Node.swift` declares `PureXML.Model.Node`
|
|
- `Sources/Parsing/Parser.swift` declares `PureXML.Parsing.Parser`
|
|
- `Sources/Emitting/Serializer.swift` declares `PureXML.Emitting.Serializer`
|
|
- `Sources/Validation/Validator.swift` declares `PureXML.Validation.Validator`
|
|
|
|
No top-level public concrete types except the root `public enum PureXML`.
|
|
|
|
## Dependency Rules
|
|
|
|
`Package.swift` must keep `dependencies: []`.
|
|
|
|
Do not add external packages, C targets, system libraries, Foundation-only
|
|
workarounds, JavaScript tooling, or generated parser dependencies without an
|
|
explicit maintainer decision.
|
|
|
|
## Verification
|
|
|
|
Before claiming a change is complete, run and cite:
|
|
|
|
```sh
|
|
bash scripts/check-style.sh
|
|
bash scripts/check-namespacing.sh
|
|
bash scripts/check-forbidden-patterns.sh
|
|
swiftformat . --config .swiftformat --lint
|
|
swiftlint --config .swiftlint.yml --strict
|
|
swift build
|
|
swift test
|
|
bash scripts/check-wasm.sh
|
|
```
|
|
|
|
Enable local hooks:
|
|
|
|
```sh
|
|
git config core.hooksPath .githooks
|
|
```
|