Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(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.md
index 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, the
member 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. One
primary-key read; it never touches the queue. **`refactoring_summary`**
@@ -1306,7 +1308,8 @@ Ids are stable within a performance model version and are never translated
across one, because grouping decides membership and two models disagree about
it. 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 through
the `finding_id` selector; storage row ids are republished on every analysis and
are 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.py
index 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.py
index 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 detail
diff --git a/packages/server/src/repowise/server/schemas/refactoring.py b/packages/server/src/repowise/server/schemas/refactoring.py
index 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: bool
steps: list[dict[str, Any]] = []
steps_total: int = 0
steps_emitted: int = 0
diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.py
index 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.py
index 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"] = True
payload["steps"] = page
payload["steps_total"] = len(steps)
payload["steps_emitted"] = len(page)
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 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.ts
index 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.ts
index 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 RefactoringOpportunityDetailResolved
extends 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 own
diff --git a/packages/ui/__tests__/health/fixtures/performance-wire-contract.json b/packages/ui/__tests__/health/fixtures/performance-wire-contract.json
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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) ? (
<LinkedCauseUnavailable
opportunityId={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.tsx
index 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.tsx
index 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 unavailable
diff --git a/packages/vscode/src/core/webviewApi.ts b/packages/vscode/src/core/webviewApi.ts
index 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): HostAp
const 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.tsx
index 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.tsx
index 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: stri
stepLimit: 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.py
index 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 result
assert result["opportunity_id"] == lead
assert 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_health
result = await get_health(opportunity_id="perf_0123456789abcdef0123")
- assert result["resolved"] is False
+ assert result["found"] is False
assert result["model_state"]["state"] == "stale_model"
assert result["model_state"]["refresh_required"] is True
assert "repowise update" in result["detail"]
diff --git a/tests/unit/server/test_open_payload_models.py b/tests/unit/server/test_open_payload_models.py
index 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.py
index 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 False
assert body["model_state"]["state"] == "stale_model"
assert body["model_state"]["refresh_required"] is True
assert "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 True
assert body["lifecycle_status"] == "open"
assert body["analyzed_commit"] == "a" * 40
assert 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 True
assert detail["lifecycle_status"] == "resolved"
diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.py
index 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 False
assert missing["model_state"]["state"] == "current"
stale = await get_health(opportunity_id="refop1_" + "0" * 20)
assert stale["model_state"]["state"] == "stale_model"