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
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.mdindex 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 onlythrough a widely imported hub module are left out. When no test reaches thechange, 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 resultsA **plan** is one detector's output for one target. An **opportunity** is onediff --git a/packages/core/src/repowise/core/analysis/health/refactoring/recommendations.py b/packages/core/src/repowise/core/analysis/health/refactoring/recommendations.pyindex 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 RefactoringSuggestionRecommendationView = 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 nameand directory. A paged surface ranks every row this way, then passes therows 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.pyindex 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 thisit 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.suggestionfacts[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.pyindex 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 rankeddiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.pyindex 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"] = repositorydiff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.pyindex 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.pyindex 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.idpayload["status"] = row.statusresult: dict[str, Any] = {"resolved": True, "plan_id": plan_id, "plan": payload}diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.pyindex 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 jsonfrom types import SimpleNamespacefrom 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_cachefrom 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.pynew file mode 100644index 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.pyindex 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")