pycodecommenter 2.1.0__tar.gz → 2.3.0__tar.gz

pycodecommenter-2.3.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.1.0 → pycodecommenter-2.3.0}/.github/workflows/publish.yml

@@ -1,33 +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
+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.1.0 → pycodecommenter-2.3.0}/.gitignore

@@ -1,56 +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/
+# 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.3.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.3.0",
+  "license": "MIT",
+  "author": "Nabasa Amos (Amos Quety)"
+}

pycodecommenter-2.3.0/CHANGELOG.md

@@ -0,0 +1,167 @@
+# 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.3.0] - 2026-08-22
+
+Follow-up work from an internal engineering audit (`Future Work/Vulnerabilties.md`),
+plus a documentation-fidelity pass (Phase 6) found during pre-release review.
+
+### Breaking Changes
+- **Minimum Python version raised from 3.8 to 3.9.** `pyproject.toml`'s
+  `requires-python` is now `>=3.9`; the `Programming Language :: Python :: 3.8`
+  classifier was removed. This was forced by the new `libcst` dependency (see
+  below), whose current release requires Python >=3.9. **Any user still on
+  Python 3.8 will no longer be able to install new releases of this package.**
+
+### Added
+- **New runtime dependency: `libcst>=1.1`.** `get_patched_code()` (the code
+  that inserts/updates generated docstrings) was rewritten to apply edits via
+  libcst's concrete syntax tree instead of line-number arithmetic on raw
+  source text. This is a hard dependency, not optional — installing
+  `pycodecommenter` now also installs `libcst`.
+- `generate` and `validate` CLI commands now accept a directory as well as a
+  single file, recursively collecting `.py` files (mirroring `coverage`'s
+  existing directory support).
+- `--fail-below THRESHOLD` flag on the `coverage` CLI command; exits 1 when
+  coverage is below the threshold.
+- `.pycodecommenter.yaml` config is now actually read by the CLI: its
+  top-level `exclude` list defaults `-e/--exclude` on all three subcommands,
+  and `coverage.threshold` defaults `--fail-below`. Both remain overridable
+  by explicit CLI flags. (Previously `config.py` existed but nothing called it.)
+- NumPy-style docstrings (`Parameters`/`Returns`/`Raises` with dash-underlined
+  headers) are now parsed as input, alongside Google and Sphinx style.
+  Sphinx-style input also gained `:type name: TYPE` support.
+
+### Fixed
+- **One-line function/class definitions could corrupt the file when patched.**
+  `def foo(): return 1` (body on the same physical line as the `def`) would
+  have its generated docstring inserted *before* the `def` line instead of
+  inside the function, producing a `SyntaxError`. Every one-liner shape
+  reproduced this: `pass`, `return`, multiple `;`-separated statements,
+  `async def`, and one-line `class` bodies. Fixed by the libcst rewrite above,
+  which converts a one-liner body to a proper indented block before inserting.
+  (This is a different, narrower bug than the "multi-line signature
+  corruption" originally suspected from the audit — see Notes below.)
+- `PyCodeCommenter.validate()` now passes the real file path to the validator
+  instead of a hardcoded `None`, so validation report locations show the
+  actual file (e.g. `src/api.py:12:my_func`) instead of `code:12:my_func`.
+- `PyCodeCommenter.check_coverage()` now uses the real file path instead of
+  the leaked `"<string>"` placeholder.
+- `docstring_parser.py`: multi-line `Args:` parameter descriptions in an
+  *existing* docstring being re-parsed were silently truncated unless the
+  continuation line was indented by exactly 8 spaces. Any other indentation
+  (including 4 spaces — the same indent this project's own generator uses)
+  lost the continuation text on merge. Now any non-blank continuation line is
+  recognized regardless of indentation depth.
+- `generate`/`validate` directory mode's default exclude list
+  (`__pycache__`, `.git`, `.venv`, `venv`, `env`, `.eggs`) missed common
+  vendor/build directories and used raw substring matching, causing two real
+  problems: `environment_config.py` was silently skipped (`"env"` is a
+  substring of `"environment"`), and files inside `.tox/.../site-packages/`
+  were *not* skipped — with `generate --inplace`, writing generated
+  docstrings into vendored third-party source. Expanded the default list
+  (added `.tox`, `.nox`, `__pypackages__`, `site-packages`, `build`, `dist`,
+  `.egg-info`, `.mypy_cache`, `.pytest_cache`, `node_modules`) and switched
+  to exact-path-component matching. `coverage`'s directory mode had the same
+  two problems independently (a separate, duplicated exclude list) and is
+  fixed the same way, plus a related bug: passing any custom `--exclude`
+  pattern previously replaced its default list entirely rather than adding
+  to it, silently losing `.venv`/`.git` protection.
+- A parameter's documented type (e.g. `x (int):`) was silently downgraded to
+  `x (any):` on regeneration whenever static type inference had nothing to
+  work with (no annotation on the parameter) — the type was parsed out of
+  the existing docstring but never stored or consulted. A real static
+  annotation still always wins; the docstring-parsed type is now used as a
+  fallback instead of being discarded.
+- An existing NumPy-style docstring was not recognized as such, so its
+  entire body was treated as free-text and a fresh, auto-generated
+  Google-style `Args:`/`Returns:` section was appended underneath it —
+  documenting the same parameter twice, in two styles, in one docstring.
+- Generated filler text for dunder methods (e.g. `__init__`) rendered with
+  broken spacing — `"Original of the   init  ."` — because
+  `name.replace('_', ' ')` turns every underscore into a space, including
+  the leading/trailing pair(s) dunder names have.
+
+### Changed
+- `ValidationStats.infos` renamed to `.info` (matches the existing `"info"`
+  key in JSON/markdown output). `.infos` remains available as a
+  backward-compatible property alias.
+
+### Notes
+- Two "CRITICAL" bugs originally suspected from the audit — corruption on
+  multi-line function signatures, and a line-shift bug when patching multiple
+  functions in one file — were investigated and do not reproduce against this
+  version or the pre-libcst version; both were verified directly against the
+  audit's own examples plus additional stress tests. No code changes were
+  made for either.
+- A third suspected bug — `ast.walk()` double-counting nested
+  functions/classes in `validate_all()`'s stats — also does not reproduce;
+  `ast.walk()` visits every node exactly once regardless of nesting depth.
+  `validator.py`'s counting logic is unchanged.
+- PEP 604 union rendering (`int | str` currently renders as `Union[int, str]`
+  in generated docstrings, per `type_analyzer.py`) was identified as a real,
+  minor issue but deliberately deferred: fixing it breaks
+  `test_type_analyzer.py::test_union_annotation`, which asserts the old
+  `Union[...]` output, and no test-file changes were in scope for that part
+  of the work.
+
+## [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.3.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.3.0
+date-released: "2026-08-22"
+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.1.0 → pycodecommenter-2.3.0}/CONTRIBUTING.md

@@ -1,29 +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!
+# 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.1.0 → pycodecommenter-2.3.0}/Future Work/Future Release WorkPlan.txt

@@ -1,15 +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
+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.3.0/Future Work/More future work prompt.md

@@ -0,0 +1,82 @@
+You have a full engineering audit attached @More future work.md. This is a
+multi-phase task with HARD STOPS between phases. You are not permitted to
+combine phases, skip ahead, or make architecture decisions on my behalf,
+even if the next step seems obvious.
+
+GLOBAL RULES (apply to every phase):
+- Work on a new git branch (e.g. `fix/audit-phaseN`). Do not commit to main.
+- Each phase lists the EXACT files you are allowed to modify. Do not touch
+  any other file. If you believe another file must change to complete the
+  phase, STOP and tell me why instead of doing it.
+- At the end of each phase, paste the FULL, UNTRUNCATED output of:
+    git diff --stat
+    git diff
+    python -m pytest -v
+  Do not summarize test results in prose ("37 passed") instead of pasting
+  the actual output. I want to see the real terminal output.
+- After posting the above, write exactly: "PHASE N COMPLETE — WAITING FOR
+  APPROVAL" and STOP. Do not start the next phase in the same response,
+  even partially. Do not pre-write code for the next phase "for
+  efficiency."
+- If completing a phase requires a design decision not specified below
+  (e.g. which library to use, which of two valid approaches to take),
+  STOP and ask me. Do not pick one yourself and proceed. A bracketed note
+  like "[we'll decide together]" means you must ask a direct question and
+  wait — it is not permission to choose.
+
+---
+
+PHASE 1 — Trivial fixes (files: commenter.py, validator.py, type_analyzer.py)
+- Fix PyCodeCommenter.validate() to pass self.file_path instead of None
+- Fix check_coverage() to use the real file path instead of "<string>"
+- Rename `infos` -> `info` consistently (backward-compatible alias is fine)
+- Fix PEP 604 rendering: `X | Y` instead of `Union[X, Y]`
+Do NOT touch get_patched_code() in this phase.
+
+---
+
+PHASE 2 — Regression tests ONLY (files: test_edge_cases.py, and any new
+test file you create — NO source files under PyCodeCommenter/ may change)
+- Write a test that reproduces the multi-line signature corruption bug
+  (Question 2, first CRITICAL issue in the audit)
+- Write a test that reproduces the line-shift insertion bug
+- Run the tests and paste output PROVING they fail against the current
+  (unfixed) source code. A test that passes at the end of this phase is a
+  FAILURE of this phase — it means either the test is wrong or you fixed
+  the bug early, both of which are not allowed here.
+- Do not modify commenter.py, validator.py, or type_analyzer.py in this
+  phase under any circumstance.
+
+---
+
+PHASE 3 — Fix the patcher (BLOCKED until I respond to a question)
+Before writing any code in this phase, ask me directly: "Should I use
+libcst, or the ast.unparse() fallback?" and list, in your own words, the
+tradeoffs of each — specifically including: does this approach preserve
+comments in the source file? Does it preserve formatting/quote style?
+What new dependency (if any) does it add?
+Wait for my answer before writing any implementation code.
+Once I've answered:
+- Implement the chosen approach in get_patched_code() only
+- Make the Phase 2 tests pass
+- Add a NEW test that checks whether comments in the source file survive
+  patching, and tell me honestly whether they do or don't
+- Confirm no other existing tests regress
+
+---
+
+PHASE 4 (files: cli.py, config.py)
+- Add directory support to `validate` and `generate` CLI commands
+- Add --fail-below to coverage CLI
+- Wire load_config() into cli.py
+
+---
+
+PHASE 5 (files: validator.py, docstring_parser.py)
+- Fix ast.walk() double-counting nested functions
+- Fix hardcoded 8-space continuation-line parsing
+
+---
+
+Begin with Phase 1 only. Stop after Phase 1 and wait for my explicit
+approval before starting Phase 2.