code-prune 1.0.0__tar.gz

code_prune-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ron Webb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code_prune-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: code-prune
+Version: 1.0.0
+Summary: Find unreachable, unused, and obsolete code before it becomes technical debt.
+License: MIT License
+         
+         Copyright (c) 2026 Ron Webb
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+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: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: braincraft (>=1.3.1,<2.0.0)
+Requires-Dist: click (>=8.0.0,<9.0.0)
+Requires-Dist: env-dir-bootstrap (>=1.0.0,<2.0.0)
+Requires-Dist: logenrich (>=1.0.1,<2.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: tree-sitter (>=0.26.0,<0.27.0)
+Requires-Dist: tree-sitter-gosu (>=0.3.0,<0.4.0)
+Requires-Dist: tree-sitter-java (>=0.23.5,<0.24.0)
+Requires-Dist: tree-sitter-javascript (>=0.25.0,<0.26.0)
+Requires-Dist: tree-sitter-python (>=0.25.0,<0.26.0)
+Requires-Dist: tree-sitter-typescript (>=0.23.2,<0.24.0)
+Project-URL: Changelog, https://github.com/rcw3bb/code-prune/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/rcw3bb/code-prune
+Project-URL: Issues, https://github.com/rcw3bb/code-prune/issues
+Project-URL: Repository, https://github.com/rcw3bb/code-prune
+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/)
+
+
+A CLI tool that scans a codebase for unreachable, unused, and obsolete code,
+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,
+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`).
+- **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.
+- **Commented-out code** — comments whose content heuristically resembles
+  source code.
+
+> Detection is heuristic and syntactic rather than a full scope- or
+> call-graph-aware analysis — treat findings as a starting point for review,
+> not a guarantee.
+
+## Requirements
+
+- Python `>=3.14`
+- Poetry `2.2`
+
+## Installation
+
+```powershell
+poetry install
+```
+
+## Usage
+
+```powershell
+poetry run code-prune <path> [options]
+```
+
+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). |
+| `--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.                 |
+
+Example:
+
+```powershell
+poetry run code-prune src --categories unreachable,unused --format all
+```
+
+## Configuration
+
+Logging is bootstrapped via `env-dir-bootstrap`. Set the `CODE_PRUNE_CONFIG_DIR`
+environment variable to override the default configuration directory used to
+resolve `logging.ini`, `config.ini`, `.codepruneignore`, and `symbol_ignore`.
+
+### Ignoring files and directories
+
+`.codepruneignore` holds gitignore-style patterns for files/directories to
+exclude from scanning (mirroring `.gitignore` syntax). Override the filename
+via `config.ini`:
+
+```ini
+[override]
+ignore-file = .codepruneignore
+```
+
+### Ignoring symbol names
+
+`symbol_ignore` holds one regex pattern per line, matched against symbol
+names to suppress from "unused function/class/method" findings — useful for
+dunder methods, `main`, test hooks (`test_*`, `setUp`), and similar
+intentionally-unreferenced symbols.
+
+## Development
+
+Run tests with coverage and generate an HTML report:
+
+```powershell
+poetry run pytest --cov=code_prune tests --cov-report html
+```
+
+Format and lint the code:
+
+```powershell
+poetry run black code_prune; poetry run pylint code_prune
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+

code_prune-1.0.0/README.md

@@ -0,0 +1,107 @@
+# 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/)
+
+
+A CLI tool that scans a codebase for unreachable, unused, and obsolete code,
+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,
+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`).
+- **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.
+- **Commented-out code** — comments whose content heuristically resembles
+  source code.
+
+> Detection is heuristic and syntactic rather than a full scope- or
+> call-graph-aware analysis — treat findings as a starting point for review,
+> not a guarantee.
+
+## Requirements
+
+- Python `>=3.14`
+- Poetry `2.2`
+
+## Installation
+
+```powershell
+poetry install
+```
+
+## Usage
+
+```powershell
+poetry run code-prune <path> [options]
+```
+
+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). |
+| `--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.                 |
+
+Example:
+
+```powershell
+poetry run code-prune src --categories unreachable,unused --format all
+```
+
+## Configuration
+
+Logging is bootstrapped via `env-dir-bootstrap`. Set the `CODE_PRUNE_CONFIG_DIR`
+environment variable to override the default configuration directory used to
+resolve `logging.ini`, `config.ini`, `.codepruneignore`, and `symbol_ignore`.
+
+### Ignoring files and directories
+
+`.codepruneignore` holds gitignore-style patterns for files/directories to
+exclude from scanning (mirroring `.gitignore` syntax). Override the filename
+via `config.ini`:
+
+```ini
+[override]
+ignore-file = .codepruneignore
+```
+
+### Ignoring symbol names
+
+`symbol_ignore` holds one regex pattern per line, matched against symbol
+names to suppress from "unused function/class/method" findings — useful for
+dunder methods, `main`, test hooks (`test_*`, `setUp`), and similar
+intentionally-unreferenced symbols.
+
+## Development
+
+Run tests with coverage and generate an HTML report:
+
+```powershell
+poetry run pytest --cov=code_prune tests --cov-report html
+```
+
+Format and lint the code:
+
+```powershell
+poetry run black code_prune; poetry run pylint code_prune
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

code_prune-1.0.0/code_prune/.codepruneignore

@@ -0,0 +1,9 @@
+# Gitignore-style patterns for files/directories to exclude from scanning.
+# One pattern per line. Lines starting with # are comments. Empty lines are ignored.
+.git/
+node_modules/
+dist/
+build/
+__pycache__/
+.venv/
+bin/

code_prune-1.0.0/code_prune/__init__.py

@@ -0,0 +1,25 @@
+"""
+Package initialization for code_prune.
+
+Bootstraps the configuration directory and logging setup.
+
+Author: Ron Webb
+Since: 1.0.0
+"""
+
+from env_dir_bootstrap import EnvDirBootstrap
+
+__app_name__ = "code-prune"
+__version__ = "1.0.0"
+
+_bootstrapper = EnvDirBootstrap(
+    env_var="CODE_PRUNE_CONFIG_DIR",
+    resources=["logging.ini", "config.ini", ".codepruneignore", "symbol_ignore"],
+    package="code_prune",
+)
+
+_bootstrapper.setup()
+
+CONF_DIR = str(_bootstrapper.get_dir())
+PATH_IGNORE_PATH = _bootstrapper.resolve(".codepruneignore")
+SYMBOL_IGNORE_PATH = _bootstrapper.resolve("symbol_ignore")