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(dead-code): one gate decides whether a finding is safe to delete (#3511)

Raghav Chamadiyaf28b155c56fc
diff --git a/docs/architecture/dead-code.md b/docs/architecture/dead-code.md
index 80c635330..eafedd159 100644
--- a/docs/architecture/dead-code.md
+++ b/docs/architecture/dead-code.md
@@ -14,7 +14,8 @@ a path says otherwise.
|--------|------|
| `analyzer.py` | `DeadCodeAnalyzer`: the four detectors, confidence scoring, caps, rescues. |
| `constants.py` | Never-flag globs, framework decorator lists, dynamic-dispatch name patterns, non-package directories, language sets. |
-| `risk_factors.py` | Path risk tokens, `SAFE_CONFIDENCE_THRESHOLD` (0.7), `RISK_CAP_CONFIDENCE` (0.4), `effective_safe_to_delete`. |
+| `risk_factors.py` | Path risk tokens, `SAFE_CONFIDENCE_THRESHOLD` (0.7), `RISK_CAP_CONFIDENCE` (0.4). |
+| `deletion_gate.py` | The one `safe_to_delete` rule: `apply_deletion_gate` at analysis time, `effective_safe_to_delete` for stored rows. |
| `serving.py` | Read side shared by MCP, REST and workspace merges: `TIER_FLOORS`, filtering, tiering, cross-repo adjustment. |
| `file_reachability.py` | The single "can anything reach this file?" answer. |
| `entry_shape.py` | Files shaped like programs (shebang, Python main guard). |
diff --git a/packages/core/src/repowise/core/analysis/dead_code/__init__.py b/packages/core/src/repowise/core/analysis/dead_code/__init__.py
index d279e1277..e92161f31 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/__init__.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/__init__.py
@@ -31,11 +31,11 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from ...lazy_exports import lazy_exports
+from .deletion_gate import effective_safe_to_delete
from .models import DeadCodeFindingData, DeadCodeKind, DeadCodeReport
from .risk_factors import (
RISK_CAP_CONFIDENCE,
SAFE_CONFIDENCE_THRESHOLD,
- effective_safe_to_delete,
path_risk_factors,
risk_evidence,
)
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 f2253331b..214d1acad 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -55,6 +55,7 @@ from .constants import (
)
from .contract_methods import is_com_method_implementation, is_contract_method
from .csharp_reachability import build_csharp_named_files, build_csharp_named_types
+from .deletion_gate import apply_deletion_gate
from .dynamic_markers import (
find_dynamic_edge_files,
find_dynamic_import_files,
@@ -1035,6 +1036,8 @@ class DeadCodeAnalyzer:
BuildFacts(repo_root=self._repo_root, dotnet_index=self._dotnet_index),
)
+ findings = 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]
diff --git a/packages/core/src/repowise/core/analysis/dead_code/deletion_gate.py b/packages/core/src/repowise/core/analysis/dead_code/deletion_gate.py
new file mode 100644
index 000000000..559fae957
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/dead_code/deletion_gate.py
@@ -0,0 +1,240 @@
+"""Deletion readiness: the one rule that decides ``safe_to_delete``.
+
+Confidence ranks a finding; deletion readiness is a promise that removing it
+breaks nothing. Every reason a finding can never carry that promise lives
+here, so the analyzer and every read-time consumer give the same answer. The
+gate only withholds: it never raises confidence, never changes a tier, and
+never turns ``safe_to_delete`` on.
+
+Two entry points share one predicate (:func:`_blockers`):
+
+- :func:`apply_deletion_gate` runs once at the end of an analysis, with the
+ graph and repository root in hand, and writes an evidence line for each
+ reason it withholds a finding.
+- :func:`effective_safe_to_delete` re-derives the flag for a stored row from
+ its columns alone (rows written before a reason existed). Reasons that need
+ the graph cannot fire there; the stored flag already carries them.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from ...code_origin import code_origin, path_origin
+from .risk_factors import REVIEW_ONLY_KINDS, SAFE_CONFIDENCE_THRESHOLD, path_risk_factors
+
+#: Above this share of guessed call edges, a language's graph in this repo is
+#: mostly name matches, so a missing edge says little. See the measurement in
+#: :func:`weak_resolution_languages`.
+WEAK_GUESSED_SHARE = 0.5
+
+
+@dataclass(frozen=True)
+class FindingView:
+ """The fields of a finding (or stored row) the gate reads."""
+
+ kind: str | None
+ file_path: str
+ confidence: float
+ export_only: bool = False
+
+
+@dataclass(frozen=True)
+class GateFacts:
+ """Repository facts the graph-backed reasons read, built once per analysis.
+
+ The default (no graph) is the read-time view: graph reasons cannot fire
+ there, and the stored flag already carries them.
+ """
+
+ repo_root: str | os.PathLike[str] | None = None
+ #: ``{file path: language}`` for every file node; None without a graph.
+ file_languages: Mapping[str, str] | None = None
+ #: ``{language: why its resolution is weak in this repo}``.
+ weak_languages: Mapping[str, str] = field(default_factory=dict)
+
+ @classmethod
+ def from_graph(
+ cls, graph: Any, paths: Iterable[str], repo_root: Any | None = None
+ ) -> GateFacts:
+ """Facts for the files at *paths* (the findings still deletion-ready)."""
+ file_languages = {
+ path: (graph.nodes[path].get("language") or "") if graph.has_node(path) else ""
+ for path in paths
+ }
+ return cls(
+ repo_root=repo_root,
+ file_languages=file_languages,
+ weak_languages=weak_resolution_languages(graph, set(file_languages.values())),
+ )
+
+
+Blocker = Callable[[FindingView, GateFacts], str | None]
+
+
+def _base_reason(view: FindingView, _facts: GateFacts) -> str | None:
+ """The ladder's own bar: kind, confidence and runtime-load path risk."""
+ if view.kind in REVIEW_ONLY_KINDS:
+ return f"A whole file ({view.kind}) is a review candidate, never deletion-ready"
+ if view.confidence < SAFE_CONFIDENCE_THRESHOLD:
+ return (
+ f"Confidence {view.confidence:.2f} is below the deletion-ready bar "
+ f"{SAFE_CONFIDENCE_THRESHOLD:.2f}"
+ )
+ if factors := path_risk_factors(view.file_path):
+ return f"Path carries a runtime-load risk factor ({', '.join(factors)})"
+ return None
+
+
+def _docs_example_reason(view: FindingView, facts: GateFacts) -> str | None:
+ # A docs site can include a snippet by line range (Writerside, mkdocs
+ # snippets), so no importer is not evidence that nothing reads it.
+ origin = (
+ path_origin(view.file_path)
+ if facts.repo_root is None
+ else code_origin(view.file_path, repo_root=facts.repo_root)
+ )
+ if origin != "docs_example":
+ return None
+ return (
+ "Documentation or example code: a docs build can include it by path or "
+ "line range, so it is not deletion-ready"
+ )
+
+
+def _export_only_reason(view: FindingView, _facts: GateFacts) -> str | None:
+ if not view.export_only:
+ return None
+ return "Only the export is unused: remove the export, not the symbol"
+
+
+def _weak_language_reason(view: FindingView, facts: GateFacts) -> str | None:
+ if facts.file_languages is None:
+ return None
+ # Fails closed: a file the graph does not place in a language has no
+ # resolution evidence to rest on.
+ language = facts.file_languages.get(view.file_path)
+ if not language:
+ return "Its language is unknown to the graph, so no importer is not proof of disuse"
+ return facts.weak_languages.get(language)
+
+
+#: Every reason a finding is never deletion-ready, in evidence order.
+_BLOCKERS: tuple[Blocker, ...] = (
+ _base_reason,
+ _docs_example_reason,
+ _export_only_reason,
+ _weak_language_reason,
+)
+
+
+def _blockers(view: FindingView, facts: GateFacts) -> list[str]:
+ return [line for check in _BLOCKERS if (line := check(view, facts))]
+
+
+def effective_safe_to_delete(
+ confidence: float,
+ file_path: str,
+ stored_safe: bool = True,
+ kind: str | None = None,
+) -> bool:
+ """Whether a stored finding is deletion-ready, from its columns alone.
+
+ Monotonic: never True when ``stored_safe`` is False, so it is safe to
+ apply to rows persisted before a reason existed.
+ """
+ if not stored_safe:
+ return False
+ view = FindingView(kind=kind, file_path=file_path or "", confidence=float(confidence or 0.0))
+ return not _blockers(view, GateFacts())
+
+
+def weak_resolution_languages(graph: Any, languages: Iterable[str]) -> dict[str, str]:
+ """Languages whose import or call resolution in this repo is weak evidence.
+
+ Two sources, both already reported elsewhere: the resolver's capability
+ table (``LanguageSpec.import_support``; anything short of ``full`` has
+ known gaps) and this repo's call-resolution basis, the per-language call
+ edges and guessed share ``get_dead_code`` reports as
+ ``call_resolution_basis``, computed here over edges whose origin is
+ recorded. Fails closed: a language with no such edge is unknown, so weak.
+ """
+ # Deferred: the ingestion package imports analysis modules at load time.
+ from ...ingestion.languages.registry import REGISTRY
+ from ...ingestion.resolution_basis import call_origins_by_language, guessed_share
+
+ origins = call_origins_by_language(graph)
+ weak: dict[str, str] = {}
+ for language in set(languages) - {""}:
+ # An edge with no origin (an older or rehydrated graph) is not known
+ # to be resolved, so it stays out of both sides of the share.
+ known = {o: n for o, n in origins.get(language, {}).items() if o is not None}
+ reason = _weakness(language, REGISTRY.import_support_for(language), guessed_share(known))
+ if reason:
+ weak[language] = reason
+ return weak
+
+
+def _weakness(language: str, support: str, share: float | None) -> str | None:
+ if support != "full":
+ return (
+ f"Imports in {language} are resolved with known gaps "
+ f"(import support: {support}), so no importer is not proof of disuse"
+ )
+ if share is None:
+ return (
+ f"No {language} call edge in this repository has a recorded resolution, "
+ "so how well its references resolve is unknown"
+ )
+ if share > WEAK_GUESSED_SHARE:
+ return (
+ f"{share:.0%} of {language} call edges in this repository are name "
+ "matches rather than resolved bindings, so no reference is not proof of disuse"
+ )
+ return None
+
+
+def apply_deletion_gate(findings: list[Any], graph: Any, repo_root: Any | None = None) -> list[Any]:
+ """Withhold ``safe_to_delete`` from every finding a reason blocks.
+
+ Each withheld finding gets the reasons as evidence lines. The repository
+ facts are built only when some finding is still deletion-ready. Mutates
+ in place and returns the same list.
+ """
+ ready = [f for f in findings if f.safe_to_delete]
+ if not ready:
+ return findings
+ facts = GateFacts.from_graph(graph, {f.file_path for f in ready}, repo_root)
+ for finding in ready:
+ reasons = _blockers(_view_of(finding), facts)
+ if reasons:
+ finding.safe_to_delete = False
+ finding.evidence.extend(_new_lines(finding.evidence, reasons))
+ return findings
+
+
+def _view_of(finding: Any) -> FindingView:
+ return FindingView(
+ kind=finding.kind,
+ file_path=finding.file_path,
+ confidence=finding.confidence,
+ export_only=finding.export_only,
+ )
+
+
+def _new_lines(existing: Iterable[str], reasons: list[str]) -> list[str]:
+ seen = set(existing)
+ return [line for line in reasons if line not in seen]
+
+
+__all__ = [
+ "WEAK_GUESSED_SHARE",
+ "FindingView",
+ "GateFacts",
+ "apply_deletion_gate",
+ "effective_safe_to_delete",
+ "weak_resolution_languages",
+]
diff --git a/packages/core/src/repowise/core/analysis/dead_code/risk_factors.py b/packages/core/src/repowise/core/analysis/dead_code/risk_factors.py
index 553c72be8..f47f3ae0c 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/risk_factors.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/risk_factors.py
@@ -205,25 +205,3 @@ def risk_evidence(factors: tuple[str, ...] | list[str]) -> str | None:
"outside static imports — review before deleting"
)
-
-def effective_safe_to_delete(
- confidence: float,
- file_path: str,
- stored_safe: bool = True,
- kind: str | None = None,
-) -> bool:
- """Re-derive whether a finding is genuinely deletion-ready.
-
- Monotonic — only ever *downgrades* the stored flag, never upgrades it, so
- it is safe to apply to findings persisted before risk factors existed:
-
- - never True when ``stored_safe`` is already False,
- - never True below :data:`SAFE_CONFIDENCE_THRESHOLD`,
- - never True when the path carries any runtime-load risk factor,
- - never True for a :data:`REVIEW_ONLY_KINDS` finding.
- """
- if not stored_safe or kind in REVIEW_ONLY_KINDS:
- return False
- if confidence < SAFE_CONFIDENCE_THRESHOLD:
- return False
- return not path_risk_factors(file_path)
diff --git a/packages/core/src/repowise/core/analysis/dead_code/serving.py b/packages/core/src/repowise/core/analysis/dead_code/serving.py
index 739556039..d02d660df 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/serving.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/serving.py
@@ -13,10 +13,10 @@ from dataclasses import dataclass
from dataclasses import field as dataclass_field
from typing import Any, Protocol
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.dead_code.risk_factors import (
RISK_CAP_CONFIDENCE,
SAFE_CONFIDENCE_THRESHOLD,
- effective_safe_to_delete,
path_risk_factors,
)
from repowise.core.analysis.finding_registry import verification_label, withheld_summary
diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.py
index de2b70ade..553b274dc 100644
--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py
+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py
@@ -15,7 +15,7 @@ from datetime import UTC, datetime
from pathlib import Path
from typing import Any
-from repowise.core.analysis.dead_code.risk_factors import effective_safe_to_delete
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.decisions.scope import binds_to_paths
from repowise.core.analysis.finding_registry import excluded_types
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
diff --git a/packages/core/src/repowise/core/ingestion/resolution_basis.py b/packages/core/src/repowise/core/ingestion/resolution_basis.py
new file mode 100644
index 000000000..428099ee9
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/resolution_basis.py
@@ -0,0 +1,50 @@
+"""How much of a language's call graph rests on a guess.
+
+One rule, read two ways: the MCP tools attach it beside an empty callers
+list (from stored edges), and dead code reads it off the in-memory graph
+before calling a finding deletion-ready.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+# Resolution origins the vocabulary in ``models.ResolutionOrigin`` annotates at
+# or below 0.75 confidence. Each binds a name to a symbol that merely exists
+# somewhere in the repo, so the edge is a guess, not a fact. NULL is not in
+# here: it means the row predates the vocabulary, which is unknown rather than
+# weak, so it counts in the denominator and not as a guess.
+GUESSED_ORIGINS: frozenset[str] = frozenset(
+ {
+ "global_unique",
+ "receiver_global",
+ "receiver_extension_global",
+ "receiver_typed_global",
+ "receiver_field_global",
+ "receiver_framework_global",
+ "return_type_global",
+ }
+)
+
+
+def guessed_share(origins: Mapping[str | None, int]) -> float | None:
+ """Share of call edges from a guessed origin, or None with no call edge."""
+ total = sum(origins.values())
+ if not total:
+ return None
+ return sum(n for origin, n in origins.items() if origin in GUESSED_ORIGINS) / total
+
+
+def call_origins_by_language(graph: Any) -> dict[str, dict[str | None, int]]:
+ """``{language: {resolution origin: call edges}}``, by the caller's language."""
+ out: dict[str, dict[str | None, int]] = {}
+ nodes = graph.nodes
+ for source, _target, data in graph.edges(data=True):
+ if data.get("edge_type") != "calls":
+ continue
+ language = nodes[source].get("language") or ""
+ origins = out.setdefault(language, {})
+ origin = data.get("resolution_origin")
+ origins[origin] = origins.get(origin, 0) + 1
+ return out
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/dead_code.py b/packages/core/src/repowise/core/persistence/crud/analysis/dead_code.py
index 16602607e..28095983f 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/dead_code.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/dead_code.py
@@ -9,11 +9,11 @@ from typing import Any
from sqlalchemy import select, text
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.dead_code.models import DeadCodeFindingData, DeadCodeKind
from repowise.core.analysis.dead_code.risk_factors import (
RISK_CAP_CONFIDENCE,
SAFE_CONFIDENCE_THRESHOLD,
- effective_safe_to_delete,
path_risk_factors,
)
from repowise.core.analysis.finding_registry import excluded_types
diff --git a/packages/server/src/repowise/server/mcp_server/_basis.py b/packages/server/src/repowise/server/mcp_server/_basis.py
index 9be407a63..857ced15f 100644
--- a/packages/server/src/repowise/server/mcp_server/_basis.py
+++ b/packages/server/src/repowise/server/mcp_server/_basis.py
@@ -19,25 +19,9 @@ from typing import Any
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ingestion.resolution_basis import guessed_share
from repowise.core.persistence.models import GraphEdge, GraphNode
-# Resolution origins the vocabulary in `ingestion/models.py::ResolutionOrigin`
-# annotates at or below 0.75 confidence. Each binds a name to a symbol that
-# merely exists somewhere in the repo, so the edge is a guess, not a fact.
-# NULL is not in here: it means the row predates the vocabulary, which is
-# unknown rather than weak, so it counts in the denominator and not as a guess.
-GUESSED_ORIGINS: frozenset[str] = frozenset(
- {
- "global_unique",
- "receiver_global",
- "receiver_extension_global",
- "receiver_typed_global",
- "receiver_field_global",
- "receiver_framework_global",
- "return_type_global",
- }
-)
-
RESOLVED_NOTE = (
"Call sites the resolver could not bind are not counted, so an empty list "
"means no resolved edge reaches this symbol, not proof that nothing calls it."
@@ -112,11 +96,10 @@ def _entry(language: str, origins: dict[str | None, int]) -> dict[str, Any]:
"unresolved_call_sites": None,
"note": NO_EDGES_NOTE,
}
- guessed = sum(n for origin, n in origins.items() if origin in GUESSED_ORIGINS)
return {
"language": language,
"resolved_call_edges": total,
- "guessed_share": round(guessed / total, 2),
+ "guessed_share": round(guessed_share(origins) or 0.0, 2),
"unresolved_call_sites": None,
"note": RESOLVED_NOTE,
}
diff --git a/packages/server/src/repowise/server/routers/dead_code.py b/packages/server/src/repowise/server/routers/dead_code.py
index 1d7e4d5d6..43ca4fcb7 100644
--- a/packages/server/src/repowise/server/routers/dead_code.py
+++ b/packages/server/src/repowise/server/routers/dead_code.py
@@ -5,9 +5,9 @@ from __future__ import annotations
from fastapi import APIRouter, Depends, HTTPException, Query, Request
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.dead_code.risk_factors import (
RISK_CAP_CONFIDENCE,
- effective_safe_to_delete,
)
from repowise.core.persistence import crud
from repowise.server.deps import get_db_session, verify_api_key
diff --git a/packages/server/src/repowise/server/routers/files.py b/packages/server/src/repowise/server/routers/files.py
index 72bf1c833..ebba66e2a 100644
--- a/packages/server/src/repowise/server/routers/files.py
+++ b/packages/server/src/repowise/server/routers/files.py
@@ -18,7 +18,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.dead_code.risk_factors import effective_safe_to_delete
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.finding_registry import excluded_types
from repowise.core.analysis.health.aggregation import NLOC_NULL_REASON
from repowise.core.analysis.health.signals import file_signals
diff --git a/packages/server/src/repowise/server/schemas/code_quality.py b/packages/server/src/repowise/server/schemas/code_quality.py
index 37e80173e..8171bb2fa 100644
--- a/packages/server/src/repowise/server/schemas/code_quality.py
+++ b/packages/server/src/repowise/server/schemas/code_quality.py
@@ -7,8 +7,8 @@ from datetime import datetime
from pydantic import BaseModel
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.dead_code.risk_factors import (
- effective_safe_to_delete,
path_risk_factors,
)
from repowise.core.analysis.finding_registry import verification_label
diff --git a/tests/unit/dead_code/test_deletion_gate.py b/tests/unit/dead_code/test_deletion_gate.py
new file mode 100644
index 000000000..9cbc984ef
--- /dev/null
+++ b/tests/unit/dead_code/test_deletion_gate.py
@@ -0,0 +1,201 @@
+"""The deletion gate withholds ``safe_to_delete`` and says why; it never grants it.
+
+One test per reason, each on a finding that is otherwise deletion-ready, plus
+the controls that keep the gate from withholding everything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+import networkx as nx
+import pytest
+
+from repowise.core.analysis.dead_code import DeadCodeAnalyzer, DeadCodeKind
+from repowise.core.analysis.dead_code.deletion_gate import (
+ WEAK_GUESSED_SHARE,
+ apply_deletion_gate,
+ effective_safe_to_delete,
+)
+from repowise.core.analysis.dead_code.models import DeadCodeFindingData
+from tests.unit.dead_code._helpers import _build_graph
+
+
+def _finding(path: str = "lib/util.py", **overrides) -> DeadCodeFindingData:
+ fields = {
+ "kind": DeadCodeKind.UNUSED_EXPORT,
+ "file_path": path,
+ "symbol_name": "lonely",
+ "symbol_kind": "function",
+ "confidence": 1.0,
+ "reason": "no importers",
+ "last_commit_at": None,
+ "commit_count_90d": 0,
+ "lines": 3,
+ "evidence": ["No file imports symbol"],
+ "safe_to_delete": True,
+ "primary_owner": None,
+ "age_days": None,
+ "start_line": 1,
+ "end_line": 3,
+ }
+ return DeadCodeFindingData(**{**fields, **overrides})
+
+
+def _graph(
+ path: str = "lib/util.py", language: str | None = "python", origins: tuple = ("import_scoped",)
+) -> nx.DiGraph:
+ """A file defining ``lonely``, called once per entry of *origins*."""
+ attrs = {"node_type": "file", "symbols": [{"name": "lonely", "kind": "function"}]}
+ graph = _build_graph({path: {**attrs, "language": language}})
+ for i, origin in enumerate(origins):
+ caller = f"app.x::f{i}"
+ graph.add_node(caller, node_type="symbol", language=language)
+ graph.add_edge(caller, f"{path}::lonely", edge_type="calls", resolution_origin=origin)
+ return graph
+
+
+def _gate(finding: DeadCodeFindingData, graph: nx.DiGraph | None = None, repo_root=None):
+ apply_deletion_gate([finding], graph if graph is not None else _graph(finding.file_path), repo_root)
+ return finding
+
+
+def _says(finding: DeadCodeFindingData, text: str) -> bool:
+ return any(text in line for line in finding.evidence)
+
+
+def test_ordinary_finding_stays_deletion_ready():
+ finding = _gate(_finding())
+ assert finding.safe_to_delete
+ assert finding.evidence == ["No file imports symbol"]
+
+
+ "path",
+ ["docs/snippets/util.py", "examples/basic/util.py", "crates/grep/examples/simple.rs"],
+)
+def test_docs_and_tool_examples_are_never_deletion_ready(path):
+ finding = _gate(_finding(path))
+ assert not finding.safe_to_delete
+ assert finding.confidence == 1.0
+ assert _says(finding, "Documentation or example code")
+
+
+def test_docs_site_snippet_tree_is_never_deletion_ready(tmp_path):
+ # A Writerside topic includes snippet files by line range.
+ site = tmp_path / "documentation-website" / "Writerside"
+ site.mkdir(parents=True)
+ (site / "writerside.cfg").write_text("<ihp/>")
+ path = "documentation-website/Writerside/snippets/src/Examples.kt"
+ finding = _gate(_finding(path), _graph(path, "kotlin"), repo_root=tmp_path)
+ assert not finding.safe_to_delete
+ assert _says(finding, "Documentation or example code")
+
+
+def test_export_only_finding_is_never_deletion_ready():
+ finding = _gate(_finding(export_only=True))
+ assert not finding.safe_to_delete
+ assert _says(finding, "remove the export, not the symbol")
+
+
+def test_language_with_partial_import_support_is_never_deletion_ready():
+ finding = _gate(_finding("src/Util.scala"), _graph("src/Util.scala", "scala"))
+ assert not finding.safe_to_delete
+ assert _says(finding, "import support: partial")
+
+
+def test_mostly_guessed_call_graph_is_never_deletion_ready():
+ origins = ("global_unique",) * 6 + ("import_scoped",) * 4
+ finding = _gate(_finding(), _graph(origins=origins))
+ assert not finding.safe_to_delete
+ assert _says(finding, "60% of python call edges")
+
+
+def test_mostly_resolved_call_graph_keeps_deletion_readiness():
+ origins = ("global_unique",) * 4 + ("import_scoped",) * 6
+ assert WEAK_GUESSED_SHARE >= 0.4
+ assert _gate(_finding(), _graph(origins=origins)).safe_to_delete
+
+
+def test_language_with_no_call_edge_is_unknown_and_withheld():
+ finding = _gate(_finding(), _graph(origins=()))
+ assert not finding.safe_to_delete
+ assert _says(finding, "No python call edge in this repository has a recorded resolution")
+
+
+def test_edges_without_an_origin_do_not_count_as_resolved():
+ # An older or rehydrated graph: edges exist, but none says how it was bound.
+ finding = _gate(_finding(), _graph(origins=(None, None, None)))
+ assert not finding.safe_to_delete
+ assert _says(finding, "has a recorded resolution")
+
+
+def test_unrecorded_edges_stay_out_of_the_share():
+ # 2 guessed of 3 known is 67%, not 2 of 6 (33%): unknown edges are not resolved ones.
+ origins = (None, None, None, "global_unique", "global_unique", "import_scoped")
+ finding = _gate(_finding(), _graph(origins=origins))
+ assert not finding.safe_to_delete
+ assert _says(finding, "67% of python call edges")
+
+
[email protected]("language", [None, ""])
+def test_file_with_no_language_is_withheld(language):
+ finding = _gate(_finding(), _graph(language=language))
+ assert not finding.safe_to_delete
+ assert _says(finding, "language is unknown")
+
+
+def test_file_missing_from_the_graph_is_withheld():
+ finding = _gate(_finding("lib/elsewhere.py"), _graph())
+ assert not finding.safe_to_delete
+ assert _says(finding, "language is unknown")
+
+
+def test_gate_never_grants_or_rescores():
+ finding = _gate(replace(_finding("docs/x.py"), safe_to_delete=False, confidence=0.9))
+ assert not finding.safe_to_delete
+ assert finding.confidence == 0.9
+ assert finding.evidence == ["No file imports symbol"]
+
+
+def test_base_reason_names_the_condition():
+ finding = _gate(_finding("lib/config/util.py"))
+ assert _says(finding, "runtime-load risk factor (config)")
+ finding = _gate(_finding(confidence=0.69))
+ assert _says(finding, "Confidence 0.69 is below the deletion-ready bar 0.70")
+
+
+def test_read_time_check_shares_the_path_reasons():
+ assert effective_safe_to_delete(1.0, "lib/util.py", True, "unused_export")
+ assert not effective_safe_to_delete(1.0, "docs/snippets/util.py", True, "unused_export")
+ assert not effective_safe_to_delete(1.0, "lib/util.py", True, "unreachable_file")
+ assert not effective_safe_to_delete(0.69, "lib/util.py", True, "unused_export")
+
+
+def test_analyzer_runs_the_gate():
+ sym = {"kind": "function", "visibility": "public", "decorators": [], "language": "python"}
+ nodes = {
+ "docs/snippets/util.py": {
+ "language": "python",
+ "symbols": [
+ {**sym, "name": "used_one", "start_line": 1, "end_line": 3},
+ {**sym, "name": "lonely", "start_line": 5, "end_line": 7},
+ ],
+ },
+ "app/main.py": {"language": "python", "is_entry_point": True},
+ }
+ imports = {"edge_type": "imports", "imported_names": ["used_one"]}
+ report = DeadCodeAnalyzer(
+ _build_graph(nodes, [("app/main.py", "docs/snippets/util.py", imports)])
+ ).analyze(
+ {
+ "detect_unreachable_files": False,
+ "detect_unused_internals": False,
+ "detect_zombie_packages": False,
+ "min_confidence": 0.0,
+ }
+ )
+ [finding] = [f for f in report.findings if f.symbol_name == "lonely"]
+ assert finding.confidence == pytest.approx(1.0)
+ assert not finding.safe_to_delete
+ assert _says(finding, "Documentation or example code")
diff --git a/tests/unit/dead_code/test_export_evidence.py b/tests/unit/dead_code/test_export_evidence.py
index b82fdd3be..2efb15f4d 100644
--- a/tests/unit/dead_code/test_export_evidence.py
+++ b/tests/unit/dead_code/test_export_evidence.py
@@ -27,6 +27,9 @@ _EXPORTS_ONLY = {
}
+_RESOLVED_CALL = {"edge_type": "calls", "resolution_origin": "same_file"}
+
+
def _sym(name: str, language: str, kind: str = "function") -> dict:
return {
"name": name,
@@ -45,6 +48,9 @@ def _export(path: str, language: str, importer_edge: dict | None, kind: str = "f
"app/main.x": {"language": language, "is_entry_point": True},
}
edges = [("app/main.x", path, importer_edge)] if importer_edge is not None else []
+ # One resolved call, so the language's resolution basis is known (the
+ # deletion gate withholds a language with none).
+ edges.append((f"{path}::lonely", f"{path}::used_one", _RESOLVED_CALL))
report = DeadCodeAnalyzer(_build_graph(nodes, edges)).analyze(dict(_EXPORTS_ONLY))
[finding] = [
f for f in report.findings
diff --git a/tests/unit/dead_code/test_risk_factors.py b/tests/unit/dead_code/test_risk_factors.py
index 0531cfc0d..996eab3e1 100644
--- a/tests/unit/dead_code/test_risk_factors.py
+++ b/tests/unit/dead_code/test_risk_factors.py
@@ -10,10 +10,10 @@ from __future__ import annotations
import pytest
from repowise.core.analysis.dead_code import DeadCodeAnalyzer
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.dead_code.risk_factors import (
RISK_CAP_CONFIDENCE,
SAFE_CONFIDENCE_THRESHOLD,
- effective_safe_to_delete,
path_risk_factors,
risk_evidence,
)
diff --git a/tests/unit/dead_code/test_vbnet_modules.py b/tests/unit/dead_code/test_vbnet_modules.py
index f46464371..bd51db6c3 100644
--- a/tests/unit/dead_code/test_vbnet_modules.py
+++ b/tests/unit/dead_code/test_vbnet_modules.py
@@ -65,6 +65,10 @@ def _tools_finding(container: str, member_called: bool):
member = f"{_PATH}::Tools::Run"
graph.add_node(member, node_type="symbol", file_path=_PATH, language="vbnet", kind="method")
graph.add_edge(f"{_PATH}::Tools", member, edge_type="has_method")
+ # One resolved call, so VB's resolution basis is known to the deletion gate.
+ graph.add_edge(
+ f"{_CALLER}::Start", f"{_PATH}::Used", edge_type="calls", resolution_origin="import_scoped"
+ )
if member_called:
graph.add_edge(f"{_CALLER}::Start", member, edge_type="calls")
source_map = {_PATH: _source(container), _CALLER: b"Sub Start()\n Run()\nEnd Sub\n"}
diff --git a/tests/unit/health/test_failing_types_demoted.py b/tests/unit/health/test_failing_types_demoted.py
index 120421de6..b9c4aae23 100644
--- a/tests/unit/health/test_failing_types_demoted.py
+++ b/tests/unit/health/test_failing_types_demoted.py
@@ -13,10 +13,10 @@ from __future__ import annotations
from types import SimpleNamespace
+from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
from repowise.core.analysis.dead_code.risk_factors import (
RISK_CAP_CONFIDENCE,
SAFE_CONFIDENCE_THRESHOLD,
- effective_safe_to_delete,
)
from repowise.core.analysis.finding_registry import excluded_types, status_of
from repowise.core.analysis.health.biomarkers.base import FileContext