PyPI - code-prune - Versions diffs - 1.0.0__tar.gz → 1.1.0__tar.gz - Mend

code-prune 1.0.0tar.gz → 1.1.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

{code_prune-1.0.0 → code_prune-1.1.0}/CHANGELOG.md RENAMED Viewed

@@ -1,5 +1,35 @@
 # Changelog
+## 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

{code_prune-1.0.0 → code_prune-1.1.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-prune
-Version: 1.0.0
+Version: 1.1.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.1.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,26 +93,27 @@ 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`).                     |
@@ -117,9 +124,16 @@ Common options:
 Example:
 ```powershell
-poetry run code-prune src --categories unreachable,unused --format all
+code-prune src --categories unreachable,unused-import,todo-marker --format all
 ```
+### 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 +144,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 +164,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.1.0}/README.md RENAMED Viewed

@@ -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.1.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,26 +37,27 @@ 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`).                     |
@@ -61,9 +68,16 @@ Common options:
 Example:
 ```powershell
-poetry run code-prune src --categories unreachable,unused --format all
+code-prune src --categories unreachable,unused-import,todo-marker --format all
 ```
+### 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 +88,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 +108,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.1.0}/code_prune/__init__.py RENAMED Viewed

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

{code_prune-1.0.0 → code_prune-1.1.0}/code_prune/cli.py RENAMED Viewed

@@ -35,10 +35,19 @@ from . import PATH_IGNORE_PATH
 from . import SYMBOL_IGNORE_PATH
 from .config import Config
 from .reporter import write_outputs
-from .scanner import CLI_CATEGORIES, load_name_ignore_patterns, scan_file
+from .scanner import (
+    CATEGORY_UNUSED_ALIAS,
+    CATEGORY_UNUSED_SYMBOL,
+    CLI_CATEGORIES,
+    SUPPORTED_EXTENSIONS,
+    UNUSED_CATEGORIES,
+    load_name_ignore_patterns,
+    scan_file,
+)
 from .store import SessionStore
 _VALID_FORMATS = ("json", "html", "all")
+_TARGET_IGNORE_FILENAME = ".codepruneignore"
 def _configure_stream_encoding(stream: object) -> None:
@@ -117,7 +126,10 @@ def _read_target_list(list_file: Path) -> list[Path]:
 def _parse_categories(raw: str) -> set[str]:
     """Parse a comma-separated category string into a validated set.
-    Raises :class:`click.UsageError` when an unknown category is given.
+    The ``unused`` alias is expanded into ``unused-import``, ``unused-local``
+    and ``unused-symbol``, so the returned set only holds concrete finding
+    categories. Raises :class:`click.UsageError` when an unknown category is
+    given.
     Author: Ron Webb
     Since: 1.0.0
@@ -129,6 +141,9 @@ def _parse_categories(raw: str) -> set[str]:
             f"Unknown categories: {', '.join(sorted(unknown))}. "
             f"Valid categories: {', '.join(CLI_CATEGORIES)}."
         )
+    if CATEGORY_UNUSED_ALIAS in requested:
+        requested.discard(CATEGORY_UNUSED_ALIAS)
+        requested.update(UNUSED_CATEGORIES)
     return requested
@@ -145,7 +160,7 @@ def _scan_and_store(task: tuple[Path, SessionStore, str, set[str]]) -> None:
     result = scan_file(file_path)
     findings = [f for f in result.findings if _category_enabled(f.category, categories)]
     store.insert_findings(session_id, findings)
-    if "unused" in categories:
+    if CATEGORY_UNUSED_SYMBOL in categories:
         store.insert_definitions(session_id, result.definitions)
     store.insert_identifiers(session_id, result.usages)
@@ -156,15 +171,7 @@ def _category_enabled(category: str, categories: set[str]) -> bool:
     Author: Ron Webb
     Since: 1.0.0
     """
-    if category == "unreachable":
-        return "unreachable" in categories
-    if category in ("unused-import", "unused-local", "unused-symbol"):
-        return "unused" in categories
-    if category == "obsolete":
-        return "obsolete" in categories
-    if category == "commented-out":
-        return "commented-out" in categories
-    return False
+    return category in categories
 def _load_ignore_file(ignore_path: Path, base_dir: Path) -> IgnoreFile | None:
