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
feat(health): surface per-file process, people, and topology signals (#490)
Raghav Chamadiya0e1ef22e3058
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.mdindex bc317b5dd..42ec7e1d8 100644--- a/docs/CODE_HEALTH.md+++ b/docs/CODE_HEALTH.md@@ -384,6 +384,38 @@ GET /api/repos/{repo_id}/health/files/trend?file_path=path/to/file.pyget_health(targets=["path/to/file.py"])```+## File signals++Every file carries process, people, and topology signals we already compute+during indexing. They answer "should I worry about this file?" with context+the score alone can't, and they surface together on the file's Health tab and+in the health drawer — grouped, captioned, and **silent ("no signal") when the+underlying data is absent** rather than imputed.++| Group | Signal | Means |+|-------|--------|-------|+| Process | Prior defects | Bug-fix commits touching this file in the last ~6 months. `0` is a real, reassuring signal. |+| Process | Change scatter | `change_entropy_pct` (0-100) — how spread out its edits are across commits. High = chaotic change. |+| Process | 90-day churn | Commits and lines added/deleted in the trailing 90 days. |+| Process | Age | How long the file has existed in git history. |+| People | Primary owner | The all-time top committer and their commit share. |+| People | Recent owner | The top committer in the last 90 days. A different name from the primary owner flags a knowledge handoff. |+| Topology | Dependents | How many files depend on this one (graph in-degree). |+| Topology | Dependencies | How many files this one depends on (graph out-degree). |++These are pure surfacing — no new measurement, no scoring. Fetch them directly:++```bash+# REST — embedded in the file-detail aggregate and the drawer breakdown+GET /api/repos/{repo_id}/files/{path} # data.health.signals+GET /api/repos/{repo_id}/health/files/breakdown?file_path=path/to/file.py+```++```python+# MCP — attached to the get_context health block (null fields dropped)+get_context(targets=["path/to/file.py"], include=["health"])+```+## ConfigurationPer-file overrides live in `.repowise/health-rules.json`:diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 3d6bbd92f..3d7408b25 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -66,6 +66,7 @@ analysis/health/├── grading.py # 3 defect-backed bands + NLOC-weighted distribution├── defect_accuracy.py # "does the score find the bugs?" self-validation├── trends.py # snapshot diff, Declining/Predicted alerts, per-file score series+├── signals.py # per-file process/people/topology join (surfacing-only)├── suggestions.py # deterministic refactoring text per biomarker├── config.py # HealthConfig + .repowise/health-rules.json├── models.py # HealthFindingData, HealthFileMetricData, HealthReport@@ -207,6 +208,7 @@ tests/unit/health/ # 99+ tests├── test_scoring_snapshot.py # stability snapshot — locks caps + deductions├── test_health_config.py # .repowise/health-rules.json├── test_trends.py # diff_snapshots, declining/predicted alerts+├── test_signals.py # file_signals join + no-signal/normalization└── test_suggestions.pytests/integration/@@ -560,6 +562,25 @@ Both are state-free; the server serialises `FileTrend` via`_file_trend_to_dict` and embeds it in the file-detail health block, thehealth-breakdown response, and the standalone trend route (§13).+### Per-file signals (`signals.py`)++The same state-free pattern, applied to the git-layer + topology fields we+already persist but only buried inside biomarker detail cards (or omitted+entirely). `file_signals(git_meta, degrees)` joins one `GitMetadata` row with+the file's graph degree into a `FileSignals` grouped as **Process**+(`prior_defect_count`, `change_entropy_pct` normalized 0-100, 90-day line+churn, `age_days`), **People** (recent vs all-time owner + commit share), and+**Topology** (`in_degree` / `out_degree`). No recompute — pure surfacing.++The honesty rule mirrors the trend: a field is `None` only when its *source+row* is absent (no git history → process/people silent; not a graph node →+topology silent), never imputed; a genuine `prior_defect_count` of `0` is kept+as a real signal. The server serialises it via `_file_signals_to_dict` and+embeds it in the file-detail health block and the breakdown response (§13); MCP+attaches a null-dropped copy to the `get_context` health block (§12). Mirrored+as `FileSignals` in `@repowise-dev/types/health`; rendered by the shared+`file-signals-panel.tsx` in both the drawer and the file-page Health tab.+---## 9. Incremental analysis — the `repowise update` path@@ -708,7 +729,8 @@ Defined in `tool_health.py`. Modes:`top_biomarkers`, `coverage_pct`, `branch_coverage_pct`.- `get_context(targets, include=["health"])` — per-file `score`,`max_ccn`, `max_nesting`, `nloc`, `module`, `duplication_pct`, top- 2 biomarkers (each with a `suggestion` string), and coverage block.+ 2 biomarkers (each with a `suggestion` string), a coverage block, and a+ null-dropped `signals` block (process/people/topology — see §8).- `get_overview()` — adds a `code_health` block: avg, repo `band`, hotspot,worst performer, open finding count, and the NLOC-weighted `distribution`.@@ -727,7 +749,7 @@ Every response carries the standard `_meta` envelope via `build_meta()`.| `GET /badge.svg` | self-rendered flat SVG health badge (color + `N.N/10`, no letter) || `GET /badge.json` | Shields.io endpoint-badge payload (`schemaVersion`/`label`/`message`/`color`/`band`) || `GET /files` | per-file metrics |-| `GET /files/breakdown` | one file's metric + score breakdown + findings + suggestions + per-file `trend` |+| `GET /files/breakdown` | one file's metric + score breakdown + findings + suggestions + per-file `trend` + `signals` || `GET /files/trend` | one file's score-over-time series + current delta + `declining` flag (`?file_path=`) || `GET /trend` | repo KPI history + alerts + last-two-snapshot per-file deltas || `GET /findings` | findings list (filterable by biomarker_type, severity, file_path) |@@ -842,6 +864,7 @@ Other perf notes:| `tests/unit/health/test_scoring.py` | Deduction caps, clamping, KPI math || `tests/unit/health/test_scoring_snapshot.py` | **Stability guard** — caps, severity table, biomarker→category mapping, two known fixture scores || `tests/unit/health/test_trends.py` | Declining + predicted alerts, ordering, per-file series + `file_trend` |+| `tests/unit/health/test_signals.py` | `file_signals` join — no-signal vs real-zero, entropy 0-1→0-100, owner handoff || `tests/unit/health/test_suggestions.py` | Suggestion strings keyed correctly || `tests/unit/health/test_health_config.py` | `.repowise/health-rules.json` parsing + glob matching || `tests/integration/test_health_coverage_integration.py` | End-to-end LCOV → analyzer → coverage_gap fires |diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.mdindex dcc1edd37..5e0917bd1 100644--- a/packages/core/src/repowise/core/analysis/health/README.md+++ b/packages/core/src/repowise/core/analysis/health/README.md@@ -72,6 +72,26 @@ Per-file trajectory (same snapshots, the `{path: score}` map):- `file_trend(history, path)` — wraps the series with `current` / `previous`/ `delta` and a `declining` flag (per-file mirror of the alerts above).+## Per-file signals++`signals.py` is the same kind of pure, state-free join: it consolidates the+per-file signals we *already* compute and persist (git history + graph+topology) into one captioned contract — no recompute, no new measurement.++- `file_signals(git_meta, degrees)` returns a `FileSignals` grouped as+ **Process** (`prior_defect_count`, `change_entropy_pct`, 90-day line churn,+ `age_days`), **People** (recent vs all-time owner + commit share), and+ **Topology** (`in_degree` / `out_degree`).+- Honesty rule: a field is `None` ("no signal") only when its *source row* is+ absent — never imputed. A git-tracked file with zero bug-fixes reports `0`+ (a real, reassuring signal); a file with no git history reports `None` for+ the whole process/people group. `change_entropy_pct` is normalized 0-1 → 0-100+ to match the hotspot API contract.++Mirrored as `FileSignals` in `@repowise-dev/types/health`; surfaced in the+dashboard drawer, the file-page Health tab, the `/health/files/breakdown` ++`files/{path}` endpoints, and the MCP `get_context(include=["health"])` block.+## Refactoring suggestions`suggestions.suggestion_for(biomarker_type)` returns the canonical, staticdiff --git a/packages/core/src/repowise/core/analysis/health/signals.py b/packages/core/src/repowise/core/analysis/health/signals.pynew file mode 100644index 000000000..b8cb8e25b--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/signals.py@@ -0,0 +1,119 @@+"""Per-file process / people / topology signals.++Phase 3 of health surfacing: consolidate the per-file signals we already+compute and persist — git history (process + people) and graph topology — into+one captioned contract the file-detail surfaces render. Pure surfacing: no+recompute, no new measurement, no LLM. State-free like :mod:`trends.py` so the+join logic stays unit-testable without a DB — callers pass already-loaded rows+and get a plain dataclass back. The same :func:`file_signals` assembler backs+the dashboard drawer, the file-page Health tab, and the MCP ``get_context``+health block, so the contract is defined once here.++The honesty rule mirrors the per-file trend: a value is ``None`` ("no signal")+only when its *source row* is absent — never imputed. A git-tracked file whose+``prior_defect_count`` is genuinely ``0`` reports ``0`` (a real, reassuring+signal), whereas a file with no git history at all reports ``None`` for the+whole process/people group. Topology degree is ``None`` when the file is not a+graph node.+"""++from __future__ import annotations++from dataclasses import asdict, dataclass+from typing import Protocol+++class GitMetaLike(Protocol):+ """The git-metadata fields the signals view reads (duck-typed).++ Matches ``persistence.models.GitMetadata``; declared as a Protocol so the+ assembler stays free of any ORM import and unit tests can pass a stub.+ """++ prior_defect_count: int | None+ change_entropy_pct: float | None+ lines_added_90d: int | None+ lines_deleted_90d: int | None+ commit_count_90d: int | None+ age_days: int | None+ primary_owner_name: str | None+ primary_owner_commit_pct: float | None+ recent_owner_name: str | None+ recent_owner_commit_pct: float | None+++@dataclass+class FileSignals:+ """A file's process / people / topology signals — all surfacing-only.++ Every field is ``None`` when its source row is absent so consumers render+ an honest "no signal" rather than a misleading zero. ``change_entropy_pct``+ is normalized to 0-100 to match the hotspot API contract (the column is+ stored on a 0-1 scale).+ """++ # Process — how the file changes over time.+ prior_defect_count: int | None+ change_entropy_pct: float | None+ lines_added_90d: int | None+ lines_deleted_90d: int | None+ commit_count_90d: int | None+ age_days: int | None+ # People — who owns it recently vs over its whole life.+ primary_owner_name: str | None+ primary_owner_commit_pct: float | None+ recent_owner_name: str | None+ recent_owner_commit_pct: float | None+ # Topology — how connected it is in the dependency graph.+ in_degree: int | None+ out_degree: int | None++ @property+ def has_any(self) -> bool:+ """True when at least one signal carries data.++ Drives the "no signal" empty state: a file with neither git history+ nor a graph node has nothing to show, so the panel renders nothing+ rather than a wall of dashes.+ """+ return any(v is not None for v in asdict(self).values())+++def _entropy_pct(raw: float | None) -> float | None:+ """Normalize the stored 0-1 change entropy to a 0-100 percentile.++ Mirrors ``routers/git.py::_hotspot_from_row`` so every consumer treats the+ value on the same scale. ``None`` stays ``None`` (no signal).+ """+ if raw is None:+ return None+ return round(raw * 100.0, 1)+++def file_signals(+ git_meta: GitMetaLike | None,+ degrees: dict[str, int] | None,+) -> FileSignals:+ """Assemble a file's :class:`FileSignals` from already-loaded rows.++ *git_meta* is the ``GitMetadata`` row (or ``None`` when the file has no git+ history); *degrees* is the ``{"in_degree", "out_degree"}`` map from+ ``get_node_degree_counts`` (or ``None`` when the file is not a graph node).+ No DB access and no recompute — this is the single join the drawer, the+ file page, and MCP all reuse.+ """+ g = git_meta+ return FileSignals(+ prior_defect_count=g.prior_defect_count if g else None,+ change_entropy_pct=_entropy_pct(g.change_entropy_pct) if g else None,+ lines_added_90d=g.lines_added_90d if g else None,+ lines_deleted_90d=g.lines_deleted_90d if g else None,+ commit_count_90d=g.commit_count_90d if g else None,+ age_days=g.age_days if g else None,+ primary_owner_name=g.primary_owner_name if g else None,+ primary_owner_commit_pct=g.primary_owner_commit_pct if g else None,+ recent_owner_name=g.recent_owner_name if g else None,+ recent_owner_commit_pct=g.recent_owner_commit_pct if g else None,+ in_degree=degrees["in_degree"] if degrees else None,+ out_degree=degrees["out_degree"] if degrees else None,+ )diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.pyindex 92b21afb5..ffaef4a05 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py@@ -9,15 +9,18 @@ dispatch rather than one long body.from __future__ import annotationsimport json+from dataclasses import asdictfrom typing import Anyfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.signals import file_signalsfrom repowise.core.persistence.crud import (get_all_file_metrics,get_community_members,get_cross_community_edges,+ get_git_metadata,get_graph_edges_for_node,get_graph_node,get_graph_nodes_by_ids,@@ -421,6 +424,20 @@ async def _resolve_health("line_coverage_pct": metric.line_coverage_pct,"branch_coverage_pct": metric.branch_coverage_pct,}++ # Process / people / topology signals — the "should I touch this file"+ # context an agent can't get from the score alone. Null fields are dropped+ # so the block stays compact; absent entirely when the file has neither git+ # history nor a graph node.+ git_meta = await get_git_metadata(session, repo_id, file_path)+ node = await get_graph_node(session, repo_id, file_path)+ degrees = (+ await get_node_degree_counts(session, repo_id, file_path) if node is not None else None+ )+ signals = {k: v for k, v in asdict(file_signals(git_meta, degrees)).items() if v is not None}+ if signals:+ health["signals"] = signals+result_data["health"] = healthdiff --git a/packages/server/src/repowise/server/routers/code_health.py b/packages/server/src/repowise/server/routers/code_health.pyindex 00d3d9cd1..8fee0ccc9 100644--- a/packages/server/src/repowise/server/routers/code_health.py+++ b/packages/server/src/repowise/server/routers/code_health.py@@ -26,6 +26,7 @@ from repowise.core.analysis.health.scoring import (biomarker_weight,severity_deduction,)+from repowise.core.analysis.health.signals import FileSignals, file_signalsfrom repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_forfrom repowise.core.analysis.health.trends import (FileTrend,@@ -100,6 +101,43 @@ def _file_trend_to_dict(t: FileTrend) -> dict:}+def _file_signals_to_dict(s: FileSignals) -> dict:+ """Wire shape for ``FileSignals`` (types/health.ts). Each value is null+ when its source row is absent so the UI shows "no signal", never a+ misleading zero. ``change_entropy_pct`` is 0-100 (the column is 0-1)."""+ return {+ "prior_defect_count": s.prior_defect_count,+ "change_entropy_pct": s.change_entropy_pct,+ "lines_added_90d": s.lines_added_90d,+ "lines_deleted_90d": s.lines_deleted_90d,+ "commit_count_90d": s.commit_count_90d,+ "age_days": s.age_days,+ "primary_owner_name": s.primary_owner_name,+ "primary_owner_commit_pct": s.primary_owner_commit_pct,+ "recent_owner_name": s.recent_owner_name,+ "recent_owner_commit_pct": s.recent_owner_commit_pct,+ "in_degree": s.in_degree,+ "out_degree": s.out_degree,+ }+++async def _load_file_signals(session: AsyncSession, repo_id: str, file_path: str) -> FileSignals:+ """Join git metadata + graph degree for one file (read-only, no recompute).++ Degree is read only when the file is a graph node so topology stays "no+ signal" for files absent from the graph, rather than reporting a spurious+ zero. Shared by the drawer breakdown and the file-detail aggregate.+ """+ git_meta = await crud.get_git_metadata(session, repo_id, file_path)+ node = await crud.get_graph_node(session, repo_id, file_path)+ degrees = (+ await crud.get_node_degree_counts(session, repo_id, file_path)+ if node is not None+ else None+ )+ return file_signals(git_meta, degrees)++async def _attach_symbol_ids(session: AsyncSession, repo_id: str, finding_dicts: list[dict]) -> list[dict]:@@ -608,6 +646,7 @@ async def file_score_breakdown("findings": finding_dicts,"suggestions": {b: _suggestion_for(b) for b in {f.biomarker_type for f in findings}},"trend": _file_trend_to_dict(file_trend(snapshots, file_path)),+ "signals": _file_signals_to_dict(await _load_file_signals(session, repo_id, file_path)),}diff --git a/packages/server/src/repowise/server/routers/files.py b/packages/server/src/repowise/server/routers/files.pyindex 7490d3cdf..e8f1d0f94 100644--- a/packages/server/src/repowise/server/routers/files.py+++ b/packages/server/src/repowise/server/routers/files.py@@ -17,6 +17,7 @@ from fastapi import APIRouter, Depends, HTTPExceptionfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.signals import file_signalsfrom repowise.core.analysis.health.trends import file_trendfrom repowise.core.persistence import crudfrom repowise.core.persistence.decision_graph import get_governing_decisions@@ -24,6 +25,7 @@ from repowise.core.persistence.models import DeadCodeFinding, Page, WikiSymbolfrom repowise.server.deps import get_db_session, verify_api_keyfrom repowise.server.mcp_server._graph_utils import parse_community_meta, percentile_rankfrom repowise.server.routers.code_health import (+ _file_signals_to_dict,_file_trend_to_dict,_finding_to_dict,_metric_to_dict,@@ -91,6 +93,13 @@ async def file_detail(git_meta = await crud.get_git_metadata(session, repo_id, file_path)metrics = await crud.get_health_metrics(session, repo_id, file_paths=[file_path])metric = metrics[0] if metrics else None+ # Degree is read once (graph node only) and shared by the health-signals+ # block below and the graph-context block further down.+ degrees = (+ await crud.get_node_degree_counts(session, repo_id, file_path)+ if node is not None+ else None+ )if node is None and git_meta is None and metric is None:raise HTTPException(status_code=404, detail=f"File not indexed: {file_path}")@@ -128,6 +137,7 @@ async def file_detail("breakdown": _score_breakdown_from_findings(findings) if findings else None,"findings": [_finding_to_dict(f) for f in findings],"trend": _file_trend_to_dict(file_trend(snapshots, file_path)),+ "signals": _file_signals_to_dict(file_signals(git_meta, degrees)),}# --- Git history ------------------------------------------------------@@ -165,7 +175,7 @@ async def file_detail(graph: dict | None = Noneif node is not None:all_files = await crud.get_all_file_metrics(session, repo_id)- degrees = await crud.get_node_degree_counts(session, repo_id, file_path)+ assert degrees is not None # node is not None here, so degrees was loadedmeta = parse_community_meta(node)edges = await crud.get_graph_edges_for_node(session, repo_id, file_path, direction="both", limit=40diff --git a/packages/types/src/files.ts b/packages/types/src/files.tsindex 91bb27c13..b152b159d 100644--- a/packages/types/src/files.ts+++ b/packages/types/src/files.ts@@ -5,7 +5,7 @@*/import type { CoChangePartner, FileAuthor, Hotspot, SignificantCommit } from "./git.js";-import type { FileHealthTrend } from "./health.js";+import type { FileHealthTrend, FileSignals } from "./health.js";export interface FileWikiPageRef {id: string;@@ -76,6 +76,8 @@ export interface FileDetailHealth {findings: FileHealthFinding[];/** Per-file score trajectory; `points` empty when history is thin. */trend: FileHealthTrend | null;+ /** Process / people / topology signals; null fields read "no signal". */+ signals: FileSignals | null;}export interface FileAgentProvenance {diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 53e74ba44..a035307bc 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -243,6 +243,39 @@ export interface HealthFileBreakdownResponse {suggestions: Record<string, string>;/** Per-file score trajectory (silent when history is thin). */trend?: FileHealthTrend | null;+ /** Process / people / topology signals (null fields read "no signal"). */+ signals?: FileSignals | null;+}++/* ------------------------------------------------------------------ *+ * Per-file signals (process / people / topology)+ * ------------------------------------------------------------------ */++/**+ * The per-file signals we already compute and persist, consolidated into one+ * captioned contract. Every field is `null` when its source row is absent so+ * consumers render an honest "no signal" rather than a misleading zero — a+ * git-tracked file with no bug-fixes reports `prior_defect_count: 0`, whereas+ * a file with no git history reports `null` for the whole process/people group.+ * `change_entropy_pct` is on a 0-100 scale (the stored column is 0-1).+ * Topology degree is `null` when the file is not a graph node.+ */+export interface FileSignals {+ // Process — how the file changes over time.+ prior_defect_count: number | null;+ change_entropy_pct: number | null;+ lines_added_90d: number | null;+ lines_deleted_90d: number | null;+ commit_count_90d: number | null;+ age_days: number | null;+ // People — who owns it recently vs over its whole life.+ primary_owner_name: string | null;+ primary_owner_commit_pct: number | null;+ recent_owner_name: string | null;+ recent_owner_commit_pct: number | null;+ // Topology — how connected it is in the dependency graph.+ in_degree: number | null;+ out_degree: number | null;}/* ------------------------------------------------------------------ *diff --git a/packages/ui/__tests__/health/file-signals-panel.test.tsx b/packages/ui/__tests__/health/file-signals-panel.test.tsxnew file mode 100644index 000000000..52be8f732--- /dev/null+++ b/packages/ui/__tests__/health/file-signals-panel.test.tsx@@ -0,0 +1,86 @@+import { describe, it, expect } from "vitest";+import { render, screen } from "@testing-library/react";+import type { FileSignals } from "@repowise-dev/types/health";+import { FileSignalsPanel } from "../../src/health/file-signals-panel.js";++function sig(partial: Partial<FileSignals>): FileSignals {+ return {+ prior_defect_count: null,+ change_entropy_pct: null,+ lines_added_90d: null,+ lines_deleted_90d: null,+ commit_count_90d: null,+ age_days: null,+ primary_owner_name: null,+ primary_owner_commit_pct: null,+ recent_owner_name: null,+ recent_owner_commit_pct: null,+ in_degree: null,+ out_degree: null,+ ...partial,+ };+}++describe("FileSignalsPanel", () => {+ it("renders populated process / people / topology signals", () => {+ render(+ <FileSignalsPanel+ signals={sig({+ prior_defect_count: 3,+ commit_count_90d: 7,+ lines_added_90d: 120,+ lines_deleted_90d: 40,+ primary_owner_name: "Ada",+ primary_owner_commit_pct: 0.62,+ in_degree: 17,+ out_degree: 4,+ })}+ />,+ );+ expect(screen.getByText("Process")).toBeInTheDocument();+ expect(screen.getByText("People")).toBeInTheDocument();+ expect(screen.getByText("Topology")).toBeInTheDocument();+ expect(screen.getByText(/3 bug-fixes/)).toBeInTheDocument();+ expect(screen.getByText(/7 commits · \+120 \/ −40/)).toBeInTheDocument();+ expect(screen.getByText(/Ada \(62%\)/)).toBeInTheDocument();+ expect(screen.getByText(/17 files depend on this/)).toBeInTheDocument();+ expect(screen.getByText(/depends on 4 files/)).toBeInTheDocument();+ });++ it("reports zero bug-fixes as a real signal, not 'No signal'", () => {+ render(<FileSignalsPanel signals={sig({ prior_defect_count: 0, commit_count_90d: 2 })} />);+ expect(screen.getByText("No bug-fixes")).toBeInTheDocument();+ });++ it("shows 'No signal' for absent fields when some are present", () => {+ render(<FileSignalsPanel signals={sig({ in_degree: 5, out_degree: 0 })} />);+ // Topology present, process/people absent.+ expect(screen.getByText(/5 files depend on this/)).toBeInTheDocument();+ expect(screen.getAllByText("No signal").length).toBeGreaterThan(0);+ });++ it("flags an owner handoff when recent owner differs from primary", () => {+ render(+ <FileSignalsPanel+ signals={sig({+ primary_owner_name: "Ada",+ primary_owner_commit_pct: 0.7,+ recent_owner_name: "Grace",+ recent_owner_commit_pct: 0.5,+ })}+ />,+ );+ expect(screen.getByText(/differs from primary/)).toBeInTheDocument();+ expect(screen.getByText(/Grace \(50%\)/)).toBeInTheDocument();+ });++ it("renders nothing when signals is null", () => {+ const { container } = render(<FileSignalsPanel signals={null} />);+ expect(container).toBeEmptyDOMElement();+ });++ it("renders nothing when every signal is absent", () => {+ const { container } = render(<FileSignalsPanel signals={sig({})} />);+ expect(container).toBeEmptyDOMElement();+ });+});diff --git a/packages/ui/src/files/file-health-tab.tsx b/packages/ui/src/files/file-health-tab.tsxindex bef203f64..7abb850a3 100644--- a/packages/ui/src/files/file-health-tab.tsx+++ b/packages/ui/src/files/file-health-tab.tsx@@ -8,6 +8,7 @@ import { BiomarkerDetails, type BiomarkerDetailsRecord } from "../health/biomarkimport { biomarkerInfo, biomarkerLabel, CATEGORY_LABEL } from "../health/biomarker-glossary";import { SEVERITY_CHIP, SEVERITY_LABEL, scoreBadgeClass, type Severity } from "../health/tokens";import { FileTrendChart } from "../health/file-trend-chart";+import { FileSignalsPanel } from "../health/file-signals-panel";import type { FileDetailHealth, FunctionBlameRow } from "@repowise-dev/types/files";export type FindingStatus = "open" | "acknowledged" | "resolved" | "false_positive";@@ -46,7 +47,7 @@ export function FileHealthTab({}: FileHealthTabProps) {const [statusOverride, setStatusOverride] = useState<Record<string, FindingStatus>>({});const [savingId, setSavingId] = useState<string | null>(null);- const { metric, breakdown, findings, trend } = health;+ const { metric, breakdown, findings, trend, signals } = health;if (!metric && findings.length === 0) {return (@@ -110,6 +111,8 @@ export function FileHealthTab({{trend && trend.points.length >= 2 && <FileTrendChart trend={trend} />}+ <FileSignalsPanel signals={signals} />+{breakdown && (<section className="space-y-2"><h3 className="text-xs font-medium uppercase tracking-wider text-[var(--color-text-tertiary)]">diff --git a/packages/ui/src/health/file-signals-panel.tsx b/packages/ui/src/health/file-signals-panel.tsxnew file mode 100644index 000000000..f14be41c1--- /dev/null+++ b/packages/ui/src/health/file-signals-panel.tsx@@ -0,0 +1,189 @@+"use client";++import type { FileSignals } from "@repowise-dev/types/health";++export interface FileSignalsPanelProps {+ signals: FileSignals | null | undefined;+ /** Hide the section heading (e.g. when the host supplies its own). */+ hideHeading?: boolean;+}++/**+ * The per-file process / people / topology signals, grouped and captioned.+ * Pure surfacing of data we already compute — no scoring, no recompute. Each+ * value carries a one-line plain-language caption; an absent value reads "no+ * signal" rather than a misleading zero (the contract is null-on-absent, see+ * `FileSignals`). The whole panel is silent when the file has neither git+ * history nor a graph node. Shared by the dashboard drawer and the file-page+ * Health tab so both render identically.+ */+export function FileSignalsPanel({ signals, hideHeading = false }: FileSignalsPanelProps) {+ if (!signals || !hasAnySignal(signals)) return null;++ const ownerHandoff =+ signals.recent_owner_name != null &&+ signals.primary_owner_name != null &&+ signals.recent_owner_name !== signals.primary_owner_name;++ return (+ <section className="space-y-2">+ {!hideHeading && (+ <h3 className="text-xs font-medium uppercase tracking-wider text-[var(--color-text-tertiary)]">+ Signals+ </h3>+ )}+ <div className="grid gap-3 sm:grid-cols-3">+ <Group label="Process">+ <Row+ value={priorDefectValue(signals.prior_defect_count)}+ caption="bug-fix commits in the last 6 months"+ present={signals.prior_defect_count != null}+ />+ <Row+ value={+ signals.change_entropy_pct == null+ ? null+ : `${Math.round(signals.change_entropy_pct)}th pct`+ }+ caption="change scatter — how spread out its edits are"+ present={signals.change_entropy_pct != null}+ />+ <Row+ value={velocityValue(signals)}+ caption="commits and line churn in the last 90 days"+ present={signals.commit_count_90d != null}+ />+ <Row+ value={signals.age_days == null ? null : `${formatAge(signals.age_days)} old`}+ caption="first seen in git history"+ present={signals.age_days != null}+ />+ </Group>++ <Group label="People">+ <Row+ value={ownerValue(signals.primary_owner_name, signals.primary_owner_commit_pct)}+ caption="primary owner (all-time)"+ present={signals.primary_owner_name != null}+ />+ <Row+ value={+ signals.recent_owner_name == null+ ? "No commits (90d)"+ : ownerValue(signals.recent_owner_name, signals.recent_owner_commit_pct)+ }+ caption={+ ownerHandoff ? "recent owner (90d) — differs from primary" : "recent owner (90d)"+ }+ present={signals.recent_owner_name != null}+ emphasize={ownerHandoff}+ />+ </Group>++ <Group label="Topology">+ <Row+ value={+ signals.in_degree == null+ ? null+ : `${signals.in_degree} ${plural(signals.in_degree, "file")} depend on this`+ }+ caption="inbound dependents"+ present={signals.in_degree != null}+ />+ <Row+ value={+ signals.out_degree == null+ ? null+ : `depends on ${signals.out_degree} ${plural(signals.out_degree, "file")}`+ }+ caption="outbound dependencies"+ present={signals.out_degree != null}+ />+ </Group>+ </div>+ </section>+ );+}++function hasAnySignal(s: FileSignals): boolean {+ return (+ s.prior_defect_count != null ||+ s.change_entropy_pct != null ||+ s.commit_count_90d != null ||+ s.age_days != null ||+ s.primary_owner_name != null ||+ s.recent_owner_name != null ||+ s.in_degree != null ||+ s.out_degree != null+ );+}++function priorDefectValue(n: number | null): string | null {+ if (n == null) return null;+ return n === 0 ? "No bug-fixes" : `${n} bug-fix${n === 1 ? "" : "es"}`;+}++function velocityValue(s: FileSignals): string | null {+ if (s.commit_count_90d == null) return null;+ const added = s.lines_added_90d ?? 0;+ const deleted = s.lines_deleted_90d ?? 0;+ return `${s.commit_count_90d} ${plural(s.commit_count_90d, "commit")} · +${added} / −${deleted}`;+}++function ownerValue(name: string | null, pct: number | null): string | null {+ if (name == null) return null;+ return pct == null ? name : `${name} (${Math.round(pct * 100)}%)`;+}++function formatAge(days: number): string {+ if (days >= 365) {+ const years = days / 365;+ return `${years.toFixed(years >= 10 ? 0 : 1)}y`;+ }+ if (days >= 30) return `${Math.round(days / 30)}mo`;+ return `${days}d`;+}++function plural(n: number, word: string): string {+ return n === 1 ? word : `${word}s`;+}++function Group({ label, children }: { label: string; children: React.ReactNode }) {+ return (+ <div className="rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] p-3 space-y-2">+ <p className="text-[10px] font-semibold uppercase tracking-wider text-[var(--color-text-tertiary)]">+ {label}+ </p>+ <div className="space-y-2">{children}</div>+ </div>+ );+}++function Row({+ value,+ caption,+ present,+ emphasize = false,+}: {+ value: string | null;+ caption: string;+ present: boolean;+ emphasize?: boolean;+}) {+ return (+ <div>+ <p+ className={`text-xs font-semibold tabular-nums ${+ present+ ? emphasize+ ? "text-[var(--color-accent-primary)]"+ : "text-[var(--color-text-primary)]"+ : "text-[var(--color-text-tertiary)]"+ }`}+ >+ {present ? value : "No signal"}+ </p>+ <p className="text-[10px] leading-tight text-[var(--color-text-tertiary)]">{caption}</p>+ </div>+ );+}diff --git a/packages/ui/src/health/health-file-drawer.tsx b/packages/ui/src/health/health-file-drawer.tsxindex 385078756..819b4e995 100644--- a/packages/ui/src/health/health-file-drawer.tsx+++ b/packages/ui/src/health/health-file-drawer.tsx@@ -7,6 +7,7 @@ import { InfoTip } from "../shared/info-tip";import { biomarkerLabel, biomarkerInfo, CATEGORY_LABEL } from "./biomarker-glossary";import { BiomarkerDetails, type BiomarkerDetailsRecord } from "./biomarker-details";import { ScoreBreakdown, type ScoreBreakdownCategory } from "./score-breakdown";+import { FileSignalsPanel } from "./file-signals-panel";import { Sparkline } from "./sparkline";import {SEVERITY_CHIP,@@ -16,7 +17,7 @@ import {scoreBadgeClass,type Severity,} from "./tokens";-import type { FileHealthTrend } from "@repowise-dev/types/health";+import type { FileHealthTrend, FileSignals } from "@repowise-dev/types/health";export interface HealthDrawerFinding {id: string;@@ -57,6 +58,8 @@ export interface HealthFileDrawerProps {suggestions?: Record<string, string>;/** Per-file score trajectory; renders a compact sparkline when populated. */trend?: FileHealthTrend | null;+ /** Process / people / topology signals; the panel is silent when absent. */+ signals?: FileSignals | null;fileViewHref?: string;/** Build a per-line deep-link from the drawer's function:line span. */fileViewHrefFor?: ((lineStart: number) => string) | undefined;@@ -85,6 +88,7 @@ export function HealthFileDrawer({findings = [],suggestions = {},trend,+ signals,fileViewHref,fileViewHrefFor,permalinkHref,@@ -182,6 +186,8 @@ export function HealthFileDrawer({</div>) : null}+ <FileSignalsPanel signals={signals} />+{fileViewHref ? (<ahref={fileViewHref}diff --git a/packages/ui/src/health/index.ts b/packages/ui/src/health/index.tsindex 9bac89b35..f0c81e660 100644--- a/packages/ui/src/health/index.ts+++ b/packages/ui/src/health/index.ts@@ -20,6 +20,7 @@ export * from "./health-tabs";export * from "./page-chrome";export * from "./trend-chart";export * from "./file-trend-chart";+export * from "./file-signals-panel";export * from "./risk-coverage-scatter";export * from "./impact-effort-quadrant";export * from "./health-file-drawer";diff --git a/packages/web/src/components/health/health-file-drawer-host.tsx b/packages/web/src/components/health/health-file-drawer-host.tsxindex 0f6fc9879..20f4cc7f3 100644--- a/packages/web/src/components/health/health-file-drawer-host.tsx+++ b/packages/web/src/components/health/health-file-drawer-host.tsx@@ -37,6 +37,7 @@ export function HealthFileDrawerHost({findings={data?.findings ?? []}suggestions={data?.suggestions ?? {}}trend={data?.trend ?? null}+ signals={data?.signals ?? null}permalinkHref={filePageHref ? `${filePageHref}?tab=health` : undefined}fileViewHref={filePageHref}fileViewHrefFor={diff --git a/tests/unit/health/test_signals.py b/tests/unit/health/test_signals.pynew file mode 100644index 000000000..88405874f--- /dev/null+++ b/tests/unit/health/test_signals.py@@ -0,0 +1,98 @@+"""Tests for ``health/signals.py`` — the per-file signals join.++The assembler is a pure surfacing layer: it must never impute a value, must+normalize change entropy to 0-100, and must report "no signal" (``None``) only+when a source row is genuinely absent.+"""++from __future__ import annotations++from dataclasses import dataclass++from repowise.core.analysis.health.signals import FileSignals, file_signals+++@dataclass+class _Git:+ """Stub mirroring the GitMetadata fields the signals view reads."""++ prior_defect_count: int | None = 0+ change_entropy_pct: float | None = 0.0+ lines_added_90d: int | None = 0+ lines_deleted_90d: int | None = 0+ commit_count_90d: int | None = 0+ age_days: int | None = 0+ primary_owner_name: str | None = None+ primary_owner_commit_pct: float | None = None+ recent_owner_name: str | None = None+ recent_owner_commit_pct: float | None = None+++def test_no_git_and_no_degrees_is_all_none():+ s = file_signals(None, None)+ assert isinstance(s, FileSignals)+ assert all(v is None for v in s.__dict__.values())+ assert s.has_any is False+++def test_present_git_surfaces_real_values_including_zero():+ git = _Git(+ prior_defect_count=3,+ lines_added_90d=120,+ lines_deleted_90d=40,+ commit_count_90d=7,+ age_days=410,+ primary_owner_name="Ada",+ primary_owner_commit_pct=0.62,+ )+ s = file_signals(git, None)+ assert s.prior_defect_count == 3+ assert s.lines_added_90d == 120+ assert s.lines_deleted_90d == 40+ assert s.commit_count_90d == 7+ assert s.age_days == 410+ assert s.primary_owner_name == "Ada"+ assert s.primary_owner_commit_pct == 0.62+ # No graph node → topology is silent, not zero.+ assert s.in_degree is None+ assert s.out_degree is None+ assert s.has_any is True+++def test_zero_prior_defects_is_a_real_signal_not_none():+ # A git-tracked file with no bug-fixes reports 0 (reassuring), not None.+ s = file_signals(_Git(prior_defect_count=0), None)+ assert s.prior_defect_count == 0+ assert s.has_any is True+++def test_change_entropy_normalized_to_0_100():+ s = file_signals(_Git(change_entropy_pct=0.734), None)+ assert s.change_entropy_pct == 73.4+++def test_change_entropy_none_stays_none():+ s = file_signals(_Git(change_entropy_pct=None), None)+ assert s.change_entropy_pct is None+++def test_recent_owner_can_differ_from_primary():+ git = _Git(+ primary_owner_name="Ada",+ primary_owner_commit_pct=0.7,+ recent_owner_name="Grace",+ recent_owner_commit_pct=0.5,+ )+ s = file_signals(git, None)+ assert s.primary_owner_name == "Ada"+ assert s.recent_owner_name == "Grace"+++def test_degrees_surfaced_when_node_present():+ s = file_signals(None, {"in_degree": 17, "out_degree": 3})+ assert s.in_degree == 17+ assert s.out_degree == 3+ # No git history → process/people stay silent.+ assert s.prior_defect_count is None+ assert s.primary_owner_name is None+ assert s.has_any is Truediff --git a/tests/unit/server/test_health_badge.py b/tests/unit/server/test_health_badge.pyindex e134b9614..2e150ca0e 100644--- a/tests/unit/server/test_health_badge.py+++ b/tests/unit/server/test_health_badge.py@@ -3,9 +3,11 @@ per-file trend serializer's wire shape."""from __future__ import annotations+from repowise.core.analysis.health.signals import file_signalsfrom repowise.core.analysis.health.trends import FileTrend, FileTrendPointfrom repowise.server.routers.code_health import (_badge_fields,+ _file_signals_to_dict,_file_trend_to_dict,_render_badge_svg,)@@ -76,3 +78,51 @@ def test_file_trend_to_dict_serializes_points() -> None:assert d["points"][1]["taken_at"] is Noneassert d["delta"] == -1.5assert d["declining"] is True+++class _Git:+ """Stub git-metadata row for the signals serializer."""++ def __init__(self, **kw: object) -> None:+ defaults = dict(+ prior_defect_count=0,+ change_entropy_pct=0.0,+ lines_added_90d=0,+ lines_deleted_90d=0,+ commit_count_90d=0,+ age_days=0,+ primary_owner_name=None,+ primary_owner_commit_pct=None,+ recent_owner_name=None,+ recent_owner_commit_pct=None,+ )+ defaults.update(kw)+ self.__dict__.update(defaults)+++def test_file_signals_to_dict_no_data_all_null() -> None:+ d = _file_signals_to_dict(file_signals(None, None))+ assert d == {+ "prior_defect_count": None,+ "change_entropy_pct": None,+ "lines_added_90d": None,+ "lines_deleted_90d": None,+ "commit_count_90d": None,+ "age_days": None,+ "primary_owner_name": None,+ "primary_owner_commit_pct": None,+ "recent_owner_name": None,+ "recent_owner_commit_pct": None,+ "in_degree": None,+ "out_degree": None,+ }+++def test_file_signals_to_dict_populated_and_normalized() -> None:+ git = _Git(prior_defect_count=2, change_entropy_pct=0.5, primary_owner_name="Ada")+ d = _file_signals_to_dict(file_signals(git, {"in_degree": 9, "out_degree": 4}))+ assert d["prior_defect_count"] == 2+ assert d["change_entropy_pct"] == 50.0 # 0-1 column → 0-100 wire+ assert d["primary_owner_name"] == "Ada"+ assert d["in_degree"] == 9+ assert d["out_degree"] == 4