Enforce Oxford spelling with Typos

[leynos]

Summary

• generate the repository spelling policy with the focused shared Python 3.14
  builder pinned to its reviewed merge commit
• add the Rust-Prover-reviewed grouped three-test phrase checker and enforce
  Typos 1.48.0 in the existing hosted build/test job
• correct prose while preserving state-graph values, workflow contracts, formal
  titles, executable examples, and machine literals
• validate existing diagrams locally with Nixie 1.1.0 and Merman CLI 0.7.0 on
  the repository's existing Rust 1.96 nightly

Validation

• make spelling (3 focused tests, 95.45% coverage)
• make check-fmt
• make check-state-graphs and byte-identical state JSON regeneration
• make markdownlint (25 files, 0 errors)
• make check-diagrams / make nixie
• make lint (Rustdoc, Clippy, and Whitaker)
• make typecheck
• make test (61 Nextest tests and 7 doctests)
• debug and release builds
• make all
• mbake validate Makefile
• Actionlint and YAML parsing
• builder/config/cache determinism
• protected-literal, identifier, and phrase audit
• git diff --check

Checkmake retains two unchanged recipe-length findings for the state-graph and
diagram checks.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Add an en-GB spelling policy with generated configuration, a phrase-rollout checker, Makefile targets, CI checks, cache exclusions, contributor guidance, and documentation spelling corrections.

Changes

Spelling enforcement

Layer / File(s)	Summary
Spelling policy configuration typos.local.toml, typos.toml	Define repository-specific exceptions and a generated en-GB oxendict correction map.
Phrase rollout checker scripts/typos_rollout_check.py, scripts/tests/test_typos_rollout_check.py	Load policy files, scan tracked files for prohibited phrases, report locations and corrections, and test policy, boundary, exclusion, and CLI behaviour.
Makefile spelling pipeline Makefile	Add spelling, configuration, phrase-check, helper-test, and generated-configuration targets; include spelling in the default and Markdown lint flows.
CI wiring and repository guidance .github/workflows/ci.yml, .gitignore, .markdownlint-cli2.jsonc, AGENTS.md, docs/...	Run formatting and spelling checks in CI, ignore tooling artefacts, document the workflow, and update repository text to match the enforced spelling.

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant Makefile
  participant Typos
  participant PhraseChecker
  CI->>Makefile: run make spelling
  Makefile->>Typos: check tracked Markdown with typos.toml
  Makefile->>PhraseChecker: reject prohibited phrases
  PhraseChecker-->>Makefile: return findings and exit status
  Makefile-->>CI: report spelling result

Loading

Possibly related PRs

• leynos/chutoro#174 — Implements the same Typos spelling gate, configuration generation, CI wiring, and phrase scanner.
• leynos/rust-prover-tools#28 — Uses the same rollout checker and Makefile spelling targets.
• leynos/agent-helper-scripts#49 — Adjusts the shared spelling target and generated configuration verification.

Poem

En-GB words march in line,
Typos guard the project gate,
Phrases find their proper sign,
CI checks before they wait,
Makefiles hum, and docs align.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (2 errors, 3 warnings)

Check name	Status	Explanation	Resolution
Testing (Overall)	❌ Error	The added tests are substantive, but the checker module has a SyntaxError at import, so the new tests cannot run and do not currently guard the behaviour.	Parenthesise the exception tuple in scripts/typos_rollout_check.py, then rerun the new pytest module and keep assertions on path, line, column, and exclusions.
Unit Architecture	❌ Error	scripts/typos_rollout_check.py still has Python 2 exception syntax, so the new checker cannot import and its query/command boundaries are not executable.	Parenthesise the exception tuple (except (OSError, UnicodeDecodeError):) and rerun the spelling tests and import check.
Developer Documentation	⚠️ Warning	Document the new spelling workflow, but the required .typos-oxendict-base.toml artefact is still undocumented in the developer docs and repository layout.	Add a note in docs/repository-layout.md and docs/developers-guide.md that .typos-oxendict-base.toml is internal/gitignored and required by the spelling gate.
Testing (Unit And Behavioural)	⚠️ Warning	FAIL: the new tests import scripts/typos_rollout_check.py, but it still contains except OSError, UnicodeDecodeError, so a SyntaxError stops the suite before any unit or CLI test runs.	Parenthesise the exception tuple, then rerun make spelling and the new pytest module so the local and CLI tests actually execute.
Testing (Property / Proof)	⚠️ Warning	FAIL: scripts/typos_rollout_check.py adds range-based masking and boundary invariants, but scripts/tests/test_typos_rollout_check.py only adds example cases, not property tests.	Add Hypothesis/proptest coverage for masking, phrase-boundary, exclusion, and ordering invariants; keep the current examples as complements.

