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(server): report when dead code and security analysis last ran (#3303)

Raghav Chamadiya084db0f93dbf
diff --git a/packages/api-client/src/security.ts b/packages/api-client/src/security.ts
index 772c03c79..2b0b7568a 100644
--- a/packages/api-client/src/security.ts
+++ b/packages/api-client/src/security.ts
@@ -13,6 +13,15 @@ export interface SecurityFinding {
commit_at: string | null;
}
+export interface SecuritySummary {
+ /** ISO 8601 UTC; `null`/absent = never ran or unknown (not an all-clear). */
+ scanned_at?: string | null;
+}
+
+export async function getSecuritySummary(repoId: string): Promise<SecuritySummary> {
+ return apiGet<SecuritySummary>(`/api/repos/${repoId}/security/summary`);
+}
+
export async function listSecurityFindings(
repoId: string,
opts: {
diff --git a/packages/api-client/src/types/dead-code.ts b/packages/api-client/src/types/dead-code.ts
index b918ebb84..c5bd7c80b 100644
--- a/packages/api-client/src/types/dead-code.ts
+++ b/packages/api-client/src/types/dead-code.ts
@@ -41,4 +41,6 @@ export interface DeadCodeSummaryResponse {
deletable_lines: number;
total_lines: number;
by_kind: Record<string, number>;
+ /** ISO 8601 UTC; `null`/absent = never ran or unknown (not an all-clear). */
+ analyzed_at?: string | null;
}
diff --git a/packages/core/src/repowise/core/analysis/security_scan.py b/packages/core/src/repowise/core/analysis/security_scan.py
index d2222dd7f..8df2a4232 100644
--- a/packages/core/src/repowise/core/analysis/security_scan.py
+++ b/packages/core/src/repowise/core/analysis/security_scan.py
@@ -1151,6 +1151,9 @@ class SecurityScanner:
),
deduped,
)
+ from repowise.core.persistence.crud.repository import stamp_analysis_ran
+
+ await stamp_analysis_ran(self._session, self._repo_id, "security")
except Exception as exc:
# Pre-migration, the table does not exist yet — silently skip (the
# historical contract for indexing against a not-yet-migrated DB).
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 28c431978..16602607e 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
@@ -20,6 +20,7 @@ from repowise.core.analysis.finding_registry import excluded_types
from ...models import DeadCodeFinding, _new_uuid
from .._shared import _BATCH_SIZE, _finding_file_path
+from ..repository import stamp_analysis_ran
def _dead_code_row_kwargs(finding: Any, repository_id: str) -> dict:
@@ -138,6 +139,7 @@ async def save_dead_code_findings(
batch = findings[i : i + _BATCH_SIZE]
session.add_all(_new_rows(batch, repository_id, null_lines_as_zero=null_lines_as_zero))
await session.flush()
+ await stamp_analysis_ran(session, repository_id, "dead_code")
def _finding_identity(finding: Any) -> tuple:
@@ -217,6 +219,7 @@ async def replace_dead_code_findings(
batch = writable[i : i + _BATCH_SIZE]
session.add_all(_new_rows(batch, repository_id, null_lines_as_zero=null_lines_as_zero))
await session.flush()
+ await stamp_analysis_ran(session, repository_id, "dead_code")
async def get_dead_code_findings(
diff --git a/packages/core/src/repowise/core/persistence/crud/repository.py b/packages/core/src/repowise/core/persistence/crud/repository.py
index 303bcd65d..02f20e101 100644
--- a/packages/core/src/repowise/core/persistence/crud/repository.py
+++ b/packages/core/src/repowise/core/persistence/crud/repository.py
@@ -7,7 +7,7 @@ every public name, so existing imports are unaffected.
from __future__ import annotations
import json
-from datetime import datetime
+from datetime import UTC, datetime
from pathlib import Path
from sqlalchemy import delete, select
@@ -79,7 +79,7 @@ async def upsert_repository(
repo.url = url
repo.default_branch = default_branch
if settings is not None:
- repo.settings_json = json.dumps(settings)
+ repo.settings_json = json.dumps(keep_analysis_ran(repo.settings_json, settings))
# Only advance the stamp when we could read a real commit; never blank
# out a previously recorded one (e.g. a transient non-checkout path).
if resolved_head:
@@ -90,6 +90,44 @@ async def upsert_repository(
return repo
+ANALYSIS_RAN_KEY = "analysis_ran_at"
+
+
+def _settings_dict(raw: str | None) -> dict:
+ try:
+ data = json.loads(raw or "{}")
+ except (TypeError, ValueError):
+ return {}
+ return data if isinstance(data, dict) else {}
+
+
+def keep_analysis_ran(old_json: str | None, new_settings: dict) -> dict:
+ """Carry the stage-completion stamps across a wholesale settings replace."""
+ kept = _settings_dict(old_json).get(ANALYSIS_RAN_KEY)
+ if kept is None or ANALYSIS_RAN_KEY in new_settings:
+ return new_settings
+ return {**new_settings, ANALYSIS_RAN_KEY: kept}
+
+
+async def stamp_analysis_ran(session: AsyncSession, repository_id: str, stage: str) -> None:
+ """Record that *stage* ("security" or "dead_code") just persisted a result.
+
+ Called only on the success path of the stage's own write, so the stamp
+ proves the stage ran, which a completed index job does not.
+ """
+ repo = await session.get(Repository, repository_id)
+ if repo is None:
+ return
+ settings = _settings_dict(repo.settings_json)
+ stamps = settings.get(ANALYSIS_RAN_KEY)
+ if not isinstance(stamps, dict):
+ stamps = {}
+ stamps[stage] = datetime.now(UTC).isoformat()
+ settings[ANALYSIS_RAN_KEY] = stamps
+ repo.settings_json = json.dumps(settings)
+ await session.flush()
+
+
def _read_head_commit(local_path: str) -> str | None:
"""Return the repo's current git HEAD SHA via plain file I/O, or None.
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 5b082d123..6f72bc007 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -2034,8 +2034,10 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
)
# ---- Dead code findings --------------------------------------------------
- if result.dead_code_report and result.dead_code_report.findings:
- await save_dead_code_findings(session, repo_id, result.dead_code_report.findings)
+ # Written even when empty: a run that found nothing must clear the old
+ # open rows, not leave them standing as current findings.
+ if result.dead_code_report is not None:
+ await save_dead_code_findings(session, repo_id, result.dead_code_report.findings or [])
# ---- Documentation drift: findings and resolved references --------------
# Both tables, one savepoint, one run. Written even when the finding list
diff --git a/packages/server/src/repowise/server/routers/dead_code.py b/packages/server/src/repowise/server/routers/dead_code.py
index 02f53ccce..1d7e4d5d6 100644
--- a/packages/server/src/repowise/server/routers/dead_code.py
+++ b/packages/server/src/repowise/server/routers/dead_code.py
@@ -17,6 +17,7 @@ from repowise.server.schemas import (
DeadCodePatchRequest,
DeadCodeSummaryResponse,
)
+from repowise.server.services.analysis_ran_at import dead_code_analyzed_at
router = APIRouter(
tags=["dead-code"],
@@ -112,7 +113,8 @@ async def dead_code_summary(
) -> DeadCodeSummaryResponse:
"""Get aggregate dead code statistics for a repository."""
summary = await crud.get_dead_code_summary(session, repo_id)
- return DeadCodeSummaryResponse(**summary)
+ analyzed_at = await dead_code_analyzed_at(session, repo_id)
+ return DeadCodeSummaryResponse(**summary, analyzed_at=analyzed_at)
@router.patch("/api/dead-code/{finding_id}", response_model=DeadCodeFindingResponse)
diff --git a/packages/server/src/repowise/server/routers/repos.py b/packages/server/src/repowise/server/routers/repos.py
index bb3d30abb..ddbbf369c 100644
--- a/packages/server/src/repowise/server/routers/repos.py
+++ b/packages/server/src/repowise/server/routers/repos.py
@@ -126,7 +126,9 @@ async def create_repo(
if body.settings is not None:
import json as _json
- repo.settings_json = _json.dumps(body.settings)
+ repo.settings_json = _json.dumps(
+ crud.keep_analysis_ran(repo.settings_json, body.settings)
+ )
await repo_session.flush()
response = RepoResponse.from_orm(repo)
else: # pragma: no cover — the row was created two lines above
@@ -289,7 +291,7 @@ async def update_repo(
style = body.settings.get("wiki_style")
if style is not None:
_reject_unknown_style(style, "wiki_style")
- repo.settings_json = json.dumps(body.settings)
+ repo.settings_json = json.dumps(crud.keep_analysis_ran(repo.settings_json, body.settings))
await session.flush()
return RepoResponse.from_orm(repo)
diff --git a/packages/server/src/repowise/server/routers/security.py b/packages/server/src/repowise/server/routers/security.py
index 8c467e674..46395e842 100644
--- a/packages/server/src/repowise/server/routers/security.py
+++ b/packages/server/src/repowise/server/routers/security.py
@@ -11,7 +11,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.analysis.security_scan import source_lines
from repowise.core.persistence.models import Repository, SecurityFinding
from repowise.server.deps import get_db_session, verify_api_key
-from repowise.server.schemas import SecurityFindingResponse
+from repowise.server.schemas import SecurityFindingResponse, SecuritySummaryResponse
+from repowise.server.services.analysis_ran_at import security_scanned_at
from repowise.server.services.security_lines import check_finding_line
router = APIRouter(
@@ -87,6 +88,15 @@ async def list_security_findings(
return responses
[email protected]("/{repo_id}/security/summary", response_model=SecuritySummaryResponse)
+async def security_summary(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session),
+) -> SecuritySummaryResponse:
+ """When the pattern scan last ran; ``scanned_at`` is null when unknown."""
+ return SecuritySummaryResponse(scanned_at=await security_scanned_at(session, repo_id))
+
+
async def _repo_root(session: AsyncSession, repo_id: str) -> Path | None:
"""Live checkout root for *repo_id*, or None when it is not on disk."""
repo = await session.get(Repository, repo_id)
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
index 7255e92d7..42b5d28a0 100644
--- a/packages/server/src/repowise/server/schemas/__init__.py
+++ b/packages/server/src/repowise/server/schemas/__init__.py
@@ -81,6 +81,7 @@ if TYPE_CHECKING:
DeadCodeSummaryResponse,
RepoStatsResponse,
SecurityFindingResponse,
+ SecuritySummaryResponse,
)
from .coupling import (
CouplingEdgeResponse,
@@ -394,6 +395,7 @@ _EXPORTS: dict[str, tuple[str, ...]] = {
"DeadCodeSummaryResponse",
"RepoStatsResponse",
"SecurityFindingResponse",
+ "SecuritySummaryResponse",
),
"coupling": ("CouplingEdgeResponse", "CouplingGraphResponse", "CouplingNodeResponse"),
"decisions": (
@@ -824,6 +826,7 @@ __all__ = [
"SearchRequest",
"SearchResultResponse",
"SecurityFindingResponse",
+ "SecuritySummaryResponse",
"SetActiveProviderRequest",
"SetApiKeyRequest",
"SymbolImportanceComponents",
diff --git a/packages/server/src/repowise/server/schemas/code_quality.py b/packages/server/src/repowise/server/schemas/code_quality.py
index 48c5580ae..37e80173e 100644
--- a/packages/server/src/repowise/server/schemas/code_quality.py
+++ b/packages/server/src/repowise/server/schemas/code_quality.py
@@ -99,6 +99,8 @@ class DeadCodeSummaryResponse(BaseModel):
deletable_lines: int
total_lines: int
by_kind: dict
+ # When dead-code analysis last ran; None = never ran or unknown (not all-clear).
+ analyzed_at: datetime | None = None
class SecurityFindingResponse(BaseModel):
@@ -123,6 +125,11 @@ class SecurityFindingResponse(BaseModel):
found_in_history: bool
+class SecuritySummaryResponse(BaseModel):
+ # When the pattern scan last ran; None = never ran or unknown (not all-clear).
+ scanned_at: datetime | None = None
+
+
class RepoStatsResponse(BaseModel):
file_count: int
symbol_count: int
diff --git a/packages/server/src/repowise/server/services/analysis_ran_at.py b/packages/server/src/repowise/server/services/analysis_ran_at.py
new file mode 100644
index 000000000..2ee33efb6
--- /dev/null
+++ b/packages/server/src/repowise/server/services/analysis_ran_at.py
@@ -0,0 +1,70 @@
+"""When did an analysis last run for a repository.
+
+``None`` means never ran or unknown, and is never replaced by ``now()``.
+
+Two sources, the later wins. The stage stamp (``Repository.settings_json``
+``analysis_ran_at``) is written on the success path of the stage's own write,
+so a run that found nothing still counts and a failed stage does not. Findings
+rows are older evidence that covers indexes written before stamps existed.
+A completed index job is deliberately not used: it proves the pipeline
+finished, not that this best-effort stage did.
+
+Ceiling: a stamp records that the stage persisted, and an incremental update
+stamps after scanning only the changed files.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence.crud.repository import ANALYSIS_RAN_KEY
+from repowise.core.persistence.models import DeadCodeFinding, Repository, SecurityFinding
+
+
+def _aware(dt: datetime | None) -> datetime | None:
+ # SQLite hands back naive datetimes; every writer stores UTC.
+ if dt is not None and dt.tzinfo is None:
+ return dt.replace(tzinfo=UTC)
+ return dt
+
+
+async def _stamp(session: AsyncSession, repo_id: str, stage: str) -> datetime | None:
+ raw = await session.scalar(select(Repository.settings_json).where(Repository.id == repo_id))
+ try:
+ stamps = json.loads(raw or "{}").get(ANALYSIS_RAN_KEY)
+ return _aware(datetime.fromisoformat(stamps[stage]))
+ except (TypeError, ValueError, KeyError, AttributeError):
+ return None
+
+
+def _latest(*times: datetime | None) -> datetime | None:
+ known = [t for t in times if t is not None]
+ return max(known) if known else None
+
+
+async def dead_code_analyzed_at(session: AsyncSession, repo_id: str) -> datetime | None:
+ rows = _aware(
+ await session.scalar(
+ select(func.max(DeadCodeFinding.analyzed_at)).where(
+ DeadCodeFinding.repository_id == repo_id
+ )
+ )
+ )
+ return _latest(rows, await _stamp(session, repo_id, "dead_code"))
+
+
+async def security_scanned_at(session: AsyncSession, repo_id: str) -> datetime | None:
+ # Working-tree rows only: history rows come from a separate on-demand scan.
+ rows = _aware(
+ await session.scalar(
+ select(func.max(SecurityFinding.detected_at)).where(
+ SecurityFinding.repository_id == repo_id,
+ func.coalesce(SecurityFinding.commit_sha, "") == "",
+ )
+ )
+ )
+ return _latest(rows, await _stamp(session, repo_id, "security"))
diff --git a/packages/types/src/dead-code.ts b/packages/types/src/dead-code.ts
index b0badf12f..696460695 100644
--- a/packages/types/src/dead-code.ts
+++ b/packages/types/src/dead-code.ts
@@ -118,4 +118,9 @@ export interface DeadCodeSummary {
deletable_lines: number;
total_lines: number;
by_kind: Record<string, number>;
+ /**
+ * ISO 8601 UTC time dead-code analysis last ran. `null` or absent (older
+ * servers) means never ran or unknown, which is not an all-clear.
+ */
+ analyzed_at?: string | null;
}
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 034c7b0a2..864433d97 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -913,6 +913,7 @@ export interface DeadCodeSummaryResponse {
deletable_lines: number;
total_lines: number;
by_kind: Record<string, unknown>;
+ analyzed_at?: string | null;
}
/** A link from a decision to a governed file or module. */
@@ -3169,6 +3170,10 @@ export interface SecurityFindingResponse {
found_in_history: boolean;
}
+export interface SecuritySummaryResponse {
+ scanned_at?: string | null;
+}
+
export interface SetActiveProviderRequest {
provider: string;
model?: string | null;
diff --git a/packages/types/src/security.ts b/packages/types/src/security.ts
index a46dfbf78..683e466b7 100644
--- a/packages/types/src/security.ts
+++ b/packages/types/src/security.ts
@@ -31,6 +31,15 @@ export interface SecurityFinding {
commit_at: string | null;
}
+/** Run metadata for the pattern scan, served beside the findings list. */
+export interface SecuritySummary {
+ /**
+ * ISO 8601 UTC time the scan last ran. `null` or absent (older servers)
+ * means never ran or unknown, which is not an all-clear.
+ */
+ scanned_at?: string | null;
+}
+
export interface SecurityFindingList {
total: number;
findings: SecurityFinding[];
diff --git a/tests/unit/server/test_dead_code.py b/tests/unit/server/test_dead_code.py
index 351308835..7b6464996 100644
--- a/tests/unit/server/test_dead_code.py
+++ b/tests/unit/server/test_dead_code.py
@@ -160,6 +160,56 @@ async def test_dead_code_summary(client: AsyncClient, app) -> None:
assert "unreachable_file" in data["by_kind"]
+async def test_dead_code_summary_analyzed_at(client: AsyncClient, app) -> None:
+ repo = await create_test_repo(client)
+ url = f"/api/repos/{repo['id']}/dead-code/summary"
+
+ # Never analyzed: unknown, not fabricated.
+ assert (await client.get(url)).json()["analyzed_at"] is None
+
+ await _insert_dead_code(app.state.session_factory, repo["id"])
+ assert (await client.get(url)).json()["analyzed_at"] is not None
+
+
+async def test_dead_code_summary_analyzed_at_zero_findings(client: AsyncClient, app) -> None:
+ """A stage run that found nothing still reports when it ran."""
+ from repowise.core.persistence.crud import replace_dead_code_findings
+ from repowise.core.persistence.database import get_session
+
+ repo = await create_test_repo(client)
+ async with get_session(app.state.session_factory) as session:
+ await replace_dead_code_findings(session, repo["id"], [])
+
+ data = (await client.get(f"/api/repos/{repo['id']}/dead-code/summary")).json()
+ assert data["total_findings"] == 0
+ assert data["analyzed_at"] is not None
+
+
+async def test_completed_job_alone_is_not_analyzed(client: AsyncClient, app) -> None:
+ """A finished index job does not prove the stage ran."""
+ from datetime import UTC, datetime
+
+ from repowise.core.persistence.database import get_session
+ from repowise.core.persistence.models import GenerationJob
+
+ repo = await create_test_repo(client)
+ async with get_session(app.state.session_factory) as session:
+ session.add(
+ GenerationJob(
+ repository_id=repo["id"],
+ status="completed",
+ finished_at=datetime(2026, 1, 2, tzinfo=UTC),
+ )
+ )
+ await session.commit()
+
+ data = (await client.get(f"/api/repos/{repo['id']}/dead-code/summary")).json()
+ assert data["analyzed_at"] is None
+
+
@pytest.mark.asyncio
async def test_analyze_dead_code(client: AsyncClient, monkeypatch) -> None:
# Stub the executor: this test covers the endpoint contract, not the pipeline.
diff --git a/tests/unit/server/test_security.py b/tests/unit/server/test_security.py
index 18a9cc16f..22196a28f 100644
--- a/tests/unit/server/test_security.py
+++ b/tests/unit/server/test_security.py
@@ -46,6 +46,49 @@ async def test_list_security_empty(client: AsyncClient) -> None:
assert resp.json() == []
+async def test_security_summary_scanned_at(client: AsyncClient, app) -> None:
+ repo = await create_test_repo(client)
+ url = f"/api/repos/{repo['id']}/security/summary"
+ assert (await client.get(url)).json() == {"scanned_at": None}
+
+ await _insert(app.state.session_factory, repo["id"], snippet="x")
+ assert (await client.get(url)).json()["scanned_at"] is not None
+
+
+async def test_security_summary_scanned_at_zero_findings(client: AsyncClient, app) -> None:
+ from repowise.core.analysis.security_scan import SecurityScanner
+ from repowise.core.persistence.database import get_session
+
+ repo = await create_test_repo(client)
+ async with get_session(app.state.session_factory) as session:
+ await SecurityScanner(session, repo["id"]).replace_findings({}, ["a.py"])
+ resp = await client.get(f"/api/repos/{repo['id']}/security/summary")
+ assert resp.json()["scanned_at"] is not None
+
+
+async def test_security_settings_patch_keeps_stamp(client: AsyncClient, app) -> None:
+ from repowise.core.persistence.crud import stamp_analysis_ran
+ from repowise.core.persistence.database import get_session
+
+ repo = await create_test_repo(client)
+ async with get_session(app.state.session_factory) as session:
+ await stamp_analysis_ran(session, repo["id"], "security")
+ await client.patch(f"/api/repos/{repo['id']}", json={"settings": {"x": 1}})
+ resp = await client.get(f"/api/repos/{repo['id']}/security/summary")
+ assert resp.json()["scanned_at"] is not None
+
+
+async def test_security_summary_ignores_history_rows(client: AsyncClient, app) -> None:
+ repo = await create_test_repo(client)
+ await _insert(app.state.session_factory, repo["id"], commit_sha="a" * 40)
+ resp = await client.get(f"/api/repos/{repo['id']}/security/summary")
+ assert resp.json()["scanned_at"] is None
+
+
@pytest.mark.asyncio
async def test_line_number_verified_against_live_file(client: AsyncClient, app) -> None:
"""The stored line still holds, so it is served verified."""