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.

55.8 KB
Raw Blame
"""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 json
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
from repowise.core.persistence.crud.analysis.fix_first import clear_fix_first_cache


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,
            "span": {"start": 12, "end": 28},
        },
        "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, function_name: str = "f"
) -> dict[str, Any]:
    return {
        "file_path": path,
        "biomarker_type": biomarker,
        "severity": "high",
        "function_name": function_name,
        "line_start": 10,
        "line_end": 30,
        # Large enough to lead with no history, so the composed plan is a candidate.
        "details": {"ccn": 85},
        "health_impact": impact,
        "reason": "seeded",
        "dimension": "defect",
    }


async def _finalize(session: Any, repo_id: str, **kwargs: Any) -> None:
    """Compose the opportunities, then judge them, as an index run does."""
    from repowise.core.persistence.crud.analysis.actions import write_read_snapshots

    await crud.finalize_refactoring_opportunities(session, repo_id, **kwargs)
    await write_read_snapshots(session, repo_id)


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, function_name=f"sym{i}") for i, p in enumerate(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 _finalize(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
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
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("refop4_")
        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


@pytest.mark.asyncio
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 _finalize(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


@pytest.mark.asyncio
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 _finalize(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"


@pytest.mark.asyncio
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 _finalize(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"


async def _seed_older_model(app, repo_id: str, statuses: list[str]) -> list[str]:
    """Copies of the current rows as an older model left them, one per status."""
    from sqlalchemy import select

    from repowise.core.analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
    from repowise.core.persistence.models import RefactoringOpportunity, _new_uuid

    old = REFACTORING_MODEL_VERSION - 1
    skip = {"id", "opportunity_id", "refactoring_model_version", "status"}
    async with app.state.session_factory() as session:
        current = (
            await session.execute(
                select(RefactoringOpportunity).where(
                    RefactoringOpportunity.repository_id == repo_id
                )
            )
        ).scalars().all()
        ids = []
        for row, status in zip(current, statuses, strict=False):
            values = {
                c.name: getattr(row, c.name)
                for c in RefactoringOpportunity.__table__.columns
                if c.name not in skip
            }
            opportunity_id = f"refop{old}_{row.opportunity_id.split('_', 1)[1]}"
            session.add(
                RefactoringOpportunity(
                    id=_new_uuid(),
                    opportunity_id=opportunity_id,
                    refactoring_model_version=old,
                    status=status,
                    **values,
                )
            )
            ids.append(opportunity_id)
        await session.commit()
    return ids


async def _states(app, repo_id: str) -> dict[str, str]:
    from sqlalchemy import select

    from repowise.core.persistence.models import RefactoringOpportunity

    async with app.state.session_factory() as session:
        rows = await session.execute(
            select(RefactoringOpportunity.opportunity_id, RefactoringOpportunity.status).where(
                RefactoringOpportunity.repository_id == repo_id
            )
        )
        return dict(rows.all())


@pytest.mark.asyncio
async def test_a_model_bump_retires_the_older_models_open_opportunities(client, app):
    """An older model's open rows resolve on the next run and are never served.

    Its plans were already resolved by the bump, so an open opportunity folded
    from them names work nobody can act on, and it doubled every count.
    """
    from repowise.core.persistence.crud.analysis.queue_counts import unit_counts

    repo_id = await _seed(client, app, files=3)
    open_old, dismissed_old, picked_up_old = await _seed_older_model(
        app, repo_id, ["open", "false_positive", "acknowledged"]
    )
    clear_fix_first_cache()

    # Served reads skip the older model even before a run retires it.
    listed = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities?scope=all")).json()
    assert listed["total"] == 3
    async with app.state.session_factory() as session:
        rows, total = await crud.list_refactoring_opportunities(session, repo_id)
        facets = await crud.refactoring_facet_counts(session, repo_id)
        counts = await unit_counts(session, repo_id, "plans")
    assert total == 3
    assert not {row.opportunity_id for row in rows} & {open_old, picked_up_old}
    assert all(sum(counts.values()) == 3 for counts in facets.values())
    # The older model's rows are no plans of the queue's inventory either.
    assert counts.inventory == 3

    async with app.state.session_factory() as session:
        await _finalize(session, repo_id)
        await session.commit()
    states = await _states(app, repo_id)
    assert states[open_old] == "resolved"
    assert states[picked_up_old] == "resolved"
    # A person's dismissal is a different claim from "this got done".
    assert states[dismissed_old] == "false_positive"
    current = {k: v for k, v in states.items() if k not in {open_old, dismissed_old, picked_up_old}}
    assert list(current.values()) == ["open"] * 3

    # A later run with no model change resolves nothing more.
    async with app.state.session_factory() as session:
        await _finalize(session, repo_id)
        await session.commit()
    assert await _states(app, repo_id) == states


# ---------------------------------------------------------------------------
# Scope: Fix first's eligible set by default, the inventory on request
# ---------------------------------------------------------------------------


async def _seed_mixed(client: AsyncClient, app) -> str:
    """Two eligible opportunities, one in a test file, one under the worth floor."""
    repo_id = await _repo(client)
    paths = ["pkg/a.py", "pkg/b.py", "tests/test_c.py", "pkg/d.py"]
    gains = [3.0, 2.0, 3.0, 0.2]
    async with app.state.session_factory() as session:
        await crud.save_health_findings(
            session,
            repo_id,
            [_finding(p, function_name=f"sym{i}") for i, p in enumerate(paths)],
        )
        await crud.save_refactoring_suggestions(
            session,
            repo_id,
            [_plan(p, f"sym{i}", impact_delta=g) for i, (p, g) in enumerate(zip(paths, gains, strict=True))],
        )
        await _finalize(session, repo_id, analyzed_commit="c" * 40)
        await session.commit()
    return repo_id


@pytest.mark.asyncio
async def test_the_default_lists_what_fix_first_takes_and_counts_the_rest(client, app):
    repo_id = await _seed_mixed(client, app)
    url = f"/api/repos/{repo_id}/refactoring/opportunities"
    body = (await client.get(url)).json()
    assert body["scope"] == "fix_first"
    assert sorted(i["file_path"] for i in body["items"]) == ["pkg/a.py", "pkg/b.py"]
    assert body["total"] == 2
    assert body["hidden"] == {"total": 2, "by_reason": {"test": 1, "below_min_worth": 1}}
    assert sum(body["facets"]["effort"].values()) == 2

    everything = (await client.get(url, params={"scope": "all"})).json()
    assert everything["scope"] == "all" and everything["total"] == 4
    assert "hidden" not in everything


@pytest.mark.asyncio
async def test_every_surface_reports_the_same_counts(client, app):
    """The list, the Code Health overview and the Fix first route carry one
    count object per unit, read from the judgements the index stored."""
    repo_id = await _seed_mixed(client, app)
    get_health = await _mcp(app)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    assert page["counts"] == {
        "inventory": 4,
        "in_scope": 3,
        "eligible": 2,
        "due": page["counts"]["due"],
        "shown": 2,
        "excluded": {"below_min_worth": 1, "test": 1},
        "gated": 0,
    }
    overview = (await client.get(f"/api/repos/{repo_id}/health/overview")).json()
    by_unit = overview["queue_counts"]
    assert {**by_unit["plans"], "shown": 2} == page["counts"]
    fix_first = (await client.get(f"/api/repos/{repo_id}/health/fix-first")).json()
    assert {**fix_first["counts"], "shown": 0} == by_unit["items"]
    mcp = await get_health(
        repo=repo_id, include=["refactoring"], only=["refactoring_plans"], limit=25
    )
    assert {**mcp["refactoring_plans_counts"], "shown": 2} == page["counts"]


@pytest.mark.asyncio
async def test_an_unjudged_store_lists_what_fix_first_takes_live(client, app):
    """A store whose rows carry no verdict yet (an older store, or a judging
    write that did not run) still lists Fix first's plans, counted not judged."""
    from sqlalchemy import update

    from repowise.core.persistence.models import RefactoringOpportunity

    repo_id = await _seed_mixed(client, app)
    async with app.state.session_factory() as session:
        await session.execute(
            update(RefactoringOpportunity).values(queue_eligible=None, queue_reason=None)
        )
        await session.commit()
    clear_fix_first_cache()
    body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    assert sorted(i["file_path"] for i in body["items"]) == ["pkg/a.py", "pkg/b.py"]
    assert body["hidden"] == {"total": 2, "by_reason": {"not_judged": 2}}
    assert body["counts"]["excluded"] == {"not_judged": 4}


@pytest.mark.asyncio
async def test_a_stale_verdict_is_judged_again_by_the_next_write(client, app):
    from sqlalchemy import select, update

    from repowise.core.persistence.crud.analysis.actions import write_read_snapshots
    from repowise.core.persistence.models import RefactoringOpportunity

    repo_id = await _seed_mixed(client, app)
    o = RefactoringOpportunity
    async with app.state.session_factory() as session:
        # An update moved a.py's plan under the worth floor.
        await session.execute(
            update(o).where(o.file_path == "pkg/a.py").values(recoverable_health=0.1)
        )
        await write_read_snapshots(session, repo_id)
        await session.commit()
        row = (await session.execute(select(o).where(o.file_path == "pkg/a.py"))).scalar_one()
    assert (row.queue_eligible, row.queue_reason) == (False, "below_min_worth")
    body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    assert [i["file_path"] for i in body["items"]] == ["pkg/b.py"]


@pytest.mark.asyncio
async def test_a_file_or_a_triaged_status_reads_the_inventory(client, app):
    repo_id = await _seed_mixed(client, app)
    url = f"/api/repos/{repo_id}/refactoring/opportunities"
    own = (await client.get(url, params={"file_path": "tests/test_c.py"})).json()
    assert own["scope"] == "all" and own["total"] == 1
    resolved = (await client.get(url, params={"status": "resolved"})).json()
    assert resolved["scope"] == "all"


@pytest.mark.asyncio
async def test_hidden_counts_follow_the_filters(client, app):
    repo_id = await _seed_mixed(client, app)
    body = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/opportunities", params={"search": "tests/"}
        )
    ).json()
    assert body["total"] == 0
    assert body["hidden"] == {"total": 1, "by_reason": {"test": 1}}


@pytest.mark.asyncio
async def test_rest_and_mcp_agree_on_the_scope(client, app):
    repo_id = await _seed_mixed(client, app)
    get_health = await _mcp(app)
    rest = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    mcp = await get_health(include=["refactoring"], only=["refactoring_opportunities"])
    assert mcp["refactoring_opportunities_total"] == rest["total"]
    assert mcp["refactoring_opportunities_scope"] == "fix_first"
    assert mcp["refactoring_opportunities_hidden"] == rest["hidden"]
    everything = await get_health(
        include=["refactoring"], only=["refactoring_opportunities"], refactoring_scope="all"
    )
    assert everything["refactoring_opportunities_total"] == 4
    assert "refactoring_opportunities_hidden" not in everything


# ---------------------------------------------------------------------------
# REST == MCP
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
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


@pytest.mark.asyncio
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


@pytest.mark.asyncio
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


@pytest.mark.asyncio
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.

    Each request is measured cold: the default scope builds the Fix-first
    queue, which is cached per store write, and a warm hit costs less.
    """
    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),
    ):
        clear_fix_first_cache()
        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


@pytest.mark.asyncio
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)
    clear_fix_first_cache()
    seen.clear()
    await client.get(
        f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 5, "offset": 0}
    )
    first = len(seen)
    clear_fix_first_cache()
    seen.clear()
    await client.get(
        f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 5, "offset": 30}
    )
    assert len(seen) == first


@pytest.mark.asyncio
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


@pytest.mark.asyncio
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
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_bare_get_health_leads_with_fix_first_and_links_the_opportunity(client, app):
    repo_id = await _seed(client, app, files=12)
    get_health = await _mcp(app)
    result = await get_health()
    assert "refactoring_directive" not in result
    assert "refactoring_opportunities" not in result
    lead = result["fix_first"]["lead"]
    assert lead["kind"] == "refactor"
    opportunity_id = lead["next_call"]["arguments"]["opportunity_id"]
    assert opportunity_id.startswith("refop4_")
    # Level 0 is a lead, not a queue: it must stay small enough to survive.
    assert len(str(result["fix_first"])) < 6000

    # And the id it names resolves in one call.
    detail = await get_health(opportunity_id=opportunity_id)
    assert detail["found"] is True
    # The lookup flag never shares a name with the lifecycle it sits beside:
    # ``resolved: true`` next to ``status: "open"`` read as a contradiction.
    assert "resolved" not in detail
    assert detail["status"] == "open"
    assert detail["mode"] == "refactoring_opportunity"
    assert detail["steps"]
    del repo_id


@pytest.mark.asyncio
async def test_the_rest_rollup_lead_is_clear_not_absent_with_no_opportunities(
    client, app
):
    repo_id = await _repo(client)
    async with app.state.session_factory() as session:
        await _finalize(session, repo_id)
        await session.commit()
    body = (await client.get(f"/api/repos/{repo_id}/refactoring/summary")).json()
    assert body["directive"]["status"] == "clear"


@pytest.mark.asyncio
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 summary["next_call"]["arguments"]["only"] == ["refactoring_opportunities"]
    assert "refactoring_opportunities" in summary["next_call"]["mcp"]


@pytest.mark.asyncio
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 _finalize(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"}


@pytest.mark.asyncio
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


@pytest.mark.asyncio
async def test_lead_finding_ids_follow_the_findings_not_their_insert_order(client, app):
    """Stored finding id lists must not depend on which index the planner reads."""
    from sqlalchemy import select

    from repowise.core.persistence.models import HealthFinding, RefactoringOpportunity

    repo_id = await _repo(client)
    path = "pkg/mod.py"
    async with app.state.session_factory() as session:
        await crud.save_health_findings(
            session,
            repo_id,
            [_finding(path, function_name=name) for name in ("zeta", "alpha", "mid")],
        )
        await crud.save_refactoring_suggestions(session, repo_id, [_plan(path, "alpha")])
        await _finalize(session, repo_id)
        await session.commit()
        by_function = {
            row.function_name: row.public_id
            for row in (
                await session.execute(
                    select(HealthFinding).where(HealthFinding.repository_id == repo_id)
                )
            ).scalars()
        }
        details = json.loads(
            (
                await session.execute(
                    select(RefactoringOpportunity.details_json).where(
                        RefactoringOpportunity.repository_id == repo_id
                    )
                )
            ).scalar_one()
        )
    assert details["lead_finding_ids"] == [by_function[n] for n in ("alpha", "mid", "zeta")]


@pytest.mark.asyncio
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"


@pytest.mark.asyncio
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"]


@pytest.mark.asyncio
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="refop4_" + "0" * 20)
    assert missing["found"] is False
    assert missing["model_state"]["state"] == "current"
    stale = await get_health(opportunity_id="refop1_" + "0" * 20)
    assert stale["model_state"]["state"] == "stale_model"


@pytest.mark.asyncio
@pytest.mark.usefixtures("dry_violation_shown")
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 _finalize(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"}


@pytest.mark.asyncio
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 _finalize(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


@pytest.mark.asyncio
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


@pytest.mark.asyncio
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


# ---------------------------------------------------------------------------
# Triage: the opportunity transition
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_one_request_triages_every_step_of_an_opportunity(client, app):
    """An opportunity has no lifecycle of its own, so the transition writes the
    steps and reads the rollup back. One request, not one per step."""
    repo_id = await _seed(client, app, files=3)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    oid = page["items"][0]["opportunity_id"]
    detail = (
        await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{oid}")
    ).json()
    step_ids = [s["plan_id"] for s in detail["steps"]]

    res = await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "acknowledged"},
    )
    assert res.status_code == 200
    body = res.json()
    assert body["status"] == "acknowledged"
    assert body["steps_updated"] == len(step_ids)

    async with app.state.session_factory() as session:
        for plan_id in step_ids:
            row = await crud.get_refactoring_suggestion(session, repo_id, plan_id)
            assert row is not None and row.status == "acknowledged"

    # And the stored column moved with it, so the indexed read agrees without
    # waiting for the next index.
    refreshed = (
        await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{oid}")
    ).json()
    assert refreshed["status"] == "acknowledged"


@pytest.mark.asyncio
async def test_a_dismissed_opportunity_reads_back_as_dismissed_not_resolved(client, app):
    """``false_positive`` and ``resolved`` are different claims - the work was
    never real against the work is done - so a person who chooses one must not
    be shown the other."""
    repo_id = await _seed(client, app, files=3)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    oid = page["items"][0]["opportunity_id"]

    res = await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "false_positive"},
    )
    assert res.status_code == 200
    assert res.json()["status"] == "false_positive"


@pytest.mark.asyncio
async def test_a_triaged_opportunity_leaves_the_open_queue(client, app):
    repo_id = await _seed(client, app, files=4)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    before = page["total"]
    oid = page["items"][0]["opportunity_id"]

    await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "resolved"},
    )
    after = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    assert after["total"] == before - 1
    assert oid not in {item["opportunity_id"] for item in after["items"]}


@pytest.mark.asyncio
async def test_an_unknown_status_is_refused_rather_than_stored(client, app):
    repo_id = await _seed(client, app, files=2)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    oid = page["items"][0]["opportunity_id"]
    res = await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "wontfix"},
    )
    assert res.status_code == 400


@pytest.mark.asyncio
async def test_an_unknown_opportunity_id_is_a_404(client, app):
    repo_id = await _seed(client, app, files=2)
    res = await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/refop2_nope/status",
        json={"status": "resolved"},
    )
    assert res.status_code == 404


def test_the_rollup_rule_separates_dismissed_from_done():
    """The pure rule, over member states alone. One step someone called a false
    positive must not resolve the work the others still describe."""
    from repowise.core.analysis.health.refactoring.opportunity import roll_up_status

    assert roll_up_status([]) == "open"
    assert roll_up_status(["open", "resolved"]) == "open"
    assert roll_up_status(["acknowledged", "resolved"]) == "acknowledged"
    assert roll_up_status(["resolved", "resolved"]) == "resolved"
    # Mixed: some done, one wrong. The work as a whole is done.
    assert roll_up_status(["resolved", "false_positive"]) == "resolved"
    # All wrong: the opportunity itself was the false positive.
    assert roll_up_status(["false_positive", "false_positive"]) == "false_positive"


@pytest.mark.asyncio
async def test_the_board_can_search_by_path_fragment(client, app):
    """The board's search box. A residual filter over the open set, which is
    what makes it a substring rather than an index seek."""
    repo_id = await _seed(client, app, files=6)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    sample = page["items"][0]["file_path"]
    fragment = sample.rsplit("/", 1)[-1][:4]

    hit = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/opportunities", params={"search": fragment}
        )
    ).json()
    assert hit["total"] >= 1
    assert all(fragment in item["file_path"] for item in hit["items"])

    miss = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/opportunities",
            params={"search": "zzz_no_such_path"},
        )
    ).json()
    assert miss["total"] == 0


@pytest.mark.asyncio
async def test_several_lead_types_come_back_in_one_request(client, app):
    """The board's Structural tab is four types, and it must not cost four
    round trips."""
    repo_id = await _seed(client, app, files=8)
    body = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/opportunities",
            params={"refactoring_type": "split_file,break_cycle"},
        )
    ).json()
    assert body.get("ignored_arguments", {}) == {}
    assert all(
        item["lead_refactoring_type"] in {"split_file", "break_cycle"} for item in body["items"]
    )

    # A misspelling inside the list is still named rather than narrowing the
    # result to the members that happened to be spelled right.
    noisy = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/opportunities",
            params={"refactoring_type": "split_file,nonsense"},
        )
    ).json()
    assert noisy["ignored_arguments"]["refactoring_type"] == "nonsense"


@pytest.mark.asyncio
async def test_a_row_can_be_asked_for_without_its_steps(client, app):
    """The product list renders step counts, not steps. Asking for the steps is
    most of the page's bytes and none of its pixels."""
    repo_id = await _seed(client, app, files=6)
    with_steps = (
        await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")
    ).json()
    without = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/opportunities", params={"step_preview": 0}
        )
    ).json()

    assert any("steps" in item for item in with_steps["items"])
    assert all("steps" not in item for item in without["items"])
    # The counts a row actually renders survive.
    assert all("step_count" in item for item in without["items"])
    assert len(json.dumps(without)) < len(json.dumps(with_steps))


@pytest.mark.asyncio
async def test_the_field_can_place_every_structural_opportunity(client, app):
    """The structural field plots file size against reach, and those are file
    facts the opportunity row has to carry: without them it could only plot the
    handful of files the bounded plan head happened to include."""
    repo_id = await _seed(client, app, files=6)
    body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    figured = [
        item
        for item in body["items"]
        if isinstance(item.get("file_nloc"), int) and isinstance(item.get("dependents"), int)
    ]
    assert figured, "the finalizer records the file's size and reach onto the row"


@pytest.mark.asyncio
async def test_a_dismissal_survives_the_next_index(client, app):
    """A person's decision is not restated by the writer.

    Both terminal states mean "nobody composes this again", so the reconciler
    sees a dismissed opportunity exactly as it sees a completed one: absent.
    Reading that absence as "resolved" would quietly turn "this was never real"
    into "this got done", and the next index would do it silently.
    """
    repo_id = await _seed(client, app, files=3)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    oid = page["items"][0]["opportunity_id"]

    await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "false_positive"},
    )
    async with app.state.session_factory() as session:
        await _finalize(session, repo_id)
        await session.commit()
        row = await crud.get_refactoring_opportunity(session, repo_id, oid)
        assert row is not None
        assert row.status == "false_positive"


@pytest.mark.asyncio
async def test_an_acknowledgement_survives_the_next_index(client, app):
    """Acknowledged is outstanding work someone picked up, so it stays composed
    and the rollup keeps saying so."""
    repo_id = await _seed(client, app, files=3)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    oid = page["items"][0]["opportunity_id"]

    await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "acknowledged"},
    )
    async with app.state.session_factory() as session:
        await _finalize(session, repo_id)
        await session.commit()
        row = await crud.get_refactoring_opportunity(session, repo_id, oid)
        assert row is not None
        assert row.status == "acknowledged"


@pytest.mark.asyncio
async def test_a_transition_that_writes_nothing_is_not_reported_as_success(client, app):
    """The rollup of an empty set is ``open``.

    So an opportunity whose steps are missing or whose plan ids no longer
    resolve would otherwise answer "dismiss this" with a stored ``open`` and an
    HTTP 200 - the caller's own request handed back as the state, with the one
    thing they asked for the one thing that did not happen.
    """
    repo_id = await _seed(client, app, files=3)
    page = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    oid = page["items"][0]["opportunity_id"]

    async with app.state.session_factory() as session:
        row = await crud.get_refactoring_opportunity(session, repo_id, oid)
        assert row is not None
        row.details_json = json.dumps({"steps": []})
        await session.commit()

    res = await client.patch(
        f"/api/repos/{repo_id}/refactoring/opportunities/{oid}/status",
        json={"status": "false_positive"},
    )
    assert res.status_code == 409

    async with app.state.session_factory() as session:
        row = await crud.get_refactoring_opportunity(session, repo_id, oid)
        assert row is not None
        # Untouched, rather than silently reset to open.
        assert row.status == "open"


def test_the_diversified_queue_never_gives_a_zero_credit_group_a_head_slot():
    from types import SimpleNamespace

    from repowise.core.persistence.crud.analysis.refactoring_opportunities import (
        _diversified_order,
    )

    def item(path, kind, health):
        return SimpleNamespace(
            file_path=path,
            lead_biomarker="complex_method" if health else None,
            lead_refactoring_type=kind,
            recoverable_health=health,
        )

    # Rank order: credited first, zero-credit after (``rank_sort_key``).
    ranked = [
        item("pkg/a/x.py", "extract_method", 0.9),
        item("pkg/a/y.py", "extract_method", 0.8),
        item("pkg/b/z.py", "extract_method", 0.3),
        item("pkg/c/cycle.py", "break_cycle", 0.0),
        item("pkg/d/split.py", "split_file", 0.0),
    ]
    order = _diversified_order(ranked)
    assert order[:3] != [0, 1, 2]  # still interleaves the credited work
    assert sorted(order[:3]) == [0, 1, 2]
    assert order[3:] == [3, 4]


# ---------------------------------------------------------------------------
# The finding registry and test files
# ---------------------------------------------------------------------------


def _clone_plan(path: str, symbol: str) -> dict[str, Any]:
    """A cross-file, co-changed clone: a step when its biomarker is shown."""
    return _plan(
        path,
        symbol,
        refactoring_type="extract_helper",
        evidence={"is_intra_file": False, "co_change_count": 9},
        impact_delta=4.0,
        source_biomarker="dry_violation",
    )


