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): 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.py
index 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)
return
table = 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.py
index 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, suggestions
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py
index 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.py
new file mode 100644
index 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 None
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
index 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 the
class'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)
@dataclass
diff --git a/tests/unit/health/test_refactoring_extract_helper.py b/tests/unit/health/test_refactoring_extract_helper.py
new file mode 100644
index 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]