Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(dead-code): cap unreachable files shaped like path-loaded entries (#2707)

Swati Ahuja020cbc979c36
diff --git a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
index ebc7b097e..4d62ee02a 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -42,6 +42,7 @@ from .dynamic_markers import (
find_dynamic_import_files,
read_source_text,
)
+from .entry_shape import clamp_entry_shaped
from .file_reachability import (
PackageFileMap,
ReachabilityRescues,
@@ -894,6 +895,9 @@ class DeadCodeAnalyzer:
findings = clamp_unverified_absence(findings, self._source_map)
findings = drop_internals_used_in_own_file(findings, self._source_map)
findings = clamp_path_mentions(findings, self._source_map)
+ findings = clamp_entry_shaped(
+ findings, self._source_map, self._public_top_level_names(findings)
+ )
min_conf = cfg.get("min_confidence", RISK_CAP_CONFIDENCE)
hidden_below_threshold = sum(1 for f in findings if f.confidence < min_conf)
@@ -1198,6 +1202,29 @@ class DeadCodeAnalyzer:
return findings
+ def _defined_symbols(self, node: Any) -> list[tuple[str, dict]]:
+ """``(symbol_id, data)`` for each symbol *node* defines."""
+ return [
+ (succ, self.graph.nodes[succ])
+ for succ in self.graph.successors(node)
+ if self.graph.nodes[succ].get("node_type") == "symbol"
+ and self.graph.get_edge_data(node, succ, {}).get("edge_type") == "defines"
+ ]
+
+ def _public_top_level_names(
+ self, findings: list[DeadCodeFindingData]
+ ) -> dict[str, frozenset[str]]:
+ """Top-level public symbol names of each unreachable file in *findings*."""
+ return {
+ f.file_path: frozenset(
+ sym["name"]
+ for _, sym in self._defined_symbols(f.file_path)
+ if sym.get("visibility") == "public" and not sym.get("parent_name")
+ )
+ for f in findings
+ if f.kind is DeadCodeKind.UNREACHABLE_FILE and self.graph.has_node(f.file_path)
+ }
+
def _export_file_context(self, node: Any, whitelist: set[str]) -> _ExportFile | None:
"""The file-level facts the unused-export pass needs, or None to skip the file."""
if _is_synthetic_node(str(node)):
@@ -1218,12 +1245,7 @@ class DeadCodeAnalyzer:
if self._should_never_flag(str(node), whitelist):
return None
- symbol_pairs = [
- (succ, self.graph.nodes[succ])
- for succ in self.graph.successors(node)
- if self.graph.nodes[succ].get("node_type") == "symbol"
- and self.graph.get_edge_data(node, succ, {}).get("edge_type") == "defines"
- ]
+ symbol_pairs = self._defined_symbols(node)
if not symbol_pairs:
return None
diff --git a/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py b/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py
new file mode 100644
index 000000000..715a632e3
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py
@@ -0,0 +1,160 @@
+"""Unreachable files shaped like something a runtime loads by path.
+
+"Nothing imports this" is weak evidence for a file whose shape says it is
+never imported in the first place:
+
+* a TS/JS module whose only export is ``default`` is what a framework's file
+ router or plugin loader picks up by path;
+* a file that does work when run (top-level statements, a ``__main__`` guard,
+ a shebang) is started by a command, not by an import;
+* three or more unreachable files in one directory exporting the same names
+ are a convention-loaded set (pages, handlers, migrations) whose loader the
+ graph does not see.
+
+Each caps the finding to the review tier; none drops it. Shape is not proof of
+use, so the file stays listed as a candidate for a person to check.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections import defaultdict
+from collections.abc import Mapping
+from pathlib import PurePosixPath
+
+from ...ingestion.extractors.visibility import _TS_BLOCK_COMMENT, _TS_CJS_EXPORTS_RE
+from ...ingestion.languages.registry import REGISTRY
+from .models import DeadCodeFindingData, DeadCodeKind
+from .risk_factors import RISK_CAP_CONFIDENCE
+
+#: Siblings sharing one export shape before the set reads as a convention.
+MIN_COHORT_SIZE = 3
+
+_JS_FAMILY = frozenset({"typescript", "javascript"})
+
+# ``export default <name>`` / ``export default function|class <name>``: the
+# named declaration is the default export, so it is not a second export.
+_DEFAULT_EXPORT_RE = re.compile(
+ r"^[ \t]*export[ \t]+default\b[ \t]*(?:async[ \t]+)?"
+ r"(?:(?:abstract[ \t]+)?class|function\*?)?[ \t]*([A-Za-z_$][\w$]*)?",
+ re.MULTILINE,
+)
+# CommonJS: a whole-module ``module.exports = x`` (not an object of names) is
+# the default; any ``exports.name`` / ``module.exports.name`` is a named export.
+_CJS_DEFAULT_RE = re.compile(r"^[ \t]*module\.exports[ \t]*=(?![=>])(?![ \t]*\{)", re.MULTILINE)
+_CJS_NAMED_RE = re.compile(r"\b(?:module\.)?exports[ \t]*(?:\.[ \t]*[A-Za-z_$]|\[)")
+
+_LOOPS_AND_BLOCKS = (ast.For, ast.AsyncFor, ast.While, ast.With, ast.AsyncWith)
+
+
+def export_shape(path: str, public_names: frozenset[str], blob: bytes | None) -> frozenset[str]:
+ """The names *path* exports, with a TS/JS default export spelled ``default``."""
+ if blob is None or REGISTRY.from_extension(PurePosixPath(path).suffix) not in _JS_FAMILY:
+ return public_names
+ text = _TS_BLOCK_COMMENT.sub("", blob.decode("utf-8", "ignore"))
+ if _TS_CJS_EXPORTS_RE.search(text):
+ # Ingestion keeps every top-level name public in a CommonJS file, so
+ # only a lone whole-module assignment says anything about its shape.
+ lone = _CJS_DEFAULT_RE.search(text) and not _CJS_NAMED_RE.search(text)
+ return frozenset({"default"}) if lone else public_names
+ defaults = list(_DEFAULT_EXPORT_RE.finditer(text))
+ if not defaults:
+ return public_names
+ named = {m.group(1) for m in defaults if m.group(1)}
+ return (public_names - named) | {"default"}
+
+
+def _is_main_guard(test: ast.expr) -> bool:
+ return (
+ isinstance(test, ast.Compare)
+ and isinstance(test.left, ast.Name)
+ and test.left.id == "__name__"
+ and any(isinstance(c, ast.Constant) and c.value == "__main__" for c in test.comparators)
+ )
+
+
+def _script_reason(path: str, blob: bytes) -> str | None:
+ """Why *blob* reads as something run rather than imported, or None."""
+ if blob.startswith(b"#!"):
+ return "Starts with a shebang, so it is run directly rather than imported"
+ if REGISTRY.from_extension(PurePosixPath(path).suffix) != "python" or path.endswith(".pyi"):
+ return None
+ try:
+ return _python_script_reason(ast.parse(blob))
+ except (SyntaxError, ValueError, RecursionError):
+ return None
+
+
+def _python_script_reason(tree: ast.Module) -> str | None:
+ for stmt in tree.body:
+ if isinstance(stmt, ast.If) and _is_main_guard(stmt.test):
+ return 'Has an `if __name__ == "__main__"` block, so it is run as a script'
+ # A bare constant is a docstring or ``...``; anything else executes on load.
+ if isinstance(stmt, _LOOPS_AND_BLOCKS) or (
+ isinstance(stmt, ast.Expr) and not isinstance(stmt.value, ast.Constant)
+ ):
+ return f"Runs statements at module level (line {stmt.lineno}), so it is run as a script"
+ return None
+
+
+def _cohorts(shapes: Mapping[str, frozenset[str]]) -> dict[str, int]:
+ """For each file in a same-directory, same-shape set of MIN_COHORT_SIZE+, the set size."""
+ groups: dict[tuple[str, frozenset[str]], list[str]] = defaultdict(list)
+ for path, shape in shapes.items():
+ if shape: # no exports is no shape to share
+ groups[(str(PurePosixPath(path).parent), shape)].append(path)
+ return {p: len(ps) for ps in groups.values() if len(ps) >= MIN_COHORT_SIZE for p in ps}
+
+
+def clamp_entry_shaped(
+ findings: list[DeadCodeFindingData],
+ source_map: dict[str, bytes],
+ public_names: Mapping[str, frozenset[str]],
+) -> list[DeadCodeFindingData]:
+ """Cap unreachable files whose shape says a runtime loads them by path.
+
+ *public_names* maps each unreachable file to its top-level public symbol
+ names. The cohort counts every unreachable sibling, capped or not, since
+ a sibling already in review is still part of the set. Mutates in place
+ and returns the same list; never raises a confidence or drops a finding.
+ """
+ unreachable = [f for f in findings if f.kind is DeadCodeKind.UNREACHABLE_FILE]
+ if not unreachable:
+ return findings
+ shapes = {
+ f.file_path: export_shape(
+ f.file_path, public_names.get(f.file_path, frozenset()), source_map.get(f.file_path)
+ )
+ for f in unreachable
+ }
+ cohort_size = _cohorts(shapes)
+
+ for finding in unreachable:
+ if finding.confidence <= RISK_CAP_CONFIDENCE:
+ continue
+ path = finding.file_path
+ reason = _entry_reason(path, shapes[path], source_map.get(path), cohort_size.get(path))
+ if reason is None:
+ continue
+ finding.confidence = min(finding.confidence, RISK_CAP_CONFIDENCE)
+ finding.safe_to_delete = False
+ finding.evidence.append(reason)
+ return findings
+
+
+def _entry_reason(
+ path: str, shape: frozenset[str], blob: bytes | None, cohort_size: int | None
+) -> str | None:
+ """The first entry shape *path* has, as an evidence line, or None."""
+ if shape == {"default"}:
+ return "Its only export is `default`, the shape a framework loads by path"
+ if blob is not None and (script := _script_reason(path, blob)):
+ return script
+ if cohort_size:
+ names = ", ".join(sorted(shape)[:3])
+ return (
+ f"One of {cohort_size} unreachable files in its directory exporting "
+ f"the same names ({names}), the shape of a convention-loaded set"
+ )
+ return None
diff --git a/tests/unit/dead_code/test_entry_shape.py b/tests/unit/dead_code/test_entry_shape.py
new file mode 100644
index 000000000..e81e6003b
--- /dev/null
+++ b/tests/unit/dead_code/test_entry_shape.py
@@ -0,0 +1,212 @@
+"""An unreachable file shaped like something loaded by path is a review candidate.
+
+A default-export-only module, a script, and a same-shape sibling set are all
+loaded without an import edge. Each is capped to the review tier and kept in
+the report; a plain dead library module keeps its confidence.
+"""
+
+from __future__ import annotations
+
+from repowise.core.analysis.dead_code import DeadCodeAnalyzer, DeadCodeKind
+from repowise.core.analysis.dead_code.entry_shape import clamp_entry_shaped
+from repowise.core.analysis.dead_code.models import DeadCodeFindingData
+from repowise.core.analysis.dead_code.risk_factors import RISK_CAP_CONFIDENCE
+from tests.unit.dead_code._helpers import _build_graph, _old_date
+
+
+def _file(path: str, confidence: float = 1.0) -> DeadCodeFindingData:
+ return DeadCodeFindingData(
+ kind=DeadCodeKind.UNREACHABLE_FILE,
+ file_path=path,
+ symbol_name=None,
+ symbol_kind=None,
+ confidence=confidence,
+ reason="File has no importers (in_degree=0)",
+ last_commit_at=None,
+ commit_count_90d=0,
+ lines=1,
+ evidence=[],
+ safe_to_delete=True,
+ primary_owner=None,
+ age_days=None,
+ )
+
+
+def _clamp(
+ files: dict[str, str], names: dict[str, set[str]] | None = None
+) -> dict[str, DeadCodeFindingData]:
+ findings = [_file(p) for p in files]
+ public = {p: frozenset((names or {}).get(p, ())) for p in files}
+ clamp_entry_shaped(findings, {p: s.encode() for p, s in files.items()}, public)
+ return {f.file_path: f for f in findings}
+
+
+def _capped(finding: DeadCodeFindingData) -> bool:
+ return finding.confidence == RISK_CAP_CONFIDENCE and finding.safe_to_delete is False
+
+
+# --- default export only -----------------------------------------------------
+
+
+def test_a_convention_loaded_default_export_directory_is_capped():
+ files = {
+ "app/routes/home.tsx": "export default function Home() { return null }\n",
+ "app/routes/about.tsx": "const About = () => null\nexport default About\n",
+ "app/routes/config.ts": "export default { runtime: 'edge' }\n",
+ }
+ out = _clamp(files, {"app/routes/home.tsx": {"Home"}})
+ for finding in out.values():
+ assert _capped(finding)
+ assert "only export is `default`" in finding.evidence[-1]
+
+
+def test_a_default_export_beside_a_named_export_is_not_default_only():
+ files = {"src/widget.ts": "export const helper = 1\nexport default function W() {}\n"}
+ out = _clamp(files, {"src/widget.ts": {"helper", "W"}})
+ assert out["src/widget.ts"].confidence == 1.0
+
+
+def test_a_default_export_inside_a_block_comment_does_not_count():
+ files = {"src/old.ts": "/*\nexport default Old\n*/\nconst x = 1\n"}
+ assert _clamp(files)["src/old.ts"].confidence == 1.0
+
+
+def test_a_lone_commonjs_module_exports_is_a_default_export():
+ body = "function helper() {}\nmodule.exports = function handler() { helper() }\n"
+ # CommonJS keeps every top-level name public, so the graph names both.
+ out = _clamp({"api/hook.js": body}, {"api/hook.js": {"helper"}})
+ assert _capped(out["api/hook.js"])
+
+
+def test_commonjs_named_exports_are_not_default_only():
+ files = {
+ "lib/a.js": "module.exports = {\n a: 1,\n}\n",
+ "lib/b.js": "exports.b = 1\n",
+ "lib/c.js": "module.exports = run\nmodule.exports.extra = 2\n",
+ }
+ out = _clamp(files, {p: {"x"} for p in ("lib/a.js",)})
+ assert all(f.confidence == 1.0 for f in out.values())
+
+
+def test_default_export_text_in_a_python_file_is_not_a_js_default():
+ out = _clamp({"pkg/gen.py": 'TEMPLATE = """\nexport default {}\n"""\n'})
+ assert out["pkg/gen.py"].confidence == 1.0
+
+
+# --- scripts ---------------------------------------------------------------------
+
+
+def test_a_main_guard_marks_a_script():
+ body = "def main():\n pass\n\nif __name__ == '__main__':\n main()\n"
+ out = _clamp({"tools/bump.py": body}, {"tools/bump.py": {"main"}})
+ assert _capped(out["tools/bump.py"])
+ assert "__main__" in out["tools/bump.py"].evidence[-1]
+
+
+def test_top_level_statements_mark_a_script():
+ body = '"""Seed the database."""\nimport db\n\ndb.connect()\nfor row in db.rows():\n print(row)\n'
+ out = _clamp({"scripts/seed.py": body})
+ assert _capped(out["scripts/seed.py"])
+ assert "line 4" in out["scripts/seed.py"].evidence[-1]
+
+
+def test_a_shebang_marks_a_script():
+ out = _clamp({"bin/release": "#!/usr/bin/env node\nconsole.log(1)\n"})
+ assert _capped(out["bin/release"])
+
+
+def test_a_plain_library_module_stays_a_positive():
+ body = '"""Old helpers."""\nimport os\n\nLIMIT = 3\n\ndef helper():\n return os.sep\n'
+ out = _clamp({"pkg/old_helpers.py": body}, {"pkg/old_helpers.py": {"helper", "LIMIT"}})
+ assert out["pkg/old_helpers.py"].confidence == 1.0
+ assert out["pkg/old_helpers.py"].evidence == []
+
+
+def test_only_whole_file_findings_are_capped():
+ finding = _file("tools/bump.py")
+ finding.kind = DeadCodeKind.UNUSED_EXPORT
+ finding.symbol_name = "main"
+ clamp_entry_shaped([finding], {"tools/bump.py": b"main()\n"}, {})
+ assert finding.confidence == 1.0
+
+
+def test_unparseable_python_is_left_alone():
+ out = _clamp({"pkg/legacy.py": "print 'py2'\n"})
+ assert out["pkg/legacy.py"].confidence == 1.0
+
+
+# --- cohorts ---------------------------------------------------------------------
+
+
+def _handler(name: str) -> str:
+ return f"def handle(event):\n return '{name}'\n"
+
+
+def test_three_siblings_with_one_export_shape_are_a_cohort():
+ paths = ["handlers/a.py", "handlers/b.py", "handlers/c.py"]
+ out = _clamp({p: _handler(p) for p in paths}, {p: {"handle"} for p in paths})
+ for p in paths:
+ assert _capped(out[p])
+ assert "One of 3 unreachable files" in out[p].evidence[-1]
+
+
+def test_two_siblings_are_not_a_cohort():
+ paths = ["handlers/a.py", "handlers/b.py"]
+ out = _clamp({p: _handler(p) for p in paths}, {p: {"handle"} for p in paths})
+ assert all(out[p].confidence == 1.0 for p in paths)
+
+
+def test_a_cohort_needs_one_directory_and_one_shape():
+ paths = ["a/x.py", "b/y.py", "c/z.py", "d/w.py"]
+ names = {"a/x.py": {"handle"}, "b/y.py": {"handle"}, "c/z.py": {"handle"}, "d/w.py": {"run"}}
+ out = _clamp({p: _handler(p) for p in paths}, names)
+ assert all(f.confidence == 1.0 for f in out.values())
+
+
+def test_files_with_no_exports_are_not_a_cohort():
+ paths = ["pkg/a.py", "pkg/b.py", "pkg/c.py"]
+ out = _clamp({p: "_x = 1\n" for p in paths})
+ assert all(f.confidence == 1.0 for f in out.values())
+
+
+def test_an_already_capped_sibling_still_counts_but_is_not_touched_again():
+ paths = ["jobs/a.py", "jobs/b.py", "jobs/c.py"]
+ findings = [_file(paths[0], confidence=0.3), _file(paths[1]), _file(paths[2])]
+ clamp_entry_shaped(
+ findings,
+ {p: _handler(p).encode() for p in paths},
+ {p: frozenset({"handle"}) for p in paths},
+ )
+ assert findings[0].confidence == 0.3 and findings[0].evidence == []
+ assert all(_capped(f) for f in findings[1:])
+
+
+# --- through the analyzer --------------------------------------------------------
+
+
+def test_the_analyzer_applies_the_cap_and_keeps_the_finding():
+ g = _build_graph(
+ nodes={
+ "pkg/main.py": {"is_entry_point": True, "symbols": []},
+ "pkg/old.py": {"symbols": [{"name": "helper", "visibility": "public"}]},
+ "pkg/run_once.py": {"symbols": [{"name": "main", "visibility": "public"}]},
+ },
+ )
+ old = {"commit_count_90d": 0, "last_commit_at": _old_date(400)}
+ source = {
+ "pkg/main.py": b"print('hi')\n",
+ "pkg/old.py": b"def helper():\n return 1\n",
+ "pkg/run_once.py": b"def main():\n pass\n\nif __name__ == '__main__':\n main()\n",
+ }
+ report = DeadCodeAnalyzer(
+ g, git_meta_map={"pkg/old.py": old, "pkg/run_once.py": old}, source_map=source
+ ).analyze(
+ {
+ "detect_unused_exports": False,
+ "detect_unused_internals": False,
+ "detect_zombie_packages": False,
+ }
+ )
+ by_path = {f.file_path: f for f in report.findings if f.kind == DeadCodeKind.UNREACHABLE_FILE}
+ assert by_path["pkg/old.py"].confidence == 1.0
+ assert by_path["pkg/run_once.py"].confidence == RISK_CAP_CONFIDENCE
diff --git a/tests/unit/dead_code/test_no_threshold_literals.py b/tests/unit/dead_code/test_no_threshold_literals.py
index 6671ca366..42342779d 100644
--- a/tests/unit/dead_code/test_no_threshold_literals.py
+++ b/tests/unit/dead_code/test_no_threshold_literals.py
@@ -48,6 +48,7 @@ _PACKAGES = pathlib.Path(__file__).resolve().parents[3] / "packages"
_GUARDED = [
"core/src/repowise/core/analysis/dead_code/analyzer.py",
"core/src/repowise/core/analysis/dead_code/name_occurrences.py",
+ "core/src/repowise/core/analysis/dead_code/entry_shape.py",
"core/src/repowise/core/analysis/dead_code/risk_factors.py",
"core/src/repowise/core/persistence/crud/analysis/dead_code.py",
"cli/src/repowise/cli/commands/dead_code_cmd.py",