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.

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.md
index 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, the
health-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 we
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py b/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
index 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_maps
from 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.py
index 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_maps
from 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.py
deleted file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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 signals
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index 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 replace
from .biomarkers.base import BiomarkerResult
from .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 * scale
total += cap
- score = max(1.0, min(10.0, 10.0 - total))
+ score = max(SCORE_FLOOR, min(SCORE_MAX, SCORE_MAX - total))
return score, per_result
diff --git a/packages/core/src/repowise/core/analysis/health/trends.py b/packages/core/src/repowise/core/analysis/health/trends.py
index 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, field
from datetime import datetime
from typing import Any
+from .scoring import SCORE_FLOOR, SCORE_MAX
+
DECLINE_THRESHOLD: float = 0.5
DECLINE_LOOKBACK: int = 5 # compare current vs snapshot N positions back
PREDICTED_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
+
+
@dataclass
class 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 | None
score: float
+ unclamped_score: float
@dataclass
@@ -220,6 +283,12 @@ class FileTrend:
drawing a misleading single dot (plan §2: "silent when < 2 real
snapshots"). ``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 | None
declining: bool
snapshot_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 None
try:
- 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 None
if val is None:
return None
try:
@@ -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-comment
sparkline, 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 the
tail is ``PREDICTED_DECLINE_CONSECUTIVE`` strict drops in a row. Single
snapshot-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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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 analysis
phase has fully completed.
"""
+ from repowise.core.analysis.health.trends import snapshot_file_maps
from 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.py
index 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"] = trends
if 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.py
index 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 Any
from repowise.core.analysis.health.models import Severity
from 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.py
index 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.py
index 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_session
from ._router import router
from .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:
continue
file_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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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 }: FileTrendC
least 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 }: FileTrendC
Declining
</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}>
<line
x1={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.tsx
index 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.py
new file mode 100644
index 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.py
index fade99c85..dc5e2b98a 100644
--- a/tests/unit/health/test_trends.py
+++ b/tests/unit/health/test_trends.py
@@ -6,6 +6,7 @@ import json
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
+from repowise.core.analysis.health.scoring import SCORE_FLOOR
from 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.0
per_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.0
diff --git a/tests/unit/persistence/test_health_snapshot_deductions.py b/tests/unit/persistence/test_health_snapshot_deductions.py
new file mode 100644
index 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.5
diff --git a/tests/unit/server/test_health_badge.py b/tests/unit/server/test_health_badge.py
index 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.0
assert 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.9
assert d["declining"] is True
diff --git a/tests/unit/server/test_health_trend_route.py b/tests/unit/server/test_health_trend_route.py
new file mode 100644
index 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