refactorika 0.2.0__py3-none-any.whl

refactorika/__init__.py

@@ -0,0 +1,3 @@
+"""Refactorika — verified structural refactoring for Python, exposed to Claude over MCP."""
+
+__version__ = "0.2.0"

refactorika/agents/base.py

@@ -0,0 +1,23 @@
+"""Base class for all specialist refactor agents."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..core.apply import apply_and_verify
+from ..core.schema import EditRecord, PlanTask
+from ..core.storage import Storage
+
+
+class SpecialistAgent(ABC):
+    supported_kinds: list[str] = []
+
+    def handle(self, task: PlanTask, storage: Storage) -> EditRecord:
+        new_content = self.propose(task, storage)
+        dominant_kind = (
+            task.opportunities[0].kind if task.opportunities else self.supported_kinds[0]
+        )
+        return apply_and_verify(task.file, new_content, dominant_kind, storage)
+
+    @abstractmethod
+    def propose(self, task: PlanTask, storage: Storage) -> str: ...

refactorika/agents/complexity_agent.py

@@ -0,0 +1,28 @@
+"""ComplexityAgent: handles function splits, nesting flattening, helper extraction.
+
+propose() is a stub — wire in LLM reasoning to generate new_content.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.schema import PlanTask
+from ..core.storage import Storage
+from .base import SpecialistAgent
+
+
+class ComplexityAgent(SpecialistAgent):
+    supported_kinds = [
+        "split_function",
+        "flatten_nesting",
+        "extract_helper",
+        "split_module",
+        "dedupe_block",
+    ]
+
+    def propose(self, task: PlanTask, storage: Storage) -> str:
+        # Stub: returns original content (no-op) until LLM reasoning is wired in.
+        # Replace with an LLM call that receives task.opportunities + file content
+        # and returns refactored source.
+        return Path(task.file).read_text()

refactorika/agents/dead_code_agent.py

@@ -0,0 +1,23 @@
+"""DeadCodeAgent: removes high-confidence dead symbols (deterministic, no LLM needed)."""
+
+from __future__ import annotations
+
+from ..core.schema import PlanTask
+from ..core.storage import Storage
+from .base import SpecialistAgent
+
+
+class DeadCodeAgent(SpecialistAgent):
+    supported_kinds = ["remove_dead_code"]
+
+    def propose(self, task: PlanTask, storage: Storage) -> str:
+        from ..analysis.dead_code import find_dead_code
+        from ..transforms.dead import remove_dead_symbols
+
+        result = find_dead_code(task.file, storage)
+        high_conf_names = {
+            s["name"].split(".")[-1]
+            for s in result.get("dead_symbols", [])
+            if s["confidence"] == "high"
+        }
+        return remove_dead_symbols(task.file, high_conf_names)

refactorika/agents/duplicate_agent.py

@@ -0,0 +1,27 @@
+"""DuplicateAgent: consolidates duplicate functions.
+
+propose() is a stub — wire in LLM reasoning to generate merged new_content.
+Multi-file consolidation overrides handle() to use apply_and_verify_multi.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.schema import EditRecord, PlanTask
+from ..core.storage import Storage
+from .base import SpecialistAgent
+
+
+class DuplicateAgent(SpecialistAgent):
+    supported_kinds = ["consolidate_duplicate"]
+
+    def handle(self, task: PlanTask, storage: Storage) -> EditRecord:
+        # Stub delegates to single-file base path.
+        # Override here to call apply_and_verify_multi once LLM wiring provides
+        # new content for both files in a duplicate pair.
+        return super().handle(task, storage)
+
+    def propose(self, task: PlanTask, storage: Storage) -> str:
+        # Stub: returns original content (no-op) until LLM reasoning is wired in.
+        return Path(task.file).read_text()

refactorika/agents/import_agent.py

@@ -0,0 +1,15 @@
+"""ImportAgent: reorders and deduplicates imports (deterministic, no LLM needed)."""
+
+from __future__ import annotations
+
+from ..core.schema import PlanTask
+from ..core.storage import Storage
+from .base import SpecialistAgent
+
+
+class ImportAgent(SpecialistAgent):
+    supported_kinds = ["reorder_imports"]
+
+    def propose(self, task: PlanTask, storage: Storage) -> str:
+        from ..transforms.imports import reorder_imports
+        return reorder_imports(task.file)

refactorika/agents/orchestrator.py

@@ -0,0 +1,82 @@
+"""Dispatch confirmed-plan tasks to specialists in dependency-ordered waves."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from ..core.schema import Plan, PlanTask
+from ..core.storage import Storage
+from .base import SpecialistAgent
+from .complexity_agent import ComplexityAgent
+from .dead_code_agent import DeadCodeAgent
+from .duplicate_agent import DuplicateAgent
+from .import_agent import ImportAgent
+
+_SPECIALISTS: list[SpecialistAgent] = [
+    ImportAgent(),
+    DeadCodeAgent(),
+    ComplexityAgent(),
+    DuplicateAgent(),
+]
+
+
+def _route(task: PlanTask) -> SpecialistAgent | None:
+    """Return the specialist that handles the task's dominant refactor_kind."""
+    if not task.opportunities:
+        return None
+    dominant = task.opportunities[0].kind
+    for s in _SPECIALISTS:
+        if dominant in s.supported_kinds:
+            return s
+    return None
+
+
+def dispatch_plan(storage: Storage, max_workers: int = 4) -> dict:
+    """Read the confirmed plan, dispatch tasks in dependency-ordered waves, return a summary."""
+    raw = storage.load_plan()
+    if raw is None:
+        return {"error": "no plan; call get_plan first"}
+    plan = Plan.from_dict(raw)
+    if not plan.confirmed:
+        return {"error": "plan not confirmed; call confirm_plan first"}
+
+    by_order: dict[int, list[PlanTask]] = defaultdict(list)
+    for task in plan.tasks:
+        by_order[task.order].append(task)
+
+    committed, rolled_back, skipped = 0, 0, 0
+    records: list[dict] = []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        for level in sorted(by_order.keys()):
+            wave = by_order[level]
+            futures = {}
+            for task in wave:
+                agent = _route(task)
+                if agent is None:
+                    skipped += 1
+                    continue
+                futures[executor.submit(agent.handle, task, storage)] = task
+
+            for future in as_completed(futures):
+                try:
+                    record = future.result()
+                    records.append(record.to_dict())
+                    if record.status == "committed":
+                        committed += 1
+                    elif record.status == "rolled-back":
+                        rolled_back += 1
+                    else:
+                        skipped += 1
+                except Exception as exc:  # noqa: BLE001
+                    task = futures[future]
+                    records.append({"file": task.file, "error": str(exc)})
+                    skipped += 1
+
+    return {
+        "committed": committed,
+        "rolled_back": rolled_back,
+        "skipped": skipped,
+        "records": records,
+    }

