Add pinned Interrogate docstring coverage gate (#676)

[leynos]

Summary

This branch adds a pinned interrogate==1.7.0 gate for Netsuke
Python infrastructure, so make lint-python now requires 100%
docstring coverage across the repository-owned source boundary.

Closes #676.

Review walkthrough

• Start with Makefile for the pinned command, explicit spelling-helper exclusions, and lint-python integration.
• Then review the developer guide for the source scope, 100% requirement, and typ.overload exception policy.
• Finish with the workflow contract for exact-pin and Makefile-command coverage.

Validation

• make check-fmt: passed
• make lint: passed; Interrogate reports 100%
• make doc-coverage: passed (99.14%)
• make test: passed (2,798 nextest tests and doctests)
• make test-workflow-contracts: passed (276 tests)
• make markdownlint: passed
• make nixie: passed
• coderabbit review --agent: invoked twice after deterministic gates; the service did not return or store review findings.

Notes

• The unfiltered baseline was 97.7% (544/557 definitions; 13 missing). The issue-comment API rejected recording it with Resource not accessible by integration; the scoped gate now passes at 100%.

References

https://lody.ai/leynos/sessions/6322cc30-e75e-4b9f-b609-ccde83f647ef

[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

Introduces a pinned Interrogate 1.7.0 quality gate requiring 100% docstring coverage for repository-owned Python sources, with explicit spelling-helper exclusions, documentation, workflow contract enforcement, and the missing docstrings needed to pass the gate.

Flow diagram for the Interrogate Python lint gate

flowchart LR
    Sources[PYTHON_SOURCES] --> Exclusions[INTERROGATE_EXCLUDES]
    Exclusions --> Interrogate[interrogate==1.7.0]
    Interrogate --> Coverage{100% coverage?}
    Coverage -->|pass| LintPython[make lint-python passes]
    Coverage -->|fail| LintPythonFail[make lint-python fails]

Loading

File-Level Changes

Change	Details	Files
Add a pinned Interrogate docstring coverage gate to the Python lint pipeline.	Pin Interrogate to version 1.7.0 and invoke it through uv. Require 100% coverage over PYTHON_SOURCES during lint-python. Exclude the synchronized spelling-helper files from Interrogate, preserving their dedicated coverage policy. Document the scope, exclusions, CI behavior, and exception policy.	Makefile docs/developers-guide.md
Extend workflow contract tests to enforce the new tool pin and command wiring.	Validate the exact Interrogate version and its Makefile command in lint-python. Keep the selected release explicitly locked to 1.7.0. Update contract documentation for local-versus-CI pin behavior.	tests/workflow_contracts/python_toolchain_sync_test.py
Bring existing Python definitions into compliance with the repository-wide docstring gate.	Add constructor docstrings to coverage and test helper classes. Document nested callbacks used for filesystem traversal and rollback testing.	scripts/doc_coverage_cargo.py scripts/doc_coverage_runner.py scripts/hoist_binstall_discovery.py scripts/tests/test_doc_coverage_cargo.py scripts/tests/test_doc_coverage_runner.py tests/workflow_contracts/hoist_binstall_rollback_test.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#676	Add a pinned Interrogate 1.7.0 command with a 100% docstring-coverage gate over the repository-owned Python sources, while explicitly excluding the estate-synchronised spelling helpers.	✅
#676	Integrate Interrogate into the Python lint workflow and document the source scope, threshold, spelling-helper policy, and targeted handling required for any future typ.overload stubs.	✅
#676	Close the missing docstring gaps needed for the selected gate and add workflow-contract tests that enforce the exact Interrogate pin and Makefile integration.	✅

Possibly linked issues

• Add pinned Interrogate docstring-coverage gate for Python infrastructure #676: The PR directly implements issue Add pinned Interrogate docstring-coverage gate for Python infrastructure #676, adding pinned Interrogate coverage enforcement and associated documentation and tests.

---

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]

No quality gates enabled for this code.