Add Markdown format gate and prebuilt mdtablefix install

[leynos]

Summary

This branch checks the formatting of every tracked Markdown file in make check-fmt and installs mdtablefix in CI from its prebuilt release archive rather than a local source build. The formatter had become a silent dependency: make fmt reflowed Markdown through mdtablefix, but no gate verified that committed documents stayed canonical, so drift could reach main unnoticed.

mdtablefix has no check-only mode, so scripts/check-markdown-format.sh stages copies of each supplied file into a temporary directory, formats the whole batch with the canonical flags, and compares each result against its source. The worktree is never handed to the formatter and never modified. Exact LF and CRLF renderings both pass; mixed line endings fail. make check-fmt discovers files through Git's tracked-file index with NUL-delimited paths, skips tracked paths deleted from the worktree, and fails closed when Git cannot enumerate the index.

CI now pins MDTABLEFIX_VERSION to 0.5.1 once and installs the formatter through leynos/shared-actions/.github/actions/install-mdtablefix, which accepts only releases with correct multi-platform metadata and never compiles anything. Every leynos/shared-actions reference on the branch is pinned to the same revision.

No roadmap task or open issue tracks this work, and the branch does not carry an execplan.

Review walkthrough

• Start with scripts/check-markdown-format.sh to see the staged-copy, batch-format, compare design, including the CRLF candidate materialised to a file before cmp to avoid broken-pipe failures under pipefail.
• Then review Makefile for the fail-closed MD_FILES_FIND discovery and Makefile for the check-fmt and test-markdown-format targets.
• Then review scripts/tests/test_check_markdown_format.py, which covers the checker across process boundaries using the controlled repository helper in scripts/tests/markdown_format_test_support.py.
• Then review .github/workflows/ci.yml for the version-pinned cache and .github/workflows/ci.yml for the shared install action, with the contract tests in tests/workflow_contracts/test_mdtablefix_installer.py pinning the action reference, version input, and absence of any local build fallback.
• Finish with docs/developers-guide.md for the local cargo binstall recipe and the documentation contract.

Validation

• make check-fmt: exit 0, 160 files already formatted.
• make test-markdown-format: 10 passed.
• make test: 791 passed, 76 snapshots passed.
• make typecheck: all checks passed.
• make lint: exit 0 (pylint-pypy and df12 lints at 10.00/10, ambrleaks clean).
• make markdownlint: 0 errors across 22 files.
• make nixie: all diagrams validated.
• Negative test: injected formatting drift into a tracked Markdown file failed make check-fmt with the offending path reported, and the worktree was left untouched.

Notes

• Lading has no Rust build (Cargo.toml is a committed fixture), so "no project Rust toolchain variable" is asserted structurally by the contract tests rather than exercised by a build.
• The local mdtablefix used to format the baseline is 0.5.0; CI installs the pinned 0.5.1 prebuilt. The prose baseline is canonical under both, and the CI contract tests assert the pinned version.
• The stale-lockfile snapshots in tests/unit/test_lockfile_message_snapshots.py adopt the <tmp-file-path> placeholder from the repository's own ambrleaks repair, keeping the snapshots machine-independent so make lint and make test pass on this branch.

Summary by Sourcery

Enforce canonical formatting for tracked Markdown and replace CI source builds with a pinned prebuilt mdtablefix installation.

New Features:

• Add a Markdown formatting gate that validates every existing tracked Markdown file through make check-fmt without modifying the worktree.
• Install the pinned mdtablefix 0.5.1 release in CI through a shared prebuilt installer with version-aware caching.

Bug Fixes:

• Prevent silently drifting committed Markdown formatting from reaching the main branch.
• Ensure Markdown discovery handles deleted paths safely and fails closed when Git cannot enumerate tracked files.

Enhancements:

• Support canonical LF and CRLF files while rejecting mixed line endings.
• Align all shared-actions workflow references on a single pinned revision.

CI:

• Add CI contract coverage for the pinned mdtablefix installer, cache, and shared action references.

Documentation:

• Document the Markdown formatting checker, its tests, and the local mdtablefix workflow.

Tests:

• Add process-boundary tests covering formatting validation, batching, line endings, source preservation, discovery behavior, and formatter failures.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Warning

Your free Security trial is over. An organization admin can upgrade to Advanced for continuous pull request security review or dismiss this notice.

---

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

[sourcery-ai]

Reviewer's Guide

