Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(health): let a 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.md
index 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 raw
per-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-weighted
rollup. 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 fix
first, its dominant finding, `recovers_weighted_deficit_points` /
diff --git a/docs/agent/VSCODE.md b/docs/agent/VSCODE.md
index 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.md
index 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.md
index 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 the
three 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.ts
index 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.py
index 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 0
score = m.score if m is not None else 10.0
primary = 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:
+ continue
total_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.py
index 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 throwing
rather 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 the
predicate; it is deliberately not folded into ``assertion_count``, which is
calibrated.
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 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.py
index 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: queue
projection 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.py
index 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_impact
findings = 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.py
index 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.nloc
score = m.score
primary = 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.py
index 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 that
both 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.ts
index 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.json
index 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.ts
index c4e83fdd1..fa608524a 100644
Binary files a/packages/vscode/src/core/fileSignals.ts and b/packages/vscode/src/core/fileSignals.ts differ
diff --git a/packages/vscode/src/core/webviewApi.ts b/packages/vscode/src/core/webviewApi.ts
index 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.tsx
index 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.py
index 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 annotations
import json
from 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.py
index 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, Severity
from repowise.core.persistence import crud
from 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], dimension
async 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.py
index 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: