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.

feat(refactoring): give each step of a multi-step plan its own verify (#3323)

Raghav Chamadiyaff81ff81591a
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.md
index e8b4bac41..bfdb42f01 100644
--- a/docs/layers/REFACTORING.md
+++ b/docs/layers/REFACTORING.md
@@ -60,6 +60,11 @@ tests named for the file, then the call graph. Tests that reach the file only
through a widely imported hub module are left out. When no test reaches the
change, the plan has no command and asks for a characterization test first.
+In a plan with several steps, such as a performance fix at several call sites,
+plan detail adds a `verify` to each step whose tests differ from the plan's: the
+tests that reach that step's lines and the command to run them. A step without
+one is checked by the plan's own command.
+
## Reading the results
A **plan** is one detector's output for one target. An **opportunity** is one
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/recommendations.py b/packages/core/src/repowise/core/analysis/health/refactoring/recommendations.py
index 36acc269e..de67b6547 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/recommendations.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/recommendations.py
@@ -45,6 +45,7 @@ from .models import RefactoringSuggestion
RecommendationView = Literal["canonical", "file_spread"]
ValidationBasis = Literal["measured", "inferred", "mixed", "unknown"]
ValidationVia = Literal["coverage", "call-graph", "import-graph", "name-match", "mixed"]
+VerifyCoverage = Literal["measured", "inferred", "none"]
DEFAULT_TEST_LIMIT = 12
# Public because the opportunity rank charges the same work and the same
@@ -301,6 +302,10 @@ class ValidationPlan:
reasons: dict[str, str] = field(default_factory=dict)
# What to do before the edit when no test reaches the change.
prerequisite: str | None = None
+ # Per ``plan["steps"]`` entry of a multi-step plan, its ``verify`` where it
+ # differs from the plan's, else ``None``; empty when none differs. Kept out
+ # of :meth:`as_dict`, which every list serves; plan detail reads it.
+ step_verify: list[dict[str, Any] | None] = field(default_factory=list)
def as_dict(self) -> dict[str, Any]:
return {
@@ -881,6 +886,122 @@ def build_validation_plan(
)
+def with_step_verify(
+ plan: ValidationPlan,
+ suggestion: RefactoringSuggestion,
+ measured: Mapping[str, list[dict[str, Any]]],
+ inferred: Mapping[str, ReachedBy],
+ *,
+ test_limit: int = DEFAULT_TEST_LIMIT,
+ evidence: ValidationEvidence | None = None,
+) -> ValidationPlan:
+ """*plan* with the ``verify`` of each step of a multi-step plan that differs.
+
+ Each step is validated as a plan of its own file and span, over the same
+ batch facts, so it picks its tests the way the plan does. Most steps get
+ the plan's own answer, which detail already shows once, so only the rest
+ are kept.
+ """
+ steps = _dict_list((suggestion.plan or {}).get("steps"))
+ if len(steps) < 2:
+ return plan
+ facts = evidence or ValidationEvidence()
+ own = verify_of(plan)
+ verify: list[dict[str, Any] | None] = []
+ for step in steps:
+ scoped = _step_scope(suggestion, step, facts)
+ check = (
+ own
+ if scoped is None
+ else verify_of(
+ build_validation_plan(
+ scoped, measured, inferred, test_limit=test_limit, evidence=facts
+ )
+ )
+ )
+ verify.append(None if check == own else check)
+ if not any(verify):
+ return plan
+ return dataclasses.replace(plan, step_verify=verify)
+
+
+_COVERAGE: dict[str, VerifyCoverage] = {
+ "measured": "measured",
+ "inferred": "inferred",
+ # Some files measured, some only inferred: not every line is proven run.
+ "mixed": "inferred",
+ "unknown": "none",
+}
+
+
+_VERIFY_KEYS = frozenset({"commands", "tests", "coverage"})
+
+
+def verify_of(validation: ValidationPlan) -> dict[str, Any]:
+ """*validation* in the per-step ``verify`` shape."""
+ return {
+ "commands": validation.commands,
+ "tests": validation.tests,
+ "coverage": _COVERAGE[validation.basis],
+ }
+
+
+def _step_scope(
+ suggestion: RefactoringSuggestion, step: Mapping[str, Any], facts: ValidationEvidence
+) -> RefactoringSuggestion | None:
+ """*suggestion* narrowed to the one file and span *step* edits.
+
+ A step with no line (an edit to a whole symbol) takes that symbol's span
+ from the graph, else the whole file. ``None`` when the step names no file.
+ """
+ path = step.get("file_path")
+ if not isinstance(path, str) or not path:
+ return None
+ line = step.get("line") if isinstance(step.get("line"), int) else None
+ symbol = step.get("symbol") if isinstance(step.get("symbol"), str) else ""
+ scoped = dataclasses.replace(
+ suggestion,
+ file_path=path,
+ target_symbol=symbol,
+ line_start=line,
+ line_end=line,
+ # No steps, locations or blast files: the step's own file and lines only.
+ plan={},
+ blast_radius={},
+ validation={},
+ )
+ if line is None and symbol:
+ span = _symbol_span(scoped, facts)
+ if span is not None:
+ scoped.line_start, scoped.line_end = span
+ return scoped
+
+
+def _symbol_span(
+ scoped: RefactoringSuggestion, facts: ValidationEvidence
+) -> tuple[int, int] | None:
+ """The graph span of the symbol *scoped* names in its file, if the graph has it."""
+ spans = facts.symbols.get(scoped.file_path, ())
+ named = set(target_symbol_ids(scoped, scoped.file_path, None, spans))
+ return next(((start, end) for symbol_id, start, end in spans if symbol_id in named), None)
+
+
+def steps_with_verify(steps: Sequence[Any], validation: ValidationPlan) -> list[dict[str, Any]]:
+ """*steps*, those whose checks differ from the plan's carrying ``verify``.
+
+ A step without one is checked by the plan-level validation: every step of
+ a single-step plan, and of a row stored before steps had their own.
+ """
+ rows = _dict_list(list(steps))
+ verify = validation.step_verify
+ if len(verify) != len(rows):
+ return rows
+ return [
+ {**step, "verify": check} if check else step
+ for step, check in zip(rows, verify, strict=True)
+ ]
+
+
@dataclass(frozen=True, slots=True)
class Recommendation:
suggestion: RefactoringSuggestion = field(repr=False, compare=False)
@@ -927,6 +1048,18 @@ class Recommendation:
"validation": self.validation.as_dict(),
}
+ def detail_dict(self) -> dict[str, Any]:
+ """:meth:`as_dict` for one plan read alone: a step whose checks differ
+ from the plan's carries its ``verify``."""
+ payload = self.as_dict()
+ steps = payload["plan"].get("steps")
+ if isinstance(steps, list) and self.validation.step_verify:
+ payload["plan"] = {
+ **payload["plan"],
+ "steps": steps_with_verify(steps, self.validation),
+ }
+ return payload
+
def rank_facts(self) -> dict[str, Any]:
"""What ranking added to the stored plan, persisted once at finalize."""
return {
@@ -941,6 +1074,7 @@ class Recommendation:
# Enriched with the caller rollup, which the stored column lacks.
"blast_radius": self.suggestion.blast_radius or {},
"validation": self.validation.as_dict(),
+ **({"step_verify": self.validation.step_verify} if self.validation.step_verify else {}),
}
@@ -968,6 +1102,14 @@ def stored_recommendation(row: Any) -> Recommendation | None:
validation = validation_from_profile(facts["validation"])
except TypeError:
return None
+ stored_steps = facts.get("step_verify")
+ validation = dataclasses.replace(
+ validation,
+ step_verify=[
+ check if isinstance(check, dict) and check.keys() >= _VERIFY_KEYS else None
+ for check in (stored_steps if isinstance(stored_steps, list) else [])
+ ],
+ )
suggestion = rehydrate_suggestion(row)
suggestion.blast_radius = dict(facts.get("blast_radius") or {})
suggestion.validation = validation.as_dict()
@@ -1156,6 +1298,7 @@ async def hydrate_recommendations(
view: RecommendationView = "canonical",
test_limit: int = DEFAULT_TEST_LIMIT,
rank_only: bool = False,
+ step_verify: bool = False,
) -> list[Recommendation]:
"""Hydrate, enrich, validate, rank, and serialize-ready all *rows*.
@@ -1167,6 +1310,10 @@ async def hydrate_recommendations(
rank and validation basis are unchanged, the test order falls back to name
and directory. A paged surface ranks every row this way, then passes the
rows it returns through :func:`detail_recommendations`.
+
+ *step_verify* also validates each step of a multi-step plan
+ (:func:`with_step_verify`). Finalize asks, so it is stored once; a live
+ read never rebuilds it and serves the plan-level answer.
"""
from repowise.core.persistence import crud
@@ -1189,6 +1336,7 @@ async def hydrate_recommendations(
test_limit=test_limit,
detailed=not rank_only,
in_degree=centrality,
+ step_verify=step_verify and not rank_only,
)
recommendations = build_recommendations(
suggestions,
@@ -1241,6 +1389,7 @@ async def _validation_plans(
detailed: bool,
inputs: ValidationInputs | None = None,
in_degree: Mapping[str, float] | None = None,
+ step_verify: bool = False,
) -> tuple[list[ValidationPlan], ValidationInputs]:
"""One validation plan per suggestion, every read batched across the set.
@@ -1273,6 +1422,18 @@ async def _validation_plans(
)
for suggestion in suggestions
]
+ if step_verify:
+ plans = [
+ with_step_verify(
+ plan,
+ suggestion,
+ inputs.measured,
+ inputs.inferred,
+ test_limit=test_limit,
+ evidence=evidence,
+ )
+ for plan, suggestion in zip(plans, suggestions, strict=True)
+ ]
return plans, inputs
@@ -1431,6 +1592,7 @@ __all__ = [
"ValidationEvidence",
"ValidationPlan",
"ValidationTarget",
+ "VerifyCoverage",
"affected_files",
"affected_symbols",
"apply_view",
@@ -1448,7 +1610,10 @@ __all__ = [
"priority_score",
"rehydrate_suggestion",
"serialize_recommendations",
+ "steps_with_verify",
"stored_recommendation",
"surface_confidence_risk",
"target_symbol_ids",
+ "verify_of",
+ "with_step_verify",
]
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
index 146699253..229d838d0 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
@@ -312,15 +312,22 @@ async def _plan_facts(
Serving one plan cannot afford the test-reachability walk, and without this
it fell back to an empty profile that read as "no tests" for every plan.
"""
- from ....analysis.health.refactoring.recommendations import hydrate_recommendations
+ from ....analysis.health.refactoring.recommendations import (
+ hydrate_recommendations,
+ steps_with_verify,
+ )
if not rows:
return {}
facts: dict[str, dict[str, Any]] = {}
- for recommendation in await hydrate_recommendations(session, repository_id, rows):
+ for recommendation in await hydrate_recommendations(
+ session, repository_id, rows, step_verify=True
+ ):
suggestion = recommendation.suggestion
facts[suggestion.plan["opportunity_id"]] = {
- "steps": (suggestion.plan or {}).get("steps", []),
+ "steps": steps_with_verify(
+ (suggestion.plan or {}).get("steps") or [], recommendation.validation
+ ),
"effort_bucket": suggestion.effort_bucket,
"benefit": recommendation.benefit,
"cost": recommendation.cost,
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
index 27c365b4c..3fe3c88e4 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
@@ -283,7 +283,7 @@ async def _rank_live_plans(session: AsyncSession, repository_id: str) -> list[An
)
)
).scalars()
- ranked = await hydrate_recommendations(session, repository_id, list(rows))
+ ranked = await hydrate_recommendations(session, repository_id, list(rows), step_verify=True)
await store_plan_ranks(session, repository_id, ranked)
return ranked
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py
index f690abff6..b01980f21 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py
@@ -143,11 +143,12 @@ def _refactoring_plan_id(r: Any, repository: str) -> str:
def _serialize_refactoring(
r: Any, repository: str | None = None
) -> dict[str, Any]:
- """Compatibility adapter; request paths hydrate through the async service."""
+ """One plan in full, as plan detail serves it; request paths hydrate
+ through the async service."""
if isinstance(r, Recommendation):
- payload = r.as_dict()
+ payload = r.detail_dict()
else:
- payload = build_recommendations([r])[0].as_dict()
+ payload = build_recommendations([r])[0].detail_dict()
if repository is not None:
payload["id"] = _refactoring_plan_id(r, repository)
payload["repository"] = repository
diff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.py
index 88c80ad7e..7bec70c37 100644
--- a/packages/server/src/repowise/server/routers/refactoring.py
+++ b/packages/server/src/repowise/server/routers/refactoring.py
@@ -511,7 +511,7 @@ async def get_refactoring_plan(
if row is None:
raise HTTPException(status_code=404, detail=f"refactoring plan not found: {suggestion_id}")
recommendation = await _service(session, repo_id).plan_recommendation(row)
- return _to_response(recommendation.as_dict())
+ return _to_response(recommendation.detail_dict())
class RefactoringStatusUpdate(BaseModel):
diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.py
index 44a577d25..ece3a7a3a 100644
--- a/packages/server/src/repowise/server/services/refactoring_health.py
+++ b/packages/server/src/repowise/server/services/refactoring_health.py
@@ -430,7 +430,7 @@ class RefactoringHealthService:
if row is None:
return {"resolved": False, "plan_id": plan_id, "reason": "unknown_plan_id"}
owner = await self._owning_opportunity(row.public_id, row.file_path)
- payload = (await self.plan_recommendation(row, owner=owner)).as_dict()
+ payload = (await self.plan_recommendation(row, owner=owner)).detail_dict()
payload["id"] = row.public_id or row.id
payload["status"] = row.status
result: dict[str, Any] = {"resolved": True, "plan_id": plan_id, "plan": payload}
diff --git a/packages/types/src/health.ts b/packages/types/src/health.ts
index a693a501f..e78dc7219 100644
--- a/packages/types/src/health.ts
+++ b/packages/types/src/health.ts
@@ -18,7 +18,12 @@
import type { C4IoKind } from "./external-systems.js";
import type { CoverageHistoryPoint, CoverageSummary } from "./generated/http.js";
import type { Paginated } from "./pagination.js";
-import type { StepClassification, ValidationBasis, ValidationVia } from "./refactoring.js";
+import type {
+ StepClassification,
+ StepVerify,
+ ValidationBasis,
+ ValidationVia,
+} from "./refactoring.js";
/** Finding severity used across the health surface. */
export type HealthSeverity = "low" | "medium" | "high" | "critical";
@@ -435,6 +440,9 @@ export interface PerformanceOpportunityPlanStep {
file_path: string | null;
line: number | null;
applicability: StepClassification;
+ /** How to check this step, when it differs from the plan's validation.
+ * Absent: the plan's validation checks it. */
+ verify?: StepVerify;
}
/** Ranking inputs behind a plan, not a cost/benefit ledger. */
diff --git a/packages/types/src/refactoring.ts b/packages/types/src/refactoring.ts
index b5d913977..da5652e9d 100644
--- a/packages/types/src/refactoring.ts
+++ b/packages/types/src/refactoring.ts
@@ -45,6 +45,19 @@ export interface RecommendationValidation {
prerequisite?: string | null;
}
+/** How a step's tests were found: coverage runs its lines, the graph reaches
+ * it, or nothing does. */
+export type StepVerifyCoverage = "measured" | "inferred" | "none";
+
+/** How to check one step of a plan, on plan detail only, and only on a step
+ * whose checks differ from the plan's. A step without one is checked by the
+ * plan-level validation (always so for a single-step plan). */
+export interface StepVerify {
+ commands: string[];
+ tests: string[];
+ coverage: StepVerifyCoverage;
+}
+
export interface RefactoringPlan {
id: string;
refactoring_type: RefactoringType | string;
diff --git a/packages/ui/__tests__/health/performance-view.test.tsx b/packages/ui/__tests__/health/performance-view.test.tsx
index d62487239..d2c880d9e 100644
--- a/packages/ui/__tests__/health/performance-view.test.tsx
+++ b/packages/ui/__tests__/health/performance-view.test.tsx
@@ -604,6 +604,70 @@ describe("PerformanceView drawer plan steps and validation", () => {
expect(liTexts[1]).toContain("Batch the second call");
});
+ it("shows a step's own check only where the server says it differs from the plan's", async () => {
+ const withSteps = page({
+ items: [
+ opportunity({
+ opportunity_id: "perf2_planready",
+ validation: {
+ basis: "inferred",
+ via: "call-graph",
+ total: 2,
+ tests: ["tests/test_a.py", "tests/test_b.py"],
+ commands: ["pytest tests/test_a.py tests/test_b.py"],
+ },
+ plan_steps: [
+ {
+ order: 1,
+ action: "Batch the first call",
+ symbol: "src/a.py::run",
+ file_path: "src/a.py",
+ line: 10,
+ applicability: "judgment",
+ verify: {
+ commands: ["pytest tests/test_a.py"],
+ tests: ["tests/test_a.py"],
+ coverage: "inferred",
+ },
+ },
+ {
+ order: 2,
+ action: "Batch the second call",
+ symbol: "src/b.py::run",
+ file_path: "src/b.py",
+ line: 20,
+ applicability: "judgment",
+ },
+ {
+ order: 3,
+ action: "Batch the third call",
+ symbol: "src/c.py::run",
+ file_path: "src/c.py",
+ line: 30,
+ applicability: "judgment",
+ verify: { commands: [], tests: [], coverage: "none" },
+ },
+ ],
+ }),
+ ],
+ });
+ render(
+ <PerformanceView adapter={adapter({ getPerformanceOpportunities: async () => withSteps })} />,
+ );
+ await openFirstRow();
+ const panel = await screen.findByRole("dialog");
+ const step = (text: RegExp) => within(panel).getByText(text).closest("li")!;
+ const first = step(/Batch the first call/);
+ expect(within(first).getByText("pytest tests/test_a.py")).toBeTruthy();
+ expect(within(first).getByRole("button", { name: "Copy command" })).toBeTruthy();
+ const second = step(/Batch the second call/);
+ expect(within(second).queryByRole("button", { name: "Copy command" })).toBeNull();
+ expect(within(second).queryByText(/No test reaches/)).toBeNull();
+ const third = step(/Batch the third call/);
+ expect(within(third).getByText("No test reaches this step.")).toBeTruthy();
+ expect(within(third).queryByRole("button", { name: "Copy command" })).toBeNull();
+ });
+
it("renders the stored validation through the shared validation summary", async () => {
const withValidation = page({
items: [
diff --git a/packages/ui/src/health/fix-first/fix-first-item.tsx b/packages/ui/src/health/fix-first/fix-first-item.tsx
index 98b2bd199..ce0e2de94 100644
--- a/packages/ui/src/health/fix-first/fix-first-item.tsx
+++ b/packages/ui/src/health/fix-first/fix-first-item.tsx
@@ -12,10 +12,11 @@
*/
import { useState, type ElementType } from "react";
-import { Check, ChevronDown, Copy } from "lucide-react";
+import { ChevronDown } from "lucide-react";
import type { FixItem, FixTier } from "@repowise-dev/types/fix-first";
import type { OpportunityStatus } from "@repowise-dev/types/refactoring";
+import { CommandLine } from "../../shared/command-line";
import { AiPromptButton } from "../ai-prompt-button";
import { CONFIDENCE_LABEL, EFFORT_LABEL, STATUS_LABEL } from "../labels";
import { TIER_LABEL, fixLocation, fixPlanLabel, tierReason } from "./scope";
@@ -273,35 +274,6 @@ export function FixVerify({ item }: { item: Pick<FixItem, "verify"> }) {
);
}
-function CommandLine({ command }: { command: string }) {
- const [copied, setCopied] = useState(false);
- const copy = async () => {
- try {
- await navigator.clipboard.writeText(command);
- setCopied(true);
- window.setTimeout(() => setCopied(false), 1600);
- } catch {
- /* clipboard blocked: the command stays selectable */
- }
- };
- return (
- <div className="mt-2 flex min-w-0 items-start gap-2 rounded bg-[var(--color-bg-inset)] px-2.5 py-1.5">
- <code className="min-w-0 flex-1 font-mono text-xs text-[var(--color-text-primary)] [overflow-wrap:anywhere]">
- {command}
- </code>
- <button
- type="button"
- onClick={() => void copy()}
- aria-label={copied ? "Copied" : "Copy command"}
- className="inline-flex shrink-0 items-center gap-1 rounded text-xs text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent-primary)]"
- >
- {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
- <span aria-hidden>{copied ? "Copied" : "Copy"}</span>
- </button>
- </div>
- );
-}
-
function Actions({
item,
planHref,
diff --git a/packages/ui/src/health/performance/drawer.tsx b/packages/ui/src/health/performance/drawer.tsx
index d897d48e6..8a1c7731d 100644
--- a/packages/ui/src/health/performance/drawer.tsx
+++ b/packages/ui/src/health/performance/drawer.tsx
@@ -10,12 +10,17 @@ import type {
PerformanceOpportunityValidation,
PerformanceModelState,
} from "@repowise-dev/types/health";
-import type { RecommendationValidation, RefactoringPlan } from "@repowise-dev/types/refactoring";
+import type {
+ RecommendationValidation,
+ RefactoringPlan,
+ StepVerify,
+} from "@repowise-dev/types/refactoring";
import { AdaptivePanel } from "../../shared/adaptive-panel";
import { CollapsibleSection } from "../../shared/collapsible-section";
import { InfoTip } from "../../shared/info-tip";
import { formatNumber } from "../../lib/format";
+import { CommandLine } from "../../shared/command-line";
import { ProvenancePathList } from "../../shared/provenance-path-list";
import { performancePlanDetail } from "../../refactoring/types";
import { SourceExcerpt } from "../../refactoring/source-excerpt";
@@ -242,7 +247,11 @@ function PlanSteps({ steps }: { steps: PerformanceOpportunityPlanStep[] }) {
<ol className="mt-3 space-y-1.5">
{groups.map((group, index) => {
const first = group[0]!;
- const places = group.map(where).filter((p): p is string => Boolean(p));
+ const places = group
+ .map((step) => ({ place: where(step), verify: step.verify }))
+ .filter((p): p is { place: string; verify: StepVerify | undefined } =>
+ Boolean(p.place),
+ );
return (
<li key={first.order} className="text-sm text-[var(--color-text-secondary)]">
<span className="tabular-nums text-[var(--color-text-tertiary)]">{index + 1}.</span>{" "}
@@ -256,14 +265,18 @@ function PlanSteps({ steps }: { steps: PerformanceOpportunityPlanStep[] }) {
<span className="ml-1.5 text-xs text-[var(--color-text-tertiary)]">mechanical</span>
) : null}
{places.length === 1 ? (
- <span className="ml-1.5 break-all font-mono text-xs text-[var(--color-text-tertiary)]">
- {places[0]}
- </span>
+ <>
+ <span className="ml-1.5 break-all font-mono text-xs text-[var(--color-text-tertiary)]">
+ {places[0]!.place}
+ </span>
+ <StepCheck verify={places[0]!.verify} />
+ </>
) : places.length > 1 ? (
<ul className="mt-1 space-y-0.5 pl-5">
{places.map((p) => (
- <li key={p} className="break-all font-mono text-xs text-[var(--color-text-tertiary)]">
- {p}
+ <li key={p.place} className="break-all font-mono text-xs text-[var(--color-text-tertiary)]">
+ {p.place}
+ <StepCheck verify={p.verify} />
</li>
))}
</ul>
@@ -275,6 +288,28 @@ function PlanSteps({ steps }: { steps: PerformanceOpportunityPlanStep[] }) {
);
}
+/**
+ * How to check one step, when it differs from the plan: the server omits
+ * `verify` on a step the plan's validation already checks.
+ */
+function StepCheck({ verify }: { verify: StepVerify | undefined }) {
+ if (!verify) return null;
+ if (verify.coverage === "none") {
+ return (
+ <p className="mt-1 font-sans text-xs text-[var(--color-text-tertiary)]">
+ No test reaches this step.
+ </p>
+ );
+ }
+ return (
+ <>
+ {verify.commands.map((command) => (
+ <CommandLine key={command} command={command} />
+ ))}
+ </>
+ );
+}
+
function PlanSection({
opportunity,
adapter,
diff --git a/packages/ui/src/shared/command-line.tsx b/packages/ui/src/shared/command-line.tsx
new file mode 100644
index 000000000..bad3fdd26
--- /dev/null
+++ b/packages/ui/src/shared/command-line.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import { useState } from "react";
+import { Check, Copy } from "lucide-react";
+
+/** A shell command with a copy button; when the clipboard is blocked it stays selectable. */
+export function CommandLine({ command }: { command: string }) {
+ const [copied, setCopied] = useState(false);
+ const copy = async () => {
+ try {
+ await navigator.clipboard.writeText(command);
+ setCopied(true);
+ window.setTimeout(() => setCopied(false), 1600);
+ } catch {
+ /* clipboard blocked: the command stays selectable */
+ }
+ };
+ return (
+ <div className="mt-2 flex min-w-0 items-start gap-2 rounded bg-[var(--color-bg-inset)] px-2.5 py-1.5">
+ <code className="min-w-0 flex-1 font-mono text-xs text-[var(--color-text-primary)] [overflow-wrap:anywhere]">
+ {command}
+ </code>
+ <button
+ type="button"
+ onClick={() => void copy()}
+ aria-label={copied ? "Copied" : "Copy command"}
+ className="inline-flex shrink-0 items-center gap-1 rounded text-xs text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent-primary)]"
+ >
+ {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+ <span aria-hidden>{copied ? "Copied" : "Copy"}</span>
+ </button>
+ </div>
+ );
+}
diff --git a/tests/unit/health/test_recommendations.py b/tests/unit/health/test_recommendations.py
index 9c7cfa7eb..341b12333 100644
--- a/tests/unit/health/test_recommendations.py
+++ b/tests/unit/health/test_recommendations.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import json
from types import SimpleNamespace
from sqlalchemy import event
@@ -19,7 +20,10 @@ from repowise.core.analysis.health.refactoring.recommendations import (
hub_files,
hydrate_recommendations,
rehydrate_suggestion,
+ steps_with_verify,
+ stored_recommendation,
target_symbol_ids,
+ with_step_verify,
)
from repowise.core.analysis.test_reachability import ReachDistance, ReachedBy, clear_test_map_cache
from repowise.core.persistence.crud import save_test_coverage
@@ -697,3 +701,190 @@ def test_hubs_are_files_above_the_fan_in_bar_or_in_the_top_percent() -> None:
assert hub_files(fan_in, {"tests/test_a.py"}) == {"src/top.py", "src/wide.py", "src/second.py"}
small = {"src/a.py": 4, "src/b.py": 1}
assert hub_files(small, set()) == frozenset()
+
+
+def _stepped_plan(*sites: tuple[str, int]) -> RefactoringSuggestion:
+ """A ``performance_fix`` with one step per call site, as the detector writes it."""
+ plan = _multi_site_plan()
+ plan.plan = {
+ "affected_locations": [
+ {"file_path": path, "line_start": line, "line_end": line} for path, line in sites
+ ],
+ "steps": [
+ {"order": index, "action": "Batch", "symbol": "load", "file_path": path, "line": line}
+ for index, (path, line) in enumerate(sites, 1)
+ ],
+ }
+ return plan
+
+
+_FIRST = "tests/test_orders.py::test_first"
+_MIDDLE = "tests/test_orders.py::test_middle"
+_SITE_COVERAGE = {
+ "svc/orders.py": [
+ {"test_id": _FIRST, "covered_lines": [10]},
+ {"test_id": _MIDDLE, "covered_lines": [40]},
+ ]
+}
+_THREE_SITES = (("svc/orders.py", 10), ("svc/orders.py", 40), ("svc/orders.py", 90))
+
+
+def _stepped(
+ suggestion: RefactoringSuggestion,
+ measured: dict | None = None,
+ inferred: dict | None = None,
+ evidence: ValidationEvidence | None = None,
+):
+ measured = _SITE_COVERAGE if measured is None else measured
+ plan = build_validation_plan(suggestion, measured, inferred or {}, evidence=evidence)
+ return with_step_verify(plan, suggestion, measured, inferred or {}, evidence=evidence)
+
+
+def test_each_step_lists_the_tests_that_run_its_own_site() -> None:
+ validation = _stepped(_stepped_plan(*_THREE_SITES))
+ assert validation.tests == [_FIRST, _MIDDLE]
+ first, middle, last = validation.step_verify
+ assert first == {"commands": [f"pytest {_FIRST}"], "tests": [_FIRST], "coverage": "measured"}
+ assert middle is not None and middle["tests"] == [_MIDDLE]
+ # Coverage proves no test runs line 90: no command, not the plan's.
+ assert last == {"commands": [], "tests": [], "coverage": "none"}
+
+
+def test_a_step_in_another_file_takes_that_files_reach() -> None:
+ reached = {
+ "svc/billing.py": ReachedBy(
+ ["tests/test_billing.py"], "call-graph", 1, ("tests/test_billing.py",), {}
+ )
+ }
+ validation = _stepped(
+ _stepped_plan(("svc/orders.py", 10), ("svc/billing.py", 5)), inferred=reached
+ )
+ orders, billing = validation.step_verify
+ assert orders is not None and orders["coverage"] == "measured"
+ assert billing == {
+ "commands": ["pytest tests/test_billing.py"],
+ "tests": ["tests/test_billing.py"],
+ "coverage": "inferred",
+ }
+
+
+def test_a_step_reached_only_through_a_hub_has_no_test_and_no_command() -> None:
+ hub = "svc/hub.py"
+ reached = {
+ hub: ReachedBy(["tests/test_other.py"], "call-graph", 1, ("tests/test_other.py",), {})
+ }
+ evidence = ValidationEvidence(symbols={hub: [(f"{hub}::load", 1, 20)]}, hubs=frozenset({hub}))
+ validation = _stepped(
+ _stepped_plan(("svc/orders.py", 10), (hub, 5)), inferred=reached, evidence=evidence
+ )
+ assert validation.tests == [_FIRST]
+ orders, through_hub = validation.step_verify
+ # The plan's basis is mixed (one file measured, one unknown); this step's is measured.
+ assert orders is not None and orders["coverage"] == "measured"
+ assert through_hub == {"commands": [], "tests": [], "coverage": "none"}
+
+
+def test_a_step_with_the_plans_answer_carries_none() -> None:
+ measured = {"svc/orders.py": [{"test_id": _FIRST, "covered_lines": [10, 40]}]}
+ suggestion = _stepped_plan(("svc/orders.py", 10), ("svc/orders.py", 40))
+ validation = _stepped(suggestion, measured)
+ assert validation.step_verify == []
+ steps = suggestion.plan["steps"]
+ assert steps_with_verify(steps, validation) == steps
+
+
+def test_a_single_step_plan_has_no_step_verify() -> None:
+ suggestion = _stepped_plan(("svc/orders.py", 10))
+ validation = _stepped(suggestion)
+ assert validation.step_verify == []
+ assert steps_with_verify(suggestion.plan["steps"], validation) == suggestion.plan["steps"]
+
+
+def test_validation_alone_builds_no_step_verify() -> None:
+ """Only finalize asks for step checks; a live read or the empty fallback does not."""
+ suggestion = _stepped_plan(*_THREE_SITES)
+ assert build_validation_plan(suggestion, _SITE_COVERAGE, {}).step_verify == []
+ (recommendation,) = build_recommendations([suggestion])
+ assert recommendation.validation.step_verify == []
+
+
+async def test_only_a_hydration_that_asks_validates_steps() -> None:
+ """An unranked store's live read never rebuilds per-step plans."""
+ engine = create_async_engine(
+ "sqlite+aiosqlite:///:memory:",
+ connect_args={"check_same_thread": False},
+ poolclass=StaticPool,
+ )
+ await init_db(engine)
+ factory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+ async with factory() as session:
+ repo = await insert_repo(session)
+ await save_test_coverage(
+ session,
+ repo.id,
+ [
+ TestCoverage(
+ test_id=test,
+ file_path="svc/orders.py",
+ covered_lines=[line],
+ source_format="coverage.py",
+ test_file="tests/test_orders.py",
+ )
+ for test, line in ((_FIRST, 10), (_MIDDLE, 40))
+ ],
+ source_format="coverage.py",
+ )
+ await session.commit()
+ clear_test_map_cache()
+ rows = [_stepped_plan(*_THREE_SITES)]
+ (live,) = await hydrate_recommendations(session, repo.id, rows)
+ (finalized,) = await hydrate_recommendations(session, repo.id, rows, step_verify=True)
+ await engine.dispose()
+ assert live.validation.step_verify == []
+ assert len(finalized.validation.step_verify) == 3
+
+
+def _stored_row(suggestion: RefactoringSuggestion, facts: dict) -> dict:
+ return {
+ "id": "p1",
+ "refactoring_type": "performance_fix",
+ "file_path": suggestion.file_path,
+ "target_symbol": suggestion.target_symbol,
+ "plan_json": json.dumps(suggestion.plan),
+ "rank_json": json.dumps(facts),
+ }
+
+
+def test_step_verify_rides_the_stored_rank_and_lists_do_not_carry_it() -> None:
+ suggestion = _stepped_plan(*_THREE_SITES)
+ validation = _stepped(suggestion)
+ (recommendation,) = build_recommendations([suggestion], validations={0: validation})
+ facts = recommendation.rank_facts()
+ assert facts["step_verify"] == validation.step_verify
+ assert "step_verify" not in recommendation.as_dict()["validation"]
+ assert "verify" not in recommendation.as_dict()["plan"]["steps"][0]
+
+ stored = stored_recommendation(_stored_row(suggestion, facts))
+ assert stored is not None
+ steps = stored.detail_dict()["plan"]["steps"]
+ assert [step["verify"]["tests"] for step in steps] == [[_FIRST], [_MIDDLE], []]
+ assert stored.as_dict()["validation"] == recommendation.as_dict()["validation"]
+
+
+def test_a_stored_row_without_usable_step_verify_serves_no_step_verify() -> None:
+ suggestion = _stepped_plan(*_THREE_SITES)
+ (recommendation,) = build_recommendations([suggestion], validations={0: _stepped(suggestion)})
+ facts = recommendation.rank_facts()
+ first = facts["step_verify"][0]
+ for step_verify in (None, facts["step_verify"][:2], [{"tests": []}, None, None]):
+ stored = stored_recommendation(_stored_row(suggestion, {**facts, "step_verify": step_verify}))
+ assert stored is not None
+ steps = stored.detail_dict()["plan"]["steps"]
+ assert all("verify" not in step for step in steps), step_verify
+ # A malformed entry reads as absent; a well-formed one beside it still serves.
+ stored = stored_recommendation(
+ _stored_row(suggestion, {**facts, "step_verify": [first, {"tests": []}, None]})
+ )
+ assert stored is not None
+ steps = stored.detail_dict()["plan"]["steps"]
+ assert ["verify" in step for step in steps] == [True, False, False]
diff --git a/tests/unit/health/test_step_verify_parity.py b/tests/unit/health/test_step_verify_parity.py
new file mode 100644
index 000000000..b09334433
--- /dev/null
+++ b/tests/unit/health/test_step_verify_parity.py
@@ -0,0 +1,44 @@
+"""The TypeScript step ``verify`` contract still says what the engine emits.
+
+Read as text, like ``tests/unit/doc_drift/test_ts_contract_parity.py``: the
+values are literals and a TypeScript parser is a dependency this suite lacks.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import get_args
+
+from repowise.core.analysis.health.refactoring.recommendations import (
+ ValidationPlan,
+ VerifyCoverage,
+ verify_of,
+)
+
+_TYPES = Path(__file__).resolve().parents[3] / "packages" / "types" / "src"
+
+
+def _source(name: str = "refactoring.ts") -> str:
+ return (_TYPES / name).read_text(encoding="utf-8")
+
+
+def test_the_coverage_union_matches_the_engine() -> None:
+ match = re.search(r"type StepVerifyCoverage\s*=\s*([^;]+);", _source())
+ assert match, "StepVerifyCoverage is not declared in refactoring.ts"
+ assert set(re.findall(r'"([^"]+)"', match.group(1))) == set(get_args(VerifyCoverage))
+
+
+def test_the_verify_fields_match_the_engine() -> None:
+ match = re.search(r"interface StepVerify \{([^}]+)\}", _source())
+ assert match, "StepVerify is not declared in refactoring.ts"
+ fields = set(re.findall(r"^\s*(\w+)\??:", match.group(1), re.MULTILINE))
+ plan = ValidationPlan("unknown", None, 0, [], False, [], [], [])
+ assert fields == set(verify_of(plan))
+
+
+def test_a_performance_plan_step_carries_the_same_verify() -> None:
+ """The drawer reads stored performance steps through this type."""
+ match = re.search(r"interface PerformanceOpportunityPlanStep \{([^}]+)\}", _source("health.ts"))
+ assert match, "PerformanceOpportunityPlanStep is not declared in health.ts"
+ assert re.search(r"^\s*verify\?:\s*StepVerify;", match.group(1), re.MULTILINE)
diff --git a/tests/unit/server/test_refactoring.py b/tests/unit/server/test_refactoring.py
index 75b9092d0..43686b70f 100644
--- a/tests/unit/server/test_refactoring.py
+++ b/tests/unit/server/test_refactoring.py
@@ -400,6 +400,46 @@ async def test_plan_detail_by_id(client: AsyncClient, app) -> None:
assert detail["plan"]["cut_edges"] == [{"from": "pkg/a.py", "to": "pkg/b.py"}]
+async def test_an_unranked_plan_detail_serves_steps_without_verify(
+ client: AsyncClient, app
+) -> None:
+ repo_id = await _seed(client, app)
+ steps = [
+ {"order": 1, "action": "Batch", "symbol": "load", "file_path": "pkg/hub.py", "line": 3},
+ {"order": 2, "action": "Batch", "symbol": "run", "file_path": "pkg/a.py", "line": 7},
+ ]
+ async with app.state.session_factory() as session:
+ await crud.save_refactoring_suggestions(
+ session,
+ repo_id,
+ [
+ {
+ "refactoring_type": "performance_fix",
+ "file_path": "pkg/hub.py",
+ "target_symbol": "pkg/hub.py::load",
+ "plan": {"opportunity_id": "opp-steps", "steps": steps},
+ "evidence": {},
+ "impact_delta": 0.0,
+ "effort_bucket": "M",
+ "blast_radius": {},
+ "confidence": "medium",
+ "source_biomarker": "io_in_loop",
+ }
+ ],
+ )
+ await session.commit()
+ listed = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/targets",
+ params={"refactoring_type": "performance_fix"},
+ )
+ ).json()["plans"]
+ assert listed[0]["plan"]["steps"] == steps
+ # Unranked here, so the read serves the plan-level answer and rebuilds no step.
+ detail = (await client.get(f"/api/repos/{repo_id}/refactoring/{listed[0]['id']}")).json()
+ assert detail["plan"]["steps"] == steps
+
+
async def test_plan_detail_unknown_id_404(client: AsyncClient, app) -> None:
repo_id = await _seed(client, app)
resp = await client.get(f"/api/repos/{repo_id}/refactoring/deadbeef")