Enforce enhanced lint requirements

[lodyai]

Summary

This branch strengthens the local and CI lint gates by requiring complete Python docstring coverage and by adopting the Rust formatting and lint baseline from the Rust agent template. It also applies the resulting workspace-wide Rust formatting changes so the new nightly rustfmt configuration passes immediately.

Review walkthrough

• Start with Makefile to see interrogate --fail-under 100 . added to the lint target.
• Review .github/workflows/ci.yml for the uv setup and interrogate tool installation before CI linting.
• Check rustfmt.toml and rust-toolchain.toml for the imported nightly rustfmt settings.
• Review tests/test_workflow_integration.py for the Python docstrings needed by the new coverage gate.
• Treat the remaining Rust source and test changes as mechanical formatting from the imported rustfmt rules, with a few fixture helper bodies expanded where the formatter's single-line output conflicted with denied Rust lints.

Validation

• make check-fmt: passed
• make lint: passed, including interrogate --fail-under 100 . at 100.0%
• make typecheck: passed
• make test: passed; first nextest pass ran 270 tests with 270 passed and 4 skipped, and the no-default-features dev-worker pass ran 156 tests with 156 passed

Notes

The supplied template URL for rustfmt.toml used blop and the repository stores the file as template/.rustfmt.toml; this branch imports that template content into the local rustfmt.toml, which rustfmt recognises at the workspace root.

References

• Lody session: https://lody.ai/leynos/sessions/14ea6aa5-1a65-49c6-9ffe-908d72f2595e

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b5471884-5fa4-4cca-90a3-756c011cafdf

📥 Commits

Reviewing files that changed from the base of the PR and between 84bd9f4 and 7148db4.

📒 Files selected for processing (6)

• docs/execplans/issue-60-3-environment-mutation-abstraction.md
• src/bin/pg_worker.rs
• tests/settings.rs
• tests/shared_cluster_handle_failure.rs
• tests/support/env_mutation.rs
• tests/worker_process.rs

🔗 Linked repositories identified

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

• leynos/cuprum (auto-detected)
• leynos/rstest-bdd (auto-detected)

---

Added a new lint/formatting policy and supporting docs: the repository now pins the Rust toolchain to nightly, imports a shared rustfmt baseline, and enforces 100% Python docstring coverage via interrogate in local and CI lint flows. This is documented in the new ADR and reflected in the developers’ guide and roadmap.

CI was updated to install interrogate before linting, and the Makefile lint target now includes the docstring coverage gate. The Rust workspace was then mechanically reformatted to match the new nightly rustfmt baseline, including a few small helper and test-body adjustments to satisfy stricter lints.

Also added a small test-support module for isolated environment mutation helpers used by the updated tests.

Walkthrough

Update the Rust toolchain and formatter settings, switch CI to install interrogate through uv, add lint-policy documentation, adjust test_support exports, and apply broad mechanical import, formatting, and doc reflow changes across source and test files.

Changes

Toolchain, formatter, lint gate, and mass reformatting

Layer / File(s)	Summary
Toolchain, CI lint install, and policy docs rust-toolchain.toml, rustfmt.toml, .github/workflows/ci.yml, docs/adr-004-enhanced-lint-requirements.md, docs/developers-guide.md, docs/roadmap.md, AGENTS.md	Pin the Rust toolchain to nightly, add rustfmt settings, install interrogate==1.7.0 through uv in CI, and add contributor-facing lint and formatting guidance.
Docs and execplan reflow docs/*.md, docs/execplans/*, AGENTS.md	Rewrap ADR, guide, roadmap, ExecPlan, and other markdown text without changing the underlying wording or meaning.
Source import and helper reformatting src/**/*.rs	Group imports, condense small helper bodies, rewrap error strings and doc examples, gate Unix-only imports, and keep runtime behaviour unchanged across source modules.
test_support exports and helpers src/test_support/mod.rs, tests/support/env_mutation.rs	Move ambient_dir_and_path behind cfg gates, split fixture re-exports, keep Unix-only cluster exports ordered at the end, and add unsafe environment-mutation helpers for isolated tests.
Test and integration file reformatting tests/**/*.rs, tests/test_workflow_integration.py	Reorder imports, simplify helper bodies, bind intermediate fixture values before RefCell wrapping, adjust feature-gated imports, and refine two Python docstrings.

Sequence Diagram(s)

sequenceDiagram
  participant ci.yml
  participant astral-sh/setup-uv
  participant uv
  ci.yml->>astral-sh/setup-uv: set up uv
  ci.yml->>uv: tool install interrogate==1.7.0

Loading

Possibly related PRs

• leynos/pg-embedded-setup-unpriv#67: Touches the same cache-related source files and import/layout clean-up in the shared binary-cache surface.
• leynos/agent-template-rust#37: Updates contributor guidance alongside similar formatting-policy text.
• leynos/pg-embedded-setup-unpriv#154: Modifies the same CI interrogate==1.7.0 installation path in .github/workflows/ci.yml.

Suggested labels: Roadmap, Issue

Poem