This PR introduces a fail-safe, non-mutating Markdown formatting gate over Git-tracked files, provisions mdtablefix 0.5.1 in CI exclusively from a pinned prebuilt archive with version-aware caching, aligns shared-action revisions, and documents and tests the resulting workflow.

Sequence diagram for CI mdtablefix installation

sequenceDiagram
    participant CI
    participant Cache
    participant Installer as SharedInstallAction
    participant Release as PrebuiltReleaseArchive
    participant Path as LocalBin
    CI->>Cache: Restore mdtablefix-${runner.os}-${runner.arch}-${MDTABLEFIX_VERSION}
    CI->>Installer: install-mdtablefix(version=MDTABLEFIX_VERSION)
    Installer->>Release: Resolve matching 0.5.1 platform archive
    Release-->>Installer: Release metadata and archive
    alt Supported archive metadata
        Installer->>Path: Install prebuilt mdtablefix
        Installer-->>CI: Add ~/.local/bin to PATH
    else Missing or invalid archive
        Installer-->>CI: Fail without compiling
    end

Loading

Flow diagram for the tracked Markdown format gate

flowchart TD
    A[make check-fmt] --> B[git ls-files -z -- *.md]
    B --> C{Git index enumerated?}
    C -- No --> F[Fail closed]
    C -- Yes --> D[Skip deleted worktree paths]
    D --> E[scripts/check-markdown-format.sh]
    E --> G[Copy files to temporary staging]
    G --> H[mdtablefix --in-place canonical formatting]
    H --> I[Compare LF and CRLF candidates with sources]
    I --> J{All files match?}
    J -- Yes --> K[Pass without changing worktree]
    J -- No --> L[Report unformatted paths and fail]

Loading

File-Level Changes

Change	Details	Files
Add a non-mutating Markdown formatting gate that validates tracked documents against canonical mdtablefix output.	Stage all discovered files into temporary copies and format them in one batch. Compare LF and CRLF candidates while rejecting mixed line endings and preserving the worktree. Discover tracked Markdown with NUL-delimited Git paths, skip deleted files, and fail closed on discovery errors. Add Makefile targets and process-boundary tests covering formatting, discovery, batching, and failure cases.	scripts/check-markdown-format.sh Makefile scripts/tests/markdown_format_test_support.py scripts/tests/test_check_markdown_format.py
Move CI mdtablefix setup from a source build to a pinned prebuilt release installation.	Define the formatter version once and pass it to the shared install action. Cache platform-specific binaries using a version-aware key. Require all shared-actions references to use the same full commit SHA. Add workflow contract tests for pinning, caching, prebuilt installation, and absence of Rust build fallbacks.	.github/workflows/ci.yml .github/workflows/coverage-main.yml .github/workflows/dependabot-automerge.yml .github/workflows/mutation-testing.yml tests/workflow_contracts/test_mdtablefix_installer.py
Document the Markdown formatting workflow and local CI-compatible formatter installation.	Explain formatter ownership, check semantics, line-ending behavior, and tracked-file discovery. Add the cargo-binstall recipe for mdtablefix 0.5.1 and describe the prebuilt-only CI contract. Update repository layout documentation for the checker and its tests.	docs/developers-guide.md docs/repository-layout.md
Apply canonical Markdown reflow to repository rules and documentation while making snapshot paths machine-independent.	Reformat Markdown tables and prose to the new canonical mdtablefix layout. Update lockfile snapshot fixtures to use a temporary-path placeholder.	.rules/python-pyproject.md .rules/python-return.md docs/adr/003-three-tier-python-linting.md docs/developers-guide.md docs/users-guide.md tests/unit/test_lockfile_message_snapshots.py tests/unit/__snapshots__/test_lockfile_message_snapshots.ambr

---

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.

[codescene-access]

Gates Failed
New code is healthy (1 new file with code health below 10.00)
Enforce critical code health rules (1 file with Bumpy Road Ahead, Deep, Nested Complexity)
Enforce advisory code health rules (1 file with Complex Method)

Our agent can fix these. Install it.

Gates Passed
3 Quality Gates Passed

Reason for failure

New code is healthy	Violations	Code Health Impact
test_mdtablefix_installer.py	3 rules	8.93	Suppress

Enforce critical code health rules	Violations	Code Health Impact
test_mdtablefix_installer.py	2 critical rules	8.93	Suppress

Enforce advisory code health rules	Violations	Code Health Impact
test_mdtablefix_installer.py	1 advisory rule	8.93	Suppress

See analysis details in CodeScene

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codescene-access]

No quality gates enabled for this code.