feat: Introduce cargo-anvil for unified Rust build/CI scaffolding

[martin-kolinek]

Introduces cargo-anvil: a cargo subcommand that ships and maintains an opinionated, unified build/CI scaffolding for Rust workspaces. One cargo anvil invocation emits a complete, reviewable tree of GitHub Actions workflows, Azure DevOps pipelines, justfiles/anvil/ recipes, and managed regions in Cargo.toml / deny.toml / rustfmt.toml / .delta.toml / clippy.toml / spellcheck.toml. Subsequent runs keep the tree in sync as the tool's catalog evolves, while preserving any local customizations the adopter has made.

Why this exists

Every Rust repo in the oxidizer / oxidizer-github / ox-tools family hand-rolls its own CI on the same opinionated checks (fmt, clippy, deny, audit, miri, careful, mutants, llvm-cov, cargo-hack, semver-check, doc, aprz, …). The cost of keeping those copies in sync — toolchain bumps, lint updates, new advisory feeds, cross-OS matrix changes — is paid per-repo, by hand, every time. cargo-anvil centralizes the catalog in one place and renders it into the per-repo CI surface.

What an adopter gets

After one cargo anvil, the repo contains:

• .github/workflows/anvil-pr.yml + anvil-pr-impl.yml and composite actions under .github/actions/anvil-* for the PR tier (anvil-pr-fast, anvil-pr-test, anvil-pr-mutants, anvil-pr-runtime-analysis).
• .github/workflows/anvil-scheduled.yml + anvil-scheduled-impl.yml and matching actions for the scheduled (nightly) tier.
• An ADO mirror under .pipelines/ (when --backend ado is selected or autodetected).
• justfiles/anvil/ recipe tree (mod.just, checks.just, groups.just, tiers.just, tools.just, versions.just). Local just anvil-pr-fast, just anvil-clippy, etc. reproduce CI without any cargo-anvil binary present.
• Layered tool-setup recipes: each tool gets anvil-tool-<name>-install / -validate-prereqs, each check anvil-<check>-setup / -validate-prereqs, each group/tier the same pattern, all composed up to a global anvil-setup. CI jobs install only what they need.
• Managed regions spliced into Cargo.toml (opinionated workspace + per-crate lints), rustfmt.toml, deny.toml, clippy.toml, spellcheck.toml, .delta.toml, .cargo-heather.toml. Each region is delimited by # managed by cargo anvil / # end managed by cargo anvil.
• A sidecar .anvil.lock manifest tracking per-file and per-region checksums for the three-checksum update algorithm.

Design highlights

