Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(health): let a surface that ranks nothing see a zero-impact finding (#2430)
Raghav Chamadiyaea61dbcdfe13
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 7db77a082..96c0fca70 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -907,11 +907,11 @@ get_health(opportunity_id="refop2_...")| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| `targets` | list[string] | No | File paths, or `module:foo` to expand a module's file set. Empty means dashboard mode. |-| `include` | list[string] | No | Opt-in blocks (default response stays lean): `"biomarkers"` (findings in dashboard mode), `"refactoring"` (structured, graph-aware refactoring plans; see below), `"trend"` (snapshot diff + declining / predicted-decline alerts), `"coverage"`, `"accuracy"` (the "does the score find the bugs?" stat, dashboard mode), `"signals"` (per-file process / people / topology signals, targeted mode), `"churn_complexity"` (churn x complexity quadrant points, dashboard mode), `"doc_drift"` (documentation whose claims about the tree no longer hold), and a dimension name (`"performance"` / `"defect"` / `"maintainability"`) to filter findings to that pillar. |+| `include` | list[string] | No | Opt-in blocks (default response stays lean): `"biomarkers"` (findings in dashboard mode), `"refactoring"` (structured, graph-aware refactoring plans; see below), `"trend"` (snapshot diff + declining / predicted-decline alerts), `"coverage"`, `"accuracy"` (the "does the score find the bugs?" stat, dashboard mode), `"signals"` (per-file process / people / topology signals, targeted mode), `"churn_complexity"` (churn x complexity quadrant points, dashboard mode), `"doc_drift"` (documentation whose claims about the tree no longer hold), and a dimension name (`"performance"` / `"defect"` / `"maintainability"` / `"advisory"`) to filter findings to that pillar. `"advisory"` is the only way to reach the advisory markers — `assertion_free_test` and `mock_saturated_test`. They carry a health impact of exactly zero, so they are out of every impact-ranked list by default: asking for the dimension is what returns them, and their absence from an unfiltered response is not a clean bill. || `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode`, `_meta`, `unresolved`, `known_modules` and each kept list's `*_total` sibling always survive. The three `include` **block** names work as aliases: `biomarkers`→`findings`, `accuracy`→`defect_accuracy`, `refactoring`→`refactoring_plans`. Note that `refactoring_plans` is the rawper-detector list and is now **opt-in**: `include=["refactoring"]` leads with`refactoring_opportunities`, the composed unit, and emitting both would ship two-representations of the same work in one response. The `include` **dimension** names (`performance`, `defect`, `maintainability`) do not — they filter rows inside several blocks and have no single key to resolve to, so they land in `unknown_only_keys`. Nor does `signals`, which merges into `metrics[].signals` — in targeted mode, where `signals` applies, name `metrics` instead. |+representations of the same work in one response. The `include` **dimension** names (`performance`, `defect`, `maintainability`, `advisory`) do not — they filter rows inside several blocks and have no single key to resolve to, so they land in `unknown_only_keys`. Nor does `signals`, which merges into `metrics[].signals` — in targeted mode, where `signals` applies, name `metrics` instead. || `repo` | string | No | *(workspace only)* Target repo alias || `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50). `0` means no rows; the `*_total` siblings still report the true counts. || `finding_id` | string | No | Resolve an emitted stable health-finding `id` directly in one call. |@@ -937,7 +937,9 @@ the name you asked for. Both are echoed on the response.pillar averages), the lowest-scoring files, and a per-module NLOC-weightedrollup. Targeted mode returns per-file marker findings with severity,per-dimension scores, and the score breakdown. Each finding carries a `dimension`-(`defect` / `maintainability` / `performance`).+(`defect` / `maintainability` / `performance` / `advisory`). Only the first three+score; `advisory` describes and never deducts, which is why a file can carry an+advisory finding and a deduction of zero.**Lead with `directive`.** Dashboard mode opens with the single file to fixfirst, its dominant finding, `recovers_weighted_deficit_points` /diff --git a/docs/agent/VSCODE.md b/docs/agent/VSCODE.mdindex d2b4610e8..0a281c64f 100644--- a/docs/agent/VSCODE.md+++ b/docs/agent/VSCODE.md@@ -143,7 +143,7 @@ covering every surface with plain-language descriptions. The full list:| `repowise.agentTools.enabled` | `true` | Enable or disable native VS Code Language Model Tools for Copilot Chat || `repowise.diagnostics.enabled` | `false` | Publish health findings to the Problems panel || `repowise.diagnostics.minSeverity` | `high` | Lowest severity surfaced in the Problems panel |-| `repowise.diagnostics.dimensions` | all | Health dimensions included in the Problems panel |+| `repowise.diagnostics.dimensions` | defect, maintainability, performance | Health dimensions included in the Problems panel. `advisory` is selectable and off by default: it never deducts from a score, and it reaches the gutter, the hovers and the language-model tools regardless || `repowise.gutterHeat.enabled` | `true` | Shade the gutter next to findings || `repowise.fileDecorations.enabled` | `true` | Badge the worst-health files in the explorer || `repowise.fileDecorations.maxScore` | `4` | Health score at or below which a file is badged |diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex b9940feeb..4c8fc9c72 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -775,7 +775,7 @@ module per surface, sharing `scope.py`, `counts.py`, `file_filters.py` and| `GET /files/breakdown` | one file's metric + score breakdown + findings + suggestions + per-file `trend` + `signals` || `GET /files/trend` | one file's score-over-time series + current delta + `declining` flag (`?file_path=`) || `GET /trend` | repo KPI history + alerts + last-two-snapshot per-file deltas |-| `GET /findings` | findings list, filterable by `biomarker_type`, `file_path`, `dimension`, `status` and severity (`severity` exact, or the `min_severity` floor). Performance is excluded unless asked for by name |+| `GET /findings` | findings list, filterable by `biomarker_type`, `file_path`, `dimension`, `status` and severity (`severity` exact, or the `min_severity` floor). The zero-impact dimensions, performance and advisory, are out of the ranked list: name one in `dimension`, name a marker in `biomarker_type`, or pass `include_zero_impact=true` || `GET /coverage` | coverage summary + per-file rows || `POST /coverage` | ingest a coverage report (used by some CI integrations) || `GET /refactoring-targets` | the work queue: files carrying findings, ranked by `total_impact / effort_bucket`. Takes the findings filters plus `search`, `module` and the `only_hotspots` / `only_untested` / `only_failing` row filters, pages by `limit` + `offset`, and returns `total` with `finding_total` beside it. Impact counts open findings only, so dismissing work moves a file down |diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.mdindex 20507bc77..3e7b71ac6 100644--- a/docs/layers/CODE_HEALTH.md+++ b/docs/layers/CODE_HEALTH.md@@ -427,9 +427,14 @@ claims to predict bugs using evidence that says nothing about bugs.`advisory` is where those markers live. It is deliberately **not** one of thethree scored dimensions: there is no weight table, category or cap keyed on it,so "never deducts" is structural rather than a promise. Its findings carry a-`health_impact` of exactly `0.0`, are excluded from every impact-ranked work-queue, are never counted in a change's introduced/worsened totals, and can never-make a review verdict blocking.+`health_impact` of exactly `0.0`, are never counted in a change's+introduced/worsened totals, and can never make a review verdict blocking.++They are also out of every impact-ranked list, which is a statement about+ranking rather than about existence: a zero-impact row appended to a list+ordered by impact reads as a deduction that rounded away. Ask for the dimension+and you get it, and a surface that ranks nothing -- one file's findings in an+editor, or a list already filtered to one marker -- gets it without asking.| Marker | Languages | What it measures ||---|---|---|diff --git a/packages/api-client/src/code-health.ts b/packages/api-client/src/code-health.tsindex 2b7a55829..93481b33a 100644--- a/packages/api-client/src/code-health.ts+++ b/packages/api-client/src/code-health.ts@@ -95,6 +95,8 @@ export async function listHealthFindings(/** Exact severities, comma-separated. Overrides `min_severity`. */severity?: string;dimension?: string;+ /** Also return performance and advisory, which no impact-ranked list holds. */+ include_zero_impact?: boolean;/** Comma-separated statuses, or `"all"`. Defaults to open work. */status?: string;limit?: number;diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.py b/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.pyindex d980f39b1..ab41c7338 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.py@@ -68,6 +68,10 @@ def _render_refactoring_targets(nloc = m.nloc if m is not None else 0score = m.score if m is not None else 10.0primary = primary_finding(fs)+ # None means every finding here is advisory, which deducts nothing and+ # so names no work for a table ranked by impact over effort.+ if primary is None:+ continuetotal_impact = round(sum(x.health_impact for x in fs), 3)bucket, weight = _effort_bucket(nloc)file_sugg = sugg_by_file.get(path, [])diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/assertion_free_test.py b/packages/core/src/repowise/core/analysis/health/biomarkers/assertion_free_test.pyindex 4dc47dc4a..3cb3a099c 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/assertion_free_test.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/assertion_free_test.py@@ -26,7 +26,7 @@ apart are in ``complexity/assertions.py``.``if (!ok) throw new Error(...)``, and a wait helper that gives up by throwingrather than by asserting, both fail their test on the property the author named.No assertion vocabulary reaches either, because a ``throw`` is a statement and-the vocabularies match callee names. ``asserts/lexicon.checks_something`` is the+the vocabularies match callee names. ``asserts/predicate.checks_something`` is thepredicate; it is deliberately not folded into ``assertion_count``, which iscalibrated.diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex 5584a72dc..1b57aac3e 100644--- a/packages/core/src/repowise/core/analysis/health/engine.py+++ b/packages/core/src/repowise/core/analysis/health/engine.py@@ -127,7 +127,7 @@ log = structlog.get_logger(__name__)# ``mock_saturated_test`` and ``large_assertion_block`` read ``assertion_count``# and ``assertion_blocks`` directly and are untouched. Only# ``assertion_free_test`` and the oracle pass behind it read the new field, both-# through ``asserts/lexicon.checks_something``, and both as a boolean.+# through ``asserts/predicate.checks_something``, and both as a boolean.## v20 finally reads an assertion call from a position ``_assertion_tier`` never# classifies, because that pass classifies statements: a ``const e =diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex ff1c89623..fa137d764 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -1563,15 +1563,16 @@ async def get_health(Every block and accepted value: docs/agent/MCP_TOOLS.md.Args:- targets: file paths or ``module:<name>``; empty means dashboard,- unmatched ones land in ``unresolved``.+ targets: file paths or ``module:<name>``; unmatched ones land in+ ``unresolved``.include: ``biomarkers``|``refactoring``|``trend``|``coverage``|``accuracy``|``signals``|``churn_complexity``|``doc_drift``,- or a dimension; ``performance``/``refactoring`` add queues.+ or a dimension incl. ``advisory``; ``performance`` and+ ``refactoring`` add queues.only: keys to keep; identity, totals, recovery survive.``biomarkers``/``accuracy``/``refactoring`` alias their block key;- ``performance``/``defect``/``maintainability`` do not: they filter- rows and land in ``unknown_only_keys``.+ ``performance``/``defect``/``maintainability``/``advisory``+ do not: they filter rows into ``unknown_only_keys``.repo: usually omitted.limit: max rows per ranked list, ``0`` for none.cursor: zero-based offset into a ranked list.@@ -1583,8 +1584,8 @@ async def get_health(performance_view/_context/_boundary/_confidence/_sort: queueprojection and filters; the facets list them.scope / counts: default ``all``/``everything``. ``production`` drops- test files, which score higher; ``code_shape`` drops the- git-derived half of the score and its findings.+ test files; ``code_shape`` drops the git-derived half of the+ score and its findings."""started = perf_counter()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 ab8e4653d..0ff74bfb9 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@@ -41,7 +41,12 @@ async def list_health_findings(severity: str | None = Query(None, description="Exact severities, comma-separated. Overrides min_severity."),- dimension: str | None = Query(None),+ dimension: str | None = Query(+ None, description="defect | maintainability | performance | advisory"+ ),+ include_zero_impact: bool = Query(+ False, description="Also return the performance and advisory dimensions"+ ),status: str = Query("open", description=STATUS_FILTER_DESCRIPTION),limit: int = Query(100, ge=1, le=1000),scope: str = ScopeQuery,@@ -50,12 +55,30 @@ async def list_health_findings() -> list[dict]:"""Findings, ranked by health impact. Open work unless ``status`` says otherwise.- Performance is out of the unfiltered list by default. Its findings carry a- health impact of zero by construction, so ranking them here sorts them- below every defect row and reads as "nothing here" rather than as a- different unit; the performance surfaces rank the same evidence by cause.- Asking for ``dimension=performance`` still returns it.+ The zero-impact dimensions, performance and advisory, are out of the+ unfiltered list by default. Their findings carry a health impact of zero by+ construction, so ranking them here sorts them below every defect row and+ reads as "nothing here" rather than as a different unit; the performance+ surfaces rank the same evidence by cause.++ Three things return them. ``dimension`` names one outright and always has.+ ``biomarker_type`` names a marker, which fixes its dimension, so applying+ the exclusion on top could only ever answer nothing -- and the marker menu+ on the work queue is built from a breakdown that counts every dimension,+ so every zero-impact option in it matched nothing. And+ ``include_zero_impact`` asks, for the caller whose own narrowing the+ parameters cannot express.++ That last one is a flag rather than an inference from ``file_path``+ because two callers pass a path wanting opposite things: an editor+ signalling one open file wants every finding on it, while the web+ expander behind "show all N findings" wants exactly the set the queue+ counted N from, and a wider answer there opens onto more rows than the+ row above it promised."""+ # The exclusion holds for the list that ranks the whole repository against+ # itself. See the docstring for the three ways out.+ ranks_everything = biomarker_type is None and not include_zero_impactfindings = await crud.get_health_findings(session,repo_id,@@ -65,7 +88,9 @@ async def list_health_findings(severity=severity,dimension=dimension,status=parse_status_filter(status),- exclude_dimensions=tuple(sorted(ZERO_IMPACT_DIMENSIONS)),+ exclude_dimensions=(+ tuple(sorted(ZERO_IMPACT_DIMENSIONS)) if ranks_everything else None+ ),)# A finding carries a path, not ``is_test``, so narrowing it needs the# metric rows that do. Read them only when the answer depends on them: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 4325372ab..00d93a55d 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@@ -71,7 +71,9 @@ async def health_work_queue(severity: str | None = Query(None, description="Exact severities, comma-separated. Overrides min_severity."),- dimension: str | None = Query(None, description="defect | maintainability | performance"),+ dimension: str | None = Query(+ None, description="defect | maintainability | performance | advisory"+ ),status: str = Query("open", description=STATUS_FILTER_DESCRIPTION),search: str | None = Query(None, description="Substring filter on file_path"),only_hotspots: bool = Query(False),@@ -100,15 +102,19 @@ async def health_work_queue(raise HTTPException(status_code=404, detail="Repository not found")metrics = await crud.get_health_metrics(session, repo_id)+ # As the findings list does, so a row's count and the list behind it agree:+ # the zero-impact dimensions stay out of the ranking, and naming one thing+ # -- here a marker -- takes the caller out of that ranking and returns it.+ # The marker options come from the unfiltered breakdown, so without this+ # every advisory and performance marker in that menu matches nothing.findings = await crud.get_health_findings(session,repo_id,dimension=dimension,status=parse_status_filter(status),- # As the findings list does, so a row's count and the list behind it- # agree. Performance carries zero health impact and ranks by cause on- # its own surface; ``dimension=performance`` still returns it.- exclude_dimensions=tuple(sorted(ZERO_IMPACT_DIMENSIONS)),+ exclude_dimensions=(+ tuple(sorted(ZERO_IMPACT_DIMENSIONS)) if biomarker is None else None+ ),)metrics, findings = narrow(scope, metrics, findings)metrics, findings, _unscored = project(counts, metrics, findings)@@ -157,6 +163,14 @@ async def health_work_queue(nloc = m.nlocscore = m.scoreprimary = primary_finding(fs)+ if primary is None:+ # Every finding here is advisory, so no cause accuses this file and+ # the general queue never reaches this: advisory is excluded from+ # it. A caller who filtered to an advisory marker did reach it, and+ # the marker they asked for is the honest lead for the row.+ primary = max(+ fs, key=lambda x: (_SEVERITY_ORDER.get(x.severity, 0), -(x.line_start or 0))+ )# Impact, and therefore the ranking, counts only findings still open:# ``score`` on this row was computed from open findings, and a file# whose findings were all dismissed is not work to rank near the top.diff --git a/packages/server/src/repowise/server/routers/code_health/serializers.py b/packages/server/src/repowise/server/routers/code_health/serializers.pyindex 7245e6e99..d5bc973dc 100644--- a/packages/server/src/repowise/server/routers/code_health/serializers.py+++ b/packages/server/src/repowise/server/routers/code_health/serializers.py@@ -52,15 +52,18 @@ def _primary_and_magnitude(findings: list[Any]) -> dict:is already the applied, capped value), so it distinguishes two files thatboth floor at 1.0 (a -25 file from a -9 one) without touching ``score``.- All-null on an empty list: a clean file has no lead and no magnitude.+ All-null on an empty list: a clean file has no lead and no magnitude. A+ file whose every finding is advisory gets a null lead and a real magnitude+ of zero -- ``primary_finding`` declines to name a cause that deducts+ nothing, and reading that refusal as a finding raised here instead."""if not findings:return {"primary_biomarker": None, "primary_reason": None, "total_deduction": None}primary = primary_finding(findings)total = sum(float(x.health_impact or 0.0) for x in findings)return {- "primary_biomarker": primary.biomarker_type,- "primary_reason": primary.reason,+ "primary_biomarker": primary.biomarker_type if primary else None,+ "primary_reason": primary.reason if primary else None,"total_deduction": round(total, 3),}diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 672e960d6..add68e3b4 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -44,8 +44,10 @@ export type ScoredHealthDimension = "defect" | "maintainability" | "performance"/*** The non-scoring fourth dimension. A marker homes here when it measures* something no defect corpus labels, so it can never be calibrated and never- * earns weight. Its findings carry a zero health impact by construction and are- * kept out of every impact-ranked queue, so they describe without accusing.+ * earns weight. Its findings carry a zero health impact by construction and so+ * are kept out of every impact-ranked queue, describing without accusing. That+ * is about ranking, not existence: a surface that ranks nothing, such as one+ * file's findings in an editor, asks for them and gets them.** Mirror of `ADVISORY_DIMENSION` in core's `scoring.py`. Deliberately outside* `HEALTH_DIMENSIONS`, which stays exactly the set that carries a score.diff --git a/packages/vscode/package.json b/packages/vscode/package.jsonindex e3053ce24..9e0d83fa2 100644--- a/packages/vscode/package.json+++ b/packages/vscode/package.json@@ -93,10 +93,10 @@"type": "array","items": {"type": "string",- "enum": ["defect", "maintainability", "performance"]+ "enum": ["defect", "maintainability", "performance", "advisory"]},"default": ["defect", "maintainability", "performance"],- "description": "Health dimensions included in the Problems panel."+ "description": "Health dimensions included in the Problems panel. Advisory findings never deduct from a score, so they are off by default; they stay visible in the gutter, in hovers and to the language-model tools either way."},"repowise.gutterHeat.enabled": {"type": "boolean",diff --git a/packages/vscode/src/core/fileSignals.ts b/packages/vscode/src/core/fileSignals.tsindex c4e83fdd1..fa608524a 100644Binary files a/packages/vscode/src/core/fileSignals.ts and b/packages/vscode/src/core/fileSignals.ts differdiff --git a/packages/vscode/src/core/webviewApi.ts b/packages/vscode/src/core/webviewApi.tsindex 597692685..767fcc99e 100644--- a/packages/vscode/src/core/webviewApi.ts+++ b/packages/vscode/src/core/webviewApi.ts@@ -77,7 +77,7 @@ const SETTING_DEFAULTS: SettingsValues = {};const SEVERITIES = ["critical", "high", "medium", "low"];-const DIMENSIONS = ["defect", "maintainability", "performance"];+const DIMENSIONS = ["defect", "maintainability", "performance", "advisory"];/*** Per-key validator for writes. The webview is untrusted input, so an out-of-diff --git a/packages/vscode/webview/src/views/settings/App.tsx b/packages/vscode/webview/src/views/settings/App.tsxindex 4bf47d82a..114234232 100644--- a/packages/vscode/webview/src/views/settings/App.tsx+++ b/packages/vscode/webview/src/views/settings/App.tsx@@ -76,13 +76,15 @@ const GROUPS: Group[] = [{key: "diagnostics.dimensions",label: "Problem dimensions",- description: "Which health dimensions appear in the Problems panel.",+ description:+ "Which health dimensions appear in the Problems panel. Advisory never deducts from a score, so it is off by default and stays in the gutter and in hovers.",kind: "multiselect",needs: "diagnostics.enabled",options: [{ value: "defect", label: "Defect" },{ value: "maintainability", label: "Maintainability" },{ value: "performance", label: "Performance" },+ { value: "advisory", label: "Advisory" },],},{diff --git a/tests/unit/cli/test_refactoring_targets_render.py b/tests/unit/cli/test_refactoring_targets_render.pyindex d4e2aba8d..87cef3243 100644--- a/tests/unit/cli/test_refactoring_targets_render.py+++ b/tests/unit/cli/test_refactoring_targets_render.py@@ -11,6 +11,11 @@ from __future__ import annotationsimport jsonfrom repowise.cli.commands.health_cmd import _render_refactoring_targets+from repowise.core.analysis.health.models import (+ HealthFileMetricData,+ HealthFindingData,+ Severity,+)from repowise.core.analysis.health.refactoring import RefactoringSuggestion@@ -178,3 +183,57 @@ def test_a_step_whose_plan_falls_outside_the_limit_still_renders(capsys):for fmt in ("console", "md"):_render_refactoring_targets([], [], suggestions, fmt=fmt, limit=3)assert capsys.readouterr().out+++def _metric(path: str) -> HealthFileMetricData:+ return HealthFileMetricData(+ file_path=path,+ score=7.0,+ max_ccn=1,+ max_nesting=1,+ nloc=40,+ has_test_file=False,+ )+++def _finding(path: str, biomarker: str, impact: float) -> HealthFindingData:+ return HealthFindingData(+ biomarker_type=biomarker,+ severity=Severity.LOW,+ file_path=path,+ function_name="f",+ line_start=3,+ line_end=5,+ details={},+ health_impact=impact,+ reason=f"{biomarker} in {path}",+ )+++def test_a_file_whose_findings_are_all_advisory_leaves_the_table(capsys):+ """``primary_finding`` names no cause for one, and the table ranks causes.++ It returns None rather than an advisory row, because advisory deducts+ nothing. Dereferencing that took the whole command down, and the row it+ would have produced ranks at an impact of zero regardless.+ """+ metrics = [_metric("a.py"), _metric("b_test.py")]+ findings = [+ _finding("a.py", "complex_method", 2.5),+ _finding("b_test.py", "assertion_free_test", 0.0),+ ]+ _render_refactoring_targets(metrics, findings, [], fmt="json")+ out = json.loads(capsys.readouterr().out)+ assert [t["file_path"] for t in out["targets"]] == ["a.py"]+++def test_an_advisory_finding_beside_a_real_one_keeps_the_real_lead(capsys):+ """The sibling shape: a file is only dropped when nothing accuses it."""+ metrics = [_metric("a.py")]+ findings = [+ _finding("a.py", "assertion_free_test", 0.0),+ _finding("a.py", "complex_method", 2.5),+ ]+ _render_refactoring_targets(metrics, findings, [], fmt="json")+ out = json.loads(capsys.readouterr().out)+ assert [t["primary_biomarker"] for t in out["targets"]] == ["complex_method"]diff --git a/tests/unit/server/test_findings_performance_exclusion.py b/tests/unit/server/test_findings_performance_exclusion.pyindex 7dddcad0f..12c52f390 100644--- a/tests/unit/server/test_findings_performance_exclusion.py+++ b/tests/unit/server/test_findings_performance_exclusion.py@@ -1,9 +1,15 @@-"""Performance stays out of the impact-ranked queues, and reachable on request.--Every performance finding carries a health impact of zero by construction, so a-list ordered by impact sorts them below every defect row. That is not a ranking-of performance work, it is a tail nobody reads, and it renders as a deduction-that rounded away. The dimension answers on its own surfaces instead.+"""The zero-impact dimensions stay out of the ranked queues, and stay reachable.++Every performance and advisory finding carries a health impact of zero by+construction, so a list ordered by impact sorts them below every defect row.+That is not a ranking of that work, it is a tail nobody reads, and it renders+as a deduction that rounded away. The dimension answers on its own surfaces.++The defence is about ranking everything against everything. A caller naming one+file or one marker has left that ranking, so it gets every finding on the thing+it named -- which is what a per-file editor signal and a marker-filtered list+both need, and without which a marker menu built from the unfiltered breakdown+offers options that match nothing."""from __future__ import annotations@@ -14,10 +20,15 @@ from repowise.core.analysis.health.models import HealthFindingData, Severityfrom repowise.core.persistence import crudfrom tests.unit.server.conftest import create_test_repo+_BIOMARKER = {+ "performance": "io_in_loop",+ "advisory": "assertion_free_test",+}+def _finding(path: str, dimension: str, impact: float) -> HealthFindingData:return HealthFindingData(- biomarker_type="io_in_loop" if dimension == "performance" else "complex_method",+ biomarker_type=_BIOMARKER.get(dimension, "complex_method"),severity=Severity.MEDIUM,file_path=path,function_name="run",@@ -49,7 +60,7 @@ async def _seed(app, client: AsyncClient) -> str:repo = await create_test_repo(client)async with app.state.session_factory() as session:await crud.save_health_metrics(- session, repo["id"], [_metric(f"src/{n}.py") for n in "abc"]+ session, repo["id"], [_metric(f"src/{n}.py") for n in "abcd"])await crud.save_health_findings(session,@@ -58,26 +69,136 @@ async def _seed(app, client: AsyncClient) -> str:_finding("src/a.py", "defect", 2.5),_finding("src/b.py", "maintainability", 1.0),_finding("src/c.py", "performance", 0.0),+ _finding("src/d.py", "advisory", 0.0),],)await session.commit()return repo["id"]-async def test_the_unfiltered_findings_list_leaves_performance_out(app, client):+async def test_the_unfiltered_findings_list_leaves_the_zero_impact_ones_out(app, client):repo_id = await _seed(app, client)rows = (await client.get(f"/api/repos/{repo_id}/health/findings")).json()assert {r["dimension"] for r in rows} == {"defect", "maintainability"}-async def test_asking_for_the_dimension_still_returns_it(app, client):+async def test_a_caller_that_asks_gets_every_finding_on_a_file(app, client):+ """The per-file fetch behind every editor signal. It ranks nothing.++ A flag rather than an inference from ``file_path``, because the web+ expander names a path too and wants the opposite: exactly the set the row+ above it counted.+ """+ repo_id = await _seed(app, client)+ for path, dimension in (("src/c.py", "performance"), ("src/d.py", "advisory")):+ params = {"file_path": path, "include_zero_impact": "true"}+ rows = (+ await client.get(f"/api/repos/{repo_id}/health/findings", params=params)+ ).json()+ assert [r["dimension"] for r in rows] == [dimension], path+++async def test_naming_a_file_alone_stays_in_the_ranked_set(app, client):+ repo_id = await _seed(app, client)+ for path in ("src/c.py", "src/d.py"):+ rows = (+ await client.get(+ f"/api/repos/{repo_id}/health/findings", params={"file_path": path}+ )+ ).json()+ assert rows == [], path+++async def test_naming_a_marker_returns_its_findings(app, client):repo_id = await _seed(app, client)rows = (await client.get(- f"/api/repos/{repo_id}/health/findings", params={"dimension": "performance"}+ f"/api/repos/{repo_id}/health/findings",+ params={"biomarker_type": "assertion_free_test"},+ )+ ).json()+ assert [r["file_path"] for r in rows] == ["src/d.py"]+++async def test_asking_does_not_widen_the_list_past_the_file_named(app, client):+ """The escape is from the dimension filter, not from the file filter."""+ repo_id = await _seed(app, client)+ rows = (+ await client.get(+ f"/api/repos/{repo_id}/health/findings",+ params={"file_path": "src/a.py", "include_zero_impact": "true"},+ )+ ).json()+ assert [r["file_path"] for r in rows] == ["src/a.py"]+++async def test_the_work_queue_ranks_without_the_zero_impact_dimensions(app, client):+ repo_id = await _seed(app, client)+ queue = (await client.get(f"/api/repos/{repo_id}/health/refactoring-targets")).json()+ assert {t["file_path"] for t in queue["targets"]} == {"src/a.py", "src/b.py"}+++async def test_a_file_with_only_advisory_findings_has_no_lead(app, client):+ """And the overview still answers.++ ``primary_finding`` returns None for a file no finding accuses, which is+ deliberate: an advisory marker deducts nothing, so naming one as the reason+ a file is unhealthy would print a cause beside a deduction of zero. Every+ reader of it has to treat that None as an answer.+ """+ repo_id = await _seed(app, client)+ response = await client.get(f"/api/repos/{repo_id}/health/overview")+ assert response.status_code == 200+ lead = next(f for f in response.json()["files"] if f["file_path"] == "src/d.py")+ assert lead["primary_biomarker"] is None+ assert lead["primary_reason"] is None+ assert lead["total_deduction"] == 0.0+++async def test_a_queue_row_filtered_to_an_advisory_marker_leads_with_it(app, client):+ """The one reader that cannot pass the refusal on: the row needs a lead."""+ repo_id = await _seed(app, client)+ queue = (+ await client.get(+ f"/api/repos/{repo_id}/health/refactoring-targets",+ params={"biomarker": "assertion_free_test"},)).json()- assert [r["file_path"] for r in rows] == ["src/c.py"]+ assert [t["file_path"] for t in queue["targets"]] == ["src/d.py"]+ assert queue["targets"][0]["primary_biomarker"] == "assertion_free_test"+ assert queue["targets"][0]["total_impact"] == 0.0+++async def test_every_marker_the_menu_offers_returns_a_row(app, client):+ """The marker menu is built from the unfiltered breakdown, so it must.++ Selecting an option that can never match reads as "no such work", which is+ the opposite of what the breakdown that offered it said.+ """+ repo_id = await _seed(app, client)+ overview = (await client.get(f"/api/repos/{repo_id}/health/overview")).json()+ offered = sorted({b["biomarker_type"] for b in overview["biomarkers"]})+ assert "assertion_free_test" in offered, offered+ for marker in offered:+ queue = (+ await client.get(+ f"/api/repos/{repo_id}/health/refactoring-targets",+ params={"biomarker": marker},+ )+ ).json()+ assert queue["targets"], marker+ assert {t["primary_biomarker"] for t in queue["targets"]} == {marker}+++async def test_asking_for_the_dimension_still_returns_it(app, client):+ repo_id = await _seed(app, client)+ for dimension, path in (("performance", "src/c.py"), ("advisory", "src/d.py")):+ rows = (+ await client.get(+ f"/api/repos/{repo_id}/health/findings", params={"dimension": dimension}+ )+ ).json()+ assert [r["file_path"] for r in rows] == [path], dimensionasync def test_a_null_dimension_still_reads_as_defect_work(app, client):@@ -95,7 +216,16 @@ async def test_a_null_dimension_still_reads_as_defect_work(app, client):async def test_the_overview_queue_leaves_performance_out_but_still_counts_it(app, client):repo_id = await _seed(app, client)overview = (await client.get(f"/api/repos/{repo_id}/health/overview")).json()- assert all(f["dimension"] != "performance" for f in overview["top_findings"])- # The rollups above the queue still see every dimension: excluding a row- # from a ranking is not the same as pretending it does not exist.+ ranked = {f["dimension"] for f in overview["top_findings"]}+ assert ranked == {"defect", "maintainability"}+ # The rollup above the queue still counts performance: excluding a row from+ # a ranking is not the same as pretending it does not exist. Advisory is+ # the one dimension it also leaves out, because it is not open work.assert overview["summary"]["open_findings"] == 3+ # The marker breakdown behind the marker menu counts all four, which is+ # what makes the menu wider than any ranked list it filters.+ assert {b["biomarker_type"] for b in overview["biomarkers"]} == {+ "complex_method",+ "io_in_loop",+ "assertion_free_test",+ }diff --git a/tests/unit/server/test_health_work_queue_controls.py b/tests/unit/server/test_health_work_queue_controls.pyindex 219f05b0f..cf4f896a7 100644--- a/tests/unit/server/test_health_work_queue_controls.py+++ b/tests/unit/server/test_health_work_queue_controls.py@@ -258,6 +258,37 @@ async def test_a_rows_count_matches_the_findings_behind_it(client, session, tmp_assert row["finding_count"] == len(behind) == 1+async def test_a_zero_impact_finding_does_not_break_that_count(+ client, session, tmp_path+) -> None:+ """The unfiltered pair, which the severity filter above never reaches.++ Both sides leave the zero-impact dimensions out, and a per-file read only+ widens past them when it says so. Naming a path is not saying so: this is+ the caller that wants exactly what the row beside it counted.+ """+ repo_id = await _repo(+ client,+ session,+ tmp_path,+ [_metric("a.py", 4.0)],+ [+ _finding("a.py"),+ _finding("a.py", "io_in_loop", impact=0.0, dimension="performance"),+ _finding("a.py", "assertion_free_test", impact=0.0, dimension="advisory"),+ ],+ )++ row = (await _queue(client, repo_id, ""))["targets"][0]+ url = f"/api/repos/{repo_id}/health/findings?file_path=a.py"+ behind = (await client.get(url)).json()+ assert row["finding_count"] == len(behind) == 1++ # And the caller that does say so gets all three.+ widened = (await client.get(f"{url}&include_zero_impact=true")).json()+ assert len(widened) == 3++async def test_exact_severity_beats_the_threshold_on_the_findings_list(client, session, tmp_path) -> None: