code-prune 1.0.0__tar.gz → 1.2.0__tar.gz

code_prune-1.2.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 1.2.0 - 2026-11-15
+
+### Added
+
+- `--search-path`: files and/or directories (separated by `;`) searched
+  textually for each `unused-symbol` candidate. Symbols found there are no
+  longer reported. Classes and functions/methods are both matched with a
+  whole-word regex; a method additionally requires its enclosing class's name
+  to be found in the same file. The symbol's own file is ignored and
+  `.codepruneignore` rules apply.
+- `--search-ext`: extensions of the files searched in `--search-path`
+  (default: every text file). Requires `--search-path`.
+
+## 1.1.0 - 2026-11-05
+
+### Added
+
+- `todo-marker` category: `TODO`/`FIXME`/`XXX` comments are reported separately
+  from `obsolete` since they are not necessarily obsolete.
+- `--categories` now accepts `unused-import`, `unused-local` and `unused-symbol`
+  explicitly; `unused` remains as shorthand for all three.
+- `category-counts` in the JSON report, and per-category counts in the HTML
+  report category filter dropdown.
+- A `.codepruneignore` in the target path extends the configured ignore
+  patterns; it is not affected by `config.ini`.
+
+### Changed
+
+- The HTML report's category filter is now a dropdown of the categories present
+  in the report (with counts).
+- Only supported source files are read; all other files are skipped.
+- `obsolete` now covers `@deprecated`-style markers and `deprecated` comments
+  only (TODO/FIXME/XXX moved to `todo-marker`).
+- README: installation uses `pip install code-prune`; Poetry instructions moved
+  to a Development section.
+
+### Fixed
+
+- Comments following a terminating statement are no longer reported as
+  unreachable code.
+- Documentation comments (Javadoc/JSDoc `/** ... */`) are no longer reported as
+  commented-out code.
+
+## 1.0.0 - 2026-11-01
+
+### Added
+
+- Core dead-code CLI: `code-prune <path> [options]`, built on Click and Rich,
+  mirroring the `litscan` basis project's architecture.
+- Tree-sitter based detection across Python, JavaScript, TypeScript, Java,
+  and Gosu for five categories of findings: unreachable code, unused imports
+  & local variables, cross-file unused functions/classes/methods, obsolete
+  (`@deprecated`/TODO/FIXME) markers, and commented-out code.
+- `config.ini` with an `[override] ignore-file` setting, a bundled
+  `.codepruneignore` (gitignore-style path exclusions), and a bundled
+  `symbol_ignore` (regex symbol-name exclusions for unused-symbol findings).
+- SQLite-backed `SessionStore` for concurrent per-file scanning and a
+  SQL-aggregated cross-file "unused symbol" resolution pass.
+- JSON and HTML report output via `--format`.
+
+### Fixed
+
+- Upgraded `tree-sitter-gosu` to `>=0.3.0,<0.4.0`, which decomposes `${...}`
+  string interpolation into real `interpolation`/`identifier` nodes. This
+  resolves a false-positive `unused-local`/`unused-import`/`unused-symbol`
+  finding for Gosu names referenced only inside string interpolation (e.g.
+  `"... ${myVar} ..."`).

