Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(health): close out Fix first: perf lines, refactoring default scope, plain text (#2841)
Raghav Chamadiyacae6d2756fce
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex ebefbd48d..5f3404d84 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -978,6 +978,7 @@ representations of the same work in one response. The `include` **dimension** na| `plan_id` | string | No | Resolve an emitted stable refactoring-plan `id` directly in one call. || `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 `fix_id` and the two above; passing more than one returns `mode: "conflict"` naming them, never 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_scope` | string | No | Which open opportunities `refactoring_opportunities` lists. `fix_first` (the default with no `targets`) keeps only what Fix first would take, by the same eligibility and exclusion rules; `refactoring_opportunities_hidden` then counts the rest of the filtered set, `{"total": n, "by_reason": {...}}`, by Fix first's exclusion reasons. `all` lists the full inventory, and is the default when `targets` name files. `refactoring_opportunities_scope` says which scope the total counts. || `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. |@@ -1167,7 +1168,9 @@ The opt-in enrichments:actually addresses that diagnosis (`addresses_primary_problem`, tri-state -`null` means no dominant finding was recorded, which is not `false`), itsordered `steps` with a `mechanical` / `judgment` `applicability` each, and- counts for the evidence behind it. Ordered by `refactoring_view`. A step+ counts for the evidence behind it. Ordered by `refactoring_view`. With no+ `targets` it lists only what Fix first would take (`refactoring_scope`), and+ `refactoring_opportunities_hidden` counts the rest by reason. A stepcarrying `relocated_by` names an earlier step that moves its symbol to anotherfile: locate the symbol again before applying it, because the step's own`file_path` and span describe where the symbol was.diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.mdindex 76a12fec2..5f093bbb3 100644--- a/docs/layers/CODE_HEALTH.md+++ b/docs/layers/CODE_HEALTH.md@@ -630,6 +630,55 @@ opportunity links by its exact stable `opportunity_id` to the matchingnearby plan. When no safe plan exists, Code Health says so and keeps the rawevidence available.+## Fix first++**Fix first** is one ranked list of what to fix in a repository, built once in+core (`analysis/health/fix_first/`) from stored rows and rendered the same way by+`get_health()`, `repowise health`, the Code Health page, the Overview's Do next and+the generated CLAUDE.md. An item is one unit of work: a file's composed+refactoring, one performance intervention (the loop you change), or the strongest+code-shape finding of a file that has no plan. Each item says what to change and+where (file and line), why it matters there, the first concrete edit, the gain, the+effort and the tests to run after.++**What may be an item.** A unit must be shipped code with a concrete first edit+that is worth doing. Everything else is left out and counted in+`totals.excluded`, one reason per unit:++| Reason | What it leaves out |+|---|---|+| `test` | Test files. `scope=all` keeps them, labelled. |+| `tooling` | Scripts, tools, benchmarks, build and CI files, migrations, and code under a directory whose role is unknown (docs, demos). |+| `generated` | Generated files. |+| `vendored` | Third-party code: `vendor/`, `third_party/`, `node_modules/` and similar directories, minified files, and a library with its own license header among served assets. |+| `docs_example` | Documentation code and examples: `docs/`, `docs_src/`, `examples/`, tutorials, samples. |+| `unknown` | A performance cause whose code context could not be classified. |+| `expected` | A performance cause whose repetition is expected. |+| `no_strategy` | A performance cause with no supported fix strategy. |+| `no_plan` | A performance cause with no stored safe plan to quote. |+| `below_min_worth` | A refactoring that recovers under 0.5 health on its file, or has no steps; a string built in a loop that is bounded or not in production code. |+| `history_only` | A file whose only findings come from git history (churn, ownership, co-change). History is context on an item, never the item. |+| `deprecated` | A function marked deprecated. |+| `inherent_dispatch` | A function where one dispatch on one value holds 60% or more of its decision points, unless a duplicate also sits in it. On the dev labels that share held 9 complexity rows, 8 of them rejected. |+| `small_function` | A complexity unit under 30 code lines and under CCN 15. On the 67 labelled dev rows that cut drops 13 rejected and 4 accepted. |+| `no_concrete_step` | No first edit with a file and a line or a named group: a cycle with no import line to cut, a move with no destination, a split with no named groups, a class finding with no member groups. |+| `low_value_kind` | A kind raters found not worth doing: Extract Class (0 of 14), Move Method (0 of 34), low cohesion (0 of 46), long method (0 of 10), and long parameter lists (0 of 2, thinly measured). |++**Order.** Items rank by value first: the larger of the health they recover and+the size of the problem (CCN 20, 40, 80 and 150; 100, 200, 400 and 800 lines;+nesting 5, 6 and 8; a critical or brain-method finding; one more on a hot file),+so a function far past every bar leads ahead of tidy work. A performance fix's+value is its cost: a production, entry-reachable database or network call in a+loop that grows with the data shares the top band. Then tier: `now` (worth doing,+and the plan is safe to start), `next` (worth doing, the fix needs judgment),+`later`. No kind takes more than 3 of the first 5 places while another has an item+worth doing.++**Verify.** Each item carries up to 5 tests from its stored validation profile,+each with how it reaches the changed code (call graph, import graph, a matching+name or a coverage report), and the command that runs them. A finding with no+plan says so and names none.+## Refactoring targets```bashdiff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.mdindex bad08280c..a7468417b 100644--- a/docs/layers/REFACTORING.md+++ b/docs/layers/REFACTORING.md@@ -154,6 +154,33 @@ Both older values keep working. The same parameter also selects the legacy`refactoring_plans` list's view, where `diversified` resolves to that list'shistorical `canonical` default.+## Fix first, and the default scope++Fix first ([CODE_HEALTH.md](CODE_HEALTH.md#fix-first)) ranks refactorings beside+performance fixes and code-shape findings. A refactoring opportunity is a Fix-first+candidate when its file ships, it recovers at least 0.5 health, its lead step is a+kind raters found worth doing, and that step names a concrete edit (lines to lift,+a destination, the import to cut, named groups); a complexity step also needs a+function of at least 30 code lines or CCN 15 that is not mostly one dispatch on one+value.++**The refactoring view lists those by default.** On this repository's index that is+94 of 702 open opportunities: 507 fall below the worth floor, 42 are in tests, 41+are small functions, and 18 are tooling, low-value kinds, docs, generated or+without a concrete step. The eligibility is read from the Fix-first builder itself,+so the view and the queue cannot disagree.++| `scope` | Lists |+|---|---|+| `fix_first` *(default for the open, repository-wide queue)* | Only what Fix first would take. `hidden` counts the rest of the filtered set, `{"total": n, "by_reason": {...}}`, by the same exclusion reasons. |+| `all` | The full inventory. The default when the call names a file, or lists a triaged status, which Fix first never reads. |++The REST route takes `scope`, MCP `get_health` takes `refactoring_scope` and reports+`refactoring_opportunities_scope` and `refactoring_opportunities_hidden`, and facet+counts follow the scope. The web board's Scope control switches between **Worth+doing** and **Full inventory**, and its count line reads "Showing N worth doing; M+more in the full inventory", with the reasons beneath it.+## Surfaces```bash@@ -176,6 +203,7 @@ get_health(targets=["src/api/server.py"]) # one file# 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?scope=all # the full inventoryGET /api/repos/{repo_id}/refactoring/opportunities?file_path=src/api/server.pyGET /api/repos/{repo_id}/refactoring/opportunities/{opportunity_id}GET /api/repos/{repo_id}/refactoring/summarydiff --git a/packages/api-client/src/refactoring.ts b/packages/api-client/src/refactoring.tsindex 89dfee70b..9db163d43 100644--- a/packages/api-client/src/refactoring.ts+++ b/packages/api-client/src/refactoring.ts@@ -13,6 +13,7 @@ import type {RefactoringPlanPage,RefactoringPlan,RefactoringPlanStatusUpdate,+ RefactoringScope,RefactoringSummaryResponse,RefactoringTargets,RefactoringTriageStatus,@@ -135,6 +136,8 @@ export interface RefactoringOpportunityParams {search?: string;/** Only opportunities carrying at least one mechanical step. */mechanical?: boolean;+ /** `fix_first` (server default for the open queue) or `all`, the full inventory. */+ scope?: RefactoringScope;view?: RefactoringView;order?: RefactoringOrder;/** Steps inlined per row. 0 for a list that renders counts and opens a drawer. */@@ -159,6 +162,7 @@ export async function getRefactoringOpportunities(// Only sent when true: the server defaults it to false, and sending// `false` would turn a shared default into a caller's assertion.mechanical: params.mechanical ? true : undefined,+ scope: params.scope,view: params.view,order: params.order,step_preview: params.stepPreview,diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.py b/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.pyindex 4f82f7074..dfb4af80a 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/refactoring_targets.py@@ -165,6 +165,7 @@ def _render_stored_refactoring_targets(return {"summary": summary,"total": page.total,+ "hidden": page.hidden,"details": details,"metrics": metrics,"findings": findings,@@ -181,10 +182,15 @@ def _render_stored_refactoring_targets(analyzed_commit = stored["summary"].get("analyzed_commit")if fmt == "table":commit = f" at {analyzed_commit[:7]}" if analyzed_commit else ""+ hidden = (stored["hidden"] or {}).get("total") or 0+ scope = (+ f"{stored['total']} worth doing ({hidden} more in the full inventory)"+ if stored["hidden"] is not None+ else f"{stored['total']} open opportunities"+ )console.print(- f"[dim]Read from the index{commit}. Showing {len(rows)} of "- f"{stored['total']} open opportunities. Pass --recompute to analyze the "- "working tree instead.[/dim]"+ f"[dim]Read from the index{commit}. Showing {len(rows)} of {scope}. "+ "Pass --recompute to analyze the working tree instead.[/dim]")_emit(targets,@@ -198,6 +204,7 @@ def _render_stored_refactoring_targets("source": "index","analyzed_commit": analyzed_commit,"opportunities_total": stored["total"],+ "opportunities_hidden": stored["hidden"],"targets": targets,"refactoring_opportunities": rows,"refactoring_plans": plans,diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/build.py b/packages/core/src/repowise/core/analysis/health/fix_first/build.pyindex 6fb7a11b2..a80715c8a 100644--- a/packages/core/src/repowise/core/analysis/health/fix_first/build.py+++ b/packages/core/src/repowise/core/analysis/health/fix_first/build.py@@ -152,6 +152,10 @@ LOW_VALUE_KINDS: dict[str, str] = {"move_method": "dev 0/14, all 0/34","low_cohesion": "dev 0/26, all 0/46","large_method": "dev 0/4, all 0/10",+ # Thinly measured: one held-out item (two labels), none on the dev repos.+ # A low-value maintainability nudge that otherwise fills a small repo's+ # whole top three; revisit when more of it is labelled.+ "primitive_obsession": "dev 0/0, all 0/2",}@@ -276,7 +280,7 @@ def _risk(files_touched: int, dependents: int | None) -> FixRisk:level = "low"parts = [f"touches {text.plural(files_touched, 'file')}"]if dependents:- parts.append(f"{text.plural(dependents, 'file')} import it")+ parts.append(text.imports_it(dependents))return FixRisk(level, dependents, files_touched, "; ".join(parts).capitalize() + ".")@@ -285,7 +289,8 @@ def _verify(profile: Mapping[str, Any] | None) -> FixVerify:if not profile:return FixVerify((), 0, None, "unknown")via = profile.get("via")- reason = f"reaches the changed code through the {text.humanize(via)}" if via else "covers it"+ how = text.TEST_VIA.get(via or "")+ reason = f"reaches the changed code {how}" if how else "covers it"tests = tuple(FixTest(str(t), reason) for t in (profile.get("tests") or [])[:MAX_TESTS])commands = profile.get("commands") or []basis = profile.get("basis")@@ -881,7 +886,28 @@ def _perf_value(row: Any, facets: Mapping[str, Any]) -> int:return value-def _perf_unit(rows: list[Any], files: _Files) -> _Unit:+def _perf_step_text(step: Mapping[str, Any], path: str) -> str:+ """A plan step's action, naming its function once: an action that already+ says the name is not followed by it again."""+ action = step.get("action") or ""+ name = text.scope_name(step.get("symbol"), path)+ if not name or name.rsplit(".", 1)[-1] in action:+ return action+ return f"{action} ({name})"+++def _site_symbol(symbol: str | None) -> str | None:+ """The function a call site sits in; ``None`` for none, or a file's top+ level, which is no symbol to jump to."""+ short = text.short_symbol(symbol)+ if not short or short.rsplit(".", 1)[-1] == "__module__":+ return None+ return short+++def _perf_unit(+ rows: list[Any], files: _Files, symbol_lines: Mapping[str, int] | None = None+) -> _Unit:lead = min(rows, key=lambda r: (field(r, "rank_position") or 0, field(r, "opportunity_id")))details = detail_map(lead)facets = details.get("facets") or {}@@ -902,6 +928,10 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:def fields() -> dict[str, Any]:# A cause with no intervention symbol is named by the function its plan edits.first = plan_steps[0] if plan_steps else {}+ lines = symbol_lines or {}+ # The lead observation: the first call site the plan names. The item+ # points at the loop around it, else at the call itself.+ site = next((s for s in plan_steps if s.get("line")), None)name = (text.scope_name(symbol, path)or text.scope_name(first.get("symbol"), path)@@ -940,12 +970,12 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:FixFact("files", str(files_n)),FixFact("reachable from an entry point",- {"entry_reachable": "Yes", "not_entry_reachable": "No"}.get(exposure or "", "Unknown"),+ text.REACH_ANSWER.get(exposure or "", "unknown"),"inferred" if exposure in ("entry_reachable", "not_entry_reachable") else "unknown",),FixFact("loop size",- text.humanize(magnitude) if magnitude and magnitude != "n/a" else "unknown",+ text.loop_size(magnitude),"inferred" if magnitude in ("grows_with_data", "bounded") else "unknown",),]@@ -955,10 +985,9 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:steps = tuple(FixStep(int(s.get("order") or i + 1),- s.get("action", "")- + (f" ({text.scope_name(s.get('symbol'), path)})" if s.get("symbol") else ""),+ _perf_step_text(s, path),s.get("file_path") or path,- s.get("line"),+ s.get("line") or lines.get(s.get("symbol") or ""),s.get("applicability") == "mechanical",)for i, s in enumerate(plan_steps)@@ -966,10 +995,18 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:strategy = field(lead, "fix_strategy") or ""return {"title": text.clip(title),- "target": FixTarget(- path,- name if (symbol or first.get("symbol")) and not module else None,- first.get("line"),+ "target": (+ FixTarget(+ site.get("file_path") or path,+ _site_symbol(site.get("symbol")),+ site.get("loop_line") or site.get("line"),+ )+ if site+ else FixTarget(+ path,+ name if (symbol or first.get("symbol")) and not module else None,+ steps[0].line if steps else None,+ )),"why": f"{what}; {', '.join(reach) or 'the loop size is unknown'}.","facts": tuple(facts[:MAX_FACTS]),@@ -1012,9 +1049,11 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:improves="performance",rank_inputs=lambda: [FixRankFact("runs in", field(lead, "execution_context") or "unknown"),- FixRankFact("entry reachable", text.humanize(exposure or "unknown")),- FixRankFact("loop size", text.humanize(magnitude or "unknown")),- FixRankFact("boundary", field(lead, "boundary_kind") or "none"),+ FixRankFact("entry reachable", text.REACH_ANSWER.get(exposure or "", "unknown")),+ FixRankFact("loop size", text.loop_size(magnitude)),+ FixRankFact(+ "boundary", text.BOUNDARY_NOUN.get(field(lead, "boundary_kind") or "", "none")+ ),],fields=fields,)@@ -1110,6 +1149,29 @@ def _small(shape: Mapping[str, int]) -> bool:return nloc < SMALL_NLOC and shape.get("ccn", 0) < SMALL_CCN+def _refactor_exclusion(+ gain: float,+ steps: list[Mapping[str, Any]],+ plans: Mapping[str, Any],+ files: _Files,+ path: str,+) -> str | None:+ """Why an open refactoring opportunity in scope is no candidate, or ``None``."""+ if gain < MIN_WORTH or not steps:+ return "below_min_worth"+ lead = steps[0]+ if lead.get("refactoring_type") in LOW_VALUE_KINDS:+ return "low_value_kind"+ reason = files.unit_exclusion(+ path,+ lead.get("target_symbol"),+ complexity=lead.get("refactoring_type") == "extract_method",+ )+ if reason is None and not _concrete(lead, plans.get(lead.get("plan_id"))):+ return "no_concrete_step"+ return reason++def _finding_exclusion(finding: Any, files: _Files) -> str | None:if field(finding, "biomarker_type") in LOW_VALUE_KINDS:return "low_value_kind"@@ -1246,6 +1308,7 @@ def build_fix_first(basis: Mapping[str, str | None] | None = None,item_id: str | None = None,hot_cuts: tuple[float, float] | None = None,+ symbol_lines: Mapping[str, int] | None = None,) -> FixFirstQueue:"""One ranked queue of what to fix, from stored rows (shapes in the module docstring).@@ -1255,7 +1318,9 @@ def build_fix_first(``item_id`` keeps just that item, at its rank, for a lookup by id.``hot_cuts`` are the (churn, dependents) thresholds for a hot file when thecaller measured them over more files than it passed in ``metrics``; see- :func:`hot_cut` for the rule.+ :func:`hot_cut` for the rule. ``symbol_lines`` maps a symbol id+ (``path::name``) to its first line, for a performance plan step that+ names a function but stored no line."""metrics = list(metrics)findings = list(findings)@@ -1283,45 +1348,36 @@ def build_fix_first(_extractions(plans),)- def out_of_scope(path: str, context: str | None = None) -> bool:+ def scope_reason(path: str, context: str | None = None) -> str | None:+ """Why ``path`` is out of scope, counted; ``None`` when it is in."""reason = _path_exclusion(path, files.is_test(path), context, files.origin(path))if reason is None or (reason == "test" and keep_tests):- return False+ return Noneexcluded[reason] += 1- return True+ return reason++ def out_of_scope(path: str, context: str | None = None) -> bool:+ return scope_reason(path, context) is not Noneplan_rows = {field(p, "public_id"): p for p in plans}units: list[_Unit] = []planned_files: set[str] = set()+ refactoring_reasons: dict[str, str | None] = {}for row in sorted((r for r in refactoring if _open(r)),key=lambda r: (field(r, "rank_position") or 0, field(r, "opportunity_id")),):path = field(row, "file_path")- if out_of_scope(path):- continue- if _num(field(row, "recoverable_health")) < MIN_WORTH:- excluded["below_min_worth"] += 1- continue+ reason = scope_reason(path)details = detail_map(row)steps = list(details.get("steps") or [])gain = _num(field(row, "recoverable_health"))- if not steps:- excluded["below_min_worth"] += 1- continue- reason = (- "low_value_kind"- if steps[0].get("refactoring_type") in LOW_VALUE_KINDS- else files.unit_exclusion(- path,- steps[0].get("target_symbol"),- complexity=steps[0].get("refactoring_type") == "extract_method",- )- )- if reason is None and not _concrete(steps[0], plan_rows.get(steps[0].get("plan_id"))):- reason = "no_concrete_step"+ if reason is None:+ reason = _refactor_exclusion(gain, steps, plan_rows, files, path)+ if reason is not None:+ excluded[reason] += 1+ refactoring_reasons[field(row, "opportunity_id")] = reasonif reason is not None:- excluded[reason] += 1continueunits.append(_refactor_unit(row, details, steps, gain, plan_rows, files))# Only a plan that became an item speaks for the file's findings; an@@ -1353,7 +1409,7 @@ def build_fix_first(if not worth:excluded["below_min_worth"] += 1continue- units.append(_perf_unit(worth, files))+ units.append(_perf_unit(worth, files, symbol_lines))for path, (shape, history) in split.items():if path in planned_files:@@ -1392,6 +1448,7 @@ def build_fix_first(),by_improves={k: by_improves.get(k, 0) for k in FIX_IMPROVES},basis=dict(basis) if basis is not None else _basis(metrics),+ refactoring_reasons=refactoring_reasons,)diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/model.py b/packages/core/src/repowise/core/analysis/health/fix_first/model.pyindex 783604db0..6d4ad25b2 100644--- a/packages/core/src/repowise/core/analysis/health/fix_first/model.py+++ b/packages/core/src/repowise/core/analysis/health/fix_first/model.py@@ -231,6 +231,10 @@ class FixFirstQueue:basis: dict[str, str | None] = field(default_factory=lambda: {"analyzed_commit": None, "health_analyzed_at": None})+ #: Every open refactoring opportunity the builder read, by id: ``None``+ #: when it is eligible, else the exclusion that kept it out. The+ #: refactoring view's default scope reads it; never on the wire.+ refactoring_reasons: dict[str, str | None] = field(default_factory=dict)@propertydef lead(self) -> FixItem | None:diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/text.py b/packages/core/src/repowise/core/analysis/health/fix_first/text.pyindex 2eb158a5d..02b997528 100644--- a/packages/core/src/repowise/core/analysis/health/fix_first/text.py+++ b/packages/core/src/repowise/core/analysis/health/fix_first/text.py@@ -93,6 +93,18 @@ PERF_SHAPE: dict[str, tuple[str, str, str]] = {),}+#: How a verify block found its tests, completing "reaches the changed code ...".+TEST_VIA: dict[str, str] = {+ "coverage": "in a coverage report",+ "call-graph": "through the call graph",+ "import-graph": "through the import graph",+ "name-match": "by a matching test name",+ "mixed": "through the call and import graphs",+}++#: Whether an entry point reaches a performance cause, as a short answer.+REACH_ANSWER: dict[str, str] = {"entry_reachable": "yes", "not_entry_reachable": "no"}+FIX_STRATEGY: dict[str, str] = {"batch_or_prefetch_io": "Batch the calls, or fetch the data once before the loop","replace_membership_collection": "Use a set or dict for the membership test",@@ -105,6 +117,18 @@ def humanize(token: str) -> str:return token.replace("_", " ")+def loop_size(magnitude: str | None) -> str:+ """``grows with data``, ``bounded``, ``no loop`` or ``unknown``."""+ if magnitude == "n/a":+ return "no loop"+ return humanize(magnitude) if magnitude else "unknown"+++def imports_it(dependents: int) -> str:+ """``1 file imports it`` / ``7 files import it``."""+ return f"{plural(dependents, 'file')} import{'s' if dependents == 1 else ''} it"++def plural(n: int, noun: str) -> str:return f"{n:,} {noun}" if n == 1 else f"{n:,} {noun}s"@@ -211,7 +235,7 @@ def exposure(dependents: int | None, commits: int, coverage: float | None = Noneits lines``, or nothing. Coverage only when a report measured the file."""parts = []if dependents:- parts.append(f"{plural(dependents, 'file')} import{'s' if dependents == 1 else ''} it")+ parts.append(imports_it(dependents))if commits:parts.append(f"changed {plural(commits, 'time')} in 90 days")if coverage is not None:@@ -331,7 +355,9 @@ __all__ = ["HISTORY_LABEL","PERF_SHAPE","PROBLEM",+ "REACH_ANSWER","REFACTOR_TITLE",+ "TEST_VIA","TITLE_MAX","basename","changes",@@ -341,6 +367,8 @@ __all__ = ["health_gain","history_fact","humanize",+ "imports_it",+ "loop_size","marker_label","measured","plural",diff --git a/packages/core/src/repowise/core/analysis/health/perf/facts.py b/packages/core/src/repowise/core/analysis/health/perf/facts.pyindex 796355b5a..83c998b93 100644--- a/packages/core/src/repowise/core/analysis/health/perf/facts.py+++ b/packages/core/src/repowise/core/analysis/health/perf/facts.py@@ -147,6 +147,9 @@ def evidence_row(facts: ObservationFacts) -> dict[str, Any]:"reason": facts.reason,"path": list(facts.details.get("path", ())),"provenance": facts.resolution_basis,+ # The loop around the call, where a reader starts; absent when the+ # walk stored none, so older evidence reads unchanged.+ **({"loop_line": loop} if (loop := facts.details.get("loop_line")) else {}),}diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py b/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.pyindex 851c9708e..5e40cf20d 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py@@ -90,6 +90,7 @@ def fix_steps("symbol": location.get("function_name"),"file_path": location.get("file_path"),"line": location.get("line_start"),+ **({"loop_line": location["loop_line"]} if location.get("loop_line") else {}),"applicability": applicability,}for location in locations@@ -149,6 +150,7 @@ def _suggestion("function_name": item.get("function_name"),"line_start": item.get("line_start"),"line_end": item.get("line_end"),+ **({"loop_line": item["loop_line"]} if item.get("loop_line") else {}),}for item in opportunity.evidence]diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py b/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.pyindex f8a687c8c..a71d32eb1 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py@@ -37,6 +37,7 @@ from repowise.core.analysis.health.scoring import history_biomarkersfrom ...models import (GitMetadata,GraphMetric,+ GraphNode,HealthFileMetric,HealthFinding,PerformanceOpportunity,@@ -340,6 +341,27 @@ async def _plans()+async def _symbol_lines(session: AsyncSession, repo_id: str, performance: list[Any]) -> dict[str, int]:+ """First lines of the functions a performance plan step names with no+ line of its own (the intervention a batched form is added to)."""+ wanted = {+ step["symbol"]+ for row in performance+ if row.details+ for step in (row.details.get("plan") or {}).get("steps") or ()+ if not step.get("line") and "::" in (step.get("symbol") or "")+ }+ if not wanted:+ return {}+ g = GraphNode+ rows = await session.execute(+ select(g.node_id, g.start_line).where(+ g.repository_id == repo_id, g.node_id.in_(wanted), g.start_line.is_not(None)+ )+ )+ return {node_id: line for node_id, line in rows.all()}++#: Built queues kept in process. A handful covers the shapes one surface asks#: for (dashboard, CLI, Do next, one id), per repository a server holds.CACHE_SIZE = 32@@ -434,6 +456,7 @@ async def _build(item_id=item_id,basis=await _basis(session, repository_id),hot_cuts=await _hot_cuts(session, repository_id),+ symbol_lines=await _symbol_lines(session, repository_id, performance),)diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.pyindex 4fa65a96f..d8d71ca00 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py@@ -511,11 +511,16 @@ def _opportunity_filters(path_prefix: str | None,mechanical_only: bool,addresses_primary: bool | None,+ opportunity_ids: list[str] | None = None,) -> list[Any]:predicates: list[Any] = [RefactoringOpportunity.repository_id == repository_id,RefactoringOpportunity.status == status,]+ if opportunity_ids is not None:+ # A scope resolved in Python (Fix first's eligible set); an empty one+ # matches nothing, as ``file_paths`` does.+ predicates.append(RefactoringOpportunity.opportunity_id.in_(opportunity_ids))if lead_types:# One value is still one equality; a list is how the board's# "Structural" tab asks for its four types without four round trips.@@ -571,6 +576,7 @@ async def list_refactoring_opportunities(path_prefix: str | None = None,mechanical_only: bool = False,addresses_primary: bool | None = None,+ opportunity_ids: list[str] | None = None,order: str = DEFAULT_ORDER,limit: int = 20,offset: int = 0,@@ -587,6 +593,7 @@ async def list_refactoring_opportunities(path_prefix=path_prefix,mechanical_only=mechanical_only,addresses_primary=addresses_primary,+ opportunity_ids=opportunity_ids,)total = int((@@ -606,6 +613,37 @@ async def list_refactoring_opportunities(return rows, total+async def refactoring_opportunity_ids(+ session: AsyncSession,+ repository_id: str,+ *,+ status: str = "open",+ lead_types: list[str] | None = None,+ confidence: str | None = None,+ effort: str | None = None,+ file_paths: list[str] | None = None,+ path_contains: str | None = None,+ path_prefix: str | None = None,+ mechanical_only: bool = False,+ addresses_primary: bool | None = None,+) -> list[str]:+ """The ids the same filters match, unpaged: one narrow column."""+ predicates = _opportunity_filters(+ repository_id,+ status=status,+ lead_types=lead_types,+ confidence=confidence,+ effort=effort,+ file_paths=file_paths,+ path_contains=path_contains,+ path_prefix=path_prefix,+ mechanical_only=mechanical_only,+ addresses_primary=addresses_primary,+ )+ rows = await session.execute(select(RefactoringOpportunity.opportunity_id).where(*predicates))+ return [opportunity_id for (opportunity_id,) in rows.all()]++async def get_refactoring_opportunity(session: AsyncSession, repository_id: str, opportunity_id: str) -> RefactoringOpportunity | None:@@ -704,12 +742,17 @@ async def get_refactoring_summary(async def refactoring_facet_counts(- session: AsyncSession, repository_id: str, *, status: str = "open"+ session: AsyncSession,+ repository_id: str,+ *,+ status: str = "open",+ opportunity_ids: list[str] | None = None,) -> 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 onestatement each, so adding a facet never adds a round trip.+ ``opportunity_ids`` narrows the counts to a scope the list applies too."""columns = (RefactoringOpportunity.lead_refactoring_type,@@ -721,6 +764,11 @@ async def refactoring_facet_counts(.where(RefactoringOpportunity.repository_id == repository_id,RefactoringOpportunity.status == status,+ *(+ [RefactoringOpportunity.opportunity_id.in_(opportunity_ids)]+ if opportunity_ids is not None+ else []+ ),).group_by(*columns))@@ -743,5 +791,6 @@ __all__ = ["get_refactoring_summary","list_refactoring_opportunities","refactoring_facet_counts",+ "refactoring_opportunity_ids","update_refactoring_opportunity_status",]diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/loading.py b/packages/server/src/repowise/server/mcp_server/tool_health/loading.pyindex 478d2cd5e..c7f7a3008 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/loading.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/loading.py@@ -276,6 +276,7 @@ async def _read_pillars(lead_type=req.refactoring_type,confidence=req.refactoring_confidence,effort=req.refactoring_effort,+ scope=req.refactoring_scope,)performance = await _performance_blocks(performance_service,diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/pillars.py b/packages/server/src/repowise/server/mcp_server/tool_health/pillars.pyindex 18ba0d388..66da4e61e 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/pillars.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/pillars.py@@ -130,6 +130,7 @@ async def _refactoring_blocks(lead_type: str | None = None,confidence: str | None = None,effort: str | None = None,+ scope: str | None = None,) -> _RefactoringBlocks:"""Read the materialized queue and its rollup.@@ -149,6 +150,7 @@ async def _refactoring_blocks(lead_type=lead_type,confidence=confidence,effort=effort,+ scope=scope,file_paths=list(file_paths) if file_paths is not None else None,limit=min(max(limit, 0), _REFACTORING_COLLECTION_CAP) if emits_queue else 1,offset=cursor if emits_queue else 0,@@ -179,6 +181,10 @@ def _render_refactoring(result["refactoring_opportunities"] = page.itemsresult["refactoring_opportunities_total"] = page.totalresult["refactoring_opportunities_emitted"] = len(page.items)+ result["refactoring_opportunities_scope"] = page.scope+ if page.hidden is not None:+ # What the default scope leaves out, by reason; ``all`` lists it.+ result["refactoring_opportunities_hidden"] = page.hiddenif len(page.items) < page.total:result["refactoring_opportunities_reduced_reason"] = ("collection_cap" if req.limit > _REFACTORING_COLLECTION_CAP else "limit"diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py b/packages/server/src/repowise/server/mcp_server/tool_health/projection.pyindex b2cb257e4..f7f07f9f0 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/projection.py@@ -86,7 +86,8 @@ def _project("""if not req.only:return result- # Each kept list keeps its ``*_total`` siblings, so truncation stays visible.+ # Each kept list keeps its ``*_total`` siblings, so truncation stays visible,+ # and the scope its total is over, with what that scope left out.keep = (set(req.only_list)| _ALWAYS_KEPT@@ -97,6 +98,8 @@ def _project(f"{k}_total",f"{k}_emitted",f"{k}_reduced_reason",+ f"{k}_scope",+ f"{k}_hidden",)})diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/request.py b/packages/server/src/repowise/server/mcp_server/tool_health/request.pyindex c497f8957..f609d1352 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/request.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/request.py@@ -61,6 +61,7 @@ class HealthRequest:refactoring_type: str | Nonerefactoring_confidence: str | Nonerefactoring_effort: str | None+ refactoring_scope: str | Noneperformance_view: str | Noneperformance_context: str | Noneperformance_boundary: str | Nonediff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.pyindex 306006459..199921f29 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py@@ -128,6 +128,7 @@ async def get_health(refactoring_type: str | None = None,refactoring_confidence: str | None = None,refactoring_effort: str | None = None,+ refactoring_scope: str | None = None,cursor: int = 0,finding_id: str | None = None,plan_id: str | None = None,@@ -166,7 +167,7 @@ async def get_health(opportunity_id: ``perf...``/``refop...``: the unit, its steps orplan, evidence paged by ``only=["*_evidence"]``.refactoring_view: ``diversified`` (default)|``canonical``|- ``file_spread``; _type/_confidence/_effort filter.+ ``file_spread``; _type/_confidence/_effort/_scope filter.performance_view/_context/_boundary/_confidence/_actionability/_sort:queue filters.scope / counts: default ``all``/``everything``. ``production`` drops@@ -190,6 +191,7 @@ async def get_health(refactoring_type=refactoring_type,refactoring_confidence=refactoring_confidence,refactoring_effort=refactoring_effort,+ refactoring_scope=refactoring_scope,performance_view=performance_view,performance_context=performance_context,performance_boundary=performance_boundary,diff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.pyindex 0e9290b61..e8456c583 100644--- a/packages/server/src/repowise/server/routers/refactoring.py+++ b/packages/server/src/repowise/server/routers/refactoring.py@@ -409,6 +409,13 @@ async def get_refactoring_opportunities(file_path: str | None = Query(None, description="One repo-relative file path"),search: str | None = Query(None, description="Substring of the file path"),mechanical: bool = Query(False, description="Only opportunities with a mechanical step"),+ scope: str | None = Query(+ None,+ description=(+ "fix_first (default for the open queue with no file_path): only what Fix first "+ "would take, the rest counted in `hidden` | all: the full inventory"+ ),+ ),view: str = Query(DEFAULT_VIEW, description=" | ".join(CANONICAL_VIEWS)),order: str | None = Query(None, description=" | ".join(CANONICAL_ORDERS)),step_preview: int = Query(@@ -440,6 +447,7 @@ async def get_refactoring_opportunities(order=order,limit=limit,offset=offset,+ scope=scope,)page = await _service(session, repo_id).page(query,@@ -455,7 +463,10 @@ async def get_refactoring_opportunities("next_offset": page.next_offset,"facets": page.facets,"summary": page.summary,+ "scope": page.scope,}+ if page.hidden is not None:+ body["hidden"] = page.hiddenif ignored:body["ignored_arguments"] = ignoredreturn bodydiff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.pyindex 2a9871c4e..2e01c708a 100644--- a/packages/server/src/repowise/server/schemas/__init__.py+++ b/packages/server/src/repowise/server/schemas/__init__.py@@ -229,6 +229,7 @@ if TYPE_CHECKING:PatchCoverageTestHint,)from .refactoring import (+ RefactoringHiddenCounts,RefactoringOpportunitiesResponse,RefactoringOpportunityDetailResponse,RefactoringOpportunityStatusResponse,@@ -511,6 +512,7 @@ _EXPORTS: dict[str, tuple[str, ...]] = {"PatchCoverageTestHint",),"refactoring": (+ "RefactoringHiddenCounts","RefactoringOpportunitiesResponse","RefactoringOpportunityDetailResponse","RefactoringOpportunityStatusResponse",@@ -778,6 +780,7 @@ __all__ = ["ProviderEntry","ProviderStatusResponse","ProviderValidationResponse",+ "RefactoringHiddenCounts","RefactoringOpportunitiesResponse","RefactoringOpportunityDetailResponse","RefactoringOpportunityStatusResponse",diff --git a/packages/server/src/repowise/server/schemas/refactoring.py b/packages/server/src/repowise/server/schemas/refactoring.pyindex d113fde1f..d9fb52974 100644--- a/packages/server/src/repowise/server/schemas/refactoring.py+++ b/packages/server/src/repowise/server/schemas/refactoring.py@@ -9,11 +9,19 @@ schemas exist to prevent. The envelopes around them are pinned.from __future__ import annotations-from typing import Any+from typing import Any, Literalfrom pydantic import BaseModel, ConfigDict+class RefactoringHiddenCounts(BaseModel):+ """What the ``fix_first`` scope leaves out of a page's filtered set."""++ total: int = 0+ #: Count per Fix-first exclusion reason, largest first.+ by_reason: dict[str, int] = {}++class RefactoringOpportunitiesResponse(BaseModel):"""One page of composed opportunities, with facets and the rollup."""@@ -29,6 +37,10 @@ class RefactoringOpportunitiesResponse(BaseModel):summary: dict[str, Any] | None = None#: Present only when the request carried arguments the query ignored.ignored_arguments: dict[str, str] | None = None+ #: ``fix_first``: only what Fix first would take; ``all``: the inventory.+ scope: Literal["fix_first", "all"] = "all"+ #: Under ``fix_first``, the rest of the filtered set, by reason.+ hidden: RefactoringHiddenCounts | None = Noneclass RefactoringRollupResponse(BaseModel):diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.pyindex 81a7ad633..f078d3fd1 100644--- a/packages/server/src/repowise/server/services/refactoring_health.py+++ b/packages/server/src/repowise/server/services/refactoring_health.py@@ -16,6 +16,7 @@ module reads what the finalizer wrote.from __future__ import annotationsimport json+from collections import Counterfrom collections.abc import Sequencefrom dataclasses import dataclass, fieldfrom typing import Any, Literal@@ -23,11 +24,13 @@ from typing import Any, Literalfrom sqlalchemy import or_, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.persistence.crud.analysis.fix_first import load_fix_firstfrom repowise.core.persistence.crud.analysis.refactoring_opportunities import (get_refactoring_opportunity,get_refactoring_summary,list_refactoring_opportunities,refactoring_facet_counts,+ refactoring_opportunity_ids,)from repowise.core.persistence.models import RefactoringOpportunity, RefactoringSuggestion@@ -53,6 +56,17 @@ DEFAULT_VIEW = "diversified"# default resolves to the value that list has always defaulted to._PLAN_VIEWS = {"canonical": "canonical", "file_spread": "file_spread", "diversified": "canonical"}+# Which open opportunities a queue lists:+#+# - ``fix_first`` the default for a repository-wide open queue: only the+# opportunities Fix first would take (its eligibility and exclusion rules,+# read from the same builder), with the rest counted by reason.+# - ``all`` the full inventory. The default when the caller names files (a+# file surface asks for its own work) or lists a triaged status, which Fix+# first never reads.+SCOPES = ("fix_first", "all")+DEFAULT_SCOPE = "fix_first"+# The triage vocabulary, shared with health findings._STATUSES = ("open", "acknowledged", "resolved", "false_positive")@@ -92,6 +106,7 @@ class RefactoringQuery:order: str | None = Nonelimit: int = 20offset: int = 0+ scope: str = DEFAULT_SCOPE@propertydef resolved_order(self) -> str:@@ -110,6 +125,10 @@ class RefactoringPage:facets: dict[str, dict[str, int]] = field(default_factory=dict)summary: dict[str, Any] | None = Noneignored_arguments: dict[str, str] = field(default_factory=dict)+ scope: str = "all"+ #: Under ``fix_first``: the opportunities the same filters match that Fix+ #: first leaves out, ``{"total": n, "by_reason": {reason: n}}``.+ hidden: dict[str, Any] | None = Nonedef parse_query(@@ -127,6 +146,7 @@ def parse_query(order: str | None = None,limit: int = 20,offset: int = 0,+ scope: str | None = None,) -> tuple[RefactoringQuery, dict[str, str]]:"""Normalize a caller's arguments, naming anything it had to discard.@@ -165,10 +185,16 @@ def parse_query(if resolved_view not in _VIEW_ORDERS:ignored["refactoring_view"] = resolved_viewresolved_view = DEFAULT_VIEW+ resolved_status = admit("status", status, _STATUSES) or "open"+ resolved_scope = admit("scope", scope, SCOPES) or (+ "all" if file_paths is not None else DEFAULT_SCOPE+ )+ if resolved_status != "open":+ resolved_scope = "all" # Fix first reads open opportunities only.return (RefactoringQuery(lead_types=admit_many("refactoring_type", lead_type, _TYPES),- status=admit("status", status, _STATUSES) or "open",+ status=resolved_status,confidence=admit("confidence", confidence, _CONFIDENCES),effort=admit("effort", effort, _EFFORTS),mechanical_only=bool(mechanical),@@ -184,6 +210,7 @@ def parse_query(order=admit("order", order, CANONICAL_ORDERS),limit=max(int(limit), 0),offset=max(int(offset), 0),+ scope=resolved_scope,),ignored,)@@ -238,19 +265,31 @@ class RefactoringHealthService:filters over the open set, so those two are bounded by the open rowcount rather than by the page. Neither has a consumer yet - index themwhen one exists, not before.++ Under the ``fix_first`` scope the Fix-first queue (cached per store+ write) says which opportunities it takes, and one id-only read of the+ filtered set counts what it leaves out, by reason."""+ filters: dict[str, Any] = {+ "status": query.status,+ "lead_types": list(query.lead_types) if query.lead_types else None,+ "confidence": query.confidence,+ "effort": query.effort,+ "file_paths": list(query.file_paths) if query.file_paths is not None else None,+ "path_contains": query.path_contains,+ "path_prefix": query.path_prefix,+ "mechanical_only": query.mechanical_only,+ "addresses_primary": query.addresses_primary,+ }+ shown_ids: list[str] | None = None+ hidden: dict[str, Any] | None = None+ if query.scope == "fix_first":+ shown_ids, hidden = await self._fix_first_scope(filters)rows, total = await list_refactoring_opportunities(self._session,self._repository_id,- status=query.status,- lead_types=list(query.lead_types) if query.lead_types else None,- confidence=query.confidence,- effort=query.effort,- file_paths=list(query.file_paths) if query.file_paths is not None else None,- path_contains=query.path_contains,- path_prefix=query.path_prefix,- mechanical_only=query.mechanical_only,- addresses_primary=query.addresses_primary,+ **filters,+ opportunity_ids=shown_ids,order=query.resolved_order,limit=query.limit,offset=query.offset,@@ -270,13 +309,39 @@ class RefactoringHealthService:# set while the list shows the resolved one would put a badge on# a tab that returns nothing.await refactoring_facet_counts(- self._session, self._repository_id, status=query.status+ self._session,+ self._repository_id,+ status=query.status,+ opportunity_ids=shown_ids,)if with_facetselse {}),summary=await self.summary() if with_summary else None,+ scope=query.scope,+ hidden=hidden,+ )++ async def _fix_first_scope(+ self, filters: dict[str, Any]+ ) -> tuple[list[str], dict[str, Any]]:+ """The filtered ids Fix first takes, and what it leaves out by reason.++ Ceiling: the shown ids go back to the page read as an ``IN`` list, one+ entry per open opportunity Fix first takes (94 on this repository).+ Upgrade path: store the eligibility on the opportunity row at index+ time and filter on the column.+ """+ queue = await load_fix_first(self._session, self._repository_id, limit=0)+ reasons = queue.refactoring_reasons+ matched = await refactoring_opportunity_ids(+ self._session, self._repository_id, **filters)+ # The queue is keyed on the stores' newest write, so it has read every+ # open id; one written between the two reads is in neither count.+ shown = [i for i in matched if i in reasons and reasons[i] is None]+ left_out = Counter(r for i in matched if (r := reasons.get(i)))+ return shown, {"total": sum(left_out.values()), "by_reason": dict(left_out.most_common())}# -- headline ---------------------------------------------------------diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex d3ce2dc23..32702dd64 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -2634,6 +2634,12 @@ export interface ProviderValidationResponse {error?: string | null;}+/** What the ``fix_first`` scope leaves out of a page's filtered set. */+export interface RefactoringHiddenCounts {+ total?: number;+ by_reason?: Record<string, number>;+}+/** One page of composed opportunities, with facets and the rollup. */export interface RefactoringOpportunitiesResponse {items?: Record<string, unknown>[];@@ -2644,6 +2650,8 @@ export interface RefactoringOpportunitiesResponse {facets?: Record<string, Record<string, number>>;summary?: Record<string, unknown> | null;ignored_arguments?: Record<string, string> | null;+ scope?: "fix_first" | "all";+ hidden?: RefactoringHiddenCounts | null;}/**diff --git a/packages/types/src/refactoring.ts b/packages/types/src/refactoring.tsindex 551953fbe..33ab6489b 100644--- a/packages/types/src/refactoring.ts+++ b/packages/types/src/refactoring.ts@@ -1,5 +1,6 @@/** Canonical wire contract for structured refactoring recommendations. */+import type { FixExclusion } from "./fix-first.js";import type { Paginated } from "./pagination.js";export type RefactoringType =@@ -315,6 +316,19 @@ export type RefactoringView = "diversified" | "canonical" | "file_spread";*/export type RefactoringOrder = "queue" | "rank" | "health" | "effort" | "file";+/**+ * Which open opportunities a queue lists. ``fix_first`` (the default for the+ * repository-wide open queue) keeps only what Fix first would take; ``all`` is+ * the full inventory, and the default for a file or a triaged status.+ */+export type RefactoringScope = "fix_first" | "all";++/** What the ``fix_first`` scope leaves out of the filtered set, by reason. */+export interface RefactoringHiddenCounts {+ total: number;+ by_reason: Partial<Record<FixExclusion, number>>;+}+/** No stored analysis: the counts genuinely do not exist, so none are present. */export interface RefactoringRollupUnavailable {status: "unavailable";@@ -400,6 +414,10 @@ export interface RefactoringOpportunityPage {summary: RefactoringOpportunityRollup | null;/** Values the server could not admit, named rather than dropped. */ignored_arguments?: Record<string, string>;+ /** The scope the server applied, which `total` and `facets` count. */+ scope?: RefactoringScope;+ /** Under ``fix_first`` only. */+ hidden?: RefactoringHiddenCounts;}/** ``GET /api/repos/{repo_id}/refactoring/summary``. */diff --git a/packages/ui/__tests__/health/fixtures/fix-first.ts b/packages/ui/__tests__/health/fixtures/fix-first.tsindex 86351fac0..0af3957af 100644--- a/packages/ui/__tests__/health/fixtures/fix-first.ts+++ b/packages/ui/__tests__/health/fixtures/fix-first.ts@@ -328,7 +328,7 @@ export const FIX_FIRST_QUEUE: FixFirstQueue = {"steps": [{"order": 1,- "text": "Add a form of ensure_repo_registration that takes every key at once (ensure_repo_registration)",+ "text": "Add a form of ensure_repo_registration that takes every key at once","file_path": "packages/server/src/repowise/server/repo_db.py","line": null,"mechanical": falsediff --git a/packages/ui/__tests__/refactoring/phase4-plan-contract.test.tsx b/packages/ui/__tests__/refactoring/phase4-plan-contract.test.tsxindex 8e9935a27..377e453b1 100644--- a/packages/ui/__tests__/refactoring/phase4-plan-contract.test.tsx+++ b/packages/ui/__tests__/refactoring/phase4-plan-contract.test.tsx@@ -97,6 +97,9 @@ describe("Phase 4 structured plan contract", () => {effort: null,confidence: null,mechanicalOnly: false,+ scope: "all",+ appliedScope: "all",+ hidden: null,total: 1,offset: 0,nextOffset: null,diff --git a/packages/ui/__tests__/refactoring/refactoring-board-scope.test.tsx b/packages/ui/__tests__/refactoring/refactoring-board-scope.test.tsxnew file mode 100644index 000000000..5e00d718a--- /dev/null+++ b/packages/ui/__tests__/refactoring/refactoring-board-scope.test.tsx@@ -0,0 +1,107 @@+import { fireEvent, render, screen } from "@testing-library/react";+import { describe, expect, it, vi } from "vitest";+import type { RefactoringOpportunity } from "@repowise-dev/types/refactoring";++import {+ RefactoringBoard,+ type RefactoringBoardServerState,+} from "../../src/refactoring/refactoring-board";++const opportunity: RefactoringOpportunity = {+ opportunity_id: "refop2_scope",+ refactoring_model_version: 2,+ status: "open",+ file_path: "src/core.py",+ lead_biomarker: "complex_method",+ lead_refactoring_type: "extract_method",+ addresses_primary_problem: true,+ effort_bucket: "S",+ confidence: "high",+ step_count: 1,+ mechanical_steps: 1,+ judgment_steps: 0,+ evidence_total: 0,+ affected_files_total: 1,+ recoverable_health: 1.2,+ rank_score: 1.2,+ rank_position: 1,+ queue_position: 1,+ rank_factors: {},+ why_ranked: [],+};++const state: RefactoringBoardServerState = {+ query: "",+ order: "queue",+ status: "open",+ effort: null,+ confidence: null,+ mechanicalOnly: false,+ scope: "fix_first",+ appliedScope: "fix_first",+ hidden: { total: 3, by_reason: { test: 2, below_min_worth: 1 } },+ total: 1,+ offset: 0,+ nextOffset: null,+};++function board(over: Partial<RefactoringBoardServerState> = {}, onChange = vi.fn()) {+ render(+ <RefactoringBoard+ opportunities={[opportunity]}+ showLede={false}+ serverState={{ ...state, ...over }}+ onServerStateChange={onChange}+ />,+ );+ return onChange;+}++describe("RefactoringBoard scope", () => {+ it("says how many are worth doing and how many the inventory adds, with reasons", () => {+ board();+ expect(+ screen.getByRole("heading", {+ name: "Showing 1 worth doing; 3 more in the full inventory",+ }),+ ).toBeTruthy();+ expect(screen.getByText("Left out: 2 in tests, 1 below the worth floor.")).toBeTruthy();+ expect(screen.getByRole("radio", { name: "Worth doing" }).getAttribute("aria-checked")).toBe(+ "true",+ );+ });++ it("switches to the full inventory from the first page", () => {+ const onChange = board();+ fireEvent.click(screen.getByRole("radio", { name: "Full inventory" }));+ expect(onChange).toHaveBeenCalledWith({ scope: "all", offset: 0 });+ });++ it("counts the inventory in its own words", () => {+ board({ scope: "all", appliedScope: "all", hidden: null, total: 4 });+ expect(screen.getByText(/4 open\s+opportunities/)).toBeTruthy();+ expect(screen.queryByText(/worth doing;/)).toBeNull();+ });++ it("disables Worth doing for a triaged status, with the reason", () => {+ board({ status: "resolved", appliedScope: "all", hidden: null });+ const worth = screen.getByRole("radio", { name: /Worth doing/ });+ expect(worth.getAttribute("aria-disabled")).toBe("true");+ expect(screen.getByText("Fix first ranks open opportunities only.")).toBeTruthy();+ });++ it("says why an empty page is empty when the default left everything out", () => {+ render(+ <RefactoringBoard+ opportunities={[]}+ showLede={false}+ summary={null}+ serverState={{ ...state, total: 0, query: "tests/" }}+ onServerStateChange={() => {}}+ />,+ );+ expect(+ screen.getByText("None of these is worth doing first. 3 more are in the full inventory."),+ ).toBeTruthy();+ });+});diff --git a/packages/ui/src/health/fix-first/scope.ts b/packages/ui/src/health/fix-first/scope.tsindex de97e8af5..866eb740e 100644--- a/packages/ui/src/health/fix-first/scope.ts+++ b/packages/ui/src/health/fix-first/scope.ts@@ -78,10 +78,18 @@ export function fixFirstScopeSentence(queue: FixFirstQueue<unknown>): string {const head = `${formatNumber(shown)} of ${formatNumber(eligible)} eligible item${eligible === 1 ? "" : "s"}.`;- const parts = EXCLUSION_ORDER.filter((key) => (excluded[key] ?? 0) > 0).map(- (key) => `${formatNumber(excluded[key])} ${EXCLUSION_LABEL[key]}`,- );- return parts.length ? `${head} Excluded: ${parts.join(", ")}.` : head;+ const parts = exclusionPhrase(excluded);+ return parts ? `${head} Excluded: ${parts}.` : head;+}++/**+ * `3 in tests, 12 below the worth floor`: each nonzero exclusion count with+ * its words, in the sentence order. Empty when nothing was excluded.+ */+export function exclusionPhrase(counts: Partial<Record<FixExclusion, number>>): string {+ return EXCLUSION_ORDER.filter((key) => (counts[key] ?? 0) > 0)+ .map((key) => `${formatNumber(counts[key] ?? 0)} ${EXCLUSION_LABEL[key]}`)+ .join(", ");}/** `path:60`, or the path alone when core stored no line. */diff --git a/packages/ui/src/refactoring/refactoring-board.tsx b/packages/ui/src/refactoring/refactoring-board.tsxindex 79efd8d47..0f20abec8 100644--- a/packages/ui/src/refactoring/refactoring-board.tsx+++ b/packages/ui/src/refactoring/refactoring-board.tsx@@ -21,6 +21,12 @@* it, so it stays available here as a named order rather than becoming the* default and quietly making this a second, worse copy of that page.*+ * **The list defaults to what Fix first would take.** Every per-file+ * opportunity is a lot of rows (702 on this repository), most of them below+ * the worth floor or in tests. Core's Fix-first rules decide which are worth+ * doing; the scope control switches to the full inventory, and the count line+ * says how many the default leaves out and why.+ ** Filters are server-owned and single-valued, which is what the queue endpoint* admits: one effort, one confidence. Chips toggle rather than accumulate, and* the confidence row is built from the confidences actually present, so it@@ -33,6 +39,9 @@ import { Search } from "lucide-react";import { Input } from "../ui/input";import { FilterSelect } from "../health/code-health-controls";import { PaginationControls } from "../shared/pagination-controls";+import { Segmented } from "../shared/segmented";+import { exclusionPhrase } from "../health/fix-first/scope";+import { formatNumber } from "../lib/format";import { OpportunityRows } from "./opportunity-rows";import { RefactoringLede } from "./refactoring-lede";import { StartHere } from "./start-here";@@ -43,8 +52,10 @@ import type {EffortBucket,OpportunityStatus,RefactoringOpportunity,+ RefactoringHiddenCounts,RefactoringOpportunityRollup,RefactoringOrder,+ RefactoringScope,} from "@repowise-dev/types/refactoring";const PAGE_SIZE = 60;@@ -68,6 +79,12 @@ export interface RefactoringBoardServerState {effort: EffortBucket | null;confidence: Confidence | null;mechanicalOnly: boolean;+ /** The scope asked for: what Fix first would take, or the full inventory. */+ scope: RefactoringScope;+ /** The scope the server applied, which `total` counts. */+ appliedScope: RefactoringScope;+ /** Under `fix_first`, what the filtered set leaves out, by reason. */+ hidden: RefactoringHiddenCounts | null;total: number;offset: number;nextOffset: number | null;@@ -130,7 +147,9 @@ export function RefactoringBoard({const rollupTotal =summary && summary.status === "available" ? summary.opportunities_total : null;- if ((rollupTotal ?? opportunities.length) === 0 && serverState.status === "open") {+ // Empty only when the inventory is: the default scope can list none of it.+ const inventory = rollupTotal ?? serverState.total + (serverState.hidden?.total ?? 0);+ if (inventory === 0 && serverState.status === "open") {return (<div className="border-t border-[var(--color-border-default)] pt-10 text-center"><h3 className="text-sm font-semibold text-[var(--color-text-primary)]">{emptyTitle}</h3>@@ -148,6 +167,9 @@ export function RefactoringBoard({serverState.mechanicalOnly ||serverState.status !== "open";const resultTotal = serverState.total;+ const worthOnly = serverState.appliedScope === "fix_first";+ const hiddenTotal = serverState.hidden?.total ?? 0;+ const hiddenWhy = serverState.hidden ? exclusionPhrase(serverState.hidden.by_reason) : "";return (<div className="space-y-10">@@ -166,13 +188,34 @@ export function RefactoringBoard({) : null}<section className="space-y-4 border-t border-[var(--color-border-default)] pt-8">- <div>- <h2 className="text-lg font-semibold text-[var(--color-text-primary)]">{sectionTitle}</h2>- <p className="mt-1 max-w-[68ch] text-sm text-[var(--color-text-secondary)]">- One row is one file's work, with its steps in dependency-safe order. The- recommended order rotates cause and area so the head is a set of choices; every row- opens the same inspector with the full explanation.- </p>+ <div className="flex flex-wrap items-start justify-between gap-4">+ <div>+ <h2 className="text-lg font-semibold text-[var(--color-text-primary)]">+ {sectionTitle}+ </h2>+ <p className="mt-1 max-w-[68ch] text-sm text-[var(--color-text-secondary)]">+ One row is one file's work, with its steps in dependency-safe order. The+ recommended order rotates cause and area so the head is a set of choices; every row+ opens the same inspector with the full explanation.+ </p>+ </div>+ <Segmented<RefactoringScope>+ label="Scope"+ value={serverState.appliedScope}+ onChange={(scope) => onServerStateChange({ scope, offset: 0 })}+ options={[+ {+ value: "fix_first",+ label: "Worth doing",+ hint: "Only what Fix first would take",+ disabledReason:+ serverState.status === "open"+ ? undefined+ : "Fix first ranks open opportunities only.",+ },+ { value: "all", label: "Full inventory", hint: "Every open opportunity" },+ ]}+ /></div><div className="flex flex-wrap items-center gap-3">@@ -258,14 +301,31 @@ export function RefactoringBoard({/></div>- <div className="flex items-center justify-between">- <h3 className="text-sm font-semibold tabular-nums text-[var(--color-text-primary)]">- {resultTotal.toLocaleString()} {STATUS_LABEL[serverState.status].toLowerCase()}{" "}- opportunit{resultTotal === 1 ? "y" : "ies"}- {filtersActive ? (- <span className="font-normal text-[var(--color-text-tertiary)]"> matching</span>- ) : null}- </h3>+ <div className="flex items-start justify-between gap-4">+ {worthOnly ? (+ <div>+ <h3 className="text-sm font-semibold tabular-nums text-[var(--color-text-primary)]">+ Showing {formatNumber(resultTotal)} worth doing+ {filtersActive ? (+ <span className="font-normal text-[var(--color-text-tertiary)]"> that match</span>+ ) : null}+ ; {formatNumber(hiddenTotal)} more in the full inventory+ </h3>+ {hiddenWhy ? (+ <p className="mt-0.5 text-xs text-[var(--color-text-tertiary)]">+ Left out: {hiddenWhy}.+ </p>+ ) : null}+ </div>+ ) : (+ <h3 className="text-sm font-semibold tabular-nums text-[var(--color-text-primary)]">+ {resultTotal.toLocaleString()} {STATUS_LABEL[serverState.status].toLowerCase()}{" "}+ opportunit{resultTotal === 1 ? "y" : "ies"}+ {filtersActive ? (+ <span className="font-normal text-[var(--color-text-tertiary)]"> matching</span>+ ) : null}+ </h3>+ )}{filtersActive ? (<buttontype="button"@@ -288,8 +348,10 @@ export function RefactoringBoard({{opportunities.length === 0 ? (<p className="border-t border-[var(--color-border-default)] py-10 text-center text-sm text-[var(--color-text-tertiary)]">- {serverState.status === "open"- ? "No opportunities match these filters."+ {worthOnly && hiddenTotal > 0+ ? `None of these is worth doing first. ${formatNumber(hiddenTotal)} more are in the full inventory.`+ : serverState.status === "open"+ ? "No opportunities match these filters.": `Nothing has been marked ${STATUS_LABEL[serverState.status].toLowerCase()} yet.`}</p>) : (diff --git a/packages/web/src/app/repos/[id]/refactoring/page.tsx b/packages/web/src/app/repos/[id]/refactoring/page.tsxindex 367d6452f..7e1b9c628 100644--- a/packages/web/src/app/repos/[id]/refactoring/page.tsx+++ b/packages/web/src/app/repos/[id]/refactoring/page.tsx@@ -42,6 +42,7 @@ import type {RefactoringOpportunityPage,RefactoringOrder,RefactoringPlan,+ RefactoringScope,} from "@repowise-dev/types/refactoring";import {AiPromptModal,@@ -88,6 +89,8 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: striconst [effort, setEffort] = useState<EffortBucket | null>(null);const [confidence, setConfidence] = useState<Confidence | null>(null);const [mechanicalOnly, setMechanicalOnly] = useState(false);+ // What Fix first would take, by default; the full inventory on request.+ const [scope, setScope] = useState<RefactoringScope>("fix_first");const [offset, setOffset] = useState(0);const { data, error, isLoading, mutate } = useSWR<RefactoringOpportunityPage>(@@ -101,12 +104,14 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: strieffort,confidence,mechanicalOnly,+ scope,offset,],() =>getRefactoringOpportunities(repoId, {refactoringType: leadTypeFor(type),status,+ scope,search: deferredQuery || undefined,effort: effort ?? undefined,confidence: confidence ?? undefined,@@ -123,12 +128,13 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stri// The structural head for "Start here". A separate bounded call rather than a// slice of the list above: the list is under whatever filter the reader chose,- // and Start here describes the whole repository.+ // and Start here describes the whole repository, in the scope the list is in.const { data: structural } = useSWR<RefactoringOpportunityPage>(- type === "all" ? ["refactoring-structural", repoId] : null,+ type === "all" ? ["refactoring-structural", repoId, scope] : null,() =>getRefactoringOpportunities(repoId, {refactoringType: STRUCTURAL_CSV,+ scope,order: "rank",stepPreview: 0,limit: 100,@@ -230,6 +236,9 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: strieffort,confidence,mechanicalOnly,+ scope,+ appliedScope: data?.scope ?? "all",+ hidden: data?.hidden ?? null,total: data?.total ?? 0,offset,nextOffset: data?.next_offset ?? null,@@ -297,6 +306,7 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: striif (change.effort !== undefined) setEffort(change.effort);if (change.confidence !== undefined) setConfidence(change.confidence);if (change.mechanicalOnly !== undefined) setMechanicalOnly(change.mechanicalOnly);+ if (change.scope !== undefined) setScope(change.scope);if (change.offset !== undefined) setOffset(change.offset);}}onOpen={(o) => void setOpenId(o.opportunity_id)}@@ -313,7 +323,9 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: strishowLede={type === "all"}sectionTitle={type === "all"- ? "All opportunities"+ ? serverState.appliedScope === "fix_first"+ ? "Opportunities worth doing"+ : "All opportunities": type === "structural"? "Structural opportunities": `${typeMeta(type).label} opportunities`diff --git a/tests/unit/cli/test_refactoring_targets_stored.py b/tests/unit/cli/test_refactoring_targets_stored.pyindex 9d8b8400f..0c8a2aad7 100644--- a/tests/unit/cli/test_refactoring_targets_stored.py+++ b/tests/unit/cli/test_refactoring_targets_stored.py@@ -49,7 +49,8 @@ def _finding(path: str, symbol: str) -> dict[str, Any]:"function_name": symbol,"line_start": 10,"line_end": 30,- "details": {},+ # Past Fix first's size floor, so each opportunity is in the default scope.+ "details": {"ccn": 16},"health_impact": 3.0,"reason": "seeded","dimension": "defect",diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.pyindex 51002113f..7fed0a7e1 100644--- a/tests/unit/health/test_fix_first_build.py+++ b/tests/unit/health/test_fix_first_build.py@@ -205,3 +205,15 @@ def test_value_leads_tier_and_a_huge_function_says_so() -> None:assert planned.title == ("Start breaking up run (CCN 120, 900 lines): first lift lines 20-35 into sum_rows")+++def test_every_open_refactoring_opportunity_carries_its_reason() -> None:+ queue = _build(limit=0)+ assert queue.items == ()+ assert queue.refactoring_reasons == {+ "refop2_core": None,+ "refop2_small": "below_min_worth",+ "refop2_test": "test",+ }+ # Off the wire: the reasons are a read-model input, not part of the queue.+ assert "refactoring_reasons" not in queue.as_dict()diff --git a/tests/unit/health/test_fix_first_closeout.py b/tests/unit/health/test_fix_first_closeout.pynew file mode 100644index 000000000..c37ad11df--- /dev/null+++ b/tests/unit/health/test_fix_first_closeout.py@@ -0,0 +1,136 @@+"""Fix first close-out: every item points at a line, and its words read plainly."""++from __future__ import annotations++import re++import pytest++from repowise.core.analysis.health.fix_first import FixFirstQueue, build_fix_first+from repowise.core.analysis.health.fix_first.build import LOW_VALUE_KINDS+from repowise.core.analysis.health.refactoring.performance_fix import fix_steps+from tests.unit.health.fix_first_rows import FINDINGS, METRICS, _perf++# --- a performance item names the loop it changes -----------------------------------+++def _batched(site: dict) -> dict:+ row = _perf("perf3_batch", "src/db.py::fetch")+ row["details"] = {+ **row["details"],+ "plan": {+ "effort_bucket": "M",+ "steps": [+ {"order": 1, "action": "Add a form of load_all that takes every key at once",+ "symbol": "src/repo.py::load_all", "file_path": "src/repo.py", "line": None,+ "applicability": "judgment"},+ {"order": 2, "action": "Collect the keys before the loop and call the batched "+ "form once", "symbol": "sync", "file_path": "src/jobs.py", "line": 40,+ "applicability": "judgment", **site},+ ],+ },+ }+ return row+++def _lead(row: dict, **over):+ return build_fix_first(metrics=[{**METRICS[0], "file_path": "src/repo.py"}],+ performance=[row], **over).lead+++def test_a_perf_item_points_at_the_loop_around_its_lead_call() -> None:+ target = _lead(_batched({"loop_line": 31})).target+ assert (target.file_path, target.line_start, target.symbol) == ("src/jobs.py", 31, "sync")+++def test_without_a_stored_loop_it_points_at_the_call() -> None:+ assert _lead(_batched({})).target.line_start == 40+++def test_a_call_site_outside_any_function_names_no_symbol() -> None:+ target = _lead(_batched({"symbol": None})).target+ assert (target.file_path, target.line_start, target.symbol) == ("src/jobs.py", 40, None)+++def test_a_step_names_its_function_once_and_takes_the_symbol_line() -> None:+ lead = _lead(_batched({}), symbol_lines={"src/repo.py::load_all": 12})+ first, second = lead.action.steps+ assert first.text == "Add a form of load_all that takes every key at once"+ assert first.line == 12+ assert second.text.endswith("(sync)")+++def test_a_step_with_no_known_line_keeps_none() -> None:+ assert _lead(_batched({})).action.steps[0].line is None+++def test_plan_steps_carry_the_loop_line_of_their_site() -> None:+ steps = fix_steps(+ "batch_or_prefetch_io", "advisory", None, "src/db.py::fetch",+ [{"file_path": "src/jobs.py", "function_name": "sync", "line_start": 40,+ "loop_line": 31}, {"file_path": "src/b.py", "function_name": "g", "line_start": 9}],+ )+ sites = [s for s in steps if s.get("line")]+ assert sites[0]["loop_line"] == 31+ assert "loop_line" not in sites[1]+++# --- a long parameter list is a low-value nudge ---------------------------------------+++def test_a_long_parameter_list_is_no_candidate() -> None:+ finding = {**FINDINGS[1], "biomarker_type": "primitive_obsession", "public_id": "f_po"}+ queue = build_fix_first(metrics=[METRICS[0]], findings=[finding])+ assert queue.items == ()+ assert queue.totals.excluded["low_value_kind"] == 1+ assert LOW_VALUE_KINDS["primitive_obsession"] == "dev 0/0, all 0/2"+++# --- no internal token reaches a text field -------------------------------------------++_RAW = re.compile(+ r"__module__|\bp\d\d\b|percentile|\bNone\b|\(\)| |:$|:\)|\bn/a\b|[a-z]+-graph|name-match"+ r"|\b(?:entry_reachable|not_entry_reachable|grows_with_data|db)\b"+)+++def _texts(item) -> list[str]:+ return [+ item.title, item.why, item.action.summary, item.gain.text, item.effort.basis,+ item.risk.text, item.confidence.reason,+ *(f"{f.label}: {f.value}" for f in item.facts),+ *(s.text for s in item.action.steps),+ *(f"{c.label}: {c.value}" for c in item.context),+ *(f"{r.factor}: {r.value}" for r in item.why_ranked),+ *(t.reason for t in item.verify.tests),+ ]+++def _validated(magnitude: str, via: str, dependents: int) -> FixFirstQueue:+ row = _perf("perf3_raw", "src/db.py::fetch")+ details = row["details"]+ row["details"] = {+ **details,+ "facets": {**details["facets"], "loop_magnitude": magnitude},+ "plan": {**details["plan"], "validation": {"tests": ["tests/test_repo.py"], "via": via}},+ }+ finding = {**FINDINGS[1], "public_id": "f_raw"}+ return build_fix_first(+ metrics=[{**METRICS[0], "dependents": dependents}, METRICS[3]],+ findings=[finding], performance=[row],+ )++[email protected]("via", ["coverage", "call-graph", "import-graph", "name-match", "mixed"])[email protected]("magnitude", ["n/a", "grows_with_data", "unknown"])+def test_no_text_field_carries_an_internal_token(via: str, magnitude: str) -> None:+ queue = _validated(magnitude, via, dependents=1)+ assert len(queue.items) == 2+ for item in queue.items:+ for line in _texts(item):+ assert not _RAW.search(line), line+++def test_one_importer_reads_in_the_singular() -> None:+ item = next(i for i in _validated("unknown", "mixed", 1).items if i.kind == "finding")+ assert item.risk.text == "Touches 1 file; 1 file imports it."diff --git a/tests/unit/health/test_fix_first_precision.py b/tests/unit/health/test_fix_first_precision.pyindex afcd33e4e..0a7adecf1 100644--- a/tests/unit/health/test_fix_first_precision.py+++ b/tests/unit/health/test_fix_first_precision.py@@ -473,9 +473,9 @@ def test_an_extract_class_step_names_the_members_it_moves() -> None:def test_only_a_size_finding_is_titled_break_up() -> None:- wide = {**_finding(ccn=12, nloc=40, max_nesting=8), "biomarker_type": "primitive_obsession"}+ wide = {**_finding(ccn=12, nloc=40, max_nesting=8), "biomarker_type": "complex_conditional"}item = _queue([wide]).lead- assert item.title == "Group the parameters of run"+ assert item.title == "Simplify the condition in run"def test_a_one_line_block_reads_as_one_line() -> None:diff --git a/tests/unit/server/mcp/test_performance_levels.py b/tests/unit/server/mcp/test_performance_levels.pyindex 17403e76d..766d22983 100644--- a/tests/unit/server/mcp/test_performance_levels.py+++ b/tests/unit/server/mcp/test_performance_levels.py@@ -98,8 +98,9 @@ async def test_a_bare_dashboard_leads_with_something_to_do(setup_mcp, materializassert "performance_directive" not in resultperf = [i for i in result["fix_first"]["items"] if i["kind"] == "perf_fix"]assert perf, result["fix_first"]- # The five callers behind one shared helper are one intervention, one item.- shared = [i for i in perf if i["target"]["symbol"] == "load"]+ # The five callers behind one shared helper are one intervention, one item;+ # it points at the loop of its first caller, so its title names the helper.+ shared = [i for i in perf if i["title"].endswith(" load")]assert len(shared) == 1, perfassert shared[0]["next_call"]["arguments"]["opportunity_id"].startswith("perf")assert 0 < len(json.dumps(shared[0])) <= 1500diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.pyindex 2449c3ade..293bf01e0 100644--- a/tests/unit/server/test_refactoring_opportunities.py+++ b/tests/unit/server/test_refactoring_opportunities.py@@ -18,6 +18,7 @@ from httpx import AsyncClientfrom sqlalchemy import eventfrom repowise.core.persistence import crud+from repowise.core.persistence.crud.analysis.fix_first import clear_fix_first_cacheasync def _repo(client: AsyncClient) -> str:@@ -186,6 +187,86 @@ async def test_lifecycle_rolls_up_from_the_member_plans(client, app):assert refreshed["status"] == "acknowledged"+# ---------------------------------------------------------------------------+# 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 crud.finalize_refactoring_opportunities(session, repo_id, analyzed_commit="c" * 40)+ await session.commit()+ return repo_id+++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+++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"+++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}}+++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# ---------------------------------------------------------------------------@@ -285,7 +366,11 @@ def _counter(engine) -> list[str]: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."""+ """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 = {}@@ -297,6 +382,7 @@ async def test_queue_query_count_is_constant_in_page_size_and_row_count(("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}@@ -310,11 +396,13 @@ async def test_queue_query_count_is_constant_in_page_size_and_row_count(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}