@@ -207,8 +214,61 @@ def _build_ignore(base_dir: Path) -> IgnoreFile | None:
     return _load_ignore_file(Path(PATH_IGNORE_PATH), base_dir)
+class _CombinedIgnore:
+    """Path matcher that ignores a path when any wrapped matcher does.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    def __init__(self, matchers: list[IgnoreFile]) -> None:
+        """Store the matchers to consult.
+        Author: Ron Webb
+        Since: 1.1.0
+        """
+        self._matchers = matchers
+    def is_ignored(self, path: Path) -> bool:
+        """Return whether any wrapped matcher ignores *path*.
+        Author: Ron Webb
+        Since: 1.1.0
+        """
+        return any(matcher.is_ignored(path) for matcher in self._matchers)
+def _build_target_ignore(target: Path) -> IgnoreFile | None:
+    """Build a matcher from the ``.codepruneignore`` located at *target*.
+    The file is looked up in *target* itself (or its parent for a file target)
+    under a fixed name, so it is not affected by ``config.ini``. Returns
+    ``None`` when there is no such file.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    base_dir = target if target.is_dir() else target.parent
+    ignore_path = base_dir / _TARGET_IGNORE_FILENAME
+    if not ignore_path.is_file():
+        return None
+    return _load_ignore_file(ignore_path, base_dir)
+def _build_combined_ignore(target: Path) -> _CombinedIgnore | None:
+    """Combine the configured ignore file with the target's ``.codepruneignore``.
+    The target-level file extends, rather than replaces, the configured one.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    matchers = [m for m in (_build_ignore(target), _build_target_ignore(target)) if m]
+    return _CombinedIgnore(matchers) if matchers else None
 def _walk_unignored(
-    root: Path, ignore: IgnoreFile | None
+    root: Path, ignore: IgnoreFile | _CombinedIgnore | None
 ) -> Generator[Path, None, None]:
     """Recursively yield files under *root*, pruning directories matched by *ignore*.
