Import Rust template documentation

[leynos]

Summary

This pull request targets origin/rust-project-enhancements and layers the generated-template documentation work onto the Rust project tooling enhancements already present on that base branch.

It updates the generated AGENTS.md contract, adds in-template documentation navigation, refreshes shared generated-project documentation, and tightens review findings that were in scope for this PR: keyword/category filtering, immutable cross installation, a Markdown grammar fix, and focused parent-template contract assertions.

Review Walkthrough

• Review template/AGENTS.md.jinja for the generated agent guidance. It now renders flavour-specific documentation expectations for application versus library projects and records the expected rigour for rstest, rstest-bdd, proptest, kani, and verus.
• Review template/docs/contents.md.jinja and template/docs/repository-layout.md.jinja for the new generated documentation navigation and generated repository layout reference.
• Review the refreshed generated documentation in template/docs/documentation-style-guide.md, template/docs/complexity-antipatterns-and-refactoring-strategies.md, template/docs/reliable-testing-in-rust-via-dependency-injection.md, template/docs/rust-doctest-dry-guide.md, and template/docs/rust-testing-with-rstest-fixtures.md.
• Review template/Cargo.toml.jinja for empty keyword/category filtering before rendering Cargo metadata.
• Review template/.github/workflows/{% if flavour == 'app' %}release.yml{% endif %}.jinja for immutable cross installation via the dereferenced commit for v0.2.5.
• Review tests/test_template.py for the rendered-output contract checks, including the split helper assertions for package metadata, Makefile contracts, local tooling, CI, release workflow configuration, and generated documentation.

Validation

• make test 2>&1 | tee /tmp/test-agent-template-rust-update-templated-documentation.out: 12 passed in 21.44s
• markdownlint-cli2 template/docs/rust-testing-with-rstest-fixtures.md: Summary: 0 error(s)
• git diff --check: clean
• rg --fixed-strings -- "v0.2.5" template tests: no matches
• rg --fixed-strings -- "--tag" template tests: only the negative assertion remains
• coderabbit review --agent: review_completed, findings: 0

Notes

This PR is intended to be reviewed against origin/rust-project-enhancements, not origin/main.

The snapshot-test request was left out of this PR because it would expand the parent-template assertion strategy and test dependencies beyond the in-scope review fixes. The current changes keep the existing rendered-output contract style while reducing the large contract test into focused assertion helpers.

During formatting, mdtablefix exposed a reproducible issue where wrapping can split GitHub Flavoured Markdown footnote reference markers such as [^4]. The affected generated documentation was repaired manually, and a draft issue with a minimal testcase was written locally to /tmp/mdtablefix-breaks-gfm-refs-issue.md.

[coderabbitai]

Warning

Review limit reached

@lodyai[bot], we couldn't start this review because you've used your available PR reviews for now.

Your plan includes 10 reviews of capacity. Refill in 7 minutes and 25 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 04986535-11f2-4326-99af-e09cb97a68b8

📥 Commits

Reviewing files that changed from the base of the PR and between 13d144e and ce6ca40.

📒 Files selected for processing (15)

• template/.github/workflows/{% if flavour == 'app' %}release.yml{% endif %}.jinja
• template/AGENTS.md.jinja
• template/Cargo.toml.jinja
• template/README.md.jinja
• template/docs/complexity-antipatterns-and-refactoring-strategies.md
• template/docs/contents.md.jinja
• template/docs/developers-guide.md.jinja
• template/docs/documentation-style-guide.md
• template/docs/reliable-testing-in-rust-via-dependency-injection.md
• template/docs/repository-layout.md.jinja
• template/docs/rust-doctest-dry-guide.md
• template/docs/rust-testing-with-rstest-fixtures.md
• template/docs/users-guide.md.jinja
• tests/__snapshots__/test_template.ambr
• tests/test_template.py

Walkthrough

The PR extends the Rust Copier template with build environment isolation for cross-compilation (pinning cross via commit SHA and clearing RUSTFLAGS), introduces four new documentation templates (contents index, user guide, developer guide, repository layout), standardises documentation architecture through updated style rules, expands AGENTS.md with detailed quality contracts for testing and observability, refines existing testing documentation, and comprehensively validates generated project structure and guidance through expanded test helpers and contract assertions.

