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.

refactor(performance): move the pure serving half into core and keep the queue rules as data (#2852)

Raghav Chamadiya57aaafede81d
diff --git a/packages/core/src/repowise/core/analysis/health/perf/serving.py b/packages/core/src/repowise/core/analysis/health/perf/serving.py
new file mode 100644
index 000000000..3b91eb69d
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/perf/serving.py
@@ -0,0 +1,575 @@
+"""Serving performance opportunities: the pure half, with no session.
+
+Query parsing, the vocabulary, the plan link and every response shape live
+here. The queue's sort, filter and facet rules are data: the store builds its
+``ORDER BY``, ``WHERE`` and facet aggregate from the same tables that
+: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.
+
+Rows may be ORM rows, SQL rows or mappings; every read goes through
+``rows.field``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from repowise.core.analysis.health import queue_rules
+from repowise.core.analysis.health.finding_identity import finding_public_id
+from repowise.core.analysis.health.fix_first.text import perf_cost
+from repowise.core.analysis.health.queue_rules import NULL_VALUE, FilterRule, SortKeys
+from repowise.core.analysis.health.rows import detail_map, field, json_field
+
+from .opportunities import PERFORMANCE_MODEL_VERSION
+from .opportunity_rank import DEFAULT_QUEUE_STATES, NON_LEADING_MARKERS
+
+if TYPE_CHECKING:
+ from .opportunities import PerformanceOpportunity
+
+PerformanceContext = Literal["production", "tooling", "test", "unknown", "all"]
+
+CANONICAL_CONTEXTS = ("production", "tooling", "test", "unknown")
+"""The whole vocabulary. ``all`` is every one of them, never a subset."""
+
+DEFAULT_CONTEXT: PerformanceContext = "production"
+"""What a caller that names no context is asking about.
+
+Measured on a 17-repository corpus: 56.5% of opportunities are outside
+production code, and the markers concentrated there are the ones that fail
+hand-labelling. Test fixtures, benchmark harnesses, CI scripts and mocks are
+real code, but "this benchmark repeats work" is a fact about a benchmark, not
+performance work someone should schedule. Defaulting to production makes the
+first answer the one a reader can act on; every other context stays one
+selection away and is counted in ``repository_total`` either way.
+"""
+
+_DEPRECATED_CONTEXTS = {"production_tooling": frozenset({"production", "tooling"})}
+"""Accepted for one compatibility window and never emitted as canonical.
+
+An older client asks for Production+Tooling under one name. Answering it keeps
+that client working; echoing the name back would make a retired spelling look
+like the current product concept.
+"""
+
+CANONICAL_VIEWS = ("detail", "summary")
+CONFIDENCES = ("high", "medium", "low")
+ACTIONABILITIES = ("plan_ready", "advisory", "investigate", "expected")
+BOUNDARIES = ("db", "network", "filesystem", "subprocess", "lock", NULL_VALUE)
+
+DEFAULT_ACTIONABILITIES = DEFAULT_QUEUE_STATES
+"""``expected`` rows offer nothing to change and ``investigate`` rows no strategy to apply,
+so both are asked for, not queued. The summary's ``default_queue`` counts each one left out."""
+
+PLAN_REASONS = {
+ "available": "A stored performance plan addresses this exact opportunity.",
+ "no_safe_plan": (
+ "The analysis found the shared cause but could not prove one coherent "
+ "intervention without guessing."
+ ),
+ "not_persisted": (
+ "A supported strategy exists, but this index does not contain its matching "
+ "stored plan. Reindex to refresh recommendations."
+ ),
+}
+
+SUMMARY_UNAVAILABLE = {
+ "status": "unavailable",
+ "reason": "no_materialized_analysis",
+ "detail": (
+ "This index has no materialized performance analysis. Run repowise update "
+ "to build it."
+ ),
+}
+
+# ---------------------------------------------------------------------------
+# The rules, as data
+# ---------------------------------------------------------------------------
+
+#: Orderings the queue offers, as ``(field, descending)`` keys, each ending in
+#: rank so every one is total. Applied by the store rather than to a fetched
+#: page: sorting a page selected by a different key would order twenty rows
+#: correctly and the repository wrongly.
+SORTS: dict[str, SortKeys] = {
+ "rank": (("rank_position", False),),
+ "leverage": (("affected_call_sites_total", True), ("rank_position", False)),
+ "observations": (("observations_total", True), ("rank_position", False)),
+}
+DEFAULT_SORT = "rank"
+CANONICAL_SORTS = tuple(SORTS)
+
+#: The parameters are :class:`PerformanceQuery` attributes; ``status`` is
+#: always ``open``, since a resolved id is a detail read, never a queue row.
+FILTERS: tuple[FilterRule, ...] = (
+ FilterRule("status", "status", "eq", "always"),
+ FilterRule("contexts", "execution_context", "in", "set"),
+ # A cause with no I/O boundary is stored as NULL and asked for as ``none``.
+ FilterRule("boundary", "boundary_kind", "eq_or_null", "set"),
+ FilterRule("confidence", "evidence_confidence", "eq", "set"),
+ FilterRule("actionabilities", "actionability_state", "in", "set"),
+ FilterRule("file_paths", "file_path", "in", "set"),
+)
+
+#: Facet name, the field it counts, and the filter parameter it is
+#: cross-filtered by (``None``: no filter narrows it).
+FACETS: tuple[tuple[str, str, str | None], ...] = (
+ ("context", "execution_context", "contexts"),
+ ("boundary", "boundary_kind", "boundary"),
+ ("confidence", "evidence_confidence", "confidence"),
+ ("actionability", "actionability_state", "actionabilities"),
+ ("plan_state", "plan_state", None),
+)
+FACET_FIELDS = tuple(column for _, column, _ in FACETS)
+
+# The rules a facet group can be tested by: the ones on a facet's own field.
+_FACET_FILTERS = tuple(rule for rule in FILTERS if rule.field in FACET_FIELDS)
+
+
+def sort_keys(sort: str | None) -> SortKeys:
+ """The keys for *sort*; an unknown sort reads as rank."""
+ return SORTS.get(sort or DEFAULT_SORT, SORTS[DEFAULT_SORT])
+
+
+def keep(row: Any, params: Any) -> bool:
+ """Whether *row* passes every filter *params* sets (a query or a mapping)."""
+ return queue_rules.keep(FILTERS, row, params)
+
+
+def row_sort_key(row: Any, sort: str | None = None) -> tuple[Any, ...]:
+ """The sort key for *sort*; an unknown sort reads as rank."""
+ return queue_rules.sort_key(sort_keys(sort), row)
+
+
+def _facet_selection(query: PerformanceQuery) -> dict[str, Any]:
+ """What a caller chose, per facet. The default queue states are not a
+ choice, so an unfiltered actionability control still shows every state."""
+ return {
+ "contexts": query.contexts,
+ "boundary": query.boundary,
+ "confidence": query.confidence,
+ "actionabilities": (
+ None if query.actionability is None else frozenset({query.actionability})
+ ),
+ }
+
+
+def _count(groups: list[dict[str, Any]], column: str, params: dict[str, Any]) -> dict[str, int]:
+ counts: dict[str, int] = {}
+ for group in groups:
+ if queue_rules.keep(_FACET_FILTERS, group, params):
+ key = group[column] or NULL_VALUE
+ counts[key] = counts.get(key, 0) + group["count"]
+ return counts
+
+
+def fold_facets(
+ groups: Iterable[Sequence[Any]], query: PerformanceQuery
+) -> dict[str, list[dict[str, Any]]]:
+ """Fold ``(*facet fields, count)`` groups into per-value counts.
+
+ Each facet is cross-filtered by the *other* selections: counting a facet
+ under its own filter would leave every alternative at zero, so choosing
+ one value would erase the others from the control.
+ """
+ rows = [dict(zip((*FACET_FIELDS, "count"), group, strict=True)) for group in groups]
+ selection = _facet_selection(query)
+ facets: dict[str, list[dict[str, Any]]] = {}
+ for name, column, own in FACETS:
+ others = {param: value for param, value in selection.items() if param != own}
+ counts = _count(rows, column, others)
+ facets[name] = [
+ {"value": value, "total": total}
+ for value, total in sorted(counts.items(), key=lambda item: (-item[1], item[0]))
+ ]
+ return facets
+
+
+def facet_counts(rows: Iterable[Any], query: PerformanceQuery) -> dict[str, list[dict[str, Any]]]:
+ """:func:`fold_facets` over opportunity rows in memory, as the store scopes them:
+ every open row in the query's files."""
+ scope = {"status": "open", "file_paths": query.file_paths}
+ return fold_facets(
+ ((*(field(row, column) for column in FACET_FIELDS), 1) for row in rows if keep(row, scope)),
+ query,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Query
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class PerformanceQuery:
+ """One request for a page of the queue, in canonical terms.
+
+ Built by :func:`parse_query` so both adapters normalize identically and an
+ unrecognized value is reported rather than silently read as "no results".
+ """
+
+ context: PerformanceContext = DEFAULT_CONTEXT
+ boundary: str | None = None
+ confidence: str | None = None
+ actionability: str | None = None
+ view: str = "detail"
+ sort: str = DEFAULT_SORT
+ file_paths: tuple[str, ...] | None = None
+ limit: int = 20
+ offset: int = 0
+
+ @property
+ def status(self) -> str:
+ return "open"
+
+ @property
+ def contexts(self) -> frozenset[str] | None:
+ if self.context == "all":
+ return None
+ alias = _DEPRECATED_CONTEXTS.get(self.context)
+ return alias if alias is not None else frozenset({self.context})
+
+ @property
+ def actionabilities(self) -> frozenset[str]:
+ """The set the queue is filtered to: one explicit state, or the default queue states (plan_ready, advisory)."""
+ if self.actionability is None:
+ return DEFAULT_ACTIONABILITIES
+ return frozenset({self.actionability})
+
+
+def _resolve_context(context: str | None, ignored: dict[str, str]) -> PerformanceContext:
+ if not context:
+ return DEFAULT_CONTEXT
+ if context in CANONICAL_CONTEXTS or context == "all" or context in _DEPRECATED_CONTEXTS:
+ return context # type: ignore[return-value]
+ # Named, so the caller learns the value was not understood, then treated
+ # as absent like every other unrecognized filter.
+ ignored["performance_context"] = (
+ f"{context} (accepted: {', '.join((*CANONICAL_CONTEXTS, 'all'))})"
+ )
+ return DEFAULT_CONTEXT
+
+
+def parse_query(
+ *,
+ context: str | None = None,
+ boundary: str | None = None,
+ confidence: str | None = None,
+ actionability: str | None = None,
+ view: str | None = None,
+ sort: str | None = None,
+ file_paths: tuple[str, ...] | None = None,
+ limit: int = 20,
+ offset: int = 0,
+) -> tuple[PerformanceQuery, dict[str, str]]:
+ """Normalize caller input, reporting anything unrecognized by name.
+
+ An unknown filter value must not read as an empty repository, so it is
+ dropped from the query and named in the returned map instead.
+ """
+ ignored: dict[str, str] = {}
+
+ def pick(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:
+ if value is None or value == "":
+ return None
+ if value in allowed:
+ return value
+ # Name the vocabulary, so a rejected value is recoverable from the reply.
+ ignored[name] = f"{value} (accepted: {', '.join(allowed)})"
+ return None
+
+ resolved_context = _resolve_context(context, ignored)
+ return (
+ PerformanceQuery(
+ context=resolved_context,
+ boundary=pick("performance_boundary", boundary, BOUNDARIES),
+ confidence=pick("performance_confidence", confidence, CONFIDENCES),
+ actionability=pick("performance_actionability", actionability, ACTIONABILITIES),
+ view=pick("performance_view", view, CANONICAL_VIEWS) or "detail",
+ sort=pick("performance_sort", sort, CANONICAL_SORTS) or DEFAULT_SORT,
+ file_paths=file_paths,
+ limit=max(0, limit),
+ offset=max(0, offset),
+ ),
+ ignored,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Plan link
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class PlanLink:
+ """Where the plan for one opportunity lives, in both address spaces.
+
+ ``row_id`` resolves through the repository-scoped REST route and
+ ``public_id`` through the ``plan_id`` selector on the agent surface. The
+ rule that decides *whether* there is a plan is :func:`plan_link`.
+ """
+
+ state: str
+ row_id: str | None = None
+ public_id: str | None = None
+
+ @property
+ def reason(self) -> str:
+ return PLAN_REASONS[self.state]
+
+
+def plan_link(row: Any, plan: Any | None, public_id: str | None = None) -> PlanLink:
+ """The link for one opportunity row, given its stored plan row (if any)."""
+ if plan is None:
+ # The materialized state already distinguishes "no safe plan" from
+ # "a strategy exists but this index has no plan row".
+ state = field(row, "plan_state")
+ return PlanLink(state if state != "available" else "not_persisted")
+ return PlanLink("available", row_id=str(field(plan, "id")), public_id=public_id)
+
+
+def intervention_file(opportunity: PerformanceOpportunity) -> str:
+ """The file a reader would open first: the intervention, else the evidence."""
+ symbol = opportunity.intervention_symbol
+ if symbol:
+ return symbol.split("::", 1)[0]
+ return opportunity.evidence[0]["file_path"] if opportunity.evidence else ""
+
+
+# ---------------------------------------------------------------------------
+# Shapes
+# ---------------------------------------------------------------------------
+
+
+def serialize(row: Any, link: PlanLink, *, summary: bool = False) -> dict[str, Any]:
+ """Rebuild the canonical opportunity payload from row plus details.
+
+ Columns carry what a query filters or orders on and ``details_json``
+ carries the rest, so no fact is stored twice and nothing here computes
+ a value the writer already decided.
+ """
+ details = detail_map(row)
+ payload = {
+ "opportunity_id": field(row, "opportunity_id"),
+ "performance_model_version": field(row, "performance_model_version"),
+ "biomarker_type": field(row, "biomarker_type"),
+ "biomarker_types": details.get("biomarker_types", []),
+ "boundary_kind": field(row, "boundary_kind"),
+ "execution_context": field(row, "execution_context"),
+ "terminal_sink": field(row, "terminal_sink"),
+ "intervention_symbol": field(row, "intervention_symbol"),
+ "intervention_kind": details.get("intervention_kind"),
+ "file_path": field(row, "file_path"),
+ "affected_call_sites_total": field(row, "affected_call_sites_total"),
+ "affected_files_total": field(row, "affected_files_total"),
+ "observations_total": field(row, "observations_total"),
+ "confidence": field(row, "evidence_confidence"),
+ "actionability_state": field(row, "actionability_state"),
+ "rank_score": field(row, "rank_score"),
+ "rank_position": field(row, "rank_position"),
+ "why_ranked": details.get("why_ranked", []),
+ # An older store has no per-group answer; its marker gives the old one.
+ "may_lead": details.get(
+ "may_lead", field(row, "biomarker_type") not in NON_LEADING_MARKERS
+ ),
+ "plan_id": link.row_id,
+ "plan_reference": link.public_id,
+ "plan_status": link.state,
+ "plan_reason": link.reason,
+ }
+ if summary:
+ return payload
+ return {**payload, **_detail_fields(row, details)}
+
+
+def _detail_fields(row: Any, details: dict[str, Any]) -> dict[str, Any]:
+ """What the ``detail`` view adds to the summary payload."""
+ fix_strategy = field(row, "fix_strategy")
+ return {
+ "terminal_sinks": details.get("terminal_sinks", []),
+ "shared_path_suffix": details.get("shared_path_suffix", []),
+ "resource_fingerprints": details.get("resource_fingerprints", []),
+ "reliable_entry_reachability": details.get("reliable_entry_reachability"),
+ "provenance": details.get("provenance"),
+ "facets": details.get("facets", {}),
+ "gain_text": gain_text(row, details.get("facets") or {}),
+ "actionability_reason": details.get("actionability_reason"),
+ "prerequisites": details.get("prerequisites", []),
+ "rank_factors": details.get("rank_factors", {}),
+ "siblings": details.get("siblings", []),
+ **plan_brief(details.get("plan")),
+ "fix": None
+ if fix_strategy is None
+ else {
+ "strategy": fix_strategy,
+ "safety": field(row, "fix_safety"),
+ "rationale": details.get("fix_rationale") or "",
+ **({"api": details["fix_api"]} if details.get("fix_api") else {}),
+ },
+ }
+
+
+def gain_text(row: Any, facets: dict[str, Any]) -> str:
+ """What fixing this cause buys, in the words the Fix-first item uses."""
+ _problem, gain = perf_cost(
+ "",
+ field(row, "biomarker_type"),
+ field(row, "boundary_kind"),
+ facets.get("amplification"),
+ facets.get("loop_magnitude"),
+ )
+ return gain
+
+
+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:
+ return {}
+ validation = plan.get("validation") or {}
+ keys = ("basis", "via", "total", "tests", "reasons", "commands")
+ return {
+ "validation": {key: validation.get(key) for key in keys},
+ "plan_steps": plan.get("steps", []),
+ "plan_economics": {
+ key: plan.get(key) for key in ("effort_bucket", "benefit", "cost", "risk")
+ },
+ }
+
+
+def summary_payload(row: Any | None) -> dict[str, Any]:
+ """The canonical rollup for one stored summary row, or its absence.
+
+ A missing row means this index has never materialized the analysis, which
+ is a different answer from an empty one and must not read as a clean
+ repository.
+ """
+ if row is None:
+ return dict(SUMMARY_UNAVAILABLE)
+ payload = json_field(row, "summary_json", {})
+ if not isinstance(payload, dict):
+ payload = {}
+ materialized = field(row, "performance_model_version")
+ stale = materialized != PERFORMANCE_MODEL_VERSION
+ return {
+ "status": "stale_model" if stale else "current",
+ "performance_model_version": PERFORMANCE_MODEL_VERSION,
+ "materialized_model_version": materialized,
+ "analyzed_commit": field(row, "analyzed_commit"),
+ "total": field(row, "opportunities_total"),
+ "actionability": payload.get("actionability", {}),
+ "context": payload.get("context", {}),
+ "boundary": payload.get("boundary", {}),
+ "with_plan_total": payload.get("with_plan_total", 0),
+ **({"default_queue": payload["default_queue"]} if "default_queue" in payload else {}),
+ **(
+ {"refresh_required": True, "detail": "Run repowise update to rescore."}
+ if stale
+ else {}
+ ),
+ }
+
+
+def rescope_summary(
+ base: dict[str, Any], groups: Iterable[Sequence[Any]], contexts: frozenset[str]
+) -> dict[str, Any]:
+ """Recount one stored rollup over *contexts*, from the facet aggregate.
+
+ The same grouped counts the filter control is drawn from, summed a second
+ way. Deriving the scoped headline here keeps one materialized row as the
+ only stored rollup: a per-context rollup would be four more rows to write,
+ version and keep honest for a number two sums recover exactly.
+ """
+ actionability: dict[str, int] = {}
+ context: dict[str, int] = {}
+ boundary: dict[str, int] = {}
+ total = 0
+ with_plan = 0
+ for execution_context, boundary_kind, _confidence, state, plan_state, count in groups:
+ if execution_context not in contexts:
+ continue
+ total += count
+ actionability[state] = actionability.get(state, 0) + count
+ context[execution_context] = context.get(execution_context, 0) + count
+ key = boundary_kind or NULL_VALUE
+ boundary[key] = boundary.get(key, 0) + count
+ if plan_state == "available":
+ with_plan += count
+ return {
+ **base,
+ "total": total,
+ "actionability": actionability,
+ "context": context,
+ "boundary": boundary,
+ "with_plan_total": with_plan,
+ }
+
+
+def unresolved_detail(state: dict[str, Any]) -> str:
+ """Why an opportunity id did not resolve, from its ``model_state``."""
+ if state["state"] == "stale_model":
+ return (
+ "That id was minted by performance model "
+ f"{state['requested_model_version']}; this index is on model "
+ f"{state['performance_model_version']}. Membership differs between "
+ "models, so the id is not translated. Run repowise update to rescore."
+ )
+ if state["state"] == "unrecognized":
+ return "That is not a performance opportunity id."
+ return "No open or resolved opportunity in this repository carries that id."
+
+
+def evidence_payload(row: Any) -> dict[str, Any]:
+ """One public evidence entry, addressed by the finding's public id.
+
+ The stored id when there is one, the same kernel recomputed when a store
+ predates the column, and never the storage row id.
+ """
+ details = detail_map(row)
+ return {
+ "finding_id": field(row, "public_id") or finding_public_id(row),
+ "file_path": field(row, "file_path"),
+ "biomarker_type": field(row, "biomarker_type") or "",
+ "function_name": field(row, "function_name"),
+ "line_start": field(row, "line_start"),
+ "line_end": field(row, "line_end"),
+ "reason": field(row, "reason"),
+ "path": list(details.get("path", ())),
+ "provenance": details.get("resolution_basis", "direct"),
+ }
+
+
+__all__ = [
+ "ACTIONABILITIES",
+ "BOUNDARIES",
+ "CANONICAL_CONTEXTS",
+ "CANONICAL_SORTS",
+ "CANONICAL_VIEWS",
+ "CONFIDENCES",
+ "DEFAULT_ACTIONABILITIES",
+ "DEFAULT_CONTEXT",
+ "DEFAULT_SORT",
+ "FACETS",
+ "FACET_FIELDS",
+ "FILTERS",
+ "PLAN_REASONS",
+ "SORTS",
+ "SUMMARY_UNAVAILABLE",
+ "PerformanceContext",
+ "PerformanceQuery",
+ "PlanLink",
+ "evidence_payload",
+ "facet_counts",
+ "fold_facets",
+ "gain_text",
+ "intervention_file",
+ "keep",
+ "parse_query",
+ "plan_brief",
+ "plan_link",
+ "rescope_summary",
+ "row_sort_key",
+ "serialize",
+ "sort_keys",
+ "summary_payload",
+ "unresolved_detail",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/queue_rules.py b/packages/core/src/repowise/core/analysis/health/queue_rules.py
new file mode 100644
index 000000000..5b3cb427e
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/queue_rules.py
@@ -0,0 +1,102 @@
+"""Queue filter and sort rules as data, read over rows in memory.
+
+A materialized queue (refactoring, performance) declares its filters as
+:class:`FilterRule` rows and its orders as ``(field, descending)`` keys. The
+performance store turns the same tables into SQL
+(``persistence.sql.rule_predicate`` and ``persistence.sql.order_by``); the
+functions here read them over rows already in memory, so the two cannot
+disagree about what a queue holds or its order.
+
+Rows and params may be ORM rows, dataclasses or mappings; every read goes
+through ``rows.field``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from repowise.core.analysis.health.rows import field
+
+FilterOp = Literal["eq", "in", "contains", "prefix", "positive", "is", "eq_or_null"]
+
+#: How ``eq_or_null`` spells a NULL column in a caller's vocabulary.
+NULL_VALUE = "none"
+
+SortKeys = tuple[tuple[str, bool], ...]
+
+
+@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"]
+
+
+def active_filters(rules: Iterable[FilterRule], params: Any) -> list[tuple[FilterRule, Any]]:
+ """The *rules* that *params* (a query or a mapping) narrows by, with values."""
+ active: list[tuple[FilterRule, Any]] = []
+ for rule in rules:
+ 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:
+ """Whether a row's *actual* field value passes *rule* set to *value*."""
+ if rule.op == "eq":
+ return actual == value
+ if rule.op == "in":
+ return actual in value
+ if rule.op == "eq_or_null":
+ return actual is None if value == NULL_VALUE else actual == 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(rules: Iterable[FilterRule], row: Any, params: Any) -> bool:
+ """Whether *row* passes every one of *rules* that *params* sets."""
+ return all(
+ matches(rule, value, field(row, rule.field))
+ for rule, value in active_filters(rules, params)
+ )
+
+
+def sort_key(keys: SortKeys, row: Any) -> tuple[Any, ...]:
+ """The sort key for *row* under *keys*; a descending field must be numeric."""
+ return tuple(-field(row, name) if descending else field(row, name) for name, descending in keys)
+
+
+__all__ = [
+ "NULL_VALUE",
+ "FilterOp",
+ "FilterRule",
+ "SortKeys",
+ "active_filters",
+ "keep",
+ "matches",
+ "sort_key",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/serving.py b/packages/core/src/repowise/core/analysis/health/refactoring/serving.py
index a0fc3ec16..9aeff2950 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/serving.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/serving.py
@@ -15,6 +15,7 @@ from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any, Literal
+from repowise.core.analysis.health.queue_rules import FilterRule
from repowise.core.analysis.health.rows import detail_map, field
from .recommendations import _loads_dict
@@ -89,24 +90,6 @@ SORTS: dict[str, tuple[tuple[str, bool], ...]] = {
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"),
@@ -574,7 +557,6 @@ __all__ = [
"SCOPES",
"SORTS",
"UNAVAILABLE",
- "FilterRule",
"RefactoringQuery",
"active_filters",
"directive_from_summary",
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
index f8a9dac9e..fcad7f2c2 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
@@ -27,6 +27,7 @@ from ...models import (
_new_uuid,
_now_utc,
)
+from ...sql import order_by, rule_predicate
from .refactoring import _refactoring_row_kwargs
if TYPE_CHECKING:
@@ -100,6 +101,8 @@ def _row_kwargs(
analyzed_commit: str | None,
plan: dict[str, Any] | None = None,
) -> dict[str, Any]:
+ from ....analysis.health.perf.serving import intervention_file
+
fix = opportunity.fix
return {
"opportunity_id": opportunity.opportunity_id,
@@ -115,7 +118,7 @@ def _row_kwargs(
"plan_state": plan_state,
"fix_strategy": fix.strategy if fix else None,
"fix_safety": fix.safety if fix else None,
- "file_path": _intervention_file(opportunity),
+ "file_path": intervention_file(opportunity),
"intervention_symbol": opportunity.intervention_symbol,
"terminal_sink": opportunity.terminal_sink,
"observations_total": opportunity.observations_total,
@@ -126,14 +129,6 @@ def _row_kwargs(
}
-def _intervention_file(opportunity: OpportunityModel) -> str:
- """The file a reader would open first: the intervention, else the evidence."""
- symbol = opportunity.intervention_symbol
- if symbol:
- return symbol.split("::", 1)[0]
- return opportunity.evidence[0]["file_path"] if opportunity.evidence else ""
-
-
def _summary_payload(
opportunities: list[OpportunityModel],
plan_states: dict[str, str],
@@ -144,6 +139,7 @@ def _summary_payload(
default_queue_counts,
default_queue_exclusion,
)
+ from ....analysis.health.perf.serving import intervention_file
counts: dict[str, int] = {}
contexts: dict[str, int] = {}
@@ -179,7 +175,7 @@ def _summary_payload(
"execution_context": lead.execution_context,
"intervention_symbol": lead.intervention_symbol,
"terminal_sink": lead.terminal_sink,
- "file_path": _intervention_file(lead),
+ "file_path": intervention_file(lead),
"observations_total": lead.observations_total,
"affected_call_sites_total": lead.affected_call_sites_total,
"affected_files_total": lead.affected_files_total,
@@ -435,52 +431,18 @@ async def get_performance_opportunity(
return result.scalars().first()
-def _predicates(
- repository_id: str,
- *,
- contexts: frozenset[str] | None,
- boundary: str | None,
- confidence: str | None,
- actionabilities: frozenset[str] | None,
- file_paths: tuple[str, ...] | None,
-) -> list[Any]:
- where: list[Any] = [
+def _predicates(repository_id: str, **params: Any) -> list[Any]:
+ """The ``WHERE`` for *params* over open rows, built from the serving layer's filter table."""
+ from ....analysis.health.perf.serving import FILTERS
+ from ....analysis.health.queue_rules import active_filters
+
+ return [
PerformanceOpportunity.repository_id == repository_id,
- PerformanceOpportunity.status == "open",
+ *(
+ rule_predicate(PerformanceOpportunity, rule, value)
+ for rule, value in active_filters(FILTERS, {"status": "open", **params})
+ ),
]
- if contexts is not None:
- where.append(PerformanceOpportunity.execution_context.in_(sorted(contexts)))
- if boundary is not None:
- where.append(
- PerformanceOpportunity.boundary_kind.is_(None)
- if boundary == "none"
- else PerformanceOpportunity.boundary_kind == boundary
- )
- if confidence is not None:
- where.append(PerformanceOpportunity.evidence_confidence == confidence)
- if actionabilities is not None:
- where.append(PerformanceOpportunity.actionability_state.in_(sorted(actionabilities)))
- if file_paths is not None:
- where.append(PerformanceOpportunity.file_path.in_(list(file_paths)))
- return where
-
-
-_ORDERS = {
- "rank": (PerformanceOpportunity.rank_position.asc(),),
- "leverage": (
- PerformanceOpportunity.affected_call_sites_total.desc(),
- PerformanceOpportunity.rank_position.asc(),
- ),
- "observations": (
- PerformanceOpportunity.observations_total.desc(),
- PerformanceOpportunity.rank_position.asc(),
- ),
-}
-"""Orderings the queue offers, each ending in rank so every one is total.
-
-Applied in SQL rather than to the fetched page: sorting a page selected by a
-different key would order twenty rows correctly and the repository wrongly.
-"""
async def list_performance_opportunities(
@@ -501,6 +463,8 @@ async def list_performance_opportunities(
Both statements are index-driven and the fetched rows are the page, so cost
tracks the page rather than the repository.
"""
+ from ....analysis.health.perf.serving import sort_keys
+
where = _predicates(
repository_id,
contexts=contexts,
@@ -521,7 +485,7 @@ async def list_performance_opportunities(
await session.execute(
select(PerformanceOpportunity)
.where(*where)
- .order_by(*_ORDERS.get(sort, _ORDERS["rank"]))
+ .order_by(*order_by(PerformanceOpportunity, sort_keys(sort)))
.offset(offset)
.limit(limit)
)
@@ -540,35 +504,18 @@ async def performance_facet_counts(
) -> list[tuple[str, str | None, str, str, str, int]]:
"""Grouped counts over every open opportunity, in one aggregate statement.
- Returned pre-aggregation rather than as finished facets so the caller can
- cross-filter: a facet must be counted with every filter applied *except*
- its own, or choosing one value would erase the alternatives.
+ Returned pre-aggregation, one ``(*FACET_FIELDS, count)`` tuple per group,
+ so ``perf.serving.fold_facets`` can cross-filter: a facet must be counted
+ with every filter applied *except* its own, or choosing one value would
+ erase the alternatives.
"""
- where = _predicates(
- repository_id,
- contexts=None,
- boundary=None,
- confidence=None,
- actionabilities=None,
- file_paths=file_paths,
- )
+ from ....analysis.health.perf.serving import FACET_FIELDS
+
+ columns = tuple(getattr(PerformanceOpportunity, name) for name in FACET_FIELDS)
result = await session.execute(
- select(
- PerformanceOpportunity.execution_context,
- PerformanceOpportunity.boundary_kind,
- PerformanceOpportunity.evidence_confidence,
- PerformanceOpportunity.actionability_state,
- PerformanceOpportunity.plan_state,
- func.count(),
- )
- .where(*where)
- .group_by(
- PerformanceOpportunity.execution_context,
- PerformanceOpportunity.boundary_kind,
- PerformanceOpportunity.evidence_confidence,
- PerformanceOpportunity.actionability_state,
- PerformanceOpportunity.plan_state,
- )
+ select(*columns, func.count())
+ .where(*_predicates(repository_id, file_paths=file_paths))
+ .group_by(*columns)
)
return [tuple(row) for row in result.all()]
@@ -605,14 +552,7 @@ async def performance_file_rollups(
per-file query. Ordered best-rank first, which is the order a bounded map
feed admits files in.
"""
- where = _predicates(
- repository_id,
- contexts=None,
- boundary=None,
- confidence=None,
- actionabilities=None,
- file_paths=file_paths,
- )
+ where = _predicates(repository_id, file_paths=file_paths)
result = await session.execute(
select(
PerformanceOpportunity.file_path,
diff --git a/packages/core/src/repowise/core/persistence/sql.py b/packages/core/src/repowise/core/persistence/sql.py
index a7938041d..a4cb796fd 100644
--- a/packages/core/src/repowise/core/persistence/sql.py
+++ b/packages/core/src/repowise/core/persistence/sql.py
@@ -7,6 +7,9 @@ escaping the CRUD layer uses.
from __future__ import annotations
+from collections.abc import Iterable
+from typing import Any
+
#: The escape character to pass as ``escape=`` on every ``like``/``ilike``
#: paired with :func:`escape_like`. SQLite has no default LIKE escape
#: character, so it has to be declared on the call for the escaping below to
@@ -25,6 +28,40 @@ def escape_like(value: str) -> str:
return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+def rule_predicate(model: Any, rule: Any, value: Any) -> Any:
+ """One ``analysis.health.queue_rules.FilterRule`` as a SQL predicate on *model*.
+
+ ``queue_rules.matches`` is the same rule read over a row in memory.
+ """
+ # Deferred: the analysis package imports persistence.
+ from repowise.core.analysis.health.queue_rules import NULL_VALUE
+
+ column = getattr(model, rule.field)
+ if rule.op == "eq":
+ return column == value
+ if rule.op == "in":
+ # One value is still one equality; an empty list matches nothing.
+ values = list(value)
+ return column == values[0] if len(values) == 1 else column.in_(values)
+ if rule.op == "eq_or_null":
+ return column.is_(None) if value == NULL_VALUE else column == value
+ if rule.op == "contains":
+ 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 order_by(model: Any, keys: Iterable[tuple[str, bool]]) -> tuple[Any, ...]:
+ """``(field, descending)`` sort keys as an ``ORDER BY`` on *model*."""
+ return tuple(
+ getattr(model, name).desc() if descending else getattr(model, name).asc()
+ for name, descending in keys
+ )
+
+
def is_missing_table(exc: Exception) -> bool:
"""Whether *exc* is "that table is not there" rather than a real failure.
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 ea387a7de..33341a55d 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 annotations
from dataclasses import dataclass, field
from typing import Any
+from repowise.core.analysis.health.perf.serving import parse_query
from repowise.core.analysis.health.refactoring.serving import parse_query as parse_refactoring_query
from repowise.core.analysis.next_call import ActionCommand
from repowise.server.mcp_server.tool_health.paging import Pager
@@ -12,7 +13,6 @@ from repowise.server.mcp_server.tool_health.request import HealthRequest
from repowise.server.services.performance_health import (
PerformanceHealthService,
PerformancePage,
- parse_query,
)
from repowise.server.services.refactoring_health import RefactoringHealthService
diff --git a/packages/server/src/repowise/server/routers/code_health/performance_routes.py b/packages/server/src/repowise/server/routers/code_health/performance_routes.py
index 408262fa5..636311204 100644
--- a/packages/server/src/repowise/server/routers/code_health/performance_routes.py
+++ b/packages/server/src/repowise/server/routers/code_health/performance_routes.py
@@ -13,11 +13,9 @@ from typing import Any
from fastapi import Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.health.perf.serving import parse_query
from repowise.server.deps import get_db_session
-from repowise.server.services.performance_health import (
- PerformanceHealthService,
- parse_query,
-)
+from repowise.server.services.performance_health import PerformanceHealthService
from ._router import router
diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.py
index fc21fb6e4..b2c5a237f 100644
--- a/packages/server/src/repowise/server/services/performance_health.py
+++ b/packages/server/src/repowise/server/services/performance_health.py
@@ -3,35 +3,38 @@
Both surfaces used to load every open finding, regroup the repository, filter
in Python, and link plans by reading two different JSON fields. They disagreed
about the second of those, so one of them never linked a plan at all. This
-module owns the query, the order, the page, the facets, the plan link, the
-detail, and the recovery once; the two adapters map their own vocabulary onto
-it and serialize what comes back.
-
-Nothing here decides what an opportunity *means*. Grouping, actionability, and
-rank live in the analysis package, and the values this module reads were
-already decided when the opportunities were materialized.
+module runs the reads for the query, the order, the page, the facets, the plan
+link, the detail, and the recovery once; the two adapters map their own
+vocabulary onto it and serialize what comes back.
+
+The session-free half (query parsing, the sort/filter/facet rules, the plan
+link and every response shape) is ``analysis/health/perf/serving.py``; this
+module runs the reads and hands rows to it. Nothing here decides what an
+opportunity *means*: grouping, actionability, and rank live in the analysis
+package, and the values read here were decided when the opportunities were
+materialized.
"""
from __future__ import annotations
-import json
from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import Any
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.health.finding_identity import finding_public_id
-from repowise.core.analysis.health.fix_first.text import perf_cost
-from repowise.core.analysis.health.perf.opportunities import (
- PERFORMANCE_MODEL_VERSION,
- model_state,
-)
-from repowise.core.analysis.health.perf.opportunity_rank import (
- DEFAULT_QUEUE_STATES,
- NON_LEADING_MARKERS,
+from repowise.core.analysis.health.perf.opportunities import model_state
+from repowise.core.analysis.health.perf.serving import (
+ PerformanceQuery,
+ PlanLink,
+ evidence_payload,
+ fold_facets,
+ plan_link,
+ rescope_summary,
+ serialize,
+ summary_payload,
+ unresolved_detail,
)
from repowise.core.analysis.health.refactoring.serving import evidence_block
-from repowise.core.analysis.health.rows import detail_map
from repowise.core.persistence.crud import (
get_performance_opportunity,
get_performance_plan_rows,
@@ -44,114 +47,6 @@ from repowise.core.persistence.crud import (
from ..mcp_server._references import refactoring_plan_id
-PerformanceContext = Literal["production", "tooling", "test", "unknown", "all"]
-
-CANONICAL_CONTEXTS = ("production", "tooling", "test", "unknown")
-"""The whole vocabulary. ``all`` is every one of them, never a subset."""
-
-DEFAULT_CONTEXT: PerformanceContext = "production"
-"""What a caller that names no context is asking about.
-
-Measured on a 17-repository corpus: 56.5% of opportunities are outside
-production code, and the markers concentrated there are the ones that fail
-hand-labelling. Test fixtures, benchmark harnesses, CI scripts and mocks are
-real code, but "this benchmark repeats work" is a fact about a benchmark, not
-performance work someone should schedule. Defaulting to production makes the
-first answer the one a reader can act on; every other context stays one
-selection away and is counted in ``repository_total`` either way.
-"""
-
-_DEPRECATED_CONTEXTS = {"production_tooling": frozenset({"production", "tooling"})}
-"""Accepted for one compatibility window and never emitted as canonical.
-
-An older client asks for Production+Tooling under one name. Answering it keeps
-that client working; echoing the name back would make a retired spelling look
-like the current product concept.
-"""
-
-CANONICAL_SORTS = ("rank", "leverage", "observations")
-CANONICAL_VIEWS = ("detail", "summary")
-_CONFIDENCES = ("high", "medium", "low")
-_ACTIONABILITIES = ("plan_ready", "advisory", "investigate", "expected")
-_BOUNDARIES = ("db", "network", "filesystem", "subprocess", "lock", "none")
-
-_DEFAULT_ACTIONABILITIES = DEFAULT_QUEUE_STATES
-"""``expected`` rows offer nothing to change and ``investigate`` rows no strategy to apply,
-so both are asked for, not queued. The summary's ``default_queue`` counts each one left out."""
-
-_PLAN_REASONS = {
- "available": "A stored performance plan addresses this exact opportunity.",
- "no_safe_plan": (
- "The analysis found the shared cause but could not prove one coherent "
- "intervention without guessing."
- ),
- "not_persisted": (
- "A supported strategy exists, but this index does not contain its matching "
- "stored plan. Reindex to refresh recommendations."
- ),
-}
-
-_SUMMARY_UNAVAILABLE = {
- "status": "unavailable",
- "reason": "no_materialized_analysis",
- "detail": (
- "This index has no materialized performance analysis. Run repowise update "
- "to build it."
- ),
-}
-
-
-@dataclass(frozen=True, slots=True)
-class PerformanceQuery:
- """One request for a page of the queue, in canonical terms.
-
- Built by :func:`parse_query` so both adapters normalize identically and an
- unrecognized value is reported rather than silently read as "no results".
- """
-
- context: PerformanceContext = DEFAULT_CONTEXT
- boundary: str | None = None
- confidence: str | None = None
- actionability: str | None = None
- view: str = "detail"
- sort: str = "rank"
- file_paths: tuple[str, ...] | None = None
- limit: int = 20
- offset: int = 0
-
- @property
- def contexts(self) -> frozenset[str] | None:
- if self.context == "all":
- return None
- alias = _DEPRECATED_CONTEXTS.get(self.context)
- return alias if alias is not None else frozenset({self.context})
-
- @property
- def actionabilities(self) -> frozenset[str]:
- """The set the queue is filtered to: one explicit state, or the default queue states (plan_ready, advisory)."""
- if self.actionability is None:
- return _DEFAULT_ACTIONABILITIES
- return frozenset({self.actionability})
-
-
-@dataclass(frozen=True, slots=True)
-class PlanLink:
- """Where the plan for one opportunity lives, in both address spaces.
-
- ``row_id`` resolves through the repository-scoped REST route and
- ``public_id`` through the ``plan_id`` selector on the agent surface. The
- rule that decides *whether* there is a plan is above them and is written
- once.
- """
-
- state: str
- row_id: str | None = None
- public_id: str | None = None
-
- @property
- def reason(self) -> str:
- return _PLAN_REASONS[self.state]
-
@dataclass(frozen=True, slots=True)
class PerformancePage:
@@ -164,60 +59,6 @@ class PerformancePage:
ignored_arguments: dict[str, str] = field(default_factory=dict)
-def parse_query(
- *,
- context: str | None = None,
- boundary: str | None = None,
- confidence: str | None = None,
- actionability: str | None = None,
- view: str | None = None,
- sort: str | None = None,
- file_paths: tuple[str, ...] | None = None,
- limit: int = 20,
- offset: int = 0,
-) -> tuple[PerformanceQuery, dict[str, str]]:
- """Normalize caller input, reporting anything unrecognized by name.
-
- An unknown filter value must not read as an empty repository, so it is
- dropped from the query and named in the returned map instead.
- """
- ignored: dict[str, str] = {}
-
- def pick(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:
- if value is None or value == "":
- return None
- if value in allowed:
- return value
- # Name the vocabulary, so a rejected value is recoverable from the reply.
- ignored[name] = f"{value} (accepted: {', '.join(allowed)})"
- return None
-
- resolved_context: PerformanceContext = DEFAULT_CONTEXT
- if context:
- if context in CANONICAL_CONTEXTS or context == "all" or context in _DEPRECATED_CONTEXTS:
- resolved_context = context # type: ignore[assignment]
- else:
- # Named, so the caller learns the value was not understood, then
- # treated as absent like every other unrecognized filter.
- ignored["performance_context"] = (
- f"{context} (accepted: {', '.join((*CANONICAL_CONTEXTS, 'all'))})"
- )
- return (
- PerformanceQuery(
- context=resolved_context,
- boundary=pick("performance_boundary", boundary, _BOUNDARIES),
- confidence=pick("performance_confidence", confidence, _CONFIDENCES),
- actionability=pick("performance_actionability", actionability, _ACTIONABILITIES),
- view=pick("performance_view", view, CANONICAL_VIEWS) or "detail",
- sort=pick("performance_sort", sort, CANONICAL_SORTS) or "rank",
- file_paths=file_paths,
- limit=max(0, limit),
- offset=max(0, offset),
- ),
- ignored,
- )
-
-
class PerformanceHealthService:
"""Query, page, detail, facets, plan linkage, and recovery, in one place."""
@@ -264,9 +105,7 @@ class PerformanceHealthService:
evidence = await self._evidence_for(rows, evidence_per_item)
items = [
{
- **self._serialize(
- row, links[row.opportunity_id], summary=query.view == "summary"
- ),
+ **serialize(row, links[row.opportunity_id], summary=query.view == "summary"),
**(
evidence_block(
evidence.get(row.opportunity_id, []), row.observations_total, 0
@@ -313,61 +152,16 @@ class PerformanceHealthService:
links: dict[str, PlanLink] = {}
for row in rows:
plan = plans.get(row.opportunity_id)
- if plan is None:
- # The materialized state already distinguishes "no safe plan"
- # from "a strategy exists but this index has no plan row".
- state = row.plan_state if row.plan_state != "available" else "not_persisted"
- links[row.opportunity_id] = PlanLink(state)
- continue
- links[row.opportunity_id] = PlanLink(
- "available",
- row_id=str(plan.id),
- public_id=refactoring_plan_id(plan, self._repository),
- )
+ public_id = None if plan is None else refactoring_plan_id(plan, self._repository)
+ links[row.opportunity_id] = plan_link(row, plan, public_id)
return links
async def _facets(self, query: PerformanceQuery) -> dict[str, list[dict[str, Any]]]:
- """Counts per filter value, each cross-filtered by the *other* filters.
-
- Counting a facet under its own filter would leave every alternative at
- zero, so choosing one value would erase the others from the control.
- """
+ """Counts per filter value, each cross-filtered by the *other* filters."""
grouped = await performance_facet_counts(
self._session, self._repository_id, file_paths=query.file_paths
)
- dimensions = {
- "context": 0,
- "boundary": 1,
- "confidence": 2,
- "actionability": 3,
- "plan_state": 4,
- }
- selected = {
- "context": query.contexts,
- "boundary": None if query.boundary is None else frozenset({query.boundary}),
- "confidence": None if query.confidence is None else frozenset({query.confidence}),
- "actionability": (
- None if query.actionability is None else frozenset({query.actionability})
- ),
- "plan_state": None,
- }
- facets: dict[str, list[dict[str, Any]]] = {}
- for name, index in dimensions.items():
- counts: dict[str, int] = {}
- for row in grouped:
- if any(
- values is not None
- and other != name
- and (row[dimensions[other]] or "none") not in values
- for other, values in selected.items()
- ):
- continue
- counts[row[index] or "none"] = counts.get(row[index] or "none", 0) + row[5]
- facets[name] = [
- {"value": value, "total": total}
- for value, total in sorted(counts.items(), key=lambda item: (-item[1], item[0]))
- ]
- return facets
+ return fold_facets(grouped, query)
# -- headline ----------------------------------------------------------
@@ -384,14 +178,14 @@ class PerformanceHealthService:
``repository_total`` survives every scoping, so the census of what was
analyzed is never the thing a filter hides.
"""
- base = _summary_of(await get_performance_summary(self._session, self._repository_id))
+ base = summary_payload(await get_performance_summary(self._session, self._repository_id))
if base["status"] == "unavailable":
return base
base["repository_total"] = base["total"]
if contexts is None:
return base
grouped = await performance_facet_counts(self._session, self._repository_id)
- return _rescope(base, grouped, contexts)
+ return rescope_summary(base, grouped, contexts)
# -- detail ------------------------------------------------------------
@@ -408,10 +202,10 @@ class PerformanceHealthService:
"found": False,
"opportunity_id": opportunity_id,
"model_state": state,
- "detail": _unresolved_detail(state),
+ "detail": unresolved_detail(state),
}
links = await self._plan_links([row])
- payload = self._serialize(row, links[opportunity_id])
+ payload = serialize(row, links[opportunity_id])
evidence, total = await self.evidence(
opportunity_id,
limit=evidence_limit,
@@ -448,215 +242,8 @@ class PerformanceHealthService:
)
return [evidence_payload(row) for row in rows], total
- # -- serialization -----------------------------------------------------
-
- def _serialize(self, row: Any, link: PlanLink, *, summary: bool = False) -> dict[str, Any]:
- """Rebuild the canonical opportunity payload from row plus details.
-
- Columns carry what a query filters or orders on and ``details_json``
- carries the rest, so no fact is stored twice and nothing here computes
- a value the writer already decided.
- """
- details = _loads(row.details_json)
- payload = {
- "opportunity_id": row.opportunity_id,
- "performance_model_version": row.performance_model_version,
- "biomarker_type": row.biomarker_type,
- "biomarker_types": details.get("biomarker_types", []),
- "boundary_kind": row.boundary_kind,
- "execution_context": row.execution_context,
- "terminal_sink": row.terminal_sink,
- "intervention_symbol": row.intervention_symbol,
- "intervention_kind": details.get("intervention_kind"),
- "file_path": row.file_path,
- "affected_call_sites_total": row.affected_call_sites_total,
- "affected_files_total": row.affected_files_total,
- "observations_total": row.observations_total,
- "confidence": row.evidence_confidence,
- "actionability_state": row.actionability_state,
- "rank_score": row.rank_score,
- "rank_position": row.rank_position,
- "why_ranked": details.get("why_ranked", []),
- # An older store has no per-group answer; its marker gives the old one.
- "may_lead": details.get("may_lead", row.biomarker_type not in NON_LEADING_MARKERS),
- "plan_id": link.row_id,
- "plan_reference": link.public_id,
- "plan_status": link.state,
- "plan_reason": link.reason,
- }
- if summary:
- return payload
- fix_strategy = row.fix_strategy
- return {
- **payload,
- "terminal_sinks": details.get("terminal_sinks", []),
- "shared_path_suffix": details.get("shared_path_suffix", []),
- "resource_fingerprints": details.get("resource_fingerprints", []),
- "reliable_entry_reachability": details.get("reliable_entry_reachability"),
- "provenance": details.get("provenance"),
- "facets": details.get("facets", {}),
- "gain_text": _gain_text(row, details.get("facets") or {}),
- "actionability_reason": details.get("actionability_reason"),
- "prerequisites": details.get("prerequisites", []),
- "rank_factors": details.get("rank_factors", {}),
- "siblings": details.get("siblings", []),
- **_plan_brief(details.get("plan")),
- "fix": None
- if fix_strategy is None
- else {
- "strategy": fix_strategy,
- "safety": row.fix_safety,
- "rationale": details.get("fix_rationale") or "",
- **({"api": details["fix_api"]} if details.get("fix_api") else {}),
- },
- }
-
-
-def _gain_text(row: Any, facets: dict[str, Any]) -> str:
- """What fixing this cause buys, in the words the Fix-first item uses."""
- _problem, gain = perf_cost(
- "",
- row.biomarker_type,
- row.boundary_kind,
- facets.get("amplification"),
- facets.get("loop_magnitude"),
- )
- return gain
-
-
-def _rescope(
- base: dict[str, Any],
- grouped: list[tuple[str, str | None, str, str, str, int]],
- contexts: frozenset[str],
-) -> dict[str, Any]:
- """Recount one stored rollup over *contexts*, from the facet aggregate.
-
- The same grouped counts the filter control is drawn from, summed a second
- way. Deriving the scoped headline here keeps one materialized row as the
- only stored rollup: a per-context rollup would be four more rows to write,
- version and keep honest for a number two sums recover exactly.
- """
- actionability: dict[str, int] = {}
- context: dict[str, int] = {}
- boundary: dict[str, int] = {}
- total = 0
- with_plan = 0
- for execution_context, boundary_kind, _confidence, state, plan_state, count in grouped:
- if execution_context not in contexts:
- continue
- total += count
- actionability[state] = actionability.get(state, 0) + count
- context[execution_context] = context.get(execution_context, 0) + count
- key = boundary_kind or "none"
- boundary[key] = boundary.get(key, 0) + count
- if plan_state == "available":
- with_plan += count
- return {
- **base,
- "total": total,
- "actionability": actionability,
- "context": context,
- "boundary": boundary,
- "with_plan_total": with_plan,
- }
-
-
-def _summary_of(row: Any) -> dict[str, Any]:
- """The canonical rollup for one stored summary row, or its absence.
-
- A missing row means this index has never materialized the analysis, which
- is a different answer from an empty one and must not read as a clean
- repository.
- """
- if row is None:
- return dict(_SUMMARY_UNAVAILABLE)
- payload = _loads(row.summary_json)
- stale = row.performance_model_version != PERFORMANCE_MODEL_VERSION
- return {
- "status": "stale_model" if stale else "current",
- "performance_model_version": PERFORMANCE_MODEL_VERSION,
- "materialized_model_version": row.performance_model_version,
- "analyzed_commit": row.analyzed_commit,
- "total": row.opportunities_total,
- "actionability": payload.get("actionability", {}),
- "context": payload.get("context", {}),
- "boundary": payload.get("boundary", {}),
- "with_plan_total": payload.get("with_plan_total", 0),
- **({"default_queue": payload["default_queue"]} if "default_queue" in payload else {}),
- **(
- {"refresh_required": True, "detail": "Run repowise update to rescore."}
- if stale
- else {}
- ),
- }
-
-
-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:
- return {}
- validation = plan.get("validation") or {}
- keys = ("basis", "via", "total", "tests", "reasons", "commands")
- return {
- "validation": {key: validation.get(key) for key in keys},
- "plan_steps": plan.get("steps", []),
- "plan_economics": {
- key: plan.get(key) for key in ("effort_bucket", "benefit", "cost", "risk")
- },
- }
-
-
-def _unresolved_detail(state: dict[str, Any]) -> str:
- if state["state"] == "stale_model":
- return (
- "That id was minted by performance model "
- f"{state['requested_model_version']}; this index is on model "
- f"{state['performance_model_version']}. Membership differs between "
- "models, so the id is not translated. Run repowise update to rescore."
- )
- if state["state"] == "unrecognized":
- return "That is not a performance opportunity id."
- return "No open or resolved opportunity in this repository carries that id."
-
-
-def evidence_payload(row: Any) -> dict[str, Any]:
- """One public evidence entry, addressed by the finding's public id.
-
- The stored id when there is one, the same kernel recomputed when a store
- predates the column, and never the storage row id.
- """
- details = detail_map(row)
- return {
- "finding_id": row.public_id or finding_public_id(row),
- "file_path": row.file_path,
- "biomarker_type": row.biomarker_type or "",
- "function_name": row.function_name,
- "line_start": row.line_start,
- "line_end": row.line_end,
- "reason": row.reason,
- "path": list(details.get("path", ())),
- "provenance": details.get("resolution_basis", "direct"),
- }
-
-
-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_CONTEXTS",
- "CANONICAL_SORTS",
- "CANONICAL_VIEWS",
"PerformanceHealthService",
"PerformancePage",
- "PerformanceQuery",
- "PlanLink",
- "evidence_payload",
- "parse_query",
]
diff --git a/tests/unit/health/test_perf_serving.py b/tests/unit/health/test_perf_serving.py
new file mode 100644
index 000000000..36269924f
--- /dev/null
+++ b/tests/unit/health/test_perf_serving.py
@@ -0,0 +1,283 @@
+"""The session-free half of performance 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
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from repowise.core.analysis.health.perf.opportunities import PERFORMANCE_MODEL_VERSION
+from repowise.core.analysis.health.perf.serving import (
+ SORTS,
+ SUMMARY_UNAVAILABLE,
+ PerformanceQuery,
+ facet_counts,
+ fold_facets,
+ intervention_file,
+ keep,
+ parse_query,
+ plan_link,
+ rescope_summary,
+ row_sort_key,
+ summary_payload,
+)
+from repowise.core.analysis.health.rows import field
+
+# ---------------------------------------------------------------------------
+# Pure shapes
+# ---------------------------------------------------------------------------
+
+
+def test_parse_query_reports_what_it_discards() -> None:
+ query, ignored = parse_query(
+ context="nowhere",
+ boundary="tape",
+ confidence="high",
+ actionability="maybe",
+ view="wide",
+ sort="random",
+ limit=-3,
+ offset=-1,
+ )
+ assert query == PerformanceQuery(confidence="high", limit=0, offset=0)
+ assert set(ignored) == {
+ "performance_context",
+ "performance_boundary",
+ "performance_actionability",
+ "performance_view",
+ "performance_sort",
+ }
+ assert ignored["performance_sort"] == "random (accepted: rank, leverage, observations)"
+
+
+def test_query_resolves_contexts_and_default_queue() -> None:
+ assert parse_query(context="all")[0].contexts is None
+ assert parse_query(context="production_tooling")[0].contexts == {"production", "tooling"}
+ assert parse_query()[0].actionabilities == {"plan_ready", "advisory"}
+ assert parse_query(actionability="expected")[0].actionabilities == {"expected"}
+ assert parse_query(boundary="none")[0].boundary == "none"
+
+
+def test_plan_link_states() -> None:
+ assert plan_link({"plan_state": "no_safe_plan"}, None).state == "no_safe_plan"
+ # A stored "available" with no plan row is a plan this index lacks.
+ missing = plan_link({"plan_state": "available"}, None)
+ assert missing.state == "not_persisted" and "Reindex" in missing.reason
+ linked = plan_link({"plan_state": "available"}, {"id": 7}, "plan:x")
+ assert (linked.state, linked.row_id, linked.public_id) == ("available", "7", "plan:x")
+
+
+def test_intervention_file_prefers_the_symbol() -> None:
+ def opp(symbol: str | None, evidence: list[dict[str, Any]]) -> Any:
+ return SimpleNamespace(intervention_symbol=symbol, evidence=evidence)
+
+ assert intervention_file(opp("a/b.py::f", [{"file_path": "c.py"}])) == "a/b.py"
+ assert intervention_file(opp(None, [{"file_path": "c.py"}])) == "c.py"
+ assert intervention_file(opp(None, [])) == ""
+
+
+def test_summary_payload_names_absence_and_staleness() -> None:
+ assert summary_payload(None) == SUMMARY_UNAVAILABLE
+ row = {
+ "summary_json": '{"actionability": {"advisory": 2}, "default_queue": {"x": 1}}',
+ "performance_model_version": PERFORMANCE_MODEL_VERSION - 1,
+ "analyzed_commit": "c",
+ "opportunities_total": 2,
+ }
+ payload = summary_payload(row)
+ assert payload["status"] == "stale_model" and payload["refresh_required"] is True
+ assert payload["actionability"] == {"advisory": 2} and payload["default_queue"] == {"x": 1}
+ assert summary_payload({**row, "summary_json": "[1]"})["actionability"] == {}
+
+
+def test_rescope_summary_recounts_one_context() -> None:
+ groups = [
+ ("production", None, "high", "advisory", "available", 2),
+ ("production", "db", "low", "plan_ready", "no_safe_plan", 1),
+ ("test", "db", "low", "advisory", "available", 5),
+ ]
+ scoped = rescope_summary({"total": 8, "x": 1}, groups, frozenset({"production"}))
+ assert scoped == {
+ "total": 3,
+ "x": 1,
+ "actionability": {"advisory": 2, "plan_ready": 1},
+ "context": {"production": 3},
+ "boundary": {"none": 2, "db": 1},
+ "with_plan_total": 2,
+ }
+
+
+# ---------------------------------------------------------------------------
+# One rule table, two readers
+# ---------------------------------------------------------------------------
+
+_SEEDS: list[dict[str, Any]] = [
+ {"execution_context": "production", "boundary_kind": "db", "evidence_confidence": "high",
+ "actionability_state": "plan_ready", "plan_state": "available", "file_path": "a.py",
+ "affected_call_sites_total": 4, "observations_total": 9},
+ {"execution_context": "production", "boundary_kind": None, "evidence_confidence": "medium",
+ "actionability_state": "advisory", "plan_state": "no_safe_plan", "file_path": "b.py",
+ "affected_call_sites_total": 4, "observations_total": 2},
+ {"execution_context": "test", "boundary_kind": "network", "evidence_confidence": "low",
+ "actionability_state": "advisory", "plan_state": "not_persisted", "file_path": "a.py",
+ "affected_call_sites_total": 7, "observations_total": 2},
+ {"execution_context": "tooling", "boundary_kind": None, "evidence_confidence": "high",
+ "actionability_state": "expected", "plan_state": "no_safe_plan", "file_path": "c.py",
+ "affected_call_sites_total": 1, "observations_total": 9},
+ {"execution_context": "production", "boundary_kind": "db", "evidence_confidence": "high",
+ "actionability_state": "investigate", "plan_state": "no_safe_plan", "file_path": "c.py",
+ "affected_call_sites_total": 0, "observations_total": 5},
+ {"execution_context": "unknown", "boundary_kind": "filesystem", "evidence_confidence": "medium",
+ "actionability_state": "plan_ready", "plan_state": "available", "file_path": "b.py",
+ "affected_call_sites_total": 7, "observations_total": 1},
+ # Resolved: in no queue and no facet.
+ {"execution_context": "production", "boundary_kind": "db", "evidence_confidence": "high",
+ "actionability_state": "plan_ready", "plan_state": "available", "file_path": "a.py",
+ "affected_call_sites_total": 99, "observations_total": 99, "status": "resolved"},
+]
+
+_QUERIES: list[dict[str, Any]] = [
+ {},
+ {"context": "all"},
+ {"context": "test"},
+ {"context": "production_tooling", "actionability": "expected"},
+ {"context": "all", "boundary": "none"},
+ {"context": "all", "boundary": "db", "confidence": "high"},
+ {"context": "all", "actionability": "investigate"},
+ {"context": "all", "file_paths": ("a.py", "b.py")},
+ {"context": "all", "file_paths": ()},
+ {"boundary": "network"},
+]
+
+
+def _seed_rows(repository_id: str) -> list[Any]:
+ from repowise.core.persistence.models import PerformanceOpportunity
+
+ return [
+ PerformanceOpportunity(
+ repository_id=repository_id,
+ opportunity_id=f"perf_{i}",
+ performance_model_version=PERFORMANCE_MODEL_VERSION,
+ status=seed.get("status", "open"),
+ rank_position=i,
+ details_json="{}",
+ **{k: v for k, v in seed.items() if k != "status"},
+ )
+ 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", "rank_position", *_SEEDS[0],
+ )
+ }
+
+
+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()
+
+
+def _both_shapes(repository_id: str) -> list[list[Any]]:
+ rows = _seed_rows(repository_id)
+ return [rows, [_as_mapping(r) for r in rows]]
+
+
[email protected]("args", _QUERIES)
[email protected]("sort", [*SORTS])
+async def test_keep_and_sort_agree_with_the_store(store, args, sort) -> None:
+ from repowise.core.persistence.crud.analysis.performance import (
+ list_performance_opportunities,
+ )
+
+ session, repository_id = store
+ query, _ = parse_query(**args, sort=sort, limit=100)
+ stored, total = await list_performance_opportunities(
+ session,
+ repository_id,
+ contexts=query.contexts,
+ boundary=query.boundary,
+ confidence=query.confidence,
+ actionabilities=query.actionabilities,
+ file_paths=query.file_paths,
+ sort=query.sort,
+ limit=query.limit,
+ )
+ expected = [row.opportunity_id for row in stored]
+ assert total == len(expected)
+ for rows in _both_shapes(repository_id):
+ kept = sorted((r for r in rows if keep(r, query)), key=lambda r: row_sort_key(r, sort))
+ assert [field(r, "opportunity_id") for r in kept] == expected
+
+
+def _reference_facets(groups: list[tuple], query: PerformanceQuery) -> dict[str, Any]:
+ """The cross-filtered fold as the service wrote it before the rules were data."""
+ dimensions = {"context": 0, "boundary": 1, "confidence": 2, "actionability": 3,
+ "plan_state": 4}
+ selected = {
+ "context": query.contexts,
+ "boundary": None if query.boundary is None else frozenset({query.boundary}),
+ "confidence": None if query.confidence is None else frozenset({query.confidence}),
+ "actionability": (
+ None if query.actionability is None else frozenset({query.actionability})
+ ),
+ "plan_state": None,
+ }
+ facets = {}
+ for name, index in dimensions.items():
+ counts: dict[str, int] = {}
+ for row in groups:
+ if any(
+ values is not None and other != name
+ and (row[dimensions[other]] or "none") not in values
+ for other, values in selected.items()
+ ):
+ continue
+ counts[row[index] or "none"] = counts.get(row[index] or "none", 0) + row[5]
+ facets[name] = [
+ {"value": v, "total": t}
+ for v, t in sorted(counts.items(), key=lambda item: (-item[1], item[0]))
+ ]
+ return facets
+
+
[email protected]("args", _QUERIES)
+async def test_facet_counts_agree_with_the_store(store, args) -> None:
+ from repowise.core.persistence.crud.analysis.performance import performance_facet_counts
+
+ session, repository_id = store
+ query, _ = parse_query(**args)
+ grouped = await performance_facet_counts(
+ session, repository_id, file_paths=query.file_paths
+ )
+ expected = fold_facets(grouped, query)
+ assert expected == _reference_facets(grouped, query)
+ for rows in _both_shapes(repository_id):
+ assert facet_counts(rows, query) == expected