Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(health): lead with one score, and let the reader choose what it counts (#2164)
Raghav Chamadiyad019d389abe4
diff --git a/packages/api-client/src/code-health.ts b/packages/api-client/src/code-health.tsindex 2c651e703..8eef9d10c 100644--- a/packages/api-client/src/code-health.ts+++ b/packages/api-client/src/code-health.ts@@ -22,6 +22,7 @@ import type {HealthWorkQueueQuery,HealthWorkQueueResponse,HealthScope,+ HealthCounts,} from "@repowise-dev/types/health";import type { Paginated } from "@repowise-dev/types";import { apiGet, apiPatch } from "./client";@@ -51,6 +52,7 @@ export type {HealthMapSelection,HealthModuleRow,HealthOverviewResponse,+ HealthCounts,HealthScope,HealthTrendResponse,HealthWorkItem,@@ -76,10 +78,11 @@ export async function getHealthOverview(repoId: string,limit = 25,scope?: HealthScope,+ counts?: HealthCounts,): Promise<HealthOverviewResponse> {return apiGet<HealthOverviewResponse>(`/api/repos/${repoId}/health/overview`,- { limit, scope },+ { limit, scope, counts },);}@@ -92,6 +95,7 @@ export async function listHealthFindings(dimension?: string;limit?: number;scope?: HealthScope;+ counts?: HealthCounts;},): Promise<HealthFinding[]> {return apiGet<HealthFinding[]>(`/api/repos/${repoId}/health/findings`, opts);@@ -158,6 +162,7 @@ export async function getHealthMap(cap: opts.cap,active: opts.active?.length ? opts.active.join(",") : undefined,scope: opts.scope,+ counts: opts.counts,});}@@ -174,10 +179,11 @@ export async function listHealthFiles(export async function getHealthFileBreakdown(repoId: string,filePath: string,+ counts?: HealthCounts,): Promise<HealthFileBreakdownResponse> {return apiGet<HealthFileBreakdownResponse>(`/api/repos/${repoId}/health/files/breakdown`,- { file_path: filePath },+ { file_path: filePath, counts },);}diff --git a/packages/core/src/repowise/core/analysis/health/counts.py b/packages/core/src/repowise/core/analysis/health/counts.pynew file mode 100644index 000000000..f4c52765c--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/counts.py@@ -0,0 +1,89 @@+"""Whether a code-health figure counts change history or only code shape.++Roughly half of a file's deduction comes from git-derived markers — churn,+co-change, ownership, prior fixes — which rise as a file is worked on. That is+correct for predicting defects and useless for answering "is my code getting+better", so the page lets a reader drop that half and score the code alone.++The projection needs no rescore: both halves are stored per file, and the+scorer's own arithmetic is ``clamp(SCORE_MAX - structure - history)``, so+leaving one out is a subtraction rather than a second pass over the findings.+"""++from __future__ import annotations++from typing import Any, Literal++from .scoring import SCORE_FLOOR, SCORE_MAX++HealthCounts = Literal["everything", "code_shape"]+DEFAULT_COUNTS: HealthCounts = "everything"+COUNTS: tuple[HealthCounts, ...] = ("everything", "code_shape")+++def parse_counts(value: str | None) -> HealthCounts:+ """Read a value, falling back to the default on anything unknown.++ The REST layer declares a pattern and refuses a bad value before this runs,+ so the fallback is for internal callers passing a stored or computed string.+ """+ return value if value in COUNTS else DEFAULT_COUNTS # type: ignore[return-value]+++def code_shape_score(structure_deduction: float | None) -> float | None:+ """A file's score with the history half removed, clamped like any score.++ ``None`` when the split was never recorded, which is every row written+ before it existed. Coercing a missing half to zero would print a confident+ 10.0 for a file nobody has measured.+ """+ if structure_deduction is None:+ return None+ return max(SCORE_FLOOR, min(SCORE_MAX, SCORE_MAX - structure_deduction))+++class CodeShapeMetric:+ """One metric row read with the history half of its score removed.++ A wrapper rather than a mutation. The rows handed to a route are live ORM+ objects, so assigning a projected score to one would mark it dirty and+ write the projection back to the store on the next flush.+ """++ # ``score`` is the surfaced number every aggregate weights and+ # ``defect_score`` mirrors it on the wire; both move or the page disagrees+ # with itself. ``history_deduction`` reads 0.0 because that is what this+ # reading counts, which keeps every figure derived from the two halves —+ # the wire row's ``unclamped_score``, the summary's history average — in+ # step with the score beside it rather than describing the other reading.+ # Everything else falls through to the row.+ __slots__ = ("_row", "defect_score", "history_deduction", "score")++ def __init__(self, row: Any, score: float) -> None:+ object.__setattr__(self, "_row", row)+ object.__setattr__(self, "score", score)+ object.__setattr__(self, "defect_score", score)+ object.__setattr__(self, "history_deduction", 0.0)++ def __getattr__(self, name: str) -> Any:+ return getattr(self._row, name)+++def project(counts: str, metrics: list[Any]) -> tuple[list[Any], int]:+ """Re-read *metrics* under *counts*, dropping rows it cannot answer for.++ Returns the projected rows and how many were dropped for want of a+ recorded split, so a caller can say "not measured" rather than imply the+ repository shrank.+ """+ if parse_counts(counts) != "code_shape":+ return metrics, 0+ out: list[Any] = []+ unmeasured = 0+ for m in metrics:+ score = code_shape_score(getattr(m, "structure_deduction", None))+ if score is None:+ unmeasured += 1+ continue+ out.append(CodeShapeMetric(m, score))+ return out, unmeasureddiff --git a/packages/server/src/repowise/server/routers/code_health/counts.py b/packages/server/src/repowise/server/routers/code_health/counts.pynew file mode 100644index 000000000..b7a920974--- /dev/null+++ b/packages/server/src/repowise/server/routers/code_health/counts.py@@ -0,0 +1,40 @@+"""Reading a code-health response with or without its change-history half."""++from __future__ import annotations++from typing import Any++from fastapi import Query++from repowise.core.analysis.health.counts import COUNTS, DEFAULT_COUNTS, parse_counts+from repowise.core.analysis.health.counts import project as project_metrics+from repowise.core.analysis.health.models import split_by_origin++CountsQuery = Query(+ DEFAULT_COUNTS,+ description=(+ "What the score counts: 'everything' (code shape and change history, as "+ "calibrated) or 'code_shape' (the git-derived half removed). Change "+ "history rises as a file is worked on, so it answers what a repository "+ "has been through rather than what its code is like."+ ),+ pattern=f"^({'|'.join(COUNTS)})$",+)+++def project(+ counts: str, metrics: list[Any], *findings: list[Any]+) -> tuple[Any, ...]:+ """Re-score *metrics* under *counts*, returning ``(rows, ..., unscored)``.++ The findings a reading stops counting are dropped with it: under+ ``code_shape`` a history finding contributes to no figure on the page, so+ leaving it in the lists would show work that sums past the score it sits+ under. The count of rows the reading could not answer for is returned+ alongside rather than recomputed, which on a large repo is a second walk of+ the whole table building a second set of wrappers.+ """+ projected, unscored = project_metrics(counts, metrics)+ if parse_counts(counts) != "code_shape":+ return (projected, *findings, unscored)+ return (projected, *(split_by_origin(rows)[0] for rows in findings), unscored)diff --git a/packages/server/src/repowise/server/routers/code_health/files_routes.py b/packages/server/src/repowise/server/routers/code_health/files_routes.pyindex c85929490..50ce386db 100644--- a/packages/server/src/repowise/server/routers/code_health/files_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/files_routes.py@@ -15,6 +15,7 @@ from repowise.server.deps import get_db_sessionfrom ._router import routerfrom .breakdown import _score_breakdown_from_findings+from .counts import CountsQuery, projectfrom .loaders import _attach_symbol_ids, _load_file_signalsfrom .scope import ScopeQuery, narrowfrom .serializers import (@@ -60,12 +61,16 @@ async def list_health_files(),),scope: str = ScopeQuery,+ counts: str = CountsQuery,session: AsyncSession = Depends(get_db_session),) -> dict:if sort not in _SORT_FIELDS:sort = "score"metrics = await crud.get_health_metrics(session, repo_id)(metrics,) = narrow(scope, metrics)+ # Projected before every filter and the sort, so `total` and the ranking+ # describe the same population the score does.+ metrics, _unscored = project(counts, metrics)hotspot_paths: set[str] = set()if only_hotspots:@@ -146,14 +151,19 @@ async def list_health_files(async def file_score_breakdown(repo_id: str,file_path: str = Query(..., description="File path to break down"),+ counts: str = CountsQuery,session: AsyncSession = Depends(get_db_session),) -> dict:repo = await crud.get_repository(session, repo_id)if repo is None:raise HTTPException(status_code=404, detail="Repository not found")metrics = await crud.get_health_metrics(session, repo_id, file_paths=[file_path])- metric = metrics[0] if metrics else Nonefindings = await crud.get_health_findings(session, repo_id, file_path=file_path)+ # This drawer opens from a row the reader just saw a score on. Reading it+ # under the other counts would answer a click on 8.5 with a 2.0 and list+ # the findings the page had just said were excluded.+ metrics, findings, _unscored = project(counts, metrics, findings)+ metric = metrics[0] if metrics else Nonebreakdown = _score_breakdown_from_findings(findings)finding_dicts = await _attach_symbol_ids(session, repo_id, [_finding_to_dict(f) for f in findings]diff --git a/packages/server/src/repowise/server/routers/code_health/findings_routes.py b/packages/server/src/repowise/server/routers/code_health/findings_routes.pyindex f8c5d5e80..45fe5f552 100644--- a/packages/server/src/repowise/server/routers/code_health/findings_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/findings_routes.py@@ -6,6 +6,8 @@ from fastapi import Depends, HTTPException, Queryfrom pydantic import BaseModel, Fieldfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.counts import parse_counts+from repowise.core.analysis.health.models import split_by_originfrom repowise.core.analysis.health.scope import parse_scopefrom repowise.core.persistence import crudfrom repowise.server.deps import get_db_session@@ -15,6 +17,7 @@ from repowise.server.schemas import ()from ._router import router+from .counts import CountsQueryfrom .loaders import _attach_symbol_idsfrom .scope import ScopeQuery, narrowfrom .serializers import _finding_to_dict@@ -32,6 +35,7 @@ async def list_health_findings(dimension: str | None = Query(None),limit: int = Query(100, ge=1, le=1000),scope: str = ScopeQuery,+ counts: str = CountsQuery,session: AsyncSession = Depends(get_db_session),) -> list[dict]:"""Open findings, ranked by health impact.@@ -57,6 +61,10 @@ async def list_health_findings(if parse_scope(scope) == "production":metrics = await crud.get_health_metrics(session, repo_id)_, findings = narrow(scope, metrics, findings)+ # A history finding contributes nothing to a code-shape score, so listing+ # it under one would show work that sums past the figure above it.+ if parse_counts(counts) == "code_shape":+ findings = split_by_origin(findings)[0]return await _attach_symbol_ids(session, repo_id, [_finding_to_dict(f) for f in findings[:limit]])diff --git a/packages/server/src/repowise/server/routers/code_health/map_routes.py b/packages/server/src/repowise/server/routers/code_health/map_routes.pyindex e6b50acc7..44974317e 100644--- a/packages/server/src/repowise/server/routers/code_health/map_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/map_routes.py@@ -21,6 +21,7 @@ from repowise.server.services.health_map import ()from ._router import router+from .counts import CountsQueryfrom .scope import ScopeQuery@@ -37,10 +38,11 @@ async def get_health_map(),),scope: str = ScopeQuery,+ counts: str = CountsQuery,session: AsyncSession = Depends(get_db_session),) -> dict[str, Any]:"""One bounded field plus the exact scope of what the cap left out."""feed = await HealthMapService(session, repo_id).feed(- cap=cap, active=parse_active(active), scope=scope+ cap=cap, active=parse_active(active), scope=scope, counts=counts)return feed.payload()diff --git a/packages/server/src/repowise/server/routers/code_health/overview_routes.py b/packages/server/src/repowise/server/routers/code_health/overview_routes.pyindex 9c67734a9..cbc954fe5 100644--- a/packages/server/src/repowise/server/routers/code_health/overview_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/overview_routes.py@@ -22,6 +22,7 @@ from repowise.server.deps import get_db_sessionfrom repowise.server.mcp_server._meta import resolve_indexed_commitfrom ._router import router+from .counts import CountsQuery, projectfrom .loaders import _attach_symbol_idsfrom .scope import ScopeQuery, narrowfrom .serializers import _finding_to_dict, _leads_by_file, _metric_to_dict@@ -51,6 +52,7 @@ async def health_overview(repo_id: str,limit: int = Query(20, ge=1, le=200),scope: str = ScopeQuery,+ counts: str = CountsQuery,session: AsyncSession = Depends(get_db_session),) -> dict:"""KPIs + lowest-scoring files + per-module rollup + meta."""@@ -65,6 +67,10 @@ async def health_overview(metrics = await crud.get_health_metrics(session, repo_id)findings = await crud.get_health_findings(session, repo_id)metrics, findings = narrow(scope, metrics, findings)+ # Every figure below is computed from these two lists, so projecting here+ # is what keeps the headline, the distribution, the hotspot figure and the+ # work the page lists all describing the same thing.+ metrics, findings, unscored = project(counts, metrics, findings)summary = await crud.get_health_summary(session, repo_id, metrics=metrics, findings=findings)@@ -91,6 +97,10 @@ async def health_overview(**summary,"hotspot_health": hotspot_health_value,"severity_breakdown": severity_breakdown(findings),+ # Echoed so a surface labels what it was sent rather than what it+ # asked for; the two differ while a request is in flight.+ "counts": counts,+ "unscored_files": unscored,"band": band_for(float(avg)) if avg is not None else None,}distribution = health_distribution(metric_dicts)diff --git a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.pyindex 77144efb3..3846f06d9 100644--- a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py@@ -18,6 +18,7 @@ from repowise.server.deps import get_db_sessionfrom repowise.server.schemas import HealthWorkQueueResponsefrom ._router import router+from .counts import CountsQuery, projectfrom .scope import ScopeQuery, narrow_SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2, "critical": 3}@@ -67,6 +68,7 @@ async def health_work_queue("impact_per_effort", pattern="^(impact_per_effort|total_impact|score|finding_count)$"),scope: str = ScopeQuery,+ counts: str = CountsQuery,session: AsyncSession = Depends(get_db_session),) -> dict:"""Health work items ranked by impact / effort.@@ -86,6 +88,7 @@ async def health_work_queue(metrics = await crud.get_health_metrics(session, repo_id)findings = await crud.get_health_findings(session, repo_id)metrics, findings = narrow(scope, metrics, findings)+ metrics, findings, _unscored = project(counts, metrics, findings)metric_by_path = {m.file_path: m for m in metrics}by_file: dict[str, list[Any]] = {}@@ -106,8 +109,14 @@ async def health_work_queue(if module and not file_path.startswith(module):continuem = metric_by_path.get(file_path)- nloc = m.nloc if m is not None else 0- score = m.score if m is not None else 10.0+ # No metric row means this reading cannot score the file: under+ # ``code_shape`` that is a row with no recorded split. Ranking it on a+ # stand-in 10.0 would put an unmeasured file at the top of a list+ # ordered by how bad things are.+ if m is None:+ continue+ nloc = m.nloc+ score = m.scoreprimary = primary_finding(fs)total_impact = round(sum(x.health_impact for x in fs), 3)effort_bucket = _effort_for_nloc(nloc)diff --git a/packages/server/src/repowise/server/services/health_map.py b/packages/server/src/repowise/server/services/health_map.pyindex 8d7a27ad9..0d03e3da5 100644--- a/packages/server/src/repowise/server/services/health_map.py+++ b/packages/server/src/repowise/server/services/health_map.py@@ -20,6 +20,8 @@ from typing import Anyfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.counts import DEFAULT_COUNTS+from repowise.core.analysis.health.counts import project as project_countsfrom repowise.core.analysis.health.perf.coverage import supported_perf_languagesfrom repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scopefrom repowise.core.persistence import crud@@ -60,10 +62,12 @@ class HealthMapFeed:performance: dict[str, Any] | None = None#: Which half of the repository the field describes.scope: str = DEFAULT_SCOPE+ counts: str = DEFAULT_COUNTSdef payload(self) -> dict[str, Any]:return {"scope": self.scope,+ "counts": self.counts,"files": self.files,"cap": self.cap,"shown": self.shown,@@ -108,6 +112,7 @@ class HealthMapService:cap: int = DEFAULT_MAP_CAP,active: tuple[str, ...] = (),scope: str = DEFAULT_SCOPE,+ counts: str = DEFAULT_COUNTS,) -> HealthMapFeed:session, repo_id = self._session, self._repository_idmetrics = await crud.get_health_metrics(session, repo_id)@@ -122,6 +127,18 @@ class HealthMapService:kept = {m.file_path for m in metrics}rollups = [r for r in rollups if r.file_path in kept]+ # Re-marks the same field: every node keeps its size and its module,+ # and only the colour moves. A file with no recorded split cannot be+ # coloured on this basis, so it leaves the field rather than sitting+ # there in whatever colour it last had.+ #+ # ``rollups`` is deliberately left whole. The page says performance is+ # scored separately and never blended into health, so its totals must+ # not move when the health reading does; only the per-node join below+ # narrows, and a node that is not drawn simply never looks one up.+ counted = len(metrics)+ metrics, _ = project_counts(counts, metrics)+by_path = {m.file_path: m for m in metrics}# A zero-NLOC file cannot be sized, and the map drops it on arrival.# Counting it as eligible would promise a node that never appears.@@ -175,7 +192,7 @@ class HealthMapService:cap=cap,shown=len(chosen),eligible_total=len(eligible),- repository_total=len(metrics),+ repository_total=counted,selection={"basis": "active_then_performance_then_nloc","active_requested": list(active),@@ -208,6 +225,7 @@ class HealthMapService:else self._performance_block(rollups, summary, len(performance_eligible))),scope=DEFAULT_SCOPE if not scope_narrowed else "production",+ counts=counts,)def _row(diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 8b4df46fd..523c385b0 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -48,6 +48,15 @@ export const HEALTH_DIMENSIONS: readonly HealthDimension[] = ["performance",] as const;+/**+ * What a code-health figure counts. `everything` is the calibrated score;+ * `code_shape` removes the git-derived half, which rises as a file is worked+ * on and so answers what a repository has been through rather than what its+ * code is like.+ */+export type HealthCounts = "everything" | "code_shape";+export const HEALTH_COUNTS: readonly HealthCounts[] = ["everything", "code_shape"] as const;+/*** Which half of a repository a health figure describes. Tests score higher* than production code, so narrowing lowers every figure without a defect@@ -544,6 +553,10 @@ export interface HealthOverviewSummary {*/structure_average?: number | null;history_average?: number | null;+ /** What this response counted. Echoed so a label cannot get ahead of its data. */+ counts?: HealthCounts;+ /** Files a code-shape reading cannot answer for, having no recorded split. */+ unscored_files?: number;}export interface HealthOverviewResponse {@@ -574,6 +587,7 @@ export interface HealthFilesResponse {}export interface HealthFilesQuery {+ counts?: HealthCounts;/** Which half of the repository to describe. Defaults to `"all"`. */scope?: HealthScope;limit?: number;@@ -679,6 +693,7 @@ export interface HealthMapFeed {}export interface HealthMapQuery {+ counts?: HealthCounts;cap?: number;/** Paths guaranteed a node, admitted before any other band. */active?: string[];@@ -1065,6 +1080,7 @@ export interface HealthWorkQueueResponse {}export interface HealthWorkQueueQuery {+ counts?: HealthCounts;limit?: number;module?: string;biomarker?: string;diff --git a/packages/ui/__tests__/health/code-health-lede.test.tsx b/packages/ui/__tests__/health/code-health-lede.test.tsxnew file mode 100644index 000000000..428a8e675--- /dev/null+++ b/packages/ui/__tests__/health/code-health-lede.test.tsx@@ -0,0 +1,107 @@+import { describe, it, expect } from "vitest";+import { render, screen } from "@testing-library/react";+import type { HealthOverviewSummary } from "@repowise-dev/types/health";+import { CodeHealthLede } from "../../src/health/code-health-lede.js";++function summary(partial: Partial<HealthOverviewSummary> = {}): HealthOverviewSummary {+ return {+ average_health: 7.0,+ maintainability_average: 8.0,+ hotspot_health: 4.5,+ performance_average: 9.7,+ performance_findings: 942,+ file_count: 3787,+ open_findings: 14755,+ structure_average: 1.59,+ history_average: 1.44,+ ...partial,+ } as HealthOverviewSummary;+}++describe("CodeHealthLede — how many scores the first screen carries", () => {+ // The page used to print Structure 8.4 beside Maintainability 8.0. Both are+ // code-shape readings on the same 0-10 scale, so the screen answered "which+ // number do I steer by?" twice, with two different numbers. The history half+ // is a share of the deduction now, which says the same thing without minting+ // a rival score.++ it("states the history share rather than a second score out of 10", () => {+ render(<CodeHealthLede summary={summary()} />);+ expect(screen.getByText("48%")).toBeTruthy();+ expect(screen.getByText(/comes from change history, not from the code/)).toBeTruthy();+ });++ it("no longer prints a structure figure", () => {+ const { container } = render(<CodeHealthLede summary={summary()} />);+ expect(container.textContent).not.toContain("Structure");+ expect(container.textContent).not.toContain("8.4");+ });++ it("carries one score out of 10, with Maintainability demoted to the ribbon", () => {+ const { container } = render(<CodeHealthLede summary={summary()} />);+ // The headline is the only figure at lede weight; Maintainability is still+ // on the page, as a ribbon stat beside the other cuts of the same scoring.+ expect(container.querySelectorAll("dt")).toHaveLength(4);+ expect(screen.getByText("Code health")).toBeTruthy();+ expect(screen.getByText("Maintainability")).toBeTruthy();+ expect(screen.getByText("8.0")).toBeTruthy();+ expect(screen.getAllByText("out of 10")).toHaveLength(1);+ });++ it("drops Open findings, which the tab row already counts", () => {+ render(<CodeHealthLede summary={summary()} />);+ expect(screen.queryByText("Open findings")).toBeNull();+ });++ it("gives every figure an explainer a reader can open", () => {+ render(<CodeHealthLede summary={summary()} />);+ for (const label of ["Code health", "Files", "Maintainability", "Performance risk", "Hotspot health"]) {+ expect(screen.getByLabelText(`What ${label} means`)).toBeTruthy();+ }+ });++ it("says nothing when the split was never recorded", () => {+ const { container } = render(+ <CodeHealthLede summary={summary({ structure_average: null, history_average: null })} />,+ );+ expect(container.textContent).not.toContain("comes from change history");+ });+});++describe("CodeHealthLede — the two readings of one figure", () => {+ it("names change history as the reason when it is counted", () => {+ render(<CodeHealthLede summary={summary({ counts: "everything" })} />);+ expect(screen.getByText(/comes from change history, not from the code/)).toBeTruthy();+ });++ it("says what it excluded, and that the findings now add up", () => {+ render(<CodeHealthLede summary={summary({ counts: "code_shape" })} />);+ expect(+ screen.getByText(/Change history excluded\. This scores the code alone/),+ ).toBeTruthy();+ expect(screen.queryByText(/comes from change history/)).toBeNull();+ });++ it("stops claiming churn and ownership are inputs once they are not", () => {+ const { container } = render(<CodeHealthLede summary={summary({ counts: "code_shape" })} />);+ expect(container.textContent).not.toContain("churn and ownership");+ });++ it("drops the bug-prediction claim, which only the calibrated score earns", () => {+ const accuracy = { hits: 20, k: 20, precision: 1, base_rate: 0.41, lift: 2.43, window_days: 180 };+ const withClaim = render(+ <CodeHealthLede summary={summary({ counts: "everything" })} accuracy={accuracy as never} />,+ );+ expect(withClaim.container.textContent).toContain("Ranked against real bug-fix history");+ withClaim.unmount();+ const withoutClaim = render(+ <CodeHealthLede summary={summary({ counts: "code_shape" })} accuracy={accuracy as never} />,+ );+ expect(withoutClaim.container.textContent).not.toContain("Ranked against real bug-fix history");+ });++ it("owns up to files it cannot score on this basis", () => {+ render(<CodeHealthLede summary={summary({ counts: "code_shape", unscored_files: 287 })} />);+ expect(screen.getByText(/287 files are not scored here/)).toBeTruthy();+ });+});diff --git a/packages/ui/src/git/churn-bar.tsx b/packages/ui/src/git/churn-bar.tsxindex 011204792..97e5ee74e 100644--- a/packages/ui/src/git/churn-bar.tsx+++ b/packages/ui/src/git/churn-bar.tsx@@ -3,15 +3,25 @@ import { cn } from "../lib/cn";interface ChurnBarProps {percentile: number;className?: string;+ /**+ * `"scale"` grades the value red/amber/green. `"neutral"` draws the same+ * length in one quiet colour, for a table that is already sorted by this+ * number: every row of a hotspot list is high-churn by definition, so+ * grading them paints the whole column red and reads as an alarm about+ * something that is merely the subject of the table.+ */+ tone?: "scale" | "neutral";}-export function ChurnBar({ percentile, className }: ChurnBarProps) {+export function ChurnBar({ percentile, className, tone = "scale" }: ChurnBarProps) {const color =- percentile >= 75- ? "bg-[var(--color-error)]"- : percentile >= 50- ? "bg-[var(--color-warning)]"- : "bg-[var(--color-success)]";+ tone === "neutral"+ ? "bg-[var(--color-text-tertiary)]"+ : percentile >= 75+ ? "bg-[var(--color-error)]"+ : percentile >= 50+ ? "bg-[var(--color-warning)]"+ : "bg-[var(--color-success)]";return (<div className={cn("h-1.5 w-full rounded-full bg-[var(--color-bg-elevated)]", className)}>diff --git a/packages/ui/src/git/hotspot-table.tsx b/packages/ui/src/git/hotspot-table.tsxindex 40e9c25a8..21d5292d4 100644--- a/packages/ui/src/git/hotspot-table.tsx+++ b/packages/ui/src/git/hotspot-table.tsx@@ -2,12 +2,11 @@import * as React from "react";import { useState, useMemo } from "react";-import { TrendingUp, TrendingDown, Search, Flame, Bug, ArrowUpDown, ArrowUp, ArrowDown, GitBranch, BookOpen, Radius, ChevronRight, ChevronDown } from "lucide-react";+import { TrendingUp, TrendingDown, Search, Flame, Bug, ArrowUpDown, ArrowUp, ArrowDown, ChevronRight, ChevronDown } from "lucide-react";import { Badge } from "../ui/badge";import { Input } from "../ui/input";import { EmptyState } from "../shared/empty-state";import { ResultsFooter } from "../shared/results-footer";-import { RowActions } from "../shared/row-actions";import { AiPromptButton } from "../health/ai-prompt-button";import { ChurnBar } from "./churn-bar";import { formatLOC } from "../lib/format";@@ -15,7 +14,6 @@ import { summarizeFixHistory } from "../lib/fix-history";import { cn } from "../lib/cn";import { useVirtualRows } from "../shared/virtualized-table";import { clickableRowProps, CLICKABLE_ROW_CLS } from "../shared/responsive-table";-import { docsPagePath, filePageId } from "../shared/entity/routes";import type { Hotspot } from "@repowise-dev/types/git";/**@@ -27,6 +25,12 @@ const ESTIMATED_ROW_HEIGHT = 44;interface HotspotTableProps {hotspots: Hotspot[];+ /**+ * Kept for callers that still pass them. The rows carried a Graph / Docs /+ * Blast Radius menu built from these; a table already sorted by risk did not+ * need three links per row competing with the row's own click, so it is+ * gone and these no longer do anything.+ */repoId?: string;linkPrefix?: string;/**@@ -78,8 +82,6 @@ function ariaSortFor(column: SortKey, sortKey: SortKey, sortDir: SortDir): "noneexport function HotspotTable({hotspots,- repoId,- linkPrefix,onSelect,total,hasMore,@@ -98,7 +100,6 @@ export function HotspotTable({return next;});};- const prefix = linkPrefix ?? (repoId ? `/repos/${repoId}` : undefined);const [search, setSearch] = useState("");const [filter, setFilter] = useState<Filter>("all");const [sortKey, setSortKey] = useState<SortKey>("trend");@@ -418,7 +419,7 @@ export function HotspotTable({)}<td className="px-3 py-2.5 hidden lg:table-cell"><div className="flex items-center gap-2">- <ChurnBar percentile={h.churn_percentile} className="w-16" />+ <ChurnBar percentile={h.churn_percentile} className="w-16" tone="neutral" /><span className="text-xs text-[var(--color-text-tertiary)] tabular-nums w-8">{Math.round(h.churn_percentile)}%</span>@@ -439,13 +440,15 @@ export function HotspotTable({</span></td><td className="px-3 py-2.5 hidden md:table-cell">+ {/* A number, not a badge. A tinted pill on every row+ made a column of ordinary counts look like a column+ of alerts; only a sole owner is worth marking, and+ the colour alone says it. */}<span- className={`inline-flex items-center justify-center rounded px-1.5 py-0.5 text-xs font-medium tabular-nums ${+ className={`text-xs tabular-nums ${h.bus_factor <= 1- ? "bg-[var(--color-error)]/15 text-[var(--color-error)]"- : h.bus_factor === 2- ? "bg-[var(--color-warning)]/15 text-[var(--color-warning)]"- : "bg-[var(--color-success)]/15 text-[var(--color-success)]"+ ? "text-[var(--color-warning)]"+ : "text-[var(--color-text-secondary)]"}`}>{h.bus_factor}@@ -461,7 +464,9 @@ export function HotspotTable({</td><td className="px-3 py-2.5" onClick={(e) => e.stopPropagation()}><div className="flex items-center gap-1">- {h.is_hotspot && <Badge variant="outdated">Hot</Badge>}+ {/* No "Hot" badge: every row in a hotspot table is+ one, so it labelled nothing. "Stable" still earns+ its place — it is the row that is not. */}{h.is_stable && <Badge variant="fresh">Stable</Badge>}{onGeneratePrompt && (<AiPromptButton@@ -470,21 +475,6 @@ export function HotspotTable({onClick={() => onGeneratePrompt(h)}/>)}- {prefix && (- <RowActions- actions={[- { icon: GitBranch, label: "Graph", href: `${prefix}/architecture?view=files&node=${encodeURIComponent(h.file_path)}` },- // `?file=` is read by nothing in the docs- // surface, so this used to open the repo- // overview while looking like it had worked.- // `?page=` is the reader's parameter and takes a- // wiki page id; a file with no page gets told so- // by name.- { icon: BookOpen, label: "Docs", href: docsPagePath(prefix, filePageId(h.file_path)) },- { icon: Radius, label: "Blast Radius", href: `${prefix}/code-health?tab=impact&file=${encodeURIComponent(h.file_path)}` },- ]}- />- )}</div></td></tr>diff --git a/packages/ui/src/health/code-health-lede.tsx b/packages/ui/src/health/code-health-lede.tsxindex 0dcc34b15..59b72a82f 100644--- a/packages/ui/src/health/code-health-lede.tsx+++ b/packages/ui/src/health/code-health-lede.tsx@@ -1,20 +1,24 @@/**- * The Code Health page's opening read: the two figures that lead, and the- * sentences that make them mean something.+ * The Code Health page's opening read: one figure, and the sentences that make+ * it mean something.*- * Two rather than one because they answer different questions. Code health is- * the calibrated, bug-predicting number, and roughly half of what it deducts- * comes from git history, so it can fall through a week of good refactoring- * and tell the reader nothing they can act on. Maintainability is pure code- * shape, which is why it sits at the same weight rather than in the ribbon: it- * is the number a refactor is supposed to move.+ * One rather than two. It carried Code health and Maintainability side by side,+ * both scores out of ten, both largely about code shape — so the screen+ * answered "which number do I steer by?" twice, with two different numbers. The+ * page's Counts control answers it instead: the single figure either includes+ * change history or does not, and the reader picks. Maintainability keeps its+ * place in the ribbon, beside the other cuts of the same scoring.+ *+ * Every figure carries an explainer. A number a reader cannot define is a+ * number they cannot act on, and "Performance risk 942" beside "Hotspot health+ * 4.5" reads as two scores when one is a count that only goes up.** The prose is not decoration. "329 risks" reads as alarming on its own;* "329 static performance risks, scored separately and never blended into the- * health number" reads as informative. Same figure. The accuracy claim in- * particular only means anything next to its base rate: a 72% hit rate is- * excellent against a 20% baseline and unremarkable against a 70% one, so it- * is a sentence rather than a badge.+ * health number" reads as informative. The accuracy claim in particular only+ * means anything next to its base rate: a 72% hit rate is excellent against a+ * 20% baseline and unremarkable against a 70% one, so it is a sentence rather+ * than a badge.*/import {@@ -24,13 +28,51 @@ import {type HealthDistribution,type HealthOverviewSummary,} from "@repowise-dev/types/health";-import { LedeFigure, PageLede } from "../shared/page-lede";+import { PageLede } from "../shared/page-lede";import { StatRibbon, type RibbonStat } from "../stats/stat-ribbon";import { formatNumber } from "../lib/format";import { healthBandColor, scoreTextColor } from "./tokens";import { HealthDistributionBar } from "./health-distribution-bar";-/** Which of the two figures the page's current selection describes. */+const HEALTH_HINT =+ "Fitted against real bug history to predict where defects appear. Built from " ++ "code shape — complexity, duplication, coverage — and from what git says about " ++ "each file: how often it changes, alongside what, and how many people touch it. " ++ "1 to 10, higher is better.";++const CODE_SHAPE_HINT =+ "The same score with its change-history half removed: complexity, " ++ "duplication and coverage, but not churn, co-change, ownership or prior " ++ "fixes. It answers what the code is like rather than what the repository " ++ "has been through, so it moves when you refactor. Not the calibrated " ++ "bug-risk figure — the badge and the leaderboard keep reporting that one.";++const FILES_HINT =+ "Files scored. Only code is scored, so markdown, JSON, YAML, lockfiles and " ++ "other non-code carry no score and are not counted here.";++const MAINTAINABILITY_HINT =+ "Code shape alone: complexity, duplication and error handling, weighted for " ++ "how hard the code is to work with rather than for bug risk. It counts no " ++ "tests and no change history, so it is the figure a refactor moves.";++const PERFORMANCE_HINT =+ "A count of open performance risks, not a score — it counts up as the analyzer " ++ "finds more and falls only when they are fixed. Each one is a database, " ++ "network, filesystem or subprocess call inside a loop, traced across function " ++ "boundaries. Never blended into the health score.";++const HOTSPOT_HINT =+ "Code health averaged over the repo's churn hotspots — the files you change " ++ "most often. Lower than the overall figure on most repos, because " ++ "heavily-changed files carry the most change-history deduction.";++const HOTSPOT_HINT_CODE_SHAPE =+ "Code shape averaged over the repo's churn hotspots — the files you change " ++ "most often. With change history excluded this asks whether the code you " ++ "touch most is well built, rather than how much it has moved.";++/** Which figure the page's current selection describes; marks it in the ribbon. */export type LedePillar = "health" | "maintainability";export interface CodeHealthLedeProps {@@ -73,76 +115,98 @@ export function CodeHealthLede({const perf = summary.performance_average;const perfFindings = summary.performance_findings ?? 0;const hotspot = summary.hotspot_health;+ // Read off the response, not the page's control: the two disagree while a+ // request is in flight, and a figure captioned by the mode the reader just+ // asked for rather than the one it was computed under is the whole bug this+ // page exists to remove.+ const codeShape = summary.counts === "code_shape";+ const unscored = summary.unscored_files ?? 0;const structure = summary.structure_average;- const healthChip = bandChip(health);+ const historyDeduction = summary.history_average;+ // How much of the deduction is git history rather than code. Stated as a+ // share, not as a second score out of 10: a rival 0-10 figure beside+ // Maintainability made the page answer "which number do I steer by?" twice.+ const deduction = (structure ?? 0) + (historyDeduction ?? 0);+ const historyShare =+ structure == null || historyDeduction == null || deduction <= 0+ ? null+ : Math.round((historyDeduction / deduction) * 100);+ // The band words were fitted against the full, bug-predicting score, so+ // they are not a verdict this projection has earned: clamp(10 - structure)+ // reads systematically higher, and almost every repo would print "Healthy"+ // under it. The figure and the spread still say where the repo sits.+ const healthChip = codeShape ? undefined : bandChip(health);const stats: RibbonStat[] = [- { label: "Files", value: formatNumber(summary.file_count) },+ { label: "Files", value: formatNumber(summary.file_count), hint: FILES_HINT },+ {+ label: "Maintainability",+ value: maint == null ? "" : maint.toFixed(1),+ valueColor: maint == null ? undefined : scoreTextColor(maint),+ hint: MAINTAINABILITY_HINT,+ // The map's lens marks its figure here now that the lede carries one+ // number. Dimming the sole headline when the lens moved would have said+ // the page was describing something else.+ highlighted: pillar === "maintainability",+ },{label: "Performance risk",value: perf == null ? "" : formatNumber(perfFindings),- hint: "Open static performance risks: a DB, network, filesystem or subprocess call per loop iteration, found across function boundaries. High precision, low recall. This is a count of open causes, not a score, so it counts up as the analyzer finds more and falls only when they are fixed.",+ hint: PERFORMANCE_HINT,},{label: "Hotspot health",value: hotspot == null ? "" : hotspot.toFixed(1),valueColor: hotspot == null ? undefined : scoreTextColor(hotspot),- hint: "The score averaged over the repo's churn hotspots only. How healthy is the code you touch most?",+ hint: codeShape ? HOTSPOT_HINT_CODE_SHAPE : HOTSPOT_HINT,},- { label: "Open findings", value: formatNumber(summary.open_findings) },];+return (<div className="flex flex-col gap-6"><PageLedelabel="Code health"+ labelHint={codeShape ? CODE_SHAPE_HINT : HEALTH_HINT}value={health.toFixed(1)}- valueColor={healthChip.color}+ valueColor={healthChip?.color}unit="out of 10"- band={healthChip}+ {...(healthChip ? { band: healthChip } : {})}action={action}layout="beside"- figureHighlighted={pillar === "health"}// The two second reads that belong to this number: how the repo's code- // volume splits across the bands, and which half of the score is- // holding it down. The average alone hides whether this is+ // volume splits across the bands, and how much of the deduction no+ // refactor can reach. The average alone hides whether this is// everything-mediocre or mostly-healthy-with-a-bad-corner, and it hides// that a refactor may not move it at all.figureFooter={<>{distribution && <HealthDistributionBar distribution={distribution} height="sm" />}- {structure != null && (+ {codeShape ? (<p className="mt-3 text-[11px] leading-snug text-[var(--color-text-tertiary)]">- Structure{" "}- <span className="tabular-nums text-[var(--color-text-secondary)]">- {(10 - structure).toFixed(1)}- </span>- . History pulls it to{" "}- <span className="tabular-nums text-[var(--color-text-secondary)]">- {health.toFixed(1)}- </span>- .+ Change history excluded. This scores the code alone, and every+ finding on this page counts toward it.+ {unscored > 0 && (+ <>+ {" "}+ {formatNumber(unscored)} files are not scored here, having no+ recorded split yet.+ </>+ )}</p>+ ) : (+ historyShare != null && (+ <p className="mt-3 text-[11px] leading-snug text-[var(--color-text-tertiary)]">+ <span className="tabular-nums text-[var(--color-text-secondary)]">+ {historyShare}%+ </span>{" "}+ of this comes from change history, not from the code. No edit to+ these files clears it.+ </p>+ ))}</>}- figureSecondary={- <LedeFigure- label="Maintainability"- value={maint == null ? "—" : maint.toFixed(1)}- valueColor={maint == null ? undefined : bandChip(maint).color}- unit={maint == null ? undefined : "out of 10"}- band={maint == null ? undefined : bandChip(maint)}- highlighted={pillar === "maintainability"}- footer={- <p className="text-[11px] leading-snug text-[var(--color-text-tertiary)]">- {maint == null- ? "Not measured on this index."- : "Code shape only. This is the number that moves when you refactor."}- </p>- }- />- }><p>Across{" "}@@ -154,18 +218,19 @@ export function CodeHealthLede({{health.toFixed(1)} out of 10</strong>{" "}for code health, weighted by lines of code and built from complexity,- duplication, coverage, churn and ownership. We rate that{" "}- {healthChip.label.toLowerCase()}.+ duplication, coverage+ {codeShape ? "" : ", churn and ownership"}.+ {healthChip ? <> We rate that {healthChip.label.toLowerCase()}.</> : null}{perf != null && (<>{" "}Static performance risk is scored separately at {perf.toFixed(1)} out- of 10 and never blended into either figure.+ of 10 and never blended into the health score.</>)}</p>- {accuracy && (+ {accuracy && !codeShape && (<p className="mt-2.5">Ranked against real bug-fix history:{" "}<strong className="font-semibold text-[var(--color-text-primary)]">diff --git a/packages/ui/src/health/trend-view.tsx b/packages/ui/src/health/trend-view.tsxindex 054d18557..851d592ad 100644--- a/packages/ui/src/health/trend-view.tsx+++ b/packages/ui/src/health/trend-view.tsx@@ -19,7 +19,7 @@*/import { AlertTriangle } from "lucide-react";-import type { HealthTrendResponse } from "@repowise-dev/types/health";+import type { HealthCounts, HealthTrendResponse } from "@repowise-dev/types/health";import { Skeleton } from "../ui/skeleton";import { StatRibbon, type RibbonStat } from "../stats/stat-ribbon";@@ -39,10 +39,13 @@ export function TrendView({data,isLoading,error,+ counts,}: {data: HealthTrendResponse | undefined;isLoading: boolean;error: unknown;+ /** What the page's figures count, so this section cannot claim the other reading. */+ counts?: HealthCounts;}) {if (isLoading) return <Skeleton className="h-64 w-full rounded-lg" />;if (error || !data) {@@ -69,27 +72,41 @@ export function TrendView({// has dropped. Say so rather than printing one.const hotspot = summary.current_hotspot_health;+ // Snapshots recorded the full score, so there is no code-shape series to+ // read. These two carry the same labels as the lede's figures, and showing+ // the other reading of them here put two different numbers under one name on+ // one screen — the exact confusion the single headline exists to end.+ const otherReading = counts === "code_shape";+const stats: RibbonStat[] = [{label: "Average health",- value: summary.current_average_health.toFixed(1),- valueColor: scoreTextColor(summary.current_average_health),- sub: deltaSub(summary.average_delta, summary.previous_average_health),- ...(Math.abs(summary.average_delta ?? 0) >= 0.05- ? { subColor: deltaColor(summary.average_delta) }- : {}),+ value: otherReading ? "—" : summary.current_average_health.toFixed(1),+ ...(otherReading+ ? { sub: "recorded on the full score" }+ : {+ valueColor: scoreTextColor(summary.current_average_health),+ sub: deltaSub(summary.average_delta, summary.previous_average_health),+ ...(Math.abs(summary.average_delta ?? 0) >= 0.05+ ? { subColor: deltaColor(summary.average_delta) }+ : {}),+ }),},{label: "Hotspot health",- value: hotspot == null ? "—" : hotspot.toFixed(1),- ...(hotspot == null ? {} : { valueColor: scoreTextColor(hotspot) }),- sub:- hotspot == null- ? "not measured for this scope"- : deltaSub(summary.hotspot_delta, summary.previous_hotspot_health),- ...(hotspot != null && Math.abs(summary.hotspot_delta ?? 0) >= 0.05- ? { subColor: deltaColor(summary.hotspot_delta) }- : {}),+ value: otherReading || hotspot == null ? "—" : hotspot.toFixed(1),+ ...(otherReading+ ? { sub: "recorded on the full score" }+ : {+ ...(hotspot == null ? {} : { valueColor: scoreTextColor(hotspot) }),+ sub:+ hotspot == null+ ? "not measured for this scope"+ : deltaSub(summary.hotspot_delta, summary.previous_hotspot_health),+ ...(hotspot != null && Math.abs(summary.hotspot_delta ?? 0) >= 0.05+ ? { subColor: deltaColor(summary.hotspot_delta) }+ : {}),+ }),},{label: "Snapshots",diff --git a/packages/ui/src/shared/page-lede.tsx b/packages/ui/src/shared/page-lede.tsxindex a13efeb1b..1702829e3 100644--- a/packages/ui/src/shared/page-lede.tsx+++ b/packages/ui/src/shared/page-lede.tsx@@ -1,4 +1,5 @@import * as React from "react";+import { InfoTip } from "./info-tip";export interface PageLedeBand {label: string;@@ -10,6 +11,8 @@ export interface PageLedeBand {export interface PageLedeProps {/** Mono micro-label above the figure. */label: string;+ /** What the figure measures, on an `InfoTip` beside the label. */+ labelHint?: string | undefined;/** The figure itself, pre-formatted. */value: string;/** Colour for the figure. Same rule as `band.color`. */@@ -44,53 +47,43 @@ export interface PageLedeProps {* for another statistic.*/figureFooter?: React.ReactNode;- /** Marks the primary figure as the one the current selection describes. */- figureHighlighted?: boolean | undefined;- /**- * A co-equal second figure, built with `LedeFigure` so both share one type- * scale. For a page whose subject genuinely has two headline numbers; a- * supporting statistic belongs in the ribbon, where it reads as supporting.- */- figureSecondary?: React.ReactNode;}export interface LedeFigureProps {label: string;+ /** What the figure measures, on an `InfoTip` beside the label. */+ labelHint?: string | undefined;value: string;valueColor?: string | undefined;unit?: string | undefined;band?: PageLedeBand | undefined;badge?: React.ReactNode;footer?: React.ReactNode;- /** Marks this figure as the one the page's current selection describes. */- highlighted?: boolean | undefined;}/**- * One labelled figure at lede weight. Exported so a page with two headline- * numbers composes the second from the same source as the first, rather than- * re-deriving the 44/48px step and the chip geometry by hand.+ * One labelled figure at lede weight.+ *+ * A page carries one. It was exported so a second could be composed at the+ * same type scale, and the one page that did found the two figures answered+ * the same question with different numbers; the supporting statistic belongs+ * in the ribbon, where it reads as supporting.*/-export function LedeFigure({+function LedeFigure({label,+ labelHint,value,valueColor,unit,band,badge,footer,- highlighted,}: LedeFigureProps) {return (<div className="flex min-w-0 flex-col">- <p- className={- highlighted- ? "font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-accent-primary)]"- : "font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]"- }- >+ <p className="flex items-center gap-1 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">{label}+ {labelHint && <InfoTip content={labelHint} label={`What ${label} means`} />}</p><div className="mt-2.5 flex flex-wrap items-baseline gap-x-3 gap-y-1">@@ -101,22 +94,17 @@ export function LedeFigure({{value}</span>{unit && <span className="text-xs text-[var(--color-text-tertiary)]">{unit}</span>}+ {/* A dot and a word, not a badge. Filled and outlined, this read as a+ notification demanding action — and the band is a description of+ where a number sits, which is not news. The colour still carries+ the reading; it just stops shouting it. */}{band && (- <span- className="rounded-full border px-2.5 py-0.5 text-[11px] font-medium"- style={- band.color- ? {- color: band.color,- borderColor: `color-mix(in srgb, ${band.color} 40%, transparent)`,- background: `color-mix(in srgb, ${band.color} 9%, transparent)`,- }- : {- color: "var(--color-text-secondary)",- borderColor: "var(--color-border-hover)",- }- }- >+ <span className="inline-flex items-center gap-1.5 text-[11px] text-[var(--color-text-secondary)]">+ <span+ aria-hidden+ className="inline-block h-1.5 w-1.5 rounded-full"+ style={{ background: band.color ?? "var(--color-text-tertiary)" }}+ />{band.label}</span>)}@@ -143,6 +131,7 @@ export function LedeFigure({*/export function PageLede({label,+ labelHint,value,valueColor,unit,@@ -152,38 +141,29 @@ export function PageLede({action,layout = "stacked",figureFooter,- figureHighlighted,- figureSecondary,}: PageLedeProps) {const beside = layout === "beside";- const paired = figureSecondary != null;-const primary = (<LedeFigurelabel={label}+ labelHint={labelHint}value={value}valueColor={valueColor}unit={unit}band={band}badge={badge}footer={figureFooter}- highlighted={figureHighlighted}/>);- const figure = paired ? (- <div className="grid gap-x-10 gap-y-6 sm:grid-cols-2">- {primary}- {figureSecondary}- </div>- ) : (+ const figure = (<div className={beside ? "flex shrink-0 flex-col" : "flex flex-col"}>{primary}</div>);const prose = (<divclassName={- beside && !paired+ beside? // Two columns from xl. Three paragraphs in one 62ch column runs tall// enough to push the page's actual subject below the fold while// leaving half the row empty; flowed into two ~48ch columns it is@@ -205,7 +185,7 @@ export function PageLede({// the number is; without it a 7.5 and a 10.0 indent the paragraph// differently and the block looks unaligned between repos.<div className="flex flex-col gap-5 lg:flex-row lg:items-start lg:gap-12">- <div className={paired ? "lg:w-[420px] lg:shrink-0" : "lg:w-[220px]"}>{figure}</div>+ <div className="lg:w-[220px]">{figure}</div>{prose}</div>);diff --git a/packages/ui/src/shared/page-shell.tsx b/packages/ui/src/shared/page-shell.tsxindex 8b42ab97f..71dd4abb3 100644--- a/packages/ui/src/shared/page-shell.tsx+++ b/packages/ui/src/shared/page-shell.tsx@@ -69,7 +69,14 @@ export function PageShell({</p>)}</div>- {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}+ {/* Wraps rather than refusing to shrink. `shrink-0` here sized the+ block to its contents and let it run off the side of a phone,+ taking the whole page's horizontal scroll with it. */}+ {actions && (+ <div className="flex min-w-0 flex-wrap items-center justify-end gap-2">+ {actions}+ </div>+ )}</header>{children}</div>diff --git a/packages/ui/src/shared/view-tabs.tsx b/packages/ui/src/shared/view-tabs.tsxindex fabcde5d0..2507812cc 100644--- a/packages/ui/src/shared/view-tabs.tsx+++ b/packages/ui/src/shared/view-tabs.tsx@@ -29,6 +29,9 @@ export interface ViewTabsProps {* derived from this value so the host can name them without a callback. */panelId?: string;className?: string;+ /** Names the row when a page carries more than one, so the two are+ * distinguishable to a screen reader announcing "tab list". */+ "aria-label"?: string;}/**@@ -43,6 +46,7 @@ export function ViewTabs({children,panelId: externalPanelId,className,+ "aria-label": ariaLabel,}: ViewTabsProps) {// Stable id base so each tab can be aria-labelled to the shared panel and// the panel can point back at the active tab.@@ -85,6 +89,7 @@ export function ViewTabs({<div className={cn("space-y-4", className)}><divrole="tablist"+ aria-label={ariaLabel}onKeyDown={onKeyDown}className="flex items-center gap-4 overflow-x-auto border-b border-[var(--color-border-default)] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">diff --git a/packages/ui/src/stats/stat-ribbon.tsx b/packages/ui/src/stats/stat-ribbon.tsxindex 36556fb77..596b75ff6 100644--- a/packages/ui/src/stats/stat-ribbon.tsx+++ b/packages/ui/src/stats/stat-ribbon.tsx@@ -1,8 +1,16 @@import * as React from "react";+import { InfoTip } from "../shared/info-tip";+export interface RibbonStat {label: string;value: string;+ /**+ * What this figure means, shown on an `InfoTip` beside the label. A figure a+ * reader cannot define is a figure they cannot act on, and the native `title`+ * this used to render was invisible, unreachable by keyboard and absent on+ * touch — an explainer nobody could find.+ */hint?: string;/*** Tailwind text-colour class for the value. Only for figures that carry a@@ -15,6 +23,8 @@ export interface RibbonStat {sub?: string | undefined;/** Tailwind text-colour class for `sub`. Same rule as `valueColor`. */subColor?: string | undefined;+ /** Marks the figure the page's current selection describes. */+ highlighted?: boolean | undefined;/** Optional jump to the page that owns this figure. Added because the* Overview replaced a strip of *linked* KPI tiles with this component, and* without it Files and Symbols lost their only entry point from that page. */@@ -49,10 +59,8 @@ export function StatRibbon({{shown.map((s, i) => (<divkey={s.label}- title={s.hint}className={[s.href ? "" : "px-4 py-3.5",- s.hint ? "cursor-help" : "",// Hairlines between cells only — the outer edges come from the// wrapper's border-y, so cells never double up on the boundary."border-[var(--color-border-default)]",@@ -71,8 +79,11 @@ export function StatRibbon({// The link wraps the whole cell rather than the value, so the// padding is part of the hit target instead of a dead margin// around it.+ // A linked cell keeps the native tooltip: the anchor wraps the whole+ // cell, and a tip is a button, which cannot nest inside it.<Ahref={s.href}+ title={s.hint}className="group block px-4 py-3.5 no-underline transition-colors hover:bg-[var(--color-bg-elevated)]"><dt className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">@@ -88,8 +99,15 @@ export function StatRibbon({</A>) : (<>- <dt className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">+ <dt+ className={`flex items-center gap-1 font-mono text-[10px] uppercase tracking-[0.12em] ${+ s.highlighted+ ? "text-[var(--color-accent-primary)]"+ : "text-[var(--color-text-tertiary)]"+ }`}+ >{s.label}+ {s.hint && <InfoTip content={s.hint} label={`What ${s.label} means`} />}</dt><ddclassName={`mt-1 text-xl font-semibold tabular-nums ${diff --git a/packages/web/src/app/repos/[id]/code-health/page.tsx b/packages/web/src/app/repos/[id]/code-health/page.tsxindex 0e519180e..f4b01a763 100644--- a/packages/web/src/app/repos/[id]/code-health/page.tsx+++ b/packages/web/src/app/repos/[id]/code-health/page.tsx@@ -42,10 +42,22 @@ import { PageShell } from "@repowise-dev/ui/shared/page-shell";import { ViewTabs } from "@repowise-dev/ui/shared/view-tabs";import { OverviewSection } from "@repowise-dev/ui/overview";import { Button } from "@repowise-dev/ui/ui/button";+import {+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+} from "@repowise-dev/ui/ui/select";import { formatDateTime } from "@repowise-dev/ui/lib/format";import type { CodeHealthOverlay } from "@repowise-dev/ui/health";import type { DeadCodeSummary } from "@repowise-dev/types/dead-code";-import { HEALTH_SCOPES, type HealthScope } from "@repowise-dev/types/health";+import {+ HEALTH_COUNTS,+ HEALTH_SCOPES,+ type HealthCounts,+ type HealthScope,+} from "@repowise-dev/types/health";import { TriageTab } from "@/components/code-health/triage-tab";import { HotspotsSection } from "@/components/code-health/hotspots-section";import { FindingsTab } from "@/components/code-health/findings-tab";@@ -140,6 +152,58 @@ const SCOPE_LABEL: Record<HealthScope, string> = {production: "Production",};+/**+ * Tabs whose data honours `counts`. The trend is deliberately absent even+ * though it sits on the Overview: snapshots recorded the full score, so there+ * is no code-shape series to draw and inventing one from mean deductions would+ * disagree with the headline wherever a file sits at the score floor.+ */+const COUNTED_TABS: TabId[] = ["triage", "findings"];++/**+ * A named dropdown for a view control in the page header.+ *+ * These are filters over everything on the page, not navigation, so they read+ * as a question and its current answer rather than as a second row of tabs+ * competing with the real one.+ */+function ViewSelect({+ label,+ value,+ onValueChange,+ options,+}: {+ label: string;+ value: string;+ onValueChange: (next: string) => void;+ options: { id: string; label: string }[];+}) {+ return (+ <div className="flex min-w-0 items-center gap-2">+ <span className="shrink-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">+ {label}+ </span>+ <Select value={value} onValueChange={onValueChange}>+ <SelectTrigger aria-label={label} className="h-8 w-auto gap-1.5 px-2.5 text-xs">+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {options.map((o) => (+ <SelectItem key={o.id} value={o.id}>+ {o.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </div>+ );+}++const COUNTS_LABEL: Record<HealthCounts, string> = {+ everything: "Everything",+ code_shape: "Code shape only",+};+/*** Nodes the map draws. The server chooses which ones: the selected file first,* then every file carrying an open performance cause in rank order, then the@@ -194,6 +258,16 @@ export default function CodeHealthPage() {// stays valid and the narrowed one gets its own.const scopeKey = scope === "all" ? "" : `:${scope}`;+ const rawCounts = searchParams.get("counts");+ const counts: HealthCounts = (HEALTH_COUNTS as readonly string[]).includes(rawCounts ?? "")+ ? (rawCounts as HealthCounts)+ : "everything";+ // Same convention as scope, and appended after it: the two suffixes have to+ // compose in one fixed order or the page-level key and the view-level key+ // stop matching and the overview is fetched twice.+ const countsKey = counts === "everything" ? "" : `:${counts}`;+ const viewKey = `${scopeKey}${countsKey}`;+const rawLens = searchParams.get("lens");const overlay: CodeHealthOverlay = (OVERLAYS as readonly string[]).includes(rawLens ?? "")? (rawLens as CodeHealthOverlay)@@ -209,8 +283,8 @@ export default function CodeHealthPage() {// Shares the SWR key with TriageView — the meta line and the findings count// cost no extra request.const { data: overview } = useSWR<HealthOverviewResponse>(- `code-health-overview:${repoId}${scopeKey}`,- () => getHealthOverview(repoId, 25, scope),+ `code-health-overview:${repoId}${viewKey}`,+ () => getHealthOverview(repoId, 25, scope, counts),{ revalidateOnFocus: false },);const meta = overview?.meta;@@ -267,12 +341,13 @@ export default function CodeHealthPage() {[selectedPath, highlightPaths],);const { data: mapFeed } = useSWR<HealthMapFeed>(- `code-health-map:${repoId}${scopeKey}:${activePaths.join(",")}`,+ `code-health-map:${repoId}${viewKey}:${activePaths.join(",")}`,() =>getHealthMap(repoId, {cap: MAP_CAP,...(activePaths.length ? { active: activePaths } : {}),scope,+ counts,}),{ revalidateOnFocus: false, keepPreviousData: true },);@@ -368,6 +443,17 @@ export default function CodeHealthPage() {[router, searchParams],);+ const setCounts = useCallback(+ (next: string) => {+ const sp = new URLSearchParams(searchParams.toString());+ if (next === "everything") sp.delete("counts");+ else sp.set("counts", next);+ const qs = sp.toString();+ router.replace(qs ? `?${qs}` : "?", { scroll: false });+ },+ [router, searchParams],+ );+const setOverlay = useCallback((next: CodeHealthOverlay) => {const sp = new URLSearchParams(searchParams.toString());@@ -391,12 +477,25 @@ export default function CodeHealthPage() {// goes entirely to the field, which is this page's whole subject.maxWidth="wide"actions={- <div className="flex items-center gap-4">+ // Two named dropdowns rather than two tab rows. Four choices spelled+ // out in full overflowed the header on a phone and set the whole page+ // scrolling sideways; a trigger shows the current answer and spends no+ // width on the alternative.+ <div className="flex min-w-0 flex-wrap items-center gap-x-4 gap-y-2">{SCOPED_TABS.includes(activeTab) && (- <ViewTabs- tabs={HEALTH_SCOPES.map((id) => ({ id, label: SCOPE_LABEL[id] }))}+ <ViewSelect+ label="Files"value={scope}onValueChange={setScope}+ options={HEALTH_SCOPES.map((id) => ({ id, label: SCOPE_LABEL[id] }))}+ />+ )}+ {COUNTED_TABS.includes(activeTab) && (+ <ViewSelect+ label="Counts"+ value={counts}+ onValueChange={setCounts}+ options={HEALTH_COUNTS.map((id) => ({ id, label: COUNTS_LABEL[id] }))}/>)}<Button size="sm" variant="outline" onClick={refresh} disabled={refreshing}>@@ -433,6 +532,7 @@ export default function CodeHealthPage() {>{activeTab === "triage" && (<TriageTab+ counts={counts}repoId={repoId}trend={trend}overlay={overlay}@@ -450,12 +550,17 @@ export default function CodeHealthPage() {title="Health trend"description="How the scores have moved across indexed snapshots.">- <TrendSection data={trend} isLoading={trendLoading} error={trendError} />+ <TrendSection+ data={trend}+ isLoading={trendLoading}+ error={trendError}+ counts={counts}+ /></OverviewSection>}/>)}- {activeTab === "findings" && <FindingsTab repoId={repoId} scope={scope} />}+ {activeTab === "findings" && <FindingsTab repoId={repoId} scope={scope} counts={counts} />}{activeTab === "performance" && <PerformanceTab repoId={repoId} />}{activeTab === "coverage" && <CoverageTab repoId={repoId} />}{activeTab === "dead-code" && <DeadCodeTab repoId={repoId} />}diff --git a/packages/web/src/components/code-health/findings-tab.tsx b/packages/web/src/components/code-health/findings-tab.tsxindex 141e06f01..34bfed16f 100644--- a/packages/web/src/components/code-health/findings-tab.tsx+++ b/packages/web/src/components/code-health/findings-tab.tsx@@ -24,30 +24,35 @@ import {getFileOpportunity,refactoringOpportunityHref,} from "@/lib/api/file-opportunity";-import type { HealthScope } from "@repowise-dev/types/health";+import type { HealthCounts, HealthScope } from "@repowise-dev/types/health";export function FindingsTab({repoId: id,scope,+ counts,}: {repoId: string;/** Which half of the repository every figure here describes. */scope?: HealthScope;+ /** Whether those figures count change history or code shape alone. */+ counts?: HealthCounts;}) {const router = useRouter();const prefix = `/repos/${id}`;const adapter: CodeHealthAdapter = {- cacheKey: scope && scope !== "all" ? `${id}:${scope}` : id,- getOverview: (limit) => getHealthOverview(id, limit, scope),+ cacheKey: `${id}${scope && scope !== "all" ? `:${scope}` : ""}${+ counts && counts !== "everything" ? `:${counts}` : ""+ }`,+ getOverview: (limit) => getHealthOverview(id, limit, scope, counts),listFindings: (opts) =>- listHealthFindings(id, { ...opts, ...(scope ? { scope } : {}) }),+ listHealthFindings(id, { ...opts, ...(scope ? { scope } : {}), ...(counts ? { counts } : {}) }),getFileOpportunity: (filePath) => getFileOpportunity(id, filePath),refactoringOpportunityHref: (opportunityId) =>refactoringOpportunityHref(id, opportunityId),- listFiles: (opts) => listHealthFiles(id, { ...opts, ...(scope ? { scope } : {}) }),+ listFiles: (opts) => listHealthFiles(id, { ...opts, ...(scope ? { scope } : {}), ...(counts ? { counts } : {}) }),getHealthWorkQueue: (opts) =>- getHealthWorkQueue(id, { ...opts, ...(scope ? { scope } : {}) }),+ getHealthWorkQueue(id, { ...opts, ...(scope ? { scope } : {}), ...(counts ? { counts } : {}) }),updateFindingStatus: (findingId, status) =>updateFindingStatus(id, findingId, status),getCoverage: (opts) => getHealthCoverage(id, opts),@@ -55,7 +60,12 @@ export function FindingsTab({symbolHref: (symbolId) => symbolEntityPath(prefix, symbolId),navigate: (href) => router.push(href),renderFileDrawer: ({ filePath, onClose }) => (- <HealthFileDrawerHost repoId={id} filePath={filePath} onClose={onClose} />+ <HealthFileDrawerHost+ repoId={id}+ filePath={filePath}+ onClose={onClose}+ counts={counts}+ />),};diff --git a/packages/web/src/components/code-health/triage-tab.tsx b/packages/web/src/components/code-health/triage-tab.tsxindex 007e32726..db83c8fae 100644--- a/packages/web/src/components/code-health/triage-tab.tsx+++ b/packages/web/src/components/code-health/triage-tab.tsx@@ -25,7 +25,7 @@ import {type HealthTrendResponse,type HealthMapFeed,} from "@/lib/api/code-health";-import type { HealthScope } from "@repowise-dev/types/health";+import type { HealthCounts, HealthScope } from "@repowise-dev/types/health";import { HealthFileDrawerHost } from "@/components/health/health-file-drawer-host";export function TriageTab({@@ -42,6 +42,7 @@ export function TriageTab({hotspotsSlot,trendSlot,scope,+ counts,}: {repoId: string;/** Trend fetched once at the page level. */@@ -65,21 +66,27 @@ export function TriageTab({trendSlot?: ReactNode;/** Which half of the repository every figure here describes. */scope?: HealthScope;+ /** Whether those figures count change history or code shape alone. */+ counts?: HealthCounts;}) {const router = useRouter();const prefix = `/repos/${id}`;- // Scope rides in the cache key as well as the query: the views key their SWR- // off it, so narrowing has to make a different key or the first population- // stays on screen under the second one's label.+ // Scope and counts ride in the cache key as well as the query: the views key+ // their SWR off it, so a re-read has to make a different key or the first+ // population stays on screen under the second one's label. The suffixes+ // compose in the same fixed order the page uses, or the two keys diverge and+ // the overview is fetched twice.const adapter: CodeHealthAdapter = {- cacheKey: scope && scope !== "all" ? `${id}:${scope}` : id,- getOverview: (limit) => getHealthOverview(id, limit, scope),+ cacheKey: `${id}${scope && scope !== "all" ? `:${scope}` : ""}${+ counts && counts !== "everything" ? `:${counts}` : ""+ }`,+ getOverview: (limit) => getHealthOverview(id, limit, scope, counts),listFindings: (opts) =>- listHealthFindings(id, { ...opts, ...(scope ? { scope } : {}) }),- listFiles: (opts) => listHealthFiles(id, { ...opts, ...(scope ? { scope } : {}) }),+ listHealthFindings(id, { ...opts, ...(scope ? { scope } : {}), ...(counts ? { counts } : {}) }),+ listFiles: (opts) => listHealthFiles(id, { ...opts, ...(scope ? { scope } : {}), ...(counts ? { counts } : {}) }),getHealthWorkQueue: (opts) =>- getHealthWorkQueue(id, { ...opts, ...(scope ? { scope } : {}) }),+ getHealthWorkQueue(id, { ...opts, ...(scope ? { scope } : {}), ...(counts ? { counts } : {}) }),updateFindingStatus: (findingId, status) =>updateFindingStatus(id, findingId, status),getCoverage: (opts) => getHealthCoverage(id, opts),@@ -91,6 +98,7 @@ export function TriageTab({repoId={id}filePath={filePath}onClose={onClose}+ counts={counts}{...(lens ? { lens } : {})}/>),diff --git a/packages/web/src/components/health/health-file-drawer-host.tsx b/packages/web/src/components/health/health-file-drawer-host.tsxindex 47f019605..dce99d0a4 100644--- a/packages/web/src/components/health/health-file-drawer-host.tsx+++ b/packages/web/src/components/health/health-file-drawer-host.tsx@@ -14,6 +14,7 @@ import {refactoringOpportunityHref,} from "@/lib/api/file-opportunity";import { useFileBreakdown } from "./use-file-breakdown";+import type { HealthCounts } from "@repowise-dev/types/health";/** Causes listed for one file. A file with more than this is its own queue. */const FILE_CAUSE_LIMIT = 10;@@ -23,15 +24,18 @@ export function HealthFileDrawerHost({filePath,onClose,lens,+ counts,}: {repoId: string;filePath: string | null;onClose: () => void;+ /** The reading the row that opened this drawer was scored under. */+ counts?: HealthCounts;/** The surface the file was opened from; drives what the drawer leads with. */lens?: string;}) {const router = useRouter();- const { data, isLoading } = useFileBreakdown(repoId, filePath);+ const { data, isLoading } = useFileBreakdown(repoId, filePath, counts);const prefix = `/repos/${repoId}`;const filePageHref = filePath ? fileEntityPath(prefix, filePath) : undefined;diff --git a/packages/web/src/components/health/use-file-breakdown.ts b/packages/web/src/components/health/use-file-breakdown.tsindex 077654880..caa39021d 100644--- a/packages/web/src/components/health/use-file-breakdown.ts+++ b/packages/web/src/components/health/use-file-breakdown.ts@@ -5,11 +5,20 @@ import {getHealthFileBreakdown,type HealthFileBreakdownResponse,} from "@/lib/api/code-health";+import type { HealthCounts } from "@repowise-dev/types/health";-export function useFileBreakdown(repoId: string, filePath: string | null) {+export function useFileBreakdown(+ repoId: string,+ filePath: string | null,+ counts?: HealthCounts,+) {+ // Counts is in the key as well as the query: the drawer opens from a row+ // whose score was read under it, and a cached breakdown from the other+ // reading would answer a click on one number with a different one.+ const suffix = counts && counts !== "everything" ? `:${counts}` : "";return useSWR<HealthFileBreakdownResponse>(- filePath ? `code-health-breakdown:${repoId}:${filePath}` : null,- () => getHealthFileBreakdown(repoId, filePath!),+ filePath ? `code-health-breakdown:${repoId}:${filePath}${suffix}` : null,+ () => getHealthFileBreakdown(repoId, filePath!, counts),{ revalidateOnFocus: false },);}diff --git a/tests/unit/health/test_counts.py b/tests/unit/health/test_counts.pynew file mode 100644index 000000000..8d056ec49--- /dev/null+++ b/tests/unit/health/test_counts.py@@ -0,0 +1,97 @@+"""Reading a health figure with or without its change-history half."""++from __future__ import annotations++from dataclasses import dataclass++from repowise.core.analysis.health.counts import (+ DEFAULT_COUNTS,+ code_shape_score,+ parse_counts,+ project,+)+from repowise.core.analysis.health.scoring import SCORE_FLOOR, SCORE_MAX+++@dataclass+class _M:+ file_path: str+ score: float+ structure_deduction: float | None+ history_deduction: float | None+ nloc: int = 100+ defect_score: float | None = None+ is_test: bool = False+++def test_unknown_values_fall_back_rather_than_raise():+ assert parse_counts("nonsense") == DEFAULT_COUNTS+ assert parse_counts(None) == DEFAULT_COUNTS+ assert parse_counts("code_shape") == "code_shape"+++def test_the_default_reading_is_the_rows_themselves():+ """No projection means no copies, so nothing downstream can diverge."""+ rows = [_M("a.py", 7.0, 1.6, 1.4)]+ out, unmeasured = project("everything", rows)+ assert out is rows+ assert unmeasured == 0+++def test_code_shape_subtracts_only_the_structure_half():+ rows = [_M("a.py", 7.0, 1.6, 1.4)]+ out, _ = project("code_shape", rows)+ assert out[0].score == 8.4+ # The wire mirror has to move with it, or one surface reports the other's+ # number under this one's label.+ assert out[0].defect_score == 8.4+++def test_a_file_pinned_at_the_floor_can_show_its_code_shape():+ """The founding case for the split: 1.0 hides whether the code is bad."""+ rows = [_M("deep.py", SCORE_FLOOR, 2.0, 9.5)]+ out, _ = project("code_shape", rows)+ assert out[0].score == 8.0+++def test_the_projection_is_clamped_like_any_score():+ assert code_shape_score(12.9) == SCORE_FLOOR+ assert code_shape_score(0.0) == SCORE_MAX+++def test_rows_predating_the_split_are_dropped_not_scored_ten():+ """Coercing a missing half to zero prints a confident 10.0 for a guess."""+ rows = [_M("old.py", 9.0, None, None), _M("new.py", 7.0, 1.6, 1.4)]+ out, unmeasured = project("code_shape", rows)+ assert [m.file_path for m in out] == ["new.py"]+ assert unmeasured == 1+ assert code_shape_score(None) is None+++def test_the_history_half_reads_as_zero_so_derived_figures_agree():+ """A row shipping a projected score beside a full-reading unclamped one+ contradicts itself on the wire, and the summary's history average would+ describe the reading the page is not showing."""+ rows = [_M("a.py", 7.0, 1.6, 1.4)]+ out, _ = project("code_shape", rows)+ assert out[0].history_deduction == 0.0+ assert out[0].structure_deduction == 1.6+ # 10 - structure - history now matches the score the same row carries.+ assert SCORE_MAX - out[0].structure_deduction - out[0].history_deduction == out[0].score+++def test_everything_else_reads_through_to_the_row():+ """The projection re-scores; it must not hide the rest of the record."""+ rows = [_M("a.py", 7.0, 1.6, 1.4, nloc=250, is_test=True)]+ out, _ = project("code_shape", rows)+ assert out[0].nloc == 250+ assert out[0].file_path == "a.py"+ assert out[0].is_test is True+++def test_the_projection_never_writes_back_to_the_row():+ """The rows a route holds are live ORM objects; a mutation would flush."""+ row = _M("a.py", 7.0, 1.6, 1.4)+ out, _ = project("code_shape", [row])+ assert out[0].score == 8.4+ assert row.score == 7.0diff --git a/tests/unit/server/test_health_counts_route.py b/tests/unit/server/test_health_counts_route.pynew file mode 100644index 000000000..03397a975--- /dev/null+++ b/tests/unit/server/test_health_counts_route.py@@ -0,0 +1,121 @@+"""``counts=code_shape`` across the routes that answer to it.++The control exists because roughly half of a file's deduction is git-derived+and rises as the file is worked on, so the headline falls through a week of+good refactoring. Dropping that half is a subtraction over stored columns, not+a rescore — these fix what every surface does with it, because a headline that+moves while the map, the file list and the findings under it do not is the+contradiction the control was added to remove.+"""++from __future__ import annotations++from repowise.core.analysis.health.models import HealthFileMetricData+from repowise.core.persistence.crud import save_health_metrics, upsert_repository++from .conftest import create_test_repo+++def _metric(path: str, score: float, structure: float | None, history: float | None, nloc: int = 100):+ return HealthFileMetricData(+ file_path=path,+ score=score,+ max_ccn=1,+ max_nesting=1,+ nloc=nloc,+ has_test_file=False,+ defect_score=score,+ structure_deduction=structure,+ history_deduction=history,+ )+++async def _repo_with_metrics(client, session, tmp_path, metrics):+ repo = await create_test_repo(client, tmp_path)+ await upsert_repository(session, name="r", local_path=repo["local_path"])+ await save_health_metrics(session, repo["id"], metrics)+ await session.commit()+ return repo["id"]+++async def test_the_headline_drops_the_history_half(client, session, tmp_path) -> None:+ """Two files whose scores are held down almost entirely by churn."""+ repo_id = await _repo_with_metrics(+ client,+ session,+ tmp_path,+ [_metric("a.py", 5.0, 1.0, 4.0), _metric("b.py", 6.0, 1.0, 3.0)],+ )++ full = (await client.get(f"/api/repos/{repo_id}/health/overview")).json()+ assert full["summary"]["average_health"] == 5.5+ assert full["summary"]["counts"] == "everything"++ shaped = (+ await client.get(f"/api/repos/{repo_id}/health/overview?counts=code_shape")+ ).json()+ assert shaped["summary"]["average_health"] == 9.0+ assert shaped["summary"]["counts"] == "code_shape"+++async def test_the_distribution_is_recomputed_not_carried_over(client, session, tmp_path) -> None:+ """A band split describing the other reading is worse than none."""+ repo_id = await _repo_with_metrics(+ client, session, tmp_path, [_metric("a.py", 3.0, 0.5, 6.5)]+ )+ shaped = (+ await client.get(f"/api/repos/{repo_id}/health/overview?counts=code_shape")+ ).json()+ bands = shaped["distribution"]["bands"]+ assert bands["healthy"]["files"] == 1+ assert bands["alert"]["files"] == 0+++async def test_rows_without_a_split_are_reported_not_scored_ten(client, session, tmp_path) -> None:+ repo_id = await _repo_with_metrics(+ client,+ session,+ tmp_path,+ [_metric("new.py", 5.0, 1.0, 4.0), _metric("old.py", 9.0, None, None)],+ )+ shaped = (+ await client.get(f"/api/repos/{repo_id}/health/overview?counts=code_shape")+ ).json()+ assert shaped["summary"]["unscored_files"] == 1+ assert shaped["summary"]["average_health"] == 9.0+++async def test_the_file_list_is_re_ranked_by_the_same_reading(client, session, tmp_path) -> None:+ """Worst-first has to mean worst under the reading on screen."""+ repo_id = await _repo_with_metrics(+ client,+ session,+ tmp_path,+ [_metric("churned.py", 2.0, 0.5, 7.5), _metric("complex.py", 6.0, 4.0, 0.0)],+ )+ rows = (+ await client.get(f"/api/repos/{repo_id}/health/files?counts=code_shape&limit=5")+ ).json()+ items = rows.get("items") or rows.get("files")+ assert next(r["file_path"] for r in items) == "complex.py"+ assert items[0]["score"] == 6.0+++async def test_an_unknown_value_is_refused_rather_than_guessed(client, session, tmp_path) -> None:+ """The query declares a pattern, so a typo 422s instead of silently+ serving the default reading under whatever label the caller sent."""+ repo_id = await _repo_with_metrics(+ client, session, tmp_path, [_metric("a.py", 5.0, 1.0, 4.0)]+ )+ resp = await client.get(f"/api/repos/{repo_id}/health/overview?counts=nonsense")+ assert resp.status_code == 422+++async def test_the_stored_rows_are_never_rewritten(client, session, tmp_path) -> None:+ """The projection wraps live ORM rows; assigning to one would flush it."""+ repo_id = await _repo_with_metrics(+ client, session, tmp_path, [_metric("a.py", 5.0, 1.0, 4.0)]+ )+ await client.get(f"/api/repos/{repo_id}/health/overview?counts=code_shape")+ after = (await client.get(f"/api/repos/{repo_id}/health/overview")).json()+ assert after["summary"]["average_health"] == 5.0