Changes

Extended Rust Copier Template: Quality Contracts and Documentation

Layer / File(s)	Summary
Release workflow cross-compiler pinning and build isolation template/.github/workflows/{% if flavour == 'app' %}release.yml{% endif %}.jinja	CROSS_REVISION is pinned by commit SHA (88f49ff) instead of semver tag; installation uses --rev rather than --tag; release build step explicitly clears RUSTFLAGS environment to isolate repository-local linker settings from cross-compilation.
Cargo.toml keyword and category preprocessing template/Cargo.toml.jinja	package_keywords and package_categories are split on commas, trimmed, and filtered for empty entries; precomputed lists are rendered into Cargo.toml arrays, replacing previous inline trimming.
Four new documentation templates template/docs/contents.md.jinja, template/docs/users-guide.md.jinja, template/docs/developers-guide.md.jinja, template/docs/repository-layout.md.jinja	New contents index with three linked sections; user guide documenting tooling, Makefile targets, and project setup; developer guide covering contributor workflow and build commands; canonical repository-layout guide describing directory structure, ownership boundaries, and update procedures.
Documentation style guide canonicalisation template/docs/documentation-style-guide.md	Specifies canonical filename set; requires developers-guide to link repository-layout normatively; prohibits repository-layout embedding in other guides; updates ADR and roadmap code-block identifiers to plaintext; mandates contents file link to repository-layout.
README documentation section template/README.md.jinja	Replaces "Build Linkers" section with new "Documentation" section linking to contents index, user guide, and developer guide.
Testing and dependency-injection documentation refinements template/docs/reliable-testing-in-rust-via-dependency-injection.md, template/docs/rust-testing-with-rstest-fixtures.md, template/docs/rust-doctest-dry-guide.md, template/docs/complexity-antipatterns-and-refactoring-strategies.md	Clarifies non-determinism of direct std::env::var and SystemTime::now() usage; updates dependency-injection patterns to describe mockable traits; simplifies mockable Cargo.toml snippet to 0.3; expands integration-test guidance for temp_env; refines rstest fixture, async, and table formatting; adjusts doctest citations and cognitive-complexity line wrapping.
AGENTS.md quality contracts and guidance template/AGENTS.md.jinja	Detailed testing checklist covering happy/unhappy paths, end-to-end testing, and proof tools (proptest, kani, verus); Observability section prescribing structured tracing events, metric emission, and library vs application instrumentation; Project Documentation section requiring ADR-backed decisions and conditional user/developer guide updates per flavour.
Test infrastructure helper expansion and contract validation tests/test_template.py	render_project helper accepts explicit package_keywords, package_categories, and dev_target parameters. New test test_empty_package_keywords_and_categories_are_omitted validates empty keyword/category handling. Main contract test refactored into focused assertion helpers: assert_package_metadata_contracts, assert_makefile_contracts, assert_local_toolchain_contracts, assert_ci_contracts, assert_generated_documentation_contracts. New parameterised tests test_generated_tooling_contracts and test_generated_agent_instructions_include_quality_contracts validate generated project structure, documentation links, and AGENTS.md quality requirements including flavour-specific wording.

Possibly related issues

• Document deterministic timing test patterns and Clock-trait reuse strategy axinite#193: Main PR changes expand the dependency-injection testing documentation to explicitly mention using mockable traits like Env and Clock (and upgrade mockable to 0.3), directly addressing the issue's request for deterministic-timing/Clock guidance and mock-injection patterns.

Possibly related PRs

• leynos/dear-diary#26: Both PRs modernise the release workflow to install a pinned cross tool via commit SHA revision pinning and add environment-variable isolation (RUSTFLAGS), aligning on cross-compilation reliability and build environment hygiene during release.

Poem

Cross your fingers, clear those flags—
Build releases without rags.
Docs now link where they belong,
Tests assert the contracts strong.
Quality blooms where structure's clear.

🚥 Pre-merge checks | ✅ 15 | ❌ 5

❌ Failed checks (5 warnings)

