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): split the Fix-first builder into unit modules (#4071)

Raghav Chamadiyaeae43af55841
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/_files.py b/packages/core/src/repowise/core/analysis/health/fix_first/_files.py
new file mode 100644
index 000000000..ec130457b
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/_files.py
@@ -0,0 +1,439 @@
+"""Shared pieces of the Fix-first units: per-file facts, ranks and item parts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from repowise.core.analysis.health.biomarkers.function_hotspot import FunctionHotspotDetector
+from repowise.core.analysis.health.biomarkers.prior_defect import PriorDefectDetector
+from repowise.core.analysis.health.queue.eligibility import DeadSpan, dead_target
+from repowise.core.analysis.health.queue.order import LEVEL_RANK
+from repowise.core.analysis.health.queue.value import (
+ MIN_CHURN_COMMITS,
+ function_reach,
+ history_weight,
+ removed,
+ shape_value,
+ size_value,
+ tier,
+ worth,
+)
+from repowise.core.analysis.health.rows import detail_map, field
+from repowise.core.analysis.health.suggestions import suggestion_for
+from repowise.core.analysis.health.worth import SIZE_MARKERS, measure, measured_nloc, worth_size
+from repowise.core.analysis.next_call import ActionCommand
+
+from . import text
+from ._parts import (
+ CLASS_MARKERS,
+ MAX_CONTEXT,
+ MAX_STEPS,
+ Rows,
+ _about,
+ _helper_code,
+ _num,
+ _one_of,
+ _quantile_cut,
+ _tail,
+ _Unit,
+ symbol_key,
+)
+from .model import (
+ FIX_EFFORTS,
+ FixAction,
+ FixContext,
+ FixFact,
+ FixGain,
+ FixItem,
+ FixRankFact,
+ FixStep,
+ fix_id,
+)
+from .plan_steps import _above_bar_note, _extract_text, _extraction_worth, _plan_body, _span
+
+
+class _Files:
+ """Per-file facts the units share: metrics, heat, history context."""
+
+ def __init__(
+ self,
+ metrics: Rows,
+ history: Mapping[str, list[Any]],
+ functions: Mapping[tuple[str, str], list[Any]],
+ cuts: tuple[float, float] | None,
+ clones: Mapping[str, list[tuple[int, int]]] | None = None,
+ extractions: Mapping[tuple[str, str], list[Any]] | None = None,
+ dead: Mapping[str, list[DeadSpan]] | None = None,
+ function_changes: Mapping[str, int] | None = None,
+ blame_skipped: Iterable[str] = (),
+ ) -> None:
+ self.by_path = {field(m, "file_path"): m for m in metrics}
+ self.function_changes = function_changes
+ self.blame_skipped = frozenset(blame_skipped)
+ self.functions = functions
+ self.clones = clones or {}
+ self.extractions = extractions or {}
+ self.dead = dead or {}
+ if cuts is None:
+ production = [m for m in self.by_path.values() if not field(m, "is_test")]
+ cuts = (
+ _quantile_cut([field(m, "commit_count_90d") or 0 for m in production]),
+ _quantile_cut([field(m, "dependents") or 0 for m in production]),
+ )
+ self.churn_cut, self.deps_cut = cuts
+ self.history = history
+ # History that shows a function costs something: bug fixes in its
+ # file, or the function changing more than most in the repository.
+ self.fixed = {
+ p for p, rows in history.items()
+ if any(field(f, "biomarker_type") == PriorDefectDetector.name for f in rows)
+ }
+ self.hotspots = {
+ p: {_tail(field(f, "function_name")) for f in rows
+ if field(f, "biomarker_type") == FunctionHotspotDetector.name}
+ for p, rows in history.items()
+ }
+
+ def is_test(self, path: str) -> bool | None:
+ """The stored flag; ``None`` when the file has no metric row or flag."""
+ return field(self.by_path.get(path), "is_test")
+
+ def origin(self, path: str) -> str | None:
+ """The stored code origin; ``None`` before it was recorded."""
+ return field(self.by_path.get(path), "code_origin")
+
+ def commits(self, path: str) -> int:
+ return int(field(self.by_path.get(path), "commit_count_90d") or 0)
+
+ def coverage(self, path: str) -> float | None:
+ """Measured line coverage in percent; ``None`` when no report has it."""
+ return field(self.by_path.get(path), "line_coverage_pct")
+
+ def dependents(self, path: str) -> int | None:
+ return field(self.by_path.get(path), "dependents")
+
+ def nloc(self, path: str) -> int | None:
+ return field(self.by_path.get(path), "nloc")
+
+ def central(self, path: str) -> bool:
+ return (self.dependents(path) or 0) >= self.deps_cut
+
+ def churning(self, path: str) -> bool:
+ return self.commits(path) >= max(self.churn_cut, MIN_CHURN_COMMITS)
+
+ def changes(self, path: str, symbol: str | None, *, function: bool) -> int | None:
+ """Commits that changed the function ``symbol`` in ``path``, 0 with no
+ stored row; ``None`` when the repository keeps no function history,
+ the blame pass skipped the file for size, or the unit is led by no
+ function (a class, a file, a duplicated span), so its file's churn
+ stands in."""
+ key = symbol_key(path, symbol) if function else None
+ if self.function_changes is None or key is None or path in self.blame_skipped:
+ return None
+ return int(self.function_changes.get(key) or 0)
+
+ def evidence(self, path: str, symbol: str | None) -> bool | None:
+ """Whether history shows work on ``symbol`` pays: its file changes
+ often or has bug fixes, or the function itself is a hotspot.
+ ``None`` when the file's history is unknown: no commit count, or a
+ repository whose history does not tell files apart."""
+ tail = _tail(symbol)
+ if self.churning(path) or path in self.fixed or (tail and tail in self.hotspots.get(path, ())):
+ return True
+ known = field(self.by_path.get(path), "commit_count_90d") is not None
+ return False if known and self.churn_cut >= MIN_CHURN_COMMITS else None
+
+ def reach(
+ self, path: str, shape: Mapping[str, int], dependents: int | None, *, sized: bool
+ ) -> tuple[int | None, bool]:
+ """The importers a unit in ``path`` is credited with, and whether that
+ makes it central: a function-size unit's are ``queue.value.function_reach``,
+ any other unit's are its file's."""
+ deps = self.dependents(path) if dependents is None else dependents
+ if not sized:
+ return deps, self.central(path)
+ credited = function_reach(deps, measured_nloc(shape), self.nloc(path))
+ if credited == deps:
+ return deps, self.central(path)
+ return credited, (credited or 0) >= self.deps_cut
+
+ def shape(self, path: str, symbol: str | None) -> dict[str, int]:
+ """The measured size of ``symbol`` in ``path``, from its findings."""
+ if not symbol:
+ return {}
+ found = self.functions.get((path, symbol))
+ if found is None:
+ tail = symbol.rsplit(".", 1)[-1]
+ found = next(
+ (
+ rows
+ for (p, fn), rows in self.functions.items()
+ if p == path and fn.rsplit(".", 1)[-1] == tail
+ ),
+ (),
+ )
+ return measure(found)
+
+ def cloned(self, path: str, shape: Mapping[str, int]) -> bool:
+ """Whether a stored duplicate overlaps the function ``shape`` spans."""
+ start, end = shape.get("start"), shape.get("end")
+ if not start or not end:
+ return False
+ return any(a <= end and b >= start for a, b in self.clones.get(path, ()))
+
+ def first_step(self, finding: Any) -> FixStep | None:
+ """The concrete first edit for a finding with no plan of its own.
+
+ A function-size finding starts at the best stored Extract Method span
+ inside the function, else at its deepest nested block. Any other
+ finding names its own line or function. ``None`` when there is no
+ such edit to name: a class-level finding with no member groups, or a
+ size finding with neither fact stored.
+ """
+ path = field(finding, "file_path")
+ marker = field(finding, "biomarker_type") or ""
+ function = field(finding, "function_name")
+ line = field(finding, "line_start")
+ if marker in CLASS_MARKERS:
+ return None
+ if marker not in SIZE_MARKERS:
+ if line or function:
+ summary = text.first_sentence(suggestion_for(marker))
+ return FixStep(1, summary, path, line, False)
+ return None
+ tail = _tail(function) or ""
+ best = self.extraction(finding)
+ if best is not None:
+ start, end = _span(best)
+ body = _plan_body(best)
+ step = _above_bar_note(_extract_text(tail, body, start, end), best)
+ return FixStep(1, step, path, start, **_helper_code(body))
+ shape = self.shape(path, function)
+ start, end = shape.get("deep_start"), shape.get("deep_end")
+ if start and end:
+ depth = shape.get("max_nesting")
+ where = f"where it nests {depth} deep" if depth else "where it nests deepest"
+ lines = f"line {start}" if start == end else f"lines {start}-{end}"
+ return FixStep(
+ 1,
+ f"Start with {lines}, {where}: return early or move it into a helper",
+ path,
+ start,
+ )
+ return None
+
+ def extraction(self, finding: Any) -> Any | None:
+ """The best stored Extract Method plan inside a function-size
+ finding's function, which :meth:`first_step` lifts first."""
+ if field(finding, "biomarker_type") not in SIZE_MARKERS:
+ return None
+ tail = _tail(field(finding, "function_name")) or ""
+ plans = self.extractions.get((field(finding, "file_path"), tail)) or ()
+ return max(plans, key=_extraction_worth, default=None)
+
+ def unreachable(self, path: str, symbol: str | None, line: int | None) -> bool:
+ """Whether a sure dead-code finding covers ``symbol`` (at ``line``) in
+ ``path``: the whole file, the line inside the finding's span, or, for a
+ finding stored with no lines, the same name as written (``Old.run`` is
+ not ``New.run``)."""
+ return dead_target(self.dead, path, symbol, line)
+
+ def why(
+ self,
+ path: str,
+ *,
+ measured: str | None,
+ fallback: str,
+ dependents: int | None = None,
+ cloned: bool = False,
+ changes: int | None = None,
+ function: bool = False,
+ ) -> str:
+ """One sentence: the problem, then why it matters here (how often the
+ function changed, who imports the file, how often it changes, how much
+ of it tests run)."""
+ deps = dependents if dependents is not None else self.dependents(path)
+ head = measured or fallback.rstrip(". ")
+ if cloned:
+ head += f", {text.CLONED}"
+ if changes is not None and changes >= MIN_CHURN_COMMITS:
+ head += f"; {text.own_changes(changes)}"
+ exposure = text.exposure(
+ deps, self.commits(path), self.coverage(path), function=function
+ )
+ return f"{head}{exposure}."
+
+ def context(self, path: str, symbol: str | None = None) -> tuple[FixContext, ...]:
+ """History is context: shown beside the item, never lifting its band.
+ An item on ``symbol`` shows its file's rows and its own, never another
+ function's."""
+ out: list[FixContext] = []
+ commits = self.commits(path)
+ if commits:
+ people = field(self.by_path.get(path), "contributor_count")
+ out.append(FixContext("recent changes", text.changes(commits, people)))
+ if self.is_test(path):
+ out.append(FixContext("file kind", "test"))
+ ranked = sorted(self.history.get(path, ()), key=lambda f: -_num(field(f, "health_impact")))
+ for f in ranked:
+ if not _about(field(f, "function_name"), symbol):
+ continue
+ marker = field(f, "biomarker_type") or ""
+ sentence = text.history_fact(marker, detail_map(f), field(f, "function_name"))
+ if sentence:
+ out.append(FixContext(text.HISTORY_LABEL.get(marker, "history"), sentence))
+ return tuple(out[:MAX_CONTEXT])
+
+ def common_facts(
+ self, path: str, dependents: int | None = None, *, function: bool = False
+ ) -> list[FixFact]:
+ out = []
+ deps = dependents if dependents is not None else self.dependents(path)
+ if deps:
+ label = "files that import its file" if function else "files that import it"
+ out.append(FixFact(label, str(deps)))
+ commits = self.commits(path)
+ if commits:
+ out.append(FixFact("changes in 90 days", str(commits)))
+ return out
+
+
+def _finish(
+ *,
+ kind: str,
+ source_id: str,
+ value: int,
+ ready: bool,
+ worth: float,
+ confidence: str,
+ effort: str,
+ improves: str,
+ rank_inputs: Callable[[], list[FixRankFact]],
+ fields: Callable[[], dict[str, Any]],
+ may_lead: bool = True,
+ low: str | None = None,
+ cold_value: int | None = None,
+) -> _Unit:
+ confidence = _one_of(confidence, LEVEL_RANK, "low")
+ effort = _one_of(effort, FIX_EFFORTS, "M")
+ 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=unit_tier,
+ kind=kind,
+ improves=improves,
+ value=value,
+ why_ranked=(
+ # A later item ranks by value only among later items.
+ FixRankFact("value" if low is None else "value within later", str(value)),
+ *rank_inputs(),
+ FixRankFact("worth in band", f"{worth:.0f}"),
+ FixRankFact("tier", why_tier),
+ ),
+ **fields(),
+ )
+
+ return _Unit(
+ item_id, kind, unit_tier, value, worth, confidence, effort, improves, write, may_lead
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class _ShapeRank:
+ """What a unit led by a function's shape is valued and tiered on: one rule
+ for a refactoring item, a finding item and the stored judgement."""
+
+ shape: dict[str, int]
+ central: bool
+ churning: bool
+ #: Commits that changed the lead function (``_Files.changes``).
+ changes: int | None
+ cloned: bool
+ low: str | None
+ gain: float
+ ccn_removed: int
+ dependents: int | None
+ #: The importers the value counts (``_Files.reach``): ``dependents``, or a
+ #: function's share of them in a file far larger than it.
+ credited: int | None
+
+ @property
+ def value(self) -> int:
+ return shape_value(self.gain, self.shape, self.cloned, central=self.central)
+
+ @property
+ def cold_value(self) -> int:
+ return shape_value(self.gain, self.shape, self.cloned, central=False)
+
+ @property
+ def tier(self) -> str:
+ return tier(self.cold_value, "medium", False, self.low)[0]
+
+ @property
+ def history(self) -> float:
+ return history_weight(self.changes, self.churning)
+
+ def facts(self) -> list[FixRankFact]:
+ size = size_value(self.shape, self.central) if self.low is None else worth_size(self.shape)
+ return [
+ FixRankFact("health gain", f"{self.gain:.2f}"),
+ FixRankFact("complexity removed", str(self.ccn_removed)),
+ FixRankFact("problem size", str(size)),
+ *_reach_facts(self.dependents, self.central, self.credited),
+ _history_fact(self.changes, self.churning),
+ FixRankFact("duplicate inside", "yes" if self.cloned else "no"),
+ ]
+
+
+def _finish_shaped(rank: _ShapeRank, **unit: Any) -> _Unit:
+ """:func:`_finish` for a unit whose value, worth and rank facts come from ``rank``."""
+ return _finish(
+ value=rank.value,
+ cold_value=rank.cold_value,
+ worth=worth(removed(rank.ccn_removed, rank.gain), rank.credited, rank.history),
+ low=rank.low,
+ rank_inputs=rank.facts,
+ **unit,
+ )
+
+
+def _reach_facts(deps: int | None, central: bool, credited: int | None) -> list[FixRankFact]:
+ """What reach adds: importers lift the band when central. A function
+ credited with only its share of its file's importers says so."""
+ share = f", {credited} counted for its share of the file" if credited != deps else ""
+ return [
+ FixRankFact(
+ "files that import it", f"{deps or 0}{' (top fifth)' if central else ''}{share}"
+ ),
+ ]
+
+
+def _history_fact(changes: int | None, churning: bool) -> FixRankFact:
+ """What history adds, which only orders inside the band: the function's
+ own changes, or, with no function history, whether its file changes often."""
+ if changes is None:
+ return FixRankFact("changes often", "yes" if churning else "no")
+ return FixRankFact("function changed in", text.plural(changes, "commit"))
+
+
+def _size_facts(shape: Mapping[str, int]) -> list[FixFact]:
+ size_text = text.size_line(shape)
+ return [FixFact("size", size_text)] if size_text else []
+
+
+def _action(summary: str, steps: tuple[FixStep, ...], mechanical: bool) -> FixAction:
+ return FixAction(summary, steps[:MAX_STEPS], len(steps), mechanical)
+
+
+def _health_gain(gain: float, *, ceiling: bool) -> FixGain:
+ return FixGain("health_points", round(gain, 3), text.health_gain(gain, ceiling=ceiling))
+
+
+def _opportunity_call(label: str, opportunity_id: str) -> ActionCommand:
+ return ActionCommand.call(label, "get_health", {"opportunity_id": opportunity_id})
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/_parts.py b/packages/core/src/repowise/core/analysis/health/fix_first/_parts.py
new file mode 100644
index 000000000..71394e86b
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/_parts.py
@@ -0,0 +1,164 @@
+"""Constants, rank limits and item parts every Fix-first unit shares."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from repowise.core.analysis.health.rows import field
+from repowise.core.analysis.health.worth import WORTH_MAGNITUDE
+
+from . import text
+from .model import FixItem, FixRisk, FixTest, FixVerify
+
+Rows = Iterable[Any]
+
+#: 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
+#: A file in the top fifth of production files by dependents is central (one
+#: value step); by churn it changes often (orders within a band only).
+HOT_QUANTILE = 0.8
+MAX_FACTS = 5
+MAX_TESTS = 5
+MAX_STEPS = 5
+MAX_CONTEXT = 3
+DEFAULT_LIMIT = 10
+#: Class-level findings: a fix names member groups, which only a plan holds.
+CLASS_MARKERS = frozenset({"low_cohesion", "god_class"})
+#: Refactorings that change one function, whose own history orders them.
+_FUNCTION_LEADS = frozenset({"extract_method", "move_method"})
+
+
+@dataclass(frozen=True, slots=True)
+class _Unit:
+ """What ranking reads, and how to write the item once it is shown.
+
+ Items are written only for the ranks a caller keeps: the copy, facts and
+ verify block cost more than the ranking, and most units are never shown.
+ """
+
+ id: str
+ kind: str
+ tier: str
+ value: int
+ worth: float
+ confidence: str
+ effort: str
+ improves: str
+ write: Callable[[int], FixItem]
+ #: False for a performance cause whose marker has not cleared the bar for
+ #: leading (``opportunity_rank.may_lead``): listed, never first.
+ may_lead: bool = True
+
+
+def _tail(symbol: str | None) -> str | None:
+ """A symbol's own name: ``a.py::Cls.run`` and ``Cls::run`` read ``run``."""
+ return re.split(r"::|\.", symbol)[-1] if symbol else None
+
+
+def _about(function: str | None, symbol: str | None) -> bool:
+ """Whether a history row on ``function`` speaks to an item on ``symbol``:
+ a file-level row or item, the same function, or a member of the item's
+ class. ``Engine.run`` never keeps ``Other.run``; a bare name on either
+ side matches by name, since it names no class to tell them apart."""
+ if not function or not symbol:
+ return True
+ own = text.short_symbol(symbol) or ""
+ if function == own or function.startswith(f"{own}."):
+ return True
+ return ("." not in function or "." not in own) and _tail(function) == _tail(own)
+
+
+def symbol_key(path: str, symbol: str | None) -> str | None:
+ """A function's ``git_function_blame`` key, ``path::name``; ``None`` for no symbol."""
+ name = text.short_symbol(symbol)
+ return f"{path}::{name}" if name else None
+
+
+def _open(row: Any) -> bool:
+ return (field(row, "status") or "open") == "open"
+
+
+def _num(value: Any) -> float:
+ return float(value or 0.0)
+
+
+def _one_of(value: Any, known: Iterable[Any], default: str) -> Any:
+ """*value* when it is one of *known*, else *default*."""
+ return value if value in known else default
+
+
+def hot_cut_offset(count: int) -> int:
+ """Where the top fifth starts in ``count`` ascending values."""
+ return min(int(count * HOT_QUANTILE), count - 1)
+
+
+def hot_cut(value_at_offset: float | None) -> float:
+ """The value at :func:`hot_cut_offset`, never below 1 (zero is not hot)."""
+ return math.inf if value_at_offset is None else max(value_at_offset, 1)
+
+
+def _quantile_cut(values: list[int]) -> float:
+ """The smallest value in the top fifth of production files."""
+ if not values:
+ return math.inf
+ return hot_cut(sorted(values)[hot_cut_offset(len(values))])
+
+
+def _risk(files_touched: int, dependents: int | None, *, function: bool = False) -> FixRisk:
+ deps = dependents or 0
+ if files_touched >= 5 or deps >= 20:
+ level = "high"
+ elif files_touched >= 2 or deps >= 5:
+ level = "medium"
+ else:
+ level = "low"
+ parts = [f"touches {text.plural(files_touched, 'file')}"]
+ if dependents:
+ parts.append(text.imports_it(dependents, function=function))
+ return FixRisk(level, dependents, files_touched, "; ".join(parts).capitalize() + ".")
+
+
+#: Validation profile for a finding with no stored plan: (path, function, line start, line end).
+Validate = Callable[[str, Any, Any, Any], Mapping[str, Any] | None]
+
+
+def _verify(profile: Mapping[str, Any] | None) -> FixVerify:
+ """The stored validation profile, shown short. Never recomputed here."""
+ if not profile:
+ return FixVerify((), 0, None, "unknown")
+ via = profile.get("via")
+ how = text.TEST_VIA.get(via or "")
+ reason = f"reaches the changed code {how}" if how else "covers it"
+ tests = tuple(FixTest(str(t), reason) for t in (profile.get("tests") or [])[:MAX_TESTS])
+ commands = profile.get("commands") or []
+ basis = profile.get("basis")
+ return FixVerify(
+ tests,
+ int(profile.get("total") or len(tests)),
+ commands[0] if commands else None,
+ basis if basis in ("measured", "inferred") else "unknown",
+ None if tests else profile.get("prerequisite"),
+ )
+
+
+def _step_command(check: Mapping[str, Any] | None, item_command: str | None) -> str | None:
+ """A step's own command (a validation profile, or a plan step's ``verify``),
+ kept only when it differs from the item's."""
+ commands = (check or {}).get("commands") or []
+ return commands[0] if commands and commands[0] != item_command else None
+
+
+def _helper_code(body: Mapping[str, Any]) -> dict[str, str | None]:
+ """An Extract Method plan's rendered helper header and call, when it wrote them."""
+ symbol = body.get("new_symbol") or {}
+ site = body.get("call_site") or {}
+ return {
+ "signature": symbol.get("signature_text") if isinstance(symbol, dict) else None,
+ "call": site.get("new_text") if isinstance(site, dict) else None,
+ }
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 217573c4a..4db78be46 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
@@ -57,1562 +57,55 @@ Row shapes (field names are the SQL columns):
from __future__ import annotations
-import math
-import re
from collections import Counter, defaultdict
-from collections.abc import Callable, Iterable, Mapping
-from dataclasses import dataclass
+from collections.abc import Iterable, Mapping
from typing import Any
from repowise.core.analysis.finding_registry import excluded_types
-from repowise.core.analysis.health.biomarkers.function_hotspot import FunctionHotspotDetector
-from repowise.core.analysis.health.biomarkers.prior_defect import PriorDefectDetector
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.queue.counts import COVERED_BY_PLAN, NOT_FILE_LEAD, Judgement
from repowise.core.analysis.health.queue.eligibility import (
DEAD_CONFIDENCE,
DEFAULT_QUEUE_CONTEXTS,
- UNAUDITED_KINDS,
- DeadSpan,
Tally,
Verdict,
dead_spans,
- dead_target,
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 (
- MIN_CHURN_COMMITS,
- function_reach,
- history_weight,
- perf_confidence,
- perf_ready,
- perf_value,
- perf_worth,
- removed,
- shape_value,
- size_value,
- tier,
- worth,
-)
-from repowise.core.analysis.health.refactoring.recipe import ELSEWHERE_NOTE, plan_anchors
-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 (
- SIZE_MARKERS,
- WORTH_MAGNITUDE,
- LowPriority,
- by_function,
- execution_role,
- low_priority,
- magnitude,
- measure,
- measured_nloc,
- worst_after,
- worth_size,
-)
-from repowise.core.analysis.next_call import ActionCommand
-from repowise.core.ci.markdown import code as md_code
+from repowise.core.analysis.health.queue.order import order
+from repowise.core.analysis.health.rows import detail_map, field
+from repowise.core.analysis.health.worth import SIZE_MARKERS, by_function
from . import text
-from .model import (
- FIX_EFFORTS,
- FIX_EXCLUSIONS,
- FIX_IMPROVES,
- FixAction,
- FixConfidence,
- FixContext,
- FixEffortEstimate,
- FixFact,
- FixFirstQueue,
- FixGain,
- FixItem,
- FixRankFact,
- FixRisk,
- FixSource,
- FixStep,
- FixTarget,
- FixTest,
- FixTotals,
- FixVerify,
- fix_id,
+from ._files import _Files
+from ._parts import ( # noqa: F401 (moved helpers re-exported)
+ CLASS_MARKERS,
+ DEFAULT_LIMIT,
+ HOT_QUANTILE,
+ MAX_CONTEXT,
+ MAX_FACTS,
+ MAX_STEPS,
+ MAX_TESTS,
+ SIZE_BREAK_UP,
+ Rows,
+ Validate,
+ _about,
+ _num,
+ _open,
+ _Unit,
+ hot_cut,
+ hot_cut_offset,
+ symbol_key,
)
-
-Rows = Iterable[Any]
-
-#: 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
-#: A file in the top fifth of production files by dependents is central (one
-#: value step); by churn it changes often (orders within a band only).
-HOT_QUANTILE = 0.8
-MAX_FACTS = 5
-MAX_TESTS = 5
-MAX_STEPS = 5
-MAX_CONTEXT = 3
-DEFAULT_LIMIT = 10
-#: Class-level findings: a fix names member groups, which only a plan holds.
-CLASS_MARKERS = frozenset({"low_cohesion", "god_class"})
-#: Refactorings that change one function, whose own history orders them.
-_FUNCTION_LEADS = frozenset({"extract_method", "move_method"})
-
-
-@dataclass(frozen=True, slots=True)
-class _Unit:
- """What ranking reads, and how to write the item once it is shown.
-
- Items are written only for the ranks a caller keeps: the copy, facts and
- verify block cost more than the ranking, and most units are never shown.
- """
-
- id: str
- kind: str
- tier: str
- value: int
- worth: float
- confidence: str
- effort: str
- improves: str
- write: Callable[[int], FixItem]
- #: False for a performance cause whose marker has not cleared the bar for
- #: leading (``opportunity_rank.may_lead``): listed, never first.
- may_lead: bool = True
-
-
-def _tail(symbol: str | None) -> str | None:
- """A symbol's own name: ``a.py::Cls.run`` and ``Cls::run`` read ``run``."""
- return re.split(r"::|\.", symbol)[-1] if symbol else None
-
-
-def _about(function: str | None, symbol: str | None) -> bool:
- """Whether a history row on ``function`` speaks to an item on ``symbol``:
- a file-level row or item, the same function, or a member of the item's
- class. ``Engine.run`` never keeps ``Other.run``; a bare name on either
- side matches by name, since it names no class to tell them apart."""
- if not function or not symbol:
- return True
- own = text.short_symbol(symbol) or ""
- if function == own or function.startswith(f"{own}."):
- return True
- return ("." not in function or "." not in own) and _tail(function) == _tail(own)
-
-
-def symbol_key(path: str, symbol: str | None) -> str | None:
- """A function's ``git_function_blame`` key, ``path::name``; ``None`` for no symbol."""
- name = text.short_symbol(symbol)
- return f"{path}::{name}" if name else None
-
-
-def _open(row: Any) -> bool:
- return (field(row, "status") or "open") == "open"
-
-
-def _num(value: Any) -> float:
- return float(value or 0.0)
-
-
-def _one_of(value: Any, known: Iterable[Any], default: str) -> Any:
- """*value* when it is one of *known*, else *default*."""
- return value if value in known else default
-
-
-def hot_cut_offset(count: int) -> int:
- """Where the top fifth starts in ``count`` ascending values."""
- return min(int(count * HOT_QUANTILE), count - 1)
-
-
-def hot_cut(value_at_offset: float | None) -> float:
- """The value at :func:`hot_cut_offset`, never below 1 (zero is not hot)."""
- return math.inf if value_at_offset is None else max(value_at_offset, 1)
-
-
-def _quantile_cut(values: list[int]) -> float:
- """The smallest value in the top fifth of production files."""
- if not values:
- return math.inf
- return hot_cut(sorted(values)[hot_cut_offset(len(values))])
-
-
-def _risk(files_touched: int, dependents: int | None, *, function: bool = False) -> FixRisk:
- deps = dependents or 0
- if files_touched >= 5 or deps >= 20:
- level = "high"
- elif files_touched >= 2 or deps >= 5:
- level = "medium"
- else:
- level = "low"
- parts = [f"touches {text.plural(files_touched, 'file')}"]
- if dependents:
- parts.append(text.imports_it(dependents, function=function))
- return FixRisk(level, dependents, files_touched, "; ".join(parts).capitalize() + ".")
-
-
-#: Validation profile for a finding with no stored plan: (path, function, line start, line end).
-Validate = Callable[[str, Any, Any, Any], Mapping[str, Any] | None]
-
-
-def _verify(profile: Mapping[str, Any] | None) -> FixVerify:
- """The stored validation profile, shown short. Never recomputed here."""
- if not profile:
- return FixVerify((), 0, None, "unknown")
- via = profile.get("via")
- how = text.TEST_VIA.get(via or "")
- reason = f"reaches the changed code {how}" if how else "covers it"
- tests = tuple(FixTest(str(t), reason) for t in (profile.get("tests") or [])[:MAX_TESTS])
- commands = profile.get("commands") or []
- basis = profile.get("basis")
- return FixVerify(
- tests,
- int(profile.get("total") or len(tests)),
- commands[0] if commands else None,
- basis if basis in ("measured", "inferred") else "unknown",
- None if tests else profile.get("prerequisite"),
- )
-
-
-def _step_command(check: Mapping[str, Any] | None, item_command: str | None) -> str | None:
- """A step's own command (a validation profile, or a plan step's ``verify``),
- kept only when it differs from the item's."""
- commands = (check or {}).get("commands") or []
- return commands[0] if commands and commands[0] != item_command else None
-
-
-def _helper_code(body: Mapping[str, Any]) -> dict[str, str | None]:
- """An Extract Method plan's rendered helper header and call, when it wrote them."""
- symbol = body.get("new_symbol") or {}
- site = body.get("call_site") or {}
- return {
- "signature": symbol.get("signature_text") if isinstance(symbol, dict) else None,
- "call": site.get("new_text") if isinstance(site, dict) else None,
- }
-
-
-class _Files:
- """Per-file facts the units share: metrics, heat, history context."""
-
- def __init__(
- self,
- metrics: Rows,
- history: Mapping[str, list[Any]],
- functions: Mapping[tuple[str, str], list[Any]],
- cuts: tuple[float, float] | None,
- clones: Mapping[str, list[tuple[int, int]]] | None = None,
- extractions: Mapping[tuple[str, str], list[Any]] | None = None,
- dead: Mapping[str, list[DeadSpan]] | None = None,
- function_changes: Mapping[str, int] | None = None,
- blame_skipped: Iterable[str] = (),
- ) -> None:
- self.by_path = {field(m, "file_path"): m for m in metrics}
- self.function_changes = function_changes
- self.blame_skipped = frozenset(blame_skipped)
- self.functions = functions
- self.clones = clones or {}
- self.extractions = extractions or {}
- self.dead = dead or {}
- if cuts is None:
- production = [m for m in self.by_path.values() if not field(m, "is_test")]
- cuts = (
- _quantile_cut([field(m, "commit_count_90d") or 0 for m in production]),
- _quantile_cut([field(m, "dependents") or 0 for m in production]),
- )
- self.churn_cut, self.deps_cut = cuts
- self.history = history
- # History that shows a function costs something: bug fixes in its
- # file, or the function changing more than most in the repository.
- self.fixed = {
- p for p, rows in history.items()
- if any(field(f, "biomarker_type") == PriorDefectDetector.name for f in rows)
- }
- self.hotspots = {
- p: {_tail(field(f, "function_name")) for f in rows
- if field(f, "biomarker_type") == FunctionHotspotDetector.name}
- for p, rows in history.items()
- }
-
- def is_test(self, path: str) -> bool | None:
- """The stored flag; ``None`` when the file has no metric row or flag."""
- return field(self.by_path.get(path), "is_test")
-
- def origin(self, path: str) -> str | None:
- """The stored code origin; ``None`` before it was recorded."""
- return field(self.by_path.get(path), "code_origin")
-
- def commits(self, path: str) -> int:
- return int(field(self.by_path.get(path), "commit_count_90d") or 0)
-
- def coverage(self, path: str) -> float | None:
- """Measured line coverage in percent; ``None`` when no report has it."""
- return field(self.by_path.get(path), "line_coverage_pct")
-
- def dependents(self, path: str) -> int | None:
- return field(self.by_path.get(path), "dependents")
-
- def nloc(self, path: str) -> int | None:
- return field(self.by_path.get(path), "nloc")
-
- def central(self, path: str) -> bool:
- return (self.dependents(path) or 0) >= self.deps_cut
-
- def churning(self, path: str) -> bool:
- return self.commits(path) >= max(self.churn_cut, MIN_CHURN_COMMITS)
-
- def changes(self, path: str, symbol: str | None, *, function: bool) -> int | None:
- """Commits that changed the function ``symbol`` in ``path``, 0 with no
- stored row; ``None`` when the repository keeps no function history,
- the blame pass skipped the file for size, or the unit is led by no
- function (a class, a file, a duplicated span), so its file's churn
- stands in."""
- key = symbol_key(path, symbol) if function else None
- if self.function_changes is None or key is None or path in self.blame_skipped:
- return None
- return int(self.function_changes.get(key) or 0)
-
- def evidence(self, path: str, symbol: str | None) -> bool | None:
- """Whether history shows work on ``symbol`` pays: its file changes
- often or has bug fixes, or the function itself is a hotspot.
- ``None`` when the file's history is unknown: no commit count, or a
- repository whose history does not tell files apart."""
- tail = _tail(symbol)
- if self.churning(path) or path in self.fixed or (tail and tail in self.hotspots.get(path, ())):
- return True
- known = field(self.by_path.get(path), "commit_count_90d") is not None
- return False if known and self.churn_cut >= MIN_CHURN_COMMITS else None
-
- def reach(
- self, path: str, shape: Mapping[str, int], dependents: int | None, *, sized: bool
- ) -> tuple[int | None, bool]:
- """The importers a unit in ``path`` is credited with, and whether that
- makes it central: a function-size unit's are ``queue.value.function_reach``,
- any other unit's are its file's."""
- deps = self.dependents(path) if dependents is None else dependents
- if not sized:
- return deps, self.central(path)
- credited = function_reach(deps, measured_nloc(shape), self.nloc(path))
- if credited == deps:
- return deps, self.central(path)
- return credited, (credited or 0) >= self.deps_cut
-
- def shape(self, path: str, symbol: str | None) -> dict[str, int]:
- """The measured size of ``symbol`` in ``path``, from its findings."""
- if not symbol:
- return {}
- found = self.functions.get((path, symbol))
- if found is None:
- tail = symbol.rsplit(".", 1)[-1]
- found = next(
- (
- rows
- for (p, fn), rows in self.functions.items()
- if p == path and fn.rsplit(".", 1)[-1] == tail
- ),
- (),
- )
- return measure(found)
-
- def cloned(self, path: str, shape: Mapping[str, int]) -> bool:
- """Whether a stored duplicate overlaps the function ``shape`` spans."""
- start, end = shape.get("start"), shape.get("end")
- if not start or not end:
- return False
- return any(a <= end and b >= start for a, b in self.clones.get(path, ()))
-
- def first_step(self, finding: Any) -> FixStep | None:
- """The concrete first edit for a finding with no plan of its own.
-
- A function-size finding starts at the best stored Extract Method span
- inside the function, else at its deepest nested block. Any other
- finding names its own line or function. ``None`` when there is no
- such edit to name: a class-level finding with no member groups, or a
- size finding with neither fact stored.
- """
- path = field(finding, "file_path")
- marker = field(finding, "biomarker_type") or ""
- function = field(finding, "function_name")
- line = field(finding, "line_start")
- if marker in CLASS_MARKERS:
- return None
- if marker not in SIZE_MARKERS:
- if line or function:
- summary = text.first_sentence(suggestion_for(marker))
- return FixStep(1, summary, path, line, False)
- return None
- tail = _tail(function) or ""
- best = self.extraction(finding)
- if best is not None:
- start, end = _span(best)
- body = _plan_body(best)
- step = _above_bar_note(_extract_text(tail, body, start, end), best)
- return FixStep(1, step, path, start, **_helper_code(body))
- shape = self.shape(path, function)
- start, end = shape.get("deep_start"), shape.get("deep_end")
- if start and end:
- depth = shape.get("max_nesting")
- where = f"where it nests {depth} deep" if depth else "where it nests deepest"
- lines = f"line {start}" if start == end else f"lines {start}-{end}"
- return FixStep(
- 1,
- f"Start with {lines}, {where}: return early or move it into a helper",
- path,
- start,
- )
- return None
-
- def extraction(self, finding: Any) -> Any | None:
- """The best stored Extract Method plan inside a function-size
- finding's function, which :meth:`first_step` lifts first."""
- if field(finding, "biomarker_type") not in SIZE_MARKERS:
- return None
- tail = _tail(field(finding, "function_name")) or ""
- plans = self.extractions.get((field(finding, "file_path"), tail)) or ()
- return max(plans, key=_extraction_worth, default=None)
-
- def unreachable(self, path: str, symbol: str | None, line: int | None) -> bool:
- """Whether a sure dead-code finding covers ``symbol`` (at ``line``) in
- ``path``: the whole file, the line inside the finding's span, or, for a
- finding stored with no lines, the same name as written (``Old.run`` is
- not ``New.run``)."""
- return dead_target(self.dead, path, symbol, line)
-
- def why(
- self,
- path: str,
- *,
- measured: str | None,
- fallback: str,
- dependents: int | None = None,
- cloned: bool = False,
- changes: int | None = None,
- function: bool = False,
- ) -> str:
- """One sentence: the problem, then why it matters here (how often the
- function changed, who imports the file, how often it changes, how much
- of it tests run)."""
- deps = dependents if dependents is not None else self.dependents(path)
- head = measured or fallback.rstrip(". ")
- if cloned:
- head += f", {text.CLONED}"
- if changes is not None and changes >= MIN_CHURN_COMMITS:
- head += f"; {text.own_changes(changes)}"
- exposure = text.exposure(
- deps, self.commits(path), self.coverage(path), function=function
- )
- return f"{head}{exposure}."
-
- def context(self, path: str, symbol: str | None = None) -> tuple[FixContext, ...]:
- """History is context: shown beside the item, never lifting its band.
- An item on ``symbol`` shows its file's rows and its own, never another
- function's."""
- out: list[FixContext] = []
- commits = self.commits(path)
- if commits:
- people = field(self.by_path.get(path), "contributor_count")
- out.append(FixContext("recent changes", text.changes(commits, people)))
- if self.is_test(path):
- out.append(FixContext("file kind", "test"))
- ranked = sorted(self.history.get(path, ()), key=lambda f: -_num(field(f, "health_impact")))
- for f in ranked:
- if not _about(field(f, "function_name"), symbol):
- continue
- marker = field(f, "biomarker_type") or ""
- sentence = text.history_fact(marker, detail_map(f), field(f, "function_name"))
- if sentence:
- out.append(FixContext(text.HISTORY_LABEL.get(marker, "history"), sentence))
- return tuple(out[:MAX_CONTEXT])
-
- def common_facts(
- self, path: str, dependents: int | None = None, *, function: bool = False
- ) -> list[FixFact]:
- out = []
- deps = dependents if dependents is not None else self.dependents(path)
- if deps:
- label = "files that import its file" if function else "files that import it"
- out.append(FixFact(label, str(deps)))
- commits = self.commits(path)
- if commits:
- out.append(FixFact("changes in 90 days", str(commits)))
- return out
-
-
-def _finish(
- *,
- kind: str,
- source_id: str,
- value: int,
- ready: bool,
- worth: float,
- confidence: str,
- effort: str,
- improves: str,
- rank_inputs: Callable[[], list[FixRankFact]],
- fields: Callable[[], dict[str, Any]],
- may_lead: bool = True,
- low: str | None = None,
- cold_value: int | None = None,
-) -> _Unit:
- confidence = _one_of(confidence, LEVEL_RANK, "low")
- effort = _one_of(effort, FIX_EFFORTS, "M")
- 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=unit_tier,
- kind=kind,
- improves=improves,
- value=value,
- why_ranked=(
- # A later item ranks by value only among later items.
- FixRankFact("value" if low is None else "value within later", str(value)),
- *rank_inputs(),
- FixRankFact("worth in band", f"{worth:.0f}"),
- FixRankFact("tier", why_tier),
- ),
- **fields(),
- )
-
- return _Unit(
- item_id, kind, unit_tier, value, worth, confidence, effort, improves, write, may_lead
- )
-
-
-@dataclass(frozen=True, slots=True)
-class _ShapeRank:
- """What a unit led by a function's shape is valued and tiered on: one rule
- for a refactoring item, a finding item and the stored judgement."""
-
- shape: dict[str, int]
- central: bool
- churning: bool
- #: Commits that changed the lead function (``_Files.changes``).
- changes: int | None
- cloned: bool
- low: str | None
- gain: float
- ccn_removed: int
- dependents: int | None
- #: The importers the value counts (``_Files.reach``): ``dependents``, or a
- #: function's share of them in a file far larger than it.
- credited: int | None
-
- @property
- def value(self) -> int:
- return shape_value(self.gain, self.shape, self.cloned, central=self.central)
-
- @property
- def cold_value(self) -> int:
- return shape_value(self.gain, self.shape, self.cloned, central=False)
-
- @property
- def tier(self) -> str:
- return tier(self.cold_value, "medium", False, self.low)[0]
-
- @property
- def history(self) -> float:
- return history_weight(self.changes, self.churning)
-
- def facts(self) -> list[FixRankFact]:
- size = size_value(self.shape, self.central) if self.low is None else worth_size(self.shape)
- return [
- FixRankFact("health gain", f"{self.gain:.2f}"),
- FixRankFact("complexity removed", str(self.ccn_removed)),
- FixRankFact("problem size", str(size)),
- *_reach_facts(self.dependents, self.central, self.credited),
- _history_fact(self.changes, self.churning),
- FixRankFact("duplicate inside", "yes" if self.cloned else "no"),
- ]
-
-
-def _finish_shaped(rank: _ShapeRank, **unit: Any) -> _Unit:
- """:func:`_finish` for a unit whose value, worth and rank facts come from ``rank``."""
- return _finish(
- value=rank.value,
- cold_value=rank.cold_value,
- worth=worth(removed(rank.ccn_removed, rank.gain), rank.credited, rank.history),
- low=rank.low,
- rank_inputs=rank.facts,
- **unit,
- )
-
-
-def _reach_facts(deps: int | None, central: bool, credited: int | None) -> list[FixRankFact]:
- """What reach adds: importers lift the band when central. A function
- credited with only its share of its file's importers says so."""
- share = f", {credited} counted for its share of the file" if credited != deps else ""
- return [
- FixRankFact(
- "files that import it", f"{deps or 0}{' (top fifth)' if central else ''}{share}"
- ),
- ]
-
-
-def _history_fact(changes: int | None, churning: bool) -> FixRankFact:
- """What history adds, which only orders inside the band: the function's
- own changes, or, with no function history, whether its file changes often."""
- if changes is None:
- return FixRankFact("changes often", "yes" if churning else "no")
- return FixRankFact("function changed in", text.plural(changes, "commit"))
-
-
-def _size_facts(shape: Mapping[str, int]) -> list[FixFact]:
- size_text = text.size_line(shape)
- return [FixFact("size", size_text)] if size_text else []
-
-
-def _action(summary: str, steps: tuple[FixStep, ...], mechanical: bool) -> FixAction:
- return FixAction(summary, steps[:MAX_STEPS], len(steps), mechanical)
-
-
-def _health_gain(gain: float, *, ceiling: bool) -> FixGain:
- return FixGain("health_points", round(gain, 3), text.health_gain(gain, ceiling=ceiling))
-
-
-def _opportunity_call(label: str, opportunity_id: str) -> ActionCommand:
- return ActionCommand.call(label, "get_health", {"opportunity_id": opportunity_id})
-
-
-# --- refactoring ----------------------------------------------------------------
-
-
-def _plan_body(plan: Any) -> dict[str, Any]:
- if plan is None:
- return {}
- body = json_field(plan, "plan", None) or json_field(plan, "plan_json", {})
- return body if isinstance(body, dict) else {}
-
-
-def _above_bar(details: Mapping[str, Any]) -> LowPriority | None:
- """An opportunity one of whose plans, applied as written, still leaves a
- function above the break-up bar: half a fix, so it can wait."""
- return "above_bar_after" if details.get("leaves_above_bar") else None
-
-
-def _above_bar_reason(plan: Any) -> str | None:
- """Why the plan, applied as written, leaves a function above the break-up
- bar: its rank facts' ``leaves_above_bar``, in the plan's own words."""
- rank = json_field(plan, "rank", None) or json_field(plan, "rank_json", {})
- reason = rank.get("leaves_above_bar") if isinstance(rank, dict) else None
- return reason if isinstance(reason, str) and reason else None
-
-
-def _above_bar_note(step: str, plan: Any) -> str:
- """A finding's borrowed *step*, saying so when the plan leaves the
- function above the break-up bar (:func:`_above_bar_reason`)."""
- reason = _above_bar_reason(plan)
- return f"{step.removesuffix('.')}. This plan alone {reason}." if reason else step
-
-
-def _evidence(plan: Any) -> dict[str, Any]:
- if plan is None:
- return {}
- found = json_field(plan, "evidence", None) or json_field(plan, "evidence_json", {})
- return found if isinstance(found, dict) else {}
-
-
-def _span(plan: Any) -> tuple[int | None, int | None]:
- span = _plan_body(plan).get("span")
- if isinstance(span, dict):
- return span.get("start"), span.get("end")
- return None, None
-
-
-def _refactor_step(
- order: int, step: Mapping[str, Any], plan: Any, command: str | None = None
-) -> FixStep:
- kind = step.get("refactoring_type") or ""
- path = step.get("file_path") or ""
- sym = text.short_symbol(step.get("target_symbol")) or text.basename(path)
- body = _plan_body(plan)
- phrase = _STEP_TEXT.get(kind)
- line_text = (
- phrase(sym, path, plan, body) if phrase else f"Apply the {text.humanize(kind)} step to {sym}"
- )
- code = _helper_code(body) if kind == "extract_method" else {}
- mechanical = (step.get("applicability") or {}).get("classification") == "mechanical"
- line = _span(plan)[0] or step.get("line_start")
- return FixStep(order, line_text, path, line, mechanical, **code, command=command)
-
-
-def _first_four(names: list[str]) -> str:
- """Up to four names, then how many more."""
- more = f" and {len(names) - 4} more" if len(names) > 4 else ""
- return f"{', '.join(names[:4])}{more}"
-
-
-def _extract_class_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
- """The smallest named group of methods leaves for a new class."""
- groups = [g for g in body.get("groups") or [] if g.get("methods")]
- if not groups:
- return f"Move a cohesive group of {sym}'s methods into a new class"
- members = sorted(groups, key=lambda g: len(g["methods"]))[0]["methods"]
- return f"Move {_first_four(members)} out of {sym} into a new class"
-
-
-def _split_file_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
- names = [g.get("name") for g in body.get("groups") or [] if g.get("name")]
- if not names:
- return f"Split {text.basename(path)} along its independent groups"
- return f"Split {text.basename(path)} into {_first_four(names)}"
-
-
-def _break_cycle_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
- edge = _cut_edge(plan)
- if edge is None:
- return _uncut_cycle_text(path, plan)
- return (
- f"Cut the import of {text.basename(edge['to'])} in "
- f"{text.basename(edge['from'])} (line {edge['line']})"
- )
-
-
-def _move_method_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
- dest = body.get("to_class") or text.basename(body.get("to_file") or "")
- return f"Move {sym} to {dest}" if dest else f"Move {sym} to the class it uses most"
-
-
-def _extract_text(sym: str, body: Mapping[str, Any], start: Any, end: Any) -> str:
- """An Extract Method step: its span by the text it starts and ends with
- when the plan anchored it (line numbers move with every edit), else by
- its lines; a staged plan's step is its first stage."""
- into = text.signature(
- body.get("suggested_name"),
- list(body.get("params") or []),
- list(body.get("returns") or []),
- is_async=bool(body.get("needs_async", False)),
- )
- anchors = plan_anchors(body.get("anchors"))
- # Worded like the plan's own step (``recipe._extract_step``).
- if anchors is not None:
- where = f"{sym} from {md_code(anchors['first'])} to {md_code(anchors['last'])}"
- else:
- where = f"lines {start}-{end} of {sym}" if start and end else f"part of {sym}"
- line_text = _stage_one(f"Extract {where} into {into}", body)
- if anchors is not None and anchors["unique_in"] == "function":
- line_text = f"{line_text}. {ELSEWHERE_NOTE}"
- return line_text
-
-
-#: A refactoring step's sentence, by plan type, from (symbol, path, plan, plan body).
-_STEP_TEXT: dict[str, Callable[[str, str, Any, Mapping[str, Any]], str]] = {
- "extract_method": lambda sym, path, plan, body: _extract_text(sym, body, *_span(plan)),
- "extract_helper": lambda sym, *_: (
- f"Replace the duplicate in {sym} with a call to one shared helper"
- ),
- "extract_class": _extract_class_text,
- "split_file": _split_file_text,
- "break_cycle": _break_cycle_text,
- "move_method": _move_method_text,
-}
-
-
-def _stage_count(body: Mapping[str, Any]) -> int:
- """How many helpers a staged Extract Method plan splits its function into;
- 0 when unstaged. Counts stages with a span, as the plan detail page does,
- and fewer than two is no split."""
- stages = body.get("stages")
- if not isinstance(stages, (list, tuple)):
- return 0
- count = sum(_has_span(stage) for stage in stages)
- return count if count >= 2 else 0
-
-
-def _has_span(stage: Any) -> bool:
- """A stage with nonzero integer line bounds (a bool is not a line)."""
- span = stage.get("span") if isinstance(stage, dict) else None
- if not isinstance(span, dict):
- return False
- start, end = span.get("start"), span.get("end")
- return type(start) is int and type(end) is int and bool(start and end)
-
-
-def _stage_one(line_text: str, body: Mapping[str, Any]) -> str:
- """A staged plan's step is its first stage (the plan's top-level span):
- it says so, and the function's CCN once every stage is done."""
- count = _stage_count(body)
- if not count:
- return line_text
- residual = body.get("orchestrator")
- before, after = (
- (residual.get("ccn_before"), residual.get("ccn_after"))
- if isinstance(residual, dict)
- else (None, None)
- )
- ccn = (
- f" (CCN {before} -> {after} after all {count})"
- if before is not None and after is not None
- else ""
- )
- return f"Stage 1 of {count}: {line_text}{ccn}"
-
-
-def _uncut_cycle_text(path: str, plan: Any) -> str:
- """A cycle step with no import line to cut, labelled when it is idiomatic."""
- if _plan_body(plan).get("idiom"):
- return (
- f"Optional: {text.basename(path)} is in an import cycle within one "
- "directory, which is idiomatic in this language"
- )
- return f"Break the import cycle at {text.basename(path)}"
-
-
-def _cut_edge(plan: Any) -> dict[str, Any] | None:
- """The first cut edge whose import line is stored.
-
- An idiomatic cycle (one directory of a language that compiles mutual
- references in one pass) has no edge to cut, so it never reads as a must-do.
- """
- if _plan_body(plan).get("idiom"):
- return None
- for edge in _plan_body(plan).get("cut_edges") or ():
- if isinstance(edge, dict) and edge.get("line") and edge.get("from") and edge.get("to"):
- return edge
- return None
-
-
-def _concrete(step: Mapping[str, Any], plan: Any) -> bool:
- """Whether a refactoring step names an edit someone can make: lines to
- lift, a destination, the import to cut, or named groups."""
- kind = step.get("refactoring_type") or ""
- body = _plan_body(plan)
- if kind == "extract_method":
- start, end = _span(plan)
- return bool(start and end)
- if kind == "extract_helper":
- return any(
- isinstance(o, dict) and o.get("line_start") for o in body.get("occurrences") or ()
- )
- if kind == "move_method":
- return bool(body.get("to_class") or body.get("to_file"))
- if kind == "break_cycle":
- return _cut_edge(plan) is not None
- if kind in ("split_file", "extract_class"):
- members = "symbols" if kind == "split_file" else "methods"
- return any(
- isinstance(g, dict) and g.get(members) and (g.get("name") or kind == "extract_class")
- for g in body.get("groups") or ()
- )
- return bool(step.get("line_start"))
-
-
-def _extraction_worth(plan: Any) -> tuple[int, int]:
- evidence = _evidence(plan)
- return int(evidence.get("ccn_removed") or 0), int(evidence.get("slice_nloc") or 0)
-
-
-def _extractions(plans: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:
- """Open Extract Method plans with a span, by (file, function name). A plan
- a step names is read whatever its status, so a dismissed one is skipped."""
- out: dict[tuple[str, str], list[Any]] = defaultdict(list)
- for plan in plans:
- symbol = field(plan, "target_symbol")
- if field(plan, "refactoring_type") != "extract_method" or not symbol or not _open(plan):
- continue
- start, end = _span(plan)
- if start and end:
- out[(field(plan, "file_path"), text.short_symbol(symbol).rsplit(".", 1)[-1])].append(
- plan
- )
- return dict(out)
-
-
-def _refactor_unit(
- row: Any,
- details: Mapping[str, Any],
- steps: list[Mapping[str, Any]],
- gain: float,
- plans: Mapping[str, Any],
- files: _Files,
-) -> _Unit:
- plan = _RefactorPlan.read(row, details, steps, gain, plans, files)
- dimension = biomarker_dimension(plan.marker) if plan.marker else "maintainability"
- return _finish_shaped(
- plan.rank,
- kind="refactor",
- source_id=field(row, "opportunity_id"),
- ready=plan.mechanical or plan.confidence == "high",
- confidence=plan.confidence,
- effort=plan.effort,
- improves=_one_of(dimension, FIX_IMPROVES, "maintainability"),
- fields=lambda: _refactor_fields(plan),
- )
-
-
-@dataclass(frozen=True, slots=True)
-class _RefactorPlan:
- """A stored refactoring plan as its item reads it: the lead step, the
- steps an item may carry, and the shape the plan is ranked on."""
-
- row: Any
- details: Mapping[str, Any]
- lead: Mapping[str, Any]
- steps: list[Mapping[str, Any]]
- held_back: int
- plans: Mapping[str, Any]
- files: _Files
- sym: str
- lead_type: str
- marker: str | None
- confidence: str
- effort: str
- rank: _ShapeRank
-
- @classmethod
- def read(
- cls,
- row: Any,
- details: Mapping[str, Any],
- steps: list[Mapping[str, Any]],
- gain: float,
- plans: Mapping[str, Any],
- files: _Files,
- ) -> _RefactorPlan:
- path = field(row, "file_path")
- lead = steps[0]
- steps, held_back = _audited_steps(steps)
- lead_type, marker = _lead_kind(row, lead)
- shape = files.shape(path, lead.get("target_symbol"))
- deps = details.get("dependents")
- deps = files.dependents(path) if deps is None else deps
- function_size = lead_type == "extract_method"
- credited, central = files.reach(path, shape, deps, sized=function_size)
- rank = _ShapeRank(
- shape,
- central,
- files.churning(path),
- changes=files.changes(
- path, lead.get("target_symbol"), function=lead_type in _FUNCTION_LEADS
- ),
- cloned=function_size and files.cloned(path, shape),
- low=low_priority(marker, shape, function_size=function_size) or _above_bar(details),
- gain=gain,
- ccn_removed=sum(_extraction_worth(plans.get(s.get("plan_id")))[0] for s in steps),
- dependents=deps,
- credited=credited,
- )
- return cls(
- row,
- details,
- lead,
- steps,
- held_back,
- plans,
- files,
- sym=text.short_symbol(lead.get("target_symbol")) or text.basename(path),
- lead_type=lead_type,
- marker=marker,
- confidence=_one_of(field(row, "confidence") or "medium", LEVEL_RANK, "medium"),
- effort=_one_of(field(row, "effort_bucket") or "M", FIX_EFFORTS, "M"),
- rank=rank,
- )
-
- @property
- def path(self) -> str:
- return field(self.row, "file_path")
-
- @property
- def mechanical_n(self) -> int:
- return sum(
- (s.get("applicability") or {}).get("classification") == "mechanical"
- for s in self.steps
- )
-
- @property
- def mechanical(self) -> bool:
- return self.mechanical_n == len(self.steps)
-
-
-def _lead_kind(row: Any, lead: Mapping[str, Any]) -> tuple[str, str | None]:
- """The lead step's refactoring type, and the marker the plan answers."""
- lead_type = lead.get("refactoring_type") or field(row, "lead_refactoring_type") or ""
- marker = field(row, "lead_biomarker") or (
- lead_type if lead_type in ("split_file", "break_cycle") else None
- )
- return lead_type, marker
-
-
-def _refactor_fields(plan: _RefactorPlan) -> dict[str, Any]:
- lead, path, rank, files = plan.lead, plan.path, plan.rank, plan.files
- lead_plan = plan.plans.get(lead.get("plan_id"))
- profiles = {p.get("id"): p for p in plan.details.get("validation_profiles") or []}
- verify = _verify(
- profiles.get(lead.get("validation_profile_id")) or next(iter(profiles.values()), None)
- )
- fix_steps = _refactor_fix_steps(plan, profiles, verify.command)
- n_steps, mechanical_n = text.plural(len(plan.steps), "step"), plan.mechanical_n
- # The symbol the lead step edits; ``None`` for a file-level plan.
- symbol = plan.sym if lead.get("target_symbol") else None
- return {
- "title": text.clip(_refactor_title(plan, lead_plan)),
- "target": FixTarget(
- path,
- symbol,
- fix_steps[0].line,
- lead.get("line_end"),
- ),
- "why": files.why(
- path,
- measured=_refactor_measure(plan.lead_type, plan.sym, path, lead, lead_plan, files),
- fallback=text.problem(plan.marker, plan.sym),
- dependents=rank.dependents,
- cloned=rank.cloned,
- changes=rank.changes,
- function=symbol is not None,
- ),
- "facts": _refactor_facts(plan, function=symbol is not None),
- "action": _action(f"{n_steps}, {mechanical_n} mechanical", fix_steps, plan.mechanical),
- "gain": _health_gain(rank.gain, ceiling=False),
- "effort": FixEffortEstimate(plan.effort, "sized by the stored plan"),
- "risk": _risk(
- int(field(plan.row, "affected_files_total") or 1),
- rank.dependents,
- function=symbol is not None,
- ),
- "confidence": FixConfidence(
- plan.confidence, f"{mechanical_n} of {n_steps} proven mechanical by the plan"
- ),
- "verify": verify,
- "context": files.context(path, symbol),
- "source": FixSource(
- field(plan.row, "opportunity_id"),
- tuple(s.get("plan_id") for s in plan.steps if s.get("plan_id")),
- tuple(plan.details.get("lead_finding_ids") or ()),
- ),
- "next_call": _opportunity_call(
- "The full plan: ordered steps, validation and evidence",
- field(plan.row, "opportunity_id"),
- ),
- }
-
-
-def _refactor_fix_steps(
- plan: _RefactorPlan, profiles: Mapping[Any, Mapping[str, Any]], item_command: str | None
-) -> tuple[FixStep, ...]:
- return tuple(
- _refactor_step(
- i + 1,
- s,
- plan.plans.get(s.get("plan_id")),
- _step_command(profiles.get(s.get("validation_profile_id")), item_command),
- )
- for i, s in enumerate(plan.steps)
- )
-
-
-def _refactor_title(plan: _RefactorPlan, lead_plan: Any) -> str:
- """A staged plan names how many helpers it splits the function into, a big
- function's first lift names the problem and the span, and any other plan
- reads its title off the lead step's kind."""
- stages = _stage_count(_plan_body(lead_plan)) if plan.lead_type == "extract_method" else 0
- if stages:
- return _with_more_steps(plan, _staged_title(plan.sym, stages))
- return _span_title(plan, lead_plan)
-
-
-def _staged_title(sym: str, stages: int) -> str:
- return f"Split {sym} into {stages} helpers"
-
-
-def _span_title(plan: _RefactorPlan, lead_plan: Any) -> str:
- start, end = _span(lead_plan)
- # Titles never quote the helper name: it is a placeholder the step asks to rename.
- spanned = plan.lead_type == "extract_method" and bool(start and end)
- if spanned and magnitude(plan.rank.shape) >= SIZE_BREAK_UP:
- return _break_up_title(plan.sym, plan.rank.shape, f"{start}-{end}")
- template = text.REFACTOR_TITLE.get(
- "extract_method_span" if spanned else plan.lead_type, "Refactor {file}"
- )
- title = template.format(sym=plan.sym, file=text.basename(plan.path), start=start, end=end)
- return _with_more_steps(plan, title)
-
-
-def _with_more_steps(plan: _RefactorPlan, title: str) -> str:
- if len(plan.steps) > 1:
- title += f" (+{text.plural(len(plan.steps) - 1, 'more step')})"
- return title
-
-
-def _break_up_title(sym: str, shape: Mapping[str, int], span: str, suffix: str = "") -> str:
- title = f"Start breaking up {sym} ({text.size_brief(shape)}): first lift lines {span}"
- # A caveat outranks the span and the size, which the step and why name anyway.
- head = f"Start breaking up {sym}"
- for candidate in (title, f"{head} ({text.size_brief(shape)})", head):
- if len(candidate + suffix) <= text.TITLE_MAX:
- return candidate + suffix
- return head + suffix
-
-
-def _refactor_facts(plan: _RefactorPlan, *, function: bool) -> tuple[FixFact, ...]:
- rank, held_back = plan.rank, plan.held_back
- facts = [
- FixFact("health recoverable", f"+{rank.gain:.1f}", "inferred"),
- *_size_facts(rank.shape),
- FixFact("steps", f"{len(plan.steps)} ({plan.mechanical_n} mechanical)"),
- *([FixFact("steps held back", text.held_back(held_back))] if held_back else []),
- *plan.files.common_facts(plan.path, rank.dependents, function=function),
- ]
- nloc = plan.files.nloc(plan.path)
- if nloc:
- facts.append(FixFact("file size", f"{nloc} lines"))
- return tuple(facts[:MAX_FACTS])
-
-
-def _audited_steps(steps: list[Mapping[str, Any]]) -> tuple[list[Mapping[str, Any]], int]:
- """The steps an item may carry, and how many it held back: steps of a
- kind not yet audited stay in the full plan, never in the item."""
- kept = [s for s in steps if s.get("refactoring_type") not in UNAUDITED_KINDS]
- return kept, len(steps) - len(kept)
-
-
-def _refactor_measure(
- kind: str, sym: str, path: str, step: Mapping[str, Any], plan: Any, files: _Files
-) -> str | None:
- """The numbers behind a refactoring, from its plan evidence or its findings."""
- evidence = _evidence(plan)
- name = text.basename(path)
- if kind == "split_file" and evidence.get("file_nloc"):
- return (
- f"{name}: {text.plural(int(evidence['file_nloc']), 'line')} in "
- f"{evidence.get('group_count') or 'several'} loosely coupled groups"
- )
- if kind == "break_cycle" and evidence.get("cycle_size"):
- idiom = " within one directory (idiomatic)" if evidence.get("idiom") else ""
- return f"{name} is in an import cycle of {evidence['cycle_size']} files{idiom}"
- if kind == "extract_class" and evidence.get("method_count"):
- return (
- f"{sym}: {evidence['method_count']} methods in "
- f"{evidence.get('lcom4') or 'several'} groups that share little state"
- )
- if kind == "extract_helper" and evidence.get("duplicated_lines"):
- return (
- f"{sym}: {evidence['duplicated_lines']} lines duplicated across "
- f"{evidence.get('occurrence_count') or 2} places"
- )
- return text.measured(sym, files.shape(path, step.get("target_symbol")))
-
-
-# --- performance ----------------------------------------------------------------
-
-
-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."""
- action = step.get("action") or ""
- name = text.scope_name(step.get("symbol"), path)
- # A whole word that is not an attribute: ``get`` is not named by a quoted
- # ``session.get`` call, nor by ``getattr``.
- short = name.rsplit(".", 1)[-1] if name else ""
- if not name or re.search(rf"(?<![\w.]){re.escape(short)}(?!\w)", action):
- return action
- return f"{action} ({name})"
-
-
-def _site_symbol(symbol: str | None) -> str | None:
- """The function a call site sits in; ``None`` for none, or a file's top
- level, which is no symbol to jump to."""
- short = text.short_symbol(symbol)
- if not short or short.rsplit(".", 1)[-1] == "__module__":
- return None
- return short
-
-
-def _perf_unit(
- rows: list[Any], files: _Files, symbol_lines: Mapping[str, int] | None = None
-) -> _Unit:
- cause = _PerfCause.read(rows, files, symbol_lines)
- lead, path = cause.lead, cause.path
- return _finish(
- kind="perf_fix",
- may_lead=cause.details.get("may_lead") is not False,
- source_id=f"{path}::{cause.symbol or path}",
- value=perf_value(lead, cause.facets),
- ready=perf_ready(lead, cause.plan),
- worth=perf_worth(cause.call_sites, files.churning(path)),
- confidence=perf_confidence(cause.facets),
- effort=cause.plan.get("effort_bucket") or "M",
- improves="performance",
- low=perf_low_priority(lead),
- rank_inputs=lambda: _perf_rank_facts(cause),
- fields=lambda: _perf_fields(cause),
- )
-
-
-@dataclass(frozen=True, slots=True)
-class _PerfCause:
- """One intervention's performance rows as its item reads them, led by
- the best ranked."""
-
- rows: list[Any]
- files: _Files
- symbol_lines: Mapping[str, int]
- lead: Any
- details: Mapping[str, Any]
- facets: Mapping[str, Any]
- plan: Mapping[str, Any]
- path: str
- symbol: str | None
- call_sites: int
-
- @classmethod
- def read(
- cls, rows: list[Any], files: _Files, symbol_lines: Mapping[str, int] | None
- ) -> _PerfCause:
- lead = min(
- rows, key=lambda r: (field(r, "rank_position") or 0, field(r, "opportunity_id"))
- )
- details = detail_map(lead)
- return cls(
- rows,
- files,
- symbol_lines or {},
- lead,
- details,
- details.get("facets") or {},
- details.get("plan") or {},
- field(lead, "file_path") or "",
- field(lead, "intervention_symbol"),
- int(field(lead, "affected_call_sites_total") or 0),
- )
-
- @property
- def plan_steps(self) -> list[Mapping[str, Any]]:
- return self.plan.get("steps") or []
-
-
-def _perf_rank_facts(cause: _PerfCause) -> list[FixRankFact]:
- lead = cause.lead
- return [
- FixRankFact("runs in", field(lead, "execution_context") or "unknown"),
- FixRankFact("run by", execution_role(lead)),
- FixRankFact("call sites", str(cause.call_sites)),
- FixRankFact("loop size", text.loop_size(cause.facets.get("loop_magnitude"))),
- FixRankFact(
- "boundary", text.BOUNDARY_NOUN.get(field(lead, "boundary_kind") or "", "none")
- ),
- ]
-
-
-def _perf_fields(cause: _PerfCause) -> dict[str, Any]:
- lead, path = cause.lead, cause.path
- name, symbol = _perf_name(cause)
- files_n = int(field(lead, "affected_files_total") or 1)
- what, gain_text = text.perf_cost(
- name,
- field(lead, "biomarker_type"),
- field(lead, "boundary_kind"),
- cause.facets.get("amplification"),
- cause.facets.get("loop_magnitude"),
- )
- verify = _verify(cause.plan.get("validation"))
- steps = _perf_steps(cause, verify.command)
- strategy = field(lead, "fix_strategy") or ""
- return {
- "title": text.clip(_perf_title(cause, name)),
- "target": _perf_target(cause, symbol, steps),
- "why": f"{what}; {_perf_reach(cause, files_n)}.",
- "facts": _perf_facts(cause, files_n),
- "action": _action(
- text.FIX_STRATEGY.get(strategy, text.humanize(strategy).capitalize()),
- steps,
- _all_mechanical(cause.plan_steps),
- ),
- "gain": FixGain("performance", None, gain_text),
- "effort": _perf_effort(cause.plan.get("effort_bucket")),
- "risk": _risk(files_n, None),
- "confidence": FixConfidence(
- perf_confidence(cause.facets),
- cause.details.get("fix_rationale")
- or f"{text.humanize(field(lead, 'actionability_state'))} plan",
- ),
- "verify": verify,
- "context": cause.files.context(path, symbol),
- "source": FixSource(field(lead, "opportunity_id")),
- "next_call": _opportunity_call(
- "The full opportunity: ordered steps, validation and other causes here",
- field(lead, "opportunity_id"),
- ),
- }
-
-
-def _perf_name(cause: _PerfCause) -> tuple[str, str | None]:
- """What the item calls the function, and the symbol its target names:
- ``None`` at module scope or when no symbol is stored."""
- # A cause with no intervention symbol is named by the function its plan edits.
- first = cause.plan_steps[0] if cause.plan_steps else {}
- name = (
- text.scope_name(cause.symbol, cause.path)
- or text.scope_name(first.get("symbol"), cause.path)
- or text.basename(cause.path)
- )
- module = name.startswith("module scope of ")
- return name, name if (cause.symbol or first.get("symbol")) and not module else None
-
-
-def _all_mechanical(plan_steps: list[Mapping[str, Any]]) -> bool:
- return bool(plan_steps) and all(s.get("applicability") == "mechanical" for s in plan_steps)
-
-
-def _perf_title(cause: _PerfCause, name: str) -> str:
- shaped = text.PERF_SHAPE.get(field(cause.lead, "biomarker_type") or "")
- if shaped:
- return shaped[0].format(name=name)
- noun = text.BOUNDARY_NOUN.get(field(cause.lead, "boundary_kind") or "")
- if noun and cause.call_sites > 1:
- module = name.startswith("module scope of ")
- return f"Batch the {noun} calls loops make {'in' if module else 'through'} {name}"
- if noun:
- return f"Move the {noun} call in {name} out of its loop"
- return f"Fix the repeated work in {name}"
-
-
-def _perf_target(cause: _PerfCause, symbol: str | None, steps: tuple[FixStep, ...]) -> FixTarget:
- """The loop around the first call site the plan names, else the call
- itself; with no call site, the function."""
- site = next((s for s in cause.plan_steps if s.get("line")), None)
- if site:
- return FixTarget(
- site.get("file_path") or cause.path,
- _site_symbol(site.get("symbol")),
- site.get("loop_line") or site.get("line"),
- )
- return FixTarget(cause.path, symbol, steps[0].line if steps else None)
-
-
-def _perf_reach(cause: _PerfCause, files_n: int) -> str:
- reach = []
- if cause.call_sites > 1:
- reach.append(f"{cause.call_sites} call sites in {text.plural(files_n, 'file')} reach it")
- if cause.facets.get("exposure") == "entry_reachable":
- reach.append("an entry point reaches it")
- if cause.facets.get("loop_magnitude") == "grows_with_data":
- reach.append("the loop grows with the data")
- return ", ".join(reach) or "the loop size is unknown"
-
-
-def _perf_facts(cause: _PerfCause, files_n: int) -> tuple[FixFact, ...]:
- exposure, loop_magnitude = cause.facets.get("exposure"), cause.facets.get("loop_magnitude")
- facts = [
- FixFact("call sites", str(cause.call_sites)),
- FixFact("files", str(files_n)),
- FixFact(
- "reachable from an entry point",
- text.REACH_ANSWER.get(exposure or "", "unknown"),
- "inferred" if exposure in ("entry_reachable", "not_entry_reachable") else "unknown",
- ),
- FixFact(
- "loop size",
- text.loop_size(loop_magnitude),
- "inferred" if loop_magnitude in ("grows_with_data", "bounded") else "unknown",
- ),
- ]
- sinks = sorted({field(r, "terminal_sink") for r in cause.rows if field(r, "terminal_sink")})
- if len(sinks) > 1:
- facts.append(FixFact("sinks this fix covers", str(len(sinks))))
- return tuple(facts[:MAX_FACTS])
-
-
-def _perf_steps(cause: _PerfCause, item_command: str | None) -> tuple[FixStep, ...]:
- path, lines = cause.path, cause.symbol_lines
- return tuple(
- FixStep(
- int(s.get("order") or i + 1),
- _perf_step_text(s, path),
- s.get("file_path") or path,
- s.get("line") or lines.get(s.get("symbol") or ""),
- s.get("applicability") == "mechanical",
- command=_step_command(s.get("verify"), item_command),
- )
- for i, s in enumerate(cause.plan_steps)
- )
-
-
-def _perf_effort(effort: str | None) -> FixEffortEstimate:
- return FixEffortEstimate(
- _one_of(effort, FIX_EFFORTS, "M"),
- "sized by the stored plan" if effort else "not sized; the plan has no estimate",
- )
-
-
-# --- findings with no plan ----------------------------------------------------------
-
-
-def _finding_rank(finding: Any, files: _Files) -> _ShapeRank:
- path = field(finding, "file_path")
- marker = field(finding, "biomarker_type") or ""
- shape = files.shape(path, field(finding, "function_name"))
- deps = files.dependents(path)
- sized = marker in SIZE_MARKERS
- credited, central = files.reach(path, shape, deps, sized=sized)
- return _ShapeRank(
- shape,
- central,
- files.churning(path),
- changes=files.changes(
- path, field(finding, "function_name"), function=marker not in CLASS_MARKERS
- ),
- cloned=sized and files.cloned(path, shape),
- low=low_priority(marker, shape, error_kind=detail_map(finding).get("kind")),
- gain=_num(field(finding, "health_impact")),
- # Breaking up the whole function takes out its whole CCN.
- ccn_removed=shape.get("ccn", 0) if sized else 0,
- dependents=deps,
- credited=credited,
- )
-
-
-def _finding_unit(lead: Any, files: _Files, first: FixStep, validate: Validate | None) -> _Unit:
- path = field(lead, "file_path")
- marker = field(lead, "biomarker_type") or ""
- function = field(lead, "function_name")
- public_id = field(lead, "public_id")
- rank = _finding_rank(lead, files)
- led = files.extraction(lead)
- after = _plan_after(led, rank.shape, function) if led is not None else None
- if after is None or not _lowers_worst(after, rank.shape):
- led = None
-
- def fields() -> dict[str, Any]:
- where = function or text.basename(path)
- line = field(lead, "line_start")
- return {
- "title": text.clip(_finding_title(marker, function, where, rank.shape, led)),
- "target": FixTarget(path, function, line, field(lead, "line_end")),
- "why": files.why(
- path,
- measured=text.measured(where, rank.shape),
- fallback=text.problem(marker, where),
- cloned=rank.cloned,
- changes=rank.changes,
- function=function is not None,
- ),
- "facts": tuple(
- [
- FixFact("finding", text.marker_label(marker)),
- *_size_facts(rank.shape),
- FixFact("severity", _severity(field(lead, "severity"), rank.low)),
- *files.common_facts(path, function=function is not None),
- ][:MAX_FACTS]
- ),
- "action": _action(text.first_sentence(suggestion_for(marker)), (first,), False),
- "gain": _health_gain(rank.gain, ceiling=True),
- "risk": _risk(1, files.dependents(path), function=function is not None),
- "verify": _verify(
- validate(path, function, line, field(lead, "line_end")) if validate else None
- ),
- "context": files.context(path, function),
- **_finding_plan_fields(led, path, public_id),
- }
-
- return _finish_shaped(
- rank,
- kind="finding",
- source_id=public_id or f"{path}::{marker}::{function or ''}",
- ready=False,
- confidence="medium",
- effort="M",
- improves=_one_of(biomarker_dimension(marker), FIX_IMPROVES, "defect"),
- fields=fields,
- )
-
-
-def _finding_title(
- marker: str,
- function: str | None,
- where: str,
- shape: Mapping[str, int],
- led: Any = None,
-) -> str:
- """A function past the break-up bar reads "Break up", or, when a stored
- plan leads it, the title that plan's own item would have."""
- if magnitude(shape) >= SIZE_BREAK_UP and function and marker in SIZE_MARKERS:
- if led is not None:
- return _led_title(where, shape, led)
- return f"Break up {where} ({text.size_brief(shape)})"
- return text.FINDING_TITLE.get(marker, "Address the finding in {where}").format(where=where)
-
-
-def _plan_after(plan: Any, shape: Mapping[str, int], function: str | None) -> dict[str, Any] | None:
- """The largest function an Extract Method plan leaves (``worth.worst_after``)."""
- return worst_after(_evidence(plan), _plan_body(plan), _tail(function) or "", shape)
-
-
-def _lowers_worst(after: Mapping[str, Any], shape: Mapping[str, int]) -> bool:
- """Whether the largest function a plan leaves is smaller than the one it
- lifts from."""
- if shape.get("ccn"):
- return after["ccn"] < shape["ccn"]
- return after["nloc"] < measured_nloc(shape)
-
-
-#: A led title's caveat when the plan, applied as written, still leaves a
-#: function at the break-up bar, as its step says (:func:`_above_bar_reason`).
-_MORE_STAGES = " (more stages needed)"
-
-
-def _led_title(where: str, shape: Mapping[str, int], plan: Any) -> str:
- body = _plan_body(plan)
- suffix = _MORE_STAGES if _above_bar_reason(plan) else ""
- stages = _stage_count(body)
- if stages:
- return _staged_title(where, stages) + suffix
- start, end = _span(plan)
- return _break_up_title(where, shape, f"{start}-{end}", suffix)
-
-
-def _finding_plan_fields(led: Any, path: str, finding_id: str | None) -> dict[str, Any]:
- """What a finding item says about its plan: none, or the stored Extract
- Method plan its first step lifts (``led``), which the next call opens."""
- findings = (finding_id,) if finding_id else ()
- if led is None:
- return {
- "effort": FixEffortEstimate("M", "not sized; no stored plan covers this finding"),
- "confidence": FixConfidence(
- "medium", "Measured from the code; no stored plan has checked a fix."
- ),
- "source": FixSource(None, (), findings),
- "next_call": _file_findings_call(path),
- }
- plan_id = field(led, "public_id")
- next_call = _file_findings_call(path)
- if plan_id:
- next_call = ActionCommand.call(
- "The stored plan for the first step: its span, helper and checks",
- "get_health",
- {"plan_id": plan_id},
- cli=f"repowise health --plan {plan_id}",
- )
- return {
- # The plan sizes and checks its first lift only, so the item's own
- # effort and confidence stay the finding's.
- "effort": FixEffortEstimate("M", "not sized for the whole fix"),
- "confidence": FixConfidence(
- "medium", "Measured from the code; no plan checks the whole fix."
- ),
- "source": FixSource(None, (plan_id,) if plan_id else (), findings),
- "next_call": next_call,
- }
-
-
-def _file_findings_call(path: str) -> ActionCommand:
- return ActionCommand.call(
- "Every open finding in the file, with its line and reason",
- "get_health",
- {"targets": [path], "include": ["biomarkers"]},
- cli=f"repowise health --file {path}",
- )
-
-
-def _severity(severity: str | None, low: str | None) -> str:
- """The detector's severity; on a later item it says the tier overrides it."""
- severity = severity or "unknown"
- return severity if low is None else f"{severity} by the detector; lower priority by shape"
+from .finding_units import _finding_rank, _finding_unit
+from .model import FIX_EXCLUSIONS, FIX_IMPROVES, FixFirstQueue, FixTotals
+from .perf_units import _perf_step_text, _perf_unit # noqa: F401
+from .plan_steps import _concrete, _extractions, _plan_body, _refactor_step # noqa: F401
+from .refactor_units import _refactor_unit
def _clone_spans(plans: Iterable[Any]) -> dict[str, list[tuple[int, int]]]:
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/finding_units.py b/packages/core/src/repowise/core/analysis/health/fix_first/finding_units.py
new file mode 100644
index 000000000..8ab4b6c2b
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/finding_units.py
@@ -0,0 +1,216 @@
+"""Fix-first units for findings with no plan of their own."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from repowise.core.analysis.health.rows import detail_map, 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 (
+ SIZE_MARKERS,
+ low_priority,
+ magnitude,
+ measured_nloc,
+ worst_after,
+)
+from repowise.core.analysis.next_call import ActionCommand
+
+from . import text
+from ._files import _action, _Files, _finish_shaped, _health_gain, _ShapeRank, _size_facts
+from ._parts import (
+ CLASS_MARKERS,
+ MAX_FACTS,
+ SIZE_BREAK_UP,
+ Validate,
+ _num,
+ _one_of,
+ _risk,
+ _tail,
+ _Unit,
+ _verify,
+)
+from .model import (
+ FIX_IMPROVES,
+ FixConfidence,
+ FixEffortEstimate,
+ FixFact,
+ FixSource,
+ FixStep,
+ FixTarget,
+)
+from .plan_steps import _above_bar_reason, _evidence, _plan_body, _span, _stage_count
+from .refactor_units import _break_up_title, _staged_title
+
+
+def _finding_rank(finding: Any, files: _Files) -> _ShapeRank:
+ path = field(finding, "file_path")
+ marker = field(finding, "biomarker_type") or ""
+ shape = files.shape(path, field(finding, "function_name"))
+ deps = files.dependents(path)
+ sized = marker in SIZE_MARKERS
+ credited, central = files.reach(path, shape, deps, sized=sized)
+ return _ShapeRank(
+ shape,
+ central,
+ files.churning(path),
+ changes=files.changes(
+ path, field(finding, "function_name"), function=marker not in CLASS_MARKERS
+ ),
+ cloned=sized and files.cloned(path, shape),
+ low=low_priority(marker, shape, error_kind=detail_map(finding).get("kind")),
+ gain=_num(field(finding, "health_impact")),
+ # Breaking up the whole function takes out its whole CCN.
+ ccn_removed=shape.get("ccn", 0) if sized else 0,
+ dependents=deps,
+ credited=credited,
+ )
+
+
+def _finding_unit(lead: Any, files: _Files, first: FixStep, validate: Validate | None) -> _Unit:
+ path = field(lead, "file_path")
+ marker = field(lead, "biomarker_type") or ""
+ function = field(lead, "function_name")
+ public_id = field(lead, "public_id")
+ rank = _finding_rank(lead, files)
+ led = files.extraction(lead)
+ after = _plan_after(led, rank.shape, function) if led is not None else None
+ if after is None or not _lowers_worst(after, rank.shape):
+ led = None
+
+ def fields() -> dict[str, Any]:
+ where = function or text.basename(path)
+ line = field(lead, "line_start")
+ return {
+ "title": text.clip(_finding_title(marker, function, where, rank.shape, led)),
+ "target": FixTarget(path, function, line, field(lead, "line_end")),
+ "why": files.why(
+ path,
+ measured=text.measured(where, rank.shape),
+ fallback=text.problem(marker, where),
+ cloned=rank.cloned,
+ changes=rank.changes,
+ function=function is not None,
+ ),
+ "facts": tuple(
+ [
+ FixFact("finding", text.marker_label(marker)),
+ *_size_facts(rank.shape),
+ FixFact("severity", _severity(field(lead, "severity"), rank.low)),
+ *files.common_facts(path, function=function is not None),
+ ][:MAX_FACTS]
+ ),
+ "action": _action(text.first_sentence(suggestion_for(marker)), (first,), False),
+ "gain": _health_gain(rank.gain, ceiling=True),
+ "risk": _risk(1, files.dependents(path), function=function is not None),
+ "verify": _verify(
+ validate(path, function, line, field(lead, "line_end")) if validate else None
+ ),
+ "context": files.context(path, function),
+ **_finding_plan_fields(led, path, public_id),
+ }
+
+ return _finish_shaped(
+ rank,
+ kind="finding",
+ source_id=public_id or f"{path}::{marker}::{function or ''}",
+ ready=False,
+ confidence="medium",
+ effort="M",
+ improves=_one_of(biomarker_dimension(marker), FIX_IMPROVES, "defect"),
+ fields=fields,
+ )
+
+
+def _finding_title(
+ marker: str,
+ function: str | None,
+ where: str,
+ shape: Mapping[str, int],
+ led: Any = None,
+) -> str:
+ """A function past the break-up bar reads "Break up", or, when a stored
+ plan leads it, the title that plan's own item would have."""
+ if magnitude(shape) >= SIZE_BREAK_UP and function and marker in SIZE_MARKERS:
+ if led is not None:
+ return _led_title(where, shape, led)
+ return f"Break up {where} ({text.size_brief(shape)})"
+ return text.FINDING_TITLE.get(marker, "Address the finding in {where}").format(where=where)
+
+
+def _plan_after(plan: Any, shape: Mapping[str, int], function: str | None) -> dict[str, Any] | None:
+ """The largest function an Extract Method plan leaves (``worth.worst_after``)."""
+ return worst_after(_evidence(plan), _plan_body(plan), _tail(function) or "", shape)
+
+
+def _lowers_worst(after: Mapping[str, Any], shape: Mapping[str, int]) -> bool:
+ """Whether the largest function a plan leaves is smaller than the one it
+ lifts from."""
+ if shape.get("ccn"):
+ return after["ccn"] < shape["ccn"]
+ return after["nloc"] < measured_nloc(shape)
+
+
+#: A led title's caveat when the plan, applied as written, still leaves a
+#: function at the break-up bar, as its step says (:func:`_above_bar_reason`).
+_MORE_STAGES = " (more stages needed)"
+
+
+def _led_title(where: str, shape: Mapping[str, int], plan: Any) -> str:
+ body = _plan_body(plan)
+ suffix = _MORE_STAGES if _above_bar_reason(plan) else ""
+ stages = _stage_count(body)
+ if stages:
+ return _staged_title(where, stages) + suffix
+ start, end = _span(plan)
+ return _break_up_title(where, shape, f"{start}-{end}", suffix)
+
+
+def _finding_plan_fields(led: Any, path: str, finding_id: str | None) -> dict[str, Any]:
+ """What a finding item says about its plan: none, or the stored Extract
+ Method plan its first step lifts (``led``), which the next call opens."""
+ findings = (finding_id,) if finding_id else ()
+ if led is None:
+ return {
+ "effort": FixEffortEstimate("M", "not sized; no stored plan covers this finding"),
+ "confidence": FixConfidence(
+ "medium", "Measured from the code; no stored plan has checked a fix."
+ ),
+ "source": FixSource(None, (), findings),
+ "next_call": _file_findings_call(path),
+ }
+ plan_id = field(led, "public_id")
+ next_call = _file_findings_call(path)
+ if plan_id:
+ next_call = ActionCommand.call(
+ "The stored plan for the first step: its span, helper and checks",
+ "get_health",
+ {"plan_id": plan_id},
+ cli=f"repowise health --plan {plan_id}",
+ )
+ return {
+ # The plan sizes and checks its first lift only, so the item's own
+ # effort and confidence stay the finding's.
+ "effort": FixEffortEstimate("M", "not sized for the whole fix"),
+ "confidence": FixConfidence(
+ "medium", "Measured from the code; no plan checks the whole fix."
+ ),
+ "source": FixSource(None, (plan_id,) if plan_id else (), findings),
+ "next_call": next_call,
+ }
+
+
+def _file_findings_call(path: str) -> ActionCommand:
+ return ActionCommand.call(
+ "Every open finding in the file, with its line and reason",
+ "get_health",
+ {"targets": [path], "include": ["biomarkers"]},
+ cli=f"repowise health --file {path}",
+ )
+
+
+def _severity(severity: str | None, low: str | None) -> str:
+ """The detector's severity; on a later item it says the tier overrides it."""
+ severity = severity or "unknown"
+ return severity if low is None else f"{severity} by the detector; lower priority by shape"
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/perf_units.py b/packages/core/src/repowise/core/analysis/health/fix_first/perf_units.py
new file mode 100644
index 000000000..b2a0b6330
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/perf_units.py
@@ -0,0 +1,272 @@
+"""Fix-first units for performance opportunities."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from repowise.core.analysis.health.queue.eligibility import perf_low_priority
+from repowise.core.analysis.health.queue.value import (
+ perf_confidence,
+ perf_ready,
+ perf_value,
+ perf_worth,
+)
+from repowise.core.analysis.health.rows import detail_map, field
+from repowise.core.analysis.health.worth import execution_role
+
+from . import text
+from ._files import _action, _Files, _finish, _opportunity_call
+from ._parts import MAX_FACTS, _one_of, _risk, _step_command, _Unit, _verify
+from .model import (
+ FIX_EFFORTS,
+ FixConfidence,
+ FixEffortEstimate,
+ FixFact,
+ FixGain,
+ FixRankFact,
+ FixSource,
+ FixStep,
+ FixTarget,
+)
+
+
+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."""
+ action = step.get("action") or ""
+ name = text.scope_name(step.get("symbol"), path)
+ # A whole word that is not an attribute: ``get`` is not named by a quoted
+ # ``session.get`` call, nor by ``getattr``.
+ short = name.rsplit(".", 1)[-1] if name else ""
+ if not name or re.search(rf"(?<![\w.]){re.escape(short)}(?!\w)", action):
+ return action
+ return f"{action} ({name})"
+
+
+def _site_symbol(symbol: str | None) -> str | None:
+ """The function a call site sits in; ``None`` for none, or a file's top
+ level, which is no symbol to jump to."""
+ short = text.short_symbol(symbol)
+ if not short or short.rsplit(".", 1)[-1] == "__module__":
+ return None
+ return short
+
+
+def _perf_unit(
+ rows: list[Any], files: _Files, symbol_lines: Mapping[str, int] | None = None
+) -> _Unit:
+ cause = _PerfCause.read(rows, files, symbol_lines)
+ lead, path = cause.lead, cause.path
+ return _finish(
+ kind="perf_fix",
+ may_lead=cause.details.get("may_lead") is not False,
+ source_id=f"{path}::{cause.symbol or path}",
+ value=perf_value(lead, cause.facets),
+ ready=perf_ready(lead, cause.plan),
+ worth=perf_worth(cause.call_sites, files.churning(path)),
+ confidence=perf_confidence(cause.facets),
+ effort=cause.plan.get("effort_bucket") or "M",
+ improves="performance",
+ low=perf_low_priority(lead),
+ rank_inputs=lambda: _perf_rank_facts(cause),
+ fields=lambda: _perf_fields(cause),
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class _PerfCause:
+ """One intervention's performance rows as its item reads them, led by
+ the best ranked."""
+
+ rows: list[Any]
+ files: _Files
+ symbol_lines: Mapping[str, int]
+ lead: Any
+ details: Mapping[str, Any]
+ facets: Mapping[str, Any]
+ plan: Mapping[str, Any]
+ path: str
+ symbol: str | None
+ call_sites: int
+
+ @classmethod
+ def read(
+ cls, rows: list[Any], files: _Files, symbol_lines: Mapping[str, int] | None
+ ) -> _PerfCause:
+ lead = min(
+ rows, key=lambda r: (field(r, "rank_position") or 0, field(r, "opportunity_id"))
+ )
+ details = detail_map(lead)
+ return cls(
+ rows,
+ files,
+ symbol_lines or {},
+ lead,
+ details,
+ details.get("facets") or {},
+ details.get("plan") or {},
+ field(lead, "file_path") or "",
+ field(lead, "intervention_symbol"),
+ int(field(lead, "affected_call_sites_total") or 0),
+ )
+
+ @property
+ def plan_steps(self) -> list[Mapping[str, Any]]:
+ return self.plan.get("steps") or []
+
+
+def _perf_rank_facts(cause: _PerfCause) -> list[FixRankFact]:
+ lead = cause.lead
+ return [
+ FixRankFact("runs in", field(lead, "execution_context") or "unknown"),
+ FixRankFact("run by", execution_role(lead)),
+ FixRankFact("call sites", str(cause.call_sites)),
+ FixRankFact("loop size", text.loop_size(cause.facets.get("loop_magnitude"))),
+ FixRankFact(
+ "boundary", text.BOUNDARY_NOUN.get(field(lead, "boundary_kind") or "", "none")
+ ),
+ ]
+
+
+def _perf_fields(cause: _PerfCause) -> dict[str, Any]:
+ lead, path = cause.lead, cause.path
+ name, symbol = _perf_name(cause)
+ files_n = int(field(lead, "affected_files_total") or 1)
+ what, gain_text = text.perf_cost(
+ name,
+ field(lead, "biomarker_type"),
+ field(lead, "boundary_kind"),
+ cause.facets.get("amplification"),
+ cause.facets.get("loop_magnitude"),
+ )
+ verify = _verify(cause.plan.get("validation"))
+ steps = _perf_steps(cause, verify.command)
+ strategy = field(lead, "fix_strategy") or ""
+ return {
+ "title": text.clip(_perf_title(cause, name)),
+ "target": _perf_target(cause, symbol, steps),
+ "why": f"{what}; {_perf_reach(cause, files_n)}.",
+ "facts": _perf_facts(cause, files_n),
+ "action": _action(
+ text.FIX_STRATEGY.get(strategy, text.humanize(strategy).capitalize()),
+ steps,
+ _all_mechanical(cause.plan_steps),
+ ),
+ "gain": FixGain("performance", None, gain_text),
+ "effort": _perf_effort(cause.plan.get("effort_bucket")),
+ "risk": _risk(files_n, None),
+ "confidence": FixConfidence(
+ perf_confidence(cause.facets),
+ cause.details.get("fix_rationale")
+ or f"{text.humanize(field(lead, 'actionability_state'))} plan",
+ ),
+ "verify": verify,
+ "context": cause.files.context(path, symbol),
+ "source": FixSource(field(lead, "opportunity_id")),
+ "next_call": _opportunity_call(
+ "The full opportunity: ordered steps, validation and other causes here",
+ field(lead, "opportunity_id"),
+ ),
+ }
+
+
+def _perf_name(cause: _PerfCause) -> tuple[str, str | None]:
+ """What the item calls the function, and the symbol its target names:
+ ``None`` at module scope or when no symbol is stored."""
+ # A cause with no intervention symbol is named by the function its plan edits.
+ first = cause.plan_steps[0] if cause.plan_steps else {}
+ name = (
+ text.scope_name(cause.symbol, cause.path)
+ or text.scope_name(first.get("symbol"), cause.path)
+ or text.basename(cause.path)
+ )
+ module = name.startswith("module scope of ")
+ return name, name if (cause.symbol or first.get("symbol")) and not module else None
+
+
+def _all_mechanical(plan_steps: list[Mapping[str, Any]]) -> bool:
+ return bool(plan_steps) and all(s.get("applicability") == "mechanical" for s in plan_steps)
+
+
+def _perf_title(cause: _PerfCause, name: str) -> str:
+ shaped = text.PERF_SHAPE.get(field(cause.lead, "biomarker_type") or "")
+ if shaped:
+ return shaped[0].format(name=name)
+ noun = text.BOUNDARY_NOUN.get(field(cause.lead, "boundary_kind") or "")
+ if noun and cause.call_sites > 1:
+ module = name.startswith("module scope of ")
+ return f"Batch the {noun} calls loops make {'in' if module else 'through'} {name}"
+ if noun:
+ return f"Move the {noun} call in {name} out of its loop"
+ return f"Fix the repeated work in {name}"
+
+
+def _perf_target(cause: _PerfCause, symbol: str | None, steps: tuple[FixStep, ...]) -> FixTarget:
+ """The loop around the first call site the plan names, else the call
+ itself; with no call site, the function."""
+ site = next((s for s in cause.plan_steps if s.get("line")), None)
+ if site:
+ return FixTarget(
+ site.get("file_path") or cause.path,
+ _site_symbol(site.get("symbol")),
+ site.get("loop_line") or site.get("line"),
+ )
+ return FixTarget(cause.path, symbol, steps[0].line if steps else None)
+
+
+def _perf_reach(cause: _PerfCause, files_n: int) -> str:
+ reach = []
+ if cause.call_sites > 1:
+ reach.append(f"{cause.call_sites} call sites in {text.plural(files_n, 'file')} reach it")
+ if cause.facets.get("exposure") == "entry_reachable":
+ reach.append("an entry point reaches it")
+ if cause.facets.get("loop_magnitude") == "grows_with_data":
+ reach.append("the loop grows with the data")
+ return ", ".join(reach) or "the loop size is unknown"
+
+
+def _perf_facts(cause: _PerfCause, files_n: int) -> tuple[FixFact, ...]:
+ exposure, loop_magnitude = cause.facets.get("exposure"), cause.facets.get("loop_magnitude")
+ facts = [
+ FixFact("call sites", str(cause.call_sites)),
+ FixFact("files", str(files_n)),
+ FixFact(
+ "reachable from an entry point",
+ text.REACH_ANSWER.get(exposure or "", "unknown"),
+ "inferred" if exposure in ("entry_reachable", "not_entry_reachable") else "unknown",
+ ),
+ FixFact(
+ "loop size",
+ text.loop_size(loop_magnitude),
+ "inferred" if loop_magnitude in ("grows_with_data", "bounded") else "unknown",
+ ),
+ ]
+ sinks = sorted({field(r, "terminal_sink") for r in cause.rows if field(r, "terminal_sink")})
+ if len(sinks) > 1:
+ facts.append(FixFact("sinks this fix covers", str(len(sinks))))
+ return tuple(facts[:MAX_FACTS])
+
+
+def _perf_steps(cause: _PerfCause, item_command: str | None) -> tuple[FixStep, ...]:
+ path, lines = cause.path, cause.symbol_lines
+ return tuple(
+ FixStep(
+ int(s.get("order") or i + 1),
+ _perf_step_text(s, path),
+ s.get("file_path") or path,
+ s.get("line") or lines.get(s.get("symbol") or ""),
+ s.get("applicability") == "mechanical",
+ command=_step_command(s.get("verify"), item_command),
+ )
+ for i, s in enumerate(cause.plan_steps)
+ )
+
+
+def _perf_effort(effort: str | None) -> FixEffortEstimate:
+ return FixEffortEstimate(
+ _one_of(effort, FIX_EFFORTS, "M"),
+ "sized by the stored plan" if effort else "not sized; the plan has no estimate",
+ )
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.py b/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.py
new file mode 100644
index 000000000..fd40510d0
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.py
@@ -0,0 +1,257 @@
+"""Read stored refactoring plans and word their steps."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+from repowise.core.analysis.health.refactoring.recipe import ELSEWHERE_NOTE, plan_anchors
+from repowise.core.analysis.health.rows import field, json_field
+from repowise.core.analysis.health.worth import LowPriority
+from repowise.core.ci.markdown import code as md_code
+
+from . import text
+from ._parts import _helper_code, _open
+from .model import FixStep
+
+
+def _plan_body(plan: Any) -> dict[str, Any]:
+ if plan is None:
+ return {}
+ body = json_field(plan, "plan", None) or json_field(plan, "plan_json", {})
+ return body if isinstance(body, dict) else {}
+
+
+def _above_bar(details: Mapping[str, Any]) -> LowPriority | None:
+ """An opportunity one of whose plans, applied as written, still leaves a
+ function above the break-up bar: half a fix, so it can wait."""
+ return "above_bar_after" if details.get("leaves_above_bar") else None
+
+
+def _above_bar_reason(plan: Any) -> str | None:
+ """Why the plan, applied as written, leaves a function above the break-up
+ bar: its rank facts' ``leaves_above_bar``, in the plan's own words."""
+ rank = json_field(plan, "rank", None) or json_field(plan, "rank_json", {})
+ reason = rank.get("leaves_above_bar") if isinstance(rank, dict) else None
+ return reason if isinstance(reason, str) and reason else None
+
+
+def _above_bar_note(step: str, plan: Any) -> str:
+ """A finding's borrowed *step*, saying so when the plan leaves the
+ function above the break-up bar (:func:`_above_bar_reason`)."""
+ reason = _above_bar_reason(plan)
+ return f"{step.removesuffix('.')}. This plan alone {reason}." if reason else step
+
+
+def _evidence(plan: Any) -> dict[str, Any]:
+ if plan is None:
+ return {}
+ found = json_field(plan, "evidence", None) or json_field(plan, "evidence_json", {})
+ return found if isinstance(found, dict) else {}
+
+
+def _span(plan: Any) -> tuple[int | None, int | None]:
+ span = _plan_body(plan).get("span")
+ if isinstance(span, dict):
+ return span.get("start"), span.get("end")
+ return None, None
+
+
+def _refactor_step(
+ order: int, step: Mapping[str, Any], plan: Any, command: str | None = None
+) -> FixStep:
+ kind = step.get("refactoring_type") or ""
+ path = step.get("file_path") or ""
+ sym = text.short_symbol(step.get("target_symbol")) or text.basename(path)
+ body = _plan_body(plan)
+ phrase = _STEP_TEXT.get(kind)
+ line_text = (
+ phrase(sym, path, plan, body) if phrase else f"Apply the {text.humanize(kind)} step to {sym}"
+ )
+ code = _helper_code(body) if kind == "extract_method" else {}
+ mechanical = (step.get("applicability") or {}).get("classification") == "mechanical"
+ line = _span(plan)[0] or step.get("line_start")
+ return FixStep(order, line_text, path, line, mechanical, **code, command=command)
+
+
+def _first_four(names: list[str]) -> str:
+ """Up to four names, then how many more."""
+ more = f" and {len(names) - 4} more" if len(names) > 4 else ""
+ return f"{', '.join(names[:4])}{more}"
+
+
+def _extract_class_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
+ """The smallest named group of methods leaves for a new class."""
+ groups = [g for g in body.get("groups") or [] if g.get("methods")]
+ if not groups:
+ return f"Move a cohesive group of {sym}'s methods into a new class"
+ members = sorted(groups, key=lambda g: len(g["methods"]))[0]["methods"]
+ return f"Move {_first_four(members)} out of {sym} into a new class"
+
+
+def _split_file_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
+ names = [g.get("name") for g in body.get("groups") or [] if g.get("name")]
+ if not names:
+ return f"Split {text.basename(path)} along its independent groups"
+ return f"Split {text.basename(path)} into {_first_four(names)}"
+
+
+def _break_cycle_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
+ edge = _cut_edge(plan)
+ if edge is None:
+ return _uncut_cycle_text(path, plan)
+ return (
+ f"Cut the import of {text.basename(edge['to'])} in "
+ f"{text.basename(edge['from'])} (line {edge['line']})"
+ )
+
+
+def _move_method_text(sym: str, path: str, plan: Any, body: Mapping[str, Any]) -> str:
+ dest = body.get("to_class") or text.basename(body.get("to_file") or "")
+ return f"Move {sym} to {dest}" if dest else f"Move {sym} to the class it uses most"
+
+
+def _extract_text(sym: str, body: Mapping[str, Any], start: Any, end: Any) -> str:
+ """An Extract Method step: its span by the text it starts and ends with
+ when the plan anchored it (line numbers move with every edit), else by
+ its lines; a staged plan's step is its first stage."""
+ into = text.signature(
+ body.get("suggested_name"),
+ list(body.get("params") or []),
+ list(body.get("returns") or []),
+ is_async=bool(body.get("needs_async", False)),
+ )
+ anchors = plan_anchors(body.get("anchors"))
+ # Worded like the plan's own step (``recipe._extract_step``).
+ if anchors is not None:
+ where = f"{sym} from {md_code(anchors['first'])} to {md_code(anchors['last'])}"
+ else:
+ where = f"lines {start}-{end} of {sym}" if start and end else f"part of {sym}"
+ line_text = _stage_one(f"Extract {where} into {into}", body)
+ if anchors is not None and anchors["unique_in"] == "function":
+ line_text = f"{line_text}. {ELSEWHERE_NOTE}"
+ return line_text
+
+
+#: A refactoring step's sentence, by plan type, from (symbol, path, plan, plan body).
+_STEP_TEXT: dict[str, Callable[[str, str, Any, Mapping[str, Any]], str]] = {
+ "extract_method": lambda sym, path, plan, body: _extract_text(sym, body, *_span(plan)),
+ "extract_helper": lambda sym, *_: (
+ f"Replace the duplicate in {sym} with a call to one shared helper"
+ ),
+ "extract_class": _extract_class_text,
+ "split_file": _split_file_text,
+ "break_cycle": _break_cycle_text,
+ "move_method": _move_method_text,
+}
+
+
+def _stage_count(body: Mapping[str, Any]) -> int:
+ """How many helpers a staged Extract Method plan splits its function into;
+ 0 when unstaged. Counts stages with a span, as the plan detail page does,
+ and fewer than two is no split."""
+ stages = body.get("stages")
+ if not isinstance(stages, (list, tuple)):
+ return 0
+ count = sum(_has_span(stage) for stage in stages)
+ return count if count >= 2 else 0
+
+
+def _has_span(stage: Any) -> bool:
+ """A stage with nonzero integer line bounds (a bool is not a line)."""
+ span = stage.get("span") if isinstance(stage, dict) else None
+ if not isinstance(span, dict):
+ return False
+ start, end = span.get("start"), span.get("end")
+ return type(start) is int and type(end) is int and bool(start and end)
+
+
+def _stage_one(line_text: str, body: Mapping[str, Any]) -> str:
+ """A staged plan's step is its first stage (the plan's top-level span):
+ it says so, and the function's CCN once every stage is done."""
+ count = _stage_count(body)
+ if not count:
+ return line_text
+ residual = body.get("orchestrator")
+ before, after = (
+ (residual.get("ccn_before"), residual.get("ccn_after"))
+ if isinstance(residual, dict)
+ else (None, None)
+ )
+ ccn = (
+ f" (CCN {before} -> {after} after all {count})"
+ if before is not None and after is not None
+ else ""
+ )
+ return f"Stage 1 of {count}: {line_text}{ccn}"
+
+
+def _uncut_cycle_text(path: str, plan: Any) -> str:
+ """A cycle step with no import line to cut, labelled when it is idiomatic."""
+ if _plan_body(plan).get("idiom"):
+ return (
+ f"Optional: {text.basename(path)} is in an import cycle within one "
+ "directory, which is idiomatic in this language"
+ )
+ return f"Break the import cycle at {text.basename(path)}"
+
+
+def _cut_edge(plan: Any) -> dict[str, Any] | None:
+ """The first cut edge whose import line is stored.
+
+ An idiomatic cycle (one directory of a language that compiles mutual
+ references in one pass) has no edge to cut, so it never reads as a must-do.
+ """
+ if _plan_body(plan).get("idiom"):
+ return None
+ for edge in _plan_body(plan).get("cut_edges") or ():
+ if isinstance(edge, dict) and edge.get("line") and edge.get("from") and edge.get("to"):
+ return edge
+ return None
+
+
+def _concrete(step: Mapping[str, Any], plan: Any) -> bool:
+ """Whether a refactoring step names an edit someone can make: lines to
+ lift, a destination, the import to cut, or named groups."""
+ kind = step.get("refactoring_type") or ""
+ body = _plan_body(plan)
+ if kind == "extract_method":
+ start, end = _span(plan)
+ return bool(start and end)
+ if kind == "extract_helper":
+ return any(
+ isinstance(o, dict) and o.get("line_start") for o in body.get("occurrences") or ()
+ )
+ if kind == "move_method":
+ return bool(body.get("to_class") or body.get("to_file"))
+ if kind == "break_cycle":
+ return _cut_edge(plan) is not None
+ if kind in ("split_file", "extract_class"):
+ members = "symbols" if kind == "split_file" else "methods"
+ return any(
+ isinstance(g, dict) and g.get(members) and (g.get("name") or kind == "extract_class")
+ for g in body.get("groups") or ()
+ )
+ return bool(step.get("line_start"))
+
+
+def _extraction_worth(plan: Any) -> tuple[int, int]:
+ evidence = _evidence(plan)
+ return int(evidence.get("ccn_removed") or 0), int(evidence.get("slice_nloc") or 0)
+
+
+def _extractions(plans: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:
+ """Open Extract Method plans with a span, by (file, function name). A plan
+ a step names is read whatever its status, so a dismissed one is skipped."""
+ out: dict[tuple[str, str], list[Any]] = defaultdict(list)
+ for plan in plans:
+ symbol = field(plan, "target_symbol")
+ if field(plan, "refactoring_type") != "extract_method" or not symbol or not _open(plan):
+ continue
+ start, end = _span(plan)
+ if start and end:
+ out[(field(plan, "file_path"), text.short_symbol(symbol).rsplit(".", 1)[-1])].append(
+ plan
+ )
+ return dict(out)
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/refactor_units.py b/packages/core/src/repowise/core/analysis/health/fix_first/refactor_units.py
new file mode 100644
index 000000000..7158c376a
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/refactor_units.py
@@ -0,0 +1,328 @@
+"""Fix-first units for stored refactoring plans."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from repowise.core.analysis.health.queue.eligibility import UNAUDITED_KINDS
+from repowise.core.analysis.health.queue.order import LEVEL_RANK
+from repowise.core.analysis.health.rows import field
+from repowise.core.analysis.health.scoring import biomarker_dimension
+from repowise.core.analysis.health.worth import low_priority, magnitude
+
+from . import text
+from ._files import (
+ _action,
+ _Files,
+ _finish_shaped,
+ _health_gain,
+ _opportunity_call,
+ _ShapeRank,
+ _size_facts,
+)
+from ._parts import (
+ _FUNCTION_LEADS,
+ MAX_FACTS,
+ SIZE_BREAK_UP,
+ _one_of,
+ _risk,
+ _step_command,
+ _Unit,
+ _verify,
+)
+from .model import (
+ FIX_EFFORTS,
+ FIX_IMPROVES,
+ FixConfidence,
+ FixEffortEstimate,
+ FixFact,
+ FixSource,
+ FixStep,
+ FixTarget,
+)
+from .plan_steps import (
+ _above_bar,
+ _evidence,
+ _extraction_worth,
+ _plan_body,
+ _refactor_step,
+ _span,
+ _stage_count,
+)
+
+
+def _refactor_unit(
+ row: Any,
+ details: Mapping[str, Any],
+ steps: list[Mapping[str, Any]],
+ gain: float,
+ plans: Mapping[str, Any],
+ files: _Files,
+) -> _Unit:
+ plan = _RefactorPlan.read(row, details, steps, gain, plans, files)
+ dimension = biomarker_dimension(plan.marker) if plan.marker else "maintainability"
+ return _finish_shaped(
+ plan.rank,
+ kind="refactor",
+ source_id=field(row, "opportunity_id"),
+ ready=plan.mechanical or plan.confidence == "high",
+ confidence=plan.confidence,
+ effort=plan.effort,
+ improves=_one_of(dimension, FIX_IMPROVES, "maintainability"),
+ fields=lambda: _refactor_fields(plan),
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class _RefactorPlan:
+ """A stored refactoring plan as its item reads it: the lead step, the
+ steps an item may carry, and the shape the plan is ranked on."""
+
+ row: Any
+ details: Mapping[str, Any]
+ lead: Mapping[str, Any]
+ steps: list[Mapping[str, Any]]
+ held_back: int
+ plans: Mapping[str, Any]
+ files: _Files
+ sym: str
+ lead_type: str
+ marker: str | None
+ confidence: str
+ effort: str
+ rank: _ShapeRank
+
+ @classmethod
+ def read(
+ cls,
+ row: Any,
+ details: Mapping[str, Any],
+ steps: list[Mapping[str, Any]],
+ gain: float,
+ plans: Mapping[str, Any],
+ files: _Files,
+ ) -> _RefactorPlan:
+ path = field(row, "file_path")
+ lead = steps[0]
+ steps, held_back = _audited_steps(steps)
+ lead_type, marker = _lead_kind(row, lead)
+ shape = files.shape(path, lead.get("target_symbol"))
+ deps = details.get("dependents")
+ deps = files.dependents(path) if deps is None else deps
+ function_size = lead_type == "extract_method"
+ credited, central = files.reach(path, shape, deps, sized=function_size)
+ rank = _ShapeRank(
+ shape,
+ central,
+ files.churning(path),
+ changes=files.changes(
+ path, lead.get("target_symbol"), function=lead_type in _FUNCTION_LEADS
+ ),
+ cloned=function_size and files.cloned(path, shape),
+ low=low_priority(marker, shape, function_size=function_size) or _above_bar(details),
+ gain=gain,
+ ccn_removed=sum(_extraction_worth(plans.get(s.get("plan_id")))[0] for s in steps),
+ dependents=deps,
+ credited=credited,
+ )
+ return cls(
+ row,
+ details,
+ lead,
+ steps,
+ held_back,
+ plans,
+ files,
+ sym=text.short_symbol(lead.get("target_symbol")) or text.basename(path),
+ lead_type=lead_type,
+ marker=marker,
+ confidence=_one_of(field(row, "confidence") or "medium", LEVEL_RANK, "medium"),
+ effort=_one_of(field(row, "effort_bucket") or "M", FIX_EFFORTS, "M"),
+ rank=rank,
+ )
+
+ @property
+ def path(self) -> str:
+ return field(self.row, "file_path")
+
+ @property
+ def mechanical_n(self) -> int:
+ return sum(
+ (s.get("applicability") or {}).get("classification") == "mechanical"
+ for s in self.steps
+ )
+
+ @property
+ def mechanical(self) -> bool:
+ return self.mechanical_n == len(self.steps)
+
+
+def _lead_kind(row: Any, lead: Mapping[str, Any]) -> tuple[str, str | None]:
+ """The lead step's refactoring type, and the marker the plan answers."""
+ lead_type = lead.get("refactoring_type") or field(row, "lead_refactoring_type") or ""
+ marker = field(row, "lead_biomarker") or (
+ lead_type if lead_type in ("split_file", "break_cycle") else None
+ )
+ return lead_type, marker
+
+
+def _refactor_fields(plan: _RefactorPlan) -> dict[str, Any]:
+ lead, path, rank, files = plan.lead, plan.path, plan.rank, plan.files
+ lead_plan = plan.plans.get(lead.get("plan_id"))
+ profiles = {p.get("id"): p for p in plan.details.get("validation_profiles") or []}
+ verify = _verify(
+ profiles.get(lead.get("validation_profile_id")) or next(iter(profiles.values()), None)
+ )
+ fix_steps = _refactor_fix_steps(plan, profiles, verify.command)
+ n_steps, mechanical_n = text.plural(len(plan.steps), "step"), plan.mechanical_n
+ # The symbol the lead step edits; ``None`` for a file-level plan.
+ symbol = plan.sym if lead.get("target_symbol") else None
+ return {
+ "title": text.clip(_refactor_title(plan, lead_plan)),
+ "target": FixTarget(
+ path,
+ symbol,
+ fix_steps[0].line,
+ lead.get("line_end"),
+ ),
+ "why": files.why(
+ path,
+ measured=_refactor_measure(plan.lead_type, plan.sym, path, lead, lead_plan, files),
+ fallback=text.problem(plan.marker, plan.sym),
+ dependents=rank.dependents,
+ cloned=rank.cloned,
+ changes=rank.changes,
+ function=symbol is not None,
+ ),
+ "facts": _refactor_facts(plan, function=symbol is not None),
+ "action": _action(f"{n_steps}, {mechanical_n} mechanical", fix_steps, plan.mechanical),
+ "gain": _health_gain(rank.gain, ceiling=False),
+ "effort": FixEffortEstimate(plan.effort, "sized by the stored plan"),
+ "risk": _risk(
+ int(field(plan.row, "affected_files_total") or 1),
+ rank.dependents,
+ function=symbol is not None,
+ ),
+ "confidence": FixConfidence(
+ plan.confidence, f"{mechanical_n} of {n_steps} proven mechanical by the plan"
+ ),
+ "verify": verify,
+ "context": files.context(path, symbol),
+ "source": FixSource(
+ field(plan.row, "opportunity_id"),
+ tuple(s.get("plan_id") for s in plan.steps if s.get("plan_id")),
+ tuple(plan.details.get("lead_finding_ids") or ()),
+ ),
+ "next_call": _opportunity_call(
+ "The full plan: ordered steps, validation and evidence",
+ field(plan.row, "opportunity_id"),
+ ),
+ }
+
+
+def _refactor_fix_steps(
+ plan: _RefactorPlan, profiles: Mapping[Any, Mapping[str, Any]], item_command: str | None
+) -> tuple[FixStep, ...]:
+ return tuple(
+ _refactor_step(
+ i + 1,
+ s,
+ plan.plans.get(s.get("plan_id")),
+ _step_command(profiles.get(s.get("validation_profile_id")), item_command),
+ )
+ for i, s in enumerate(plan.steps)
+ )
+
+
+def _refactor_title(plan: _RefactorPlan, lead_plan: Any) -> str:
+ """A staged plan names how many helpers it splits the function into, a big
+ function's first lift names the problem and the span, and any other plan
+ reads its title off the lead step's kind."""
+ stages = _stage_count(_plan_body(lead_plan)) if plan.lead_type == "extract_method" else 0
+ if stages:
+ return _with_more_steps(plan, _staged_title(plan.sym, stages))
+ return _span_title(plan, lead_plan)
+
+
+def _staged_title(sym: str, stages: int) -> str:
+ return f"Split {sym} into {stages} helpers"
+
+
+def _span_title(plan: _RefactorPlan, lead_plan: Any) -> str:
+ start, end = _span(lead_plan)
+ # Titles never quote the helper name: it is a placeholder the step asks to rename.
+ spanned = plan.lead_type == "extract_method" and bool(start and end)
+ if spanned and magnitude(plan.rank.shape) >= SIZE_BREAK_UP:
+ return _break_up_title(plan.sym, plan.rank.shape, f"{start}-{end}")
+ template = text.REFACTOR_TITLE.get(
+ "extract_method_span" if spanned else plan.lead_type, "Refactor {file}"
+ )
+ title = template.format(sym=plan.sym, file=text.basename(plan.path), start=start, end=end)
+ return _with_more_steps(plan, title)
+
+
+def _with_more_steps(plan: _RefactorPlan, title: str) -> str:
+ if len(plan.steps) > 1:
+ title += f" (+{text.plural(len(plan.steps) - 1, 'more step')})"
+ return title
+
+
+def _break_up_title(sym: str, shape: Mapping[str, int], span: str, suffix: str = "") -> str:
+ title = f"Start breaking up {sym} ({text.size_brief(shape)}): first lift lines {span}"
+ # A caveat outranks the span and the size, which the step and why name anyway.
+ head = f"Start breaking up {sym}"
+ for candidate in (title, f"{head} ({text.size_brief(shape)})", head):
+ if len(candidate + suffix) <= text.TITLE_MAX:
+ return candidate + suffix
+ return head + suffix
+
+
+def _refactor_facts(plan: _RefactorPlan, *, function: bool) -> tuple[FixFact, ...]:
+ rank, held_back = plan.rank, plan.held_back
+ facts = [
+ FixFact("health recoverable", f"+{rank.gain:.1f}", "inferred"),
+ *_size_facts(rank.shape),
+ FixFact("steps", f"{len(plan.steps)} ({plan.mechanical_n} mechanical)"),
+ *([FixFact("steps held back", text.held_back(held_back))] if held_back else []),
+ *plan.files.common_facts(plan.path, rank.dependents, function=function),
+ ]
+ nloc = plan.files.nloc(plan.path)
+ if nloc:
+ facts.append(FixFact("file size", f"{nloc} lines"))
+ return tuple(facts[:MAX_FACTS])
+
+
+def _audited_steps(steps: list[Mapping[str, Any]]) -> tuple[list[Mapping[str, Any]], int]:
+ """The steps an item may carry, and how many it held back: steps of a
+ kind not yet audited stay in the full plan, never in the item."""
+ kept = [s for s in steps if s.get("refactoring_type") not in UNAUDITED_KINDS]
+ return kept, len(steps) - len(kept)
+
+
+def _refactor_measure(
+ kind: str, sym: str, path: str, step: Mapping[str, Any], plan: Any, files: _Files
+) -> str | None:
+ """The numbers behind a refactoring, from its plan evidence or its findings."""
+ evidence = _evidence(plan)
+ name = text.basename(path)
+ if kind == "split_file" and evidence.get("file_nloc"):
+ return (
+ f"{name}: {text.plural(int(evidence['file_nloc']), 'line')} in "
+ f"{evidence.get('group_count') or 'several'} loosely coupled groups"
+ )
+ if kind == "break_cycle" and evidence.get("cycle_size"):
+ idiom = " within one directory (idiomatic)" if evidence.get("idiom") else ""
+ return f"{name} is in an import cycle of {evidence['cycle_size']} files{idiom}"
+ if kind == "extract_class" and evidence.get("method_count"):
+ return (
+ f"{sym}: {evidence['method_count']} methods in "
+ f"{evidence.get('lcom4') or 'several'} groups that share little state"
+ )
+ if kind == "extract_helper" and evidence.get("duplicated_lines"):
+ return (
+ f"{sym}: {evidence['duplicated_lines']} lines duplicated across "
+ f"{evidence.get('occurrence_count') or 2} places"
+ )
+ return text.measured(sym, files.shape(path, step.get("target_symbol")))