Skip to content

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

fix(health): 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.md
index 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`), its
ordered `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 step
carrying `relocated_by` names an earlier step that moves its symbol to another
file: locate the symbol again before applying it, because the step's own
`file_path` and span describe where the symbol was.
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index 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 matching
nearby plan. When no safe plan exists, Code Health says so and keeps the raw
evidence 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
```bash
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.md
index 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's
historical `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 inventory
GET /api/repos/{repo_id}/refactoring/opportunities?file_path=src/api/server.py
GET /api/repos/{repo_id}/refactoring/opportunities/{opportunity_id}
GET /api/repos/{repo_id}/refactoring/summary
diff --git a/packages/api-client/src/refactoring.ts b/packages/api-client/src/refactoring.ts
index 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.py
index 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.py
index 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 the
caller 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 None
excluded[reason] += 1
- return True
+ return reason
+
+ def out_of_scope(path: str, context: str | None = None) -> bool:
+ return scope_reason(path, context) is not None
plan_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")] = reason
if reason is not None:
- excluded[reason] += 1
continue
units.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"] += 1
continue
- 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.py
index 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)
@property
def 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.py
index 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 = None
its 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.py
index 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.py
index 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.py
index 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_biomarkers
from ...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.py
index 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 one
statement 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.py
index 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.py
index 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.items
result["refactoring_opportunities_total"] = page.total
result["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.hidden
if 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.py
index 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.py
index 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 | None
refactoring_confidence: str | None
refactoring_effort: str | None
+ refactoring_scope: str | None
performance_view: str | None
performance_context: str | None
performance_boundary: str | None
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
index 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 or
plan, 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.py
index 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.hidden
if ignored:
body["ignored_arguments"] = ignored
return body
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
index 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.py
index 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, Literal
from 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 = None
class RefactoringRollupResponse(BaseModel):
diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.py
index 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 annotations
import json
+from collections import Counter
from collections.abc import Sequence
from dataclasses import dataclass, field
from typing import Any, Literal
@@ -23,11 +24,13 @@ from typing import Any, Literal
from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.persistence.crud.analysis.fix_first import load_fix_first
from 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 = None
limit: int = 20
offset: int = 0
+ scope: str = DEFAULT_SCOPE
@property
def 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 = None
ignored_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 = None
def 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_view
resolved_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 row
count rather than by the page. Neither has a consumer yet - index them
when 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_facets
else {}
),
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.ts
index 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.ts
index 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.ts
index 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": false
diff --git a/packages/ui/__tests__/refactoring/phase4-plan-contract.test.tsx b/packages/ui/__tests__/refactoring/phase4-plan-contract.test.tsx
index 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.tsx
new file mode 100644
index 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.ts
index 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.tsx
index 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&apos;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&apos;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 ? (
<button
type="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.tsx
index 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: stri
const [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: stri
effort,
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: stri
effort,
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: stri
if (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: stri
showLede={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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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, materializ
assert "performance_directive" not in result
perf = [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, perf
assert shared[0]["next_call"]["arguments"]["opportunity_id"].startswith("perf")
assert 0 < len(json.dumps(shared[0])) <= 1500
diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.py
index 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 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:
@@ -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}