Check name	Status	Explanation	Resolution
User-Facing Documentation	⚠️ Warning	Testing (rstest, rstest-bdd, proptest, kani, verus) and observability requirements (tracing, metrics) mandated in AGENTS.md are missing from users-guide.md and developers-guide.md.	Document mandatory testing frameworks and observability tools in users-guide.md and developers-guide.md templates; signpost AGENTS.md in README or contents.md.
Developer Documentation	⚠️ Warning	Execplan marked COMPLETE but not updated to reflect PR #33. Comprehensive developer guides and AGENTS.md quality contracts added, but execplan Progress/Outcomes sections still reference only PR #32.	Update execplan Progress section with PR #33 documentation work and revise Outcomes to reflect generated template guides, repository layout, and enhanced AGENTS contracts.
Testing (Compile-Time / Ui)	⚠️ Warning	PR adds ~400 lines of generated documentation. Tests use substring assertions rather than snapshots for structured, text-based output, missing validation of document structure and formatting.	Implement snapshot testing for generated documentation files using a stable snapshot library with explicit redaction of nondeterministic fields and focused semantic assertions validating content and structure.
Architectural Complexity And Maintainability	⚠️ Warning	Six assertion helpers, each used exactly twice, introduce indirection without reuse threshold or immediate simplification benefit, violating abstraction justification principles.	Inline assertions into test_generated_tooling_contracts and test_template_compiles with comments; re-extract only when a third use site appears.
Title check	⚠️ Warning	The title 'Import Rust template documentation' is overly broad and fails to capture the substantive scope of the PR, which encompasses tooling enhancements, Cargo metadata refinement, CI workflow pinning, test infrastructure updates, and generated documentation layering.	Expand the title to reflect the complete changeset. Use 'Import Rust template tooling enhancements and generated documentation' or similar to convey the tooling and documentation scope, and consider referencing the execplan (docs/execplans/rust-project-enhancements.md) per title requirements.

