code-prune 1.0.0__py3-none-any.whl

code_prune/store.py

@@ -0,0 +1,266 @@
+"""Session-scoped SQLite store for scan findings and cross-file analysis.
+
+Per-file findings, together with the definitions and usage names collected
+while scanning, are written directly to an SQLite database instead of being
+accumulated in memory. Every scan run is assigned a UUID so multiple
+concurrent invocations share the same database file without interference.
+Once every file has been scanned, :meth:`SessionStore.compute_unused_symbols`
+resolves :data:`~code_prune.scanner.CATEGORY_UNUSED_SYMBOL` findings by
+aggregating definitions against usages in SQL. After the report is written
+the caller deletes the session records, keeping the database lean.
+
+Author: Ron Webb
+Since: 1.0.0
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+import threading
+from pathlib import Path
+
+from .scanner import CATEGORY_UNUSED_SYMBOL, Definition, Finding
+
+_CREATE_FINDINGS_TABLE = (
+    "CREATE TABLE IF NOT EXISTS findings ("
+    "    session_id TEXT NOT NULL,"
+    "    category   TEXT NOT NULL,"
+    "    file_path  TEXT NOT NULL,"
+    "    line       INTEGER NOT NULL,"
+    "    col        INTEGER NOT NULL,"
+    "    name       TEXT NOT NULL,"
+    "    message    TEXT NOT NULL"
+    ")"
+)
+_CREATE_DEFINITIONS_TABLE = (
+    "CREATE TABLE IF NOT EXISTS definitions ("
+    "    session_id TEXT NOT NULL,"
+    "    file_path  TEXT NOT NULL,"
+    "    line       INTEGER NOT NULL,"
+    "    col        INTEGER NOT NULL,"
+    "    name       TEXT NOT NULL,"
+    "    kind       TEXT NOT NULL"
+    ")"
+)
+_CREATE_IDENTIFIERS_TABLE = (
+    "CREATE TABLE IF NOT EXISTS identifiers ("
+    "    session_id TEXT NOT NULL,"
+    "    name       TEXT NOT NULL"
+    ")"
+)
+_CREATE_FINDINGS_INDEX = (
+    "CREATE INDEX IF NOT EXISTS idx_findings_session ON findings (session_id)"
+)
+_CREATE_DEFINITIONS_INDEX = (
+    "CREATE INDEX IF NOT EXISTS idx_definitions_session ON definitions (session_id)"
+)
+_CREATE_IDENTIFIERS_INDEX = (
+    "CREATE INDEX IF NOT EXISTS idx_identifiers_session_name"
+    " ON identifiers (session_id, name)"
+)
+
+_INSERT_FINDING = (
+    "INSERT INTO findings (session_id, category, file_path, line, col, name, message)"
+    " VALUES (?, ?, ?, ?, ?, ?, ?)"
+)
+_INSERT_DEFINITION = (
+    "INSERT INTO definitions (session_id, file_path, line, col, name, kind)"
+    " VALUES (?, ?, ?, ?, ?, ?)"
+)
+_INSERT_IDENTIFIER = "INSERT INTO identifiers (session_id, name) VALUES (?, ?)"
+
+_SELECT_FINDINGS = (
+    "SELECT category, file_path, line, col, name, message FROM findings"
+    " WHERE session_id = ? ORDER BY file_path ASC, line ASC, col ASC"
+)
+_SELECT_UNUSED_DEFINITIONS = (
+    "SELECT d.file_path, d.line, d.col, d.name, d.kind"
+    " FROM definitions d"
+    " WHERE d.session_id = ?"
+    " AND NOT EXISTS ("
+    "   SELECT 1 FROM identifiers i"
+    "   WHERE i.session_id = d.session_id AND i.name = d.name"
+    " )"
+    " ORDER BY d.file_path ASC, d.line ASC"
+)
+
+_DELETE_FINDINGS = "DELETE FROM findings WHERE session_id = ?"
+_DELETE_DEFINITIONS = "DELETE FROM definitions WHERE session_id = ?"
+_DELETE_IDENTIFIERS = "DELETE FROM identifiers WHERE session_id = ?"
+
+
+class SessionStore:
+    """SQLite-backed session store for dead-code scan results.
+
+    A single database file is shared across all threads and concurrent runs.
+    Every run is identified by a *session_id* (UUID string) so records are
+    always isolated. The cross-file "unused symbol" pass is performed entirely
+    in SQL via a ``NOT EXISTS`` anti-join so Python never has to materialise
+    every identifier in memory to resolve it.
+
+    Author: Ron Webb
+    Since: 1.0.0
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        """Open (or create) the SQLite database at *db_path*.
+
+        WAL journal mode is enabled so reads and writes do not block each
+        other; a threading lock serialises Python-side connection calls since
+        :mod:`sqlite3` connection objects are not thread-safe.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._lock = threading.Lock()
+        with self._lock:
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.execute("PRAGMA synchronous=NORMAL")
+            self._conn.execute(_CREATE_FINDINGS_TABLE)
+            self._conn.execute(_CREATE_DEFINITIONS_TABLE)
+            self._conn.execute(_CREATE_IDENTIFIERS_TABLE)
+            self._conn.execute(_CREATE_FINDINGS_INDEX)
+            self._conn.execute(_CREATE_DEFINITIONS_INDEX)
+            self._conn.execute(_CREATE_IDENTIFIERS_INDEX)
+            self._conn.commit()
+
+    def insert_findings(self, session_id: str, findings: list[Finding]) -> None:
+        """Persist *findings* for *session_id* in the database.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        rows = [
+            (
+                session_id,
+                f.category,
+                str(f.file_path),
+                f.line,
+                f.column,
+                f.name,
+                f.message,
+            )
+            for f in findings
+        ]
+        with self._lock:
+            self._conn.executemany(_INSERT_FINDING, rows)
+            self._conn.commit()
+
+    def insert_definitions(
+        self, session_id: str, definitions: list[Definition]
+    ) -> None:
+        """Persist *definitions* for *session_id* in the database.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        rows = [
+            (session_id, str(d.file_path), d.line, d.column, d.name, d.kind)
+            for d in definitions
+        ]
+        with self._lock:
+            self._conn.executemany(_INSERT_DEFINITION, rows)
+            self._conn.commit()
+
+    def insert_identifiers(self, session_id: str, names: list[str]) -> None:
+        """Persist usage *names* for *session_id* in the database.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        rows = [(session_id, name) for name in names]
+        with self._lock:
+            self._conn.executemany(_INSERT_IDENTIFIER, rows)
+            self._conn.commit()
+
+    def read_findings(self, session_id: str) -> list[dict[str, object]]:
+        """Return every per-file finding recorded for *session_id*.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        with self._lock:
+            rows = self._conn.execute(_SELECT_FINDINGS, (session_id,)).fetchall()
+        return [
+            {
+                "category": row[0],
+                "file": row[1],
+                "line": row[2],
+                "column": row[3],
+                "name": row[4],
+                "message": row[5],
+            }
+            for row in rows
+        ]
+
+    def compute_unused_symbols(
+        self, session_id: str, ignore_patterns: list[re.Pattern[str]]
+    ) -> list[dict[str, object]]:
+        """Return a finding for every definition never referenced elsewhere.
+
+        A definition is "unused" when its name never appears in the
+        project-wide ``identifiers`` table collected for *session_id*. Names
+        matching any of *ignore_patterns* (e.g. dunder methods, ``main``,
+        test hooks) are suppressed.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        with self._lock:
+            rows = self._conn.execute(
+                _SELECT_UNUSED_DEFINITIONS, (session_id,)
+            ).fetchall()
+        results: list[dict[str, object]] = []
+        for file_path, line, col, name, kind in rows:
+            if any(p.search(name) for p in ignore_patterns):
+                continue
+            results.append(
+                {
+                    "category": CATEGORY_UNUSED_SYMBOL,
+                    "file": file_path,
+                    "line": line,
+                    "column": col,
+                    "name": name,
+                    "message": f"{kind.capitalize()} '{name}' is never referenced.",
+                }
+            )
+        return results
+
+    def delete_session(self, session_id: str) -> None:
+        """Remove every record belonging to *session_id* from the database.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        with self._lock:
+            self._conn.execute(_DELETE_FINDINGS, (session_id,))
+            self._conn.execute(_DELETE_DEFINITIONS, (session_id,))
+            self._conn.execute(_DELETE_IDENTIFIERS, (session_id,))
+            self._conn.commit()
+
+    def close(self) -> None:
+        """Close the underlying database connection.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        with self._lock:
+            self._conn.close()
+
+    def __enter__(self) -> SessionStore:
+        """Return *self* to support use as a context manager.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Close the database connection on context manager exit.
+
+        Author: Ron Webb
+        Since: 1.0.0
+        """
+        self.close()

