revrem 0.3.2__py3-none-any.whl

code_review_loop/__init__.py

@@ -0,0 +1,5 @@
+"""Utilities for running bounded AI code-review remediation loops."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.3.2"

code_review_loop/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for ``python -m code_review_loop``."""
+
+from code_review_loop.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_review_loop/_compat_jsonschema.py

@@ -0,0 +1,113 @@
+"""JSON Schema 2020-12 validation with graceful fallback.
+
+When the ``jsonschema`` package is available (the default for installed
+wheels), the real validator is used so that *all* JSON Schema keywords
+including ``minimum``, ``maximum``, ``pattern``, ``$ref``, ``allOf``,
+``anyOf``, ``oneOf``, ``if/then/else``, ``minItems``, ``maxItems``, and
+``patternProperties`` are enforced.
+
+When ``jsonschema`` is *not* installed, a minimal compat validator is
+used instead.  The compat layer validates ``type``, ``const``, ``enum``,
+``required``, ``additionalProperties``, ``minLength``, and ``items`` but
+silently ignores the keywords listed above.  Callers that rely on those
+keywords should ensure ``jsonschema`` is present.
+"""
+
+from __future__ import annotations
+
+try:
+    from jsonschema import (  # type: ignore[attr-defined,import-untyped]
+        Draft202012Validator,
+        validate,
+    )
+except ImportError:
+    from collections.abc import Iterator
+
+    class ValidationError(ValueError):
+        """Minimal stand-in for jsonschema.exceptions.ValidationError."""
+
+    def validate(instance, schema) -> None:  # type: ignore[misc]  # noqa: F811
+        Draft202012Validator(schema).validate(instance)
+
+    class Draft202012Validator:  # type: ignore[no-redef]
+        def __init__(self, schema):
+            self.schema = schema
+
+        @classmethod
+        def check_schema(cls, schema) -> None:
+            if not isinstance(schema, dict):
+                raise TypeError("schema must be a mapping")
+
+        def validate(self, instance) -> None:
+            errors = list(self.iter_errors(instance))
+            if errors:
+                raise ValidationError(errors[0])
+
+        def iter_errors(self, instance) -> Iterator[str]:
+            yield from _validate(instance, self.schema, path="$")
+
+    def _validate(instance, schema, *, path: str) -> Iterator[str]:
+        if not isinstance(schema, dict):
+            return
+
+        expected = schema.get("type")
+        if expected is not None and not _matches_type(instance, expected):
+            yield f"{path}: expected type {expected!r}"
+            return
+
+        if "const" in schema and instance != schema["const"]:
+            yield f"{path}: expected const {schema['const']!r}"
+            return
+
+        if "enum" in schema and instance not in schema["enum"]:
+            yield f"{path}: expected one of {schema['enum']!r}"
+            return
+
+        if isinstance(instance, str):
+            min_length = schema.get("minLength")
+            if min_length is not None and len(instance) < min_length:
+                yield f"{path}: string shorter than {min_length}"
+            return
+
+        if isinstance(instance, list):
+            items_schema = schema.get("items")
+            if items_schema is not None:
+                for index, item in enumerate(instance):
+                    yield from _validate(item, items_schema, path=f"{path}[{index}]")
+            return
+
+        if isinstance(instance, dict):
+            properties = schema.get("properties", {})
+            required = schema.get("required", [])
+            additional = schema.get("additionalProperties", True)
+
+            for key in required:
+                if key not in instance:
+                    yield f"{path}: missing required property {key!r}"
+
+            for key, value in instance.items():
+                if key in properties:
+                    yield from _validate(value, properties[key], path=f"{path}.{key}")
+                elif additional is False:
+                    yield f"{path}: unexpected property {key!r}"
+                elif isinstance(additional, dict):
+                    yield from _validate(value, additional, path=f"{path}.{key}")
+
+    def _matches_type(instance, expected) -> bool:
+        if isinstance(expected, list):
+            return any(_matches_type(instance, item) for item in expected)
+        if expected == "object":
+            return isinstance(instance, dict)
+        if expected == "array":
+            return isinstance(instance, list)
+        if expected == "string":
+            return isinstance(instance, str)
+        if expected == "integer":
+            return isinstance(instance, int) and not isinstance(instance, bool)
+        if expected == "number":
+            return isinstance(instance, (int, float)) and not isinstance(instance, bool)
+        if expected == "boolean":
+            return isinstance(instance, bool)
+        if expected == "null":
+            return instance is None
+        return True

