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.

refactor(dead-code): move the unreachable-file and unused-internal passes into passes/ (#4049)

Raghav Chamadiya906cafd47229
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 ea4115980..2bda4ec01 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -35,15 +35,12 @@ from .c_name_uses import (
from .constants import (
_DEAD_CODE_EXEMPT_LANGUAGES,
_DEFAULT_DYNAMIC_PATTERNS,
- _NAMESPACE_IMPORT_LANGUAGES,
_NEVER_PACKAGE_DIRS,
_PREPROCESSED_LANGUAGES,
_PROJECT_FILE_SUFFIXES,
_RUN_NOT_IMPORTED_LANGUAGES,
- _is_fixture_path,
never_flag_path,
)
-from .contract_methods import is_contract_method
from .csharp_reachability import (
build_csharp_named_files,
build_csharp_named_types,
@@ -76,7 +73,6 @@ from .file_reachability import (
PackageFileMap,
ReachabilityRescues,
build_package_file_map,
- is_file_reachable,
)
from .finding_helpers import (
_LINES_UNKNOWN,
@@ -102,13 +98,13 @@ from .name_occurrences import (
drop_internals_used_in_own_file,
drop_reference_assembly_api,
)
+from .passes.unreachable_files import UnreachableFilePass
from .passes.unused_exports import UnusedExportPass
+from .passes.unused_internals import UnusedInternalPass
from .published_api import BuildFacts, demote_published_api
from .risk_factors import (
- NO_GIT_SIGNAL_CONFIDENCE,
RISK_CAP_CONFIDENCE,
path_risk_factors,
- risk_evidence,
)
from .source_prepasses import ( # noqa: F401 (moved scans re-exported)
_BUNDLER_CONFIG_STEMS,
@@ -165,13 +161,6 @@ _UNINDEXED_SCAN_TOTAL_BYTES = 32 * 1024 * 1024
logger = structlog.get_logger(__name__)
-
-#: ``(days, confidence)`` rungs for a file with no commit in 90 days, oldest
-#: first. ``_is_old`` uses strict >, so days-1 gives >= semantics: a year or
-#: more untouched is 1.0, very likely dead.
-_GIT_AGE_RUNGS: tuple[tuple[int, float], ...] = ((364, 1.0), (179, 0.9), (89, 0.8))
-
-
class DeadCodeAnalyzer:
"""Detects unreachable files, unused exports, unused internals, and
zombie packages using the dependency graph and git metadata.
@@ -226,7 +215,7 @@ class DeadCodeAnalyzer:
) | find_dynamic_edge_files(graph)
# Parent directories of the above, precomputed once.
#
- # ``_make_unreachable_finding`` asks "does any dynamic-import file sit
+ # the unreachable-file pass asks "does any dynamic-import file sit
# in the same package as this node". That used to be a scan over
# ``_dynamic_import_files`` constructing a ``Path`` per candidate, run
# once per unreachable candidate: O(candidates x dynamic_files) with a
@@ -453,53 +442,28 @@ class DeadCodeAnalyzer:
# Detection methods
# ------------------------------------------------------------------
- def _detect_unused_exports(
+ def _detect_unreachable_files(
self,
- dynamic_patterns: tuple[str, ...],
whitelist: set[str],
) -> list[DeadCodeFindingData]:
- """Detect public symbols with no incoming edges."""
- return UnusedExportPass(self).run(dynamic_patterns, whitelist)
+ """Detect files nothing can reach that are not tests, fixtures, or config."""
+ return UnreachableFilePass(self).run(whitelist)
- def _detect_unreachable_files(
+ def _detect_unused_internals(
self,
+ dynamic_patterns: tuple[str, ...],
whitelist: set[str],
) -> list[DeadCodeFindingData]:
- """Detect files nothing can reach that are not tests, fixtures, or config."""
- findings = []
-
- # One object for the whole pass rather than one per node: the rescues
- # do not vary by candidate.
- rescues = self._reachability_rescues(whitelist)
-
- for node in self.graph.nodes():
- if _is_synthetic_node(str(node)):
- continue
-
- node_data = self.graph.nodes[node]
- # The three skips left here are *scoping*, not reachability: a test
- # file is perfectly reachable, it is just not something this pass
- # reports. Everything that answers "can anything get to this file"
- # — entry points, API contracts, never-flag globs, the whitelist,
- # barrels, bundler-alias shims and the package-granular languages
- # (Go / JVM / C-C++) — lives in the predicate, which the overview
- # assembler calls with the same state so the two cannot disagree.
- # See :mod:`file_reachability`.
- if node_data.get("language", "unknown") in _DEAD_CODE_EXEMPT_LANGUAGES:
- continue
- if node_data.get("is_test", False):
- continue
- if _is_fixture_path(str(node)):
- continue
+ """Detect private symbols with zero incoming call edges."""
+ return UnusedInternalPass(self).run(dynamic_patterns, whitelist)
- if is_file_reachable(str(node), self.graph, rescues):
- continue
-
- finding = self._make_unreachable_finding(str(node), node_data)
- if finding:
- findings.append(finding)
-
- return findings
+ def _detect_unused_exports(
+ self,
+ dynamic_patterns: tuple[str, ...],
+ whitelist: set[str],
+ ) -> list[DeadCodeFindingData]:
+ """Detect public symbols with no incoming edges."""
+ return UnusedExportPass(self).run(dynamic_patterns, whitelist)
def _preprocessed_declaration_sites(self) -> DeclarationSites:
"""Where each C/C++ symbol name is declared: a prototype's whole span, a
@@ -604,108 +568,6 @@ class DeadCodeAnalyzer:
)
return findings
- def _make_unreachable_finding(
- self,
- node: str,
- node_data: dict,
- ) -> DeadCodeFindingData | None:
- """Create an unreachable file finding with confidence scoring."""
- git_meta = self.git_meta_map.get(node)
- # No row at all is not "no commits in 90 days": that rung is for a
- # file git has data on. Scored below the deletion-ready threshold and
- # said so in the evidence, on every path that builds this map.
- no_git_signal = not git_meta
- git_meta = git_meta or {}
- commit_90d = git_meta.get("commit_count_90d", 0)
- last_commit = git_meta.get("last_commit_at")
- age_days = git_meta.get("age_days")
- primary_owner = git_meta.get("primary_owner_name")
-
- confidence = (
- NO_GIT_SIGNAL_CONFIDENCE
- if no_git_signal
- else self._git_age_confidence(commit_90d, last_commit, age_days)
- )
-
- # The ladder above is an evidence scale, not a tier boundary: its rungs
- # stay literal so moving a threshold does not silently re-score how
- # strong the git signal is. Everything below compares against or caps
- # to a threshold, so it reads the constants.
-
- # Reduce confidence when dynamic imports exist in the same package.
- if self._dynamic_import_dirs and str(Path(node).parent) in self._dynamic_import_dirs:
- confidence = min(confidence, RISK_CAP_CONFIDENCE)
-
- # Runtime-load risk factors (config / bootstrap / database /
- # environment / script / asset). These are files the never-flag allowlist
- # didn't catch but that are commonly referenced outside static
- # imports, so "in_degree=0" is weak evidence. Cap confidence below the
- # deletion-ready threshold and surface the factors as evidence — the
- # finding still shows up as a review candidate.
- risk_factors = path_risk_factors(node)
- if risk_factors:
- confidence = min(confidence, RISK_CAP_CONFIDENCE)
-
- # A namespace-imported file is reached without an edge (a same-namespace
- # ``new T()``), so no edge says little and its age says nothing more.
- namespace_imported = node_data.get("language") in _NAMESPACE_IMPORT_LANGUAGES
- if namespace_imported:
- confidence = min(confidence, RISK_CAP_CONFIDENCE)
-
- # A whole file is a review candidate, never deletion-ready: see
- # ``REVIEW_ONLY_KINDS``. Confidence still ranks it.
- safe = False
-
- evidence = ["in_degree=0 (no files import this)"]
- if no_git_signal:
- evidence.append("No git history recorded for this file")
- elif commit_90d == 0:
- evidence.append("No commits in last 90 days")
- if self._dynamic_import_files and confidence <= RISK_CAP_CONFIDENCE:
- evidence.append("Package uses dynamic imports or runtime-resolved edges")
- risk_line = risk_evidence(risk_factors)
- if risk_line:
- evidence.append(risk_line)
- if namespace_imported:
- evidence.append(
- "Imported by namespace, not by file, so having no importer is weak evidence"
- )
- lines = self._file_line_count(node)
- if lines is None:
- evidence.append(_LINES_UNKNOWN)
-
- return DeadCodeFindingData(
- kind=DeadCodeKind.UNREACHABLE_FILE,
- file_path=node,
- symbol_name=None,
- symbol_kind=None,
- confidence=confidence,
- reason="File has no importers (in_degree=0)",
- last_commit_at=last_commit if isinstance(last_commit, datetime) else None,
- commit_count_90d=commit_90d,
- lines=lines,
- evidence=evidence,
- safe_to_delete=safe,
- primary_owner=primary_owner,
- age_days=age_days,
- risk_factors=list(risk_factors),
- )
-
- def _git_age_confidence(
- self, commit_90d: int, last_commit: Any, age_days: int | None
- ) -> float:
- """The git-age evidence ladder for a file no edge reaches."""
- if commit_90d != 0:
- return 0.4
- if last_commit:
- for days, confidence in _GIT_AGE_RUNGS:
- if self._is_old(last_commit, days=days):
- return confidence
- if age_days is not None and age_days < 30:
- return 0.55 # Recently created — may be WIP
- return 0.7
-
-
def _defined_symbols(self, node: Any) -> list[tuple[str, dict]]:
"""``(symbol_id, data)`` for each symbol *node* defines."""
return [
@@ -729,7 +591,6 @@ class DeadCodeAnalyzer:
if f.kind is DeadCodeKind.UNREACHABLE_FILE and self.graph.has_node(f.file_path)
}
-
def _imported_names_by_edge(
self, node: Any, edge_types: tuple[str, ...] | None = ("imports",)
) -> Iterator[list[str]]:
@@ -740,7 +601,6 @@ class DeadCodeAnalyzer:
continue
yield edge.get("imported_names", [])
-
def _git_fields(self, file_path: str) -> dict[str, Any]:
"""The git-activity fields a symbol finding carries for *file_path*."""
git_meta = self.git_meta_map.get(file_path, {})
@@ -813,77 +673,6 @@ class DeadCodeAnalyzer:
logger.warning("read_file_text_failed", path=file_path, error=str(exc))
return None
- def _detect_unused_internals(
- self,
- dynamic_patterns: tuple[str, ...],
- whitelist: set[str],
- ) -> list[DeadCodeFindingData]:
- """Detect private symbols with zero incoming call edges.
-
- On by default. These carry a higher false-positive rate than the other
- detectors, which is why they land at a lower confidence. Disable with
- ``detect_unused_internals=False`` in the config dict.
- """
- findings: list[DeadCodeFindingData] = []
-
- for node, node_data in self.graph.nodes(data=True):
- if not self._is_internal_candidate(node_data, dynamic_patterns, whitelist):
- continue
- file_path = node_data.get("file_path", "")
- sym_name = node_data.get("name", "")
-
- # Any inbound use, not only a call. A base class that is subclassed
- # rather than instantiated, a collaborator the container constructs,
- # and a handler named as a value rather than invoked each carry a
- # symbol-level edge of their own; reading only ``calls`` here
- # reported all three as unused. The set is shared with the
- # unused-export pass, so it also carries types this population can
- # never hold — a method or an interface is filtered out above.
- # ``new X(..)`` lands on X's constructor (``path::X::X``) when X
- # declares one, and constructing a type uses it.
- if self._has_inbound_use(node) or self._has_inbound_use(
- f"{file_path}::{sym_name}::{sym_name}"
- ):
- continue
-
- # Dispatch-table pattern: a private helper imported by name
- # into a sibling module and stored in a lookup dict
- # (``HANDLERS = {"python": _extract_python_heritage, ...}``).
- # The function is reached at runtime via dict lookup, so no
- # direct ``calls`` edge ever lands in the graph — but the
- # ``imports`` edge into its file carries the symbol name. If
- # any cross-file importer pulled this symbol by name,
- # something is actively referencing it; do not flag.
- if any(
- sym_name in imported or "*" in imported
- for imported in self._imported_names_by_edge(file_path)
- ):
- continue
-
- # Private symbols keep the standard 0.65 base confidence even if deprecated.
- # A private symbol has no external consumer by construction —
- # deprecated + uncalled is the strongest possible delete signal and
- # must not be buried below the default min_confidence floor.
- # (0.3 is reserved for unused *exports*, where an invisible consumer
- # outside the repo may still import it.)
- findings.append(
- DeadCodeFindingData(
- kind=DeadCodeKind.UNUSED_INTERNAL,
- file_path=file_path,
- symbol_name=sym_name,
- symbol_kind=node_data.get("kind"),
- confidence=0.65,
- reason=f"Private symbol '{sym_name}' is not used anywhere",
- evidence=[f"No call, reference or override reaches '{sym_name}'"],
- safe_to_delete=False,
- risk_factors=list(path_risk_factors(file_path)),
- **_symbol_span(node_data),
- **self._git_fields(file_path),
- )
- )
-
- return findings
-
def _overload_unit(self, node: str) -> list[str]:
"""The members of the overload set *node* belongs to or names, else ``[]``.
@@ -950,78 +739,6 @@ class DeadCodeAnalyzer:
and pred_span["end_line"] <= node_span["end_line"]
)
- def _is_internal_candidate(
- self, node_data: dict, dynamic_patterns: tuple[str, ...], whitelist: set[str]
- ) -> bool:
- """Whether a graph node is a private symbol the unused-internal pass may judge."""
- if node_data.get("node_type") != "symbol":
- return False
- # Rust: rustc's own `dead_code` lint already reports unused
- # private items, with the macro expansion and type information a
- # static graph cannot match. Nothing here it would not find first.
- if node_data.get("language") == "rust":
- return False
- # Go's call resolver now resolves same-package (sibling-file) and
- # package-qualified calls (see call_resolver._resolve_go_*), so
- # private symbols used across a package's files carry real
- # ``calls`` edges and no longer read as universally uncalled. The
- # blanket exemption that Phase 2 added has been lifted.
- # ``internal`` is not narrow: assembly-wide in C#, module-wide in
- # Swift and Kotlin, crate-wide in Rust. A legitimate user can sit
- # anywhere in the module, so a missing inbound call edge is not
- # evidence of deadness. Nothing else observes ``internal`` either,
- # which drops an unmodified C# top-level type out of both passes.
- if node_data.get("visibility") != "private":
- return False
- file_path = node_data.get("file_path", "")
- if not file_path:
- return False
- file_data = self.graph.nodes.get(file_path, {})
- if file_data.get("is_test", False):
- return False
- if _is_fixture_path(file_path):
- return False
- if self._should_never_flag(file_path, whitelist):
- return False
- return self._is_judgeable_internal(node_data, dynamic_patterns)
-
- def _is_judgeable_internal(self, node_data: dict, dynamic_patterns: tuple[str, ...]) -> bool:
- """Whether a missing call edge says anything about this private symbol."""
- sym_name = node_data.get("name", "")
- if sym_name.startswith("__") and sym_name.endswith("__"):
- return False
- if sym_name in _ENTRY_POINT_SYMBOL_NAMES:
- return False
- # Namespace-path fragments (e.g. ``eShop.ClientApp``) and
- # non-callable kinds bypass the call-edge pass by design.
- if "." in sym_name:
- return False
- if node_data.get("kind") in _non_importable_kinds(node_data.get("language", "unknown")):
- return False
- # Non-callable type kinds can't have CALL edges; the call-graph
- # check this pass performs is meaningless for them (see
- # _UNCALLABLE_TYPE_KINDS). They remain covered by unused_export.
- if node_data.get("kind") in _UNCALLABLE_TYPE_KINDS:
- return False
- if is_contract_method(
- sym_name,
- node_data.get("kind"),
- node_data.get("language", "unknown"),
- modifiers=node_data.get("modifiers"),
- ):
- return False
- if self._name_matches_dynamic(sym_name, dynamic_patterns):
- return False
-
- # Framework-decorator skip — same shape as unused-export. A
- # private ``@PostConstruct``/``@EventListener``/``@Scheduled``
- # method is invoked by the container, not by a source call.
- decorators = node_data.get("decorators") or []
- meta = self._framework_meta_annotations(node_data.get("file_path", ""))
- return not (
- _is_framework_registered(decorators, meta) or _declared_deliberately_unused(decorators)
- )
-
def _detect_zombie_packages(self, whitelist: set[str]) -> list[DeadCodeFindingData]:
"""Detect monorepo packages with no incoming inter_package edges.
@@ -1234,17 +951,5 @@ class DeadCodeAnalyzer:
# __init__.py is a re-export barrel
return Path(path).name == "__init__.py"
-
def _name_matches_dynamic(self, name: str, patterns: tuple[str, ...]) -> bool:
return any(fnmatch.fnmatch(name, pattern) for pattern in patterns)
-
- def _is_old(self, dt: Any, days: int = 180) -> bool:
- """Return True if datetime is older than `days` ago."""
- if dt is None:
- return False
- now = datetime.now(UTC)
- if isinstance(dt, datetime):
- if dt.tzinfo is None:
- dt = dt.replace(tzinfo=UTC)
- return (now - dt).days > days
- return False
diff --git a/packages/core/src/repowise/core/analysis/dead_code/passes/unreachable_files.py b/packages/core/src/repowise/core/analysis/dead_code/passes/unreachable_files.py
new file mode 100644
index 000000000..b3037de28
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/dead_code/passes/unreachable_files.py
@@ -0,0 +1,179 @@
+"""The unreachable-file pass: files nothing can reach that are not tests, fixtures or config."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..constants import (
+ _DEAD_CODE_EXEMPT_LANGUAGES,
+ _NAMESPACE_IMPORT_LANGUAGES,
+ _is_fixture_path,
+)
+from ..file_reachability import is_file_reachable
+from ..finding_helpers import _LINES_UNKNOWN, _is_synthetic_node
+from ..models import DeadCodeFindingData, DeadCodeKind
+from ..risk_factors import (
+ NO_GIT_SIGNAL_CONFIDENCE,
+ RISK_CAP_CONFIDENCE,
+ path_risk_factors,
+ risk_evidence,
+)
+
+if TYPE_CHECKING:
+ from ..analyzer import DeadCodeAnalyzer
+
+
+#: ``(days, confidence)`` rungs for a file with no commit in 90 days, oldest
+#: first. ``_is_old`` uses strict >, so days-1 gives >= semantics: a year or
+#: more untouched is 1.0, very likely dead.
+_GIT_AGE_RUNGS: tuple[tuple[int, float], ...] = ((364, 1.0), (179, 0.9), (89, 0.8))
+
+
+class UnreachableFilePass:
+ """Scores each file the shared reachability predicate cannot reach."""
+
+ def __init__(self, ctx: DeadCodeAnalyzer) -> None:
+ self.ctx = ctx
+ self.graph = ctx.graph
+
+ def run(
+ self,
+ whitelist: set[str],
+ ) -> list[DeadCodeFindingData]:
+ """Detect files nothing can reach that are not tests, fixtures, or config."""
+ findings = []
+
+ # The rescues do not vary by candidate: build them once per pass.
+ rescues = self.ctx._reachability_rescues(whitelist)
+
+ for node in self.graph.nodes():
+ if _is_synthetic_node(str(node)):
+ continue
+
+ node_data = self.graph.nodes[node]
+ # These skips are scoping, not reachability; every reachability
+ # rule lives in :func:`is_file_reachable`, which the overview
+ # assembler shares so the two cannot disagree.
+ if node_data.get("language", "unknown") in _DEAD_CODE_EXEMPT_LANGUAGES:
+ continue
+ if node_data.get("is_test", False):
+ continue
+ if _is_fixture_path(str(node)):
+ continue
+
+ if is_file_reachable(str(node), self.graph, rescues):
+ continue
+
+ finding = self._make_unreachable_finding(str(node), node_data)
+ if finding:
+ findings.append(finding)
+
+ return findings
+
+ def _make_unreachable_finding(
+ self,
+ node: str,
+ node_data: dict,
+ ) -> DeadCodeFindingData | None:
+ """Create an unreachable file finding with confidence scoring."""
+ git_meta = self.ctx.git_meta_map.get(node)
+ # No row at all is not "no commits in 90 days": that rung is for a
+ # file git has data on. Scored below the deletion-ready threshold and
+ # said so in the evidence, on every path that builds this map.
+ no_git_signal = not git_meta
+ git_meta = git_meta or {}
+ commit_90d = git_meta.get("commit_count_90d", 0)
+ last_commit = git_meta.get("last_commit_at")
+ age_days = git_meta.get("age_days")
+ primary_owner = git_meta.get("primary_owner_name")
+
+ confidence = (
+ NO_GIT_SIGNAL_CONFIDENCE
+ if no_git_signal
+ else self._git_age_confidence(commit_90d, last_commit, age_days)
+ )
+
+ # The git-age rungs are an evidence scale and stay literal; the caps
+ # below are tier boundaries and read the constants.
+
+ # Reduce confidence when dynamic imports exist in the same package.
+ if self.ctx._dynamic_import_dirs and str(Path(node).parent) in self.ctx._dynamic_import_dirs:
+ confidence = min(confidence, RISK_CAP_CONFIDENCE)
+
+ # Runtime-load risk factors (config, bootstrap, scripts, assets) make
+ # "in_degree=0" weak evidence: cap and say so in the evidence.
+ risk_factors = path_risk_factors(node)
+ if risk_factors:
+ confidence = min(confidence, RISK_CAP_CONFIDENCE)
+
+ # A namespace-imported file is reached without an edge (a same-namespace
+ # ``new T()``), so no edge says little and its age says nothing more.
+ namespace_imported = node_data.get("language") in _NAMESPACE_IMPORT_LANGUAGES
+ if namespace_imported:
+ confidence = min(confidence, RISK_CAP_CONFIDENCE)
+
+ # A whole file is a review candidate, never deletion-ready: see
+ # ``REVIEW_ONLY_KINDS``. Confidence still ranks it.
+ safe = False
+
+ evidence = ["in_degree=0 (no files import this)"]
+ if no_git_signal:
+ evidence.append("No git history recorded for this file")
+ elif commit_90d == 0:
+ evidence.append("No commits in last 90 days")
+ if self.ctx._dynamic_import_files and confidence <= RISK_CAP_CONFIDENCE:
+ evidence.append("Package uses dynamic imports or runtime-resolved edges")
+ risk_line = risk_evidence(risk_factors)
+ if risk_line:
+ evidence.append(risk_line)
+ if namespace_imported:
+ evidence.append(
+ "Imported by namespace, not by file, so having no importer is weak evidence"
+ )
+ lines = self.ctx._file_line_count(node)
+ if lines is None:
+ evidence.append(_LINES_UNKNOWN)
+
+ return DeadCodeFindingData(
+ kind=DeadCodeKind.UNREACHABLE_FILE,
+ file_path=node,
+ symbol_name=None,
+ symbol_kind=None,
+ confidence=confidence,
+ reason="File has no importers (in_degree=0)",
+ last_commit_at=last_commit if isinstance(last_commit, datetime) else None,
+ commit_count_90d=commit_90d,
+ lines=lines,
+ evidence=evidence,
+ safe_to_delete=safe,
+ primary_owner=primary_owner,
+ age_days=age_days,
+ risk_factors=list(risk_factors),
+ )
+
+ def _git_age_confidence(
+ self, commit_90d: int, last_commit: Any, age_days: int | None
+ ) -> float:
+ """The git-age evidence ladder for a file no edge reaches."""
+ if commit_90d != 0:
+ return 0.4
+ if last_commit:
+ for days, confidence in _GIT_AGE_RUNGS:
+ if self._is_old(last_commit, days=days):
+ return confidence
+ if age_days is not None and age_days < 30:
+ return 0.55 # Recently created: may be work in progress
+ return 0.7
+
+ def _is_old(self, dt: Any, days: int = 180) -> bool:
+ """Return True if datetime is older than `days` ago."""
+ if dt is None:
+ return False
+ now = datetime.now(UTC)
+ if isinstance(dt, datetime):
+ if dt.tzinfo is None:
+ dt = dt.replace(tzinfo=UTC)
+ return (now - dt).days > days
+ return False
diff --git a/packages/core/src/repowise/core/analysis/dead_code/passes/unused_internals.py b/packages/core/src/repowise/core/analysis/dead_code/passes/unused_internals.py
new file mode 100644
index 000000000..415ef58eb
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/dead_code/passes/unused_internals.py
@@ -0,0 +1,140 @@
+"""The unused-internal pass: private symbols no call, reference or override reaches."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..constants import _is_fixture_path
+from ..contract_methods import is_contract_method
+from ..decorator_rules import _declared_deliberately_unused, _is_framework_registered
+from ..finding_helpers import _symbol_span
+from ..models import DeadCodeFindingData, DeadCodeKind
+from ..risk_factors import path_risk_factors
+from ..symbol_rules import _ENTRY_POINT_SYMBOL_NAMES, _UNCALLABLE_TYPE_KINDS, _non_importable_kinds
+
+if TYPE_CHECKING:
+ from ..analyzer import DeadCodeAnalyzer
+
+
+class UnusedInternalPass:
+ """Judges every private symbol node of the graph."""
+
+ def __init__(self, ctx: DeadCodeAnalyzer) -> None:
+ self.ctx = ctx
+ self.graph = ctx.graph
+
+ def run(
+ self,
+ dynamic_patterns: tuple[str, ...],
+ whitelist: set[str],
+ ) -> list[DeadCodeFindingData]:
+ """Detect private symbols with zero incoming call edges.
+
+ On by default. These carry a higher false-positive rate than the other
+ detectors, which is why they land at a lower confidence. Disable with
+ ``detect_unused_internals=False`` in the config dict.
+ """
+ findings: list[DeadCodeFindingData] = []
+
+ for node, node_data in self.graph.nodes(data=True):
+ if not self._is_internal_candidate(node_data, dynamic_patterns, whitelist):
+ continue
+ file_path = node_data.get("file_path", "")
+ sym_name = node_data.get("name", "")
+
+ # Any inbound use, not only a call (a subclassed base, a handler
+ # named as a value). ``new X(..)`` lands on X's constructor
+ # (``path::X::X``) when X declares one, and constructing X uses it.
+ if self.ctx._has_inbound_use(node) or self.ctx._has_inbound_use(
+ f"{file_path}::{sym_name}::{sym_name}"
+ ):
+ continue
+
+ # A private helper imported by name elsewhere (a dispatch table
+ # entry) is referenced even with no ``calls`` edge.
+ if any(
+ sym_name in imported or "*" in imported
+ for imported in self.ctx._imported_names_by_edge(file_path)
+ ):
+ continue
+
+ # 0.65 even when deprecated: a private symbol has no outside
+ # consumer, unlike an export (0.3), so deprecation is no reason to hide it.
+ findings.append(
+ DeadCodeFindingData(
+ kind=DeadCodeKind.UNUSED_INTERNAL,
+ file_path=file_path,
+ symbol_name=sym_name,
+ symbol_kind=node_data.get("kind"),
+ confidence=0.65,
+ reason=f"Private symbol '{sym_name}' is not used anywhere",
+ evidence=[f"No call, reference or override reaches '{sym_name}'"],
+ safe_to_delete=False,
+ risk_factors=list(path_risk_factors(file_path)),
+ **_symbol_span(node_data),
+ **self.ctx._git_fields(file_path),
+ )
+ )
+
+ return findings
+
+ def _is_internal_candidate(
+ self, node_data: dict, dynamic_patterns: tuple[str, ...], whitelist: set[str]
+ ) -> bool:
+ """Whether a graph node is a private symbol the unused-internal pass may judge."""
+ if node_data.get("node_type") != "symbol":
+ return False
+ # Rust: the compiler's ``dead_code`` lint already reports these, with
+ # macro expansion and types a static graph cannot match.
+ if node_data.get("language") == "rust":
+ return False
+ # ``internal`` is assembly-, module- or crate-wide, so a missing call
+ # edge is no evidence; no pass judges it, which drops an unmodified
+ # C# top-level type out of both symbol passes.
+ if node_data.get("visibility") != "private":
+ return False
+ file_path = node_data.get("file_path", "")
+ if not file_path:
+ return False
+ file_data = self.graph.nodes.get(file_path, {})
+ if file_data.get("is_test", False):
+ return False
+ if _is_fixture_path(file_path):
+ return False
+ if self.ctx._should_never_flag(file_path, whitelist):
+ return False
+ return self._is_judgeable_internal(node_data, dynamic_patterns)
+
+ def _is_judgeable_internal(self, node_data: dict, dynamic_patterns: tuple[str, ...]) -> bool:
+ """Whether a missing call edge says anything about this private symbol."""
+ sym_name = node_data.get("name", "")
+ if sym_name.startswith("__") and sym_name.endswith("__"):
+ return False
+ if sym_name in _ENTRY_POINT_SYMBOL_NAMES:
+ return False
+ # Namespace-path fragments (e.g. ``eShop.ClientApp``) and
+ # non-callable kinds bypass the call-edge pass by design.
+ if "." in sym_name:
+ return False
+ if node_data.get("kind") in _non_importable_kinds(node_data.get("language", "unknown")):
+ return False
+ # Type kinds have no call edges; the export pass still judges them.
+ if node_data.get("kind") in _UNCALLABLE_TYPE_KINDS:
+ return False
+ if is_contract_method(
+ sym_name,
+ node_data.get("kind"),
+ node_data.get("language", "unknown"),
+ modifiers=node_data.get("modifiers"),
+ ):
+ return False
+ if self.ctx._name_matches_dynamic(sym_name, dynamic_patterns):
+ return False
+
+ # A private ``@PostConstruct`` or ``@Scheduled`` method is called by
+ # the container, as in the export pass.
+ decorators = node_data.get("decorators") or []
+ meta = self.ctx._framework_meta_annotations(node_data.get("file_path", ""))
+ return not (
+ _is_framework_registered(decorators, meta) or _declared_deliberately_unused(decorators)
+ )
diff --git a/tests/unit/dead_code/test_no_threshold_literals.py b/tests/unit/dead_code/test_no_threshold_literals.py
index 94563515f..58ad7bb68 100644
--- a/tests/unit/dead_code/test_no_threshold_literals.py
+++ b/tests/unit/dead_code/test_no_threshold_literals.py
@@ -47,7 +47,9 @@ _PACKAGES = pathlib.Path(__file__).resolve().parents[3] / "packages"
#: Modules that decide, cap, or bucket by the dead-code confidence tiers.
_GUARDED = [
"core/src/repowise/core/analysis/dead_code/analyzer.py",
+ "core/src/repowise/core/analysis/dead_code/passes/unreachable_files.py",
"core/src/repowise/core/analysis/dead_code/passes/unused_exports.py",
+ "core/src/repowise/core/analysis/dead_code/passes/unused_internals.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",