Skip to content

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

fix(health): state the performance queue's reason on every finding and settle example-path contexts (#3612)

Raghav Chamadiya7780888f8efc
diff --git a/docs/layers/PERFORMANCE.md b/docs/layers/PERFORMANCE.md
index f6269224a..9dd8034ea 100644
--- a/docs/layers/PERFORMANCE.md
+++ b/docs/layers/PERFORMANCE.md
@@ -87,7 +87,10 @@ Everything else is counted by reason, not hidden:
| `cold_role` | Only startup, a CLI command, tooling, tests or client UI code run the loop, so no server pays it per request |
| `background_unproven` | A scheduled job runs the loop and nothing shows it grows with the data; listed under `proof=background_unproven` |
-To see them, widen the filter (below). Performance work also appears in
+To see them, widen the filter (below). Each performance finding also stores the reason its cause is in or out of the queue.
+Code in a package path that only looks like an example tree (`com/example/...`) is judged as production when the index read it as production.
+
+Performance work also appears in
[Fix first](CODE_HEALTH.md#fix-first), where it competes with other kinds of work.
## Reading it
diff --git a/packages/core/src/repowise/core/analysis/health/perf/causal.py b/packages/core/src/repowise/core/analysis/health/perf/causal.py
index ae9060b6d..b19d9d521 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/causal.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/causal.py
@@ -17,6 +17,7 @@ import hashlib
import json
import re
from collections import defaultdict
+from collections.abc import Iterable, Mapping
from typing import Any, Literal
from repowise.core.code_origin import path_origin
@@ -103,6 +104,25 @@ def execution_context(file_path: str) -> ExecutionContext:
return context
+def settled_context(
+ context: ExecutionContext, files: Iterable[str], origins: Mapping[str, str | None]
+) -> ExecutionContext:
+ """The context a cause is stored and queued in; never a kernel input.
+
+ ``unknown`` under a directory is an example, demo or docs token somewhere
+ in the path, and a JVM package (``com/example/...``) matches one. The
+ stored ``code_origin`` read the file and reads those tokens near the
+ module root only, so its ``production`` for every file settles it. A
+ root-level file stays ``unknown``.
+ """
+ if context != "unknown":
+ return context
+ paths = list(files)
+ if paths and all("/" in path and origins.get(path) == "production" for path in paths):
+ return "production"
+ return context
+
+
def cost_shape(marker: str) -> str:
"""Compatibility family for observations that may share one intervention."""
if marker in {"io_in_loop", "nested_loop_with_io"}:
@@ -291,6 +311,7 @@ __all__ = [
"model_state",
"opportunity_id_for_finding",
"opportunity_id_model_version",
+ "settled_context",
"shared_helper",
"shared_path_suffix",
"stable_id",
diff --git a/packages/core/src/repowise/core/analysis/health/perf/opportunities.py b/packages/core/src/repowise/core/analysis/health/perf/opportunities.py
index af6da8b17..6a18dc201 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/opportunities.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/opportunities.py
@@ -16,6 +16,7 @@ The orchestration below holds no policy of its own.
from __future__ import annotations
+from collections.abc import Mapping
from dataclasses import dataclass
from typing import Any
@@ -46,6 +47,7 @@ from .causal import (
model_state,
opportunity_id_for_finding,
opportunity_id_model_version,
+ settled_context,
shared_path_suffix,
stable_id,
)
@@ -216,16 +218,20 @@ def _facets(r: _Reading, confidence: str) -> dict[str, str]:
}
-def _assemble(key: Any, members: list[Any], cap: int) -> PerformanceOpportunity:
+def _assemble(
+ key: Any, members: list[Any], cap: int, origins: Mapping[str, str | None]
+) -> PerformanceOpportunity:
"""Read one group's answers off its owners. Decides nothing itself.
Context, boundary, and intervention are kernel inputs, so the group
already agrees on them by construction. Taking them off the key keeps one
- owner for each instead of reclassifying a representative row. Sinks are
- members' facts, so they are listed rather than assumed shared. Everything
- else comes from :func:`_read_live`; inert members are listed last.
+ owner for each instead of reclassifying a representative row. A stored
+ origin may settle an ``unknown`` context; the id keeps the key's. Sinks
+ are members' facts, so they are listed rather than assumed shared.
+ Everything else comes from :func:`_read_live`; inert members are listed
+ last.
"""
- context = key_context(key)
+ context = settled_context(key_context(key), {facts.file_path for facts in members}, origins)
boundary = key_boundary(key)
r = _read_live(members)
evidence_confidence = provenance_confidence(r.provenance)
@@ -296,14 +302,21 @@ def _assemble(key: Any, members: list[Any], cap: int) -> PerformanceOpportunity:
def build_performance_opportunities(
- findings: list[Any], *, evidence_limit: int = 8
+ findings: list[Any],
+ *,
+ evidence_limit: int = 8,
+ origins: Mapping[str, str | None] | None = None,
) -> list[PerformanceOpportunity]:
- """Group, link, and rank performance rows in one deterministic pass."""
+ """Group, link, and rank performance rows in one deterministic pass.
+
+ *origins* is each file's stored ``code_origin``, which settles an
+ ``unknown`` context (:func:`.causal.settled_context`).
+ """
cap = max(0, evidence_limit)
opportunities: list[PerformanceOpportunity] = []
sites: dict[str, set[Any]] = {}
for key, members in group_observations(findings).items():
- opportunity = _assemble(key, members, cap)
+ opportunity = _assemble(key, members, cap, origins or {})
opportunities.append(opportunity)
sites[opportunity.opportunity_id] = {facts.site for facts in members}
return link_siblings(opportunities, sites, rank_sort_key)
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
index f48cc9cad..7a01ac8a4 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
@@ -20,7 +20,9 @@ from typing import TYPE_CHECKING, Any, NamedTuple
from sqlalchemy import delete, func, select, update
from sqlalchemy.ext.asyncio import AsyncSession
+from ...batches import chunked
from ...models import (
+ HealthFileMetric,
HealthFinding,
PerformanceOpportunity,
PerformanceSummary,
@@ -48,6 +50,13 @@ Serving reads evidence from the findings table by opportunity, so this bounds
the plan payload only.
"""
+# A finding's queue judgement: its cause's, written by the finalizer.
+_QUEUE_COLUMNS = (
+ HealthFinding.queue_eligible,
+ HealthFinding.queue_reason,
+ HealthFinding.queue_value,
+ HealthFinding.queue_tier,
+)
# 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.
@@ -235,7 +244,7 @@ async def finalize_performance_opportunities(
rows = list(
(
await session.execute(
- select(*_OBSERVATION_COLUMNS).where(
+ select(*_OBSERVATION_COLUMNS, *_QUEUE_COLUMNS).where(
HealthFinding.repository_id == repository_id,
HealthFinding.status == "open",
HealthFinding.dimension == "performance",
@@ -245,13 +254,17 @@ async def finalize_performance_opportunities(
)
if execution_roles is not None:
rows = await _restamp_roles(session, rows, execution_roles)
- opportunities = build_performance_opportunities(rows, evidence_limit=_EVIDENCE_LIMIT)
+ opportunities = build_performance_opportunities(
+ rows,
+ evidence_limit=_EVIDENCE_LIMIT,
+ origins=await _unknown_context_origins(session, repository_id, rows),
+ )
- await _restamp_findings(session, rows)
plan_states, plans = await _replace_plans(session, repository_id, opportunities, policy)
- await _reconcile_opportunities(
+ verdicts = await _reconcile_opportunities(
session, repository_id, opportunities, plan_states, analyzed_commit, plans
)
+ await _restamp_findings(session, rows, verdicts)
await _write_summary(session, repository_id, opportunities, plan_states, analyzed_commit, plans)
return len(opportunities)
@@ -285,8 +298,30 @@ async def _restamp_roles(
return out
-async def _restamp_findings(session: AsyncSession, rows: list[Any]) -> None:
- """Point every stored observation at its cause, and give it a public id.
+async def _unknown_context_origins(
+ session: AsyncSession, repository_id: str, rows: list[Any]
+) -> dict[str, str | None]:
+ """The stored ``code_origin`` of each file whose code context is ``unknown``."""
+ from ....analysis.health.perf.causal import execution_context
+
+ paths = sorted(p for p in {r.file_path for r in rows} if execution_context(p) == "unknown")
+ origins: dict[str, str | None] = {}
+ m = HealthFileMetric
+ for batch in chunked(paths):
+ result = await session.execute(
+ select(m.file_path, m.code_origin).where(
+ m.repository_id == repository_id, m.file_path.in_(batch)
+ )
+ )
+ origins.update(result.tuples().all())
+ return origins
+
+
+async def _restamp_findings(
+ session: AsyncSession, rows: list[Any], verdicts: dict[str, dict[str, Any]]
+) -> None:
+ """Point every stored observation at its cause, give it a public id, and
+ write its cause's queue judgement on it.
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.
@@ -297,8 +332,13 @@ async def _restamp_findings(session: AsyncSession, rows: list[Any]) -> None:
changed = []
for row in rows:
- values = {}
- if (opportunity_id := opportunity_id_for_finding(row)) != row.opportunity_id:
+ opportunity_id = opportunity_id_for_finding(row)
+ values = {
+ name: value
+ for name, value in verdicts.get(opportunity_id, {}).items()
+ if getattr(row, name) != value
+ }
+ if opportunity_id != row.opportunity_id:
values["opportunity_id"] = opportunity_id
if not row.public_id:
# A store written before the column existed. Backfilling here is
@@ -391,8 +431,9 @@ async def _reconcile_opportunities(
plan_states: dict[str, str],
analyzed_commit: str | None,
plans: dict[str, dict[str, Any]] | None = None,
-) -> None:
- """Update, insert, and resolve, in one pass over the stored rows."""
+) -> dict[str, dict[str, Any]]:
+ """Update, insert, and resolve, in one pass over the stored rows. Returns
+ each open cause's queue judgement columns, by opportunity id."""
stored = {
(row.performance_model_version, row.opportunity_id): row
for row in (
@@ -406,6 +447,7 @@ async def _reconcile_opportunities(
.all()
}
seen: set[tuple[int, str]] = set()
+ verdicts: dict[str, dict[str, Any]] = {}
now = _now_utc()
for position, item in enumerate(opportunities):
key = (item.performance_model_version, item.opportunity_id)
@@ -417,6 +459,7 @@ async def _reconcile_opportunities(
analyzed_commit=analyzed_commit,
plan=(plans or {}).get(item.opportunity_id),
)
+ verdicts[item.opportunity_id] = {c.key: values[c.key] for c in _QUEUE_COLUMNS}
row = stored.get(key)
if row is None:
session.add(
@@ -436,6 +479,7 @@ async def _reconcile_opportunities(
row.status = "resolved"
row.updated_at = now
await session.flush()
+ return verdicts
async def _write_summary(
diff --git a/tests/unit/persistence/test_performance_materialization.py b/tests/unit/persistence/test_performance_materialization.py
index 6dfa5393b..ef2b40ba2 100644
--- a/tests/unit/persistence/test_performance_materialization.py
+++ b/tests/unit/persistence/test_performance_materialization.py
@@ -406,3 +406,77 @@ async def test_an_unmeasured_loop_is_stored_unproven_and_never_leads(async_sessi
assert summary["lead"] is None
assert summary["default_queue"]["total"] == 0
assert summary["default_queue"]["excluded"]["unmeasured_cost"] == 1
+
+
+async def _findings(session, repo_id: str) -> list[HealthFinding]:
+ result = await session.execute(select(HealthFinding).where(HealthFinding.repository_id == repo_id))
+ return list(result.scalars().all())
+
+
+async def test_every_observation_carries_its_cause_queue_judgement(async_session) -> None:
+ """A finding the queue leaves out says why on its own row, not NULL."""
+ repo = await insert_repo(async_session)
+ await _write(async_session, repo.id, [_finding("src/a.py", 10, loop_magnitude="unknown")])
+ (finding,) = await _findings(async_session, repo.id)
+ assert (finding.queue_eligible, finding.queue_reason) == (False, "unmeasured_cost")
+
+ other = await insert_repo(async_session, name="queued", local_path="/tmp/queued")
+ await _write(async_session, other.id, _corpus())
+ (cause,) = await _rows(async_session, other.id)
+ assert cause.queue_eligible is True
+ for finding in await _findings(async_session, other.id):
+ assert (finding.queue_eligible, finding.queue_reason, finding.queue_tier) == (
+ True,
+ None,
+ cause.queue_tier,
+ )
+
+
+async def _write_with_origin(session, repo_id: str, path: str, origin: str | None) -> None:
+ from repowise.core.analysis.health.models import HealthFileMetricData
+
+ if origin is not None:
+ metric = HealthFileMetricData(
+ file_path=path, score=8.0, max_ccn=3, max_nesting=1, nloc=40, has_test_file=False,
+ code_origin=origin,
+ )
+ await crud.save_health_metrics(session, repo_id, [metric])
+ await _write(session, repo_id, [_finding(path, 10)])
+
+
+ ("path", "origin", "context"),
+ [
+ # ``example`` is a JVM package segment here, not an examples tree.
+ ("app/src/main/kotlin/com/example/app/Sync.kt", "production", "production"),
+ ("app/src/main/kotlin/com/example/app/Sync.kt", None, "unknown"),
+ ("examples/basic/run.py", "docs_example", "unknown"),
+ # A root-level file carries no evidence either way, whatever its origin.
+ ("sync.py", "production", "unknown"),
+ ],
+)
+async def test_a_stored_production_origin_settles_an_unknown_context(
+ async_session, path: str, origin: str | None, context: str
+) -> None:
+ repo = await insert_repo(async_session)
+ await _write_with_origin(async_session, repo.id, path, origin)
+ (cause,) = await _rows(async_session, repo.id)
+ assert cause.execution_context == context
+ if context == "unknown":
+ assert cause.queue_reason == "unknown"
+ else:
+ assert cause.queue_eligible is True
+
+
+async def test_settling_the_context_keeps_the_cause_id(async_session) -> None:
+ path = "app/src/main/kotlin/com/example/app/Sync.kt"
+ settled = await insert_repo(async_session, name="settled", local_path="/tmp/settled")
+ await _write_with_origin(async_session, settled.id, path, "production")
+ plain = await insert_repo(async_session, name="plain", local_path="/tmp/plain")
+ await _write_with_origin(async_session, plain.id, path, None)
+ (a,) = await _rows(async_session, settled.id)
+ (b,) = await _rows(async_session, plain.id)
+ assert a.opportunity_id == b.opportunity_id