refactorai-core 3.0.0__py3-none-any.whl

refactor_core/__init__.py

@@ -0,0 +1,27 @@
+"""Shared core for the refactor platform.
+
+This package is the single source of truth for code indexing, pipeline data
+contracts, quality-gate evaluation, constitution parsing, and central-store
+path resolution. It is imported by both the CLI (`refactor`) and, going
+forward, the server-side worker so local and server runs stay in parity
+(see docs/15-local-cli-and-constitution-spec.md, ADR-204).
+"""
+
+from refactor_core.models import (
+    Finding,
+    GateResult,
+    GeneratedTest,
+    PatchGroup,
+    RunArtifact,
+)
+
+__all__ = [
+    "Finding",
+    "GateResult",
+    "GeneratedTest",
+    "PatchGroup",
+    "RunArtifact",
+    "__version__",
+]
+
+__version__ = "3.0.0"

refactor_core/apply.py

@@ -0,0 +1,252 @@
+"""Unified-diff parsing and atomic in-place application with backup/revert.
+
+Patches are produced as unified diffs (the run artifact). Applying them is
+atomic: all target files are computed first (raising on any mismatch), the
+originals are snapshotted into the run's ``backup/`` directory, then the new
+contents are written. ``revert`` restores from that snapshot.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import re
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def make_unified_diff(path: str, original_text: str, new_text: str) -> str:
+    """Build a unified diff for a single file (consistent with the applier)."""
+    a = original_text.split("\n")
+    b = new_text.split("\n")
+    diff = difflib.unified_diff(a, b, fromfile=f"a/{path}", tofile=f"b/{path}", lineterm="")
+    return "\n".join(diff)
+
+_HUNK_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+APPLIED_MARKER = "applied.json"
+BACKUP_DIR = "backup"
+
+
+class ApplyError(RuntimeError):
+    """Raised when a diff cannot be cleanly applied."""
+
+
+@dataclass
+class Hunk:
+    old_start: int
+    lines: list[tuple[str, str]] = field(default_factory=list)
+
+
+@dataclass
+class FilePatch:
+    path: str
+    hunks: list[Hunk] = field(default_factory=list)
+
+
+def _strip_ab_prefix(path: str) -> str:
+    path = path.strip()
+    if path.startswith(("a/", "b/")):
+        return path[2:]
+    return path
+
+
+def parse_unified_diff(diff_text: str) -> list[FilePatch]:
+    """Parse a (possibly multi-file) unified diff into ``FilePatch`` objects."""
+    patches: list[FilePatch] = []
+    current: FilePatch | None = None
+    lines = diff_text.split("\n")
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.startswith("--- "):
+            i += 1
+            continue
+        if line.startswith("+++ "):
+            current = FilePatch(path=_strip_ab_prefix(line[4:]))
+            patches.append(current)
+            i += 1
+            continue
+        match = _HUNK_RE.match(line)
+        if match:
+            if current is None:
+                raise ApplyError("Hunk encountered before a file header")
+            hunk = Hunk(old_start=int(match.group(1)))
+            i += 1
+            while i < len(lines):
+                hl = lines[i]
+                if not hl or hl[0] not in " -+" or hl.startswith(("--- ", "+++ ")) or _HUNK_RE.match(hl):
+                    break
+                hunk.lines.append((hl[0], hl[1:]))
+                i += 1
+            current.hunks.append(hunk)
+            continue
+        i += 1
+    return patches
+
+
+def apply_file_patch(original_text: str, hunks: list[Hunk]) -> str:
+    """Apply hunks to ``original_text`` and return the new text."""
+    original = original_text.split("\n")
+    result: list[str] = []
+    idx = 0  # 0-based cursor into original
+
+    for hunk in hunks:
+        start = max(hunk.old_start - 1, 0)
+        if start < idx:
+            raise ApplyError("Overlapping or out-of-order hunks")
+        result.extend(original[idx:start])
+        idx = start
+        for tag, content in hunk.lines:
+            if tag == " ":
+                if idx >= len(original) or original[idx] != content:
+                    raise ApplyError(f"Context mismatch at line {idx + 1}: expected {content!r}")
+                result.append(original[idx])
+                idx += 1
+            elif tag == "-":
+                if idx >= len(original) or original[idx] != content:
+                    raise ApplyError(f"Removal mismatch at line {idx + 1}: expected {content!r}")
+                idx += 1
+            elif tag == "+":
+                result.append(content)
+    result.extend(original[idx:])
+    return "\n".join(result)
+
+
+def validate_diff(project_root: Path | str, diff_text: str) -> tuple[bool, str]:
+    """Validate a single unified diff without mutating any files (R9, FR-13).
+
+    Returns ``(ok, reason)``. A diff is valid when it has at least one file
+    header, parses, and applies cleanly against current on-disk content.
+    """
+    if not diff_text or not diff_text.strip():
+        return False, "empty diff"
+    try:
+        patches = parse_unified_diff(diff_text)
+    except ApplyError as exc:
+        return False, f"malformed diff: {exc}"
+    if not patches:
+        return False, "no file headers (expected 'a/<path>' and 'b/<path>')"
+    if not any(fp.hunks for fp in patches):
+        return False, "no hunks to apply"
+    try:
+        compute_file_changes(project_root, [diff_text])
+    except ApplyError as exc:
+        return False, f"does not apply cleanly: {exc}"
+    return True, ""
+
+
+def compute_file_changes(project_root: Path | str, diff_texts: list[str]) -> dict[str, str]:
+    """Compute new file contents for all diffs without writing anything.
+
+    Raises ``ApplyError`` if any hunk fails to apply, so callers can abort
+    before touching the working tree.
+    """
+    project_root = Path(project_root)
+    changes: dict[str, str] = {}
+    for diff_text in diff_texts:
+        for file_patch in parse_unified_diff(diff_text):
+            target = project_root / file_patch.path
+            if file_patch.path in changes:
+                base = changes[file_patch.path]
+            elif target.exists():
+                base = target.read_text(encoding="utf-8")
+            else:
+                base = ""
+            changes[file_patch.path] = apply_file_patch(base, file_patch.hunks)
+    return changes
+
+
+def apply_changes(project_root: Path | str, run_dir: Path, changes: dict[str, str]) -> list[str]:
+    """Snapshot originals into the run backup dir, then write new contents.
+
+    Returns the list of changed relative paths. On a write failure, restores
+    from the just-written backups and re-raises.
+    """
+    project_root = Path(project_root)
+    backup_root = run_dir / BACKUP_DIR
+    backup_root.mkdir(parents=True, exist_ok=True)
+
+    existing: list[str] = []
+    new_files: list[str] = []
+    for rel in changes:
+        src = project_root / rel
+        if src.exists():
+            dst = backup_root / rel
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)
+            existing.append(rel)
+        else:
+            new_files.append(rel)
+
+    written: list[str] = []
+    try:
+        for rel, text in changes.items():
+            dest = project_root / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(text, encoding="utf-8")
+            written.append(rel)
+    except OSError as exc:
+        _restore(project_root, backup_root, existing, new_files_written=written, new_files=new_files)
+        raise ApplyError(f"Write failed, rolled back: {exc}") from exc
+
+    _write_marker(run_dir, status="applied", existing=existing, new_files=new_files)
+    return written
+
+
+def revert_from_backup(project_root: Path | str, run_dir: Path) -> list[str]:
+    """Restore files from the run's backup snapshot."""
+    project_root = Path(project_root)
+    marker = read_marker(run_dir)
+    if not marker or marker.get("status") != "applied":
+        raise ApplyError("Latest run has no applied changes to revert")
+
+    existing = marker.get("files", [])
+    new_files = marker.get("new_files", [])
+    restored = _restore(project_root, run_dir / BACKUP_DIR, existing, new_files_written=new_files, new_files=new_files)
+    _write_marker(run_dir, status="reverted", existing=existing, new_files=new_files)
+    return restored
+
+
+def _restore(project_root: Path, backup_root: Path, existing: list[str], *, new_files_written: list[str], new_files: list[str]) -> list[str]:
+    restored: list[str] = []
+    for rel in existing:
+        backup = backup_root / rel
+        if backup.exists():
+            dest = project_root / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(backup, dest)
+            restored.append(rel)
+    for rel in new_files_written:
+        if rel in new_files:
+            target = project_root / rel
+            if target.exists():
+                target.unlink()
+                restored.append(rel)
+    return restored
+
+
+def _write_marker(run_dir: Path, *, status: str, existing: list[str], new_files: list[str]) -> None:
+    (run_dir / APPLIED_MARKER).write_text(
+        json.dumps(
+            {
+                "status": status,
+                "files": existing,
+                "new_files": new_files,
+                "at": datetime.now(timezone.utc).isoformat(),
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+
+def read_marker(run_dir: Path) -> dict | None:
+    path = run_dir / APPLIED_MARKER
+    if not path.is_file():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None

refactor_core/budgeting.py

@@ -0,0 +1,153 @@
+"""Model-aware context budgeting and deterministic batch packing (R9.1, ADR-211).
+
+Turns a flat list of index documents into one or more batches that each fit an
+effective input-token budget derived from the resolved model context window and
+a reserved output allowance. Both execution modes consume this so no single
+provider call exceeds the model's limits.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from refactor_core.capabilities import CapabilitySnapshot
+
+# Conservative chars-per-token estimate. Real tokenizers vary; we err on the
+# side of *fewer* chars per token (i.e. higher token estimate) for safety.
+CHARS_PER_TOKEN = 3.5
+DEFAULT_BUDGET_RATIO = 0.55
+# Per-request prompt scaffolding (instructions + constitution) reserve.
+PROMPT_OVERHEAD_TOKENS = 1_500
+
+
+@dataclass(frozen=True)
+class Budget:
+    context_window: int
+    reserved_output_tokens: int
+    input_budget_tokens: int
+    ratio: float
+
+
+@dataclass
+class BatchPlan:
+    budget: Budget
+    batches: list[list[dict]]
+    estimated_tokens: list[int]
+    total_documents: int
+    skipped_oversized: int
+
+    @property
+    def batch_count(self) -> int:
+        return len(self.batches)
+
+    @property
+    def total_estimated_tokens(self) -> int:
+        return sum(self.estimated_tokens)
+
+
+def estimate_tokens(text: str) -> int:
+    """Conservative token estimate for a chunk of text."""
+    if not text:
+        return 0
+    return max(1, math.ceil(len(text) / CHARS_PER_TOKEN))
+
+
+def estimate_document_tokens(doc: dict) -> int:
+    """Estimate tokens for a single index document, including light JSON framing."""
+    chunk = doc.get("chunk_text", "") or ""
+    path = doc.get("path", "") or ""
+    # ~20 tokens of structural framing per document (keys, braces, language).
+    return estimate_tokens(chunk) + estimate_tokens(path) + 20
+
+
+def compute_budget(
+    capabilities: CapabilitySnapshot,
+    *,
+    ratio: float = DEFAULT_BUDGET_RATIO,
+    output_ceiling: int | None = None,
+) -> Budget:
+    """Derive the effective input-token budget for a single provider call."""
+    ratio = _clamp_ratio(ratio)
+    context_window = max(1, int(capabilities.context_window))
+    reserved = int(capabilities.max_output_tokens)
+    if output_ceiling is not None:
+        reserved = min(reserved, max(1, int(output_ceiling)))
+    reserved = min(reserved, context_window - 1)
+
+    usable = (context_window - reserved) * ratio
+    input_budget = int(usable) - PROMPT_OVERHEAD_TOKENS
+    input_budget = max(input_budget, 1)
+    return Budget(
+        context_window=context_window,
+        reserved_output_tokens=reserved,
+        input_budget_tokens=input_budget,
+        ratio=ratio,
+    )
+
+
+def plan_batches(
+    documents: list[dict],
+    capabilities: CapabilitySnapshot,
+    *,
+    ratio: float = DEFAULT_BUDGET_RATIO,
+    output_ceiling: int | None = None,
+) -> BatchPlan:
+    """Pack documents into context-safe batches (deterministic, input order).
+
+    A document larger than the whole input budget is placed in its own batch
+    (the provider/pipeline may further truncate); it is counted in
+    ``skipped_oversized`` for observability but is never silently dropped.
+    """
+    budget = compute_budget(capabilities, ratio=ratio, output_ceiling=output_ceiling)
+
+    batches: list[list[dict]] = []
+    estimated: list[int] = []
+    current: list[dict] = []
+    current_tokens = 0
+    skipped_oversized = 0
+
+    for doc in documents:
+        doc_tokens = estimate_document_tokens(doc)
+
+        if doc_tokens > budget.input_budget_tokens:
+            skipped_oversized += 1
+            if current:
+                batches.append(current)
+                estimated.append(current_tokens)
+                current = []
+                current_tokens = 0
+            batches.append([doc])
+            estimated.append(doc_tokens)
+            continue
+
+        if current and current_tokens + doc_tokens > budget.input_budget_tokens:
+            batches.append(current)
+            estimated.append(current_tokens)
+            current = []
+            current_tokens = 0
+
+        current.append(doc)
+        current_tokens += doc_tokens
+
+    if current:
+        batches.append(current)
+        estimated.append(current_tokens)
+
+    return BatchPlan(
+        budget=budget,
+        batches=batches,
+        estimated_tokens=estimated,
+        total_documents=len(documents),
+        skipped_oversized=skipped_oversized,
+    )
+
+
+def _clamp_ratio(ratio: float) -> float:
+    try:
+        ratio = float(ratio)
+    except (TypeError, ValueError):
+        return DEFAULT_BUDGET_RATIO
+    if ratio <= 0 or ratio >= 1:
+        return DEFAULT_BUDGET_RATIO
+    return ratio

refactor_core/capabilities.py

@@ -0,0 +1,56 @@
+"""Resolved provider/model capability snapshot (R9.1).
+
+Combines a provider instance's declared metadata with the built-in model catalog
+and ``model_context_overrides`` from ``refactor.config`` into a single snapshot
+used by budgeting, mode resolution, and ``refactor doctor``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from refactor_core.model_catalog import ModelContext, resolve_model_context
+
+
+@dataclass(frozen=True)
+class CapabilitySnapshot:
+    provider: str
+    model_id: str
+    supports_tools: bool
+    supports_refactor: bool
+    context_window: int
+    max_output_tokens: int
+    source: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def resolve_capabilities(provider, settings: dict | None = None) -> CapabilitySnapshot:
+    """Resolve effective capabilities for a provider instance.
+
+    Precedence for context/tool values: a provider that *explicitly* declares a
+    non-default ``supports_tools`` keeps it; otherwise the catalog/override value
+    wins. Context-window and output-token ceilings always come from the catalog/
+    override resolution (the authoritative per-model source).
+    """
+    settings = settings or {}
+    provider_name = getattr(provider, "provider_name", "unknown")
+    model_id = getattr(provider, "model_id", "unknown")
+    overrides = settings.get("model_context_overrides")
+
+    ctx: ModelContext = resolve_model_context(provider_name, model_id, overrides=overrides)
+
+    # Honor an explicit provider-level opt-in to tools if the catalog is unsure.
+    declared_tools = bool(getattr(provider, "supports_tools", False))
+    supports_tools = ctx.supports_tools or declared_tools
+
+    return CapabilitySnapshot(
+        provider=provider_name,
+        model_id=model_id,
+        supports_tools=supports_tools,
+        supports_refactor=bool(getattr(provider, "supports_refactor", True)),
+        context_window=ctx.context_window,
+        max_output_tokens=ctx.max_output_tokens,
+        source=ctx.source,
+    )

refactor_core/compliance/__init__.py

@@ -0,0 +1,34 @@
+"""Compliance pack loading/projection namespace (R18)."""
+
+from refactor_core.compliance.evidence import (
+    ComplianceGateDecision,
+    build_compliance_evidence_bundle,
+    evaluate_compliance_gate,
+)
+from refactor_core.compliance.loader import (
+    CompliancePackError,
+    load_compliance_pack_for_framework,
+    resolve_compliance_packs,
+)
+from refactor_core.compliance.models import (
+    CompliancePack,
+    CompliancePackResolution,
+    ComplianceProjectedRule,
+    ComplianceRuleDef,
+)
+from refactor_core.compliance.projection import project_compliance_for_finding
+
+__all__ = [
+    "CompliancePack",
+    "CompliancePackError",
+    "ComplianceGateDecision",
+    "CompliancePackResolution",
+    "ComplianceProjectedRule",
+    "ComplianceRuleDef",
+    "build_compliance_evidence_bundle",
+    "evaluate_compliance_gate",
+    "load_compliance_pack_for_framework",
+    "project_compliance_for_finding",
+    "resolve_compliance_packs",
+]
+

refactor_core/compliance/detectors.py

@@ -0,0 +1,109 @@
+"""Project-context detectors for compliance projection (R18 Phase 3)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+_SENSITIVE_SEGMENTS = {
+    "auth",
+    "iam",
+    "billing",
+    "payment",
+    "payments",
+    "audit",
+    "security",
+    "crypto",
+    "pii",
+    "privacy",
+    "ephi",
+}
+
+_CODE_EXTS = {
+    ".py",
+    ".js",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".java",
+    ".go",
+    ".cs",
+    ".php",
+    ".rb",
+    ".rs",
+    ".cpp",
+    ".cc",
+    ".c",
+    ".h",
+}
+
+
+@dataclass(frozen=True)
+class ComplianceProjectContext:
+    """Derived context used by rule projection."""
+
+    project_root: Path
+    languages: tuple[str, ...]
+    has_package_json: bool
+    has_pyproject: bool
+    has_go_mod: bool
+
+
+def detect_project_context(project_root: Path | str) -> ComplianceProjectContext:
+    root = Path(project_root)
+    langs: set[str] = set()
+    if (root / "package.json").is_file():
+        langs.update({"js", "ts"})
+    if (root / "pyproject.toml").is_file() or (root / "requirements.txt").is_file():
+        langs.add("py")
+    if (root / "go.mod").is_file():
+        langs.add("go")
+    # Cheap fallback: infer from extension seen in top-level/src.
+    for candidate in (root, root / "src"):
+        if not candidate.is_dir():
+            continue
+        for item in candidate.rglob("*"):
+            if not item.is_file():
+                continue
+            if item.suffix.lower() not in _CODE_EXTS:
+                continue
+            suffix = item.suffix.lower()
+            if suffix in {".js", ".jsx", ".ts", ".tsx"}:
+                langs.update({"js", "ts"})
+            elif suffix == ".py":
+                langs.add("py")
+            elif suffix == ".go":
+                langs.add("go")
+            elif suffix in {".java"}:
+                langs.add("java")
+    return ComplianceProjectContext(
+        project_root=root,
+        languages=tuple(sorted(langs)),
+        has_package_json=(root / "package.json").is_file(),
+        has_pyproject=(root / "pyproject.toml").is_file(),
+        has_go_mod=(root / "go.mod").is_file(),
+    )
+
+
+def normalize_rel_path(value: str) -> str:
+    text = str(value or "").strip().replace("\\", "/").lstrip("./")
+    while "//" in text:
+        text = text.replace("//", "/")
+    return text.strip().lower()
+
+
+def path_segments(path_value: str) -> tuple[str, ...]:
+    norm = normalize_rel_path(path_value)
+    if not norm:
+        return ()
+    return tuple(chunk for chunk in norm.split("/") if chunk)
+
+
+def touches_sensitive_path(path_value: str) -> bool:
+    return any(seg in _SENSITIVE_SEGMENTS for seg in path_segments(path_value))
+
+
+def looks_like_serializer(path_value: str) -> bool:
+    norm = normalize_rel_path(path_value)
+    return "serial" in norm or norm.endswith("_dto.py") or "schema" in norm
+

refactor_core/compliance/evidence.py

@@ -0,0 +1,45 @@
+"""Compliance gate/evidence helpers (R18 Phase 7)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ComplianceGateDecision:
+    status: str  # passed | blocked
+    reasons: tuple[str, ...] = ()
+
+
+def evaluate_compliance_gate(compliance_summary: dict | None, *, base_gate_status: str) -> ComplianceGateDecision:
+    """Derive compliance gate outcome from summary payload and base gate status."""
+    summary = compliance_summary if isinstance(compliance_summary, dict) else {}
+    try:
+        blocked_count = int(summary.get("blocked_count", 0) or 0)
+    except (TypeError, ValueError):
+        blocked_count = 0
+    level = str(summary.get("level", "standard") or "standard").strip().lower()
+    if base_gate_status == "blocked":
+        return ComplianceGateDecision(status="blocked", reasons=("quality_gate_blocked",))
+    if blocked_count > 0 and level in {"standard", "strict"}:
+        return ComplianceGateDecision(status="blocked", reasons=("compliance_controls_blocked",))
+    return ComplianceGateDecision(status="passed", reasons=())
+
+
+def build_compliance_evidence_bundle(report: dict) -> dict:
+    """Create an auditor-friendly compliance evidence payload from run report."""
+    payload = dict(report or {})
+    return {
+        "run_id": payload.get("run_id", ""),
+        "target": payload.get("target", ""),
+        "created_at": payload.get("created_at", ""),
+        "model_id": payload.get("model_id", ""),
+        "gate": payload.get("gate", {}),
+        "compliance_summary": payload.get("compliance_summary", {}),
+        "rule_trace": {
+            "rule_source": payload.get("rule_source", ""),
+            "rule_pattern": payload.get("rule_pattern", ""),
+            "rule_hash": payload.get("rule_hash", ""),
+        },
+    }
+