@pytest.mark.asyncio
async def test_withheld_plans_reach_no_list_queue_or_lead(client, app):
    repo_id = await _repo(client)
    plans = [_clone_plan(f"dup{i}/m{i}.py", f"c{i}") for i in range(6)]
    plans.append(_plan("svc/core.py", "work", impact_delta=0.5))
    async with app.state.session_factory() as session:
        await crud.save_refactoring_suggestions(session, repo_id, plans)
        await _finalize(session, repo_id)
        # Stored all the same: the registry decides visibility, not persistence.
        assert len(await crud.get_refactoring_suggestions(session, repo_id)) == 1
        assert await crud.count_refactoring_suggestions(session, repo_id) == 1
        await session.commit()

    queue = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    assert [item["file_path"] for item in queue["items"]] == ["svc/core.py"]
    targets = (await client.get(f"/api/repos/{repo_id}/refactoring/targets")).json()
    assert [plan["file_path"] for plan in targets["plans"]] == ["svc/core.py"]
    rollup = (await client.get(f"/api/repos/{repo_id}/refactoring/summary")).json()
    assert rollup["directive"]["fix_first"] == "svc/core.py"


@pytest.mark.asyncio
async def test_a_test_file_is_never_the_lead_or_ahead_of_production(client, app):
    repo_id = await _repo(client)
    plans = [
        _plan("tests/test_core.py", "helper", impact_delta=9.0),
        _plan("svc/a.py", "a", impact_delta=0.5),
        _plan("svc/b.py", "b", impact_delta=0.4),
    ]
    async with app.state.session_factory() as session:
        await crud.save_refactoring_suggestions(session, repo_id, plans)
        await _finalize(session, repo_id)
        await session.commit()

    for view in ("diversified", "canonical"):
        items = (
            await client.get(
                f"/api/repos/{repo_id}/refactoring/opportunities",
                params={"view": view, "scope": "all"},
            )
        ).json()["items"]
        assert [item["file_path"] for item in items][-1] == "tests/test_core.py"
    rollup = (await client.get(f"/api/repos/{repo_id}/refactoring/summary")).json()
    assert rollup["directive"]["fix_first"] == "svc/a.py"


