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(health): name the opportunity lookup flag found, not resolved (#2812)
Raghav Chamadiyaa828639bb8c9
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex aaee3ae32..020be7f7d 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -1168,7 +1168,9 @@ The opt-in enrichments:`file_path` and span describe where the symbol was.`get_health(opportunity_id="refop...")` returns the full ordered steps, themember plan payloads, the validation profile and structured `next_actions`;- `only=["refactoring_evidence"]` plus `cursor` pages the evidence.+ `only=["refactoring_evidence"]` plus `cursor` pages the evidence. `found`+ says whether the id named a stored opportunity; `status` is its triage+ lifecycle (`open`, `acknowledged`, `resolved`, `false_positive`).- **`refactoring_directive`** rides on a bare `get_health()`: one opportunity,what it addresses, and the exact `opportunity_id` call that opens it. Oneprimary-key read; it never touches the queue. **`refactoring_summary`**@@ -1306,7 +1308,8 @@ Ids are stable within a performance model version and are never translatedacross one, because grouping decides membership and two models disagree aboutit. An id from an older model resolves to `model_state.state: "stale_model"`with `refresh_required`, rather than failing to match and reading as "no plan".-Evidence rows carry the finding's public `finding_id`, which round-trips through+`found` says whether the id named a stored opportunity; `lifecycle_status` is+its lifecycle (`open` or `resolved`). Evidence rows carry the finding's public `finding_id`, which round-trips throughthe `finding_id` selector; storage row ids are republished on every analysis andare never emitted.diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/details.py b/packages/server/src/repowise/server/mcp_server/tool_health/details.pyindex e8961c708..58e405b31 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/details.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/details.py@@ -233,7 +233,7 @@ async def _performance_detail_response(return {"mode": "performance_evidence","opportunity_id": opportunity_id,- "resolved": total > 0,+ "found": total > 0,**evidence_block(rows, total, cursor),"_meta": _build_meta(repository=repository),}@@ -274,7 +274,7 @@ async def _refactoring_detail_response(result = {"mode": "refactoring_evidence","opportunity_id": opportunity_id,- "resolved": bool(detail.get("resolved")),+ "found": bool(detail.get("found")),**block,"_meta": _build_meta(repository=repository),}@@ -297,7 +297,7 @@ async def _refactoring_detail_response(evidence_limit=_REFACTORING_EVIDENCE_CAP,)file_path = detail.get("file_path")- if not detail.get("resolved"):+ if not detail.get("found"):detail.setdefault("model_state", _refactoring_model_state(opportunity_id))diff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.pyindex 81f5e6a2d..b526c4aff 100644--- a/packages/server/src/repowise/server/routers/refactoring.py+++ b/packages/server/src/repowise/server/routers/refactoring.py@@ -482,7 +482,7 @@ async def get_refactoring_opportunity_detail(evidence_limit=evidence_limit,evidence_offset=evidence_offset,)- if not detail.get("resolved"):+ if not detail.get("found"):raise HTTPException(status_code=404, detail="Unknown opportunity id")return detaildiff --git a/packages/server/src/repowise/server/schemas/refactoring.py b/packages/server/src/repowise/server/schemas/refactoring.pyindex 6fe952d21..d113fde1f 100644--- a/packages/server/src/repowise/server/schemas/refactoring.py+++ b/packages/server/src/repowise/server/schemas/refactoring.py@@ -68,7 +68,8 @@ class RefactoringOpportunityDetailResponse(BaseModel):model_config = ConfigDict(extra="allow")- resolved: bool+ #: Whether the id named a stored opportunity. Lifecycle is ``status``.+ found: boolsteps: list[dict[str, Any]] = []steps_total: int = 0steps_emitted: int = 0diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.pyindex 6c7b0b21c..e02ebed82 100644--- a/packages/server/src/repowise/server/services/performance_health.py+++ b/packages/server/src/repowise/server/services/performance_health.py@@ -465,7 +465,7 @@ class PerformanceHealthService:)if row is None:return {- "resolved": False,+ "found": False,"opportunity_id": opportunity_id,"model_state": state,"detail": _unresolved_detail(state),@@ -480,7 +480,7 @@ class PerformanceHealthService:)payload.update({- "resolved": True,+ "found": True,"lifecycle_status": row.status,"analyzed_commit": row.analyzed_commit,"model_state": state,diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.pyindex ae584eddb..77fd54393 100644--- a/packages/server/src/repowise/server/services/refactoring_health.py+++ b/packages/server/src/repowise/server/services/refactoring_health.py@@ -352,13 +352,20 @@ class RefactoringHealthService:evidence_offset: int = 0,with_plans: bool = True,) -> dict[str, Any]:- """One opportunity by id: an indexed seek, then its member plans."""+ """One opportunity by id: an indexed seek, then its member plans.++ ``found`` says whether the id named a stored row; ``status`` is the+ opportunity's triage lifecycle. The lookup flag is not called+ ``resolved`` because ``status`` can itself be ``resolved``, and a+ payload reading ``resolved: true`` beside ``status: "open"`` would+ contradict itself.+ """row = await get_refactoring_opportunity(self._session, self._repository_id, opportunity_id)if row is None:return {- "resolved": False,+ "found": False,"opportunity_id": opportunity_id,"reason": "unknown_opportunity_id",}@@ -366,7 +373,7 @@ class RefactoringHealthService:steps = list(details.get("steps") or [])page = steps[step_offset : step_offset + max(step_limit, 0)]payload = self._serialize(row, steps_limit=None, evidence_limit=0)- payload["resolved"] = True+ payload["found"] = Truepayload["steps"] = pagepayload["steps_total"] = len(steps)payload["steps_emitted"] = len(page)diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 15ece9401..5ce1bb16a 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -2508,7 +2508,7 @@ export interface RefactoringOpportunitiesResponse {* part and anything else passes through rather than being dropped.*/export interface RefactoringOpportunityDetailResponse {- resolved: boolean;+ found: boolean;steps?: Record<string, unknown>[];steps_total?: number;steps_emitted?: number;diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 7bfad3a66..d54dab8ea 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -501,7 +501,7 @@ export interface PerformanceModelState {*/export type PerformanceOpportunityDetail =| ({- resolved: true;+ found: true;lifecycle_status: "open" | "resolved";analyzed_commit: string | null;model_state: PerformanceModelState;@@ -510,7 +510,7 @@ export type PerformanceOpportunityDetail =evidence_next_cursor?: number;} & PerformanceOpportunity)| {- resolved: false;+ found: false;opportunity_id: string;model_state: PerformanceModelState;detail: string;diff --git a/packages/types/src/refactoring.ts b/packages/types/src/refactoring.tsindex 68adfe527..cd0506d15 100644--- a/packages/types/src/refactoring.ts+++ b/packages/types/src/refactoring.ts@@ -248,16 +248,17 @@ export interface RefactoringOpportunity {}/**- * A detail lookup either resolved or did not; the two shapes share nothing but- * the discriminant, so narrow on `resolved` before reading anything else.- * REST 404s on the unresolved branch, MCP returns it verbatim.+ * A detail lookup either found the id or did not; the two shapes share nothing+ * but the discriminant, so narrow on `found` before reading anything else.+ * `found` is the lookup, `status` the triage lifecycle (which can itself be+ * `resolved`). REST 404s on the not-found branch, MCP returns it verbatim.*/export type RefactoringOpportunityDetail =| RefactoringOpportunityDetailResolved| RefactoringOpportunityDetailUnresolved;export interface RefactoringOpportunityDetailUnresolved {- resolved: false;+ found: false;opportunity_id: string;reason: "unknown_opportunity_id";/** MCP only: tells a stale-model id apart from one never minted here. */@@ -272,7 +273,7 @@ export interface RefactoringOpportunityDetailUnresolved {export interface RefactoringOpportunityDetailResolvedextends Omit<RefactoringOpportunity, "steps_total"> {- resolved: true;+ found: true;/*** `unavailable` when the opportunity resolved but its steps could not be* read: `steps` is empty and `steps_total` is null, while the row's owndiff --git a/packages/ui/__tests__/health/fixtures/performance-wire-contract.json b/packages/ui/__tests__/health/fixtures/performance-wire-contract.jsonindex 3c43fc35a..b9da0a026 100644--- a/packages/ui/__tests__/health/fixtures/performance-wire-contract.json+++ b/packages/ui/__tests__/health/fixtures/performance-wire-contract.json@@ -97,15 +97,15 @@],"detail_extra": ["analyzed_commit",+ "found","lifecycle_status",- "model_state",- "resolved"+ "model_state"],"unresolved_detail": ["detail",+ "found","model_state",- "opportunity_id",- "resolved"+ "opportunity_id"],"model_state": ["opportunity_id",diff --git a/packages/ui/__tests__/health/fixtures/performance.ts b/packages/ui/__tests__/health/fixtures/performance.tsindex 0b3c97b75..b5ae42bc5 100644--- a/packages/ui/__tests__/health/fixtures/performance.ts+++ b/packages/ui/__tests__/health/fixtures/performance.ts@@ -200,11 +200,11 @@ export function legacyPage(): PerformanceOpportunityPage {}export function resolvedDetail(- overrides: Partial<Extract<PerformanceOpportunityDetail, { resolved: true }>> = {},+ overrides: Partial<Extract<PerformanceOpportunityDetail, { found: true }>> = {},): PerformanceOpportunityDetail {return {...opportunity({ opportunity_id: "perf2_planready" }),- resolved: true,+ found: true,lifecycle_status: "open",analyzed_commit: "848a8f180abc",model_state: {diff --git a/packages/ui/__tests__/health/performance-contract.test.ts b/packages/ui/__tests__/health/performance-contract.test.tsindex 26b828e94..b14619175 100644--- a/packages/ui/__tests__/health/performance-contract.test.ts+++ b/packages/ui/__tests__/health/performance-contract.test.ts@@ -68,9 +68,9 @@ describe("canonical performance wire contract", () => {for (const field of contract.detail_extra) expect(detail[field]).toBeDefined();expect(contract.unresolved_detail).toEqual(["detail",+ "found","model_state","opportunity_id",- "resolved",]);expect(contract.model_state).toContain("refresh_required");});diff --git a/packages/ui/__tests__/health/performance-view.test.tsx b/packages/ui/__tests__/health/performance-view.test.tsxindex c42e6b88a..c349ecfa7 100644--- a/packages/ui/__tests__/health/performance-view.test.tsx+++ b/packages/ui/__tests__/health/performance-view.test.tsx@@ -287,7 +287,7 @@ describe("PerformanceView drawer", () => {it("tells an unresolvable id apart from a stale one and from an empty index", async () => {const getDetail = vi.fn(async () => ({- resolved: false as const,+ found: false as const,opportunity_id: "perf2_planready",model_state: {state: "unrecognized" as const,@@ -834,7 +834,7 @@ describe("PerformanceView opened by a link", () => {it("says so when the link names a cause this index cannot resolve", async () => {const unresolved = {- resolved: false as const,+ found: false as const,opportunity_id: "perf2_retired",model_state: {state: "stale_model" as const,diff --git a/packages/ui/__tests__/refactoring/opportunity-drawer.test.tsx b/packages/ui/__tests__/refactoring/opportunity-drawer.test.tsxindex 6c81edf5d..178ca97de 100644--- a/packages/ui/__tests__/refactoring/opportunity-drawer.test.tsx+++ b/packages/ui/__tests__/refactoring/opportunity-drawer.test.tsx@@ -16,7 +16,7 @@ function detail(overrides: Partial<RefactoringOpportunityDetailResolved> = {},): RefactoringOpportunityDetailResolved {return {- resolved: true,+ found: true,opportunity_id: "refop2_drawer",refactoring_model_version: 2,status: "open",diff --git a/packages/ui/__tests__/refactoring/opportunity-prompt.test.ts b/packages/ui/__tests__/refactoring/opportunity-prompt.test.tsindex ef458bb7f..c80f2f3ce 100644--- a/packages/ui/__tests__/refactoring/opportunity-prompt.test.ts+++ b/packages/ui/__tests__/refactoring/opportunity-prompt.test.ts@@ -44,7 +44,7 @@ function detail(overrides: Partial<RefactoringOpportunityDetailResolved> = {},): RefactoringOpportunityDetailResolved {return {- resolved: true,+ found: true,opportunity_id: "refop2_abc123",refactoring_model_version: 2,status: "open",diff --git a/packages/ui/src/health/performance-view.tsx b/packages/ui/src/health/performance-view.tsxindex 671c9757c..87ca5180b 100644--- a/packages/ui/src/health/performance-view.tsx+++ b/packages/ui/src/health/performance-view.tsx@@ -155,7 +155,7 @@ export function PerformanceView({// Both branches of the detail carry an id, so the discriminant decides:// an id from a retired model resolves to a state, not to a cause, and// opening a drawer on it would render an empty panel.- if (linked?.resolved) setSelected(linked);+ if (linked?.found) setSelected(linked);}, [linked]);if (!load) return <LegacyPerformanceFindings adapter={adapter} />;@@ -318,10 +318,10 @@ export function PerformanceView({/></section>- {pendingId && (linkError || linked?.resolved === false) ? (+ {pendingId && (linkError || linked?.found === false) ? (<LinkedCauseUnavailableopportunityId={pendingId}- detail={linked && !linked.resolved ? linked.detail : null}+ detail={linked && !linked.found ? linked.detail : null}onDismiss={() => onOpenOpportunityChange?.(null)}/>) : null}diff --git a/packages/ui/src/health/performance/drawer.tsx b/packages/ui/src/health/performance/drawer.tsxindex e5faf3b83..7c91a99a9 100644--- a/packages/ui/src/health/performance/drawer.tsx+++ b/packages/ui/src/health/performance/drawer.tsx@@ -363,8 +363,8 @@ export function OpportunityDrawer({// The row is the fallback body: a host without the detail call still reads// every field the queue carried, and simply learns nothing extra.- const resolved = detail && detail.resolved ? detail : null;- const unresolved = detail && !detail.resolved ? detail : null;+ const resolved = detail && detail.found ? detail : null;+ const unresolved = detail && !detail.found ? detail : null;const current: PerformanceOpportunity | null = resolved ?? opportunity;const plan = useVerifiedPlan(current, adapter, planEnabled);diff --git a/packages/ui/src/refactoring/opportunity-drawer.tsx b/packages/ui/src/refactoring/opportunity-drawer.tsxindex ac84eda91..cdd5caaf4 100644--- a/packages/ui/src/refactoring/opportunity-drawer.tsx+++ b/packages/ui/src/refactoring/opportunity-drawer.tsx@@ -82,7 +82,7 @@ export function OpportunityDrawer({onOpenStep,fileHref,}: OpportunityDrawerProps) {- const resolved = detail?.resolved ? detail : null;+ const resolved = detail?.found ? detail : null;return (<Sheet open={open} onOpenChange={onOpenChange}><SheetContent@@ -108,7 +108,7 @@ export function OpportunityDrawer({<Skeleton className="h-40 rounded-none" /></SkeletonRegion></>- ) : detail && !detail.resolved ? (+ ) : detail && !detail.found ? (<><SheetTitle className="border-b border-[var(--color-border-default)] px-5 py-4 pr-12 text-[15px]">Opportunity unavailablediff --git a/packages/vscode/src/core/webviewApi.ts b/packages/vscode/src/core/webviewApi.tsindex 5f58a726d..f0ff8bcd5 100644--- a/packages/vscode/src/core/webviewApi.ts+++ b/packages/vscode/src/core/webviewApi.ts@@ -313,7 +313,7 @@ export function createHostApi(ctx: RepowiseContext, epoch: () => number): HostApconst detail = await cached(`refactor:opp:${opportunityId}`, (id) =>getRefactoringOpportunity(id, opportunityId, { stepLimit: 50, evidenceLimit: 20 }),);- if (!detail.resolved) {+ if (!detail.found) {throw new Error(`No refactoring opportunity resolves for ${opportunityId}.`);}const repoName = ctx.repo?.name;diff --git a/packages/vscode/webview/src/views/refactoring/App.tsx b/packages/vscode/webview/src/views/refactoring/App.tsxindex 90c137271..ef9fb2888 100644--- a/packages/vscode/webview/src/views/refactoring/App.tsx+++ b/packages/vscode/webview/src/views/refactoring/App.tsx@@ -104,7 +104,7 @@ function OpportunityDetailView({return <ErrorNote title="Could not load the opportunity.">{state.message}</ErrorNote>;}const detail = state.data;- if (!detail.resolved) {+ if (!detail.found) {return (<ErrorNote title="Opportunity unavailable.">{detail.model_state?.state === "stale_model"diff --git a/packages/web/src/app/repos/[id]/refactoring/page.tsx b/packages/web/src/app/repos/[id]/refactoring/page.tsxindex 1f2f3d702..a8f6baa3f 100644--- a/packages/web/src/app/repos/[id]/refactoring/page.tsx+++ b/packages/web/src/app/repos/[id]/refactoring/page.tsx@@ -168,7 +168,7 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stristepLimit: 50,evidenceLimit: 20,});- if (detail.resolved) setPromptFor({ kind: "opportunity", value: detail });+ if (detail.found) setPromptFor({ kind: "opportunity", value: detail });},[repoId],);diff --git a/tests/unit/server/mcp/test_performance_levels.py b/tests/unit/server/mcp/test_performance_levels.pyindex 9ad2b5023..efb008274 100644--- a/tests/unit/server/mcp/test_performance_levels.py+++ b/tests/unit/server/mcp/test_performance_levels.py@@ -287,7 +287,9 @@ async def test_one_id_returns_the_cause_its_plan_and_its_rank_rationale(result = await get_health(opportunity_id=lead)assert result["mode"] == "performance_opportunity"- assert result["resolved"] is True+ assert result["found"] is True+ # The lookup flag never shares a name with the lifecycle beside it.+ assert "resolved" not in resultassert result["opportunity_id"] == leadassert result["intervention_symbol"] == "src/shared.py::load"assert result["plan_status"] == "available"@@ -396,7 +398,7 @@ async def test_an_id_from_an_older_model_reports_stale_and_how_to_refresh(from repowise.server.mcp_server import get_healthresult = await get_health(opportunity_id="perf_0123456789abcdef0123")- assert result["resolved"] is False+ assert result["found"] is Falseassert result["model_state"]["state"] == "stale_model"assert result["model_state"]["refresh_required"] is Trueassert "repowise update" in result["detail"]diff --git a/tests/unit/server/test_open_payload_models.py b/tests/unit/server/test_open_payload_models.pyindex 66976a659..b1f1d681a 100644--- a/tests/unit/server/test_open_payload_models.py+++ b/tests/unit/server/test_open_payload_models.py@@ -18,7 +18,7 @@ from repowise.server.schemas import (def test_opportunity_detail_carries_keys_it_never_declared() -> None:payload = {- "resolved": True,+ "found": True,"steps": [{"plan_id": "p1"}],"steps_total": 1,"steps_emitted": 1,diff --git a/tests/unit/server/test_performance_opportunities.py b/tests/unit/server/test_performance_opportunities.pyindex 436b03d76..a5429ba30 100644--- a/tests/unit/server/test_performance_opportunities.py+++ b/tests/unit/server/test_performance_opportunities.py@@ -311,7 +311,7 @@ async def test_an_id_from_an_older_model_reports_stale_rather_than_no_plan(f"/api/repos/{repo_id}/health/performance-opportunities/perf_0123456789abcdef0123")).json()- assert body["resolved"] is False+ assert body["found"] is Falseassert body["model_state"]["state"] == "stale_model"assert body["model_state"]["refresh_required"] is Trueassert "repowise update" in body["detail"]@@ -327,7 +327,7 @@ async def test_detail_carries_the_facets_and_evidence_for_one_cause(params={"evidence_limit": 1},)).json()- assert body["resolved"] is True+ assert body["found"] is Trueassert body["lifecycle_status"] == "open"assert body["analyzed_commit"] == "a" * 40assert body["model_state"]["state"] == "current"@@ -359,7 +359,7 @@ async def test_a_cause_that_stops_being_observed_is_resolved_not_deleted(f"/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}")).json()- assert detail["resolved"] is True+ assert detail["found"] is Trueassert detail["lifecycle_status"] == "resolved"diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.pyindex 7b27b3f15..d9bbb6956 100644--- a/tests/unit/server/test_refactoring_opportunities.py+++ b/tests/unit/server/test_refactoring_opportunities.py@@ -385,7 +385,11 @@ async def test_bare_get_health_carries_one_bounded_refactoring_directive(client,# And the id it names resolves in one call.detail = await get_health(opportunity_id=directive["opportunity_id"])- assert detail["resolved"] is True+ assert detail["found"] is True+ # The lookup flag never shares a name with the lifecycle it sits beside:+ # ``resolved: true`` next to ``status: "open"`` read as a contradiction.+ assert "resolved" not in detail+ assert detail["status"] == "open"assert detail["mode"] == "refactoring_opportunity"assert detail["steps"]del repo_id@@ -508,7 +512,7 @@ async def test_an_unknown_opportunity_id_says_which_kind_of_unknown(client, app)await _seed(client, app, files=2)get_health = await _mcp(app)missing = await get_health(opportunity_id="refop2_" + "0" * 20)- assert missing["resolved"] is False+ assert missing["found"] is Falseassert missing["model_state"]["state"] == "current"stale = await get_health(opportunity_id="refop1_" + "0" * 20)assert stale["model_state"]["state"] == "stale_model"