code_prune/symbol_ignore

@@ -0,0 +1,18 @@
+# Regex patterns for symbol names to exclude from unused-code findings.
+# One pattern per line. Lines starting with # are comments. Empty lines are ignored.
+
+# Dunder / magic methods and common entry points
+^__.*__$
+^main$
+
+# Common test hooks and fixtures
+^[Tt]est
+^setUp$
+^tearDown$
+^setUpClass$
+^tearDownClass$
+
+# Commonly overridden object methods
+^toString$
+^equals$
+^hashCode$

code_prune-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+code_prune/.codepruneignore,sha256=9mRAQiaYZdmlMXazShKy5pjbWEfMfFOTUaHOVC8irJI,218
+code_prune/__init__.py,sha256=CwVyXaoBkWqhSmGXqTI8LuXQJnJZStsT-XAugp4ilV4,601
+code_prune/cli.py,sha256=lAQMhkzygcGMrs_SmqBtQP9G_y_JWo6xWmcMCpN3q70,14524
+code_prune/config.ini,sha256=URW6VcIlLXCuV5MHBIh32ANoLEIRLSdPszWtIxao5Qs,42
+code_prune/config.py,sha256=DcNIfQrGNQK2D7F7aoS5nLN3hJsud0BSVzorHJSBieg,1105
+code_prune/logging.ini,sha256=05lRtFd7GeQoFfVA5I_nLd6WXqsj_aANOtkqm-FHkFw,534
+code_prune/parser.py,sha256=fnMQK7_xY8_uCDL75ZDbmZ6MgFV3sfF73gwnNzZWj50,2219
+code_prune/reporter.py,sha256=4DlIeiEAHQ4QIsRfps18QYOgrodeLpQ9mYFyN4LME0Y,11924
+code_prune/scanner.py,sha256=8Mk7e_J06HS5wJzsVKwR5Q0lQWIGI4zB49-WbKrYTnk,27006
+code_prune/store.py,sha256=ObeAjjIbegLf7PYAqiMQm_p1WHDl02Fd3GPICN15TQY,8895
+code_prune/symbol_ignore,sha256=0GxX-Uaa31ItSPedlsWc8jDN4PMiWZV5P8oidg322S8,383
+code_prune-1.0.0.dist-info/METADATA,sha256=wbPiDVmhtdK9fs3WyeeA61-OwFxjfrpKhoZvr4-hr5Q,6943
+code_prune-1.0.0.dist-info/WHEEL,sha256=M5asmiAlL6HEcOq52Yi5mmk9KmTVjY2RDPtO4p9DMrc,88
+code_prune-1.0.0.dist-info/entry_points.txt,sha256=iyShO9vHCgkDexXC9rYhzNlERG6xRZNXNXg2lOWIZE0,50
+code_prune-1.0.0.dist-info/licenses/LICENSE,sha256=Fs1jiRzMbn9F-lRZC-Z219JKSDzhFFCNibLKwGkRtCY,1065
+code_prune-1.0.0.dist-info/RECORD,,

code_prune-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.0
+Root-Is-Purelib: true
+Tag: py3-none-any

code_prune-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+code-prune=code_prune.cli:main
+

code_prune-1.0.0.dist-info/licenses/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.