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(health): surface per-file process, people, and topology signals (#490)

Raghav Chamadiya0e1ef22e3058
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.md
index 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.py
get_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"])
+```
+
## Configuration
Per-file overrides live in `.repowise/health-rules.json`:
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 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.py
tests/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, the
health-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.md
index 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, static
diff --git a/packages/core/src/repowise/core/analysis/health/signals.py b/packages/core/src/repowise/core/analysis/health/signals.py
new file mode 100644
index 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.py
index 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 annotations
import json
+from dataclasses import asdict
from typing import Any
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.health.signals import file_signals
from 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"] = health
diff --git a/packages/server/src/repowise/server/routers/code_health.py b/packages/server/src/repowise/server/routers/code_health.py
index 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_signals
from repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_for
from 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.py
index 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, HTTPException
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.health.signals import file_signals
from repowise.core.analysis.health.trends import file_trend
from repowise.core.persistence import crud
from repowise.core.persistence.decision_graph import get_governing_decisions
@@ -24,6 +25,7 @@ from repowise.core.persistence.models import DeadCodeFinding, Page, WikiSymbol
from repowise.server.deps import get_db_session, verify_api_key
from repowise.server.mcp_server._graph_utils import parse_community_meta, percentile_rank
from 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 = None
if 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 loaded
meta = parse_community_meta(node)
edges = await crud.get_graph_edges_for_node(
session, repo_id, file_path, direction="both", limit=40
diff --git a/packages/types/src/files.ts b/packages/types/src/files.ts
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
index 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/biomark
import { 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.tsx
new file mode 100644
index 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.tsx
index 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 ? (
<a
href={fileViewHref}
diff --git a/packages/ui/src/health/index.ts b/packages/ui/src/health/index.ts
index 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.tsx
index 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.py
new file mode 100644
index 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 True
diff --git a/tests/unit/server/test_health_badge.py b/tests/unit/server/test_health_badge.py
index 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_signals
from repowise.core.analysis.health.trends import FileTrend, FileTrendPoint
from 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 None
assert d["delta"] == -1.5
assert 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