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): frame findings as cleanup candidates, not safe-to-delete (#433)

Raghav Chamadiyafae97fb70b34
diff --git a/packages/cli/src/repowise/cli/commands/dead_code_cmd.py b/packages/cli/src/repowise/cli/commands/dead_code_cmd.py
index e2a9c9e09..404cd4059 100644
--- a/packages/cli/src/repowise/cli/commands/dead_code_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/dead_code_cmd.py
@@ -19,7 +19,11 @@ from repowise.cli.helpers import (
@click.command("dead-code")
@click.argument("path", required=False, type=click.Path(exists=True))
@click.option("--min-confidence", default=0.4, type=float, help="Minimum confidence threshold.")
[email protected]("--safe-only", is_flag=True, help="Only show safe_to_delete=True findings.")
+ "--safe-only",
+ is_flag=True,
+ help="Only show deletion-ready findings (high confidence, no runtime-load risk factors).",
+)
@click.option(
"--kind",
type=click.Choice(["unreachable_file", "unused_export", "unused_internal", "zombie_package"]),
@@ -206,6 +210,7 @@ def dead_code_command(
"confidence": f.confidence,
"reason": f.reason,
"safe_to_delete": f.safe_to_delete,
+ "risk_factors": f.risk_factors,
"lines": f.lines,
"primary_owner": f.primary_owner,
}
@@ -216,9 +221,9 @@ def dead_code_command(
if fmt == "md":
click.echo("# Dead Code Report\n")
click.echo(f"**Total findings:** {len(findings)}")
- click.echo(f"**Deletable lines:** {report.deletable_lines}\n")
+ click.echo(f"**Cleanup-candidate lines:** {report.deletable_lines}\n")
for f in findings:
- safe = " (safe to remove)" if f.safe_to_delete else ""
+ safe = " (cleanup-ready)" if f.safe_to_delete else ""
name = f"`{f.symbol_name}`" if f.symbol_name else f"`{f.file_path}`"
click.echo(f"- [{f.kind.value}] {name} — {f.reason} ({f.confidence:.0%}){safe}")
return
@@ -228,7 +233,7 @@ def dead_code_command(
table.add_column("Kind", style="cyan")
table.add_column("File / Symbol")
table.add_column("Confidence", justify="right")
- table.add_column("Safe?", justify="center")
+ table.add_column("Ready?", justify="center")
table.add_column("Lines", justify="right")
table.add_column("Reason")
@@ -246,6 +251,6 @@ def dead_code_command(
console.print(table)
console.print(
- f"\nDeletable lines: [bold]{report.deletable_lines:,}[/bold] "
+ f"\nCleanup-candidate lines: [bold]{report.deletable_lines:,}[/bold] "
f"(confidence: {report.confidence_summary})"
)
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 10992c3af..6b3028988 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/__init__.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/__init__.py
@@ -26,10 +26,22 @@ from __future__ import annotations
from .analyzer import DeadCodeAnalyzer
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,
+)
__all__ = [
+ "RISK_CAP_CONFIDENCE",
+ "SAFE_CONFIDENCE_THRESHOLD",
"DeadCodeAnalyzer",
"DeadCodeFindingData",
"DeadCodeKind",
"DeadCodeReport",
+ "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 e87adeb0b..adfb31dc1 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -38,6 +38,7 @@ from .cpp_reachability import (
)
from .go_reachability import build_go_package_files, is_go_file_reachable
from .jvm_reachability import build_jvm_package_files, is_jvm_file_reachable
+from .risk_factors import RISK_CAP_CONFIDENCE, path_risk_factors, risk_evidence
# Symbol kinds that cannot be independently imported by name in any
# supported language. Flagging them as "unused exports" is a guaranteed
@@ -569,6 +570,16 @@ class DeadCodeAnalyzer:
confidence = min(confidence, 0.4)
break
+ # Runtime-load risk factors (config / bootstrap / database /
+ # environment / script). 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)
+
safe = confidence >= 0.7
if safe and self._matches_dynamic_patterns(node, dynamic_patterns):
safe = False
@@ -578,6 +589,9 @@ class DeadCodeAnalyzer:
evidence.append("No commits in last 90 days")
if self._dynamic_import_files and confidence <= 0.4:
evidence.append("Package uses dynamic imports or runtime-resolved edges")
+ risk_line = risk_evidence(risk_factors)
+ if risk_line:
+ evidence.append(risk_line)
return DeadCodeFindingData(
kind=DeadCodeKind.UNREACHABLE_FILE,
@@ -594,6 +608,7 @@ class DeadCodeAnalyzer:
safe_to_delete=safe,
primary_owner=primary_owner,
age_days=age_days,
+ risk_factors=list(risk_factors),
)
def _detect_unused_exports(
@@ -882,10 +897,23 @@ class DeadCodeAnalyzer:
):
confidence = min(confidence, 0.4)
+ # Runtime-load risk factors for the defining file (config /
+ # bootstrap / database / environment / script): symbols in
+ # such files are often wired up reflectively, so cap below the
+ # deletion-ready threshold and tag the finding for review.
+ risk_factors = path_risk_factors(str(node))
+ if risk_factors:
+ confidence = min(confidence, RISK_CAP_CONFIDENCE)
+
safe = confidence >= 0.7
git_meta = self.git_meta_map.get(str(node), {})
+ evidence = [f"No imports of '{sym_name}' found in graph"]
+ risk_line = risk_evidence(risk_factors)
+ if risk_line:
+ evidence.append(risk_line)
+
findings.append(
DeadCodeFindingData(
kind=DeadCodeKind.UNUSED_EXPORT,
@@ -900,10 +928,11 @@ class DeadCodeAnalyzer:
commit_count_90d=git_meta.get("commit_count_90d", 0),
lines=sym.get("end_line", 0) - sym.get("start_line", 0),
package=self._get_package(str(node)),
- evidence=[f"No imports of '{sym_name}' found in graph"],
+ evidence=evidence,
safe_to_delete=safe,
primary_owner=git_meta.get("primary_owner_name"),
age_days=git_meta.get("age_days"),
+ risk_factors=list(risk_factors),
)
)
@@ -1039,6 +1068,7 @@ class DeadCodeAnalyzer:
safe_to_delete=False,
primary_owner=git_meta.get("primary_owner_name"),
age_days=git_meta.get("age_days"),
+ risk_factors=list(path_risk_factors(file_path)),
)
)
@@ -1142,6 +1172,7 @@ class DeadCodeAnalyzer:
safe_to_delete=False,
primary_owner=pkg_owner,
age_days=pkg_age_days,
+ risk_factors=list(path_risk_factors(pkg)),
)
)
diff --git a/packages/core/src/repowise/core/analysis/dead_code/models.py b/packages/core/src/repowise/core/analysis/dead_code/models.py
index a4c8e584d..d93f31a11 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/models.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/models.py
@@ -2,7 +2,7 @@
from __future__ import annotations
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from datetime import datetime
from enum import StrEnum
@@ -30,6 +30,10 @@ class DeadCodeFindingData:
safe_to_delete: bool
primary_owner: str | None
age_days: int | None
+ # Runtime-load risk factors (config / bootstrap / database / environment /
+ # script). Non-empty means the finding is a review candidate, never
+ # deletion-ready, regardless of confidence. See :mod:`risk_factors`.
+ risk_factors: list[str] = field(default_factory=list)
@dataclass
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
new file mode 100644
index 000000000..898784cb0
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/dead_code/risk_factors.py
@@ -0,0 +1,164 @@
+"""Risk factors for dead-code findings — soft signals that a file is more
+likely loaded at runtime than a static-reachability graph can observe.
+
+The ``_NEVER_FLAG_PATTERNS`` allowlist in :mod:`constants` removes files we
+are *confident* are framework/config/generated (``alembic/versions/*``,
+``*.config.*``, ``page.tsx``, …). This module is the softer, complementary
+layer: a file that *escaped* that allowlist but still looks like a config /
+bootstrap / database / environment / script file. Such a file is not removed
+from the report — surfacing likely-unused code is the whole point — but it is
+capped below the deletion-ready threshold and tagged with the risk factors
+that explain why, so the UI can present it as a *candidate to review* rather
+than as *safe to delete*.
+
+Static reachability + git age cannot *prove* a file is unused; it can only
+say nothing imports it. For ordinary modules that is a strong signal. For a
+``database/environment.db.js`` bootstrap file — exactly the class of file that
+is wired up by a runtime loader, a config key, or a string path rather than a
+static import — it is not. This module encodes that asymmetry.
+
+The classifier is pure path inspection, so it can run both at analysis time
+(to cap the persisted finding) and at read time (to defensively re-derive
+effective safety for findings persisted before this logic existed).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePosixPath
+
+# Findings at or above this confidence, with no risk factors, are presented as
+# deletion-ready ("safe to delete"). Anything below — or anything carrying a
+# risk factor — is a review candidate. Kept here as the single source of truth
+# so the analyzer and every read-time consumer agree.
+SAFE_CONFIDENCE_THRESHOLD: float = 0.7
+
+# Confidence ceiling applied to a finding that carries a runtime-load risk
+# factor. 0.4 is the default ``min_confidence`` floor, so the finding still
+# surfaces (as a medium / review-required candidate) but never reads as
+# deletion-ready.
+RISK_CAP_CONFIDENCE: float = 0.4
+
+# Filename-stem tokens → risk-factor tag. Matched against the basename split on
+# ``. _ -`` so ``environment.db.js`` yields {environment, db, js} → environment
+# + database. Deliberately curated: broad identifiers (app, main, index, core,
+# base, util) are excluded because they would cap ordinary modules.
+_FILENAME_RISK_TOKENS: dict[str, str] = {
+ # config
+ "config": "config",
+ "configs": "config",
+ "configuration": "config",
+ "conf": "config",
+ "settings": "config",
+ "setting": "config",
+ "setup": "config",
+ # environment
+ "env": "environment",
+ "environment": "environment",
+ "environ": "environment",
+ "dotenv": "environment",
+ # bootstrap / runtime entry
+ "bootstrap": "bootstrap",
+ "startup": "bootstrap",
+ "entrypoint": "bootstrap",
+ # database
+ "database": "database",
+ "db": "database",
+ "schema": "database",
+ "seed": "database",
+ "seeds": "database",
+ "migration": "database",
+ "migrations": "database",
+ "datastore": "database",
+ "sqlite": "database",
+}
+
+# Directory-segment tokens → risk-factor tag. A file *inside* one of these
+# directories inherits the tag even when its own name is generic.
+_DIRECTORY_RISK_TOKENS: dict[str, str] = {
+ "config": "config",
+ "configs": "config",
+ "settings": "config",
+ "env": "environment",
+ "environments": "environment",
+ "bootstrap": "bootstrap",
+ "database": "database",
+ "db": "database",
+ "migrations": "database",
+ "scripts": "script",
+ "bin": "script",
+ "tasks": "script",
+}
+
+# Human-readable one-liners per factor, used to build evidence strings.
+_FACTOR_BLURB: dict[str, str] = {
+ "config": "configuration",
+ "environment": "environment/bootstrap",
+ "bootstrap": "bootstrap/entry-point",
+ "database": "database/schema",
+ "script": "script/task",
+}
+
+_SPLIT_RE = re.compile(r"[._\-]+")
+
+
+def path_risk_factors(file_path: str) -> tuple[str, ...]:
+ """Return the sorted, de-duplicated runtime-load risk factors for *file_path*.
+
+ Empty tuple means no risk factor — an ordinary module. A non-empty result
+ means the file looks like the kind of thing that is referenced outside
+ normal static imports (config, bootstrap, database, environment, script),
+ so a "no importers" finding for it is weaker evidence than it looks.
+ """
+ if not file_path:
+ return ()
+
+ norm = file_path.replace("\\", "/")
+ p = PurePosixPath(norm)
+ factors: set[str] = set()
+
+ # Filename tokens (includes the extension, which never matches a token).
+ for token in _SPLIT_RE.split(p.name.lower()):
+ tag = _FILENAME_RISK_TOKENS.get(token)
+ if tag:
+ factors.add(tag)
+
+ # Directory segments.
+ for segment in p.parent.parts:
+ tag = _DIRECTORY_RISK_TOKENS.get(segment.lower())
+ if tag:
+ factors.add(tag)
+
+ return tuple(sorted(factors))
+
+
+def risk_evidence(factors: tuple[str, ...] | list[str]) -> str | None:
+ """Build a single human-readable evidence line for *factors*, or None."""
+ if not factors:
+ return None
+ blurbs = ", ".join(_FACTOR_BLURB.get(f, f) for f in factors)
+ return (
+ f"Runtime-load risk ({blurbs}): files of this kind are often referenced "
+ "outside static imports — review before deleting"
+ )
+
+
+def effective_safe_to_delete(
+ confidence: float,
+ file_path: str,
+ stored_safe: bool = True,
+) -> 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.
+ """
+ if not stored_safe:
+ return False
+ if confidence < SAFE_CONFIDENCE_THRESHOLD:
+ return False
+ return not path_risk_factors(file_path)
diff --git a/packages/core/src/repowise/core/generation/templates/file_page.j2 b/packages/core/src/repowise/core/generation/templates/file_page.j2
index bcfab54ce..517b3ca01 100644
--- a/packages/core/src/repowise/core/generation/templates/file_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/file_page.j2
@@ -222,7 +222,7 @@ Use these as the source of truth for the "why" when explaining design choices be
## Potentially unused code
{% for finding in ctx.dead_code_findings %}
- `{{ finding.symbol_name }}` — {{ finding.reason }}
- (confidence: {{ (finding.confidence * 100) | int }}%{% if finding.safe_to_delete %}, safe to remove{% endif %})
+ (confidence: {{ (finding.confidence * 100) | int }}%{% if finding.safe_to_delete %}, cleanup-ready{% endif %})
{% endfor %}
{% endif %}
diff --git a/packages/core/src/repowise/core/generation/templates/module_page.j2 b/packages/core/src/repowise/core/generation/templates/module_page.j2
index 55d931cdc..23b9de2d1 100644
--- a/packages/core/src/repowise/core/generation/templates/module_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/module_page.j2
@@ -78,7 +78,7 @@ Use these to explain *why* the module is shaped the way it is. Do not invent rat
{% if ctx.dead_code_findings %}
## Potentially unused code in this module
{% for finding in ctx.dead_code_findings[:10] %}
-- `{{ finding.symbol_name or '?' }}` — {{ finding.reason }} ({{ (finding.confidence * 100) | int }}%{% if finding.safe_to_delete %}, safe to remove{% endif %})
+- `{{ finding.symbol_name or '?' }}` — {{ finding.reason }} ({{ (finding.confidence * 100) | int }}%{% if finding.safe_to_delete %}, cleanup-ready{% endif %})
{% endfor %}
{% endif %}
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis.py b/packages/core/src/repowise/core/persistence/crud/analysis.py
index bad89b472..347d56a05 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis.py
@@ -13,6 +13,8 @@ from typing import Any
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 ..models import (
CoverageFile,
DeadCodeFinding,
@@ -199,10 +201,20 @@ async def get_dead_code_summary(session: AsyncSession, repository_id: str) -> di
total_lines += f.lines
by_kind[f.kind] = by_kind.get(f.kind, 0) + 1
+ # Re-derive effective safety from confidence + path risk factors rather
+ # than trusting the persisted boolean alone, so findings written before the
+ # risk-factor logic existed (or in a config/bootstrap/database/environment
+ # file the allowlist missed) are not counted as deletion-ready.
+ deletable_lines = sum(
+ f.lines
+ for f in findings
+ if effective_safe_to_delete(f.confidence, f.file_path, f.safe_to_delete)
+ )
+
return {
"total_findings": len(findings),
"confidence_summary": summary,
- "deletable_lines": sum(f.lines for f in findings if f.safe_to_delete),
+ "deletable_lines": deletable_lines,
"total_lines": total_lines,
"by_kind": by_kind,
}
diff --git a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
index be7dcbe19..5ea724e40 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
@@ -7,6 +7,10 @@ from typing import Any
from sqlalchemy import select
+from repowise.core.analysis.dead_code.risk_factors import (
+ effective_safe_to_delete,
+ path_risk_factors,
+)
from repowise.core.persistence.database import get_session
from repowise.core.persistence.models import (
DeadCodeFinding,
@@ -75,7 +79,9 @@ async def get_dead_code(
kind: Filter by kind (unreachable_file, unused_export, unused_internal, zombie_package).
min_confidence: Minimum confidence threshold (default 0.5). Use 0.7 for high-confidence
cleanups only.
- safe_only: Only return findings marked safe_to_delete (default false).
+ safe_only: Only return deletion-ready findings — high confidence with no runtime-load
+ risk factors (config/bootstrap/database/environment/script files are excluded even
+ when persisted as safe). Default false.
limit: Maximum findings per tier (default 20). Clamped to 25 because larger
payloads exceed MCP transport token caps; paginate by tier/directory/owner
for deeper exploration.
@@ -148,7 +154,7 @@ async def get_dead_code(
elif _excluded_kinds:
repo_filtered = [f for f in repo_filtered if f.kind not in _excluded_kinds]
if safe_only:
- repo_filtered = [f for f in repo_filtered if f.safe_to_delete]
+ repo_filtered = [f for f in repo_filtered if _effective_safe(f)]
if min_confidence > 0:
repo_filtered = [f for f in repo_filtered if f.confidence >= min_confidence]
if directory:
@@ -169,8 +175,8 @@ async def get_dead_code(
# Accumulate summary stats from unfiltered findings
total_all += len(repo_findings)
- total_deletable += sum(f.lines for f in repo_findings if f.safe_to_delete)
- total_safe += sum(1 for f in repo_findings if f.safe_to_delete)
+ total_deletable += sum(f.lines for f in repo_findings if _effective_safe(f))
+ total_safe += sum(1 for f in repo_findings if _effective_safe(f))
for f in repo_findings:
merged_by_kind[f.kind] = merged_by_kind.get(f.kind, 0) + 1
@@ -204,7 +210,8 @@ async def get_dead_code(
if tier is None or tier == "high":
tiers["high"] = _tier_from_dicts(
high,
- "High confidence (>=0.8): Zero references in the codebase. Safe to delete.",
+ "High confidence (>=0.8): No references found in the codebase. "
+ "Strong cleanup candidates — review (especially runtime-loaded files) before deleting.",
)
if tier is None or tier == "medium":
tiers["medium"] = _tier_from_dicts(
@@ -281,7 +288,7 @@ async def get_dead_code(
elif _excluded_kinds:
filtered = [f for f in filtered if f.kind not in _excluded_kinds]
if safe_only:
- filtered = [f for f in filtered if f.safe_to_delete]
+ filtered = [f for f in filtered if _effective_safe(f)]
if min_confidence > 0:
filtered = [f for f in filtered if f.confidence >= min_confidence]
if directory:
@@ -304,8 +311,8 @@ async def get_dead_code(
summary = {
"total_findings": len(all_findings),
"filtered_findings": len(filtered),
- "deletable_lines": sum(f.lines for f in all_findings if f.safe_to_delete),
- "safe_to_delete_count": sum(1 for f in all_findings if f.safe_to_delete),
+ "deletable_lines": sum(f.lines for f in all_findings if _effective_safe(f)),
+ "safe_to_delete_count": sum(1 for f in all_findings if _effective_safe(f)),
"by_kind": by_kind,
}
@@ -389,6 +396,16 @@ def _find_last_meaningful_change(gm: Any) -> str | None:
return None
+def _effective_safe(f: Any) -> bool:
+ """Re-derive deletion-readiness for a DeadCodeFinding ORM row.
+
+ Mirrors the API/CLI: the persisted boolean is only ever downgraded, never
+ trusted blindly, so config/bootstrap/database/environment/script files (and
+ findings written before risk factors existed) never read as safe-to-delete.
+ """
+ return effective_safe_to_delete(f.confidence, f.file_path, f.safe_to_delete)
+
+
def _serialize_finding(f: Any, git_meta_map: dict | None = None) -> dict:
"""Serialize a single DeadCodeFinding to dict."""
result = {
@@ -397,7 +414,8 @@ def _serialize_finding(f: Any, git_meta_map: dict | None = None) -> dict:
"symbol_name": f.symbol_name,
"confidence": f.confidence,
"reason": f.reason,
- "safe_to_delete": f.safe_to_delete,
+ "safe_to_delete": _effective_safe(f),
+ "risk_factors": list(path_risk_factors(f.file_path)),
"lines": f.lines,
"last_commit_at": f.last_commit_at.isoformat() if f.last_commit_at else None,
"primary_owner": f.primary_owner,
@@ -451,7 +469,7 @@ def _build_tiers(
"description": description,
"count": len(items),
"lines": sum(f.lines for f in items),
- "safe_count": sum(1 for f in items if f.safe_to_delete),
+ "safe_count": sum(1 for f in items if _effective_safe(f)),
"findings": [_serialize_finding(f, git_meta_map) for f in items[:limit]],
"truncated": len(items) > limit,
}
@@ -461,7 +479,8 @@ def _build_tiers(
tiers["high"] = _tier_block(
"high",
high,
- "High confidence (>=0.8): Zero references in the codebase. Safe to delete.",
+ "High confidence (>=0.8): No references found in the codebase. "
+ "Strong cleanup candidates — review (especially runtime-loaded files) before deleting.",
)
if tier_filter is None or tier_filter == "medium":
tiers["medium"] = _tier_block(
@@ -489,7 +508,7 @@ def _rollup_by_directory(findings: list) -> list[dict]:
dirs[dir_key] = {"directory": dir_key, "count": 0, "lines": 0, "safe_count": 0}
dirs[dir_key]["count"] += 1
dirs[dir_key]["lines"] += f.lines
- if f.safe_to_delete:
+ if _effective_safe(f):
dirs[dir_key]["safe_count"] += 1
return sorted(dirs.values(), key=lambda d: -d["lines"])
@@ -504,7 +523,7 @@ def _rollup_by_owner(findings: list) -> list[dict]:
owners[name] = {"owner": name, "count": 0, "lines": 0, "safe_count": 0}
owners[name]["count"] += 1
owners[name]["lines"] += f.lines
- if f.safe_to_delete:
+ if _effective_safe(f):
owners[name]["safe_count"] += 1
return sorted(owners.values(), key=lambda o: -o["lines"])
@@ -525,8 +544,9 @@ def _compute_impact(tiers: dict) -> dict:
"total_lines_reclaimable": total_lines,
"safe_lines_reclaimable": safe_lines,
"recommendation": (
- "Start with the 'high' tier — these have zero references and are safe to remove. "
- "Then review 'medium' tier findings with your team."
+ "Start with the 'high' tier — these have no references in the graph and are the "
+ "strongest cleanup candidates. Confirm each (runtime-loaded config/bootstrap/database "
+ "files are flagged but never auto-marked safe), then review 'medium' tier with your team."
if total_lines > 0
else "No dead code found matching your filters."
),
diff --git a/packages/server/src/repowise/server/routers/dead_code.py b/packages/server/src/repowise/server/routers/dead_code.py
index 3db7dc1a6..32cbe5448 100644
--- a/packages/server/src/repowise/server/routers/dead_code.py
+++ b/packages/server/src/repowise/server/routers/dead_code.py
@@ -2,9 +2,10 @@
from __future__ import annotations
+from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
-from fastapi import APIRouter, Depends, HTTPException, Query
+from repowise.core.analysis.dead_code.risk_factors import effective_safe_to_delete
from repowise.core.persistence import crud
from repowise.server.deps import get_db_session, verify_api_key
from repowise.server.schemas import (
@@ -41,7 +42,11 @@ async def list_dead_code(
status=status,
)
if safe_only:
- findings = [f for f in findings if f.safe_to_delete]
+ findings = [
+ f
+ for f in findings
+ if effective_safe_to_delete(f.confidence, f.file_path, f.safe_to_delete)
+ ]
return [DeadCodeFindingResponse.from_orm(f) for f in findings[:limit]]
diff --git a/packages/server/src/repowise/server/schemas/code_quality.py b/packages/server/src/repowise/server/schemas/code_quality.py
index d732941d0..6402fd437 100644
--- a/packages/server/src/repowise/server/schemas/code_quality.py
+++ b/packages/server/src/repowise/server/schemas/code_quality.py
@@ -2,10 +2,16 @@
from __future__ import annotations
+import json
from datetime import datetime
from pydantic import BaseModel
+from repowise.core.analysis.dead_code.risk_factors import (
+ effective_safe_to_delete,
+ path_risk_factors,
+)
+
class DeadCodeFindingResponse(BaseModel):
id: str
@@ -16,23 +22,42 @@ class DeadCodeFindingResponse(BaseModel):
confidence: float
reason: str
lines: int
+ # Effective deletion-readiness — re-derived from confidence + path risk
+ # factors, not the raw persisted boolean. A config/bootstrap/database/
+ # environment/script file is never deletion-ready even when stored safe.
safe_to_delete: bool
+ # Why this finding is a review candidate rather than a delete (empty for
+ # ordinary modules). Drives the UI risk chips.
+ risk_factors: list[str]
+ # Human-readable signals behind the finding (in_degree, commit age, risk).
+ evidence: list[str]
primary_owner: str | None
status: str
note: str | None
@classmethod
def from_orm(cls, obj: object) -> DeadCodeFindingResponse:
+ file_path: str = obj.file_path # type: ignore[attr-defined]
+ confidence: float = obj.confidence # type: ignore[attr-defined]
+ stored_safe: bool = obj.safe_to_delete # type: ignore[attr-defined]
+ try:
+ evidence = json.loads(obj.evidence_json) # type: ignore[attr-defined]
+ if not isinstance(evidence, list):
+ evidence = []
+ except (AttributeError, TypeError, ValueError):
+ evidence = []
return cls(
id=obj.id, # type: ignore[attr-defined]
kind=obj.kind, # type: ignore[attr-defined]
- file_path=obj.file_path, # type: ignore[attr-defined]
+ file_path=file_path,
symbol_name=obj.symbol_name, # type: ignore[attr-defined]
symbol_kind=obj.symbol_kind, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
+ confidence=confidence,
reason=obj.reason, # type: ignore[attr-defined]
lines=obj.lines, # type: ignore[attr-defined]
- safe_to_delete=obj.safe_to_delete, # type: ignore[attr-defined]
+ safe_to_delete=effective_safe_to_delete(confidence, file_path, stored_safe),
+ risk_factors=list(path_risk_factors(file_path)),
+ evidence=evidence,
primary_owner=obj.primary_owner, # type: ignore[attr-defined]
status=obj.status, # type: ignore[attr-defined]
note=obj.note, # type: ignore[attr-defined]
diff --git a/packages/types/src/dead-code.ts b/packages/types/src/dead-code.ts
index 2c97d12ba..c78e00f31 100644
--- a/packages/types/src/dead-code.ts
+++ b/packages/types/src/dead-code.ts
@@ -18,7 +18,16 @@ export interface DeadCodeFinding {
confidence: number;
reason: string;
lines: number;
+ /**
+ * Effective deletion-readiness — high confidence AND no runtime-load risk
+ * factors. Re-derived server-side, not the raw persisted boolean.
+ */
safe_to_delete: boolean;
+ /**
+ * Runtime-load risk factors (config / bootstrap / database / environment /
+ * script). Non-empty means a review candidate, never deletion-ready.
+ */
+ risk_factors?: string[];
primary_owner: string | null;
status: DeadCodeStatus;
note: string | null;
diff --git a/packages/ui/src/chat/artifacts.tsx b/packages/ui/src/chat/artifacts.tsx
index c0ca23234..5df4a14f4 100644
--- a/packages/ui/src/chat/artifacts.tsx
+++ b/packages/ui/src/chat/artifacts.tsx
@@ -429,7 +429,7 @@ export function DeadCodeRenderer({ data }: { data: DeadCodeArtifactData }) {
value={data.total_findings.toLocaleString()}
/>
<StatRow
- label="Deletable lines"
+ label="Candidate lines"
value={data.deletable_lines.toLocaleString()}
/>
</div>
@@ -489,7 +489,7 @@ function DeadCodeRow({
{showLines && typeof finding.lines === "number" && (
<> · {finding.lines} lines</>
)}
- {finding.safe_to_delete && <> · safe to delete</>}
+ {finding.safe_to_delete && <> · cleanup-ready</>}
</div>
<p className="text-[11px] text-[var(--color-text-secondary)] mt-1 line-clamp-2">
{finding.reason}
diff --git a/packages/ui/src/dead-code/safe-to-delete-pile.tsx b/packages/ui/src/dead-code/safe-to-delete-pile.tsx
index 4ed13785b..03e3ab220 100644
--- a/packages/ui/src/dead-code/safe-to-delete-pile.tsx
+++ b/packages/ui/src/dead-code/safe-to-delete-pile.tsx
@@ -93,11 +93,12 @@ export function SafeToDeletePile({
<span className="text-3xl font-semibold tabular-nums text-[var(--color-text-primary)]">
{lines.toLocaleString()}
</span>
- <span className="text-sm text-[var(--color-text-secondary)]">lines safe to delete</span>
+ <span className="text-sm text-[var(--color-text-secondary)]">lines in cleanup candidates</span>
</div>
<p className="mt-1 text-xs text-[var(--color-text-tertiary)]">
- High-confidence findings across <span className="font-medium">{files}</span> file
- {files === 1 ? "" : "s"} ({findings.length} finding{findings.length === 1 ? "" : "s"}).
+ High-confidence candidates across <span className="font-medium">{files}</span> file
+ {files === 1 ? "" : "s"} ({findings.length} finding{findings.length === 1 ? "" : "s"}) —
+ {" "}review before deleting.
</p>
</div>
{onPropose && findings.length > 0 && (
diff --git a/packages/ui/src/dead-code/summary-bar.tsx b/packages/ui/src/dead-code/summary-bar.tsx
index 7d2d8ee10..41eced424 100644
--- a/packages/ui/src/dead-code/summary-bar.tsx
+++ b/packages/ui/src/dead-code/summary-bar.tsx
@@ -20,9 +20,9 @@ export function SummaryBar({ summary }: SummaryBarProps) {
<div className="rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] p-4">
<p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-1">
- Deletable Lines
+ Candidate Lines
</p>
- <p className="text-2xl font-bold text-red-500 tabular-nums">
+ <p className="text-2xl font-bold text-amber-500 tabular-nums">
{formatNumber(summary.deletable_lines)}
</p>
</div>
diff --git a/packages/web/src/app/repos/[id]/overview/page.tsx b/packages/web/src/app/repos/[id]/overview/page.tsx
index 4931bd6bd..39fd3edf0 100644
--- a/packages/web/src/app/repos/[id]/overview/page.tsx
+++ b/packages/web/src/app/repos/[id]/overview/page.tsx
@@ -193,7 +193,7 @@ export default async function OverviewPage({ params }: Props) {
value={stats ? formatNumber(stats.dead_export_count) : "–"}
description={
deadCodeSummary
- ? `${formatNumber(deadCodeSummary.deletable_lines)} deletable lines`
+ ? `${formatNumber(deadCodeSummary.deletable_lines)} cleanup-candidate lines`
: undefined
}
href={`/repos/${id}/dead-code`}
diff --git a/packages/web/src/components/dead-code/finding-row.tsx b/packages/web/src/components/dead-code/finding-row.tsx
index cfd9927e7..5c82ec3eb 100644
--- a/packages/web/src/components/dead-code/finding-row.tsx
+++ b/packages/web/src/components/dead-code/finding-row.tsx
@@ -133,9 +133,18 @@ export function FindingRow({ finding, repoId, selected, onToggle, onUpdate }: Fi
</td>
<td className="px-4 py-2.5 hidden sm:table-cell">
{finding.safe_to_delete ? (
- <Badge variant="fresh">Safe</Badge>
+ <Badge variant="fresh">Candidate</Badge>
) : (
- <Badge variant="default">Review</Badge>
+ <Badge
+ variant="default"
+ title={
+ finding.risk_factors && finding.risk_factors.length > 0
+ ? `Runtime-load risk (${finding.risk_factors.join(", ")}) — verify it isn't loaded outside static imports before deleting`
+ : "Lower confidence — verify before deleting"
+ }
+ >
+ Review
+ </Badge>
)}
</td>
<td className="px-4 py-2.5 hidden sm:table-cell">
diff --git a/packages/web/src/components/dead-code/findings-table.tsx b/packages/web/src/components/dead-code/findings-table.tsx
index 975f5bccb..3122a69a5 100644
--- a/packages/web/src/components/dead-code/findings-table.tsx
+++ b/packages/web/src/components/dead-code/findings-table.tsx
@@ -138,7 +138,7 @@ export function FindingsTable({ repoId }: FindingsTableProps) {
onChange={(e) => setSafeOnly(e.target.checked)}
className="rounded border-[var(--color-border-default)]"
/>
- Safe to delete only
+ Cleanup-ready only
</label>
{selected.size > 0 && (
diff --git a/packages/web/src/lib/api/types/dead-code.ts b/packages/web/src/lib/api/types/dead-code.ts
index d364a8ee9..0263c730b 100644
--- a/packages/web/src/lib/api/types/dead-code.ts
+++ b/packages/web/src/lib/api/types/dead-code.ts
@@ -11,7 +11,12 @@ export interface DeadCodeFindingResponse {
confidence: number;
reason: string;
lines: number;
+ /** Effective deletion-readiness — re-derived from confidence + risk factors. */
safe_to_delete: boolean;
+ /** Runtime-load risk factors that make this a review candidate, not a delete. */
+ risk_factors: string[];
+ /** Human-readable signals behind the finding (no-importers, age, risk). */
+ evidence: string[];
primary_owner: string | null;
status: string;
note: string | null;
diff --git a/tests/unit/dead_code/test_risk_factors.py b/tests/unit/dead_code/test_risk_factors.py
new file mode 100644
index 000000000..9140bf61c
--- /dev/null
+++ b/tests/unit/dead_code/test_risk_factors.py
@@ -0,0 +1,133 @@
+"""Unit tests for runtime-load risk factors and effective deletion-readiness.
+
+Covers the issue's core ask: config / bootstrap / database / environment /
+script files that escape the never-flag allowlist must be presented as review
+candidates, never as safe-to-delete, regardless of git age / confidence.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.analysis.dead_code import DeadCodeAnalyzer
+from repowise.core.analysis.dead_code.risk_factors import (
+ RISK_CAP_CONFIDENCE,
+ SAFE_CONFIDENCE_THRESHOLD,
+ effective_safe_to_delete,
+ path_risk_factors,
+ risk_evidence,
+)
+from tests.unit.dead_code._helpers import _build_graph, _old_date
+
+
+ "path,expected",
+ [
+ # The issue's concrete example.
+ ("src/database/environment.db.js", {"database", "environment"}),
+ # Filename-token signals.
+ ("app/config.py", {"config"}),
+ ("lib/settings.ts", {"config"}),
+ ("pkg/bootstrap.go", {"bootstrap"}),
+ ("server/environment.ts", {"environment"}),
+ ("a/b/schema.rb", {"database"}),
+ # Directory-segment signals (generic filename).
+ ("config/loader.py", {"config"}),
+ ("scripts/cleanup.py", {"script"}),
+ ("db/connection.py", {"database"}),
+ # Ordinary modules — no risk factor.
+ ("src/services/user_service.py", set()),
+ ("pkg/old_unused.py", set()),
+ ("components/Button.tsx", set()),
+ ("", set()),
+ ],
+)
+def test_path_risk_factors(path: str, expected: set[str]) -> None:
+ assert set(path_risk_factors(path)) == expected
+
+
+def test_effective_safe_downgrades_risk_file() -> None:
+ """A high-confidence config/db file is never effectively safe."""
+ # Ordinary high-confidence file → safe.
+ assert effective_safe_to_delete(0.9, "src/dead_module.py", stored_safe=True) is True
+ # Same confidence, but a database/environment file → not safe.
+ assert (
+ effective_safe_to_delete(0.9, "src/database/environment.db.js", stored_safe=True) is False
+ )
+
+
+def test_effective_safe_is_monotonic() -> None:
+ """Never upgrades: already-unsafe or low-confidence stays unsafe."""
+ assert effective_safe_to_delete(0.9, "src/foo.py", stored_safe=False) is False
+ assert (
+ effective_safe_to_delete(SAFE_CONFIDENCE_THRESHOLD - 0.01, "src/foo.py", stored_safe=True)
+ is False
+ )
+ assert (
+ effective_safe_to_delete(SAFE_CONFIDENCE_THRESHOLD, "src/foo.py", stored_safe=True) is True
+ )
+
+
+def test_risk_evidence_text() -> None:
+ assert risk_evidence(()) is None
+ line = risk_evidence(("database", "environment"))
+ assert line is not None
+ assert "review before deleting" in line
+
+
+def test_analyzer_caps_risk_file_even_when_old() -> None:
+ """An unreachable database/environment bootstrap file that hasn't been
+ touched in a year still surfaces, but capped and not safe-to-delete."""
+ g = _build_graph(
+ nodes={
+ "src/database/environment.db.js": {
+ "language": "javascript",
+ "is_entry_point": False,
+ "is_test": False,
+ "is_api_contract": False,
+ "symbol_count": 8,
+ "symbols": [],
+ },
+ "src/old_module.js": {
+ "language": "javascript",
+ "is_entry_point": False,
+ "is_test": False,
+ "is_api_contract": False,
+ "symbol_count": 8,
+ "symbols": [],
+ },
+ },
+ )
+ git_meta = {
+ "src/database/environment.db.js": {
+ "commit_count_90d": 0,
+ "last_commit_at": _old_date(days=400),
+ "age_days": 400,
+ },
+ "src/old_module.js": {
+ "commit_count_90d": 0,
+ "last_commit_at": _old_date(days=400),
+ "age_days": 400,
+ },
+ }
+
+ analyzer = DeadCodeAnalyzer(g, git_meta_map=git_meta)
+ report = analyzer.analyze(
+ {
+ "detect_unused_exports": False,
+ "detect_zombie_packages": False,
+ "min_confidence": 0.0,
+ }
+ )
+ by_path = {f.file_path: f for f in report.findings}
+
+ risky = by_path["src/database/environment.db.js"]
+ assert risky.safe_to_delete is False
+ assert risky.confidence <= RISK_CAP_CONFIDENCE
+ assert set(risky.risk_factors) == {"database", "environment"}
+ assert any("review before deleting" in e for e in risky.evidence)
+
+ # The ordinary file with identical git age is still confidently safe.
+ ordinary = by_path["src/old_module.js"]
+ assert ordinary.safe_to_delete is True
+ assert ordinary.risk_factors == []