Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(health): add deterministic Extract Helper refactoring detector (#587)
Raghav Chamadiyac9c27ac9f92f
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd.py b/packages/cli/src/repowise/cli/commands/health_cmd.pyindex 0e084d330..65ace4226 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd.py@@ -549,11 +549,19 @@ def _render_refactoring_targets(# Structured plans are ranked + displayed independently of the impact/effort# file table (a god class worth splitting may not top that churn-weighted- # list), highest recovered impact first.- ranked_plans = sorted(- (_suggestion_to_dict(s) for s in suggestions),- key=lambda p: -p.get("impact_delta", 0.0),- )[:limit]+ # list): highest recovered impact first, then — for clone dedup, where the+ # dry_violation deduction is near-uniform — the actively co-changed, larger+ # blocks; target_symbol last for a deterministic tie-break.+ def _plan_rank(p: dict) -> tuple:+ ev = p.get("evidence", {}) or {}+ return (+ -p.get("impact_delta", 0.0),+ -int(ev.get("co_change_count", 0)),+ -int(ev.get("duplicated_lines", 0)),+ p.get("target_symbol", ""),+ )++ ranked_plans = sorted((_suggestion_to_dict(s) for s in suggestions), key=_plan_rank)[:limit]if fmt == "json":click.echo(json.dumps({"targets": targets, "refactoring_plans": ranked_plans}, indent=2))@@ -567,6 +575,7 @@ def _render_refactoring_targets(f"— {t['primary_biomarker']}: {t['primary_reason']}")_render_extract_class_plans_md(ranked_plans)+ _render_extract_helper_plans_md(ranked_plans)returntable = Table(title=f"Refactoring targets ({len(targets)})")@@ -587,6 +596,7 @@ def _render_refactoring_targets()console.print(table)_render_extract_class_plans_console(ranked_plans)+ _render_extract_helper_plans_console(ranked_plans)def _render_extract_class_plans_console(plans: list[dict]) -> None:@@ -629,6 +639,46 @@ def _render_extract_class_plans_md(plans: list[dict]) -> None:click.echo(f" {i}. methods: {', '.join(g['methods'])} · fields: {fields}")+def _render_extract_helper_plans_console(plans: list[dict]) -> None:+ """Print the concrete Extract Helper (clone dedup) plans below the table."""+ eh_plans = [p for p in plans if p["refactoring_type"] == "extract_helper"]+ if not eh_plans:+ return+ console.print(f"\n[bold]Extract Helper plans ({len(eh_plans)})[/bold]")+ for p in eh_plans:+ ev = p["evidence"]+ occ = p["plan"].get("occurrences", [])+ site = p["plan"].get("suggested_site", {}) or {}+ where = site.get("module") or site.get("directory") or "a shared module"+ co = ev.get("co_change_count", 0)+ console.print(+ f"\n[cyan]{ev.get('duplicated_lines')} duplicated lines[/cyan] across "+ f"{len(occ)} sites → extract a helper near [bold]{where}[/bold] "+ f"[dim](recover ~{p['impact_delta']:.2f}, effort {p['effort_bucket']}, "+ f"{p['confidence']} confidence" + (f", co-changed {co}x" if co else "") + ")[/dim]"+ )+ for o in occ:+ console.print(f" [dim]-[/dim] {o['file']}:{o['line_start']}-{o['line_end']}")+++def _render_extract_helper_plans_md(plans: list[dict]) -> None:+ eh_plans = [p for p in plans if p["refactoring_type"] == "extract_helper"]+ if not eh_plans:+ return+ click.echo("\n## Extract Helper plans\n")+ for p in eh_plans:+ ev = p["evidence"]+ occ = p["plan"].get("occurrences", [])+ site = p["plan"].get("suggested_site", {}) or {}+ where = site.get("module") or site.get("directory") or "a shared module"+ click.echo(+ f"- **{ev.get('duplicated_lines')} duplicated lines** across "+ f"{len(occ)} sites — extract a helper near `{where}`:"+ )+ for o in occ:+ click.echo(f" - {o['file']}:{o['line_start']}-{o['line_end']}")++def _render_trend(repo_path: object, *, fmt: str) -> None:"""Print the last 10 health snapshots straight from SQLite history.diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex 5043e3a5d..0370c407c 100644--- a/packages/core/src/repowise/core/analysis/health/engine.py+++ b/packages/core/src/repowise/core/analysis/health/engine.py@@ -787,6 +787,8 @@ class HealthAnalyzer:classes=fcx.classes,findings=findings,dependents_count=dependents_count,+ clones=list(clones),+ module_map=self.module_map,)suggestions = detect_refactorings(rctx, disabled=disabled_refactorings or ())return metric, findings, suggestionsdiff --git a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.pyindex 248dbee4c..5ffc1e0c8 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py@@ -13,7 +13,10 @@ from __future__ import annotations# Importing the detector modules triggers their ``@register`` side effect.# Listed explicitly (and in a fixed order) so the registry is deterministic.-from . import extract_class # noqa: F401 (import-for-side-effect)+from . import (+ extract_class, # noqa: F401 (import-for-side-effect)+ extract_helper, # noqa: F401 (import-for-side-effect)+)from .models import (CONFIDENCE_LEVELS,RefactoringContext,diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.py b/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.pynew file mode 100644index 000000000..c860287ab--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.py@@ -0,0 +1,371 @@+"""Extract Helper detector — clone dedup as a shared helper (Phase 2).++When the same block of code is duplicated across two or more sites, the+fix is to extract it once into a shared helper. The duplication is not a+heuristic: it *is* the verified clone pairs the health pass already+computed (``duplication.detect_clones`` → ``ctx.clones``), so the+suggestion is deterministic and matches the ``dry_violation`` biomarker.++The detector runs in the existing per-file pass, but a clone block spans+files, so two safeguards keep one block from producing one nag per site:++- **Clone-set clustering.** A file's clone pairs are grouped by the block+ they touch (overlapping line ranges on this file's side), and each+ group's *occurrences* are the block's region here plus every partner's+ region. Because the duplication detector emits a clone bucket pairwise,+ the lexicographically-smallest member of a clone set pairs with every+ other member, so that one anchor file sees the whole set (A↔B, A↔C ⇒+ the set ``{A, B, C}`` is visible from ``A``).+- **Canonical anchor.** Each block is emitted only from the pass of its+ anchor file — the smallest occurrence path — so ``{A, B, C}`` yields one+ suggestion (from ``A``), never three.++Precision-first, the gate demands a block genuinely worth a helper:++- the shared span is at least ``_MIN_HELPER_LINES`` real lines (a helper,+ not a two-line idiom);+- after dropping test-file and generated occurrences (DB migrations,+ vendored bundles) the block still duplicates across ``>= 2`` sites — test+ fixtures and migration boilerplate duplicate constantly but a shared+ helper is the wrong fix for them;+- the recovered impact is read off the file's ``dry_violation`` finding+ when it overlaps the block, else ``0`` (same posture as Extract Class).++Confidence rides the co-change signal: a clone whose sites are actively+co-modified is real, maintained duplication (``high``); a dormant clone is+still worth extracting but ranks ``medium``.+"""++from __future__ import annotations++from typing import Any++from .models import RefactoringContext, RefactoringSuggestion+from .registry import RefactoringDetector, effort_bucket, register++# The biomarker this detector answers — the recovered impact is read off it.+_SOURCE_BIOMARKER = "dry_violation"++# Minimum shared-line span for a clone to be worth a helper. The clone+# pipeline already floors regions at 6 lines (``DEFAULT_MIN_LINES``); a+# helper is a real unit of behaviour, so we ask for a little more and reject+# the smallest window-sized matches that read as incidental similarity.+_MIN_HELPER_LINES = 8++# Co-change count at/above which duplication counts as actively maintained+# (mirrors ``dry_violation._ACTIVE_CO_CHANGE``) — the strong, high-confidence+# smell rather than a dormant clone.+_ACTIVE_CO_CHANGE = 3++# Slack (lines) for treating two clone regions on this file's side as the+# same block — matches the duplication merger's one-line window slack.+_REGION_SLACK = 1+++def _is_test_path(path: str) -> bool:+ """Conservative test-file check (mirrors the engine's ``_is_test_file``).++ Kept local so the detector stays self-contained — duplication among test+ fixtures is common and low value, so test occurrences are dropped before+ a suggestion is formed.+ """+ p = path.lower().replace("\\", "/")+ return (+ "/test/" in p+ or "/tests/" in p+ or "/__tests__/" in p+ or p.rsplit("/", 1)[-1].startswith("test_")+ or p.endswith("_test.py")+ or p.endswith("_test.go")+ or p.endswith(".test.ts")+ or p.endswith(".test.tsx")+ or p.endswith(".test.js")+ or p.endswith(".test.mts")+ or p.endswith(".test.cts")+ or p.endswith(".spec.ts")+ or p.endswith(".spec.js")+ or p.endswith(".spec.mts")+ or p.endswith(".spec.cts")+ )+++def _is_generated_path(path: str) -> bool:+ """Non-refactorable generated/append-only code (DB migrations, vendored+ bundles). Their boilerplate duplicates heavily but extracting a shared+ helper is the wrong advice — a migration must stay self-contained — so+ these occurrences are dropped like test ones (plan's "no generated-file+ noise" gate)."""+ p = path.lower().replace("\\", "/")+ return (+ "/migrations/versions/" in p+ or "/alembic/versions/" in p+ or "/migrations/" in p+ or "/node_modules/" in p+ or "/vendor/" in p+ or "/__generated__/" in p+ or p.endswith(".min.js")+ )+++def _is_skippable_occurrence(path: str) -> bool:+ return _is_test_path(path) or _is_generated_path(path)+++class _Block:+ """One duplicated code block as seen from the anchor file: the region on+ this file's side plus the geometry needed to gather every occurrence."""++ __slots__ = ("anchor_end", "anchor_start", "co_change", "occurrences", "token_count")++ def __init__(self, start: int, end: int) -> None:+ self.anchor_start = start+ self.anchor_end = end+ # (file, line_start, line_end) — de-duplicated, sorted at emit time.+ self.occurrences: set[tuple[str, int, int]] = set()+ self.token_count = 0+ self.co_change = 0++ def touches(self, start: int, end: int) -> bool:+ """Overlap (within slack) on the anchor side — same physical block."""+ return start <= self.anchor_end + _REGION_SLACK and end >= self.anchor_start - _REGION_SLACK++ def absorb(self, start: int, end: int, pair: Any, *, anchor: str) -> None:+ self.anchor_start = min(self.anchor_start, start)+ self.anchor_end = max(self.anchor_end, end)+ self.token_count = max(self.token_count, int(getattr(pair, "token_count", 0)))+ self.co_change = max(self.co_change, int(getattr(pair, "co_change_count", 0)))+ # The anchor-side region of this pair is always an occurrence; add it+ # plus the partner region(s). Intra-file pairs contribute both regions.+ self.occurrences.add((anchor, start, end))+ if pair.file_a == anchor and pair.file_b == anchor:+ self.occurrences.add((anchor, pair.b_start_line, pair.b_end_line))+ elif pair.file_a == anchor:+ self.occurrences.add((pair.file_b, pair.b_start_line, pair.b_end_line))+ else:+ self.occurrences.add((pair.file_a, pair.a_start_line, pair.a_end_line))+++@register+class ExtractHelperDetector(RefactoringDetector):+ name = "extract_helper"++ def detect(self, ctx: RefactoringContext) -> list[RefactoringSuggestion]:+ if not ctx.clones:+ return []++ blocks = self._cluster_blocks(ctx)+ if not blocks:+ return []++ impact_lookup = self._impact_for_dry_violation(ctx)+ out: list[RefactoringSuggestion] = []+ for block in blocks:+ suggestion = self._build_suggestion(ctx, block, impact_lookup)+ if suggestion is not None:+ out.append(suggestion)++ # Stable order: biggest recovery first, then — because dry_violation+ # deductions are near-uniform, so impact rarely separates clones — the+ # plan's "co_change x span" priority (actively co-modified, larger+ # blocks first), then target for a fully deterministic tie-break.+ out.sort(+ key=lambda s: (+ -s.impact_delta,+ -int(s.evidence.get("co_change_count", 0)),+ -int(s.evidence.get("duplicated_lines", 0)),+ s.target_symbol,+ )+ )+ return out++ def _cluster_blocks(self, ctx: RefactoringContext) -> list[_Block]:+ """Group this file's clone pairs into blocks by their anchor-side+ region. Pairs are processed in a deterministic order so block+ boundaries (and therefore the output) never depend on dict order."""+ anchor = ctx.file_path++ def _anchor_region(pair: Any) -> tuple[int, int]:+ # For an inter-file pair, the region on *this* file's side; for an+ # intra-file pair, the earlier of the two regions.+ if pair.file_a == anchor and pair.file_b == anchor:+ return min(+ (pair.a_start_line, pair.a_end_line),+ (pair.b_start_line, pair.b_end_line),+ )+ if pair.file_a == anchor:+ return pair.a_start_line, pair.a_end_line+ return pair.b_start_line, pair.b_end_line++ ordered = sorted(ctx.clones, key=lambda p: _anchor_region(p))+ blocks: list[_Block] = []+ for pair in ordered:+ start, end = _anchor_region(pair)+ target = next((b for b in blocks if b.touches(start, end)), None)+ if target is None:+ target = _Block(start, end)+ blocks.append(target)+ target.absorb(start, end, pair, anchor=anchor)+ return blocks++ def _build_suggestion(+ self,+ ctx: RefactoringContext,+ block: _Block,+ impact_lookup: list[tuple[int, int, float]],+ ) -> RefactoringSuggestion | None:+ # Drop test-file occurrences — duplication among fixtures is noise —+ # then coalesce the overlapping windows the clone detector emits for one+ # physical block into a single site per region (without merging, the+ # same import/parse block reads as "5 sites" when it is really one).+ kept = [o for o in block.occurrences if not _is_skippable_occurrence(o[0])]+ occurrences = _merge_ranges_per_file(kept)+ if len(occurrences) < 2:+ return None++ occ_files = sorted({o[0] for o in occurrences})+ # Canonical anchor: emit each block exactly once, from its smallest+ # occurrence path. (Also guarantees ``ctx.file_path`` is non-test.)+ if ctx.file_path != occ_files[0]:+ return None++ duplicated_lines = max(end - start + 1 for _f, start, end in occurrences)+ if duplicated_lines < _MIN_HELPER_LINES:+ return None++ # Anchor region = this file's merged region overlapping the block (its+ # largest, deterministically) so the headline line range is the real one.+ anchor_region = next(+ ((s, e) for f, s, e in occurrences if f == ctx.file_path),+ (block.anchor_start, block.anchor_end),+ )+ impact = self._impact_for_block(anchor_region, impact_lookup)+ is_intra = len(occ_files) == 1++ plan = {+ "occurrences": [{"file": f, "line_start": s, "line_end": e} for f, s, e in occurrences],+ "suggested_site": self._suggested_site(ctx, occ_files),+ "duplicated_lines": duplicated_lines,+ }+ evidence = {+ "occurrence_count": len(occurrences),+ "duplicated_lines": duplicated_lines,+ "token_count": block.token_count,+ "co_change_count": block.co_change,+ "is_intra_file": is_intra,+ }+ other_files = [f for f in occ_files if f != ctx.file_path]+ blast_radius = {+ "files": other_files,+ "file_count": len(other_files),+ "co_change_count": block.co_change,+ }+ basename = ctx.file_path.replace("\\", "/").rsplit("/", 1)[-1]+ return RefactoringSuggestion(+ refactoring_type=self.name,+ file_path=ctx.file_path,+ target_symbol=f"{basename}:{anchor_region[0]}-{anchor_region[1]}",+ line_start=anchor_region[0],+ line_end=anchor_region[1],+ plan=plan,+ evidence=evidence,+ impact_delta=round(float(impact), 3),+ effort_bucket=effort_bucket(duplicated_lines),+ blast_radius=blast_radius,+ confidence="high" if block.co_change >= _ACTIVE_CO_CHANGE else "medium",+ source_biomarker=_SOURCE_BIOMARKER,+ )++ def _suggested_site(+ self, ctx: RefactoringContext, occ_files: list[str]+ ) -> dict[str, str | None]:+ """Where the shared helper should live: the community centroid of the+ occurrences (the module most of them belong to), with the shared+ directory as a fallback when no community labels exist."""+ module = None+ if ctx.module_map:+ counts: dict[str, int] = {}+ for f in occ_files:+ mod = ctx.module_map.get(f)+ if mod:+ counts[mod] = counts.get(mod, 0) + 1+ if counts:+ # Centroid = most-shared module; ties broken lexicographically+ # so the site is deterministic.+ module = min(counts, key=lambda m: (-counts[m], m))+ return {"module": module, "directory": _common_directory(occ_files)}++ @staticmethod+ def _impact_for_dry_violation(ctx: RefactoringContext) -> list[tuple[int, int, float]]:+ """The file's ``dry_violation`` findings as (line_start, line_end,+ impact) so a block can claim the impact of the clone it overlaps."""+ out: list[tuple[int, int, float]] = []+ for f in ctx.findings:+ if getattr(f, "biomarker_type", "") != _SOURCE_BIOMARKER:+ continue+ start = getattr(f, "line_start", None)+ end = getattr(f, "line_end", None)+ impact = float(getattr(f, "health_impact", 0.0) or 0.0)+ if start is None or end is None:+ # No region — attribute to the whole file (matches any block).+ out.append((0, 1_000_000_000, impact))+ else:+ out.append((int(start), int(end), impact))+ return out++ @staticmethod+ def _impact_for_block(+ region: tuple[int, int], impact_lookup: list[tuple[int, int, float]]+ ) -> float:+ """Recovered impact for the block whose anchor region overlaps a+ ``dry_violation`` finding; 0 when none does (precision-first)."""+ start, end = region+ best = 0.0+ for f_start, f_end, impact in impact_lookup:+ if start <= f_end and end >= f_start and impact > best:+ best = impact+ return best+++def _merge_ranges_per_file(+ occurrences: list[tuple[str, int, int]],+) -> list[tuple[str, int, int]]:+ """Collapse overlapping/adjacent line ranges within each file into one+ region. The clone detector emits a block as several offset windows+ (8-35, 8-36, 9-36, 22-28 …); left unmerged those read as separate sites,+ so a single duplicated block looks far more spread out than it is.++ Returns the merged ``(file, start, end)`` tuples, sorted — so the output+ is deterministic regardless of the input order.+ """+ by_file: dict[str, list[tuple[int, int]]] = {}+ for f, start, end in occurrences:+ by_file.setdefault(f, []).append((start, end))+ out: list[tuple[str, int, int]] = []+ for f, ranges in by_file.items():+ cur_start, cur_end = None, None+ for start, end in sorted(ranges):+ if cur_start is None:+ cur_start, cur_end = start, end+ elif start <= cur_end + _REGION_SLACK:+ cur_end = max(cur_end, end)+ else:+ out.append((f, cur_start, cur_end))+ cur_start, cur_end = start, end+ if cur_start is not None:+ out.append((f, cur_start, cur_end))+ return sorted(out)+++def _common_directory(paths: list[str]) -> str | None:+ """Longest shared directory prefix of *paths* (POSIX), or ``None`` when+ they share no directory. Component-wise, never mid-segment."""+ seg_lists = [p.replace("\\", "/").split("/")[:-1] for p in paths]+ if not seg_lists or any(not segs for segs in seg_lists):+ return None+ common: list[str] = []+ for parts in zip(*seg_lists, strict=False):+ if len(set(parts)) == 1:+ common.append(parts[0])+ else:+ break+ return "/".join(common) or Nonediff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.pyindex 8b19679cd..aa11b743c 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/models.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/models.py@@ -18,6 +18,18 @@ type without touching this module. For Extract Class (Phase 1):"wmc": int}`` — the cohesion/size signals that justify the split.- ``blast_radius`` = ``{"dependents_count": int}`` — files importing theclass's file that may need to follow the split.++For Extract Helper (Phase 2):++- ``plan`` = ``{"occurrences": [{"file": str, "line_start": int,+ "line_end": int}, ...], "suggested_site": {"module": str | None,+ "directory": str | None}, "duplicated_lines": int}`` — every site of the+ duplicated block and where the shared helper should live.+- ``evidence`` = ``{"occurrence_count": int, "duplicated_lines": int,+ "token_count": int, "co_change_count": int, "is_intra_file": bool}`` — the+ size + activity signals that justify extracting a helper.+- ``blast_radius`` = ``{"files": [...], "file_count": int,+ "co_change_count": int}`` — the other files that must change in lockstep."""from __future__ import annotations@@ -53,6 +65,17 @@ class RefactoringContext:findings: list[Any] = field(default_factory=list)# Files importing this file (graph in-degree) — the blast-radius seed.dependents_count: int = 0+ # The file's clone pairs (``duplication.ClonePair`` records, typed ``Any``+ # for the same circular-import reason) — every pair touches this file.+ # Consumed by the Extract Helper detector. Empty when duplication is+ # disabled or the file has no clones.+ clones: list[Any] = field(default_factory=list)+ # Repo-wide file -> community/module label map (a shared reference, not a+ # per-file copy). The Extract Helper detector reads it to place the+ # extracted helper at the community centroid of the clone's occurrences.+ # Empty on small repos that produced no community labels — the detector+ # then falls back to a shared-directory site.+ module_map: dict[str, str] = field(default_factory=dict)@dataclassdiff --git a/tests/unit/health/test_refactoring_extract_helper.py b/tests/unit/health/test_refactoring_extract_helper.pynew file mode 100644index 000000000..5f3d59f7a--- /dev/null+++ b/tests/unit/health/test_refactoring_extract_helper.py@@ -0,0 +1,357 @@+"""Tests for the Extract Helper refactoring detector (clone dedup).++The detector turns the verified clone pairs the health pass already computed+(``ClonePair`` records, surfaced on ``RefactoringContext.clones``) into a+structured "extract this duplicated block into a shared helper" suggestion.++Fixtures build ``ClonePair`` records directly so the clone geometry — which+files, which line ranges, co-change — is explicit and the expected+occurrences are unambiguous and deterministic.+"""++from __future__ import annotations++from repowise.core.analysis.health.duplication import ClonePair+from repowise.core.analysis.health.refactoring import (+ RefactoringContext,+ detect_refactorings,+ registered_detectors,+)+from repowise.core.analysis.health.refactoring.extract_helper import (+ _common_directory,+ _merge_ranges_per_file,+)+++class _DryFinding:+ """Minimal HealthFindingData-like stand-in for a dry_violation finding."""++ def __init__(self, start: int, end: int, impact: float):+ self.biomarker_type = "dry_violation"+ self.line_start = start+ self.line_end = end+ self.health_impact = impact+ self.function_name = None+ self.details = {}+++def _pair(+ file_a: str,+ file_b: str,+ a_start: int,+ a_end: int,+ b_start: int,+ b_end: int,+ *,+ token_count: int = 50,+ co_change: int = 0,+) -> ClonePair:+ return ClonePair(+ file_a=file_a,+ file_b=file_b,+ a_start_line=a_start,+ a_end_line=a_end,+ b_start_line=b_start,+ b_end_line=b_end,+ token_count=token_count,+ co_change_count=co_change,+ )+++def _ctx(+ file_path: str,+ clones: list[ClonePair],+ *,+ findings: list | None = None,+ module_map: dict[str, str] | None = None,+) -> RefactoringContext:+ return RefactoringContext(+ file_path=file_path,+ language="python",+ nloc=200,+ classes=[],+ findings=findings or [],+ dependents_count=0,+ clones=clones,+ module_map=module_map or {},+ )+++# ---- registration --------------------------------------------------------+++def test_detector_registered():+ assert "extract_helper" in [d.name for d in registered_detectors()]+++def test_silent_without_clones():+ assert detect_refactorings(_ctx("a/x.py", [])) == []+++# ---- cross-file extraction + canonical anchor ----------------------------+++def test_emits_for_cross_file_clone():+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55)+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ ]+ assert len(sugs) == 1+ s = sugs[0]+ assert s.file_path == "pkg/a.py"+ assert s.target_symbol == "a.py:10-25"+ assert s.plan["occurrences"] == [+ {"file": "pkg/a.py", "line_start": 10, "line_end": 25},+ {"file": "pkg/b.py", "line_start": 40, "line_end": 55},+ ]+ assert s.evidence["occurrence_count"] == 2+ assert s.evidence["duplicated_lines"] == 16+ assert s.evidence["is_intra_file"] is False+ assert s.blast_radius == {+ "files": ["pkg/b.py"],+ "file_count": 1,+ "co_change_count": 0,+ }+++def test_canonical_anchor_dedups():+ # The same pair seen from the non-anchor file (b > a) yields nothing, so a+ # clone set is suggested exactly once.+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55)+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/b.py", [pair]))+ if s.refactoring_type == "extract_helper"+ ]+ assert sugs == []+++def test_transitive_clone_set_one_suggestion():+ # A clones with B and C; from A (the min path) both partners are visible →+ # one suggestion listing all three sites.+ clones = [+ _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55),+ _pair("pkg/a.py", "pkg/c.py", 10, 25, 70, 85),+ ]+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", clones))+ if s.refactoring_type == "extract_helper"+ ]+ assert len(sugs) == 1+ files = [o["file"] for o in sugs[0].plan["occurrences"]]+ assert files == ["pkg/a.py", "pkg/b.py", "pkg/c.py"]+ assert sugs[0].blast_radius["file_count"] == 2+++def test_intra_file_clone():+ pair = _pair("pkg/a.py", "pkg/a.py", 10, 25, 60, 75)+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ ]+ assert len(sugs) == 1+ s = sugs[0]+ assert s.evidence["is_intra_file"] is True+ assert s.plan["occurrences"] == [+ {"file": "pkg/a.py", "line_start": 10, "line_end": 25},+ {"file": "pkg/a.py", "line_start": 60, "line_end": 75},+ ]+ assert s.blast_radius["files"] == []+++def test_overlapping_windows_collapse_to_one_site():+ # The clone detector emits a block as several offset windows; they must+ # coalesce into one occurrence per file, not read as many sites.+ clones = [+ _pair("pkg/a.py", "pkg/b.py", 8, 35, 40, 67),+ _pair("pkg/a.py", "pkg/b.py", 9, 36, 41, 68),+ _pair("pkg/a.py", "pkg/b.py", 22, 30, 54, 62),+ ]+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", clones))+ if s.refactoring_type == "extract_helper"+ ]+ assert len(sugs) == 1+ assert sugs[0].plan["occurrences"] == [+ {"file": "pkg/a.py", "line_start": 8, "line_end": 36},+ {"file": "pkg/b.py", "line_start": 40, "line_end": 68},+ ]+ assert sugs[0].evidence["occurrence_count"] == 2+++def test_merge_ranges_per_file_helper():+ merged = _merge_ranges_per_file(+ [("a.py", 8, 35), ("a.py", 9, 36), ("a.py", 22, 28), ("a.py", 60, 75), ("b.py", 1, 9)]+ )+ assert merged == [("a.py", 8, 36), ("a.py", 60, 75), ("b.py", 1, 9)]+++def test_two_distinct_blocks_in_one_file():+ # Two non-overlapping anchor regions → two separate suggestions.+ clones = [+ _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55),+ _pair("pkg/a.py", "pkg/c.py", 100, 120, 5, 25),+ ]+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", clones))+ if s.refactoring_type == "extract_helper"+ ]+ assert len(sugs) == 2+ assert {s.line_start for s in sugs} == {10, 100}+++# ---- gates ---------------------------------------------------------------+++def test_below_min_lines_skipped():+ # 6-line clone — below the 8-line helper floor.+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 15, 40, 45)+ assert [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ ] == []+++def test_test_file_occurrences_dropped():+ # A clone shared only with a test file collapses to one real site → skip.+ pair = _pair("pkg/a.py", "tests/test_a.py", 10, 25, 40, 55)+ assert [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ ] == []+++def test_test_file_dropped_but_real_sites_kept():+ clones = [+ _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55),+ _pair("pkg/a.py", "tests/test_a.py", 10, 25, 5, 20),+ ]+ sugs = [+ s+ for s in detect_refactorings(_ctx("pkg/a.py", clones))+ if s.refactoring_type == "extract_helper"+ ]+ assert len(sugs) == 1+ files = [o["file"] for o in sugs[0].plan["occurrences"]]+ assert files == ["pkg/a.py", "pkg/b.py"]+++def test_generated_migration_occurrences_dropped():+ # Migration boilerplate duplicates heavily but is never refactored — a+ # clone confined to migration files yields no suggestion.+ pair = _pair(+ "core/alembic/versions/0001_a.py",+ "core/alembic/versions/0002_b.py",+ 10,+ 25,+ 10,+ 25,+ )+ assert [+ s+ for s in detect_refactorings(_ctx("core/alembic/versions/0001_a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ ] == []+++def test_disabled_detector_yields_nothing():+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55)+ assert detect_refactorings(_ctx("pkg/a.py", [pair]), disabled=["extract_helper"]) == []+++# ---- impact + confidence -------------------------------------------------+++def test_impact_from_overlapping_dry_violation():+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55)+ findings = [_DryFinding(12, 22, 1.8)]+ sugs = detect_refactorings(_ctx("pkg/a.py", [pair], findings=findings))+ s = next(s for s in sugs if s.refactoring_type == "extract_helper")+ assert s.impact_delta == 1.8+++def test_no_impact_when_finding_disjoint():+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55)+ findings = [_DryFinding(200, 210, 1.8)]+ sugs = detect_refactorings(_ctx("pkg/a.py", [pair], findings=findings))+ s = next(s for s in sugs if s.refactoring_type == "extract_helper")+ assert s.impact_delta == 0.0+++def test_confidence_high_when_actively_co_changed():+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55, co_change=4)+ s = next(+ s+ for s in detect_refactorings(_ctx("pkg/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ )+ assert s.confidence == "high"+ assert s.evidence["co_change_count"] == 4+++def test_confidence_medium_when_dormant():+ pair = _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55, co_change=0)+ s = next(+ s+ for s in detect_refactorings(_ctx("pkg/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ )+ assert s.confidence == "medium"+++# ---- suggested site ------------------------------------------------------+++def test_suggested_site_community_centroid():+ pair = _pair("api/a.py", "core/b.py", 10, 25, 40, 55)+ module_map = {"api/a.py": "api", "core/b.py": "api"}+ s = next(+ s+ for s in detect_refactorings(_ctx("api/a.py", [pair], module_map=module_map))+ if s.refactoring_type == "extract_helper"+ )+ assert s.plan["suggested_site"]["module"] == "api"+++def test_suggested_site_directory_fallback():+ pair = _pair("pkg/sub/a.py", "pkg/sub/b.py", 10, 25, 40, 55)+ s = next(+ s+ for s in detect_refactorings(_ctx("pkg/sub/a.py", [pair]))+ if s.refactoring_type == "extract_helper"+ )+ assert s.plan["suggested_site"]["module"] is None+ assert s.plan["suggested_site"]["directory"] == "pkg/sub"+++def test_common_directory_helper():+ assert _common_directory(["a/b/x.py", "a/b/y.py"]) == "a/b"+ assert _common_directory(["a/b/x.py", "a/c/y.py"]) == "a"+ assert _common_directory(["a/x.py", "b/y.py"]) is None+ assert _common_directory(["x.py", "a/y.py"]) is None+++# ---- determinism ---------------------------------------------------------+++def test_deterministic_and_stable_order():+ clones = [+ _pair("pkg/a.py", "pkg/b.py", 10, 25, 40, 55),+ _pair("pkg/a.py", "pkg/c.py", 100, 120, 5, 25),+ ]+ findings = [_DryFinding(100, 120, 3.0), _DryFinding(10, 25, 1.0)]+ a = detect_refactorings(_ctx("pkg/a.py", clones, findings=findings))+ b = detect_refactorings(_ctx("pkg/a.py", clones, findings=findings))+ a = [s for s in a if s.refactoring_type == "extract_helper"]+ b = [s for s in b if s.refactoring_type == "extract_helper"]+ # Bigger recovered impact first.+ assert [s.line_start for s in a] == [100, 10]+ assert [(s.target_symbol, s.plan) for s in a] == [(s.target_symbol, s.plan) for s in b]