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): serve composed opportunities from a materialized read model (#1992)

Raghav Chamadiya01289585356a
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 82ab6e46c..167c88f69 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -719,6 +719,8 @@ get_health(include=["trend"], only=["trend"])
get_health(include=["accuracy"], only=["accuracy"])
get_health(include=["coverage"], only=["coverage"])
get_health(include=["performance","refactoring"], only=["performance_opportunities","refactoring_plans"])
+get_health(include=["refactoring"], only=["refactoring_opportunities"], limit=6)
+get_health(opportunity_id="refop2_...")
```
**Parameters:**
@@ -727,12 +729,18 @@ get_health(include=["performance","refactoring"], only=["performance_opportuniti
|-----------|------|----------|-------------|
| `targets` | list[string] | No | File paths, or `module:foo` to expand a module's file set. Empty means dashboard mode. |
| `include` | list[string] | No | Opt-in blocks (default response stays lean): `"biomarkers"` (findings in dashboard mode), `"refactoring"` (structured, graph-aware refactoring plans; see below), `"trend"` (snapshot diff + declining / predicted-decline alerts), `"coverage"`, `"accuracy"` (the "does the score find the bugs?" stat, dashboard mode), `"signals"` (per-file process / people / topology signals, targeted mode), `"churn_complexity"` (churn x complexity quadrant points, dashboard mode), and a dimension name (`"performance"` / `"defect"` / `"maintainability"`) to filter findings to that pillar. |
-| `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode`, `_meta`, `unresolved`, `known_modules` and each kept list's `*_total` sibling always survive. The three `include` **block** names work as aliases: `biomarkers`→`findings`, `accuracy`→`defect_accuracy`, `refactoring`→`refactoring_plans`. The `include` **dimension** names (`performance`, `defect`, `maintainability`) do not — they filter rows inside several blocks and have no single key to resolve to, so they land in `unknown_only_keys`. Nor does `signals`, which merges into `metrics[].signals` — in targeted mode, where `signals` applies, name `metrics` instead. |
+| `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode`, `_meta`, `unresolved`, `known_modules` and each kept list's `*_total` sibling always survive. The three `include` **block** names work as aliases: `biomarkers`→`findings`, `accuracy`→`defect_accuracy`, `refactoring`→`refactoring_plans`. Note that `refactoring_plans` is the raw
+per-detector list and is now **opt-in**: `include=["refactoring"]` leads with
+`refactoring_opportunities`, the composed unit, and emitting both would ship two
+representations of the same work in one response. The `include` **dimension** names (`performance`, `defect`, `maintainability`) do not — they filter rows inside several blocks and have no single key to resolve to, so they land in `unknown_only_keys`. Nor does `signals`, which merges into `metrics[].signals` — in targeted mode, where `signals` applies, name `metrics` instead. |
| `repo` | string | No | *(workspace only)* Target repo alias |
| `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50). `0` means no rows; the `*_total` siblings still report the true counts. |
| `finding_id` | string | No | Resolve an emitted stable health-finding `id` directly in one call. |
| `plan_id` | string | No | Resolve an emitted stable refactoring-plan `id` directly in one call. |
-| `opportunity_id` | string | No | Resolve a performance opportunity `id` directly. Mutually exclusive with the two above; passing more than one returns `mode: "conflict"` naming them rather than answering about whichever was checked first. |
+| `opportunity_id` | string | No | Resolve one opportunity `id` directly. The prefix picks the pillar: `perf...` is a performance cause, `refop...` a composed refactoring. Mutually exclusive with the two above; passing more than one returns `mode: "conflict"` naming them rather than answering about whichever was checked first. |
+| `refactoring_type` / `refactoring_confidence` / `refactoring_effort` | string | No | Queue filters over the same read model and vocabulary the REST route uses. An unrecognized value is reported back in `ignored_arguments` rather than silently narrowing to nothing. |
+| `refactoring_view` | string | No | Named ordering for `refactoring_opportunities`. `diversified` (default) round-robins the rank order over cause, refactoring type and area, because the ranked head is a genuine run of ties; `canonical` is the published rank order verbatim, ties and all; `file_spread` asked for one row per file, which a composed opportunity satisfies by construction, so it resolves onto the diversified order. Both older values keep working. It also selects the legacy `refactoring_plans` list's view, where `diversified` resolves to that list's historical `canonical` default. |
+| `cursor` | int | No | Zero-based offset into a ranked collection; the `recovery` block names the exact next call. |
| `performance_view` | string | No | `detail` (default) or `summary`. `summary` keeps identity, counts and plan state and drops the explanatory fields. |
| `performance_context` | string | No | `production` / `tooling` / `test` / `unknown` / `all`. |
| `performance_boundary` | string | No | `db` / `network` / `filesystem` / `subprocess` / `lock` / `none`. |
@@ -866,7 +874,26 @@ The opt-in enrichments:
- **`churn_complexity`** returns `churn_complexity` points (one per recently-changed
file: 90-day commit count, max CCN, NLOC, score, churn percentile): the
refactor zone where volatility and tangle collide.
-- **`refactoring`** returns ranked, structured refactoring plans (not template
+- **`refactoring`** returns `refactoring_opportunities`: one composed unit per
+ file, carrying the diagnosis it leads with (`lead_biomarker`), whether it
+ actually addresses that diagnosis (`addresses_primary_problem`, tri-state -
+ `null` means no dominant finding was recorded, which is not `false`), its
+ ordered `steps` with a `mechanical` / `judgment` `applicability` each, and
+ counts for the evidence behind it. Ordered by `refactoring_view`. A step
+ carrying `relocated_by` names an earlier step that moves its symbol to another
+ file: locate the symbol again before applying it, because the step's own
+ `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.
+- **`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`**
+ (`only=["refactoring_summary"]`) is the rollup by type, effort, confidence,
+ lifecycle and mechanical-vs-judgment, with facets.
+- **`refactoring_plans`** is the raw per-detector list, unchanged and still
+ addressable by `plan_id`, but **opt-in**: name it in `only` to get it. It
+ returns ranked, structured refactoring plans (not template
strings): `extract_class` (the cohesion `groups` to split into), `extract_helper`
(clone `occurrences` + `suggested_site`), `move_method` (`{method, from_class,
to_class}`), and `break_cycle` (the import `cut_edges`). Each plan carries its
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.md
index e0fdb486c..f1b2ca613 100644
--- a/docs/layers/REFACTORING.md
+++ b/docs/layers/REFACTORING.md
@@ -95,6 +95,55 @@ detector-native benefit even with zero health impact. Ties break deterministical
> works **across files** (class splits, method moves, cycle breaks), and feeds the
> co-change + graph context straight into the plan.
+## Opportunities: the unit a surface serves
+
+A **plan** is one detector output. An **opportunity** is one file's composed
+refactoring: the diagnosis it leads with, its plans ordered so that applying
+them in sequence is safe, and the clone groups that support the diagnosis
+without instructing a change. The plan stays the addressable atom; a step names
+one by `plan_id`.
+
+Composition is deterministic and pure
+(`analysis/health/refactoring/opportunity.py`), and it runs at **index time**:
+the finalizer writes `refactoring_opportunities` and a one-row
+`refactoring_summaries` headline in the same transaction that reconciles the
+plans. Folding at read time was measured at 91 ms over 2,283 plans and 787 ms
+at ten times that, plus 1,118 ms to rebuild the validation profiles, so every
+page cost the whole repository.
+
+| Field | Meaning |
+|---|---|
+| `opportunity_id` | `refop<model>_<digest>` over the member plan ids. Evidence is deliberately outside the kernel: a clone appearing or vanishing must not rename work an agent holds an id for. |
+| `lead_biomarker` | The file's dominant finding, from the one owner of that rule (`analysis/health/models.py::primary_finding`). |
+| `addresses_primary_problem` | Tri-state. `null` means no dominant finding was recorded, which is not the same claim as `false`. On the dogfood index it reads 201 true / 380 false / 3 unknown, and the false answers are the honest ones. |
+| `steps[].applicability` | `mechanical` or `judgment`, with the reasons and the facts behind it, and the facts it could not establish under `unknowns`. Extraction is the only mechanical class. |
+| `steps[].relocated_by` | An earlier step that moves this step's symbol to another file. The step's own `file_path` and span describe where the symbol *was*: locate it again before applying. Any surface that renders an ordered step list must say so. |
+| `status` | Rolled up from the member plans' triage. Resolved only when every step is; one step marked a false positive does not resolve the rest. An `acknowledged` step is still outstanding work, so it keeps composing. |
+| `steps[].finding_ids` | The findings this step's cause produced, so a step round-trips to its diagnosis through `get_health(finding_id=...)`. The key is **omitted entirely** when no finding on the file is addressable by id (a store written before findings carried public ids); an empty list means "none for this cause", which is a different answer. `lead_finding_ids` on the opportunity follows the same rule. |
+| `steps[].validation_profile_id` | Points into the opportunity's `validation_profiles`. Resolved once at index time; the test-reachability walk behind it is never repeated per request. |
+
+`performance_fix` plans are excluded by construction: the performance layer
+composes, ranks and owns the lifecycle of its own opportunities.
+
+### Ordering, and `refactoring_view`
+
+The ranked head is honestly flat. On the dogfood index eight of the top ten
+score identically: single high-confidence extractions recovering the same
+quantised `complex_method` deduction, separated only by file path. They really
+are equal under the published factors, so the answer is a queue that spends its
+first rows on distinct problems rather than a tiebreaker invented to hide the
+tie.
+
+| `refactoring_view` | Order |
+|---|---|
+| `diversified` *(default)* | Rank order round-robined over (lead biomarker, lead refactoring type, containing area). Falls back to plain rank order when a repository has one cause in one area. |
+| `canonical` | The published rank order verbatim, ties and all. What the old default produced. |
+| `file_spread` | Asked for one row per file. An opportunity *is* one file's work, so the spread is satisfied by construction; the value resolves onto the diversified order, which is what it was reaching for. |
+
+Both older values keep working. The same parameter also selects the legacy
+`refactoring_plans` list's view, where `diversified` resolves to that list's
+historical `canonical` default.
+
## Surfaces
```bash
@@ -102,19 +151,36 @@ repowise health --refactoring-targets # ranked table
```
```python
-# MCP: the same structured plans, ranked
-get_health(include=["refactoring"])
-get_health(targets=["src/api/server.py"]) # one file
-get_health(targets=["module:src.api"]) # one module
+# MCP. A bare call already carries one bounded refactoring_directive.
+get_health()
+get_health(include=["refactoring"], only=["refactoring_opportunities"], limit=6)
+get_health(include=["refactoring"], only=["refactoring_summary"])
+get_health(opportunity_id="refop2_...") # steps, plans, validation
+get_health(opportunity_id="refop2_...", only=["refactoring_evidence"], cursor=3)
+get_health(plan_id="refac2_...") # one plan, and its owner
+get_health(include=["refactoring"], only=["refactoring_plans"]) # the raw list, opt-in
+get_health(targets=["src/api/server.py"]) # one file
```
```text
-# REST: what the web tab reads
+# REST. Both surfaces read services/refactoring_health.py, so they cannot
+# answer differently; a parity suite asserts order, filters, totals and detail.
+GET /api/repos/{repo_id}/refactoring/opportunities?view=diversified&limit=20
+GET /api/repos/{repo_id}/refactoring/opportunities?file_path=src/api/server.py
+GET /api/repos/{repo_id}/refactoring/opportunities/{opportunity_id}
+GET /api/repos/{repo_id}/refactoring/summary
GET /api/repos/{repo_id}/refactoring/targets?refactoring_type=extract_class&min_confidence=high
GET /api/repos/{repo_id}/refactoring/targets/page?limit=60&offset=0&refactoring_type=performance_fix
GET /api/repos/{repo_id}/refactoring/{suggestion_id} # one plan + blast-radius detail
```
+A file's opportunities are a **separate call** - the queue filtered by
+`file_path` - and deliberately not a field on the file-detail aggregate. That
+aggregate is already the widest read in the server and every one of its callers
+would pay for this whether or not it renders it, while the surface that wants
+it knows it wants it. R2's `(repository_id, status, file_path)` index makes it
+one indexed lookup rather than a scan.
+
The web **Refactoring** page uses one shared plan board and drawer for every
type, including a Performance filter. Its initial data path is bounded and
server-owned: search, type, confidence, effort, canonical sorting, true totals,
diff --git a/packages/core/alembic/versions/0059_refactoring_opportunities.py b/packages/core/alembic/versions/0059_refactoring_opportunities.py
new file mode 100644
index 000000000..0d8401c9e
--- /dev/null
+++ b/packages/core/alembic/versions/0059_refactoring_opportunities.py
@@ -0,0 +1,121 @@
+"""Materialize composed refactoring opportunities and the repository headline.
+
+Composition folds a file's plans into one ordered opportunity, and the
+validation profile behind each step costs a test-reachability walk. Both ran
+per request over every open plan, so a page of twenty cost the repository:
+measured on the dogfood index, folding 2,283 plans is 91 ms (787 ms at ten
+times the rows) and hydrating their validation is 1,118 ms.
+
+This adds the read model the serving layer pages: one row per opportunity with
+the filter, order and identity columns a query needs, and one summary row per
+repository for the bare-dashboard directive. Both are derived state, rebuilt by
+the finalizer on every analysis, so an existing store upgrades empty and
+repopulates on its next run.
+
+Revision ID: 0059
+Revises: 0058
+Create Date: 2026-08-29
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0059"
+down_revision: str | None = "0058"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_OPPORTUNITY_INDEXES = (
+ ("ix_refactoring_opportunities_repo_id", ["repository_id", "opportunity_id"]),
+ (
+ "ix_refactoring_opportunities_repo_status_queue",
+ ["repository_id", "status", "queue_position"],
+ ),
+ (
+ "ix_refactoring_opportunities_repo_status_rank",
+ ["repository_id", "status", "rank_position"],
+ ),
+ (
+ "ix_refactoring_opportunities_repo_status_type_rank",
+ ["repository_id", "status", "lead_refactoring_type", "rank_position"],
+ ),
+ (
+ "ix_refactoring_opportunities_repo_status_path",
+ ["repository_id", "status", "file_path"],
+ ),
+)
+
+
+def upgrade() -> None:
+ op.create_table(
+ "refactoring_opportunities",
+ sa.Column("id", sa.String(32), primary_key=True),
+ sa.Column(
+ "repository_id",
+ sa.String(32),
+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),
+ nullable=False,
+ ),
+ sa.Column("opportunity_id", sa.String(64), nullable=False),
+ sa.Column(
+ "refactoring_model_version", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("status", sa.String(32), nullable=False, server_default="open"),
+ sa.Column("rank_position", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("queue_position", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("rank_score", sa.Float(), nullable=False, server_default="0"),
+ sa.Column("file_path", sa.Text(), nullable=False, server_default=""),
+ sa.Column("lead_biomarker", sa.String(64), nullable=True),
+ sa.Column("lead_refactoring_type", sa.String(32), nullable=False, server_default=""),
+ # Nullable on purpose: "no lead to compare against" is a different
+ # answer from "does not address the lead", and the surface says so.
+ sa.Column("addresses_primary_problem", sa.Boolean(), nullable=True),
+ sa.Column("effort_bucket", sa.String(4), nullable=False, server_default="M"),
+ sa.Column("confidence", sa.String(16), nullable=False, server_default="medium"),
+ sa.Column("step_count", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("mechanical_steps", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("judgment_steps", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("evidence_total", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("affected_files_total", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("recoverable_health", sa.Float(), nullable=False, server_default="0"),
+ sa.Column("details_json", sa.Text(), nullable=False, server_default="{}"),
+ sa.Column("analyzed_commit", sa.String(40), nullable=True),
+ sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+ sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+ sa.UniqueConstraint(
+ "repository_id",
+ "refactoring_model_version",
+ "opportunity_id",
+ name="uq_refactoring_opportunities_repo_model_id",
+ ),
+ )
+ for name, columns in _OPPORTUNITY_INDEXES:
+ op.create_index(name, "refactoring_opportunities", columns, if_not_exists=True)
+
+ op.create_table(
+ "refactoring_summaries",
+ sa.Column(
+ "repository_id",
+ sa.String(32),
+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),
+ primary_key=True,
+ ),
+ sa.Column(
+ "refactoring_model_version", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("opportunities_total", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("summary_json", sa.Text(), nullable=False, server_default="{}"),
+ sa.Column("analyzed_commit", sa.String(40), nullable=True),
+ sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+ )
+
+
+def downgrade() -> None:
+ op.drop_table("refactoring_summaries")
+ for name, _columns in _OPPORTUNITY_INDEXES:
+ op.drop_index(name, table_name="refactoring_opportunities", if_exists=True)
+ op.drop_table("refactoring_opportunities")
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
index 59bd86a3d..e80924db0 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
@@ -76,6 +76,13 @@ from .refactoring import (
update_refactoring_suggestion_status,
upsert_refactoring_suggestions,
)
+from .refactoring_opportunities import (
+ finalize_refactoring_opportunities,
+ get_refactoring_opportunity,
+ get_refactoring_summary,
+ list_refactoring_opportunities,
+ refactoring_facet_counts,
+)
__all__ = [
"FILE_TREND_SNAPSHOT_WINDOW",
@@ -87,6 +94,7 @@ __all__ = [
"covered_source_files",
"files_covered_by",
"finalize_performance_opportunities",
+ "finalize_refactoring_opportunities",
"finalize_refactoring_suggestions",
"get_average_health",
"get_coverage_summary",
@@ -104,17 +112,21 @@ __all__ = [
"get_performance_opportunity",
"get_performance_plan_rows",
"get_performance_summary",
+ "get_refactoring_opportunity",
"get_refactoring_suggestion",
"get_refactoring_suggestions",
+ "get_refactoring_summary",
"get_test_coverage_summary",
"list_evidence_for_opportunities",
"list_health_snapshots",
"list_opportunity_evidence",
"list_performance_opportunities",
+ "list_refactoring_opportunities",
"load_coverage_for_repo",
"opportunity_details",
"performance_facet_counts",
"performance_file_rollups",
+ "refactoring_facet_counts",
"replace_dead_code_findings",
"replace_governance_findings",
"save_coverage_files",
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
new file mode 100644
index 000000000..514cc7898
--- /dev/null
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
@@ -0,0 +1,612 @@
+"""Materialized refactoring opportunities: one writer, indexed readers.
+
+Composition and validation run once per health persistence transaction over the
+authoritative stored plans, and everything that serves the queue reads the
+result. Measured on the dogfood index before this existed: folding 2,283 plans
+cost 91 ms per request (787 ms at ten times the rows) and hydrating their
+validation profiles another 1,118 ms, so a page of twenty cost the repository.
+
+The writer is the only place that decides lifecycle, and it decides it by
+rolling up the member plans' triage rather than holding an opinion of its own -
+an opportunity is exactly as resolved as the work it names. An opportunity
+nobody composes this run is resolved rather than deleted, so a held id keeps
+answering and stops reading as current.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...models import (
+ HealthFinding,
+ RefactoringOpportunity,
+ RefactoringSuggestion,
+ RefactoringSummary,
+ _new_uuid,
+ _now_utc,
+)
+
+if TYPE_CHECKING:
+ from ....analysis.health.refactoring.opportunity import (
+ RefactoringOpportunity as OpportunityModel,
+ )
+
+_PERF_TYPE = "performance_fix"
+
+# Plan states an opportunity is still composed from. ``resolved`` and
+# ``false_positive`` are the two that stop describing work.
+_LIVE_PLAN_STATUSES = frozenset({"open", "acknowledged"})
+
+# Orders the queue can be read in. Every one ends in a unique column so the
+# total order is deterministic and a deep offset cannot repeat or skip a row.
+_ORDERS: dict[str, tuple[Any, ...]] = {
+ "queue": (RefactoringOpportunity.queue_position.asc(),),
+ "rank": (RefactoringOpportunity.rank_position.asc(),),
+ "health": (
+ RefactoringOpportunity.recoverable_health.desc(),
+ RefactoringOpportunity.rank_position.asc(),
+ ),
+ "effort": (
+ RefactoringOpportunity.step_count.asc(),
+ RefactoringOpportunity.rank_position.asc(),
+ ),
+ "file": (
+ RefactoringOpportunity.file_path.asc(),
+ RefactoringOpportunity.rank_position.asc(),
+ ),
+}
+
+DEFAULT_ORDER = "queue"
+
+
+# ---------------------------------------------------------------------------
+# Writer
+# ---------------------------------------------------------------------------
+
+
+def _diversified_order(opportunities: list[OpportunityModel]) -> list[int]:
+ """Rank positions reordered so the head is not one cause in one directory.
+
+ The ranked head is honestly flat: on the dogfood index eight of the top ten
+ score identically, single high-confidence extractions recovering the same
+ quantised deduction, separated only by file path. They are equal under the
+ published factors, so the fix is not a tiebreaker invented to hide the tie -
+ it is showing a queue that spends its first rows on distinct problems.
+
+ Round-robins over (lead biomarker, lead refactoring type, area), groups
+ ordered by their best member, members within a group in rank order.
+
+ The area is the containing directory capped at two segments, never the file
+ itself: the flat head is eight *different* files, so any key that varies per
+ file gives each row its own group and reproduces rank order exactly. What
+ actually repeats is the cause, the kind of work and the part of the tree.
+
+ Deterministic, and a repository with one cause in one area degrades to
+ plain rank order rather than inventing a difference.
+ """
+ groups: dict[tuple[str, str, str], list[int]] = {}
+ for position, item in enumerate(opportunities):
+ parent = item.file_path.rsplit("/", 1)[0] if "/" in item.file_path else ""
+ area = "/".join(parent.split("/")[:2])
+ groups.setdefault(
+ (item.lead_biomarker or "", item.lead_refactoring_type, area), []
+ ).append(position)
+ ordered_groups = sorted(groups.values(), key=lambda members: members[0])
+ order: list[int] = []
+ for round_index in range(max((len(m) for m in ordered_groups), default=0)):
+ for members in ordered_groups:
+ if round_index < len(members):
+ order.append(members[round_index])
+ return order
+
+
+def _finding_ids_by_file(findings: list[HealthFinding]) -> dict[str, dict[str, list[str]]]:
+ """Public finding ids per file, grouped by biomarker, for evidence round-trips."""
+ out: dict[str, dict[str, list[str]]] = {}
+ for finding in findings:
+ public_id = finding.public_id
+ if not public_id:
+ continue
+ out.setdefault(finding.file_path, {}).setdefault(finding.biomarker_type, []).append(
+ public_id
+ )
+ return out
+
+
+def _details_payload(
+ opportunity: OpportunityModel,
+ *,
+ validations: dict[str, dict[str, Any]],
+ finding_ids: dict[str, list[str]],
+) -> dict[str, Any]:
+ """Everything explanatory, kept out of the indexed columns.
+
+ Steps carry a validation profile id rather than the profile, and the
+ profiles are stored once per opportunity: a file's steps usually share one
+ test set, and repeating it per step is how a response stops fitting.
+ """
+ profiles: dict[str, dict[str, Any]] = {}
+ steps: list[dict[str, Any]] = []
+ for step in opportunity.steps:
+ payload = step.as_dict()
+ validation = validations.get(step.plan_id)
+ if validation:
+ profile_id = _validation_profile_id(validation)
+ profiles.setdefault(profile_id, {"id": profile_id, **validation})
+ payload["validation_profile_id"] = profile_id
+ # The findings this step's cause names, so an agent can round-trip from
+ # a step back to the diagnosis that produced it in one call. Emitted
+ # only when this file has addressable findings at all: on a store
+ # written before findings carried public ids there are none, and an
+ # empty list there would claim "this cause produced no finding" when
+ # the truth is "no finding here is addressable by id".
+ if finding_ids:
+ payload["finding_ids"] = finding_ids.get(step.source_biomarker, [])
+ steps.append(payload)
+ return {
+ "steps": steps,
+ "evidence": [item.as_dict() for item in opportunity.evidence],
+ "affected_files": list(opportunity.affected_files),
+ "rank_factors": dict(opportunity.rank_factors),
+ "why_ranked": [dict(item) for item in opportunity.why_ranked],
+ "validation_profiles": list(profiles.values()),
+ **(
+ {"lead_finding_ids": finding_ids.get(opportunity.lead_biomarker or "", [])}
+ if finding_ids
+ else {}
+ ),
+ }
+
+
+def _validation_profile_id(validation: dict[str, Any]) -> str:
+ import hashlib
+
+ encoded = json.dumps(validation, sort_keys=True, separators=(",", ":"), default=str)
+ return "validation_" + hashlib.sha256(encoded.encode()).hexdigest()[:16]
+
+
+def _row_kwargs(
+ opportunity: OpportunityModel,
+ *,
+ rank_position: int,
+ queue_position: int,
+ status: str,
+ details: dict[str, Any],
+ analyzed_commit: str | None,
+) -> dict[str, Any]:
+ return {
+ "opportunity_id": opportunity.opportunity_id,
+ "refactoring_model_version": opportunity.refactoring_model_version,
+ "status": status,
+ "rank_position": rank_position,
+ "queue_position": queue_position,
+ "rank_score": float(opportunity.rank_score),
+ "file_path": opportunity.file_path,
+ "lead_biomarker": opportunity.lead_biomarker,
+ "lead_refactoring_type": opportunity.lead_refactoring_type,
+ "addresses_primary_problem": opportunity.addresses_primary_problem,
+ "effort_bucket": opportunity.effort_bucket,
+ "confidence": opportunity.confidence,
+ "step_count": opportunity.step_count,
+ "mechanical_steps": opportunity.mechanical_steps,
+ "judgment_steps": opportunity.judgment_steps,
+ "evidence_total": len(opportunity.evidence),
+ "affected_files_total": len(opportunity.affected_files),
+ "recoverable_health": float(opportunity.recoverable_health),
+ "details_json": json.dumps(details, separators=(",", ":"), default=str),
+ "analyzed_commit": analyzed_commit,
+ }
+
+
+def _summary_payload(
+ opportunities: list[OpportunityModel],
+ statuses: dict[str, str],
+ lead_details: dict[str, Any] | None,
+) -> dict[str, Any]:
+ by_type: dict[str, int] = {}
+ by_effort: dict[str, int] = {}
+ by_confidence: dict[str, int] = {}
+ by_status: dict[str, int] = {}
+ mechanical = judgment = 0
+ addresses_primary = not_primary = unknown_primary = 0
+ for item in opportunities:
+ by_type[item.lead_refactoring_type] = by_type.get(item.lead_refactoring_type, 0) + 1
+ by_effort[item.effort_bucket] = by_effort.get(item.effort_bucket, 0) + 1
+ by_confidence[item.confidence] = by_confidence.get(item.confidence, 0) + 1
+ state = statuses.get(item.opportunity_id, "open")
+ by_status[state] = by_status.get(state, 0) + 1
+ mechanical += item.mechanical_steps
+ judgment += item.judgment_steps
+ if item.addresses_primary_problem is True:
+ addresses_primary += 1
+ elif item.addresses_primary_problem is False:
+ not_primary += 1
+ else:
+ unknown_primary += 1
+ return {
+ "opportunities_total": len(opportunities),
+ "files_total": len({item.file_path for item in opportunities}),
+ "steps_total": mechanical + judgment,
+ "mechanical_steps_total": mechanical,
+ "judgment_steps_total": judgment,
+ "by_lead_type": by_type,
+ "by_effort": by_effort,
+ "by_confidence": by_confidence,
+ "by_status": by_status,
+ "addresses_primary_problem": {
+ "yes": addresses_primary,
+ "no": not_primary,
+ "unknown": unknown_primary,
+ },
+ "lead": lead_details,
+ }
+
+
+async def finalize_refactoring_opportunities(
+ session: AsyncSession,
+ repository_id: str,
+ *,
+ analyzed_commit: str | None = None,
+) -> int:
+ """Compose the stored plans into opportunities and reconcile the read model.
+
+ Called by both index paths inside the transaction that has just written the
+ plans, so composition always sees the authoritative set rather than a
+ partially-written one. Repository-wide even on an incremental run: an
+ opportunity is a fold over a file's plans, and a file the run did not touch
+ can still lose its opportunity when a cross-file clone elsewhere resolves.
+
+ Returns the number of open opportunities.
+ """
+ from ....analysis.health.models import primary_biomarker_by_file
+ from ....analysis.health.refactoring.opportunity import (
+ compose_opportunities,
+ opportunity_status,
+ )
+ from ....analysis.health.refactoring.recommendations import hydrate_recommendations
+
+ plan_rows = list(
+ (
+ await session.execute(
+ select(RefactoringSuggestion).where(
+ RefactoringSuggestion.repository_id == repository_id,
+ RefactoringSuggestion.refactoring_type != _PERF_TYPE,
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ # Acknowledged is outstanding work a person has picked up, not work that is
+ # gone: dropping it here would resolve the opportunity the moment someone
+ # said they were doing it.
+ live_plans = [row for row in plan_rows if row.status in _LIVE_PLAN_STATUSES]
+ findings = list(
+ (
+ await session.execute(
+ select(HealthFinding).where(HealthFinding.repository_id == repository_id)
+ )
+ )
+ .scalars()
+ .all()
+ )
+
+ opportunities = compose_opportunities(
+ live_plans, primary_biomarker_by_file=primary_biomarker_by_file(findings)
+ )
+
+ # Validation is resolved once, here, for exactly the plans that became
+ # steps. It used to be rebuilt on every request for every open plan, which
+ # is the single largest cost the serving path used to carry.
+ step_plan_ids = {step.plan_id for item in opportunities for step in item.steps}
+ step_rows = [row for row in live_plans if row.public_id in step_plan_ids]
+ validations: dict[str, dict[str, Any]] = {}
+ if step_rows:
+ # Keyed by the storage id ``rehydrate_suggestion`` carries through, never
+ # by position: ``hydrate_recommendations`` returns its results in rank
+ # order, so zipping them against the input pairs most steps with another
+ # plan's validation profile.
+ public_by_storage = {row.id: row.public_id for row in step_rows}
+ for recommendation in await hydrate_recommendations(
+ session, repository_id, step_rows
+ ):
+ public_id = public_by_storage.get(
+ getattr(recommendation.suggestion, "id", None)
+ )
+ # Through ``as_dict`` rather than the attribute: ``validation`` is a
+ # dataclass, and the serialized form is the one every surface shows.
+ validation = recommendation.as_dict().get("validation")
+ if public_id and validation:
+ validations[public_id] = validation
+
+ plan_status = {row.public_id: row.status for row in plan_rows if row.public_id}
+ statuses = {
+ item.opportunity_id: opportunity_status(item, plan_status) for item in opportunities
+ }
+ finding_ids = _finding_ids_by_file(findings)
+ queue_order = _diversified_order(opportunities)
+
+ details_by_id = {
+ item.opportunity_id: _details_payload(
+ item,
+ validations=validations,
+ finding_ids=finding_ids.get(item.file_path, {}),
+ )
+ for item in opportunities
+ }
+ queue_position_by_rank = {rank: slot for slot, rank in enumerate(queue_order)}
+
+ await _reconcile_opportunities(
+ session,
+ repository_id,
+ opportunities,
+ statuses=statuses,
+ details_by_id=details_by_id,
+ queue_position_by_rank=queue_position_by_rank,
+ analyzed_commit=analyzed_commit,
+ )
+
+ lead_rank = queue_order[0] if queue_order else None
+ lead = opportunities[lead_rank] if lead_rank is not None else None
+ lead_details = None
+ if lead is not None:
+ lead_details = {
+ "opportunity_id": lead.opportunity_id,
+ "file_path": lead.file_path,
+ "lead_biomarker": lead.lead_biomarker,
+ "lead_refactoring_type": lead.lead_refactoring_type,
+ "addresses_primary_problem": lead.addresses_primary_problem,
+ "step_count": lead.step_count,
+ "mechanical_steps": lead.mechanical_steps,
+ "judgment_steps": lead.judgment_steps,
+ "effort_bucket": lead.effort_bucket,
+ "confidence": lead.confidence,
+ "recoverable_health": round(lead.recoverable_health, 3),
+ "status": statuses.get(lead.opportunity_id, "open"),
+ }
+ await _write_summary(
+ session,
+ repository_id,
+ opportunities,
+ statuses=statuses,
+ lead_details=lead_details,
+ analyzed_commit=analyzed_commit,
+ )
+ return sum(1 for state in statuses.values() if state != "resolved")
+
+
+async def _reconcile_opportunities(
+ session: AsyncSession,
+ repository_id: str,
+ opportunities: list[OpportunityModel],
+ *,
+ statuses: dict[str, str],
+ details_by_id: dict[str, dict[str, Any]],
+ queue_position_by_rank: dict[int, int],
+ analyzed_commit: str | None,
+) -> None:
+ """Update, insert, and resolve, in one pass over the stored rows."""
+ from ....analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
+
+ stored = {
+ (row.refactoring_model_version, row.opportunity_id): row
+ for row in (
+ await session.execute(
+ select(RefactoringOpportunity).where(
+ RefactoringOpportunity.repository_id == repository_id,
+ # Rows an older model minted are left exactly as they are:
+ # their keys can never be composed again, so reading them
+ # only to re-resolve them would grow this read for the life
+ # of the repository.
+ RefactoringOpportunity.refactoring_model_version
+ == REFACTORING_MODEL_VERSION,
+ )
+ )
+ )
+ .scalars()
+ .all()
+ }
+ seen: set[tuple[int, str]] = set()
+ now = _now_utc()
+ for rank_position, item in enumerate(opportunities):
+ key = (item.refactoring_model_version, item.opportunity_id)
+ seen.add(key)
+ values = _row_kwargs(
+ item,
+ rank_position=rank_position,
+ queue_position=queue_position_by_rank.get(rank_position, rank_position),
+ status=statuses.get(item.opportunity_id, "open"),
+ details=details_by_id.get(item.opportunity_id, {}),
+ analyzed_commit=analyzed_commit,
+ )
+ row = stored.get(key)
+ if row is None:
+ session.add(
+ RefactoringOpportunity(id=_new_uuid(), repository_id=repository_id, **values)
+ )
+ continue
+ for name, value in values.items():
+ setattr(row, name, value)
+ row.updated_at = now
+ for key, row in stored.items():
+ if key not in seen and row.status != "resolved":
+ row.status = "resolved"
+ row.updated_at = now
+ await session.flush()
+
+
+async def _write_summary(
+ session: AsyncSession,
+ repository_id: str,
+ opportunities: list[OpportunityModel],
+ *,
+ statuses: dict[str, str],
+ lead_details: dict[str, Any] | None,
+ analyzed_commit: str | None,
+) -> None:
+ from ....analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
+
+ payload = json.dumps(
+ _summary_payload(opportunities, statuses, lead_details), separators=(",", ":")
+ )
+ row = await session.get(RefactoringSummary, repository_id)
+ if row is None:
+ row = RefactoringSummary(repository_id=repository_id)
+ session.add(row)
+ row.refactoring_model_version = REFACTORING_MODEL_VERSION
+ row.opportunities_total = len(opportunities)
+ row.summary_json = payload
+ row.analyzed_commit = analyzed_commit
+ row.updated_at = _now_utc()
+ await session.flush()
+
+
+# ---------------------------------------------------------------------------
+# Indexed readers
+# ---------------------------------------------------------------------------
+
+
+def _opportunity_filters(
+ repository_id: str,
+ *,
+ status: str,
+ lead_type: str | None,
+ confidence: str | None,
+ effort: str | None,
+ file_paths: list[str] | None,
+ mechanical_only: bool,
+ addresses_primary: bool | None,
+) -> list[Any]:
+ predicates: list[Any] = [
+ RefactoringOpportunity.repository_id == repository_id,
+ RefactoringOpportunity.status == status,
+ ]
+ if lead_type is not None:
+ predicates.append(RefactoringOpportunity.lead_refactoring_type == lead_type)
+ if confidence is not None:
+ predicates.append(RefactoringOpportunity.confidence == confidence)
+ if effort is not None:
+ predicates.append(RefactoringOpportunity.effort_bucket == effort)
+ if file_paths is not None:
+ predicates.append(RefactoringOpportunity.file_path.in_(file_paths))
+ if mechanical_only:
+ predicates.append(RefactoringOpportunity.mechanical_steps > 0)
+ if addresses_primary is not None:
+ predicates.append(
+ RefactoringOpportunity.addresses_primary_problem.is_(addresses_primary)
+ )
+ return predicates
+
+
+async def list_refactoring_opportunities(
+ session: AsyncSession,
+ repository_id: str,
+ *,
+ status: str = "open",
+ lead_type: str | None = None,
+ confidence: str | None = None,
+ effort: str | None = None,
+ file_paths: list[str] | None = None,
+ mechanical_only: bool = False,
+ addresses_primary: bool | None = None,
+ order: str = DEFAULT_ORDER,
+ limit: int = 20,
+ offset: int = 0,
+) -> tuple[list[RefactoringOpportunity], int]:
+ """One page and its total: two statements, whatever the row count."""
+ predicates = _opportunity_filters(
+ repository_id,
+ status=status,
+ lead_type=lead_type,
+ confidence=confidence,
+ effort=effort,
+ file_paths=file_paths,
+ mechanical_only=mechanical_only,
+ addresses_primary=addresses_primary,
+ )
+ total = int(
+ (
+ await session.execute(
+ select(func.count()).select_from(RefactoringOpportunity).where(*predicates)
+ )
+ ).scalar_one()
+ )
+ query: Select[Any] = (
+ select(RefactoringOpportunity)
+ .where(*predicates)
+ .order_by(*_ORDERS.get(order, _ORDERS[DEFAULT_ORDER]))
+ .offset(max(offset, 0))
+ .limit(max(limit, 0))
+ )
+ rows = list((await session.execute(query)).scalars().all())
+ return rows, total
+
+
+async def get_refactoring_opportunity(
+ session: AsyncSession, repository_id: str, opportunity_id: str
+) -> RefactoringOpportunity | None:
+ """Resolve one opportunity id. Indexed seek, newest model version first."""
+ result = await session.execute(
+ select(RefactoringOpportunity)
+ .where(
+ RefactoringOpportunity.repository_id == repository_id,
+ RefactoringOpportunity.opportunity_id == opportunity_id,
+ )
+ .order_by(RefactoringOpportunity.refactoring_model_version.desc())
+ .limit(1)
+ )
+ return result.scalar_one_or_none()
+
+
+async def get_refactoring_summary(
+ session: AsyncSession, repository_id: str
+) -> RefactoringSummary | None:
+ """The repository headline, by primary key."""
+ return await session.get(RefactoringSummary, repository_id)
+
+
+async def refactoring_facet_counts(
+ session: AsyncSession, repository_id: str, *, status: str = "open"
+) -> dict[str, dict[str, int]]:
+ """Counts for every facet dimension, in one statement.
+
+ Grouped by all three dimensions at once and folded here rather than one
+ statement each, so adding a facet never adds a round trip.
+ """
+ columns = (
+ RefactoringOpportunity.lead_refactoring_type,
+ RefactoringOpportunity.effort_bucket,
+ RefactoringOpportunity.confidence,
+ )
+ rows = await session.execute(
+ select(*columns, func.count())
+ .where(
+ RefactoringOpportunity.repository_id == repository_id,
+ RefactoringOpportunity.status == status,
+ )
+ .group_by(*columns)
+ )
+ facets: dict[str, dict[str, int]] = {"lead_type": {}, "effort": {}, "confidence": {}}
+ for lead_type, effort, confidence, count in rows.all():
+ for name, key in (
+ ("lead_type", lead_type),
+ ("effort", effort),
+ ("confidence", confidence),
+ ):
+ if key is not None:
+ facets[name][str(key)] = facets[name].get(str(key), 0) + int(count)
+ return facets
+
+
+__all__ = [
+ "DEFAULT_ORDER",
+ "finalize_refactoring_opportunities",
+ "get_refactoring_opportunity",
+ "get_refactoring_summary",
+ "list_refactoring_opportunities",
+ "refactoring_facet_counts",
+]
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 5b778c89f..f28a8cb28 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -1446,6 +1446,127 @@ class PerformanceSummary(Base):
)
+class RefactoringOpportunity(Base):
+ """One file's composed refactoring work, materialized for serving.
+
+ Composition folds a file's plans into one ordered, precondition-aware
+ opportunity. Folding at read time costs the whole repository per request
+ (measured: 91 ms over 2,283 plans, 787 ms at ten times that), and the
+ validation profile behind each step costs another second of test-reachability
+ walking. Both run once, when plans are persisted, and land here; a page is
+ then an indexed range scan.
+
+ Filter, order and identity live in columns because SQLite and PostgreSQL
+ both index those and neither indexes a JSON predicate portably. The ordered
+ steps, evidence, rank factors and validation profiles stay in
+ ``details_json``, where a new fact costs no migration.
+ """
+
+ __tablename__ = "refactoring_opportunities"
+
+ id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)
+ repository_id: Mapped[str] = mapped_column(
+ String(32), ForeignKey("repositories.id", ondelete="CASCADE"), nullable=False
+ )
+ # ``refop<model>_<digest>``, the digest of the member plan ids. Unique per
+ # repository *and* model version, for the reason the plan id is.
+ opportunity_id: Mapped[str] = mapped_column(String(64), nullable=False)
+ refactoring_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ # Rolled up from the member plans' triage, never written directly here.
+ status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")
+ # Position in the deterministic rank order.
+ rank_position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ # Position in the diversified default order. Separate column because the
+ # two orders answer different questions and both have to be indexed: rank
+ # answers "what scores highest", queue answers "what should a queue show
+ # first" when the ranked head is a run of ties from one package.
+ queue_position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ rank_score: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
+ file_path: Mapped[str] = mapped_column(Text, nullable=False, default="")
+ # The file's dominant biomarker; ``None`` when no finding names one.
+ lead_biomarker: Mapped[str | None] = mapped_column(String(64), nullable=True)
+ lead_refactoring_type: Mapped[str] = mapped_column(String(32), nullable=False, default="")
+ # Tri-state on purpose: ``None`` means no lead was available to compare
+ # against, which is not the same claim as "does not address it".
+ addresses_primary_problem: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+ effort_bucket: Mapped[str] = mapped_column(String(4), nullable=False, default="M")
+ confidence: Mapped[str] = mapped_column(String(16), nullable=False, default="medium")
+ step_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ mechanical_steps: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ judgment_steps: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ evidence_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ affected_files_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ recoverable_health: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
+ details_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
+ analyzed_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)
+ created_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False, default=_now_utc
+ )
+ updated_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc
+ )
+
+ __table_args__ = (
+ UniqueConstraint(
+ "repository_id",
+ "refactoring_model_version",
+ "opportunity_id",
+ name="uq_refactoring_opportunities_repo_model_id",
+ ),
+ Index("ix_refactoring_opportunities_repo_id", "repository_id", "opportunity_id"),
+ Index(
+ "ix_refactoring_opportunities_repo_status_queue",
+ "repository_id",
+ "status",
+ "queue_position",
+ ),
+ Index(
+ "ix_refactoring_opportunities_repo_status_rank",
+ "repository_id",
+ "status",
+ "rank_position",
+ ),
+ Index(
+ "ix_refactoring_opportunities_repo_status_type_rank",
+ "repository_id",
+ "status",
+ "lead_refactoring_type",
+ "rank_position",
+ ),
+ Index(
+ "ix_refactoring_opportunities_repo_status_path",
+ "repository_id",
+ "status",
+ "file_path",
+ ),
+ )
+
+
+class RefactoringSummary(Base):
+ """The current refactoring headline for one repository, in one row.
+
+ A bare dashboard has to lead with one actionable opportunity without
+ touching the queue, so the lead and the rollup are written by the
+ transaction that materializes the opportunities and read back by primary
+ key. Current state, never history.
+ """
+
+ __tablename__ = "refactoring_summaries"
+
+ repository_id: Mapped[str] = mapped_column(
+ String(32),
+ ForeignKey("repositories.id", ondelete="CASCADE"),
+ primary_key=True,
+ )
+ refactoring_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ opportunities_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ summary_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
+ analyzed_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)
+ updated_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc
+ )
+
+
class HealthFileMetric(Base):
"""Per-file aggregate metrics + final score."""
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 59695b87d..71ad58180 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -939,6 +939,7 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non
"""
from repowise.core.persistence.crud import (
finalize_performance_opportunities,
+ finalize_refactoring_opportunities,
upsert_health_findings,
upsert_health_metrics,
upsert_refactoring_suggestions,
@@ -1004,6 +1005,12 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non
analyzed_commit=analyzed_commit,
plan_policy=getattr(report, "performance_plan_policy", None),
)
+ # Repository-wide, like the queue above and for the same reason: an
+ # opportunity folds a file's plans, and a file this run did not touch
+ # can still lose one when a cross-file plan elsewhere resolves.
+ await finalize_refactoring_opportunities(
+ session, repo_id, analyzed_commit=analyzed_commit
+ )
# Per-function blame rollup for the changed files (keeps git_function_blame
# current between full indexes; FULL git tier only — empty otherwise).
fn_blame_rows = getattr(report, "function_blame_rows", None)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 60c2eaf68..a09fac56a 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1513,6 +1513,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
from repowise.core.persistence.crud import (
bulk_upsert_decisions,
finalize_performance_opportunities,
+ finalize_refactoring_opportunities,
recompute_decision_staleness,
save_coverage_files,
save_dead_code_findings,
@@ -1565,6 +1566,12 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
analyzed_commit=head_sha,
plan_policy=getattr(hr, "performance_plan_policy", None),
)
+ # Fold the plans just written into per-file opportunities. Last in
+ # the savepoint because it composes over the stored rows, so it has
+ # to see the reconciliation above rather than the detector output.
+ await finalize_refactoring_opportunities(
+ session, repo_id, analyzed_commit=head_sha
+ )
# Resolved coverage rows, when a report was ingested this run.
coverage_files = getattr(hr, "coverage_files", None)
if coverage_files:
diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
index a15d59890..30a156ff9 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
@@ -177,6 +177,8 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"trends[]",
"metrics[]",
"refactoring_plans[]",
+ "refactoring_opportunities[]",
+ "refactoring_summary",
"performance_opportunities[]",
"performance_summary",
"high_leverage_files[]",
@@ -185,10 +187,11 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
protected=(
"mode",
"directive",
- # The performance lead is bounded by construction and is the only
- # actionable performance content a bare dashboard carries, so
- # shedding it would leave the pillar with counts and nothing to do.
+ # Both pillar leads are bounded by construction and are the only
+ # actionable content a bare dashboard carries for them, so shedding
+ # one would leave that pillar with counts and nothing to do.
"performance_directive",
+ "refactoring_directive",
"opportunity_id",
"model_state",
"targets",
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.py
index f435f1191..fa2c55ce8 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py
@@ -9,7 +9,7 @@ from pathlib import Path
from time import perf_counter
from typing import Any
-from sqlalchemy import select
+from sqlalchemy import func, select
from repowise.core.analysis.health.churn_complexity import churn_complexity_points
from repowise.core.analysis.health.complexity.languages import LANGUAGE_MAPS
@@ -73,6 +73,34 @@ from repowise.server.services.performance_health import (
evidence_block,
parse_query,
)
+from repowise.server.services.refactoring_health import CANONICAL_VIEWS as _REFACTORING_VIEWS
+from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT
+from repowise.server.services.refactoring_health import (
+ RefactoringHealthService,
+ plan_view,
+)
+from repowise.server.services.refactoring_health import (
+ parse_query as parse_refactoring_query,
+)
+
+# The opportunity id space is shared with the performance pillar's, and told
+# apart by prefix alone, so ``opportunity_id`` stays one selector.
+_REFACTORING_OPPORTUNITY_PREFIX = "refop"
+
+_REFACTORING_COLLECTION_CAP = 6
+"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""
+
+_REFACTORING_STEP_CAP = 3
+"""Steps per row in the queue. The detail call pages the rest."""
+
+_REFACTORING_STEP_PAGE_CAP = 20
+"""Ceiling on one page of a detail call's ordered steps."""
+
+_REFACTORING_EVIDENCE_CAP = 3
+"""Evidence rows beside a detail response. ``only=['refactoring_evidence']`` pages more."""
+
+_REFACTORING_EVIDENCE_PAGE_CAP = 20
+"""Ceiling on one evidence page."""
_PERFORMANCE_COLLECTION_CAP = 6
"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""
@@ -208,6 +236,68 @@ async def _resolve_finding(
)
+@dataclass(frozen=True, slots=True)
+class _RefactoringBlocks:
+ """Everything the refactoring pillar contributes to one response."""
+
+ page: Any = None
+ summary: dict[str, Any] | None = None
+ directive: dict[str, Any] | None = None
+ ignored: dict[str, str] = field(default_factory=dict)
+
+
+async def _refactoring_blocks(
+ service: RefactoringHealthService,
+ *,
+ wants: Any,
+ included: bool,
+ file_paths: tuple[str, ...] | None,
+ scoped: bool,
+ limit: int,
+ cursor: int,
+ view: str,
+ lead_type: str | None = None,
+ confidence: str | None = None,
+ effort: str | None = None,
+) -> _RefactoringBlocks:
+ """Read the materialized queue, its rollup, and the dashboard lead.
+
+ Each block is gated on surviving the projection, so a caller that asked for
+ one of the three does not pay for the other two.
+ """
+ page = None
+ ignored: dict[str, str] = {}
+ if included:
+ emits_queue = wants("refactoring_opportunities")
+ query, ignored = parse_refactoring_query(
+ view=view,
+ lead_type=lead_type,
+ confidence=confidence,
+ effort=effort,
+ file_paths=list(file_paths) if file_paths else None,
+ limit=min(max(limit, 0), _REFACTORING_COLLECTION_CAP) if emits_queue else 1,
+ offset=cursor if emits_queue else 0,
+ )
+ page = await service.page(
+ query,
+ steps_per_item=_REFACTORING_STEP_CAP if emits_queue else 0,
+ with_facets=wants("refactoring_summary"),
+ )
+ return _RefactoringBlocks(
+ page=page,
+ summary=await service.summary() if included and wants("refactoring_summary") else None,
+ # The dashboard lead only. A targeted call is already about a file the
+ # caller named, so pointing it at the repository's worst file elsewhere
+ # would be answering a question nobody asked.
+ directive=(
+ await service.directive()
+ if not scoped and wants("refactoring_directive")
+ else None
+ ),
+ ignored=ignored,
+ )
+
+
async def _performance_detail_response(
session: Any,
repository: Any,
@@ -245,24 +335,87 @@ async def _performance_detail_response(
repository=repository, targets=[file_path] if file_path else None
),
}
- metric_rows = (
- list(
- (
- await session.execute(
- select(HealthFileMetric).where(
- HealthFileMetric.repository_id == repository.id,
- HealthFileMetric.file_path == file_path,
- )
- )
- ).scalars()
+ await _attach_repository_analysis_meta(session, repository, result["_meta"])
+ return result
+
+
+async def _refactoring_detail_response(
+ session: Any,
+ repository: Any,
+ reference_repository: str,
+ opportunity_id: str,
+ *,
+ evidence_only: bool,
+ limit: int,
+ cursor: int,
+) -> dict[str, Any]:
+ """One composed opportunity, or one page of the evidence behind it."""
+ service = RefactoringHealthService(session, repository.id, reference_repository)
+ if evidence_only:
+ detail = await service.detail(
+ opportunity_id,
+ step_limit=0,
+ evidence_limit=min(max(limit, 0), _REFACTORING_EVIDENCE_PAGE_CAP),
+ evidence_offset=cursor,
+ with_plans=False,
)
- if file_path
- else []
+ block = {k: v for k, v in detail.items() if k.startswith("evidence")}
+ result = {
+ "mode": "refactoring_evidence",
+ "opportunity_id": opportunity_id,
+ "resolved": bool(detail.get("resolved")),
+ **block,
+ "_meta": _build_meta(repository=repository),
+ }
+ if block.get("evidence_next_cursor") is not None:
+ result["recovery"] = {
+ "evidence": {
+ "remaining": block["evidence_total"] - block["evidence_next_cursor"],
+ "call": (
+ f"get_health(opportunity_id={opportunity_id!r}, "
+ f"only=['refactoring_evidence'], limit={limit}, "
+ f"cursor={block['evidence_next_cursor']})"
+ ),
+ }
+ }
+ return result
+ detail = await service.detail(
+ opportunity_id,
+ step_limit=min(max(limit, 0), _REFACTORING_STEP_PAGE_CAP),
+ step_offset=cursor,
+ evidence_limit=_REFACTORING_EVIDENCE_CAP,
)
- _attach_health_analysis_meta(result["_meta"], metric_rows)
+ file_path = detail.get("file_path")
+ if not detail.get("resolved"):
+ detail.setdefault(
+ "model_state", _refactoring_model_state(opportunity_id)
+ )
+ result = {
+ "mode": "refactoring_opportunity",
+ **detail,
+ "_meta": _build_meta(
+ repository=repository, targets=[file_path] if file_path else None
+ ),
+ }
+ await _attach_repository_analysis_meta(session, repository, result["_meta"])
return result
+def _refactoring_model_state(opportunity_id: str) -> dict[str, Any]:
+ """Tell a stale-model id apart from a wrong one, from the string alone."""
+ from repowise.core.analysis.health.refactoring.identity import (
+ REFACTORING_MODEL_VERSION,
+ model_state,
+ )
+
+ state = model_state(
+ opportunity_id.replace(_REFACTORING_OPPORTUNITY_PREFIX, "refac", 1)
+ )
+ state["public_id"] = opportunity_id
+ state["refactoring_model_version"] = REFACTORING_MODEL_VERSION
+ return state
+
+
def _perf_rank(biomarker_type: str | None, details: Any) -> int:
"""Order-of-magnitude ordering key for one ``performance`` finding.
@@ -917,11 +1070,71 @@ def _attach_health_analysis_meta(
meta: dict[str, Any], metrics: list[HealthFileMetric]
) -> None:
"""Keep stored analysis distinct from index/live Git verification."""
- meta["health_semantics"] = health_semantics_contract()
analyzed = [m for m in metrics if getattr(m, "updated_at", None)]
- commits = {c for m in analyzed if (c := getattr(m, "analyzed_commit", None))}
latest = max(analyzed, key=lambda m: m.updated_at) if analyzed else None
- latest_commit = getattr(latest, "analyzed_commit", None) if latest else None
+ _write_health_analysis_meta(
+ meta,
+ has_metrics=bool(metrics),
+ latest_at=latest.updated_at if latest is not None else None,
+ latest_commit=getattr(latest, "analyzed_commit", None) if latest else None,
+ distinct_commits=len({c for m in analyzed if (c := getattr(m, "analyzed_commit", None))}),
+ )
+
+
+async def _attach_repository_analysis_meta(
+ session: Any, repository: Any, meta: dict[str, Any]
+) -> None:
+ """The same block, computed over the repository rather than one file.
+
+ "Has this repository's health analysis recorded its commit" is a fact about
+ the analysis, but every detail mode used to answer it from the rows it
+ happened to be reporting on. A ``plan_id`` call scoped to a file whose row
+ carries a commit said ``available`` at the same instant the dashboard said
+ ``degraded (analysis_commit_not_recorded)`` from the repo-wide latest row,
+ and the reverse when the scoped file was the one missing it. Three bounded
+ aggregates, so agreeing costs no scan.
+ """
+ latest = (
+ await session.execute(
+ select(HealthFileMetric.updated_at, HealthFileMetric.analyzed_commit)
+ .where(
+ HealthFileMetric.repository_id == repository.id,
+ HealthFileMetric.updated_at.is_not(None),
+ )
+ .order_by(HealthFileMetric.updated_at.desc())
+ .limit(1)
+ )
+ ).first()
+ total, distinct = (
+ await session.execute(
+ select(
+ func.count(),
+ func.count(func.distinct(HealthFileMetric.analyzed_commit)),
+ ).where(HealthFileMetric.repository_id == repository.id)
+ )
+ ).one()
+ _write_health_analysis_meta(
+ meta,
+ has_metrics=total > 0,
+ latest_at=latest[0] if latest else None,
+ latest_commit=latest[1] if latest else None,
+ distinct_commits=distinct,
+ )
+
+
+def _write_health_analysis_meta(
+ meta: dict[str, Any],
+ *,
+ has_metrics: bool,
+ latest_at: Any,
+ latest_commit: str | None,
+ distinct_commits: int,
+) -> None:
+ """The one place the analysis-freshness block is shaped."""
+ meta["health_semantics"] = health_semantics_contract()
+ metrics = has_metrics
+ analyzed = latest_at is not None
+ commits_count = distinct_commits
status = "available" if latest_commit else "degraded" if metrics else "unavailable"
analysis: dict[str, Any] = {
"status": status,
@@ -944,17 +1157,16 @@ def _attach_health_analysis_meta(
if not metrics:
analysis["reason"] = "no_stored_health_metrics"
if analyzed:
- assert latest is not None
- analyzed_at = latest.updated_at.isoformat()
+ analyzed_at = latest_at.isoformat()
analysis["analyzed_at"] = analyzed_at
meta["health_analyzed_at"] = analyzed_at
if latest_commit:
analyzed_commit = latest_commit[:12]
analysis["analyzed_commit"] = analyzed_commit
meta["health_analyzed_commit"] = analyzed_commit
- if len(commits) > 1:
- analysis["analyzed_commits_distinct"] = len(commits)
- meta["health_analyzed_commits_distinct"] = len(commits)
+ if commits_count > 1:
+ analysis["analyzed_commits_distinct"] = commits_count
+ meta["health_analyzed_commits_distinct"] = commits_count
if not latest_commit:
analysis["reason"] = "analysis_commit_not_recorded"
analysis["analyzed_commit"] = None
@@ -1231,7 +1443,10 @@ async def get_health(
repo: str | None = None,
limit: int = 20,
only: list[str] | None = None,
- refactoring_view: str = "canonical",
+ refactoring_view: str = _REFACTORING_VIEW_DEFAULT,
+ refactoring_type: str | None = None,
+ refactoring_confidence: str | None = None,
+ refactoring_effort: str | None = None,
cursor: int = 0,
finding_id: str | None = None,
plan_id: str | None = None,
@@ -1250,26 +1465,26 @@ async def get_health(
Args:
targets: file paths or ``module:<name>``. Empty means dashboard;
- unmatched ones appear in ``unresolved``, surviving any ``only``.
+ unmatched ones land in ``unresolved``, surviving ``only``.
include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |
- ``accuracy`` | ``signals`` | ``churn_complexity``, or one dimension
- name. ``performance`` also adds the opportunity queue.
+ ``accuracy`` | ``signals`` | ``churn_complexity``, or a dimension.
+ ``performance`` and ``refactoring`` add their queues.
only: keys to keep; identity, counts and recovery survive.
``biomarkers``, ``accuracy`` and ``refactoring`` alias their block
key. ``performance``, ``defect`` and ``maintainability`` do not:
they filter rows and land in ``unknown_only_keys``.
repo: usually omitted.
limit: max rows per ranked list, ``0`` for none.
- refactoring_view: ``canonical`` (default) or ``file_spread``.
- cursor: zero-based offset for ranked collections.
- finding_id: stable ``id`` emitted by a health finding.
- plan_id: stable ``id`` emitted by a refactoring plan.
- opportunity_id: ``perf...`` id from ``performance_directive`` or the
- queue: the cause, its plan or why there is none, and evidence,
- which ``only=["performance_evidence"]`` plus ``cursor`` pages.
- Excludes the two ids above.
+ cursor: zero-based offset into a ranked list.
+ finding_id: stable ``id`` from a health finding.
+ plan_id: stable ``id`` from a refactoring plan.
+ opportunity_id: ``perf...`` or ``refop...`` id from a directive or
+ queue: the unit, its steps or plan, and evidence paged by
+ ``only=["*_evidence"]``. Excludes the two ids above.
+ refactoring_view: ``diversified`` (default) | ``canonical`` |
+ ``file_spread``; refactoring_type / _confidence / _effort filter.
performance_view / _context / _boundary / _confidence / _sort: queue
- projection and filters; the facets list their values.
+ projection and filters; the facets list them.
"""
started = perf_counter()
@@ -1283,8 +1498,8 @@ async def get_health(
# "the totals, none of the rows" silently returned a row.
limit = max(limit, 0)
cursor = max(cursor, 0)
- if refactoring_view not in {"canonical", "file_spread"}:
- refactoring_view = "canonical"
+ if refactoring_view not in _REFACTORING_VIEWS:
+ refactoring_view = _REFACTORING_VIEW_DEFAULT
include_set = set(include or [])
known_includes = {
"biomarkers",
@@ -1334,6 +1549,11 @@ async def get_health(
or wants("recommendation_lede")
or wants("performance_summary")
)
+ wants_refactoring_opportunities = (
+ wants("refactoring_opportunities")
+ or wants("recommendation_lede")
+ or wants("refactoring_summary")
+ )
# Everything downstream of the test/production split, in one place.
#
# Keep this list exhaustive. The read it gates is not free (the column list
@@ -1379,6 +1599,8 @@ async def get_health(
"churn_complexity",
"coverage.files",
"refactoring_plans",
+ "refactoring_opportunities",
+ "refactoring_evidence",
"performance_opportunities",
"performance_evidence",
}
@@ -1394,7 +1616,12 @@ async def get_health(
if tail_start < len(rows):
next_limit = (
min(row_cap or 6, 6)
- if label in {"refactoring_plans", "performance_opportunities"}
+ if label
+ in {
+ "refactoring_plans",
+ "refactoring_opportunities",
+ "performance_opportunities",
+ }
else min(len(rows) - tail_start, 50)
)
page_recoveries[label] = (
@@ -1433,23 +1660,20 @@ async def get_health(
targets=[match.file_path] if match else None,
),
}
- metric_rows = (
- list(
- (
- await session.execute(
- select(HealthFileMetric).where(
- HealthFileMetric.repository_id == repository.id,
- HealthFileMetric.file_path == match.file_path,
- )
- )
- ).scalars()
- )
- if match
- else []
- )
- _attach_health_analysis_meta(result["_meta"], metric_rows)
+ await _attach_repository_analysis_meta(session, repository, result["_meta"])
return result
+ if opportunity_id and opportunity_id.startswith(_REFACTORING_OPPORTUNITY_PREFIX):
+ return await _refactoring_detail_response(
+ session,
+ repository,
+ reference_repository,
+ opportunity_id,
+ evidence_only=only_set == {"refactoring_evidence"},
+ limit=limit,
+ cursor=cursor,
+ )
+
if opportunity_id:
return await _performance_detail_response(
session,
@@ -1462,48 +1686,35 @@ async def get_health(
)
if plan_id:
- plan_rows = await get_refactoring_suggestions(session, repository.id)
- recommendations = await hydrate_recommendations(
- session, repository.id, plan_rows
- )
- match = next(
- (
- row
- for row in recommendations
- if plan_id
- in {row.id, _refactoring_plan_id(row, reference_repository)}
- ),
- None,
+ # An indexed seek and one hydration, not a full load and a linear
+ # scan: resolving one id used to cost every open plan in the repo.
+ service = RefactoringHealthService(
+ session, repository.id, reference_repository
)
+ resolved = await service.plan_detail(plan_id)
+ plan = resolved.get("plan") if resolved.get("resolved") else None
+ if plan is not None:
+ plan.setdefault("id", plan_id)
+ plan["repository"] = reference_repository
result = {
"mode": "refactoring_plan",
"plan_id": plan_id,
- "plan": (
- _serialize_refactoring(match, reference_repository)
- if match
- else None
- ),
- "resolved": match is not None,
+ "plan": plan,
+ "resolved": bool(resolved.get("resolved")),
"_meta": _build_meta(
repository=repository,
- targets=[match.suggestion.file_path] if match else None,
+ targets=[plan["file_path"]] if plan else None,
),
}
- metric_rows = (
- list(
- (
- await session.execute(
- select(HealthFileMetric).where(
- HealthFileMetric.repository_id == repository.id,
- HealthFileMetric.file_path == match.suggestion.file_path,
- )
- )
- ).scalars()
+ if resolved.get("opportunity_id"):
+ result["opportunity_id"] = resolved["opportunity_id"]
+ result["next_action"] = resolved["next_action"]
+ elif plan is not None:
+ result["opportunity_note"] = (
+ "This plan is addressable but is not a step of any composed "
+ "opportunity; a demoted clone is supporting evidence, not work."
)
- if match
- else []
- )
- _attach_health_analysis_meta(result["_meta"], metric_rows)
+ await _attach_repository_analysis_meta(session, repository, result["_meta"])
return result
all_metrics_q = select(HealthFileMetric).where(
@@ -1784,11 +1995,18 @@ async def get_health(
# asked for, scoped to the same targets, exclude-filtered like findings.
refactoring_rows: list[Any] = []
refactoring_recommendations: list[Recommendation] = []
- if (
- "refactoring" in include_set
- and (wants("refactoring_plans") or wants("recommendation_lede"))
- and not nothing_resolved
- ):
+ # Only when a caller names the plan list. ``include=["refactoring"]``
+ # leads with composed opportunities now, and emitting both would ship
+ # two representations of the same work in one response - 52k chars on
+ # this repo, past the expanded budget, most of it duplicated. The
+ # documented ``only=["refactoring_plans"]`` call is unchanged.
+ plans_requested = "refactoring" in include_set and (
+ "refactoring_plans" in only_set
+ # The cross-pillar lede quotes one plan beside one performance
+ # opportunity, and only when both pillars were asked for.
+ or ({"performance", "refactoring"} <= include_set and wants("recommendation_lede"))
+ )
+ if plans_requested and not nothing_resolved:
refactoring_rows = filter_rows_by_attr(
await get_refactoring_suggestions(
session,
@@ -1803,7 +2021,7 @@ async def get_health(
repository.id,
refactoring_rows,
metric_rows=all_metrics,
- view=refactoring_view, # type: ignore[arg-type]
+ view=plan_view(refactoring_view),
)
# The materialized causal read model. Filtering, ordering, paging, plan
@@ -1812,6 +2030,22 @@ async def get_health(
performance_service = PerformanceHealthService(
session, repository.id, reference_repository
)
+ refactoring_service = RefactoringHealthService(
+ session, repository.id, reference_repository
+ )
+ refactoring = await _refactoring_blocks(
+ refactoring_service,
+ wants=wants,
+ included="refactoring" in include_set and wants_refactoring_opportunities,
+ file_paths=tuple(effective_targets) if scoped else None,
+ scoped=scoped,
+ limit=limit,
+ cursor=cursor,
+ view=refactoring_view,
+ lead_type=refactoring_type,
+ confidence=refactoring_confidence,
+ effort=refactoring_effort,
+ )
performance = await _performance_blocks(
performance_service,
wants=wants,
@@ -2096,6 +2330,15 @@ async def get_health(
# above is unchanged: performance findings carry no defect impact,
# so they never competed for it and the dashboard said nothing an
# agent could act on about them.
+ # Two more additive leads, on the same terms: the block above ranks
+ # files by health deficit and cannot say which composed work to do,
+ # and it explicitly reports that no plan addresses the cause it
+ # names on most files. These say what there is to do about it.
+ **(
+ {"refactoring_directive": refactoring.directive}
+ if refactoring.directive is not None
+ else {}
+ ),
**(
{"performance_directive": performance.directive}
if performance.directive is not None
@@ -2220,7 +2463,7 @@ async def get_health(
)
result["test_findings_total"] = test_findings_total
- if "refactoring" in include_set:
+ if plans_requested:
# Canonical is the shared REST/MCP/CLI order. File diversity remains
# available only through the explicitly named ``file_spread`` view.
validation_profiles: dict[str, dict[str, Any]] = {}
@@ -2302,6 +2545,37 @@ async def get_health(
if len(recent) > limit:
result["trend"]["recent_reduced_reason"] = "limit"
+ if refactoring.page is not None and wants("refactoring_opportunities"):
+ result["refactoring_opportunities"] = refactoring.page.items
+ result["refactoring_opportunities_total"] = refactoring.page.total
+ result["refactoring_opportunities_emitted"] = len(refactoring.page.items)
+ if len(refactoring.page.items) < refactoring.page.total:
+ result["refactoring_opportunities_reduced_reason"] = (
+ "collection_cap" if limit > _REFACTORING_COLLECTION_CAP else "limit"
+ )
+ if refactoring.page.next_offset is not None:
+ page_recoveries["refactoring_opportunities"] = (
+ refactoring.page.next_offset,
+ _REFACTORING_COLLECTION_CAP,
+ refactoring.page.total - refactoring.page.next_offset,
+ )
+ if refactoring.ignored:
+ result["ignored_arguments"] = {
+ **result.get("ignored_arguments", {}),
+ **refactoring.ignored,
+ }
+
+ if refactoring.summary is not None:
+ result["refactoring_summary"] = {
+ **refactoring.summary,
+ "facets": refactoring.page.facets if refactoring.page else {},
+ "view": refactoring_view,
+ "next_call": (
+ "get_health(include=['refactoring'], "
+ "only=['refactoring_opportunities'], limit=6)"
+ ),
+ }
+
if performance.page is not None and wants("performance_opportunities"):
result["performance_opportunities"] = performance.page.items
result["performance_opportunities_total"] = performance.page.total
@@ -2579,7 +2853,13 @@ async def get_health(
# dashboard (no targets) keeps the repo-level warning.
result["_meta"] = _build_meta(repository=repository, targets=targets if targets else None)
analyzed_source = metric_rows if scoped else all_metrics
- _attach_health_analysis_meta(result["_meta"], analyzed_source)
+ if scoped:
+ # Scoped calls used to answer repository freshness from the caller's own
+ # files, which is how the same repo read ``available`` and ``degraded``
+ # in the same second depending on which mode answered.
+ await _attach_repository_analysis_meta(session, repository, result["_meta"])
+ else:
+ _attach_health_analysis_meta(result["_meta"], analyzed_source)
# Server-side wall clock, as ``get_context`` already reports. Without it a
# regression in here is invisible until someone profiles it by hand.
for label, dropped in semantic_omissions.items():
diff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.py
index 295105e2f..293792603 100644
--- a/packages/server/src/repowise/server/routers/refactoring.py
+++ b/packages/server/src/repowise/server/routers/refactoring.py
@@ -27,6 +27,16 @@ from repowise.core.analysis.health.refactoring.recommendations import (
from repowise.core.persistence import crud
from repowise.core.persistence.crud.analysis.refactoring import ALLOWED_STATUSES
from repowise.server.deps import get_db_session, verify_api_key
+from repowise.server.services.refactoring_health import (
+ CANONICAL_ORDERS,
+ CANONICAL_VIEWS,
+ DEFAULT_VIEW,
+ RefactoringHealthService,
+ parse_query,
+)
+
+_STEPS_PER_ROW = 3
+"""Steps carried on a queue row; the detail call pages the rest."""
router = APIRouter(
prefix="/api/repos",
@@ -371,6 +381,93 @@ async def _local_repo_path(session: AsyncSession, repo_id: str) -> Path:
return repo_path
+# ---------------------------------------------------------------------------
+# Composed opportunities. Thin adapters: filtering, ordering, paging, facets
+# and detail all live in ``services/refactoring_health.py``, which the MCP
+# surface reads through as well, so the two cannot answer differently.
+# ---------------------------------------------------------------------------
+
+
+def _service(session: AsyncSession, repo_id: str) -> RefactoringHealthService:
+ return RefactoringHealthService(session, repo_id, repo_id)
+
+
[email protected]("/{repo_id}/refactoring/opportunities")
+async def get_refactoring_opportunities(
+ repo_id: str,
+ refactoring_type: str | None = Query(None, description="Filter by lead refactoring type"),
+ confidence: str | None = Query(None, description="low | medium | high"),
+ effort: str | None = Query(None, description="S | M | L | XL"),
+ file_path: str | None = Query(None, description="One repo-relative file path"),
+ mechanical: bool = Query(False, description="Only opportunities with a mechanical step"),
+ view: str = Query(DEFAULT_VIEW, description=" | ".join(CANONICAL_VIEWS)),
+ order: str | None = Query(None, description=" | ".join(CANONICAL_ORDERS)),
+ limit: int = Query(20, ge=1, le=100),
+ offset: int = Query(0, ge=0),
+ session: AsyncSession = Depends(get_db_session),
+) -> dict[str, Any]:
+ """One page of composed opportunities, with facets and the rollup."""
+ query, ignored = parse_query(
+ lead_type=refactoring_type,
+ confidence=confidence,
+ effort=effort,
+ mechanical=mechanical,
+ file_paths=[file_path] if file_path else None,
+ view=view,
+ order=order,
+ limit=limit,
+ offset=offset,
+ )
+ page = await _service(session, repo_id).page(
+ query, steps_per_item=_STEPS_PER_ROW, with_facets=True, with_summary=True
+ )
+ body: dict[str, Any] = {
+ "items": page.items,
+ "total": page.total,
+ "offset": page.offset,
+ "has_more": page.next_offset is not None,
+ "next_offset": page.next_offset,
+ "facets": page.facets,
+ "summary": page.summary,
+ }
+ if ignored:
+ body["ignored_arguments"] = ignored
+ return body
+
+
[email protected]("/{repo_id}/refactoring/summary")
+async def get_refactoring_rollup(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session),
+) -> dict[str, Any]:
+ """The repository rollup and its one lead, by primary key."""
+ service = _service(session, repo_id)
+ return {"summary": await service.summary(), "directive": await service.directive()}
+
+
[email protected]("/{repo_id}/refactoring/opportunities/{opportunity_id}")
+async def get_refactoring_opportunity_detail(
+ repo_id: str,
+ opportunity_id: str,
+ step_limit: int = Query(20, ge=0, le=200),
+ step_offset: int = Query(0, ge=0),
+ evidence_limit: int = Query(8, ge=0, le=200),
+ evidence_offset: int = Query(0, ge=0),
+ session: AsyncSession = Depends(get_db_session),
+) -> dict[str, Any]:
+ """One opportunity: its ordered steps, evidence, validation and plans."""
+ detail = await _service(session, repo_id).detail(
+ opportunity_id,
+ step_limit=step_limit,
+ step_offset=step_offset,
+ evidence_limit=evidence_limit,
+ evidence_offset=evidence_offset,
+ )
+ if not detail.get("resolved"):
+ raise HTTPException(status_code=404, detail="Unknown opportunity id")
+ return detail
+
+
@router.get("/{repo_id}/refactoring/settings", response_model=RefactoringSettings)
async def get_refactoring_settings(
repo_id: str,
diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.py
new file mode 100644
index 000000000..32473c9ad
--- /dev/null
+++ b/packages/server/src/repowise/server/services/refactoring_health.py
@@ -0,0 +1,655 @@
+"""One read model for refactoring opportunities, shared by REST and MCP.
+
+Both surfaces used to load every open plan, hydrate it, rank it and page it in
+Python, and they disagreed about almost everything they did with the result:
+different filter vocabularies, two incompatible pagination contracts, and two
+ways of resolving one id - REST an indexed point lookup, MCP a full hydration
+followed by a linear scan. Query, filter, order, page, facets, detail and the
+directive live here now, so the agent surface and the product surface cannot
+drift apart.
+
+Nothing in this module composes or ranks. Composition is
+``analysis/health/refactoring/opportunity.py`` and it runs at index time; this
+module reads what the finalizer wrote.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence.crud.analysis.refactoring_opportunities import (
+ get_refactoring_opportunity,
+ get_refactoring_summary,
+ list_refactoring_opportunities,
+ refactoring_facet_counts,
+)
+from repowise.core.persistence.models import RefactoringOpportunity, RefactoringSuggestion
+
+# ``refactoring_view`` predates the opportunity. Both old values keep working
+# and both are documented in docs/layers/REFACTORING.md:
+#
+# - ``canonical`` the published rank order, ties and all. What the old default
+# produced, kept for a caller that wants the score order verbatim.
+# - ``file_spread`` asked for one row per file. An opportunity *is* one file's
+# work, so the spread is now satisfied by construction; the value maps onto
+# the diversified order, which is what it was reaching for.
+# - ``diversified`` the new default. Rank order round-robined over cause and
+# directory, because the ranked head is a genuine run of ties.
+_VIEW_ORDERS: dict[str, str] = {
+ "canonical": "rank",
+ "file_spread": "queue",
+ "diversified": "queue",
+}
+CANONICAL_VIEWS = tuple(_VIEW_ORDERS)
+DEFAULT_VIEW = "diversified"
+
+# The legacy plan list has no notion of the diversified order, so the new
+# default resolves to the value that list has always defaulted to.
+_PLAN_VIEWS = {"canonical": "canonical", "file_spread": "file_spread", "diversified": "canonical"}
+
+CANONICAL_ORDERS = ("queue", "rank", "health", "effort", "file")
+_CONFIDENCES = ("low", "medium", "high")
+_EFFORTS = ("S", "M", "L", "XL")
+_TYPES = (
+ "break_cycle",
+ "extract_class",
+ "extract_helper",
+ "extract_method",
+ "move_method",
+ "split_file",
+)
+
+_UNAVAILABLE = {
+ "status": "unavailable",
+ "reason": "no_refactoring_analysis",
+ "detail": "No refactoring analysis is stored for this repository. Run `repowise update`.",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class RefactoringQuery:
+ """A normalized queue request. The only shape either adapter passes down."""
+
+ lead_type: str | None = None
+ confidence: str | None = None
+ effort: str | None = None
+ mechanical_only: bool = False
+ addresses_primary: bool | None = None
+ file_paths: tuple[str, ...] | None = None
+ view: str = DEFAULT_VIEW
+ order: str | None = None
+ limit: int = 20
+ offset: int = 0
+
+ @property
+ def resolved_order(self) -> str:
+ """An explicit ``order`` wins; otherwise the view picks one."""
+ if self.order in CANONICAL_ORDERS:
+ return self.order
+ return _VIEW_ORDERS.get(self.view, _VIEW_ORDERS[DEFAULT_VIEW])
+
+
+@dataclass(frozen=True, slots=True)
+class RefactoringPage:
+ items: list[dict[str, Any]]
+ total: int
+ offset: int
+ next_offset: int | None
+ facets: dict[str, dict[str, int]] = field(default_factory=dict)
+ summary: dict[str, Any] | None = None
+ ignored_arguments: dict[str, str] = field(default_factory=dict)
+
+
+def parse_query(
+ *,
+ lead_type: str | None = None,
+ confidence: str | None = None,
+ effort: str | None = None,
+ mechanical: bool | None = None,
+ addresses_primary: bool | None = None,
+ file_paths: list[str] | tuple[str, ...] | None = None,
+ view: str | None = None,
+ order: str | None = None,
+ limit: int = 20,
+ offset: int = 0,
+) -> tuple[RefactoringQuery, dict[str, str]]:
+ """Normalize a caller's arguments, naming anything it had to discard.
+
+ An unrecognized value is reported back rather than silently treated as "no
+ filter": a caller who misspells a type should not be told the repository is
+ clean.
+ """
+ ignored: dict[str, str] = {}
+
+ def admit(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:
+ if value is None:
+ return None
+ if value in allowed:
+ return value
+ ignored[name] = value
+ return None
+
+ resolved_view = view or DEFAULT_VIEW
+ if resolved_view not in _VIEW_ORDERS:
+ ignored["refactoring_view"] = resolved_view
+ resolved_view = DEFAULT_VIEW
+ return (
+ RefactoringQuery(
+ lead_type=admit("refactoring_type", lead_type, _TYPES),
+ confidence=admit("confidence", confidence, _CONFIDENCES),
+ effort=admit("effort", effort, _EFFORTS),
+ mechanical_only=bool(mechanical),
+ addresses_primary=addresses_primary,
+ file_paths=tuple(file_paths) if file_paths else None,
+ view=resolved_view,
+ order=admit("order", order, CANONICAL_ORDERS),
+ limit=max(int(limit), 0),
+ offset=max(int(offset), 0),
+ ),
+ ignored,
+ )
+
+
+def plan_view(view: str | None) -> Literal["canonical", "file_spread"]:
+ """The legacy plan list's view for a caller's ``refactoring_view``."""
+ return _PLAN_VIEWS.get(view or DEFAULT_VIEW, "canonical") # type: ignore[return-value]
+
+
+def evidence_block(
+ evidence: list[dict[str, Any]], total: int, offset: int
+) -> dict[str, Any]:
+ """One evidence page plus the exact call that reads the rest."""
+ emitted = len(evidence)
+ block: dict[str, Any] = {
+ "evidence": evidence,
+ "evidence_total": total,
+ "evidence_emitted": emitted,
+ "evidence_truncated": offset + emitted < total,
+ }
+ if block["evidence_truncated"]:
+ block["evidence_reduced_reason"] = "evidence_page"
+ block["evidence_next_cursor"] = offset + emitted
+ return block
+
+
+class RefactoringHealthService:
+ """Query, page, detail and headline over the materialized opportunities."""
+
+ def __init__(self, session: AsyncSession, repository_id: str, repository: str) -> None:
+ self._session = session
+ self._repository_id = repository_id
+ self._repository = repository
+
+ # -- queue ------------------------------------------------------------
+
+ async def page(
+ self,
+ query: RefactoringQuery,
+ *,
+ steps_per_item: int | None = None,
+ evidence_per_item: int = 0,
+ with_facets: bool = False,
+ with_summary: bool = False,
+ ) -> RefactoringPage:
+ """One page: two statements, plus one each for facets and the headline.
+
+ The statement count is constant in page size and in row count. The
+ indexes cover repository, status and the orderings, plus lead type and
+ file path; ``mechanical_only`` and ``addresses_primary`` are residual
+ filters over the open set, so those two are bounded by the open row
+ count rather than by the page. Neither has a consumer yet - index them
+ when one exists, not before.
+ """
+ rows, total = await list_refactoring_opportunities(
+ self._session,
+ self._repository_id,
+ lead_type=query.lead_type,
+ confidence=query.confidence,
+ effort=query.effort,
+ file_paths=list(query.file_paths) if query.file_paths else None,
+ mechanical_only=query.mechanical_only,
+ addresses_primary=query.addresses_primary,
+ order=query.resolved_order,
+ limit=query.limit,
+ offset=query.offset,
+ )
+ items = [
+ self._serialize(row, steps_limit=steps_per_item, evidence_limit=evidence_per_item)
+ for row in rows
+ ]
+ next_offset = query.offset + len(items)
+ return RefactoringPage(
+ items=items,
+ total=total,
+ offset=query.offset,
+ next_offset=next_offset if next_offset < total else None,
+ facets=(
+ await refactoring_facet_counts(self._session, self._repository_id)
+ if with_facets
+ else {}
+ ),
+ summary=await self.summary() if with_summary else None,
+ )
+
+ # -- headline ---------------------------------------------------------
+
+ async def summary(self) -> dict[str, Any]:
+ """The Level-1 rollup, read by primary key."""
+ row = await get_refactoring_summary(self._session, self._repository_id)
+ if row is None:
+ return dict(_UNAVAILABLE)
+ payload = _loads(row.summary_json)
+ payload["status"] = "available"
+ payload["refactoring_model_version"] = row.refactoring_model_version
+ payload["analyzed_commit"] = row.analyzed_commit
+ return payload
+
+ async def directive(self) -> dict[str, Any]:
+ """The Level-0 lead: one opportunity, and the exact call that opens it.
+
+ The same primary-key read the summary uses, so a bare dashboard pays one
+ statement for it and never touches the queue.
+ """
+ row = await get_refactoring_summary(self._session, self._repository_id)
+ if row is None:
+ return dict(_UNAVAILABLE)
+ payload = _loads(row.summary_json)
+ lead = payload.get("lead")
+ if not lead:
+ return {
+ "status": "clear",
+ "reason": "no_open_opportunities",
+ "detail": "No refactoring opportunity is open for this repository.",
+ "opportunities_total": int(payload.get("opportunities_total") or 0),
+ }
+ addresses = lead.get("addresses_primary_problem")
+ directive: dict[str, Any] = {
+ "status": "available",
+ "opportunity_id": lead.get("opportunity_id"),
+ "fix_first": lead.get("file_path"),
+ "reason": lead.get("lead_biomarker"),
+ "lead_refactoring_type": lead.get("lead_refactoring_type"),
+ "steps": lead.get("step_count"),
+ "mechanical_steps": lead.get("mechanical_steps"),
+ "judgment_steps": lead.get("judgment_steps"),
+ "effort_bucket": lead.get("effort_bucket"),
+ "confidence": lead.get("confidence"),
+ "recovers_health_points": lead.get("recoverable_health"),
+ "addresses_primary_problem": addresses,
+ "opportunities_total": int(payload.get("opportunities_total") or 0),
+ "next_action": {
+ "tool": "get_health",
+ "arguments": {"opportunity_id": lead.get("opportunity_id")},
+ },
+ }
+ # The honest half. A file's plans very often answer a different question
+ # from the one that made it the worst file, and saying so beats routing
+ # an agent to cleanup it will read as the fix.
+ if addresses is False:
+ directive["note"] = (
+ f"These steps do not address {lead.get('lead_biomarker')!r}, this file's "
+ "dominant finding. Treat them as related cleanup, not the fix for it."
+ )
+ elif addresses is None:
+ directive["note"] = (
+ "No dominant finding was recorded for this file, so whether these steps "
+ "address it is unknown rather than no."
+ )
+ return directive
+
+ # -- detail -----------------------------------------------------------
+
+ async def detail(
+ self,
+ opportunity_id: str,
+ *,
+ step_limit: int = 20,
+ step_offset: int = 0,
+ evidence_limit: int = 3,
+ evidence_offset: int = 0,
+ with_plans: bool = True,
+ ) -> dict[str, Any]:
+ """One opportunity by id: an indexed seek, then its member plans."""
+ row = await get_refactoring_opportunity(
+ self._session, self._repository_id, opportunity_id
+ )
+ if row is None:
+ return {
+ "resolved": False,
+ "opportunity_id": opportunity_id,
+ "reason": "unknown_opportunity_id",
+ }
+ details = _loads(row.details_json)
+ 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["steps"] = page
+ payload["steps_total"] = len(steps)
+ payload["steps_emitted"] = len(page)
+ if step_offset + len(page) < len(steps):
+ payload["steps_reduced_reason"] = "limit"
+ payload["steps_next_cursor"] = step_offset + len(page)
+ evidence = list(details.get("evidence") or [])
+ payload.update(
+ evidence_block(
+ evidence[evidence_offset : evidence_offset + max(evidence_limit, 0)],
+ len(evidence),
+ evidence_offset,
+ )
+ )
+ payload["validation_profiles"] = list(details.get("validation_profiles") or [])
+ payload["affected_files"] = list(details.get("affected_files") or [])
+ payload["lead_finding_ids"] = list(details.get("lead_finding_ids") or [])
+ payload["next_actions"] = self._next_actions(row, page)
+ if with_plans and page:
+ payload["plans"] = await self._plans_for([s["plan_id"] for s in page])
+ # Ordered steps carry ``relocated_by``; a surface that renders them must
+ # say the symbol has to be located again before the step is applied.
+ if any(step.get("relocated_by") for step in page):
+ payload["ordering_note"] = (
+ "A step carrying `relocated_by` names a symbol an earlier step moves. "
+ "Locate it again before applying the step; its file and span describe "
+ "where the symbol was."
+ )
+ return payload
+
+ async def plan_detail(self, plan_id: str) -> dict[str, Any]:
+ """Resolve one plan id without hydrating the repository.
+
+ Every read is a seek. The row comes from the storage-or-public id index,
+ its rank inputs from the one metric row and the one file's centrality,
+ and its validation from the profile the finalizer already resolved. The
+ payload is built by the same ``build_recommendations`` every surface
+ uses, so it is field-identical to the hydrated form; what is gone is the
+ two full-table reads and the test-reachability walk that made resolving
+ one id cost the repository.
+ """
+ from repowise.core.analysis.health.refactoring.recommendations import (
+ build_recommendations,
+ rehydrate_suggestion,
+ )
+ from repowise.core.persistence.crud import get_refactoring_suggestion
+
+ row = await get_refactoring_suggestion(self._session, self._repository_id, plan_id)
+ 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)
+ metric_by_path, centrality = await self._rank_inputs(row.file_path)
+ built = build_recommendations(
+ [rehydrate_suggestion(row)],
+ metric_by_path=metric_by_path,
+ centrality=centrality,
+ validations={0: _stored_validation(owner, row.public_id)},
+ )
+ payload = built[0].as_dict() if built else _plan_payload(row)
+ payload["id"] = row.public_id or row.id
+ payload["status"] = row.status
+ result: dict[str, Any] = {"resolved": True, "plan_id": plan_id, "plan": payload}
+ if owner is not None:
+ # On the envelope as well as the plan: a plan is a step of one
+ # opportunity, and that is the unit the caller should move to.
+ payload["opportunity_id"] = owner.opportunity_id
+ result["opportunity_id"] = owner.opportunity_id
+ result["next_action"] = {
+ "tool": "get_health",
+ "arguments": {"opportunity_id": owner.opportunity_id},
+ }
+ return result
+
+ async def _rank_inputs(self, file_path: str) -> tuple[dict[str, Any], dict[str, float]]:
+ """The two rank inputs for one file, as seeks rather than repo reads.
+
+ ``build_recommendations`` wants a metric per path and an in-degree per
+ node. Serving one plan used to load every metric row and every graph
+ metric in the repository to supply them for a single file.
+ """
+ from repowise.core.persistence.models import GraphMetric, HealthFileMetric
+
+ metric = (
+ await self._session.execute(
+ select(HealthFileMetric).where(
+ HealthFileMetric.repository_id == self._repository_id,
+ HealthFileMetric.file_path == file_path,
+ )
+ )
+ ).scalar_one_or_none()
+ rows = (
+ await self._session.execute(
+ select(GraphMetric.node_id, GraphMetric.in_degree).where(
+ GraphMetric.repository_id == self._repository_id,
+ or_(
+ GraphMetric.node_id == file_path,
+ # The separator matters: a bare ``f"{file_path}%"`` also
+ # matches a sibling whose name extends this one, so
+ # ``Component.ts`` would absorb ``Component.tsx``.
+ GraphMetric.node_id.like(f"{file_path}::%"),
+ ),
+ )
+ )
+ ).all()
+ return (
+ {metric.file_path: metric} if metric is not None else {},
+ {node_id: float(in_degree or 0.0) for node_id, in_degree in rows},
+ )
+
+ # -- internals --------------------------------------------------------
+
+ async def _owning_opportunity(self, public_id: str | None, file_path: str) -> Any | None:
+ """The opportunity holding this plan, found through its file.
+
+ One indexed lookup on ``(repository_id, status, file_path)``: a plan
+ belongs to at most one file's opportunity, so the file narrows it to a
+ single candidate and the step list confirms it.
+ """
+ if not public_id:
+ return None
+ rows = list(
+ (
+ await self._session.execute(
+ select(RefactoringOpportunity)
+ .where(
+ RefactoringOpportunity.repository_id == self._repository_id,
+ RefactoringOpportunity.status == "open",
+ RefactoringOpportunity.file_path == file_path,
+ )
+ .limit(5)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ for row in rows:
+ steps = _loads(row.details_json).get("steps") or []
+ if any(step.get("plan_id") == public_id for step in steps):
+ return row
+ return None
+
+ async def _plans_for(self, plan_ids: list[str]) -> list[dict[str, Any]]:
+ """The member plans' payloads, in one indexed query over the page."""
+ if not plan_ids:
+ return []
+ rows = list(
+ (
+ await self._session.execute(
+ select(RefactoringSuggestion).where(
+ RefactoringSuggestion.repository_id == self._repository_id,
+ RefactoringSuggestion.public_id.in_(plan_ids),
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ by_id = {row.public_id: row for row in rows}
+ return [_plan_payload(by_id[pid]) for pid in plan_ids if pid in by_id]
+
+ def _next_actions(self, row: Any, steps: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """Structured follow-ups, so a drill-down ends somewhere rather than stops."""
+ actions: list[dict[str, Any]] = []
+ first = steps[0] if steps else None
+ if first and first.get("line_start") is not None and first.get("line_end") is not None:
+ actions.append(
+ {
+ "why": "read the span the first step names",
+ "tool": "get_symbol",
+ "arguments": {
+ "symbol_id": f"{first['file_path']}:{first['line_start']}-{first['line_end']}"
+ },
+ }
+ )
+ actions.append(
+ {
+ "why": "what history says about touching this file",
+ "tool": "get_risk",
+ "arguments": {"targets": [row.file_path]},
+ }
+ )
+ if row.evidence_total:
+ actions.append(
+ {
+ "why": "page the supporting observations",
+ "tool": "get_health",
+ "arguments": {
+ "opportunity_id": row.opportunity_id,
+ "only": ["refactoring_evidence"],
+ },
+ }
+ )
+ return actions
+
+ def _serialize(
+ self, row: Any, *, steps_limit: int | None = None, evidence_limit: int = 0
+ ) -> dict[str, Any]:
+ details = _loads(row.details_json)
+ steps = list(details.get("steps") or [])
+ evidence = list(details.get("evidence") or [])
+ payload: dict[str, Any] = {
+ "opportunity_id": row.opportunity_id,
+ "refactoring_model_version": row.refactoring_model_version,
+ "status": row.status,
+ "file_path": row.file_path,
+ "lead_biomarker": row.lead_biomarker,
+ "lead_refactoring_type": row.lead_refactoring_type,
+ "addresses_primary_problem": row.addresses_primary_problem,
+ "effort_bucket": row.effort_bucket,
+ "confidence": row.confidence,
+ "step_count": row.step_count,
+ "mechanical_steps": row.mechanical_steps,
+ "judgment_steps": row.judgment_steps,
+ "evidence_total": row.evidence_total,
+ "affected_files_total": row.affected_files_total,
+ "recoverable_health": round(float(row.recoverable_health), 3),
+ "rank_score": round(float(row.rank_score), 4),
+ "rank_position": row.rank_position,
+ "queue_position": row.queue_position,
+ "rank_factors": details.get("rank_factors") or {},
+ "why_ranked": details.get("why_ranked") or [],
+ }
+ if steps_limit is not None:
+ kept = steps[: max(steps_limit, 0)]
+ payload["steps"] = kept
+ payload["steps_total"] = len(steps)
+ payload["steps_emitted"] = len(kept)
+ if len(kept) < len(steps):
+ payload["steps_reduced_reason"] = "limit"
+ if evidence_limit:
+ payload.update(evidence_block(evidence[:evidence_limit], len(evidence), 0))
+ return payload
+
+
+def _stored_validation(owner: Any, public_id: str | None) -> Any:
+ """The validation profile the finalizer resolved for this step.
+
+ Test reachability is a graph walk over the whole unanswered set; it belongs
+ at index time, and this reads its result rather than repeating it.
+ """
+ from repowise.core.analysis.health.refactoring.recommendations import (
+ ValidationPlan,
+ ValidationTarget,
+ )
+
+ if owner is None or not public_id:
+ return None
+ details = _loads(owner.details_json)
+ wanted = next(
+ (
+ step.get("validation_profile_id")
+ for step in (details.get("steps") or [])
+ if step.get("plan_id") == public_id
+ ),
+ None,
+ )
+ if not wanted:
+ return None
+ profile = next(
+ (p for p in (details.get("validation_profiles") or []) if p.get("id") == wanted),
+ None,
+ )
+ if profile is None:
+ return None
+ target_fields = set(ValidationTarget.__dataclass_fields__)
+ values = {
+ key: value
+ for key, value in profile.items()
+ if key in ValidationPlan.__dataclass_fields__
+ }
+ values["targets"] = [
+ ValidationTarget(**{k: v for k, v in target.items() if k in target_fields})
+ for target in (profile.get("targets") or [])
+ if isinstance(target, dict)
+ ]
+ return ValidationPlan(**values)
+
+
+def _plan_payload(row: Any) -> dict[str, Any]:
+ """The stored plan, without re-hydrating rank or validation.
+
+ Detail reads the payload the detector wrote and the finalizer already
+ validated; recomputing benefit and coverage here is what made a one-row
+ lookup cost the repository.
+ """
+ return {
+ "id": row.public_id or row.id,
+ "refactoring_type": row.refactoring_type,
+ "file_path": row.file_path,
+ "target_symbol": row.target_symbol,
+ "line_start": row.line_start,
+ "line_end": row.line_end,
+ "plan": _loads(row.plan_json),
+ "evidence": _loads(row.evidence_json),
+ "blast_radius": _loads(row.blast_radius_json),
+ "impact_delta": row.impact_delta,
+ "effort_bucket": row.effort_bucket,
+ "confidence": row.confidence,
+ "source_biomarker": row.source_biomarker,
+ "status": row.status,
+ }
+
+
+def _loads(raw: str | None) -> dict[str, Any]:
+ if not raw:
+ return {}
+ try:
+ value = json.loads(raw)
+ except (TypeError, ValueError):
+ return {}
+ return value if isinstance(value, dict) else {}
+
+
+__all__ = [
+ "CANONICAL_ORDERS",
+ "CANONICAL_VIEWS",
+ "DEFAULT_VIEW",
+ "RefactoringHealthService",
+ "RefactoringPage",
+ "RefactoringQuery",
+ "evidence_block",
+ "parse_query",
+ "plan_view",
+]
diff --git a/packages/types/src/refactoring.ts b/packages/types/src/refactoring.ts
index c877e423c..912bfdc1a 100644
--- a/packages/types/src/refactoring.ts
+++ b/packages/types/src/refactoring.ts
@@ -115,3 +115,241 @@ export interface GeneratedCode {
validation: Record<string, unknown>;
spans: GeneratedSpan[];
}
+
+/* ---------------------------------------------------------------------------
+ * Composed opportunities (repowise 0.47.0).
+ *
+ * The product unit is a file's composed refactoring: the diagnosis it leads
+ * with, its steps in an order that is safe to apply, and the observations
+ * behind it. Plans remain addressable and unchanged; a step names one.
+ * Every field here is additive, so an older server simply omits the block.
+ * ------------------------------------------------------------------------ */
+
+/** ``mechanical`` only when the detector's proof obligations all hold. */
+export type StepClassification = "mechanical" | "judgment";
+
+export interface StepApplicability {
+ classification: StepClassification;
+ /** Closed vocabulary; see docs/layers/REFACTORING.md. */
+ reasons: string[];
+ facts: Record<string, unknown>;
+ /** Facts the layer could not establish. Never silently false. */
+ unknowns: string[];
+}
+
+export interface OpportunityStep {
+ /** The plan this step is; resolves through the plan detail route. */
+ plan_id: string;
+ refactoring_type: RefactoringType;
+ target_symbol: string;
+ file_path: string;
+ line_start: number | null;
+ line_end: number | null;
+ effort_bucket: EffortBucket;
+ confidence: Confidence;
+ impact_delta: number;
+ source_biomarker: string;
+ /**
+ * An earlier step that moves this step's symbol to another file. When set,
+ * this step's file and span say where the symbol was: locate it again before
+ * applying. Any surface rendering an ordered list has to say so.
+ */
+ relocated_by: string | null;
+ applicability: StepApplicability;
+ /** Findings this step's cause produced, for a round trip to the diagnosis. */
+ finding_ids?: string[];
+ validation_profile_id?: string;
+}
+
+/** A supporting observation. Never an instruction to change anything. */
+export interface OpportunityEvidence {
+ plan_id: string;
+ refactoring_type: RefactoringType;
+ target_symbol: string;
+ source_biomarker: string;
+ summary: Record<string, unknown>;
+}
+
+export type OpportunityStatus = "open" | "acknowledged" | "resolved";
+
+export interface RefactoringOpportunity {
+ /** ``refop<model>_<digest>`` over the member plan ids. */
+ opportunity_id: string;
+ refactoring_model_version: number;
+ status: OpportunityStatus;
+ file_path: string;
+ /** The file's dominant finding; null when none was recorded. */
+ lead_biomarker: string | null;
+ lead_refactoring_type: RefactoringType | "";
+ /**
+ * Tri-state. ``null`` means no dominant finding was available to compare
+ * against, which is not the same claim as ``false``.
+ */
+ addresses_primary_problem: boolean | null;
+ effort_bucket: EffortBucket;
+ confidence: Confidence;
+ step_count: number;
+ mechanical_steps: number;
+ judgment_steps: number;
+ evidence_total: number;
+ affected_files_total: number;
+ recoverable_health: number;
+ rank_score: number;
+ rank_position: number;
+ /** Position in the diversified default order. */
+ queue_position: number;
+ rank_factors: Record<string, number>;
+ why_ranked: Array<{ factor: string; value: number }>;
+ steps?: OpportunityStep[];
+ steps_total?: number;
+ steps_emitted?: number;
+ steps_reduced_reason?: string;
+ /** Present only when the queue row was asked for inline evidence. */
+ evidence?: OpportunityEvidence[];
+ evidence_emitted?: number;
+ evidence_truncated?: boolean;
+ evidence_reduced_reason?: string;
+ evidence_next_cursor?: number;
+}
+
+/**
+ * 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.
+ */
+export type RefactoringOpportunityDetail =
+ | RefactoringOpportunityDetailResolved
+ | RefactoringOpportunityDetailUnresolved;
+
+export interface RefactoringOpportunityDetailUnresolved {
+ resolved: false;
+ opportunity_id: string;
+ reason: "unknown_opportunity_id";
+ /** MCP only: tells a stale-model id apart from one never minted here. */
+ model_state?: {
+ state: "current" | "stale_model" | "unrecognized";
+ public_id: string;
+ requested_model_version: number | null;
+ refactoring_model_version: number;
+ refresh_required: boolean;
+ };
+}
+
+export interface RefactoringOpportunityDetailResolved extends RefactoringOpportunity {
+ resolved: true;
+ steps: OpportunityStep[];
+ steps_total: number;
+ steps_emitted: number;
+ steps_reduced_reason?: string;
+ steps_next_cursor?: number;
+ evidence: OpportunityEvidence[];
+ evidence_emitted: number;
+ evidence_truncated: boolean;
+ evidence_reduced_reason?: string;
+ evidence_next_cursor?: number;
+ affected_files: string[];
+ /** Absent when no finding on this file is addressable by id. */
+ lead_finding_ids?: string[];
+ validation_profiles: Array<{ id: string } & RecommendationValidation>;
+ /** The member plans' payloads, so the steps are executable in one call. */
+ plans: RefactoringPlan[];
+ next_actions: Array<{ why: string; tool: string; arguments: Record<string, unknown> }>;
+ /** Present only when a step carries `relocated_by`. */
+ ordering_note?: string;
+}
+
+/** Named orderings for the queue. ``diversified`` is the default. */
+export type RefactoringView = "diversified" | "canonical" | "file_spread";
+
+/** No stored analysis: the counts genuinely do not exist, so none are present. */
+export interface RefactoringRollupUnavailable {
+ status: "unavailable";
+ reason: "no_refactoring_analysis";
+ detail: string;
+}
+
+export interface RefactoringRollupAvailable {
+ status: "available";
+ opportunities_total: number;
+ files_total: number;
+ steps_total: number;
+ mechanical_steps_total: number;
+ judgment_steps_total: number;
+ by_lead_type: Record<string, number>;
+ by_effort: Record<string, number>;
+ by_confidence: Record<string, number>;
+ by_status: Record<string, number>;
+ addresses_primary_problem: { yes: number; no: number; unknown: number };
+ /** The same lead the directive reads; null when nothing is open. */
+ lead: RefactoringDirectiveLead | null;
+ refactoring_model_version: number;
+ analyzed_commit: string | null;
+ /** Present on the MCP block only. */
+ facets?: Record<string, Record<string, number>>;
+ next_call?: string;
+}
+
+export type RefactoringOpportunityRollup =
+ | RefactoringRollupAvailable
+ | RefactoringRollupUnavailable;
+
+export interface RefactoringDirectiveLead {
+ opportunity_id: string;
+ file_path: string;
+ lead_biomarker: string | null;
+ lead_refactoring_type: string;
+ addresses_primary_problem: boolean | null;
+ step_count: number;
+ mechanical_steps: number;
+ judgment_steps: number;
+ effort_bucket: EffortBucket;
+ confidence: Confidence;
+ recoverable_health: number;
+ status: OpportunityStatus;
+}
+
+/**
+ * The Level-0 lead on a bare health call. Three shapes, one discriminant:
+ * there is work, there is none, or there is no analysis to answer from.
+ */
+export type RefactoringDirective =
+ | RefactoringDirectiveAvailable
+ | { status: "clear"; reason: "no_open_opportunities"; detail: string; opportunities_total: number }
+ | RefactoringRollupUnavailable;
+
+export interface RefactoringDirectiveAvailable {
+ status: "available";
+ opportunity_id: string;
+ fix_first: string;
+ reason: string | null;
+ lead_refactoring_type: string;
+ steps: number;
+ mechanical_steps: number;
+ judgment_steps: number;
+ effort_bucket: EffortBucket;
+ confidence: Confidence;
+ recovers_health_points: number;
+ addresses_primary_problem: boolean | null;
+ opportunities_total: number;
+ next_action: { tool: string; arguments: Record<string, unknown> };
+ /** Set when the steps do not address the file's dominant finding, or cannot say. */
+ note?: string;
+}
+
+export interface RefactoringOpportunityPage {
+ items: RefactoringOpportunity[];
+ total: number;
+ offset: number;
+ has_more: boolean;
+ next_offset: number | null;
+ facets: Record<string, Record<string, number>>;
+ summary: RefactoringOpportunityRollup | null;
+ /** Values the server could not admit, named rather than dropped. */
+ ignored_arguments?: Record<string, string>;
+}
+
+/** ``GET /api/repos/{repo_id}/refactoring/summary``. */
+export interface RefactoringSummaryResponse {
+ summary: RefactoringOpportunityRollup;
+ directive: RefactoringDirective;
+}
diff --git a/tests/unit/persistence/test_refactoring_opportunity_store.py b/tests/unit/persistence/test_refactoring_opportunity_store.py
new file mode 100644
index 000000000..72b6f38fd
--- /dev/null
+++ b/tests/unit/persistence/test_refactoring_opportunity_store.py
@@ -0,0 +1,95 @@
+"""The materialized opportunity store: migration shape and model agreement."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def _tables(db_path: Path) -> set[str]:
+ conn = sqlite3.connect(db_path)
+ try:
+ return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+ finally:
+ conn.close()
+
+
+def _columns(db_path: Path, table: str) -> set[str]:
+ conn = sqlite3.connect(db_path)
+ try:
+ return {row[1] for row in conn.execute(f'PRAGMA table_info("{table}")')}
+ finally:
+ conn.close()
+
+
+def _indexes(db_path: Path, table: str) -> set[str]:
+ conn = sqlite3.connect(db_path)
+ try:
+ return {row[1] for row in conn.execute(f'PRAGMA index_list("{table}")')}
+ finally:
+ conn.close()
+
+
+def _alembic_config(db_path: Path):
+ from alembic.config import Config
+
+ root = Path(__file__).resolve().parents[3] / "packages" / "core"
+ # Built without the ini file on purpose; see the performance store's twin.
+ config = Config()
+ config.set_main_option("script_location", str(root / "alembic"))
+ config.set_main_option("sqlalchemy.url", f"sqlite+aiosqlite:///{db_path}")
+ return config
+
+
+def test_the_migration_upgrades_and_rolls_back(tmp_path: Path) -> None:
+ from alembic import command
+
+ db_path = tmp_path / "wiki.db"
+ config = _alembic_config(db_path)
+
+ command.upgrade(config, "0059")
+ assert {"refactoring_opportunities", "refactoring_summaries"} <= _tables(db_path)
+ assert {
+ "opportunity_id",
+ "refactoring_model_version",
+ "status",
+ "rank_position",
+ "queue_position",
+ "addresses_primary_problem",
+ "details_json",
+ } <= _columns(db_path, "refactoring_opportunities")
+
+ command.downgrade(config, "0058")
+ assert not {"refactoring_opportunities", "refactoring_summaries"} & _tables(db_path)
+
+
+def test_the_migration_and_the_model_declare_the_same_shape(tmp_path: Path) -> None:
+ """A local store is built by ``init_db`` and never sees Alembic.
+
+ So the two descriptions have to agree, or a hosted store and a local one
+ disagree about the table this phase serves everything from.
+ """
+ import asyncio
+
+ from alembic import command
+
+ from repowise.core.persistence.database import create_engine, init_db
+
+ migrated = tmp_path / "migrated.db"
+ command.upgrade(_alembic_config(migrated), "head")
+
+ declared = tmp_path / "declared.db"
+
+ async def _build() -> None:
+ engine = create_engine(f"sqlite+aiosqlite:///{declared}")
+ await init_db(engine)
+ await engine.dispose()
+
+ asyncio.run(_build())
+
+ for table in ("refactoring_opportunities", "refactoring_summaries"):
+ assert _columns(migrated, table) == _columns(declared, table), table
+ # Index names too: the queue reads through them by name in the query plan.
+ assert _indexes(migrated, "refactoring_opportunities") == _indexes(
+ declared, "refactoring_opportunities"
+ )
diff --git a/tests/unit/server/mcp/test_cross_tool_reference_contracts.py b/tests/unit/server/mcp/test_cross_tool_reference_contracts.py
index 072a87a6c..fe4e52c51 100644
--- a/tests/unit/server/mcp/test_cross_tool_reference_contracts.py
+++ b/tests/unit/server/mcp/test_cross_tool_reference_contracts.py
@@ -542,6 +542,14 @@ async def test_canonical_emitter_reference_inventory(reference_repo, health_data
[context_target], include=["callers", "callees"]
)
)
+ # The plan list is an opt-in projection now: ``include=["refactoring"]``
+ # leads with composed opportunities. The plan reference is still emitted by
+ # get_health, so the inventory asks the call that carries it.
+ responses["get_health"].append(
+ await tool_middleware(get_health)(
+ include=["refactoring"], only=["refactoring_plans"]
+ )
+ )
inventory = {
emitter: [
ref
diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.py
index 712025066..712e98f5b 100644
--- a/tests/unit/server/mcp/test_health.py
+++ b/tests/unit/server/mcp/test_health.py
@@ -21,9 +21,14 @@ async def test_get_health_dashboard(setup_mcp, health_data):
assert result["mode"] == "dashboard"
assert result["kpis"]["file_count"] == 2
assert result["kpis"]["worst_performer_path"] == "src/auth/service.py"
- # Two leads, both first: the defect one and the performance pillar's own,
- # which carries no defect impact and so never competed for the first.
- assert list(result)[:3] == ["directive", "performance_directive", "mode"]
+ # Three leads, all first: the defect one, and one per pillar that carries
+ # no defect impact and so never competed for it.
+ assert list(result)[:4] == [
+ "directive",
+ "refactoring_directive",
+ "performance_directive",
+ "mode",
+ ]
assert "high_leverage_files" in result
assert "worst_files" not in result
assert result["secondary_rankings"]["worst_files"]["total"] == 2
@@ -186,10 +191,16 @@ async def test_get_health_dashboard_surfaces_leverage(setup_mcp, health_data):
@pytest.mark.asyncio
async def test_get_health_refactoring_capped_and_leverage_ranked(setup_mcp, health_data):
- """refactoring_plans is bounded by limit and reports the honest total."""
+ """refactoring_plans is bounded by limit and reports the honest total.
+
+ Named explicitly: ``include=["refactoring"]`` leads with the composed
+ opportunity queue, and the raw plan list is the opt-in projection.
+ """
from repowise.server.mcp_server import get_health
- result = await get_health(include=["refactoring"], limit=5)
+ result = await get_health(
+ include=["refactoring"], only=["refactoring_plans"], limit=5
+ )
assert "refactoring_plans" in result
assert len(result["refactoring_plans"]) <= 5
# Honest truncation signal is always present when refactoring is requested.
@@ -285,9 +296,14 @@ def test_validation_profiles_deduplicate_without_dropping_commands_or_target_tes
@pytest.mark.asyncio
-async def test_target_freshness_uses_only_the_requested_health_rows(
- setup_mcp, health_data, session
-):
+async def test_freshness_is_a_repository_fact_in_every_mode(setup_mcp, health_data, session):
+ """Whether the analysis recorded its commit cannot depend on the mode asked.
+
+ Each mode used to compute "latest analysed row" over whatever rows it was
+ reporting on, so a call scoped to an older file reported that file's commit
+ as the repository's, and a detail call could read ``available`` at the same
+ instant the dashboard read ``degraded``. The block is repository-wide now.
+ """
from datetime import UTC, datetime
from sqlalchemy import select
@@ -311,10 +327,17 @@ async def test_target_freshness_uses_only_the_requested_health_rows(
by_path["src/db/models.py"].analyzed_commit = "b" * 40
await session.flush()
- result = await get_health(targets=["src/auth/service.py"], only=["metrics"])
- assert result["_meta"]["health_analyzed_at"].startswith("2025-01-01")
- assert result["_meta"]["health_analyzed_commit"] == "a" * 12
- assert "health_analyzed_commits_distinct" not in result["_meta"]
+ scoped = await get_health(targets=["src/auth/service.py"], only=["metrics"])
+ dashboard = await get_health(only=["kpis"])
+ for meta in (scoped["_meta"], dashboard["_meta"]):
+ # The repository's newest analysed row, not the scoped file's.
+ assert meta["health_analyzed_at"].startswith("2026-01-01")
+ assert meta["health_analyzed_commit"] == "b" * 12
+ assert meta["health_analyzed_commits_distinct"] == 2
+ assert (
+ scoped["_meta"]["health_analysis"]["status"]
+ == dashboard["_meta"]["health_analysis"]["status"]
+ )
@pytest.mark.asyncio
@@ -1592,9 +1615,14 @@ async def test_refactoring_plans_spread_across_files(setup_mcp, health_data, ses
],
)
- plans = (await get_health(include=["refactoring"], limit=4, refactoring_view="file_spread"))[
- "refactoring_plans"
- ]
+ plans = (
+ await get_health(
+ include=["refactoring"],
+ only=["refactoring_plans"],
+ limit=4,
+ refactoring_view="file_spread",
+ )
+ )["refactoring_plans"]
assert len(plans) == 4
# Both files are represented rather than the worst file owning the list.
assert len({p["file_path"] for p in plans}) == 2
@@ -1628,7 +1656,9 @@ async def test_refactoring_spread_is_exhaustive_when_one_file_has_them_all(
],
)
- plans = (await get_health(include=["refactoring"], limit=4))["refactoring_plans"]
+ plans = (
+ await get_health(include=["refactoring"], only=["refactoring_plans"], limit=4)
+ )["refactoring_plans"]
assert len(plans) == 4
assert {p["file_path"] for p in plans} == {"src/auth/service.py"}
diff --git a/tests/unit/server/mcp/test_health_semantics_matrix.py b/tests/unit/server/mcp/test_health_semantics_matrix.py
index 948e8c7bc..6d51ebe7c 100644
--- a/tests/unit/server/mcp/test_health_semantics_matrix.py
+++ b/tests/unit/server/mcp/test_health_semantics_matrix.py
@@ -80,7 +80,6 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (
invariant_paths=(
"metrics",
"findings",
- "refactoring_plans",
"_meta.health_analysis",
"_meta.health_semantics",
),
@@ -108,7 +107,6 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (
invariant_paths=(
"metrics",
"findings",
- "refactoring_plans",
"_meta.health_analysis",
"_meta.health_semantics",
),
@@ -206,7 +204,9 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (
),
comparison="independent performance and refactoring projections",
comparison_kwargs=_frozen(
- include=("performance", "refactoring"), limit=1
+ include=("performance", "refactoring"),
+ only=("performance_opportunities", "refactoring_plans"),
+ limit=1,
),
plans_requested=True,
expected_plan_count=1,
@@ -244,7 +244,6 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (
recovery="none",
invariant_paths=(
"findings",
- "refactoring_plans",
"_meta.health_analysis",
"_meta.health_semantics",
),
@@ -495,7 +494,10 @@ async def test_sealed_projection_invariance_uses_independent_calls(setup_mcp, he
assert directive["_meta"]["health_analysis"] == dashboard["_meta"]["health_analysis"]
broad = await get_health(
- targets=["src/auth/service.py"], include=["refactoring"], limit=2
+ targets=["src/auth/service.py"],
+ include=["refactoring"],
+ only=["metrics", "findings", "refactoring_plans", "kpis"],
+ limit=2,
)
narrow = await get_health(
targets=["src/auth/service.py"],
diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.py
new file mode 100644
index 000000000..007e375fa
--- /dev/null
+++ b/tests/unit/server/test_refactoring_opportunities.py
@@ -0,0 +1,629 @@
+"""Serving contracts for composed refactoring opportunities.
+
+REST and MCP read one service over one materialized read model, so the two
+must answer identically, and a page must cost its page rather than the
+repository. Both are asserted here, the second by counting statements rather
+than by wall clock.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import event
+
+from repowise.core.persistence import crud
+
+
+async def _repo(client: AsyncClient) -> str:
+ repo_dir = Path(tempfile.mkdtemp()) / "opp-repo"
+ repo_dir.mkdir(exist_ok=True)
+ (repo_dir / ".git").mkdir(exist_ok=True)
+ resp = await client.post(
+ "/api/repos",
+ json={
+ "index": False,
+ "name": "opp-repo",
+ "local_path": str(repo_dir),
+ "url": "https://github.com/example/opp-repo",
+ },
+ )
+ assert resp.status_code == 201
+ return resp.json()["id"]
+
+
+def _plan(path: str, symbol: str, **over: Any) -> dict[str, Any]:
+ plan = {
+ "refactoring_type": "extract_method",
+ "file_path": path,
+ "target_symbol": symbol,
+ "line_start": 10,
+ "line_end": 30,
+ "plan": {"extracted_name": f"_{symbol}_part", "local_scope": True},
+ "evidence": {"ccn_removed": 6, "slice_nloc": 20},
+ "impact_delta": 1.0,
+ "effort_bucket": "S",
+ "blast_radius": {"scope": "local"},
+ "confidence": "high",
+ "source_biomarker": "complex_method",
+ }
+ plan.update(over)
+ return plan
+
+
+def _finding(path: str, biomarker: str = "complex_method", impact: float = 3.0) -> dict[str, Any]:
+ return {
+ "file_path": path,
+ "biomarker_type": biomarker,
+ "severity": "high",
+ "function_name": "f",
+ "line_start": 10,
+ "line_end": 30,
+ "details": {},
+ "health_impact": impact,
+ "reason": "seeded",
+ "dimension": "defect",
+ }
+
+
+async def _seed(client: AsyncClient, app, *, files: int = 8) -> str:
+ """A repository whose plans compose into one opportunity per file."""
+ repo_id = await _repo(client)
+ paths = [f"pkg{i % 3}/mod{i}.py" for i in range(files)]
+ async with app.state.session_factory() as session:
+ await crud.save_health_findings(session, repo_id, [_finding(p) for p in paths])
+ await crud.save_refactoring_suggestions(
+ session,
+ repo_id,
+ [_plan(path, f"sym{i}", impact_delta=float(files - i)) for i, path in enumerate(paths)],
+ )
+ await crud.finalize_refactoring_opportunities(session, repo_id, analyzed_commit="c" * 40)
+ await session.commit()
+ return repo_id
+
+
+async def _mcp(app):
+ """Point the MCP tool at this test's database and hand back ``get_health``."""
+ import asyncio
+
+ from repowise.server.mcp_server import _state
+ from repowise.server.mcp_server.tool_health import get_health
+
+ _state._session_factory = app.state.session_factory
+ _state._repo_path = "/tmp/opp-repo"
+ _state._registry = None
+ _state._vector_store_ready = asyncio.Event()
+ _state._vector_store_ready.set()
+ return get_health
+
+
+# ---------------------------------------------------------------------------
+# The writer
+# ---------------------------------------------------------------------------
+
+
+async def test_finalizer_composes_one_opportunity_per_file(client, app):
+ repo_id = await _seed(client, app, files=5)
+ resp = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["total"] == 5
+ assert len({item["file_path"] for item in body["items"]}) == 5
+ for item in body["items"]:
+ assert item["opportunity_id"].startswith("refop2_")
+ assert item["step_count"] == 1
+ # The lead was supplied, so this is a real answer rather than unknown.
+ assert item["addresses_primary_problem"] is True
+
+
+async def test_addresses_primary_problem_is_unknown_without_a_lead(client, app):
+ """A file with no recorded finding gets ``None``, never a quiet ``False``."""
+ repo_id = await _repo(client)
+ async with app.state.session_factory() as session:
+ await crud.save_refactoring_suggestions(session, repo_id, [_plan("pkg/x.py", "s")])
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ assert body["items"][0]["addresses_primary_problem"] is None
+
+
+async def test_an_opportunity_nobody_composes_resolves_rather_than_vanishing(client, app):
+ repo_id = await _seed(client, app, files=3)
+ before = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ held = before["items"][0]["opportunity_id"]
+ async with app.state.session_factory() as session:
+ # A run that detects nothing resolves every plan, so nothing composes.
+ await crud.save_refactoring_suggestions(session, repo_id, [])
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+ after = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ assert after["total"] == 0
+ # The id an agent is holding still resolves, and reads as resolved.
+ detail = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{held}")
+ assert detail.status_code == 200
+ assert detail.json()["status"] == "resolved"
+
+
+async def test_lifecycle_rolls_up_from_the_member_plans(client, app):
+ repo_id = await _seed(client, app, files=2)
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ detail = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities/"
+ f"{body['items'][0]['opportunity_id']}"
+ )
+ ).json()
+ plan_id = detail["steps"][0]["plan_id"]
+ async with app.state.session_factory() as session:
+ await crud.update_refactoring_suggestion_status(session, repo_id, plan_id, "acknowledged")
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+ refreshed = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities/{detail['opportunity_id']}"
+ )
+ ).json()
+ assert refreshed["status"] == "acknowledged"
+
+
+# ---------------------------------------------------------------------------
+# REST == MCP
+# ---------------------------------------------------------------------------
+
+
+async def test_rest_and_mcp_agree_on_order_totals_and_detail(client, app):
+ repo_id = await _seed(client, app, files=9)
+ get_health = await _mcp(app)
+
+ rest = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 6}
+ )
+ ).json()
+ mcp = await get_health(
+ include=["refactoring"], only=["refactoring_opportunities"], limit=6
+ )
+
+ assert rest["total"] == mcp["refactoring_opportunities_total"]
+ assert [item["opportunity_id"] for item in rest["items"]] == [
+ item["opportunity_id"] for item in mcp["refactoring_opportunities"]
+ ]
+ assert [item["rank_position"] for item in rest["items"]] == [
+ item["rank_position"] for item in mcp["refactoring_opportunities"]
+ ]
+
+ target = rest["items"][0]["opportunity_id"]
+ rest_detail = (
+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{target}")
+ ).json()
+ mcp_detail = await get_health(opportunity_id=target)
+ for key in (
+ "opportunity_id",
+ "file_path",
+ "lead_biomarker",
+ "step_count",
+ "rank_score",
+ "addresses_primary_problem",
+ "steps",
+ ):
+ assert rest_detail[key] == mcp_detail[key], key
+
+
+async def test_rest_and_mcp_agree_under_a_view(client, app):
+ repo_id = await _seed(client, app, files=9)
+ get_health = await _mcp(app)
+ for view in ("canonical", "diversified", "file_spread"):
+ rest = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities",
+ params={"limit": 6, "view": view},
+ )
+ ).json()
+ mcp = await get_health(
+ include=["refactoring"],
+ only=["refactoring_opportunities"],
+ limit=6,
+ refactoring_view=view,
+ )
+ assert [i["opportunity_id"] for i in rest["items"]] == [
+ i["opportunity_id"] for i in mcp["refactoring_opportunities"]
+ ], view
+
+
+async def test_an_unknown_filter_value_is_named_not_swallowed(client, app):
+ repo_id = await _seed(client, app, files=3)
+ body = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities",
+ params={"refactoring_type": "extract_nonsense"},
+ )
+ ).json()
+ # A misspelling must not read as "the repository is clean".
+ assert body["ignored_arguments"] == {"refactoring_type": "extract_nonsense"}
+ assert body["total"] == 3
+
+
+# ---------------------------------------------------------------------------
+# Cost
+# ---------------------------------------------------------------------------
+
+
+def _counter(engine) -> list[str]:
+ seen: list[str] = []
+
+ @event.listens_for(engine.sync_engine, "before_cursor_execute")
+ def _before(conn, cursor, statement, params, context, executemany):
+ seen.append(statement)
+
+ return seen
+
+
+async def test_queue_query_count_is_constant_in_page_size_and_row_count(
+ client, app, test_engine
+):
+ """The statement count must not move when the page or the repository grows."""
+ small = await _seed(client, app, files=4)
+ large = await _seed(client, app, files=40)
+ counts = {}
+ seen = _counter(test_engine)
+ for label, repo_id, limit in (
+ ("small-1", small, 1),
+ ("small-20", small, 20),
+ ("large-1", large, 1),
+ ("large-20", large, 20),
+ ("large-100", large, 100),
+ ):
+ seen.clear()
+ resp = await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": limit}
+ )
+ assert resp.status_code == 200
+ counts[label] = len(seen)
+ assert len(set(counts.values())) == 1, counts
+
+
+async def test_a_deep_offset_costs_the_same_as_the_first_page(client, app, test_engine):
+ repo_id = await _seed(client, app, files=40)
+ seen = _counter(test_engine)
+ seen.clear()
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 5, "offset": 0}
+ )
+ first = len(seen)
+ seen.clear()
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 5, "offset": 30}
+ )
+ assert len(seen) == first
+
+
+async def test_point_lookups_are_bounded_and_do_not_scale_with_the_repository(
+ client, app, test_engine
+):
+ """Resolving one id used to hydrate every open plan in the repository."""
+ small = await _seed(client, app, files=4)
+ large = await _seed(client, app, files=60)
+ get_health = await _mcp(app)
+ seen = _counter(test_engine)
+ costs = {}
+ for label, repo_id in (("small", small), ("large", large)):
+ body = (
+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")
+ ).json()
+ target = body["items"][0]["opportunity_id"]
+ seen.clear()
+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{target}")
+ costs[f"{label}-opportunity"] = len(seen)
+
+ detail = (
+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{target}")
+ ).json()
+ seen.clear()
+ await get_health(plan_id=detail["steps"][0]["plan_id"])
+ costs[f"{label}-plan"] = len(seen)
+
+ assert costs["small-opportunity"] == costs["large-opportunity"], costs
+ assert costs["small-plan"] == costs["large-plan"], costs
+ # The service's own share of an opportunity lookup: the row and its plans.
+ assert costs["large-opportunity"] <= 5, costs
+
+
+async def test_a_files_opportunities_are_one_indexed_lookup(client, app, test_engine):
+ repo_id = await _seed(client, app, files=40)
+ seen = _counter(test_engine)
+ seen.clear()
+ body = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities",
+ params={"file_path": "pkg0/mod0.py"},
+ )
+ ).json()
+ assert body["total"] == 1
+ assert body["items"][0]["file_path"] == "pkg0/mod0.py"
+
+
+# ---------------------------------------------------------------------------
+# The agent contract
+# ---------------------------------------------------------------------------
+
+
+async def test_bare_get_health_carries_one_bounded_refactoring_directive(client, app):
+ repo_id = await _seed(client, app, files=12)
+ get_health = await _mcp(app)
+ result = await get_health()
+ directive = result["refactoring_directive"]
+ assert directive["status"] == "available"
+ assert directive["opportunity_id"].startswith("refop2_")
+ assert directive["next_action"]["arguments"]["opportunity_id"] == directive["opportunity_id"]
+ assert directive["opportunities_total"] == 12
+ # Level 0 is a lead, not a queue: it must stay small enough to survive.
+ assert len(str(directive)) < 1536
+ assert "refactoring_opportunities" not in result
+
+ # 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["mode"] == "refactoring_opportunity"
+ assert detail["steps"]
+ del repo_id
+
+
+async def test_the_directive_is_clear_rather_than_absent_with_no_opportunities(client, app):
+ repo_id = await _repo(client)
+ async with app.state.session_factory() as session:
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+ get_health = await _mcp(app)
+ assert (await get_health())["refactoring_directive"]["status"] == "clear"
+
+
+async def test_the_summary_rolls_up_by_type_effort_and_classification(client, app):
+ await _seed(client, app, files=6)
+ get_health = await _mcp(app)
+ summary = (
+ await get_health(include=["refactoring"], only=["refactoring_summary"])
+ )["refactoring_summary"]
+ assert summary["status"] == "available"
+ assert summary["opportunities_total"] == 6
+ assert summary["by_lead_type"]["extract_method"] == 6
+ assert summary["mechanical_steps_total"] + summary["judgment_steps_total"] == 6
+ assert summary["addresses_primary_problem"]["yes"] == 6
+ assert "facets" in summary
+ assert "refactoring_opportunities" in summary["next_call"]
+
+
+async def test_the_default_queue_does_not_reproduce_the_ranked_head(client, app):
+ """Eight equal scores from one area must not own the first page.
+
+ The scores really are equal under the published factors, so the answer is a
+ queue that spends its first rows on distinct problems, not a tiebreaker.
+ """
+ repo_id = await _repo(client)
+ # One area with a long run of identical scores, plus two other areas.
+ plans = [_plan(f"crowded/m{i}.py", f"s{i}", impact_delta=1.0) for i in range(8)]
+ plans += [_plan("other/a.py", "a", impact_delta=1.0), _plan("third/b.py", "b", impact_delta=1.0)]
+ async with app.state.session_factory() as session:
+ await crud.save_refactoring_suggestions(session, repo_id, plans)
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+
+ default = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 3}
+ )
+ ).json()["items"]
+ canonical = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities",
+ params={"limit": 3, "view": "canonical"},
+ )
+ ).json()["items"]
+
+ areas = {item["file_path"].split("/")[0] for item in default}
+ assert areas == {"crowded", "other", "third"}
+ # Pure rank order still available, and still the flat run it honestly is.
+ assert {item["file_path"].split("/")[0] for item in canonical} == {"crowded"}
+
+
+async def test_a_step_names_the_findings_its_cause_produced(client, app):
+ repo_id = await _seed(client, app, files=2)
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ detail = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities/"
+ f"{body['items'][0]['opportunity_id']}"
+ )
+ ).json()
+ step = detail["steps"][0]
+ assert step["finding_ids"], "a step must round-trip to the diagnosis behind it"
+
+ get_health = await _mcp(app)
+ resolved = await get_health(finding_id=step["finding_ids"][0])
+ assert resolved["resolved"] is True
+
+
+async def test_the_detail_hands_back_structured_next_calls(client, app):
+ repo_id = await _seed(client, app, files=2)
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ detail = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities/"
+ f"{body['items'][0]['opportunity_id']}"
+ )
+ ).json()
+ tools = {action["tool"] for action in detail["next_actions"]}
+ assert {"get_symbol", "get_risk"} <= tools
+ assert detail["plans"], "the steps' payloads come back with them"
+ assert detail["validation_profiles"], "validation is served, not recomputed"
+
+
+async def test_a_plan_id_resolves_to_the_opportunity_that_owns_it(client, app):
+ repo_id = await _seed(client, app, files=3)
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ owner = body["items"][0]["opportunity_id"]
+ detail = (
+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{owner}")
+ ).json()
+ get_health = await _mcp(app)
+ resolved = await get_health(plan_id=detail["steps"][0]["plan_id"])
+ assert resolved["resolved"] is True
+ assert resolved["opportunity_id"] == owner
+ assert resolved["next_action"]["arguments"]["opportunity_id"] == owner
+ # The payload every surface shows, rank components included.
+ assert "rank_score" in resolved["plan"]
+ assert "validation" in resolved["plan"]
+
+
+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["model_state"]["state"] == "current"
+ stale = await get_health(opportunity_id="refop1_" + "0" * 20)
+ assert stale["model_state"]["state"] == "stale_model"
+
+
+async def test_each_step_keeps_its_own_validation_profile(client, app):
+ """Validation must be keyed by plan, not by position.
+
+ ``hydrate_recommendations`` returns its results in rank order, so pairing
+ them positionally against the rows handed in gives most steps another
+ plan's tests. Two plans on two files with different affected-file sets, and
+ a rank order that is the reverse of the read order, catch it.
+ """
+ repo_id = await _repo(client)
+ local = _plan("alpha/only_here.py", "local_sym", impact_delta=0.5)
+ spanning = {
+ **_plan("beta/anchor.py", "dup_block", impact_delta=9.0),
+ "refactoring_type": "extract_helper",
+ "plan": {
+ "occurrences": [
+ {"file": "beta/anchor.py", "line_start": 10, "line_end": 30},
+ {"file": "gamma/other.py", "line_start": 5, "line_end": 25},
+ ],
+ "suggested_site": {"module": "beta", "directory": "beta"},
+ "duplicated_lines": 20,
+ },
+ "evidence": {"occurrence_count": 2, "duplicated_lines": 20, "co_change_count": 9},
+ "blast_radius": {
+ "files": ["beta/anchor.py", "gamma/other.py"],
+ "file_count": 2,
+ "co_change_count": 9,
+ },
+ "source_biomarker": "dry_violation",
+ }
+ async with app.state.session_factory() as session:
+ # Inserted lowest-rank-first, so the rank order is the reverse.
+ await crud.save_refactoring_suggestions(session, repo_id, [local, spanning])
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ seen = {}
+ for item in body["items"]:
+ detail = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities/{item['opportunity_id']}"
+ )
+ ).json()
+ profiles = {p["id"]: p for p in detail["validation_profiles"]}
+ for step in detail["steps"]:
+ profile = profiles[step["validation_profile_id"]]
+ seen[step["file_path"]] = set(profile["affected_files"])
+
+ assert seen["alpha/only_here.py"] == {"alpha/only_here.py"}
+ assert seen["beta/anchor.py"] == {"beta/anchor.py", "gamma/other.py"}
+
+
+async def test_rest_and_mcp_agree_under_every_queue_filter(client, app):
+ """MCP could order the queue but not filter it; REST could do both."""
+ repo_id = await _repo(client)
+ plans = [
+ _plan("a/one.py", "s1", impact_delta=3.0, confidence="high", effort_bucket="S"),
+ _plan("b/two.py", "s2", impact_delta=2.0, confidence="medium", effort_bucket="L"),
+ {
+ **_plan("c/three.py", "s3", impact_delta=1.0),
+ "refactoring_type": "split_file",
+ "plan": {"groups": [{"name": "g1", "symbols": ["x"]}]},
+ "source_biomarker": "large_file",
+ },
+ ]
+ async with app.state.session_factory() as session:
+ await crud.save_refactoring_suggestions(session, repo_id, plans)
+ await crud.finalize_refactoring_opportunities(session, repo_id)
+ await session.commit()
+ get_health = await _mcp(app)
+
+ for params, kwargs in (
+ ({"refactoring_type": "split_file"}, {"refactoring_type": "split_file"}),
+ ({"confidence": "high"}, {"refactoring_confidence": "high"}),
+ ({"effort": "L"}, {"refactoring_effort": "L"}),
+ ({"refactoring_type": "nope"}, {"refactoring_type": "nope"}),
+ ):
+ rest = (
+ await client.get(
+ f"/api/repos/{repo_id}/refactoring/opportunities",
+ params={"limit": 6, **params},
+ )
+ ).json()
+ mcp = await get_health(
+ include=["refactoring"], only=["refactoring_opportunities"], limit=6, **kwargs
+ )
+ assert rest["total"] == mcp["refactoring_opportunities_total"], params
+ assert [i["opportunity_id"] for i in rest["items"]] == [
+ i["opportunity_id"] for i in mcp["refactoring_opportunities"]
+ ], params
+ # An unrecognized value is named on both surfaces, never swallowed.
+ assert rest.get("ignored_arguments") == mcp.get("ignored_arguments"), params
+
+
+async def test_limit_zero_returns_the_totals_and_no_rows(client, app):
+ """``limit=0`` is the documented "totals, no rows" call at every level."""
+ repo_id = await _seed(client, app, files=4)
+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
+ get_health = await _mcp(app)
+ detail = await get_health(opportunity_id=body["items"][0]["opportunity_id"], limit=0)
+ assert detail["steps"] == []
+ assert detail["steps_total"] == 1
+ assert detail["steps_emitted"] == 0
+
+
+async def test_a_capped_queue_says_why_it_was_capped(client, app):
+ repo_id = await _seed(client, app, files=20)
+ get_health = await _mcp(app)
+ result = await get_health(
+ include=["refactoring"], only=["refactoring_opportunities"], limit=3
+ )
+ assert result["refactoring_opportunities_total"] == 20
+ assert result["refactoring_opportunities_emitted"] == 3
+ assert result["refactoring_opportunities_reduced_reason"] == "limit"
+ assert result["recovery"]["refactoring_opportunities"]["remaining"] == 17
+ del repo_id