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(analysis): answer "is this file reachable" in one place, for both callers (#1487)
Raghav Chamadiya65e7b8e2db45
diff --git a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py b/packages/core/src/repowise/core/analysis/dead_code/analyzer.pyindex 3dcdd13a7..3aa1612fa 100644--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py@@ -31,18 +31,16 @@ from .constants import (_is_fixture_path,)from .contract_methods import is_contract_method-from .cpp_reachability import (- build_cpp_package_files,- is_cpp_file_reachable,- is_cpp_path,-)from .dynamic_markers import (find_dynamic_edge_files,find_dynamic_import_files,read_source_text,)-from .go_reachability import build_go_package_files, is_go_file_reachable-from .jvm_reachability import build_jvm_package_files, is_jvm_file_reachable+from .file_reachability import (+ ReachabilityRescues,+ build_package_file_map,+ is_file_reachable,+)from .models import DeadCodeFindingData, DeadCodeKind, DeadCodeReportfrom .risk_factors import RISK_CAP_CONFIDENCE, path_risk_factors, risk_evidence@@ -339,26 +337,6 @@ _CPP_BUILTIN_MACROS: frozenset[str] = frozenset(logger = structlog.get_logger(__name__)-# Re-export barrel filenames. Skipped in the *unreachable-file* pass only:-# a barrel aggregates other modules' symbols and is reached by importing-# those names (or, for a package's public entry, via package.json-# ``exports``/``main``), so a barrel with no inbound graph edge is not dead.-# They are NOT skipped in the unused-export pass — a genuine symbol defined-# in a barrel that nobody imports should still be flagged.-_BARREL_FILENAMES: frozenset[str] = frozenset(- {- "__init__.py",- "index.ts",- "index.tsx",- "index.js",- "index.jsx",- "index.mts",- "index.cts",- "index.mjs",- "index.cjs",- }-)-def _find_jsx_namespace_files(parsed_files: dict,@@ -652,32 +630,20 @@ class DeadCodeAnalyzer:self._ts_export_aliases: dict[str, dict[str, str]] = _find_ts_export_aliases(parsed_files or {}, source_map)- # Lazily-built ``.go`` package-directory → file-node map, used by the- # Go package-granular reachability hook (see ``go_reachability``).- self._go_package_files: dict[str, list[str]] | None = None- # Lazily-built JVM (``.java`` + ``.kt``) package-directory map; see- # :mod:`jvm_reachability`.- self._jvm_package_files: dict[str, list[str]] | None = None- # Lazily-built C/C++ directory map; see :mod:`cpp_reachability`.- self._cpp_package_files: dict[str, list[str]] | None = None-- def _go_packages(self) -> dict[str, list[str]]:- """Return the cached Go package map, building it on first use."""- if self._go_package_files is None:- self._go_package_files = build_go_package_files(self.graph)- return self._go_package_files-- def _jvm_packages(self) -> dict[str, list[str]]:- """Return the cached JVM package map, building it on first use."""- if self._jvm_package_files is None:- self._jvm_package_files = build_jvm_package_files(self.graph)- return self._jvm_package_files-- def _cpp_packages(self) -> dict[str, list[str]]:- """Return the cached C/C++ directory map, building it on first use."""- if self._cpp_package_files is None:- self._cpp_package_files = build_cpp_package_files(self.graph)- return self._cpp_package_files+ # Lazily-built rescue state for the shared reachability predicate: the+ # package-directory maps for Go / JVM / C-C++ plus the bundler-alias+ # targets found above. Built on first use so a graph that never+ # reaches the unreachable-files pass never pays for it.+ self._rescues: ReachabilityRescues | None = None++ def _reachability_rescues(self) -> ReachabilityRescues:+ """Return the cached rescue state, building it on first use."""+ if self._rescues is None:+ self._rescues = ReachabilityRescues(+ bundler_alias_targets=frozenset(self._bundler_alias_targets),+ package_files=build_package_file_map(self.graph),+ )+ return self._rescuesdef analyze(self,@@ -772,40 +738,13 @@ class DeadCodeAnalyzer:continueif self._should_never_flag(str(node), whitelist):continue- # Re-export barrels (index.* / __init__.py) are reached by the- # names they forward or via package ``exports``/``main`` — a barrel- # with no inbound graph edge is not dead code.- if Path(str(node)).name in _BARREL_FILENAMES:- continue- if self._is_api_contract(node_data):- continue- # Bundler ``resolve.alias`` targets are reached through the- # aliased package name; only the config references them by path.- if str(node) in self._bundler_alias_targets:- continue- # Go reachability is package-granular: a file with no direct- # importer can still be live (entry-package sibling next to- # main.go, or a package whose siblings carry the import). Delegate- # to the Go helper instead of the raw file-level in_degree check.- node_str = str(node)- if node_str.endswith(".go"):- if is_go_file_reachable(node_str, self.graph, self._go_packages()):- continue- elif node_str.endswith(".java") or node_str.endswith(".kt"):- # JVM reachability is package-aware too: sibling-rescued- # packages plus stereotype-annotated / ``main``-carrying- # files surface as live even with no direct importer.- if is_jvm_file_reachable(node_str, self.graph, self._jvm_packages()):- continue- elif is_cpp_path(node_str):- # C/C++ reachability rescues public-API headers, ``main``-- # bearing TUs (apps/demos/benchmarks/fuzzers), internal- # headers next to their implementation files, and- # conditional-compile alternates that share a stem prefix.- if is_cpp_file_reachable(node_str, self.graph, self._cpp_packages()):- continue- elif self.graph.in_degree(node) > 0:+ # Barrels, API contracts, bundler-alias shims and the+ # package-granular languages (Go / JVM / C-C++) are all rescued+ # inside the shared predicate, which the overview assembler calls+ # with the same state so the two passes cannot disagree about what+ # "reachable" means. See :mod:`file_reachability`.+ if is_file_reachable(str(node), self.graph, self._reachability_rescues()):continuefinding = self._make_unreachable_finding(str(node), node_data, dynamic_patterns)@@ -1598,9 +1537,6 @@ class DeadCodeAnalyzer:# __init__.py is a re-export barrelreturn Path(path).name == "__init__.py"- def _is_api_contract(self, node_data: dict) -> bool:- return node_data.get("is_api_contract", False)-def _file_has_implementors(self, file_node: Any) -> bool:"""Return True iff any ``implements`` / ``method_implements`` /``extends`` edge terminates at *file_node* or at a symbol itdiff --git a/packages/core/src/repowise/core/analysis/dead_code/file_reachability.py b/packages/core/src/repowise/core/analysis/dead_code/file_reachability.pynew file mode 100644index 000000000..7e062b1b6--- /dev/null+++ b/packages/core/src/repowise/core/analysis/dead_code/file_reachability.py@@ -0,0 +1,288 @@+"""One answer to "can anything reach this file?".++Two passes ask that question and used to answer it separately. The dead-code+analyzer asks so it can report a file nobody imports as ``unreachable_file``;+the repo-overview assembler asks so it can drop an execution flow whose entry+point is that same file. Execution-flow scoring treats zero inbound calls as+its *strongest positive* signal — a symbol nothing calls looks like a front+door — so the identical fact promoted a file to Primary Execution Flow #1 and+listed it as dead code, on one index, from one piece of evidence.++The assembler could not call the analyzer's version: it is a method reading+six attributes built during analysis. So it hand-copied the barrel filename+set and carried a list of the languages where the analyzer was known to be+kinder, standing in for per-language helpers it could not reach. This module+is that predicate with its state passed in, so both callers get one answer.++Leaf in its own imports: the three per-language reachability helpers and+:mod:`repowise.core.ids`, and nothing else from either subsystem. It does not+reach the analyzer, and in particular it holds none of the analysis-time state+that made the analyzer's version uncallable, which is the coupling that+mattered.++It is not a free import, though, and the difference is worth stating rather+than implying. ``dead_code/__init__`` eagerly re-exports ``DeadCodeAnalyzer``,+so importing this module from generation executes that package init and loads+the analyzer with it: 12 extra modules, and under 10 ms, which is inside the+run-to-run spread of the roughly 550 ms assembler import it sits on top of.+Ceiling, accepted at that price. The+upgrade path if it ever stops being worth it is to move this module and the+three per-language helpers up to :mod:`repowise.core.analysis`, which none of+them has a reason to sit below; making the package init lazy would also work+but costs mypy the types of everything the package re-exports.+"""++from __future__ import annotations++from collections.abc import Mapping+from collections.abc import Set as AbstractSet+from dataclasses import dataclass, field+from pathlib import PurePosixPath+from typing import Any++from repowise.core.ids import SYMBOL_SEP, file_path_of, is_external++from .cpp_reachability import build_cpp_package_files, is_cpp_file_reachable, is_cpp_path+from .go_reachability import build_go_package_files, is_go_file_reachable+from .jvm_reachability import build_jvm_package_files, is_jvm_file_reachable++#: Re-export barrel filenames. A barrel aggregates other modules' symbols and+#: is reached by importing those names (or, for a package's public entry, via+#: package.json ``exports``/``main``), so a barrel with no inbound graph edge+#: is not unreachable.+#:+#: Scope note for the analyzer: this rescues a file in the *unreachable-file*+#: pass only. It is NOT applied in the unused-export pass — a genuine symbol+#: defined in a barrel that nobody imports should still be flagged.+BARREL_FILENAMES: frozenset[str] = frozenset(+ {+ "__init__.py",+ "index.ts",+ "index.tsx",+ "index.js",+ "index.jsx",+ "index.mts",+ "index.cts",+ "index.mjs",+ "index.cjs",+ }+)++#: Edge types that record association rather than dependency. A co-change edge+#: says two files were committed together, which is not a path any code can+#: take, so it must not answer "does anything import this".+_NON_DEPENDENCY_EDGES: frozenset[str] = frozenset({"co_changes"})++_JVM_SUFFIXES: tuple[str, ...] = (".java", ".kt")+++@dataclass(frozen=True)+class PackageFileMap:+ """Package-directory → member-file maps for the package-granular languages.++ Built from the graph alone (see the ``build_*_package_files`` helpers), so+ any caller holding a graph can supply it. One object rather than three+ arguments because the predicate needs whichever map matches the path and a+ caller has no reason to supply a subset.+ """++ go: dict[str, list[str]] = field(default_factory=dict)+ jvm: dict[str, list[str]] = field(default_factory=dict)+ cpp: dict[str, list[str]] = field(default_factory=dict)+++def build_package_file_map(graph: Any) -> PackageFileMap:+ """Build all three package maps in one call.++ Each builder is one pass over the node ids testing a filename suffix, so+ building all three on a repo that uses none of the languages costs three+ scans and yields three empty dicts. Callers cache the result rather than+ building per candidate.+ """+ return PackageFileMap(+ go=build_go_package_files(graph),+ jvm=build_jvm_package_files(graph),+ cpp=build_cpp_package_files(graph),+ )+++@dataclass(frozen=True)+class ReachabilityRescues:+ """Evidence, built by the caller, that rescues a file with no importer.++ ``package_files`` is the one field whose absence changes the answer rather+ than narrowing it. Go, JVM and C/C++ imports name a *package*, so most+ files in a live package carry no file-level in-edge at all; a caller+ without the map would call an entire language unreachable. ``None`` means+ "not checked", and the predicate resolves an unchecked package-granular+ file to reachable. That is the deliberate asymmetry, and it runs one way:+ a missed drop leaves one wrong flow on a page, an over-eager drop silently+ empties the section.++ ``bundler_alias_targets`` is a narrow allowlist — a handful of shim paths+ per repo — and defaults to empty. A caller that omits it is stricter than+ the analyzer for exactly those paths, and no wider.++ Ceiling, deliberate: the analyzer applies two further rescues this+ predicate does not, the never-flag glob set and the user whitelist, both+ of which live outside the graph (``analyzer._never_flag_regex_match``, and+ dead-code config). Same for ``bundler_alias_targets``, which needs a+ source scan of the bundler configs. The upgrade path is to thread that+ state to the second caller — for the glob set, by moving the matcher down+ to :mod:`constants` where its pattern list already lives — not to widen+ the defaults into a blanket rescue. A blanket rescue would answer+ "reachable" for every unimported TS/JS file and stop being a predicate.+ """++ bundler_alias_targets: AbstractSet[str] = frozenset()+ package_files: PackageFileMap | None = None+++#: Prefix of an :class:`repowise.core.ids.ExternalId`, matched textually rather+#: than through ``ids.parse``. Every in-edge of every candidate goes through+#: the tests below, and ``parse`` allocates a dataclass per call: on a 175k-node+#: graph that one construction was most of a 13x slowdown against the+#: ``in_degree`` read this replaced. Rendered form is pinned by+#: ``tests/unit/test_ids.py``, and ``analyzer._is_synthetic_node`` already+#: matches the same two prefixes textually.+_EXTERNAL_PREFIX = "external:"+++def _is_external_package(node: str) -> bool:+ """Third-party code we merely name, as opposed to a framework anchor."""+ return node.startswith(_EXTERNAL_PREFIX)+++def is_foreign_edge(node: str, path: str) -> bool:+ """Whether a graph neighbour is another file rather than *path* itself.++ Graph node ids are either a file path or ``<file path>::<symbol>``. Both+ spellings of "this file" are dropped so a dependency list only ever names+ other files.+ """+ if is_external(node):+ return False+ return node != path and file_path_of(node) != path+++def _is_structural_edge(neighbor: str, path: str, edge_data: Mapping[str, Any], graph: Any) -> bool:+ """Whether a graph edge between *neighbor* and *path* is a code dependency.++ Its own function because "which edges count" is exactly what the two+ callers disagreed on, and the disagreement is invisible when it is spelled+ inline at each site. Symbol containment (``defines``) is out because the+ neighbour is not a file; co-change is out because it is history, not code.+ """+ # Cheapest test first, and ordered so the two string tests below run only+ # on edges that survive it. This runs once per in-edge of every candidate.+ if edge_data.get("edge_type", "imports") in _NON_DEPENDENCY_EDGES:+ return False+ if neighbor == path:+ return False+ if graph.nodes.get(neighbor, {}).get("node_type", "file") != "file":+ return False+ # A symbol id is ``<file path>::<symbol>``, so only an id carrying the+ # separator can be another spelling of this file. Guarding the call keeps+ # ``ids.parse`` off the hot path for ordinary file-to-file edges.+ #+ # Load-bearing assumption: no knowledge-graph id ever enters this graph.+ # ``file_path_of`` also resolves a ``KgFileId`` (``file:a.py``) to a path,+ # and that spelling carries no ``::``, so it would slip through here. The+ # graph builder only ever adds a bare path, ``path::Name``, ``external:``+ # or ``framework:`` (``ingestion/graph/builder.py``), and no node id in the+ # 41-repo corpus carries a ``file:`` prefix.+ return not (SYMBOL_SEP in neighbor and file_path_of(neighbor) == path)+++def file_dependency_neighbors(graph: Any, path: str, *, incoming: bool) -> list[str]:+ """Structural file neighbours of *path* in the requested direction.++ Every file-to-file edge except co-change counts, which keeps import,+ type-use, framework and future structural edge types while excluding+ symbol containment and historical association. Code we do not own is+ excluded outright: this list names files, and a reader following it wants+ somewhere in the repository to go.+ """+ if path not in graph:+ return []++ edges = graph.in_edges(path, data=True) if incoming else graph.out_edges(path, data=True)+ neighbors = []+ for source, target, edge_data in edges:+ neighbor = source if incoming else target+ if is_external(neighbor) or graph.nodes.get(neighbor, {}).get("language") == "external":+ continue+ if _is_structural_edge(neighbor, path, edge_data, graph):+ neighbors.append(neighbor)+ return neighbors+++def has_dependency_importer(graph: Any, path: str) -> bool:+ """Whether anything in the graph depends on *path*.++ Replaces a raw ``graph.in_degree(path) > 0``, which counted a co-change+ edge — "these two files were committed together" — as an import, and+ counted a file's own symbols and a self-import as importers of it.++ A ``framework:`` anchor counts and an ``external:`` one does not, the same+ split the zombie-package pass already makes: a framework anchor records+ that a runtime loads this file (a TYPO3 ``ext_localconf.php`` has no+ source-level importer and is not dead), whereas an ``external:`` node is a+ third-party package we merely name.+ """+ if path not in graph:+ return False+ return any(+ not _is_external_package(source) and _is_structural_edge(source, path, edge_data, graph)+ for source, _target, edge_data in graph.in_edges(path, data=True)+ )+++def is_file_reachable(+ path: str,+ graph: Any,+ rescues: ReachabilityRescues | None = None,+) -> bool:+ """Whether anything in the repository can reach *path*.++ ``False`` means "no importer and no rescue applies" — the condition the+ dead-code analyzer reports as ``unreachable_file`` and the overview+ assembler reads as "this cannot be an execution flow entry point".++ *path* must be a file node id; a caller holding a symbol id resolves it+ first. An id that is not in the graph answers ``True``, because an+ unresolvable node is unchecked rather than unreachable.+ """+ if path not in graph:+ return True++ rescues = rescues or ReachabilityRescues()+ node_data = graph.nodes.get(path, {})++ # Conventional entry points, framework-instantiated files and published+ # API contracts are reached from outside the graph. Nothing imports+ # ``main.py`` either.+ if node_data.get("is_entry_point", False):+ return True+ if node_data.get("is_api_contract", False):+ return True+ # Workspace-driven never-flag, set by language warmups that read the build+ # manifest (Gradle non-``main`` source sets, Cargo ``[[example]]`` targets).+ if node_data.get("is_never_flag", False):+ return True+ if PurePosixPath(path).name in BARREL_FILENAMES:+ return True+ # Bundler ``resolve.alias`` targets are reached through the aliased package+ # name; only the config names them by path.+ if path in rescues.bundler_alias_targets:+ return True++ packages = rescues.package_files+ if path.endswith(".go"):+ return True if packages is None else is_go_file_reachable(path, graph, packages.go)+ if path.endswith(_JVM_SUFFIXES):+ return True if packages is None else is_jvm_file_reachable(path, graph, packages.jvm)+ if is_cpp_path(path):+ return True if packages is None else is_cpp_file_reachable(path, graph, packages.cpp)++ return has_dependency_importer(graph, path)diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.pyindex 7ab5bb232..82c08e244 100644--- a/packages/core/src/repowise/core/generation/context/assembler.py+++ b/packages/core/src/repowise/core/generation/context/assembler.py@@ -9,6 +9,11 @@ from typing import Anyimport structlog+from repowise.core.analysis.dead_code.file_reachability import (+ ReachabilityRescues,+ file_dependency_neighbors,+ is_file_reachable,+)from repowise.core.ids import file_path_of, is_externalfrom repowise.core.ingestion.models import ParsedFile, RepoStructure, Symbol@@ -42,44 +47,11 @@ from .token_budget import (log = structlog.get_logger(__name__)-def _is_foreign_edge(node: str, path: str) -> bool:- """Whether a graph neighbour is a real dependency rather than this file itself.-- Graph node ids are either a file path or ``<file path>::<symbol>``. Both- spellings of "this file" are dropped so a dependency list only ever names- other files.- """- if is_external(node):- return False- return node != path and file_path_of(node) != path--# Maximum imports to include before truncating_MAX_IMPORTS = 30# Maximum top-files to include in repo overview_MAX_TOP_FILES = 20-# Languages whose imports name a package rather than a file, so most files in a-# live package carry no file-level in-edge. The dead-code analyzer delegates-# these to per-language reachability helpers.-_PACKAGE_GRANULAR_SUFFIXES = re.compile(r"\.(go|java|kt|c|cc|cpp|cxx|h|hh|hpp|hxx)$", re.I)-# Deliberate copy of ``dead_code.analyzer._BARREL_FILENAMES``. Importing the-# analyzer would drag the whole dead-code stack into generation for one-# frozenset. The real fix is a shared reachability predicate both call; until-# then this must be kept in step by hand.-_BARREL_FILENAMES: frozenset[str] = frozenset(- {- "__init__.py",- "index.ts",- "index.tsx",- "index.js",- "index.jsx",- "index.mts",- "index.cts",- "index.mjs",- "index.cjs",- }-)# How many rows the concept index may carry. A module page groups directories,# so a wide one can reach several hundred public symbols and the table would# then be longer than the page it is attached to. Rows past this are counted@@ -225,34 +197,7 @@ def build_concept_index(return rows, total - len(rows)-def _file_dependency_neighbors(graph: Any, path: str, *, incoming: bool) -> list[str]:- """Return structural file neighbors in the requested direction.-- The file graph treats every file-to-file edge except ``co_changes`` as a- dependency. This keeps import, type-use, framework, and future structural- edge types while excluding symbol containment and historical association.- """- if path not in graph:- return []-- edges = graph.in_edges(path, data=True) if incoming else graph.out_edges(path, data=True)- neighbors: list[str] = []- for source, target, edge_data in edges:- neighbor = source if incoming else target- neighbor_data = graph.nodes[neighbor]- if not _is_foreign_edge(neighbor, path):- continue- if neighbor_data.get("node_type", "file") != "file":- continue- if neighbor_data.get("language") == "external":- continue- if edge_data.get("edge_type", "imports") == "co_changes":- continue- neighbors.append(neighbor)- return neighbors---def _flow_entry_is_reachable(flow: Any, graph: Any) -> bool:+def _flow_entry_is_reachable(flow: Any, graph: Any, rescues: ReachabilityRescues) -> bool:"""Can anything actually get to this flow's entry point?Execution-flow scoring treats zero inbound calls as its strongest positive@@ -263,37 +208,20 @@ def _flow_entry_is_reachable(flow: Any, graph: Any) -> bool:the same fact, on the same index.Dead code is right in that argument and the flow is wrong, so drop the- flow. A conventional entry point is exempt for the same reason the- dead-code pass exempts it: nothing imports ``main.py`` either.-- Deliberately more forgiving than ``unreachable_file``, in one direction- only. The analyzer rescues a zero-in-degree file through a dozen further- checks, several of which need state built during analysis (bundler alias- targets, never-flag whitelists, per-language package maps) and are not- reachable from here. Rather than reimplement a second, subtly different- reachability, this bails out wherever the analyzer is known to be kinder:- an unresolvable entry point, a barrel, and the languages whose imports are- package-granular rather than file-granular. A missed drop leaves a wrong- flow on the page; an over-eager one silently empties the section, which is- the failure the caller's own comment exists to prevent. See the backlog:- the real fix is one shared predicate.+ flow. Which files that argument spares is not decided here: it is+ :func:`is_file_reachable`, the same predicate the dead-code pass asks, so+ the two cannot drift. This function only resolves a flow to a file path.++ An unresolvable entry point stays. That is the one rescue local to this+ caller, and it runs in the forgiving direction for the reason the caller's+ own comment gives: a missed drop leaves one wrong flow on the page, while+ an over-eager drop silently empties the section."""node = graph.nodes.get(flow.entry_point_id, {})path = node.get("file_path") or file_path_of(flow.entry_point_id) or ""- if not path or path not in graph:- return True- if graph.nodes[path].get("is_entry_point"):- return True- # Go, JVM and C/C++ resolve imports per package, so most files in a live- # package carry no file-level in-edge at all. The analyzer delegates to a- # per-language helper here; without one, this check would drop nearly- # every flow on such a repository.- if _PACKAGE_GRANULAR_SUFFIXES.search(path):- return True- # A barrel is reached by the names it forwards, never by its own path.- if PurePosixPath(path).name in _BARREL_FILENAMES:+ if not path:return True- return bool(_file_dependency_neighbors(graph, path, incoming=True))+ return is_file_reachable(path, graph, rescues)# ---------------------------------------------------------------------------@@ -392,8 +320,8 @@ class ContextAssembler:# Structural file dependencies only. The full graph also contains# file→symbol containment and historical co-change edges.- in_edges = _file_dependency_neighbors(graph, path, incoming=True)- out_edges = _file_dependency_neighbors(graph, path, incoming=False)+ in_edges = file_dependency_neighbors(graph, path, incoming=True)+ out_edges = file_dependency_neighbors(graph, path, incoming=False)# Decoded to derive the vocabulary below, and deliberately not carried on# the returned context. The context used to hold a ``file_source_snippet``@@ -841,7 +769,21 @@ class ContextAssembler:key=lambda f: (-f.entry_point_score, f.entry_point_id),)flow_graph = graph_builder.graph()- kept = [f for f in ranked if _flow_entry_is_reachable(f, flow_graph)]+ # No package map, deliberately: an unchecked Go / JVM /+ # C-C++ file answers "reachable", so this section keeps+ # being more forgiving than the dead-code pass for exactly+ # those languages. Measured on test-repos/, supplying+ # ``build_package_file_map(flow_graph)`` here would flip+ # 0-43% of their files to unreachable (43% on+ # nlohmann-json, 29% on openclaw, 27% on Crow), and an+ # over-eager drop empties the section. Ceiling, not+ # oversight: closing it is one argument, and wants its own+ # measurement of what the overview actually loses.+ kept = [+ f+ for f in ranked+ if _flow_entry_is_reachable(f, flow_graph, ReachabilityRescues())+ ]if len(kept) != len(ranked):# The section disappears when this empties it, and a# silently empty section is the failure the commentdiff --git a/tests/unit/analysis/test_file_reachability.py b/tests/unit/analysis/test_file_reachability.pynew file mode 100644index 000000000..3d9d7e372--- /dev/null+++ b/tests/unit/analysis/test_file_reachability.py@@ -0,0 +1,309 @@+"""The one shared file-reachability predicate.++Two passes ask "can anything reach this file?": the dead-code analyzer, to+report ``unreachable_file``, and the overview assembler, to drop an execution+flow whose entry point is that file. They used to answer it separately — the+assembler hand-copied the barrel filename set and carried a list of languages+where the analyzer was known to be kinder, because the analyzer's version was+a method reading state built during analysis.++What is asserted here:++- co-change and self-import edges are not importers (the analyzer counted+ both through a raw ``in_degree``; the assembler already excluded them);+- an absent package map means "not checked" and answers reachable, which is+ the one place the predicate is deliberately forgiving;+- a supplied package map gets the real per-language answer;+- both callers reach the same verdict on the same graph.+"""++from __future__ import annotations++import networkx as nx+import pytest++from repowise.core.analysis.dead_code.file_reachability import (+ BARREL_FILENAMES,+ ReachabilityRescues,+ build_package_file_map,+ has_dependency_importer,+ is_file_reachable,+)+++def _graph(files: dict[str, dict], edges: list[tuple[str, str, str]] | None = None) -> nx.DiGraph:+ g = nx.DiGraph()+ for path, attrs in files.items():+ g.add_node(path, node_type="file", language=attrs.pop("language", "python"), **attrs)+ for src, dst, edge_type in edges or []:+ g.add_edge(src, dst, edge_type=edge_type)+ return g+++def _rescued(graph: nx.DiGraph) -> ReachabilityRescues:+ """Rescue state a caller holding only the graph can build."""+ return ReachabilityRescues(package_files=build_package_file_map(graph))+++# ---------------------------------------------------------------------------+# which in-edges count as an importer+# ---------------------------------------------------------------------------+++def test_import_edge_makes_a_file_reachable():+ g = _graph(+ {"src/caller.py": {}, "src/service.py": {}},+ [("src/caller.py", "src/service.py", "imports")],+ )+ assert is_file_reachable("src/service.py", g, _rescued(g)) is True+++def test_co_change_edge_is_not_an_importer():+ """Committed together is a historical association, not a path code takes."""+ g = _graph(+ {"src/orphan.py": {}, "docs/notes.md": {"language": "markdown"}},+ [("docs/notes.md", "src/orphan.py", "co_changes")],+ )+ assert has_dependency_importer(g, "src/orphan.py") is False+ assert is_file_reachable("src/orphan.py", g, _rescued(g)) is False+++def test_self_import_is_not_an_importer():+ """A file importing itself is not evidence that anything else uses it.++ Real shape, not a contrivance: ``celery/contrib/sphinx.py`` and several of+ react's feature-flag forks resolve an import back onto themselves, and a+ raw ``in_degree`` read that as a live importer.+ """+ g = _graph({"src/orphan.py": {}}, [("src/orphan.py", "src/orphan.py", "imports")])+ assert has_dependency_importer(g, "src/orphan.py") is False+ assert is_file_reachable("src/orphan.py", g, _rescued(g)) is False+++def test_edge_from_a_symbol_this_file_defines_is_not_an_importer():+ g = _graph({"src/orphan.py": {}})+ g.add_node("src/orphan.py::helper", node_type="symbol", file_path="src/orphan.py")+ g.add_edge("src/orphan.py::helper", "src/orphan.py", edge_type="calls")+ assert is_file_reachable("src/orphan.py", g, _rescued(g)) is False+++def test_a_framework_anchor_counts_but_an_external_package_does_not():+ """The split the zombie-package pass already makes. A TYPO3+ ``ext_localconf.php`` has no source-level importer and is not dead."""+ g = _graph({"ext_localconf.php": {"language": "php"}, "vendored.py": {}})+ g.add_node("framework:typo3-core", language="external")+ g.add_node("external:requests", language="external")+ g.add_edge("framework:typo3-core", "ext_localconf.php", edge_type="framework")+ g.add_edge("external:requests", "vendored.py", edge_type="imports")++ assert is_file_reachable("ext_localconf.php", g, _rescued(g)) is True+ assert is_file_reachable("vendored.py", g, _rescued(g)) is False+++def test_framework_edge_still_counts():+ """Only association edges are excluded, not every non-import edge type."""+ g = _graph(+ {"src/route.py": {}, "src/app.py": {}},+ [("src/app.py", "src/route.py", "framework")],+ )+ assert is_file_reachable("src/route.py", g, _rescued(g)) is True+++# ---------------------------------------------------------------------------+# rescues available to any caller holding the graph+# ---------------------------------------------------------------------------++[email protected]("attr", ["is_entry_point", "is_api_contract", "is_never_flag"])+def test_node_flag_rescues_a_file_with_no_importer(attr):+ g = _graph({"src/thing.py": {attr: True}})+ assert is_file_reachable("src/thing.py", g, _rescued(g)) is True++[email protected]("name", sorted(BARREL_FILENAMES))+def test_barrel_is_reachable(name):+ """A barrel is reached by the names it forwards, never by its own path."""+ path = f"src/feature/{name}"+ g = _graph({path: {}})+ assert is_file_reachable(path, g, _rescued(g)) is True+++def test_bundler_alias_target_is_reachable_when_the_caller_supplies_it():+ g = _graph({"src/shims/shiki.ts": {"language": "typescript"}})+ assert is_file_reachable("src/shims/shiki.ts", g, _rescued(g)) is False+ rescues = ReachabilityRescues(+ bundler_alias_targets=frozenset({"src/shims/shiki.ts"}),+ package_files=build_package_file_map(g),+ )+ assert is_file_reachable("src/shims/shiki.ts", g, rescues) is True+++def test_a_node_outside_the_graph_is_unchecked_not_unreachable():+ assert is_file_reachable("src/gone.py", _graph({}), None) is True+++# ---------------------------------------------------------------------------+# the package-granular languages — the one deliberately forgiving branch+# ---------------------------------------------------------------------------++_PACKAGE_GRANULAR = [+ "internal/scheduler/queue.go",+ "src/main/java/app/Queue.java",+ "src/Queue.kt",+ "src/engine/queue.cpp",+ "include/engine/queue.h",+]++[email protected]("path", _PACKAGE_GRANULAR)+def test_no_package_map_means_not_checked_and_answers_reachable(path):+ """Their imports name a package, so most files in a live package carry no+ file-level in-edge. A caller without the map would call a whole language+ unreachable, so an unchecked package-granular file is kept."""+ g = _graph({path: {}})+ assert is_file_reachable(path, g, ReachabilityRescues()) is True++[email protected]("path", _PACKAGE_GRANULAR)+def test_a_supplied_package_map_gets_the_real_answer(path):+ """With the map the predicate stops guessing: a lone file in its own+ package, with no importer and no entry-point sibling, is unreachable."""+ g = _graph({path: {}})+ assert is_file_reachable(path, g, _rescued(g)) is False+++ ("path", "package_granular"),+ [+ ("src/Queue.GO", False), # the old assembler regex was case-insensitive+ ("src/Queue.CPP", False),+ ("src/queue.h++", True), # is_cpp_path covers these; the regex did not+ ("src/queue.inc", True),+ ],+)+def test_which_extensions_count_as_package_granular(path, package_granular):+ """Pinned because the two callers disagreed here and the merge picked one.++ The analyzer's rule wins: ``endswith`` plus ``is_cpp_path``. Both are+ case-sensitive, with one exception that is not an oversight —+ ``_CPP_SOURCE_EXTS`` lists ``.C``, the traditional Unix spelling of a C+++ source. The assembler previously used a case-insensitive regex, so+ an uppercase ``.CPP`` is now checked rather than blanket-rescued, and+ ``.h++`` / ``.inc`` are blanket-rescued where the regex missed them. No+ file in the 41-repo corpus has either spelling, so this pins intent rather+ than recording an observed change.+ """+ g = _graph({path: {}})+ assert is_file_reachable(path, g, ReachabilityRescues()) is package_granular+++def test_package_sibling_rescue_applies_through_the_predicate():+ """The per-language helpers are not bypassed — an imported sibling in the+ same package rescues the whole package."""+ g = _graph(+ {+ "internal/q/queue.go": {"language": "go"},+ "internal/q/worker.go": {"language": "go"},+ "cmd/app/main.go": {"language": "go"},+ },+ [("cmd/app/main.go", "internal/q/worker.go", "imports")],+ )+ assert is_file_reachable("internal/q/queue.go", g, _rescued(g)) is True+++# ---------------------------------------------------------------------------+# the two callers agree — the whole point of the extraction+# ---------------------------------------------------------------------------+++def test_analyzer_flags_a_file_whose_only_in_edge_is_co_change():+ """End to end through the detector, not just the predicate: the analyzer+ read a raw ``in_degree``, so a doc committed alongside a file counted as+ that file's importer and silenced the finding."""+ from repowise.core.analysis.dead_code import DeadCodeAnalyzer+ from repowise.core.analysis.dead_code.constants import _DEFAULT_DYNAMIC_PATTERNS++ g = _graph(+ {"src/orphan.py": {}, "docs/notes.md": {"language": "markdown"}},+ [("docs/notes.md", "src/orphan.py", "co_changes")],+ )+ findings = DeadCodeAnalyzer(g)._detect_unreachable_files(_DEFAULT_DYNAMIC_PATTERNS, set())+ assert "src/orphan.py" in {f.file_path for f in findings}+++def test_analyzer_flags_a_file_that_only_imports_itself():+ from repowise.core.analysis.dead_code import DeadCodeAnalyzer+ from repowise.core.analysis.dead_code.constants import _DEFAULT_DYNAMIC_PATTERNS++ g = _graph({"src/orphan.py": {}}, [("src/orphan.py", "src/orphan.py", "imports")])+ findings = DeadCodeAnalyzer(g)._detect_unreachable_files(_DEFAULT_DYNAMIC_PATTERNS, set())+ assert "src/orphan.py" in {f.file_path for f in findings}+++def test_the_predicate_is_the_only_thing_deciding_reachability():+ """Which side of the split each rescue sits on, pinned.++ Asserting ``flagged == {n for n in nodes if not is_file_reachable(n)}``+ would look like a strong agreement check and be nearly vacuous, since the+ detector calls that same function. So does ``not flagged - unreachable``+ below: the predicate is the last gate before a finding is made, so that+ containment holds by construction and only guards against reordering.++ The assertion that earns its place is ``unreachable - flagged``, which+ names every file the predicate calls unreachable that the analyzer still+ declines to report. Move the barrel rescue out of the predicate and+ ``__init__.py`` joins that set; move ``is_test`` into the predicate and the+ test file leaves it. Either way this fails.++ What that set means, precisely: the analyzer's remaining skips are+ candidacy rules, "is this a file we would ever report", and the assembler+ deliberately wants none of them applied to an execution flow. Note the+ split is not clean the other way — ``is_entry_point``, ``is_never_flag``+ and the ``__init__.py`` barrel are checked in *both* places, harmlessly,+ since every one of them is idempotent. And ``_should_never_flag`` is a+ reachability rule rather than a candidacy one (``*.sh`` is exempt because+ CI invokes it by name), which is exactly why ``ReachabilityRescues``+ records its glob set as a rescue the second caller is missing.++ Coverage ceiling: the fixture exercises the non-code-language,+ ``is_entry_point`` and ``is_test`` skips. ``_is_synthetic_node``,+ ``_is_fixture_path`` and the never-flag globs are not represented here.+ """+ from repowise.core.analysis.dead_code import DeadCodeAnalyzer+ from repowise.core.analysis.dead_code.constants import _DEFAULT_DYNAMIC_PATTERNS++ g = _graph(+ {+ "src/caller.py": {},+ "src/service.py": {},+ "src/orphan.py": {},+ "src/main.py": {"is_entry_point": True},+ "src/pkg/__init__.py": {},+ "tests/test_orphan.py": {"is_test": True},+ "docs/notes.md": {"language": "markdown"},+ },+ [+ ("src/caller.py", "src/service.py", "imports"),+ ("docs/notes.md", "src/orphan.py", "co_changes"),+ ],+ )++ analyzer = DeadCodeAnalyzer(g)+ rescues = analyzer._reachability_rescues()+ flagged = {+ f.file_path for f in analyzer._detect_unreachable_files(_DEFAULT_DYNAMIC_PATTERNS, set())+ }+ unreachable = {n for n in g.nodes() if not is_file_reachable(str(n), g, rescues)}++ assert flagged == {"src/caller.py", "src/orphan.py"}+ assert "src/service.py" not in flagged+ assert "src/main.py" not in flagged+ assert "src/pkg/__init__.py" not in flagged++ # The gap between the two is candidacy and nothing else. A markdown file+ # and a test file are both unreachable and neither is dead code, and the+ # rules that say so are the analyzer's non-code-language and is_test skips+ # — deliberately not in the predicate, which the assembler also does not+ # want applied to an execution flow.+ assert unreachable - flagged == {"docs/notes.md", "tests/test_orphan.py"}+ assert not flagged - unreachablediff --git a/tests/unit/generation/test_context_assembler.py b/tests/unit/generation/test_context_assembler.pyindex e6a5b7da1..a35e3af8c 100644--- a/tests/unit/generation/test_context_assembler.py+++ b/tests/unit/generation/test_context_assembler.py@@ -484,20 +484,20 @@ def test_foreign_edge_rejects_this_files_own_symbols():were 70% of every dependency line on the file pages, and on some pagesthey were the entire list."""- from repowise.core.generation.context.assembler import _is_foreign_edge+ from repowise.core.analysis.dead_code.file_reachability import is_foreign_edgepath = "pkg/mod.py"- assert not _is_foreign_edge("pkg/mod.py", path)- assert not _is_foreign_edge("pkg/mod.py::Thing", path)- assert not _is_foreign_edge("pkg/mod.py::Thing::method", path)- assert not _is_foreign_edge("external:requests", path)+ assert not is_foreign_edge("pkg/mod.py", path)+ assert not is_foreign_edge("pkg/mod.py::Thing", path)+ assert not is_foreign_edge("pkg/mod.py::Thing::method", path)+ assert not is_foreign_edge("external:requests", path)def test_foreign_edge_keeps_real_neighbours():- from repowise.core.generation.context.assembler import _is_foreign_edge+ from repowise.core.analysis.dead_code.file_reachability import is_foreign_edgepath = "pkg/mod.py"- assert _is_foreign_edge("pkg/other.py", path)- assert _is_foreign_edge("pkg/other.py::Thing", path)+ assert is_foreign_edge("pkg/other.py", path)+ assert is_foreign_edge("pkg/other.py::Thing", path)# A path that merely shares a prefix is a different file.- assert _is_foreign_edge("pkg/mod_extra.py", path)+ assert is_foreign_edge("pkg/mod_extra.py", path)diff --git a/tests/unit/generation/test_overview_execution_flows.py b/tests/unit/generation/test_overview_execution_flows.pyindex 3adc974e2..886bffaae 100644--- a/tests/unit/generation/test_overview_execution_flows.py+++ b/tests/unit/generation/test_overview_execution_flows.py@@ -164,9 +164,15 @@ def test_conventional_entry_point_survives_having_no_importers(],)def test_filter_bails_out_where_dead_code_is_kinder(sample_config, sample_repo_structure, path):- """The analyzer rescues these from unreachable_file through checks this- filter cannot reach. Over-dropping empties the section silently, so where- the two models are known to diverge the flow is kept."""+ """The analyzer rescues these from unreachable_file, so the flow stays.++ The barrels are rescued by the shared predicate outright. The+ package-granular languages are rescued because this caller passes no+ package map, which the predicate reads as "not checked" and answers+ reachable — the forgiving direction, chosen at the call site rather than+ falling out of what state happened to be available. Over-dropping empties+ the section silently, which is the failure being avoided.+ """graph = _graph_with({path: {"is_entry_point": False}}, imports=[])flows = [_flow(f"{path}::f", 0.95, ["a", "b"])]@@ -178,6 +184,38 @@ def test_filter_bails_out_where_dead_code_is_kinder(sample_config, sample_repo_sassert [f["entry_point"] for f in ctx.execution_flows] == [f"{path}::f"][email protected]("attr", ["is_api_contract", "is_never_flag"])+def test_flow_survives_the_rescues_the_analyzer_already_applied(+ sample_config, sample_repo_structure, attr+):+ """Both flags live on the graph node, so this caller always had them and+ never asked. Sharing the predicate means it does now, and the two passes+ stop disagreeing about a published API contract with no importer."""+ graph = _graph_with({"src/contract.py": {"is_entry_point": False, attr: True}}, imports=[])+ flows = [_flow("src/contract.py::f", 0.95, ["a", "b"])]++ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(+ sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)+ )++ assert [f["entry_point"] for f in ctx.execution_flows] == ["src/contract.py::f"]+++def test_self_import_does_not_rescue_a_flow_entry_point(sample_config, sample_repo_structure):+ """A file importing itself is not evidence anything else reaches it."""+ graph = _graph_with({"src/orphan.py": {"is_entry_point": False}}, imports=[])+ graph.add_edge("src/orphan.py", "src/orphan.py", edge_type="imports")+ flows = [_flow("src/orphan.py::f", 0.95, ["a", "b"])]++ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(+ sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)+ )++ assert ctx.execution_flows == []++def test_dropping_a_flow_is_logged(sample_config, sample_repo_structure):"""An empty section is a fine outcome; a silent one is not."""graph = _graph_with({"src/orphan.py": {"is_entry_point": False}}, imports=[])