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(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.py
index 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, DeadCodeReport
from .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._rescues
def analyze(
self,
@@ -772,40 +738,13 @@ class DeadCodeAnalyzer:
continue
if 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()):
continue
finding = self._make_unreachable_finding(str(node), node_data, dynamic_patterns)
@@ -1598,9 +1537,6 @@ class DeadCodeAnalyzer:
# __init__.py is a re-export barrel
return 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 it
diff --git a/packages/core/src/repowise/core/analysis/dead_code/file_reachability.py b/packages/core/src/repowise/core/analysis/dead_code/file_reachability.py
new file mode 100644
index 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.py
index 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 Any
import 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_external
from 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 comment
diff --git a/tests/unit/analysis/test_file_reachability.py b/tests/unit/analysis/test_file_reachability.py
new file mode 100644
index 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 - unreachable
diff --git a/tests/unit/generation/test_context_assembler.py b/tests/unit/generation/test_context_assembler.py
index 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 pages
they 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_edge
path = "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_edge
path = "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.py
index 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_s
assert [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=[])