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(change-risk): lead the headline, reasons, actions and findings with the same finding (#4215)
Raghav Chamadiyae0ccad426660
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.mdindex 41e087f43..b3ef299fd 100644--- a/docs/reference/MCP_RESPONSE_FIELDS.md+++ b/docs/reference/MCP_RESPONSE_FIELDS.md@@ -266,7 +266,7 @@ Every float is rounded to 4 significant digits. Direct rows' `structural_score`| Field | Meaning ||-------|---------|-| `directive` | `status` (`review_required`, `review_recommended`, `clear_in_analyzed_scope`, `unknown`), a headline, reasons, next actions |+| `directive` | `status` (`review_required`, `review_recommended`, `clear_in_analyzed_scope`, `unknown`), a headline, reasons, next actions. Findings that gate the verdict (high or critical, not performance) lead the reasons, the inspect actions and `top_findings`, so the headline's finding comes first in each; its count reads "N of M" when other findings are lower. The headline ends with the changed code's health on both sides || `health_delta` | What the change newly made worse. See below || `risk_percentile` | The change's diff size and spread ranked against the repo's recent commits. Size, not a verdict: `directive.status` is the verdict. `include=["scales"]` adds the `review_priority` tercile and its `classification` (`Below-typical`, `Typical` or `Above-typical diff size`) || `is_fix` | Present only when the change is a bug fix |diff --git a/packages/core/src/repowise/core/analysis/review_directive.py b/packages/core/src/repowise/core/analysis/review_directive.pyindex 0b9128002..1a7d591c9 100644--- a/packages/core/src/repowise/core/analysis/review_directive.py+++ b/packages/core/src/repowise/core/analysis/review_directive.py@@ -12,10 +12,12 @@ is given.from __future__ import annotationsimport hashlib+from collections.abc import Iterablefrom dataclasses import dataclassfrom typing import Literal-from .change_health.models import NOT_ANALYZABLE_DATA, ChangeHealthDelta+from .change_health.file_scores import score_change+from .change_health.models import NOT_ANALYZABLE_DATA, ChangeFinding, ChangeHealthDeltafrom .health.scoring import ADVISORY_DIMENSION#: How much of a lane's evidence was actually computed.@@ -116,6 +118,20 @@ class CoveringTestEvidence:run_all: str | None = None+def _blocks(finding: ChangeFinding) -> bool:+ return finding.severity in _BLOCKING_SEVERITIES and finding.dimension not in _ADVISORY_DIMENSIONS+++def review_order(findings: Iterable[ChangeFinding]) -> list[ChangeFinding]:+ """The findings that gate the verdict first, each group in its given order.++ The headline, reasons, inspect actions and any finding list a surface+ shows all read this one order, so the finding the headline names leads+ every one of them.+ """+ return sorted(findings, key=lambda f: not _blocks(f))++def _plural(word: str, count: int) -> str:return word if count == 1 else f"{word}s"@@ -140,18 +156,19 @@ def _verdict(delta: ChangeHealthDelta) -> tuple[ReviewStatus, str, EvidenceStateif delta.status in _UNTRUSTWORTHY:return "unknown", f"No trustworthy baseline: {delta.explanation}", "degraded"- blocking = [- f- for f in delta.findings- if f.severity in _BLOCKING_SEVERITIES and f.dimension not in _ADVISORY_DIMENSIONS- ]+ blocking = [f for f in delta.findings if _blocks(f)]state: EvidenceState = "partial" if delta.status == "partial" else "available"if blocking:- lead = blocking[0]+ lead, total = blocking[0], len(delta.findings)+ # Out of every finding, so the headline's count agrees with the delta's.+ counted = (+ f"{len(blocking)} new {_plural('finding', len(blocking))}"+ if len(blocking) == total+ else f"{len(blocking)} of {total} new findings"+ )return ("review_required",- f"{len(blocking)} new {_plural('finding', len(blocking))} "- f"{'needs' if len(blocking) == 1 else 'need'} review, "+ f"{counted} {'needs' if len(blocking) == 1 else 'need'} review, "f"starting with {lead.biomarker_type} in {lead.path}.",state,)@@ -182,7 +199,7 @@ def _reasons(delta: ChangeHealthDelta) -> tuple[str, ...]:reasons = [f"{f.severity} {f.dimension}: {f.biomarker_type} in "f"{f.symbol or f.path} ({f.attribution_basis})"- for f in delta.findings+ for f in review_order(delta.findings)]skipped = len(delta.code_skipped)if skipped:@@ -195,7 +212,7 @@ def _reasons(delta: ChangeHealthDelta) -> tuple[str, ...]:def _actions(delta: ChangeHealthDelta, tests: CoveringTestEvidence) -> tuple[ReviewAction, ...]:actions: list[ReviewAction] = []- for priority, finding in enumerate(delta.findings):+ for priority, finding in enumerate(review_order(delta.findings)):where = f"{finding.path}:{finding.line_start}" if finding.line_start else finding.pathactions.append(ReviewAction(@@ -250,6 +267,17 @@ def _actions(delta: ChangeHealthDelta, tests: CoveringTestEvidence) -> tuple[Revreturn tuple(actions)+def _net_health(delta: ChangeHealthDelta) -> str:+ """The changed code's base-nloc average score on both sides, or ``""`` without one."""+ change = score_change(delta.files)+ if change is None:+ return ""+ base, head = round(change.base, 2), round(change.head, 2)+ if base == head:+ return f" Health of the changed code holds at {head:.2f}."+ return f" Health of the changed code: {base:.2f} to {head:.2f} ({head - base:+.2f})."++def review_directive(delta: ChangeHealthDelta,tests: CoveringTestEvidence | None = None,@@ -259,7 +287,7 @@ def review_directive(status, headline, state = _verdict(delta)return ReviewDirective(status=status,- headline=headline,+ headline=headline + _net_health(delta),reasons=_reasons(delta),actions=_actions(delta, tests),evidence_state=state,diff --git a/packages/server/src/repowise/server/mcp_server/_change_health.py b/packages/server/src/repowise/server/mcp_server/_change_health.pyindex 3ccde06f8..be70712a0 100644--- a/packages/server/src/repowise/server/mcp_server/_change_health.py+++ b/packages/server/src/repowise/server/mcp_server/_change_health.py@@ -20,6 +20,7 @@ from repowise.core.analysis.review_directive import (ReviewAction,ReviewDirective,review_directive,+ review_order,)from repowise.server.mcp_server._test_selection import UNAVAILABLE_REASON@@ -165,7 +166,7 @@ def _scope_words(label: str) -> str:def health_delta_block(delta: ChangeHealthDelta, *, revspec: str | None) -> dict[str, Any]:"""The compact delta: what got worse, how much was compared, and how sure."""- emitted = delta.findings[:TOP_FINDINGS_LIMIT]+ emitted = review_order(delta.findings)[:TOP_FINDINGS_LIMIT]block: dict[str, Any] = {"status": delta.status,"explanation": delta.explanation,diff --git a/packages/server/src/repowise/server/mcp_server/tool_change_risk/payload.py b/packages/server/src/repowise/server/mcp_server/tool_change_risk/payload.pyindex c58cdd758..6278f56cf 100644--- a/packages/server/src/repowise/server/mcp_server/tool_change_risk/payload.py+++ b/packages/server/src/repowise/server/mcp_server/tool_change_risk/payload.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom typing import Anyfrom repowise.core.analysis.change_risk.render import LIMITS, size_text+from repowise.core.analysis.review_directive import review_order# Patchable names are read off the package at call time so patches reach them.from repowise.server.mcp_server import tool_change_risk as _pkg@@ -126,7 +127,7 @@ def _attach_health(if expand:from repowise.server.mcp_server._change_health import finding_row- block["top_findings"] = [finding_row(f, revspec) for f in delta.findings]+ block["top_findings"] = [finding_row(f, revspec) for f in review_order(delta.findings)]block["findings_emitted"] = len(delta.findings)block.pop("findings_reduced_reason", None)block.pop("all_findings_via", None)@@ -156,7 +157,7 @@ def _drill_down(payload: dict, delta: Any, finding_id: str, revspec: str | None)return {"error": f"No change finding {finding_id!r} in {payload.get('ref', 'this change')}.","hint": "Ids are scoped to one comparison; re-run without finding_id to list them.",- "available": [f.change_finding_id for f in delta.findings[:10]],+ "available": [f.change_finding_id for f in review_order(delta.findings)[:10]],}return {"finding": _finding_detail(match, revspec),diff --git a/tests/unit/analysis/test_review_directive.py b/tests/unit/analysis/test_review_directive.pyindex 330abe856..03af5dd33 100644--- a/tests/unit/analysis/test_review_directive.py+++ b/tests/unit/analysis/test_review_directive.py@@ -68,6 +68,21 @@ def test_blocking_finding_requires_review():assert directive.evidence_state == "available"+def test_the_headline_states_the_changed_codes_health_on_both_sides():+ from repowise.core.analysis.change_health.file_scores import FileScoreDelta++ def row(path, base, head):+ return FileScoreDelta(path, base, head, 10 - base, 10 - head, 100, 100)++ delta = _delta([_finding(severity="critical")])+ delta.files = [row("app/a.py", 8.0, 7.0), row("app/b.py", 9.5, 9.5)]+ assert review_directive(delta).headline.endswith(+ "Health of the changed code: 8.75 to 8.25 (-0.50)."+ )+ delta.files = [row("app/b.py", 9.5, 9.5)]+ assert review_directive(delta).headline.endswith("Health of the changed code holds at 9.50.")++def test_low_severity_only_recommends_review():directive = review_directive(_delta([_finding(severity="low")]))assert directive.status == "review_recommended"@@ -160,6 +175,21 @@ def test_each_finding_produces_an_inspect_action_with_its_id():assert [a.priority for a in actions] == [0, 1]+def test_the_finding_the_headline_names_leads_the_reasons_and_actions():+ mediums = [_finding(severity="medium", path=f"app/m{i}.py") for i in range(3)]+ high = _finding(severity="high", path="app/h.py", biomarker="large_method")+ directive = review_directive(_delta([*mediums, high]))+ assert directive.headline == (+ "1 of 4 new findings needs review, starting with large_method in app/h.py."+ )+ assert directive.reasons[0].startswith("high defect: large_method")+ assert directive.actions[0].targets == (high.change_finding_id,)+ # The rest keep the order the delta gave them.+ assert [a.targets[0] for a in directive.actions[1:4]] == [+ f.change_finding_id for f in mediums+ ]++def test_measured_tests_become_a_run_action_with_every_target():tests = CoveringTestEvidence(state="available", tests_to_run=tuple(f"t{i}" for i in range(9)), basis="measured")action = next(a for a in review_directive(_delta(), tests).actions if a.kind == "run_tests")diff --git a/tests/unit/change_health/test_mcp_contract.py b/tests/unit/change_health/test_mcp_contract.pyindex a3dfa0bb1..8781b03c3 100644--- a/tests/unit/change_health/test_mcp_contract.py+++ b/tests/unit/change_health/test_mcp_contract.py@@ -53,6 +53,20 @@ async def test_the_response_leads_with_the_directive_then_the_delta(tool, make_rassert result["directive"]["next_actions"]+async def test_the_headline_its_first_action_and_the_first_finding_agree(tool, make_repo):+ module = tool(seeded(make_repo))++ result = await module.get_change_risk("HEAD", baseline=0)+ directive, delta = result["directive"], result["health_delta"]+ lead = delta["top_findings"][0]++ assert directive["status"] == "review_required"+ assert f"in {lead['path']}." in directive["headline"]+ assert directive["next_actions"][0].endswith(f"({lead['id']})")+ change = delta["score_change"]+ assert f"{change['base']:.2f} to {change['head']:.2f}" in directive["headline"]++async def test_the_default_response_stays_small_and_omits_score_mechanics(tool, make_repo):module = tool(seeded(make_repo))