{code_prune-1.0.0 → code_prune-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-prune
-Version: 1.0.0
+Version: 1.2.0
 Summary: Find unreachable, unused, and obsolete code before it becomes technical debt.
 License: MIT License
          
@@ -27,7 +27,7 @@ License-File: LICENSE
 Keywords: cli,static-analysis,dead-code,unused-code,tree-sitter,code-quality
 Author: Ron Webb
 Requires-Python: >=3.14
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
 
 # code-prune
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rcw3bb/code-prune/blob/main/LICENSE) [![Version](https://img.shields.io/badge/Version-1.0.0-green.svg)](https://github.com/rcw3bb/code-prune/blob/main/CHANGELOG.md) [![Python](https://img.shields.io/badge/Python-3.14%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-code-prune-orange)](https://pypi.org/project/code-prune/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rcw3bb/code-prune/blob/main/LICENSE) [![Version](https://img.shields.io/badge/Version-1.2.0-green.svg)](https://github.com/rcw3bb/code-prune/blob/main/CHANGELOG.md) [![Python](https://img.shields.io/badge/Python-3.14%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-code--prune-orange)](https://pypi.org/project/code-prune/)
 
 
 A CLI tool that scans a codebase for unreachable, unused, and obsolete code,
@@ -65,20 +65,26 @@ helping you find dead code before it becomes technical debt.
 ## Features
 
 `code-prune` parses source files with [tree-sitter](https://tree-sitter.github.io/tree-sitter/)
-and reports five categories of findings across **Python, JavaScript,
+and reports six categories of findings across **Python, JavaScript,
 TypeScript, Java, and Gosu**:
 
 - **Unreachable code** — statements after `return`/`raise`/`throw`/`break`/
   `continue`, and `if` branches whose condition is a constant falsy literal
-  (`False`/`false`/`0`).
+  (`False`/`false`/`0`). Comments are never reported as unreachable.
 - **Unused imports & local variables** — per-file, syntactic detection of
   bindings that are never referenced again in the same file.
 - **Unused functions/classes/methods** — cross-file detection of definitions
   that are never referenced anywhere in the scanned project.
 - **Obsolete markers** — `@deprecated`/`@Deprecated`-style decorators and
-  annotations, plus `TODO`/`FIXME`/`XXX` comment tags.
+  annotations, plus comments mentioning `deprecated`.
+- **TODO markers** — `TODO`/`FIXME`/`XXX` comment tags (not necessarily
+  obsolete, so reported separately).
 - **Commented-out code** — comments whose content heuristically resembles
-  source code.
+  source code. Documentation comments (Javadoc/JSDoc `/** ... */`) and Python
+  docstrings are not treated as commented-out code.
+
+Only supported files (`.py`, `.pyi`, `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`,
+`.java`, `.gs`, `.gsx`) are read; every other file is skipped.
 
 > Detection is heuristic and syntactic rather than a full scope- or
 > call-graph-aware analysis — treat findings as a starting point for review,
@@ -87,39 +93,50 @@ TypeScript, Java, and Gosu**:
 ## Requirements
 
 - Python `>=3.14`
-- Poetry `2.2`
 
 ## Installation
 
 ```powershell
-poetry install
+pip install code-prune
 ```
 
 ## Usage
 
 ```powershell
-poetry run code-prune <path> [options]
+code-prune <path> [options]
 ```
 
+`<path>` may be a file, a directory, or several of them separated by `;`.
+
 Common options:
 
 | Option            | Description                                                                 |
 |-------------------|------------------------------------------------------------------------------|
-| `--ext`           | Comma-separated extensions to include (e.g. `py,js,ts,java,gs,gsx`).         |
-| `--categories`    | Comma-separated categories to report: `unreachable,unused,obsolete,commented-out` (default: all). |
+| `--ext`           | Comma-separated extensions to include (e.g. `py,js,ts,java,gs,gsx`). Omit to scan every supported file. |
+| `--categories`    | Comma-separated categories to report: `unreachable`, `unused-import`, `unused-local`, `unused-symbol`, `obsolete`, `todo-marker`, `commented-out`. `unused` is shorthand for all three `unused-*` categories (default: all). |
 | `--format`        | Output format: `json`, `html`, or `all` (default: `json`).                  |
 | `--output`        | Base output filename without extension (default: `code-prune-output`).     |
 | `--output-dir`    | Directory for the report file(s) (default: `reports`).                     |
 | `--workers`       | Number of parallel worker threads used to scan files.                      |
 | `--db`            | Path to the SQLite scratch database used during a scan run.                |
 | `--target-list`   | Treat `path` as a file listing target paths, one per line.                 |
+| `--search-path`   | Files and/or directories (separated by `;`) searched textually for each `unused-symbol` candidate; a symbol found there is not reported. Classes and functions/methods are both matched by a whole-word regex; a method additionally requires its enclosing class's name to appear in the same file. The symbol's own file is skipped and `.codepruneignore` rules apply. |
+| `--search-ext`    | Comma-separated extensions of the files searched in `--search-path` (e.g. `xml,json`). Omit to search every text file. Requires `--search-path`. |
 
 Example:
 
 ```powershell
-poetry run code-prune src --categories unreachable,unused --format all
+code-prune src --categories unreachable,unused-import,todo-marker --format all
+code-prune src --categories unused-symbol --search-path "templates;../other-repo" --search-ext xml,json,py
 ```
 
+### Reports
+
+Both report formats include the number of findings per category: the JSON
+report has a `category-counts` object, and the HTML report shows the counts in
+a category dropdown filter listing the categories present in the report. The
+HTML summary line shows only the total number of findings.
+
 ## Configuration
 
 Logging is bootstrapped via `env-dir-bootstrap`. Set the `CODE_PRUNE_CONFIG_DIR`
@@ -130,13 +147,17 @@ resolve `logging.ini`, `config.ini`, `.codepruneignore`, and `symbol_ignore`.
 
 `.codepruneignore` holds gitignore-style patterns for files/directories to
 exclude from scanning (mirroring `.gitignore` syntax). Override the filename
-via `config.ini`:
+used in the configuration directory via `config.ini`:
 
 ```ini
 [override]
 ignore-file = .codepruneignore
 ```
 
+In addition, a `.codepruneignore` placed in the target path (the scanned
+directory, or the directory containing a scanned file) extends those patterns.
+It always uses that fixed name and is not affected by `config.ini`.
+
 ### Ignoring symbol names
 
 `symbol_ignore` holds one regex pattern per line, matched against symbol
@@ -146,6 +167,20 @@ intentionally-unreferenced symbols.
 
 ## Development
 
+Development uses [Poetry](https://python-poetry.org/) `2.2`.
+
+Install the project and its dev dependencies:
+
+```powershell
+poetry install
+```
+
+Run the CLI from the working tree:
+
+```powershell
+poetry run code-prune <path> [options]
+```
+
 Run tests with coverage and generate an HTML report:
 
 ```powershell

{code_prune-1.0.0 → code_prune-1.2.0}/README.md

@@ -1,6 +1,6 @@
 # code-prune
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rcw3bb/code-prune/blob/main/LICENSE) [![Version](https://img.shields.io/badge/Version-1.0.0-green.svg)](https://github.com/rcw3bb/code-prune/blob/main/CHANGELOG.md) [![Python](https://img.shields.io/badge/Python-3.14%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-code-prune-orange)](https://pypi.org/project/code-prune/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rcw3bb/code-prune/blob/main/LICENSE) [![Version](https://img.shields.io/badge/Version-1.2.0-green.svg)](https://github.com/rcw3bb/code-prune/blob/main/CHANGELOG.md) [![Python](https://img.shields.io/badge/Python-3.14%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-code--prune-orange)](https://pypi.org/project/code-prune/)
 
 
 A CLI tool that scans a codebase for unreachable, unused, and obsolete code,
@@ -9,20 +9,26 @@ helping you find dead code before it becomes technical debt.
 ## Features
 
 `code-prune` parses source files with [tree-sitter](https://tree-sitter.github.io/tree-sitter/)
-and reports five categories of findings across **Python, JavaScript,
+and reports six categories of findings across **Python, JavaScript,
 TypeScript, Java, and Gosu**:
 
 - **Unreachable code** — statements after `return`/`raise`/`throw`/`break`/
   `continue`, and `if` branches whose condition is a constant falsy literal
-  (`False`/`false`/`0`).
+  (`False`/`false`/`0`). Comments are never reported as unreachable.
 - **Unused imports & local variables** — per-file, syntactic detection of
   bindings that are never referenced again in the same file.
 - **Unused functions/classes/methods** — cross-file detection of definitions
   that are never referenced anywhere in the scanned project.
 - **Obsolete markers** — `@deprecated`/`@Deprecated`-style decorators and
-  annotations, plus `TODO`/`FIXME`/`XXX` comment tags.
+  annotations, plus comments mentioning `deprecated`.
+- **TODO markers** — `TODO`/`FIXME`/`XXX` comment tags (not necessarily
+  obsolete, so reported separately).
 - **Commented-out code** — comments whose content heuristically resembles
-  source code.
+  source code. Documentation comments (Javadoc/JSDoc `/** ... */`) and Python
+  docstrings are not treated as commented-out code.
+
+Only supported files (`.py`, `.pyi`, `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`,
+`.java`, `.gs`, `.gsx`) are read; every other file is skipped.
 
 > Detection is heuristic and syntactic rather than a full scope- or
 > call-graph-aware analysis — treat findings as a starting point for review,
@@ -31,39 +37,50 @@ TypeScript, Java, and Gosu**:
 ## Requirements
 
 - Python `>=3.14`
-- Poetry `2.2`
 
 ## Installation
 
 ```powershell
-poetry install
+pip install code-prune
 ```
 
 ## Usage
 
 ```powershell
-poetry run code-prune <path> [options]
+code-prune <path> [options]
 ```
 
+`<path>` may be a file, a directory, or several of them separated by `;`.
+
 Common options:
 
 | Option            | Description                                                                 |
 |-------------------|------------------------------------------------------------------------------|
-| `--ext`           | Comma-separated extensions to include (e.g. `py,js,ts,java,gs,gsx`).         |
-| `--categories`    | Comma-separated categories to report: `unreachable,unused,obsolete,commented-out` (default: all). |
+| `--ext`           | Comma-separated extensions to include (e.g. `py,js,ts,java,gs,gsx`). Omit to scan every supported file. |
+| `--categories`    | Comma-separated categories to report: `unreachable`, `unused-import`, `unused-local`, `unused-symbol`, `obsolete`, `todo-marker`, `commented-out`. `unused` is shorthand for all three `unused-*` categories (default: all). |
 | `--format`        | Output format: `json`, `html`, or `all` (default: `json`).                  |
 | `--output`        | Base output filename without extension (default: `code-prune-output`).     |
 | `--output-dir`    | Directory for the report file(s) (default: `reports`).                     |
 | `--workers`       | Number of parallel worker threads used to scan files.                      |
 | `--db`            | Path to the SQLite scratch database used during a scan run.                |
 | `--target-list`   | Treat `path` as a file listing target paths, one per line.                 |
+| `--search-path`   | Files and/or directories (separated by `;`) searched textually for each `unused-symbol` candidate; a symbol found there is not reported. Classes and functions/methods are both matched by a whole-word regex; a method additionally requires its enclosing class's name to appear in the same file. The symbol's own file is skipped and `.codepruneignore` rules apply. |
+| `--search-ext`    | Comma-separated extensions of the files searched in `--search-path` (e.g. `xml,json`). Omit to search every text file. Requires `--search-path`. |
 
 Example:
 
 ```powershell
-poetry run code-prune src --categories unreachable,unused --format all
+code-prune src --categories unreachable,unused-import,todo-marker --format all
+code-prune src --categories unused-symbol --search-path "templates;../other-repo" --search-ext xml,json,py
 ```
 
+### Reports
+
+Both report formats include the number of findings per category: the JSON
+report has a `category-counts` object, and the HTML report shows the counts in
+a category dropdown filter listing the categories present in the report. The
+HTML summary line shows only the total number of findings.
+
 ## Configuration
 
 Logging is bootstrapped via `env-dir-bootstrap`. Set the `CODE_PRUNE_CONFIG_DIR`
@@ -74,13 +91,17 @@ resolve `logging.ini`, `config.ini`, `.codepruneignore`, and `symbol_ignore`.
 
 `.codepruneignore` holds gitignore-style patterns for files/directories to
 exclude from scanning (mirroring `.gitignore` syntax). Override the filename
-via `config.ini`:
+used in the configuration directory via `config.ini`:
 
 ```ini
 [override]
 ignore-file = .codepruneignore
 ```
 
+In addition, a `.codepruneignore` placed in the target path (the scanned
+directory, or the directory containing a scanned file) extends those patterns.
+It always uses that fixed name and is not affected by `config.ini`.
+
 ### Ignoring symbol names
 
 `symbol_ignore` holds one regex pattern per line, matched against symbol
@@ -90,6 +111,20 @@ intentionally-unreferenced symbols.
 
 ## Development
 
+Development uses [Poetry](https://python-poetry.org/) `2.2`.
+
+Install the project and its dev dependencies:
+
+```powershell
+poetry install
+```
+
+Run the CLI from the working tree:
+
+```powershell
+poetry run code-prune <path> [options]
+```
+
 Run tests with coverage and generate an HTML report:
 
 ```powershell

{code_prune-1.0.0 → code_prune-1.2.0}/code_prune/__init__.py

@@ -10,7 +10,7 @@ Since: 1.0.0
 from env_dir_bootstrap import EnvDirBootstrap
 
 __app_name__ = "code-prune"
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 
 _bootstrapper = EnvDirBootstrap(
     env_var="CODE_PRUNE_CONFIG_DIR",