pycodecommenter 2.0.3__tar.gz → 2.2.0__tar.gz

pycodecommenter-2.2.0/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+# .github/workflows/docs.yml
+# Builds and deploys the MkDocs documentation site to GitHub Pages.
+#
+# Trigger: any push to `main` that touches docs/ or this workflow file.
+# Manual trigger: workflow_dispatch (run from the Actions tab at any time).
+#
+# REQUIRED ONE-TIME SETUP:
+# GitHub repo → Settings → Pages → Source → select "GitHub Actions"
+# Without that change the deploy job runs but the site never goes live.
+
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation Site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs and theme
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build site
+        run: mkdocs build --strict --site-dir _site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

pycodecommenter-2.2.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycodecommenter
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pycodecommenter-2.2.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local/Temp Files for PyCodeCommenter
+env_info.txt
+out.txt
+output.txt
+modern_output.txt
+modern_results.txt
+test_output.txt
+reproduction.py
+test_cst.txt
+main_output.txt
+out_*.txt
+verify_*.py
+verify_*.txt
+error.txt
+version_info.txt
+
+# VS Code
+.vscode/

pycodecommenter-2.2.0/.well-known/ai-plugin.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": "v1",
+  "name_for_human": "PyCodeCommenter",
+  "name_for_model": "pycodecommenter",
+  "description_for_human": "Python docstring generator and validator. Generates Google-style docstrings from AST, validates them against real function signatures, and measures documentation coverage.",
+  "description_for_model": "PyCodeCommenter is a deterministic, AST-based Python tool. It can: (1) generate Google-style docstrings for undocumented Python functions and classes from their AST, (2) validate existing docstrings against real function signatures across six check categories, (3) measure documentation coverage per file or project, and (4) export structured JSON reports. It requires no AI, no network access, and no API keys. Install with 'pip install pycodecommenter'. Main classes: PyCodeCommenter (generation), DocstringValidator (validation), CoverageAnalyzer (coverage).",
+  "auth": {
+    "type": "none"
+  },
+  "api": {
+    "type": "none"
+  },
+  "logo_url": "https://amosquety.github.io/PyCodeCommenter/assets/logo.png",
+  "contact_email": "amosnabasa4@gmail.com",
+  "legal_info_url": "https://github.com/AmosQuety/PyCodeCommenter/blob/main/LICENSE",
+  "homepage": "https://amosquety.github.io/PyCodeCommenter/",
+  "repository": "https://github.com/AmosQuety/PyCodeCommenter",
+  "pypi": "https://pypi.org/project/pycodecommenter/",
+  "install_command": "pip install pycodecommenter",
+  "version": "2.2.0",
+  "license": "MIT",
+  "author": "Nabasa Amos (Amos Quety)"
+}

pycodecommenter-2.2.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to PyCodeCommenter will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [2.2.0] - 2026-07-12
+
+### Added
+- **Decorator-aware validation** — `@property` setter and deleter variants no longer produce false-positive
+  "missing Returns section" warnings. `@classmethod` (`cls`) and `@staticmethod` were verified already correct.
+- **`--output-format json`** flag on both `validate` and `coverage` subcommands. Prints machine-readable
+  JSON to stdout; text output is completely unchanged.
+- **`ValidationReport.to_dict()`** updated to spec-compliant shape: `stats.total`, `stats.info`,
+  `stats.coverage_percentage`; issues now include `line` (integer), `severity` (uppercase), `check`, `message`.
+- **`_has_raises_section()` helper** in `validator.py` — recognises `Raises:` (Google), `Raises\n`
+  (bare header), and `:raises ` (Sphinx, trailing space prevents false matches).
+- **`llms.txt`** file at repo root — AI agent and LLM crawler discovery file.
+- **SEO/AEO optimisation** — keyword-rich README, PyPI classifiers/keywords, per-page meta tags on all
+  doc pages, JSON-LD `SoftwareApplication` schema on docs homepage.
+
+### Changed
+- `test_validation.py` rewritten from script-style to proper pytest (17 tests, all pass).
+- `pyproject.toml` keywords expanded to 20 terms; classifiers expanded with `Code Generators`,
+  `Libraries :: Python Modules`, `Environment :: Console`, `Operating System :: OS Independent`.
+- `mkdocs.yml` enriched with `site_author`, explicit `language: en`, `navigation.indexes`,
+  `search.share`, `toc.follow`, and `meta` markdown extension for per-page SEO tags.
+
+## [2.0.0] - 2026-01-25
+
+###  Major Release - Complete Rewrite
+
+#### Added
+- **Comprehensive Validation System** - 6 types of documentation checks
+- **Coverage Analysis** - Project-wide documentation metrics
+- **Modern Type Support** - PEP 604 unions, PEP 585 generics
+- **Async Function Support** - Full support for `async def`
+- **Multiple Export Formats** - JSON, Markdown, console output
+- **Smart Docstring Parsing** - Preserves existing documentation
+- **Structured AST Traversal** - NodeVisitor pattern for reliability
+- **Professional Reporting** - Actionable error messages with suggestions
+- **CI/CD Ready** - Easy integration with pipelines
+
+#### Changed
+- Replaced basic type inference with comprehensive `TypeAnalyzer`
+- Improved docstring generation with better templates
+- Enhanced error handling with proper logging
+- Better handling of edge cases and malformed code
+
+#### Fixed
+- Duplicate `_infer_type` methods consolidated
+- Brittle patching logic made robust
+- Import resolution issues
+- Unicode/encoding handling
+
+#### Breaking Changes
+- Minimum Python version: 3.8+
+- Some internal APIs changed (public API remains compatible)
+
+## [1.0.0] - Earlier Version
+
+- Basic docstring generation
+- Template-based descriptions
+- File and string input support

pycodecommenter-2.2.0/CITATION.cff

@@ -0,0 +1,32 @@
+cff-version: 1.2.0
+message: "If you use PyCodeCommenter in your research or project, please cite it using this metadata."
+type: software
+title: PyCodeCommenter
+abstract: >
+  PyCodeCommenter is an open-source Python tool for automatically generating
+  Google-style docstrings from Python AST, validating existing docstrings
+  against real function signatures, and measuring documentation coverage.
+  It is deterministic, rule-based, and requires no AI or network access.
+authors:
+  - family-names: Amos
+    given-names: Nabasa
+    alias: Amos Quety
+    email: amosnabasa4@gmail.com
+    website: https://nabasa-amos.netlify.app
+    orcid: ""
+version: 2.2.0
+date-released: "2026-07-12"
+license: MIT
+repository-code: https://github.com/AmosQuety/PyCodeCommenter
+url: https://amosquety.github.io/PyCodeCommenter/
+keywords:
+  - python
+  - docstring
+  - documentation
+  - validation
+  - coverage
+  - google-style
+  - ast
+  - developer-tools
+  - ci-cd
+  - static-analysis

pycodecommenter-2.2.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to PyCodeCommenter
+
+First off, thank you for considering contributing to PyCodeCommenter! It's people like you who make it a great tool for everyone.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+*   Check the [Issues](https://github.com/AmosQuety/PyCodeCommenter/issues) to see if it has already been reported.
+*   If not, open a new issue. Include a clear title, a description of the problem, and steps to reproduce (like a small code snippet).
+
+### Proposing Enhancements
+*   Open an issue to discuss your idea before starting work.
+*   Explain why this feature would be useful and how it should work.
+
+### Pull Requests
+1.  Fork the repo and create your branch from `main`.
+2.  Follow the existing code style.
+3.  Add tests if you're adding new functionality.
+4.  Ensure all tests pass.
+5.  Update documentation (including `README.md`) if necessary.
+6.  Open a Pull Request with a clear description of your changes.
+
+## Code Style
+*   Use [black](https://github.com/psf/black) for formatting.
+*   Follow Google-style docstrings (since that's what we generate!).
+*   Maintain Python 3.8+ compatibility.
+
+## Need Help?
+Feel free to open a discussion or an issue if you have any questions!

pycodecommenter-2.2.0/Future Work/Future Release WorkPlan.txt

@@ -0,0 +1,15 @@
+v2.1.0 — Safety & Trust · Jun 10 → Jun 30
+This is the "stop scaring users" release. All four items are independent so you can ship them in any order.
+--dry-run and --backup first — they're the most urgent. Dry-run prints a unified diff to stdout. Backup simply does shutil.copy(path, path + ".bak") before any in-place write. Maybe 2 days each.
+Config loader next. Add a config.py module that walks up the directory tree looking for .pycodecommenter.yaml and loads it with ruamel.yaml. Wire the values to the existing hard-coded defaults. A week's work max.
+Smarter parameter inference is also v2.1 — see the dedicated audit prompt below.
+Test rewrite is ongoing across all phases but the baseline pass (assertions on critical paths) should land here.
+
+v2.2.0 — Accuracy & Output · Jul 1 → Aug 15
+This is the "be correct and be composable" release. Decorator awareness cleans up the false-positive noise. JSON output unlocks every downstream integration — make it a flag on both validate and coverage. The Sphinx :raises: fix is a targeted one-liner in validator.py.
+
+v3.0.0 — Safe, Configurable, Extensible · Aug 16 → Nov 1
+The big one. The merge algorithm is the hardest item in the entire roadmap — budget 3–4 weeks for it alone. The approach: parse the existing docstring into sections, generate fresh sections, then do a section-by-section merge where any section with human content that doesn't match the auto-generated template is preserved. Multi-style support travels alongside — once the generator is style-aware, NumPy and Sphinx become config flags.
+
+v3.1.0 — Integrations · Nov 2, 2026 → Mar 1, 2027
+VS Code extension, GitHub Action for PR automation, SARIF output. These all depend on the v3.0 foundation being solid. Don't start them until merge and JSON output are stable.

pycodecommenter-2.2.0/Future Work/Vulnerabilties.md

@@ -0,0 +1,301 @@
+# PyCodeCommenter — Principal Engineer & DX Analysis
+
+> Reviewed by: Antigravity (Principal SE / DX Expert)  
+> Codebase version: v2.2.0 · Files reviewed: all source, all docs, all tests
+
+---
+
+## Question 1 — Is This Tool Actually Useful, or Is It a Novelty?
+
+**Honest verdict: It is real, but only in one narrow workflow.**
+
+The strongest use case — the one where this tool earns its install — is:
+
+> **You join a legacy Python project. It has 400 functions. Zero docstrings. You need to get it to a documentable state before a code review, open-source release, or handover.**
+
+In that scenario, `pycodecommenter generate . --inplace` gives you structural scaffolding (correct parameters, correct types, correct sections) in seconds. Even though the *descriptions* are weak, you now have the *structure* to fill in, which is faster than writing from scratch. The validator then catches regressions as the codebase evolves.
+
+**Where it does NOT compete:**
+
+- Active, well-maintained projects — they already use docstring conventions enforced via pre-commit + `pydocstyle`/`ruff D` rules, which are richer and team-proven.
+- Projects using AI coding assistants (Copilot, Cursor, Gemini) — docstrings get generated automatically from context, at higher quality.
+- Greenfield projects — the generate-then-fix workflow adds friction rather than removing it.
+
+**The tool's real competitive edge is the validator**, not the generator. `pydocstyle` checks *style*. PyCodeCommenter checks *semantic accuracy* (is parameter `timeout` actually in the `Args:` section?). That's a genuinely differentiated check that existing linters don't do as directly.
+
+---
+
+## Question 2 — Biggest Technical Limitations & Code-Corruption Risks
+
+These are ordered by severity. The top two can silently corrupt user files.
+
+---
+
+### 🔴 CRITICAL: The Patcher Can Corrupt Multi-Line Signatures
+
+**File:** `commenter.py`, `get_patched_code()`, lines 119–162.
+
+The patcher finds the `def` line by scanning forward from `node.lineno` looking for a line that starts with `def`, `class`, or `async def`. It then uses `node.body[0].lineno - 1` as the insertion point.
+
+**The failure case:**
+
+```python
+def very_long_function_name(
+    argument_one: str,
+    argument_two: int,     # <-- lineno of body[0] is THIS line
+    argument_three: bool,
+) -> dict:
+    pass
+```
+
+`ast` sets `lineno` to the `def` line, but `body[0].lineno` points to the *first statement inside the body*. For a multi-line signature, the first body statement starts *after the closing parenthesis and colon*. The patcher inserts the docstring at `body[0].lineno - 1`, which is actually inside the signature continuation lines. **Result: the file is corrupted.** This is not a hypothetical — any function with a multi-line signature hits this.
+
+---
+
+### 🔴 CRITICAL: `get_patched_code()` Uses Line-Number Arithmetic on Mutable `lines[]`
+
+**File:** `commenter.py`, lines 153–160.
+
+The patcher accumulates `changes` (tuples of `(start, end, content)`), sorts them in reverse, then applies them. The sort is on `x[0]` (start line). But when an *insertion* is made (`start > end`), it calls `lines.insert(start, content)` which shifts all subsequent line numbers by 1. If two insertions land close together and are processed in an order where one's `start` overlaps with another's post-shift position, the second edit lands on the wrong line.
+
+**Existing tests never catch this** because `test_validation.py` tests the *validator*, and none of the other test files test `get_patched_code()` on multi-function files with real line shifts.
+
+---
+
+### 🟡 HIGH: `ast.walk()` in `validate_all()` Is Order-Indeterminate and Visits Nested Functions Twice
+
+**File:** `validator.py`, lines 182–188.
+
+`ast.walk()` does a breadth-first traversal. A nested function inside a class inside another function will be visited — and validated — independently. But the *parent* class body is also walked, so the nested function's stats (`total_functions`) get double-counted. If a class method is inside a nested class, it gets counted three times.
+
+This causes the `coverage_percentage` in the validation report to be wrong for any non-trivial project with nested classes.
+
+---
+
+### 🟡 HIGH: `DocstringParser._parse_google()` Uses a Regex That Drops Multi-Line Param Descriptions
+
+**File:** `docstring_parser.py`, lines 79–94.
+
+```python
+sections = re.split(r'(?m)^ *(Args|Returns|Attributes|Methods):$', content)
+```
+
+This regex requires the section header to be on its own line with nothing after the colon. But the continuation-line handling in `_parse_google_args()` only recognises lines starting with **8 spaces**:
+
+```python
+elif current_arg and line.startswith('        '):  # 8 spaces hardcoded
+```
+
+Any project using 2-space indentation (common in Django, Flask) or 4-space body + 2-space continuation will silently drop continuation lines. The description gets truncated after the first line. No warning is raised. **This causes the merger in `get_patched_code()` to silently overwrite human-written multi-line descriptions.**
+
+---
+
+### 🟠 MEDIUM: `check_signature_match()` Self/Cls Heuristic Is Name-Based, Not AST-Based
+
+**File:** `validator.py`, lines 271–276.
+
+```python
+if actual_params and actual_params[0] in ('self', 'cls'):
+    actual_params = actual_params[1:]
+```
+
+If a developer names their first parameter `self` on a module-level function (unusual but valid), the validator silently strips it. Conversely, if a classmethod's `cls` is not the first parameter (impossible under normal usage but possible in generated/metaprogrammed code), the strip doesn't fire. The fix from v2.2.0 (decorator detection) partially addresses this for `@classmethod`, but the underlying heuristic is still name-based and fragile.
+
+---
+
+### 🟠 MEDIUM: `generate` CLI Does Not Accept Directory Paths
+
+**File:** `cli.py`, line 37.
+
+`pycodecommenter generate myfile.py` works. `pycodecommenter generate ./src/` does not — it fails silently or errors out. `coverage` accepts directories; `validate` accepts only files; `generate` accepts only files. This asymmetry is documented but it's a DX cliff: every new user tries `pycodecommenter generate .` first.
+
+---
+
+### 🟡 HIGH: `validate` CLI Also Does Not Accept Directories
+
+**File:** `cli.py`, lines 81–85.
+
+Same problem as generate. The pre-commit recipe works around this with `pass_filenames: true`, but running `pycodecommenter validate src/` manually — the most natural thing to type — silently passes on `DocstringValidator(file_path="src/")` which opens a directory and fails in `ast.parse()`.
+
+---
+
+### 🟠 MEDIUM: `PEP 604` Union Type Renders as `Union[X, Y]` Not `X | Y`
+
+**File:** `type_analyzer.py`, line 138–140.
+
+```python
+if isinstance(annotation.op, ast.BitOr):
+    return f"Union[{left}, {right}]"
+```
+
+A type hint written as `int | str` (modern Python) gets documented as `Union[int, str]` — the older style. In a Python 3.10+ codebase, this is visually inconsistent and potentially confusing.
+
+---
+
+### 🟠 MEDIUM: Config File Is Loaded But Ignored at Runtime
+
+**File:** `config.py` is complete and correct. The problem is it's never called from `cli.py` or any core class. The `--exclude` flag is implemented independently in the CLI without ever reading `.pycodecommenter.yaml`. A user who creates a config file gets zero effect. This is documented in the configuration page but it's a credibility problem — if the config doesn't work, sophisticated users leave.
+
+---
+
+## Question 3 — API Design Review
+
+### What Works
+
+The fluent builder pattern is clean:
+```python
+PyCodeCommenter().from_file("f.py").get_patched_code()
+```
+This is a good DX decision. It's Pythonic and readable.
+
+### What Is Broken or Confusing
+
+**1. The `validate()` method on `PyCodeCommenter` is a redundant wrapper that hides a bug.**
+
+```python
+# commenter.py line 434
+validator = DocstringValidator(code_string=self.code, file_path=None)
+```
+
+`file_path=None` is hardcoded. So `report.file_path` is always `None` when called via `commenter.validate()`, even though the commenter loaded from a file. Every issue's `location` string starts with `code:` instead of the real file path. The user sees `[ERROR] code:12:my_func` instead of `[ERROR] src/api.py:12:my_func`. **The file path information is lost.**
+
+```python
+# Fix: pass self.file_path
+validator = DocstringValidator(code_string=self.code, file_path=self.file_path)
+```
+
+**2. Two different ways to validate — neither documented to prefer one over the other.**
+
+```python
+# Path A — via commenter
+report = PyCodeCommenter().from_file("f.py").validate()
+
+# Path B — via validator directly  
+report = DocstringValidator(file_path="f.py").validate_all()
+```
+
+Path A loses the file path (see above). Path B uses a different method name (`validate_all()` vs `validate()`). The docs use both without explaining the difference. New users pick one randomly.
+
+**API fix:** Deprecate `PyCodeCommenter.validate()` or make it delegate correctly. Standardise on `validate_all()` or rename it to `validate()` on the validator.
+
+**3. `ValidationReport.to_dict()` and `to_markdown()` have no corresponding `from_dict()`.**
+
+You can export but not import. This means you can't round-trip a report — e.g., store the JSON, load it later, add new issues, re-export. Minor for now, but becomes a problem when building dashboards or trend analysis.
+
+**4. The `check_coverage()` method on `PyCodeCommenter` returns a `FileCoverage` with `path="<string>"`.**
+
+```python
+# commenter.py line 456
+coverage = FileCoverage(path="<string>")
+```
+
+If the commenter was loaded from a file, the path should be the actual file path. `"<string>"` is an internal implementation detail that leaks to the user.
+
+**5. `ValidationStats` uses `infos` (plural) but `ValidationReport.to_dict()` now uses `info` (singular) after v2.2.0.**
+
+The internal attribute is `stats.infos`; the JSON key is `"info"`. This is an inconsistency that will confuse anyone reading both the Python API docs and the JSON output docs side by side.
+
+---
+
+## Question 4 — Top 3 Changes Required for Production-Grade Adoption
+
+### #1 — Fix the Patcher: Replace Line-Number Arithmetic with AST-Position-Aware Rewriting
+
+**Priority: BLOCKING. Teams will not use a tool that can corrupt their files.**
+
+The current patcher (`get_patched_code()`) is a string-manipulation layer built on top of AST line numbers. This is the correct *concept* but the *execution* is fragile.
+
+**What to do:**
+
+Replace the line-number approach with `libcst` (Concrete Syntax Tree). CST-based rewriting is the industry standard for safe code modification — it's what `black`, `isort`, `rope`, and `jedi` all use. With CST:
+
+- Multi-line signatures are handled correctly because the CST knows exactly where the body begins.
+- Existing comments and blank lines are preserved.
+- The edit is applied at the AST node level, not the string-manipulation level.
+- There is no index-shift bug.
+
+If adding `libcst` is too heavy, the minimum safe fix is: **use `ast.unparse()` + `ast.fix_missing_locations()`** — parse → modify the AST directly → unparse. This is lossy (comments are dropped) but at least it can't corrupt the file.
+
+Until this is fixed, the generate command should **always require `--backup`** when using `--inplace`, and the docs should warn explicitly that multi-line signatures are not yet safe.
+
+---
+
+### #2 — Make `validate` and `generate` Accept Directories (and Recursive Globbing)
+
+**Priority: HIGH. This is the single biggest DX friction point.**
+
+Every user's first instinct is `pycodecommenter validate .` or `pycodecommenter validate src/`. Today this silently fails or errors. The `coverage` command already accepts directories — the asymmetry is jarring and implies the tool is unfinished.
+
+**What to do:**
+
+```python
+# cli.py validate handler
+if os.path.isdir(args.file):
+    from pathlib import Path
+    py_files = list(Path(args.file).rglob("*.py"))
+    # apply exclude patterns
+    # run validator on each, aggregate report
+else:
+    # existing single-file path
+```
+
+Also add `--recursive` / `-r` flag. Add `--exclude` to `validate` (it's already on `coverage`).
+
+This is ~50 lines of code that removes the most common first-use failure.
+
+---
+
+### #3 — Wire the Config File Into the Runtime, and Add `--fail-below` to the Coverage CLI
+
+**Priority: HIGH. Without this, the tool cannot be adopted by teams.**
+
+Right now a team lead cannot enforce "all PRs must have >80% doc coverage" via a config file. They have to write a custom Python script (`check_coverage.py` — the recipe we documented). That is not acceptable for a tool that bills itself as CI-ready.
+
+**Two things to do, both required:**
+
+**3a. Wire `load_config()` into the CLI.**
+
+```python
+# cli.py, top of main()
+from .config import load_config, ConfigError
+try:
+    config = load_config()
+except ConfigError as e:
+    print(f"Warning: {e}", file=sys.stderr)
+    config = {}
+```
+
+Then honour at minimum these two keys:
+- `coverage.threshold` → used by `coverage` subcommand as `--fail-below` default
+- `exclude` → used by `coverage` and `validate` as default exclude list
+
+**3b. Add `--fail-below` to the `coverage` CLI.**
+
+```bash
+pycodecommenter coverage ./src --fail-below 80
+```
+
+This is the killer CI feature. Without it, `coverage` is a reporting tool, not an enforcement tool. With it, a team can add one line to their GitHub Actions workflow and get hard coverage gating. This is what makes the difference between "I tried it once" and "we installed it as a mandatory check."
+
+---
+
+## Summary Table
+
+| Issue | Severity | Effort |
+|---|---|---|
+| Multi-line signature patcher corrupts files | 🔴 Critical | Large (CST rewrite) |
+| `validate`/`generate` don't accept directories | 🟡 High | Small (50 lines) |
+| `--fail-below` missing from coverage CLI | 🟡 High | Small (20 lines) |
+| Config file is loaded but ignored | 🟡 High | Medium (wire into CLI) |
+| `PyCodeCommenter.validate()` loses file path | 🟠 Medium | Trivial (1 line) |
+| `ast.walk()` double-counts nested functions | 🟠 Medium | Small |
+| Hard-coded 8-space continuation in parser | 🟠 Medium | Small |
+| PEP 604 renders as `Union[X,Y]` not `X\|Y` | 🟠 Medium | Trivial |
+| `infos` vs `info` internal/external naming inconsistency | 🟢 Low | Trivial |
+| `check_coverage()` returns `path="<string>"` | 🟢 Low | Trivial |
+
+---
+
+## Bottom Line
+
+PyCodeCommenter has a real, defensible use case (legacy codebase bootstrapping + signature-accuracy validation) and solid bones (the AST-walking validator is genuinely useful). But it has **two critical reliability issues** (file corruption on multi-line signatures, directory-mode missing) that will cause any team's first serious use to fail. Fix those two first. Then wire the config file. After those three changes, this is a legitimate addition to a Python team's standard toolkit.