Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.mdindex 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 witFix first is built once in `analysis/health/fix_first/build.py` from stored rowsand rendered unchanged by `get_health`, `repowise health`, the dashboard and thegenerated 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 stepdiff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.mdindex 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 nothingin the code anchors one. A Split File or Extract Class plan with an unnamed groupis 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 meanthe code needs no attention: check the findings indiff --git a/packages/core/src/repowise/core/analysis/health/fix_first/build.py b/packages/core/src/repowise/core/analysis/health/fix_first/build.pyindex 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 functoolsimport mathimport refrom collections import Counter, defaultdict@@ -60,38 +59,41 @@ from typing import Anyfrom repowise.core.analysis.finding_registry import excluded_typesfrom repowise.core.analysis.health.complexity.dispatch import DISPATCH_SHAREfrom 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_fieldfrom repowise.core.analysis.health.scoring import biomarker_dimensionfrom repowise.core.analysis.health.suggestions import suggestion_forfrom 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_originfrom . import textfrom .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.8MAX_FACTS = 5MAX_TESTS = 5MAX_STEPS = 5MAX_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 = 3DEFAULT_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 0if files_touched >= 5 or deps >= 20:@@ -454,32 +356,6 @@ class _Files:return Truereturn 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 alreadysays 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)``, thesymbol ``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 verdictplan_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:continueunits.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:continuerows.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 Nonefor 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:continueif 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"))continueunits.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.pyindex 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 hashlibfrom dataclasses import asdict, dataclass, fieldfrom 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, Tierfrom 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 = TierFIX_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.pyindex 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, Mappingfrom dataclasses import asdict, dataclassfrom 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_RANKfrom repowise.core.analysis.health.rows import detail_map, field#: The vertical midline, in lines to change. The work queue's Medium effortdiff --git a/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py b/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.pyindex 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 log2from typing import Anyfrom ..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_reasonBOUNDARY_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 iswhat 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.pyindex 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, Literalfrom repowise.core.analysis.health import queue_rulesfrom repowise.core.analysis.health.finding_identity import finding_public_idfrom 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, SortKeysfrom 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_LABELfrom .opportunities import PERFORMANCE_MODEL_VERSION-from .opportunity_rank import DEFAULT_QUEUE_PROOFS, DEFAULT_QUEUE_STATES, NON_LEADING_MARKERS+from .opportunity_rank import NON_LEADING_MARKERSif TYPE_CHECKING:from .opportunities import PerformanceOpportunitydiff --git a/packages/core/src/repowise/core/analysis/health/queue/__init__.py b/packages/core/src/repowise/core/analysis/health/queue/__init__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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.pyindex 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_WORTHfrom repowise.core.analysis.health.refactoring.identity import REFACTORING_MODEL_VERSIONfrom 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.pyindex 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_verdictfrom ....analysis.health.worth import cost_proofcounts: dict[str, int] = {}@@ -161,12 +158,12 @@ def _summary_payload((ofor 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.pyindex 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 Counterfrom dataclasses import dataclass, fieldfrom typing import Any, Literalfrom sqlalchemy import or_, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.health.queue.eligibility import Tally, Verdictfrom repowise.core.analysis.health.queue_rules import keep, sort_keyfrom repowise.core.analysis.health.refactoring.identity import REFACTORING_MODEL_VERSIONfrom 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.pyindex 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 == 0assert 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.pyindex 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 reimport pytestfrom 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_KINDSfrom repowise.core.analysis.health.refactoring.performance_fix import fix_stepsfrom tests.unit.health.fix_first_rows import FINDINGS, METRICS, _perfdiff --git a/tests/unit/health/test_fix_first_precision.py b/tests/unit/health/test_fix_first_precision.pyindex 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_MAXassert _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"] == 1moved = _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"] == 0def 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.pyindex 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_idfrom repowise.core.analysis.health.fix_first import build_fix_firstfrom repowise.core.analysis.health.models import HealthFindingData, Severityfrom 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_verdictfrom 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() -> NNone,)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"] == 1def 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.pyindex 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, Severityfrom repowise.core.analysis.health.perf.causal import execution_contextfrom repowise.core.analysis.health.perf.cold_paths import is_cold_pathfrom 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_verdictdef _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).eligibledef 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.pyindex 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).reasonif reason is None:assert item.execution_context == "production"assert item.fix is not Nonediff --git a/tests/unit/health/test_queue_eligibility.py b/tests/unit/health/test_queue_eligibility.pynew file mode 100644index 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.pyindex 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_priorityrow = {"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_priorityrow = {"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_verdictfrom repowise.core.analysis.health.worth import cost_proofrow = {"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_countsdef 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"] == 1assert counts["excluded"]["unmeasured_cost"] == 1 and counts["excluded"]["test"] == 1assert 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.pyindex 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_EXCLUSIONSassert _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