Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(health): let a file at the score floor show movement, and stop the trend hiding improvements (#1364)
Raghav Chamadiya63715d99c0e4
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex a077337ac..8fb647d74 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -245,7 +245,12 @@ The returned report rides on `PipelineResult.health_report`. Then`core/pipeline/persist.py` writes it in one session: `save_health_metrics`,`save_health_findings` (only when there are findings), and a`save_health_snapshot` carrying the three KPIs plus a `{path: score}` map for-trend tracking (rolling 50-row window per repo).+trend tracking (rolling 50-row window per repo), and a second+`{path: total_deduction}` map covering only the files whose score is held at+the floor. Both maps come from `trends.snapshot_file_maps`, which the other two+snapshot writers (`repowise health` and `repowise upgrade`) also call — a repo+whose writers disagreed would get a history whose depth changed depending on+which command last wrote it.---@@ -564,6 +569,23 @@ 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).+#### Below the floor++The stored score is clamped to `[SCORE_FLOOR, SCORE_MAX]`, so files 12.9 and+9.1 points deep both persist as `1.0` and their series is flat however much of+the work gets done. The second snapshot map (`per_file_deductions_json`) keeps+the pre-clamp deduction for exactly those files — for every other file the+deduction is `SCORE_MAX - score`, so there is nothing to store.++Each point therefore carries `unclamped_score` alongside `score`:+`SCORE_MAX - deduction` where the snapshot recorded one, and `score` otherwise.+It is the series `_file_declining` runs on, so `declining` describes the line+that can actually move, and a file getting worse *below* the floor now trips it.++Snapshots written before this existed have no deduction map. Their floored+files stay flat, which is correct — the depth was never measured, and inventing+one would be worse than a flat line.+### Per-file signals (`signals.py`)The same state-free pattern, applied to the git-layer + topology fields wediff --git a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py b/packages/cli/src/repowise/cli/commands/health_cmd/persist.pyindex 6cdb77a0b..bedbcaf89 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/persist.py@@ -69,6 +69,7 @@ def _persist_health(repo_path: object, *, report: object) -> None:returns rather than crashing the CLI."""from repowise.cli.helpers import get_db_url_for_repo+ from repowise.core.analysis.health.trends import snapshot_file_mapsfrom repowise.core.persistence import (create_engine,create_session_factory,@@ -103,6 +104,7 @@ def _persist_health(repo_path: object, *, report: object) -> None:kpis = getattr(report, "kpis", {}) or {}metrics = getattr(report, "metrics", []) or []try:+ scores_map, deductions_map = snapshot_file_maps(metrics, findings)await save_health_snapshot(session,repo_id,@@ -110,7 +112,8 @@ def _persist_health(repo_path: object, *, report: object) -> None:average_health=float(kpis.get("average_health", 10.0)),worst_performer_path=kpis.get("worst_performer_path"),worst_performer_score=kpis.get("worst_performer_score"),- per_file_scores={m.file_path: round(float(m.score), 2) for m in metrics},+ per_file_scores=scores_map,+ per_file_deductions=deductions_map,)except Exception as exc:console.print(f"[yellow]Snapshot write skipped: {exc}[/yellow]")diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.pyindex 544f2c051..32b734d84 100644--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py@@ -341,6 +341,7 @@ async def _run_upgrade(# biomarkers land — otherwise the upgrade leaves the health tables frozen# at the fast index's ESSENTIAL state. Mirrors what `init` / `update` do.try:+ from repowise.core.analysis.health.trends import snapshot_file_mapsfrom repowise.core.persistence.crud import (save_health_findings,save_health_metrics,@@ -362,6 +363,9 @@ async def _run_upgrade(await save_health_findings(session, repo_id, health_report.findings)kpis = health_report.kpis or {}with contextlib.suppress(Exception): # snapshot is best-effort+ scores_map, deductions_map = snapshot_file_maps(+ health_report.metrics or [], health_report.findings or []+ )await save_health_snapshot(session,repo_id,@@ -369,10 +373,8 @@ async def _run_upgrade(average_health=float(kpis.get("average_health", 10.0)),worst_performer_path=kpis.get("worst_performer_path"),worst_performer_score=kpis.get("worst_performer_score"),- per_file_scores={- m.file_path: round(float(m.score), 2)- for m in health_report.metrics or []- },+ per_file_scores=scores_map,+ per_file_deductions=deductions_map,)console.print(f"Code health recomputed at FULL tier: "diff --git a/packages/core/alembic/versions/0046_graph_edge_hint_source.py b/packages/core/alembic/versions/0046_graph_edge_hint_source.pydeleted file mode 100644index 25e1704bf..000000000--- a/packages/core/alembic/versions/0046_graph_edge_hint_source.py+++ /dev/null@@ -1,51 +0,0 @@-"""Persist ``graph_edges.hint_source`` so cohesion survives rehydration.--Several resolver passes synthesise file-level edges to record that two files-belong to one compilation unit — Go package siblings, JVM same-package classes,-C# ``partial`` fragments and global usings, Swift same-module files, and the-C/C++ header/implementation pair. Each pass stamps ``hint_source`` on the edge.--Cycle detection reads that stamp to drop those edges: files in one compilation-unit cannot depend on each other, so counting them turns every cohesive package-into a fabricated import cycle (issue #1294).--The stamp only lived in the in-memory NetworkX graph. Anything running against a-graph rehydrated from ``graph_edges`` — the health engine's break-cycle detector,-incremental updates — saw cohesion edges as ordinary imports and re-reported the-false cycles. Persisting the column closes that gap.--Nullable with no default: NULL means "a real import/using directive", which is-the correct reading for every pre-existing row.--``init_db``'s additive schema reconciler picks the column up from the model for-local SQLite stores that never run Alembic; this migration covers the managed-Postgres ones. The two converge on the same shape.--Revision ID: 0046-Revises: 0045-Create Date: 2026-08-08-"""--from __future__ import annotations--from collections.abc import Sequence--import sqlalchemy as sa-from alembic import op--# revision identifiers-revision: str = "0046"-down_revision: str | None = "0045"-branch_labels: str | Sequence[str] | None = None-depends_on: str | Sequence[str] | None = None---def upgrade() -> None:- op.add_column(- "graph_edges",- sa.Column("hint_source", sa.String(length=64), nullable=True),- )---def downgrade() -> None:- op.drop_column("graph_edges", "hint_source")diff --git a/packages/core/alembic/versions/0047_graph_edge_hint_source.py b/packages/core/alembic/versions/0047_graph_edge_hint_source.pynew file mode 100644index 000000000..b90530a20--- /dev/null+++ b/packages/core/alembic/versions/0047_graph_edge_hint_source.py@@ -0,0 +1,92 @@+"""Persist ``graph_edges.hint_source`` so cohesion survives rehydration.++Several resolver passes synthesise file-level edges to record that two files+belong to one compilation unit — Go package siblings, JVM same-package classes,+C# ``partial`` fragments and global usings, Swift same-module files, and the+C/C++ header/implementation pair. Each pass stamps ``hint_source`` on the edge.++Cycle detection reads that stamp to drop those edges: files in one compilation+unit cannot depend on each other, so counting them turns every cohesive package+into a fabricated import cycle (issue #1294).++The stamp only lived in the in-memory NetworkX graph. Anything running against a+graph rehydrated from ``graph_edges`` — the health engine's break-cycle detector,+incremental updates — saw cohesion edges as ordinary imports and re-reported the+false cycles. Persisting the column closes that gap.++Nullable with no default: NULL means "a real import/using directive", which is+the correct reading for every pre-existing row.++``init_db``'s additive schema reconciler picks the column up from the model for+local SQLite stores that never run Alembic; this migration covers the managed+Postgres ones. The two converge on the same shape.++Renumbered 0046 -> 0047. This landed as ``0046`` at the same time as the+``wiki_symbols`` index migration, so the directory carried **two** revisions+declaring ``revision = "0046"`` and ``down_revision = "0045"``. Alembic reported+``heads: ['0046', '0046']`` behind a ``Revision 0046 is present more than once``+warning, which makes the chain unusable — one of the two is unreachable and no+further revision can name a single parent. Renumbering is safe precisely because+the chain was broken: nothing could run to a well-defined head while it was.++Because it is ambiguous which of the two a database that already reports+``0046`` actually applied, this revision repairs **both** halves of that+ambiguity and each step is idempotent:++* If the store ran *this* migration as ``0046``, ``hint_source`` is already+ there and the column step is skipped.+* If it ran the ``wiki_symbols`` one as ``0046``, then ``0046`` is marked+ applied and ``ix_wiki_symbols_repo_path`` would **never** be created — the+ index would be permanently missing, silently, and every file-scoped symbol+ lookup would keep the scan plan that migration exists to remove. So this one+ also creates that index ``if_not_exists``.++A store that got both is unaffected; a store that got neither gets both.++Revision ID: 0047+Revises: 0046+Create Date: 2026-08-08+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0047"+down_revision: str | None = "0046"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++_SYMBOL_INDEX = "ix_wiki_symbols_repo_path"+++def _has_hint_source() -> bool:+ inspector = sa.inspect(op.get_bind())+ return any(c["name"] == "hint_source" for c in inspector.get_columns("graph_edges"))+++def upgrade() -> None:+ if not _has_hint_source():+ op.add_column(+ "graph_edges",+ sa.Column("hint_source", sa.String(length=64), nullable=True),+ )+ # The other half of the duplicate-0046 repair; see the note above.+ op.create_index(+ _SYMBOL_INDEX,+ "wiki_symbols",+ ["repository_id", "file_path"],+ if_not_exists=True,+ )+++def downgrade() -> None:+ # The index is left in place: 0046 owns it, and dropping it here would+ # take it away from a store that legitimately ran 0046.+ if _has_hint_source():+ op.drop_column("graph_edges", "hint_source")diff --git a/packages/core/alembic/versions/0048_health_snapshot_deductions.py b/packages/core/alembic/versions/0048_health_snapshot_deductions.pynew file mode 100644index 000000000..5345a6e53--- /dev/null+++ b/packages/core/alembic/versions/0048_health_snapshot_deductions.py@@ -0,0 +1,77 @@+"""Record how deep a floored file actually is, per snapshot.++``health_snapshots.per_file_scores_json`` stores the **clamped** score, and the+score clamps at 1.0. On the repowise index 28 of the 29 floored files have a+completely flat 1.0 series across every snapshot, with 9.06 to 12.91 points of+deduction hidden behind that 1.0 — so improving the worst file is invisible+until roughly a third of the work is already done.++This adds a sibling column rather than changing the shape of the existing one.+``per_file_scores_json`` is ``{path: score}`` and three readers parse it as+such; a value that became a dict would blank every file's series in+``trends.file_score_series`` silently and 500 the trend route loudly, while+``get_health_snapshot_file_counts``' ``len(parsed)`` would keep working and hide+both. A second column cannot do any of that.++Only files whose score sits at the floor are recorded — for every other file the+deduction is exactly ``10 - score``, so this stores what the clamp destroys and+nothing else. Measured on the repowise index: 1,895 B against a 187,597 B score+map, versus 142,812 B if every file with findings were written.++Rows written before this lands have no deduction data and keep reporting their+clamped score. That is correct: the depth was never captured, and inventing one+would be worse than a flat line.++``init_db``'s additive schema reconciler picks the column up from the model for+local SQLite stores that never run Alembic; this migration covers the managed+Postgres ones. The two converge on the same shape.++Revision ID: 0048+Revises: 0047+Create Date: 2026-08-09+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0048"+down_revision: str | None = "0047"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def _has_column() -> bool:+ inspector = sa.inspect(op.get_bind())+ return any(+ c["name"] == "per_file_deductions_json"+ for c in inspector.get_columns("health_snapshots")+ )+++def upgrade() -> None:+ # Guarded because ``init_db``'s additive reconciler adds any model column+ # missing from a live table, and it runs against whatever URL the server is+ # booted with — Postgres included. A deployment where the app started+ # before the migration ran would otherwise wedge the chain on a+ # duplicate-column error.+ if _has_column():+ return+ op.add_column(+ "health_snapshots",+ sa.Column(+ "per_file_deductions_json",+ sa.Text,+ nullable=False,+ server_default="{}",+ ),+ )+++def downgrade() -> None:+ if _has_column():+ op.drop_column("health_snapshots", "per_file_deductions_json")diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.mdindex 6e5dbc839..0a881ccdb 100644--- a/packages/core/src/repowise/core/analysis/health/README.md+++ b/packages/core/src/repowise/core/analysis/health/README.md@@ -71,6 +71,16 @@ Per-file trajectory (same snapshots, the `{path: score}` map):history). Reused verbatim by the PR bot's in-comment sparkline.- `file_trend(history, path)` — wraps the series with `current` / `previous`/ `delta` and a `declining` flag (per-file mirror of the alerts above).+- `snapshot_file_maps(metrics, findings)` — the writer's other half: builds+ both `{path: score}` and `{path: total_deduction}` from one health report.+ All three snapshot writers call it so a repo's history cannot change shape+ depending on which command wrote it.++The score clamps at `SCORE_FLOOR`, so a file deep enough to sit on it has a+flat series no matter how much of the work gets done. The deduction map covers+those files only, and each point carries `unclamped_score` — `SCORE_MAX -+deduction` where recorded, `score` otherwise — which is the series+`_file_declining` reads.## Per-file signalsdiff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.pyindex d7355a8b0..cd924e93f 100644--- a/packages/core/src/repowise/core/analysis/health/scoring.py+++ b/packages/core/src/repowise/core/analysis/health/scoring.py@@ -25,6 +25,13 @@ from dataclasses import replacefrom .biomarkers.base import BiomarkerResultfrom .models import HealthFileMetricData, HealthFindingData, Severity+# The band every dimension's score is clamped into. Named because the floor is+# lossy — a file 12.9 points deep and one 9.1 points deep both print 1.0 — and+# the snapshot writer needs the same number to decide whose depth is worth+# recording. Values unchanged; this only stops them being written out per site.+SCORE_FLOOR: float = 1.0+SCORE_MAX: float = 10.0+# Per-category max deduction.CATEGORY_CAPS: dict[str, float] = {"organizational": 3.5,@@ -533,7 +540,7 @@ def _score_dimension(per_result[idx] = d * scaletotal += cap- score = max(1.0, min(10.0, 10.0 - total))+ score = max(SCORE_FLOOR, min(SCORE_MAX, SCORE_MAX - total))return score, per_resultdiff --git a/packages/core/src/repowise/core/analysis/health/trends.py b/packages/core/src/repowise/core/analysis/health/trends.pyindex a76ccca07..d63952465 100644--- a/packages/core/src/repowise/core/analysis/health/trends.py+++ b/packages/core/src/repowise/core/analysis/health/trends.py@@ -29,6 +29,8 @@ from dataclasses import dataclass, fieldfrom datetime import datetimefrom typing import Any+from .scoring import SCORE_FLOOR, SCORE_MAX+DECLINE_THRESHOLD: float = 0.5DECLINE_LOOKBACK: int = 5 # compare current vs snapshot N positions backPREDICTED_DECLINE_CONSECUTIVE: int = 3@@ -193,22 +195,83 @@ def recent_kpis(history: list[Any], limit: int = 10) -> list[dict[str, Any]]:# --------------------------------------------------------------------------- ## Per-file trajectory#-# The snapshot writer stores a compact ``{path: score}`` map per snapshot-# (``HealthSnapshot.per_file_scores_json``). These helpers turn that rolling-# window into a single file's score-over-time series. Like the repo-level-# helpers above they are intentionally state-free:-# callers pass the snapshot history (oldest → newest) and get plain data back,-# so the logic stays unit-testable without a DB and is reused verbatim by the-# PR bot's in-comment sparkline.+# The snapshot writer stores two compact maps per snapshot: ``{path: score}``+# (``HealthSnapshot.per_file_scores_json``) for every scored file, and+# ``{path: total_deduction}`` (``per_file_deductions_json``) for the files whose+# score is held at ``SCORE_FLOOR``. These helpers turn that rolling window into+# a single file's trajectory. Like the repo-level helpers above they are+# intentionally state-free: callers pass the snapshot history (oldest → newest)+# and get plain data back, so the logic stays unit-testable without a DB and is+# reused verbatim by the PR bot's in-comment sparkline.# --------------------------------------------------------------------------- #+def snapshot_file_maps(+ metrics: list[Any],+ findings: list[Any],+) -> tuple[dict[str, float], dict[str, float]]:+ """Build both of a snapshot's per-file maps from one health report.++ Returns ``(per_file_scores, per_file_deductions)``, ready to hand to+ ``save_health_snapshot``.++ One function because there are three writers — ``repowise health``,+ ``repowise upgrade`` and the full-index pipeline — and a repo's history+ would otherwise carry different data depending on which of them wrote the+ row last. That failure has happened here before, with a different argument+ and four call sites.++ ``per_file_deductions`` holds only the files whose score sits at+ ``SCORE_FLOOR``. For every other file the deduction is exactly+ ``SCORE_MAX - score``, so recording it would be storing a value the reader+ can already compute — on the repowise index, 2,083 B of floored files+ against 142,812 B if every file with findings were written, beside a+ 187,593 B score map. The deduction is summed from ``health_impact``, which+ is the per-finding contribution the scorer used to produce ``score``, so+ the pair is consistent by construction rather than by reconciliation.++ Note the recorded depth is the **category-capped** total, so it is itself+ bounded by ``sum(CATEGORY_CAPS)`` and the unclamped score cannot go below+ ``SCORE_MAX - sum(CATEGORY_CAPS)``. A file with every category at its cap+ is flat again, one level down. Nothing on the repowise index is close+ (deepest is 12.91 of a possible 13.5), and recording the pre-cap sum+ instead would be recording a number the score was never computed from.+ """+ per_file_scores = {m.file_path: round(float(m.score), 2) for m in metrics}++ totals: dict[str, float] = {}+ for f in findings:+ path = getattr(f, "file_path", None)+ if not path:+ continue+ totals[path] = totals.get(path, 0.0) + float(getattr(f, "health_impact", 0.0) or 0.0)++ per_file_deductions = {+ m.file_path: round(totals[m.file_path], 2)+ for m in metrics+ if float(m.score) <= SCORE_FLOOR and m.file_path in totals+ }+ return per_file_scores, per_file_deductions++@dataclassclass FileTrendPoint:- """One file's score at one snapshot."""+ """One file's score at one snapshot.++ ``score`` is the clamped, surfaced number. ``unclamped_score`` is+ ``SCORE_MAX - total_deduction`` where the snapshot recorded a deduction,+ and ``score`` otherwise — so it is the series that keeps moving after the+ floor is hit, and is identical to ``score`` for every file that has not hit+ it and for every row written before deductions were captured.++ Required rather than defaulted: a point that silently defaults to its own+ score is exactly the flat line this field exists to stop, and it would be+ indistinguishable from a real one at the read site.+ """taken_at: datetime | Nonescore: float+ unclamped_score: float@dataclass@@ -220,6 +283,12 @@ class FileTrend:drawing a misleading single dot (plan §2: "silent when < 2 realsnapshots"). ``current`` / ``previous`` / ``delta`` and ``declining``are all ``None`` / ``False`` in that case.++ ``current`` / ``previous`` / ``delta`` stay on the clamped score — that is+ the number printed everywhere else in the product and changing it would+ make the trend disagree with the file's own header. ``unclamped_delta`` is+ the movement the floor hides, and equals ``delta`` whenever the floor is+ not involved, so a consumer can read it unconditionally."""file_path: str@@ -229,23 +298,24 @@ class FileTrend:delta: float | Nonedeclining: boolsnapshot_count: int+ unclamped_delta: float | None = None-def _score_in_snapshot(snap: Any, file_path: str) -> float | None:- """Read ``file_path``'s score from a snapshot's compact JSON map.+def _value_in_snapshot(snap: Any, column: str, file_path: str) -> float | None:+ """Read one float out of a snapshot's compact ``{path: value}`` JSON map.- Returns ``None`` when the file is absent from that snapshot (it may have- been added later, renamed, or filtered out of that run) or when the map- can't be parsed — the series simply skips that snapshot.+ Returns ``None`` when the file is absent from that map (it may have been+ added later, renamed, filtered out of that run, or — for the deductions map+ — simply not be at the floor) or when the map can't be parsed."""- raw = getattr(snap, "per_file_scores_json", None)+ raw = getattr(snap, column, None)if not raw:return Nonetry:- scores = json.loads(raw)+ parsed = json.loads(raw)except (ValueError, TypeError):return None- val = scores.get(file_path) if isinstance(scores, dict) else None+ val = parsed.get(file_path) if isinstance(parsed, dict) else Noneif val is None:return Nonetry:@@ -254,6 +324,32 @@ def _score_in_snapshot(snap: Any, file_path: str) -> float | None:return None+def _score_in_snapshot(snap: Any, file_path: str) -> float | None:+ """``file_path``'s clamped score in *snap*, or ``None`` if not recorded."""+ return _value_in_snapshot(snap, "per_file_scores_json", file_path)+++def _unclamped_in_snapshot(snap: Any, file_path: str, score: float) -> float | None:+ """``file_path``'s score with the floor undone, as far as *snap* knows.++ Three cases, and the third is the one that matters:++ * A recorded deduction means the clamp bit and this snapshot kept the+ depth. The honest value is ``SCORE_MAX - deduction``, below the floor and+ possibly negative.+ * No deduction and a score above the floor: the clamp did not bite, so the+ score already *is* the unclamped value.+ * No deduction and a score **at** the floor: the depth is unknown. The row+ predates deduction capture, or the file had no findings to sum. Returns+ ``None`` — not ``score``, which would assert a depth of exactly 9.0 that+ was never measured.+ """+ deduction = _value_in_snapshot(snap, "per_file_deductions_json", file_path)+ if deduction is not None:+ return round(SCORE_MAX - deduction, 2)+ return score if score > SCORE_FLOOR else None++def file_score_series(history: list[Any], file_path: str) -> list[FileTrendPoint]:"""A file's oldest-first score series across the snapshot window.@@ -264,13 +360,39 @@ def file_score_series(history: list[Any], file_path: str) -> list[FileTrendPoint*history* is expected oldest-first (the natural ``list_health_snapshots``order). This is the exact function the PR bot reuses for its in-commentsparkline, so it stays free of any persistence or presentation concern.++ ``unclamped_score`` diverges from ``score`` only when **every** point in+ the series has a known depth. A series that mixes measured depth with+ snapshots that never recorded it is the dangerous case, not the harmless+ one: the unmeasured points read as ``1.0`` and the measured ones as their+ real depth, so the first index after depth capture is switched on draws a+ cliff on a file that did not change. Measured against the live index —+ fifteen snapshots without capture plus one with, and nothing altered —+ that flipped **21 of 32** floored files to ``declining`` with drops up to+ 3.9 points. Waiting for the window to fill costs a slow start; not waiting+ reports a collapse that never happened."""- points: list[FileTrendPoint] = []+ raw: list[tuple[Any, float, float | None]] = []for snap in history:score = _score_in_snapshot(snap, file_path)if score is None:continue- points.append(FileTrendPoint(taken_at=getattr(snap, "taken_at", None), score=score))+ raw.append(+ (+ getattr(snap, "taken_at", None),+ score,+ _unclamped_in_snapshot(snap, file_path, score),+ )+ )+ depth_known = all(unclamped is not None for _, _, unclamped in raw)+ points = [+ FileTrendPoint(+ taken_at=taken_at,+ score=score,+ unclamped_score=unclamped if depth_known else score,+ )+ for taken_at, score, unclamped in raw+ ]if len(points) < 2:return []return points@@ -283,10 +405,20 @@ def _file_declining(points: list[FileTrendPoint]) -> bool:``DECLINE_THRESHOLD`` below the point ``DECLINE_LOOKBACK`` back, or thetail is ``PREDICTED_DECLINE_CONSECUTIVE`` strict drops in a row. Singlesnapshot-to-snapshot noise is deliberately not enough.++ Computed on ``unclamped_score``, which is identical to ``score`` for every+ file that has not hit the floor — so nothing changes for the 99% — and is+ the only series that can move for one that has. There is deliberately **no**+ third ``at_floor`` state: the original complaint was that ``declining:+ false`` sat beside a visibly collapsed series, and that was a disagreement+ between the flag and the *clamped* line, not a missing state. Against the+ unclamped line a flat flag now describes a flat series, and a file that+ keeps getting worse below the floor trips the flag for the first time —+ which is the behaviour the flag always claimed to have."""if len(points) <= 1:return False- scores = [p.score for p in points]+ scores = [p.unclamped_score for p in points]if (len(scores) > DECLINE_LOOKBACK@@ -329,6 +461,7 @@ def file_trend(history: list[Any], file_path: str) -> FileTrend:current=current,previous=previous,delta=round(current - previous, 2),+ unclamped_delta=round(points[-1].unclamped_score - points[-2].unclamped_score, 2),declining=_file_declining(points),snapshot_count=len(history),)diff --git a/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py b/packages/core/src/repowise/core/persistence/_interfaces/_analysis.pyindex 4b3ef663d..a5fc49961 100644--- a/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py+++ b/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py@@ -217,6 +217,7 @@ class AnalysisIndexStore(ABC):worst_performer_path: str | None,worst_performer_score: float | None,per_file_scores: dict[str, float] | None = None,+ per_file_deductions: dict[str, float] | None = None,taken_at: datetime | None = None,) -> HealthSnapshot: ...diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.pyindex 95d4b6c21..f240e57d0 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py@@ -636,6 +636,7 @@ async def save_health_snapshot(worst_performer_path: str | None,worst_performer_score: float | None,per_file_scores: dict[str, float] | None = None,+ per_file_deductions: dict[str, float] | None = None,taken_at: datetime | None = None,) -> HealthSnapshot:"""Append a snapshot; prune oldest rows past ``HEALTH_SNAPSHOT_RETENTION``.@@ -643,6 +644,12 @@ async def save_health_snapshot(Returns the inserted row. Per-file scores are stored compactly as``{path: score}`` JSON (no per-finding detail — that lives in``HealthFinding`` rows; snapshots are a thin history layer).++ ``per_file_deductions`` is the same shape for the files whose score is held+ at the floor, where the stored score has stopped carrying information.+ Build both with ``trends.snapshot_file_maps`` rather than by hand: a repo+ whose writers disagree gets a history that changes depth depending on which+ command last wrote it."""snap = HealthSnapshot(id=_new_uuid(),@@ -655,6 +662,7 @@ async def save_health_snapshot(float(worst_performer_score) if worst_performer_score is not None else None),per_file_scores_json=json.dumps(per_file_scores or {}, separators=(",", ":")),+ per_file_deductions_json=json.dumps(per_file_deductions or {}, separators=(",", ":")),)session.add(snap)await session.flush()diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex dcbc7b4d7..171be1c2d 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1249,6 +1249,13 @@ class HealthSnapshot(Base):worst_performer_path: Mapped[str | None] = mapped_column(Text, nullable=True)worst_performer_score: Mapped[float | None] = mapped_column(Float, nullable=True)per_file_scores_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")+ # ``{path: total_deduction}`` for the files whose score is held at the+ # floor, and only those — everywhere else the deduction is exactly+ # ``10 - score``, so this carries what the clamp destroys and nothing more.+ # A sibling column rather than a richer value inside ``per_file_scores_json``+ # because that blob's ``{path: score}`` shape is parsed by three readers,+ # two of which would fail quietly if a value became a dict.+ per_file_deductions_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")class CoverageFile(Base):diff --git a/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py b/packages/core/src/repowise/core/persistence/stores/_sql_analysis.pyindex 3deb76a14..97b558093 100644--- a/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py+++ b/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py@@ -252,6 +252,7 @@ class _SqlAnalysisMixin(AnalysisIndexStore):worst_performer_path: str | None,worst_performer_score: float | None,per_file_scores: dict[str, float] | None = None,+ per_file_deductions: dict[str, float] | None = None,taken_at: datetime | None = None,) -> HealthSnapshot:return await crud.save_health_snapshot(@@ -262,6 +263,7 @@ class _SqlAnalysisMixin(AnalysisIndexStore):worst_performer_path=worst_performer_path,worst_performer_score=worst_performer_score,per_file_scores=per_file_scores,+ per_file_deductions=per_file_deductions,taken_at=taken_at,)diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 9b0d10988..100f4a7d4 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -1202,6 +1202,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:decisions/governance are idempotent. Intended to run once the analysisphase has fully completed."""+ from repowise.core.analysis.health.trends import snapshot_file_mapsfrom repowise.core.persistence.crud import (bulk_upsert_decisions,recompute_decision_staleness,@@ -1247,6 +1248,9 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:# Snapshot the run for trend tracking (rolling delete inside).kpis = hr.kpis or {}try:+ scores_map, deductions_map = snapshot_file_maps(+ hr.metrics or [], hr.findings or []+ )await save_health_snapshot(session,repo_id,@@ -1254,7 +1258,8 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:average_health=float(kpis.get("average_health", 10.0)),worst_performer_path=kpis.get("worst_performer_path"),worst_performer_score=kpis.get("worst_performer_score"),- per_file_scores={m.file_path: round(float(m.score), 2) for m in hr.metrics or []},+ per_file_scores=scores_map,+ per_file_deductions=deductions_map,)except Exception as _snap_err:logger.warning("health_snapshot_skipped", error=str(_snap_err))diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex 2bc46e2a8..69c311af9 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -1037,15 +1037,24 @@ async def get_health(t = file_trend(snapshots, m.file_path)if not t.points:continue- trends.append(- {- "file_path": t.file_path,- "series": [round(p.score, 2) for p in t.points],- "current": t.current,- "delta": t.delta,- "declining": t.declining,- }- )+ series = [round(p.score, 2) for p in t.points]+ entry: dict[str, Any] = {+ "file_path": t.file_path,+ "series": series,+ "current": t.current,+ "delta": t.delta,+ "declining": t.declining,+ }+ # The score floors at 1.0, so a file deep enough to sit on it keeps+ # a flat series however much of the work gets done. Where a+ # snapshot recorded the real depth, carry the series that can still+ # move — and only there, so the files the floor never touches pay+ # nothing for it.+ unclamped = [round(p.unclamped_score, 2) for p in t.points]+ if unclamped != series:+ entry["unclamped_series"] = unclamped+ entry["unclamped_delta"] = t.unclamped_delta+ trends.append(entry)if trends:result["trends"] = trendsif module_targets:diff --git a/packages/server/src/repowise/server/routers/code_health/breakdown.py b/packages/server/src/repowise/server/routers/code_health/breakdown.pyindex be2e0bf0e..b81153f6d 100644--- a/packages/server/src/repowise/server/routers/code_health/breakdown.py+++ b/packages/server/src/repowise/server/routers/code_health/breakdown.py@@ -8,6 +8,8 @@ from typing import Anyfrom repowise.core.analysis.health.models import Severityfrom repowise.core.analysis.health.scoring import (CATEGORY_CAPS,+ SCORE_FLOOR,+ SCORE_MAX,biomarker_category,biomarker_weight,severity_deduction,@@ -100,7 +102,7 @@ def _score_breakdown_from_findings(findings: list[Any]) -> dict:})total_deduction += applied_sum- score = max(1.0, min(10.0, 10.0 - total_deduction))+ score = max(SCORE_FLOOR, min(SCORE_MAX, SCORE_MAX - total_deduction))return {"score": round(score, 2),"total_deduction": round(total_deduction, 3),diff --git a/packages/server/src/repowise/server/routers/code_health/serializers.py b/packages/server/src/repowise/server/routers/code_health/serializers.pyindex 929ddd9d8..9e191850c 100644--- a/packages/server/src/repowise/server/routers/code_health/serializers.py+++ b/packages/server/src/repowise/server/routers/code_health/serializers.py@@ -117,12 +117,17 @@ def _file_trend_to_dict(t: FileTrend) -> dict:{"taken_at": p.taken_at.isoformat() if p.taken_at else None,"score": round(p.score, 2),+ # The score with the floor undone. Equal to ``score`` unless+ # the snapshot recorded how deep the file actually was, which+ # only happens once it is sitting on the floor.+ "unclamped_score": round(p.unclamped_score, 2),}for p in t.points],"current": t.current,"previous": t.previous,"delta": t.delta,+ "unclamped_delta": t.unclamped_delta,"declining": t.declining,"snapshot_count": t.snapshot_count,}diff --git a/packages/server/src/repowise/server/routers/code_health/trends_routes.py b/packages/server/src/repowise/server/routers/code_health/trends_routes.pyindex b6752b659..6c73beb1c 100644--- a/packages/server/src/repowise/server/routers/code_health/trends_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/trends_routes.py@@ -14,6 +14,10 @@ from repowise.server.deps import get_db_sessionfrom ._router import routerfrom .serializers import _file_trend_to_dict+# How many per-file movements the trend response carries. Paired with+# ``file_deltas_total`` so a caller can always tell a full list from a slice.+FILE_DELTA_LIMIT: int = 50+@router.get("/api/repos/{repo_id}/health/files/trend")async def file_health_trend(@@ -62,7 +66,14 @@ async def health_trend(if d == 0:continuefile_deltas.append({"file_path": p, "before": before, "after": after, "delta": d})- file_deltas.sort(key=lambda r: r["delta"])+ # Largest movement first, in either direction. Sorting ascending and+ # slicing made the block the N biggest *drops*: improvements only+ # survived the cut while fewer than ``FILE_DELTA_LIMIT`` files had+ # regressed, so the one render that most wants to show progress — the+ # index after a cleanup — is the one that hides it. The client+ # (``TrendSlopeChart``) already ranks by absolute delta before drawing,+ # so this is also the order it was asking for.+ file_deltas.sort(key=lambda r: (-abs(r["delta"]), r["file_path"]))return {"history": recent_kpis(snapshots, limit=limit),@@ -85,6 +96,9 @@ async def health_trend(}for a in summary.alerts],- "file_deltas": file_deltas[:50],+ "file_deltas": file_deltas[:FILE_DELTA_LIMIT],+ # The true count behind the slice, so the UI can say "N of M" instead+ # of presenting a truncated list as the whole story.+ "file_deltas_total": len(file_deltas),"snapshot_count": len(snapshots),}diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex cfd7fef90..f99b02616 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -415,6 +415,14 @@ export interface FileSignals {export interface FileTrendPoint {taken_at: string | null;score: number;+ /**+ * `score` with the 1.0 floor undone, so a file too deep to move the visible+ * score still has a line that moves. Equal to `score` unless the snapshot+ * recorded the file's real depth, which only happens once it is on the+ * floor; may go below 0. Optional: the hosted backend does not send it, and+ * neither do rows written before deductions were captured.+ */+ unclamped_score?: number;}/**@@ -431,6 +439,12 @@ export interface FileHealthTrend {current: number | null;previous: number | null;delta: number | null;+ /**+ * Movement in the unclamped score between the last two points. Equal to+ * `delta` whenever the floor is not involved, so it can be read+ * unconditionally. Optional for hosted, which does not send it.+ */+ unclamped_delta?: number | null;declining: boolean;snapshot_count: number;}@@ -463,7 +477,13 @@ export interface HealthTrendResponse {delta: number;message: string;}>;+ /** Largest movements first, in either direction, capped server-side. */file_deltas: Array<{ file_path: string; before: number; after: number; delta: number }>;+ /**+ * How many files moved in total, before the cap. Optional: the hosted+ * backend does not send it, so consumers fall back to `file_deltas.length`.+ */+ file_deltas_total?: number;snapshot_count: number;}diff --git a/packages/ui/__tests__/health/file-trend-chart.test.tsx b/packages/ui/__tests__/health/file-trend-chart.test.tsxindex 3e0084c0d..bdae25fc6 100644--- a/packages/ui/__tests__/health/file-trend-chart.test.tsx+++ b/packages/ui/__tests__/health/file-trend-chart.test.tsx@@ -68,4 +68,104 @@ describe("FileTrendChart", () => {render(<FileTrendChart trend={null} />);expect(screen.getByText(/No score history yet/)).toBeInTheDocument();});++ describe("below the score floor", () => {+ // The score clamps at 1.0, so the worst files in a repo all print 1.0 and+ // their line is flat however much of the work gets done. The server sends+ // the pre-clamp value for exactly those files.+ const floored = trend({+ points: [+ { taken_at: null, score: 1, unclamped_score: -2.9 },+ { taken_at: null, score: 1, unclamped_score: -0.4 },+ ],+ current: 1,+ previous: 1,+ delta: 0,+ unclamped_delta: 2.5,+ snapshot_count: 2,+ });++ it("reports the movement the floor hides instead of a flat 0", () => {+ render(<FileTrendChart trend={floored} />);+ expect(screen.getByText(/\+2\.50 vs\. previous/)).toBeInTheDocument();+ // The number the clamped delta would have produced must not appear —+ // "0.00 vs. previous" beside a real improvement is the original bug.+ expect(screen.queryByText(/0\.00 vs\. previous/)).not.toBeInTheDocument();+ });++ it("explains why the displayed score has not moved", () => {+ render(<FileTrendChart trend={floored} />);+ expect(screen.getByText(/scores below the 1\.0 floor/i)).toBeInTheDocument();+ });++ it("extends the axis under the floor and marks it", () => {+ const { container } = render(<FileTrendChart trend={floored} />);+ // The domain has to reach the deepest point, else the line is drawn+ // outside the plot area and reads as flat along the bottom edge.+ const ticks = Array.from(container.querySelectorAll("text")).map((t) => t.textContent);+ expect(ticks).toContain("-3");+ expect(ticks).toContain("score floor");+ });++ it("marks the floor for a file that is only just below it", () => {+ // 9 to 10 points of deduction puts the unclamped score inside [0, 1):+ // below the floor, but not below zero. Gating the marker on a negative+ // axis minimum captioned this file as floored while drawing no floor.+ const { container } = render(+ <FileTrendChart+ trend={trend({+ points: [+ { taken_at: null, score: 1, unclamped_score: 0.9 },+ { taken_at: null, score: 1, unclamped_score: 0.4 },+ ],+ delta: 0,+ unclamped_delta: -0.5,+ snapshot_count: 2,+ })}+ />,+ );+ expect(screen.getByText(/scores below the 1\.0 floor/i)).toBeInTheDocument();+ const ticks = Array.from(container.querySelectorAll("text")).map((t) => t.textContent);+ expect(ticks).toContain("score floor");+ });++ it("leaves an ordinary chart alone", () => {+ const { container } = render(+ <FileTrendChart+ trend={trend({+ points: [+ { taken_at: null, score: 8, unclamped_score: 8 },+ { taken_at: null, score: 6.5, unclamped_score: 6.5 },+ ],+ delta: -1.5,+ unclamped_delta: -1.5,+ snapshot_count: 2,+ })}+ />,+ );+ const ticks = Array.from(container.querySelectorAll("text")).map((t) => t.textContent);+ expect(ticks).not.toContain("score floor");+ expect(screen.queryByText(/scores below the 1\.0 floor/i)).not.toBeInTheDocument();+ });++ it("falls back to the plain score when the server sends no depth", () => {+ // Hosted, and every row written before deductions were captured. A+ // floored file stays flat rather than acquiring an invented depth.+ const { container } = render(+ <FileTrendChart+ trend={trend({+ points: [+ { taken_at: null, score: 1 },+ { taken_at: null, score: 1 },+ ],+ delta: 0,+ snapshot_count: 2,+ })}+ />,+ );+ const ticks = Array.from(container.querySelectorAll("text")).map((t) => t.textContent);+ expect(ticks).not.toContain("score floor");+ expect(screen.queryByText(/vs\. previous/)).not.toBeInTheDocument();+ });+ });});diff --git a/packages/ui/__tests__/health/trend-view.test.tsx b/packages/ui/__tests__/health/trend-view.test.tsxnew file mode 100644index 000000000..bbcc8ef39--- /dev/null+++ b/packages/ui/__tests__/health/trend-view.test.tsx@@ -0,0 +1,87 @@+import { describe, it, expect } from "vitest";+import { render, screen } from "@testing-library/react";+import type { HealthTrendResponse } from "@repowise-dev/types/health";+import { TrendView } from "../../src/health/trend-view.js";++function response(partial: Partial<HealthTrendResponse>): HealthTrendResponse {+ return {+ history: [],+ summary: {+ current_hotspot_health: 5,+ current_average_health: 7,+ previous_hotspot_health: 5,+ previous_average_health: 7,+ hotspot_delta: 0,+ average_delta: 0,+ },+ alerts: [],+ file_deltas: [],+ snapshot_count: 2,+ ...partial,+ };+}++const deltas = (n: number, offset = 0) =>+ Array.from({ length: n }, (_, i) => ({+ file_path: `f${i + offset}.py`,+ before: 8,+ after: 7,+ delta: -1,+ }));++describe("TrendView — largest score changes", () => {+ // Two caps sit between the response and the picture: the server slices its+ // list, and the chart draws only the largest few of what arrives. The block+ // is headed "Largest score changes since last index" with no total, so a+ // reader cannot tell all-of-them from a truncated tail.++ it("says how many of the total it is drawing", () => {+ render(+ <TrendView data={response({ file_deltas: deltas(50), file_deltas_total: 183 })} isLoading={false} error={null} />,+ );+ expect(screen.getByText(/Showing the 18 largest of 183 files that changed\./)).toBeInTheDocument();+ });++ it("says so plainly when nothing was dropped", () => {+ render(+ <TrendView data={response({ file_deltas: deltas(4), file_deltas_total: 4 })} isLoading={false} error={null} />,+ );+ expect(screen.getByText(/All 4 files that changed\./)).toBeInTheDocument();+ });++ it("claims no total when the server sends none", () => {+ // Hosted sends no `file_deltas_total` and caps its own list, so the list+ // length is not the total. Saying "all 3" would be a guess presented as+ // a fact; the sentence describes only what is drawn.+ render(<TrendView data={response({ file_deltas: deltas(3) })} isLoading={false} error={null} />);+ expect(screen.getByText(/Showing the 3 largest changes\./)).toBeInTheDocument();+ expect(screen.queryByText(/All 3/)).not.toBeInTheDocument();+ });++ it("does not claim completeness against a backend that caps silently", () => {+ // The concrete hosted shape: 50 rows arrive, capped server-side by a+ // backend that reports no total. "All 50 files that changed" would be+ // wrong whenever more than 50 moved.+ render(<TrendView data={response({ file_deltas: deltas(50) })} isLoading={false} error={null} />);+ expect(screen.getByText(/Showing the 18 largest changes\./)).toBeInTheDocument();+ expect(screen.queryByText(/of 50/)).not.toBeInTheDocument();+ expect(screen.queryByText(/All 50/)).not.toBeInTheDocument();+ });++ it("still counts the chart's own cap when the server sent everything", () => {+ // 25 arrive, 18 are drawn, nothing was truncated server-side. Reporting+ // "All 25" here would describe the response rather than the picture.+ render(+ <TrendView data={response({ file_deltas: deltas(25), file_deltas_total: 25 })} isLoading={false} error={null} />,+ );+ expect(screen.getByText(/Showing the 18 largest of 25 files that changed\./)).toBeInTheDocument();+ });++ it("keeps the empty state rather than reporting zero of zero", () => {+ render(+ <TrendView data={response({ file_deltas: [], file_deltas_total: 0 })} isLoading={false} error={null} />,+ );+ expect(screen.getByText(/No file changed score between the last two snapshots\./)).toBeInTheDocument();+ expect(screen.queryByText(/Showing the/)).not.toBeInTheDocument();+ });+});diff --git a/packages/ui/src/health/file-trend-chart.tsx b/packages/ui/src/health/file-trend-chart.tsxindex 3b91fe151..69bfbd71f 100644--- a/packages/ui/src/health/file-trend-chart.tsx+++ b/packages/ui/src/health/file-trend-chart.tsx@@ -11,15 +11,34 @@ export interface FileTrendChartProps {bare?: boolean;}+/** The score floor. Below it the visible score stops moving; see `plotted`. */+const SCORE_FLOOR = 1;++/**+ * The value actually drawn for a point: the score with the floor undone where+ * the server recorded how deep the file is, and the plain score otherwise.+ *+ * Two files 12.9 and 9.1 points deep both print 1.0, so a floored file's line+ * is flat however much of the work gets done — which is the opposite of the+ * feedback someone who just did that work needs. Plotting the unclamped value+ * is identical for every file the floor never touches, so there is one code+ * path rather than a mode.+ */+const plotted = (p: FileHealthTrend["points"][number]) => p.unclamped_score ?? p.score;+/*** A single file's score trajectory over the snapshot history — the per-file- * counterpart to the repo-level `TrendChart`. Purpose-built for one 0-10- * series (rather than overloading the 3-KPI chart): a fixed 0-10 Y axis, a- * delta chip, and a declining flag. Silent ("no history yet") when the file- * has fewer than two snapshots, matching the silent-on-thin-history contract.+ * counterpart to the repo-level `TrendChart`. Purpose-built for one series+ * (rather than overloading the 3-KPI chart): a 0-10 Y axis that extends+ * downward only when a file has sunk below the floor, a delta chip, and a+ * declining flag. Silent ("no history yet") when the file has fewer than two+ * snapshots, matching the silent-on-thin-history contract.*/export function FileTrendChart({ trend, height = 140, bare = false }: FileTrendChartProps) {const points = trend?.points ?? [];+ const belowFloor = points.some((p) => plotted(p) < SCORE_FLOOR);+ // Equal to `delta` unless the floor is in play, so it needs no branch.+ const delta = trend?.unclamped_delta ?? trend?.delta;const body =points.length < 2 ? (@@ -28,7 +47,16 @@ export function FileTrendChart({ trend, height = 140, bare = false }: FileTrendCleast two <code>repowise</code> runs.</div>) : (- <Chart points={points} height={height} />+ <>+ <Chart points={points} height={height} />+ {belowFloor && (+ <p className="text-[11px] leading-snug text-[var(--color-text-tertiary)]">+ This file scores below the {SCORE_FLOOR.toFixed(1)} floor, so its+ displayed score cannot move. The line shows the score before the+ floor is applied, which is what improvements here shift first.+ </p>+ )}+ </>);if (bare) return body;@@ -47,9 +75,9 @@ export function FileTrendChart({ trend, height = 140, bare = false }: FileTrendCDeclining</span>)}- {trend?.delta != null && trend.delta !== 0 && (- <span className={`text-xs font-semibold tabular-nums ${deltaColor(trend.delta)}`}>- {formatDelta(trend.delta)} vs. previous+ {delta != null && delta !== 0 && (+ <span className={`text-xs font-semibold tabular-nums ${deltaColor(delta)}`}>+ {formatDelta(delta)} vs. previous</span>)}</div>@@ -76,15 +104,29 @@ function Chart({const plotW = W - padL - padR;const plotH = H - padT - padB;+ const values = points.map(plotted);+ // 0-10 normally. A file below the floor is plotted on its real depth, which+ // can be negative, so the domain drops to the next whole point beneath it —+ // never above 0, so the usual chart is pixel-identical to before.+ const yMin = Math.min(0, Math.floor(Math.min(...values)));+ const yMax = 10;+ const ticks = yMin < 0 ? [yMin, 0, 5, 10] : [0, 5, 10];+ // Gated on the same condition as the explanatory caption above. Keying the+ // marker off `yMin < 0` instead left a file 9 to 10 points deep — unclamped+ // inside [0, 1) — captioned as below the floor with no floor drawn.+ const showFloor = Math.min(...values) < SCORE_FLOOR;+const xScale = (i: number) =>points.length === 1 ? padL + plotW / 2 : padL + (i / (points.length - 1)) * plotW;- const yScale = (v: number) => padT + ((10 - v) / 10) * plotH;+ const yScale = (v: number) => padT + ((yMax - v) / (yMax - yMin)) * plotH;- const coords = points.map((p, i) => [xScale(i), yScale(p.score)] as const);+ const coords = values.map((v, i) => [xScale(i), yScale(v)] as const);const line = coords.map(([x, y], i) => (i === 0 ? `M${x},${y}` : `L${x},${y}`)).join(" ");const last = points[points.length - 1]!;const first = points[0]!;+ // Banded on the score the product shows elsewhere, not on the plotted depth,+ // so the end dot's colour matches the file's stated score.const endColor = scoreTextColor(last.score);const fmtDate = (iso: string | null) => (iso ? new Date(iso).toLocaleDateString() : "");@@ -98,7 +140,7 @@ function Chart({role="img"aria-label="File health score over time">- {[0, 5, 10].map((v) => (+ {ticks.map((v) => (<g key={v}><linex1={padL}@@ -120,6 +162,31 @@ function Chart({</text></g>))}+ {/* The floor, drawn only when the line crosses it — otherwise it would+ be a second axis rule at the bottom of every ordinary chart. */}+ {showFloor && (+ <>+ <line+ x1={padL}+ x2={W - padR}+ y1={yScale(SCORE_FLOOR)}+ y2={yScale(SCORE_FLOOR)}+ stroke="var(--color-error)"+ strokeOpacity={0.45}+ strokeDasharray="3 3"+ />+ <text+ x={W - padR}+ y={yScale(SCORE_FLOOR) - 3}+ fontSize={9}+ textAnchor="end"+ fill="var(--color-error)"+ opacity={0.7}+ >+ score floor+ </text>+ </>+ )}<path d={line} stroke="var(--color-accent-primary)" strokeWidth={1.8} fill="none" />{coords.map(([x, y], i) => (<circle key={i} cx={x} cy={y} r={2.2} fill="var(--color-accent-primary)" />diff --git a/packages/ui/src/health/trend-view.tsx b/packages/ui/src/health/trend-view.tsxindex a555e8ed8..2b108a1b1 100644--- a/packages/ui/src/health/trend-view.tsx+++ b/packages/ui/src/health/trend-view.tsx@@ -28,6 +28,13 @@ import { TrendChart } from "./trend-chart";import { TrendSlopeChart } from "./trend-slope-chart";import { deltaColor, formatDelta, scoreTextColor } from "./tokens";+/**+ * How many slopes the chart draws. Passed explicitly rather than left to+ * `TrendSlopeChart`'s default so the sentence above the chart and the chart+ * itself cannot report different numbers.+ */+const SLOPE_MAX = 18;+export function TrendView({data,isLoading,@@ -131,7 +138,30 @@ export function TrendView({: "No file changed score between the last two snapshots."}</p>) : (- <TrendSlopeChart points={data.file_deltas} />+ <>+ {/* Two caps sit between the response and the picture — the server+ slices its list, and the chart draws the largest few of what+ arrives. Naming the drawn count against the true total is the+ difference between "these are the changes" and "these are the+ biggest of N". */}+ <p className="text-xs text-[var(--color-text-tertiary)]">+ {(() => {+ const drawn = Math.min(SLOPE_MAX, data.file_deltas.length);+ // Without a server-sent total there is no way to know whether+ // the list arrived complete, so claim only what is drawn.+ // Saying "all N" off the response length would be a flat lie+ // against a backend that caps at N and does not report it.+ if (data.file_deltas_total == null) {+ return `Showing the ${drawn} largest ${drawn === 1 ? "change" : "changes"}.`;+ }+ const total = data.file_deltas_total;+ return drawn < total+ ? `Showing the ${drawn} largest of ${total} files that changed.`+ : `All ${total} ${total === 1 ? "file that changed" : "files that changed"}.`;+ })()}+ </p>+ <TrendSlopeChart points={data.file_deltas} max={SLOPE_MAX} />+ </>)}</section></div>diff --git a/tests/unit/health/test_snapshot_writers_agree.py b/tests/unit/health/test_snapshot_writers_agree.pynew file mode 100644index 000000000..d6176c93f--- /dev/null+++ b/tests/unit/health/test_snapshot_writers_agree.py@@ -0,0 +1,85 @@+"""Every snapshot writer has to record the same thing.++``save_health_snapshot`` is called from four places: the ``repowise health``+persister, the upgrade flow, the full-index pipeline, and the store wrapper+that forwards to crud. A repo's history is whichever of those wrote it last.++This has already gone wrong once here, with a different argument: four+``HealthAnalyzer`` call sites of which only one passed ``module_map``, so a+repo's module namespace flipped depending on which command last ran. The same+shape applied to ``per_file_deductions`` would make a floored file's trend+depth appear and disappear as the user alternated between ``repowise health``,+``repowise upgrade`` and a full index — a bug that reproduces only for people+who use more than one of them.++So this walks the source rather than any one code path. A fifth writer added+later gets caught the day it lands, which is the only time the fix is cheap.+"""++from __future__ import annotations++import ast+from pathlib import Path++_ROOT = Path(__file__).resolve().parents[3] / "packages"+# Only the shipped Python. Walking ``packages`` whole spends 25s in the UI+# packages' ``node_modules`` to find nothing.+_SOURCE_ROOTS = sorted(_ROOT.glob("*/src"))++# The store wrapper forwards whatever it is handed; it builds no maps of its+# own, so it is a pass-through rather than a writer with an opinion.+_FORWARDERS = {"_sql_analysis.py"}+++def _snapshot_calls() -> list[tuple[Path, ast.Call]]:+ out: list[tuple[Path, ast.Call]] = []+ for root in _SOURCE_ROOTS:+ for path in root.rglob("*.py"):+ if path.name in _FORWARDERS:+ continue+ try:+ tree = ast.parse(path.read_text(encoding="utf-8"))+ except (SyntaxError, UnicodeDecodeError): # pragma: no cover - not our files+ continue+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ func = node.func+ name = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", None)+ if name == "save_health_snapshot":+ out.append((path, node))+ return out+++def test_the_writers_this_test_guards_still_exist() -> None:+ """Without this the sweep below passes vacuously if the call is renamed."""+ calls = _snapshot_calls()+ assert len(calls) >= 3, [str(p) for p, _ in calls]+++def test_every_writer_records_the_depth_as_well_as_the_score() -> None:+ missing = []+ for path, call in _snapshot_calls():+ kwargs = {kw.arg for kw in call.keywords}+ if not {"per_file_scores", "per_file_deductions"} <= kwargs:+ missing.append(f"{path.name}:{call.lineno} passes {sorted(kwargs)}")+ assert not missing, "snapshot writers that would record a different history: " + "; ".join(+ missing+ )+++def test_no_writer_builds_the_maps_by_hand() -> None:+ """Both maps come from ``snapshot_file_maps``.++ The score map used to be an inline dict comprehension repeated at each+ site. Two comprehensions that agree today drift the moment one of them+ learns about rounding, exclusions or test files and the others do not.+ """+ inline = []+ for path, call in _snapshot_calls():+ for kw in call.keywords:+ if kw.arg in {"per_file_scores", "per_file_deductions"} and not isinstance(+ kw.value, ast.Name+ ):+ inline.append(f"{path.name}:{call.lineno} builds {kw.arg} inline")+ assert not inline, "; ".join(inline)diff --git a/tests/unit/health/test_trends.py b/tests/unit/health/test_trends.pyindex fade99c85..dc5e2b98a 100644--- a/tests/unit/health/test_trends.py+++ b/tests/unit/health/test_trends.py@@ -6,6 +6,7 @@ import jsonfrom dataclasses import dataclassfrom datetime import UTC, datetime, timedelta+from repowise.core.analysis.health.scoring import SCORE_FLOORfrom repowise.core.analysis.health.trends import (DECLINE_LOOKBACK,DECLINE_THRESHOLD,@@ -13,6 +14,7 @@ from repowise.core.analysis.health.trends import (file_score_series,file_trend,recent_kpis,+ snapshot_file_maps,)@@ -24,6 +26,10 @@ class _S:worst_performer_path: str | None = "x"worst_performer_score: float | None = 1.0per_file_scores_json: str = "{}"+ # Deliberately defaulted to the empty map rather than omitted: a snapshot+ # written before deductions were captured has exactly this, and the+ # "history stays flat" tests below depend on that being the shape.+ per_file_deductions_json: str = "{}"def _ts(n: int) -> datetime:@@ -174,3 +180,237 @@ def test_file_trend_declining_on_consecutive_drops():def test_file_trend_not_declining_when_recovering():t = file_trend(_file_series([{"a.py": 7.0}, {"a.py": 8.0}, {"a.py": 9.0}]), "a.py")assert t.declining is False+++# --------------------------------------------------------------------------- #+# Below the floor+#+# The stored score clamps at SCORE_FLOOR, so a file deep enough to sit on it+# has a flat series however much of the work gets done. Snapshots record the+# pre-clamp deduction for those files only; ``unclamped_score`` is the series+# that can still move.+# --------------------------------------------------------------------------- #+++@dataclass+class _Metric:+ file_path: str+ score: float+++@dataclass+class _Finding:+ file_path: str+ health_impact: float+++def _floored_series(+ per_file: list[dict[str, float]],+ per_file_ded: list[dict[str, float]],+) -> list[_S]:+ """Snapshots carrying both maps, zipped positionally."""+ return [+ _S(+ taken_at=_ts(i),+ hotspot_health=10.0,+ average_health=10.0,+ per_file_scores_json=json.dumps(scores),+ per_file_deductions_json=json.dumps(ded),+ )+ for i, (scores, ded) in enumerate(zip(per_file, per_file_ded, strict=True))+ ]+++def test_unclamped_score_tracks_the_recorded_deduction():+ # The motivating case: three snapshots, all printing 1.0, while 3.3 points+ # of deduction were actually cleared. The visible series says nothing+ # happened; the unclamped one says a third of the way there.+ snaps = _floored_series(+ [{"a.py": 1.0}, {"a.py": 1.0}, {"a.py": 1.0}],+ [{"a.py": 12.9}, {"a.py": 11.2}, {"a.py": 9.6}],+ )+ pts = file_score_series(snaps, "a.py")+ assert [p.score for p in pts] == [1.0, 1.0, 1.0]+ assert [p.unclamped_score for p in pts] == [-2.9, -1.2, 0.4]++ t = file_trend(snaps, "a.py")+ # The surfaced score is unchanged — it really is 1.0 and it really has not+ # moved. The unclamped delta is where the work shows up.+ assert t.current == 1.0+ assert t.delta == 0.0+ assert t.unclamped_delta == 1.6+++def test_unclamped_score_equals_score_without_a_recorded_deduction():+ # Every file the floor never touches, and every row written before+ # deductions were captured: one series, no divergence, no second code path.+ snaps = _file_series([{"a.py": 9.0}, {"a.py": 7.5}])+ pts = file_score_series(snaps, "a.py")+ assert [p.unclamped_score for p in pts] == [9.0, 7.5]+ t = file_trend(snaps, "a.py")+ assert t.unclamped_delta == t.delta == -1.5+++def test_pre_existing_floored_history_stays_flat():+ # A repo indexed before this landed has scores but no deductions. Its+ # floored files must stay flat rather than acquire an invented depth.+ snaps = _file_series([{"a.py": 1.0}, {"a.py": 1.0}, {"a.py": 1.0}])+ t = file_trend(snaps, "a.py")+ assert [p.unclamped_score for p in t.points] == [1.0, 1.0, 1.0]+ assert t.unclamped_delta == 0.0+ assert t.declining is False+++def test_a_partial_deduction_history_reports_no_depth_at_all():+ """The shape the first index after this ships produces, and the one that+ has to stay quiet.++ Old rows carry no deduction; the newest does. Reading the old points as+ 1.0 and the new one as its real depth draws a cliff on a file that did not+ change — measured against the live index, that flipped 21 of 32 floored+ files to ``declining`` on an index where nothing moved. The series+ therefore stays clamped until the whole window has depth.+ """+ snaps = _floored_series(+ [{"a.py": 1.0}, {"a.py": 1.0}, {"a.py": 1.0}],+ [{}, {}, {"a.py": 11.0}],+ )+ pts = file_score_series(snaps, "a.py")+ assert [p.unclamped_score for p in pts] == [1.0, 1.0, 1.0]++ t = file_trend(snaps, "a.py")+ assert t.unclamped_delta == 0.0+ assert t.declining is False+++def test_depth_appears_once_the_whole_window_has_it():+ """The other side of the gate: nothing is lost, only deferred."""+ snaps = _floored_series(+ [{"a.py": 1.0}, {"a.py": 1.0}, {"a.py": 1.0}],+ [{"a.py": 12.0}, {"a.py": 11.5}, {"a.py": 11.0}],+ )+ assert [p.unclamped_score for p in file_score_series(snaps, "a.py")] == [-2.0, -1.5, -1.0]+ assert file_trend(snaps, "a.py").unclamped_delta == 0.5+++def test_an_unfloored_point_counts_as_known_depth():+ """A file that collapsed *into* the floor must still chart the collapse.++ Its early points are above the floor, where the score is already the+ unclamped value, so the window is complete even though only the tail+ carries a recorded deduction. Gating on "every point has a deduction"+ instead of "every point has a known depth" would have silenced this.+ """+ snaps = _floored_series(+ [{"a.py": 8.8}, {"a.py": 5.2}, {"a.py": 3.5}, {"a.py": 1.0}],+ [{}, {}, {}, {"a.py": 12.0}],+ )+ assert [p.unclamped_score for p in file_score_series(snaps, "a.py")] == [8.8, 5.2, 3.5, -2.0]+ t = file_trend(snaps, "a.py")+ assert t.unclamped_delta == -5.5+ # Four points, each below the last, so the consecutive-drop rule fires.+ assert t.declining is True+++def test_unclamped_score_ignores_a_deduction_for_a_different_file():+ # The deduction map is keyed by path like the score map; a hit on a+ # neighbour must not leak into this file's depth.+ snaps = _floored_series(+ [{"a.py": 1.0}, {"a.py": 1.0}],+ [{"b.py": 12.0}, {"b.py": 11.0}],+ )+ assert [p.unclamped_score for p in file_score_series(snaps, "a.py")] == [1.0, 1.0]+++def test_unclamped_series_skips_snapshots_missing_the_file():+ # A deduction recorded in a snapshot that does not score the file at all+ # cannot manufacture a point — the score map is what decides membership.+ snaps = _floored_series(+ [{"a.py": 1.0}, {"b.py": 5.0}, {"a.py": 1.0}],+ [{"a.py": 12.0}, {"a.py": 3.0}, {"a.py": 10.5}],+ )+ pts = file_score_series(snaps, "a.py")+ assert len(pts) == 2+ assert [p.unclamped_score for p in pts] == [-2.0, -0.5]+++def test_unclamped_score_tolerates_a_broken_deduction_map():+ # A deduction map that will not parse is an unknown depth, not a zero one,+ # so the series stays clamped rather than reporting a 3-point drop into+ # the unparseable snapshot. The score map still drives the points.+ snaps = _floored_series([{"a.py": 1.0}, {"a.py": 1.0}], [{"a.py": 12.0}, {}])+ snaps[1].per_file_deductions_json = "not json"+ pts = file_score_series(snaps, "a.py")+ assert [p.score for p in pts] == [1.0, 1.0]+ assert [p.unclamped_score for p in pts] == [1.0, 1.0]+++def test_declining_fires_for_a_file_getting_worse_below_the_floor():+ # The flag's whole claim is "is it getting worse now". On the clamped+ # series it could never answer yes for a floored file; every value is 1.0.+ worsening = _floored_series(+ [{"a.py": 1.0}] * 4,+ [{"a.py": 9.5}, {"a.py": 10.5}, {"a.py": 11.5}, {"a.py": 12.5}],+ )+ assert file_trend(worsening, "a.py").declining is True+ # And the same shape without recorded depth cannot, which is what makes+ # the assertion above about this change rather than about the fixture.+ assert file_trend(_file_series([{"a.py": 1.0}] * 4), "a.py").declining is False+++def test_declining_stays_false_while_a_floored_file_recovers():+ recovering = _floored_series(+ [{"a.py": 1.0}] * 4,+ [{"a.py": 12.5}, {"a.py": 11.5}, {"a.py": 10.5}, {"a.py": 9.5}],+ )+ assert file_trend(recovering, "a.py").declining is False+++# --------------------------------------------------------------------------- #+# snapshot_file_maps — the writer half+# --------------------------------------------------------------------------- #+++def test_snapshot_file_maps_records_depth_only_at_the_floor():+ metrics = [_Metric("floored.py", SCORE_FLOOR), _Metric("fine.py", 7.5)]+ findings = [+ _Finding("floored.py", 6.0),+ _Finding("floored.py", 6.9),+ _Finding("fine.py", 2.5),+ ]+ scores, deductions = snapshot_file_maps(metrics, findings)+ assert scores == {"floored.py": 1.0, "fine.py": 7.5}+ # Summed across the file's findings, and only for the floored one — the+ # unfloored file's deduction is exactly 10 - 7.5 and needs no storage.+ assert deductions == {"floored.py": 12.9}+++def test_snapshot_file_maps_omits_a_floored_file_with_no_findings():+ # Nothing to sum means nothing is known; recording 0.0 would claim the+ # file is at 10.0 and invert its trend.+ scores, deductions = snapshot_file_maps([_Metric("a.py", SCORE_FLOOR)], [])+ assert scores == {"a.py": 1.0}+ assert deductions == {}+++def test_snapshot_file_maps_ignores_findings_for_unscored_files():+ # Findings can outlive a metric row (a file dropped from this run). The+ # deduction map is keyed off metrics so it cannot grow phantom entries.+ scores, deductions = snapshot_file_maps(+ [_Metric("a.py", SCORE_FLOOR)],+ [_Finding("a.py", 11.0), _Finding("gone.py", 9.0)],+ )+ assert scores == {"a.py": 1.0}+ assert deductions == {"a.py": 11.0}+++def test_snapshot_file_maps_round_trips_into_the_reader():+ # The two halves are written and read by different modules; this pins that+ # they agree on the same file's depth end to end.+ metrics = [_Metric("a.py", SCORE_FLOOR)]+ before = snapshot_file_maps(metrics, [_Finding("a.py", 12.0)])+ after = snapshot_file_maps(metrics, [_Finding("a.py", 10.0)])+ snaps = _floored_series([before[0], after[0]], [before[1], after[1]])+ t = file_trend(snaps, "a.py")+ assert t.delta == 0.0+ assert t.unclamped_delta == 2.0diff --git a/tests/unit/persistence/test_health_snapshot_deductions.py b/tests/unit/persistence/test_health_snapshot_deductions.pynew file mode 100644index 000000000..4e571f0f4--- /dev/null+++ b/tests/unit/persistence/test_health_snapshot_deductions.py@@ -0,0 +1,109 @@+"""The snapshot column that keeps a floored file's trend alive.++``per_file_scores_json`` stores the clamped score, and the score clamps at 1.0.+A file 12.9 points deep and one 9.1 points deep both persist as ``1.0``, so+their whole history is a flat line and doing the work produces no visible+movement. ``per_file_deductions_json`` carries the pre-clamp magnitude for+those files — and only those, since everywhere else it is ``10 - score``.++These pin the storage half. The read half (``unclamped_score``) lives in+``tests/unit/health/test_trends.py``.+"""++from __future__ import annotations++import json+from datetime import UTC, datetime, timedelta++from sqlalchemy import select++from repowise.core.analysis.health.trends import file_trend+from repowise.core.persistence.crud import (+ list_health_snapshots,+ save_health_snapshot,+ upsert_repository,+)+from repowise.core.persistence.models import HealthSnapshot+++async def _snapshot(session, repo_id: str, *, scores, deductions=None, day: int = 0):+ return await save_health_snapshot(+ session,+ repo_id,+ hotspot_health=5.0,+ average_health=5.0,+ worst_performer_path="a.py",+ worst_performer_score=1.0,+ per_file_scores=scores,+ per_file_deductions=deductions,+ taken_at=datetime(2026, 1, 1, tzinfo=UTC) + timedelta(days=day),+ )+++async def test_deductions_are_stored_alongside_the_scores(async_session, tmp_path) -> None:+ repo = await upsert_repository(async_session, name="repo", local_path=str(tmp_path))+ await _snapshot(+ async_session,+ repo.id,+ scores={"a.py": 1.0, "b.py": 7.5},+ deductions={"a.py": 12.9},+ )++ row = (await async_session.execute(select(HealthSnapshot))).scalars().one()++ assert json.loads(row.per_file_scores_json) == {"a.py": 1.0, "b.py": 7.5}+ assert json.loads(row.per_file_deductions_json) == {"a.py": 12.9}+++async def test_the_score_map_keeps_its_shape(async_session, tmp_path) -> None:+ """A sibling column, not a richer value inside the existing blob.++ ``per_file_scores_json`` is parsed as ``{path: score}`` by the trend+ series, the trend route and the snapshot file-count read. A value that+ became a dict would blank every file's series in the first, 500 the second+ and go unnoticed in the third. This asserts the shape is untouched.+ """+ repo = await upsert_repository(async_session, name="repo", local_path=str(tmp_path))+ await _snapshot(async_session, repo.id, scores={"a.py": 1.0}, deductions={"a.py": 11.0})++ row = (await async_session.execute(select(HealthSnapshot))).scalars().one()++ parsed = json.loads(row.per_file_scores_json)+ assert all(isinstance(v, int | float) for v in parsed.values())+++async def test_a_writer_that_passes_no_deductions_stores_an_empty_map(+ async_session, tmp_path+) -> None:+ """The default has to be a parseable empty map, not NULL.++ Every reader does ``json.loads(...)`` on it, and a row written by a caller+ that has not been threaded through — or one that predates the column — has+ to read as "no depth recorded" rather than raise.+ """+ repo = await upsert_repository(async_session, name="repo", local_path=str(tmp_path))+ await _snapshot(async_session, repo.id, scores={"a.py": 1.0})++ row = (await async_session.execute(select(HealthSnapshot))).scalars().one()++ assert row.per_file_deductions_json == "{}"+ assert json.loads(row.per_file_deductions_json) == {}+++async def test_stored_depth_reaches_the_trend_reader(async_session, tmp_path) -> None:+ """End to end through the DB: two snapshots at 1.0, real movement between.++ The write and the read live in different modules and are joined only by+ the column name, so this is the assertion that they actually meet.+ """+ repo = await upsert_repository(async_session, name="repo", local_path=str(tmp_path))+ await _snapshot(async_session, repo.id, scores={"a.py": 1.0}, deductions={"a.py": 12.9}, day=0)+ await _snapshot(async_session, repo.id, scores={"a.py": 1.0}, deductions={"a.py": 10.4}, day=1)++ snapshots = await list_health_snapshots(async_session, repo.id)+ trend = file_trend(snapshots, "a.py")++ assert [p.score for p in trend.points] == [1.0, 1.0]+ assert [p.unclamped_score for p in trend.points] == [-2.9, -0.4]+ assert trend.delta == 0.0+ assert trend.unclamped_delta == 2.5diff --git a/tests/unit/server/test_health_badge.py b/tests/unit/server/test_health_badge.pyindex f3b8845ea..21be7367b 100644--- a/tests/unit/server/test_health_badge.py+++ b/tests/unit/server/test_health_badge.py@@ -54,6 +54,10 @@ def test_file_trend_to_dict_thin_history() -> None:"current": None,"previous": None,"delta": None,+ # Null alongside ``delta``, not absent: a thin history has no movement+ # to report on either series, and a consumer reading+ # ``unclamped_delta ?? delta`` must not fall through to a stale number.+ "unclamped_delta": None,"declining": False,"snapshot_count": 1,}@@ -65,20 +69,29 @@ def test_file_trend_to_dict_serializes_points() -> None:t = FileTrend(file_path="a.py",points=[- FileTrendPoint(taken_at=datetime(2026, 1, 1, tzinfo=UTC), score=8.0),- FileTrendPoint(taken_at=None, score=6.5),+ FileTrendPoint(+ taken_at=datetime(2026, 1, 1, tzinfo=UTC), score=8.0, unclamped_score=8.0+ ),+ # Sitting on the floor with the real depth recorded: the point the+ # serializer has to carry both numbers for.+ FileTrendPoint(taken_at=None, score=1.0, unclamped_score=-2.9),],- current=6.5,+ current=1.0,previous=8.0,- delta=-1.5,+ delta=-7.0,+ unclamped_delta=-10.9,declining=True,snapshot_count=2,)d = _file_trend_to_dict(t)assert d["points"][0]["taken_at"] == "2026-01-01T00:00:00+00:00"assert d["points"][0]["score"] == 8.0+ assert d["points"][0]["unclamped_score"] == 8.0assert d["points"][1]["taken_at"] is None- assert d["delta"] == -1.5+ assert d["points"][1]["score"] == 1.0+ assert d["points"][1]["unclamped_score"] == -2.9+ assert d["delta"] == -7.0+ assert d["unclamped_delta"] == -10.9assert d["declining"] is Truediff --git a/tests/unit/server/test_health_trend_route.py b/tests/unit/server/test_health_trend_route.pynew file mode 100644index 000000000..5eb3670bf--- /dev/null+++ b/tests/unit/server/test_health_trend_route.py@@ -0,0 +1,154 @@+"""``/health/trend``'s per-file movement block.++The block is headed "Largest score changes since last index" and was built by+sorting the deltas ascending and slicing the first 50 — that is, the 50+biggest *drops*. Improvements only appeared while fewer than 50 files had+regressed, so the one index that most wants to show progress, the one after a+cleanup or a re-score, is the one that hides it. And with no total beside the+slice a reader could not tell a complete list from a truncated one.++Measured on the repowise index when this was written: only 15 files moved+between the last two snapshots, so the cap was latent — but the oldest-vs-newest+comparison, which is the shape a full re-index produces, moves 183 files with+107 regressions. These construct that state rather than waiting for it.+"""++from __future__ import annotations++from datetime import UTC, datetime, timedelta++from repowise.core.persistence.crud import save_health_snapshot, upsert_repository+from repowise.server.routers.code_health.trends_routes import FILE_DELTA_LIMIT++from .conftest import create_test_repo+++async def _two_snapshots(session, repo_id: str, before: dict, after: dict) -> None:+ base = datetime(2026, 1, 1, tzinfo=UTC)+ for day, scores in ((0, before), (1, after)):+ await save_health_snapshot(+ session,+ repo_id,+ hotspot_health=5.0,+ average_health=5.0,+ worst_performer_path="a.py",+ worst_performer_score=1.0,+ per_file_scores=scores,+ taken_at=base + timedelta(days=day),+ )+ await session.commit()+++async def _repo(client, session, tmp_path):+ repo = await create_test_repo(client, tmp_path)+ await upsert_repository(session, name="r", local_path=repo["local_path"])+ return repo["id"]+++async def test_improvements_survive_a_wall_of_regressions(client, session, tmp_path) -> None:+ """The failure the ascending sort produced, constructed exactly.++ ``FILE_DELTA_LIMIT`` + 10 files regress by a little and three improve by a+ lot. Sorted ascending, the improvements sit past the end of the slice and+ never reach the page, even though they are the largest changes in the repo.+ """+ repo_id = await _repo(client, session, tmp_path)+ before = {f"r{i}.py": 8.0 for i in range(FILE_DELTA_LIMIT + 10)}+ after = {f"r{i}.py": 7.9 for i in range(FILE_DELTA_LIMIT + 10)}+ for i in range(3):+ before[f"win{i}.py"] = 2.0+ after[f"win{i}.py"] = 9.0++ await _two_snapshots(session, repo_id, before, after)+ resp = await client.get(f"/api/repos/{repo_id}/health/trend")+ assert resp.status_code == 200, resp.text+ body = resp.json()++ paths = [d["file_path"] for d in body["file_deltas"]]+ assert [p for p in paths if p.startswith("win")] == ["win0.py", "win1.py", "win2.py"]+ # And they lead, because they are the biggest movements in either direction.+ assert paths[:3] == ["win0.py", "win1.py", "win2.py"]+++async def test_the_total_counts_everything_the_slice_dropped(client, session, tmp_path) -> None:+ repo_id = await _repo(client, session, tmp_path)+ n = FILE_DELTA_LIMIT + 27+ before = {f"f{i}.py": 8.0 for i in range(n)}+ # Distinct magnitudes so the ordering is total and the slice is well-defined.+ after = {f"f{i}.py": 8.0 - (i + 1) / 100 for i in range(n)}+ await _two_snapshots(session, repo_id, before, after)++ body = (await client.get(f"/api/repos/{repo_id}/health/trend")).json()++ assert len(body["file_deltas"]) == FILE_DELTA_LIMIT+ assert body["file_deltas_total"] == n+++async def test_the_total_equals_the_list_when_nothing_is_dropped(+ client, session, tmp_path+) -> None:+ """The common case, and the one that makes the UI say "all N" rather than+ "the N largest of N"."""+ repo_id = await _repo(client, session, tmp_path)+ await _two_snapshots(+ session, repo_id, {"a.py": 8.0, "b.py": 5.0}, {"a.py": 7.0, "b.py": 6.0}+ )++ body = (await client.get(f"/api/repos/{repo_id}/health/trend")).json()++ assert body["file_deltas_total"] == 2 == len(body["file_deltas"])+++async def test_unchanged_files_are_not_counted_as_movement(client, session, tmp_path) -> None:+ """``file_deltas_total`` counts files that moved, not files that exist —+ otherwise "3 of 3,263" would read as though the repo barely changed.++ A guard, not a regression test: the zero-delta filter predates this change,+ so only the ``file_deltas_total`` lookup fails on revert.+ """+ repo_id = await _repo(client, session, tmp_path)+ before = {f"f{i}.py": 8.0 for i in range(20)}+ after = dict(before)+ after["f0.py"] = 6.0++ await _two_snapshots(session, repo_id, before, after)+ body = (await client.get(f"/api/repos/{repo_id}/health/trend")).json()++ assert body["file_deltas_total"] == 1+++async def test_ordering_is_total_across_equal_magnitudes(client, session, tmp_path) -> None:+ """Ties broken by path, so the slice boundary cannot shuffle between+ requests — the set membership of a truncated list has to be stable."""+ repo_id = await _repo(client, session, tmp_path)+ before = {"c.py": 8.0, "a.py": 8.0, "b.py": 8.0}+ # Same magnitude, opposite directions: a |delta| sort alone is ambiguous.+ after = {"c.py": 7.0, "a.py": 9.0, "b.py": 7.0}+ await _two_snapshots(session, repo_id, before, after)++ body = (await client.get(f"/api/repos/{repo_id}/health/trend")).json()++ assert [d["file_path"] for d in body["file_deltas"]] == ["a.py", "b.py", "c.py"]+++async def test_a_single_snapshot_reports_no_movement(client, session, tmp_path) -> None:+ """Zero-history edge: the block is empty and the total says so rather than+ being absent, so the UI never has to guess whether the field is missing or+ the answer is nothing."""+ repo_id = await _repo(client, session, tmp_path)+ await save_health_snapshot(+ session,+ repo_id,+ hotspot_health=5.0,+ average_health=5.0,+ worst_performer_path=None,+ worst_performer_score=None,+ per_file_scores={"a.py": 5.0},+ )+ await session.commit()++ body = (await client.get(f"/api/repos/{repo_id}/health/trend")).json()++ assert body["file_deltas"] == []+ assert body["file_deltas_total"] == 0+ assert body["snapshot_count"] == 1