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.

feat(performance): serve the opportunity queue from a materialized read model (#1981)

Raghav Chamadiyaf84eb0b2cc27
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 1f030f6c0..82ab6e46c 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -732,6 +732,12 @@ get_health(include=["performance","refactoring"], only=["performance_opportuniti
| `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50). `0` means no rows; the `*_total` siblings still report the true counts. |
| `finding_id` | string | No | Resolve an emitted stable health-finding `id` directly in one call. |
| `plan_id` | string | No | Resolve an emitted stable refactoring-plan `id` directly in one call. |
+| `opportunity_id` | string | No | Resolve a performance opportunity `id` directly. Mutually exclusive with the two above; passing more than one returns `mode: "conflict"` naming them rather than answering about whichever was checked first. |
+| `performance_view` | string | No | `detail` (default) or `summary`. `summary` keeps identity, counts and plan state and drops the explanatory fields. |
+| `performance_context` | string | No | `production` / `tooling` / `test` / `unknown` / `all`. |
+| `performance_boundary` | string | No | `db` / `network` / `filesystem` / `subprocess` / `lock` / `none`. |
+| `performance_confidence` | string | No | Evidence confidence: `high` / `medium` / `low`. Fix safety and actionability are separate facets. |
+| `performance_sort` | string | No | `rank` (default) / `leverage` / `observations`. |
**Returns:** Dashboard mode (no `targets`) returns a `directive`, repo-level KPIs
(hotspot health, average health, worst performer, maintainability / performance
@@ -894,10 +900,15 @@ payload:
| signal | reads | why |
|---|---|---|
-| the marker | `biomarker_type` | superlinear (`nested_loop_quadratic` 5) > N×M or lock-serialized (4) > one crossing per iteration, or one crossing proven on a hot path (3) > in-loop CPU/allocation (2) > cheap in-loop idioms (1) |
-| the boundary | `details.boundary_kind` | `subprocess` 4 > `network` 3 > `db`/`lock` 2 > `filesystem` 1 — a process spawn in a loop is not a stat in a loop |
+| the marker | `biomarker_type` | superlinear (`nested_loop_quadratic`, `nested_loop_with_io`, `sql_cartesian_join` 6) > lock-serialized (5) > one crossing per iteration, or one proven on a hot path (4) > in-loop CPU/allocation (3) > repeated acquisition with no boundary (2); an unweighted marker takes the floor (1) |
+| the boundary | `details.boundary_kind` | `subprocess` 5 > `network`/`db` 4 > `lock` 3 > `filesystem` 2. A process spawn in a loop is not a stat in a loop |
| the call shape | `details.cross_function` | +1. An intra-function loop is usually visibly bounded at the call site; a cross-function N+1 is the one nobody sees by reading the loop |
+These are the same weights the causal opportunity ranking reads. Two tables
+used to answer "which marker costs more" and had drifted apart on markers both
+named, so a finding and the opportunity built from it could disagree about the
+same evidence.
+
Request-reachability is read off the marker rather than a column:
`hot_path_sync_io` and `nested_loop_quadratic` are only ever emitted for a
function the perf ranker called hot (top-quintile call-graph in-degree, or a
@@ -934,6 +945,33 @@ get_health(only=["top_findings"]) # + top_findings_total, au
get_health(only=["kpis"], limit=0) # headline numbers, no rows at all
```
+### Performance: one lead, then drill down
+
+A bare `get_health()` carries `performance_directive`: one bounded lead with
+its status (`plan_ready` / `advisory` / `investigate` / `clear` / `unavailable`),
+up to three `why_ranked` facets, the exact plan state, and a structured
+`next_action`. Performance findings carry `health_impact: 0` by construction, so
+they never competed for the main `directive` and the dashboard used to report
+counts and nothing to act on. `clear` means no supported pattern surfaced, which
+is not a claim about how the code runs; `unavailable` means this index has not
+materialized the analysis yet, or did so under an older model.
+
+```
+get_health() # the lead
+get_health(include=["performance"], only=["performance_summary"])
+get_health(include=["performance"], only=["performance_opportunities"], performance_context="production")
+get_health(opportunity_id="perf2_...") # the cause, its plan, its evidence
+get_health(opportunity_id="perf2_...", only=["performance_evidence"], cursor=3)
+```
+
+Ids are stable within a performance model version and are never translated
+across one, because grouping decides membership and two models disagree about
+it. An id from an older model resolves to `model_state.state: "stale_model"`
+with `refresh_required`, rather than failing to match and reading as "no plan".
+Evidence rows carry the finding's public `finding_id`, which round-trips through
+the `finding_id` selector; storage row ids are republished on every analysis and
+are never emitted.
+
---
## Supplementary tools
diff --git a/packages/api-client/src/code-health.ts b/packages/api-client/src/code-health.ts
index 260df27e4..10c67d40b 100644
--- a/packages/api-client/src/code-health.ts
+++ b/packages/api-client/src/code-health.ts
@@ -14,6 +14,10 @@ import type {
HealthFileBreakdownResponse,
HealthOverviewResponse,
HealthTrendResponse,
+ PerformanceActionabilityState,
+ PerformanceExecutionContext,
+ PerformanceOpportunityConfidence,
+ PerformanceOpportunityDetail,
PerformanceOpportunityPage,
HealthWorkQueueQuery,
HealthWorkQueueResponse,
@@ -45,6 +49,15 @@ export type {
HealthWorkQueueQuery,
HealthWorkQueueResponse,
ModuleCoverageRow,
+ PerformanceActionabilityState,
+ PerformanceExecutionContext,
+ PerformanceFacets,
+ PerformanceOpportunity,
+ PerformanceOpportunityConfidence,
+ PerformanceOpportunityDetail,
+ PerformanceOpportunityEvidence,
+ PerformanceOpportunityPage,
+ PerformanceOpportunitySummary,
RefactoringQuery,
RefactoringTarget,
RefactoringTargetsResponse,
@@ -74,7 +87,18 @@ export async function listHealthFindings(
}
export interface PerformanceOpportunityPageParams {
- context?: "production_tooling" | "test" | "all";
+ /**
+ * Canonical contexts. `production_tooling` is a retired spelling the server
+ * still answers as Production+Tooling; it is never returned as a context.
+ */
+ context?: PerformanceExecutionContext | "all" | "production_tooling";
+ boundary?: string;
+ /** Evidence confidence, reported apart from fix safety and actionability. */
+ confidence?: PerformanceOpportunityConfidence;
+ actionability?: PerformanceActionabilityState;
+ /** `summary` drops the explanatory fields and keeps identity and counts. */
+ view?: "detail" | "summary";
+ sort?: "rank" | "leverage" | "observations";
limit?: number;
offset?: number;
}
@@ -85,7 +109,28 @@ export async function getPerformanceOpportunities(
): Promise<PerformanceOpportunityPage> {
return apiGet<PerformanceOpportunityPage>(
`/api/repos/${repoId}/health/performance-opportunities`,
- { context: opts.context, limit: opts.limit, offset: opts.offset },
+ {
+ context: opts.context,
+ boundary: opts.boundary,
+ confidence: opts.confidence,
+ actionability: opts.actionability,
+ view: opts.view,
+ sort: opts.sort,
+ limit: opts.limit,
+ offset: opts.offset,
+ },
+ );
+}
+
+/** One opportunity by its stable id, with bounded evidence. */
+export async function getPerformanceOpportunity(
+ repoId: string,
+ opportunityId: string,
+ opts: { evidenceLimit?: number; evidenceOffset?: number } = {},
+): Promise<PerformanceOpportunityDetail> {
+ return apiGet<PerformanceOpportunityDetail>(
+ `/api/repos/${repoId}/health/performance-opportunities/${encodeURIComponent(opportunityId)}`,
+ { evidence_limit: opts.evidenceLimit, evidence_offset: opts.evidenceOffset },
);
}
diff --git a/packages/core/alembic/versions/0057_performance_opportunities.py b/packages/core/alembic/versions/0057_performance_opportunities.py
new file mode 100644
index 000000000..94679bbc3
--- /dev/null
+++ b/packages/core/alembic/versions/0057_performance_opportunities.py
@@ -0,0 +1,158 @@
+"""Materialize performance opportunities and give findings a queryable identity.
+
+The performance queue was rebuilt from every open performance finding on every
+request, so serving one page of twenty cost the whole repository. This adds the
+table that holds the grouped result, the columns that make identity and plan
+linkage indexable instead of JSON predicates, and the single-row current
+summary a bare dashboard reads.
+
+Every column is nullable or defaulted, and every index is additive, so an
+existing store upgrades without a rewrite and repopulates on its next analysis.
+
+Revision ID: 0057
+Revises: 0056
+Create Date: 2026-08-29
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0057"
+down_revision: str | None = "0056"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_FINDING_INDEXES = (
+ ("ix_health_findings_repo_public_id", ["repository_id", "public_id"]),
+ (
+ "ix_health_findings_repo_status_dimension_opportunity",
+ ["repository_id", "status", "dimension", "opportunity_id"],
+ ),
+)
+
+_OPPORTUNITY_INDEXES = (
+ ("ix_performance_opportunities_repo_id", ["repository_id", "opportunity_id"]),
+ (
+ "ix_performance_opportunities_repo_status_rank",
+ ["repository_id", "status", "rank_position"],
+ ),
+ (
+ "ix_performance_opportunities_repo_status_context_rank",
+ ["repository_id", "status", "execution_context", "rank_position"],
+ ),
+ (
+ "ix_performance_opportunities_repo_status_action_rank",
+ ["repository_id", "status", "actionability_state", "rank_position"],
+ ),
+ (
+ "ix_performance_opportunities_repo_status_path",
+ ["repository_id", "status", "file_path"],
+ ),
+)
+
+
+def upgrade() -> None:
+ op.add_column("health_findings", sa.Column("public_id", sa.String(64), nullable=True))
+ op.add_column("health_findings", sa.Column("opportunity_id", sa.String(64), nullable=True))
+ for name, columns in _FINDING_INDEXES:
+ op.create_index(name, "health_findings", columns, if_not_exists=True)
+
+ op.add_column(
+ "refactoring_suggestions", sa.Column("opportunity_id", sa.String(64), nullable=True)
+ )
+ op.create_index(
+ "ix_refactoring_suggestions_repo_type_opportunity",
+ "refactoring_suggestions",
+ ["repository_id", "refactoring_type", "opportunity_id"],
+ if_not_exists=True,
+ )
+
+ op.create_table(
+ "performance_opportunities",
+ sa.Column("id", sa.String(32), primary_key=True),
+ sa.Column(
+ "repository_id",
+ sa.String(32),
+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),
+ nullable=False,
+ ),
+ sa.Column("opportunity_id", sa.String(64), nullable=False),
+ sa.Column(
+ "performance_model_version", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("status", sa.String(32), nullable=False, server_default="open"),
+ sa.Column("rank_position", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("rank_score", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column(
+ "execution_context", sa.String(16), nullable=False, server_default="unknown"
+ ),
+ sa.Column("boundary_kind", sa.String(32), nullable=True),
+ sa.Column("biomarker_type", sa.String(64), nullable=False, server_default=""),
+ sa.Column(
+ "actionability_state", sa.String(16), nullable=False, server_default="investigate"
+ ),
+ sa.Column("evidence_confidence", sa.String(16), nullable=False, server_default="low"),
+ sa.Column("plan_state", sa.String(16), nullable=False, server_default="no_safe_plan"),
+ sa.Column("fix_strategy", sa.String(64), nullable=True),
+ sa.Column("fix_safety", sa.String(16), nullable=True),
+ sa.Column("file_path", sa.Text(), nullable=False, server_default=""),
+ sa.Column("intervention_symbol", sa.Text(), nullable=True),
+ sa.Column("terminal_sink", sa.Text(), nullable=True),
+ sa.Column("observations_total", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column(
+ "affected_call_sites_total", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("affected_files_total", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("details_json", sa.Text(), nullable=False, server_default="{}"),
+ sa.Column("analyzed_commit", sa.String(40), nullable=True),
+ sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+ sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+ sa.UniqueConstraint(
+ "repository_id",
+ "performance_model_version",
+ "opportunity_id",
+ name="uq_performance_opportunities_repo_model_id",
+ ),
+ )
+ for name, columns in _OPPORTUNITY_INDEXES:
+ op.create_index(name, "performance_opportunities", columns, if_not_exists=True)
+
+ op.create_table(
+ "performance_summaries",
+ sa.Column(
+ "repository_id",
+ sa.String(32),
+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),
+ primary_key=True,
+ ),
+ sa.Column(
+ "performance_model_version", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("opportunities_total", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column("summary_json", sa.Text(), nullable=False, server_default="{}"),
+ sa.Column("analyzed_commit", sa.String(40), nullable=True),
+ sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+ )
+
+
+def downgrade() -> None:
+ op.drop_table("performance_summaries")
+ for name, _columns in _OPPORTUNITY_INDEXES:
+ op.drop_index(name, table_name="performance_opportunities", if_exists=True)
+ op.drop_table("performance_opportunities")
+
+ op.drop_index(
+ "ix_refactoring_suggestions_repo_type_opportunity",
+ table_name="refactoring_suggestions",
+ if_exists=True,
+ )
+ op.drop_column("refactoring_suggestions", "opportunity_id")
+
+ for name, _columns in _FINDING_INDEXES:
+ op.drop_index(name, table_name="health_findings", if_exists=True)
+ op.drop_column("health_findings", "opportunity_id")
+ op.drop_column("health_findings", "public_id")
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index f417a3861..c85c76afa 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -56,6 +56,7 @@ from .perf import (
link_performance_findings,
)
from .refactoring import (
+ PerformancePlanPolicy,
RefactoringContext,
RefactoringSuggestion,
detect_refactorings,
@@ -561,6 +562,10 @@ class HealthAnalyzer:
kpis=kpis,
function_blame_rows=self._function_blame_rows(walked),
refactoring_suggestions=suggestions,
+ performance_plan_policy=PerformancePlanPolicy(
+ enabled=refactoring_enabled and "performance_fix" not in disabled_refactorings,
+ min_confidence=refactoring_min_confidence,
+ ),
)
async def analyze_async(
@@ -754,6 +759,10 @@ class HealthAnalyzer:
kpis=kpis,
function_blame_rows=self._function_blame_rows(walked),
refactoring_suggestions=suggestions,
+ performance_plan_policy=PerformancePlanPolicy(
+ enabled=refactoring_enabled and "performance_fix" not in disabled_refactorings,
+ min_confidence=refactoring_min_confidence,
+ ),
)
# ------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/analysis/health/finding_identity.py b/packages/core/src/repowise/core/analysis/health/finding_identity.py
new file mode 100644
index 000000000..fa38d31d8
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/finding_identity.py
@@ -0,0 +1,79 @@
+"""The public identity of one health finding.
+
+Every finding is republished on each analysis, so a storage row id is a fresh
+UUID every time and cannot be quoted back. This kernel names the finding by
+what it *is* instead, which makes the id stable across runs, storable as a
+column, and safe to hand to an agent.
+
+The kernel holds structural coordinates and detector evidence. It deliberately
+excludes prose and derived values: ``reason`` is generated text that a wording
+change would churn, and two ``details`` keys are outputs of later passes rather
+than facts about the location, so leaving them in would make the id of a
+finding move whenever an unrelated model changed its mind.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import posixpath
+from typing import Any
+
+from .rows import detail_map, field
+
+FINDING_ID_VERSION = 1
+"""Version of the identity kernel below.
+
+It is hashed rather than spelled into the id, because the public reference
+vocabulary is ``<kind>_<digest>`` across every tool and a finding has no
+cross-version resolution story to tell: bumping this simply changes every
+value, and an id minted by an older kernel stops matching.
+"""
+
+_PREFIX = "finding"
+
+_DERIVED_DETAIL_KEYS = frozenset({"opportunity_id", "reliable_entry_reachability"})
+"""Detail keys written by later passes, not by the detector that found the row.
+
+``opportunity_id`` is stamped by causal grouping, so leaving it in would make
+every finding id churn whenever the performance model version moved.
+``reliable_entry_reachability`` is a repository-wide graph answer that flips
+when unrelated code changes.
+"""
+
+
+def _path_identity(path: str) -> str:
+ """One repository-relative POSIX form, so a Windows caller matches."""
+ normalized = posixpath.normpath(str(path).strip().replace("\\", "/"))
+ return normalized.removeprefix("./")
+
+
+def finding_public_id(row: Any) -> str:
+ """The stable public id for one finding row."""
+ details = {
+ key: value
+ for key, value in detail_map(row).items()
+ if key not in _DERIVED_DETAIL_KEYS
+ }
+ kernel = {
+ "kernel_version": FINDING_ID_VERSION,
+ "dimension": field(row, "dimension", None) or "defect",
+ "path": _path_identity(field(row, "file_path", "") or ""),
+ "kind": field(row, "biomarker_type", "") or "",
+ "symbol": field(row, "function_name", None) or "",
+ "line_start": field(row, "line_start", None),
+ "line_end": field(row, "line_end", None),
+ "details": details,
+ }
+ payload = json.dumps(kernel, sort_keys=True, separators=(",", ":"), default=str)
+ digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:20]
+ return f"{_PREFIX}_{digest}"
+
+
+def is_finding_public_id(value: str) -> bool:
+ """Whether a caller-supplied string has the shape this kernel mints."""
+ prefix, separator, digest = value.partition("_")
+ return bool(separator) and prefix == _PREFIX and len(digest) == 20
+
+
+__all__ = ["FINDING_ID_VERSION", "finding_public_id", "is_finding_public_id"]
diff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.py
index d92befb1c..722a92415 100644
--- a/packages/core/src/repowise/core/analysis/health/models.py
+++ b/packages/core/src/repowise/core/analysis/health/models.py
@@ -91,3 +91,9 @@ class HealthReport:
# closure whose performance rows/plans were recomputed for full parity.
authoritative_paths: set[str] = field(default_factory=set)
performance_authoritative_paths: set[str] = field(default_factory=set)
+ # Plan policy for the writer that persists these findings. The performance
+ # plans in ``refactoring_suggestions`` above are a report-level convenience
+ # built from one run's findings; the authoritative ones are generated once,
+ # against the merged stored set, and need this configuration to get there.
+ # Typed ``Any`` for the same reason as ``refactoring_suggestions``.
+ performance_plan_policy: Any | None = None
diff --git a/packages/core/src/repowise/core/analysis/health/perf/facts.py b/packages/core/src/repowise/core/analysis/health/perf/facts.py
index b1e9b75d2..796355b5a 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/facts.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/facts.py
@@ -7,31 +7,11 @@ in: analyzer dataclass, ORM row, or plain dict all reduce here.
from __future__ import annotations
-import json
from dataclasses import dataclass
from typing import Any
-
-def field(row: Any, name: str, default: Any = None) -> Any:
- """Read one attribute from a dataclass, an ORM row, or a dict."""
- if isinstance(row, dict):
- return row.get(name, default)
- return getattr(row, name, default)
-
-
-def detail_map(row: Any) -> dict[str, Any]:
- """The finding's open ``details`` payload, whether stored or in memory."""
- value = field(row, "details", None)
- if isinstance(value, dict):
- return value
- raw = field(row, "details_json", None)
- if isinstance(raw, str):
- try:
- loaded = json.loads(raw)
- return loaded if isinstance(loaded, dict) else {}
- except (TypeError, ValueError):
- return {}
- return {}
+from ..finding_identity import finding_public_id
+from ..rows import detail_map, field
def is_performance(row: Any) -> bool:
@@ -125,8 +105,9 @@ class ObservationFacts:
def observation_facts(row: Any) -> ObservationFacts:
details = detail_map(row)
raw_path = details.get("path", ())
+ stored = field(row, "public_id", None)
return ObservationFacts(
- finding_id=str(field(row, "id", "") or ""),
+ finding_id=stored if isinstance(stored, str) and stored else finding_public_id(row),
file_path=str(field(row, "file_path", "")),
function_name=field(row, "function_name", None),
line_start=field(row, "line_start", None),
@@ -152,8 +133,9 @@ def performance_facts(rows: list[Any]) -> list[ObservationFacts]:
def evidence_row(facts: ObservationFacts) -> dict[str, Any]:
"""One public evidence entry.
- ``finding_id`` is the storage row id, not a content hash: empty before
- persistence, a fresh UUID after. It points within one index only.
+ ``finding_id`` is the finding's public id, which round-trips through the
+ ``finding_id`` selector on both surfaces. Storage row ids are republished
+ on every analysis and never leave this package.
"""
return {
"finding_id": facts.finding_id,
diff --git a/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py b/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py
index 30cac7948..bf64d6632 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py
@@ -20,17 +20,54 @@ from math import log2
from typing import Any
BOUNDARY_POINTS = {"subprocess": 5, "network": 4, "db": 4, "lock": 3, "filesystem": 2}
+"""What one crossing of each boundary costs, as an order of magnitude.
+
+A process spawn is milliseconds, a wire round-trip hundreds of microseconds up,
+a pooled local query tens, and a filesystem call is usually a page-cache hit.
+"A subprocess spawn in a loop is not a stat in a loop" is the whole point.
+"""
+
MULTIPLIER_POINTS = {
+ # Superlinear in the input.
"nested_loop_with_io": 6,
"nested_loop_quadratic": 6,
+ "sql_cartesian_join": 6,
+ # One wait every other thread queues behind.
"blocking_io_under_lock": 5,
+ # One boundary crossing per iteration, or one proven to sit on a hot path.
"io_in_loop": 4,
"serial_await_in_loop": 4,
"resource_construction_in_loop": 4,
+ "goroutine_in_unbounded_loop": 4,
+ "hot_path_sync_io": 4,
+ # In-loop CPU or allocation: real, and orders below a round-trip.
"membership_test_against_list_in_loop": 3,
"string_concat_in_loop": 3,
+ "blocking_sync_in_async": 3,
+ "pandas_iterrows_in_loop": 3,
+ "pd_concat_in_loop": 3,
+ "json_parse_in_loop": 3,
+ "array_spread_in_reduce": 3,
+ "defer_in_loop": 3,
+ "regex_compile_in_loop": 3,
+ "list_insert_zero_in_loop": 3,
+ # Repeated acquisition with no boundary behind it.
"lock_in_loop": 2,
}
+"""How often the marker proves the cost is paid.
+
+Exhaustive over every detector declaring the performance category, because
+both the observation order and the opportunity order read it and a marker
+missing from here would silently take the floor on both.
+"""
+
+UNKNOWN_MULTIPLIER_POINTS = 1
+"""A detector added without a weight under-ranks rather than jumps the queue."""
+
+CROSS_FUNCTION_POINTS = 1
+"""A loop and a sink in different functions is the one nobody sees by reading
+the loop, so it earns a point that an intra-function hit does not."""
+
CONTEXT_POINTS = {"production": 3, "tooling": 2, "test": 1, "unknown": 1}
PROVENANCE_POINTS = {"call-site": 3, "direct": 3, "reliable-edge": 2, "name-fallback": 0}
@@ -114,6 +151,20 @@ def change_risk(affected_files: int) -> str:
return _band(affected_files, _CHANGE_RISK_BANDS, "wide")
+def observation_rank(marker: str | None, boundary: str | None, cross_function: bool) -> int:
+ """Order-of-magnitude key for one raw observation, not one opportunity.
+
+ Findings all carry zero health impact by construction, so without this the
+ performance rows in a ranked list came back in file order. Same tables as
+ the opportunity order above, deliberately: "which marker costs more" is one
+ question, and answering it twice with two sets of numbers is how the two
+ surfaces came to disagree about the same marker.
+ """
+ points = MULTIPLIER_POINTS.get(marker or "", UNKNOWN_MULTIPLIER_POINTS)
+ points += BOUNDARY_POINTS.get(boundary or "", 0)
+ return points + (CROSS_FUNCTION_POINTS if cross_function else 0)
+
+
def rank_factors(
*,
marker: str,
@@ -174,13 +225,16 @@ __all__ = [
"AMPLIFICATION",
"BOUNDARY_POINTS",
"CONTEXT_POINTS",
+ "CROSS_FUNCTION_POINTS",
"MULTIPLIER_POINTS",
"PROVENANCE_POINTS",
+ "UNKNOWN_MULTIPLIER_POINTS",
"amplification",
"change_risk",
"dominant_marker",
"exposure",
"leverage",
+ "observation_rank",
"rank_factors",
"rank_sort_key",
"weakest_provenance",
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py
index 69cf339ce..884620d32 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py
@@ -27,7 +27,7 @@ from .models import (
RefactoringContext,
RefactoringSuggestion,
)
-from .performance_fix import performance_fix_suggestions
+from .performance_fix import PerformancePlanPolicy, performance_fix_suggestions
from .rank import rank_suggestions
from .registry import (
RefactoringDetector,
@@ -39,6 +39,7 @@ from .registry import (
__all__ = [
"CONFIDENCE_LEVELS",
+ "PerformancePlanPolicy",
"RefactoringContext",
"RefactoringDetector",
"RefactoringSuggestion",
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py b/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py
index 525ab6345..07b520e04 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py
@@ -3,6 +3,7 @@
from __future__ import annotations
from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
from repowise.core.analysis.execution_graph import file_of_symbol
@@ -11,6 +12,19 @@ from .models import RefactoringSuggestion
from .registry import effort_bucket
+@dataclass(frozen=True, slots=True)
+class PerformancePlanPolicy:
+ """Whether authoritative plans are generated, and at what confidence floor.
+
+ Read from analyzer configuration and carried to the writer that persists
+ them, because that writer sees the merged stored findings and this module
+ has no view of configuration.
+ """
+
+ enabled: bool = True
+ min_confidence: str | None = None
+
+
def performance_fix_suggestions(
opportunities: Iterable[PerformanceOpportunity],
*,
@@ -101,4 +115,4 @@ def performance_fix_suggestions(
return out
-__all__ = ["performance_fix_suggestions"]
+__all__ = ["PerformancePlanPolicy", "performance_fix_suggestions"]
diff --git a/packages/core/src/repowise/core/analysis/health/rows.py b/packages/core/src/repowise/core/analysis/health/rows.py
new file mode 100644
index 000000000..edb909ad5
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/rows.py
@@ -0,0 +1,36 @@
+"""Reading one health finding whatever shape it arrives in.
+
+A finding reaches this package as an analyzer dataclass before persistence, as
+an ORM row after it, and as a plain dict in tests and fixtures. Everything that
+reads one goes through these two adapters so no consumer has to know which.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def field(row: Any, name: str, default: Any = None) -> Any:
+ """Read one attribute from a dataclass, an ORM row, or a dict."""
+ if isinstance(row, dict):
+ return row.get(name, default)
+ return getattr(row, name, default)
+
+
+def detail_map(row: Any) -> dict[str, Any]:
+ """The finding's open ``details`` payload, whether stored or in memory."""
+ value = field(row, "details", None)
+ if isinstance(value, dict):
+ return value
+ raw = field(row, "details_json", None)
+ if isinstance(raw, str):
+ try:
+ loaded = json.loads(raw)
+ return loaded if isinstance(loaded, dict) else {}
+ except (TypeError, ValueError):
+ return {}
+ return {}
+
+
+__all__ = ["detail_map", "field"]
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
index 83bdcec99..895bb2746 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
@@ -8,7 +8,7 @@ imports are unaffected.
from __future__ import annotations
-from . import coverage, coverage_map, dead_code, health, refactoring # noqa: F401
+from . import coverage, coverage_map, dead_code, health, performance, refactoring # noqa: F401
from .coverage import (
get_coverage_summary,
load_coverage_for_repo,
@@ -54,6 +54,18 @@ from .health import (
upsert_health_findings,
upsert_health_metrics,
)
+from .performance import (
+ finalize_performance_opportunities,
+ get_health_finding_by_public_id,
+ get_performance_opportunity,
+ get_performance_plan_rows,
+ get_performance_summary,
+ list_evidence_for_opportunities,
+ list_opportunity_evidence,
+ list_performance_opportunities,
+ opportunity_details,
+ performance_facet_counts,
+)
from .refactoring import (
get_refactoring_suggestion,
get_refactoring_suggestions,
@@ -69,23 +81,33 @@ __all__ = [
"backfill_module_attribution",
"covered_source_files",
"files_covered_by",
+ "finalize_performance_opportunities",
"get_average_health",
"get_coverage_summary",
"get_dead_code_findings",
"get_dead_code_summary",
"get_deduction_by_path",
"get_file_language_map",
+ "get_health_finding_by_public_id",
"get_health_findings",
"get_health_metrics",
"get_health_snapshot_file_counts",
"get_health_snapshot_headline",
"get_health_summary",
"get_perf_coverage",
+ "get_performance_opportunity",
+ "get_performance_plan_rows",
+ "get_performance_summary",
"get_refactoring_suggestion",
"get_refactoring_suggestions",
"get_test_coverage_summary",
+ "list_evidence_for_opportunities",
"list_health_snapshots",
+ "list_opportunity_evidence",
+ "list_performance_opportunities",
"load_coverage_for_repo",
+ "opportunity_details",
+ "performance_facet_counts",
"replace_dead_code_findings",
"replace_governance_findings",
"save_coverage_files",
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
index 4b76cb2b3..cc607a8eb 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
@@ -26,6 +26,55 @@ from ...models import (
from .._shared import _BATCH_SIZE
+def _health_finding_row_kwargs(finding: Any, repository_id: str) -> dict:
+ """Normalize an analyzer dataclass or a plain dict into ORM row kwargs.
+
+ All three writers land here, so a column added to the row is written by
+ every path or by none. ``public_id`` is stamped here because this is the
+ one place every persisted finding passes through.
+ """
+ # Deferred: the analysis package imports persistence, so a module-level
+ # import here would close the cycle.
+
+ # Deferred: the analysis package imports persistence, so importing it at
+ # module level here would close the cycle.
+ from ....analysis.health.finding_identity import finding_public_id
+ from ....analysis.health.rows import detail_map
+
+ if hasattr(finding, "biomarker_type"):
+ severity = finding.severity
+ data = {
+ "file_path": finding.file_path,
+ "biomarker_type": finding.biomarker_type,
+ "severity": str(severity.value) if hasattr(severity, "value") else str(severity),
+ "function_name": finding.function_name,
+ "line_start": finding.line_start,
+ "line_end": finding.line_end,
+ "details_json": json.dumps(finding.details or {}),
+ "health_impact": float(finding.health_impact),
+ "reason": finding.reason or "",
+ "dimension": getattr(finding, "dimension", None) or "defect",
+ }
+ else:
+ data = dict(finding)
+ if "details" in data:
+ data["details_json"] = json.dumps(data.pop("details") or {})
+ data.setdefault("public_id", finding_public_id(finding))
+ if data.get("dimension") == "performance":
+ # Present before the finalizer runs because the analyzer stamps it into
+ # ``details``; the finalizer restates it from authoritative stored rows.
+ data.setdefault("opportunity_id", detail_map(finding).get("opportunity_id"))
+ return {
+ "id": _new_uuid(),
+ "repository_id": repository_id,
+ **{
+ k: v
+ for k, v in data.items()
+ if k not in ("id", "repository_id") and hasattr(HealthFinding, k)
+ },
+ }
+
+
async def save_health_findings(
session: AsyncSession,
repository_id: str,
@@ -48,37 +97,7 @@ async def save_health_findings(
for i in range(0, len(findings), _BATCH_SIZE):
batch = findings[i : i + _BATCH_SIZE]
for f in batch:
- if hasattr(f, "biomarker_type"):
- severity = f.severity
- severity_str = str(severity.value) if hasattr(severity, "value") else str(severity)
- data = {
- "file_path": f.file_path,
- "biomarker_type": f.biomarker_type,
- "severity": severity_str,
- "function_name": f.function_name,
- "line_start": f.line_start,
- "line_end": f.line_end,
- "details_json": json.dumps(f.details or {}),
- "health_impact": float(f.health_impact),
- "reason": f.reason or "",
- "dimension": getattr(f, "dimension", None) or "defect",
- }
- else:
- data = dict(f)
- if "details" in data:
- data["details_json"] = json.dumps(data.pop("details") or {})
-
- session.add(
- HealthFinding(
- id=_new_uuid(),
- repository_id=repository_id,
- **{
- k: v
- for k, v in data.items()
- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)
- },
- )
- )
+ session.add(HealthFinding(**_health_finding_row_kwargs(f, repository_id)))
await session.flush()
@@ -131,37 +150,7 @@ async def replace_governance_findings(
for i in range(0, len(findings), _BATCH_SIZE):
batch = findings[i : i + _BATCH_SIZE]
for f in batch:
- if hasattr(f, "biomarker_type"):
- severity = f.severity
- severity_str = str(severity.value) if hasattr(severity, "value") else str(severity)
- data = {
- "file_path": f.file_path,
- "biomarker_type": f.biomarker_type,
- "severity": severity_str,
- "function_name": f.function_name,
- "line_start": f.line_start,
- "line_end": f.line_end,
- "details_json": json.dumps(f.details or {}),
- "health_impact": float(f.health_impact),
- "reason": f.reason or "",
- "dimension": getattr(f, "dimension", None) or "defect",
- }
- else:
- data = dict(f)
- if "details" in data:
- data["details_json"] = json.dumps(data.pop("details") or {})
-
- session.add(
- HealthFinding(
- id=_new_uuid(),
- repository_id=repository_id,
- **{
- k: v
- for k, v in data.items()
- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)
- },
- )
- )
+ session.add(HealthFinding(**_health_finding_row_kwargs(f, repository_id)))
await session.flush()
@@ -942,37 +931,7 @@ async def upsert_health_findings(
for i in range(0, len(scoped), _BATCH_SIZE):
batch = scoped[i : i + _BATCH_SIZE]
for f in batch:
- if hasattr(f, "biomarker_type"):
- severity = f.severity
- severity_str = str(severity.value) if hasattr(severity, "value") else str(severity)
- data = {
- "file_path": f.file_path,
- "biomarker_type": f.biomarker_type,
- "severity": severity_str,
- "function_name": f.function_name,
- "line_start": f.line_start,
- "line_end": f.line_end,
- "details_json": json.dumps(f.details or {}),
- "health_impact": float(f.health_impact),
- "reason": f.reason or "",
- "dimension": getattr(f, "dimension", None) or "defect",
- }
- else:
- data = dict(f)
- if "details" in data:
- data["details_json"] = json.dumps(data.pop("details") or {})
-
- session.add(
- HealthFinding(
- id=_new_uuid(),
- repository_id=repository_id,
- **{
- k: v
- for k, v in data.items()
- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)
- },
- )
- )
+ session.add(HealthFinding(**_health_finding_row_kwargs(f, repository_id)))
await session.flush()
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
new file mode 100644
index 000000000..bffb9b615
--- /dev/null
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
@@ -0,0 +1,670 @@
+"""Materialized performance opportunities: one writer, indexed readers.
+
+Grouping runs once per health persistence transaction over the authoritative
+stored findings, and everything that serves the queue reads the result. That is
+the whole point of this module: a request should cost its page, not the
+repository.
+
+The writer is deliberately the only place that decides lifecycle. A cause that
+stops being observed is resolved rather than deleted, so an id an agent is
+holding keeps answering, and rows minted by an older model version are resolved
+for the same reason - they can no longer describe the current tree.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import delete, func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...models import (
+ HealthFileMetric,
+ HealthFinding,
+ PerformanceOpportunity,
+ PerformanceSummary,
+ RefactoringSuggestion,
+ _new_uuid,
+ _now_utc,
+)
+from .refactoring import _refactoring_row_kwargs
+
+if TYPE_CHECKING:
+ from ....analysis.health.perf.opportunities import (
+ PerformanceOpportunity as OpportunityModel,
+ )
+ from ....analysis.health.refactoring.performance_fix import PerformancePlanPolicy
+
+_PLAN_TYPE = "performance_fix"
+
+_EVIDENCE_LIMIT = 8
+"""Evidence rows folded into a persisted plan's affected-location list.
+
+Serving reads evidence from the findings table by opportunity, so this bounds
+the plan payload only.
+"""
+
+# Columns the causal model reads off a row. Narrower than the ORM entity on
+# purpose: the finalizer walks every open performance finding, and ``severity``
+# and ``health_impact`` are not inputs to grouping.
+_OBSERVATION_COLUMNS = (
+ HealthFinding.id,
+ HealthFinding.public_id,
+ HealthFinding.file_path,
+ HealthFinding.biomarker_type,
+ HealthFinding.function_name,
+ HealthFinding.line_start,
+ HealthFinding.line_end,
+ HealthFinding.reason,
+ HealthFinding.details_json,
+ HealthFinding.dimension,
+ HealthFinding.opportunity_id,
+)
+
+
+def opportunity_details(opportunity: OpportunityModel) -> dict[str, Any]:
+ """The explanatory half of one opportunity, the half no query filters on.
+
+ Everything a column already holds is deliberately absent, so the row and
+ the payload cannot drift into disagreeing about the same fact.
+ """
+ return {
+ "biomarker_types": list(opportunity.biomarker_types),
+ "shared_path_suffix": list(opportunity.shared_path_suffix),
+ "resource_fingerprints": list(opportunity.resource_fingerprints),
+ "reliable_entry_reachability": opportunity.reliable_entry_reachability,
+ "provenance": opportunity.provenance,
+ "facets": dict(opportunity.facets),
+ "actionability_reason": opportunity.actionability_reason,
+ "prerequisites": list(opportunity.prerequisites),
+ "rank_factors": dict(opportunity.rank_factors),
+ "why_ranked": [dict(entry) for entry in opportunity.why_ranked],
+ "fix_rationale": opportunity.fix.rationale if opportunity.fix else None,
+ }
+
+
+def _row_kwargs(
+ opportunity: OpportunityModel,
+ *,
+ position: int,
+ plan_state: str,
+ analyzed_commit: str | None,
+) -> dict[str, Any]:
+ fix = opportunity.fix
+ return {
+ "opportunity_id": opportunity.opportunity_id,
+ "performance_model_version": opportunity.performance_model_version,
+ "status": "open",
+ "rank_position": position,
+ "rank_score": opportunity.rank_score,
+ "execution_context": opportunity.execution_context,
+ "boundary_kind": opportunity.boundary_kind,
+ "biomarker_type": opportunity.biomarker_type,
+ "actionability_state": opportunity.actionability_state,
+ "evidence_confidence": opportunity.confidence,
+ "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),
+ "intervention_symbol": opportunity.intervention_symbol,
+ "terminal_sink": opportunity.terminal_sink,
+ "observations_total": opportunity.observations_total,
+ "affected_call_sites_total": opportunity.affected_call_sites_total,
+ "affected_files_total": opportunity.affected_files_total,
+ "details_json": json.dumps(opportunity_details(opportunity), separators=(",", ":")),
+ "analyzed_commit": analyzed_commit,
+ }
+
+
+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]) -> dict:
+ """The compact current headline, written once and read by primary key."""
+ counts: dict[str, int] = {}
+ contexts: dict[str, int] = {}
+ boundaries: dict[str, int] = {}
+ for item in opportunities:
+ counts[item.actionability_state] = counts.get(item.actionability_state, 0) + 1
+ contexts[item.execution_context] = contexts.get(item.execution_context, 0) + 1
+ key = item.boundary_kind or "none"
+ boundaries[key] = boundaries.get(key, 0) + 1
+ lead = opportunities[0] if opportunities else None
+ return {
+ "actionability": counts,
+ "context": contexts,
+ "boundary": boundaries,
+ "with_plan_total": sum(1 for state in plan_states.values() if state == "available"),
+ "lead": None
+ if lead is None
+ else {
+ "opportunity_id": lead.opportunity_id,
+ "actionability_state": lead.actionability_state,
+ "biomarker_type": lead.biomarker_type,
+ "boundary_kind": lead.boundary_kind,
+ "execution_context": lead.execution_context,
+ "intervention_symbol": lead.intervention_symbol,
+ "terminal_sink": lead.terminal_sink,
+ "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,
+ "plan_state": plan_states.get(lead.opportunity_id, "no_safe_plan"),
+ "why_ranked": [dict(entry) for entry in lead.why_ranked],
+ "prerequisites": list(lead.prerequisites),
+ "actionability_reason": lead.actionability_reason,
+ },
+ }
+
+
+async def finalize_performance_opportunities(
+ session: AsyncSession,
+ repository_id: str,
+ *,
+ analyzed_commit: str | None = None,
+ plan_policy: PerformancePlanPolicy | None = None,
+) -> int:
+ """Rebuild this repository's performance read model from stored findings.
+
+ Called by both the repo-wide and the per-path health writers, after their
+ own rows land and inside their transaction, so the queue can never describe
+ a set of findings that was never committed. Returns the number of open
+ opportunities.
+ """
+ # Deferred throughout this module: the analysis package imports
+ # persistence, so a module-level import here would close the cycle.
+ from ....analysis.health.perf.opportunities import build_performance_opportunities
+ from ....analysis.health.refactoring.performance_fix import PerformancePlanPolicy
+
+ policy = plan_policy or PerformancePlanPolicy()
+ rows = list(
+ (
+ await session.execute(
+ select(*_OBSERVATION_COLUMNS).where(
+ HealthFinding.repository_id == repository_id,
+ HealthFinding.status == "open",
+ HealthFinding.dimension == "performance",
+ )
+ )
+ ).all()
+ )
+ opportunities = build_performance_opportunities(rows, evidence_limit=_EVIDENCE_LIMIT)
+
+ await _restamp_findings(session, rows)
+ plan_states = await _replace_plans(session, repository_id, opportunities, policy)
+ await _reconcile_opportunities(session, repository_id, opportunities, plan_states, analyzed_commit)
+ await _write_summary(session, repository_id, opportunities, plan_states, analyzed_commit)
+ return len(opportunities)
+
+
+async def _restamp_findings(session: AsyncSession, rows: list[Any]) -> None:
+ """Point every stored observation at its cause, and give it a public id.
+
+ The causal key reads one observation's own facts, so the link only ever
+ changes for rows written before the column existed or under an older model.
+ """
+
+ from ....analysis.health.finding_identity import finding_public_id
+ from ....analysis.health.perf.opportunities import opportunity_id_for_finding
+
+ changed = []
+ for row in rows:
+ values = {}
+ if (opportunity_id := opportunity_id_for_finding(row)) != row.opportunity_id:
+ values["opportunity_id"] = opportunity_id
+ if not row.public_id:
+ # A store written before the column existed. Backfilling here is
+ # what lets its evidence carry a quotable reference without a
+ # separate migration pass over the table.
+ values["public_id"] = finding_public_id(row)
+ if values:
+ changed.append({"id": row.id, **values})
+ if changed:
+ await session.execute(update(HealthFinding), changed)
+
+
+async def _replace_plans(
+ session: AsyncSession,
+ repository_id: str,
+ opportunities: list[OpportunityModel],
+ policy: PerformancePlanPolicy,
+) -> dict[str, str]:
+ """Write the authoritative plans and report each opportunity's plan state.
+
+ Plans are generated here rather than from an analysis report because the
+ report sees one run's findings while this sees the merged stored set, and a
+ partial run must not be allowed to publish a plan built from a subset.
+ """
+
+ from ....analysis.health.refactoring.performance_fix import performance_fix_suggestions
+
+ await session.execute(
+ delete(RefactoringSuggestion).where(
+ RefactoringSuggestion.repository_id == repository_id,
+ RefactoringSuggestion.refactoring_type == _PLAN_TYPE,
+ )
+ )
+ states = {
+ item.opportunity_id: ("no_safe_plan" if item.fix is None else "not_persisted")
+ for item in opportunities
+ }
+ if not policy.enabled:
+ return states
+
+ nloc_by_file = dict(
+ (
+ await session.execute(
+ select(HealthFileMetric.file_path, HealthFileMetric.nloc).where(
+ HealthFileMetric.repository_id == repository_id
+ )
+ )
+ ).all()
+ )
+ suggestions = performance_fix_suggestions(
+ opportunities,
+ nloc_by_file=nloc_by_file,
+ min_confidence=policy.min_confidence,
+ )
+ for suggestion in suggestions:
+ session.add(RefactoringSuggestion(**_refactoring_row_kwargs(suggestion, repository_id)))
+ states[suggestion.plan["opportunity_id"]] = "available"
+ await session.flush()
+ return states
+
+
+async def _reconcile_opportunities(
+ session: AsyncSession,
+ repository_id: str,
+ opportunities: list[OpportunityModel],
+ plan_states: dict[str, str],
+ analyzed_commit: str | None,
+) -> None:
+ """Update, insert, and resolve, in one pass over the stored rows."""
+ stored = {
+ (row.performance_model_version, row.opportunity_id): row
+ for row in (
+ await session.execute(
+ select(PerformanceOpportunity).where(
+ PerformanceOpportunity.repository_id == repository_id
+ )
+ )
+ )
+ .scalars()
+ .all()
+ }
+ seen: set[tuple[int, str]] = set()
+ now = _now_utc()
+ for position, item in enumerate(opportunities):
+ key = (item.performance_model_version, item.opportunity_id)
+ seen.add(key)
+ values = _row_kwargs(
+ item,
+ position=position,
+ plan_state=plan_states.get(item.opportunity_id, "no_safe_plan"),
+ analyzed_commit=analyzed_commit,
+ )
+ row = stored.get(key)
+ if row is None:
+ session.add(
+ PerformanceOpportunity(
+ id=_new_uuid(), repository_id=repository_id, **values
+ )
+ )
+ continue
+ for name, value in values.items():
+ setattr(row, name, value)
+ row.updated_at = now
+ for key, row in stored.items():
+ # A cause nobody observed this run, or one an older model minted, is
+ # resolved rather than removed: a held id must keep answering, and it
+ # must not keep reading as current.
+ if key not in seen and row.status != "resolved":
+ row.status = "resolved"
+ row.updated_at = now
+ await session.flush()
+
+
+async def _write_summary(
+ session: AsyncSession,
+ repository_id: str,
+ opportunities: list[OpportunityModel],
+ plan_states: dict[str, str],
+ analyzed_commit: str | None,
+) -> None:
+
+ from ....analysis.health.perf.opportunities import PERFORMANCE_MODEL_VERSION
+
+ payload = json.dumps(_summary_payload(opportunities, plan_states), separators=(",", ":"))
+ row = await session.get(PerformanceSummary, repository_id)
+ if row is None:
+ row = PerformanceSummary(repository_id=repository_id)
+ session.add(row)
+ row.performance_model_version = PERFORMANCE_MODEL_VERSION
+ row.opportunities_total = len(opportunities)
+ row.summary_json = payload
+ row.analyzed_commit = analyzed_commit
+ row.updated_at = _now_utc()
+ await session.flush()
+
+
+# ---------------------------------------------------------------------------
+# Indexed readers
+# ---------------------------------------------------------------------------
+
+
+async def get_performance_summary(
+ session: AsyncSession, repository_id: str
+) -> PerformanceSummary | None:
+ """The current headline, by primary key. One statement, no scan."""
+ return await session.get(PerformanceSummary, repository_id)
+
+
+async def get_performance_opportunity(
+ session: AsyncSession, repository_id: str, opportunity_id: str
+) -> PerformanceOpportunity | None:
+ """One materialized opportunity, current model or resolved older one."""
+ result = await session.execute(
+ select(PerformanceOpportunity)
+ .where(
+ PerformanceOpportunity.repository_id == repository_id,
+ PerformanceOpportunity.opportunity_id == opportunity_id,
+ )
+ .order_by(PerformanceOpportunity.performance_model_version.desc())
+ .limit(1)
+ )
+ return result.scalars().first()
+
+
+def _predicates(
+ repository_id: str,
+ *,
+ contexts: frozenset[str] | None,
+ boundary: str | None,
+ confidence: str | None,
+ actionability: str | None,
+ file_paths: tuple[str, ...] | None,
+) -> list[Any]:
+ where: list[Any] = [
+ PerformanceOpportunity.repository_id == repository_id,
+ PerformanceOpportunity.status == "open",
+ ]
+ 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 actionability is not None:
+ where.append(PerformanceOpportunity.actionability_state == actionability)
+ 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(
+ session: AsyncSession,
+ repository_id: str,
+ *,
+ contexts: frozenset[str] | None = None,
+ boundary: str | None = None,
+ confidence: str | None = None,
+ actionability: str | None = None,
+ file_paths: tuple[str, ...] | None = None,
+ sort: str = "rank",
+ limit: int = 20,
+ offset: int = 0,
+) -> tuple[list[PerformanceOpportunity], int]:
+ """One page in the requested order, plus the exact total behind it.
+
+ Both statements are index-driven and the fetched rows are the page, so cost
+ tracks the page rather than the repository.
+ """
+ where = _predicates(
+ repository_id,
+ contexts=contexts,
+ boundary=boundary,
+ confidence=confidence,
+ actionability=actionability,
+ file_paths=file_paths,
+ )
+ total = int(
+ (
+ await session.execute(
+ select(func.count()).select_from(PerformanceOpportunity).where(*where)
+ )
+ ).scalar_one()
+ )
+ rows = (
+ (
+ await session.execute(
+ select(PerformanceOpportunity)
+ .where(*where)
+ .order_by(*_ORDERS.get(sort, _ORDERS["rank"]))
+ .offset(offset)
+ .limit(limit)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ return list(rows), total
+
+
+async def performance_facet_counts(
+ session: AsyncSession,
+ repository_id: str,
+ *,
+ file_paths: tuple[str, ...] | None = None,
+) -> 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.
+ """
+ where = _predicates(
+ repository_id,
+ contexts=None,
+ boundary=None,
+ confidence=None,
+ actionability=None,
+ file_paths=file_paths,
+ )
+ 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,
+ )
+ )
+ return [tuple(row) for row in result.all()]
+
+
+async def get_performance_plan_rows(
+ session: AsyncSession, repository_id: str, opportunity_ids: list[str]
+) -> dict[str, RefactoringSuggestion]:
+ """The plans for one page of opportunities, in one indexed batch."""
+ if not opportunity_ids:
+ return {}
+ rows = (
+ (
+ await session.execute(
+ select(RefactoringSuggestion).where(
+ RefactoringSuggestion.repository_id == repository_id,
+ RefactoringSuggestion.refactoring_type == _PLAN_TYPE,
+ RefactoringSuggestion.opportunity_id.in_(opportunity_ids),
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ matches: dict[str, RefactoringSuggestion] = {}
+ for row in rows:
+ # The writer replaces every plan for the repository, so one per cause is
+ # what a store this writer produced holds. Choosing deterministically
+ # keeps a store an older writer left with two from returning a different
+ # plan on every read.
+ key = row.opportunity_id
+ if key and (key not in matches or row.id < matches[key].id):
+ matches[key] = row
+ return matches
+
+
+async def list_opportunity_evidence(
+ session: AsyncSession,
+ repository_id: str,
+ opportunity_id: str,
+ *,
+ limit: int = 8,
+ offset: int = 0,
+ total: int | None = None,
+) -> tuple[list[Any], int]:
+ """One page of the observations behind a cause, and their exact total.
+
+ A caller holding the opportunity row already knows the total, and it is the
+ same number over the same rows in the same transaction, so passing it in
+ saves a count.
+ """
+ where = [
+ HealthFinding.repository_id == repository_id,
+ HealthFinding.status == "open",
+ HealthFinding.dimension == "performance",
+ HealthFinding.opportunity_id == opportunity_id,
+ ]
+ if total is None:
+ total = int(
+ (
+ await session.execute(
+ select(func.count()).select_from(HealthFinding).where(*where)
+ )
+ ).scalar_one()
+ )
+ rows = (
+ await session.execute(
+ select(*_OBSERVATION_COLUMNS)
+ .where(*where)
+ .order_by(
+ HealthFinding.file_path.asc(),
+ HealthFinding.line_start.asc(),
+ HealthFinding.id.asc(),
+ )
+ .offset(offset)
+ .limit(limit)
+ )
+ ).all()
+ return list(rows), total
+
+
+async def list_evidence_for_opportunities(
+ session: AsyncSession,
+ repository_id: str,
+ opportunity_ids: list[str],
+ *,
+ per_opportunity: int = 3,
+) -> dict[str, list[Any]]:
+ """A few evidence rows for each opportunity on a page, in one statement.
+
+ Ranked inside the database rather than fetched and trimmed afterwards, so
+ a page containing one very large cause still reads a bounded number of
+ rows. Both supported backends implement the window function this uses.
+ """
+ if not opportunity_ids or per_opportunity <= 0:
+ return {}
+ ranked = (
+ select(
+ *_OBSERVATION_COLUMNS,
+ func.row_number()
+ .over(
+ partition_by=HealthFinding.opportunity_id,
+ order_by=(
+ HealthFinding.file_path.asc(),
+ HealthFinding.line_start.asc(),
+ HealthFinding.id.asc(),
+ ),
+ )
+ .label("position"),
+ )
+ .where(
+ HealthFinding.repository_id == repository_id,
+ HealthFinding.status == "open",
+ HealthFinding.dimension == "performance",
+ HealthFinding.opportunity_id.in_(opportunity_ids),
+ )
+ .subquery()
+ )
+ rows = (
+ await session.execute(select(ranked).where(ranked.c.position <= per_opportunity))
+ ).all()
+ grouped: dict[str, list[Any]] = {}
+ for row in sorted(rows, key=lambda item: item.position):
+ grouped.setdefault(row.opportunity_id, []).append(row)
+ return grouped
+
+
+async def get_health_finding_by_public_id(
+ session: AsyncSession, repository_id: str, public_id: str
+) -> HealthFinding | None:
+ """One finding by its quoted public id, through the index."""
+ result = await session.execute(
+ select(HealthFinding)
+ .where(
+ HealthFinding.repository_id == repository_id,
+ HealthFinding.public_id == public_id,
+ )
+ .limit(1)
+ )
+ return result.scalars().first()
+
+
+__all__ = [
+ "finalize_performance_opportunities",
+ "get_health_finding_by_public_id",
+ "get_performance_opportunity",
+ "get_performance_plan_rows",
+ "get_performance_summary",
+ "list_evidence_for_opportunities",
+ "list_opportunity_evidence",
+ "list_performance_opportunities",
+ "opportunity_details",
+ "performance_facet_counts",
+]
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py
index ae324511c..87b6c932b 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py
@@ -37,6 +37,17 @@ def _refactoring_row_kwargs(suggestion: Any, repository_id: str) -> dict:
if key in data:
data[f"{key}_json"] = json.dumps(data.pop(key) or {})
+ if data.get("refactoring_type") == "performance_fix":
+ # Lift the causal id out of the plan payload into its own column. Two
+ # surfaces used to answer "does this opportunity have a plan" by reading
+ # two different JSON fields, and one of them always said no.
+ try:
+ plan = json.loads(data.get("plan_json") or "{}")
+ except (TypeError, ValueError):
+ plan = {}
+ if isinstance(plan, dict) and isinstance(plan.get("opportunity_id"), str):
+ data.setdefault("opportunity_id", plan["opportunity_id"])
+
return {
"id": _new_uuid(),
"repository_id": repository_id,
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 89e25e880..c1039d582 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -1199,6 +1199,15 @@ class HealthFinding(Base):
# performance). Nullable + no backfill: old rows stay NULL until the next
# index recomputes them; new writes always set it (defaults to "defect").
dimension: Mapped[str | None] = mapped_column(String(16), nullable=True, default="defect")
+ # The finding's stable public identity, from
+ # ``analysis.health.finding_identity``. Stored so a quoted id resolves by
+ # index instead of by hashing every open row. Nullable while stores written
+ # before the column existed still carry NULL.
+ public_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+ # The causal performance opportunity this observation belongs to, on
+ # performance rows only. Also inside ``details_json``; the column is what
+ # makes "the evidence for this opportunity" an indexed seek.
+ opportunity_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
@@ -1207,15 +1216,24 @@ class HealthFinding(Base):
DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc
)
- # The table had no index at all, so every read full-scanned it. Two shapes
+ # The table had no index at all, so every read full-scanned it. Four shapes
# are served: a file-scoped lookup (``get_health`` with targets, the call an
- # agent makes to self-check a file before and after an edit) and a
- # repo-wide top-N ordered by impact. The first index turns the scan into a
- # seek; the second lets the ranked read stop early instead of sorting the
- # whole table into a temp B-tree.
+ # agent makes to self-check a file before and after an edit), a repo-wide
+ # top-N ordered by impact, a quoted public id, and the evidence for one
+ # causal opportunity. The first turns the scan into a seek; the second lets
+ # the ranked read stop early instead of sorting the whole table into a temp
+ # B-tree; the last two keep drill-down proportional to the page.
__table_args__ = (
Index("ix_health_findings_repo_status_path", "repository_id", "status", "file_path"),
Index("ix_health_findings_repo_status_impact", "repository_id", "status", "health_impact"),
+ Index("ix_health_findings_repo_public_id", "repository_id", "public_id"),
+ Index(
+ "ix_health_findings_repo_status_dimension_opportunity",
+ "repository_id",
+ "status",
+ "dimension",
+ "opportunity_id",
+ ),
)
@@ -1248,6 +1266,12 @@ class RefactoringSuggestion(Base):
blast_radius_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
confidence: Mapped[str] = mapped_column(String(16), nullable=False, default="medium")
source_biomarker: Mapped[str] = mapped_column(String(64), nullable=False, default="")
+ # The performance opportunity this plan addresses, on ``performance_fix``
+ # rows only. The id also sits inside ``plan_json``; the column is the
+ # repository-scoped link the queue joins on, so linking a page of
+ # opportunities to their plans is one indexed batch rather than a scan of
+ # every plan's JSON.
+ opportunity_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
@@ -1256,6 +1280,133 @@ class RefactoringSuggestion(Base):
DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc
)
+ __table_args__ = (
+ Index(
+ "ix_refactoring_suggestions_repo_type_opportunity",
+ "repository_id",
+ "refactoring_type",
+ "opportunity_id",
+ ),
+ )
+
+
+class PerformanceOpportunity(Base):
+ """One causal performance opportunity, materialized for serving.
+
+ The queue used to be rebuilt from every open performance finding on every
+ request, so a page of twenty cost the whole repository. Grouping happens
+ once, when findings are persisted, and lands here; a page is then an
+ indexed range scan.
+
+ Filter, order, and identity live in columns because SQLite and PostgreSQL
+ both index those and neither indexes a JSON predicate portably. Everything
+ explanatory - facets, rank factors, why-ranked, prerequisites, path suffix -
+ stays in ``details_json``, where a new fact costs no migration.
+ """
+
+ __tablename__ = "performance_opportunities"
+
+ id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)
+ repository_id: Mapped[str] = mapped_column(
+ String(32), ForeignKey("repositories.id", ondelete="CASCADE"), nullable=False
+ )
+ # Public causal id, ``perf<model>_<digest>``. Unique per repository *and*
+ # model version, never globally: the same cause in two repositories is two
+ # rows, and two model versions disagree about membership by construction.
+ opportunity_id: Mapped[str] = mapped_column(String(64), nullable=False)
+ performance_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ # ``open`` or ``resolved``. A cause that stops being observed is resolved,
+ # not deleted, so a quoted id keeps answering after the code was fixed.
+ status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")
+ # Position in the deterministic total order, so the queue reads in rank
+ # order from an index rather than sorting the repository per request.
+ rank_position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ rank_score: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ execution_context: Mapped[str] = mapped_column(String(16), nullable=False, default="unknown")
+ boundary_kind: Mapped[str | None] = mapped_column(String(32), nullable=True)
+ biomarker_type: Mapped[str] = mapped_column(String(64), nullable=False, default="")
+ actionability_state: Mapped[str] = mapped_column(String(16), nullable=False, default="investigate")
+ evidence_confidence: Mapped[str] = mapped_column(String(16), nullable=False, default="low")
+ # ``available`` | ``no_safe_plan`` | ``not_persisted``, decided once by the
+ # writer that also decides whether a plan row exists.
+ plan_state: Mapped[str] = mapped_column(String(16), nullable=False, default="no_safe_plan")
+ fix_strategy: Mapped[str | None] = mapped_column(String(64), nullable=True)
+ fix_safety: Mapped[str | None] = mapped_column(String(16), nullable=True)
+ # The file holding the symbol worth editing, so target scoping is a column.
+ file_path: Mapped[str] = mapped_column(Text, nullable=False, default="")
+ intervention_symbol: Mapped[str | None] = mapped_column(Text, nullable=True)
+ terminal_sink: Mapped[str | None] = mapped_column(Text, nullable=True)
+ observations_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ affected_call_sites_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ affected_files_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ details_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
+ analyzed_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)
+ created_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False, default=_now_utc
+ )
+ updated_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc
+ )
+
+ __table_args__ = (
+ UniqueConstraint(
+ "repository_id",
+ "performance_model_version",
+ "opportunity_id",
+ name="uq_performance_opportunities_repo_model_id",
+ ),
+ Index("ix_performance_opportunities_repo_id", "repository_id", "opportunity_id"),
+ Index(
+ "ix_performance_opportunities_repo_status_rank",
+ "repository_id",
+ "status",
+ "rank_position",
+ ),
+ Index(
+ "ix_performance_opportunities_repo_status_context_rank",
+ "repository_id",
+ "status",
+ "execution_context",
+ "rank_position",
+ ),
+ Index(
+ "ix_performance_opportunities_repo_status_action_rank",
+ "repository_id",
+ "status",
+ "actionability_state",
+ "rank_position",
+ ),
+ Index("ix_performance_opportunities_repo_status_path", "repository_id", "status", "file_path"),
+ )
+
+
+class PerformanceSummary(Base):
+ """The current performance headline for one repository, in one row.
+
+ A bare dashboard call must be able to lead with something actionable
+ without touching the queue, so the lead and the counts are written by the
+ same transaction that materializes the opportunities and read back by
+ primary key. One row per repository: this is the *current* state, not
+ history, and must never be served from a trend snapshot.
+ """
+
+ __tablename__ = "performance_summaries"
+
+ repository_id: Mapped[str] = mapped_column(
+ String(32),
+ ForeignKey("repositories.id", ondelete="CASCADE"),
+ primary_key=True,
+ )
+ performance_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ opportunities_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ # Counts, context split, and the single lead. Read whole or not at all, so
+ # there is nothing to filter on and no reason to spend columns.
+ summary_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
+ analyzed_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)
+ updated_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc
+ )
+
class HealthFileMetric(Base):
"""Per-file aggregate metrics + final score."""
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index b0e646d88..9f7a89051 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -938,6 +938,7 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non
and metrics across an incremental ``repowise update``.
"""
from repowise.core.persistence.crud import (
+ finalize_performance_opportunities,
upsert_health_findings,
upsert_health_metrics,
upsert_refactoring_suggestions,
@@ -952,54 +953,55 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non
)
if not changed_paths and not performance_paths:
return
- if changed_paths:
- await upsert_health_metrics(
- session,
- repo_id,
- report.metrics or [],
- analyzed_commit=await _analyzed_commit(session, repo_id),
- )
- await upsert_health_findings(
- session, repo_id, list(report.findings or []), file_paths=changed_paths
- )
- if performance_paths:
- await upsert_health_findings(
- session,
- repo_id,
- list(report.findings or []),
- file_paths=performance_paths,
- dimension="performance",
- )
- # Refactoring suggestions for the changed files only (unchanged files keep
- # theirs). Scoped delete-then-insert across the full changed-file set, so a
- # file that became clean has its stale suggestions removed.
- if changed_paths:
- await upsert_refactoring_suggestions(
- session,
- repo_id,
- list(getattr(report, "refactoring_suggestions", None) or []),
- file_paths=changed_paths,
- )
- if performance_paths:
- performance_suggestions = [
- suggestion
- for suggestion in list(getattr(report, "refactoring_suggestions", None) or [])
- if suggestion.refactoring_type == "performance_fix"
- ]
- # A causal plan is stored at its shared intervention, which can sit
- # downstream of every caller file in the performance invalidation
- # closure. Include those targets in the scoped replacement or the
- # findings refresh while their matching plans are silently discarded.
- performance_plan_paths = sorted(
- set(performance_paths)
- | {suggestion.file_path for suggestion in performance_suggestions}
- )
- await upsert_refactoring_suggestions(
+ analyzed_commit = await _analyzed_commit(session, repo_id)
+ # One savepoint over the findings and everything derived from them. This
+ # writer's caller logs a failed step and carries on to commit the rest of
+ # the run, so without the savepoint a rebuild that failed halfway would
+ # leave the queue describing findings that were never stored.
+ async with session.begin_nested():
+ if changed_paths:
+ await upsert_health_metrics(
+ session,
+ repo_id,
+ report.metrics or [],
+ analyzed_commit=analyzed_commit,
+ )
+ await upsert_health_findings(
+ session, repo_id, list(report.findings or []), file_paths=changed_paths
+ )
+ if performance_paths:
+ await upsert_health_findings(
+ session,
+ repo_id,
+ list(report.findings or []),
+ file_paths=performance_paths,
+ dimension="performance",
+ )
+ # Refactoring suggestions for the changed files only (unchanged files
+ # keep theirs). Scoped delete-then-insert across the full changed-file
+ # set, so a file that became clean has its stale suggestions removed.
+ if changed_paths:
+ await upsert_refactoring_suggestions(
+ session,
+ repo_id,
+ [
+ suggestion
+ for suggestion in (getattr(report, "refactoring_suggestions", None) or [])
+ if suggestion.refactoring_type != "performance_fix"
+ ],
+ file_paths=changed_paths,
+ )
+ # A partial run sees a subset of the findings, so the plans and the
+ # queue it would derive are a subset too. Both are rebuilt here instead,
+ # from the merged stored rows, by the same writer the full path uses.
+ # That is what makes the two paths agree, and it retires the file-scoped
+ # plan bookkeeping that used to try to reach a shared intervention from
+ # its callers.
+ await finalize_performance_opportunities(
session,
repo_id,
- performance_suggestions,
- file_paths=performance_plan_paths,
- refactoring_type="performance_fix",
+ analyzed_commit=analyzed_commit,
+ plan_policy=getattr(report, "performance_plan_policy", None),
)
# Per-function blame rollup for the changed files (keeps git_function_blame
# current between full indexes; FULL git tier only — empty otherwise).
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index f8ce2e64d..47f11235a 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1512,6 +1512,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
from repowise.core.analysis.health.trends import snapshot_file_maps
from repowise.core.persistence.crud import (
bulk_upsert_decisions,
+ finalize_performance_opportunities,
recompute_decision_staleness,
save_coverage_files,
save_dead_code_findings,
@@ -1534,8 +1535,35 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
# index instead of assuming the two moved together.
head_sha = getattr(result, "head_commit", None) or getattr(result, "commit_sha", None)
await save_health_metrics(session, repo_id, hr.metrics or [], analyzed_commit=head_sha)
- if hr.findings:
- await save_health_findings(session, repo_id, hr.findings)
+ # One savepoint over the findings and everything derived from them, so
+ # a rebuild that failed halfway cannot leave the queue describing
+ # findings that were never stored. It runs on an empty finding set too:
+ # the queue has to be reconciled to nothing just the same.
+ async with session.begin_nested():
+ if hr.findings:
+ await save_health_findings(session, repo_id, hr.findings)
+ # Structured refactoring suggestions (Extract Class, ...). Repo-wide
+ # delete-then-insert like findings; empty list clears prior rows.
+ # Performance plans are excluded: the finalizer below owns them, so
+ # they are generated once, from the merged stored findings, by the
+ # same writer on the full and the incremental path.
+ await save_refactoring_suggestions(
+ session,
+ repo_id,
+ [
+ suggestion
+ for suggestion in (getattr(hr, "refactoring_suggestions", None) or [])
+ if getattr(suggestion, "refactoring_type", None) != "performance_fix"
+ ],
+ )
+ # Group the stored performance findings into the materialized causal
+ # read model, then reconcile lifecycle and plans.
+ await finalize_performance_opportunities(
+ session,
+ repo_id,
+ analyzed_commit=head_sha,
+ plan_policy=getattr(hr, "performance_plan_policy", None),
+ )
# Resolved coverage rows, when a report was ingested this run.
coverage_files = getattr(hr, "coverage_files", None)
if coverage_files:
@@ -1546,11 +1574,6 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
source_format=getattr(hr, "coverage_format", None) or "lcov",
ingested_commit_sha=head_sha,
)
- # Structured refactoring suggestions (Extract Class, ...). Repo-wide
- # delete-then-insert like findings; empty list clears prior rows.
- await save_refactoring_suggestions(
- session, repo_id, getattr(hr, "refactoring_suggestions", None) or []
- )
# Per-function blame rollup (FULL tier only; empty otherwise).
fn_blame_rows = getattr(hr, "function_blame_rows", None)
if fn_blame_rows:
diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
index c15cf2be1..a15d59890 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
@@ -178,12 +178,19 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"metrics[]",
"refactoring_plans[]",
"performance_opportunities[]",
+ "performance_summary",
"high_leverage_files[]",
"secondary_rankings",
),
protected=(
"mode",
"directive",
+ # The performance lead is bounded by construction and is the only
+ # actionable performance content a bare dashboard carries, so
+ # shedding it would leave the pillar with counts and nothing to do.
+ "performance_directive",
+ "opportunity_id",
+ "model_state",
"targets",
"unresolved",
"known_modules",
diff --git a/packages/server/src/repowise/server/mcp_server/_references.py b/packages/server/src/repowise/server/mcp_server/_references.py
index bc1d5ac03..a6bff398a 100644
--- a/packages/server/src/repowise/server/mcp_server/_references.py
+++ b/packages/server/src/repowise/server/mcp_server/_references.py
@@ -125,6 +125,35 @@ def stable_entity_id(prefix: str, repository: str, coordinates: Mapping[str, obj
return f"{prefix}_{content_id(identity)}"
+def refactoring_plan_id(suggestion: Any, repository: str) -> str:
+ """Return the public ID for one refactoring plan, ORM row or dataclass.
+
+ Lives here rather than beside one caller because two surfaces address the
+ same plan and must arrive at the same string.
+ """
+
+ raw_plan = getattr(suggestion, "plan", None)
+ if raw_plan is None:
+ raw_plan = getattr(suggestion, "plan_json", None) or "{}"
+ try:
+ raw_plan = json.loads(raw_plan)
+ except (TypeError, json.JSONDecodeError):
+ raw_plan = str(raw_plan)
+ return stable_entity_id(
+ "plan",
+ repository,
+ {
+ "path": path_identity(suggestion.file_path),
+ "kind": suggestion.refactoring_type,
+ "symbol": suggestion.target_symbol or "",
+ "line_start": suggestion.line_start,
+ "line_end": suggestion.line_end,
+ "source_biomarker": suggestion.source_biomarker or "",
+ "plan": raw_plan,
+ },
+ )
+
+
# Compatibility aliases for the get_why-specific module that originally
# owned these primitives. Keeping the private spellings prevents a mechanical
# promotion from changing sealed evidence identities or downstream imports.
@@ -138,6 +167,7 @@ __all__ = [
"content_id",
"omission_reference",
"path_identity",
+ "refactoring_plan_id",
"reference",
"repository_identity",
"source_reference",
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.py
index 94e37f6fa..1cb824927 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import hashlib
import json
-from dataclasses import asdict
+from dataclasses import asdict, dataclass, field
from pathlib import Path
from time import perf_counter
from typing import Any
@@ -16,10 +16,11 @@ from repowise.core.analysis.health.churn_complexity import churn_complexity_poin
from repowise.core.analysis.health.complexity.languages import LANGUAGE_MAPS
from repowise.core.analysis.health.coverage import decay_since, measurement_ref
from repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy
+from repowise.core.analysis.health.finding_identity import finding_public_id
from repowise.core.analysis.health.grading import HEALTHY_MIN, band_for
from repowise.core.analysis.health.grading import distribution as health_distribution
from repowise.core.analysis.health.perf.coverage import PerfCoverage, coverage_for_metrics
-from repowise.core.analysis.health.perf.opportunities import build_performance_opportunities
+from repowise.core.analysis.health.perf.opportunity_rank import observation_rank
from repowise.core.analysis.health.refactoring.recommendations import (
Recommendation,
build_recommendations,
@@ -36,6 +37,7 @@ from repowise.core.persistence.crud import (
get_coverage_summary,
get_file_language_map,
get_git_metadata_bulk,
+ get_health_finding_by_public_id,
get_hotspot_file_paths,
get_node_degree_counts_bulk,
get_refactoring_suggestions,
@@ -60,106 +62,226 @@ from repowise.server.mcp_server._helpers import (
filter_rows_by_attr,
)
from repowise.server.mcp_server._meta import build_meta as _build_meta
-from repowise.server.mcp_server._references import path_identity, stable_entity_id
-
-# How much a single execution of each I/O boundary costs, as an order of
-# magnitude rather than a measurement: a process spawn is milliseconds, a wire
-# round-trip is hundreds of microseconds up, a pooled local query is tens, and a
-# filesystem call is usually a page-cache hit. "A subprocess spawn in a loop is
-# not a filesystem stat in a loop" is the whole point of ranking on this.
-_PERF_BOUNDARY_POINTS = {"subprocess": 4, "network": 3, "db": 2, "lock": 2, "filesystem": 1}
-
-# What the marker itself proves about *how often* the boundary cost is paid.
-# Two independent proofs, and neither dominates — which is why the three signals
-# are added rather than multiplied:
-#
-# * a **multiplier** — the cost repeats per iteration (N), per nested pair
-# (N x M), or quadratically. Every ``*_in_loop`` marker carries this.
-# * **hotness** — the cost is paid on a request-reachable path.
-# ``hot_path_sync_io`` and ``nested_loop_quadratic`` are the request-
-# reachability signal, and it needs no new column: both are emitted **only**
-# for a function ``perf.ranking.PerfRanker`` called hot (top-quintile
-# call-graph in-degree, or a churny/hotspot file), so their presence is
-# already a proof. ``blocking_io_under_lock`` proves something adjacent —
-# every thread serializes behind the wait.
-#
-# ``hot_path_sync_io`` therefore sits level with a plain loop marker, not above
-# it: it proves hotness and no multiplier, and a loop proves a multiplier and no
-# hotness. Boundary kind is what separates them in practice.
-#
-# Deliberately not ``severity``: the column disagrees with this ordering and
-# cannot be fixed from here without a re-score. ``hot_path_sync_io`` is written
-# ``LOW`` and ``io_in_loop`` ``MEDIUM``, so the marker carrying a hotness proof
-# is graded *below* the ungated one — and on this repo severity takes exactly
-# two values across all 697 perf findings (522 medium, 175 low), which is not
-# an ordering.
-#
-# Exhaustive over the 20 detectors declaring ``category = "performance"``;
-# ``test_perf_rank.py`` fails if a new one is added without a weight, so the
-# default below is a guard rather than a resting place.
-_PERF_MARKER_POINTS = {
- # Superlinear, and gated on hotness.
- "nested_loop_quadratic": 5,
- # N x M round-trips, or a wait every thread queues behind.
- "nested_loop_with_io": 4,
- "blocking_io_under_lock": 4,
- "sql_cartesian_join": 4,
- # One boundary crossing per iteration — the N+1 family.
- "io_in_loop": 3,
- "serial_await_in_loop": 3,
- "lock_in_loop": 3,
- "goroutine_in_unbounded_loop": 3,
- "resource_construction_in_loop": 3,
- # One crossing, but proven to sit on a hot path.
- "hot_path_sync_io": 3,
- # In-loop CPU/allocation costs: real, and orders below a round-trip.
- "blocking_sync_in_async": 2,
- "pandas_iterrows_in_loop": 2,
- "pd_concat_in_loop": 2,
- "json_parse_in_loop": 2,
- "array_spread_in_reduce": 2,
- "defer_in_loop": 2,
- "regex_compile_in_loop": 1,
- "string_concat_in_loop": 1,
- "membership_test_against_list_in_loop": 1,
- "list_insert_zero_in_loop": 1,
-}
+from repowise.server.mcp_server._references import (
+ path_identity,
+ refactoring_plan_id,
+ stable_entity_id,
+)
+from repowise.server.services.performance_health import (
+ PerformanceHealthService,
+ PerformancePage,
+ evidence_block,
+ parse_query,
+)
+
+_PERFORMANCE_COLLECTION_CAP = 6
+"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""
+
+_PERFORMANCE_EVIDENCE_CAP = 3
+"""Evidence rows per opportunity in the collection. The detail call pages more."""
+
+_PERFORMANCE_EVIDENCE_PAGE_CAP = 20
+"""Ceiling on one evidence page. ``limit`` still means what it says below it,
+including ``limit=0`` for the totals and no rows."""
+
+
+def _selector_conflict(**selectors: str | None) -> dict[str, Any] | None:
+ """Refuse two detail selectors instead of answering about one of them.
+
+ Preferring whichever was checked first gave a caller a confident answer to
+ a question they had not only asked, with no sign the other was dropped.
+ """
+ named = sorted(name for name, value in selectors.items() if value)
+ if len(named) < 2:
+ return None
+ return {
+ "mode": "conflict",
+ "resolved": False,
+ "reason": "mutually_exclusive_selectors",
+ "selectors": named,
+ "detail": "Pass exactly one of finding_id, plan_id, opportunity_id.",
+ }
+
+
+@dataclass(frozen=True, slots=True)
+class _PerformanceBlocks:
+ """Everything the performance pillar contributes to one response."""
+
+ page: PerformancePage | None = None
+ summary: dict[str, Any] | None = None
+ directive: dict[str, Any] | None = None
+ ignored: dict[str, str] = field(default_factory=dict)
+
+
+async def _performance_blocks(
+ service: PerformanceHealthService,
+ *,
+ wants: Any,
+ included: bool,
+ file_paths: tuple[str, ...] | None,
+ scoped: bool,
+ limit: int,
+ cursor: int,
+ view: str | None,
+ context: str | None,
+ boundary: str | None,
+ confidence: str | None,
+ sort: str | None,
+) -> _PerformanceBlocks:
+ """Read the materialized queue, its rollup, and the dashboard lead.
+
+ Each block is gated on surviving the projection, so a caller that asked for
+ one of the three does not pay for the other two.
+ """
+ page = None
+ ignored: dict[str, str] = {}
+ if included:
+ # The lede quotes only the first row and no evidence, so a projection
+ # down to it reads one row rather than a page of six.
+ emits_queue = wants("performance_opportunities")
+ query, ignored = parse_query(
+ context=context,
+ boundary=boundary,
+ confidence=confidence,
+ view=view,
+ sort=sort,
+ file_paths=file_paths,
+ limit=min(max(limit, 0), _PERFORMANCE_COLLECTION_CAP) if emits_queue else 1,
+ offset=cursor if emits_queue else 0,
+ )
+ page = await service.page(
+ query,
+ evidence_per_item=_PERFORMANCE_EVIDENCE_CAP if emits_queue else 0,
+ # Facets are rendered by the summary block alone, so a queue or a
+ # lede does not pay for the aggregate.
+ with_facets=wants("performance_summary"),
+ )
+ return _PerformanceBlocks(
+ page=page,
+ summary=await service.summary() if included and wants("performance_summary") else None,
+ # The bare dashboard lead: one primary-key read of the current summary
+ # row, so it does not grow with the repository and never touches the
+ # queue.
+ directive=(
+ await service.directive() if not scoped and wants("performance_directive") else None
+ ),
+ ignored=ignored,
+ )
+
+
+async def _resolve_finding(
+ session: Any, repository_id: str, finding_id: str, repository: str
+) -> Any:
+ """Find one health finding by any id form a caller can be holding.
+
+ The public id is a column, so the common case is a seek. The scan is the
+ compatibility path: a raw storage id, or an id minted before the column
+ existed, still has to resolve.
+ """
+ match = await get_health_finding_by_public_id(session, repository_id, finding_id)
+ if match is not None:
+ return match
+ rows = (
+ (
+ await session.execute(
+ select(HealthFinding).where(
+ HealthFinding.repository_id == repository_id,
+ HealthFinding.status == "open",
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ return next(
+ (
+ row
+ for row in rows
+ if finding_id
+ in {
+ row.id,
+ _health_finding_id(row, repository),
+ _legacy_health_finding_id(row, repository),
+ }
+ ),
+ None,
+ )
-# Unknown marker. Deliberately the floor, not the middle: a detector added
-# without a weight should under-rank rather than jump the queue, the same
-# degrade-to-no-signal direction the perf gate itself takes.
-_PERF_UNKNOWN_MARKER_POINTS = 1
-# A hit whose loop and whose sink are in different functions. Worth a point on
-# its own: an intra-function loop is often visibly bounded at the call site,
-# while a cross-function N+1 is the one nobody sees by reading the loop.
-_PERF_CROSSFN_POINTS = 1
+async def _performance_detail_response(
+ session: Any,
+ repository: Any,
+ reference_repository: str,
+ opportunity_id: str,
+ *,
+ evidence_only: bool,
+ limit: int,
+ cursor: int,
+) -> dict[str, Any]:
+ """One causal opportunity, or one page of the evidence behind it.
+
+ ``limit`` means what it means everywhere else, ``0`` included: reading it
+ as "unset" would return a page the caller declined.
+ """
+ service = PerformanceHealthService(session, repository.id, reference_repository)
+ evidence_limit = min(max(limit, 0), _PERFORMANCE_EVIDENCE_PAGE_CAP)
+ if evidence_only:
+ rows, total = await service.evidence(
+ opportunity_id, limit=evidence_limit, offset=cursor
+ )
+ return {
+ "mode": "performance_evidence",
+ "opportunity_id": opportunity_id,
+ "resolved": total > 0,
+ **evidence_block(rows, total, cursor),
+ "_meta": _build_meta(repository=repository),
+ }
+ detail = await service.detail(opportunity_id, evidence_limit=evidence_limit)
+ file_path = detail.get("file_path")
+ result = {
+ "mode": "performance_opportunity",
+ **detail,
+ "_meta": _build_meta(
+ repository=repository, targets=[file_path] if file_path else None
+ ),
+ }
+ metric_rows = (
+ list(
+ (
+ await session.execute(
+ select(HealthFileMetric).where(
+ HealthFileMetric.repository_id == repository.id,
+ HealthFileMetric.file_path == file_path,
+ )
+ )
+ ).scalars()
+ )
+ if file_path
+ else []
+ )
+ _attach_health_analysis_meta(result["_meta"], metric_rows)
+ return result
def _perf_rank(biomarker_type: str | None, details: Any) -> int:
- """Order-of-magnitude ranking key for one ``performance`` finding.
-
- The performance dimension had none. Every finding carries
- ``health_impact: 0`` by construction — the dimension is deliberately never
- blended into the score — so the list came back in whatever order the impact
- tie broke, which is file order. "Which of these 697 matters" was
- unanswerable from the payload, and worse, the *cap* was arbitrary too: with
- ``include=['performance']`` the head is 20 of 697 chosen by nothing.
-
- Additive over three signals the payload already carries, in points rather
- than a calibrated scale, because it is an **ordering key and not a score**.
- Nothing here is blended into ``score`` / ``performance_score``, and nothing
- here was fitted against the defect corpus — the frozen weights this file
- documents stay frozen. A caller who disagrees can re-rank: every input is in
+ """Order-of-magnitude ordering key for one ``performance`` finding.
+
+ Every performance finding carries ``health_impact: 0`` by construction, so
+ without a key the list came back in file order and "which of these matters"
+ was unanswerable from the payload.
+
+ The weights live with the opportunity ranking rather than here. Two tables
+ used to answer "which marker costs more" and they had already drifted apart
+ on markers both named, so a finding and the opportunity built from it could
+ disagree about the same evidence. Nothing here is blended into ``score`` or
+ ``performance_score``; a caller who disagrees can re-rank from
``biomarker_type`` and ``details`` on the same row.
"""
if not isinstance(details, dict):
details = {}
- points = _PERF_MARKER_POINTS.get(biomarker_type or "", _PERF_UNKNOWN_MARKER_POINTS)
- points += _PERF_BOUNDARY_POINTS.get(details.get("boundary_kind") or "", 0)
- if details.get("cross_function"):
- points += _PERF_CROSSFN_POINTS
- return points
+ return observation_rank(
+ biomarker_type, details.get("boundary_kind"), bool(details.get("cross_function"))
+ )
def _rank_emitted(rows: list[Any]) -> list[Any]:
@@ -200,7 +322,23 @@ def _rank_emitted(rows: list[Any]) -> list[Any]:
return sorted(rows, key=key)
-def _health_finding_id(f: HealthFinding, repository: str) -> str:
+def _health_finding_id(f: Any, repository: str) -> str:
+ """The finding's public id: the stored one, else the same kernel recomputed.
+
+ Storage row ids are republished on every analysis, so they cannot be quoted
+ back. This is the id evidence carries and the ``finding_id`` selector
+ resolves, and it is a column, so resolving it is a seek.
+ """
+ stored = getattr(f, "public_id", None)
+ return stored if isinstance(stored, str) and stored else finding_public_id(f)
+
+
+def _legacy_health_finding_id(f: Any, repository: str) -> str:
+ """The pre-column id form, still accepted so a quoted one keeps resolving.
+
+ Its kernel held generated prose and derived detail keys, so it moved
+ whenever a detector reworded itself or a later model changed its mind.
+ """
try:
details = json.loads(f.details_json) if f.details_json else {}
except (TypeError, json.JSONDecodeError):
@@ -254,27 +392,8 @@ def _serialize_finding(f: HealthFinding, repository: str = "default") -> dict[st
def _refactoring_plan_id(r: Any, repository: str) -> str:
- suggestion = r.suggestion if isinstance(r, Recommendation) else r
- raw_plan = getattr(suggestion, "plan", None)
- if raw_plan is None:
- raw_plan = getattr(suggestion, "plan_json", None) or "{}"
- try:
- raw_plan = json.loads(raw_plan)
- except (TypeError, json.JSONDecodeError):
- raw_plan = str(raw_plan)
- return stable_entity_id(
- "plan",
- repository,
- {
- "path": path_identity(suggestion.file_path),
- "kind": suggestion.refactoring_type,
- "symbol": suggestion.target_symbol or "",
- "line_start": suggestion.line_start,
- "line_end": suggestion.line_end,
- "source_biomarker": suggestion.source_biomarker or "",
- "plan": raw_plan,
- },
- )
+ """Unwrap a hydrated recommendation, then defer to the identity owner."""
+ return refactoring_plan_id(r.suggestion if isinstance(r, Recommendation) else r, repository)
def _serialize_refactoring(
@@ -1083,6 +1202,22 @@ def _compute_kpis(
'only=["performance_opportunities","refactoring_plans"])',
("get_health",),
),
+ ToolRecipe(
+ "health_performance_summary",
+ 'get_health(include=["performance"], only=["performance_summary"])',
+ ("get_health",),
+ ),
+ ToolRecipe(
+ "health_performance_opportunity",
+ 'get_health(opportunity_id="perf...")',
+ ("get_health",),
+ ),
+ ToolRecipe(
+ "health_performance_evidence",
+ 'get_health(opportunity_id="perf...", '
+ 'only=["performance_evidence"], cursor=0)',
+ ("get_health",),
+ ),
),
)
async def get_health(
@@ -1095,36 +1230,49 @@ async def get_health(
cursor: int = 0,
finding_id: str | None = None,
plan_id: str | None = None,
+ opportunity_id: str | None = None,
+ performance_view: str | None = None,
+ performance_context: str | None = None,
+ performance_boundary: str | None = None,
+ performance_confidence: str | None = None,
+ performance_sort: str | None = None,
) -> dict:
"""Code-health scores and findings from stored analysis.
No ``targets`` returns a dashboard; targets return ranked files and findings.
- This verifies Git/index facts but never recomputes health. For comparisons,
- commit health changes then run ``repowise update``; it ignores uncommitted edits.
+ Never recomputes health: commit changes, then run ``repowise update``.
+ Every block and accepted value: docs/agent/MCP_TOOLS.md.
Args:
- targets: file paths or ``module:<name>``. Empty → dashboard. Unmatched
- targets appear in ``unresolved`` and survive any ``only``.
+ targets: file paths or ``module:<name>``. Empty means dashboard;
+ unmatched ones appear in ``unresolved``, surviving any ``only``.
include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |
- ``accuracy`` | ``signals`` | ``churn_complexity`` |
- ``performance``/``defect``/``maintainability`` (dimension).
- ``performance`` adds causal opportunities; with ``refactoring``,
- a compact recommendation lede. Pair with ``only`` to project.
- only: top-level keys to keep; identity, counts, unresolved targets,
- and recovery metadata survive. ``biomarkers``, ``accuracy``, and
- ``refactoring`` alias; ``performance``, ``defect``, and
- ``maintainability`` do not.
+ ``accuracy`` | ``signals`` | ``churn_complexity``, or one dimension
+ name. ``performance`` also adds the opportunity queue.
+ only: keys to keep; identity, counts and recovery survive.
+ ``biomarkers``, ``accuracy`` and ``refactoring`` alias their block
+ key. ``performance``, ``defect`` and ``maintainability`` do not:
+ they filter rows and land in ``unknown_only_keys``.
repo: usually omitted.
- limit: max rows per ranked list (``0`` for none). Performance
- opportunities and refactoring plans have independent caps of 6;
- performance evidence is capped at 3 rows per opportunity.
- refactoring_view: ``canonical`` (default) or diversified
- ``file_spread``.
- cursor: zero-based offset for top-level ranked collections.
+ limit: max rows per ranked list, ``0`` for none.
+ refactoring_view: ``canonical`` (default) or ``file_spread``.
+ cursor: zero-based offset for ranked collections.
finding_id: stable ``id`` emitted by a health finding.
plan_id: stable ``id`` emitted by a refactoring plan.
+ opportunity_id: ``perf...`` id from ``performance_directive`` or the
+ queue: the cause, its plan or why there is none, and evidence,
+ which ``only=["performance_evidence"]`` plus ``cursor`` pages.
+ Excludes the two ids above.
+ performance_view / _context / _boundary / _confidence / _sort: queue
+ projection and filters; the facets list their values.
+
"""
started = perf_counter()
+ conflict = _selector_conflict(
+ finding_id=finding_id, plan_id=plan_id, opportunity_id=opportunity_id
+ )
+ if conflict is not None:
+ return conflict
# ``0`` means none, matching the ``module_limit`` convention on the REST
# coverage route. It used to clamp up to 1, so the documented way to ask for
# "the totals, none of the rows" silently returned a row.
@@ -1170,8 +1318,10 @@ async def get_health(
# block that carries findings survives the projection.
wants_findings = wants("findings") or wants("top_findings")
wants_test_findings = wants("test_findings")
- wants_performance_opportunities = wants("performance_opportunities") or wants(
- "recommendation_lede"
+ wants_performance_opportunities = (
+ wants("performance_opportunities")
+ or wants("recommendation_lede")
+ or wants("performance_summary")
)
# Everything downstream of the test/production split, in one place.
#
@@ -1219,6 +1369,7 @@ async def get_health(
"coverage.files",
"refactoring_plans",
"performance_opportunities",
+ "performance_evidence",
}
def bounded(rows: list[Any], label: str, *, cap: int | None = None) -> list[Any]:
@@ -1256,25 +1407,8 @@ async def get_health(
reference_repository = ctx.alias or repository.name
if finding_id:
- rows = list(
- (
- await session.execute(
- select(HealthFinding).where(
- HealthFinding.repository_id == repository.id,
- HealthFinding.status == "open",
- )
- )
- )
- .scalars()
- .all()
- )
- match = next(
- (
- row
- for row in rows
- if finding_id in {row.id, _health_finding_id(row, reference_repository)}
- ),
- None,
+ match = await _resolve_finding(
+ session, repository.id, finding_id, reference_repository
)
result = {
"mode": "finding",
@@ -1305,6 +1439,17 @@ async def get_health(
_attach_health_analysis_meta(result["_meta"], metric_rows)
return result
+ if opportunity_id:
+ return await _performance_detail_response(
+ session,
+ repository,
+ reference_repository,
+ opportunity_id,
+ evidence_only=only_set == {"performance_evidence"},
+ limit=limit,
+ cursor=cursor,
+ )
+
if plan_id:
plan_rows = await get_refactoring_suggestions(session, repository.id)
recommendations = await hydrate_recommendations(
@@ -1648,6 +1793,27 @@ async def get_health(
view=refactoring_view, # type: ignore[arg-type]
)
+ # The materialized causal read model. Filtering, ordering, paging, plan
+ # linkage, and facets are the shared service's; this tool caps the
+ # collection, pages it, and serializes what comes back.
+ performance_service = PerformanceHealthService(
+ session, repository.id, reference_repository
+ )
+ performance = await _performance_blocks(
+ performance_service,
+ wants=wants,
+ included="performance" in include_set and wants_performance_opportunities,
+ file_paths=tuple(effective_targets) if scoped else None,
+ scoped=scoped,
+ limit=limit,
+ cursor=cursor,
+ view=performance_view,
+ context=performance_context,
+ boundary=performance_boundary,
+ confidence=performance_confidence,
+ sort=performance_sort,
+ )
+
coverage_rows: list[Any] = []
coverage_summary: dict[str, Any] = {}
if "coverage" in include_set and not nothing_resolved:
@@ -1913,6 +2079,15 @@ async def get_health(
plan_biomarkers_by_path,
plan_count_by_path,
),
+ # A second, additive lead for the performance pillar. The block
+ # above is unchanged: performance findings carry no defect impact,
+ # so they never competed for it and the dashboard said nothing an
+ # agent could act on about them.
+ **(
+ {"performance_directive": performance.directive}
+ if performance.directive is not None
+ else {}
+ ),
"mode": "dashboard",
"kpis": kpis,
"distribution": health_distribution(all_metrics),
@@ -2114,67 +2289,60 @@ async def get_health(
if len(recent) > limit:
result["trend"]["recent_reduced_reason"] = "limit"
- opportunities = []
- if "performance" in include_set and wants_performance_opportunities:
- performance_rows = [row for row in lead_rows if _in_dimensions(row, {"performance"})]
- opportunities = build_performance_opportunities(
- performance_rows,
- evidence_limit=max(len(performance_rows), 3),
- )
- opportunity_payload = []
- selected_opportunities = bounded(
- opportunities,
- "performance_opportunities",
- cap=min(limit, 6),
- )
- for opportunity in selected_opportunities:
- payload = opportunity.as_dict()
- evidence = list(payload.get("evidence", []))
- payload["evidence"] = bounded(
- evidence,
- f"performance_opportunities.{opportunity.opportunity_id}.evidence",
- cap=3,
+ if performance.page is not None and wants("performance_opportunities"):
+ result["performance_opportunities"] = performance.page.items
+ result["performance_opportunities_total"] = performance.page.total
+ result["performance_opportunities_emitted"] = len(performance.page.items)
+ if performance.page.next_offset is not None:
+ page_recoveries["performance_opportunities"] = (
+ performance.page.next_offset,
+ _PERFORMANCE_COLLECTION_CAP,
+ performance.page.total - performance.page.next_offset,
)
- payload["evidence_total"] = payload.get("observations_total", len(evidence))
- payload["evidence_emitted"] = len(payload["evidence"])
- if payload["evidence_emitted"] < payload["evidence_total"]:
- payload["evidence_reduced_reason"] = "evidence_cap"
- opportunity_payload.append(payload)
- result["performance_opportunities"] = opportunity_payload
- result["performance_opportunities_total"] = len(opportunities)
+ if performance.ignored:
+ result["ignored_arguments"] = {
+ **result.get("ignored_arguments", {}),
+ **performance.ignored,
+ }
+
+ if performance.summary is not None:
+ result["performance_summary"] = {
+ **performance.summary,
+ "facets": performance.page.facets if performance.page else {},
+ "next_call": (
+ "get_health(include=['performance'], "
+ "only=['performance_opportunities'], limit=6)"
+ ),
+ }
if {"performance", "refactoring"} <= include_set and wants("recommendation_lede"):
- performance_lead = opportunities[0] if opportunities else None
+ performance_lead = (
+ performance.page.items[0] if performance.page and performance.page.items else None
+ )
recommendation_lead = (
refactoring_recommendations[0] if refactoring_recommendations else None
)
- matching = next(
- (
- recommendation
- for recommendation in refactoring_recommendations
- if performance_lead is not None
- and recommendation.suggestion.refactoring_type == "performance_fix"
- and (recommendation.suggestion.evidence or {}).get("opportunity_id")
- == performance_lead.opportunity_id
- ),
- None,
- )
lead_payload = (
_serialize_refactoring(recommendation_lead, reference_repository)
if recommendation_lead
else None
)
result["recommendation_lede"] = {
- "performance_opportunities_total": len(opportunities),
+ "performance_opportunities_total": (
+ performance.page.total if performance.page else 0
+ ),
"refactoring_plans_total": len(refactoring_recommendations),
"performance_lead": (
{
- "opportunity_id": performance_lead.opportunity_id,
- "intervention_symbol": performance_lead.intervention_symbol,
- "boundary_kind": performance_lead.boundary_kind,
- "execution_context": performance_lead.execution_context,
- "affected_call_sites_total": performance_lead.affected_call_sites_total,
- "rank_score": performance_lead.rank_score,
+ key: performance_lead[key]
+ for key in (
+ "opportunity_id",
+ "intervention_symbol",
+ "boundary_kind",
+ "execution_context",
+ "affected_call_sites_total",
+ "rank_score",
+ )
}
if performance_lead
else None
@@ -2197,8 +2365,14 @@ async def get_health(
if lead_payload
else None
),
+ # The exact plan for the exact lead, from the one place that decides
+ # plan linkage. This used to match on a key the plan writer never
+ # wrote, so it was unconditionally null.
"performance_plan_id": (
- _refactoring_plan_id(matching, reference_repository) if matching else None
+ performance_lead["plan_reference"] if performance_lead else None
+ ),
+ "performance_plan_reason": (
+ performance_lead["plan_reason"] if performance_lead else None
),
"next_call": (
f"get_health(targets={raw_targets!r}, repo={repo!r}, "
@@ -2279,7 +2453,9 @@ async def get_health(
"test_findings": test_findings_total,
"churn_complexity": len(churn_points),
"refactoring_plans": len(refactoring_recommendations),
- "performance_opportunities": len(opportunities),
+ "performance_opportunities": (
+ performance.page.total if performance.page is not None else 0
+ ),
}
for key, total in collection_totals.items():
if total is None:
@@ -2331,6 +2507,9 @@ async def get_health(
"unknown_include_keys",
"unknown_include_keys_total",
"unknown_include_keys_emitted",
+ # A rejected filter value is a caller-error report, so it
+ # survives a projection for the same reason ``unresolved`` does.
+ "ignored_arguments",
"recovery",
}
| {
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 c28f89c99..3b9b498f6 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
@@ -1,133 +1,127 @@
-"""Bounded causal performance opportunities and raw-evidence drill-down."""
+"""Bounded causal performance opportunities and raw-evidence drill-down.
+
+A thin adapter: query parameters map onto the shared performance service, and
+the response is what that service returned. Filtering, ordering, paging, plan
+linkage, and facets live there, so this surface and the agent surface cannot
+drift apart about what the same opportunity is.
+"""
from __future__ import annotations
-import json
-from typing import Any, Literal
+from typing import Any
from fastapi import Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.health.perf.opportunities import (
- build_performance_opportunities,
- opportunity_id_for_finding,
-)
-from repowise.core.persistence import crud
from repowise.server.deps import get_db_session
+from repowise.server.services.performance_health import (
+ PerformanceHealthService,
+ parse_query,
+)
from ._router import router
-from .loaders import _attach_symbol_ids
-from .serializers import _finding_to_dict
-
-
-def _json_dict(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 {}
-
-
-def _plan_ids(rows: list[Any]) -> dict[str, str]:
- matches: dict[str, str] = {}
- for row in rows:
- opportunity_id = _json_dict(row.plan_json).get("opportunity_id")
- if isinstance(opportunity_id, str) and opportunity_id:
- plan_id = str(row.id)
- matches[opportunity_id] = min(matches.get(opportunity_id, plan_id), plan_id)
- return matches
-
-
-def _finding_opportunity_id(row: Any) -> str:
- persisted = _json_dict(getattr(row, "details_json", None)).get("opportunity_id")
- return (
- persisted if isinstance(persisted, str) and persisted else opportunity_id_for_finding(row)
- )
-def _plan_link(opportunity: Any, plan_id: str | None) -> dict[str, str | None]:
- if plan_id:
- return {
- "plan_id": plan_id,
- "plan_status": "available",
- "plan_reason": "A stored performance plan addresses this exact opportunity.",
- }
- if opportunity.fix is None:
- return {
- "plan_id": None,
- "plan_status": "no_safe_plan",
- "plan_reason": (
- "The analysis found the shared cause but could not prove one coherent "
- "intervention without guessing."
- ),
- }
+def _service(session: AsyncSession, repo_id: str) -> PerformanceHealthService:
+ """Bind the shared service to this repository.
+
+ The repository token only scopes the agent-address-space plan reference,
+ which this surface strips: a plan here is addressed by the row id its own
+ detail route resolves.
+ """
+ return PerformanceHealthService(session, repo_id, repo_id)
+
+
+_EVIDENCE_PER_ITEM = 8
+"""Evidence rows carried inline on a queue row, so the tab can show the paths."""
+
+
+def _item(item: dict[str, Any]) -> dict[str, Any]:
+ """Drop the reference minted for the other address space."""
+ return {key: value for key, value in item.items() if key != "plan_reference"}
+
+
+def _summary(summary: dict[str, Any]) -> dict[str, Any]:
+ """Add the flat counter names the current tab reads.
+
+ A projection of the canonical rollup, not a second count: every value is
+ read off the fields above it. The flat names retire with the tab.
+ """
+ context = summary.get("context", {})
+ total = summary.get("total", 0)
+ with_plan = summary.get("with_plan_total", 0)
return {
- "plan_id": None,
- "plan_status": "not_persisted",
- "plan_reason": (
- "A supported strategy exists, but this index does not contain its matching "
- "stored plan. Reindex to refresh recommendations."
- ),
+ **summary,
+ "production_total": context.get("production", 0),
+ "tooling_total": context.get("tooling", 0),
+ "test_total": context.get("test", 0),
+ "unknown_total": context.get("unknown", 0),
+ "with_plan_total": with_plan,
+ "without_plan_total": total - with_plan,
}
@router.get("/api/repos/{repo_id}/health/performance-opportunities")
async def list_performance_opportunities(
repo_id: str,
- context: Literal["production_tooling", "test", "all"] = Query("production_tooling"),
+ context: str = Query("all"),
+ boundary: str | None = Query(None),
+ confidence: str | None = Query(None),
+ actionability: str | None = Query(None),
+ view: str = Query("detail"),
+ sort: str = Query("rank"),
limit: int = Query(20, ge=1, le=100),
offset: int = Query(0, ge=0),
session: AsyncSession = Depends(get_db_session),
) -> dict[str, Any]:
- """One bounded page over the canonical causal read model.
+ """One bounded page over the materialized causal read model.
- Findings and performance-plan rows are each read once. Exact
- ``opportunity_id`` equality is the only accepted plan match.
+ The rows fetched are the page, not the repository: grouping already
+ happened when the findings were persisted.
"""
- findings = await crud.get_health_findings(session, repo_id, dimension="performance")
- plan_rows = await crud.get_refactoring_suggestions(
- session, repo_id, refactoring_type="performance_fix"
+ query, ignored = parse_query(
+ context=context,
+ boundary=boundary,
+ confidence=confidence,
+ actionability=actionability,
+ view=view,
+ sort=sort,
+ limit=limit,
+ offset=offset,
+ )
+ page = await _service(session, repo_id).page(
+ query, evidence_per_item=_EVIDENCE_PER_ITEM, with_facets=True, with_summary=True
)
- opportunities = build_performance_opportunities(findings, evidence_limit=8)
- matches = _plan_ids(plan_rows)
- contexts = {
- "production_tooling": {"production", "tooling"},
- "test": {"test"},
- # An unclassifiable file is reported as unknown rather than assumed to
- # ship, so it belongs in the unfiltered view and is counted below.
- "all": {"production", "tooling", "test", "unknown"},
- }[context]
- filtered = [item for item in opportunities if item.execution_context in contexts]
- total = len(filtered)
- page = filtered[offset : offset + limit]
- next_offset = offset + len(page) if offset + len(page) < total else None
return {
- "items": [
- {
- **item.as_dict(),
- **_plan_link(item, matches.get(item.opportunity_id)),
- }
- for item in page
- ],
- "total": total,
- "has_more": next_offset is not None,
- "next_offset": next_offset,
- "summary": {
- "total": len(opportunities),
- "production_total": sum(
- item.execution_context == "production" for item in opportunities
- ),
- "tooling_total": sum(item.execution_context == "tooling" for item in opportunities),
- "test_total": sum(item.execution_context == "test" for item in opportunities),
- "unknown_total": sum(item.execution_context == "unknown" for item in opportunities),
- "with_plan_total": sum(item.opportunity_id in matches for item in opportunities),
- "without_plan_total": sum(item.opportunity_id not in matches for item in opportunities),
- },
+ "items": [_item(item) for item in page.items],
+ "total": page.total,
+ "has_more": page.next_offset is not None,
+ "next_offset": page.next_offset,
+ "facets": page.facets,
+ "summary": _summary(page.summary),
+ **({"ignored_arguments": ignored} if ignored else {}),
}
[email protected]("/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}")
+async def get_performance_opportunity_detail(
+ repo_id: str,
+ opportunity_id: str,
+ evidence_limit: int = Query(8, ge=0, le=200),
+ evidence_offset: int = Query(0, ge=0),
+ session: AsyncSession = Depends(get_db_session),
+) -> dict[str, Any]:
+ """One opportunity by its stable id, with bounded evidence.
+
+ An id from an older performance model resolves to an explicit stale-model
+ state and the refresh that fixes it, rather than reading as "no plan".
+ """
+ detail = await _service(session, repo_id).detail(
+ opportunity_id, evidence_limit=evidence_limit, evidence_offset=evidence_offset
+ )
+ return _item(detail)
+
+
@router.get("/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}/findings")
async def list_performance_opportunity_findings(
repo_id: str,
@@ -136,24 +130,21 @@ async def list_performance_opportunity_findings(
offset: int = Query(0, ge=0),
session: AsyncSession = Depends(get_db_session),
) -> dict[str, Any]:
- """Click-gated raw canonical observations for one stable opportunity id."""
- findings = await crud.get_health_findings(session, repo_id, dimension="performance")
- matched = [
- finding for finding in findings if _finding_opportunity_id(finding) == opportunity_id
- ]
- matched.sort(key=lambda row: (row.file_path, row.line_start or 0, row.id))
- total = len(matched)
- page = matched[offset : offset + limit]
- items = await _attach_symbol_ids(
- session, repo_id, [_finding_to_dict(finding) for finding in page]
+ """Click-gated raw observations for one stable opportunity id."""
+ items, total = await _service(session, repo_id).evidence(
+ opportunity_id, limit=limit, offset=offset
)
- next_offset = offset + len(page) if offset + len(page) < total else None
+ emitted = offset + len(items)
return {
"items": items,
"total": total,
- "has_more": next_offset is not None,
- "next_offset": next_offset,
+ "has_more": emitted < total,
+ "next_offset": emitted if emitted < total else None,
}
-__all__ = ["list_performance_opportunities", "list_performance_opportunity_findings"]
+__all__ = [
+ "get_performance_opportunity_detail",
+ "list_performance_opportunities",
+ "list_performance_opportunity_findings",
+]
diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.py
new file mode 100644
index 000000000..c2d25e490
--- /dev/null
+++ b/packages/server/src/repowise/server/services/performance_health.py
@@ -0,0 +1,630 @@
+"""One read model for performance opportunities, serving REST and MCP.
+
+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.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.analysis.health.finding_identity import finding_public_id
+from repowise.core.analysis.health.perf.opportunities import (
+ PERFORMANCE_MODEL_VERSION,
+ model_state,
+)
+from repowise.core.analysis.health.rows import detail_map
+from repowise.core.persistence.crud import (
+ get_performance_opportunity,
+ get_performance_plan_rows,
+ get_performance_summary,
+ list_evidence_for_opportunities,
+ list_opportunity_evidence,
+ list_performance_opportunities,
+ performance_facet_counts,
+)
+
+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."""
+
+_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")
+_BOUNDARIES = ("db", "network", "filesystem", "subprocess", "lock", "none")
+
+_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 = "all"
+ 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})
+
+
+@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:
+ items: list[dict[str, Any]]
+ total: int
+ offset: int
+ next_offset: int | None
+ facets: dict[str, list[dict[str, Any]]]
+ summary: dict[str, Any]
+ 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
+ ignored[name] = value
+ return None
+
+ resolved_context: PerformanceContext = "all"
+ if context:
+ if context in CANONICAL_CONTEXTS or context == "all" or context in _DEPRECATED_CONTEXTS:
+ resolved_context = context # type: ignore[assignment]
+ else:
+ ignored["performance_context"] = context
+ 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."""
+
+ def __init__(self, session: AsyncSession, repository_id: str, repository: str) -> None:
+ self._session = session
+ self._repository_id = repository_id
+ self._repository = repository
+
+ # -- collection --------------------------------------------------------
+
+ async def page(
+ self,
+ query: PerformanceQuery,
+ *,
+ evidence_per_item: int = 0,
+ with_facets: bool = False,
+ with_summary: bool = False,
+ ) -> PerformancePage:
+ """One page and its plan links, plus whatever else the caller renders.
+
+ Three statements for the page itself: the rows, their count, and their
+ plans, and each fetches the page rather than the repository. Evidence,
+ facets, and the headline each cost one more and are opt-in, because a
+ caller that quotes one row should not pay for a rollup it discards.
+
+ The facet aggregate is the one that reads more than the page: it groups
+ every open opportunity, which is the only way to report the counts a
+ filter control needs. It stays a single indexed aggregate over a table
+ that already holds one row per cause rather than one per observation.
+ """
+ rows, total = await list_performance_opportunities(
+ self._session,
+ self._repository_id,
+ contexts=query.contexts,
+ boundary=query.boundary,
+ confidence=query.confidence,
+ actionability=query.actionability,
+ file_paths=query.file_paths,
+ sort=query.sort,
+ limit=query.limit,
+ offset=query.offset,
+ )
+ links = await self._plan_links(rows)
+ evidence = await self._evidence_for(rows, evidence_per_item)
+ items = [
+ {
+ **self._serialize(
+ row, links[row.opportunity_id], summary=query.view == "summary"
+ ),
+ **(
+ evidence_block(
+ evidence.get(row.opportunity_id, []), row.observations_total, 0
+ )
+ if evidence_per_item
+ else {}
+ ),
+ }
+ for row in rows
+ ]
+ emitted = query.offset + len(items)
+ return PerformancePage(
+ items=items,
+ total=total,
+ offset=query.offset,
+ next_offset=emitted if emitted < total else None,
+ facets=await self._facets(query) if with_facets else {},
+ summary=await self.summary() if with_summary else {},
+ )
+
+ async def _evidence_for(
+ self, rows: list[Any], per_item: int
+ ) -> dict[str, list[dict[str, Any]]]:
+ """A few observations for every row on the page, in one statement.
+
+ Ranked inside the database, so a page holding one very large cause
+ still reads a bounded number of rows.
+ """
+ if not per_item or not rows:
+ return {}
+ grouped = await list_evidence_for_opportunities(
+ self._session,
+ self._repository_id,
+ [row.opportunity_id for row in rows],
+ per_opportunity=per_item,
+ )
+ return {key: [evidence_payload(row) for row in group] for key, group in grouped.items()}
+
+ async def _plan_links(self, rows: list[Any]) -> dict[str, PlanLink]:
+ """One indexed batch for the whole page, never one query per row."""
+ plans = await get_performance_plan_rows(
+ self._session, self._repository_id, [row.opportunity_id for row in rows]
+ )
+ 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),
+ )
+ 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.
+ """
+ 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
+
+ # -- headline ----------------------------------------------------------
+
+ async def summary(self) -> dict[str, Any]:
+ """The compact rollup, from the one-row current summary.
+
+ Reads by primary key, so a bare dashboard pays one statement for its
+ performance headline however large the repository is.
+ """
+ return _summary_of(await get_performance_summary(self._session, self._repository_id))
+
+ async def directive(self) -> dict[str, Any]:
+ """One bounded next action for a bare dashboard call.
+
+ Selection is the best concrete next action rather than the highest raw
+ rank: the materialized order already sorts actionable work above
+ high-volume evidence, so the lead is the first row.
+
+ The lead and the counts come off the same row read, because the lead is
+ the reason the row exists.
+ """
+ row = await get_performance_summary(self._session, self._repository_id)
+ summary = _summary_of(row)
+ if summary["status"] == "unavailable":
+ return {
+ "status": "unavailable",
+ "reason": summary["reason"],
+ "detail": summary["detail"],
+ }
+ lead = _loads(row.summary_json).get("lead")
+ counts = summary["actionability"]
+ base = {
+ "performance_model_version": PERFORMANCE_MODEL_VERSION,
+ "opportunities_total": summary["total"],
+ "plan_ready_total": counts.get("plan_ready", 0),
+ "advisory_total": counts.get("advisory", 0),
+ "investigate_total": counts.get("investigate", 0),
+ }
+ if summary["status"] == "stale_model":
+ return {
+ **base,
+ "status": "unavailable",
+ "reason": "stale_model",
+ "detail": (
+ "The stored performance analysis predates the current model. "
+ "Run repowise update to rescore."
+ ),
+ }
+ if lead is None:
+ return {
+ **base,
+ "status": "clear",
+ # Never "fast": the analysis found no supported pattern, which
+ # is not a measurement of how this code runs.
+ "detail": "No supported open pattern surfaced.",
+ }
+ return {
+ **base,
+ "status": lead["actionability_state"],
+ "opportunity_id": lead["opportunity_id"],
+ "title": _title(lead),
+ "file_path": lead["file_path"],
+ "execution_context": lead["execution_context"],
+ "boundary_kind": lead["boundary_kind"],
+ "affected_call_sites_total": lead["affected_call_sites_total"],
+ "observations_total": lead["observations_total"],
+ "why_ranked": lead["why_ranked"][:3],
+ "plan_state": lead["plan_state"],
+ "plan_reason": _PLAN_REASONS[lead["plan_state"]],
+ "prerequisites": lead["prerequisites"],
+ "next_action": {
+ "tool": "get_health",
+ "arguments": {"opportunity_id": lead["opportunity_id"]},
+ },
+ }
+
+ # -- detail ------------------------------------------------------------
+
+ async def detail(
+ self, opportunity_id: str, *, evidence_limit: int = 3, evidence_offset: int = 0
+ ) -> dict[str, Any]:
+ """One opportunity by id, with bounded evidence and exact plan state."""
+ state = model_state(opportunity_id)
+ row = await get_performance_opportunity(
+ self._session, self._repository_id, opportunity_id
+ )
+ if row is None:
+ return {
+ "resolved": False,
+ "opportunity_id": opportunity_id,
+ "model_state": state,
+ "detail": _unresolved_detail(state),
+ }
+ links = await self._plan_links([row])
+ payload = self._serialize(row, links[opportunity_id])
+ evidence, total = await self.evidence(
+ opportunity_id,
+ limit=evidence_limit,
+ offset=evidence_offset,
+ total=row.observations_total,
+ )
+ payload.update(
+ {
+ "resolved": True,
+ "lifecycle_status": row.status,
+ "analyzed_commit": row.analyzed_commit,
+ "model_state": state,
+ **evidence_block(evidence, total, evidence_offset),
+ }
+ )
+ return payload
+
+ async def evidence(
+ self,
+ opportunity_id: str,
+ *,
+ limit: int = 3,
+ offset: int = 0,
+ total: int | None = None,
+ ) -> tuple[list[dict[str, Any]], int]:
+ """One page of the observations behind a cause, and their exact total."""
+ rows, total = await list_opportunity_evidence(
+ self._session,
+ self._repository_id,
+ opportunity_id,
+ limit=max(0, limit),
+ offset=max(0, offset),
+ total=total,
+ )
+ 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,
+ "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", []),
+ "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,
+ "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", {}),
+ "actionability_reason": details.get("actionability_reason"),
+ "prerequisites": details.get("prerequisites", []),
+ "rank_factors": details.get("rank_factors", {}),
+ "fix": None
+ if fix_strategy is None
+ else {
+ "strategy": fix_strategy,
+ "safety": row.fix_safety,
+ "rationale": details.get("fix_rationale") or "",
+ },
+ }
+
+
+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),
+ **(
+ {"refresh_required": True, "detail": "Run repowise update to rescore."}
+ if stale
+ else {}
+ ),
+ }
+
+
+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 _title(lead: dict[str, Any]) -> str:
+ """A human cause, not a marker name."""
+ symbol = lead.get("intervention_symbol") or lead.get("terminal_sink") or lead["file_path"]
+ return f"{lead['biomarker_type']} reaching {symbol}"
+
+
+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_block",
+ "evidence_payload",
+ "parse_query",
+]
diff --git a/packages/types/src/health.ts b/packages/types/src/health.ts
index 6ce7385af..39d5624be 100644
--- a/packages/types/src/health.ts
+++ b/packages/types/src/health.ts
@@ -253,8 +253,33 @@ export interface PerformanceOpportunityEvidence {
provenance: string;
}
+export type PerformanceActionabilityState = "plan_ready" | "advisory" | "investigate";
+export type PerformancePlanStatus = "available" | "no_safe_plan" | "not_persisted";
+
+/** One rank term, the input it read, and the points it contributed. */
+export interface PerformanceWhyRanked {
+ factor: string;
+ value: string | number | boolean | null;
+ points: number;
+}
+
+/**
+ * The facets that are not published anywhere else on the row.
+ * `confidence` stays evidence confidence and `fix.safety` stays fix safety,
+ * so no value appears twice.
+ */
+export interface PerformanceOpportunityFacets {
+ actionability_confidence: PerformanceOpportunityConfidence;
+ exposure: string;
+ amplification: string;
+ leverage: string;
+ change_risk: string;
+}
+
export interface PerformanceOpportunity {
opportunity_id: string;
+ /** Ids are stable within a model version and never translated across one. */
+ performance_model_version: number;
biomarker_type: string;
biomarker_types: string[];
boundary_kind: C4IoKind | null;
@@ -262,34 +287,99 @@ export interface PerformanceOpportunity {
terminal_sink: string | null;
shared_path_suffix: string[];
intervention_symbol: string | null;
+ /** The file holding the symbol worth editing. */
+ file_path: string;
+ resource_fingerprints: string[];
affected_call_sites_total: number;
affected_files_total: number;
observations_total: number;
evidence: PerformanceOpportunityEvidence[];
evidence_truncated: boolean;
+ evidence_total: number;
+ evidence_emitted: number;
+ /** Offset for the next evidence page, absent once the last one is emitted. */
+ evidence_next_cursor?: number;
reliable_entry_reachability: boolean | null;
provenance: string;
+ /** Evidence confidence: how reliably the call path resolved. */
confidence: PerformanceOpportunityConfidence;
+ facets: PerformanceOpportunityFacets;
+ actionability_state: PerformanceActionabilityState;
+ actionability_reason: string;
+ prerequisites: string[];
rank_score: number;
+ rank_position: number;
rank_factors: Record<string, number>;
+ why_ranked: PerformanceWhyRanked[];
fix: PerformanceOpportunityFix | null;
/** Exact stored match. Never inferred from file, marker, or rank. */
plan_id: string | null;
- plan_status: "available" | "no_safe_plan" | "not_persisted";
+ plan_status: PerformancePlanStatus;
plan_reason: string;
}
+/** Whether a quoted id still names something this index can resolve. */
+export interface PerformanceModelState {
+ state: "current" | "stale_model" | "unrecognized";
+ opportunity_id: string;
+ requested_model_version: number | null;
+ performance_model_version: number;
+ refresh_required: boolean;
+}
+
+/**
+ * One opportunity by id. An unresolved id still answers, with the model state
+ * and what to do about it, rather than reading as "nothing to fix here".
+ */
+export type PerformanceOpportunityDetail =
+ | ({
+ resolved: true;
+ lifecycle_status: "open" | "resolved";
+ analyzed_commit: string | null;
+ model_state: PerformanceModelState;
+ evidence_total: number;
+ evidence_emitted: number;
+ evidence_next_cursor?: number;
+ } & PerformanceOpportunity)
+ | {
+ resolved: false;
+ opportunity_id: string;
+ model_state: PerformanceModelState;
+ detail: string;
+ };
+
+/** Counts per value for one filter, cross-filtered by the other filters. */
+export interface PerformanceFacetCount {
+ value: string;
+ total: number;
+}
+
+export type PerformanceFacets = Record<string, PerformanceFacetCount[]>;
+
export interface PerformanceOpportunitySummary {
+ /** `current` once materialized, `stale_model` after a model bump, or
+ * `unavailable` when this index has not been analyzed yet. */
+ status: "current" | "stale_model" | "unavailable";
total: number;
+ performance_model_version?: number;
+ analyzed_commit?: string | null;
+ actionability?: Partial<Record<PerformanceActionabilityState, number>>;
+ context?: Partial<Record<PerformanceExecutionContext, number>>;
+ boundary?: Record<string, number>;
+ with_plan_total: number;
+ /** Flat counters the current tab reads, projected from `context` above. */
production_total: number;
tooling_total: number;
test_total: number;
- with_plan_total: number;
+ unknown_total: number;
without_plan_total: number;
}
export interface PerformanceOpportunityPage extends Paginated<PerformanceOpportunity> {
summary: PerformanceOpportunitySummary;
+ facets: PerformanceFacets;
+ /** Filter values the server did not recognize, named rather than dropped. */
+ ignored_arguments?: Record<string, string>;
}
export interface HealthModuleRow {
diff --git a/packages/ui/__tests__/health/performance-view.test.tsx b/packages/ui/__tests__/health/performance-view.test.tsx
index 1caff9191..34f94f5db 100644
--- a/packages/ui/__tests__/health/performance-view.test.tsx
+++ b/packages/ui/__tests__/health/performance-view.test.tsx
@@ -14,6 +14,7 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {
items: [
{
opportunity_id: "opp-1",
+ performance_model_version: 2,
biomarker_type: "io_in_loop",
biomarker_types: ["io_in_loop"],
boundary_kind: "db",
@@ -21,6 +22,8 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {
terminal_sink: "src/db.py::fetch",
shared_path_suffix: ["src/shared.py::load", "src/db.py::fetch"],
intervention_symbol: "src/shared.py::load",
+ file_path: "src/shared.py",
+ resource_fingerprints: [],
affected_call_sites_total: 2,
affected_files_total: 2,
observations_total: 6,
@@ -49,11 +52,26 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {
},
],
evidence_truncated: true,
+ evidence_total: 6,
+ evidence_emitted: 2,
+ evidence_next_cursor: 2,
reliable_entry_reachability: true,
provenance: "reliable-edge",
confidence: "medium",
+ facets: {
+ actionability_confidence: "medium",
+ exposure: "entry_reachable",
+ amplification: "per_iteration",
+ leverage: "local",
+ change_risk: "moderate",
+ },
+ actionability_state: "advisory",
+ actionability_reason: "strategy_requires_validation",
+ prerequisites: ["batch_api_contract"],
rank_score: 12.5,
+ rank_position: 0,
rank_factors: {},
+ why_ranked: [{ factor: "boundary_kind", value: "db", points: 4 }],
fix: {
strategy: "batch_or_prefetch_io",
safety: "advisory",
@@ -67,11 +85,14 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {
total: 1,
has_more: false,
next_offset: null,
+ facets: {},
summary: {
+ status: "current",
total: 2,
production_total: 1,
tooling_total: 0,
test_total: 1,
+ unknown_total: 0,
with_plan_total: planId ? 1 : 0,
without_plan_total: planId ? 1 : 2,
},
diff --git a/tests/fixtures/perf_corpus/golden_opportunities.json b/tests/fixtures/perf_corpus/golden_opportunities.json
index c739ebbb0..aad16d559 100644
--- a/tests/fixtures/perf_corpus/golden_opportunities.json
+++ b/tests/fixtures/perf_corpus/golden_opportunities.json
@@ -15,7 +15,7 @@
{
"biomarker_type": "serial_await_in_loop",
"file_path": "src/app/fanout.py",
- "finding_id": "async_serial_awaits-09",
+ "finding_id": "hf1_b157597c538312230160",
"function_name": "gather_all",
"line_end": 92,
"line_start": 90,
@@ -90,7 +90,7 @@
{
"biomarker_type": "resource_construction_in_loop",
"file_path": "src/app/clients.py",
- "finding_id": "resource_construction-16",
+ "finding_id": "hf1_5ad540ed5be9ff91a083",
"function_name": "each",
"line_end": 172,
"line_start": 170,
@@ -165,7 +165,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/entry.py",
- "finding_id": "reachability_states-25",
+ "finding_id": "hf1_0823db7a2e988fb8b165",
"function_name": "a",
"line_end": 252,
"line_start": 250,
@@ -180,7 +180,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/entry.py",
- "finding_id": "reachability_states-26",
+ "finding_id": "hf1_578bec48b788a57ce085",
"function_name": "b",
"line_end": 257,
"line_start": 255,
@@ -265,7 +265,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/api.py",
- "finding_id": "specific_shared_helper-03",
+ "finding_id": "hf1_e944c79df994e87201d0",
"function_name": "list_users",
"line_end": 32,
"line_start": 30,
@@ -280,7 +280,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/api.py",
- "finding_id": "specific_shared_helper-04",
+ "finding_id": "hf1_369c4ed522b7c79bb338",
"function_name": "list_orders",
"line_end": 33,
"line_start": 31,
@@ -366,7 +366,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/reindex.py",
- "finding_id": "cost_shape_merge-21",
+ "finding_id": "hf1_f326415f03634da6edff",
"function_name": "one",
"line_end": 212,
"line_start": 210,
@@ -381,7 +381,7 @@
{
"biomarker_type": "nested_loop_with_io",
"file_path": "src/app/reindex.py",
- "finding_id": "cost_shape_merge-22",
+ "finding_id": "hf1_1ca34d0590635ad5fa7e",
"function_name": "many",
"line_end": 217,
"line_start": 215,
@@ -466,7 +466,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/sync.py",
- "finding_id": "same_file_db_helper-07",
+ "finding_id": "hf1_ddc30fca4e968dc937dc",
"function_name": "sync_one",
"line_end": 72,
"line_start": 70,
@@ -481,7 +481,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/sync.py",
- "finding_id": "same_file_db_helper-08",
+ "finding_id": "hf1_8a8dbf682cb16d7351a0",
"function_name": "sync_all",
"line_end": 73,
"line_start": 71,
@@ -566,7 +566,7 @@
{
"biomarker_type": "blocking_io_under_lock",
"file_path": "src/app/cache.py",
- "finding_id": "single_lock_owner-11",
+ "finding_id": "hf1_42138363b2d56be00569",
"function_name": "refresh",
"line_end": 112,
"line_start": 110,
@@ -649,7 +649,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/billing.py",
- "finding_id": "generic_infra_sink-01",
+ "finding_id": "hf1_5e1434284085c8d89807",
"function_name": "handle",
"line_end": 13,
"line_start": 11,
@@ -733,7 +733,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/orders.py",
- "finding_id": "generic_infra_sink-00",
+ "finding_id": "hf1_b5e9b88139938221b07f",
"function_name": "handle",
"line_end": 12,
"line_start": 10,
@@ -817,7 +817,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/reports.py",
- "finding_id": "generic_infra_sink-02",
+ "finding_id": "hf1_5a4726fc8549aab5f4a3",
"function_name": "handle",
"line_end": 14,
"line_start": 12,
@@ -901,7 +901,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/job.py",
- "finding_id": "context_split-18",
+ "finding_id": "hf1_6076ccc742fcda80f642",
"function_name": "run",
"line_end": 202,
"line_start": 200,
@@ -985,7 +985,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/lone.py",
- "finding_id": "sink_without_caller-33",
+ "finding_id": "hf1_7ecc1136a23953fb0936",
"function_name": "run",
"line_end": 11,
"line_start": 9,
@@ -1067,7 +1067,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "scripts/backfill.py",
- "finding_id": "context_split-19",
+ "finding_id": "hf1_5ff8013358afaf016e7c",
"function_name": "run",
"line_end": 202,
"line_start": 200,
@@ -1151,7 +1151,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/edge.py",
- "finding_id": "provenance_mix-23",
+ "finding_id": "hf1_af7e43a631e63d3a640c",
"function_name": "run",
"line_end": 232,
"line_start": 230,
@@ -1235,7 +1235,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "tests/test_job.py",
- "finding_id": "context_split-20",
+ "finding_id": "hf1_0a2ba842c19f76c1c567",
"function_name": "run",
"line_end": 202,
"line_start": 200,
@@ -1319,7 +1319,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/guess.py",
- "finding_id": "provenance_mix-24",
+ "finding_id": "hf1_5f39d2fe1231369724a4",
"function_name": "run",
"line_end": 242,
"line_start": 240,
@@ -1404,7 +1404,7 @@
{
"biomarker_type": "membership_test_against_list_in_loop",
"file_path": "src/app/filters.py",
- "finding_id": "membership_scan-14",
+ "finding_id": "hf1_5b38d822737127eff696",
"function_name": "select",
"line_end": 152,
"line_start": 150,
@@ -1482,7 +1482,7 @@
{
"biomarker_type": "string_concat_in_loop",
"file_path": "src/app/render.py",
- "finding_id": "string_accumulation-15",
+ "finding_id": "hf1_b1d031c5caf612deae23",
"function_name": "to_csv",
"line_end": 162,
"line_start": 160,
@@ -1559,7 +1559,7 @@
{
"biomarker_type": "blocking_io_under_lock",
"file_path": "src/app/pool.py",
- "finding_id": "distinct_lock_owners-13",
+ "finding_id": "hf1_53aa0b7de62bef7cf3a1",
"function_name": "reaper",
"line_end": 132,
"line_start": 130,
@@ -1574,7 +1574,7 @@
{
"biomarker_type": "blocking_io_under_lock",
"file_path": "src/app/pool.py",
- "finding_id": "distinct_lock_owners-12",
+ "finding_id": "hf1_70aae64c974e10e8567e",
"function_name": "writer",
"line_end": 132,
"line_start": 130,
@@ -1654,7 +1654,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/formatter.py",
- "finding_id": "shared_dominator_fan_in-29",
+ "finding_id": "hf1_49feb9a4d9831db3880b",
"function_name": "run",
"line_end": 24,
"line_start": 22,
@@ -1669,7 +1669,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/lexer.py",
- "finding_id": "shared_dominator_fan_in-27",
+ "finding_id": "hf1_02b54f38fbb30a5c663f",
"function_name": "run",
"line_end": 22,
"line_start": 20,
@@ -1684,7 +1684,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/linter.py",
- "finding_id": "shared_dominator_fan_in-28",
+ "finding_id": "hf1_b142f6e353eb4b957ec5",
"function_name": "run",
"line_end": 23,
"line_start": 21,
@@ -1699,7 +1699,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/resolver.py",
- "finding_id": "shared_dominator_fan_in-30",
+ "finding_id": "hf1_f43aa873be79bf90590a",
"function_name": "run",
"line_end": 25,
"line_start": 23,
@@ -1779,7 +1779,7 @@
{
"biomarker_type": "resource_construction_in_loop",
"file_path": "src/app/clients.py",
- "finding_id": "resource_construction-17",
+ "finding_id": "hf1_199ce617b3bc8a442dc6",
"function_name": "each_varying",
"line_end": 182,
"line_start": 180,
@@ -1852,7 +1852,7 @@
{
"biomarker_type": "serial_await_in_loop",
"file_path": "src/app/fanout.py",
- "finding_id": "async_serial_awaits-10",
+ "finding_id": "hf1_a20deca6f8a2935a9f60",
"function_name": "gather_seq",
"line_end": 97,
"line_start": 95,
@@ -1925,7 +1925,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/walker.py",
- "finding_id": "filesystem_fan_out-05",
+ "finding_id": "hf1_1ac91145d11248da1c67",
"function_name": "scan",
"line_end": 52,
"line_start": 50,
@@ -2004,7 +2004,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "src/app/walker.py",
- "finding_id": "filesystem_fan_out-06",
+ "finding_id": "hf1_6f6b30a7872faf6737f0",
"function_name": "index",
"line_end": 53,
"line_start": 51,
@@ -2083,7 +2083,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "docs/snippets/walk.py",
- "finding_id": "unclassified_context-31",
+ "finding_id": "hf1_233c919884cf9aa50001",
"function_name": "demo",
"line_end": 10,
"line_start": 8,
@@ -2156,7 +2156,7 @@
{
"biomarker_type": "io_in_loop",
"file_path": "bootstrap.py",
- "finding_id": "unclassified_context-32",
+ "finding_id": "hf1_072c88fe4bfe6a1bab1f",
"function_name": "main",
"line_end": 16,
"line_start": 14,
diff --git a/tests/unit/health/test_perf_identity_contract.py b/tests/unit/health/test_perf_identity_contract.py
index 8aae13f13..8717f27d7 100644
--- a/tests/unit/health/test_perf_identity_contract.py
+++ b/tests/unit/health/test_perf_identity_contract.py
@@ -17,6 +17,7 @@ import copy
import pytest
+from repowise.core.analysis.health.finding_identity import finding_public_id
from repowise.core.analysis.health.perf.opportunities import (
PERFORMANCE_MODEL_VERSION,
build_performance_opportunities,
@@ -266,26 +267,48 @@ def test_the_plan_id_is_absent_from_plan_evidence_today() -> None:
assert "opportunity_id" not in plan.evidence
-def test_a_performance_finding_has_no_content_derived_public_reference() -> None:
- """The only stable public key on a performance finding is its group id.
+def test_evidence_is_addressed_by_a_content_derived_public_reference() -> None:
+ """Evidence carries the finding's public id, never a storage row id.
- ``evidence[].finding_id`` is the storage row id: empty in memory, a random
- UUID once persisted. Nothing joins on it across a reindex, so it is not
- an identity.
+ The row id is republished on every analysis, so a caller who quoted one
+ back was quoting a value that no longer existed. The public id is derived
+ from the finding's own coordinates, so it survives the reindex and is the
+ same string before and after persistence.
"""
in_memory = _row()
del in_memory["id"]
- opportunity = build_performance_opportunities([in_memory])[0]
- assert opportunity.evidence[0]["finding_id"] == ""
+ reference = build_performance_opportunities([in_memory])[0].evidence[0]["finding_id"]
+ assert reference == finding_public_id(in_memory)
persisted = _row(id="8f14e45fceea167a5a36dedd4bea2543")
- assert build_performance_opportunities([persisted])[0].evidence[0]["finding_id"] == (
- "8f14e45fceea167a5a36dedd4bea2543"
+ assert build_performance_opportunities([persisted])[0].evidence[0]["finding_id"] == reference
+
+ stored = _row(id="8f14e45fceea167a5a36dedd4bea2543", public_id="finding_already_stored")
+ assert build_performance_opportunities([stored])[0].evidence[0]["finding_id"] == (
+ "finding_already_stored"
)
link_performance_findings([persisted])
assert persisted["details"]["opportunity_id"] == CROSS_FUNCTION_ID
+def test_the_public_finding_id_ignores_prose_and_derived_details() -> None:
+ """Rewording a detector, or a later model changing its mind, moves nothing.
+
+ The id is stored on the row and quoted by agents, so anything that can
+ change without the finding moving has to stay out of its kernel.
+ """
+ base = _row()
+ assert finding_public_id(base) == finding_public_id(_row(reason="reworded entirely"))
+ assert finding_public_id(base) == finding_public_id(
+ _row(details={**base["details"], "opportunity_id": "perf9_deadbeef"})
+ )
+ assert finding_public_id(base) == finding_public_id(
+ _row(details={**base["details"], "reliable_entry_reachability": True})
+ )
+ # Structural coordinates are in the kernel, so a real move is a new id.
+ assert finding_public_id(base) != finding_public_id(_row(line_start=999))
+
+
def test_a_path_node_that_names_nothing_never_becomes_an_intervention_symbol() -> None:
"""An empty node is absence, not a symbol called \"\"."""
row = _row(details={"path": ["", "src/app/db.py::get_session"]})
diff --git a/tests/unit/persistence/test_models.py b/tests/unit/persistence/test_models.py
index 0ea407b52..d6e087181 100644
--- a/tests/unit/persistence/test_models.py
+++ b/tests/unit/persistence/test_models.py
@@ -319,6 +319,8 @@ def test_base_includes_all_models():
"health_file_metrics",
"health_snapshots",
"refactoring_suggestions",
+ "performance_opportunities",
+ "performance_summaries",
"coverage_files",
"test_coverage",
"pipeline_jobs",
diff --git a/tests/unit/persistence/test_performance_materialization.py b/tests/unit/persistence/test_performance_materialization.py
new file mode 100644
index 000000000..774b87df4
--- /dev/null
+++ b/tests/unit/persistence/test_performance_materialization.py
@@ -0,0 +1,372 @@
+"""The writer that turns stored performance findings into a servable queue.
+
+Grouping used to happen on every read, so a page of twenty cost the whole
+repository. It happens here instead, once per health persistence transaction,
+and both index paths call it. These tests pin what that means: the same answer
+from a full and a partial run, plans generated exactly once, a cause that stops
+being observed resolved rather than dropped, and a schema that upgrades and
+rolls back.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+import pytest
+from sqlalchemy import select
+
+from repowise.core.analysis.health.models import HealthFindingData, Severity
+from repowise.core.analysis.health.perf.opportunities import (
+ PERFORMANCE_MODEL_VERSION,
+ link_performance_findings,
+)
+from repowise.core.analysis.health.refactoring.performance_fix import PerformancePlanPolicy
+from repowise.core.persistence import crud
+from repowise.core.persistence.models import (
+ HealthFinding,
+ PerformanceOpportunity,
+ PerformanceSummary,
+ RefactoringSuggestion,
+)
+from tests.unit.persistence.helpers import insert_repo
+
+_SHARED = ["{caller}::run", "src/shared.py::load", "src/db.py::fetch"]
+
+
+def _finding(path: str, line: int, *, marker: str = "serial_await_in_loop", **details):
+ return HealthFindingData(
+ biomarker_type=marker,
+ severity=Severity.MEDIUM,
+ file_path=path,
+ function_name="run",
+ line_start=line,
+ line_end=line,
+ details={
+ "boundary_kind": "db",
+ "cross_function": True,
+ "path": [node.format(caller=path) for node in _SHARED],
+ "resolution_basis": "call-site",
+ "dataflow_verified": True,
+ **details,
+ },
+ health_impact=0.0,
+ reason="Awaited database work repeats for every loop iteration.",
+ dimension="performance",
+ )
+
+
+def _corpus() -> list:
+ return [_finding("src/a.py", 10), _finding("src/b.py", 20), _finding("src/c.py", 30)]
+
+
+async def _write(session, repo_id: str, findings: list, **kwargs) -> int:
+ link_performance_findings(findings)
+ await crud.save_health_findings(session, repo_id, findings)
+ return await crud.finalize_performance_opportunities(session, repo_id, **kwargs)
+
+
+async def _rows(session, repo_id: str) -> list[PerformanceOpportunity]:
+ result = await session.execute(
+ select(PerformanceOpportunity)
+ .where(PerformanceOpportunity.repository_id == repo_id)
+ .order_by(PerformanceOpportunity.rank_position)
+ )
+ return list(result.scalars().all())
+
+
+async def test_one_pass_materializes_the_queue_its_plans_and_its_headline(
+ async_session,
+) -> None:
+ repo = await insert_repo(async_session)
+ total = await _write(async_session, repo.id, _corpus(), analyzed_commit="b" * 40)
+
+ assert total == 1
+ (row,) = await _rows(async_session, repo.id)
+ assert row.status == "open"
+ assert row.rank_position == 0
+ assert row.observations_total == 3
+ assert row.affected_call_sites_total == 3
+ assert row.intervention_symbol == "src/shared.py::load"
+ assert row.file_path == "src/shared.py"
+ assert row.plan_state == "available"
+ assert row.performance_model_version == PERFORMANCE_MODEL_VERSION
+ assert row.analyzed_commit == "b" * 40
+
+ # Filter and order live in columns; the rest stays in the open payload, and
+ # nothing appears in both.
+ details = json.loads(row.details_json)
+ assert set(details) & {"execution_context", "rank_score", "boundary_kind"} == set()
+ assert details["facets"]["leverage"] == "local"
+
+ plans = await crud.get_refactoring_suggestions(
+ async_session, repo.id, refactoring_type="performance_fix"
+ )
+ assert [plan.opportunity_id for plan in plans] == [row.opportunity_id]
+
+ summary = await crud.get_performance_summary(async_session, repo.id)
+ assert summary.opportunities_total == 1
+ assert json.loads(summary.summary_json)["lead"]["opportunity_id"] == row.opportunity_id
+
+
+async def test_every_stored_observation_carries_its_cause_and_its_public_id(
+ async_session,
+) -> None:
+ """Both are columns, which is what makes drill-down an indexed seek."""
+ repo = await insert_repo(async_session)
+ await _write(async_session, repo.id, _corpus())
+ rows = (
+ (
+ await async_session.execute(
+ select(HealthFinding).where(HealthFinding.repository_id == repo.id)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ (opportunity,) = await _rows(async_session, repo.id)
+ assert {row.opportunity_id for row in rows} == {opportunity.opportunity_id}
+ assert all(row.public_id and row.public_id.startswith("finding_") for row in rows)
+ assert len({row.public_id for row in rows}) == 3
+
+
+async def test_a_store_written_before_the_columns_existed_is_backfilled(
+ async_session,
+) -> None:
+ """The columns are nullable, so an upgraded store arrives with them empty."""
+ repo = await insert_repo(async_session)
+ await _write(async_session, repo.id, _corpus())
+ await async_session.execute(
+ HealthFinding.__table__.update()
+ .where(HealthFinding.repository_id == repo.id)
+ .values(public_id=None, opportunity_id=None)
+ )
+ await crud.finalize_performance_opportunities(async_session, repo.id)
+
+ rows = (
+ (
+ await async_session.execute(
+ select(HealthFinding).where(HealthFinding.repository_id == repo.id)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ assert all(row.public_id and row.opportunity_id for row in rows)
+
+
+async def test_a_partial_run_and_a_full_run_reach_the_same_queue(async_session) -> None:
+ """The partial path sees a subset, so it must not build the queue itself.
+
+ It writes its own findings and then rebuilds from the merged stored set,
+ which is the only way the two paths can agree.
+ """
+ full_repo = await insert_repo(async_session, name="full", local_path="/tmp/full")
+ await _write(async_session, full_repo.id, _corpus())
+ expected = [
+ (row.opportunity_id, row.rank_position, row.observations_total, row.plan_state)
+ for row in await _rows(async_session, full_repo.id)
+ ]
+
+ partial_repo = await insert_repo(async_session, name="partial", local_path="/tmp/partial")
+ first = _corpus()[:1]
+ link_performance_findings(first)
+ await crud.save_health_findings(async_session, partial_repo.id, first)
+ rest = _corpus()[1:]
+ link_performance_findings(rest)
+ await crud.upsert_health_findings(
+ async_session,
+ partial_repo.id,
+ rest,
+ file_paths=["src/b.py", "src/c.py"],
+ )
+ await crud.finalize_performance_opportunities(async_session, partial_repo.id)
+
+ assert [
+ (row.opportunity_id, row.rank_position, row.observations_total, row.plan_state)
+ for row in await _rows(async_session, partial_repo.id)
+ ] == expected
+
+
+async def test_a_cause_nobody_observes_is_resolved_and_its_plan_withdrawn(
+ async_session,
+) -> None:
+ repo = await insert_repo(async_session)
+ await _write(async_session, repo.id, _corpus())
+ (before,) = await _rows(async_session, repo.id)
+
+ await _write(async_session, repo.id, [_finding("src/z.py", 40, marker="io_in_loop")])
+ rows = {row.opportunity_id: row for row in await _rows(async_session, repo.id)}
+
+ assert rows[before.opportunity_id].status == "resolved"
+ assert len([row for row in rows.values() if row.status == "open"]) == 1
+ # The withdrawn cause's plan goes with it: plans are replaced wholesale
+ # from the current opportunities, never left behind pointing at nothing.
+ plans = await crud.get_refactoring_suggestions(
+ async_session, repo.id, refactoring_type="performance_fix"
+ )
+ assert before.opportunity_id not in {plan.opportunity_id for plan in plans}
+
+
+async def test_a_row_from_an_older_model_is_resolved_rather_than_reused(
+ async_session,
+) -> None:
+ """Two model versions disagree about membership, so neither can stand in
+ for the other. The old row stays addressable and stops reading as current.
+ """
+ repo = await insert_repo(async_session)
+ await _write(async_session, repo.id, _corpus())
+ async_session.add(
+ PerformanceOpportunity(
+ id="0" * 32,
+ repository_id=repo.id,
+ opportunity_id="perf1_0123456789abcdef0123",
+ performance_model_version=PERFORMANCE_MODEL_VERSION - 1,
+ status="open",
+ )
+ )
+ await async_session.flush()
+
+ await crud.finalize_performance_opportunities(async_session, repo.id)
+ rows = {row.opportunity_id: row.status for row in await _rows(async_session, repo.id)}
+ assert rows["perf1_0123456789abcdef0123"] == "resolved"
+
+
+async def test_disabling_plans_leaves_the_queue_and_withdraws_the_plans(
+ async_session,
+) -> None:
+ repo = await insert_repo(async_session)
+ await _write(
+ async_session,
+ repo.id,
+ _corpus(),
+ plan_policy=PerformancePlanPolicy(enabled=False),
+ )
+ (row,) = await _rows(async_session, repo.id)
+ assert row.plan_state == "not_persisted"
+ assert row.fix_strategy == "parallelize_independent_awaits"
+ assert (
+ await async_session.execute(
+ select(RefactoringSuggestion).where(
+ RefactoringSuggestion.repository_id == repo.id
+ )
+ )
+ ).scalars().first() is None
+
+
+async def test_a_repository_with_no_performance_findings_still_has_a_headline(
+ async_session,
+) -> None:
+ """A missing summary row means "never analyzed"; an empty one means clear.
+
+ Collapsing the two would make an index that has not run yet look healthy.
+ """
+ repo = await insert_repo(async_session)
+ assert await crud.get_performance_summary(async_session, repo.id) is None
+
+ await crud.finalize_performance_opportunities(async_session, repo.id)
+ summary = await crud.get_performance_summary(async_session, repo.id)
+ assert isinstance(summary, PerformanceSummary)
+ assert summary.opportunities_total == 0
+ assert json.loads(summary.summary_json)["lead"] is None
+
+
+async def test_a_rebuild_that_fails_halfway_leaves_the_previous_state(
+ async_session, monkeypatch
+) -> None:
+ """The queue must never describe findings that were never stored.
+
+ The incremental caller logs a failed health step and carries on to commit
+ the rest of the run, so the savepoint around the write is what stops a
+ half-finished rebuild from becoming the current answer.
+ """
+ from repowise.core.persistence.crud.analysis import performance as writer
+
+ repo = await insert_repo(async_session)
+ await _write(async_session, repo.id, _corpus(), analyzed_commit="1" * 40)
+ (before,) = await _rows(async_session, repo.id)
+
+ async def explode(*_args, **_kwargs):
+ raise RuntimeError("summary write failed")
+
+ monkeypatch.setattr(writer, "_write_summary", explode)
+ findings = [_finding("src/z.py", 40, marker="io_in_loop")]
+ link_performance_findings(findings)
+ with pytest.raises(RuntimeError):
+ async with async_session.begin_nested():
+ await crud.save_health_findings(async_session, repo.id, findings)
+ await crud.finalize_performance_opportunities(async_session, repo.id)
+
+ rows = await _rows(async_session, repo.id)
+ assert [(row.opportunity_id, row.status) for row in rows] == [
+ (before.opportunity_id, "open")
+ ]
+ summary = await crud.get_performance_summary(async_session, repo.id)
+ assert summary.analyzed_commit == "1" * 40
+ stored = (
+ (
+ await async_session.execute(
+ select(HealthFinding.file_path).where(
+ HealthFinding.repository_id == repo.id
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ assert sorted(stored) == ["src/a.py", "src/b.py", "src/c.py"]
+
+
+def _tables(db_path: Path) -> set[str]:
+ conn = sqlite3.connect(db_path)
+ try:
+ return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+ finally:
+ conn.close()
+
+
+def _columns(db_path: Path, table: str) -> set[str]:
+ conn = sqlite3.connect(db_path)
+ try:
+ return {row[1] for row in conn.execute(f'PRAGMA table_info("{table}")')}
+ finally:
+ conn.close()
+
+
+def test_the_migration_upgrades_and_rolls_back(tmp_path: Path) -> None:
+ """Explicit migration for managed stores, both directions.
+
+ Local stores are created by ``init_db`` and never see Alembic, which is why
+ the model declaration and this migration have to describe the same shape.
+ """
+ from alembic import command
+ from alembic.config import Config
+
+ root = Path(__file__).resolve().parents[3] / "packages" / "core"
+ db_path = tmp_path / "wiki.db"
+ # Built without the ini file on purpose. Passing it makes ``env.py`` call
+ # ``fileConfig``, which reconfigures logging for the rest of the session and
+ # silences the warnings other tests assert on.
+ config = Config()
+ config.set_main_option("script_location", str(root / "alembic"))
+ config.set_main_option("sqlalchemy.url", f"sqlite+aiosqlite:///{db_path}")
+
+ command.upgrade(config, "0057")
+ assert {"performance_opportunities", "performance_summaries"} <= _tables(db_path)
+ assert {"public_id", "opportunity_id"} <= _columns(db_path, "health_findings")
+ assert "opportunity_id" in _columns(db_path, "refactoring_suggestions")
+
+ command.downgrade(config, "0056")
+ assert not {"performance_opportunities", "performance_summaries"} & _tables(db_path)
+ assert not {"public_id", "opportunity_id"} & _columns(db_path, "health_findings")
+ assert "opportunity_id" not in _columns(db_path, "refactoring_suggestions")
diff --git a/tests/unit/persistence/test_refactoring_suggestions_crud.py b/tests/unit/persistence/test_refactoring_suggestions_crud.py
index 38421816d..3c60b7720 100644
--- a/tests/unit/persistence/test_refactoring_suggestions_crud.py
+++ b/tests/unit/persistence/test_refactoring_suggestions_crud.py
@@ -197,7 +197,14 @@ async def test_performance_only_partial_scope_clears_stale_plan(async_session):
@pytest.mark.asyncio
-async def test_partial_performance_scope_persists_downstream_intervention(async_session):
+async def test_a_partial_run_never_persists_its_own_performance_plans(async_session):
+ """A partial run sees a subset of the findings, so its plans are a subset.
+
+ The plans it carries are a report-level convenience. The authoritative ones
+ are rebuilt from the merged stored findings by the writer both index paths
+ share, which is also what retired the path bookkeeping this writer used to
+ need to reach a shared intervention downstream of its callers.
+ """
from repowise.core.pipeline.incremental import persist_partial_health
repo = await insert_repo(async_session)
@@ -224,7 +231,5 @@ async def test_partial_performance_scope_persists_downstream_intervention(async_
await persist_partial_health(async_session, repo.id, report)
await async_session.commit()
- rows = await get_refactoring_suggestions(async_session, repo.id)
- assert [(row.refactoring_type, row.file_path, row.target_symbol) for row in rows] == [
- ("performance_fix", "shared.py", "shared.py::load")
- ]
+ # No stored findings, so the rebuild leaves no performance plan behind.
+ assert await get_refactoring_suggestions(async_session, repo.id) == []
diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.py
index 43f046e32..83d2eb83e 100644
--- a/tests/unit/server/mcp/test_health.py
+++ b/tests/unit/server/mcp/test_health.py
@@ -21,7 +21,9 @@ async def test_get_health_dashboard(setup_mcp, health_data):
assert result["mode"] == "dashboard"
assert result["kpis"]["file_count"] == 2
assert result["kpis"]["worst_performer_path"] == "src/auth/service.py"
- assert list(result)[:2] == ["directive", "mode"]
+ # Two leads, both first: the defect one and the performance pillar's own,
+ # which carries no defect impact and so never competed for the first.
+ assert list(result)[:3] == ["directive", "performance_directive", "mode"]
assert "high_leverage_files" in result
assert "worst_files" not in result
assert result["secondary_rankings"]["worst_files"]["total"] == 2
@@ -388,11 +390,20 @@ async def test_combined_recommendation_lede_is_compact_and_self_directing(
}
],
)
+ # The queue is materialized, so the fixture's findings only reach the lede
+ # once the writer both index paths use has grouped them.
+ from repowise.core.persistence.crud import finalize_performance_opportunities
+
+ await finalize_performance_opportunities(session, health_data)
+ await session.commit()
+
result = await get_health(include=["performance", "refactoring"], only=["recommendation_lede"])
lede = result["recommendation_lede"]
assert set(result) <= {"mode", "recommendation_lede", "_meta"}
assert lede["performance_opportunities_total"] == 1
- assert lede["refactoring_plans_total"] == 1
+ # Two: the seeded extract-class plan, and the authoritative performance
+ # plan the finalizer generated for the fixture's own opportunity.
+ assert lede["refactoring_plans_total"] == 2
assert lede["performance_lead"]["boundary_kind"] == "db"
assert {"benefit", "leverage", "cost", "risk"} <= set(lede["recommendation_lead"])
assert "validation" not in lede["recommendation_lead"]
diff --git a/tests/unit/server/mcp/test_overview_surface.py b/tests/unit/server/mcp/test_overview_surface.py
index 7d674885b..63880b880 100644
--- a/tests/unit/server/mcp/test_overview_surface.py
+++ b/tests/unit/server/mcp/test_overview_surface.py
@@ -209,4 +209,12 @@ async def test_live_registry_recipe_calls_bind_to_current_tool_signatures(setup_
'get_health(include=["performance","refactoring"], '
'only=["performance_opportunities","refactoring_plans"])'
),
+ "health_performance_summary": (
+ 'get_health(include=["performance"], only=["performance_summary"])'
+ ),
+ "health_performance_opportunity": 'get_health(opportunity_id="perf...")',
+ "health_performance_evidence": (
+ 'get_health(opportunity_id="perf...", '
+ 'only=["performance_evidence"], cursor=0)'
+ ),
}
diff --git a/tests/unit/server/mcp/test_perf_rank.py b/tests/unit/server/mcp/test_perf_rank.py
index 2d8185d66..e590462e7 100644
--- a/tests/unit/server/mcp/test_perf_rank.py
+++ b/tests/unit/server/mcp/test_perf_rank.py
@@ -19,11 +19,11 @@ import uuid
import pytest
from repowise.core.analysis.health.biomarkers import registered_biomarkers
-from repowise.server.mcp_server.tool_health import (
- _PERF_MARKER_POINTS,
- _perf_rank,
- _rank_emitted,
+from repowise.core.analysis.health.perf.opportunity_rank import (
+ MULTIPLIER_POINTS,
+ UNKNOWN_MULTIPLIER_POINTS,
)
+from repowise.server.mcp_server.tool_health import _perf_rank, _rank_emitted
# ---------------------------------------------------------------------------
# The key itself
@@ -31,7 +31,12 @@ from repowise.server.mcp_server.tool_health import (
def test_every_performance_biomarker_carries_a_weight() -> None:
- """The weight table must not silently acquire a default.
+ """One weight table, and it must not silently acquire a default.
+
+ The observation key and the opportunity rank read the same table. They
+ used to keep one each and had already drifted apart on markers both named,
+ so a finding and the opportunity built from it disagreed about the same
+ evidence.
A detector added without a weight ranks at the floor, which is the safe
direction but also an invisible one — a new high-cost marker would sort
@@ -42,12 +47,12 @@ def test_every_performance_biomarker_carries_a_weight() -> None:
b.name for b in registered_biomarkers() if getattr(b, "category", "") == "performance"
}
assert registered, "no performance detectors registered — the check is vacuous"
- assert registered <= set(_PERF_MARKER_POINTS), (
- f"unweighted performance biomarkers: {sorted(registered - set(_PERF_MARKER_POINTS))}"
+ assert registered <= set(MULTIPLIER_POINTS), (
+ f"unweighted performance biomarkers: {sorted(registered - set(MULTIPLIER_POINTS))}"
)
# And no stale entries pointing at detectors that no longer exist.
- assert set(_PERF_MARKER_POINTS) <= registered, (
- f"weights for unregistered markers: {sorted(set(_PERF_MARKER_POINTS) - registered)}"
+ assert set(MULTIPLIER_POINTS) <= registered, (
+ f"weights for unregistered markers: {sorted(set(MULTIPLIER_POINTS) - registered)}"
)
@@ -91,7 +96,8 @@ def test_the_gated_markers_carry_their_hotness_proof() -> None:
def test_an_unknown_marker_sinks_rather_than_floats() -> None:
- assert _perf_rank("some_future_marker", {}) == min(_PERF_MARKER_POINTS.values())
+ assert _perf_rank("some_future_marker", {}) == UNKNOWN_MULTIPLIER_POINTS
+ assert min(MULTIPLIER_POINTS.values()) > UNKNOWN_MULTIPLIER_POINTS
def test_malformed_details_never_raise() -> None:
@@ -219,21 +225,22 @@ async def test_the_perf_head_is_the_costliest_findings_not_the_first_alphabetica
that was file order, so a small ``limit`` returned the cheapest findings in
the repo and called them the top ones.
- The base fixture's perf finding carries a non-zero impact, so it still leads
- — the key breaks ties *within* an impact tier and never reorders across one.
+ The base fixture's perf finding carries a non-zero impact, so it still
+ leads: the key breaks ties *within* an impact tier and never reorders
+ across one.
"""
from repowise.server.mcp_server import get_health
result = await get_health(include=["biomarkers", "performance"], limit=4)
assert [f["file_path"] for f in result["findings"]] == [
"src/auth/service.py",
+ "h_nested_db.py",
"i_spawn_xfn.py",
- "g_hot_spawn.py",
"f_db_xfn.py",
]
- # Rank 6 is a three-way tie (the base fixture's row, the cross-function db
- # N+1 and the nested db loop); ``file_path`` is what makes the order total.
- assert [f["perf_rank"] for f in result["findings"]] == [6, 8, 7, 6]
+ ranks = [f["perf_rank"] for f in result["findings"]]
+ # A tie at the top, broken by ``file_path`` so the order is total.
+ assert ranks[1] == ranks[2] > ranks[3]
# The total still describes the whole filtered set, so the cap stays visible.
assert result["findings_total"] == 10
@@ -256,17 +263,14 @@ async def test_perf_rank_is_absent_from_every_other_dimension(setup_mcp, perf_fi
@pytest.mark.asyncio
async def test_narrow_projection_leads_with_one_shared_causal_opportunity(
- setup_mcp, perf_findings, session, monkeypatch, tmp_path
+ setup_mcp, perf_findings, session
):
+ """One shared helper, five callers, one cause, and a recoverable tail."""
import json
- from repowise.core.distill.store import OmissionStore
+ from repowise.core.persistence.crud import finalize_performance_opportunities
from repowise.core.persistence.models import HealthFinding
from repowise.server.mcp_server import get_health
- from repowise.server.mcp_server._budget import collector as collector_module
-
- store_path = tmp_path / "omissions.db"
- monkeypatch.setattr(collector_module, "default_store_path", lambda _root: store_path)
for index, caller in enumerate(
("src/a.py", "src/b.py", "src/c.py", "src/d.py", "src/e.py"), start=10
@@ -296,8 +300,12 @@ async def test_narrow_projection_leads_with_one_shared_causal_opportunity(
)
)
await session.flush()
+ await finalize_performance_opportunities(session, perf_findings)
+ await session.commit()
- result = await get_health(include=["performance"], only=["performance_opportunities"], limit=50)
+ result = await get_health(
+ include=["performance"], only=["performance_opportunities"], limit=50
+ )
shared = [
item
for item in result["performance_opportunities"]
@@ -311,47 +319,21 @@ async def test_narrow_projection_leads_with_one_shared_causal_opportunity(
assert {item["function_name"] for item in shared[0]["evidence"]} == {"run"}
assert shared[0]["evidence_total"] == 5
assert shared[0]["evidence_emitted"] == 3
- assert shared[0]["evidence_reduced_reason"] == "evidence_cap"
- refs = result["_meta"]["omitted"]["refs"]
- assert len(refs) == 1
- store = OmissionStore(store_path)
- try:
- omitted = store.get(refs[0]) or ""
- finally:
- store.close()
- assert '"line_start": 13' in omitted
- assert '"line_start": 14' in omitted
- assert '"line_start": 10' not in omitted
- assert result["performance_opportunities_total"] >= 1
- assert "top_findings" not in result
-
-
-async def test_the_default_dashboard_does_not_pay_for_the_ranking_read(
- setup_mcp, perf_findings, monkeypatch
-):
- """``details_json`` joins the narrow read only when perf can reach the head.
-
- Every perf finding carries impact 0, so in a mixed list all the defect
- findings sort above them and the rank cannot move a row — paying for the
- column there would be 6.6ms bought for nothing. This asserts the *read*:
- the response is identical either way, so a payload-only test would pass on
- the unfixed code.
- """
- from repowise.server.mcp_server import get_health, tool_health
-
- selected: list[list[str]] = []
- real = tool_health.select
-
- def spy(*cols):
- selected.append([getattr(c, "key", str(c)) for c in cols])
- return real(*cols)
-
- monkeypatch.setattr(tool_health, "select", spy)
-
- await get_health()
- assert not any("details_json" in cols for cols in selected)
-
- selected.clear()
- await get_health(include=["biomarkers", "performance"])
- assert any("details_json" in cols for cols in selected)
+ assert shared[0]["evidence_reduced_reason"] == "evidence_page"
+
+ # The tail is recovered by paging it, not by unpacking an omission blob.
+ # A blob would have cost the full read of every observation to build.
+ tail = await get_health(
+ opportunity_id=shared[0]["opportunity_id"],
+ only=["performance_evidence"],
+ cursor=shared[0]["evidence_next_cursor"],
+ limit=50,
+ )
+ assert [item["line_start"] for item in tail["evidence"]] == [13, 14]
+ assert tail["evidence_total"] == 5
+ assert "evidence_next_cursor" not in tail
+
+ # And every reference round-trips through the finding selector.
+ detail = await get_health(finding_id=tail["evidence"][0]["finding_id"])
+ assert detail["resolved"] is True
+ assert detail["finding"]["file_path"] == "src/d.py"
diff --git a/tests/unit/server/mcp/test_performance_levels.py b/tests/unit/server/mcp/test_performance_levels.py
new file mode 100644
index 000000000..26a0ca51f
--- /dev/null
+++ b/tests/unit/server/mcp/test_performance_levels.py
@@ -0,0 +1,452 @@
+"""The agent contract for performance: actionable by default, deep on demand.
+
+Four levels, one read model. The dashboard leads with something to do, the
+summary rolls it up, the queue pages it, and one id drills all the way to
+evidence and back out through the finding selector. The REST surface is the
+same projection of the same rows, which is what these tests hold it to.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+
+import pytest
+from sqlalchemy import event
+from sqlalchemy.engine import Engine
+
+from repowise.core.persistence.crud import finalize_performance_opportunities
+from repowise.core.persistence.models import HealthFinding
+
+_CALLERS = ("src/a.py", "src/b.py", "src/c.py", "src/d.py", "src/e.py")
+
+
+def _row(repo_id: str, caller: str, line: int) -> HealthFinding:
+ return HealthFinding(
+ id=str(uuid.uuid4()),
+ repository_id=repo_id,
+ file_path=caller,
+ biomarker_type="serial_await_in_loop",
+ severity="medium",
+ function_name="run",
+ line_start=line,
+ line_end=line,
+ details_json=json.dumps(
+ {
+ "boundary_kind": "db",
+ "cross_function": True,
+ "path": [f"{caller}::run", "src/shared.py::load", "src/db.py::fetch"],
+ "resolution_basis": "call-site",
+ "dataflow_verified": True,
+ }
+ ),
+ health_impact=0.0,
+ reason="Awaited database work repeats for every loop iteration.",
+ dimension="performance",
+ status="open",
+ )
+
+
+async def materialized(session, health_data: str) -> str:
+ """Five callers behind one shared helper, plus the base fixture's own row.
+
+ The fixture contributes a second production cause, which is why the totals
+ below are two rather than one.
+ """
+ for index, caller in enumerate(_CALLERS, start=10):
+ session.add(_row(health_data, caller, index))
+ await session.flush()
+ await finalize_performance_opportunities(session, health_data, analyzed_commit="c" * 40)
+ await session.commit()
+ return health_data
+
+
+class _Statements:
+ """Counts statements on every engine, including ones a tool opens itself."""
+
+ def __init__(self) -> None:
+ self.n = 0
+
+ def __enter__(self):
+ event.listen(Engine, "before_cursor_execute", self._hit)
+ return self
+
+ def __exit__(self, *_exc) -> None:
+ event.remove(Engine, "before_cursor_execute", self._hit)
+
+ def _hit(self, *_args, **_kwargs) -> None:
+ self.n += 1
+
+
+async def test_a_bare_dashboard_leads_with_something_to_do(setup_mcp, materialized):
+ """Performance carries no defect impact, so it never won the main lead.
+
+ The dashboard reported counts and nothing an agent could act on. The
+ additive lead is one primary-key read of the current summary row.
+ """
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health()
+ directive = result["performance_directive"]
+ assert directive["status"] == "plan_ready"
+ assert directive["opportunity_id"].startswith("perf")
+ assert directive["plan_state"] == "available"
+ assert directive["next_action"] == {
+ "tool": "get_health",
+ "arguments": {"opportunity_id": directive["opportunity_id"]},
+ }
+ assert 0 < len(json.dumps(directive)) <= 1500
+ # The existing lead is untouched.
+ assert "directive" in result
+
+
+async def test_the_cheapest_documented_call_stays_cheap(setup_mcp, materialized):
+ """``only=["directive"]`` must not start paying for the second lead."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(only=["directive"])
+ assert "performance_directive" not in result
+ assert "directive" in result
+
+
+async def test_a_clear_repository_never_reports_that_it_is_fast(setup_mcp, health_data):
+ """No supported pattern is not a measurement of how the code runs."""
+ from repowise.core.persistence.crud import finalize_performance_opportunities as finalize
+ from repowise.server.mcp_server import _state, get_health
+
+ async with _state._session_factory() as session:
+ await session.execute(
+ HealthFinding.__table__.delete().where(HealthFinding.dimension == "performance")
+ )
+ await finalize(session, health_data)
+ await session.commit()
+ directive = (await get_health())["performance_directive"]
+ assert directive["status"] == "clear"
+ assert "fast" not in directive["detail"].lower()
+
+
+async def test_an_unanalyzed_index_is_unavailable_not_clear(setup_mcp, health_data):
+ """A missing materialization must not read as a clean repository."""
+ from repowise.server.mcp_server import get_health
+
+ directive = (await get_health())["performance_directive"]
+ assert directive["status"] == "unavailable"
+ assert directive["reason"] == "no_materialized_analysis"
+
+
+async def test_the_summary_rolls_up_and_names_the_next_call(setup_mcp, materialized):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(include=["performance"], only=["performance_summary"])
+ summary = result["performance_summary"]
+ assert summary["status"] == "current"
+ assert summary["actionability"]["plan_ready"] == 1
+ assert summary["with_plan_total"] == 2
+ assert summary["analyzed_commit"] == "c" * 40
+ assert "get_health" in summary["next_call"]
+ assert len(json.dumps(summary)) <= 3000
+
+
+async def test_the_queue_filters_before_it_caps(setup_mcp, materialized):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(
+ include=["performance"],
+ only=["performance_opportunities"],
+ performance_context="production",
+ performance_boundary="db",
+ )
+ assert result["performance_opportunities_total"] == 2
+ assert {
+ item["execution_context"] for item in result["performance_opportunities"]
+ } == {"production"}
+
+ narrowed = await get_health(
+ include=["performance"],
+ only=["performance_opportunities"],
+ performance_confidence="medium",
+ )
+ assert narrowed["performance_opportunities_total"] == 0
+
+ empty = await get_health(
+ include=["performance"],
+ only=["performance_opportunities"],
+ performance_context="test",
+ )
+ assert empty["performance_opportunities_total"] == 0
+
+
+async def test_an_unrecognized_filter_value_is_named_not_silently_empty(
+ setup_mcp, materialized
+):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(
+ include=["performance"],
+ only=["performance_opportunities"],
+ performance_context="staging",
+ )
+ assert result["performance_opportunities_total"] == 2
+ assert result["ignored_arguments"] == {"performance_context": "staging"}
+
+
+async def test_the_summary_view_omits_evidence_without_changing_identity(
+ setup_mcp, materialized
+):
+ from repowise.server.mcp_server import get_health
+
+ detailed = await get_health(include=["performance"], only=["performance_opportunities"])
+ summary = await get_health(
+ include=["performance"],
+ only=["performance_opportunities"],
+ performance_view="summary",
+ )
+ assert (
+ detailed["performance_opportunities"][0]["opportunity_id"]
+ == summary["performance_opportunities"][0]["opportunity_id"]
+ )
+ assert "facets" not in summary["performance_opportunities"][0]
+ assert "facets" in detailed["performance_opportunities"][0]
+
+
+async def test_one_id_returns_the_cause_its_plan_and_its_rank_rationale(
+ setup_mcp, materialized
+):
+ from repowise.server.mcp_server import get_health
+
+ lead = (await get_health())["performance_directive"]["opportunity_id"]
+ result = await get_health(opportunity_id=lead)
+
+ assert result["mode"] == "performance_opportunity"
+ assert result["resolved"] is True
+ assert result["opportunity_id"] == lead
+ assert result["intervention_symbol"] == "src/shared.py::load"
+ assert result["plan_status"] == "available"
+ assert result["plan_reference"].startswith("plan_")
+ assert result["confidence"] == "high"
+ assert result["fix"]["safety"] == "proven"
+ assert result["facets"]["leverage"] == "shared"
+ assert result["why_ranked"]
+ assert len(json.dumps(result)) <= 20_000
+
+ # The plan reference resolves through the plan selector.
+ plan = await get_health(plan_id=result["plan_reference"])
+ assert plan["resolved"] is True
+
+
+async def test_evidence_pages_to_exhaustion_with_no_duplicate_or_missing_row(
+ setup_mcp, materialized
+):
+ from repowise.server.mcp_server import get_health
+
+ lead = (await get_health())["performance_directive"]["opportunity_id"]
+ seen: list[str] = []
+ cursor: int | None = 0
+ while cursor is not None:
+ page = await get_health(
+ opportunity_id=lead, only=["performance_evidence"], cursor=cursor, limit=2
+ )
+ seen.extend(item["finding_id"] for item in page["evidence"])
+ cursor = page.get("evidence_next_cursor")
+ assert len(seen) == len(set(seen)) == 5
+
+
+async def test_every_evidence_reference_round_trips_through_the_finding_selector(
+ setup_mcp, materialized
+):
+ """Evidence used to carry the storage row id, which a reindex replaces."""
+ from repowise.server.mcp_server import get_health
+
+ lead = (await get_health())["performance_directive"]["opportunity_id"]
+ page = await get_health(opportunity_id=lead, only=["performance_evidence"], limit=50)
+ for item in page["evidence"]:
+ resolved = await get_health(finding_id=item["finding_id"])
+ assert resolved["resolved"] is True
+ assert resolved["finding"]["file_path"] == item["file_path"]
+ assert resolved["finding"]["id"] == item["finding_id"]
+
+
+async def test_asking_for_no_rows_returns_no_rows(setup_mcp, materialized):
+ """``limit=0`` is the documented way to ask for the totals and nothing else.
+
+ Reading it as "unset" would hand back a page the caller declined, which is
+ the same defect the ranked collections already fixed.
+ """
+ from repowise.server.mcp_server import get_health
+
+ lead = (await get_health())["performance_directive"]["opportunity_id"]
+ page = await get_health(
+ opportunity_id=lead, only=["performance_evidence"], limit=0
+ )
+ assert page["evidence"] == []
+ assert page["evidence_total"] == 5
+ assert page["evidence_next_cursor"] == 0
+
+ detail = await get_health(opportunity_id=lead, limit=0)
+ assert detail["evidence"] == []
+ assert detail["evidence_total"] == 5
+
+
+async def test_the_summary_costs_the_same_however_many_causes_there_are(
+ setup_mcp, materialized, session
+):
+ """The facet aggregate reads every open cause; its query count must not."""
+ from repowise.server.mcp_server import get_health
+
+ with _Statements() as small:
+ await get_health(include=["performance"], only=["performance_summary"])
+
+ for index in range(40):
+ row = _row(materialized, f"src/bulk_{index}.py", 500 + index)
+ row.details_json = row.details_json.replace(
+ "src/db.py::fetch", f"src/db.py::fetch_{index}"
+ )
+ session.add(row)
+ await session.flush()
+ await finalize_performance_opportunities(session, materialized)
+ await session.commit()
+
+ with _Statements() as large:
+ result = await get_health(include=["performance"], only=["performance_summary"])
+ assert result["performance_summary"]["total"] > 40
+ assert large.n == small.n
+ assert {entry["value"] for entry in result["performance_summary"]["facets"]["context"]}
+
+
+async def test_an_id_from_an_older_model_reports_stale_and_how_to_refresh(
+ setup_mcp, materialized
+):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(opportunity_id="perf_0123456789abcdef0123")
+ assert result["resolved"] is False
+ assert result["model_state"]["state"] == "stale_model"
+ assert result["model_state"]["refresh_required"] is True
+ assert "repowise update" in result["detail"]
+
+ unknown = await get_health(opportunity_id="not-an-id")
+ assert unknown["model_state"]["state"] == "unrecognized"
+
+
+async def test_two_detail_selectors_conflict_explicitly(setup_mcp, materialized):
+ """Preferring one silently answered confidently about the wrong question."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(finding_id="finding_x", opportunity_id="perf2_x")
+ assert result["mode"] == "conflict"
+ assert result["resolved"] is False
+ assert result["selectors"] == ["finding_id", "opportunity_id"]
+
+
+async def test_the_lede_links_the_exact_plan_for_the_exact_lead(setup_mcp, materialized):
+ """This used to match on a key the plan writer never wrote, so it was null."""
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(
+ include=["performance", "refactoring"], only=["recommendation_lede"]
+ )
+ lede = result["recommendation_lede"]
+ assert lede["performance_plan_id"] is not None
+ assert lede["performance_plan_id"].startswith("plan_")
+ plan = await get_health(plan_id=lede["performance_plan_id"])
+ assert plan["resolved"] is True
+
+
+async def test_the_queue_costs_the_same_however_many_opportunities_there_are(
+ setup_mcp, materialized, session
+):
+ """Query count is what this holds: wall clock on a laptop is not evidence."""
+ from repowise.server.mcp_server import get_health
+
+ with _Statements() as small:
+ await get_health(include=["performance"], only=["performance_opportunities"], limit=2)
+
+ for index in range(40):
+ # A distinct sink per row, so these are forty causes rather than one.
+ row = _row(materialized, f"src/bulk_{index}.py", 500 + index)
+ row.details_json = row.details_json.replace(
+ "src/db.py::fetch", f"src/db.py::fetch_{index}"
+ )
+ session.add(row)
+ await session.flush()
+ await finalize_performance_opportunities(session, materialized)
+ await session.commit()
+
+ with _Statements() as large:
+ result = await get_health(
+ include=["performance"], only=["performance_opportunities"], limit=2
+ )
+ assert result["performance_opportunities_total"] > 40
+ assert large.n == small.n
+ assert len(result["performance_opportunities"]) == 2
+
+
+async def test_rest_and_the_agent_surface_project_the_same_rows(
+ setup_mcp, materialized, factory
+):
+ """Two adapters, one service. Order, totals, identity, and plan state agree."""
+ from repowise.server.mcp_server import get_health
+ from repowise.server.routers.code_health.performance_routes import (
+ list_performance_opportunities,
+ )
+
+ agent = await get_health(
+ include=["performance"], only=["performance_opportunities"], limit=6
+ )
+ async with factory() as session:
+ rest = await list_performance_opportunities(
+ materialized,
+ context="all",
+ boundary=None,
+ confidence=None,
+ actionability=None,
+ view="detail",
+ sort="rank",
+ limit=6,
+ offset=0,
+ session=session,
+ )
+
+ assert rest["total"] == agent["performance_opportunities_total"]
+ shared = (
+ "opportunity_id",
+ "rank_position",
+ "actionability_state",
+ "execution_context",
+ "boundary_kind",
+ "plan_status",
+ "confidence",
+ "observations_total",
+ "affected_call_sites_total",
+ )
+ assert [{key: item[key] for key in shared} for item in rest["items"]] == [
+ {key: item[key] for key in shared} for item in agent["performance_opportunities"]
+ ]
+ # Two address spaces for the same plan: the row id this surface's own
+ # detail route resolves, and the reference the agent selector resolves.
+ assert all(item["plan_id"] for item in rest["items"] if item["plan_status"] == "available")
+ assert "plan_reference" not in rest["items"][0]
+ assert all(
+ item["plan_reference"]
+ for item in agent["performance_opportunities"]
+ if item["plan_status"] == "available"
+ )
diff --git a/tests/unit/server/test_performance_opportunities.py b/tests/unit/server/test_performance_opportunities.py
index 17bb96513..8e2fabb0c 100644
--- a/tests/unit/server/test_performance_opportunities.py
+++ b/tests/unit/server/test_performance_opportunities.py
@@ -1,18 +1,20 @@
-"""Bounded causal performance product API and exact plan handoff."""
+"""Bounded causal performance product API and exact plan handoff.
+
+Every case seeds through the writer that both index paths use, because the
+queue is materialized: findings alone are no longer a queue, and a test that
+inserted findings and read the surface would be testing a state the product
+never reaches.
+"""
from __future__ import annotations
from httpx import AsyncClient
+from sqlalchemy import select
from repowise.core.analysis.health.models import HealthFindingData, Severity
-from repowise.core.analysis.health.perf.opportunities import (
- build_performance_opportunities,
- link_performance_findings,
-)
-from repowise.core.analysis.health.refactoring.performance_fix import (
- performance_fix_suggestions,
-)
+from repowise.core.analysis.health.perf.opportunities import link_performance_findings
from repowise.core.persistence import crud
+from repowise.core.persistence.models import PerformanceOpportunity
from tests.unit.server.conftest import create_test_repo
@@ -36,9 +38,8 @@ def _finding(path: str, line: int, path_nodes: list[str], *, marker: str = "io_i
)
-async def _seed(app, client: AsyncClient) -> tuple[str, str]:
- repo = await create_test_repo(client)
- findings = [
+def _findings() -> list:
+ return [
_finding("src/a.py", 10, ["src/a.py::run", "src/shared.py::load", "src/db.py::fetch"]),
_finding("src/b.py", 20, ["src/b.py::run", "src/shared.py::load", "src/db.py::fetch"]),
# A separate test-suite cause with no coherent shared intervention.
@@ -49,49 +50,63 @@ async def _seed(app, client: AsyncClient) -> tuple[str, str]:
marker="serial_await_in_loop",
),
]
+
+
+async def _materialize(app, repo_id: str, findings: list) -> None:
link_performance_findings(findings)
- opportunities = build_performance_opportunities(findings)
- production = next(item for item in opportunities if item.execution_context == "production")
- plans = performance_fix_suggestions([production])
async with app.state.session_factory() as session:
- await crud.save_health_findings(session, repo["id"], findings)
- await crud.save_refactoring_suggestions(session, repo["id"], plans)
+ await crud.save_health_findings(session, repo_id, findings)
+ await crud.finalize_performance_opportunities(
+ session, repo_id, analyzed_commit="a" * 40
+ )
await session.commit()
- return repo["id"], production.opportunity_id
-async def test_opportunities_are_grouped_bounded_and_split_by_context(
- client: AsyncClient, app
-) -> None:
- repo_id, opportunity_id = await _seed(app, client)
- production = (
- await client.get(
- f"/api/repos/{repo_id}/health/performance-opportunities", params={"limit": 1}
+async def _seed(app, client: AsyncClient, findings: list | None = None) -> tuple[str, str]:
+ repo = await create_test_repo(client)
+ await _materialize(app, repo["id"], _findings() if findings is None else findings)
+ async with app.state.session_factory() as session:
+ rows = (
+ (
+ await session.execute(
+ select(PerformanceOpportunity).where(
+ PerformanceOpportunity.repository_id == repo["id"],
+ PerformanceOpportunity.execution_context == "production",
+ )
+ )
+ )
+ .scalars()
+ .all()
)
- ).json()
+ return repo["id"], rows[0].opportunity_id if rows else ""
- assert len(production["items"]) == 1
- assert production["items"][0]["opportunity_id"] == opportunity_id
- assert production["items"][0]["affected_call_sites_total"] == 2
- assert production["items"][0]["confidence"] == "medium"
- assert production["items"][0]["plan_status"] == "available"
- assert production["items"][0]["plan_id"]
- assert production["summary"] == {
- "total": 2,
- "production_total": 1,
- "tooling_total": 0,
- "test_total": 1,
- "unknown_total": 0,
- "with_plan_total": 1,
- "without_plan_total": 1,
- }
- test_page = (
+async def _page(client: AsyncClient, repo_id: str, **params) -> dict:
+ return (
await client.get(
- f"/api/repos/{repo_id}/health/performance-opportunities",
- params={"context": "test"},
+ f"/api/repos/{repo_id}/health/performance-opportunities", params=params
)
).json()
+
+
+async def test_opportunities_are_grouped_bounded_and_split_by_context(
+ client: AsyncClient, app
+) -> None:
+ repo_id, opportunity_id = await _seed(app, client)
+ page = await _page(client, repo_id, context="production", limit=1)
+
+ assert len(page["items"]) == 1
+ assert page["items"][0]["opportunity_id"] == opportunity_id
+ assert page["items"][0]["affected_call_sites_total"] == 2
+ assert page["items"][0]["confidence"] == "medium"
+ assert page["items"][0]["plan_status"] == "available"
+ assert page["items"][0]["plan_id"]
+ assert page["summary"]["total"] == 2
+ assert page["summary"]["context"] == {"production": 1, "test": 1}
+ assert page["summary"]["with_plan_total"] == 1
+ assert page["summary"]["status"] == "current"
+
+ test_page = await _page(client, repo_id, context="test")
assert test_page["total"] == 1
assert test_page["items"][0]["plan_id"] is None
assert test_page["items"][0]["plan_status"] == "no_safe_plan"
@@ -115,13 +130,15 @@ async def test_raw_evidence_is_paged_and_plan_matching_never_falls_back(
).json()
assert first["total"] == 2
assert len(first["items"]) == len(second["items"]) == 1
- assert first["items"][0]["id"] != second["items"][0]["id"]
+ assert first["items"][0]["finding_id"] != second["items"][0]["finding_id"]
+ # A public reference, never the storage row id a reindex replaces.
+ assert first["items"][0]["finding_id"].startswith("finding_")
async with app.state.session_factory() as session:
rows = await crud.get_refactoring_suggestions(session, repo_id)
- rows[0].plan_json = '{"opportunity_id":"unrelated"}'
+ rows[0].opportunity_id = "unrelated"
await session.commit()
- page = (await client.get(f"/api/repos/{repo_id}/health/performance-opportunities")).json()
+ page = await _page(client, repo_id, context="production")
assert page["items"][0]["plan_id"] is None
assert page["items"][0]["plan_status"] == "not_persisted"
@@ -132,22 +149,165 @@ async def test_an_unclassifiable_file_is_counted_and_stays_visible(app, client:
Reporting an unclassifiable file as production was the thing to fix. Losing
it from every view instead would be the same mistake pointing the other way.
"""
- repo = await create_test_repo(client)
- findings = [
- _finding(
- "docs/snippets/walk.py",
- 10,
- ["docs/snippets/walk.py::demo", "src/shared.py::load", "src/db.py::fetch"],
+ repo_id, _ = await _seed(
+ app,
+ client,
+ [
+ _finding(
+ "docs/snippets/walk.py",
+ 10,
+ ["docs/snippets/walk.py::demo", "src/shared.py::load", "src/db.py::fetch"],
+ )
+ ],
+ )
+ body = await _page(client, repo_id, context="all")
+ assert body["summary"]["context"] == {"unknown": 1}
+ assert [item["execution_context"] for item in body["items"]] == ["unknown"]
+ assert (await _page(client, repo_id, context="unknown"))["total"] == 1
+
+
+async def test_the_retired_context_spelling_still_answers_but_is_never_echoed(
+ app, client: AsyncClient
+) -> None:
+ """An older client asked 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.
+ """
+ repo_id, _ = await _seed(app, client)
+ body = await _page(client, repo_id, context="production_tooling")
+ assert body["total"] == 1
+ assert [item["execution_context"] for item in body["items"]] == ["production"]
+ assert "production_tooling" not in body["summary"]["context"]
+
+
+async def test_an_unrecognized_filter_value_is_reported_not_read_as_no_data(
+ app, client: AsyncClient
+) -> None:
+ """Silently emptying the queue would look like a clean repository."""
+ repo_id, _ = await _seed(app, client)
+ body = await _page(client, repo_id, context="staging", boundary="pigeon")
+ assert body["total"] == 2
+ assert body["ignored_arguments"] == {
+ "performance_context": "staging",
+ "performance_boundary": "pigeon",
+ }
+
+
+async def test_facets_keep_the_alternatives_a_selected_filter_would_erase(
+ app, client: AsyncClient
+) -> None:
+ """A facet counted under its own filter reports every other value as zero."""
+ repo_id, _ = await _seed(app, client)
+ facets = (await _page(client, repo_id, context="test"))["facets"]
+ assert {entry["value"] for entry in facets["context"]} == {"production", "test"}
+ assert {entry["value"]: entry["total"] for entry in facets["context"]}["production"] == 1
+ # A filter on another dimension does narrow this one.
+ assert (await _page(client, repo_id, boundary="network"))["facets"]["context"] == []
+
+
+async def test_an_id_from_an_older_model_reports_stale_rather_than_no_plan(
+ app, client: AsyncClient
+) -> None:
+ """A first-model id used to fail to match, which read as nothing to do."""
+ repo_id, _ = await _seed(app, client)
+ body = (
+ await client.get(
+ f"/api/repos/{repo_id}/health/performance-opportunities/perf_0123456789abcdef0123"
)
- ]
- link_performance_findings(findings)
+ ).json()
+ assert body["resolved"] is False
+ assert body["model_state"]["state"] == "stale_model"
+ assert body["model_state"]["refresh_required"] is True
+ assert "repowise update" in body["detail"]
+
+
+async def test_detail_carries_the_facets_and_evidence_for_one_cause(
+ app, client: AsyncClient
+) -> None:
+ repo_id, opportunity_id = await _seed(app, client)
+ body = (
+ await client.get(
+ f"/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}",
+ params={"evidence_limit": 1},
+ )
+ ).json()
+ assert body["resolved"] is True
+ assert body["lifecycle_status"] == "open"
+ assert body["analyzed_commit"] == "a" * 40
+ assert body["model_state"]["state"] == "current"
+ assert set(body["facets"]) == {
+ "actionability_confidence",
+ "exposure",
+ "amplification",
+ "leverage",
+ "change_risk",
+ }
+ assert body["evidence_total"] == 2
+ assert body["evidence_emitted"] == 1
+ assert body["evidence_next_cursor"] == 1
+ assert body["plan_status"] == "available"
+
+
+async def test_a_cause_that_stops_being_observed_is_resolved_not_deleted(
+ app, client: AsyncClient
+) -> None:
+ """A held id has to keep answering after the code was fixed."""
+ repo_id, opportunity_id = await _seed(app, client)
+ await _materialize(app, repo_id, [_findings()[2]])
+
+ page = await _page(client, repo_id, context="all")
+ assert [item["opportunity_id"] for item in page["items"]] != [opportunity_id]
+ detail = (
+ await client.get(
+ f"/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}"
+ )
+ ).json()
+ assert detail["resolved"] is True
+ assert detail["lifecycle_status"] == "resolved"
+
+
+async def test_an_alternative_order_is_applied_before_the_page_not_after(
+ app, client: AsyncClient
+) -> None:
+ """Sorting the fetched page would order twenty rows right and the repo wrong."""
+ repo_id, opportunity_id = await _seed(app, client)
+ by_leverage = await _page(client, repo_id, context="all", sort="leverage", limit=1)
+ assert by_leverage["total"] == 2
+ # The production cause carries two call sites; the test one carries a
+ # single site, so leverage puts production first whatever its rank is.
+ assert by_leverage["items"][0]["opportunity_id"] == opportunity_id
+ assert by_leverage["items"][0]["affected_call_sites_total"] == 2
+
+
+async def test_a_page_costs_the_page_not_the_repository(app, client: AsyncClient) -> None:
+ """Two hundred unrelated findings must not reach the performance queue."""
+ repo_id, _ = await _seed(app, client)
async with app.state.session_factory() as session:
- await crud.save_health_findings(session, repo["id"], findings)
+ await crud.save_health_findings(
+ session,
+ repo_id,
+ [
+ HealthFindingData(
+ biomarker_type="long_function",
+ severity=Severity.MEDIUM,
+ file_path=f"src/noise_{index}.py",
+ function_name="run",
+ line_start=index,
+ line_end=index,
+ details={},
+ health_impact=1.0,
+ reason="Unrelated defect finding.",
+ dimension="defect",
+ )
+ for index in range(200)
+ ]
+ + _findings(),
+ )
+ await crud.finalize_performance_opportunities(session, repo_id)
await session.commit()
- response = await client.get(
- f"/api/repos/{repo['id']}/health/performance-opportunities", params={"context": "all"}
- )
- body = response.json()
- assert body["summary"]["unknown_total"] == 1
- assert [item["execution_context"] for item in body["items"]] == ["unknown"]
+ page = await _page(client, repo_id, context="all", limit=1)
+ assert page["total"] == 2
+ assert len(page["items"]) == 1
+ assert page["summary"]["total"] == 2