✅ Passed checks (15 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description comprehensively relates to the changeset by detailing specific template updates (AGENTS.md, documentation navigation, Cargo filtering, cross pinning, tests) and providing validation evidence demonstrating that the changes work as intended.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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.
Testing (Overall)	✅ Passed	Tests substantively exercise behavioural changes with rigorous assertions; would fail for plausible bugs like SHA mismatches, missing filtering, removed quality guidance.
Module-Level Documentation	✅ Passed	All modules have docstrings: Python modules (conftest.py, test_template.py) and Rust modules (stub.rs) with //! docs explaining purpose, utility, and relationships to other components.
Testing (Unit And Behavioural)	✅ Passed	Tests render the template and validate generated code via make all, cargo check, and contract assertions on generated files matching externally observable workflows.
Testing (Property / Proof)	✅ Passed	PR correctly recommends property testing (proptest), bounded model checking (kani), and exhaustive proofs (verus) in AGENTS.md guidance where invariants apply, with required substantivity constraint.
Unit Architecture	✅ Passed	Maintains clear separation: render_project() command with injected dependencies; assert_*() pure queries; tests compose units with coherent single responsibilities.
Domain Architecture	✅ Passed	This PR updates a Copier template generator, not a business application. The repository generates Rust projects but contains no domain logic requiring segregation from infrastructure.
Observability	✅ Passed	PR introduces only template, documentation, and test updates with no application runtime code changes. No operational behaviour is introduced, hence no observability instrumentation is required.
Security And Privacy	✅ Passed	No secrets leaked. Release workflow correctly uses GITHUB_TOKEN with minimal permissions, disables credentials, clears RUSTFLAGS. Tests verify contracts. Documentation uses fake test credentials.
Performance And Resource Use	✅ Passed	Jinja2 keyword processing is O(k≤5), YAML workflow loops iterate ~12 steps (constant), file I/O reads small files, no unbounded collections or memory accumulation, and tests execute quickly (~21s).
Concurrency And State	✅ Passed	PR introduces no concurrency code. Changes are configuration, documentation templates (.jinja, .md) and test infrastructure only.
Rust Compiler Lint Integrity	✅ Passed	Uses #[expect(clippy::print_stdout)] on app stub main(), not #[allow(...)]; no dead_code suppressions; no artificial lint appeasement; compiler can detect unused code.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch update-templated-documentation

---

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

[sourcery-ai]

Reviewer's Guide

Updates the Rust Copier template so generated projects have stricter Rust tooling (Cranelift + mold + lld, llvm-tools, Whitaker, nextest), richer Cargo metadata, pinned CI/release workflows, and new contributor/docs scaffolding, all enforced via expanded pytest-copier tests that render lib/app projects and run their public gates.

Sequence diagram for generated CI test and lint workflow

sequenceDiagram
  participant CI as GitHub_Actions_ci_yml
  participant Repo as Generated_Project_Repo
  participant RustSetup as setup-rust_action
  participant Mold as Install_mold_linker_step
  participant UV as setup-uv_action
  participant Tools as Install_template_test_tools_step
  participant CacheW as actions_cache_for_Whitaker
  participant WhitakerInst as Install_Whitaker_step
  participant Make as make_test_target

  CI->>Repo: actions_checkout
  CI->>RustSetup: leynos/shared-actions/setup-rust
  CI->>Mold: run apt-get install clang lld mold
  CI->>UV: astral-sh/setup-uv
  CI->>Tools: cargo binstall cargo-nextest
  Tools->>Tools: uv tool install mbake
  CI->>CacheW: actions/cache (whitaker paths)
  CI->>WhitakerInst: cargo install whitaker-installer (if cache-miss)
  WhitakerInst->>WhitakerInst: whitaker-installer --cranelift
  CI->>Make: make test
  Make->>Make: cargo nextest run || cargo test

Loading

File-Level Changes

Change	Details	Files
Tighten generated Rust tooling defaults (toolchain, linkers, coverage, linting) and expose them via the Makefile.	Add rust-toolchain components for clippy, llvm-tools-preview, and rustc-codegen-cranelift-preview. Introduce .cargo/config.toml with Cranelift dev backend and optional Linux mold linker config keyed by dev_target. Extend Makefile to select cargo-nextest with cargo test fallback, add lld-based coverage target, and run Whitaker consistently via a resolved binary path and PATH override. Document mold and lld usage plus coverage entrypoint in the generated README.	template/rust-toolchain.toml.jinja template/.cargo/config.toml.jinja template/Makefile.jinja template/README.md.jinja
Enrich Copier prompts and generated Cargo.toml metadata, including optional binstall metadata for app flavour.	Add copier.yaml questions for package_description, repository_url, homepage_url, package_keywords, package_categories, and dev_target. Render description, license, readme, repository, homepage, keywords, and categories into Cargo.toml. For app projects, generate package.metadata.binstall configuration using the repository URL and package name.	copier.yaml template/Cargo.toml.jinja
Revise template and parent CI workflows to pin actions, install required tools, cache Whitaker, and drive tests via Make/nextest with correct linker settings for coverage.	Update parent .github/workflows/ci.yml to pin actions, install clang/lld/mold, setup uv, install cargo-nextest and mbake, cache and install Whitaker from a pinned git revision, and run make test. Update template .github/workflows/ci.yml to mirror pinned actions, install linkers, configure coverage-specific linker flags, and call make-based gates. Introduce an app-only release workflow that cross-compiles binaries via cross, caches cross per revision, and publishes artifacts with pinned upload-artifact/download-artifact/gh-release actions. Pin delayed-pr-comment workflow action to a specific SHA.	.github/workflows/ci.yml template/.github/workflows/ci.yml template/.github/workflows/{% if flavour == 'app' %}release.yml{% endif %}.jinja .github/workflows/delayed-pr-comment.yml
Add and refine documentation for contributors, generated projects, and Rust testing guidance, plus a repository layout and contents index for generated repos.	Add root AGENTS.md, developers-guide.md, and users-guide.md describing parent-template purpose, tooling, and generated-project behaviour. Convert template AGENTS.md to a Jinja template with flavour-specific users-guide expectations and detailed testing/proof obligations. Introduce template docs: contents index, repository-layout reference (with flavour-specific paths), and tighten documentation-style-guide around canonical files and layout responsibilities. Polish existing Rust docs (rstest fixtures, doctest DRY, dependency injection, complexity guide) for clarity, formatting, links, and tables.	AGENTS.md docs/developers-guide.md docs/users-guide.md template/AGENTS.md.jinja template/docs/contents.md.jinja template/docs/repository-layout.md.jinja template/docs/documentation-style-guide.md template/docs/rust-testing-with-rstest-fixtures.md template/docs/rust-doctest-dry-guide.md template/docs/reliable-testing-in-rust-via-dependency-injection.md template/docs/complexity-antipatterns-and-refactoring-strategies.md
Expand pytest-copier tests to render realistic lib/app projects, run generated public gates, and assert key tooling/documentation contracts.	Introduce a shared render_project helper that populates realistic Cargo metadata and returns a CopierProject. Update existing tests to use render_project, assert that lib/app-specific files exist (including app release workflow), and run make all instead of raw cargo build in most cases. Add tests that validate Makefile (mbake), lint target (make lint), and cargo check across flavours. Add new tests that parse generated Cargo.toml via tomllib and assert metadata, linker config, coverage and Whitaker wiring, CI workflow contents, docs navigation, release workflow pins, binstall metadata, and flavour-specific AGENTS wording. Configure pytest-copier via a new copier_template_paths fixture in tests/conftest.py.	tests/test_template.py tests/conftest.py
Document and track the Rust tooling import work via an execplan and align README with the new template behaviour.	Add docs/execplans/rust-project-enhancements.md describing constraints, progress, decisions, and outcomes for the Rust template tooling work. Update root README to mention new metadata prompts, fast tooling defaults, and where user/developer docs live.	docs/execplans/rust-project-enhancements.md README.md
Add a disposable generated test stub to ensure nextest has at least one test in new projects.	Introduce template/tests/stub.rs with a simple assertion and clear guidance to delete once real tests exist. Wire documentation and tests to expect this stub file in generated repositories.	template/tests/stub.rs template/docs/repository-layout.md.jinja tests/test_template.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[leynos]

@coderabbitai please create a new GitHub issue for the following:

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

Outside diff comments:
In @tests/test_template.py:

• Around line 1-716: The file is over 400 lines; extract grouped assertion
  helpers into a dedicated test-support module and leave only test orchestration
  here: create a new module (e.g. tests/test_support/contracts.py) containing the
  helper functions assert_package_contracts, assert_makefile_contracts,
  assert_local_toolchain_contracts, assert_ci_contracts,
  assert_generated_documentation_contracts, and assert_release_workflow_contracts
  (preserving their signatures and docstrings), then update tests/test_template.py
  to import those functions from the new module and remove their definitions from
  this file so the top-level test file falls below 400 logical lines; ensure all
  references to those symbols (calls in test_generated_tooling_contracts and
  elsewhere) remain unchanged.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@leynos: Done — the issue has been created and assigned to you. The link will appear in the output above once the script runs.

---

🏁 Script executed:

gh issue create \
  --repo leynos/agent-template-rust \
  --assignee leynos \
  --title "Refactor: extract assertion helpers from tests/test_template.py into tests/test_support/contracts.py" \
  --body "## Background

Raised from PR `#33` (https://github.com/leynos/agent-template-rust/pull/33).

## Problem

\`tests/test_template.py\` currently exceeds 400 logical lines. The grouped assertion helper functions are defined inline in the top-level test file alongside test orchestration, making the file harder to navigate and maintain.

## Task

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

Specifically:

1. Create a new module \`tests/test_support/contracts.py\` (with an appropriate \`tests/test_support/__init__.py\` if needed).
2. Move the following helper functions—preserving their signatures and docstrings—into that new module:
   - \`assert_package_contracts\`
   - \`assert_makefile_contracts\`
   - \`assert_local_toolchain_contracts\`
   - \`assert_ci_contracts\`
   - \`assert_generated_documentation_contracts\`
   - \`assert_release_workflow_contracts\`
3. Update \`tests/test_template.py\` to import those functions from \`tests.test_support.contracts\` and remove their definitions from this file.
4. Ensure all call sites (e.g. inside \`test_generated_tooling_contracts\` and elsewhere) remain unchanged.
5. Confirm the top-level test file falls below 400 logical lines after the refactor.
6. Validate: run \`make test\` and confirm all tests pass.

## Acceptance criteria

- \`tests/test_support/contracts.py\` exists and contains the six helper functions with their original signatures and docstrings.
- \`tests/test_template.py\` imports the helpers from the new module and is below 400 logical lines.
- All existing test calls to the helpers are unmodified.
- \`make test\` passes with no regressions.

Requested by `@leynos`."

Length of output: 56

---

@leynos: Issue created at #35, assigned to you.