@pytest.mark.asyncio
async def test_the_directive_names_no_test_file_when_only_tests_have_work(client, app):
    repo_id = await _repo(client)
    async with app.state.session_factory() as session:
        await crud.save_refactoring_suggestions(
            session, repo_id, [_plan("tests/test_core.py", "helper")]
        )
        await _finalize(session, repo_id)
        await session.commit()
    rollup = (await client.get(f"/api/repos/{repo_id}/refactoring/summary")).json()
    directive = rollup["directive"]
    assert directive["status"] == "clear"
    assert directive["reason"] == "only_test_file_opportunities"
    assert directive["opportunities_total"] == 1


# ---------------------------------------------------------------------------
# The recipe and the agent prompts core renders from it
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_a_plans_recipe_is_served_only_when_asked_and_alike_on_rest_and_mcp(client, app):
    repo_id = await _seed(client, app, files=2)
    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()
    plan_id = detail["steps"][0]["plan_id"]
    get_health = await _mcp(app)

    bare = (await client.get(f"/api/repos/{repo_id}/refactoring/{plan_id}")).json()
    assert "recipe" not in bare
    assert "recipe" not in (await get_health(plan_id=plan_id))["plan"]

    rest = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/{plan_id}", params={"include": "recipe"}
        )
    ).json()["recipe"]
    mcp = (await get_health(plan_id=plan_id, include=["recipe"]))["plan"]["recipe"]
    assert rest["id"] == mcp["id"] == plan_id
    assert rest["steps"] == mcp["steps"]
    (step,) = rest["steps"]
    assert step["action"] == "extract"
    assert step["span"] == {"start": 12, "end": 28}
    assert rest["postconditions"][0]["kind"] == "verify"


@pytest.mark.asyncio
async def test_the_plan_and_opportunity_prompts_are_rendered_by_the_server(client, app):
    repo_id = await _seed(client, app, files=2)
    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()
    plan_id = detail["steps"][0]["plan_id"]

    plan = (
        await client.get(
            f"/api/repos/{repo_id}/refactoring/{plan_id}/prompt",
            params={"flavor": "claude-code-mcp"},
        )
    ).json()
    assert plan["flavor"] == "claude-code-mcp"
    assert "## Extract Method (`opp-repo`)" in plan["text"]
    assert f'get_health(plan_id="{plan_id}")' in plan["text"]

    opportunity = (
        await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{owner}/prompt")
    ).json()
    assert f"`{owner}`" in opportunity["text"]
    assert f"Step id: `{plan_id}`" in opportunity["text"]
    # The step's own instruction comes from its plan's recipe.
    assert "Move lines 12-28 of `" in opportunity["text"]

    missing = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/refop_nope/prompt")
    assert missing.status_code == 404


@pytest.mark.asyncio
async def test_the_opportunity_prompt_route_is_not_read_as_a_plan_id(client, app):
    """``/refactoring/{suggestion_id}/prompt`` must not swallow the opportunity
    prompt path, nor ``opportunities/{id}`` the plan prompt."""
    repo_id = await _seed(client, app, files=1)
    body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()
    owner = body["items"][0]["opportunity_id"]

    resp = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{owner}/prompt")
    assert resp.status_code == 200
    assert "composed the ordered refactoring steps" in resp.json()["text"]
    # "opportunities" alone is the opportunity detail route, never a plan id.
    shadow = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/prompt")
    assert shadow.json().get("detail") == "Unknown opportunity id"