Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(health): lead Fix first with work that pays (#3422)

Raghav Chamadiyaf3d1b3ba5e5f
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 62557de8e..7f3ae5566 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -683,10 +683,13 @@ reason. These reasons and the performance default queue's are decided in one pla
| `no_concrete_step` | No first edit with a file and line or a named group |
| `low_value_kind` | Low cohesion (0 of 46 accepted), long method (0 of 10), long parameter lists (0 of 2) |
| `kind_unaudited` | Plans led by Extract Class (0 of 14 accepted) or Move Method (0 of 34), kept to the full list until each passes a per-language audit |
+| `terminal_flow` | A quarter or more of the function's calls print or prompt (`complexity/terminal.py`): a status report, checklist or setup wizard |
+| `moderate_quiet` | Under CCN 80 and 200 lines, in a file outside the top fifth by churn (or changed once), with no `prior_defect` in the file and no `function_hotspot` on the function |
Order: value first (the larger of health recovered and size: CCN 20/40/80/150,
lines 100/200/400/800, nesting 5/6/8, a critical or brain-method finding, one step
-more on a hot file); a performance fix's value is its cost, with production,
+more on a hot file, where a function under 5% of its file's lines is credited that
+share of the file's importers); a performance fix's value is its cost, with production,
entry-reachable, data-growing DB or network calls in the top band. Then tier
`now` / `next` / `later`, with at most `HEAD_PER_KIND` (3) of the first `HEAD` (5)
places per kind. `worth.py` decides `later` for every default list: a function
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index caba9c62e..c762daf82 100644
--- a/docs/layers/CODE_HEALTH.md
+++ b/docs/layers/CODE_HEALTH.md
@@ -99,6 +99,10 @@ Left out, and counted with a reason:
- kinds that reviewers found not worth doing
- code a sure dead-code finding covers (the fix is to delete it)
- dormant functions, which a constant flag switches off
+- print and prompt flows (status reports, checklists, setup wizards), whose
+ branches choose what to show
+- functions under CCN 80 and 200 lines whose file rarely changes and has no bug
+ fixes; they stay in the refactoring list
A function is dormant when its body opens with `if not FLAG: return ...` (or is one
`if FLAG:` block) and `FLAG` is a module-level `False`, `0` or `None` (`const FLAG =
@@ -110,7 +114,8 @@ outside with `setattr` or a test's monkeypatch, still reads as off.
Items rank by value first (how far the code sits past size and complexity bars,
one step more in a widely imported file), then by tier. Within a value, the
complexity a fix removes times how widely the file is imported decides, so a
-4,000-line loop outranks a long print routine. A performance fix ranks by what runs
+4,000-line loop outranks a long print routine. A function under a twentieth of a
+very large file counts only its share of that file's importers. A performance fix ranks by what runs
it: a request or message handler, then a scheduled job, then code with no role
evidence. No kind takes more than 3 of the first 5 places while another has work
worth doing.
@@ -142,6 +147,8 @@ snoozing a row takes effect at once.
A fragile file asks for tests only when no measured coverage and no test in the
code graph reaches it; otherwise the row asks you to simplify its lead function.
+A folder where bug fixes concentrate names its first step, the most fixed file's,
+or is left out.
An index with fewer than five commits leaves out the rows ranked by history.
```bash
diff --git a/packages/core/src/repowise/core/analysis/actions/rules/code.py b/packages/core/src/repowise/core/analysis/actions/rules/code.py
index f294fd1d2..357fdd159 100644
--- a/packages/core/src/repowise/core/analysis/actions/rules/code.py
+++ b/packages/core/src/repowise/core/analysis/actions/rules/code.py
@@ -387,7 +387,10 @@ def fix_concentration(facts: RepoFacts, ctx: RepoContext) -> RuleOutcome:
Told as an area of work rather than a list of files, because that is how a
lead plans it. The deepest folder that still clears the share wins, so the
- answer is `update_cmd/`, not `packages/`.
+ answer is `update_cmd/`, not `packages/`. The title names where to start:
+ the first step of its most fixed fragile file. A folder with no such step
+ is left out and counted in the outcome's reason, and its files keep their
+ own rows.
"""
rule = "fix_concentration"
if "files" in facts.unavailable:
@@ -438,72 +441,110 @@ def fix_concentration(facts: RepoFacts, ctx: RepoContext) -> RuleOutcome:
continue
chosen.append(folder)
actions = []
+ no_step = 0
for folder in chosen[:CONCENTRATION_MAX_ACTIONS]:
n = len(shas_per_folder[folder])
- share = round(100 * n / total)
members = sorted(
fixed_files[folder], key=lambda p: -production[p].fix_commits_90d
)
includes = tuple(
p for p in members if is_fragile(production[p], ctx) and p not in named
)
+ first = _first_step(includes, production)
+ if first is None:
+ no_step += 1
+ continue
actions.append(
- Action(
- rule=rule,
- tier="plan",
- horizons=("quarter",),
- severity="high",
- title=(
- f"Stabilise {code(folder + '/')}: {share}% of the bug fixes land in "
- f"its {plural(files_per_folder[folder], 'file')}"
- ),
- impact=(
- f"{n} of the {total} bug-fix commits in the last 90 days touched "
- f"this folder, which holds {files_per_folder[folder] / n_prod:.1%} "
- "of the production files."
- ),
- why=(
- WhyFact("share of bug-fix commits", f"{share}%"),
- WhyFact("files with repeated fixes", str(len(members))),
- WhyFact("most fixed", posixpath.basename(members[0])),
- ),
- target_kind="folder",
- target_path=folder,
- surface="findings",
- effort="L",
- confidence="medium",
- done_when="Its share of bug-fix commits falls over the next 90 days.",
- weight=float(n),
- evidence_total=len(members),
+ _folder_action(
+ folder,
+ first=first,
+ fixes=(n, total),
+ files=(files_per_folder[folder], n_prod),
+ members=[(p, production[p]) for p in members],
includes=includes,
- fingerprint=fingerprint(share // 5),
- details=tuple(
- ActionDetail(
- path=p,
- reason=(
- f"{production[p].fix_commits_90d} bug-fix commits, "
- f"{production[p].commits_90d} commits in 90 days"
- ),
- )
- for p in members
- ),
- commands=(
- ActionCommand.call(
- "Bug-fix history and co-change partners for the most fixed files",
- "get_risk",
- {"targets": members[:5]},
- cli="repowise risk " + " ".join(f"-t {p}" for p in members[:5]),
- ),
- ActionCommand.call(
- "Why the folder is shaped this way",
- "get_why",
- {"targets": [f"{folder}/"]},
- cli=f"repowise why {folder}/",
- ),
- ),
)
)
- return RuleOutcome(rule, "evaluated", "", tuple(actions))
+ reason = (
+ f"{plural(no_step, 'folder')} left out: no file in it names a first step."
+ if no_step
+ else ""
+ )
+ return RuleOutcome(rule, "evaluated", reason, tuple(actions))
+
+
+def _folder_action(
+ folder: str,
+ *,
+ first: str,
+ fixes: tuple[int, int],
+ files: tuple[int, int],
+ members: list[tuple[str, FileFacts]],
+ includes: tuple[str, ...],
+) -> Action:
+ """The folder's action: ``fixes`` is (the folder's bug-fix commits, the
+ repository's), ``files`` (its production files, the repository's)."""
+ n, total = fixes
+ share = round(100 * n / total)
+ paths = [p for p, _f in members]
+ return Action(
+ rule="fix_concentration",
+ tier="plan",
+ horizons=("quarter",),
+ severity="high",
+ title=f"Stabilise {code(folder + '/')}: first, {first}",
+ impact=(
+ f"{n} of the {total} bug-fix commits in the last 90 days ({share}%) "
+ f"touched this folder's {plural(files[0], 'file')}, "
+ f"{files[0] / files[1]:.1%} of the production files."
+ ),
+ why=(
+ WhyFact("share of bug-fix commits", f"{share}%"),
+ WhyFact("files with repeated fixes", str(len(members))),
+ WhyFact("most fixed", posixpath.basename(paths[0])),
+ ),
+ target_kind="folder",
+ target_path=folder,
+ surface="findings",
+ effort="L",
+ confidence="medium",
+ done_when="Its share of bug-fix commits falls over the next 90 days.",
+ weight=float(n),
+ evidence_total=len(members),
+ includes=includes,
+ fingerprint=fingerprint(share // 5),
+ details=tuple(
+ ActionDetail(
+ path=p,
+ reason=f"{f.fix_commits_90d} bug-fix commits, {f.commits_90d} commits in 90 days",
+ )
+ for p, f in members
+ ),
+ commands=(
+ ActionCommand.call(
+ "Bug-fix history and co-change partners for the most fixed files",
+ "get_risk",
+ {"targets": paths[:5]},
+ cli="repowise risk " + " ".join(f"-t {p}" for p in paths[:5]),
+ ),
+ ActionCommand.call(
+ "Why the folder is shaped this way",
+ "get_why",
+ {"targets": [f"{folder}/"]},
+ cli=f"repowise why {folder}/",
+ ),
+ ),
+ )
+
+
+def _first_step(includes: tuple[str, ...], production: dict[str, FileFacts]) -> str | None:
+ """The first step of the most fixed file in ``includes`` that has one, as
+ a clause: ``simplify `run` in `a.py```."""
+ for path in includes:
+ step = _fragile_step(production[path])
+ if step is not None:
+ title = step[0].split(": ", 1)[0]
+ return title[0].lower() + title[1:]
+ return None
def _ancestors(path: str) -> list[str]:
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
index 9f571d640..cc88816c6 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
@@ -165,6 +165,15 @@ class BiomarkerResult:
deduction: float | None = None
+def shape_details(fn: FunctionComplexity) -> dict[str, Any]:
+ """The shape facts every function-size marker stores beside its numbers:
+ the dispatch share always, the terminal share only when there is one."""
+ out: dict[str, Any] = {"dispatch_share": fn.dispatch_share}
+ if fn.terminal_share:
+ out["terminal_share"] = fn.terminal_share
+ return out
+
+
class Biomarker(Protocol):
"""Detector contract. Each concrete biomarker is a stateless object."""
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py
index bc416e539..53587e32f 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py
@@ -29,7 +29,7 @@ from __future__ import annotations
from ..complexity.dispatch import judged_ccn
from ..models import Severity
-from .base import BiomarkerResult, FileContext
+from .base import BiomarkerResult, FileContext, shape_details
class BrainMethodDetector:
@@ -87,7 +87,7 @@ class BrainMethodDetector:
"max_nesting": fn.max_nesting,
"dependents_count": ctx.dependents_count,
"centrality_floor": floor,
- "dispatch_share": fn.dispatch_share,
+ **shape_details(fn),
},
reason=(
f"Brain Method: {fn.name} is {fn.nloc} lines, CCN {fn.ccn}, "
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
index 05253edb3..8d0946d7b 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
@@ -9,7 +9,7 @@ from __future__ import annotations
from ..complexity.dispatch import judged_ccn
from ..models import Severity
-from .base import BiomarkerResult, FileContext
+from .base import BiomarkerResult, FileContext, shape_details
class ComplexMethodDetector:
@@ -42,7 +42,7 @@ class ComplexMethodDetector:
"ccn": fn.ccn,
"cognitive": fn.cognitive,
"nloc": fn.nloc,
- "dispatch_share": fn.dispatch_share,
+ **shape_details(fn),
},
reason=f"{fn.name} has cyclomatic complexity {fn.ccn}",
)
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py
index 9f85ccf02..f1ad86607 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py
@@ -13,7 +13,7 @@ they don't double-count.
from __future__ import annotations
from ..models import Severity
-from .base import BiomarkerResult, FileContext
+from .base import BiomarkerResult, FileContext, shape_details
class LargeMethodDetector:
@@ -64,7 +64,7 @@ class LargeMethodDetector:
details={
"nloc": fn.nloc,
"ccn": fn.ccn,
- "dispatch_share": fn.dispatch_share,
+ **shape_details(fn),
},
reason=f"{fn.name} is {fn.nloc} lines long",
)
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py b/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py
index a28af8506..e8826c0b4 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py
@@ -8,7 +8,7 @@ from __future__ import annotations
from ..complexity.dispatch import judged_nesting
from ..models import Severity
-from .base import BiomarkerResult, FileContext
+from .base import BiomarkerResult, FileContext, shape_details
class NestedComplexityDetector:
@@ -41,7 +41,7 @@ class NestedComplexityDetector:
"max_nesting": fn.max_nesting,
"ccn": fn.ccn,
"cognitive": fn.cognitive,
- "dispatch_share": fn.dispatch_share,
+ **shape_details(fn),
},
reason=f"{fn.name} nests {fn.max_nesting} levels deep",
)
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/assertions.py b/packages/core/src/repowise/core/analysis/health/complexity/assertions.py
index 49085c90a..260af465c 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/assertions.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/assertions.py
@@ -31,11 +31,12 @@ design (``asserts/lexicon.py`` carries the vocabulary and the evidence):
``called_names`` rides along on the same traversal. Alone among these it is
collected **through** nested function bodies, because nothing else ever
-collects them.
+collects them. ``terminal_share`` (``terminal.py``) counts the same calls.
"""
from __future__ import annotations
+from dataclasses import dataclass
from typing import TYPE_CHECKING
from ..asserts.lexicon import NARROW_PREFIXES, STUB_EXCEPTIONS, AssertDialect
@@ -46,10 +47,19 @@ from .ast_utils import (
_receiver_method_verdict,
)
from .languages import LanguageNodeMap
+from .terminal import is_terminal_call, terminal_share
if TYPE_CHECKING:
from tree_sitter import Node
+@dataclass(slots=True)
+class _CallTally:
+ """Calls read in one body, and those on the terminal."""
+
+ calls: int = 0
+ terminal: int = 0
+
+
_EXPRESSION_STATEMENT = "expression_statement"
_AWAIT_WRAPPER_KINDS = ("await_expression", "await", "parenthesized_expression")
@@ -343,8 +353,8 @@ def _is_oracle_raise(node: Node) -> bool:
def _collect_assertion_facts(
body_node: Node, lmap: LanguageNodeMap, dialect: AssertDialect | None = None
-) -> tuple[list[tuple[int, int, int]], int, int, int, frozenset[str], frozenset[str]]:
- """``(blocks, total, verifications, raises, called, bare)`` for one body.
+) -> tuple[list[tuple[int, int, int]], int, int, int, frozenset[str], frozenset[str], float]:
+ """``(blocks, total, verifications, raises, called, bare, terminal)`` for one body.
*blocks* are runs of ≥2 consecutive **narrow-tier** assertion statements,
each recorded as ``(start_line, end_line, count)``. Runs are found per
@@ -392,17 +402,30 @@ def _collect_assertion_facts(
function body twice. It counts nothing and so cannot move a calibrated
marker. Empty under the early return above, which is fine only because the
one reader ships no language that takes it.
+
+ *terminal* is :func:`terminal.terminal_share` over the same calls *called*
+ reads, nested bodies included.
"""
if not lmap.assert_kinds and not lmap.assert_call_kinds:
- return [], 0, 0, 0, frozenset(), frozenset()
+ return [], 0, 0, 0, frozenset(), frozenset(), 0.0
blocks: list[tuple[int, int, int]] = []
total = 0
verifications = 0
raises = 0
called: set[str] = set()
bare: set[str] = set()
+ tally = _CallTally()
call_kinds = lmap.call_kinds or lmap.assert_call_kinds
+ def _record_call(node: Node) -> None:
+ names = _callee_names(node)
+ if names is not None:
+ called.add(names[0])
+ if not names[1]:
+ bare.add(names[0])
+ tally.calls += 1
+ tally.terminal += is_terminal_call(names[0], names[1])
+
def _scan_siblings(parent: Node, *, count_total: bool) -> None:
nonlocal total, verifications
run_start = 0
@@ -452,11 +475,7 @@ def _collect_assertion_facts(
if node.type in lmap.raise_kinds and not under_lambda and _is_oracle_raise(node):
raises += 1
if node.type in call_kinds:
- names = _callee_names(node)
- if names is not None:
- called.add(names[0])
- if not names[1]:
- bare.add(names[0])
+ _record_call(node)
for child in node.children:
child_under_lambda = under_lambda or child.type in lmap.lambda_kinds
if child.type in lmap.function_kinds:
@@ -470,11 +489,7 @@ def _collect_assertion_facts(
def _visit_names_only(node: Node) -> None:
if node.type in call_kinds:
- names = _callee_names(node)
- if names is not None:
- called.add(names[0])
- if not names[1]:
- bare.add(names[0])
+ _record_call(node)
for child in node.children:
_visit_names_only(child)
@@ -492,4 +507,12 @@ def _collect_assertion_facts(
verifications += 1
elif tier != _NOT_ASSERTION:
total += 1
- return blocks, total, verifications, raises, frozenset(called), frozenset(bare)
+ return (
+ blocks,
+ total,
+ verifications,
+ raises,
+ frozenset(called),
+ frozenset(bare),
+ terminal_share(tally.terminal, tally.calls),
+ )
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/models.py b/packages/core/src/repowise/core/analysis/health/complexity/models.py
index b0da16b3c..e9873a38d 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/models.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/models.py
@@ -119,6 +119,9 @@ class FunctionComplexity:
# CCN points inside that dispatch's heaviest arm, its own case point not
# counted: a switch of one-line cases has 0.
dispatch_arm: int = 0
+ # Calls on the terminal (print, prompt, console, stdout) over all calls in
+ # the body, nested bodies included, to two decimals. ``complexity/terminal.py``.
+ terminal_share: float = 0.0
# True when the declaration is marked deprecated or the body's top level
# issues a deprecation warning. ``complexity/deprecation.py``.
deprecated: bool = False
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/terminal.py b/packages/core/src/repowise/core/analysis/health/complexity/terminal.py
new file mode 100644
index 000000000..80817316e
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/complexity/terminal.py
@@ -0,0 +1,65 @@
+"""How much of a function's work is talking to a terminal.
+
+A status report, a doctor checklist or a setup wizard is long and branchy by
+construction: each check prints a line, each step prompts. Its CCN counts
+``if configured: print(...) else: print(...)`` pairs, which split into helpers
+without making anything safer. ``terminal_share`` lets a reader tell that shape
+apart from a function whose branches decide what the program does.
+
+The share is the calls in the function (nested bodies included) that write to
+or read from a terminal, over all its calls, read by the callee's name: the
+print family in any language, a ``print_*`` / ``prompt_*`` / ``confirm_*``
+helper, ``console.log`` and its siblings, and a write to stdout or stderr. A
+function with fewer than :data:`MIN_CALLS` calls has no share.
+"""
+
+from __future__ import annotations
+
+#: From this share of its calls on the terminal, a function is a print or
+#: prompt flow. Chosen in the gap between the status and setup commands
+#: (0.27 to 0.50) and the largest share of a function that decides program
+#: behaviour (0.15, a CLI init command) in three repositories' Fix first lists.
+TERMINAL_SHARE = 0.25
+#: Fewer calls than this say nothing about what a function is for.
+MIN_CALLS = 4
+
+_PLAIN = frozenset(
+ {
+ "print",
+ "println",
+ "printf",
+ "eprint",
+ "eprintln",
+ "puts",
+ "echo",
+ "secho",
+ "pprint",
+ "input",
+ "getpass",
+ "prompt",
+ "confirm",
+ }
+)
+# Prefixes with their separator: ``printer_for`` and ``echo_server`` are not output.
+_PREFIXES = ("print_", "prompt_", "confirm_")
+_CONSOLE_METHODS = frozenset({"log", "info", "warn", "error", "table", "debug"})
+_STREAMS = frozenset({"stdout", "stderr"})
+
+
+def is_terminal_call(name: str, roots: set[str]) -> bool:
+ """Whether a call named *name* (lowercased) on receiver path *roots*
+ writes to or reads from a terminal."""
+ bare = name.lstrip("_")
+ if bare in _PLAIN or bare.startswith(_PREFIXES):
+ return True
+ if "console" in roots and bare in _CONSOLE_METHODS:
+ return True
+ return bare == "write" and not _STREAMS.isdisjoint(roots)
+
+
+def terminal_share(terminal: int, calls: int) -> float:
+ """*terminal* calls over *calls*, to two decimals; 0.0 under :data:`MIN_CALLS`."""
+ return round(terminal / calls, 2) if calls >= MIN_CALLS else 0.0
+
+
+__all__ = ["MIN_CALLS", "TERMINAL_SHARE", "is_terminal_call", "terminal_share"]
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/walker.py b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
index 2a03e5614..b8b732d6c 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -30,6 +30,7 @@ The whole-file passes share one descent of the tree (``file_scan``):
- ``assertions``: assertion blocks + per-function assertion totals
- ``test_case``: whether a walked function is a test case
- ``dispatch``: how much of the CCN is one dispatch on one value
+- ``terminal``: how much of the function prints or prompts
- ``deprecation``: whether a function is marked deprecated
- ``gating``: whether a constant-false flag switches a function off
- ``mock_walk``: per-function mock-setup counting (test-quality)
@@ -190,6 +191,7 @@ def walk_file(
raises,
called,
bare_called,
+ terminal,
) = _collect_assertion_facts(body, lmap, asserts)
name = _find_function_entry_name(fn_node, lmap)
typed, scalar = typed_param_counts(_parameter_list(fn_node), lmap)
@@ -219,6 +221,7 @@ def walk_file(
bare_called_names=bare_called,
dispatch_share=dispatch_share(dispatch.points, ccn),
dispatch_arm=dispatch.arm,
+ terminal_share=terminal,
deprecated=is_deprecated(fn_node, body, name, lmap, source),
gated_off=body is not fn_node and is_gated_off(body, flags),
deepest_block=(deepest[0], deepest[1]) if deepest else None,
diff --git a/packages/core/src/repowise/core/analysis/health/finding_identity.py b/packages/core/src/repowise/core/analysis/health/finding_identity.py
index 8de0f9a2f..77359b302 100644
--- a/packages/core/src/repowise/core/analysis/health/finding_identity.py
+++ b/packages/core/src/repowise/core/analysis/health/finding_identity.py
@@ -78,6 +78,7 @@ _DERIVED_DETAIL_KEYS = frozenset(
"execution_role",
"role_owner",
"dispatch_share",
+ "terminal_share",
"deprecated",
"gated_off",
"loop_line",
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 4deaec3ae..4fe9cf4ec 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,6 +57,8 @@ from dataclasses import dataclass
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
@@ -77,6 +79,8 @@ from repowise.core.analysis.health.queue.eligibility import (
)
from repowise.core.analysis.health.queue.order import LEVEL_RANK, order
from repowise.core.analysis.health.queue.value import (
+ MIN_CHURN_COMMITS,
+ function_reach,
perf_confidence,
perf_ready,
perf_value,
@@ -98,6 +102,7 @@ from repowise.core.analysis.health.worth import (
low_priority,
magnitude,
measure,
+ measured_nloc,
worth_size,
)
from repowise.core.analysis.next_call import ActionCommand
@@ -166,6 +171,11 @@ class _Unit:
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 _open(row: Any) -> bool:
return (field(row, "status") or "open") == "open"
@@ -276,6 +286,17 @@ class _Files:
)
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."""
@@ -302,7 +323,32 @@ class _Files:
return (self.dependents(path) or 0) >= self.deps_cut
def churning(self, path: str) -> bool:
- return self.commits(path) >= self.churn_cut
+ return self.commits(path) >= max(self.churn_cut, MIN_CHURN_COMMITS)
+
+ 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."""
@@ -490,6 +536,9 @@ class _ShapeRank:
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:
@@ -509,7 +558,7 @@ class _ShapeRank:
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.churning),
+ *_reach_facts(self.dependents, self.central, self.churning, self.credited),
FixRankFact("duplicate inside", "yes" if self.cloned else "no"),
]
@@ -519,18 +568,24 @@ def _finish_shaped(rank: _ShapeRank, **unit: Any) -> _Unit:
return _finish(
value=rank.value,
cold_value=rank.cold_value,
- worth=worth(removed(rank.ccn_removed, rank.gain), rank.dependents, rank.churning),
+ worth=worth(removed(rank.ccn_removed, rank.gain), rank.credited, rank.churning),
low=rank.low,
rank_inputs=rank.facts,
**unit,
)
-def _reach_facts(deps: int | None, central: bool, churning: bool) -> list[FixRankFact]:
+def _reach_facts(
+ deps: int | None, central: bool, churning: bool, credited: int | None
+) -> list[FixRankFact]:
"""What reach and history add: importers lift the band when central,
- churn only orders inside it."""
+ churn only orders inside it. 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 ''}"),
+ FixRankFact(
+ "files that import it", f"{deps or 0}{' (top fifth)' if central else ''}{share}"
+ ),
FixRankFact("changes often", "yes" if churning else "no"),
]
@@ -798,15 +853,19 @@ class _RefactorPlan:
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,
- files.central(path),
+ central,
files.churning(path),
- cloned=lead_type == "extract_method" and files.cloned(path, shape),
- low=low_priority(marker, shape, function_size=lead_type == "extract_method"),
+ cloned=function_size and files.cloned(path, shape),
+ low=low_priority(marker, shape, function_size=function_size),
gain=gain,
ccn_removed=sum(_extraction_worth(plans.get(s.get("plan_id")))[0] for s in steps),
- dependents=files.dependents(path) if deps is None else deps,
+ dependents=deps,
+ credited=credited,
)
return cls(
row,
@@ -1246,16 +1305,20 @@ 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,
- files.central(path),
+ central,
files.churning(path),
- cloned=marker in SIZE_MARKERS and files.cloned(path, shape),
+ 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 marker in SIZE_MARKERS else 0,
- dependents=files.dependents(path),
+ ccn_removed=shape.get("ccn", 0) if sized else 0,
+ dependents=deps,
+ credited=credited,
)
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/model.py b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
index c9c6ef14b..7054ba2dd 100644
--- a/packages/core/src/repowise/core/analysis/health/fix_first/model.py
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
@@ -43,6 +43,8 @@ FIX_FACT_BASES: tuple[str, ...] = get_args(FixFactBasis)
# ``expected`` and ``no_strategy`` come from the performance ladder; ``gated_off``
# also keeps out any other unit in a function a constant-false flag switches
# off. ``unreachable``: an open dead-code finding covers the target.
+# ``terminal_flow``: a print or prompt flow; ``moderate_quiet``: a function
+# under the large-size bar with no churn or bug-fix history.
FixExclusion = Literal[
"test",
"tooling",
@@ -64,6 +66,8 @@ FixExclusion = Literal[
"no_concrete_step",
"low_value_kind",
"kind_unaudited",
+ "terminal_flow",
+ "moderate_quiet",
]
FIX_EXCLUSIONS: tuple[str, ...] = get_args(FixExclusion)
diff --git a/packages/core/src/repowise/core/analysis/health/queue/eligibility.py b/packages/core/src/repowise/core/analysis/health/queue/eligibility.py
index 0088eecaf..10ed42a0b 100644
--- a/packages/core/src/repowise/core/analysis/health/queue/eligibility.py
+++ b/packages/core/src/repowise/core/analysis/health/queue/eligibility.py
@@ -30,8 +30,11 @@ from ..worth import (
dispatch_shaped,
dormant,
execution_role,
+ large_function,
lead_reason,
+ measured_nloc,
perf_facets,
+ terminal_shaped,
)
Reason = Literal[
@@ -58,6 +61,8 @@ Reason = Literal[
"unmeasured_cost",
"cold_role",
"background_unproven",
+ "terminal_flow",
+ "moderate_quiet",
]
"""Why a unit is out of a default queue. Each surface counts the subset its
ladders can produce (``fix_first.model.FIX_EXCLUSIONS``,
@@ -270,14 +275,14 @@ class UnitFacts(Protocol):
def cloned(self, path: str, shape: Mapping[str, int]) -> bool: ...
+ def evidence(self, path: str, symbol: str | None) -> bool | None: ...
+
def small(shape: Mapping[str, int]) -> bool:
"""Under both size floors. A function whose size findings carry no line
count is measured by its span, which bounds its code lines from above; one
with neither is not judged small."""
- nloc = shape.get("nloc")
- if not nloc and shape.get("start") and shape.get("end"):
- nloc = shape["end"] - shape["start"] + 1
+ nloc = measured_nloc(shape)
if not nloc:
return False
return nloc < SMALL_NLOC and shape.get("ccn", 0) < SMALL_CCN
@@ -292,6 +297,10 @@ def unit_verdict(
way out, and a dormant one does not run. A complexity unit on a function
that is mostly one dispatch on one value is usually fine as it is, unless
a duplicate also sits in it; one on a small function is not worth an item.
+ A print or prompt flow branches on what to show, so splitting it buys
+ little. A function under :func:`worth.large_function` in a file whose
+ history is known leads only on evidence that it costs something: it
+ changes often or fixes land there. Unknown history keeps it in.
"""
if facts.unreachable(path, symbol, line):
return Verdict("unreachable")
@@ -306,9 +315,23 @@ def unit_verdict(
return Verdict("inherent_dispatch")
if small(shape):
return Verdict("small_function")
+ if terminal_shaped(shape):
+ return Verdict("terminal_flow")
+ if (
+ _measured(shape)
+ and not large_function(shape)
+ and facts.evidence(path, symbol) is False
+ ):
+ return Verdict("moderate_quiet")
return ELIGIBLE
+def _measured(shape: Mapping[str, int]) -> bool:
+ """Whether any size was measured: with none, there are no grounds to call
+ the function moderate."""
+ return bool(shape.get("ccn") or measured_nloc(shape))
+
+
def refactor_verdict(
gain: float,
steps: list[Mapping[str, Any]],
diff --git a/packages/core/src/repowise/core/analysis/health/queue/value.py b/packages/core/src/repowise/core/analysis/health/queue/value.py
index d6f991cd9..e1070179f 100644
--- a/packages/core/src/repowise/core/analysis/health/queue/value.py
+++ b/packages/core/src/repowise/core/analysis/health/queue/value.py
@@ -10,7 +10,7 @@ only re-orders units there.
from __future__ import annotations
from collections.abc import Mapping
-from math import log2
+from math import ceil, log2
from typing import Any
from ...execution_roles import COLD_ROLES, LEADING_ROLES
@@ -35,6 +35,9 @@ GAIN_CCN = SIZE_CCN[0]
PERF_CCN = SIZE_CCN[1]
#: On a file in the top fifth by churn. History re-orders inside a band only.
CHURN_WEIGHT = 1.25
+#: One change in 90 days is not changing often. Where the top fifth starts
+#: below this (a shallow clone, a young repository), history tells nothing.
+MIN_CHURN_COMMITS = 2
def gain_value(gain: float, central: bool) -> int:
@@ -66,6 +69,22 @@ def reach(dependents: int | None) -> float:
return 1 + log2(1 + max(dependents or 0, 0))
+#: A function under this share of its file's code lines gets that share of
+#: the file's importers, not all of them: in a file that holds many modules'
+#: worth of code, the importers come for the rest. Chosen after seeing the
+#: dogfood lists (no own-repo function in them is under 8% of its file).
+HUB_SHARE = 0.05
+
+
+def function_reach(dependents: int | None, function_nloc: int, file_nloc: int | None) -> int | None:
+ """The importers a function is credited with: its file's, or, under
+ :data:`HUB_SHARE` of the file, that share of them, rounded up."""
+ if not dependents or not function_nloc or not file_nloc:
+ return dependents
+ share = function_nloc / file_nloc
+ return dependents if share >= HUB_SHARE else ceil(dependents * share)
+
+
def worth(removed_ccn: float, dependents: int | None, churning: bool) -> float:
"""The order inside a value band: complexity removed times :func:`reach`,
:data:`CHURN_WEIGHT` more on a file that changes often. Unbounded on
@@ -143,9 +162,12 @@ __all__ = [
"CHURN_WEIGHT",
"GAIN_CCN",
"GAIN_CUTS",
+ "HUB_SHARE",
+ "MIN_CHURN_COMMITS",
"PERF_CCN",
"SIZE_SEVERE",
"VALUE_MAX",
+ "function_reach",
"gain_value",
"perf_confidence",
"perf_ready",
diff --git a/packages/core/src/repowise/core/analysis/health/worth.py b/packages/core/src/repowise/core/analysis/health/worth.py
index a64a18027..cad621b2c 100644
--- a/packages/core/src/repowise/core/analysis/health/worth.py
+++ b/packages/core/src/repowise/core/analysis/health/worth.py
@@ -17,6 +17,7 @@ from collections.abc import Iterable, Mapping, Sequence
from typing import Any, Literal
from .complexity.dispatch import DISPATCH_SHARE
+from .complexity.terminal import TERMINAL_SHARE
from .rows import detail_map, field
#: Problem-size cut points. Each is a multiple of the detector's own bar: CCN
@@ -120,6 +121,7 @@ def measure(findings: Iterable[Any]) -> dict[str, int]:
``deprecated`` when any sits in a function marked deprecated,
``gated_off`` when any sits in a :func:`dormant` function,
``dispatch_pct`` is the largest stored dispatch share in percent,
+ ``terminal_pct`` the largest stored terminal share (``complexity/terminal.py``),
``start`` / ``end`` span the function as its size findings place it, and
``deep_start`` / ``deep_end`` are its deepest nested block's lines.
"""
@@ -136,9 +138,10 @@ def measure(findings: Iterable[Any]) -> dict[str, int]:
if isinstance(deepest, dict) and deepest.get("start") and "deep_start" not in shape:
shape["deep_start"] = int(deepest["start"])
shape["deep_end"] = int(deepest.get("end") or deepest["start"])
- share = details.get("dispatch_share")
- if isinstance(share, (int, float)):
- shape["dispatch_pct"] = max(shape.get("dispatch_pct", 0), round(share * 100))
+ for key, pct in (("dispatch_share", "dispatch_pct"), ("terminal_share", "terminal_pct")):
+ share = details.get(key)
+ if isinstance(share, (int, float)):
+ shape[pct] = max(shape.get(pct, 0), round(share * 100))
if field(f, "biomarker_type") in SIZE_MARKERS:
start, end = field(f, "line_start"), field(f, "line_end")
if start and end:
@@ -165,6 +168,27 @@ def dispatch_shaped(shape: Mapping[str, int]) -> bool:
return shape.get("dispatch_pct", 0) >= DISPATCH_SHARE * 100
+def terminal_shaped(shape: Mapping[str, int]) -> bool:
+ """The function is a print or prompt flow: a status report, a checklist,
+ a setup wizard, whose branches choose what to show."""
+ return shape.get("terminal_pct", 0) >= TERMINAL_SHARE * 100
+
+
+def measured_nloc(shape: Mapping[str, int]) -> int:
+ """The function's code lines; with none stored, its span, which bounds
+ them from above; 0 with neither."""
+ nloc = shape.get("nloc") or 0
+ if not nloc and shape.get("start") and shape.get("end"):
+ nloc = shape["end"] - shape["start"] + 1
+ return nloc
+
+
+def large_function(shape: Mapping[str, int]) -> bool:
+ """Big enough to lead on size alone: CCN 80 or 200 lines. Nesting does not
+ count here: a deep block in a short function is a small fix."""
+ return shape.get("ccn", 0) >= SIZE_CCN[2] or measured_nloc(shape) >= SIZE_NLOC[1]
+
+
#: Nesting this share of the CCN or more is one else-if or ternary chain,
#: each arm nested in the last: deep by count, flat to read.
CHAIN_SHARE = 0.8
@@ -178,10 +202,7 @@ def _chained(shape: Mapping[str, int]) -> bool:
def worth_size(shape: Mapping[str, int]) -> int:
""":func:`magnitude` with nesting under 8 counted only in a function past
the length bar: moderate depth in a short function is a small fix."""
- nloc = shape.get("nloc") or 0
- if not nloc and shape.get("start") and shape.get("end"):
- nloc = shape["end"] - shape["start"] + 1
- if nloc >= SIZE_NLOC[0] or shape.get("max_nesting", 0) >= SIZE_NESTING[2]:
+ if measured_nloc(shape) >= SIZE_NLOC[0] or shape.get("max_nesting", 0) >= SIZE_NESTING[2]:
return magnitude(shape)
return magnitude({**shape, "max_nesting": 0})
@@ -344,10 +365,13 @@ __all__ = [
"dormant",
"execution_role",
"finding_priorities",
+ "large_function",
"lead_reason",
"low_priority",
"magnitude",
"measure",
+ "measured_nloc",
"perf_facets",
+ "terminal_shaped",
"worth_size",
]
diff --git a/packages/types/src/fix-first.ts b/packages/types/src/fix-first.ts
index d590d536c..e23e7a800 100644
--- a/packages/types/src/fix-first.ts
+++ b/packages/types/src/fix-first.ts
@@ -45,7 +45,9 @@ export type FixExclusion =
| "small_function"
| "no_concrete_step"
| "low_value_kind"
- | "kind_unaudited";
+ | "kind_unaudited"
+ | "terminal_flow"
+ | "moderate_quiet";
/** `all` keeps test files, labelled in `context`. */
export type FixScope = "production" | "all";
diff --git a/packages/types/src/queue.ts b/packages/types/src/queue.ts
index 00bfaeeee..033f44c42 100644
--- a/packages/types/src/queue.ts
+++ b/packages/types/src/queue.ts
@@ -33,6 +33,8 @@ export type QueueReason =
| "unmeasured_cost"
| "cold_role"
| "background_unproven"
+ | "terminal_flow"
+ | "moderate_quiet"
| "not_judged"
| "covered_by_plan"
| "not_file_lead"
diff --git a/packages/ui/__tests__/health/fixtures/fix-first.ts b/packages/ui/__tests__/health/fixtures/fix-first.ts
index bd23b97fe..d1c9db983 100644
--- a/packages/ui/__tests__/health/fixtures/fix-first.ts
+++ b/packages/ui/__tests__/health/fixtures/fix-first.ts
@@ -627,7 +627,9 @@ export const FIX_FIRST_QUEUE: FixFirstQueue = {
"small_function": 0,
"no_concrete_step": 0,
"low_value_kind": 0,
- "kind_unaudited": 0
+ "kind_unaudited": 0,
+ "terminal_flow": 0,
+ "moderate_quiet": 0
},
"dormant": 0
},
diff --git a/packages/ui/src/health/fix-first/scope.ts b/packages/ui/src/health/fix-first/scope.ts
index c63398f3a..9eea160fe 100644
--- a/packages/ui/src/health/fix-first/scope.ts
+++ b/packages/ui/src/health/fix-first/scope.ts
@@ -46,11 +46,13 @@ export const EXCLUSION_LABEL: Record<FixExclusion, string> = {
gated_off: "switched off by a constant flag",
cold_path: "run once per deploy, boot or incident",
unreachable: "in dead code (delete it)",
- inherent_dispatch: "one long dispatch on a value",
+ inherent_dispatch: "long dispatch on a value",
small_function: "small functions",
no_concrete_step: "with no concrete first edit",
low_value_kind: "of a kind rarely worth doing",
kind_unaudited: "of a kind not yet audited for this list",
+ terminal_flow: "print and prompt flows",
+ moderate_quiet: "moderate functions that rarely change or break",
};
const EXCLUSION_ORDER: FixExclusion[] = [
@@ -74,6 +76,8 @@ const EXCLUSION_ORDER: FixExclusion[] = [
"no_concrete_step",
"low_value_kind",
"kind_unaudited",
+ "terminal_flow",
+ "moderate_quiet",
];
/**
diff --git a/packages/web/src/components/code-health/fix-first-section.test.tsx b/packages/web/src/components/code-health/fix-first-section.test.tsx
index a60d1185c..159bb90cc 100644
--- a/packages/web/src/components/code-health/fix-first-section.test.tsx
+++ b/packages/web/src/components/code-health/fix-first-section.test.tsx
@@ -78,6 +78,8 @@ function queue(items: FixItem[]): FixFirstQueue {
no_concrete_step: 0,
low_value_kind: 0,
kind_unaudited: 0,
+ terminal_flow: 0,
+ moderate_quiet: 0,
},
dormant: 0,
},
diff --git a/tests/unit/analysis/test_actions_rules.py b/tests/unit/analysis/test_actions_rules.py
index 2fab87eb4..9eff3f038 100644
--- a/tests/unit/analysis/test_actions_rules.py
+++ b/tests/unit/analysis/test_actions_rules.py
@@ -232,6 +232,29 @@ def test_concentration_picks_the_narrow_high_lift_folder() -> None:
assert set(a.includes) == {f"pkg/cli/update/a{i}.py" for i in range(4)}
+def test_a_folder_names_its_first_step() -> None:
+ (a,) = _run(code.fix_concentration, _concentration_facts()).actions
+ # Every file here is untested; the most fixed one comes first.
+ assert a.title == (
+ "Stabilise `pkg/cli/update/`: first, add tests around `pkg/cli/update/a0.py` "
+ "before its next change"
+ )
+ assert "10 of the 25 bug-fix commits" in a.impact
+
+
+def test_a_folder_with_no_first_step_is_left_out_and_counted() -> None:
+ facts = _concentration_facts()
+ # No coverage report and no test map: no file can name a step.
+ unknown = {p: replace(f, tests_reaching=None) for p, f in facts.files.items()}
+ out = _run(code.fix_concentration, replace(facts, files=unknown))
+ assert out.actions == ()
+ assert out.reason == "1 folder left out: no file in it names a first step."
+
+
+def test_a_folder_whose_files_fix_first_names_has_no_first_step() -> None:
+ assert code._first_step((), {}) is None
+
+
def test_engine_drops_fragile_rows_a_folder_absorbed() -> None:
facts = _concentration_facts()
# Sanity: on their own, the folder's files are fragile.
diff --git a/tests/unit/cli/test_refactoring_targets_stored.py b/tests/unit/cli/test_refactoring_targets_stored.py
index 24d20dc82..812824b60 100644
--- a/tests/unit/cli/test_refactoring_targets_stored.py
+++ b/tests/unit/cli/test_refactoring_targets_stored.py
@@ -49,8 +49,8 @@ def _finding(path: str, symbol: str) -> dict[str, Any]:
"function_name": symbol,
"line_start": 10,
"line_end": 30,
- # Past Fix first's size floor, so each opportunity is in the default scope.
- "details": {"ccn": 16},
+ # Large enough to lead with no history, so each opportunity is in the default scope.
+ "details": {"ccn": 85},
"health_impact": 3.0,
"reason": "seeded",
"dimension": "defect",
diff --git a/tests/unit/health/fix_first_rows.py b/tests/unit/health/fix_first_rows.py
index 9612510fb..2537d1f70 100644
--- a/tests/unit/health/fix_first_rows.py
+++ b/tests/unit/health/fix_first_rows.py
@@ -9,14 +9,15 @@ AT = datetime(2026, 9, 30, 12, 0)
METRICS = [
{"file_path": "src/core.py", "score": 4.0, "nloc": 300, "is_test": False,
"commit_count_90d": 12, "dependents": 9, "analyzed_commit": "abc", "updated_at": AT},
+ # Changes often: a moderate function leads only on churn or fix history.
{"file_path": "src/plain.py", "score": 7.0, "nloc": 80, "is_test": False,
- "commit_count_90d": 1, "dependents": 1, "analyzed_commit": "abc", "updated_at": AT},
+ "commit_count_90d": 12, "dependents": 1, "analyzed_commit": "abc", "updated_at": AT},
{"file_path": "src/hist.py", "score": 6.0, "nloc": 50, "is_test": False,
"commit_count_90d": 3, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},
{"file_path": "src/repo.py", "score": 8.0, "nloc": 90, "is_test": False,
"commit_count_90d": 2, "dependents": 2, "analyzed_commit": "abc", "updated_at": AT},
{"file_path": "tests/test_core.py", "score": 5.0, "nloc": 90, "is_test": True,
- "commit_count_90d": 4, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},
+ "commit_count_90d": 12, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},
{"file_path": "scripts/tool.py", "score": 5.0, "nloc": 90, "is_test": False,
"commit_count_90d": 1, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},
]
diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.py
index 258ae2157..a473fd7cb 100644
--- a/tests/unit/health/test_fix_first_build.py
+++ b/tests/unit/health/test_fix_first_build.py
@@ -61,6 +61,8 @@ def test_each_exclusion_is_counted_by_reason() -> None:
"no_concrete_step": 0,
"low_value_kind": 0,
"kind_unaudited": 0,
+ "terminal_flow": 0,
+ "moderate_quiet": 0,
}
assert queue.totals.dormant == 0
assert queue.totals.eligible == 3
diff --git a/tests/unit/health/test_fix_first_worth.py b/tests/unit/health/test_fix_first_worth.py
new file mode 100644
index 000000000..e3a359819
--- /dev/null
+++ b/tests/unit/health/test_fix_first_worth.py
@@ -0,0 +1,175 @@
+"""What Fix first leads with: print and prompt flows, moderate functions with no
+history, and functions credited with a hub file's importers.
+
+Each test builds the smallest rows that show the rule firing and the nearest
+case where it must not.
+"""
+
+from __future__ import annotations
+
+from repowise.core.analysis.health.complexity.terminal import is_terminal_call, terminal_share
+from repowise.core.analysis.health.complexity.walker import walk_file
+from repowise.core.analysis.health.fix_first import build_fix_first
+from repowise.core.analysis.health.queue.value import HUB_SHARE, function_reach
+from tests.unit.health.fix_first_rows import AT
+
+# Neither churning nor central unless a test says so.
+_CUTS = (10.0, 10.0)
+
+
+def _metric(path: str, *, commits: int = 1, dependents: int = 0, nloc: int = 900) -> dict:
+ return {"file_path": path, "score": 3.0, "nloc": nloc, "is_test": False,
+ "commit_count_90d": commits, "dependents": dependents,
+ "analyzed_commit": "abc", "updated_at": AT}
+
+
+def _size(path: str, function: str, *, line: int = 10, **details) -> dict:
+ return {"file_path": path, "biomarker_type": "complex_method", "severity": "high",
+ "function_name": function, "line_start": line, "line_end": line + details["nloc"],
+ "health_impact": 1.0, "reason": f"{function} is complex",
+ "public_id": f"finding_{path}_{function}", "dimension": "defect",
+ "details": {**details, "deepest_block": {"start": line + 5, "end": line + 9}}}
+
+
+def _history(path: str, marker: str, function: str | None = None) -> dict:
+ return {"file_path": path, "biomarker_type": marker, "severity": "medium",
+ "function_name": function, "health_impact": 0.5, "reason": marker,
+ "public_id": f"finding_{path}_{marker}_{function}", "dimension": "defect"}
+
+
+def _queue(metrics: list[dict], findings: list[dict]):
+ return build_fix_first(metrics=metrics, findings=findings, hot_cuts=_CUTS, limit=None)
+
+
+def _symbols(queue) -> set[str]:
+ return {i.target.symbol for i in queue.items}
+
+
+# --- print and prompt flows ------------------------------------------------------
+
+
+def test_terminal_calls_are_read_by_name_and_receiver() -> None:
+ assert is_terminal_call("print", set())
+ assert is_terminal_call("print_info", set())
+ assert is_terminal_call("_prompt_checklist", set())
+ assert is_terminal_call("log", {"console"})
+ assert is_terminal_call("write", {"sys", "stdout"})
+ assert not is_terminal_call("log", {"logger"})
+ assert not is_terminal_call("write", {"handle"})
+ assert not is_terminal_call("build_prompt", set())
+ for name in ("printer_for", "printable", "confirmed_order", "promptly", "echo_server_handle"):
+ assert not is_terminal_call(name, set()), name
+
+
+def test_a_function_with_few_calls_has_no_terminal_share() -> None:
+ assert terminal_share(2, 3) == 0.0
+ assert terminal_share(2, 4) == 0.5
+
+
+def test_the_walker_measures_a_status_command_and_not_a_resolver() -> None:
+ status = (
+ "def show_status(cfg):\n"
+ + "".join(
+ f" if cfg.get('k{i}'):\n print('k{i} on')\n else:\n"
+ f" print('k{i} off')\n"
+ for i in range(6)
+ )
+ + " return load(cfg)\n"
+ )
+ resolver = "def resolve(cfg):\n a = load(cfg)\n b = merge(a, cfg)\n return check(b)\n"
+ fns = {f.name: f for f in walk_file("s.py", "python", (status + resolver).encode()).functions}
+ # 12 prints of 19 calls (six `cfg.get` and one `load` are not terminal).
+ assert fns["show_status"].terminal_share == 0.63
+ assert fns["resolve"].terminal_share == 0.0
+
+
+def test_a_print_flow_is_counted_out_and_a_logic_function_beside_it_stays() -> None:
+ metrics = [_metric("cli/status.py", commits=40), _metric("core/run.py", commits=40)]
+ findings = [
+ _size("cli/status.py", "show_status", ccn=153, nloc=478, max_nesting=4,
+ terminal_share=0.35),
+ _size("core/run.py", "finalize", ccn=131, nloc=408, max_nesting=6, terminal_share=0.1),
+ ]
+ queue = _queue(metrics, findings)
+ assert _symbols(queue) == {"finalize"}
+ assert queue.totals.excluded["terminal_flow"] == 1
+
+
+# --- moderate functions need history ----------------------------------------------
+
+
+_MODERATE = {"ccn": 45, "nloc": 120, "max_nesting": 6}
+
+
+def test_a_moderate_function_in_a_known_quiet_file_is_counted_out() -> None:
+ queue = _queue([_metric("lib/parse.py")], [_size("lib/parse.py", "parse", **_MODERATE)])
+ assert queue.items == ()
+ assert queue.totals.excluded["moderate_quiet"] == 1
+
+
+def test_a_moderate_function_with_unknown_history_still_leads() -> None:
+ finding = _size("lib/parse.py", "parse", **_MODERATE)
+ # No commit count: no git, or a file git has not seen.
+ no_git = {**_metric("lib/parse.py"), "commit_count_90d": None}
+ assert _symbols(_queue([no_git], [finding])) == {"parse"}
+ # A shallow clone: every file changed once, so history tells files apart not at all.
+ metrics = [_metric("lib/parse.py", commits=1), _metric("lib/other.py", commits=1)]
+ shallow = build_fix_first(metrics=metrics, findings=[finding], limit=None)
+ assert _symbols(shallow) == {"parse"}
+ assert shallow.totals.excluded["moderate_quiet"] == 0
+
+
+def test_churn_bug_fixes_or_a_hotspot_on_the_function_let_it_lead() -> None:
+ finding = _size("lib/parse.py", "parse", **_MODERATE)
+ churning = _queue([_metric("lib/parse.py", commits=40)], [finding])
+ fixed = _queue([_metric("lib/parse.py")], [finding, _history("lib/parse.py", "prior_defect")])
+ hot = _queue([_metric("lib/parse.py")],
+ [finding, _history("lib/parse.py", "function_hotspot", "parse")])
+ assert all(_symbols(q) == {"parse"} for q in (churning, fixed, hot))
+
+
+def test_a_hotspot_on_another_function_is_no_evidence() -> None:
+ queue = _queue([_metric("lib/parse.py")],
+ [_size("lib/parse.py", "parse", **_MODERATE),
+ _history("lib/parse.py", "function_hotspot", "other")])
+ assert queue.totals.excluded["moderate_quiet"] == 1
+
+
+def test_a_large_function_leads_without_history() -> None:
+ long_ = _size("lib/a.py", "long_one", ccn=45, nloc=230, max_nesting=6)
+ branchy = _size("lib/b.py", "branchy", ccn=85, nloc=150, max_nesting=6)
+ queue = _queue([_metric("lib/a.py"), _metric("lib/b.py")], [long_, branchy])
+ assert _symbols(queue) == {"long_one", "branchy"}
+
+
+# --- a hub file's importers -------------------------------------------------------
+
+
+def test_function_reach_credits_a_small_share_of_a_hub_file() -> None:
+ assert function_reach(287, 265, 21080) == 4
+ assert function_reach(18, 423, 1405) == 18
+ assert function_reach(None, 265, 21080) is None
+ assert function_reach(80, 0, 9000) == 80
+ assert function_reach(100, int(HUB_SHARE * 1000), 1000) == 100
+
+
+def test_a_function_lost_in_a_hub_file_is_not_central() -> None:
+ finding = _size("gateway/run.py", "send_progress", ccn=75, nloc=265, max_nesting=5)
+ hub = _queue([_metric("gateway/run.py", commits=40, dependents=287, nloc=21080)], [finding])
+ focused = _queue([_metric("gateway/run.py", commits=40, dependents=287, nloc=1000)], [finding])
+ (lost,), (kept,) = hub.items, focused.items
+ assert (lost.value, kept.value) == (2, 3)
+ facts = {f.factor: f.value for f in lost.why_ranked}
+ assert facts["files that import it"] == "287, 4 counted for its share of the file"
+ assert {f.factor: f.value for f in kept.why_ranked}["files that import it"] == "287 (top fifth)"
+ # What the file is, the item still says.
+ assert "287" in lost.why
+
+
+def test_size_markers_store_a_terminal_share_only_when_there_is_one() -> None:
+ from repowise.core.analysis.health.biomarkers.base import shape_details
+
+ src = b"def a():\n print(1)\n run()\n go()\n print(2)\n\ndef b():\n run()\n"
+ fns = {f.name: f for f in walk_file("x.py", "python", src).functions}
+ assert shape_details(fns["a"]) == {"dispatch_share": 0.0, "terminal_share": 0.5}
+ assert shape_details(fns["b"]) == {"dispatch_share": 0.0}
diff --git a/tests/unit/health/test_queue_eligibility.py b/tests/unit/health/test_queue_eligibility.py
index 3bdc19dd1..c3967e8ba 100644
--- a/tests/unit/health/test_queue_eligibility.py
+++ b/tests/unit/health/test_queue_eligibility.py
@@ -24,6 +24,9 @@ class _Facts:
def cloned(self, path, shape):
return False
+ def evidence(self, path, symbol):
+ return True
+
def _cause(**over):
row = {
diff --git a/tests/unit/health/test_queue_value_order.py b/tests/unit/health/test_queue_value_order.py
index 432b06830..c596e1721 100644
--- a/tests/unit/health/test_queue_value_order.py
+++ b/tests/unit/health/test_queue_value_order.py
@@ -45,7 +45,8 @@ FINDINGS = [
# highest of the large functions, which is what used to rank it first.
_finding("cli/status.py", "show_status", 0.72, ccn=153, nloc=478, max_nesting=6),
_finding("gateway/config.py", "load_gateway_config", 0.52, ccn=151, nloc=341, max_nesting=6),
- # Past the bars by less: CCN 45 over 120 lines, in a file nothing imports.
+ # Past the bars by less: CCN 45 over 120 lines, in a file nothing imports
+ # and nobody changed. It leads only on churn or fix history, so it is out.
_finding("lib/parse.py", "parse_block", 1.6, ccn=45, nloc=120, max_nesting=6),
]
@@ -65,7 +66,6 @@ GOLDEN = [
("show_status", "4", "the wizard: band 4 on size, CCN 153 x reach of only 7 importers"),
("perf_req", "4", "request-run growing db loop: top band, worth a CCN 40 x 3 call sites"),
("perf_unknown", "2", "the same loop with no role evidence: band 2, worth 103"),
- ("parse_block", "2", "band 2 on size and gain; worth 45 (no importers) is below 103"),
]
@@ -90,6 +90,17 @@ def test_rank_order_golden() -> None:
assert got == [(symbol, band) for symbol, band, _why in GOLDEN]
+def test_a_moderate_function_with_no_history_is_counted_out() -> None:
+ queue = _queue()
+ assert "parse_block" not in {i.target.symbol for i in queue.items}
+ assert queue.totals.excluded["moderate_quiet"] == 1
+ churned = [{**m, "commit_count_90d": 40} if m["file_path"] == "lib/parse.py" else m
+ for m in METRICS]
+ again = build_fix_first(metrics=churned, findings=FINDINGS, performance=PERFORMANCE,
+ hot_cuts=_CUTS, limit=None)
+ assert "parse_block" in {i.target.symbol for i in again.items}
+
+
def test_the_giant_outranks_the_wizard_on_complexity_removed_times_reach() -> None:
by_symbol = {i.target.symbol: i for i in _queue().items}
giant, wizard = by_symbol["run_conversation"], by_symbol["show_status"]
diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.py
index ead131785..b6a1bf25f 100644
--- a/tests/unit/server/test_refactoring_opportunities.py
+++ b/tests/unit/server/test_refactoring_opportunities.py
@@ -71,8 +71,8 @@ def _finding(
"function_name": function_name,
"line_start": 10,
"line_end": 30,
- # Past Fix first's size floor, so the composed plan is a candidate.
- "details": {"ccn": 16},
+ # Large enough to lead with no history, so the composed plan is a candidate.
+ "details": {"ccn": 85},
"health_impact": impact,
"reason": "seeded",
"dimension": "defect",