• Three impact tiers (modified, affected, required) backed by cargo-delta. Each check is tagged with the tier it scopes to; CI wiring emits one include-list env var per tier with a --skip sentinel for empty tiers. The required tier is included for tools whose correctness resolves through the dep graph (cargo doc, cargo hack, cargo udeps); the unscoped bucket is reserved for Cargo.lock- and PR-context-only checks (deny, audit, aprz, pr-title).
• Three update decisions (Write, LeaveAlone, Propose) keyed on a three-way comparison of (original-template, current-template, live-file) checksums, all tracked in the lock manifest. A user edit inside a managed region is preserved when the template hasn't moved; a template bump becomes a .anvil-proposed sidecar with a one-line summary, so customizations are never silently overwritten.
• Backend autodetection from origin's URL; explicit --backend github / --backend ado override; --no-backends for local-only.
• Cross-OS matrix defaults matching the surveyed-repo evidence. GitHub default: Linux/Windows × x86_64/aarch64 (4 legs, using GH's hosted ARM runners). ADO default: Linux + Windows x86_64 (ADO has no hosted ARM agents). Compile-sensitive checks matrix; text/metadata checks ride along on the same matrix to keep group definitions stable.
• Caching (GitHub actions/cache, ADO Cache@2) keyed on OS + arch + rustc version + lockfile-family hashes + versions.just hash, so toolchain bumps and catalog updates invalidate cleanly.
• Self-validation gate via .github/workflows/regenerate-check.yml — the one hand-written workflow that builds cargo-anvil from the PR's branch, runs cargo anvil --dry-run, and fails the PR if the in-tree state drifts from what the templates would render.

Verification

• 199 unit tests in crates/cargo-anvil/src/ (run/plan/decision/region/emit/workspace/manifest/checksum).
• 4 schema tests in tests/schemas.rs (every emitted TOML parseable; every emitted workflow valid against actionlint; ADO YAML indentation consistent; every emitted recipe just-parseable).
• 3 snapshot tests in tests/snapshots.rs covering the three representative backend combinations (local-only, GitHub-backend, ADO-backend) — full byte-exact emitted tree.
• 4 fixture tests in tests/update.rs covering single-crate (no [workspace]), opt-outs (emptied managed region preserved), customized (user edit inside a managed region preserved), migration (pre-existing hand-written Justfile / deny.toml / [profile.release] survive splicing).
• Dogfooded against ox-tools itself: this PR's workspace is the first adopter, so the full PR tier (anvil-pr-fast, anvil-pr-test, anvil-pr-mutants, anvil-pr-runtime-analysis) plus the scheduled tier runs against the very cargo-anvil build under review on every push.
• cargo-delta CLI and JSON shape verified by running the actual binary against this workspace; the impact-step shell scripts encode the real two-snapshot --baseline / --current flow.

Total: 210 tests green locally + 4 PR-tier groups × 4 OS legs + impact + scheduled-runtime tier all green in CI.

Documentation

Lives under crates/cargo-anvil/docs/:

• design/design.md — top-level design and CLI shape.
• design/local.md — the just recipe tree, impact env vars, daily-driver flow.
• design/github.md — owned reusable workflows, per-group composite actions, impact scoping.
• design/ado.md — owned stages templates, per-group step templates, 1ESPT composition guidance.
• design/checks.md — the opinionated catalog and per-group OS scope matrix.
• design/updates.md — the three-checksum state machine validated by fixture tests.
• verification.md — continuous-validation strategy (dogfooding + snapshot + fixtures + schema).
• implementation-plans/0000.md — initial implementation plan (history).
• implementation-plans/0001.md — design-vs-implementation reconciliation plan executed in this PR.

Naming

The crate, binary, recipe namespace, lockfile, env vars, and managed-region markers all use anvil (no ox- prefix). This keeps the tool open-sourceable outside the ox- brand. The forge metaphor (anvil = stable opinionated surface for forging per-repo build tooling) is mentioned in design/design.md once and intentionally absent from user-facing surfaces.

Follow-ups (not in this PR)

• Publish cargo-anvil to crates.io once a few in-tree adopters have shaken it out.
• 1ESPT-compliant ADO composition examples for repos that need them — cargo-anvil emits composable stages, not a 1ESPT extender; adopters compose the stages template into their compliance pipeline.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 95.56465% with 130 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.4%. Comparing base (9c14fe3) to head (01c92a8).

Files with missing lines	Patch %	Lines
crates/cargo-anvil/src/run.rs	91.8%	35 Missing ⚠️
crates/cargo-anvil/src/backend.rs	78.6%	32 Missing ⚠️
crates/cargo-anvil/src/plan.rs	96.1%	18 Missing ⚠️
crates/cargo-anvil/src/main.rs	0.0%	17 Missing ⚠️
crates/cargo-anvil/src/region.rs	97.8%	6 Missing ⚠️
crates/cargo-anvil/src/workspace.rs	97.7%	5 Missing ⚠️
crates/cargo-anvil/src/emit/github.rs	97.4%	4 Missing ⚠️
crates/cargo-anvil/src/emit/ado.rs	97.8%	3 Missing ⚠️
crates/cargo-anvil/src/emit/cargo_toml.rs	98.1%	3 Missing ⚠️
crates/cargo-anvil/src/emit/shared_configs.rs	97.4%	2 Missing ⚠️
... and 4 more

Additional details and impacted files

@@           Coverage Diff           @@
##            main     #33     +/-   ##
=======================================
+ Coverage   93.2%   95.4%   +2.1%     
=======================================
  Files         28      48     +20     
  Lines       1262    5029   +3767     
=======================================
+ Hits        1177    4799   +3622     
- Misses        85     230    +145     

Flag	Coverage Δ
linux	95.4% <95.5%> (?)
linux-arm	95.4% <95.5%> (?)
windows	59.4% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

⚠️ Breaking Changes Detected

error: failed to retrieve local crate data from git revision

Caused by:
    0: failed to retrieve manifest file from git revision source
    1: possibly due to errors: [
         failed when reading /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958/scripts/crate-template/Cargo.toml: TOML parse error at line 9, column 26
         |
       9 | keywords = ["oxidizer", {{CRATE_KEYWORDS}}]
         |                          ^
       missing key for inline table element, expected key
       : TOML parse error at line 9, column 26
         |
       9 | keywords = ["oxidizer", {{CRATE_KEYWORDS}}]
         |                          ^
       missing key for inline table element, expected key
       ,
         failed to parse /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958/crates/cargo_ensure_no_cyclic_deps/tests/fixtures/without_cycle/Cargo.toml: no `package` table,
         failed to parse /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958/crates/cargo_ensure_no_cyclic_deps/tests/fixtures/with_dev_cycle/Cargo.toml: no `package` table,
         failed to parse /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958/Cargo.toml: no `package` table,
         failed to parse /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958/crates/cargo_ensure_no_cyclic_deps/tests/fixtures/with_cycle/Cargo.toml: no `package` table,
         failed to parse /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958/crates/cargo_ensure_no_cyclic_deps/tests/fixtures/with_self_dev_dep/Cargo.toml: no `package` table,
       ]
    2: package `cargo-anvil` not found in /home/runner/work/ox-tools/ox-tools/target/semver-checks/git-origin_main/3b8d0ca833db6717e02d157ce4f59f148fa8d958

Stack backtrace:
   0: anyhow::error::<impl anyhow::Error>::msg
   1: cargo_semver_checks::rustdoc_gen::RustdocFromProjectRoot::get_crate_source
   2: cargo_semver_checks::rustdoc_gen::StatefulRustdocGenerator<cargo_semver_checks::rustdoc_gen::CoupledState>::prepare_generator
   3: cargo_semver_checks::Check::check_release::{{closure}}
   4: cargo_semver_checks::Check::check_release
   5: cargo_semver_checks::exit_on_error
   6: cargo_semver_checks::main
   7: std::sys::backtrace::__rust_begin_short_backtrace
   8: main

If the breaking changes are intentional then everything is fine - this message is merely informative.

Remember to apply a version number bump with the correct severity when publishing a version with breaking changes (1.x.x -> 2.x.x or 0.1.x -> 0.2.x).

[github-actions]

⚠️ Potential breaking changes detected

cargo semver-checks flagged the following on this PR. This is informational -- breaking changes between commits are expected; the major-version bump happens at release time, not on every PR.

cargo-heather

    Building cargo-heather v0.2.1 (current)
       Built [   5.803s] (current)
     Parsing cargo-heather v0.2.1 (current)
      Parsed [   0.002s] (current)
    Building cargo-heather v0.2.1 (baseline)
       Built [   5.953s] (baseline)
     Parsing cargo-heather v0.2.1 (baseline)
      Parsed [   0.002s] (baseline)
    Checking cargo-heather v0.2.1 -> v0.2.1 (no change; assume minor)
     Checked [   0.013s] 196 checks: 195 pass, 1 fail, 0 warn, 49 skip

--- failure method_parameter_count_changed: pub method parameter count changed ---

Description:
A publicly-visible method now takes a different number of parameters, not counting the receiver (self) parameter.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#fn-change-arity
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/method_parameter_count_changed.ron

Failed in:
  cargo_heather::CommentStyle::format_header now takes 2 parameters instead of 1, in /home/runner/work/ox-tools/ox-tools/crates/cargo-heather/src/comment.rs:129

     Summary semver requires new major version: 1 major and 0 minor checks failed
    Finished [  12.189s] cargo-heather

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[Ralf Biedert (ralfbiedert)]

Awww, I like the new name :)