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
feat(perf): keep repetition with nothing to change out of the default queue (#2514)
Raghav Chamadiyaf3d890c5beff
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 00cc484ae..eb02f94d7 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -927,6 +927,7 @@ representations of the same work in one response. The `include` **dimension** na| `performance_context` | string | No | `production` (default) / `tooling` / `test` / `unknown` / `all`. The summary block is scoped to the same context as the queue; `repository_total` stays the count over every context. || `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_actionability` | string | No | `plan_ready` / `advisory` / `investigate` / `expected`. Unset means all but `expected` (real repetition with nothing to change), which is still counted in the facet and `repository_total`. || `performance_sort` | string | No | `rank` (default) / `leverage` / `observations`. || `scope` | string | No | Which files every figure describes: `all` (default) or `production`. Narrowing drops test files from the headline, the distribution and every ranked list. Tests score higher than production code, so `production` lowers the number without a defect having been found. || `counts` | string | No | What the score counts: `everything` (default, the calibrated number) or `code_shape`, which removes the git-derived half. Change history rises as a file is worked on, so it answers what a repository has been through rather than what its code is like — `code_shape` is the reading that answers "is this code getting better". Files with no stored split are reported in `unscored_files` rather than counted. Findings from history are dropped, not re-scored. |diff --git a/packages/core/src/repowise/core/analysis/change_health/service.py b/packages/core/src/repowise/core/analysis/change_health/service.pyindex e9443c531..e998001c9 100644--- a/packages/core/src/repowise/core/analysis/change_health/service.py+++ b/packages/core/src/repowise/core/analysis/change_health/service.py@@ -461,6 +461,8 @@ def _suggestion(finding: HealthFindingData, perf: PerfOpportunityView | None) ->if perf is not None:if perf.actionability_state == "plan_ready" and perf.intervention_symbol:return f"Hoist or batch the repeated call in {perf.intervention_symbol}."+ if perf.actionability_state == "expected":+ return "Nothing to change: the repetition is inherent or already batched."return perf.actionability_reason or "Confirm the cost before changing it."return finding.reason or f"Review the {finding.biomarker_type.replace('_', ' ')}."diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex 701fce51f..093dfa3c5 100644--- a/packages/core/src/repowise/core/analysis/health/engine.py+++ b/packages/core/src/repowise/core/analysis/health/engine.py@@ -111,6 +111,9 @@ log = structlog.get_logger(__name__)# and a declining call's arguments are not scanned, so an assertion passed as an# argument still does not stand in for the header's oracle.#+# v25: repetition with nothing to change (a filesystem or subprocess boundary, or+# a loop already walking chunks) is stored as ``expected``; a v24 store says investigate.+## v24: ``session.get(Model, key)`` is a db sink, an awaited TS limiter closure runs# in its loop, and Go/Java loops report chunking; a v23 store has none of them.#@@ -250,7 +253,7 @@ log = structlog.get_logger(__name__)# forms. Files that were counted untested and are not become tested, which# moves untested-hotspot findings and the scores that carry them, on every# language with a prefix or spec convention rather than Ruby alone.-HEALTH_ANALYZER_VERSION = 24+HEALTH_ANALYZER_VERSION = 25def walked_functions(diff --git a/packages/core/src/repowise/core/analysis/health/perf/actionability.py b/packages/core/src/repowise/core/analysis/health/perf/actionability.pyindex 27e0b2c0b..c3dfe5543 100644--- a/packages/core/src/repowise/core/analysis/health/perf/actionability.py+++ b/packages/core/src/repowise/core/analysis/health/perf/actionability.py@@ -21,7 +21,11 @@ from typing import Any, LiteralFixSafety = Literal["proven", "advisory"]OpportunityConfidence = Literal["high", "medium", "low"]-ActionabilityState = Literal["plan_ready", "advisory", "investigate"]+# ``expected``: the repetition is real and there is nothing to change.+ActionabilityState = Literal["plan_ready", "advisory", "investigate", "expected"]++# Refusals that are facts about the code, not missing proofs: nothing to investigate.+_EXPECTED_REFUSALS = frozenset({"inherent_to_boundary", "loop_already_chunked"})FixStrategy = Literal["parallelize_independent_awaits","replace_membership_collection",@@ -195,7 +199,7 @@ def assess_fix(if boundary not in BATCHABLE_BOUNDARIES:# Filesystem and subprocess repetition is real, but there is no# batch or prefetch operation to point the caller at.- return FixAssessment(None, ("batch_operation_for_boundary",))+ return FixAssessment(None, (), refusal="inherent_to_boundary")form = _shared(details, "batch_form")if form:if _shared(details, "batch_equivalent") is True:@@ -262,9 +266,10 @@ def actionability("""fix = assessment.fixif fix is None:- return Actionability(- "investigate", assessment.refusal, "low", assessment.prerequisites, None+ state: ActionabilityState = (+ "expected" if assessment.refusal in _EXPECTED_REFUSALS else "investigate")+ return Actionability(state, assessment.refusal, "low", assessment.prerequisites, None)if evidence_confidence == "low":# A transformation proven against a path we could not resolve is not# proven against this code. The safety label moves with the verdict sodiff --git a/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py b/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.pyindex 03aaa8bc5..6a9c47694 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@@ -91,12 +91,12 @@ listed and :func:`amplification` supplies the rest. A marker nobody hascharacterised reports ``unknown`` rather than borrowing a neighbour's shape."""-ACTIONABILITY_ORDER = {"plan_ready": 0, "advisory": 1, "investigate": 2}+ACTIONABILITY_ORDER = {"plan_ready": 0, "advisory": 1, "investigate": 2, "expected": 3}"""Actionable work sorts above evidence, whatever the raw magnitude.A generic sink accumulates points through sheer volume. Left to the scorealone it buries every group somebody could act on today, which is the wrong-lead for both an agent and a person.+lead for both an agent and a person. ``expected`` is never a lead."""_LEVERAGE_BANDS = ((1, "isolated"), (3, "local"), (9, "shared"))diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py b/packages/core/src/repowise/core/persistence/crud/analysis/performance.pyindex 4cb9be9d2..1bc4115a1 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py@@ -145,7 +145,8 @@ def _summary_payload(contexts[item.execution_context] = contexts.get(item.execution_context, 0) + 1key = item.boundary_kind or "none"boundaries[key] = boundaries.get(key, 0) + 1- lead = opportunities[0] if opportunities else None+ # ``expected`` rows rank last and offer nothing to do, so they never lead.+ lead = next((o for o in opportunities if o.actionability_state != "expected"), None)return {"actionability": counts,"context": contexts,@@ -423,7 +424,7 @@ def _predicates(contexts: frozenset[str] | None,boundary: str | None,confidence: str | None,- actionability: str | None,+ actionabilities: frozenset[str] | None,file_paths: tuple[str, ...] | None,) -> list[Any]:where: list[Any] = [@@ -440,8 +441,8 @@ def _predicates()if confidence is not None:where.append(PerformanceOpportunity.evidence_confidence == confidence)- if actionability is not None:- where.append(PerformanceOpportunity.actionability_state == actionability)+ if actionabilities is not None:+ where.append(PerformanceOpportunity.actionability_state.in_(sorted(actionabilities)))if file_paths is not None:where.append(PerformanceOpportunity.file_path.in_(list(file_paths)))return where@@ -472,7 +473,7 @@ async def list_performance_opportunities(contexts: frozenset[str] | None = None,boundary: str | None = None,confidence: str | None = None,- actionability: str | None = None,+ actionabilities: frozenset[str] | None = None,file_paths: tuple[str, ...] | None = None,sort: str = "rank",limit: int = 20,@@ -488,7 +489,7 @@ async def list_performance_opportunities(contexts=contexts,boundary=boundary,confidence=confidence,- actionability=actionability,+ actionabilities=actionabilities,file_paths=file_paths,)total = int(@@ -531,7 +532,7 @@ async def performance_facet_counts(contexts=None,boundary=None,confidence=None,- actionability=None,+ actionabilities=None,file_paths=file_paths,)result = await session.execute(@@ -555,8 +556,8 @@ async def performance_facet_counts(return [tuple(row) for row in result.all()]-_ACTIONABILITY_STATES = ("plan_ready", "advisory", "investigate")-"""The states a rollup breaks down. Named, so a fourth cannot vanish silently."""+_ACTIONABILITY_STATES = ("plan_ready", "advisory", "investigate", "expected")+"""The states a rollup breaks down. Named, so a fifth cannot vanish silently."""class PerformanceFileRollup(NamedTuple):@@ -568,6 +569,7 @@ class PerformanceFileRollup(NamedTuple):plan_ready: intadvisory: intinvestigate: int+ expected: intbest_rank: int"""Lowest ``rank_position`` on the file, so a map can rank files by cause."""@@ -591,7 +593,7 @@ async def performance_file_rollups(contexts=None,boundary=None,confidence=None,- actionability=None,+ actionabilities=None,file_paths=file_paths,)result = await session.execute(@@ -620,6 +622,7 @@ async def performance_file_rollups("plan_ready": 0,"advisory": 0,"investigate": 0,+ "expected": 0,"best_rank": best_rank or 0,},)@@ -636,6 +639,7 @@ async def performance_file_rollups(plan_ready=row["plan_ready"],advisory=row["advisory"],investigate=row["investigate"],+ expected=row["expected"],best_rank=row["best_rank"],)for path, row in folded.items()diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex 901aad1ae..6e835db5f 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -206,6 +206,7 @@ async def _performance_blocks(context: str | None,boundary: str | None,confidence: str | None,+ actionability: str | None,sort: str | None,) -> _PerformanceBlocks:"""Read the materialized queue, its rollup, and the dashboard lead.@@ -224,6 +225,7 @@ async def _performance_blocks(context=context,boundary=boundary,confidence=confidence,+ actionability=actionability,view=view,sort=sort,file_paths=file_paths,@@ -1555,6 +1557,7 @@ async def get_health(performance_context: str | None = None,performance_boundary: str | None = None,performance_confidence: str | None = None,+ performance_actionability: str | None = None,performance_sort: str | None = None,scope: str = DEFAULT_SCOPE,counts: str = DEFAULT_COUNTS,@@ -1584,8 +1587,8 @@ async def get_health(plan, evidence paged by ``only=["*_evidence"]``.refactoring_view: ``diversified`` (default)|``canonical``|``file_spread``; _type/_confidence/_effort filter.- performance_view/_context/_boundary/_confidence/_sort: queue- projection and filters; a rejected value lists the accepted.+ performance_view/_context/_boundary/_confidence/_actionability/_sort:+ queue filters; a rejected value lists the accepted.scope / counts: default ``all``/``everything``. ``production`` dropstest files; ``code_shape`` drops the git-derived half of thescore and its findings.@@ -2202,6 +2205,7 @@ async def get_health(context=performance_context,boundary=performance_boundary,confidence=performance_confidence,+ actionability=performance_actionability,sort=performance_sort,)diff --git a/packages/server/src/repowise/server/services/health_map.py b/packages/server/src/repowise/server/services/health_map.pyindex 0d03e3da5..db2426bfa 100644--- a/packages/server/src/repowise/server/services/health_map.py+++ b/packages/server/src/repowise/server/services/health_map.py@@ -23,6 +23,7 @@ from sqlalchemy.ext.asyncio import AsyncSessionfrom repowise.core.analysis.health.counts import DEFAULT_COUNTSfrom repowise.core.analysis.health.counts import project as project_countsfrom repowise.core.analysis.health.perf.coverage import supported_perf_languages+from repowise.core.analysis.health.perf.opportunity_rank import ACTIONABILITY_ORDERfrom repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scopefrom repowise.core.persistence import crud@@ -158,7 +159,9 @@ class HealthMapService:active_shown = [path for path in active if admit(path)]- performance_eligible = [r.file_path for r in rollups if r.file_path in eligible_paths]+ # A file whose only causes are ``expected`` has nothing to do; it earns no priority slot.+ open_rollups = [r for r in rollups if r.opportunities > r.expected]+ performance_eligible = [r.file_path for r in open_rollups if r.file_path in eligible_paths]performance_shown = sum(1 for path in performance_eligible if admit(path))nloc_before = len(chosen)@@ -178,12 +181,12 @@ class HealthMapService:# on a file with no lines can never be drawn at any cap, and counting# it here would promise a recovery that pinning the path cannot give.undrawn_perf = [- r for r in rollups if r.file_path in eligible_paths and r.file_path not in taken+ r for r in open_rollups if r.file_path in eligible_paths and r.file_path not in taken]omitted = {"files": len(eligible) - len(chosen),"performance_files": len(undrawn_perf),- "opportunities": sum(r.opportunities for r in undrawn_perf),+ "opportunities": sum(r.opportunities - r.expected for r in undrawn_perf),"observations": sum(r.observations for r in undrawn_perf),}@@ -252,7 +255,8 @@ class HealthMapService:"has_test_file": metric.has_test_file,"maintainability_score": metric.maintainability_score,"performance_analyzed": languages.get(metric.file_path) in perf_languages,- "performance_opportunities": rollup.opportunities if rollup else 0,+ # What the default queue shows: ``expected`` causes have nothing to do.+ "performance_opportunities": rollup.opportunities - rollup.expected if rollup else 0,"performance_observations": rollup.observations if rollup else 0,}actionability = _leading_actionability(rollup)@@ -322,6 +326,7 @@ class HealthMapService:"plan_ready": sum(r.plan_ready for r in rollups),"advisory": sum(r.advisory for r in rollups),"investigate": sum(r.investigate for r in rollups),+ "expected": sum(r.expected for r in rollups),},"model_version": getattr(summary, "performance_model_version", None),"analyzed_commit": getattr(summary, "analyzed_commit", None),@@ -334,10 +339,7 @@ def _leading_actionability(rollup: Any) -> str | None:Best rather than most common: a file with one stored plan and nineinvestigations is a file with a stored plan."""- if rollup is None or rollup.opportunities == 0:+ if rollup is None:return None- if rollup.plan_ready:- return "plan_ready"- if rollup.advisory:- return "advisory"- return "investigate"+ # ``expected`` is never a lead: it has nothing to do.+ return next((s for s in ACTIONABILITY_ORDER if s != "expected" and getattr(rollup, s)), None)diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.pyindex 1ca4d1bef..6c7b0b21c 100644--- a/packages/server/src/repowise/server/services/performance_health.py+++ b/packages/server/src/repowise/server/services/performance_health.py@@ -66,9 +66,12 @@ like the current product concept.CANONICAL_SORTS = ("rank", "leverage", "observations")CANONICAL_VIEWS = ("detail", "summary")_CONFIDENCES = ("high", "medium", "low")-_ACTIONABILITIES = ("plan_ready", "advisory", "investigate")+_ACTIONABILITIES = ("plan_ready", "advisory", "investigate", "expected")_BOUNDARIES = ("db", "network", "filesystem", "subprocess", "lock", "none")+_DEFAULT_ACTIONABILITIES = frozenset({"plan_ready", "advisory", "investigate"})+"""``expected`` rows are true but offer nothing to change, so they are asked for, not queued."""+_PLAN_REASONS = {"available": "A stored performance plan addresses this exact opportunity.","no_safe_plan": (@@ -116,6 +119,13 @@ class PerformanceQuery:alias = _DEPRECATED_CONTEXTS.get(self.context)return alias if alias is not None else frozenset({self.context})+ @property+ def actionabilities(self) -> frozenset[str]:+ """The set the queue is filtered to: one explicit state, or the default three."""+ if self.actionability is None:+ return _DEFAULT_ACTIONABILITIES+ return frozenset({self.actionability})+@dataclass(frozen=True, slots=True)class PlanLink:@@ -237,7 +247,7 @@ class PerformanceHealthService:contexts=query.contexts,boundary=query.boundary,confidence=query.confidence,- actionability=query.actionability,+ actionabilities=query.actionabilities,file_paths=query.file_paths,sort=query.sort,limit=query.limit,@@ -402,6 +412,7 @@ class PerformanceHealthService:"plan_ready_total": counts.get("plan_ready", 0),"advisory_total": counts.get("advisory", 0),"investigate_total": counts.get("investigate", 0),+ "expected_total": counts.get("expected", 0),}if summary["status"] == "stale_model":return {diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex f38b90ccf..357dab8a3 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -347,7 +347,7 @@ export interface PerformanceOpportunityEvidence {provenance: string;}-export type PerformanceActionabilityState = "plan_ready" | "advisory" | "investigate";+export type PerformanceActionabilityState = "plan_ready" | "advisory" | "investigate" | "expected";export type PerformancePlanStatus = "available" | "no_safe_plan" | "not_persisted";/** One rank term, the input it read, and the points it contributed. */diff --git a/packages/ui/__tests__/health/performance-query.test.ts b/packages/ui/__tests__/health/performance-query.test.tsindex 6f0148fc9..3524b1ed5 100644--- a/packages/ui/__tests__/health/performance-query.test.ts+++ b/packages/ui/__tests__/health/performance-query.test.ts@@ -31,6 +31,13 @@ describe("performance filter state", () => {expect(parseFilters(serializeFilters(state))).toEqual(state);});+ it("round trips the expected actionability state", () => {+ // expected sits out of the default queue but is still a real, selectable+ // state: the round trip must not treat it as unrecognized.+ const state = { ...INITIAL_FILTERS, actionability: "expected" as const };+ expect(parseFilters(serializeFilters(state))).toEqual(state);+ });+it("drops a value the vocabulary does not contain instead of forwarding it", () => {const parsed = parseFilters("context=production_tooling&actionability=nonsense&offset=-3");expect(parsed.context).toBe("production");diff --git a/packages/ui/__tests__/health/performance-view.test.tsx b/packages/ui/__tests__/health/performance-view.test.tsxindex 030de201d..da95fb704 100644--- a/packages/ui/__tests__/health/performance-view.test.tsx+++ b/packages/ui/__tests__/health/performance-view.test.tsx@@ -67,6 +67,13 @@ describe("PerformanceView queue", () => {);});+ it("labels the actionability select's empty option as excluding expected", async () => {+ render(<PerformanceView adapter={adapter()} />);+ await rows();+ const actionability = screen.getByLabelText("Actionability");+ expect(within(actionability).getByRole("option", { name: "All but expected" })).toBeTruthy();+ });+it("states a facet with one value instead of offering a control that cannot narrow", async () => {render(<PerformanceView adapter={adapter()} />);await rows();diff --git a/packages/ui/src/health/performance/filters.tsx b/packages/ui/src/health/performance/filters.tsxindex 137908a71..70c91da3c 100644--- a/packages/ui/src/health/performance/filters.tsx+++ b/packages/ui/src/health/performance/filters.tsx@@ -91,7 +91,9 @@ interface NarrowingSpec {}const NARROWING: NarrowingSpec[] = [- { key: "actionability", facet: "actionability", anyLabel: "Any" },+ // "expected" causes are real but offer nothing to change, so the default+ // (no explicit selection) reads as "every other state" rather than "any".+ { key: "actionability", facet: "actionability", anyLabel: "All but expected" },{ key: "boundary", facet: "boundary", anyLabel: "Any" },{ key: "confidence", facet: "confidence", anyLabel: "Any" },];diff --git a/packages/ui/src/health/performance/presentation.ts b/packages/ui/src/health/performance/presentation.tsindex feb7ae8c1..b7b7791a6 100644--- a/packages/ui/src/health/performance/presentation.ts+++ b/packages/ui/src/health/performance/presentation.ts@@ -44,12 +44,14 @@ export const ACTIONABILITY_LABEL: Record<PerformanceActionabilityState, string>plan_ready: "Plan ready",advisory: "Advisory",investigate: "Needs investigation",+ expected: "Expected",};export const ACTIONABILITY_HINT: Record<PerformanceActionabilityState, string> = {plan_ready: "A named intervention the analysis considers safe to apply.",advisory: "A coherent intervention, but the analysis cannot prove it is safe.",investigate: "Evidence worth reading before any change is proposed.",+ expected: "The repetition is real and there is no change to make.",};export const CONFIDENCE_LABEL: Record<PerformanceOpportunityConfidence, string> = {diff --git a/packages/ui/src/health/performance/query.ts b/packages/ui/src/health/performance/query.tsindex f74f40dc9..378c81456 100644--- a/packages/ui/src/health/performance/query.ts+++ b/packages/ui/src/health/performance/query.ts@@ -50,6 +50,7 @@ const ACTIONABILITIES: readonly PerformanceActionabilityState[] = ["plan_ready","advisory","investigate",+ "expected",];const CONTEXTS: readonly PerformanceContextFilter[] = ["all",diff --git a/tests/fixtures/perf_corpus/golden_opportunities.json b/tests/fixtures/perf_corpus/golden_opportunities.jsonindex d24821eb4..52131eed7 100644--- a/tests/fixtures/perf_corpus/golden_opportunities.json+++ b/tests/fixtures/perf_corpus/golden_opportunities.json@@ -1940,134 +1940,6 @@}]},- {- "actionability_reason": "no_supported_strategy",- "actionability_state": "investigate",- "affected_call_sites_total": 4,- "affected_files_total": 4,- "biomarker_type": "io_in_loop",- "biomarker_types": [- "io_in_loop"- ],- "boundary_kind": "filesystem",- "confidence": "high",- "evidence": [- {- "biomarker_type": "io_in_loop",- "file_path": "src/app/formatter.py",- "finding_id": "finding_b853807b08e242e784f5",- "function_name": "run",- "line_end": 24,- "line_start": 22,- "path": [- "src/app/formatter.py::run",- "src/app/parse.py::_get_query",- "src/app/parse.py::_load_compiled_query"- ],- "provenance": "call-site",- "reason": "shared_dominator_fan_in: io_in_loop at src/app/formatter.py:22 repeats work per iteration."- },- {- "biomarker_type": "io_in_loop",- "file_path": "src/app/lexer.py",- "finding_id": "finding_7e425174e879fb9f9d23",- "function_name": "run",- "line_end": 22,- "line_start": 20,- "path": [- "src/app/lexer.py::run",- "src/app/parse.py::_get_query",- "src/app/parse.py::_load_compiled_query"- ],- "provenance": "call-site",- "reason": "shared_dominator_fan_in: io_in_loop at src/app/lexer.py:20 repeats work per iteration."- },- {- "biomarker_type": "io_in_loop",- "file_path": "src/app/linter.py",- "finding_id": "finding_34d631c0ff0bed50aafd",- "function_name": "run",- "line_end": 23,- "line_start": 21,- "path": [- "src/app/linter.py::run",- "src/app/parse.py::_get_query",- "src/app/parse.py::_load_compiled_query"- ],- "provenance": "call-site",- "reason": "shared_dominator_fan_in: io_in_loop at src/app/linter.py:21 repeats work per iteration."- },- {- "biomarker_type": "io_in_loop",- "file_path": "src/app/resolver.py",- "finding_id": "finding_ef6b980a3a371a707424",- "function_name": "run",- "line_end": 25,- "line_start": 23,- "path": [- "src/app/resolver.py::run",- "src/app/parse.py::_get_query",- "src/app/parse.py::_load_compiled_query"- ],- "provenance": "call-site",- "reason": "shared_dominator_fan_in: io_in_loop at src/app/resolver.py:23 repeats work per iteration."- }- ],- "evidence_truncated": false,- "execution_context": "production",- "facets": {- "actionability_confidence": "low",- "amplification": "per_iteration",- "change_risk": "moderate",- "exposure": "unknown",- "leverage": "shared",- "loop_magnitude": "unknown"- },- "fix": null,- "intervention_symbol": "src/app/parse.py::_get_query",- "observations_total": 4,- "opportunity_id": "perf2_a445d6f2d021ddf6a425",- "performance_model_version": 2,- "prerequisites": [- "batch_operation_for_boundary"- ],- "provenance": "call-site",- "rank_factors": {- "affected_call_sites": 4,- "boundary_kind": 2,- "entry_reachability": 0,- "execution_context": 3,- "loop_magnitude": 1,- "multiplier_shape": 4,- "provenance": 3- },- "rank_score": 17,- "reliable_entry_reachability": null,- "resource_fingerprints": [],- "shared_path_suffix": [- "src/app/parse.py::_get_query",- "src/app/parse.py::_load_compiled_query"- ],- "siblings": [],- "terminal_sink": "src/app/parse.py::_load_compiled_query",- "why_ranked": [- {- "factor": "affected_call_sites",- "points": 4,- "value": 4- },- {- "factor": "multiplier_shape",- "points": 4,- "value": "io_in_loop"- },- {- "factor": "execution_context",- "points": 3,- "value": "production"- }- ]- },{"actionability_reason": "no_supported_strategy","actionability_state": "investigate",@@ -2297,8 +2169,134 @@]},{- "actionability_reason": "no_supported_strategy",- "actionability_state": "investigate",+ "actionability_reason": "inherent_to_boundary",+ "actionability_state": "expected",+ "affected_call_sites_total": 4,+ "affected_files_total": 4,+ "biomarker_type": "io_in_loop",+ "biomarker_types": [+ "io_in_loop"+ ],+ "boundary_kind": "filesystem",+ "confidence": "high",+ "evidence": [+ {+ "biomarker_type": "io_in_loop",+ "file_path": "src/app/formatter.py",+ "finding_id": "finding_b853807b08e242e784f5",+ "function_name": "run",+ "line_end": 24,+ "line_start": 22,+ "path": [+ "src/app/formatter.py::run",+ "src/app/parse.py::_get_query",+ "src/app/parse.py::_load_compiled_query"+ ],+ "provenance": "call-site",+ "reason": "shared_dominator_fan_in: io_in_loop at src/app/formatter.py:22 repeats work per iteration."+ },+ {+ "biomarker_type": "io_in_loop",+ "file_path": "src/app/lexer.py",+ "finding_id": "finding_7e425174e879fb9f9d23",+ "function_name": "run",+ "line_end": 22,+ "line_start": 20,+ "path": [+ "src/app/lexer.py::run",+ "src/app/parse.py::_get_query",+ "src/app/parse.py::_load_compiled_query"+ ],+ "provenance": "call-site",+ "reason": "shared_dominator_fan_in: io_in_loop at src/app/lexer.py:20 repeats work per iteration."+ },+ {+ "biomarker_type": "io_in_loop",+ "file_path": "src/app/linter.py",+ "finding_id": "finding_34d631c0ff0bed50aafd",+ "function_name": "run",+ "line_end": 23,+ "line_start": 21,+ "path": [+ "src/app/linter.py::run",+ "src/app/parse.py::_get_query",+ "src/app/parse.py::_load_compiled_query"+ ],+ "provenance": "call-site",+ "reason": "shared_dominator_fan_in: io_in_loop at src/app/linter.py:21 repeats work per iteration."+ },+ {+ "biomarker_type": "io_in_loop",+ "file_path": "src/app/resolver.py",+ "finding_id": "finding_ef6b980a3a371a707424",+ "function_name": "run",+ "line_end": 25,+ "line_start": 23,+ "path": [+ "src/app/resolver.py::run",+ "src/app/parse.py::_get_query",+ "src/app/parse.py::_load_compiled_query"+ ],+ "provenance": "call-site",+ "reason": "shared_dominator_fan_in: io_in_loop at src/app/resolver.py:23 repeats work per iteration."+ }+ ],+ "evidence_truncated": false,+ "execution_context": "production",+ "facets": {+ "actionability_confidence": "low",+ "amplification": "per_iteration",+ "change_risk": "moderate",+ "exposure": "unknown",+ "leverage": "shared",+ "loop_magnitude": "unknown"+ },+ "fix": null,+ "intervention_symbol": "src/app/parse.py::_get_query",+ "observations_total": 4,+ "opportunity_id": "perf2_a445d6f2d021ddf6a425",+ "performance_model_version": 2,+ "prerequisites": [],+ "provenance": "call-site",+ "rank_factors": {+ "affected_call_sites": 4,+ "boundary_kind": 2,+ "entry_reachability": 0,+ "execution_context": 3,+ "loop_magnitude": 1,+ "multiplier_shape": 4,+ "provenance": 3+ },+ "rank_score": 17,+ "reliable_entry_reachability": null,+ "resource_fingerprints": [],+ "shared_path_suffix": [+ "src/app/parse.py::_get_query",+ "src/app/parse.py::_load_compiled_query"+ ],+ "siblings": [],+ "terminal_sink": "src/app/parse.py::_load_compiled_query",+ "why_ranked": [+ {+ "factor": "affected_call_sites",+ "points": 4,+ "value": 4+ },+ {+ "factor": "multiplier_shape",+ "points": 4,+ "value": "io_in_loop"+ },+ {+ "factor": "execution_context",+ "points": 3,+ "value": "production"+ }+ ]+ },+ {+ "actionability_reason": "inherent_to_boundary",+ "actionability_state": "expected","affected_call_sites_total": 1,"affected_files_total": 1,"biomarker_type": "io_in_loop",@@ -2338,9 +2336,7 @@"observations_total": 1,"opportunity_id": "perf2_19a89b391403e23aed4d","performance_model_version": 2,- "prerequisites": [- "batch_operation_for_boundary"- ],+ "prerequisites": [],"provenance": "call-site","rank_factors": {"affected_call_sites": 2,@@ -2379,8 +2375,8 @@]},{- "actionability_reason": "no_supported_strategy",- "actionability_state": "investigate",+ "actionability_reason": "inherent_to_boundary",+ "actionability_state": "expected","affected_call_sites_total": 1,"affected_files_total": 1,"biomarker_type": "io_in_loop",@@ -2420,9 +2416,7 @@"observations_total": 1,"opportunity_id": "perf2_68583bf925fadb4f4731","performance_model_version": 2,- "prerequisites": [- "batch_operation_for_boundary"- ],+ "prerequisites": [],"provenance": "call-site","rank_factors": {"affected_call_sites": 2,@@ -2461,8 +2455,8 @@]},{- "actionability_reason": "no_supported_strategy",- "actionability_state": "investigate",+ "actionability_reason": "inherent_to_boundary",+ "actionability_state": "expected","affected_call_sites_total": 1,"affected_files_total": 1,"biomarker_type": "io_in_loop",@@ -2499,9 +2493,7 @@"observations_total": 1,"opportunity_id": "perf2_8ffbe99d8409ad899a72","performance_model_version": 2,- "prerequisites": [- "batch_operation_for_boundary"- ],+ "prerequisites": [],"provenance": "direct","rank_factors": {"affected_call_sites": 2,@@ -2537,8 +2529,8 @@]},{- "actionability_reason": "no_supported_strategy",- "actionability_state": "investigate",+ "actionability_reason": "inherent_to_boundary",+ "actionability_state": "expected","affected_call_sites_total": 1,"affected_files_total": 1,"biomarker_type": "io_in_loop",@@ -2575,9 +2567,7 @@"observations_total": 1,"opportunity_id": "perf2_91e5b79c0937ef51ec73","performance_model_version": 2,- "prerequisites": [- "batch_operation_for_boundary"- ],+ "prerequisites": [],"provenance": "direct","rank_factors": {"affected_call_sites": 2,diff --git a/tests/unit/change_health/test_regressions.py b/tests/unit/change_health/test_regressions.pyindex 1d6763bdb..2ef9e45a5 100644--- a/tests/unit/change_health/test_regressions.py+++ b/tests/unit/change_health/test_regressions.py@@ -2,13 +2,19 @@from __future__ import annotations+from types import SimpleNamespace+import pytestfrom repowise.core.analysis.change_health.analyzer import MAX_FILE_BYTESfrom repowise.core.analysis.change_health.identity import change_finding_id, finding_keyfrom repowise.core.analysis.change_health.matcher import FindingMatcherfrom repowise.core.analysis.change_health.models import FindingKey-from repowise.core.analysis.change_health.service import ChangeHealthDeltaService, DeltaRequest+from repowise.core.analysis.change_health.service import (+ ChangeHealthDeltaService,+ DeltaRequest,+ _suggestion,+)from repowise.core.analysis.change_health.sources import GitRevisionSourcefrom repowise.core.analysis.health import HealthFindingData, Severityfrom repowise.core.analysis.health.scoring import score_file@@ -227,3 +233,12 @@ def test_a_continuous_marker_still_worsens_when_its_own_deduction_grows():better = FindingMatcher().match([gradient(0.6)], [gradient(0.2)]).matchedassert [m.kind for m in better] == ["unchanged"]+++def test_an_expected_cause_says_there_is_nothing_to_change():+ perf = SimpleNamespace(+ actionability_state="expected",+ actionability_reason="inherent_to_boundary",+ intervention_symbol=None,+ )+ assert "inherent_to_boundary" not in _suggestion(SimpleNamespace(), perf)diff --git a/tests/unit/health/test_model_version_coupling.py b/tests/unit/health/test_model_version_coupling.pyindex 0e09bd4ad..8a0ce256b 100644--- a/tests/unit/health/test_model_version_coupling.py+++ b/tests/unit/health/test_model_version_coupling.py@@ -22,7 +22,7 @@ from repowise.core.analysis.health.refactoring.identity import (# The three stamps as they stand together. Moving either identity model means# moving the analyzer with it, and updating this tuple in the same commit.-_STAMPS = (24, 2, 2)+_STAMPS = (25, 2, 2)def test_the_identity_models_and_the_analyzer_stamp_are_pinned_together() -> None:diff --git a/tests/unit/health/test_perf_corpus_golden.py b/tests/unit/health/test_perf_corpus_golden.pyindex 7a0d2f8db..95361673e 100644--- a/tests/unit/health/test_perf_corpus_golden.py+++ b/tests/unit/health/test_perf_corpus_golden.py@@ -198,7 +198,7 @@ def test_a_path_that_names_no_caller_is_keyed_locally() -> None:def test_every_group_reports_an_actionability_state_and_a_reason() -> None:"""Nothing is dropped for being unexplainable; it is labelled instead."""- states = {"plan_ready", "advisory", "investigate"}+ states = {"plan_ready", "advisory", "investigate", "expected"}for item in _opportunities():assert item.actionability_state in statesassert item.actionability_reasondiff --git a/tests/unit/health/test_perf_opportunities.py b/tests/unit/health/test_perf_opportunities.pyindex f613c108a..40215aa47 100644--- a/tests/unit/health/test_perf_opportunities.py+++ b/tests/unit/health/test_perf_opportunities.py@@ -342,8 +342,51 @@ def test_a_loop_that_already_chunks_is_not_told_to_batch():)[0]assert opportunity.fix is None- assert opportunity.actionability_state == "investigate"+ assert opportunity.actionability_state == "expected"assert opportunity.actionability_reason == "loop_already_chunked"+ assert opportunity.prerequisites == ()+++def test_a_repeated_call_at_a_non_batchable_boundary_is_expected_not_investigate():+ """Filesystem/subprocess repetition is real, but no detector could ever++ supply a batch API for it, so it is a fact to read rather than a queued+ investigation.+ """+ opportunity = build_performance_opportunities(+ [_finding("fs.py", 8, boundary="filesystem", call_path=("fs.py::run", "fs.py::read"))]+ )[0]++ assert opportunity.fix is None+ assert opportunity.actionability_state == "expected"+ assert opportunity.actionability_reason == "inherent_to_boundary"+ assert opportunity.prerequisites == ()+++def test_expected_sorts_after_investigate_regardless_of_raw_rank():+ """``ACTIONABILITY_ORDER`` is compared before ``rank_score``, so an+ ``expected`` fact never leads an ``investigate`` cause, whichever one this+ corpus would otherwise score higher.+ """+ opportunities = build_performance_opportunities(+ [+ _finding("sync.py", 5, chunked_iteration=True),+ _finding(+ "a.py",+ 3,+ marker="blocking_io_under_lock",+ call_path=("a.py::critical", "store.py::flush", "db.py::fetch"),+ ),+ _finding(+ "b.py",+ 4,+ marker="blocking_io_under_lock",+ call_path=("b.py::critical", "store.py::flush", "db.py::fetch"),+ ),+ ]+ )+ states = [item.actionability_state for item in opportunities]+ assert states.index("investigate") < states.index("expected")def test_two_causes_on_one_line_name_each_other_and_the_stronger_fix_leads():diff --git a/tests/unit/server/mcp/test_performance_levels.py b/tests/unit/server/mcp/test_performance_levels.pyindex 399de83ef..9ad2b5023 100644--- a/tests/unit/server/mcp/test_performance_levels.py+++ b/tests/unit/server/mcp/test_performance_levels.py@@ -186,6 +186,60 @@ async def test_the_queue_filters_before_it_caps(setup_mcp, materialized):assert empty["performance_opportunities_total"] == 0+async def test_performance_actionability_threads_through_and_defaults_off_expected(+ setup_mcp, session, materialized+):+ """``performance_actionability`` reaches the service like the other filters,+ and an unfiltered call still excludes ``expected`` (see performance_health's+ default queue)."""+ from repowise.server.mcp_server import get_health++ session.add(+ HealthFinding(+ id=str(uuid.uuid4()),+ repository_id=materialized,+ file_path="src/fs.py",+ biomarker_type="io_in_loop",+ severity="medium",+ function_name="run",+ line_start=1,+ line_end=1,+ details_json=json.dumps(+ {+ "boundary_kind": "filesystem",+ "cross_function": True,+ "path": ["src/fs.py::run", "src/fs.py::read"],+ "resolution_basis": "reliable-edge",+ }+ ),+ health_impact=0.0,+ reason="A file is read for every loop iteration.",+ dimension="performance",+ status="open",+ )+ )+ await session.flush()+ await finalize_performance_opportunities(session, materialized, analyzed_commit="d" * 40)+ await session.commit()++ default = await get_health(+ include=["performance"], only=["performance_opportunities"]+ )+ assert all(+ item["actionability_state"] != "expected"+ for item in default["performance_opportunities"]+ )++ expected_only = await get_health(+ include=["performance"],+ only=["performance_opportunities"],+ performance_actionability="expected",+ )+ assert expected_only["performance_opportunities_total"] == 1+ assert expected_only["performance_opportunities"][0]["actionability_state"] == "expected"++@pytest.mark.asyncioasync def test_an_unrecognized_filter_value_is_named_not_silently_empty(setup_mcp, materializeddiff --git a/tests/unit/server/test_health_map_feed.py b/tests/unit/server/test_health_map_feed.pyindex 6ecfc84e9..639f8d4a5 100644--- a/tests/unit/server/test_health_map_feed.py+++ b/tests/unit/server/test_health_map_feed.py@@ -141,6 +141,54 @@ async def test_rows_carry_the_burden_the_lens_rings_by(app, client):assert "performance_actionability" not in big+async def test_a_file_with_only_expected_causes_reads_clear_on_the_map(+ app, client: AsyncClient+):+ """The map counts what the default queue shows; the repository rollup still counts all."""+ repo = await create_test_repo(client)+ repo_id = repo["id"]+ metrics = [_metric("src/fs.py", 5), _metric("src/big.py", 500)]+ findings = [+ HealthFindingData(+ biomarker_type="io_in_loop",+ severity=Severity.MEDIUM,+ file_path="src/fs.py",+ function_name="run",+ line_start=1,+ line_end=1,+ details={+ "boundary_kind": "filesystem",+ "cross_function": True,+ "path": ["src/fs.py::run", "src/fs.py::read"],+ "resolution_basis": "reliable-edge",+ },+ health_impact=0.0,+ reason="A file is read for every loop iteration.",+ dimension="performance",+ )+ ]+ link_performance_findings(findings)+ async with app.state.session_factory() as session:+ await crud.save_health_metrics(session, repo_id, metrics)+ await crud.save_health_findings(session, repo_id, findings)+ await crud.finalize_performance_opportunities(+ session, repo_id, analyzed_commit="b" * 40+ )+ await session.commit()++ feed = await _feed(client, repo_id, cap=100)+ row = next(f for f in feed["files"] if f["file_path"] == "src/fs.py")+ assert row["performance_opportunities"] == 0+ assert "performance_actionability" not in row+ perf = feed["performance"]+ assert perf["actionability"]["expected"] == 1+ assert sum(perf["actionability"].values()) == perf["opportunities_total"]+ # Nor does it take a priority slot from the size sample.+ capped = await _feed(client, repo_id, cap=1)+ assert [f["file_path"] for f in capped["files"]] == ["src/big.py"]+ assert capped["selection"]["performance_shown"] == 0++async def test_the_repository_block_reports_what_the_lens_can_say(app, client):repo_id = await _seed(app, client)feed = await _feed(client, repo_id, cap=100)diff --git a/tests/unit/server/test_performance_opportunities.py b/tests/unit/server/test_performance_opportunities.pyindex d420ef09b..436b03d76 100644--- a/tests/unit/server/test_performance_opportunities.py+++ b/tests/unit/server/test_performance_opportunities.py@@ -239,6 +239,68 @@ async def test_facets_keep_the_alternatives_a_selected_filter_would_erase(assert (await _page(client, repo_id, boundary="network"))["facets"]["context"] == []+def _filesystem_finding(path: str, line: int, path_nodes: list[str]) -> HealthFindingData:+ """A repetition with no batch API to offer: this is what ``expected`` is for."""+ return HealthFindingData(+ biomarker_type="io_in_loop",+ severity=Severity.MEDIUM,+ file_path=path,+ function_name="run",+ line_start=line,+ line_end=line,+ details={+ "boundary_kind": "filesystem",+ "cross_function": True,+ "path": path_nodes,+ "resolution_basis": "reliable-edge",+ },+ health_impact=0.0,+ reason="A file is read for every loop iteration.",+ dimension="performance",+ )+++async def test_expected_sits_out_of_the_default_queue_but_not_the_facet(+ app, client: AsyncClient+) -> None:+ """466 of a real corpus's rows are exactly this: real, but nothing to do.++ The default page must not show them, the facet must still count them (so a+ reader can find them), and asking for them explicitly must return only+ them.+ """+ findings = [+ *_findings(),+ _filesystem_finding("src/fs.py", 1, ["src/fs.py::run", "src/fs.py::read"]),+ ]+ repo_id, _ = await _seed(app, client, findings)++ default = await _page(client, repo_id)+ assert all(item["actionability_state"] != "expected" for item in default["items"])+ assert default["summary"]["repository_total"] >= default["total"]++ facets = default["facets"]+ assert {entry["value"]: entry["total"] for entry in facets["actionability"]}.get(+ "expected"+ ) == 1++ only_expected = await _page(client, repo_id, actionability="expected")+ assert only_expected["total"] == 1+ assert only_expected["items"][0]["actionability_state"] == "expected"+ assert only_expected["items"][0]["actionability_reason"] == "inherent_to_boundary"+++async def test_an_expected_row_never_leads_the_directive(app, client: AsyncClient) -> None:+ from repowise.server.services.performance_health import PerformanceHealthService++ finding = _filesystem_finding("src/fs.py", 1, ["src/fs.py::run", "src/fs.py::read"])+ repo_id, _ = await _seed(app, client, [finding])+ async with app.state.session_factory() as session:+ directive = await PerformanceHealthService(session, repo_id, "repo").directive()+ assert directive["status"] == "clear"+ assert directive["expected_total"] == 1++async def test_an_id_from_an_older_model_reports_stale_rather_than_no_plan(app, client: AsyncClient) -> None: