Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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_shapedfrom .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 Nonediff --git a/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py b/packages/core/src/repowise/core/analysis/dead_code/entry_shape.pynew file mode 100644index 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 Nonediff --git a/tests/unit/dead_code/test_entry_shape.py b/tests/unit/dead_code/test_entry_shape.pynew file mode 100644index 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_CONFIDENCEdiff --git a/tests/unit/dead_code/test_no_threshold_literals.py b/tests/unit/dead_code/test_no_threshold_literals.pyindex 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",