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 zombie-package pass and split the guarded-render scan (#4053)

Raghav Chamadiya2dd3e4f8e538
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 2bda4ec01..0ae4e2314 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -11,21 +11,17 @@ source-scan rules live in sibling modules under this package.
from __future__ import annotations
-import contextlib
import fnmatch
-import os
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
from collections.abc import Set as AbstractSet
-from datetime import UTC, datetime
+from datetime import datetime
from pathlib import Path
from typing import Any
import structlog
-from ...code_origin import code_origin, is_build_file
-from ...entry_candidacy import is_reachability_root
+from ...code_origin import code_origin
from ...ingestion.models import REACHABILITY_USE_EDGE_TYPES
-from ...ingestion.package_roots import package_manifest_names
from ...ingestion.symbol_identity import base_symbol_id, overload_sets
from .c_name_uses import (
DEFINITION_HEADER_LINES,
@@ -33,12 +29,8 @@ from .c_name_uses import (
drop_preprocessed_named_elsewhere,
)
from .constants import (
- _DEAD_CODE_EXEMPT_LANGUAGES,
_DEFAULT_DYNAMIC_PATTERNS,
- _NEVER_PACKAGE_DIRS,
_PREPROCESSED_LANGUAGES,
- _PROJECT_FILE_SUFFIXES,
- _RUN_NOT_IMPORTED_LANGUAGES,
never_flag_path,
)
from .csharp_reachability import (
@@ -64,17 +56,14 @@ from .dynamic_markers import (
)
from .entry_shape import (
clamp_entry_shaped,
- defines_main_function,
drop_program_entries,
- is_program,
)
from .file_reachability import (
- _NON_DEPENDENCY_EDGES,
PackageFileMap,
ReachabilityRescues,
build_package_file_map,
)
-from .finding_helpers import (
+from .finding_helpers import ( # noqa: F401 (moved helpers re-exported)
_LINES_UNKNOWN,
_csharp_exports,
_is_synthetic_node,
@@ -82,7 +71,6 @@ from .finding_helpers import (
_symbol_span,
)
from .go_name_uses import drop_go_package_uses
-from .jvm_reachability import defines_main
from .kotlin_multiplatform import settle_platform_declarations
from .meta_annotations import MetaAnnotations
from .models import DeadCodeFindingData, DeadCodeKind, DeadCodeReport
@@ -101,10 +89,10 @@ from .name_occurrences import (
from .passes.unreachable_files import UnreachableFilePass
from .passes.unused_exports import UnusedExportPass
from .passes.unused_internals import UnusedInternalPass
+from .passes.zombie_packages import ZombiePackagePass
from .published_api import BuildFacts, demote_published_api
from .risk_factors import (
RISK_CAP_CONFIDENCE,
- path_risk_factors,
)
from .source_prepasses import ( # noqa: F401 (moved scans re-exported)
_BUNDLER_CONFIG_STEMS,
@@ -310,33 +298,50 @@ class DeadCodeAnalyzer:
advance per-stage progress; safe to pass ``None``.
"""
cfg = config or {}
- findings: list[DeadCodeFindingData] = []
-
dynamic_patterns = cfg.get("dynamic_patterns", _DEFAULT_DYNAMIC_PATTERNS)
# Machine output known only by its content (a webpack chunk, a minified
# bundle) joins the whitelist, which every pass already honours.
whitelist = set(cfg.get("whitelist", [])) | self._content_machine_output()
- if cfg.get("detect_unreachable_files", True):
- findings.extend(self._detect_unreachable_files(whitelist))
- if on_step:
- on_step("unreachable_files")
+ findings = self._run_passes(cfg, dynamic_patterns, whitelist, on_step)
+ findings = self._settle(findings)
- if cfg.get("detect_unused_exports", True):
- findings.extend(self._detect_unused_exports(dynamic_patterns, whitelist))
- if on_step:
- on_step("unused_exports")
+ min_conf = cfg.get("min_confidence", RISK_CAP_CONFIDENCE)
+ hidden_below_threshold = sum(1 for f in findings if f.confidence < min_conf)
+ findings = [f for f in findings if f.confidence >= min_conf]
- if cfg.get("detect_unused_internals", True):
- findings.extend(self._detect_unused_internals(dynamic_patterns, whitelist))
- if on_step:
- on_step("unused_internals")
+ return DeadCodeReport.from_findings(
+ findings, hidden_below_threshold=hidden_below_threshold
+ )
- if cfg.get("detect_zombie_packages", True):
- findings.extend(self._detect_zombie_packages(whitelist))
- if on_step:
- on_step("zombie_packages")
+ def _run_passes(
+ self,
+ cfg: dict,
+ dynamic_patterns: tuple[str, ...],
+ whitelist: set[str],
+ on_step: Any | None,
+ ) -> list[DeadCodeFindingData]:
+ """Run each enabled detection pass in order, reporting each stage to *on_step*."""
+ passes: tuple[tuple[str, str, Callable[[], list[DeadCodeFindingData]]], ...] = (
+ ("detect_unreachable_files", "unreachable_files",
+ lambda: self._detect_unreachable_files(whitelist)),
+ ("detect_unused_exports", "unused_exports",
+ lambda: self._detect_unused_exports(dynamic_patterns, whitelist)),
+ ("detect_unused_internals", "unused_internals",
+ lambda: self._detect_unused_internals(dynamic_patterns, whitelist)),
+ ("detect_zombie_packages", "zombie_packages",
+ lambda: self._detect_zombie_packages(whitelist)),
+ )
+ findings: list[DeadCodeFindingData] = []
+ for flag, stage, run in passes:
+ if cfg.get(flag, True):
+ findings.extend(run())
+ if on_step:
+ on_step(stage)
+ return findings
+ def _settle(self, findings: list[DeadCodeFindingData]) -> list[DeadCodeFindingData]:
+ """Drop, demote and clamp the pass findings on evidence the graph does not carry."""
# First: a C# type another file in its scope names is used, and a
# C/C++ name written outside its declaration is a use. Both settle the
# finding before any clamp re-scores it.
@@ -357,9 +362,8 @@ class DeadCodeAnalyzer:
# Before the name search: an ``expect``'s own ``actual`` files write its
# name, which that search would read as a use elsewhere.
findings = settle_platform_declarations(findings, self._source_map)
- # Same position and for the same reason. This one asks the wider
- # version of the same question — not "could an unread file explain
- # this" but "did we look anywhere except the import graph".
+ # Same position and reason, asking the wider question: did we look
+ # anywhere except the import graph.
findings = drop_bare_name_uses(findings, self._source_map)
# Before the clamp, which would otherwise read a same-file use as
# "named elsewhere" and leave the row in the default view.
@@ -382,15 +386,11 @@ class DeadCodeAnalyzer:
BuildFacts(repo_root=self._repo_root, dotnet_index=self._dotnet_index),
)
- findings = apply_deletion_gate(findings, self.graph, self._repo_root)
+ return apply_deletion_gate(findings, self.graph, self._repo_root)
- min_conf = cfg.get("min_confidence", RISK_CAP_CONFIDENCE)
- hidden_below_threshold = sum(1 for f in findings if f.confidence < min_conf)
- findings = [f for f in findings if f.confidence >= min_conf]
-
- return DeadCodeReport.from_findings(
- findings, hidden_below_threshold=hidden_below_threshold
- )
+ def _detect_zombie_packages(self, whitelist: set[str]) -> list[DeadCodeFindingData]:
+ """Detect monorepo packages with no incoming inter_package edges."""
+ return ZombiePackagePass(self).run(whitelist)
def _drop_csharp_named_exports(
self, findings: list[DeadCodeFindingData]
@@ -739,175 +739,6 @@ class DeadCodeAnalyzer:
and pred_span["end_line"] <= node_span["end_line"]
)
- def _detect_zombie_packages(self, whitelist: set[str]) -> list[DeadCodeFindingData]:
- """Detect monorepo packages with no incoming inter_package edges.
-
- ``framework:`` predecessors (synthetic anchors added by
- ``framework_edges``) count as cross-package importers — TYPO3 / Django
- / etc. wiring is a real cross-cutting dependency. ``external:``
- predecessors do not count (they represent third-party imports).
- """
- findings = []
-
- packages: dict[str, list[str]] = {}
- for node in self.graph.nodes():
- if _is_synthetic_node(str(node)):
- continue
- parts = Path(str(node)).parts
- if len(parts) > 1:
- pkg = parts[0]
- packages.setdefault(pkg, []).append(str(node))
-
- if len(packages) < 2:
- return findings
-
- for pkg, files in packages.items():
- if not self._is_package_candidate(pkg, files, whitelist):
- continue
- if self._has_cross_package_importer(pkg, files):
- continue
-
- # A package total is only as known as its least-known file.
- counts = [
- self._file_line_count(f)
- for f in files
- if self.graph.nodes[f].get("node_type") != "symbol"
- ]
- known = [c for c in counts if c is not None]
- total_lines = sum(known) if len(known) == len(counts) else None
- evidence = [f"No inter-package imports into '{pkg}'"]
- if total_lines is None:
- evidence.append(_LINES_UNKNOWN)
- activity = self._package_git_activity(files)
- findings.append(
- DeadCodeFindingData(
- kind=DeadCodeKind.ZOMBIE_PACKAGE,
- file_path=pkg,
- symbol_name=None,
- symbol_kind=None,
- confidence=0.5,
- reason=f"Package '{pkg}' has no importers from other packages",
- lines=total_lines,
- evidence=evidence,
- safe_to_delete=False,
- risk_factors=list(path_risk_factors(pkg)),
- **activity,
- )
- )
-
- return findings
-
- def _is_package_candidate(self, pkg: str, files: list[str], whitelist: set[str]) -> bool:
- """Whether a top-level directory is a code package the zombie pass may judge."""
- if pkg in whitelist:
- return False
- # Skip known non-package dirs (.github, .vscode, docs, ...)
- # and any other dotfile directory at the repo root.
- if pkg in _NEVER_PACKAGE_DIRS or pkg.startswith("."):
- return False
- # A folder is a package only when it declares itself one: a Next.js
- # ``app/``, a ``benchmarks/`` folder or a Go ``cmd/`` has no manifest
- # and nothing is meant to import it.
- if not self._has_package_manifest(pkg, files):
- return False
- # Tests are run, never imported, and so is a package that ships a
- # program: a CLI started by its shebang, a JVM ``main``, or a root
- # with a top-level ``main`` (Dart ``lib/main.dart``). A root alone is
- # not enough: a Rust ``lib.rs`` is a root and the library's surface.
- # One program file is enough, even a stray script: this errs toward
- # not calling a package dead. A build-run source set (``is_never_flag``)
- # counts as a test. Files only: a test file's symbols carry no test flag.
- files = [
- f
- for f in files
- if (nd := self.graph.nodes.get(f, {})).get("node_type") != "symbol"
- and not nd.get("is_test")
- and not nd.get("is_never_flag")
- ]
- if any(
- is_program(f, self._source_map.get(f, b""))
- or defines_main(self.graph, f)
- or (
- is_reachability_root(self.graph.nodes[f])
- and defines_main_function(self.graph, f)
- )
- for f in files
- ):
- return False
- # A real package contains at least one source file something could
- # import. Config and data (YAML, JSON, MD, TOML) is metadata, and a
- # folder of Dockerfiles, shell scripts and build files is run, never
- # imported.
- return any(
- self.graph.nodes.get(f, {}).get("language", "unknown")
- not in _DEAD_CODE_EXEMPT_LANGUAGES | _RUN_NOT_IMPORTED_LANGUAGES
- and not is_build_file(f)
- for f in files
- )
-
- def _has_package_manifest(self, pkg: str, files: list[str]) -> bool:
- """Whether *pkg* holds a package manifest of its own, on disk or indexed.
-
- A top-level folder whose manifest sits at the repository root (a
- Python package built by the root ``pyproject.toml``) is the repository
- itself, not a package of it, so it is never a candidate.
- """
- names = {f.partition("/")[2] for f in files if f.count("/") == 1}
- if self._repo_root is not None:
- with contextlib.suppress(OSError):
- names.update(os.listdir(Path(self._repo_root) / pkg))
- manifests = package_manifest_names()
- return any(n in manifests or n.endswith(_PROJECT_FILE_SUFFIXES) for n in names)
-
- def _has_cross_package_importer(self, pkg: str, files: list[str]) -> bool:
- """Whether anything outside *pkg* depends on a file inside it."""
- for f in files:
- for pred, _f, edge_data in self.graph.in_edges(f, data=True):
- # Committed together is history, not a dependency.
- if edge_data.get("edge_type") in _NON_DEPENDENCY_EDGES:
- continue
- pred_str = str(pred)
- if pred_str.startswith("external:"):
- # Third-party imports don't count as cross-package
- # importers; framework: synthetic anchors do.
- continue
- pred_parts = Path(pred_str).parts
- if len(pred_parts) > 0 and pred_parts[0] != pkg:
- return True
- return False
-
- def _package_git_activity(self, files: list[str]) -> dict[str, Any]:
- """Latest commit, 90-day commits, most common owner and age across *files*."""
- pkg_last_commit: datetime | None = None
- pkg_total_commits_90d = 0
- pkg_owner: str | None = None
- owner_counts: dict[str, int] = {}
- for f in files:
- # git_meta_map values are plain dicts (see pipeline/phases/analysis.py);
- # use .get() not getattr() — getattr on a dict never finds arbitrary
- # string keys and always returns the default, silently zeroing all
- # git-activity metadata on zombie-package findings.
- gm = self.git_meta_map.get(f)
- if gm is None:
- continue
- f_last = gm.get("last_commit_at")
- if f_last and (pkg_last_commit is None or f_last > pkg_last_commit):
- pkg_last_commit = f_last
- pkg_total_commits_90d += gm.get("commit_count_90d", 0) or 0
- f_owner = gm.get("primary_owner_name")
- if f_owner:
- owner_counts[f_owner] = owner_counts.get(f_owner, 0) + 1
- if owner_counts:
- pkg_owner = max(owner_counts, key=lambda k: owner_counts[k])
- pkg_age_days: int | None = None
- if pkg_last_commit:
- pkg_age_days = (datetime.now(UTC) - pkg_last_commit).days
- return {
- "last_commit_at": pkg_last_commit,
- "commit_count_90d": pkg_total_commits_90d,
- "primary_owner": pkg_owner,
- "age_days": pkg_age_days,
- }
# ------------------------------------------------------------------
# Helpers
diff --git a/packages/core/src/repowise/core/analysis/dead_code/jsx_prop_guards.py b/packages/core/src/repowise/core/analysis/dead_code/jsx_prop_guards.py
index beace9cce..e2a674fde 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/jsx_prop_guards.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/jsx_prop_guards.py
@@ -9,6 +9,22 @@ from tree_sitter import Language, Parser
from ...ingestion.models import REACHABILITY_USE_EDGE_TYPES
+_FUNCTION_NODES = ("function_declaration", "arrow_function", "function_expression", "method_definition")
+_BINDING_CONTAINERS = (
+ "array_pattern",
+ "object_pattern",
+ "pair_pattern",
+ "variable_declarator",
+ "rest_pattern",
+ "formal_parameters",
+ "parameters",
+ "required_parameter",
+ "optional_parameter",
+ "assignment_pattern",
+)
+_BINDING_PUNCTUATION = (":", "=", ",", "[", "]", "{", "}", "...", "var", "let", "const")
+_FALSY_LITERALS = ("undefined", "null", "false")
+
def extract_guarded_jsx_renders(
file_path: str,
@@ -37,310 +53,355 @@ def extract_guarded_jsx_renders(
except Exception:
return []
- code = src.encode("utf-8")
- results: list[tuple[str, str, str]] = []
+ scan = _GuardScan(src.encode("utf-8"))
+ scan.module_vars = scan.module_local_vars(tree.root_node)
+ scan.walk(tree.root_node)
+ return scan.results
+
+
+class _GuardScan:
+ """One file's guarded-render scan: source bytes, module-level names, results."""
+
+ def __init__(self, code: bytes) -> None:
+ self.code = code
+ self.module_vars: set[str] = set()
+ self.results: list[tuple[str, str, str]] = []
- def _node_text(n: Any) -> str:
- return code[n.start_byte : n.end_byte].decode("utf-8", errors="replace")
+ def text(self, n: Any) -> str:
+ return self.code[n.start_byte : n.end_byte].decode("utf-8", errors="replace")
- def _extract_prop_names(
+ # -- guard conditions ---------------------------------------------------
+
+ def prop_names(
+ self,
n: Any,
local_vars: set[str] | None = None,
param_props: set[str] | None = None,
) -> list[str]:
+ """Prop names a guard condition *n* tests, or ``[]`` when it tests none."""
if n.type == "parenthesized_expression":
for c in n.children:
if c.type not in ("(", ")"):
- return _extract_prop_names(c, local_vars, param_props)
+ return self.prop_names(c, local_vars, param_props)
elif n.type == "member_expression":
- obj_node = n.children[0]
- obj_text = _node_text(obj_node)
- prop_text = None
- for c in n.children:
- if c.type == "property_identifier":
- prop_text = _node_text(c)
- if (
- obj_text in ("props", "this.props", "self.props") or obj_text.endswith(".props")
- ) and prop_text:
- return [prop_text]
+ return self._member_prop(n)
elif n.type == "identifier":
- name = _node_text(n)
- if name in ("true", "false", "undefined", "null"):
- return []
- if local_vars is not None and name in local_vars:
- return []
- if param_props is not None:
- return [name] if name in param_props else []
- return [name]
+ return self._identifier_prop(n, local_vars, param_props)
elif n.type == "unary_expression":
- op = None
- operand = None
- for c in n.children:
- if c.type == "!":
- op = "!"
- else:
- operand = c
- if op == "!":
- if operand and operand.type == "unary_expression":
- sub_op = None
- sub_operand = None
- for sub in operand.children:
- if sub.type == "!":
- sub_op = "!"
- else:
- sub_operand = sub
- if sub_op == "!" and sub_operand:
- return _extract_prop_names(sub_operand, local_vars, param_props)
- return []
+ return self._double_negated_props(n, local_vars, param_props)
elif n.type == "binary_expression":
- op = None
- left = None
- right = None
- for c in n.children:
- if c.type in ("&&", "===", "==", "!==", "!="):
- op = c.type
- elif left is None:
- left = c
- else:
- right = c
- if op in ("&&", "===", "==") and left and right:
- return _extract_prop_names(left, local_vars, param_props) + _extract_prop_names(
- right, local_vars, param_props
- )
- elif op in ("!==", "!=") and left and right:
- right_text = _node_text(right)
- left_text = _node_text(left)
- if right_text in ("undefined", "null", "false"):
- return _extract_prop_names(left, local_vars, param_props)
- elif left_text in ("undefined", "null", "false"):
- return _extract_prop_names(right, local_vars, param_props)
+ return self._comparison_props(n, local_vars, param_props)
return []
- def _find_jsx_targets(n: Any) -> list[str]:
- targets: list[str] = []
- if n.type in ("jsx_self_closing_element", "jsx_opening_element", "jsx_element"):
- if n.type == "jsx_element":
- for c in n.children:
- if c.type == "jsx_opening_element":
- targets.extend(_find_jsx_targets(c))
+ def _member_prop(self, n: Any) -> list[str]:
+ obj_text = self.text(n.children[0])
+ prop_text = None
+ for c in n.children:
+ if c.type == "property_identifier":
+ prop_text = self.text(c)
+ if (
+ obj_text in ("props", "this.props", "self.props") or obj_text.endswith(".props")
+ ) and prop_text:
+ return [prop_text]
+ return []
+
+ def _identifier_prop(
+ self, n: Any, local_vars: set[str] | None, param_props: set[str] | None
+ ) -> list[str]:
+ name = self.text(n)
+ if name in ("true", "false", "undefined", "null"):
+ return []
+ if local_vars is not None and name in local_vars:
+ return []
+ if param_props is not None:
+ return [name] if name in param_props else []
+ return [name]
+
+ def _double_negated_props(
+ self, n: Any, local_vars: set[str] | None, param_props: set[str] | None
+ ) -> list[str]:
+ """``!!x`` reads as ``x``; any other unary guard tests no prop."""
+ negated, operand = _negation(n)
+ if not negated:
+ return []
+ if operand and operand.type == "unary_expression":
+ inner_negated, inner = _negation(operand)
+ if inner_negated and inner:
+ return self.prop_names(inner, local_vars, param_props)
+ return []
+
+ def _comparison_props(
+ self, n: Any, local_vars: set[str] | None, param_props: set[str] | None
+ ) -> list[str]:
+ op = None
+ left = None
+ right = None
+ for c in n.children:
+ if c.type in ("&&", "===", "==", "!==", "!="):
+ op = c.type
+ elif left is None:
+ left = c
else:
- for c in n.children:
- if c.type in ("identifier", "property_identifier"):
- name = _node_text(c)
- if name and name[0].isupper():
- targets.append(name)
- break
- elif c.type == "member_expression":
- prop_name = None
- for sub in c.children:
- if sub.type == "property_identifier":
- prop_name = _node_text(sub)
- if prop_name and prop_name[0].isupper():
- targets.append(prop_name)
- break
- else:
+ right = c
+ if not (left and right):
+ return []
+ if op in ("&&", "===", "=="):
+ return self.prop_names(left, local_vars, param_props) + self.prop_names(
+ right, local_vars, param_props
+ )
+ if op in ("!==", "!="):
+ if self.text(right) in _FALSY_LITERALS:
+ return self.prop_names(left, local_vars, param_props)
+ if self.text(left) in _FALSY_LITERALS:
+ return self.prop_names(right, local_vars, param_props)
+ return []
+
+ # -- guarded components -------------------------------------------------
+
+ def jsx_targets(self, n: Any) -> list[str]:
+ """Capitalised component names rendered by JSX elements under *n*."""
+ if n.type == "jsx_element":
+ targets: list[str] = []
for c in n.children:
- targets.extend(_find_jsx_targets(c))
+ if c.type == "jsx_opening_element":
+ targets.extend(self.jsx_targets(c))
+ return targets
+ if n.type in ("jsx_self_closing_element", "jsx_opening_element"):
+ name = self._element_component(n)
+ return [name] if name else []
+ targets = []
+ for c in n.children:
+ targets.extend(self.jsx_targets(c))
return targets
- def _extract_bound_names(n: Any) -> list[str]:
- names: list[str] = []
+ def _element_component(self, n: Any) -> str | None:
+ """The first capitalised tag name of an opening or self-closing element."""
+ for c in n.children:
+ if c.type in ("identifier", "property_identifier"):
+ name = self.text(c)
+ elif c.type == "member_expression":
+ name = self._last_property(c)
+ else:
+ continue
+ if name and name[0].isupper():
+ return name
+ return None
+
+ def _last_property(self, member: Any) -> str | None:
+ prop_name = None
+ for sub in member.children:
+ if sub.type == "property_identifier":
+ prop_name = self.text(sub)
+ return prop_name
+
+ # -- bindings -----------------------------------------------------------
+
+ def bound_names(self, n: Any) -> list[str]:
+ """Every name a declaration or parameter pattern binds."""
if n.type in ("identifier", "shorthand_property_identifier_pattern"):
- names.append(_node_text(n))
- elif n.type in (
- "array_pattern",
- "object_pattern",
- "pair_pattern",
- "variable_declarator",
- "rest_pattern",
- "formal_parameters",
- "parameters",
- "required_parameter",
- "optional_parameter",
- "assignment_pattern",
- ):
+ return [self.text(n)]
+ names: list[str] = []
+ if n.type in _BINDING_CONTAINERS:
for c in n.children:
- if c.type not in (":", "=", ",", "[", "]", "{", "}", "...", "var", "let", "const"):
- names.extend(_extract_bound_names(c))
+ if c.type not in _BINDING_PUNCTUATION:
+ names.extend(self.bound_names(c))
return names
- def _collect_module_local_vars(root: Any) -> set[str]:
+ def _declarator_names(self, declarator: Any) -> list[str]:
+ for c in declarator.children:
+ if c.type in ("identifier", "array_pattern", "object_pattern"):
+ return self.bound_names(c)
+ return []
+
+ def module_local_vars(self, root: Any) -> set[str]:
+ """Names declared at module level, exported or not."""
mod_vars: set[str] = set()
for child in root.children:
- target_node = child
- if child.type == "export_statement":
- for c in child.children:
- if c.type in ("lexical_declaration", "variable_declaration"):
- target_node = c
- break
+ target_node = _exported_declaration(child)
if target_node.type in ("lexical_declaration", "variable_declaration"):
- for dec in target_node.children:
- if dec.type == "variable_declarator":
- for c in dec.children:
- if c.type in ("identifier", "array_pattern", "object_pattern"):
- mod_vars.update(_extract_bound_names(c))
- break
+ mod_vars.update(self._declaration_names(target_node))
return mod_vars
- module_vars = _collect_module_local_vars(tree.root_node)
+ def _declaration_names(self, declaration: Any) -> list[str]:
+ names: list[str] = []
+ for dec in declaration.children:
+ if dec.type == "variable_declarator":
+ names.extend(self._declarator_names(dec))
+ return names
- def _collect_function_param_props(fn_node: Any) -> set[str] | None:
- params_node = None
- for c in fn_node.children:
- if c.type in ("formal_parameters", "parameters"):
- params_node = c
- break
+ def function_param_props(self, fn_node: Any) -> set[str] | None:
+ """Names destructured from a function's parameters, or ``None`` if none is destructured."""
+ params_node = next(
+ (c for c in fn_node.children if c.type in ("formal_parameters", "parameters")), None
+ )
if not params_node:
return None
-
param_props: set[str] = set()
has_destructured_param = False
-
for param in params_node.children:
if param.type in ("(", ")", ",", ":"):
continue
- p = param
- if p.type == "required_parameter":
- for child in p.children:
- if child.type in ("object_pattern", "identifier", "assignment_pattern"):
- p = child
- break
- if p.type == "assignment_pattern":
- for child in p.children:
- if child.type in ("object_pattern", "identifier"):
- p = child
- break
-
+ p = _unwrap_param(param)
if p.type == "object_pattern":
has_destructured_param = True
- param_props.update(_extract_bound_names(p))
-
+ param_props.update(self.bound_names(p))
return param_props if has_destructured_param else None
- def _collect_function_param_names(fn_node: Any) -> set[str]:
+ def function_param_names(self, fn_node: Any) -> set[str]:
for c in fn_node.children:
if c.type in ("formal_parameters", "parameters"):
- return set(_extract_bound_names(c))
+ return set(self.bound_names(c))
single_param = fn_node.child_by_field_name("parameter")
if single_param is not None:
- return set(_extract_bound_names(single_param))
+ return set(self.bound_names(single_param))
return set()
- def _collect_function_local_vars(
- fn_node: Any, inherited_vars: set[str] | None = None
- ) -> set[str]:
- # A nested callback closes over the variables in its enclosing
- # component. Keep those names in scope while adding declarations from
- # the callback itself; otherwise ``show && <Child />`` inside a
- # callback is mistaken for a prop guard even when ``show`` is local
- # state in the component.
- local_vars: set[str] = set(module_vars)
+ def function_local_vars(self, fn_node: Any, inherited_vars: set[str] | None = None) -> set[str]:
+ """Module names, *inherited_vars* and the function's own declarations.
+
+ A nested callback keeps its component's locals in scope, so
+ ``show && <Child />`` on component state is not read as a prop guard.
+ """
+ local_vars: set[str] = set(self.module_vars)
if inherited_vars:
local_vars.update(inherited_vars)
+ self._scan_declarations(fn_node, fn_node, local_vars)
+ return local_vars
- def _scan(n: Any) -> None:
- if n != fn_node and n.type in (
- "function_declaration",
- "arrow_function",
- "function_expression",
- "method_definition",
- ):
- return
- if n.type == "variable_declarator":
- for c in n.children:
- if c.type in ("identifier", "array_pattern", "object_pattern"):
- local_vars.update(_extract_bound_names(c))
- break
- for c in n.children:
- _scan(c)
+ def _scan_declarations(self, n: Any, fn_node: Any, local_vars: set[str]) -> None:
+ if n != fn_node and n.type in _FUNCTION_NODES:
+ return
+ if n.type == "variable_declarator":
+ local_vars.update(self._declarator_names(n))
+ for c in n.children:
+ self._scan_declarations(c, fn_node, local_vars)
- _scan(fn_node)
- return local_vars
+ # -- walk ---------------------------------------------------------------
- def _walk(
+ def walk(
+ self,
n: Any,
current_fn: str | None = None,
local_vars: set[str] | None = None,
param_props: set[str] | None = None,
function_depth: int = 0,
) -> None:
- current_local_vars = local_vars
- current_param_props = param_props
- if n.type in (
- "function_declaration",
- "arrow_function",
- "function_expression",
- "method_definition",
- ):
- fn_name = current_fn
- if n.type in ("function_declaration", "method_definition"):
- for c in n.children:
- if c.type in ("identifier", "property_identifier"):
- fn_name = _node_text(c)
- break
- elif n.parent and n.parent.type == "variable_declarator":
- for c in n.parent.children:
- if c.type == "identifier":
- fn_name = _node_text(c)
- break
- current_fn = fn_name or "Anonymous"
- current_local_vars = _collect_function_local_vars(n, local_vars)
- current_param_props = set(param_props or ())
- current_param_props.update(_collect_function_param_props(n) or ())
- if function_depth > 0:
- # A callback parameter can shadow an outer destructured prop.
- # Treat only the callback's own bindings as locals; the outer
- # component's destructured props remain eligible guards.
- current_local_vars.update(_collect_function_param_names(n))
+ if n.type in _FUNCTION_NODES:
+ current_fn = self._function_name(n, current_fn)
+ local_vars, param_props = self._function_scope(n, local_vars, param_props, function_depth)
function_depth += 1
-
if n.type == "binary_expression":
- op = None
- left = None
- right = None
- for c in n.children:
- if c.type == "&&":
- op = "&&"
- elif left is None:
- left = c
- else:
- right = c
- if op == "&&" and left and right:
- jsx_targets = _find_jsx_targets(right)
- if jsx_targets and current_fn:
- prop_names = _extract_prop_names(left, current_local_vars, current_param_props)
- for prop_name in prop_names:
- for target in jsx_targets:
- results.append((current_fn, target, prop_name))
-
+ self._record_and_guard(n, current_fn, local_vars, param_props)
elif n.type == "ternary_expression":
- cond = None
- consequence = None
- for c in n.children:
- if c.type not in ("?", ":"):
- if cond is None:
- cond = c
- elif consequence is None:
- consequence = c
- if cond and consequence and current_fn:
- jsx_targets = _find_jsx_targets(consequence)
- if jsx_targets:
- prop_names = _extract_prop_names(cond, current_local_vars, current_param_props)
- for prop_name in prop_names:
- for target in jsx_targets:
- results.append((current_fn, target, prop_name))
-
+ self._record_ternary_guard(n, current_fn, local_vars, param_props)
for child in n.children:
- _walk(
- child,
- current_fn,
- current_local_vars,
- current_param_props,
- function_depth,
- )
+ self.walk(child, current_fn, local_vars, param_props, function_depth)
- _walk(tree.root_node)
- return results
+ def _function_name(self, n: Any, current_fn: str | None) -> str:
+ fn_name = current_fn
+ if n.type in ("function_declaration", "method_definition"):
+ for c in n.children:
+ if c.type in ("identifier", "property_identifier"):
+ fn_name = self.text(c)
+ break
+ elif n.parent and n.parent.type == "variable_declarator":
+ for c in n.parent.children:
+ if c.type == "identifier":
+ fn_name = self.text(c)
+ break
+ return fn_name or "Anonymous"
+
+ def _function_scope(
+ self,
+ n: Any,
+ local_vars: set[str] | None,
+ param_props: set[str] | None,
+ function_depth: int,
+ ) -> tuple[set[str], set[str]]:
+ scope_vars = self.function_local_vars(n, local_vars)
+ scope_props = set(param_props or ())
+ scope_props.update(self.function_param_props(n) or ())
+ if function_depth > 0:
+ # A callback's own parameters shadow outer names; the component's
+ # destructured props stay eligible guards.
+ scope_vars.update(self.function_param_names(n))
+ return scope_vars, scope_props
+
+ def _record_and_guard(
+ self, n: Any, current_fn: str | None, local_vars: set[str] | None, param_props: set[str] | None
+ ) -> None:
+ op = None
+ left = None
+ right = None
+ for c in n.children:
+ if c.type == "&&":
+ op = "&&"
+ elif left is None:
+ left = c
+ else:
+ right = c
+ if op == "&&" and left and right:
+ jsx_targets = self.jsx_targets(right)
+ if jsx_targets and current_fn:
+ self._record(current_fn, jsx_targets, self.prop_names(left, local_vars, param_props))
+
+ def _record_ternary_guard(
+ self, n: Any, current_fn: str | None, local_vars: set[str] | None, param_props: set[str] | None
+ ) -> None:
+ cond = None
+ consequence = None
+ for c in n.children:
+ if c.type not in ("?", ":"):
+ if cond is None:
+ cond = c
+ elif consequence is None:
+ consequence = c
+ if cond and consequence and current_fn:
+ jsx_targets = self.jsx_targets(consequence)
+ if jsx_targets:
+ self._record(current_fn, jsx_targets, self.prop_names(cond, local_vars, param_props))
+
+ def _record(self, current_fn: str, jsx_targets: list[str], prop_names: list[str]) -> None:
+ for prop_name in prop_names:
+ for target in jsx_targets:
+ self.results.append((current_fn, target, prop_name))
+
+
+def _negation(n: Any) -> tuple[bool, Any]:
+ """Whether unary *n* is ``!`` and its operand (the last non-``!`` child)."""
+ negated = False
+ operand = None
+ for c in n.children:
+ if c.type == "!":
+ negated = True
+ else:
+ operand = c
+ return negated, operand
+
+
+def _exported_declaration(child: Any) -> Any:
+ """The declaration inside ``export const ...``, else *child* itself."""
+ if child.type == "export_statement":
+ for c in child.children:
+ if c.type in ("lexical_declaration", "variable_declaration"):
+ return c
+ return child
+
+
+def _unwrap_param(param: Any) -> Any:
+ """The pattern inside a typed or defaulted parameter."""
+ p = param
+ if p.type == "required_parameter":
+ for child in p.children:
+ if child.type in ("object_pattern", "identifier", "assignment_pattern"):
+ p = child
+ break
+ if p.type == "assignment_pattern":
+ for child in p.children:
+ if child.type in ("object_pattern", "identifier"):
+ p = child
+ break
+ return p
GuardedRenders = Callable[[str], list[tuple[str, str, str]]]
diff --git a/packages/core/src/repowise/core/analysis/dead_code/passes/zombie_packages.py b/packages/core/src/repowise/core/analysis/dead_code/passes/zombie_packages.py
new file mode 100644
index 000000000..f1c287856
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/dead_code/passes/zombie_packages.py
@@ -0,0 +1,198 @@
+"""The zombie-package pass: top-level packages nothing outside them depends on."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ....code_origin import is_build_file
+from ....entry_candidacy import is_reachability_root
+from ....ingestion.package_roots import package_manifest_names
+from ..constants import (
+ _DEAD_CODE_EXEMPT_LANGUAGES,
+ _NEVER_PACKAGE_DIRS,
+ _PROJECT_FILE_SUFFIXES,
+ _RUN_NOT_IMPORTED_LANGUAGES,
+)
+from ..entry_shape import defines_main_function, is_program
+from ..file_reachability import _NON_DEPENDENCY_EDGES
+from ..finding_helpers import _LINES_UNKNOWN, _is_synthetic_node
+from ..jvm_reachability import defines_main
+from ..models import DeadCodeFindingData, DeadCodeKind
+from ..risk_factors import path_risk_factors
+
+if TYPE_CHECKING:
+ from ..analyzer import DeadCodeAnalyzer
+
+
+class ZombiePackagePass:
+ """Groups files by top-level directory and judges each package."""
+
+ def __init__(self, ctx: DeadCodeAnalyzer) -> None:
+ self.ctx = ctx
+ self.graph = ctx.graph
+
+ def run(self, whitelist: set[str]) -> list[DeadCodeFindingData]:
+ """Detect monorepo packages with no incoming inter_package edges.
+
+ A ``framework:`` anchor counts as a cross-package importer (framework
+ wiring is a real dependency); an ``external:`` third-party one does not.
+ """
+ findings = []
+
+ packages: dict[str, list[str]] = {}
+ for node in self.graph.nodes():
+ if _is_synthetic_node(str(node)):
+ continue
+ parts = Path(str(node)).parts
+ if len(parts) > 1:
+ pkg = parts[0]
+ packages.setdefault(pkg, []).append(str(node))
+
+ if len(packages) < 2:
+ return findings
+
+ for pkg, files in packages.items():
+ if not self._is_package_candidate(pkg, files, whitelist):
+ continue
+ if self._has_cross_package_importer(pkg, files):
+ continue
+
+ # A package total is only as known as its least-known file.
+ counts = [
+ self.ctx._file_line_count(f)
+ for f in files
+ if self.graph.nodes[f].get("node_type") != "symbol"
+ ]
+ known = [c for c in counts if c is not None]
+ total_lines = sum(known) if len(known) == len(counts) else None
+ evidence = [f"No inter-package imports into '{pkg}'"]
+ if total_lines is None:
+ evidence.append(_LINES_UNKNOWN)
+ activity = self._package_git_activity(files)
+ findings.append(
+ DeadCodeFindingData(
+ kind=DeadCodeKind.ZOMBIE_PACKAGE,
+ file_path=pkg,
+ symbol_name=None,
+ symbol_kind=None,
+ confidence=0.5,
+ reason=f"Package '{pkg}' has no importers from other packages",
+ lines=total_lines,
+ evidence=evidence,
+ safe_to_delete=False,
+ risk_factors=list(path_risk_factors(pkg)),
+ **activity,
+ )
+ )
+
+ return findings
+
+ def _is_package_candidate(self, pkg: str, files: list[str], whitelist: set[str]) -> bool:
+ """Whether a top-level directory is a code package the zombie pass may judge."""
+ if pkg in whitelist:
+ return False
+ # Skip known non-package dirs (.github, .vscode, docs, ...)
+ # and any other dotfile directory at the repo root.
+ if pkg in _NEVER_PACKAGE_DIRS or pkg.startswith("."):
+ return False
+ # A folder is a package only when it declares itself one: a Next.js
+ # ``app/``, a ``benchmarks/`` folder or a Go ``cmd/`` has no manifest
+ # and nothing is meant to import it.
+ if not self._has_package_manifest(pkg, files):
+ return False
+ # A package that ships a program (shebang CLI, JVM ``main``, a root
+ # with a top-level ``main``) is run, never imported; one such file is
+ # enough. A root alone is not (a Rust ``lib.rs`` is the library surface).
+ # Test files, build-run source sets and symbol nodes are left out first.
+ files = [
+ f
+ for f in files
+ if (nd := self.graph.nodes.get(f, {})).get("node_type") != "symbol"
+ and not nd.get("is_test")
+ and not nd.get("is_never_flag")
+ ]
+ if any(
+ is_program(f, self.ctx._source_map.get(f, b""))
+ or defines_main(self.graph, f)
+ or (
+ is_reachability_root(self.graph.nodes[f])
+ and defines_main_function(self.graph, f)
+ )
+ for f in files
+ ):
+ return False
+ # A real package contains at least one source file something could
+ # import. Config and data (YAML, JSON, MD, TOML) is metadata, and a
+ # folder of Dockerfiles, shell scripts and build files is run, never
+ # imported.
+ return any(
+ self.graph.nodes.get(f, {}).get("language", "unknown")
+ not in _DEAD_CODE_EXEMPT_LANGUAGES | _RUN_NOT_IMPORTED_LANGUAGES
+ and not is_build_file(f)
+ for f in files
+ )
+
+ def _has_package_manifest(self, pkg: str, files: list[str]) -> bool:
+ """Whether *pkg* holds a package manifest of its own, on disk or indexed.
+
+ A top-level folder whose manifest sits at the repository root (a
+ Python package built by the root ``pyproject.toml``) is the repository
+ itself, not a package of it, so it is never a candidate.
+ """
+ names = {f.partition("/")[2] for f in files if f.count("/") == 1}
+ if self.ctx._repo_root is not None:
+ with contextlib.suppress(OSError):
+ names.update(os.listdir(Path(self.ctx._repo_root) / pkg))
+ manifests = package_manifest_names()
+ return any(n in manifests or n.endswith(_PROJECT_FILE_SUFFIXES) for n in names)
+
+ def _has_cross_package_importer(self, pkg: str, files: list[str]) -> bool:
+ """Whether anything outside *pkg* depends on a file inside it."""
+ for f in files:
+ for pred, _f, edge_data in self.graph.in_edges(f, data=True):
+ # Committed together is history, not a dependency.
+ if edge_data.get("edge_type") in _NON_DEPENDENCY_EDGES:
+ continue
+ pred_str = str(pred)
+ if pred_str.startswith("external:"):
+ # Third-party imports don't count as cross-package
+ # importers; framework: synthetic anchors do.
+ continue
+ pred_parts = Path(pred_str).parts
+ if len(pred_parts) > 0 and pred_parts[0] != pkg:
+ return True
+ return False
+
+ def _package_git_activity(self, files: list[str]) -> dict[str, Any]:
+ """Latest commit, 90-day commits, most common owner and age across *files*."""
+ pkg_last_commit: datetime | None = None
+ pkg_total_commits_90d = 0
+ pkg_owner: str | None = None
+ owner_counts: dict[str, int] = {}
+ for f in files:
+ # git_meta_map values are plain dicts: read them with .get().
+ gm = self.ctx.git_meta_map.get(f)
+ if gm is None:
+ continue
+ f_last = gm.get("last_commit_at")
+ if f_last and (pkg_last_commit is None or f_last > pkg_last_commit):
+ pkg_last_commit = f_last
+ pkg_total_commits_90d += gm.get("commit_count_90d", 0) or 0
+ f_owner = gm.get("primary_owner_name")
+ if f_owner:
+ owner_counts[f_owner] = owner_counts.get(f_owner, 0) + 1
+ if owner_counts:
+ pkg_owner = max(owner_counts, key=lambda k: owner_counts[k])
+ pkg_age_days: int | None = None
+ if pkg_last_commit:
+ pkg_age_days = (datetime.now(UTC) - pkg_last_commit).days
+ return {
+ "last_commit_at": pkg_last_commit,
+ "commit_count_90d": pkg_total_commits_90d,
+ "primary_owner": pkg_owner,
+ "age_days": pkg_age_days,
+ }
diff --git a/tests/unit/dead_code/test_no_threshold_literals.py b/tests/unit/dead_code/test_no_threshold_literals.py
index 58ad7bb68..69c056085 100644
--- a/tests/unit/dead_code/test_no_threshold_literals.py
+++ b/tests/unit/dead_code/test_no_threshold_literals.py
@@ -50,6 +50,7 @@ _GUARDED = [
"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/passes/zombie_packages.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",