@@ -225,14 +285,16 @@ def _walk_unignored(
 def discover_files(
-    path: Path, extensions: list[str], ignore: IgnoreFile | None = None
+    path: Path,
+    extensions: list[str],
+    ignore: IgnoreFile | _CombinedIgnore | None = None,
 ) -> list[Path]:
-    """Discover files under *path* that match the given extensions.
+    """Discover supported source files under *path*.
-    When *extensions* is empty every file is included.
-    Both files and directories are accepted; for a plain file the extension
-    filter still applies. When *ignore* is given, matching files are skipped
-    and matching directories are pruned from the walk entirely.
+    Only files with an extension in :data:`SUPPORTED_EXTENSIONS` are returned;
+    when *extensions* is given it narrows that set further. Both files and
+    directories are accepted. When *ignore* is given, matching files are
+    skipped and matching directories are pruned from the walk entirely.
     Author: Ron Webb
     Since: 1.0.0
@@ -245,9 +307,12 @@ def discover_files(
     else:
         return []
-    if not extensions:
-        return candidates
-    return [f for f in candidates if f.suffix.lower() in extensions]
+    allowed = (
+        SUPPORTED_EXTENSIONS.intersection(extensions)
+        if extensions
+        else SUPPORTED_EXTENSIONS
+    )
+    return [f for f in candidates if f.suffix.lower() in allowed]
 def _run_concurrent_scan(
@@ -297,7 +362,7 @@ def _run_concurrent_scan(
     default="",
     help=(
         "Comma-separated file extensions to include "
-        "(e.g. py,java,js,ts,gs,gsx). Omit to scan all files."
+        "(e.g. py,java,js,ts,gs,gsx). Omit to scan every supported file."
     ),
 )
 @click.option(
@@ -352,8 +417,8 @@ def _run_concurrent_scan(
     help=(
         "Comma-separated categories to report: "
         f"{', '.join(CLI_CATEGORIES)} (default: all). "
-        "'unused' covers unused imports, local variables, and "
-        "cross-file-unused functions/classes/methods."
+        "'unused' is shorthand for unused-import, unused-local and "
+        "unused-symbol (cross-file unused functions/classes/methods)."
     ),
 )
 @click.option(
@@ -387,6 +452,11 @@ def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
     _logger.info(_header)
     _console.print(f"[bold]{_header}[/bold]")
     extensions = _parse_extensions(ext) if ext else []
+    unsupported = sorted(set(extensions) - SUPPORTED_EXTENSIONS)
+    if unsupported:
+        _console.print(
+            f"[yellow]Ignoring unsupported extension(s): {', '.join(unsupported)}[/yellow]"
+        )
     selected_categories = _parse_categories(categories)
     paths = _parse_paths(path)
     if target_list:
@@ -438,7 +508,7 @@ def _discover_all_files(paths: list[Path], extensions: list[str]) -> list[Path]:
     files: list[Path] = []
     with _console.status("[bold cyan]Discovering files\u2026", spinner="dots"):
         for target_path in paths:
-            ignore = _build_ignore(target_path)
+            ignore = _build_combined_ignore(target_path)
             for found_file in discover_files(target_path, extensions, ignore):
                 if found_file not in seen:
                     seen.add(found_file)
@@ -461,7 +531,7 @@ def _scan_project(
     try:
         _run_concurrent_scan(files, store, session_id, workers, categories)
         findings = store.read_findings(session_id)
-        if "unused" in categories:
+        if CATEGORY_UNUSED_SYMBOL in categories:
             name_ignore_patterns = load_name_ignore_patterns(Path(SYMBOL_IGNORE_PATH))
             findings.extend(
                 store.compute_unused_symbols(session_id, name_ignore_patterns)

{code_prune-1.0.0 → code_prune-1.1.0}/code_prune/reporter.py RENAMED Viewed

@@ -59,7 +59,7 @@ _CSS = """
   th.sortable.desc .sort-icon::after { content: '\\25bc'; }
   th.sortable:not(.asc):not(.desc) .sort-icon::after { content: '\\21c5'; opacity: 0.6; }
   .filter-row th { background: #1a3a5c; padding: 0.3em 1em 0.5em; }
-  .filter-row input {
+  .filter-row input, .filter-row select {
     width: 100%;
     padding: 0.3em 0.5em;
     border: 1px solid #3d6b9e;
@@ -70,7 +70,7 @@ _CSS = """
     outline: none;
   }
   .filter-row input::placeholder { color: #aac4e8; }
-  .filter-row input:focus { border-color: #7eb3e8; background: #255085; }
+  .filter-row input:focus, .filter-row select:focus { border-color: #7eb3e8; background: #255085; }
   td {
     padding: 0.6em 1em;
     border-bottom: 1px solid #e8ecf0;
@@ -93,6 +93,23 @@ _CSS = """
 """
+def _category_counts(
+    findings: list[dict[str, object]], categories: list[str]
+) -> dict[str, int]:
+    """Return the number of findings per category, sorted by category name.
+    Every selected category is present, with ``0`` when it has no findings.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    counts = dict.fromkeys(categories, 0)
+    for finding in findings:
+        category = str(finding["category"])
+        counts[category] = counts.get(category, 0) + 1
+    return dict(sorted(counts.items()))
 def _write_json(
     findings: list[dict[str, object]],
     path: Path,
@@ -111,12 +128,31 @@ def _write_json(
         "run-date": run_date,
         "paths-scanned": paths_scanned,
         "categories": categories,
+        "category-counts": _category_counts(findings, categories),
         "findings": findings,
     }
     path.write_text(json.dumps(report, indent=2), encoding="utf-8")
-def _build_thead_html() -> str:
+def _build_category_select(counts: dict[str, int]) -> str:
+    """Return the category ``<select>`` listing categories that have findings.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    options = ['<option value="">All categories</option>']
+    for category, count in counts.items():
+        if count:
+            escaped = _html.escape(category, quote=True)
+            options.append(f'<option value="{escaped}">{escaped} ({count})</option>')
+    return (
+        '<select id="filter-category" onchange="codePruneFilter()">'
+        + "".join(options)
+        + "</select>"
+    )
+def _build_thead_html(counts: dict[str, int]) -> str:
     """Return the HTML ``<thead>`` element with sortable headers and a filter row.
     Author: Ron Webb
@@ -133,8 +169,7 @@ def _build_thead_html() -> str:
         "</tr>\n"
         '      <tr class="filter-row">'
         "<th></th>"
-        '<th><input type="text" id="filter-category" placeholder="Filter category\u2026"'
-        ' oninput="codePruneFilter()"></th>'
+        f"<th>{_build_category_select(counts)}</th>"
         '<th><input type="text" id="filter-location" placeholder="Filter location\u2026"'
         ' oninput="codePruneFilter()"></th>'
         '<th><input type="text" id="filter-name" placeholder="Filter name\u2026"'
@@ -145,6 +180,15 @@ def _build_thead_html() -> str:
     )
+def _build_summary(total: int) -> str:
+    """Return the summary line with the total number of findings.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    return f"Found {total} finding(s)"
 def _build_html_scaffold(  # pylint: disable=too-many-arguments,too-many-positional-arguments
     run_date: str,
     total: int,
@@ -152,13 +196,14 @@ def _build_html_scaffold(  # pylint: disable=too-many-arguments,too-many-positio
     script: str,
     paths_scanned: list[str],
     categories: list[str],
+    counts: dict[str, int],
 ) -> str:
     """Wrap the table body and script into a complete HTML document.
     Author: Ron Webb
     Since: 1.0.0
     """
-    thead = _build_thead_html()
+    thead = _build_thead_html(counts)
     paths_html = "<br>".join(_html.escape(p, quote=False) for p in paths_scanned)
     categories_html = (
         ", ".join(_html.escape(c, quote=False) for c in categories) or "(none)"
@@ -181,7 +226,7 @@ def _build_html_scaffold(  # pylint: disable=too-many-arguments,too-many-positio
         f"    <p>Paths scanned: {paths_html}</p>\n"
         f"    <p>Categories: {categories_html}</p>\n"
         "  </header>\n"
-        f'  <p class="summary">Found {total} finding(s)</p>\n'
+        f'  <p class="summary">{_build_summary(total)}</p>\n'
         '  <div class="table-wrap">\n'
         "  <table>\n"
         f"{thead}"
@@ -236,12 +281,12 @@ _SCRIPT = (
     "  }\n"
     "\n"
     "  function applyFilter() {\n"
-    "    var catFilter = document.getElementById('filter-category').value.toLowerCase();\n"
+    "    var catFilter = document.getElementById('filter-category').value;\n"
     "    var locFilter = document.getElementById('filter-location').value.toLowerCase();\n"
     "    var nameFilter = document.getElementById('filter-name').value.toLowerCase();\n"
     "    var tbody = document.querySelector('tbody');\n"
     "    tbody.querySelectorAll('tr').forEach(function (row) {\n"
-    "      var catMatch = !catFilter || row.dataset.category.toLowerCase().indexOf(catFilter) !== -1;\n"
+    "      var catMatch = !catFilter || row.dataset.category === catFilter;\n"
     "      var locMatch = !locFilter || row.dataset.location.toLowerCase().indexOf(locFilter) !== -1;\n"
     "      var nameMatch = !nameFilter || row.dataset.name.toLowerCase().indexOf(nameFilter) !== -1;\n"
     "      row.style.display = (catMatch && locMatch && nameMatch) ? '' : 'none';\n"
@@ -309,7 +354,13 @@ def _build_html(
         )
     rows_html = "\n".join(rows)
     return _build_html_scaffold(
-        run_date, len(findings), rows_html, _SCRIPT, paths_scanned, categories
+        run_date,
+        len(findings),
+        rows_html,
+        _SCRIPT,
+        paths_scanned,
+        categories,
+        _category_counts(findings, categories),
     )

{code_prune-1.0.0 → code_prune-1.1.0}/code_prune/scanner.py RENAMED Viewed

@@ -33,12 +33,38 @@ CATEGORY_UNUSED_IMPORT = "unused-import"
 CATEGORY_UNUSED_LOCAL = "unused-local"
 CATEGORY_UNUSED_SYMBOL = "unused-symbol"
 CATEGORY_OBSOLETE = "obsolete"
+CATEGORY_TODO_MARKER = "todo-marker"
 CATEGORY_COMMENTED_OUT = "commented-out"
-#: Categories a user may toggle via ``--categories``. ``unused`` expands to
-#: both :data:`CATEGORY_UNUSED_IMPORT`/:data:`CATEGORY_UNUSED_LOCAL` (per-file)
-#: and :data:`CATEGORY_UNUSED_SYMBOL` (cross-file).
-CLI_CATEGORIES = ("unreachable", "unused", "obsolete", "commented-out")
+#: Blanket ``--categories`` value that expands to every ``unused-*`` category.
+CATEGORY_UNUSED_ALIAS = "unused"
+#: Concrete ``unused-*`` finding categories covered by :data:`CATEGORY_UNUSED_ALIAS`.
+UNUSED_CATEGORIES = (
+    CATEGORY_UNUSED_IMPORT,
+    CATEGORY_UNUSED_LOCAL,
+    CATEGORY_UNUSED_SYMBOL,
+)
+#: Concrete finding categories (what appears in reports).
+FINDING_CATEGORIES = (
+    CATEGORY_UNREACHABLE,
+    *UNUSED_CATEGORIES,
+    CATEGORY_OBSOLETE,
+    CATEGORY_TODO_MARKER,
+    CATEGORY_COMMENTED_OUT,
+)
+#: Categories a user may toggle via ``--categories``. ``unused`` is an alias
+#: expanding to :data:`UNUSED_CATEGORIES`.
+CLI_CATEGORIES = (
+    CATEGORY_UNREACHABLE,
+    CATEGORY_UNUSED_ALIAS,
+    *UNUSED_CATEGORIES,
+    CATEGORY_OBSOLETE,
+    CATEGORY_TODO_MARKER,
+    CATEGORY_COMMENTED_OUT,
+)
 # --------------------------------------------------------------------------
 # Per-language grammar node-type tables (verified empirically against each
@@ -58,6 +84,9 @@ EXTENSION_TO_LANGUAGE: dict[str, str] = {
     ".gsx": "Gosu",
 }
+#: File extensions the scanner can parse.
+SUPPORTED_EXTENSIONS = frozenset(EXTENSION_TO_LANGUAGE)
 #: Function/method definition node types, per language.
 FUNCTION_NODE_TYPES: dict[str, frozenset[str]] = {
     "Python": frozenset({"function_definition"}),
@@ -178,8 +207,11 @@ USAGE_NODE_TYPES: dict[str, frozenset[str]] = {
 #: optionally stripping surrounding parentheses added by some grammars).
 _FALSY_CONDITION_RE = re.compile(r"^\(*\s*(False|false|0)\s*\)*$")
-#: Regex matching obsolete markers inside comment text.
-_OBSOLETE_COMMENT_RE = re.compile(r"\b(TODO|FIXME|XXX|deprecated)\b", re.IGNORECASE)
+#: Regex matching TODO-style markers inside comment text.
+_TODO_COMMENT_RE = re.compile(r"\b(TODO|FIXME|XXX)\b", re.IGNORECASE)
+#: Regex matching deprecation markers inside comment text.
+_DEPRECATED_COMMENT_RE = re.compile(r"\b(deprecated)\b", re.IGNORECASE)
 #: Regex fragments that suggest a comment line contains commented-out code.
 _CODE_LIKE_RE = re.compile(
@@ -296,7 +328,12 @@ def detect_unreachable(
     for node in _iter_nodes(tree.root_node):
         if node.type in block_types:
             findings.extend(
-                _unreachable_after_terminator(node, terminating_types, file_path)
+                _unreachable_after_terminator(
+                    node,
+                    terminating_types,
+                    COMMENT_NODE_TYPES.get(language, frozenset()),
+                    file_path,
+                )
             )
         elif node.type == "if_statement":
             findings.extend(_unreachable_dead_branch(node, source_bytes, file_path))
@@ -305,15 +342,20 @@ def detect_unreachable(
 def _unreachable_after_terminator(
-    block: Node, terminating_types: frozenset[str], file_path: Path
+    block: Node,
+    terminating_types: frozenset[str],
+    comment_types: frozenset[str],
+    file_path: Path,
 ) -> list[Finding]:
     """Flag statements following a terminator within *block*.
+    Comment nodes are not statements and are never flagged.
     Author: Ron Webb
     Since: 1.0.0
     """
     findings: list[Finding] = []
-    statements = block.named_children
+    statements = [n for n in block.named_children if n.type not in comment_types]
     terminator_index: int | None = None
     for index, statement in enumerate(statements):
         if terminator_index is not None:
@@ -600,10 +642,34 @@ def _unused_binding_findings(
 # --------------------------------------------------------------------------
+def _marker_finding(
+    category: str, node: Node, file_path: Path, name: str, message: str
+) -> Finding:
+    """Build a :class:`Finding` located at the start of *node*.
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    row, col = node.start_point
+    return Finding(
+        category=category,
+        file_path=file_path,
+        line=row + 1,
+        column=col,
+        name=name,
+        message=message,
+    )
 def detect_obsolete_markers(
     tree: Tree, source_bytes: bytes, language: str, file_path: Path
 ) -> list[Finding]:
-    """Detect deprecation decorators/annotations and TODO/FIXME-style comments.
+    """Detect obsolete code markers.
+    Deprecation decorators/annotations and ``deprecated`` comments are reported
+    as :data:`CATEGORY_OBSOLETE`; ``TODO``/``FIXME``/``XXX`` comments, which are
+    not necessarily obsolete, are reported separately as
+    :data:`CATEGORY_TODO_MARKER`.
     Author: Ron Webb
     Since: 1.0.0
@@ -614,32 +680,38 @@ def detect_obsolete_markers(
     for node in _iter_nodes(tree.root_node):
         if decorator_types and node.type in decorator_types:
-            text = _decode(source_bytes, node)
-            if re.search(r"deprecated", text, re.IGNORECASE):
-                row, col = node.start_point
+            if re.search(r"deprecated", _decode(source_bytes, node), re.IGNORECASE):
                 findings.append(
-                    Finding(
-                        category=CATEGORY_OBSOLETE,
-                        file_path=file_path,
-                        line=row + 1,
-                        column=col,
-                        name=node.type,
-                        message="Deprecated marker found.",
+                    _marker_finding(
+                        CATEGORY_OBSOLETE,
+                        node,
+                        file_path,
+                        node.type,
+                        "Deprecated marker found.",
                     )
                 )
         elif node.type in comment_types:
             text = _decode(source_bytes, node)
-            match = _OBSOLETE_COMMENT_RE.search(text)
-            if match:
-                row, col = node.start_point
+            todo = _TODO_COMMENT_RE.search(text)
+            if todo:
                 findings.append(
-                    Finding(
-                        category=CATEGORY_OBSOLETE,
-                        file_path=file_path,
-                        line=row + 1,
-                        column=col,
-                        name=match.group(1).upper(),
-                        message=f"Obsolete marker '{match.group(1)}' found in comment.",
+                    _marker_finding(
+                        CATEGORY_TODO_MARKER,
+                        node,
+                        file_path,
+                        todo.group(1).upper(),
+                        f"Marker '{todo.group(1)}' found in comment.",
+                    )
+                )
+            deprecated = _DEPRECATED_COMMENT_RE.search(text)
+            if deprecated:
+                findings.append(
+                    _marker_finding(
+                        CATEGORY_OBSOLETE,
+                        node,
+                        file_path,
+                        deprecated.group(1).upper(),
+                        f"Obsolete marker '{deprecated.group(1)}' found in comment.",
                     )
                 )
     return findings
@@ -681,6 +753,16 @@ def _looks_like_code(text: str) -> bool:
     return stripped.endswith(("{", "}")) and len(stripped) > 1
+def _is_doc_comment(text: str) -> bool:
+    """Return ``True`` for ``/** ... */`` documentation comments (Javadoc/JSDoc).
+    Author: Ron Webb
+    Since: 1.1.0
+    """
+    stripped = text.lstrip()
+    return stripped.startswith("/**") and not stripped.startswith("/**/")
 def detect_commented_out_code(
     tree: Tree, source_bytes: bytes, language: str, file_path: Path
 ) -> list[Finding]:
@@ -696,7 +778,11 @@ def detect_commented_out_code(
     comment_types = COMMENT_NODE_TYPES.get(language, frozenset())
     if not comment_types:
         return []
-    comments = [n for n in _iter_nodes(tree.root_node) if n.type in comment_types]
+    comments = [
+        n
+        for n in _iter_nodes(tree.root_node)
+        if n.type in comment_types and not _is_doc_comment(_decode(source_bytes, n))
+    ]
     comments.sort(key=lambda n: n.start_point)
     findings: list[Finding] = []

{code_prune-1.0.0 → code_prune-1.1.0}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "code-prune"
-version = "1.0.0"
+version = "1.1.0"
 description = "Find unreachable, unused, and obsolete code before it becomes technical debt."
 authors = [
     {name = "Ron Webb"}
@@ -10,7 +10,7 @@ license = {file = "LICENSE"}
 requires-python = ">=3.14"
 keywords = ["cli", "static-analysis", "dead-code", "unused-code", "tree-sitter", "code-quality"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",