code_review_loop/_compat_tomli_w.py

@@ -0,0 +1,97 @@
+"""Minimal TOML writer used when the external `tomli-w` package is unavailable."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+
+def dumps(data: Mapping[str, object]) -> str:
+    lines: list[str] = []
+    _write_table(lines, (), data)
+    return "\n".join(lines)
+
+
+def _write_table(lines: list[str], prefix: tuple[str, ...], table: Mapping[str, object]) -> None:
+    scalars: list[tuple[str, object]] = []
+    nested: list[tuple[str, Mapping[str, object]]] = []
+    arrays: list[tuple[str, Sequence[object]]] = []
+
+    for key, value in table.items():
+        if isinstance(value, Mapping):
+            nested.append((key, value))
+        elif isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+            arrays.append((key, value))
+        else:
+            scalars.append((key, value))
+
+    # Implicit table: a node with only nested sub-tables needs no [header] line;
+    # its children emit their own fully-qualified [a.b.c] paths.
+    container = not scalars and not arrays and nested
+    if prefix and not container:
+        lines.append(f"[{'.'.join(_format_key(part) for part in prefix)}]")
+
+    for key, value in scalars:
+        lines.append(f"{_format_key(key)} = {_format_value(value)}")
+
+    for key, value in arrays:
+        lines.append(f"{_format_key(key)} = {_format_array(value)}")
+
+    for key, value in nested:
+        if lines and (scalars or arrays or (prefix and not container)):
+            lines.append("")
+        _write_table(lines, (*prefix, key), value)
+
+
+def _format_key(key: str) -> str:
+    if key and all(_is_bare_key_char(ch) for ch in key):
+        return key
+    escaped = key.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _is_bare_key_char(ch: str) -> bool:
+    return ch.isascii() and (ch.isalnum() or ch in {"-", "_"})
+
+
+def _format_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int) and not isinstance(value, bool):
+        return str(value)
+    if isinstance(value, float):
+        return repr(value)
+    if value is None:
+        raise TypeError("TOML does not support null/None values")
+    if isinstance(value, str):
+        escaped = _escape_basic_string(value)
+        return f'"{escaped}"'
+    raise TypeError(f"unsupported TOML value type: {type(value).__name__}")
+
+
+def _format_array(values: Sequence[object]) -> str:
+    return "[" + ", ".join(_format_value(value) for value in values) + "]"
+
+
+def _escape_basic_string(value: str) -> str:
+    parts: list[str] = []
+    for char in value:
+        codepoint = ord(char)
+        if char == "\\":
+            parts.append("\\\\")
+        elif char == '"':
+            parts.append('\\"')
+        elif char == "\b":
+            parts.append("\\b")
+        elif char == "\t":
+            parts.append("\\t")
+        elif char == "\n":
+            parts.append("\\n")
+        elif char == "\f":
+            parts.append("\\f")
+        elif char == "\r":
+            parts.append("\\r")
+        elif codepoint < 0x20 or codepoint == 0x7F:
+            parts.append(f"\\u{codepoint:04x}")
+        else:
+            parts.append(char)
+    return "".join(parts)

code_review_loop/artifacts.py

@@ -0,0 +1,87 @@
+"""Artifact writing helpers with canonical JSON and path-safety checks."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import unicodedata
+from collections.abc import Mapping, Sequence
+from contextlib import suppress
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+JSON_SCHEMA_VERSION = "1.0"
+
+
+class ArtifactPathError(ValueError):
+    """Raised when an artifact path would escape its run directory."""
+
+
+def safe_artifact_path(run_dir: Path, relative_path: str | Path) -> Path:
+    path = Path(relative_path)
+    if path.is_absolute():
+        raise ArtifactPathError("artifact path must be relative")
+    if any(part in {"", ".", ".."} for part in path.parts):
+        raise ArtifactPathError("artifact path must not contain empty, current, or parent parts")
+
+    root = run_dir.resolve()
+    target = run_dir / path
+    parent = target.parent
+    resolved_parent = parent.resolve(strict=False)
+    if not resolved_parent.is_relative_to(root):
+        raise ArtifactPathError("artifact path resolves outside the run directory")
+    parent.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def write_text_artifact(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write(path, content.encode("utf-8"))
+
+
+def write_json_artifact(
+    run_dir: Path,
+    relative_path: str | Path,
+    payload: Mapping[str, Any],
+    *,
+    schema_version: str = JSON_SCHEMA_VERSION,
+) -> Path:
+    target = safe_artifact_path(run_dir, relative_path)
+    serializable = canonicalize_json({**dict(payload), "schema_version": schema_version})
+    content = json.dumps(serializable, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    _atomic_write(target, content.encode("utf-8"))
+    return target
+
+
+def canonicalize_json(value: Any) -> Any:
+    if isinstance(value, str):
+        return unicodedata.normalize("NFC", value)
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, Mapping):
+        return {str(canonicalize_json(key)): canonicalize_json(item) for key, item in value.items()}
+    if isinstance(value, Sequence) and not isinstance(value, bytes | bytearray | str):
+        return [canonicalize_json(item) for item in value]
+    return value
+
+
+def _atomic_write(path: Path, content: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    tmp_path = Path(tmp_name)
+    fd_consumed = False
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            fd_consumed = True
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, path)
+    except Exception:
+        if not fd_consumed:
+            os.close(fd)
+        with suppress(FileNotFoundError):
+            tmp_path.unlink()
+        raise

code_review_loop/budgets.py

@@ -0,0 +1,129 @@
+"""Run budget accounting for bounded RevRem execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from time import monotonic
+from typing import Any
+
+
+@dataclass(frozen=True)
+class BudgetConfig:
+    max_wall_seconds: float | None = None
+    max_tokens: int | None = None
+    max_usd: Decimal | None = None
+    soft_warn_fraction: float = 0.8
+
+
+@dataclass
+class BudgetState:
+    started_at_monotonic: float
+    wall_warning_emitted: bool = False
+    tokens_used: int = 0
+    tokens_reported: bool = False
+    usd_used: Decimal = Decimal("0")
+    usd_reported: bool = False
+
+
+class BudgetExceeded(Exception):
+    """Raised when a configured run ceiling has already been reached."""
+
+    def __init__(self, *, ceiling: str, limit: Any, actual: Any):
+        super().__init__(f"{ceiling} budget reached: {actual} >= {limit}")
+        self.ceiling = ceiling
+        self.limit = limit
+        self.actual = actual
+
+
+def started_now() -> BudgetState:
+    return BudgetState(started_at_monotonic=monotonic())
+
+
+def parse_usd(value: str | None) -> Decimal | None:
+    if value is None:
+        return None
+    try:
+        amount = Decimal(value)
+    except InvalidOperation as exc:
+        raise ValueError("--max-usd must be a decimal number") from exc
+    if not amount.is_finite():
+        raise ValueError("--max-usd must be a finite decimal number")
+    if amount < 0:
+        raise ValueError("--max-usd must be 0 or greater")
+    return amount
+
+
+def validate_config(config: BudgetConfig) -> None:
+    if config.max_wall_seconds is not None and config.max_wall_seconds < 0:
+        raise ValueError("--max-wall-seconds must be 0 or greater")
+    if config.max_tokens is not None and config.max_tokens < 0:
+        raise ValueError("--max-tokens must be 0 or greater")
+    if config.max_usd is not None and config.max_usd < 0:
+        raise ValueError("--max-usd must be 0 or greater")
+    if not 0 < config.soft_warn_fraction <= 1:
+        raise ValueError("--soft-warn-fraction must be greater than 0 and no more than 1")
+
+
+def wall_elapsed_seconds(state: BudgetState, *, now: float | None = None) -> float:
+    current = monotonic() if now is None else now
+    return max(0.0, current - state.started_at_monotonic)
+
+
+def wall_warning_due(
+    config: BudgetConfig,
+    state: BudgetState,
+    *,
+    now: float | None = None,
+) -> tuple[bool, float]:
+    if config.max_wall_seconds is None or state.wall_warning_emitted:
+        return False, wall_elapsed_seconds(state, now=now)
+    elapsed = wall_elapsed_seconds(state, now=now)
+    return elapsed >= config.max_wall_seconds * config.soft_warn_fraction, elapsed
+
+
+def check_wall_budget(
+    config: BudgetConfig,
+    state: BudgetState,
+    *,
+    now: float | None = None,
+) -> float:
+    elapsed = wall_elapsed_seconds(state, now=now)
+    if config.max_wall_seconds is not None and elapsed >= config.max_wall_seconds:
+        raise BudgetExceeded(
+            ceiling="wall",
+            limit=f"{config.max_wall_seconds:g}",
+            actual=f"{elapsed:g}",
+        )
+    return elapsed
+
+
+def record_charge(
+    config: BudgetConfig,
+    state: BudgetState,
+    *,
+    tokens: int | None = None,
+    usd: Decimal | None = None,
+) -> None:
+    if tokens is not None:
+        if tokens < 0:
+            raise ValueError("token charge must be 0 or greater")
+        state.tokens_reported = True
+        state.tokens_used += tokens
+    if usd is not None:
+        if usd < 0:
+            raise ValueError("USD charge must be 0 or greater")
+        state.usd_reported = True
+        state.usd_used += usd
+    if config.max_tokens is not None and state.tokens_used >= config.max_tokens:
+        raise BudgetExceeded(
+            ceiling="tokens",
+            limit=config.max_tokens,
+            actual=state.tokens_used,
+        )
+    if config.max_usd is not None and state.usd_used >= config.max_usd:
+        raise BudgetExceeded(
+            ceiling="usd",
+            limit=str(config.max_usd),
+            actual=str(state.usd_used),
+        )

code_review_loop/bug_bundle.py

@@ -0,0 +1,205 @@
+"""Create deterministic, redacted RevRem bug-report bundles."""
+
+from __future__ import annotations
+
+import gzip
+import io
+import json
+import os
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from code_review_loop import artifacts, redaction, suppressions
+
+BUG_BUNDLE_SCHEMA_VERSION = "1.0"
+MANIFEST_NAME = "bug-bundle.json"
+DEFAULT_JSON_NAMES = {
+    "summary.json",
+    "diagnostics.json",
+    "events.jsonl",
+    "doctor.json",
+    "preflight.json",
+    "profile.json",
+}
+DEFAULT_TEXT_NAMES = {"profile.toml"}
+
+
+@dataclass(frozen=True)
+class BundleOptions:
+    run_dir: Path
+    output_path: Path | None = None
+    include_raw_transcripts: bool = False
+    redact: bool = True
+
+
+@dataclass(frozen=True)
+class BundleResult:
+    output_path: Path
+    manifest: dict[str, object]
+
+
+def create_bug_bundle(options: BundleOptions) -> BundleResult:
+    run_dir = options.run_dir.resolve()
+    if not run_dir.is_dir():
+        raise FileNotFoundError(f"run directory not found: {options.run_dir}")
+
+    run_id = _run_id(run_dir)
+    output_path = (options.output_path or _default_output_path(run_id, run_dir)).resolve()
+    entries: list[tuple[str, bytes]] = []
+    redaction_counts: dict[str, int] = {}
+    for path in _bundle_files(run_dir, include_raw_transcripts=options.include_raw_transcripts):
+        arcname = path.relative_to(run_dir).as_posix()
+        content = path.read_text(encoding="utf-8", errors="replace")
+        if options.redact:
+            result = redaction.redact_text(content)
+            content = result.text
+            _merge_counts(redaction_counts, redaction.redaction_summary(result))
+        entries.append((arcname, content.encode("utf-8")))
+    for path in _suppression_audit_paths(run_dir):
+        summary = suppressions.audit_summary(path)
+        if summary is None:
+            continue
+        arcname = f"suppressions/{path.stem}.summary.json"
+        content = json.dumps(summary, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        entries.append((arcname, content.encode("utf-8")))
+
+    manifest = {
+        "schema_version": BUG_BUNDLE_SCHEMA_VERSION,
+        "run_id": run_id,
+        "source_run_dir_name": run_dir.name,
+        "include_raw_transcripts": options.include_raw_transcripts,
+        "redacted": options.redact,
+        "files": [arcname for arcname, _content in entries],
+        "suppression_audit_summaries": [
+            arcname for arcname, _content in entries if arcname.startswith("suppressions/")
+        ],
+        "redaction_counts": redaction_counts,
+    }
+    manifest_bytes = (
+        json.dumps(
+            artifacts.canonicalize_json(manifest),
+            ensure_ascii=False,
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n"
+    ).encode("utf-8")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = output_path.with_suffix(".tar.gz.tmp")
+    try:
+        with (
+            tmp_path.open("wb") as raw,
+            gzip.GzipFile(fileobj=raw, mode="wb", filename="", mtime=0) as gz,
+            tarfile.open(fileobj=gz, mode="w") as tar,
+        ):
+            _add_bytes(tar, MANIFEST_NAME, manifest_bytes)
+            for arcname, bundle_bytes in entries:
+                _add_bytes(tar, arcname, bundle_bytes)
+        os.replace(tmp_path, output_path)
+    except BaseException:
+        tmp_path.unlink(missing_ok=True)
+        raise
+    return BundleResult(output_path=output_path, manifest=manifest)
+
+
+def default_output_path(run_dir: Path) -> Path:
+    return _default_output_path(_run_id(run_dir), run_dir)
+
+
+def _default_output_path(run_id: str, run_dir: Path) -> Path:
+    return Path.cwd() / f"revrem-bug-{_bundle_name_component(run_dir, run_id=run_id)}.tar.gz"
+
+
+def _bundle_files(run_dir: Path, *, include_raw_transcripts: bool) -> list[Path]:
+    candidates = []
+    for path in run_dir.rglob("*"):
+        if path.is_symlink():
+            continue
+        if not path.is_file():
+            continue
+        relative = path.relative_to(run_dir).as_posix()
+        if relative == MANIFEST_NAME:
+            continue
+        if path.name in DEFAULT_JSON_NAMES or path.name.startswith("check-"):
+            candidates.append(path)
+            continue
+        if path.name in DEFAULT_TEXT_NAMES:
+            candidates.append(path)
+            continue
+        if path.name.startswith("review-") and path.name.endswith("-status.json"):
+            candidates.append(path)
+            continue
+        if path.name.startswith("diagnostics-") and path.suffix == ".json":
+            candidates.append(path)
+            continue
+        if path.name.startswith("triage-") and path.suffix == ".json":
+            candidates.append(path)
+            continue
+        if include_raw_transcripts and path.name == "suppressions.audit.jsonl":
+            candidates.append(path)
+            continue
+        if include_raw_transcripts and path.suffix == ".txt":
+            candidates.append(path)
+    return sorted(candidates, key=lambda item: item.relative_to(run_dir).as_posix())
+
+
+def _add_bytes(tar: tarfile.TarFile, arcname: str, content: bytes) -> None:
+    info = tarfile.TarInfo(arcname)
+    info.size = len(content)
+    info.mtime = 0
+    info.mode = 0o644
+    info.uid = 0
+    info.gid = 0
+    info.uname = ""
+    info.gname = ""
+    tar.addfile(info, io.BytesIO(content))
+
+
+def _run_id(run_dir: Path) -> str:
+    summary_path = run_dir / "summary.json"
+    if summary_path.is_file() and not summary_path.is_symlink():
+        try:
+            summary = json.loads(summary_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            summary = {}
+        run_id = summary.get("run_id") if isinstance(summary, dict) else None
+        if isinstance(run_id, str):
+            return run_id
+    return run_dir.name
+
+
+def _bundle_name_component(run_dir: Path, *, run_id: str | None = None) -> str:
+    run_id = run_id if run_id is not None else _run_id(run_dir)
+    if run_id:
+        candidate = Path(run_id).name
+        if candidate not in {"", ".", ".."}:
+            return candidate
+    if run_dir.name not in {"", ".", ".."}:
+        return run_dir.name
+    return "run"
+
+
+def _suppression_audit_paths(run_dir: Path) -> list[Path]:
+    paths = []
+    for candidate in (
+        _owning_revrem_audit_path(run_dir),
+        suppressions.repo_audit_path(run_dir),
+        run_dir / ".revrem" / "suppressions.audit.jsonl",
+    ):
+        if candidate.is_file() and not candidate.is_symlink():
+            paths.append(candidate)
+    return sorted(set(paths))
+
+
+def _owning_revrem_audit_path(run_dir: Path) -> Path:
+    for ancestor in (run_dir, *run_dir.parents):
+        if ancestor.name == ".revrem":
+            return ancestor / "suppressions.audit.jsonl"
+    return run_dir / ".revrem" / "suppressions.audit.jsonl"
+
+
+def _merge_counts(target: dict[str, int], source: dict[str, int]) -> None:
+    for key, value in source.items():
+        target[key] = target.get(key, 0) + value