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.

refactor(health): one eligibility module and reason vocabulary for every default queue (#3328)

Raghav Chamadiyae48e61e16aa4
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 687d9a746..62557de8e 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -666,7 +666,8 @@ Index and update save the queue and the Do next list, so these surfaces open wit
Fix first is built once in `analysis/health/fix_first/build.py` from stored rows
and rendered unchanged by `get_health`, `repowise health`, the dashboard and the
generated CLAUDE.md. Every excluded unit is counted in `totals.excluded` under one
-reason:
+reason. These reasons and the performance default queue's are decided in one place,
+`analysis/health/queue/`:
| Reason | What it leaves out |
|---|---|
@@ -680,7 +681,8 @@ reason:
| `inherent_dispatch` | One dispatch holds 60% or more of the decision points (labels: 8 of 9 such rows rejected), unless a duplicate also sits in it |
| `small_function` | Under 30 code lines and CCN 15 (on 67 labelled rows this cut drops 13 rejected and 4 accepted) |
| `no_concrete_step` | No first edit with a file and line or a named group |
-| `low_value_kind` | Extract Class (0 of 14 accepted), Move Method (0 of 34), low cohesion (0 of 46), long method (0 of 10), long parameter lists (0 of 2) |
+| `low_value_kind` | Low cohesion (0 of 46 accepted), long method (0 of 10), long parameter lists (0 of 2) |
+| `kind_unaudited` | Plans led by Extract Class (0 of 14 accepted) or Move Method (0 of 34), kept to the full list until each passes a per-language audit |
Order: value first (the larger of health recovered and size: CCN 20/40/80/150,
lines 100/200/400/800, nesting 5/6/8, a critical or brain-method finding, one step
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.md
index bfdb42f01..be7c27e10 100644
--- a/docs/layers/REFACTORING.md
+++ b/docs/layers/REFACTORING.md
@@ -107,11 +107,13 @@ Break Cycle out, matching the opportunities; `by_type` still counts it.
Names are never invented. A suggested helper or file name is `null` when nothing
in the code anchors one. A Split File or Extract Class plan with an unnamed group
is held as `needs_design`, like a cycle: it is not a step and never reaches Fix
-first. Code only moves within a language family, so Java, Kotlin and Scala are
-separate. A callback is named after the call it is passed to. An Extract Method
-helper is named from a stage label, a banner comment, or `compute_<value>` when the
-span has no outside effects. A name already taken where the helper lands is
-dropped, so a `null` name means you name the helper.
+first. A plan led by Move Method or Extract Class stays in the full list but is
+kept out of Fix first and the default scope, counted as not yet audited, until
+that kind passes a per-language review. Code only moves within a language family,
+so Java, Kotlin and Scala are separate. A callback is named after the call it is
+passed to. An Extract Method helper is named from a stage label, a banner comment,
+or `compute_<value>` when the span has no outside effects. A name already taken
+where the helper lands is dropped, so a `null` name means you name the helper.
An empty list means no detector found work that clears its gates. It does not mean
the code needs no attention: check the findings in
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/build.py b/packages/core/src/repowise/core/analysis/health/fix_first/build.py
index 96ea46661..7567c104c 100644
--- a/packages/core/src/repowise/core/analysis/health/fix_first/build.py
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/build.py
@@ -49,7 +49,6 @@ Row shapes (field names are the SQL columns):
from __future__ import annotations
-import functools
import math
import re
from collections import Counter, defaultdict
@@ -60,38 +59,41 @@ from typing import Any
from repowise.core.analysis.finding_registry import excluded_types
from repowise.core.analysis.health.complexity.dispatch import DISPATCH_SHARE
from repowise.core.analysis.health.models import primary_finding, split_by_origin
-from repowise.core.analysis.health.perf.causal import code_context
-from repowise.core.analysis.health.perf.opportunity_rank import (
+from repowise.core.analysis.health.queue.eligibility import (
DEFAULT_QUEUE_CONTEXTS,
- strategy_exclusion,
+ Tally,
+ Verdict,
+ finding_verdict,
+ path_verdict,
+ perf_fix_verdict,
+ perf_low_priority,
+ refactor_verdict,
+)
+from repowise.core.analysis.health.queue.order import LEVEL_RANK, order
+from repowise.core.analysis.health.queue.value import (
+ perf_value,
+ shape_value,
+ size_value,
+ tier,
)
from repowise.core.analysis.health.rows import detail_map, field, json_field
from repowise.core.analysis.health.scoring import biomarker_dimension
from repowise.core.analysis.health.suggestions import suggestion_for
from repowise.core.analysis.health.worth import (
- LOW_PRIORITY_LABEL,
SIZE_MARKERS,
WORTH_MAGNITUDE,
- dispatch_shaped,
- dormant,
- lead_reason,
low_priority,
magnitude,
measure,
- perf_low_priority,
worth_size,
)
from repowise.core.analysis.next_call import ActionCommand
-from repowise.core.code_origin import path_origin
from . import text
from .model import (
- EFFORT_RANK,
FIX_EFFORTS,
FIX_EXCLUSIONS,
FIX_IMPROVES,
- LEVEL_RANK,
- TIER_RANK,
FixAction,
FixConfidence,
FixContext,
@@ -115,67 +117,22 @@ Rows = Iterable[Any]
#: A dead-code finding's ``(symbol, start line, end line)``; no symbol for a whole file.
DeadSpan = tuple[str | None, int | None, int | None]
-#: A refactoring whose credited gain is under this is not worth an item. The
-#: refactoring model credits only the share of a finding a plan removes and
-#: drops trivial spans itself (minimum worth), so this floor is on the file.
-MIN_WORTH = 0.5
-#: Credited health gain cut points for value 1, 2 and 3.
-GAIN_CUTS = (0.5, 1.5, 3.0)
-#: Problem size, value 1 to 4, reads ``worth.SIZE_*``: health credit is
-#: calibrated per finding and saturates, so a function far past every bar
-#: would rank with a tidy one without them.
-#: A critical finding or a brain method is at least this size.
-SIZE_SEVERE = 2
#: Measured size (CCN, lines or nesting alone, before the severity floor and
#: the hot-file bonus) from which an item leads as "break up", naming the whole
#: problem: CCN 40, 200 lines or nesting 6.
SIZE_BREAK_UP = WORTH_MAGNITUDE
-#: The highest value any unit reaches.
-VALUE_MAX = 4
#: A file in the top fifth of production files by churn or dependents is hot.
HOT_QUANTILE = 0.8
MAX_FACTS = 5
MAX_TESTS = 5
MAX_STEPS = 5
MAX_CONTEXT = 3
-#: In the first HEAD places no kind takes more than HEAD_PER_KIND, unless the
-#: other kinds have nothing above the later tier.
-HEAD = 5
-HEAD_PER_KIND = 3
DEFAULT_LIMIT = 10
-#: A function-level complexity unit needs this many code lines or this CCN.
-#: Picked on the dev labels (67 complexity rows): 30 / 15 drops 13 rejected
-#: small functions and 4 accepted ones; no cut that keeps every accepted row
-#: drops more than 4 rejected.
-SMALL_NLOC = 30
-SMALL_CCN = 15
#: A dead-code finding this sure (or marked safe to delete) makes its target
#: ``unreachable``: no plan beats deleting it.
DEAD_CONFIDENCE = 0.8
#: Class-level findings: a fix names member groups, which only a plan holds.
CLASS_MARKERS = frozenset({"low_cohesion", "god_class"})
-#: Kinds the baseline raters found not worth doing: a refactoring led by one
-#: of these steps, or a plan-less finding led by one of these markers, is no
-#: candidate (it stays in the refactoring tab). Worth over rater labels, dev
-#: repos first, then all 17 baseline repos.
-LOW_VALUE_KINDS: dict[str, str] = {
- "extract_class": "dev 0/6, all 0/14",
- "move_method": "dev 0/14, all 0/34",
- "low_cohesion": "dev 0/26, all 0/46",
- "large_method": "dev 0/4, all 0/10",
- # Thinly measured: one held-out item (two labels), none on the dev repos.
- # A low-value maintainability nudge that otherwise fills a small repo's
- # whole top three; revisit when more of it is labelled.
- "primitive_obsession": "dev 0/0, all 0/2",
-}
-#: The same, for one detail ``kind`` of a marker whose other kinds stay. A Rust
-#: unwrap or panic is a crash path, not the hidden failure the error-handling
-#: item describes, and the raters found it not worth doing first. Both kinds
-#: were rated together on ripgrep, fd, serde and mini-redis.
-LOW_VALUE_DETAIL_KINDS: dict[tuple[str, str], str] = {
- ("error_handling", "unsafe_unwrap"): "rust all 1/19",
- ("error_handling", "panic_macro"): "rust all 1/19",
-}
@dataclass(frozen=True, slots=True)
@@ -200,18 +157,6 @@ class _Unit:
may_lead: bool = True
-#: Code origins that do not ship, by the exclusion each counts as. A build
-#: script is tooling to a reader choosing what to fix.
-_ORIGIN_EXCLUSION = {
- "test": "test",
- "vendored": "vendored",
- "docs_example": "docs_example",
- "generated": "generated",
- "tooling": "tooling",
- "build": "tooling",
-}
-
-
def _open(row: Any) -> bool:
return (field(row, "status") or "open") == "open"
@@ -220,39 +165,6 @@ def _num(value: Any) -> float:
return float(value or 0.0)
-#: The shared path rules, memoised: they are pure on the path and the test
-#: check dominates a cold build.
-_code_context = functools.lru_cache(maxsize=65536)(code_context)
-
-
-def _path_exclusion(
- path: str, is_test: bool | None, context: str | None = None, origin: str | None = None
-) -> str | None:
- """Why a file is out of the queue, or ``None`` when it ships.
-
- The stored ``code_origin`` decides first: it read the file's head, so it
- knows a vendored library or a docs tutorial the path alone does not.
- Then the same classifier on the path (an index stored before the origin
- column, or a build file classed before build files were), then the path
- context. Code-shape work reads :func:`code_context`, where a CLI ships. A
- performance fix passes ``production``: its stored execution context is
- judged by the performance default queue. The stored ``is_test`` flag also
- marks a test.
- """
- if origin in _ORIGIN_EXCLUSION:
- return _ORIGIN_EXCLUSION[origin]
- ctx = context or _code_context(path)
- if is_test or ctx == "test":
- return "test"
- if reason := _ORIGIN_EXCLUSION.get(path_origin(path)):
- return reason
- # ``unknown`` under a directory is docs, examples or demos at any depth:
- # code that may not ship. A root-level file stays eligible.
- if ctx == "tooling" or (ctx == "unknown" and "/" in path):
- return "tooling"
- return None
-
-
def hot_cut_offset(count: int) -> int:
"""Where the top fifth starts in ``count`` ascending values."""
return min(int(count * HOT_QUANTILE), count - 1)
@@ -270,16 +182,6 @@ def _quantile_cut(values: list[int]) -> float:
return hot_cut(sorted(values)[hot_cut_offset(len(values))])
-def _gain_value(gain: float, hot: bool) -> int:
- return min(3, sum(gain >= cut for cut in GAIN_CUTS) + int(hot))
-
-
-def _size_value(shape: Mapping[str, int], hot: bool) -> int:
- """How big the problem is, 0 to 4; a hot file counts one more."""
- base = max(magnitude(shape), SIZE_SEVERE if shape.get("severe") else 0)
- return min(VALUE_MAX, base + int(hot and base > 0))
-
-
def _risk(files_touched: int, dependents: int | None) -> FixRisk:
deps = dependents or 0
if files_touched >= 5 or deps >= 20:
@@ -454,32 +356,6 @@ class _Files:
return True
return False
- def unit_exclusion(
- self, path: str, symbol: str | None, complexity: bool, line: int | None = None
- ) -> str | None:
- """Why a unit on ``symbol`` is not a candidate, or ``None``.
-
- Unreachable code is deleted, not fixed. A deprecated function is on its
- way out, and a dormant one does not run. A complexity unit on a
- function that is mostly one dispatch on one value is usually fine as
- it is, unless a duplicate also sits in it; one on a small function is
- not worth an item.
- """
- if self.unreachable(path, symbol, line):
- return "unreachable"
- shape = self.shape(path, symbol)
- if shape.get("deprecated"):
- return "deprecated"
- if dormant(shape):
- return "gated_off"
- if not complexity:
- return None
- if dispatch_shaped(shape) and not self.cloned(path, shape):
- return "inherent_dispatch"
- if _small(shape):
- return "small_function"
- return None
-
def why(
self,
path: str,
@@ -525,20 +401,6 @@ class _Files:
return out
-def _tier(value: int, confidence: str, ready: bool, low: str | None) -> tuple[str, str]:
- """The tier and its reason, from a value that leaves the hot-file bonus
- out: history orders items within a tier but never lifts one. A problem
- the shape rule calls lower priority (``worth.low_priority``) is ``later``
- whatever its value."""
- if low is not None:
- return "later", LOW_PRIORITY_LABEL[low]
- if value >= 2 and LEVEL_RANK.get(confidence, 0) >= 1 and ready:
- return "now", "worth doing, and the plan is safe to start"
- if value >= 2:
- return "next", "worth doing; the fix needs judgment"
- return "later", "smaller payoff"
-
-
def _finish(
*,
kind: str,
@@ -557,14 +419,14 @@ def _finish(
) -> _Unit:
confidence = confidence if confidence in LEVEL_RANK else "low"
effort = effort if effort in FIX_EFFORTS else "M"
- tier, why_tier = _tier(value if cold_value is None else cold_value, confidence, ready, low)
+ unit_tier, why_tier = tier(value if cold_value is None else cold_value, confidence, ready, low)
item_id = fix_id(kind, source_id)
def write(rank: int) -> FixItem:
return FixItem(
id=item_id,
rank=rank,
- tier=tier,
+ tier=unit_tier,
kind=kind,
improves=improves,
why_ranked=(
@@ -576,7 +438,9 @@ def _finish(
**fields(),
)
- return _Unit(item_id, kind, tier, value, score, confidence, effort, improves, write, may_lead)
+ return _Unit(
+ item_id, kind, unit_tier, value, score, confidence, effort, improves, write, may_lead
+ )
# --- refactoring ----------------------------------------------------------------
@@ -751,7 +615,7 @@ def _refactor_unit(
hot = files.hot(path)
dimension = biomarker_dimension(marker) if marker else "maintainability"
shape = files.shape(path, lead.get("target_symbol"))
- size = _size_value(shape, hot)
+ size = size_value(shape, hot)
cloned = lead_type == "extract_method" and files.cloned(path, shape)
low = low_priority(marker, shape, function_size=lead_type == "extract_method")
@@ -861,8 +725,8 @@ def _refactor_unit(
return _finish(
kind="refactor",
source_id=field(row, "opportunity_id"),
- value=_value(gain, shape, cloned, hot=hot),
- cold_value=_value(gain, shape, cloned, hot=False),
+ value=shape_value(gain, shape, cloned, hot=hot),
+ cold_value=shape_value(gain, shape, cloned, hot=False),
ready=mechanical or confidence == "high",
score=_num(field(row, "rank_score")),
confidence=confidence if confidence in LEVEL_RANK else "medium",
@@ -879,14 +743,6 @@ def _refactor_unit(
)
-def _value(gain: float, shape: Mapping[str, int], cloned: bool, *, hot: bool) -> int:
- """The larger of the gain and the problem size, one step more when a
- duplicate sits in the same function: raters accepted that shape almost
- every time."""
- value = max(_gain_value(gain, hot), _size_value(shape, hot))
- return min(VALUE_MAX, value + 1) if cloned else value
-
-
def _refactor_measure(
kind: str, sym: str, path: str, step: Mapping[str, Any], plan: Any, files: _Files
) -> str | None:
@@ -917,43 +773,6 @@ def _refactor_measure(
# --- performance ----------------------------------------------------------------
-def _has_plan(row: Any) -> bool:
- return field(row, "plan_state") == "available" and bool(field(row, "fix_strategy"))
-
-
-#: Causes whose cost is real only in shipped code over a loop that grows: a
-#: string built in a bounded loop, or in a script, costs nothing a user sees.
-GROWS_ONLY_MARKERS = frozenset({"string_concat_in_loop"})
-
-
-def _perf_worth(row: Any) -> bool:
- """Whether a planned cause is worth an item at all."""
- return field(row, "biomarker_type") not in GROWS_ONLY_MARKERS or perf_low_priority(row) is None
-
-
-def _perf_value(row: Any, facets: Mapping[str, Any]) -> int:
- """0 to :data:`VALUE_MAX`. A production, entry-reachable database or
- network call in a loop that grows with the data is the costliest kind of
- work Fix first holds, so it shares the top band with the largest
- functions; capped below it, it never reached a top ten that size fills."""
- production = field(row, "execution_context") == "production"
- reachable = facets.get("exposure") == "entry_reachable"
- reason = lead_reason(field(row, "biomarker_type"), facets)
- if (
- production
- and reachable
- and facets.get("loop_magnitude") == "grows_with_data"
- and field(row, "boundary_kind") in ("db", "network")
- ):
- return VALUE_MAX
- value = 2 if production and reason is None else 1
- # No traffic data: a loop of unknown size that no entry point reaches is
- # most often an admin or maintenance path, where an N+1 is cheap.
- if reason == "unmeasured_cost" and not reachable:
- value -= 1
- return value
-
-
def _perf_step_text(step: Mapping[str, Any], path: str) -> str:
"""A plan step's action, naming its function once: an action that already
says the name is not followed by it again."""
@@ -1114,7 +933,7 @@ def _perf_unit(
kind="perf_fix",
may_lead=details.get("may_lead") is not False,
source_id=f"{path}::{symbol or path}",
- value=_perf_value(lead, facets),
+ value=perf_value(lead, facets),
ready=ready or mechanical,
score=_num(field(lead, "rank_score")),
confidence=confidence,
@@ -1145,7 +964,7 @@ def _finding_unit(lead: Any, files: _Files, first: FixStep, validate: Validate |
public_id = field(lead, "public_id")
dimension = biomarker_dimension(marker)
shape = files.shape(path, function)
- size = _size_value(shape, hot)
+ size = size_value(shape, hot)
cloned = marker in SIZE_MARKERS and files.cloned(path, shape)
low = low_priority(marker, shape, error_kind=detail_map(lead).get("kind"))
@@ -1203,8 +1022,8 @@ def _finding_unit(lead: Any, files: _Files, first: FixStep, validate: Validate |
return _finish(
kind="finding",
source_id=public_id or f"{path}::{marker}::{function or ''}",
- value=_value(impact, shape, cloned, hot=hot),
- cold_value=_value(impact, shape, cloned, hot=False),
+ value=shape_value(impact, shape, cloned, hot=hot),
+ cold_value=shape_value(impact, shape, cloned, hot=False),
ready=False,
score=impact,
confidence="medium",
@@ -1227,59 +1046,6 @@ def _severity(severity: str | None, low: str | None) -> str:
return severity if low is None else f"{severity} by the detector; lower priority by shape"
-def _small(shape: Mapping[str, int]) -> bool:
- """Under both size floors. A function whose size findings carry no line
- count is measured by its span, which bounds its code lines from above; one
- with neither is not judged small."""
- nloc = shape.get("nloc")
- if not nloc and shape.get("start") and shape.get("end"):
- nloc = shape["end"] - shape["start"] + 1
- if not nloc:
- return False
- return nloc < SMALL_NLOC and shape.get("ccn", 0) < SMALL_CCN
-
-
-def _refactor_exclusion(
- gain: float,
- steps: list[Mapping[str, Any]],
- plans: Mapping[str, Any],
- files: _Files,
- path: str,
-) -> str | None:
- """Why an open refactoring opportunity in scope is no candidate, or ``None``."""
- if gain < MIN_WORTH or not steps:
- return "below_min_worth"
- lead = steps[0]
- if lead.get("refactoring_type") in LOW_VALUE_KINDS:
- return "low_value_kind"
- reason = files.unit_exclusion(
- path,
- lead.get("target_symbol"),
- complexity=lead.get("refactoring_type") == "extract_method",
- line=lead.get("line_start"),
- )
- if reason is None and not _concrete(lead, plans.get(lead.get("plan_id"))):
- return "no_concrete_step"
- return reason
-
-
-def _finding_exclusion(finding: Any, files: _Files) -> str | None:
- marker = field(finding, "biomarker_type")
- if marker in LOW_VALUE_KINDS or (
- (marker, detail_map(finding).get("kind")) in LOW_VALUE_DETAIL_KINDS
- ):
- return "low_value_kind"
- reason = files.unit_exclusion(
- field(finding, "file_path"),
- field(finding, "function_name"),
- complexity=field(finding, "biomarker_type") in SIZE_MARKERS,
- line=field(finding, "line_start"),
- )
- if reason is None and files.first_step(finding) is None:
- return "no_concrete_step"
- return reason
-
-
def _dead_spans(rows: Rows) -> dict[str, list[DeadSpan]]:
"""Sure, open dead-code findings by file: ``(symbol, start, end)``, the
symbol ``None`` for an unreachable file."""
@@ -1309,48 +1075,6 @@ def _clone_spans(plans: Iterable[Any]) -> dict[str, list[tuple[int, int]]]:
return dict(out)
-# --- order ------------------------------------------------------------------------
-
-
-def _order(units: list[_Unit]) -> list[_Unit]:
- ranked = sorted(
- units,
- key=lambda u: (
- u.tier == "later",
- -u.value,
- TIER_RANK[u.tier],
- -LEVEL_RANK.get(u.confidence, 0),
- EFFORT_RANK.get(u.effort, 1),
- -u.score,
- u.id,
- ),
- )
- head: list[_Unit] = []
- taken: Counter[str] = Counter()
- while ranked and len(head) < HEAD:
- pick = ranked[0]
- if taken[pick.kind] >= HEAD_PER_KIND:
- pick = next(
- (
- u
- for u in ranked
- if u.tier != "later"
- and u.kind != pick.kind
- and taken[u.kind] < HEAD_PER_KIND
- ),
- pick,
- )
- ranked.remove(pick)
- head.append(pick)
- taken[pick.kind] += 1
- out = head + ranked
- # A cause that may not lead stays in the list, behind the first that may.
- first = next((i for i, u in enumerate(out) if u.may_lead), 0)
- if first:
- out.insert(0, out.pop(first))
- return out
-
-
def _by_function(findings: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:
out: dict[tuple[str, str], list[Any]] = defaultdict(list)
for f in findings:
@@ -1406,7 +1130,6 @@ def build_fix_first(
metrics = list(metrics)
findings = list(findings)
keep_tests = scope == "all"
- excluded = dict.fromkeys(FIX_EXCLUSIONS, 0)
hidden = excluded_types()
by_file: dict[str, list[Any]] = defaultdict(list)
@@ -1429,25 +1152,24 @@ def build_fix_first(
_extractions(plans),
_dead_spans(dead_code),
)
- dormant_functions: set[tuple[str, str | None]] = set()
-
- def exclude(reason: str, path: str, symbol: str | None) -> None:
- excluded[reason] += 1
- if reason == "gated_off":
- dormant_functions.add((path, text.short_symbol(symbol)))
+ tally = Tally(FIX_EXCLUSIONS)
- def scope_reason(path: str, context: str | None = None) -> str | None:
- """Why ``path`` is out of scope, counted; ``None`` when it is in."""
- reason = _path_exclusion(path, files.is_test(path), context, files.origin(path))
- if reason is None or (reason == "test" and keep_tests):
- return None
- excluded[reason] += 1
- return reason
+ def exclude(verdict: Verdict, path: str, symbol: str | None = None) -> bool:
+ return tally.add(verdict, (path, text.short_symbol(symbol)))
- def out_of_scope(path: str, context: str | None = None) -> bool:
- return scope_reason(path, context) is not None
+ def scope_verdict(path: str, context: str | None = None) -> Verdict:
+ """Why ``path`` is out of scope, counted; eligible when it is in."""
+ verdict = path_verdict(
+ path, files.is_test(path), context, files.origin(path), keep_tests=keep_tests
+ )
+ tally.add(verdict)
+ return verdict
plan_rows = {field(p, "public_id"): p for p in plans}
+
+ def concrete(step: Mapping[str, Any]) -> bool:
+ return _concrete(step, plan_rows.get(step.get("plan_id")))
+
units: list[_Unit] = []
planned_files: set[str] = set()
refactoring_reasons: dict[str, str | None] = {}
@@ -1456,16 +1178,15 @@ def build_fix_first(
key=lambda r: (field(r, "rank_position") or 0, field(r, "opportunity_id")),
):
path = field(row, "file_path")
- reason = scope_reason(path)
+ verdict = scope_verdict(path)
details = detail_map(row)
steps = list(details.get("steps") or [])
gain = _num(field(row, "recoverable_health"))
- if reason is None:
- reason = _refactor_exclusion(gain, steps, plan_rows, files, path)
- if reason is not None:
- exclude(reason, path, steps[0].get("target_symbol") if steps else None)
- refactoring_reasons[field(row, "opportunity_id")] = reason
- if reason is not None:
+ if verdict.eligible:
+ verdict = refactor_verdict(gain, steps, files, path, concrete)
+ exclude(verdict, path, steps[0].get("target_symbol") if steps else None)
+ refactoring_reasons[field(row, "opportunity_id")] = verdict.reason
+ if not verdict.eligible:
continue
units.append(_refactor_unit(row, details, steps, gain, plan_rows, files))
# Only a plan that became an item speaks for the file's findings; an
@@ -1479,31 +1200,22 @@ def build_fix_first(
if _open(row):
path = field(row, "file_path") or ""
groups[(path, field(row, "intervention_symbol") or path)].append(row)
- # The performance queue's context and actionability rule decides which
- # causes are work; an unproven cost stays in, tiered later by
- # ``perf_low_priority``. Fix first adds its path rules and needs a stored
- # plan to quote.
perf_contexts = DEFAULT_QUEUE_CONTEXTS | {"test"} if keep_tests else DEFAULT_QUEUE_CONTEXTS
+ lines = symbol_lines or {}
for (path, symbol), rows in groups.items():
- if out_of_scope(path, "production"):
+ if not scope_verdict(path, "production").eligible:
continue
rows.sort(key=lambda r: (field(r, "rank_position") or 0, field(r, "opportunity_id")))
- reasons = [strategy_exclusion(r, perf_contexts) for r in rows]
- queued = [r for r, reason in zip(rows, reasons, strict=True) if reason is None]
- ready = [r for r in queued if _has_plan(r)]
- if not ready:
- # Dormant only when every row is: one live row speaks for the group.
- live = [r for r in reasons if r != "gated_off"]
- exclude("no_plan" if queued else (live[0] if live else "gated_off"), path, symbol)
- continue
- worth = [r for r in ready if _perf_worth(r)]
- if not worth:
- excluded["below_min_worth"] += 1
- continue
- if files.unreachable(path, symbol, (symbol_lines or {}).get(symbol)):
- excluded["unreachable"] += 1
- continue
- units.append(_perf_unit(worth, files, symbol_lines))
+ verdict, worth = perf_fix_verdict(
+ rows,
+ perf_contexts,
+ lambda path=path, symbol=symbol: files.unreachable(path, symbol, lines.get(symbol)),
+ )
+ if not exclude(verdict, path, symbol):
+ units.append(_perf_unit(worth, files, symbol_lines))
+
+ def first_step(finding: Any) -> bool:
+ return files.first_step(finding) is not None
for path, (shape, history) in split.items():
if path in planned_files:
@@ -1511,22 +1223,24 @@ def build_fix_first(
lead = primary_finding(shape)
if lead is None and not history:
continue # advisory only: nothing to fix, nothing to count
- if out_of_scope(path):
+ if not scope_verdict(path).eligible:
continue
if lead is None:
- excluded["history_only"] += 1
+ tally.add(Verdict("history_only"))
continue
# A finding that is no candidate leaves the file's others to compete;
# the file is counted under its own lead's reason when none is left.
- reasons = {id(f): _finding_exclusion(f, files) for f in shape}
- eligible = primary_finding([f for f in shape if reasons[id(f)] is None])
+ verdicts = {id(f): finding_verdict(f, files, first_step) for f in shape}
+ eligible = primary_finding([f for f in shape if verdicts[id(f)].eligible])
if eligible is None:
- culprit = lead if reasons[id(lead)] else next(f for f in shape if reasons[id(f)])
- exclude(reasons[id(culprit)], path, field(culprit, "function_name"))
+ culprit = lead if not verdicts[id(lead)].eligible else next(
+ f for f in shape if not verdicts[id(f)].eligible
+ )
+ exclude(verdicts[id(culprit)], path, field(culprit, "function_name"))
continue
units.append(_finding_unit(eligible, files, files.first_step(eligible), validate))
- ordered = _order(units)
+ ordered = order(units)
if item_id is not None:
shown = [(i, u) for i, u in enumerate(ordered) if u.id == item_id]
else:
@@ -1536,11 +1250,11 @@ def build_fix_first(
return FixFirstQueue(
items=tuple(u.write(rank) for rank, u in shown),
totals=FixTotals(
- candidates=len(units) + sum(excluded.values()),
+ candidates=len(units) + tally.total,
eligible=len(units),
shown=len(shown),
- excluded=excluded,
- dormant=len(dormant_functions),
+ excluded=tally.excluded,
+ dormant=len(tally.dormant),
),
by_improves={k: by_improves.get(k, 0) for k in FIX_IMPROVES},
basis=dict(basis) if basis is not None else _basis(metrics),
@@ -1553,16 +1267,7 @@ __all__ = [
"DEAD_CONFIDENCE",
"DEFAULT_LIMIT",
"DISPATCH_SHARE",
- "GAIN_CUTS",
- "GROWS_ONLY_MARKERS",
- "HEAD",
- "HEAD_PER_KIND",
- "LOW_VALUE_DETAIL_KINDS",
- "LOW_VALUE_KINDS",
- "MIN_WORTH",
"SIZE_MARKERS",
- "SMALL_CCN",
- "SMALL_NLOC",
"build_fix_first",
"hot_cut",
"hot_cut_offset",
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/model.py b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
index 7d93942a7..1011c836a 100644
--- a/packages/core/src/repowise/core/analysis/health/fix_first/model.py
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
@@ -10,12 +10,14 @@ import hashlib
from dataclasses import asdict, dataclass, field
from typing import Any, Literal, get_args
+from repowise.core.analysis.health.queue.eligibility import SCOPE_EXCLUSIONS
+from repowise.core.analysis.health.queue.order import DUE_TIERS, Tier
from repowise.core.analysis.next_call import ActionCommand
#: Bumped when ranking, eligibility or the item shape changes meaning.
FIX_FIRST_MODEL_VERSION = 1
-FixTier = Literal["now", "next", "later"]
+FixTier = Tier
FIX_TIERS: tuple[str, ...] = get_args(FixTier)
FixKind = Literal["refactor", "perf_fix", "finding"]
@@ -36,10 +38,11 @@ FIX_LEVELS: tuple[str, ...] = get_args(FixLevel)
FixFactBasis = Literal["measured", "inferred", "unknown"]
FIX_FACT_BASES: tuple[str, ...] = get_args(FixFactBasis)
-# ``unknown``, ``gated_off``, ``expected`` and ``no_strategy`` are the
-# performance default queue's own reasons (``opportunity_rank.DEFAULT_QUEUE_EXCLUSIONS``);
-# ``gated_off`` also keeps out any other unit in a function a constant-false
-# flag switches off. ``unreachable``: an open dead-code finding covers the target.
+# The reasons Fix first's ladders produce, from the one vocabulary in
+# ``queue.eligibility.Reason``. ``unknown``, ``gated_off``, ``cold_path``,
+# ``expected`` and ``no_strategy`` come from the performance ladder; ``gated_off``
+# also keeps out any other unit in a function a constant-false flag switches
+# off. ``unreachable``: an open dead-code finding covers the target.
FixExclusion = Literal[
"test",
"tooling",
@@ -60,23 +63,13 @@ FixExclusion = Literal[
"small_function",
"no_concrete_step",
"low_value_kind",
+ "kind_unaudited",
]
FIX_EXCLUSIONS: tuple[str, ...] = get_args(FixExclusion)
-#: Exclusions that say where the code lives, not whether the work is worth
-#: doing: a unit excluded for one of these was never in scope.
-SCOPE_EXCLUSIONS = frozenset({"test", "tooling", "generated", "vendored", "docs_example"})
-
-#: Tiers a unit is due in: worth scheduling now, not just worth listing.
-DUE_TIERS = frozenset({"now", "next"})
-
FixScope = Literal["production", "all"]
FIX_SCOPES: tuple[str, ...] = get_args(FixScope)
-TIER_RANK = {t: i for i, t in enumerate(FIX_TIERS)}
-LEVEL_RANK = {"high": 2, "medium": 1, "low": 0}
-EFFORT_RANK = {e: i for i, e in enumerate(FIX_EFFORTS)}
-
_ID_PREFIX = "fix1_"
@@ -285,8 +278,6 @@ class FixFirstQueue:
__all__ = [
- "DUE_TIERS",
- "EFFORT_RANK",
"FIX_EFFORTS",
"FIX_EXCLUSIONS",
"FIX_FACT_BASES",
@@ -297,9 +288,6 @@ __all__ = [
"FIX_LEVELS",
"FIX_SCOPES",
"FIX_TIERS",
- "LEVEL_RANK",
- "SCOPE_EXCLUSIONS",
- "TIER_RANK",
"FixAction",
"FixConfidence",
"FixContext",
diff --git a/packages/core/src/repowise/core/analysis/health/impact_effort.py b/packages/core/src/repowise/core/analysis/health/impact_effort.py
index 46659654c..a79e70bd1 100644
--- a/packages/core/src/repowise/core/analysis/health/impact_effort.py
+++ b/packages/core/src/repowise/core/analysis/health/impact_effort.py
@@ -21,8 +21,8 @@ from collections.abc import Iterable, Mapping
from dataclasses import asdict, dataclass
from typing import Any, Literal
-from repowise.core.analysis.health.fix_first.build import MIN_WORTH
-from repowise.core.analysis.health.fix_first.model import TIER_RANK
+from repowise.core.analysis.health.queue.eligibility import MIN_WORTH
+from repowise.core.analysis.health.queue.order import TIER_RANK
from repowise.core.analysis.health.rows import detail_map, field
#: The vertical midline, in lines to change. The work queue's Medium effort
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 c682238ac..34c1b067f 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
@@ -21,9 +21,7 @@ from math import log2
from typing import Any
from ..rank_common import top_factors, weakest
-from ..rows import detail_map, field
-from ..worth import cost_proof, lead_reason
-from .actionability import EXPECTED_REASONS
+from ..worth import lead_reason
BOUNDARY_POINTS = {"subprocess": 5, "network": 4, "db": 4, "lock": 3, "filesystem": 2}
"""What one crossing of each boundary costs, as an order of magnitude.
@@ -138,30 +136,6 @@ one, and the default queue leaves out what has no strategy at all, which is
what kept a generic sink's volume from crowding out actionable work.
"""
-DEFAULT_QUEUE_CONTEXTS = frozenset({"production"})
-DEFAULT_QUEUE_STATES = frozenset({"plan_ready", "advisory"})
-DEFAULT_QUEUE_PROOFS = frozenset({"proven"})
-"""What the queue holds when a caller names no filter: production work with a
-strategy whose cost is measured.
-
-Test, tooling and unclassified code, ``expected`` repetition, causes with no
-supported strategy (``investigate``, whose plan state is always ``no_safe_plan``)
-and causes whose loop nobody measured (``worth.cost_proof``) are true and stay one
-filter away, but none of them is work to schedule. Each is counted by
-:func:`default_queue_exclusion` so leaving it out is never silent.
-"""
-
-DEFAULT_QUEUE_EXCLUSIONS = (
- "test",
- "tooling",
- "unknown",
- *EXPECTED_REASONS,
- "expected",
- "no_strategy",
- "unmeasured_cost",
-)
-"""Every reason the default queue leaves a cause out, in the order it is checked."""
-
_LEVERAGE_BANDS = ((1, "isolated"), (3, "local"), (9, "shared"))
_CHANGE_RISK_BANDS = ((1, "contained"), (4, "moderate"))
@@ -290,53 +264,6 @@ def why_ranked(factors: dict[str, int], values: dict[str, Any], limit: int = 3)
)
-def strategy_exclusion(
- item: Any, contexts: frozenset[str] = DEFAULT_QUEUE_CONTEXTS
-) -> str | None:
- """Why *item* is no work to schedule, by context and state, or ``None``.
-
- Reads an opportunity, an ORM row or a plain row. *contexts* widens it for a
- caller that asked for more (Fix first's ``scope="all"`` keeps test code);
- the state rule never moves. Fix first reads this rather than the default
- queue because it keeps an unproven cause, as a ``later`` item.
- """
- context = field(item, "execution_context")
- if context not in contexts:
- return context
- state = field(item, "actionability_state")
- if state in DEFAULT_QUEUE_STATES:
- return None
- if state != "expected":
- return "no_strategy"
- reason = field(item, "actionability_reason") or detail_map(item).get("actionability_reason")
- return reason if reason in EXPECTED_REASONS else "expected"
-
-
-def default_queue_exclusion(item: Any) -> str | None:
- """Why the default queue leaves *item* out, or ``None`` when it is queued.
-
- One reason per cause, context first and proof last, so the counts of every
- reason and the queue add up to the whole.
- """
- reason = strategy_exclusion(item)
- if reason is None and cost_proof(item) not in DEFAULT_QUEUE_PROOFS:
- return "unmeasured_cost"
- return reason
-
-
-def default_queue_counts(items: list[Any]) -> dict[str, Any]:
- """The default queue's size and what it leaves out, by reason."""
- excluded = dict.fromkeys(DEFAULT_QUEUE_EXCLUSIONS, 0)
- queued = 0
- for item in items:
- reason = default_queue_exclusion(item)
- if reason is None:
- queued += 1
- else:
- excluded[reason] = excluded.get(reason, 0) + 1
- return {"total": queued, "excluded": excluded}
-
-
def rank_sort_key(item: Any) -> tuple[int, int, int, str]:
"""A total order: value first, then actionability, leverage, and id.
@@ -356,10 +283,6 @@ __all__ = [
"BOUNDARY_POINTS",
"CONTEXT_POINTS",
"CROSS_FUNCTION_POINTS",
- "DEFAULT_QUEUE_CONTEXTS",
- "DEFAULT_QUEUE_EXCLUSIONS",
- "DEFAULT_QUEUE_PROOFS",
- "DEFAULT_QUEUE_STATES",
"LEADING_ORMS",
"MAGNITUDE_POINTS",
"MULTIPLIER_POINTS",
@@ -369,8 +292,6 @@ __all__ = [
"amplification",
"band",
"change_risk",
- "default_queue_counts",
- "default_queue_exclusion",
"dominant_marker",
"exposure",
"leverage",
@@ -379,7 +300,6 @@ __all__ = [
"observation_rank",
"rank_factors",
"rank_sort_key",
- "strategy_exclusion",
"weakest_provenance",
"why_ranked",
]
diff --git a/packages/core/src/repowise/core/analysis/health/perf/serving.py b/packages/core/src/repowise/core/analysis/health/perf/serving.py
index 337a59212..246eb1241 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/serving.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/serving.py
@@ -19,12 +19,17 @@ from typing import TYPE_CHECKING, Any, Literal
from repowise.core.analysis.health import queue_rules
from repowise.core.analysis.health.finding_identity import finding_public_id
from repowise.core.analysis.health.fix_first.text import perf_cost
+from repowise.core.analysis.health.queue.eligibility import (
+ DEFAULT_QUEUE_PROOFS,
+ DEFAULT_QUEUE_STATES,
+ perf_low_priority,
+)
from repowise.core.analysis.health.queue_rules import NULL_VALUE, Facet, FilterRule, SortKeys
from repowise.core.analysis.health.rows import detail_map, field, json_field
-from repowise.core.analysis.health.worth import COST_PROOFS, LOW_PRIORITY_LABEL, perf_low_priority
+from repowise.core.analysis.health.worth import COST_PROOFS, LOW_PRIORITY_LABEL
from .opportunities import PERFORMANCE_MODEL_VERSION
-from .opportunity_rank import DEFAULT_QUEUE_PROOFS, DEFAULT_QUEUE_STATES, NON_LEADING_MARKERS
+from .opportunity_rank import NON_LEADING_MARKERS
if TYPE_CHECKING:
from .opportunities import PerformanceOpportunity
diff --git a/packages/core/src/repowise/core/analysis/health/queue/__init__.py b/packages/core/src/repowise/core/analysis/health/queue/__init__.py
new file mode 100644
index 000000000..b79a1c2f4
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/queue/__init__.py
@@ -0,0 +1,34 @@
+"""One queue: which units of work are eligible, what each is worth, and their order.
+
+``eligibility`` holds every default-queue ladder and the one :data:`Reason`
+vocabulary they count in; ``value`` scores and tiers a unit; ``order`` is the
+cross-kind order. Fix first, the performance default queue and the refactoring
+list's default scope read these instead of rules of their own.
+
+Not :mod:`..queue_rules`, which filters and sorts a materialized queue by the
+parameters a caller passes.
+"""
+
+from __future__ import annotations
+
+from .eligibility import (
+ ELIGIBLE,
+ REASONS,
+ Reason,
+ Tally,
+ Verdict,
+)
+from .order import order
+from .value import perf_value, shape_value, tier
+
+__all__ = [
+ "ELIGIBLE",
+ "REASONS",
+ "Reason",
+ "Tally",
+ "Verdict",
+ "order",
+ "perf_value",
+ "shape_value",
+ "tier",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/queue/eligibility.py b/packages/core/src/repowise/core/analysis/health/queue/eligibility.py
new file mode 100644
index 000000000..e2f7f9d0d
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/queue/eligibility.py
@@ -0,0 +1,470 @@
+"""Whether a unit of work belongs in a default queue, and the one reason when not.
+
+Every default list (Fix first, the performance default queue, the refactoring
+list's default scope) reads its ladder here and counts what it leaves out with
+:class:`Tally`, so a reason means the same thing on every surface and adding
+one is a change in one place.
+
+Each ladder returns a :class:`Verdict`. The facts a ladder needs beyond the
+row (a function's measured shape, dead code, whether a step is concrete) come
+from the caller, which already holds them.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol, get_args
+
+from repowise.core.code_origin import path_origin
+
+from ..perf.actionability import EXPECTED_REASONS
+from ..perf.causal import code_context
+from ..rows import detail_map, field
+from ..worth import (
+ SIZE_MARKERS,
+ LowPriority,
+ cost_proof,
+ dispatch_shaped,
+ dormant,
+ lead_reason,
+ perf_facets,
+)
+
+Reason = Literal[
+ "test",
+ "tooling",
+ "unknown",
+ "generated",
+ "expected",
+ "no_strategy",
+ "no_plan",
+ "below_min_worth",
+ "history_only",
+ "vendored",
+ "docs_example",
+ "deprecated",
+ "gated_off",
+ "cold_path",
+ "unreachable",
+ "inherent_dispatch",
+ "small_function",
+ "no_concrete_step",
+ "low_value_kind",
+ "kind_unaudited",
+ "unmeasured_cost",
+]
+"""Why a unit is out of a default queue. Each surface counts the subset its
+ladders can produce (``fix_first.model.FIX_EXCLUSIONS``,
+:data:`DEFAULT_QUEUE_EXCLUSIONS`)."""
+REASONS: tuple[str, ...] = get_args(Reason)
+
+
+@dataclass(frozen=True, slots=True)
+class Verdict:
+ """A unit's eligibility: ``reason`` is ``None`` when it is in the queue."""
+
+ reason: Reason | None = None
+
+ @property
+ def eligible(self) -> bool:
+ return self.reason is None
+
+
+ELIGIBLE = Verdict()
+
+
+def _verdict(reason: str | None) -> Verdict:
+ return ELIGIBLE if reason is None else Verdict(reason) # type: ignore[arg-type]
+
+
+class Tally:
+ """What a queue left out, by reason: the one place exclusions are counted.
+
+ ``reasons`` seeds every key a surface reports, zeros included; a reason
+ outside them is still counted. ``dormant`` collects the functions kept out
+ as ``gated_off``, by the key the caller names them with.
+ """
+
+ __slots__ = ("dormant", "excluded")
+
+ def __init__(self, reasons: Iterable[str] = ()) -> None:
+ self.excluded: dict[str, int] = dict.fromkeys(reasons, 0)
+ self.dormant: set[Any] = set()
+
+ def add(self, verdict: Verdict, dormant_key: Any = None) -> bool:
+ """Count ``verdict`` when it excludes; returns whether it did."""
+ reason = verdict.reason
+ if reason is None:
+ return False
+ self.excluded[reason] = self.excluded.get(reason, 0) + 1
+ if reason == "gated_off" and dormant_key is not None:
+ self.dormant.add(dormant_key)
+ return True
+
+ @property
+ def total(self) -> int:
+ return sum(self.excluded.values())
+
+ def by_reason(self) -> dict[str, int]:
+ """Non-zero counts, largest first, ties in the order first counted."""
+ return dict(sorted(((r, n) for r, n in self.excluded.items() if n), key=lambda i: -i[1]))
+
+
+# --- where the code lives ------------------------------------------------------
+
+#: Code origins that do not ship, by the reason each counts as. A build script
+#: is tooling to a reader choosing what to fix.
+ORIGIN_EXCLUSION: dict[str, Reason] = {
+ "test": "test",
+ "vendored": "vendored",
+ "docs_example": "docs_example",
+ "generated": "generated",
+ "tooling": "tooling",
+ "build": "tooling",
+}
+#: Reasons that say where the code lives, not whether the work is worth doing:
+#: a unit excluded for one of these was never in scope.
+SCOPE_EXCLUSIONS = frozenset(ORIGIN_EXCLUSION.values())
+
+# Pure on the path, and the test check dominates a cold Fix first build.
+_code_context = functools.lru_cache(maxsize=65536)(code_context)
+
+
+def path_verdict(
+ path: str,
+ is_test: bool | None,
+ context: str | None = None,
+ origin: str | None = None,
+ *,
+ keep_tests: bool = False,
+) -> Verdict:
+ """Whether a file's code is in scope.
+
+ The stored ``code_origin`` decides first: it read the file's head, so it
+ knows a vendored library or a docs tutorial the path alone does not.
+ Then the same classifier on the path (an index stored before the origin
+ column, or a build file classed before build files were), then the path
+ context. Code-shape work reads :func:`code_context`, where a CLI ships. A
+ performance fix passes ``production``: its stored execution context is
+ judged by the performance ladder. The stored ``is_test`` flag also marks a
+ test. ``keep_tests`` keeps test code in scope (Fix first's ``scope="all"``).
+ """
+ reason = _path_reason(path, is_test, context, origin)
+ if reason == "test" and keep_tests:
+ return ELIGIBLE
+ return _verdict(reason)
+
+
+def _path_reason(
+ path: str, is_test: bool | None, context: str | None, origin: str | None
+) -> Reason | None:
+ if origin in ORIGIN_EXCLUSION:
+ return ORIGIN_EXCLUSION[origin]
+ ctx = context or _code_context(path)
+ if is_test or ctx == "test":
+ return "test"
+ if reason := ORIGIN_EXCLUSION.get(path_origin(path)):
+ return reason
+ # ``unknown`` under a directory is docs, examples or demos at any depth:
+ # code that may not ship. A root-level file stays eligible.
+ if ctx == "tooling" or (ctx == "unknown" and "/" in path):
+ return "tooling"
+ return None
+
+
+# --- code shape: refactorings and findings --------------------------------------
+
+#: A refactoring whose credited gain is under this is not worth an item. The
+#: refactoring model credits only the share of a finding a plan removes and
+#: drops trivial spans itself (minimum worth), so this floor is on the file.
+MIN_WORTH = 0.5
+#: A function-level complexity unit needs this many code lines or this CCN.
+#: Picked on the dev labels (67 complexity rows): 30 / 15 drops 13 rejected
+#: small functions and 4 accepted ones; no cut that keeps every accepted row
+#: drops more than 4 rejected.
+SMALL_NLOC = 30
+SMALL_CCN = 15
+#: Kinds the baseline raters found not worth doing: a refactoring led by one
+#: of these steps, or a plan-less finding led by one of these markers, is no
+#: candidate (it stays in the refactoring tab). Worth over rater labels, dev
+#: repos first, then all 17 baseline repos.
+LOW_VALUE_KINDS: dict[str, str] = {
+ "low_cohesion": "dev 0/26, all 0/46",
+ "large_method": "dev 0/4, all 0/10",
+ # Thinly measured: one held-out item (two labels), none on the dev repos.
+ # A low-value maintainability nudge that otherwise fills a small repo's
+ # whole top three; revisit when more of it is labelled.
+ "primitive_obsession": "dev 0/0, all 0/2",
+}
+#: The same, for one detail ``kind`` of a marker whose other kinds stay. A Rust
+#: unwrap or panic is a crash path, not the hidden failure the error-handling
+#: item describes, and the raters found it not worth doing first. Both kinds
+#: were rated together on ripgrep, fd, serde and mini-redis.
+LOW_VALUE_DETAIL_KINDS: dict[tuple[str, str], str] = {
+ ("error_handling", "unsafe_unwrap"): "rust all 1/19",
+ ("error_handling", "panic_macro"): "rust all 1/19",
+}
+#: Refactoring kinds served only in the full inventory until each passes a
+#: per-language audit; until then a plan they lead is never a queue item. The
+#: rater worth that first kept them out, dev repos then all 17 baseline repos.
+UNAUDITED_KINDS: dict[str, str] = {
+ "extract_class": "dev 0/6, all 0/14",
+ "move_method": "dev 0/14, all 0/34",
+}
+
+
+class UnitFacts(Protocol):
+ """What the code-shape ladders read about a function beyond its row."""
+
+ def unreachable(self, path: str, symbol: str | None, line: int | None) -> bool: ...
+
+ def shape(self, path: str, symbol: str | None) -> Mapping[str, int]: ...
+
+ def cloned(self, path: str, shape: Mapping[str, int]) -> bool: ...
+
+
+def small(shape: Mapping[str, int]) -> bool:
+ """Under both size floors. A function whose size findings carry no line
+ count is measured by its span, which bounds its code lines from above; one
+ with neither is not judged small."""
+ nloc = shape.get("nloc")
+ if not nloc and shape.get("start") and shape.get("end"):
+ nloc = shape["end"] - shape["start"] + 1
+ if not nloc:
+ return False
+ return nloc < SMALL_NLOC and shape.get("ccn", 0) < SMALL_CCN
+
+
+def unit_verdict(
+ facts: UnitFacts, path: str, symbol: str | None, *, complexity: bool, line: int | None = None
+) -> Verdict:
+ """Whether a unit on ``symbol`` is worth an item.
+
+ Unreachable code is deleted, not fixed. A deprecated function is on its
+ way out, and a dormant one does not run. A complexity unit on a function
+ that is mostly one dispatch on one value is usually fine as it is, unless
+ a duplicate also sits in it; one on a small function is not worth an item.
+ """
+ if facts.unreachable(path, symbol, line):
+ return Verdict("unreachable")
+ shape = facts.shape(path, symbol)
+ if shape.get("deprecated"):
+ return Verdict("deprecated")
+ if dormant(shape):
+ return Verdict("gated_off")
+ if not complexity:
+ return ELIGIBLE
+ if dispatch_shaped(shape) and not facts.cloned(path, shape):
+ return Verdict("inherent_dispatch")
+ if small(shape):
+ return Verdict("small_function")
+ return ELIGIBLE
+
+
+def refactor_verdict(
+ gain: float,
+ steps: list[Mapping[str, Any]],
+ facts: UnitFacts,
+ path: str,
+ concrete: Callable[[Mapping[str, Any]], bool],
+) -> Verdict:
+ """Whether an open refactoring opportunity in scope is a candidate.
+ ``concrete(step)`` says whether its lead step names an edit to make."""
+ if gain < MIN_WORTH or not steps:
+ return Verdict("below_min_worth")
+ lead = steps[0]
+ kind = lead.get("refactoring_type")
+ if kind in UNAUDITED_KINDS:
+ return Verdict("kind_unaudited")
+ if kind in LOW_VALUE_KINDS:
+ return Verdict("low_value_kind")
+ verdict = unit_verdict(
+ facts,
+ path,
+ lead.get("target_symbol"),
+ complexity=kind == "extract_method",
+ line=lead.get("line_start"),
+ )
+ if verdict.eligible and not concrete(lead):
+ return Verdict("no_concrete_step")
+ return verdict
+
+
+def finding_verdict(
+ finding: Any, facts: UnitFacts, concrete: Callable[[Any], bool]
+) -> Verdict:
+ """Whether a finding with no plan is a candidate. ``concrete(finding)``
+ says whether it has a first edit to name."""
+ marker = field(finding, "biomarker_type")
+ if marker in LOW_VALUE_KINDS or (
+ (marker, detail_map(finding).get("kind")) in LOW_VALUE_DETAIL_KINDS
+ ):
+ return Verdict("low_value_kind")
+ verdict = unit_verdict(
+ facts,
+ field(finding, "file_path"),
+ field(finding, "function_name"),
+ complexity=marker in SIZE_MARKERS,
+ line=field(finding, "line_start"),
+ )
+ if verdict.eligible and not concrete(finding):
+ return Verdict("no_concrete_step")
+ return verdict
+
+
+# --- performance ------------------------------------------------------------------
+
+DEFAULT_QUEUE_CONTEXTS = frozenset({"production"})
+DEFAULT_QUEUE_STATES = frozenset({"plan_ready", "advisory"})
+DEFAULT_QUEUE_PROOFS = frozenset({"proven"})
+"""What the performance queue holds when a caller names no filter: production
+work with a strategy whose cost is measured.
+
+Test, tooling and unclassified code, ``expected`` repetition, causes with no
+supported strategy (``investigate``, whose plan state is always ``no_safe_plan``)
+and causes whose loop nobody measured (``worth.cost_proof``) are true and stay one
+filter away, but none of them is work to schedule. Each is counted by
+:func:`perf_queue_counts` so leaving it out is never silent.
+"""
+
+DEFAULT_QUEUE_EXCLUSIONS = (
+ "test",
+ "tooling",
+ "unknown",
+ *EXPECTED_REASONS,
+ "expected",
+ "no_strategy",
+ "unmeasured_cost",
+)
+"""Every reason the performance default queue leaves a cause out, in the order
+it is checked."""
+
+#: Causes whose cost is real only in shipped code over a loop that grows: a
+#: string built in a bounded loop, or in a script, costs nothing a user sees.
+GROWS_ONLY_MARKERS = frozenset({"string_concat_in_loop"})
+
+
+def perf_strategy_verdict(
+ item: Any, contexts: frozenset[str] = DEFAULT_QUEUE_CONTEXTS
+) -> Verdict:
+ """Whether a cause is work to schedule, by context and state.
+
+ Reads an opportunity, an ORM row or a plain row. *contexts* widens it for a
+ caller that asked for more (Fix first's ``scope="all"`` keeps test code);
+ the state rule never moves. Fix first reads this rather than
+ :func:`perf_queue_verdict` because it keeps an unproven cause, as a
+ ``later`` item.
+ """
+ context = field(item, "execution_context")
+ if context not in contexts:
+ return _verdict(context)
+ state = field(item, "actionability_state")
+ if state in DEFAULT_QUEUE_STATES:
+ return ELIGIBLE
+ if state != "expected":
+ return Verdict("no_strategy")
+ reason = field(item, "actionability_reason") or detail_map(item).get("actionability_reason")
+ return _verdict(reason if reason in EXPECTED_REASONS else "expected")
+
+
+def perf_queue_verdict(item: Any) -> Verdict:
+ """Whether the performance default queue holds *item*.
+
+ One reason per cause, context first and proof last, so the counts of every
+ reason and the queue add up to the whole.
+ """
+ verdict = perf_strategy_verdict(item)
+ if verdict.eligible and cost_proof(item) not in DEFAULT_QUEUE_PROOFS:
+ return Verdict("unmeasured_cost")
+ return verdict
+
+
+def perf_queue_counts(items: Iterable[Any]) -> dict[str, Any]:
+ """The performance default queue's size and what it leaves out, by reason."""
+ tally = Tally(DEFAULT_QUEUE_EXCLUSIONS)
+ queued = 0
+ for item in items:
+ if not tally.add(perf_queue_verdict(item)):
+ queued += 1
+ return {"total": queued, "excluded": tally.excluded}
+
+
+def perf_low_priority(row: Any) -> LowPriority | None:
+ """Why a performance cause can wait: it runs outside production code, or
+ :func:`worth.lead_reason` holds it back."""
+ context = field(row, "execution_context")
+ if context != "production":
+ return "unknown_context" if context in (None, "unknown") else "not_production"
+ return lead_reason(field(row, "biomarker_type"), perf_facets(row))
+
+
+def _has_plan(row: Any) -> bool:
+ return field(row, "plan_state") == "available" and bool(field(row, "fix_strategy"))
+
+
+def _perf_worth(row: Any) -> bool:
+ """Whether a planned cause is worth an item at all."""
+ return field(row, "biomarker_type") not in GROWS_ONLY_MARKERS or perf_low_priority(row) is None
+
+
+def perf_fix_verdict(
+ rows: list[Any], contexts: frozenset[str], unreachable: Callable[[], bool]
+) -> tuple[Verdict, list[Any]]:
+ """Whether the causes one intervention groups make a Fix first item, and
+ the rows worth one.
+
+ The performance queue's context and actionability rule decides which
+ causes are work; an unproven cost stays in, tiered later by
+ :func:`perf_low_priority`. An item needs a stored plan to quote.
+ ``unreachable()`` says whether dead code covers the intervention.
+ """
+ verdicts = [perf_strategy_verdict(r, contexts) for r in rows]
+ queued = [r for r, v in zip(rows, verdicts, strict=True) if v.eligible]
+ ready = [r for r in queued if _has_plan(r)]
+ if not ready:
+ if queued:
+ return Verdict("no_plan"), []
+ # Dormant only when every row is: one live row speaks for the group.
+ live = [v for v in verdicts if v.reason != "gated_off"]
+ return (live[0] if live else Verdict("gated_off")), []
+ worth = [r for r in ready if _perf_worth(r)]
+ if not worth:
+ return Verdict("below_min_worth"), []
+ if unreachable():
+ return Verdict("unreachable"), []
+ return ELIGIBLE, worth
+
+
+__all__ = [
+ "DEFAULT_QUEUE_CONTEXTS",
+ "DEFAULT_QUEUE_EXCLUSIONS",
+ "DEFAULT_QUEUE_PROOFS",
+ "DEFAULT_QUEUE_STATES",
+ "ELIGIBLE",
+ "GROWS_ONLY_MARKERS",
+ "LOW_VALUE_DETAIL_KINDS",
+ "LOW_VALUE_KINDS",
+ "MIN_WORTH",
+ "ORIGIN_EXCLUSION",
+ "REASONS",
+ "SCOPE_EXCLUSIONS",
+ "SMALL_CCN",
+ "SMALL_NLOC",
+ "UNAUDITED_KINDS",
+ "Reason",
+ "Tally",
+ "UnitFacts",
+ "Verdict",
+ "finding_verdict",
+ "path_verdict",
+ "perf_fix_verdict",
+ "perf_low_priority",
+ "perf_queue_counts",
+ "perf_queue_verdict",
+ "perf_strategy_verdict",
+ "refactor_verdict",
+ "small",
+ "unit_verdict",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/queue/order.py b/packages/core/src/repowise/core/analysis/health/queue/order.py
new file mode 100644
index 000000000..d99355245
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/queue/order.py
@@ -0,0 +1,104 @@
+"""The one cross-kind order of eligible work: tier, value, confidence, effort.
+
+Reads any unit with ``id``, ``kind``, ``tier``, ``value``, ``score``,
+``confidence``, ``effort`` and ``may_lead``. Imports nothing from the
+surfaces, so each of them can read the rank tables from here.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Literal, Protocol, TypeVar, get_args
+
+from ..effort import EFFORT_ORDER
+
+Tier = Literal["now", "next", "later"]
+TIERS: tuple[str, ...] = get_args(Tier)
+#: Tiers a unit is due in: worth scheduling now, not just worth listing.
+DUE_TIERS = frozenset({"now", "next"})
+
+TIER_RANK = {t: i for i, t in enumerate(TIERS)}
+LEVEL_RANK = {"high": 2, "medium": 1, "low": 0}
+EFFORT_RANK = {e: i for i, e in enumerate(EFFORT_ORDER)}
+
+#: In the first HEAD places no kind takes more than HEAD_PER_KIND, unless the
+#: other kinds have nothing above the later tier.
+HEAD = 5
+HEAD_PER_KIND = 3
+
+
+class Ranked(Protocol):
+ @property
+ def id(self) -> str: ...
+ @property
+ def kind(self) -> str: ...
+ @property
+ def tier(self) -> str: ...
+ @property
+ def value(self) -> int: ...
+ @property
+ def score(self) -> float: ...
+ @property
+ def confidence(self) -> str: ...
+ @property
+ def effort(self) -> str: ...
+ @property
+ def may_lead(self) -> bool: ...
+
+
+R = TypeVar("R", bound=Ranked)
+
+
+def _key(u: Ranked) -> tuple[bool, int, int, int, int, float, str]:
+ return (
+ u.tier == "later",
+ -u.value,
+ TIER_RANK[u.tier],
+ -LEVEL_RANK.get(u.confidence, 0),
+ EFFORT_RANK.get(u.effort, 1),
+ -u.score,
+ u.id,
+ )
+
+
+def order(units: list[R]) -> list[R]:
+ """``units`` in queue order: by :func:`_key`, the head spread across kinds,
+ and a unit that may not lead behind the first that may."""
+ ranked = sorted(units, key=_key)
+ head: list[R] = []
+ taken: Counter[str] = Counter()
+ while ranked and len(head) < HEAD:
+ pick = ranked[0]
+ if taken[pick.kind] >= HEAD_PER_KIND:
+ pick = next(
+ (
+ u
+ for u in ranked
+ if u.tier != "later"
+ and u.kind != pick.kind
+ and taken[u.kind] < HEAD_PER_KIND
+ ),
+ pick,
+ )
+ ranked.remove(pick)
+ head.append(pick)
+ taken[pick.kind] += 1
+ out = head + ranked
+ first = next((i for i, u in enumerate(out) if u.may_lead), 0)
+ if first:
+ out.insert(0, out.pop(first))
+ return out
+
+
+__all__ = [
+ "DUE_TIERS",
+ "EFFORT_RANK",
+ "HEAD",
+ "HEAD_PER_KIND",
+ "LEVEL_RANK",
+ "TIERS",
+ "TIER_RANK",
+ "Ranked",
+ "Tier",
+ "order",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/queue/value.py b/packages/core/src/repowise/core/analysis/health/queue/value.py
new file mode 100644
index 000000000..3d2d39d63
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/queue/value.py
@@ -0,0 +1,91 @@
+"""How much a unit of work is worth, 0 to :data:`VALUE_MAX`, and the tier it earns.
+
+Code shape sets the value; a hot file adds one step, and history never lifts a
+unit into a higher tier (:func:`tier` reads the value without that step).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..rows import field
+from ..worth import LOW_PRIORITY_LABEL, lead_reason, magnitude
+from .order import LEVEL_RANK
+
+#: Credited health gain cut points for value 1, 2 and 3.
+GAIN_CUTS = (0.5, 1.5, 3.0)
+#: A critical finding or a brain method is at least this size. Problem size
+#: (:func:`size_value`) reads ``worth.SIZE_*`` because health credit is
+#: calibrated per finding and saturates: a function far past every bar would
+#: rank with a tidy one on gain alone.
+SIZE_SEVERE = 2
+#: The highest value any unit reaches.
+VALUE_MAX = 4
+
+
+def gain_value(gain: float, hot: bool) -> int:
+ return min(3, sum(gain >= cut for cut in GAIN_CUTS) + int(hot))
+
+
+def size_value(shape: Mapping[str, int], hot: bool) -> int:
+ """How big the problem is, 0 to 4; a hot file counts one more."""
+ base = max(magnitude(shape), SIZE_SEVERE if shape.get("severe") else 0)
+ return min(VALUE_MAX, base + int(hot and base > 0))
+
+
+def shape_value(gain: float, shape: Mapping[str, int], cloned: bool, *, hot: bool) -> int:
+ """A refactoring's or a finding's value: the larger of the gain and the
+ problem size, one step more when a duplicate sits in the same function:
+ raters accepted that shape almost every time."""
+ value = max(gain_value(gain, hot), size_value(shape, hot))
+ return min(VALUE_MAX, value + 1) if cloned else value
+
+
+def perf_value(row: Any, facets: Mapping[str, Any]) -> int:
+ """A performance cause's value. A production, entry-reachable database or
+ network call in a loop that grows with the data is the costliest kind of
+ work Fix first holds, so it shares the top band with the largest
+ functions; capped below it, it never reached a top ten that size fills."""
+ production = field(row, "execution_context") == "production"
+ reachable = facets.get("exposure") == "entry_reachable"
+ reason = lead_reason(field(row, "biomarker_type"), facets)
+ if (
+ production
+ and reachable
+ and facets.get("loop_magnitude") == "grows_with_data"
+ and field(row, "boundary_kind") in ("db", "network")
+ ):
+ return VALUE_MAX
+ value = 2 if production and reason is None else 1
+ # No traffic data: a loop of unknown size that no entry point reaches is
+ # most often an admin or maintenance path, where an N+1 is cheap.
+ if reason == "unmeasured_cost" and not reachable:
+ value -= 1
+ return value
+
+
+def tier(value: int, confidence: str, ready: bool, low: str | None) -> tuple[str, str]:
+ """The tier and its reason, from a value that leaves the hot-file bonus
+ out: history orders items within a tier but never lifts one. A problem
+ the shape rule calls lower priority (``worth.low_priority``) is ``later``
+ whatever its value."""
+ if low is not None:
+ return "later", LOW_PRIORITY_LABEL[low]
+ if value >= 2 and LEVEL_RANK.get(confidence, 0) >= 1 and ready:
+ return "now", "worth doing, and the plan is safe to start"
+ if value >= 2:
+ return "next", "worth doing; the fix needs judgment"
+ return "later", "smaller payoff"
+
+
+__all__ = [
+ "GAIN_CUTS",
+ "SIZE_SEVERE",
+ "VALUE_MAX",
+ "gain_value",
+ "perf_value",
+ "shape_value",
+ "size_value",
+ "tier",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/worth.py b/packages/core/src/repowise/core/analysis/health/worth.py
index 56c54005e..a4d1ed919 100644
--- a/packages/core/src/repowise/core/analysis/health/worth.py
+++ b/packages/core/src/repowise/core/analysis/health/worth.py
@@ -318,15 +318,6 @@ def cost_proof(row: Any) -> CostProof:
return "unproven" if reason == "unmeasured_cost" else "proven"
-def perf_low_priority(row: Any) -> LowPriority | None:
- """Why a performance opportunity can wait: it runs outside production
- code, or :func:`lead_reason` holds it back."""
- context = field(row, "execution_context")
- if context != "production":
- return "unknown_context" if context in (None, "unknown") else "not_production"
- return lead_reason(field(row, "biomarker_type"), perf_facets(row))
-
-
__all__ = [
"CHAIN_SHARE",
"COST_PROOFS",
@@ -350,6 +341,5 @@ __all__ = [
"magnitude",
"measure",
"perf_facets",
- "perf_low_priority",
"worth_size",
]
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py b/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py
index 9eabf5350..1344f50fe 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py
@@ -41,11 +41,10 @@ from repowise.core.analysis.health.fix_first import (
)
from repowise.core.analysis.health.fix_first.build import (
DEAD_CONFIDENCE,
- MIN_WORTH,
hot_cut,
hot_cut_offset,
)
-from repowise.core.analysis.health.perf.opportunity_rank import DEFAULT_QUEUE_STATES
+from repowise.core.analysis.health.queue.eligibility import DEFAULT_QUEUE_STATES, MIN_WORTH
from repowise.core.analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
from repowise.core.analysis.health.refactoring.models import (
RefactoringSuggestion as PlanSuggestion,
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 229d838d0..b18b55c97 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py
@@ -137,11 +137,8 @@ def _summary_payload(
plans: dict[str, dict[str, Any]] | None = None,
) -> dict:
"""The compact current headline, written once and read by primary key."""
- from ....analysis.health.perf.opportunity_rank import (
- default_queue_counts,
- default_queue_exclusion,
- )
from ....analysis.health.perf.serving import intervention_file
+ from ....analysis.health.queue.eligibility import perf_queue_counts, perf_queue_verdict
from ....analysis.health.worth import cost_proof
counts: dict[str, int] = {}
@@ -161,12 +158,12 @@ def _summary_payload(
(
o
for o in opportunities
- if default_queue_exclusion(o) is None and o.may_lead
+ if perf_queue_verdict(o).eligible and o.may_lead
),
None,
)
return {
- "default_queue": default_queue_counts(opportunities),
+ "default_queue": perf_queue_counts(opportunities),
"actionability": counts,
"context": contexts,
"boundary": boundaries,
diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.py
index ece3a7a3a..494ec4e02 100644
--- a/packages/server/src/repowise/server/services/refactoring_health.py
+++ b/packages/server/src/repowise/server/services/refactoring_health.py
@@ -18,13 +18,13 @@ index time; this module reads what the finalizer wrote.
from __future__ import annotations
-from collections import Counter
from dataclasses import dataclass, field
from typing import Any, Literal
from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.health.queue.eligibility import Tally, Verdict
from repowise.core.analysis.health.queue_rules import keep, sort_key
from repowise.core.analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
from repowise.core.analysis.health.refactoring.recommendations import (
@@ -335,8 +335,11 @@ class RefactoringHealthService:
# The queue is keyed on the stores' newest write, so it has read every
# open id; one written between the two reads is in neither count.
shown = [i for i in matched if i in reasons and reasons[i] is None]
- left_out = Counter(r for i in matched if (r := reasons.get(i)))
- return shown, {"total": sum(left_out.values()), "by_reason": dict(left_out.most_common())}
+ left_out = Tally()
+ for i in matched:
+ if reason := reasons.get(i):
+ left_out.add(Verdict(reason))
+ return shown, {"total": left_out.total, "by_reason": left_out.by_reason()}
# -- headline ---------------------------------------------------------
diff --git a/packages/types/src/fix-first.ts b/packages/types/src/fix-first.ts
index 15f45a5ec..69bf04994 100644
--- a/packages/types/src/fix-first.ts
+++ b/packages/types/src/fix-first.ts
@@ -43,7 +43,8 @@ export type FixExclusion =
| "inherent_dispatch"
| "small_function"
| "no_concrete_step"
- | "low_value_kind";
+ | "low_value_kind"
+ | "kind_unaudited";
/** `all` keeps test files, labelled in `context`. */
export type FixScope = "production" | "all";
diff --git a/packages/types/src/health.ts b/packages/types/src/health.ts
index e78dc7219..108760142 100644
--- a/packages/types/src/health.ts
+++ b/packages/types/src/health.ts
@@ -615,7 +615,7 @@ export type PerformanceOpportunityQuery = {
offset?: number;
};
-/** Why the default queue leaves a cause out (`opportunity_rank.DEFAULT_QUEUE_EXCLUSIONS`). */
+/** Why the default queue leaves a cause out (`queue.eligibility.DEFAULT_QUEUE_EXCLUSIONS`). */
export type PerformanceQueueExclusion =
| "test"
| "tooling"
diff --git a/packages/ui/__tests__/health/fixtures/fix-first.ts b/packages/ui/__tests__/health/fixtures/fix-first.ts
index c6a8a377e..81794cb79 100644
--- a/packages/ui/__tests__/health/fixtures/fix-first.ts
+++ b/packages/ui/__tests__/health/fixtures/fix-first.ts
@@ -622,7 +622,8 @@ export const FIX_FIRST_QUEUE: FixFirstQueue = {
"inherent_dispatch": 0,
"small_function": 0,
"no_concrete_step": 0,
- "low_value_kind": 0
+ "low_value_kind": 0,
+ "kind_unaudited": 0
},
"dormant": 0
},
diff --git a/packages/ui/src/health/fix-first/scope.ts b/packages/ui/src/health/fix-first/scope.ts
index 95453bf6a..c63398f3a 100644
--- a/packages/ui/src/health/fix-first/scope.ts
+++ b/packages/ui/src/health/fix-first/scope.ts
@@ -50,6 +50,7 @@ export const EXCLUSION_LABEL: Record<FixExclusion, string> = {
small_function: "small functions",
no_concrete_step: "with no concrete first edit",
low_value_kind: "of a kind rarely worth doing",
+ kind_unaudited: "of a kind not yet audited for this list",
};
const EXCLUSION_ORDER: FixExclusion[] = [
@@ -72,6 +73,7 @@ const EXCLUSION_ORDER: FixExclusion[] = [
"small_function",
"no_concrete_step",
"low_value_kind",
+ "kind_unaudited",
];
/**
diff --git a/packages/web/src/components/code-health/fix-first-section.test.tsx b/packages/web/src/components/code-health/fix-first-section.test.tsx
index 024b0bb2f..a60d1185c 100644
--- a/packages/web/src/components/code-health/fix-first-section.test.tsx
+++ b/packages/web/src/components/code-health/fix-first-section.test.tsx
@@ -77,6 +77,7 @@ function queue(items: FixItem[]): FixFirstQueue {
small_function: 0,
no_concrete_step: 0,
low_value_kind: 0,
+ kind_unaudited: 0,
},
dormant: 0,
},
diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.py
index e26c730c3..0d980ae7d 100644
--- a/tests/unit/health/test_fix_first_build.py
+++ b/tests/unit/health/test_fix_first_build.py
@@ -58,6 +58,7 @@ def test_each_exclusion_is_counted_by_reason() -> None:
"small_function": 0,
"no_concrete_step": 0,
"low_value_kind": 0,
+ "kind_unaudited": 0,
}
assert queue.totals.dormant == 0
assert queue.totals.eligible == 3
@@ -251,3 +252,29 @@ def test_a_finding_item_takes_its_tests_from_the_validate_callback() -> None:
assert walk.verify.basis == "inferred"
assert [t.path for t in walk.verify.tests] == ["tests/test_plain.py::test_walk"]
assert "call graph" in walk.verify.tests[0].reason
+
+
+def test_fix_first_counts_only_in_its_own_reasons() -> None:
+ """The shared tally takes any reason, so a ladder that grew one Fix first
+ does not report would surface here, not on the wire."""
+ moved = {**REFACTORING[0], "opportunity_id": "refop2_move", "file_path": "src/move.py",
+ "details": {"steps": [_step_kind("move_method")]}}
+ rows = {
+ "refactoring": [*REFACTORING, moved],
+ "performance": [
+ *PERFORMANCE,
+ _perf("perf2_cold", "c", intervention_symbol="src/repo.py::boot",
+ actionability_state="expected", actionability_reason="cold_path"),
+ _perf("perf2_unmeasured", "u", intervention_symbol="src/repo.py::guess",
+ details={"facets": {"loop_magnitude": "unknown"}}),
+ ],
+ }
+ for scope in ("production", "all"):
+ queue = _build(scope=scope, **rows)
+ assert set(queue.totals.excluded) == set(FIX_EXCLUSIONS)
+ assert queue.totals.excluded["kind_unaudited"] == 1
+
+
+def _step_kind(kind: str) -> dict:
+ return {"plan_id": "refac2_mv", "refactoring_type": kind, "target_symbol": "src/move.py::run",
+ "file_path": "src/move.py", "line_start": 5}
diff --git a/tests/unit/health/test_fix_first_closeout.py b/tests/unit/health/test_fix_first_closeout.py
index c37ad11df..632f2d812 100644
--- a/tests/unit/health/test_fix_first_closeout.py
+++ b/tests/unit/health/test_fix_first_closeout.py
@@ -7,7 +7,7 @@ import re
import pytest
from repowise.core.analysis.health.fix_first import FixFirstQueue, build_fix_first
-from repowise.core.analysis.health.fix_first.build import LOW_VALUE_KINDS
+from repowise.core.analysis.health.queue.eligibility import LOW_VALUE_KINDS
from repowise.core.analysis.health.refactoring.performance_fix import fix_steps
from tests.unit.health.fix_first_rows import FINDINGS, METRICS, _perf
diff --git a/tests/unit/health/test_fix_first_precision.py b/tests/unit/health/test_fix_first_precision.py
index 8b6f31760..80ddf3ab2 100644
--- a/tests/unit/health/test_fix_first_precision.py
+++ b/tests/unit/health/test_fix_first_precision.py
@@ -482,7 +482,7 @@ def test_a_module_scope_cause_reads_module_scope_of_its_file() -> None:
def test_a_production_reachable_growing_db_loop_is_in_the_top_band() -> None:
- from repowise.core.analysis.health.fix_first.build import VALUE_MAX
+ from repowise.core.analysis.health.queue.value import VALUE_MAX
assert _value(loop_magnitude="grows_with_data", exposure="entry_reachable") == str(VALUE_MAX)
@@ -526,11 +526,13 @@ def test_a_one_line_block_reads_as_one_line() -> None:
# --- kinds the baseline raters found not worth doing -------------------------------
-def test_extract_class_and_move_method_plans_are_low_value() -> None:
+def test_extract_class_and_move_method_plans_wait_for_their_audit() -> None:
plan = {"groups": [{"methods": ["load", "save"], "fields": ["db"]}]}
- assert _refactor_queue("extract_class", plan).totals.excluded["low_value_kind"] == 1
+ split = _refactor_queue("extract_class", plan)
+ assert split.items == () and split.totals.excluded["kind_unaudited"] == 1
moved = _refactor_queue("move_method", {"to_class": "Ledger"})
- assert moved.items == () and moved.totals.excluded["low_value_kind"] == 1
+ assert moved.items == () and moved.totals.excluded["kind_unaudited"] == 1
+ assert moved.totals.excluded["low_value_kind"] == 0
def test_large_method_and_low_cohesion_findings_are_low_value() -> None:
diff --git a/tests/unit/health/test_gated_off.py b/tests/unit/health/test_gated_off.py
index 5494156ab..51a8b9d0a 100644
--- a/tests/unit/health/test_gated_off.py
+++ b/tests/unit/health/test_gated_off.py
@@ -15,10 +15,7 @@ from repowise.core.analysis.health.finding_identity import finding_public_id
from repowise.core.analysis.health.fix_first import build_fix_first
from repowise.core.analysis.health.models import HealthFindingData, Severity
from repowise.core.analysis.health.perf.opportunities import build_performance_opportunities
-from repowise.core.analysis.health.perf.opportunity_rank import (
- default_queue_counts,
- default_queue_exclusion,
-)
+from repowise.core.analysis.health.queue.eligibility import perf_queue_counts, perf_queue_verdict
from tests.unit.health.fix_first_rows import FINDINGS, METRICS, REFACTORING, _perf
# The shape of ``decisions/evolution.py``: a documented kill switch, then a
@@ -250,8 +247,8 @@ def test_a_cause_in_a_gated_function_leaves_the_performance_default_queue() -> N
None,
)
assert live.actionability_state != "expected"
- assert default_queue_exclusion(gated) == "gated_off"
- assert default_queue_counts([gated, live])["excluded"]["gated_off"] == 1
+ assert perf_queue_verdict(gated).reason == "gated_off"
+ assert perf_queue_counts([gated, live])["excluded"]["gated_off"] == 1
def test_one_live_call_site_keeps_the_cause() -> None:
diff --git a/tests/unit/health/test_perf_cold_paths.py b/tests/unit/health/test_perf_cold_paths.py
index 41aa03c3b..29c72fcfe 100644
--- a/tests/unit/health/test_perf_cold_paths.py
+++ b/tests/unit/health/test_perf_cold_paths.py
@@ -13,7 +13,7 @@ from repowise.core.analysis.health.models import HealthFindingData, Severity
from repowise.core.analysis.health.perf.causal import execution_context
from repowise.core.analysis.health.perf.cold_paths import is_cold_path
from repowise.core.analysis.health.perf.opportunities import build_performance_opportunities
-from repowise.core.analysis.health.perf.opportunity_rank import default_queue_exclusion
+from repowise.core.analysis.health.queue.eligibility import perf_queue_verdict
def _finding(path: str, function: str) -> HealthFindingData:
@@ -89,7 +89,7 @@ def test_a_migration_loop_leaves_the_default_queue_as_expected() -> None:
assert opportunity.actionability_state == "expected"
assert opportunity.actionability_reason == "cold_path"
assert opportunity.fix is None
- assert default_queue_exclusion(opportunity) == "cold_path"
+ assert perf_queue_verdict(opportunity).reason == "cold_path"
def test_a_request_handler_named_recover_password_stays_queued() -> None:
@@ -98,7 +98,7 @@ def test_a_request_handler_named_recover_password_stays_queued() -> None:
)[0]
assert opportunity.actionability_state == "advisory"
- assert default_queue_exclusion(opportunity) is None
+ assert perf_queue_verdict(opportunity).eligible
def test_one_warm_member_keeps_a_shared_group_queued() -> None:
@@ -141,4 +141,4 @@ def test_gated_off_takes_precedence_over_cold_path() -> None:
opportunity = build_performance_opportunities([row])[0]
assert opportunity.actionability_reason == "gated_off"
- assert default_queue_exclusion(opportunity) == "gated_off"
+ assert perf_queue_verdict(opportunity).reason == "gated_off"
diff --git a/tests/unit/health/test_perf_corpus_golden.py b/tests/unit/health/test_perf_corpus_golden.py
index 81230d532..fc90ba73b 100644
--- a/tests/unit/health/test_perf_corpus_golden.py
+++ b/tests/unit/health/test_perf_corpus_golden.py
@@ -14,11 +14,11 @@ from repowise.core.analysis.health.perf.opportunities import (
build_performance_opportunities,
link_performance_findings,
)
-from repowise.core.analysis.health.perf.opportunity_rank import (
- ACTIONABILITY_ORDER,
+from repowise.core.analysis.health.perf.opportunity_rank import ACTIONABILITY_ORDER
+from repowise.core.analysis.health.queue.eligibility import (
DEFAULT_QUEUE_EXCLUSIONS,
- default_queue_counts,
- default_queue_exclusion,
+ perf_queue_counts,
+ perf_queue_verdict,
)
from repowise.core.analysis.health.refactoring.performance_fix import (
performance_fix_suggestions,
@@ -300,13 +300,13 @@ def test_a_loop_that_grows_with_data_outranks_a_bounded_one() -> None:
def test_the_default_queue_counts_everything_it_leaves_out() -> None:
"""Production work with a strategy is queued; every other cause has one reason."""
items = _opportunities()
- counts = default_queue_counts(items)
+ counts = perf_queue_counts(items)
assert counts["total"] + sum(counts["excluded"].values()) == len(items)
assert tuple(counts["excluded"]) == DEFAULT_QUEUE_EXCLUSIONS
# The corpus exercises each reason a real repository produces most.
assert all(counts["excluded"][reason] for reason in ("test", "expected", "no_strategy"))
for item in items:
- reason = default_queue_exclusion(item)
+ reason = perf_queue_verdict(item).reason
if reason is None:
assert item.execution_context == "production"
assert item.fix is not None
diff --git a/tests/unit/health/test_queue_eligibility.py b/tests/unit/health/test_queue_eligibility.py
new file mode 100644
index 000000000..3bdc19dd1
--- /dev/null
+++ b/tests/unit/health/test_queue_eligibility.py
@@ -0,0 +1,157 @@
+"""The one queue's ladders and its count bookkeeping."""
+
+from __future__ import annotations
+
+from repowise.core.analysis.health.queue.eligibility import (
+ ELIGIBLE,
+ Tally,
+ Verdict,
+ finding_verdict,
+ path_verdict,
+ perf_fix_verdict,
+ refactor_verdict,
+ unit_verdict,
+)
+
+
+class _Facts:
+ def unreachable(self, path, symbol, line):
+ return False
+
+ def shape(self, path, symbol):
+ return {"ccn": 60, "nloc": 300}
+
+ def cloned(self, path, shape):
+ return False
+
+
+def _cause(**over):
+ row = {
+ "execution_context": "production",
+ "actionability_state": "plan_ready",
+ "plan_state": "available",
+ "fix_strategy": "batch_or_prefetch_io",
+ "biomarker_type": "io_in_loop",
+ "facets": {"loop_magnitude": "grows_with_data"},
+ }
+ return {**row, **over}
+
+
+def test_the_tally_counts_once_and_names_dormant_functions_only_for_gated_off() -> None:
+ tally = Tally(("test", "gated_off"))
+ assert not tally.add(ELIGIBLE, ("a.py", "f"))
+ tally.add(Verdict("gated_off"), ("a.py", "f"))
+ tally.add(Verdict("unreachable"), ("b.py", "g"))
+ tally.add(Verdict("unreachable"))
+ assert tally.excluded == {"test": 0, "gated_off": 1, "unreachable": 2}
+ assert tally.dormant == {("a.py", "f")}
+ assert tally.total == 3
+ assert tally.by_reason() == {"unreachable": 2, "gated_off": 1}
+
+
+def test_by_reason_keeps_first_counted_order_on_ties() -> None:
+ tally = Tally()
+ for reason in ("small_function", "test", "test", "small_function", "low_value_kind"):
+ tally.add(Verdict(reason))
+ assert list(tally.by_reason()) == ["small_function", "test", "low_value_kind"]
+
+
+def test_an_unaudited_kind_is_counted_as_such_after_the_worth_floor() -> None:
+ def concrete(_step):
+ return True
+
+ for kind in ("move_method", "extract_class"):
+ steps = [{"refactoring_type": kind, "target_symbol": "a.py::f"}]
+ assert refactor_verdict(2.0, steps, _Facts(), "a.py", concrete).reason == "kind_unaudited"
+ assert refactor_verdict(0.1, steps, _Facts(), "a.py", concrete).reason == "below_min_worth"
+ steps = [{"refactoring_type": "large_method", "target_symbol": "a.py::f"}]
+ assert refactor_verdict(2.0, steps, _Facts(), "a.py", concrete).reason == "low_value_kind"
+
+
+def test_a_cause_group_needs_a_plan_and_is_dormant_only_when_every_row_is() -> None:
+ contexts = frozenset({"production"})
+ never = lambda: False # noqa: E731
+ unplanned = _cause(plan_state="none", fix_strategy=None)
+ assert perf_fix_verdict([unplanned], contexts, never)[0].reason == "no_plan"
+ gated = _cause(actionability_state="expected", actionability_reason="gated_off")
+ assert perf_fix_verdict([gated], contexts, never)[0].reason == "gated_off"
+ test_row = _cause(execution_context="test")
+ assert perf_fix_verdict([gated, test_row], contexts, never)[0].reason == "test"
+ verdict, worth = perf_fix_verdict([_cause()], contexts, never)
+ assert verdict.eligible and len(worth) == 1
+
+
+def test_a_cause_group_asks_about_dead_code_only_once_it_is_worth_an_item() -> None:
+ asked: list[bool] = []
+
+ def unreachable() -> bool:
+ asked.append(True)
+ return True
+
+ bounded = _cause(biomarker_type="string_concat_in_loop", facets={"loop_magnitude": "bounded"})
+ contexts = frozenset({"production"})
+ assert perf_fix_verdict([bounded], contexts, unreachable)[0].reason == "below_min_worth"
+ assert not asked
+ assert perf_fix_verdict([_cause()], contexts, unreachable)[0].reason == "unreachable"
+ assert asked == [True]
+
+
+class _Shaped(_Facts):
+ def __init__(self, shape, *, dead=False, cloned=False):
+ self._shape, self._dead, self._cloned = shape, dead, cloned
+
+ def unreachable(self, path, symbol, line):
+ return self._dead
+
+ def shape(self, path, symbol):
+ return self._shape
+
+ def cloned(self, path, shape):
+ return self._cloned
+
+
+def test_path_verdict_reads_the_stored_origin_first_and_keeps_tests_on_ask() -> None:
+ assert path_verdict("src/app.py", False).eligible
+ assert path_verdict("src/app.py", False, origin="vendored").reason == "vendored"
+ assert path_verdict("tests/test_app.py", None).reason == "test"
+ assert path_verdict("src/app.py", True).reason == "test"
+ assert path_verdict("tests/test_app.py", None, keep_tests=True).eligible
+ assert path_verdict("examples/demo/run.py", None).reason == "docs_example"
+ assert path_verdict("scripts/build.py", None).reason == "tooling"
+ # A root-level file carries no evidence either way and stays in.
+ assert path_verdict("run.py", None).eligible
+
+
+def test_unit_verdict_ladder_order() -> None:
+ big = {"ccn": 60, "nloc": 300}
+ assert unit_verdict(_Shaped(big, dead=True), "a.py", "f", complexity=True).reason == (
+ "unreachable"
+ )
+ assert unit_verdict(_Shaped({**big, "deprecated": 1}), "a.py", "f", complexity=True).reason == (
+ "deprecated"
+ )
+ assert unit_verdict(_Shaped({**big, "gated_off": 1}), "a.py", "f", complexity=True).reason == (
+ "gated_off"
+ )
+ dispatch = {**big, "dispatch_pct": 90}
+ assert unit_verdict(_Shaped(dispatch), "a.py", "f", complexity=True).reason == (
+ "inherent_dispatch"
+ )
+ assert unit_verdict(_Shaped(dispatch, cloned=True), "a.py", "f", complexity=True).eligible
+ small = {"ccn": 5, "nloc": 10}
+ assert unit_verdict(_Shaped(small), "a.py", "f", complexity=True).reason == "small_function"
+ assert unit_verdict(_Shaped(small), "a.py", "f", complexity=False).eligible
+
+
+def test_finding_verdict_checks_kind_then_shape_then_a_first_edit() -> None:
+ finding = {"file_path": "a.py", "function_name": "f", "line_start": 3,
+ "biomarker_type": "complex_method"}
+ facts = _Shaped({"ccn": 60, "nloc": 300})
+ assert finding_verdict(finding, facts, lambda _f: True).eligible
+ assert finding_verdict(finding, facts, lambda _f: False).reason == "no_concrete_step"
+ low = {**finding, "biomarker_type": "low_cohesion"}
+ assert finding_verdict(low, facts, lambda _f: True).reason == "low_value_kind"
+ unwrap = {**finding, "biomarker_type": "error_handling", "details": {"kind": "panic_macro"}}
+ assert finding_verdict(unwrap, facts, lambda _f: True).reason == "low_value_kind"
+ small = _Shaped({"ccn": 5, "nloc": 10})
+ assert finding_verdict(finding, small, lambda _f: True).reason == "small_function"
diff --git a/tests/unit/health/test_worth.py b/tests/unit/health/test_worth.py
index f356fe6e4..ae0eb48e6 100644
--- a/tests/unit/health/test_worth.py
+++ b/tests/unit/health/test_worth.py
@@ -180,7 +180,7 @@ def test_findings_are_tiered_per_function_and_history_waits() -> None:
],
)
def test_a_perf_cause_leads_only_on_a_loop_that_grows(context, facets, expected) -> None:
- from repowise.core.analysis.health.worth import perf_low_priority
+ from repowise.core.analysis.health.queue.eligibility import perf_low_priority
row = {"execution_context": context, "biomarker_type": "io_in_loop",
"details": {"facets": facets}}
@@ -203,7 +203,7 @@ def test_a_perf_cause_leads_only_on_a_loop_that_grows(context, facets, expected)
],
)
def test_a_perf_cause_is_judged_by_its_kind(marker, facets, expected) -> None:
- from repowise.core.analysis.health.worth import perf_low_priority
+ from repowise.core.analysis.health.queue.eligibility import perf_low_priority
row = {"execution_context": "production", "biomarker_type": marker,
"details": {"facets": facets}}
@@ -224,14 +224,14 @@ def test_a_perf_cause_is_judged_by_its_kind(marker, facets, expected) -> None:
],
)
def test_only_an_unmeasured_loop_is_unproven(marker, facets, proof) -> None:
- from repowise.core.analysis.health.perf.opportunity_rank import default_queue_exclusion
+ from repowise.core.analysis.health.queue.eligibility import perf_queue_verdict
from repowise.core.analysis.health.worth import cost_proof
row = {"execution_context": "production", "actionability_state": "advisory",
"biomarker_type": marker, "details": {"facets": facets}}
assert cost_proof(row) == proof
# The default queue leaves an unproven cause out under the shared reason.
- assert default_queue_exclusion(row) == ("unmeasured_cost" if proof == "unproven" else None)
+ assert perf_queue_verdict(row).reason == ("unmeasured_cost" if proof == "unproven" else None)
def test_an_unknown_loop_ranks_no_higher_than_a_bounded_one() -> None:
@@ -242,7 +242,7 @@ def test_an_unknown_loop_ranks_no_higher_than_a_bounded_one() -> None:
def test_the_default_queue_counts_an_unproven_cause_and_still_adds_up() -> None:
- from repowise.core.analysis.health.perf.opportunity_rank import default_queue_counts
+ from repowise.core.analysis.health.queue.eligibility import perf_queue_counts
def row(context: str, magnitude: str) -> dict:
return {"execution_context": context, "actionability_state": "advisory",
@@ -251,7 +251,7 @@ def test_the_default_queue_counts_an_unproven_cause_and_still_adds_up() -> None:
rows = [row("production", "grows_with_data"), row("production", "unknown"),
row("test", "unknown")]
- counts = default_queue_counts(rows)
+ counts = perf_queue_counts(rows)
assert counts["total"] == 1
assert counts["excluded"]["unmeasured_cost"] == 1 and counts["excluded"]["test"] == 1
assert counts["total"] + sum(counts["excluded"].values()) == len(rows)
diff --git a/tests/unit/server/test_wire_vocabulary_parity.py b/tests/unit/server/test_wire_vocabulary_parity.py
index 7b950abc8..f943859dc 100644
--- a/tests/unit/server/test_wire_vocabulary_parity.py
+++ b/tests/unit/server/test_wire_vocabulary_parity.py
@@ -125,11 +125,21 @@ def test_fix_first_vocabularies_match_python() -> None:
def test_performance_queue_exclusions_match_python() -> None:
- from repowise.core.analysis.health.perf.opportunity_rank import DEFAULT_QUEUE_EXCLUSIONS
+ from repowise.core.analysis.health.queue.eligibility import DEFAULT_QUEUE_EXCLUSIONS
assert _union_members("PerformanceQueueExclusion", "health.ts") == set(DEFAULT_QUEUE_EXCLUSIONS)
+def test_every_surface_counts_in_the_one_reason_vocabulary() -> None:
+ from repowise.core.analysis.health.fix_first import FIX_EXCLUSIONS
+ from repowise.core.analysis.health.queue.eligibility import (
+ DEFAULT_QUEUE_EXCLUSIONS,
+ REASONS,
+ )
+
+ assert set(FIX_EXCLUSIONS) | set(DEFAULT_QUEUE_EXCLUSIONS) == set(REASONS)
+
+
def test_performance_cost_proofs_match_python() -> None:
from repowise.core.analysis.health.worth import COST_PROOFS