refactorika/analysis/audit.py

@@ -0,0 +1,86 @@
+"""Repo-wide audit + dependency-ordered planning (advisory, read-only).
+
+Reuses the existing per-file analysis (`analyze_file`) and call graph
+(`CallGraph`) — no new analysis logic. The audit aggregates opportunities into a
+ranked report; the plan orders deviating files fewest-dependents-first so
+low-blast-radius edits land before the modules many things depend on.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+
+from refactorika.analysis.call_graph import CallGraph, _collect_py_files, _module_name
+from refactorika.core.analyze import analyze_file
+from refactorika.core.schema import AuditEntry, Plan, PlanTask, RepoAudit
+from refactorika.core.storage import Storage
+
+
+def audit_repo(path: str, storage: Storage) -> RepoAudit:
+    """Walk the repo, aggregate per-file opportunities into a ranked report."""
+    files, _root = _collect_py_files(path)
+    entries: list[AuditEntry] = []
+    by_kind: Counter = Counter()
+    rank_by_kind: defaultdict[str, int] = defaultdict(int)
+    total = 0
+
+    for f in files:
+        opps = analyze_file(str(f), storage).opportunities
+        if not opps:
+            continue  # a "deviating" file is one with >= 1 opportunity
+        total += len(opps)
+        for o in opps:
+            by_kind[o.kind] += 1
+            rank_by_kind[o.kind] += o.rank
+        entries.append(
+            AuditEntry(file=str(f), opportunities=opps, score=sum(o.rank for o in opps))
+        )
+
+    entries.sort(key=lambda e: e.score, reverse=True)
+
+    dominant = None
+    if rank_by_kind:  # the kind worth doing most across the repo (highest summed rank)
+        top_kind = max(rank_by_kind, key=lambda k: rank_by_kind[k])
+        dominant = f"{top_kind} ({by_kind[top_kind]} sites)"
+
+    return RepoAudit(
+        repo=path,
+        files_scanned=len(files),
+        total_opportunities=total,
+        by_kind=dict(by_kind),
+        dominant_finding=dominant,
+        entries=entries,
+    )
+
+
+def build_plan(path: str, storage: Storage) -> Plan:
+    """Order deviating files fewest-dependents-first; persist + return the plan."""
+    audit = audit_repo(path, storage)
+    files, root = _collect_py_files(path)
+    cg = CallGraph.build(path)
+    module_of = {str(f): _module_name(f, root) for f in files}
+
+    tasks: list[PlanTask] = []
+    for entry in audit.entries:  # only deviating files (>=1 opportunity)
+        module = module_of.get(entry.file, "")
+        deps = cg.dependents_of(module) if module else []
+        tasks.append(
+            PlanTask(
+                file=entry.file,
+                opportunities=entry.opportunities,
+                dependents=deps,
+                order=0,
+            )
+        )
+
+    # Fewest-dependents-first (low blast radius first); tie-break by score desc.
+    def _order_key(t: PlanTask) -> tuple[int, int]:
+        return (len(t.dependents), -sum(o.rank for o in t.opportunities))
+
+    tasks.sort(key=_order_key)
+    for i, t in enumerate(tasks):
+        t.order = i
+
+    plan = Plan(repo=path, dominant_finding=audit.dominant_finding, tasks=tasks)
+    storage.save_plan(plan.to_dict())
+    return plan