refactorai-core 3.0.0__tar.gz

refactorai_core-3.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: refactorai-core
+Version: 3.0.0
+Summary: Public client core for the refactor platform: indexing, constitution parsing, models, gate evaluation, rules, security prefilter, RR/compliance classification. Contains no proprietary inference engine.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: semgrep>=1.168.0
+Provides-Extra: intelligence
+Requires-Dist: tree-sitter==0.21.3; extra == "intelligence"
+Requires-Dist: tree-sitter-languages==1.10.2; extra == "intelligence"
+
+# refactorai-core
+
+Public client core library for Refactor AI.
+
+This package contains client-safe components used by `refactorai-cli`, including:
+
+- constitution/config parsing
+- document indexing and rule layering
+- data models and gate evaluation
+- security prefilter helpers
+- Refactor Request (RR) classification and local persistence helpers
+
+It intentionally excludes the proprietary engine runtime.

refactorai_core-3.0.0/README.md

@@ -0,0 +1,13 @@
+# refactorai-core
+
+Public client core library for Refactor AI.
+
+This package contains client-safe components used by `refactorai-cli`, including:
+
+- constitution/config parsing
+- document indexing and rule layering
+- data models and gate evaluation
+- security prefilter helpers
+- Refactor Request (RR) classification and local persistence helpers
+
+It intentionally excludes the proprietary engine runtime.

refactorai_core-3.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "refactorai-core"
+version = "3.0.0"
+description = "Public client core for the refactor platform: indexing, constitution parsing, models, gate evaluation, rules, security prefilter, RR/compliance classification. Contains no proprietary inference engine."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "pydantic>=2.8.2",
+  "PyYAML>=6.0.1",
+  "httpx>=0.27.0",
+  "semgrep>=1.168.0",
+]
+
+[project.optional-dependencies]
+# Code intelligence grammars are only needed by the engine (codeintel), but the
+# extra is kept here for backward-compatible install names.
+intelligence = [
+  "tree-sitter==0.21.3",
+  "tree-sitter-languages==1.10.2",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# R21 core split: the client distribution ships ONLY client-safe modules. The
+# proprietary engine (providers, pipeline prompts, execution run loop, codeintel,
+# sandbox/engine runtime) is shipped separately in ``refactor-core-engine`` and
+# is never present on a pip/cloud user's disk. Both distributions install into
+# the same ``refactor_core`` import package. All engine code lives in dedicated
+# subpackages (``enginecore``, ``execution``, ``providers``, ``codeintel``); the
+# top level of ``refactor_core`` contains only client-safe modules, so listing
+# ``refactor_core`` as a package here does NOT drag in any engine ``.py``.
+[tool.setuptools.packages.find]
+include = [
+  "refactor_core",
+  "refactor_core.rules",
+  "refactor_core.security",
+  "refactor_core.compliance",
+  "refactor_core.compliance.packs",
+]
+# Defensive: never ship engine subpackages in the public client wheel even if a
+# future refactor accidentally makes one discoverable.
+exclude = [
+  "refactor_core.enginecore*",
+  "refactor_core.execution*",
+  "refactor_core.providers*",
+  "refactor_core.codeintel*",
+]
+
+[tool.setuptools.package-data]
+"refactor_core.rules" = ["*.json"]
+"refactor_core.compliance.packs" = ["*.json"]

refactorai_core-3.0.0/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"

refactorai_core-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

refactorai_core-3.0.0/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

refactorai_core-3.0.0/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,
+    )

refactorai_core-3.0.0/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",
+]
+