Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.mdindex 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 itdiff --git a/packages/core/src/repowise/core/analysis/health/perf/causal.py b/packages/core/src/repowise/core/analysis/health/perf/causal.pyindex 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 hashlibimport jsonimport refrom collections import defaultdict+from collections.abc import Iterable, Mappingfrom typing import Any, Literalfrom 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.pyindex 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 Mappingfrom dataclasses import dataclassfrom 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 groupalready 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.pyindex 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, NamedTuplefrom sqlalchemy import delete, func, select, updatefrom sqlalchemy.ext.asyncio import AsyncSession+from ...batches import chunkedfrom ...models import (+ HealthFileMetric,HealthFinding,PerformanceOpportunity,PerformanceSummary,@@ -48,6 +50,13 @@ Serving reads evidence from the findings table by opportunity, so this boundsthe 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 everchanges 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_idif 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): rowfor 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 = nowawait session.flush()+ return verdictsasync def _write_summary(diff --git a/tests/unit/persistence/test_performance_materialization.py b/tests/unit/persistence/test_performance_materialization.pyindex 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_sessiassert summary["lead"] is Noneassert summary["default_queue"]["total"] == 0assert 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