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
refactor(refactoring): move the pure serving half into core and keep the queue rules as data (#2850)
Raghav Chamadiya6f8474d40181
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 dfb4af80a..7ffe26505 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@@ -121,12 +121,10 @@ def _render_stored_refactoring_targets(wrote."""from repowise.cli.helpers import repo_index_session, run_async+ from repowise.core.analysis.health.refactoring.serving import parse_queryfrom repowise.core.analysis.health.scoring import ZERO_IMPACT_DIMENSIONSfrom repowise.core.persistence import crud- from repowise.server.services.refactoring_health import (- RefactoringHealthService,- parse_query,- )+ from repowise.server.services.refactoring_health import RefactoringHealthServicedef keep(path: str) -> bool:if file_filter and path != file_filter:diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/serving.py b/packages/core/src/repowise/core/analysis/health/refactoring/serving.pynew file mode 100644index 000000000..a0fc3ec16--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/refactoring/serving.py@@ -0,0 +1,594 @@+"""Serving refactoring opportunities: the pure half, with no session.++Query parsing, the response shapes and the queue's sort, filter and facet+rules live here. The rules are data: the store builds its ``ORDER BY`` and+``WHERE`` from the same tables :func:`row_sort_key`, :func:`keep` and+:func:`facet_counts` read over rows already in memory, so the two cannot+disagree about what a queue holds or in which order.++Rows may be ORM rows or mappings; every read goes through ``rows.field``.+"""++from __future__ import annotations++from collections.abc import Iterable, Mapping, Sequence+from dataclasses import dataclass+from typing import Any, Literal++from repowise.core.analysis.health.rows import detail_map, field++from .recommendations import _loads_dict++# ``refactoring_view`` predates the opportunity. Both old values keep working+# and both are documented in docs/layers/REFACTORING.md:+#+# - ``canonical`` the published rank order, ties and all. What the old default+# produced, kept for a caller that wants the score order verbatim.+# - ``file_spread`` asked for one row per file. An opportunity *is* one file's+# work, so the spread is now satisfied by construction; the value maps onto+# the diversified order, which is what it was reaching for.+# - ``diversified`` the new default. Rank order round-robined over cause and+# directory, because the ranked head is a genuine run of ties.+_VIEW_ORDERS: dict[str, str] = {+ "canonical": "rank",+ "file_spread": "queue",+ "diversified": "queue",+}+CANONICAL_VIEWS = tuple(_VIEW_ORDERS)+DEFAULT_VIEW = "diversified"++# The legacy plan list has no notion of the diversified order, so the new+# default resolves to the value that list has always defaulted to.+_PLAN_VIEWS = {"canonical": "canonical", "file_spread": "file_spread", "diversified": "canonical"}++# 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")++_CONFIDENCES = ("low", "medium", "high")+_EFFORTS = ("S", "M", "L", "XL")+_TYPES = (+ "break_cycle",+ "extract_class",+ "extract_helper",+ "extract_method",+ "move_method",+ "split_file",+)++UNAVAILABLE: dict[str, Any] = {+ "status": "unavailable",+ "reason": "no_refactoring_analysis",+ "detail": "No refactoring analysis is stored for this repository. Run `repowise update`.",+}++# ---------------------------------------------------------------------------+# The rules, as data+# ---------------------------------------------------------------------------++#: Orders the queue can be read in, as ``(field, descending)`` keys. Every one+#: ends in a unique column so the total order is deterministic and a deep+#: offset cannot repeat or skip a row. A descending field must be numeric.+SORTS: dict[str, tuple[tuple[str, bool], ...]] = {+ "queue": (("queue_position", False),),+ "rank": (("rank_position", False),),+ "health": (("recoverable_health", True), ("rank_position", False)),+ "effort": (("step_count", False), ("rank_position", False)),+ "file": (("file_path", False), ("rank_position", False)),+}+DEFAULT_ORDER = "queue"+CANONICAL_ORDERS = tuple(SORTS)++FilterOp = Literal["eq", "in", "contains", "prefix", "positive", "is"]+++@dataclass(frozen=True, slots=True)+class FilterRule:+ """One queue filter: the parameter it reads, the field it tests, and how.++ ``applies`` is when the parameter narrows at all: ``set`` for anything but+ ``None`` (an empty ``in`` list is a scope that matches nothing), ``truthy``+ when an empty value means "no filter".+ """++ param: str+ field: str+ op: FilterOp+ applies: Literal["always", "set", "truthy"]+++#: In the order the store has always emitted its predicates.+FILTERS: tuple[FilterRule, ...] = (+ FilterRule("status", "status", "eq", "always"),+ # A scope resolved in Python (Fix first's eligible set).+ FilterRule("opportunity_ids", "opportunity_id", "in", "set"),+ # A list is how the board's "Structural" tab asks for four types at once.+ FilterRule("lead_types", "lead_refactoring_type", "in", "truthy"),+ FilterRule("confidence", "confidence", "eq", "set"),+ FilterRule("effort", "effort_bucket", "eq", "set"),+ FilterRule("file_paths", "file_path", "in", "set"),+ # The board's search box: a residual filter, case-insensitive.+ FilterRule("path_contains", "file_path", "contains", "truthy"),+ # A directory scope (the CLI's ``--module``).+ FilterRule("path_prefix", "file_path", "prefix", "truthy"),+ FilterRule("mechanical_only", "mechanical_steps", "positive", "truthy"),+ FilterRule("addresses_primary", "addresses_primary_problem", "is", "set"),+)++#: Facet name -> the field it counts.+FACETS: tuple[tuple[str, str], ...] = (+ ("lead_type", "lead_refactoring_type"),+ ("effort", "effort_bucket"),+ ("confidence", "confidence"),+)+++def active_filters(params: Any) -> list[tuple[FilterRule, Any]]:+ """The rules *params* (a query or a mapping) actually narrows by, with values."""+ active: list[tuple[FilterRule, Any]] = []+ for rule in FILTERS:+ value = field(params, rule.param)+ if rule.applies == "set" and value is None:+ continue+ if rule.applies == "truthy" and not value:+ continue+ active.append((rule, value))+ return active+++def _matches(rule: FilterRule, value: Any, actual: Any) -> bool:+ if rule.op == "eq":+ return actual == value+ if rule.op == "in":+ return actual in value+ if rule.op == "contains":+ # Ceiling: SQLite folds ASCII case only, Python folds Unicode; the two+ # differ only on a non-ASCII path fragment.+ return actual is not None and value.lower() in actual.lower()+ if rule.op == "prefix":+ # Case-sensitive, as PostgreSQL's LIKE is. SQLite's LIKE folds ASCII+ # case; paths differing only in case are not a case the queue meets.+ return actual is not None and actual.startswith(value)+ if rule.op == "positive":+ return (actual or 0) > 0+ # ``is``: SQL ``IS true/false``, so a NULL never matches either.+ return actual is not None and bool(actual) is bool(value)+++def keep(row: Any, params: Any) -> bool:+ """Whether *row* passes every filter *params* sets (a query or a mapping)."""+ return all(+ _matches(rule, value, field(row, rule.field)) for rule, value in active_filters(params)+ )+++def row_sort_key(row: Any, order: str | None = None) -> tuple[Any, ...]:+ """The sort key for *order*; an unknown order reads as the default."""+ key: list[Any] = []+ for name, descending in SORTS.get(order or DEFAULT_ORDER, SORTS[DEFAULT_ORDER]):+ value = field(row, name)+ key.append(-value if descending else value)+ return tuple(key)+++def fold_facets(groups: Iterable[Sequence[Any]]) -> dict[str, dict[str, int]]:+ """Fold ``(*facet values, count)`` groups into per-facet counts; a NULL is skipped."""+ facets: dict[str, dict[str, int]] = {name: {} for name, _ in FACETS}+ for group in groups:+ count = int(group[-1])+ for (name, _), key in zip(FACETS, group[:-1], strict=True):+ if key is not None:+ facets[name][str(key)] = facets[name].get(str(key), 0) + count+ return facets+++def facet_counts(+ rows: Iterable[Any], *, status: str = "open", opportunity_ids: Sequence[str] | None = None+) -> dict[str, dict[str, int]]:+ """Counts for every facet over the rows a status (and scope) selects."""+ params = {"status": status, "opportunity_ids": opportunity_ids}+ return fold_facets(+ (*(field(row, column) for _, column in FACETS), 1)+ for row in rows+ if keep(row, params)+ )+++# ---------------------------------------------------------------------------+# Query+# ---------------------------------------------------------------------------+++@dataclass(frozen=True, slots=True)+class RefactoringQuery:+ """A normalized queue request. The only shape either adapter passes down."""++ lead_types: tuple[str, ...] | None = None+ status: str = "open"+ confidence: str | None = None+ effort: str | None = None+ mechanical_only: bool = False+ addresses_primary: bool | None = None+ file_paths: tuple[str, ...] | None = None+ path_contains: str | None = None+ path_prefix: str | None = None+ view: str = DEFAULT_VIEW+ order: str | None = None+ limit: int = 20+ offset: int = 0+ scope: str = DEFAULT_SCOPE++ @property+ def resolved_order(self) -> str:+ """An explicit ``order`` wins; otherwise the view picks one."""+ if self.order in CANONICAL_ORDERS:+ return self.order+ return _VIEW_ORDERS.get(self.view, _VIEW_ORDERS[DEFAULT_VIEW])+++def parse_query(+ *,+ lead_type: str | Sequence[str] | None = None,+ status: str | None = None,+ confidence: str | None = None,+ effort: str | None = None,+ mechanical: bool | None = None,+ addresses_primary: bool | None = None,+ file_paths: list[str] | tuple[str, ...] | None = None,+ search: str | None = None,+ path_prefix: str | None = None,+ view: str | None = None,+ 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.++ An unrecognized value is reported back rather than silently treated as "no+ filter": a caller who misspells a type should not be told the repository is+ clean.+ """+ ignored: dict[str, str] = {}++ def admit(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:+ if value is None:+ return None+ if value in allowed:+ return value+ ignored[name] = value+ return None++ def admit_many(+ name: str, value: str | Sequence[str] | None, allowed: tuple[str, ...]+ ) -> tuple[str, ...] | None:+ """One value or several. A comma-separated string is how a query+ parameter carries a set; every member is admitted on its own, so a+ misspelling in a list is reported rather than narrowing the result to+ the members that happened to be spelled right."""+ if value is None:+ return None+ raw = value.split(",") if isinstance(value, str) else list(value)+ kept = [item.strip() for item in raw if item.strip()]+ good = tuple(item for item in kept if item in allowed)+ bad = [item for item in kept if item not in allowed]+ if bad:+ ignored[name] = ",".join(bad)+ return good or None++ resolved_view = view or DEFAULT_VIEW+ 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=resolved_status,+ confidence=admit("confidence", confidence, _CONFIDENCES),+ effort=admit("effort", effort, _EFFORTS),+ mechanical_only=bool(mechanical),+ addresses_primary=addresses_primary,+ # ``is not None``, not truthiness: an empty sequence is a scope that+ # resolved to no file, and the store turns that into ``IN ()``.+ # Reading it as "unscoped" answers a question about nothing with+ # the whole repository.+ file_paths=tuple(file_paths) if file_paths is not None else None,+ path_contains=(search or "").strip() or None,+ path_prefix=path_prefix or None,+ view=resolved_view,+ order=admit("order", order, CANONICAL_ORDERS),+ limit=max(int(limit), 0),+ offset=max(int(offset), 0),+ scope=resolved_scope,+ ),+ ignored,+ )+++def plan_view(view: str | None) -> Literal["canonical", "file_spread"]:+ """The legacy plan list's view for a caller's ``refactoring_view``."""+ return _PLAN_VIEWS.get(view or DEFAULT_VIEW, "canonical") # type: ignore[return-value]+++# ---------------------------------------------------------------------------+# Shapes+# ---------------------------------------------------------------------------+++def evidence_block(+ evidence: list[dict[str, Any]], total: int, offset: int+) -> dict[str, Any]:+ """One evidence page plus the exact call that reads the rest."""+ emitted = len(evidence)+ block: dict[str, Any] = {+ "evidence": evidence,+ "evidence_total": total,+ "evidence_emitted": emitted,+ "evidence_truncated": offset + emitted < total,+ }+ if block["evidence_truncated"]:+ block["evidence_reduced_reason"] = "evidence_page"+ block["evidence_next_cursor"] = offset + emitted+ return block+++def summary_payload(row: Any | None) -> dict[str, Any]:+ """The Level-1 rollup from the stored summary row."""+ if row is None:+ return dict(UNAVAILABLE)+ payload = _loads_dict(field(row, "summary_json"))+ payload["status"] = "available"+ payload["refactoring_model_version"] = field(row, "refactoring_model_version")+ payload["analyzed_commit"] = field(row, "analyzed_commit")+ return payload+++def directive_from_summary(row: Any | None) -> dict[str, Any]:+ """The Level-0 lead from the stored summary row: one opportunity, and the+ exact call that opens it."""+ if row is None:+ return dict(UNAVAILABLE)+ payload = _loads_dict(field(row, "summary_json"))+ lead = payload.get("lead")+ if not lead:+ return {+ "status": "clear",+ "reason": "no_open_opportunities",+ "detail": "No refactoring opportunity is open for this repository.",+ "opportunities_total": int(payload.get("opportunities_total") or 0),+ }+ addresses = lead.get("addresses_primary_problem")+ directive: dict[str, Any] = {+ "status": "available",+ "opportunity_id": lead.get("opportunity_id"),+ "fix_first": lead.get("file_path"),+ "reason": lead.get("lead_biomarker"),+ "lead_refactoring_type": lead.get("lead_refactoring_type"),+ "steps": lead.get("step_count"),+ "mechanical_steps": lead.get("mechanical_steps"),+ "judgment_steps": lead.get("judgment_steps"),+ "effort_bucket": lead.get("effort_bucket"),+ "confidence": lead.get("confidence"),+ "recovers_health_points": lead.get("recoverable_health"),+ "addresses_primary_problem": addresses,+ "opportunities_total": int(payload.get("opportunities_total") or 0),+ "next_action": {+ "tool": "get_health",+ "arguments": {"opportunity_id": lead.get("opportunity_id")},+ },+ }+ # The honest half. A file's plans very often answer a different question+ # from the one that made it the worst file, and saying so beats routing+ # an agent to cleanup it will read as the fix.+ if addresses is False:+ directive["note"] = (+ f"These steps do not address {lead.get('lead_biomarker')!r}, this file's "+ "dominant finding. Treat them as related cleanup, not the fix for it."+ )+ elif addresses is None:+ directive["note"] = (+ "No dominant finding was recorded for this file, so whether these steps "+ "address it is unknown rather than no."+ )+ return directive+++def next_actions(row: Any, steps: list[dict[str, Any]]) -> list[dict[str, Any]]:+ """Structured follow-ups, so a drill-down ends somewhere rather than stops."""+ actions: list[dict[str, Any]] = []+ first = steps[0] if steps else None+ if first and first.get("line_start") is not None and first.get("line_end") is not None:+ actions.append(+ {+ "why": "read the span the first step names",+ "tool": "get_symbol",+ "arguments": {+ "symbol_id": f"{first['file_path']}:{first['line_start']}-{first['line_end']}"+ },+ }+ )+ actions.append(+ {+ "why": "what history says about touching this file",+ "tool": "get_risk",+ "arguments": {"targets": [field(row, "file_path")]},+ }+ )+ if field(row, "evidence_total"):+ actions.append(+ {+ "why": "page the supporting observations",+ "tool": "get_health",+ "arguments": {+ "opportunity_id": field(row, "opportunity_id"),+ "only": ["refactoring_evidence"],+ },+ }+ )+ return actions+++_ROW_FIELDS = (+ "opportunity_id",+ "refactoring_model_version",+ "status",+ "file_path",+ "lead_biomarker",+ "lead_refactoring_type",+ "addresses_primary_problem",+ "effort_bucket",+ "confidence",+ "step_count",+ "mechanical_steps",+ "judgment_steps",+ "evidence_total",+ "affected_files_total",+)+++def serialize(+ row: Any, *, steps_limit: int | None = None, evidence_limit: int = 0+) -> dict[str, Any]:+ """One queue row: its columns, rank explanation, and optional step/evidence heads."""+ details = detail_map(row)+ steps = list(details.get("steps") or [])+ evidence = list(details.get("evidence") or [])+ payload: dict[str, Any] = {name: field(row, name) for name in _ROW_FIELDS}+ payload["recoverable_health"] = round(float(field(row, "recoverable_health")), 3)+ payload["rank_score"] = round(float(field(row, "rank_score")), 4)+ payload["rank_position"] = field(row, "rank_position")+ payload["queue_position"] = field(row, "queue_position")+ payload["rank_factors"] = details.get("rank_factors") or {}+ payload["why_ranked"] = details.get("why_ranked") or []+ # The file's own size and reach, recorded by the finalizer. Omitted when+ # the store predates them, so a surface can tell "not measured" from a+ # genuine zero rather than plotting an unmeasured file at the origin.+ for key in ("file_nloc", "dependents"):+ if isinstance(details.get(key), int):+ payload[key] = details[key]+ if steps_limit is not None:+ kept = steps[: max(steps_limit, 0)]+ payload["steps"] = kept+ payload["steps_total"] = len(steps)+ payload["steps_emitted"] = len(kept)+ if len(kept) < len(steps):+ payload["steps_reduced_reason"] = "limit"+ if evidence_limit:+ payload.update(evidence_block(evidence[:evidence_limit], len(evidence), 0))+ return payload+++def stored_validation(owner: Any, public_id: str | None) -> Any:+ """The validation profile the finalizer resolved for this step.++ Test reachability is a graph walk over the whole unanswered set; it belongs+ at index time, and this reads its result rather than repeating it.+ """+ if owner is None or not public_id:+ return None+ details = detail_map(owner)+ wanted = next(+ (+ step.get("validation_profile_id")+ for step in (details.get("steps") or [])+ if step.get("plan_id") == public_id+ ),+ None,+ )+ if not wanted:+ return None+ profile = next(+ (p for p in (details.get("validation_profiles") or []) if p.get("id") == wanted),+ None,+ )+ return validation_from_profile(profile) if profile is not None else None+++def validation_from_profile(profile: Mapping[str, Any]) -> Any:+ """Rebuild a stored validation profile into the plan dataclass."""+ from .recommendations import ValidationPlan, ValidationTarget++ target_fields = set(ValidationTarget.__dataclass_fields__)+ values = {+ key: value+ for key, value in profile.items()+ if key in ValidationPlan.__dataclass_fields__+ }+ values["targets"] = [+ ValidationTarget(**{k: v for k, v in target.items() if k in target_fields})+ for target in (profile.get("targets") or [])+ if isinstance(target, dict)+ ]+ return ValidationPlan(**values)+++def plan_payload(row: Any) -> dict[str, Any]:+ """The stored plan, without re-hydrating rank or validation.++ Detail reads the payload the detector wrote and the finalizer already+ validated; recomputing benefit and coverage here is what made a one-row+ lookup cost the repository.+ """+ return {+ "id": field(row, "public_id") or field(row, "id"),+ "refactoring_type": field(row, "refactoring_type"),+ "file_path": field(row, "file_path"),+ "target_symbol": field(row, "target_symbol"),+ "line_start": field(row, "line_start"),+ "line_end": field(row, "line_end"),+ "plan": _loads_dict(field(row, "plan_json")),+ "evidence": _loads_dict(field(row, "evidence_json")),+ "blast_radius": _loads_dict(field(row, "blast_radius_json")),+ "impact_delta": field(row, "impact_delta"),+ "effort_bucket": field(row, "effort_bucket"),+ "confidence": field(row, "confidence"),+ "source_biomarker": field(row, "source_biomarker"),+ "status": field(row, "status"),+ }+++__all__ = [+ "CANONICAL_ORDERS",+ "CANONICAL_VIEWS",+ "DEFAULT_ORDER",+ "DEFAULT_SCOPE",+ "DEFAULT_VIEW",+ "FACETS",+ "FILTERS",+ "SCOPES",+ "SORTS",+ "UNAVAILABLE",+ "FilterRule",+ "RefactoringQuery",+ "active_filters",+ "directive_from_summary",+ "evidence_block",+ "facet_counts",+ "fold_facets",+ "keep",+ "next_actions",+ "parse_query",+ "plan_payload",+ "plan_view",+ "row_sort_key",+ "serialize",+ "stored_validation",+ "summary_payload",+ "validation_from_profile",+]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 d8d71ca00..cd955d57e 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@@ -47,26 +47,16 @@ _LIVE_PLAN_STATUSES = frozenset({"open", "acknowledged"})# and restate the decision as its own._DECIDED_STATUSES = frozenset({"resolved", "false_positive"})-# Orders the queue can be read in. Every one ends in a unique column so the-# total order is deterministic and a deep offset cannot repeat or skip a row.-_ORDERS: dict[str, tuple[Any, ...]] = {- "queue": (RefactoringOpportunity.queue_position.asc(),),- "rank": (RefactoringOpportunity.rank_position.asc(),),- "health": (- RefactoringOpportunity.recoverable_health.desc(),- RefactoringOpportunity.rank_position.asc(),- ),- "effort": (- RefactoringOpportunity.step_count.asc(),- RefactoringOpportunity.rank_position.asc(),- ),- "file": (- RefactoringOpportunity.file_path.asc(),- RefactoringOpportunity.rank_position.asc(),- ),-}--DEFAULT_ORDER = "queue"+def _order_by(order: str | None) -> tuple[Any, ...]:+ """The ``ORDER BY`` for *order*, built from the serving layer's sort table."""+ from ....analysis.health.refactoring.serving import DEFAULT_ORDER, SORTS++ return tuple(+ getattr(RefactoringOpportunity, name).desc()+ if descending+ else getattr(RefactoringOpportunity, name).asc()+ for name, descending in SORTS.get(order or DEFAULT_ORDER, SORTS[DEFAULT_ORDER])+ )# ---------------------------------------------------------------------------@@ -499,68 +489,33 @@ async def _write_summary(# ----------------------------------------------------------------------------def _opportunity_filters(- repository_id: str,- *,- status: str,- lead_types: list[str] | None,- confidence: str | None,- effort: str | None,- file_paths: list[str] | None,- path_contains: str | None,- path_prefix: str | None,- mechanical_only: bool,- addresses_primary: bool | None,- opportunity_ids: list[str] | None = None,-) -> list[Any]:- predicates: list[Any] = [+def _predicate(rule: Any, value: Any) -> Any:+ """One serving-layer filter rule as a SQL predicate."""+ column = getattr(RefactoringOpportunity, rule.field)+ if rule.op == "eq":+ return column == value+ if rule.op == "in":+ # One value is still one equality; an empty list matches nothing.+ return column == value[0] if len(value) == 1 else column.in_(value)+ if rule.op == "contains":+ # Escaping goes through the shared helper so a path fragment is read+ # as a path fragment here the same way it is everywhere else.+ return column.ilike(f"%{escape_like(value)}%", escape=LIKE_ESCAPE)+ if rule.op == "prefix":+ return column.like(f"{escape_like(value)}%", escape=LIKE_ESCAPE)+ if rule.op == "positive":+ return column > 0+ return column.is_(value)+++def _opportunity_filters(repository_id: str, **params: Any) -> list[Any]:+ """The ``WHERE`` for *params*, built from the serving layer's filter table."""+ from ....analysis.health.refactoring.serving import active_filters++ return [RefactoringOpportunity.repository_id == repository_id,- RefactoringOpportunity.status == status,+ *(_predicate(rule, value) for rule, value in active_filters(params)),]- 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.- predicates.append(- RefactoringOpportunity.lead_refactoring_type == lead_types[0]- if len(lead_types) == 1- else RefactoringOpportunity.lead_refactoring_type.in_(lead_types)- )- if confidence is not None:- predicates.append(RefactoringOpportunity.confidence == confidence)- if effort is not None:- predicates.append(RefactoringOpportunity.effort_bucket == effort)- if file_paths is not None:- predicates.append(RefactoringOpportunity.file_path.in_(file_paths))- if path_contains:- # A residual filter over the open set, not an index seek: the board's- # search box is the one caller, and it is bounded by open row count- # rather than by page. Escaping goes through the shared helper so a- # path fragment is read as a path fragment here the same way it is- # everywhere else that builds a LIKE.- predicates.append(- RefactoringOpportunity.file_path.ilike(- f"%{escape_like(path_contains)}%", escape=LIKE_ESCAPE- )- )- if path_prefix:- # A directory scope (the CLI's ``--module``), counted in the store so- # the total is exact rather than a capped over-fetch narrowed later.- predicates.append(- RefactoringOpportunity.file_path.like(- f"{escape_like(path_prefix)}%", escape=LIKE_ESCAPE- )- )- if mechanical_only:- predicates.append(RefactoringOpportunity.mechanical_steps > 0)- if addresses_primary is not None:- predicates.append(- RefactoringOpportunity.addresses_primary_problem.is_(addresses_primary)- )- return predicatesasync def list_refactoring_opportunities(@@ -577,7 +532,7 @@ async def list_refactoring_opportunities(mechanical_only: bool = False,addresses_primary: bool | None = None,opportunity_ids: list[str] | None = None,- order: str = DEFAULT_ORDER,+ order: str | None = None,limit: int = 20,offset: int = 0,) -> tuple[list[RefactoringOpportunity], int]:@@ -605,7 +560,7 @@ async def list_refactoring_opportunities(query: Select[Any] = (select(RefactoringOpportunity).where(*predicates)- .order_by(*_ORDERS.get(order, _ORDERS[DEFAULT_ORDER]))+ .order_by(*_order_by(order)).offset(max(offset, 0)).limit(max(limit, 0)))@@ -754,38 +709,22 @@ async def refactoring_facet_counts(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,- RefactoringOpportunity.effort_bucket,- RefactoringOpportunity.confidence,- )+ from ....analysis.health.refactoring.serving import FACETS, fold_facets++ columns = tuple(getattr(RefactoringOpportunity, name) for _, name in FACETS)rows = await session.execute(select(*columns, func.count()).where(- RefactoringOpportunity.repository_id == repository_id,- RefactoringOpportunity.status == status,- *(- [RefactoringOpportunity.opportunity_id.in_(opportunity_ids)]- if opportunity_ids is not None- else []- ),+ *_opportunity_filters(+ repository_id, status=status, opportunity_ids=opportunity_ids+ )).group_by(*columns))- facets: dict[str, dict[str, int]] = {"lead_type": {}, "effort": {}, "confidence": {}}- for lead_type, effort, confidence, count in rows.all():- for name, key in (- ("lead_type", lead_type),- ("effort", effort),- ("confidence", confidence),- ):- if key is not None:- facets[name][str(key)] = facets[name].get(str(key), 0) + int(count)- return facets+ return fold_facets(rows.all())__all__ = [- "DEFAULT_ORDER","finalize_refactoring_opportunities","get_refactoring_opportunity","get_refactoring_summary",diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/details.py b/packages/server/src/repowise/server/mcp_server/tool_health/details.pyindex cc6b67bc5..0bead93e4 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/details.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/details.py@@ -7,6 +7,7 @@ from typing import Anyfrom sqlalchemy import selectfrom repowise.core.analysis.health.counts import DEFAULT_COUNTS+from repowise.core.analysis.health.refactoring.serving import evidence_blockfrom repowise.core.analysis.health.scope import DEFAULT_SCOPEfrom repowise.core.persistence.crud import get_health_finding_by_public_idfrom repowise.core.persistence.crud.analysis.fix_first import load_fix_first@@ -25,10 +26,7 @@ from repowise.server.mcp_server.tool_health.serialize import (_legacy_health_finding_id,_serialize_finding,)-from repowise.server.services.performance_health import (- PerformanceHealthService,- evidence_block,-)+from repowise.server.services.performance_health import PerformanceHealthServicefrom repowise.server.services.refactoring_health import RefactoringHealthServicediff --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 c7f7a3008..c2b517186 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@@ -24,6 +24,7 @@ from repowise.core.analysis.health.refactoring.recommendations import (detail_recommendations,hydrate_recommendations,)+from repowise.core.analysis.health.refactoring.serving import plan_viewfrom repowise.core.analysis.health.signals import file_signalsfrom repowise.core.analysis.health.trends import project_scopefrom repowise.core.ingestion.models import FILE_DEPENDENCY_EDGE_TYPES@@ -60,7 +61,7 @@ from repowise.server.mcp_server.tool_health.population import Population, load_pfrom repowise.server.mcp_server.tool_health.request import HealthRequestfrom repowise.server.mcp_server.tool_health.summary import _leads_by_filefrom repowise.server.services.performance_health import PerformanceHealthService-from repowise.server.services.refactoring_health import RefactoringHealthService, plan_view+from repowise.server.services.refactoring_health import RefactoringHealthServiceFIX_FIRST_CAP = 5"""Items in the dashboard's ``fix_first`` block, however large ``limit`` is.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 ed1c4f708..ea387a7de 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@@ -5,6 +5,7 @@ from __future__ import annotationsfrom dataclasses import dataclass, fieldfrom typing import Any+from repowise.core.analysis.health.refactoring.serving import parse_query as parse_refactoring_queryfrom repowise.core.analysis.next_call import ActionCommandfrom repowise.server.mcp_server.tool_health.paging import Pagerfrom repowise.server.mcp_server.tool_health.request import HealthRequest@@ -14,7 +15,6 @@ from repowise.server.services.performance_health import (parse_query,)from repowise.server.services.refactoring_health import RefactoringHealthService-from repowise.server.services.refactoring_health import parse_query as parse_refactoring_query# The opportunity id space is shared with the performance pillar's, and told# apart by prefix alone, so ``opportunity_id`` stays one selector.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 f609d1352..e279a0064 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@@ -5,9 +5,13 @@ from __future__ import annotationsfrom dataclasses import dataclass, fieldfrom repowise.core.analysis.finding_registry import excluded_types+from repowise.core.analysis.health.refactoring.serving import (+ CANONICAL_VIEWS as _REFACTORING_VIEWS,+)+from repowise.core.analysis.health.refactoring.serving import (+ DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT,+)from repowise.core.analysis.health.scoring import ALL_DIMENSIONS-from repowise.server.services.refactoring_health import CANONICAL_VIEWS as _REFACTORING_VIEWS-from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT# ``include`` names that land under a different response key, so ``only`` can# use the same name. ``signals`` has no top-level key (it merges intodiff --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 199921f29..308e26ccf 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@@ -12,6 +12,9 @@ from time import perf_counterfrom typing import Anyfrom repowise.core.analysis.health.counts import DEFAULT_COUNTS+from repowise.core.analysis.health.refactoring.serving import (+ DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT,+)from repowise.core.analysis.health.scope import DEFAULT_SCOPEfrom repowise.core.analysis.health.semantics import health_semantics_contractfrom repowise.core.persistence.database import get_session@@ -48,7 +51,6 @@ from repowise.server.mcp_server.tool_health.projection import ()from repowise.server.mcp_server.tool_health.request import _ONLY_ALIASES, HealthRequestfrom repowise.server.mcp_server.tool_health.targeted import ModeTotals, build_targeted-from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT__all__ = ["_ONLY_ALIASES", "get_health"]diff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.pyindex e8456c583..1119f8b20 100644--- a/packages/server/src/repowise/server/routers/refactoring.py+++ b/packages/server/src/repowise/server/routers/refactoring.py@@ -25,6 +25,12 @@ from repowise.core.analysis.health.refactoring.recommendations import (detail_recommendations,hydrate_recommendations,)+from repowise.core.analysis.health.refactoring.serving import (+ CANONICAL_ORDERS,+ CANONICAL_VIEWS,+ DEFAULT_VIEW,+ parse_query,+)from repowise.core.analysis.health.refactoring_summary import STRUCTURAL_TYPES, summarize_plansfrom repowise.core.persistence import crudfrom repowise.core.persistence.crud.analysis.refactoring import ALLOWED_STATUSES@@ -36,13 +42,7 @@ from repowise.server.schemas import (RefactoringPlanStatusResponse,RefactoringRollupResponse,)-from repowise.server.services.refactoring_health import (- CANONICAL_ORDERS,- CANONICAL_VIEWS,- DEFAULT_VIEW,- RefactoringHealthService,- parse_query,-)+from repowise.server.services.refactoring_health import RefactoringHealthService_STEPS_PER_ROW = 3"""Steps carried on a queue row; the detail call pages the rest."""diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.pyindex 2bfc8f7a4..fc21fb6e4 100644--- a/packages/server/src/repowise/server/services/performance_health.py+++ b/packages/server/src/repowise/server/services/performance_health.py@@ -30,6 +30,7 @@ from repowise.core.analysis.health.perf.opportunity_rank import (DEFAULT_QUEUE_STATES,NON_LEADING_MARKERS,)+from repowise.core.analysis.health.refactoring.serving import evidence_blockfrom repowise.core.analysis.health.rows import detail_mapfrom repowise.core.persistence.crud import (get_performance_opportunity,@@ -590,23 +591,6 @@ def _summary_of(row: Any) -> dict[str, Any]:}-def evidence_block(- evidence: list[dict[str, Any]], total: int, offset: int-) -> dict[str, Any]:- """Evidence plus the exact recovery for what it left out."""- emitted = offset + len(evidence)- block: dict[str, Any] = {- "evidence": evidence,- "evidence_total": total,- "evidence_emitted": len(evidence),- "evidence_truncated": emitted < total,- }- if emitted < total:- block["evidence_reduced_reason"] = "evidence_page"- block["evidence_next_cursor"] = emitted- return block--def _plan_brief(plan: dict[str, Any] | None) -> dict[str, Any]:"""The stored plan's validation, steps and economics, or nothing on an older store."""if not plan:@@ -673,7 +657,6 @@ __all__ = ["PerformancePage","PerformanceQuery","PlanLink",- "evidence_block","evidence_payload","parse_query",]diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.pyindex f078d3fd1..45f731746 100644--- a/packages/server/src/repowise/server/services/refactoring_health.py+++ b/packages/server/src/repowise/server/services/refactoring_health.py@@ -8,22 +8,34 @@ followed by a linear scan. Query, filter, order, page, facets, detail and thedirective live here now, so the agent surface and the product surface cannotdrift apart.-Nothing in this module composes or ranks. Composition is+The session-free half (query parsing, the sort/filter/facet rules and every+response shape) is ``analysis/health/refactoring/serving.py``; this module+runs the reads and hands rows to it. Nothing here composes or ranks. Composition is``analysis/health/refactoring/opportunity.py`` and it runs at index time; thismodule reads what the finalizer wrote."""from __future__ import annotations-import jsonfrom collections import Counter-from collections.abc import Sequencefrom dataclasses import dataclass, field-from typing import Any, Literal+from typing import Anyfrom sqlalchemy import or_, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.refactoring.serving import (+ RefactoringQuery,+ directive_from_summary,+ evidence_block,+ next_actions,+ plan_payload,+ serialize,+ stored_validation,+ summary_payload,+ validation_from_profile,+)+from repowise.core.analysis.health.rows import detail_map, json_fieldfrom repowise.core.persistence.crud.analysis.fix_first import load_fix_firstfrom repowise.core.persistence.crud.analysis.refactoring_opportunities import (get_refactoring_opportunity,@@ -34,87 +46,6 @@ from repowise.core.persistence.crud.analysis.refactoring_opportunities import ()from repowise.core.persistence.models import RefactoringOpportunity, RefactoringSuggestion-# ``refactoring_view`` predates the opportunity. Both old values keep working-# and both are documented in docs/layers/REFACTORING.md:-#-# - ``canonical`` the published rank order, ties and all. What the old default-# produced, kept for a caller that wants the score order verbatim.-# - ``file_spread`` asked for one row per file. An opportunity *is* one file's-# work, so the spread is now satisfied by construction; the value maps onto-# the diversified order, which is what it was reaching for.-# - ``diversified`` the new default. Rank order round-robined over cause and-# directory, because the ranked head is a genuine run of ties.-_VIEW_ORDERS: dict[str, str] = {- "canonical": "rank",- "file_spread": "queue",- "diversified": "queue",-}-CANONICAL_VIEWS = tuple(_VIEW_ORDERS)-DEFAULT_VIEW = "diversified"--# The legacy plan list has no notion of the diversified order, so the new-# default resolves to the value that list has always defaulted to.-_PLAN_VIEWS = {"canonical": "canonical", "file_spread": "file_spread", "diversified": "canonical"}--# 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")--CANONICAL_ORDERS = ("queue", "rank", "health", "effort", "file")-_CONFIDENCES = ("low", "medium", "high")-_EFFORTS = ("S", "M", "L", "XL")-_TYPES = (- "break_cycle",- "extract_class",- "extract_helper",- "extract_method",- "move_method",- "split_file",-)--_UNAVAILABLE = {- "status": "unavailable",- "reason": "no_refactoring_analysis",- "detail": "No refactoring analysis is stored for this repository. Run `repowise update`.",-}---@dataclass(frozen=True, slots=True)-class RefactoringQuery:- """A normalized queue request. The only shape either adapter passes down."""-- lead_types: tuple[str, ...] | None = None- status: str = "open"- confidence: str | None = None- effort: str | None = None- mechanical_only: bool = False- addresses_primary: bool | None = None- file_paths: tuple[str, ...] | None = None- path_contains: str | None = None- path_prefix: str | None = None- view: str = DEFAULT_VIEW- order: str | None = None- limit: int = 20- offset: int = 0- scope: str = DEFAULT_SCOPE-- @property- def resolved_order(self) -> str:- """An explicit ``order`` wins; otherwise the view picks one."""- if self.order in CANONICAL_ORDERS:- return self.order- return _VIEW_ORDERS.get(self.view, _VIEW_ORDERS[DEFAULT_VIEW])-@dataclass(frozen=True, slots=True)class RefactoringPage:@@ -131,113 +62,6 @@ class RefactoringPage:hidden: dict[str, Any] | None = None-def parse_query(- *,- lead_type: str | Sequence[str] | None = None,- status: str | None = None,- confidence: str | None = None,- effort: str | None = None,- mechanical: bool | None = None,- addresses_primary: bool | None = None,- file_paths: list[str] | tuple[str, ...] | None = None,- search: str | None = None,- path_prefix: str | None = None,- view: str | None = None,- 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.-- An unrecognized value is reported back rather than silently treated as "no- filter": a caller who misspells a type should not be told the repository is- clean.- """- ignored: dict[str, str] = {}-- def admit(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:- if value is None:- return None- if value in allowed:- return value- ignored[name] = value- return None-- def admit_many(- name: str, value: str | Sequence[str] | None, allowed: tuple[str, ...]- ) -> tuple[str, ...] | None:- """One value or several. A comma-separated string is how a query- parameter carries a set; every member is admitted on its own, so a- misspelling in a list is reported rather than narrowing the result to- the members that happened to be spelled right."""- if value is None:- return None- raw = value.split(",") if isinstance(value, str) else list(value)- kept = [item.strip() for item in raw if item.strip()]- good = tuple(item for item in kept if item in allowed)- bad = [item for item in kept if item not in allowed]- if bad:- ignored[name] = ",".join(bad)- return good or None-- resolved_view = view or DEFAULT_VIEW- 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=resolved_status,- confidence=admit("confidence", confidence, _CONFIDENCES),- effort=admit("effort", effort, _EFFORTS),- mechanical_only=bool(mechanical),- addresses_primary=addresses_primary,- # ``is not None``, not truthiness: an empty sequence is a scope that- # resolved to no file, and the store turns that into ``IN ()``.- # Reading it as "unscoped" answers a question about nothing with- # the whole repository.- file_paths=tuple(file_paths) if file_paths is not None else None,- path_contains=(search or "").strip() or None,- path_prefix=path_prefix or None,- view=resolved_view,- order=admit("order", order, CANONICAL_ORDERS),- limit=max(int(limit), 0),- offset=max(int(offset), 0),- scope=resolved_scope,- ),- ignored,- )---def plan_view(view: str | None) -> Literal["canonical", "file_spread"]:- """The legacy plan list's view for a caller's ``refactoring_view``."""- return _PLAN_VIEWS.get(view or DEFAULT_VIEW, "canonical") # type: ignore[return-value]---def evidence_block(- evidence: list[dict[str, Any]], total: int, offset: int-) -> dict[str, Any]:- """One evidence page plus the exact call that reads the rest."""- emitted = len(evidence)- block: dict[str, Any] = {- "evidence": evidence,- "evidence_total": total,- "evidence_emitted": emitted,- "evidence_truncated": offset + emitted < total,- }- if block["evidence_truncated"]:- block["evidence_reduced_reason"] = "evidence_page"- block["evidence_next_cursor"] = offset + emitted- return block--class RefactoringHealthService:"""Query, page, detail and headline over the materialized opportunities."""@@ -295,7 +119,7 @@ class RefactoringHealthService:offset=query.offset,)items = [- self._serialize(row, steps_limit=steps_per_item, evidence_limit=evidence_per_item)+ serialize(row, steps_limit=steps_per_item, evidence_limit=evidence_per_item)for row in rows]next_offset = query.offset + len(items)@@ -347,14 +171,7 @@ class RefactoringHealthService:async def summary(self) -> dict[str, Any]:"""The Level-1 rollup, read by primary key."""- row = await get_refactoring_summary(self._session, self._repository_id)- if row is None:- return dict(_UNAVAILABLE)- payload = _loads(row.summary_json)- payload["status"] = "available"- payload["refactoring_model_version"] = row.refactoring_model_version- payload["analyzed_commit"] = row.analyzed_commit- return payload+ return summary_payload(await get_refactoring_summary(self._session, self._repository_id))async def directive(self) -> dict[str, Any]:"""The Level-0 lead: one opportunity, and the exact call that opens it.@@ -362,52 +179,9 @@ class RefactoringHealthService:The same primary-key read the summary uses, so a bare dashboard pays onestatement for it and never touches the queue."""- row = await get_refactoring_summary(self._session, self._repository_id)- if row is None:- return dict(_UNAVAILABLE)- payload = _loads(row.summary_json)- lead = payload.get("lead")- if not lead:- return {- "status": "clear",- "reason": "no_open_opportunities",- "detail": "No refactoring opportunity is open for this repository.",- "opportunities_total": int(payload.get("opportunities_total") or 0),- }- addresses = lead.get("addresses_primary_problem")- directive: dict[str, Any] = {- "status": "available",- "opportunity_id": lead.get("opportunity_id"),- "fix_first": lead.get("file_path"),- "reason": lead.get("lead_biomarker"),- "lead_refactoring_type": lead.get("lead_refactoring_type"),- "steps": lead.get("step_count"),- "mechanical_steps": lead.get("mechanical_steps"),- "judgment_steps": lead.get("judgment_steps"),- "effort_bucket": lead.get("effort_bucket"),- "confidence": lead.get("confidence"),- "recovers_health_points": lead.get("recoverable_health"),- "addresses_primary_problem": addresses,- "opportunities_total": int(payload.get("opportunities_total") or 0),- "next_action": {- "tool": "get_health",- "arguments": {"opportunity_id": lead.get("opportunity_id")},- },- }- # The honest half. A file's plans very often answer a different question- # from the one that made it the worst file, and saying so beats routing- # an agent to cleanup it will read as the fix.- if addresses is False:- directive["note"] = (- f"These steps do not address {lead.get('lead_biomarker')!r}, this file's "- "dominant finding. Treat them as related cleanup, not the fix for it."- )- elif addresses is None:- directive["note"] = (- "No dominant finding was recorded for this file, so whether these steps "- "address it is unknown rather than no."- )- return directive+ return directive_from_summary(+ await get_refactoring_summary(self._session, self._repository_id)+ )# -- detail -----------------------------------------------------------@@ -438,10 +212,10 @@ class RefactoringHealthService:"opportunity_id": opportunity_id,"reason": "unknown_opportunity_id",}- details = _loads(row.details_json)+ details = detail_map(row)steps = list(details.get("steps") or [])page = steps[step_offset : step_offset + max(step_limit, 0)]- payload = self._serialize(row, steps_limit=None, evidence_limit=0)+ payload = serialize(row, steps_limit=None, evidence_limit=0)payload["found"] = Truepayload["steps"] = pagepayload["steps_total"] = len(steps)@@ -460,7 +234,7 @@ class RefactoringHealthService:payload["validation_profiles"] = list(details.get("validation_profiles") or [])payload["affected_files"] = list(details.get("affected_files") or [])payload["lead_finding_ids"] = list(details.get("lead_finding_ids") or [])- payload["next_actions"] = self._next_actions(row, page)+ payload["next_actions"] = next_actions(row, page)if with_plans and page:payload["plans"] = await self._plans_for([s["plan_id"] for s in page])# Ordered steps carry ``relocated_by``; a surface that renders them must@@ -500,11 +274,11 @@ class RefactoringHealthService:metric_by_path=metric_by_path,centrality=centrality,validations={- 0: _stored_validation(owner, row.public_id)+ 0: stored_validation(owner, row.public_id)or await self._performance_validation(row)},)- payload = built[0].as_dict() if built else _plan_payload(row)+ payload = built[0].as_dict() if built else plan_payload(row)payload["id"] = row.public_id or row.idpayload["status"] = row.statusresult: dict[str, Any] = {"resolved": True, "plan_id": plan_id, "plan": payload}@@ -531,14 +305,15 @@ class RefactoringHealthService:if row.refactoring_type != "performance_fix":return None- opportunity_id = _loads(row.plan_json).get("opportunity_id")+ plan = json_field(row, "plan_json", {})+ opportunity_id = plan.get("opportunity_id") if isinstance(plan, dict) else Noneif not opportunity_id:return Noneowner = await get_performance_opportunity(self._session, self._repository_id, opportunity_id)- profile = (_loads(owner.details_json).get("plan") or {}).get("validation") if owner else None- return _validation_from_profile(profile) if profile else None+ profile = (detail_map(owner).get("plan") or {}).get("validation") if owner else None+ return validation_from_profile(profile) if profile else Noneasync def _rank_inputs(self, file_path: str) -> tuple[dict[str, Any], dict[str, float]]:"""The two rank inputs for one file, as seeks rather than repo reads.@@ -603,7 +378,7 @@ class RefactoringHealthService:.all())for row in rows:- steps = _loads(row.details_json).get("steps") or []+ steps = detail_map(row).get("steps") or []if any(step.get("plan_id") == public_id for step in steps):return rowreturn None@@ -625,178 +400,7 @@ class RefactoringHealthService:.all())by_id = {row.public_id: row for row in rows}- return [_plan_payload(by_id[pid]) for pid in plan_ids if pid in by_id]-- def _next_actions(self, row: Any, steps: list[dict[str, Any]]) -> list[dict[str, Any]]:- """Structured follow-ups, so a drill-down ends somewhere rather than stops."""- actions: list[dict[str, Any]] = []- first = steps[0] if steps else None- if first and first.get("line_start") is not None and first.get("line_end") is not None:- actions.append(- {- "why": "read the span the first step names",- "tool": "get_symbol",- "arguments": {- "symbol_id": f"{first['file_path']}:{first['line_start']}-{first['line_end']}"- },- }- )- actions.append(- {- "why": "what history says about touching this file",- "tool": "get_risk",- "arguments": {"targets": [row.file_path]},- }- )- if row.evidence_total:- actions.append(- {- "why": "page the supporting observations",- "tool": "get_health",- "arguments": {- "opportunity_id": row.opportunity_id,- "only": ["refactoring_evidence"],- },- }- )- return actions+ return [plan_payload(by_id[pid]) for pid in plan_ids if pid in by_id]- def _serialize(- self, row: Any, *, steps_limit: int | None = None, evidence_limit: int = 0- ) -> dict[str, Any]:- details = _loads(row.details_json)- steps = list(details.get("steps") or [])- evidence = list(details.get("evidence") or [])- payload: dict[str, Any] = {- "opportunity_id": row.opportunity_id,- "refactoring_model_version": row.refactoring_model_version,- "status": row.status,- "file_path": row.file_path,- "lead_biomarker": row.lead_biomarker,- "lead_refactoring_type": row.lead_refactoring_type,- "addresses_primary_problem": row.addresses_primary_problem,- "effort_bucket": row.effort_bucket,- "confidence": row.confidence,- "step_count": row.step_count,- "mechanical_steps": row.mechanical_steps,- "judgment_steps": row.judgment_steps,- "evidence_total": row.evidence_total,- "affected_files_total": row.affected_files_total,- "recoverable_health": round(float(row.recoverable_health), 3),- "rank_score": round(float(row.rank_score), 4),- "rank_position": row.rank_position,- "queue_position": row.queue_position,- "rank_factors": details.get("rank_factors") or {},- "why_ranked": details.get("why_ranked") or [],- }- # The file's own size and reach, recorded by the finalizer. Omitted when- # the store predates them, so a surface can tell "not measured" from a- # genuine zero rather than plotting an unmeasured file at the origin.- for key in ("file_nloc", "dependents"):- if isinstance(details.get(key), int):- payload[key] = details[key]- if steps_limit is not None:- kept = steps[: max(steps_limit, 0)]- payload["steps"] = kept- payload["steps_total"] = len(steps)- payload["steps_emitted"] = len(kept)- if len(kept) < len(steps):- payload["steps_reduced_reason"] = "limit"- if evidence_limit:- payload.update(evidence_block(evidence[:evidence_limit], len(evidence), 0))- return payload--def _stored_validation(owner: Any, public_id: str | None) -> Any:- """The validation profile the finalizer resolved for this step.-- Test reachability is a graph walk over the whole unanswered set; it belongs- at index time, and this reads its result rather than repeating it.- """- if owner is None or not public_id:- return None- details = _loads(owner.details_json)- wanted = next(- (- step.get("validation_profile_id")- for step in (details.get("steps") or [])- if step.get("plan_id") == public_id- ),- None,- )- if not wanted:- return None- profile = next(- (p for p in (details.get("validation_profiles") or []) if p.get("id") == wanted),- None,- )- return _validation_from_profile(profile) if profile is not None else None---def _validation_from_profile(profile: dict[str, Any]) -> Any:- """Rebuild a stored validation profile into the plan dataclass."""- from repowise.core.analysis.health.refactoring.recommendations import (- ValidationPlan,- ValidationTarget,- )-- target_fields = set(ValidationTarget.__dataclass_fields__)- values = {- key: value- for key, value in profile.items()- if key in ValidationPlan.__dataclass_fields__- }- values["targets"] = [- ValidationTarget(**{k: v for k, v in target.items() if k in target_fields})- for target in (profile.get("targets") or [])- if isinstance(target, dict)- ]- return ValidationPlan(**values)---def _plan_payload(row: Any) -> dict[str, Any]:- """The stored plan, without re-hydrating rank or validation.-- Detail reads the payload the detector wrote and the finalizer already- validated; recomputing benefit and coverage here is what made a one-row- lookup cost the repository.- """- return {- "id": row.public_id or row.id,- "refactoring_type": row.refactoring_type,- "file_path": row.file_path,- "target_symbol": row.target_symbol,- "line_start": row.line_start,- "line_end": row.line_end,- "plan": _loads(row.plan_json),- "evidence": _loads(row.evidence_json),- "blast_radius": _loads(row.blast_radius_json),- "impact_delta": row.impact_delta,- "effort_bucket": row.effort_bucket,- "confidence": row.confidence,- "source_biomarker": row.source_biomarker,- "status": row.status,- }---def _loads(raw: str | None) -> dict[str, Any]:- if not raw:- return {}- try:- value = json.loads(raw)- except (TypeError, ValueError):- return {}- return value if isinstance(value, dict) else {}---__all__ = [- "CANONICAL_ORDERS",- "CANONICAL_VIEWS",- "DEFAULT_VIEW",- "RefactoringHealthService",- "RefactoringPage",- "RefactoringQuery",- "evidence_block",- "parse_query",- "plan_view",-]+__all__ = ["RefactoringHealthService", "RefactoringPage"]diff --git a/tests/unit/cli/test_refactoring_targets_stored.py b/tests/unit/cli/test_refactoring_targets_stored.pyindex 0c8a2aad7..49567e7be 100644--- a/tests/unit/cli/test_refactoring_targets_stored.py+++ b/tests/unit/cli/test_refactoring_targets_stored.py@@ -62,6 +62,7 @@ _PATHS = [f"pkg{i % 3}/mod{i}.py" for i in range(6)]async def _store(repo_path: Path, paths: list[str] = _PATHS) -> list[str]:"""Seed one opportunity per file; return the stored queue order."""+ from repowise.core.analysis.health.refactoring.serving import parse_queryfrom repowise.core.persistence import (create_engine,create_session_factory,@@ -70,10 +71,7 @@ async def _store(repo_path: Path, paths: list[str] = _PATHS) -> list[str]:init_db,upsert_repository,)- from repowise.server.services.refactoring_health import (- RefactoringHealthService,- parse_query,- )+ from repowise.server.services.refactoring_health import RefactoringHealthServicedb_path = repo_path / ".repowise" / "wiki.db"engine = create_engine(f"sqlite+aiosqlite:///{db_path.as_posix()}")diff --git a/tests/unit/health/test_refactoring_serving.py b/tests/unit/health/test_refactoring_serving.pynew file mode 100644index 000000000..7e3ab34b4--- /dev/null+++ b/tests/unit/health/test_refactoring_serving.py@@ -0,0 +1,378 @@+"""The session-free half of refactoring serving, and its agreement with the store.++The sort, filter and facet rules are one table read two ways: the store builds+SQL from it and ``keep``/``row_sort_key``/``facet_counts`` read it over rows in+memory. The agreement tests run both over the same rows.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import Any++import pytest++from repowise.core.analysis.health.refactoring.serving import (+ SORTS,+ UNAVAILABLE,+ directive_from_summary,+ evidence_block,+ facet_counts,+ keep,+ next_actions,+ parse_query,+ plan_payload,+ plan_view,+ row_sort_key,+ serialize,+ stored_validation,+ summary_payload,+ validation_from_profile,+)+from repowise.core.analysis.health.rows import field++# ---------------------------------------------------------------------------+# Pure shapes+# ---------------------------------------------------------------------------+++def test_parse_query_reports_what_it_discards() -> None:+ query, ignored = parse_query(+ lead_type="extract_method,bogus",+ status="nope",+ confidence="high",+ effort="XXL",+ view="sideways",+ order="random",+ search=" pkg ",+ limit=-5,+ offset=-1,+ )+ assert query.lead_types == ("extract_method",)+ assert query.status == "open"+ assert query.confidence == "high"+ assert query.effort is None+ assert query.path_contains == "pkg"+ assert (query.limit, query.offset) == (0, 0)+ assert query.view == "diversified"+ assert query.resolved_order == "queue"+ assert ignored == {+ "refactoring_type": "bogus",+ "status": "nope",+ "effort": "XXL",+ "refactoring_view": "sideways",+ "order": "random",+ }+++def test_parse_query_scope_follows_files_and_status() -> None:+ assert parse_query()[0].scope == "fix_first"+ assert parse_query(file_paths=[])[0].scope == "all"+ assert parse_query(file_paths=[])[0].file_paths == ()+ assert parse_query(status="resolved", scope="fix_first")[0].scope == "all"+ assert parse_query(view="canonical")[0].resolved_order == "rank"+ assert parse_query(view="canonical", order="file")[0].resolved_order == "file"+++def test_plan_view_maps_the_new_default_to_canonical() -> None:+ assert plan_view(None) == "canonical"+ assert plan_view("diversified") == "canonical"+ assert plan_view("file_spread") == "file_spread"+ assert plan_view("unknown") == "canonical"+++def test_evidence_block_names_the_next_cursor() -> None:+ assert evidence_block([{"a": 1}], 1, 0) == {+ "evidence": [{"a": 1}],+ "evidence_total": 1,+ "evidence_emitted": 1,+ "evidence_truncated": False,+ }+ block = evidence_block([{"a": 1}, {"a": 2}], 5, 2)+ assert block["evidence_truncated"] is True+ assert block["evidence_reduced_reason"] == "evidence_page"+ assert block["evidence_next_cursor"] == 4+++_TARGET = {+ "file_path": "a.py", "basis": "inferred", "via": "call-graph", "total": 1,+ "tests": ["tests/test_a.py"], "truncated": False,+}+_PROFILE = {+ **_TARGET, "affected_files": ["a.py"], "affected_symbols": [], "commands": [],+}+del _PROFILE["file_path"]+++def _row(**over: Any) -> dict[str, Any]:+ details = {+ "steps": [+ {"plan_id": "p1", "file_path": "a.py", "line_start": 3, "line_end": 9,+ "validation_profile_id": "v1"},+ {"plan_id": "p2", "file_path": "a.py"},+ ],+ "evidence": [{"e": 1}, {"e": 2}],+ "rank_factors": {"credit": 1.0},+ "why_ranked": ["x"],+ "file_nloc": 120,+ "validation_profiles": [+ {"id": "v1", **_PROFILE, "targets": [{**_TARGET, "unknown_key": 1}]},+ ],+ }+ row = {+ "opportunity_id": "refop1_a",+ "refactoring_model_version": 1,+ "status": "open",+ "file_path": "a.py",+ "lead_biomarker": "complex_method",+ "lead_refactoring_type": "extract_method",+ "addresses_primary_problem": True,+ "effort_bucket": "S",+ "confidence": "high",+ "step_count": 2,+ "mechanical_steps": 1,+ "judgment_steps": 1,+ "evidence_total": 2,+ "affected_files_total": 1,+ "recoverable_health": 1.23456,+ "rank_score": 0.123456,+ "rank_position": 0,+ "queue_position": 0,+ "details_json": json.dumps(details),+ }+ row.update(over)+ return row+++def test_serialize_reads_columns_and_details() -> None:+ payload = serialize(_row(), steps_limit=1, evidence_limit=1)+ assert list(payload)[:3] == ["opportunity_id", "refactoring_model_version", "status"]+ assert payload["recoverable_health"] == 1.235+ assert payload["rank_score"] == 0.1235+ assert payload["file_nloc"] == 120+ assert "dependents" not in payload+ assert payload["steps_total"] == 2+ assert payload["steps_emitted"] == 1+ assert payload["steps_reduced_reason"] == "limit"+ assert payload["evidence_next_cursor"] == 1+ bare = serialize(_row())+ assert "steps" not in bare and "evidence" not in bare+++def test_next_actions_end_somewhere() -> None:+ row = _row()+ steps = json.loads(row["details_json"])["steps"]+ tools = [action["tool"] for action in next_actions(row, steps)]+ assert tools == ["get_symbol", "get_risk", "get_health"]+ assert next_actions(row, steps)[0]["arguments"] == {"symbol_id": "a.py:3-9"}+ assert [a["tool"] for a in next_actions(_row(evidence_total=0), [])] == ["get_risk"]+++def _summary(lead: dict[str, Any] | None) -> dict[str, Any]:+ return {+ "summary_json": json.dumps({"opportunities_total": 3, "lead": lead}),+ "refactoring_model_version": 1,+ "analyzed_commit": "c" * 40,+ }+++def test_summary_and_directive() -> None:+ assert summary_payload(None) == UNAVAILABLE+ assert directive_from_summary(None) == UNAVAILABLE+ payload = summary_payload(_summary(None))+ assert payload["status"] == "available"+ assert payload["analyzed_commit"] == "c" * 40+ clear = directive_from_summary(_summary(None))+ assert clear["status"] == "clear" and clear["opportunities_total"] == 3+ lead = {"opportunity_id": "refop1_a", "file_path": "a.py", "lead_biomarker": "god_class"}+ available = directive_from_summary(_summary({**lead, "addresses_primary_problem": True}))+ assert available["fix_first"] == "a.py"+ assert available["next_action"]["arguments"] == {"opportunity_id": "refop1_a"}+ assert "note" not in available+ assert "do not address 'god_class'" in directive_from_summary(+ _summary({**lead, "addresses_primary_problem": False})+ )["note"]+ assert "unknown rather than no" in directive_from_summary(_summary(lead))["note"]+++def test_stored_validation_reads_the_finalizers_profile() -> None:+ validation = stored_validation(_row(), "p1")+ assert validation.basis == "inferred"+ assert [target.file_path for target in validation.targets] == ["a.py"]+ assert stored_validation(_row(), "p2") is None+ assert stored_validation(None, "p1") is None+ assert validation_from_profile({**_PROFILE, "targets": [None], "id": "v9"}).targets == []+++def test_plan_payload_prefers_the_public_id() -> None:+ row = {+ "id": "storage",+ "public_id": "refplan_1",+ "refactoring_type": "extract_method",+ "file_path": "a.py",+ "plan_json": json.dumps({"k": 1}),+ "evidence_json": None,+ "blast_radius_json": "[1]",+ "status": "open",+ }+ payload = plan_payload(row)+ assert payload["id"] == "refplan_1"+ assert payload["plan"] == {"k": 1}+ assert payload["evidence"] == {} and payload["blast_radius"] == {}+ assert plan_payload({**row, "public_id": None})["id"] == "storage"+++# ---------------------------------------------------------------------------+# One rule table, two readers+# ---------------------------------------------------------------------------++_SEEDS: list[dict[str, Any]] = [+ # Ties on recoverable health and step count, so the secondary key decides.+ {"file_path": "pkg_a/mod_x.py", "recoverable_health": 2.0, "step_count": 3,+ "lead_refactoring_type": "extract_method", "confidence": "high", "effort_bucket": "S",+ "mechanical_steps": 2, "addresses_primary_problem": True, "status": "open"},+ {"file_path": "pkg_a/modAx.py", "recoverable_health": 2.0, "step_count": 1,+ "lead_refactoring_type": "extract_class", "confidence": "medium", "effort_bucket": "M",+ "mechanical_steps": 0, "addresses_primary_problem": False, "status": "open"},+ {"file_path": "pkgb/mod_y.py", "recoverable_health": 5.0, "step_count": 3,+ "lead_refactoring_type": "split_file", "confidence": "low", "effort_bucket": "L",+ "mechanical_steps": 1, "addresses_primary_problem": None, "status": "open"},+ {"file_path": "pkg_a/sub/z.py", "recoverable_health": 0.0, "step_count": 2,+ "lead_refactoring_type": "extract_method", "confidence": "high", "effort_bucket": "S",+ "mechanical_steps": 0, "addresses_primary_problem": True, "status": "open"},+ {"file_path": "other/w.py", "recoverable_health": 1.5, "step_count": 4,+ "lead_refactoring_type": "break_cycle", "confidence": "high", "effort_bucket": "XL",+ "mechanical_steps": 3, "addresses_primary_problem": False, "status": "acknowledged"},+ {"file_path": "other/v.py", "recoverable_health": 1.5, "step_count": 1,+ "lead_refactoring_type": "extract_method", "confidence": "medium", "effort_bucket": "S",+ "mechanical_steps": 1, "addresses_primary_problem": None, "status": "open"},+]+# A queue order that disagrees with rank order, as the diversified one does.+_QUEUE = [3, 0, 5, 1, 4, 2]++_FILTERS: list[dict[str, Any]] = [+ {},+ {"status": "acknowledged"},+ {"lead_types": ["extract_method"]},+ {"lead_types": ["extract_method", "split_file"]},+ {"lead_types": []},+ {"confidence": "high", "effort": "S"},+ {"file_paths": ["pkg_a/mod_x.py", "other/v.py"]},+ {"file_paths": ["other/v.py"]},+ {"file_paths": []},+ # ``_`` is literal, not a wildcard: ``pkg_a`` must not match ``pkgb``.+ {"path_prefix": "pkg_"},+ {"path_contains": "MOD_"},+ {"path_contains": ""},+ {"mechanical_only": True},+ {"addresses_primary": True},+ {"addresses_primary": False},+ {"opportunity_ids": ["refop_0", "refop_2", "refop_5"]},+ {"opportunity_ids": []},+ {"lead_types": ["extract_method"], "mechanical_only": True, "path_prefix": "pkg_a/"},+]+++def _seed_rows(repository_id: str) -> list[Any]:+ from repowise.core.persistence.models import RefactoringOpportunity++ return [+ RefactoringOpportunity(+ repository_id=repository_id,+ opportunity_id=f"refop_{i}",+ refactoring_model_version=1,+ rank_position=i,+ queue_position=_QUEUE[i],+ rank_score=1.0 / (i + 1),+ lead_biomarker="complex_method",+ judgment_steps=0,+ evidence_total=0,+ affected_files_total=1,+ details_json="{}",+ **seed,+ )+ for i, seed in enumerate(_SEEDS)+ ]+++def _as_mapping(row: Any) -> dict[str, Any]:+ return {column: getattr(row, column) for column in (+ "opportunity_id", "status", "file_path", "lead_refactoring_type", "confidence",+ "effort_bucket", "mechanical_steps", "addresses_primary_problem", "rank_position",+ "queue_position", "recoverable_health", "step_count",+ )}+++async def store(tmp_path: Path):+ from repowise.core.persistence import (+ create_engine,+ create_session_factory,+ get_session,+ init_db,+ upsert_repository,+ )++ engine = create_engine(f"sqlite+aiosqlite:///{(tmp_path / 'wiki.db').as_posix()}")+ try:+ await init_db(engine)+ async with get_session(create_session_factory(engine)) as session:+ repo = await upsert_repository(session, name="repo", local_path=str(tmp_path))+ session.add_all(_seed_rows(repo.id))+ await session.commit()+ yield session, repo.id+ finally:+ await engine.dispose()++[email protected]("params", _FILTERS)[email protected]("order", [*SORTS, None, "unknown"])+async def test_keep_and_sort_agree_with_the_store(store, params, order) -> None:+ from repowise.core.persistence.crud.analysis.refactoring_opportunities import (+ list_refactoring_opportunities,+ refactoring_opportunity_ids,+ )++ session, repository_id = store+ stored, total = await list_refactoring_opportunities(+ session, repository_id, **params, order=order, limit=100+ )+ expected = [row.opportunity_id for row in stored]+ filters = {"status": "open", **params}+ for rows in (_seed_rows(repository_id), [_as_mapping(r) for r in _seed_rows(repository_id)]):+ kept = sorted(+ (row for row in rows if keep(row, filters)), key=lambda r: row_sort_key(r, order)+ )+ assert [field(row, "opportunity_id") for row in kept] == expected+ assert total == len(expected)+ unpaged = await refactoring_opportunity_ids(+ session, repository_id, **{k: v for k, v in params.items() if k != "opportunity_ids"}+ )+ if "opportunity_ids" not in params:+ assert sorted(unpaged) == sorted(expected)+++def test_keep_reads_a_parsed_query() -> None:+ query, _ = parse_query(lead_type="extract_method", mechanical=True)+ rows = [_as_mapping(r) for r in _seed_rows("r")]+ assert [r["opportunity_id"] for r in rows if keep(r, query)] == ["refop_0", "refop_5"]++[email protected]("status", ["open", "acknowledged", "resolved"])[email protected]("ids", [None, ["refop_0", "refop_4"], []])+async def test_facet_counts_agree_with_the_store(store, status, ids) -> None:+ from repowise.core.persistence.crud.analysis.refactoring_opportunities import (+ refactoring_facet_counts,+ )++ session, repository_id = store+ expected = await refactoring_facet_counts(+ session, repository_id, status=status, opportunity_ids=ids+ )+ assert facet_counts(_seed_rows(repository_id), status=status, opportunity_ids=ids) == expected+ assert (+ facet_counts([_as_mapping(r) for r in _seed_rows(repository_id)], status=status,+ opportunity_ids=ids)+ == expected+ )