Nightly rust now wears its crown,
imports line up, tidy down.
uv fetches interrogate bright,
docs reflow and read just right.
Tiny trims and one-line charms —
the codebase hums in orderly arms.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarises the PR’s main linting and formatting changes.
Description check	✅ Passed	The description matches the lint-gate, rustfmt, toolchain, and formatting updates in the changeset.
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	The only behavioural test touched still forces TZDIR failure and checks repeated shared_cluster_handle() calls; the new helper is a trivial support extraction.
User-Facing Documentation	✅ Passed	PASS: The branch only changes linting, formatting, developer docs, and test helpers; no end-user behaviour or public API shift needs a users-guide update.
Developer Documentation	✅ Passed	PASS: docs/developers-guide.md and ADR 004 document the pinned nightly/toolchain and interrogate gate; roadmap item 3.4.1 is checked, and CI/Makefile match.
Module-Level Documentation	✅ Passed	PASS — the scan found 0 Rust files missing a module doc comment and the lone Python module already has a top-level docstring; the new env_mutation.rs module is documented.
Testing (Unit And Behavioural)	✅ Passed	PASS: shared_cluster_handle_failure.rs exercises the real shared_cluster_handle() failure boundary, and unit tests in database_lifecycle_helpers/tests.rs assert concrete invariants.
Testing (Property / Proof)	✅ Passed	PASS: the PR only moves two unsafe env helpers into a test-support module; it adds no new range/state invariant or proof obligation beyond an existing call-site safety precondition.
Testing (Compile-Time / Ui)	✅ Passed	No compile-time or UI-adjacent behaviour changed; the diff is linting, docs, and mechanical formatting only, so trybuild or snapshot coverage is not required.
Unit Architecture	✅ Passed	Formatting-only edits preserved pure accessors and explicit Result-based fallibility; the new env mutation helper is isolated to test support and the worker command still mutates env at the command...
Domain Architecture	✅ Passed	Pass: the patch is formatting/docs/tooling only; new env helpers stay in test support, and no domain code now depends on infrastructure concerns.
Observability	✅ Passed	Branch only reflows formatting and test-support env helpers; no production operational behaviour, logging, metrics, tracing, or alerts changed.
Security And Privacy	✅ Passed	Changes are test-only/formatting; the new env helper is isolated to tests and uses hard-coded fake values, with no secrets, auth bypasses, or sensitive-data leaks found.
Performance And Resource Use	✅ Passed	PASS: The only runtime changes are two test-only env helpers and a bounded three-call cache test; no production loops, unbounded collections, or hot-path I/O were introduced.
Concurrency And State	✅ Passed	PASS: The new env helper is test-local, and the shared singleton code already uses OnceLock+Mutex; the new Unix test documents separate-binary isolation and checks repeated-call caching.
Architectural Complexity And Maintainability	✅ Passed	PASS: The PR is mostly mechanical formatting/docs; the only new helper is a private test-only module with an explicit isolation boundary, not a general abstraction.
Rust Compiler Lint Integrity	✅ Passed	PASS: the diff removes dead_code expectations, narrows the test-support boundary with env_mutation, and adds no new lint suppressions, fake anchors, or clone calls.

✨ 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 enhanced-lint-requirements

---

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

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[pandalump]

@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.

[leynos]

@coderabbitai Have the following now been resolved?

Inline comments:
In @.github/workflows/ci.yml:

• Line 23: The checkout step in the CI workflow is leaving the GitHub token
  persisted in local git config by default, which is unnecessary here. Update the
  actions/checkout usage in the workflow to disable credential persistence by
  setting persist-credentials to false, and keep the existing job behavior
  unchanged unless a later step in the CI job genuinely requires git push or
  authenticated fetches.

In @docs/adr-004-enhanced-lint-requirements.md:

• Around line 5-11: The ADR date is inconsistent with its accepted status: the
  document in the accepted section uses a future date, so update the Date field in
  the ADR to the actual acceptance date or change the status back to Proposed
  until that date is valid. Use the existing accepted-status text in the ADR to
  locate the date entry and keep the status/date aligned.

In @docs/rust-doctest-dry-guide.md:

• Around line 407-410: The Unix cfg example uses an invalid Rust predicate, so
  update the UnixSocket docs to use cfg(unix) or cfg(target_family = "unix")
  instead of cfg(target_os = "unix"), and adjust the surrounding explanation to
  refer to the unix cfg being set; make sure the prose in this section matches
  the actual directive used so the example and description stay consistent.

[coderabbitai]

Tip

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

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== ci.yml checkout step ==="
sed -n '1,30p' .github/workflows/ci.yml

echo "=== ADR date/status ==="
sed -n '1,15p' docs/adr-004-enhanced-lint-requirements.md

echo "=== rust-doctest-dry-guide.md cfg example ==="
sed -n '395,420p' docs/rust-doctest-dry-guide.md

Length of output: 2908

---

@leynos, yes — all three are resolved.

• .github/workflows/ci.yml: the checkout step now sets persist-credentials: false alongside the pinned actions/checkout SHA.
• docs/adr-004-enhanced-lint-requirements.md: the Status and Date fields are aligned at "Accepted on 2026-07-03" / "2026-07-03", consistent with the accepted status.
• docs/rust-doctest-dry-guide.md: the example uses #[cfg(any(unix, doc))], and the surrounding prose correctly refers to the unix cfg being set.

Nothing further outstanding on these three items.

(=^･ω･^=)