Docstring Coverage Checker
Relevant source files
The following files were used as context for generating this wiki page:
The Docstring Coverage Checker is a static analysis tool designed to enforce documentation standards within the numan-plugins repository. Its primary purpose is to ensure that critical publication safety modules are fully documented, requiring module-level, function-level, and class-level docstrings to explain their respective contracts.
This checker is integrated into the project's testing suite, specifically targeting scripts that manage release transactions, manifest validation, and specification generation. By mandating documentation, the project ensures maintainability and clarity for the binary-delivery pipeline that feeds the numan official registry.
Sources: scripts/test_docstring_coverage.py:1-12, README.md:1-10
Architecture and Logic
The coverage checker operates by parsing Python source files into Abstract Syntax Trees (AST). It traverses these trees to identify nodes that require documentation and verifies the presence of docstrings using built-in Python AST utilities.
Safety Module Scope
The checker specifically monitors a set of "publication safety modules" that are vital to the project's CI/CD integrity. These include:
| Module | Responsibility |
|---|---|
ensure_release_absent.py | Prevents overwriting existing immutable release assets. |
gen_spec.py | Generates registry-compliant package specifications. |
release_transaction.py | Manages the lifecycle (claim, verify, finalize) of draft releases. |
validate_manifest.py | Ensures the build manifest follows schema and upstream pins. |
Sources: scripts/test_docstring_coverage.py:11-16, REVIEW.md:20-30
Inspection Workflow
The following diagram illustrates how the DocstringCoverageTests class processes each safety module to identify missing documentation.
The logic ensures that even if multiple docstrings are missing across different files, they are all reported in a single test failure for efficient debugging.
Sources: scripts/test_docstring_coverage.py:23-33
Components and Data Structures
The system relies on the Python ast module to perform non-intrusive inspection of the code.
Key Data Structures
SAFETY_MODULES: A tuple containing the hardcoded paths to the Python scripts requiring 100% docstring coverage.missing: A list of strings used to aggregate documentation gaps, formatted asfilename:line: namefor easy location.
Sources: scripts/test_docstring_coverage.py:11-16, scripts/test_docstring_coverage.py:25
Implementation Detail: Node Extraction
The checker distinguishes between different types of definitional blocks. It specifically looks for:
ast.FunctionDef: Standard function definitions.ast.AsyncFunctionDef: Asynchronous function definitions.ast.ClassDef: Class definitions.
For each of these, ast.get_docstring(node) is called to retrieve the literal string constant located at the start of the definition.
Sources: scripts/test_docstring_coverage.py:30-33
Documentation Requirements for Safety Modules
Based on the modules checked, the following contracts must be documented:
Release Transaction Operations
release_transaction.py must document functions handling the GitHub CLI (gh) for release management.
- Claiming: Reserving a tag and creating a draft.
- Finalizing: Verifying asset SHA-256 hashes before moving from draft to public.
- Cleaning: Removing failed drafts to maintain repo hygiene.
Sources: scripts/release_transaction.py:35, scripts/release_transaction.py:61, scripts/release_transaction.py:176
Manifest Validation Logic
validate_manifest.py requires documentation for its validation routines, such as expected_targets and verify_upstream. These ensure that the build matrix in manifest.json correctly maps to the required GitHub runners (e.g., macos-15-intel for x86_64-apple-darwin).
Sources: scripts/validate_manifest.py:51, scripts/test_workflow_safety.py:126-140
Integration in CI/CD
The Docstring Coverage Checker is part of the repo-safety workflow. It complements other safety checks like actionlint and manifest verification.
Conclusion
The Docstring Coverage Checker serves as a critical linting layer in the numan-plugins repository. By enforcing documentation for modules like release_transaction.py and gen_spec.py, it ensures that the logic governing the immutability of release assets and the integrity of the binary-delivery pipeline remains transparent and maintainable for developers. This documentation requirement supports the project's invariant that release assets are immutable and must be verified before publication.
Sources: REVIEW.md:20-25, scripts/test_docstring_coverage.py:1-5