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(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.md
index 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.py
index 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.py
index 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 = 25
def 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.py
index 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, Literal
FixSafety = 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.fix
if 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 so
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 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 has
characterised 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 score
alone 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.py
index 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) + 1
key = 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: int
advisory: int
investigate: int
+ expected: int
best_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.py
index 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`` drops
test files; ``code_shape`` drops the git-derived half of the
score 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.py
index 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 AsyncSession
from repowise.core.analysis.health.counts import DEFAULT_COUNTS
from repowise.core.analysis.health.counts import project as project_counts
from repowise.core.analysis.health.perf.coverage import supported_perf_languages
+from repowise.core.analysis.health.perf.opportunity_rank import ACTIONABILITY_ORDER
from repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scope
from 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 nine
investigations 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.py
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.json
index 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.py
index 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 pytest
from repowise.core.analysis.change_health.analyzer import MAX_FILE_BYTES
from repowise.core.analysis.change_health.identity import change_finding_id, finding_key
from repowise.core.analysis.change_health.matcher import FindingMatcher
from 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 GitRevisionSource
from repowise.core.analysis.health import HealthFindingData, Severity
from 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)]).matched
assert [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.py
index 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.py
index 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 states
assert item.actionability_reason
diff --git a/tests/unit/health/test_perf_opportunities.py b/tests/unit/health/test_perf_opportunities.py
index 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.py
index 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.asyncio
async def test_an_unrecognized_filter_value_is_named_not_silently_empty(
setup_mcp, materialized
diff --git a/tests/unit/server/test_health_map_feed.py b/tests/unit/server/test_health_map_feed.py
index 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.py
index 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: