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(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.md
index 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.py
index 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 annotations
import hashlib
+from collections.abc import Iterable
from dataclasses import dataclass
from 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, ChangeHealthDelta
from .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, EvidenceState
if 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.path
actions.append(
ReviewAction(
@@ -250,6 +267,17 @@ def _actions(delta: ChangeHealthDelta, tests: CoveringTestEvidence) -> tuple[Rev
return 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.py
index 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.py
index 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 annotations
from typing import Any
from 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.py
index 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.py
index 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_r
assert 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))