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.

feat(dead-code): workspace-driven never-flag + heritage-edge symbol rescue (#281)

Raghav Chamadiya34a834d44195
diff --git a/docs/LANGUAGE_SUPPORT.md b/docs/LANGUAGE_SUPPORT.md
index f11b41d52..aea47ef69 100644
--- a/docs/LANGUAGE_SUPPORT.md
+++ b/docs/LANGUAGE_SUPPORT.md
@@ -325,6 +325,22 @@ without touching the shared pipeline files:
visibility refinement for languages where access is dictated by AST
context (C/C++ access specifiers, storage class, export attributes)
rather than modifier text alone.
+- `graph_warmups.py` `is_never_flag` stamping --- read the language's
+ build manifest during warmup and set `is_never_flag=True` on file
+ nodes the manifest declares as a non-primary / secondary target.
+ The dead-code analyzer consults this attribute in `_should_never_flag`,
+ so each repo's own build files teach the analyzer what to ignore
+ without extending the hardcoded glob list. Used today by `_warmup_jvm`
+ to exempt every file under a Gradle non-`main` source set
+ (`testFixtures`, `integrationTest`, `javaPoet`, `jcstress`, `jmh`,
+ custom names) — Caffeine's `javaPoet/` and `jcstress/` are picked up
+ automatically without us knowing the names exist. The same shape fits
+ Rust (`[[example]]` / `[[bench]]` / `[[bin]]` targets in `Cargo.toml`),
+ C# (projects with `<Sdk>Microsoft.NET.Sdk.Test</Sdk>` or
+ `Microsoft.NET.Test.Sdk` references), TS/JS (workspace `packages/*`
+ declared `"private": true`), and Go (`//go:build integration`-gated
+ files) — any language that already builds a workspace index can opt
+ in by stamping the attribute during its warmup.
---
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 0c26a2a75..1ed574323 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -775,15 +775,21 @@ class DeadCodeAnalyzer:
continue
# Symbol-level usage signal: any incoming ``calls`` /
- # ``method_implements`` / ``reads`` edge means somewhere
- # in the codebase actually uses this symbol — even if
- # the file-level ``imported_names`` machinery missed it
+ # ``method_implements`` / ``reads`` / ``extends`` /
+ # ``implements`` / ``type_use`` edge means somewhere in
+ # the codebase actually uses this symbol — even if the
+ # file-level ``imported_names`` machinery missed it
# (intra-file C++ helpers, ``Foo::method`` qualified
# definitions linked by call resolution but never named
- # in a header, Razor/XAML code-behind dispatches).
+ # in a header, Razor/XAML code-behind dispatches, and
+ # abstract base classes / interfaces that are only ever
+ # extended or implemented, never called directly — Java
+ # padding bases like ``BoundedLocalCache.BLCHeader``,
+ # Kotlin sealed parents, Scala typeclass traits).
if self.graph.has_node(sym_id) and any(
self.graph[pred][sym_id].get("edge_type")
- in ("calls", "method_implements", "reads")
+ in ("calls", "method_implements", "reads",
+ "extends", "implements", "type_use")
for pred in self.graph.predecessors(sym_id)
):
continue
@@ -1094,6 +1100,16 @@ class DeadCodeAnalyzer:
for pattern in _NEVER_FLAG_PATTERNS:
if fnmatch.fnmatch(path, pattern):
return True
+ # Workspace-driven never-flag — set by language warmups that read
+ # the build manifest (Gradle non-``main`` source sets, Cargo
+ # ``[[example]]`` / ``[[bench]]`` targets, …). Lets each language
+ # learn conventions from its own build files instead of us
+ # extending the hardcoded glob list every time a repo defines a
+ # custom source set like ``testFixtures`` / ``javaPoet`` /
+ # ``jcstress``.
+ node = self.graph.nodes.get(path)
+ if node is not None and node.get("is_never_flag", False):
+ return True
# __init__.py is a re-export barrel
return Path(path).name == "__init__.py"
diff --git a/packages/core/src/repowise/core/ingestion/graph_warmups.py b/packages/core/src/repowise/core/ingestion/graph_warmups.py
index a8dc224b5..a4068bbfd 100644
--- a/packages/core/src/repowise/core/ingestion/graph_warmups.py
+++ b/packages/core/src/repowise/core/ingestion/graph_warmups.py
@@ -61,6 +61,43 @@ def _warmup_jvm(ctx: "ResolverContext") -> None:
if node is not None:
node["is_entry_point"] = True
+ # Stamp every JVM source file under a non-``main`` Gradle source-set
+ # (``testFixtures``, ``integrationTest``, ``javaPoet``, ``jcstress``,
+ # ``jmh``, ``benchmarks``, …) as ``is_never_flag``. Gradle declares
+ # these as first-class source sets that the build runs through their
+ # own tasks; from a "source-imported by main code" perspective they
+ # always look orphan. The build-script-discovered list generalises
+ # beyond the hardcoded never-flag globs and picks up arbitrary
+ # repo-defined names (Caffeine's ``javaPoet`` and ``jcstress`` are
+ # not Gradle-builtin conventions). The check uses the workspace
+ # source-set ``src_dirs`` discovered by ``jvm_gradle.py``.
+ try:
+ from .resolvers.jvm_gradle import get_or_build_jvm_gradle_index
+
+ gradle_index = get_or_build_jvm_gradle_index(ctx)
+ except Exception:
+ gradle_index = None
+
+ if gradle_index is not None:
+ non_main_prefixes: list[str] = []
+ for project in gradle_index.projects.values():
+ base = project.root_dir.rstrip("/")
+ for ss in project.source_sets.values():
+ if ss.is_main:
+ continue
+ for src_dir in ss.src_dirs:
+ prefix = f"{base}/{src_dir}/" if base else f"{src_dir}/"
+ non_main_prefixes.append(prefix)
+ if non_main_prefixes:
+ for node_name in list(graph.nodes()):
+ s = str(node_name)
+ if not (s.endswith(".java") or s.endswith(".kt")):
+ continue
+ if any(s.startswith(p) for p in non_main_prefixes):
+ nd = graph.nodes.get(node_name)
+ if nd is not None:
+ nd["is_never_flag"] = True
+
def _warmup_dotnet(ctx: "ResolverContext") -> None:
from .resolvers.dotnet import get_or_build_index
diff --git a/tests/unit/analysis/test_jvm_reachability.py b/tests/unit/analysis/test_jvm_reachability.py
index 615352362..a12956ce9 100644
--- a/tests/unit/analysis/test_jvm_reachability.py
+++ b/tests/unit/analysis/test_jvm_reachability.py
@@ -381,3 +381,131 @@ class TestJvmEndToEnd:
# The init method should not surface as unused_internal.
kinds = [(f.kind, f.symbol_name) for f in report.findings]
assert (DeadCodeKind.UNUSED_INTERNAL, "init") not in kinds
+
+
+# ---------------------------------------------------------------------------
+# Workspace-driven never-flag (Phase 5 follow-up)
+# ---------------------------------------------------------------------------
+
+
+class TestWorkspaceNeverFlag:
+ def test_is_never_flag_node_attr_short_circuits_findings(self) -> None:
+ graph = _build_graph(
+ {
+ "lib/src/testFixtures/java/com/x/Fix.java": _java_file(
+ is_never_flag=True,
+ symbols=[{
+ "name": "Fix",
+ "kind": "class",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ },
+ )
+ analyzer = DeadCodeAnalyzer(graph)
+ report = analyzer.analyze({"min_confidence": 0.0})
+ paths = {f.file_path for f in report.findings}
+ names = {f.symbol_name for f in report.findings}
+ assert "lib/src/testFixtures/java/com/x/Fix.java" not in paths
+ assert "Fix" not in names
+
+
+# ---------------------------------------------------------------------------
+# Heritage-edge rescue: extends/implements/type_use count as symbol use
+# ---------------------------------------------------------------------------
+
+
+class TestHeritageEdgeRescue:
+ def test_extended_only_class_is_not_unused_export(self) -> None:
+ graph = _build_graph(
+ {
+ "p/Base.java": _java_file(
+ symbols=[{
+ "name": "Base",
+ "kind": "class",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ "p/Child.java": _java_file(
+ symbols=[{
+ "name": "Child",
+ "kind": "class",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ },
+ edges=[
+ ("p/Child.java", "p/Base.java", {"edge_type": "imports"}),
+ ("p/Child.java::Child", "p/Base.java::Base",
+ {"edge_type": "extends"}),
+ ],
+ )
+ analyzer = DeadCodeAnalyzer(graph)
+ report = analyzer.analyze({"min_confidence": 0.0})
+ names = {f.symbol_name for f in report.findings if f.kind == DeadCodeKind.UNUSED_EXPORT}
+ assert "Base" not in names
+
+ def test_implemented_only_interface_is_not_unused_export(self) -> None:
+ graph = _build_graph(
+ {
+ "p/Plugin.java": _java_file(
+ symbols=[{
+ "name": "Plugin",
+ "kind": "interface",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ "p/Impl.java": _java_file(
+ symbols=[{
+ "name": "Impl",
+ "kind": "class",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ },
+ edges=[
+ ("p/Impl.java", "p/Plugin.java", {"edge_type": "imports"}),
+ ("p/Impl.java::Impl", "p/Plugin.java::Plugin",
+ {"edge_type": "implements"}),
+ ],
+ )
+ analyzer = DeadCodeAnalyzer(graph)
+ report = analyzer.analyze({"min_confidence": 0.0})
+ names = {f.symbol_name for f in report.findings if f.kind == DeadCodeKind.UNUSED_EXPORT}
+ assert "Plugin" not in names
+
+ def test_type_use_only_class_is_not_unused_export(self) -> None:
+ graph = _build_graph(
+ {
+ "p/Config.java": _java_file(
+ symbols=[{
+ "name": "Config",
+ "kind": "class",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ "p/User.java": _java_file(
+ symbols=[{
+ "name": "User",
+ "kind": "class",
+ "visibility": "public",
+ "language": "java",
+ }],
+ ),
+ },
+ edges=[
+ ("p/User.java", "p/Config.java", {"edge_type": "imports"}),
+ ("p/User.java::User", "p/Config.java::Config",
+ {"edge_type": "type_use"}),
+ ],
+ )
+ analyzer = DeadCodeAnalyzer(graph)
+ report = analyzer.analyze({"min_confidence": 0.0})
+ names = {f.symbol_name for f in report.findings if f.kind == DeadCodeKind.UNUSED_EXPORT}
+ assert "Config" not in names