Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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__.pyindex 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 annotationsfrom .analyzer import DeadCodeAnalyzerfrom .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.pyindex 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_reachablefrom .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.7if 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.7git_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.pyindex 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, fieldfrom datetime import datetimefrom enum import StrEnum@@ -30,6 +30,10 @@ class DeadCodeFindingData:safe_to_delete: boolprimary_owner: str | Noneage_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)@dataclassdiff --git a/packages/core/src/repowise/core/analysis/dead_code/risk_factors.py b/packages/core/src/repowise/core/analysis/dead_code/risk_factors.pynew file mode 100644index 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.j2index 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.j2index 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.pyindex 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 Anyfrom sqlalchemy import func, selectfrom 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) -> ditotal_lines += f.linesby_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.pyindex 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 Anyfrom 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_sessionfrom 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-confidencecleanups 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 largerpayloads exceed MCP transport token caps; paginate by tier/directory/ownerfor 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 findingstotal_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"] += 1dirs[dir_key]["lines"] += f.lines- if f.safe_to_delete:+ if _effective_safe(f):dirs[dir_key]["safe_count"] += 1return 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"] += 1owners[name]["lines"] += f.lines- if f.safe_to_delete:+ if _effective_safe(f):owners[name]["safe_count"] += 1return 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 > 0else "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.pyindex 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, Queryfrom sqlalchemy.ext.asyncio import AsyncSession-from fastapi import APIRouter, Depends, HTTPException, Query+from repowise.core.analysis.dead_code.risk_factors import effective_safe_to_deletefrom repowise.core.persistence import crudfrom repowise.server.deps import get_db_session, verify_api_keyfrom 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.pyindex 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 jsonfrom datetime import datetimefrom 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: floatreason: strlines: 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 | Nonestatus: strnote: str | None@classmethoddef 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.pynew file mode 100644index 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 == []