✅ Passed checks (15 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the PR’s main change: enforcing Oxford spelling with Typos.
Description check	✅ Passed	The description matches the spelling-policy, Typos, prose-correction, and validation changes in the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 94.74% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
User-Facing Documentation	✅ Passed	PASS: The PR only adds contributor-facing spelling/CI tooling; docs/users-guide.md covers operator workflows, and no user-facing behaviour changed.
Module-Level Documentation	✅ Passed	All Python modules in scope carry top-level docstrings; the new checker explains its purpose and relation to Typos, and the test module states its testing role.
Testing (Compile-Time / Ui)	✅ Passed	No Rust/TypeScript compile-time behaviour is added, and the new CLI text output has focused deterministic tests rather than a brittle snapshot.
Domain Architecture	✅ Passed	The diff stays in CI, docs, and spelling tooling; no domain/business logic under src or crates was changed, so boundaries remain intact.
Observability	✅ Passed	Treat the change as non-production tooling: it only adds spelling CI/docs/script paths, with no runtime service, metrics, tracing, or alert surface to instrument.
Security And Privacy	✅ Passed	PASS: The new script only scans tracked UTF-8 text, the tests use fake phrases, and no secrets, credentials, or permission broadening were added.
Performance And Resource Use	✅ Passed	Bound the new work to one repo-wide pass over 99 tracked files and 7 ignore patterns; no new unbounded collections or repeated per-item I/O appear.
Concurrency And State	✅ Passed	No shared mutable state, async work, locks, or ordering-sensitive runtime logic were introduced; the changes are sequential spelling/build tooling only.
Architectural Complexity And Maintainability	✅ Passed	PASS: The spelling pipeline is narrowly scoped, documented in AGENTS/developers-guide, and uses small explicit helpers without cycles or speculative reuse layers.
Rust Compiler Lint Integrity	✅ Passed	No Rust files or Cargo manifests were changed, so this PR introduces no Rust lint suppressions or suspicious clone patterns.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch typos-roll-out-focused

---

_{Comment @coderabbitai help to get the list of available commands.}

[leynos]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 21-22: Update the “Setup uv” step to add the supported version
input for the installed uv release, matching the repository’s configured
toolchain version; keep the existing pinned action revision unchanged.

In `@docs/repository-layout.md`:
- Around line 85-89: Update the repository layout documentation near the typos
policy entries to include .typos-oxendict-base.toml, noting its role as the
shared base consumed by scripts/typos_rollout_check.py and typos.toml; if it is
intentionally gitignored or internal, explicitly label it that way instead.

In `@Makefile`:
- Around line 102-105: Update the exception handler in typos_rollout_check.py to
use a parenthesized tuple for OSError and UnicodeDecodeError, ensuring the
spelling-helper-test Ruff validation passes under Python 3.

In `@scripts/typos_rollout_check.py`:
- Around line 234-237: Update the exception handler in the file-reading logic to
use a parenthesized tuple, changing the except clause around read_text to catch
both OSError and UnicodeDecodeError with valid Python 3 syntax while preserving
the existing continue behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c55f603c-b1bd-44ed-b730-9aed6e5a0579

📥 Commits

Reviewing files that changed from the base of the PR and between d13776a and 5171a0f.

📒 Files selected for processing (17)

• .github/workflows/ci.yml
• .gitignore
• .markdownlint-cli2.jsonc
• AGENTS.md
• Makefile
• docs/adr/002-crate-layout-and-public-api.md
• docs/complexity-antipatterns-and-refactoring-strategies.md
• docs/developers-guide.md
• docs/development-plan.md
• docs/execplans/1-1-1-record-runtime-crate-split-as-adr.md
• docs/repository-layout.md
• docs/roadmap.md
• docs/rust-testing-with-rstest-fixtures.md
• scripts/tests/test_typos_rollout_check.py
• scripts/typos_rollout_check.py
• typos.local.toml
• typos.toml

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• leynos/rstest-bdd (auto-detected)

All four inline findings were addressed in 902c1eb, the threads are resolved, CodeRabbit confirmed the fixes, and replacement hosted checks pass.