Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(dead-code): surface staleness on the web, drop the package column (#1669)

Raghav Chamadiya444ac9ab1b7c
diff --git a/packages/api-client/src/hosted.ts b/packages/api-client/src/hosted.ts
index c0a86da4a..d3469e8a2 100644
--- a/packages/api-client/src/hosted.ts
+++ b/packages/api-client/src/hosted.ts
@@ -317,6 +317,10 @@ export function mapHostedDeadCodeFinding(raw: Record<string, unknown>): DeadCode
primary_owner: partial.primary_owner ?? null,
status: partial.status ?? "open",
note: partial.note ?? null,
+ // Artifacts written before these were surfaced carry neither; a missing
+ // date must not read as "never touched", so it stays null.
+ last_commit_at: partial.last_commit_at ?? null,
+ commit_count_90d: partial.commit_count_90d ?? 0,
};
}
diff --git a/packages/api-client/src/types/dead-code.ts b/packages/api-client/src/types/dead-code.ts
index ccc39d005..2170d0195 100644
--- a/packages/api-client/src/types/dead-code.ts
+++ b/packages/api-client/src/types/dead-code.ts
@@ -24,6 +24,10 @@ export interface DeadCodeFindingResponse {
primary_owner: string | null;
status: DeadCodeStatus;
note: string | null;
+ /** When the file was last touched — the staleness signal, not `age_days`. */
+ last_commit_at: string | null;
+ /** Commits to the file in the last 90 days; 0 is what earns a high confidence. */
+ commit_count_90d: number;
}
export interface DeadCodePatchRequest {
diff --git a/packages/core/alembic/versions/0054_drop_dead_code_package.py b/packages/core/alembic/versions/0054_drop_dead_code_package.py
new file mode 100644
index 000000000..b4d25d73d
--- /dev/null
+++ b/packages/core/alembic/versions/0054_drop_dead_code_package.py
@@ -0,0 +1,40 @@
+"""Drop ``dead_code_findings.package``.
+
+It was ``Path(file_path).parts[0]`` — the path's own first segment, equal to it
+on 445/445 findings on this repo's index — and no schema, router, MCP tool or
+component ever read it back. Nothing is lost that ``file_path`` does not
+already show; for a zombie-package finding ``file_path`` *is* the package.
+
+``commit_count_90d`` was audited alongside it and deliberately kept: it is NOT
+NULL, and local SQLite stores never run Alembic (``init_db``'s reconciler is
+additive-only), so removing it from the model would fail every insert against
+an index already on disk. It is surfaced on the response instead.
+
+Revision ID: 0054
+Revises: 0053
+Create Date: 2026-08-17
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0054"
+down_revision: str | None = "0053"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.drop_column("dead_code_findings", "package")
+
+
+def downgrade() -> None:
+ op.add_column(
+ "dead_code_findings",
+ sa.Column("package", sa.String(length=255), nullable=True),
+ )
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 8d2282545..9278108c6 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -951,7 +951,6 @@ class DeadCodeAnalyzer:
last_commit_at=last_commit if isinstance(last_commit, datetime) else None,
commit_count_90d=commit_90d,
lines=node_data.get("symbol_count", 0) * 10, # rough estimate
- package=self._get_package(node),
evidence=evidence,
safe_to_delete=safe,
primary_owner=primary_owner,
@@ -1324,7 +1323,6 @@ class DeadCodeAnalyzer:
# Both-or-neither: a half-known span is worse than none.
start_line=(sym.get("start_line") or None) if sym.get("end_line") else None,
end_line=(sym.get("end_line") or None) if sym.get("start_line") else None,
- package=self._get_package(str(node)),
evidence=evidence,
safe_to_delete=safe,
primary_owner=git_meta.get("primary_owner_name"),
@@ -1483,7 +1481,6 @@ class DeadCodeAnalyzer:
end_line=(node_data.get("end_line") or None)
if node_data.get("start_line")
else None,
- package=self._get_package(file_path),
evidence=[f"No call, reference or override reaches '{sym_name}'"],
safe_to_delete=False,
primary_owner=git_meta.get("primary_owner_name"),
@@ -1590,7 +1587,6 @@ class DeadCodeAnalyzer:
last_commit_at=pkg_last_commit,
commit_count_90d=pkg_total_commits_90d,
lines=total_lines,
- package=pkg,
evidence=[f"No inter-package imports into '{pkg}'"],
safe_to_delete=False,
primary_owner=pkg_owner,
@@ -1676,6 +1672,3 @@ class DeadCodeAnalyzer:
return (now - dt).days > days
return False
- def _get_package(self, path: str) -> str | None:
- parts = Path(path).parts
- return parts[0] if len(parts) > 1 else None
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 f8dfb5931..39de96527 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/models.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/models.py
@@ -25,7 +25,6 @@ class DeadCodeFindingData:
last_commit_at: datetime | None
commit_count_90d: int
lines: int
- package: str | None
evidence: list[str]
safe_to_delete: bool
primary_owner: str | None
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 4c6954754..9b9440b83 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
@@ -36,7 +36,6 @@ def _dead_code_row_kwargs(finding: Any, repository_id: str) -> dict:
"lines": finding.lines,
"start_line": finding.start_line,
"end_line": finding.end_line,
- "package": finding.package,
"evidence_json": json.dumps(finding.evidence if hasattr(finding, "evidence") else []),
"safe_to_delete": finding.safe_to_delete,
"primary_owner": finding.primary_owner,
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index c011106dd..5853c8067 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -1146,7 +1146,12 @@ class DeadCodeFinding(Base):
lines: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
start_line: Mapped[int | None] = mapped_column(Integer, nullable=True)
end_line: Mapped[int | None] = mapped_column(Integer, nullable=True)
- package: Mapped[str | None] = mapped_column(String(255), nullable=True)
+ # ``package`` dropped: it was ``Path(file_path).parts[0]``, equal to the
+ # path's own first segment on 445/445 findings, so it carried nothing the
+ # row did not already show. Safe to remove because it was nullable —
+ # ``commit_count_90d`` is NOT NULL, and the local SQLite reconciler is
+ # additive-only, so removing that one would break inserts against every
+ # index already on disk. It is surfaced instead.
evidence_json: Mapped[str] = mapped_column(Text, nullable=False, default="[]")
safe_to_delete: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
primary_owner: Mapped[str | None] = mapped_column(String(255), nullable=True)
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 8cc5094b4..622f359b0 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
@@ -419,7 +419,13 @@ def _serialize_finding(f: Any, git_meta_map: dict | None = None) -> dict:
"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,
+ # Recent churn is the top rung of the confidence ladder, so the agent
+ # gets the same reason for a low score that the web page now shows.
+ "commit_count_90d": f.commit_count_90d,
"primary_owner": f.primary_owner,
+ # NB: age_days runs from the file's *first* commit, so it is the file's
+ # age, not how long this has been dead — the two disagree on 75% of
+ # findings. last_commit_at above is the staleness signal.
"age_days": f.age_days,
}
# Phase 4: add last meaningful change date
diff --git a/packages/server/src/repowise/server/schemas/code_quality.py b/packages/server/src/repowise/server/schemas/code_quality.py
index 1f19919d0..f38e084c7 100644
--- a/packages/server/src/repowise/server/schemas/code_quality.py
+++ b/packages/server/src/repowise/server/schemas/code_quality.py
@@ -36,6 +36,15 @@ class DeadCodeFindingResponse(BaseModel):
primary_owner: str | None
status: str
note: str | None
+ # When the file was last touched — the staleness signal behind the
+ # confidence ladder. Deliberately not ``age_days``: that is measured from
+ # the *first* commit, so it answers "how old is this file", not "how long
+ # has this been dead", and the two disagree on 75% of findings.
+ last_commit_at: datetime | None
+ # Commits to the file in the last 90 days. Top rung of the confidence
+ # ladder (0 commits is what earns the high tiers), so surfacing it is what
+ # makes a low confidence score legible: the file is still being worked on.
+ commit_count_90d: int
@classmethod
def from_orm(cls, obj: object) -> DeadCodeFindingResponse:
@@ -65,6 +74,8 @@ class DeadCodeFindingResponse(BaseModel):
primary_owner=obj.primary_owner, # type: ignore[attr-defined]
status=obj.status, # type: ignore[attr-defined]
note=obj.note, # type: ignore[attr-defined]
+ last_commit_at=obj.last_commit_at, # type: ignore[attr-defined]
+ commit_count_90d=obj.commit_count_90d, # type: ignore[attr-defined]
)
diff --git a/packages/types/src/dead-code.ts b/packages/types/src/dead-code.ts
index 8edc024b4..25858376a 100644
--- a/packages/types/src/dead-code.ts
+++ b/packages/types/src/dead-code.ts
@@ -2,9 +2,10 @@
* Canonical dead-code finding types.
*
* Canonical source: engine `DeadCodeFindingResponse` + `DeadCodeSummaryResponse`.
- * Some downstream pipelines emit extra raw-shape fields (`evidence`, `package`,
- * `last_commit_at`, `commit_count_90d`, `age_days`) — preserved here as
- * optional so consumer adapters don't lose information when normalising.
+ * Some downstream pipelines emit extra raw-shape fields (`evidence`,
+ * `age_days`) — preserved here as optional so consumer adapters don't lose
+ * information when normalising. `package` was dropped: it duplicated the
+ * first segment of `file_path`.
*/
export type DeadCodeStatus = "open" | "acknowledged" | "resolved" | "false_positive";
@@ -91,11 +92,17 @@ export interface DeadCodeFinding {
primary_owner: string | null;
status: DeadCodeStatus;
note: string | null;
- /** Raw engine artifact fields — present in some downstream pipelines, optional here. */
- evidence?: string[] | null;
- package?: string | null;
+ /**
+ * When the file was last touched. This is the staleness signal, and it is
+ * not `age_days`: that is measured from the *first* commit, so it answers
+ * "how old is this file" rather than "how long has this been dead". The two
+ * disagree on 75% of findings, so never label `age_days` as deadness.
+ */
last_commit_at?: string | null;
+ /** Commits to the file in the last 90 days; 0 is what earns a high confidence. */
commit_count_90d?: number;
+ /** Raw engine artifact fields — present in some downstream pipelines, optional here. */
+ evidence?: string[] | null;
age_days?: number | null;
}
diff --git a/packages/ui/src/dead-code/findings-table.tsx b/packages/ui/src/dead-code/findings-table.tsx
index 75a5e283c..b2204c48c 100644
--- a/packages/ui/src/dead-code/findings-table.tsx
+++ b/packages/ui/src/dead-code/findings-table.tsx
@@ -14,6 +14,7 @@ import { EmptyState } from "../shared/empty-state";
import { ResponsiveTable, type ResponsiveColumn } from "../shared/responsive-table";
import { toFriendlyMessage } from "../lib/errors";
import { AiPromptButton } from "../health/ai-prompt-button";
+import { formatRelativeTimeOrNull } from "../lib/format";
import {
FindingIdentity,
FindingConfidence,
@@ -53,7 +54,7 @@ function labelForKind(kind: string): string {
.join(" ");
}
-type SortKey = "path" | "confidence" | "owner" | "lines";
+type SortKey = "path" | "confidence" | "owner" | "lines" | "last_commit_at";
/** Sort value per column; strings compare with localeCompare, numbers subtract. */
function sortValue(f: DeadCodeFinding, key: SortKey): string | number {
@@ -66,6 +67,10 @@ function sortValue(f: DeadCodeFinding, key: SortKey): string | number {
return f.lines;
case "confidence":
return f.confidence;
+ case "last_commit_at":
+ // Unknown sorts as "just touched", never as ancient: with no date we
+ // have no evidence of staleness and must not imply any.
+ return f.last_commit_at ? Date.parse(f.last_commit_at) : Date.now();
}
}
@@ -321,6 +326,32 @@ export function FindingsTable({
</span>
),
},
+ {
+ // How long this has sat untouched — the signal behind the confidence
+ // score, and until now visible only to agents via get_dead_code.
+ // Deliberately last_commit_at, not age_days: age_days runs from the
+ // file's first commit, so it answers a different question.
+ key: "last_commit_at",
+ header: "Last touched",
+ sortable: true,
+ priority: 2,
+ headerClassName: "w-28",
+ render: (f) => (
+ <span
+ className="block text-xs tabular-nums text-[var(--color-text-tertiary)]"
+ title={f.last_commit_at ? new Date(f.last_commit_at).toLocaleString() : undefined}
+ >
+ {formatRelativeTimeOrNull(f.last_commit_at)}
+ {/* Recent churn is why a finding scores low; saying so makes the
+ confidence number legible instead of arbitrary. */}
+ {f.commit_count_90d ? (
+ <span className="block text-2xs text-[var(--color-text-tertiary)]">
+ {f.commit_count_90d} commit{f.commit_count_90d === 1 ? "" : "s"}/90d
+ </span>
+ ) : null}
+ </span>
+ ),
+ },
{
key: "lines",
header: "Lines",
diff --git a/tests/unit/analysis/test_dead_code_unindexed_importers.py b/tests/unit/analysis/test_dead_code_unindexed_importers.py
index eab574fff..6fa1f6281 100644
--- a/tests/unit/analysis/test_dead_code_unindexed_importers.py
+++ b/tests/unit/analysis/test_dead_code_unindexed_importers.py
@@ -38,7 +38,6 @@ def _finding(
last_commit_at=None,
commit_count_90d=0,
lines=10,
- package=None,
evidence=[],
safe_to_delete=True,
primary_owner=None,
diff --git a/tests/unit/dead_code/test_name_occurrences.py b/tests/unit/dead_code/test_name_occurrences.py
index 8fb146d65..41d6ab11e 100644
--- a/tests/unit/dead_code/test_name_occurrences.py
+++ b/tests/unit/dead_code/test_name_occurrences.py
@@ -47,7 +47,6 @@ def _finding(
lines=3,
start_line=start_line,
end_line=end_line,
- package=None,
evidence=[],
safe_to_delete=True,
primary_owner=None,
diff --git a/tests/unit/dead_code/test_reachability.py b/tests/unit/dead_code/test_reachability.py
index 9bbf465b7..4116e4834 100644
--- a/tests/unit/dead_code/test_reachability.py
+++ b/tests/unit/dead_code/test_reachability.py
@@ -196,7 +196,7 @@ def test_framework_anchor_counts_as_cross_package_importer():
}
)
- zombie_pkgs = [f.package for f in report.findings if f.kind == DeadCodeKind.ZOMBIE_PACKAGE]
+ zombie_pkgs = [f.file_path for f in report.findings if f.kind == DeadCodeKind.ZOMBIE_PACKAGE]
assert "Configuration" not in zombie_pkgs, (
"framework: predecessors should count as cross-package importers"
)
diff --git a/tests/unit/dead_code/test_zombie_packages.py b/tests/unit/dead_code/test_zombie_packages.py
index 85e0c421c..74fd45076 100644
--- a/tests/unit/dead_code/test_zombie_packages.py
+++ b/tests/unit/dead_code/test_zombie_packages.py
@@ -65,7 +65,9 @@ def test_zombie_package_detected():
)
zombie = [f for f in report.findings if f.kind == DeadCodeKind.ZOMBIE_PACKAGE]
- pkgs = [f.package for f in zombie]
+ # file_path *is* the package on a zombie finding; the separate `package`
+ # column duplicated it and was dropped.
+ pkgs = [f.file_path for f in zombie]
# Both pkgA and pkgB are zombie since neither has inter-package importers
assert "pkgA" in pkgs
assert "pkgB" in pkgs
@@ -210,6 +212,7 @@ def test_zombie_package_commit_count_summed_from_git_meta():
)
+
def test_zombie_package_last_commit_at_from_git_meta():
"""last_commit_at on a zombie finding is the most recent commit across all files.
diff --git a/tests/unit/server/test_dead_code.py b/tests/unit/server/test_dead_code.py
index cd7c087b6..5584be7b7 100644
--- a/tests/unit/server/test_dead_code.py
+++ b/tests/unit/server/test_dead_code.py
@@ -2,6 +2,8 @@
from __future__ import annotations
+from datetime import UTC, datetime
+
import pytest
from httpx import AsyncClient
@@ -28,6 +30,8 @@ async def _insert_dead_code(session_factory, repo_id: str) -> str:
"safe_to_delete": True,
"primary_owner": "Alice",
"age_days": 180,
+ "last_commit_at": datetime(2026, 1, 5, tzinfo=UTC),
+ "commit_count_90d": 0,
},
{
"kind": "unused_export",
@@ -42,6 +46,8 @@ async def _insert_dead_code(session_factory, repo_id: str) -> str:
"safe_to_delete": False,
"primary_owner": "Bob",
"age_days": 90,
+ "last_commit_at": datetime(2026, 6, 20, tzinfo=UTC),
+ "commit_count_90d": 7,
},
],
)
@@ -71,6 +77,27 @@ async def test_list_dead_code_with_data(client: AsyncClient, app) -> None:
assert len(data) == 2
+async def test_list_dead_code_surfaces_staleness(client: AsyncClient, app) -> None:
+ """The web surface gets the age signal that used to reach only the agent.
+
+ ``last_commit_at`` is the staleness fact, not ``age_days`` — the latter
+ runs from the file's first commit and answers a different question.
+ """
+ repo = await create_test_repo(client)
+ await _insert_dead_code(app.state.session_factory, repo["id"])
+
+ data = (await client.get(f"/api/repos/{repo['id']}/dead-code")).json()
+
+ unreachable = next(f for f in data if f["kind"] == "unreachable_file")
+ assert unreachable["last_commit_at"].startswith("2026-01-05")
+ assert unreachable["commit_count_90d"] == 0
+
+ unused = next(f for f in data if f["kind"] == "unused_export")
+ assert unused["last_commit_at"].startswith("2026-06-20")
+ assert unused["commit_count_90d"] == 7
+
+
@pytest.mark.asyncio
async def test_list_dead_code_line_spans(client: AsyncClient, app) -> None:
repo = await create_test_repo(client)