constraintloop 0.1.0__py3-none-any.whl

constraintloop/runners.py

@@ -0,0 +1,290 @@
+"""Deterministic constraint runners."""
+
+from __future__ import annotations
+
+import json
+import operator
+import re
+import subprocess
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, cast
+
+from constraintloop.models import (
+    ArtifactConstraint,
+    CommandConstraint,
+    ConstraintResult,
+    Enforcement,
+    MetricConstraint,
+    Verdict,
+)
+
+_OPS: dict[str, Callable[[float, float], bool]] = {
+    "gt": operator.gt,
+    "gte": operator.ge,
+    "lt": operator.lt,
+    "lte": operator.le,
+    "eq": operator.eq,
+}
+
+
+def run_command_constraint(
+    project_root: Path,
+    constraint_id: str,
+    spec: CommandConstraint,
+    input_digest: str,
+    output_limit: int,
+) -> ConstraintResult:
+    started = time.monotonic()
+    execution = _run_command(project_root, spec.command, spec.shell, spec.cwd, spec.timeout_seconds)
+    duration = (time.monotonic() - started) * 1000
+    if isinstance(execution, str):
+        return _error_result(
+            constraint_id, spec.kind, spec.enforcement, input_digest, execution, duration
+        )
+    returncode, stdout, stderr = execution
+    if returncode in spec.pending_codes:
+        return ConstraintResult(
+            constraint_id=constraint_id,
+            kind=spec.kind,
+            verdict=Verdict.PENDING,
+            enforcement=spec.enforcement,
+            input_digest=input_digest,
+            message=f"Command is pending (exit code {returncode})",
+            duration_ms=duration,
+            exit_code=returncode,
+            output_tail=_output_tail(stdout, stderr, output_limit) or None,
+        )
+    passed = returncode in spec.success_codes
+    output = _output_tail(stdout, stderr, output_limit)
+    return ConstraintResult(
+        constraint_id=constraint_id,
+        kind=spec.kind,
+        verdict=Verdict.PASS if passed else Verdict.FAIL,
+        enforcement=spec.enforcement,
+        input_digest=input_digest,
+        message="Command passed" if passed else f"Command exited with code {returncode}",
+        duration_ms=duration,
+        exit_code=returncode,
+        output_tail=output or None,
+    )
+
+
+def run_metric_constraint(
+    project_root: Path,
+    constraint_id: str,
+    spec: MetricConstraint,
+    input_digest: str,
+    output_limit: int,
+) -> ConstraintResult:
+    started = time.monotonic()
+    execution = _run_command(project_root, spec.command, spec.shell, spec.cwd, spec.timeout_seconds)
+    duration = (time.monotonic() - started) * 1000
+    if isinstance(execution, str):
+        return _error_result(
+            constraint_id, spec.kind, spec.enforcement, input_digest, execution, duration
+        )
+    returncode, stdout, stderr = execution
+    output = _output_tail(stdout, stderr, output_limit)
+    if returncode in spec.pending_codes:
+        return ConstraintResult(
+            constraint_id=constraint_id,
+            kind=spec.kind,
+            verdict=Verdict.PENDING,
+            enforcement=spec.enforcement,
+            input_digest=input_digest,
+            message=f"Metric is pending (exit code {returncode})",
+            duration_ms=duration,
+            exit_code=returncode,
+            output_tail=output or None,
+        )
+    if returncode not in spec.success_codes:
+        return ConstraintResult(
+            constraint_id=constraint_id,
+            kind=spec.kind,
+            verdict=Verdict.FAIL,
+            enforcement=spec.enforcement,
+            input_digest=input_digest,
+            message=f"Metric command exited with code {returncode}",
+            duration_ms=duration,
+            exit_code=returncode,
+            output_tail=output or None,
+        )
+    try:
+        value = _parse_metric(project_root / spec.cwd, spec, stdout, stderr)
+    except (ValueError, OSError, json.JSONDecodeError, re.error) as exc:
+        return _error_result(
+            constraint_id,
+            spec.kind,
+            spec.enforcement,
+            input_digest,
+            f"Could not parse metric: {exc}",
+            duration,
+            output,
+        )
+    passed = _OPS[spec.threshold.operator](value, spec.threshold.value)
+    return ConstraintResult(
+        constraint_id=constraint_id,
+        kind=spec.kind,
+        verdict=Verdict.PASS if passed else Verdict.FAIL,
+        enforcement=spec.enforcement,
+        input_digest=input_digest,
+        message=(
+            f"Metric {value:g} satisfies {spec.threshold.operator} {spec.threshold.value:g}"
+            if passed
+            else (
+                f"Metric {value:g} does not satisfy "
+                f"{spec.threshold.operator} {spec.threshold.value:g}"
+            )
+        ),
+        duration_ms=duration,
+        exit_code=returncode,
+        value=value,
+        output_tail=output or None,
+    )
+
+
+def run_artifact_constraint(
+    project_root: Path,
+    constraint_id: str,
+    spec: ArtifactConstraint,
+    input_digest: str,
+) -> ConstraintResult:
+    started = time.monotonic()
+    path = (project_root / spec.path).resolve()
+    try:
+        path.relative_to(project_root.resolve())
+    except ValueError:
+        return _error_result(
+            constraint_id,
+            spec.kind,
+            spec.enforcement,
+            input_digest,
+            "Artifact path escapes the project root",
+            0,
+        )
+    if not path.is_file():
+        verdict, message = Verdict.FAIL, f"Required artifact does not exist: {spec.path}"
+    elif spec.non_empty and path.stat().st_size == 0:
+        verdict, message = Verdict.FAIL, f"Required artifact is empty: {spec.path}"
+    else:
+        try:
+            if spec.format == "json":
+                json.loads(path.read_text(encoding="utf-8"))
+            elif spec.format == "junit":
+                import xml.etree.ElementTree as ET
+
+                ET.parse(path)
+            verdict, message = Verdict.PASS, f"Artifact is present: {spec.path}"
+        except (OSError, json.JSONDecodeError, ValueError) as exc:
+            verdict, message = Verdict.FAIL, f"Artifact is invalid: {exc}"
+    return ConstraintResult(
+        constraint_id=constraint_id,
+        kind=spec.kind,
+        verdict=verdict,
+        enforcement=spec.enforcement,
+        input_digest=input_digest,
+        message=message,
+        duration_ms=(time.monotonic() - started) * 1000,
+    )
+
+
+def _run_command(
+    project_root: Path,
+    command: list[str] | str,
+    shell: bool,
+    cwd: str,
+    timeout: float,
+) -> tuple[int, str, str] | str:
+    working_dir = (project_root / cwd).resolve()
+    try:
+        working_dir.relative_to(project_root.resolve())
+    except ValueError:
+        return f"Command cwd escapes the project root: {cwd}"
+    if not working_dir.is_dir():
+        return f"Command cwd does not exist: {cwd}"
+    try:
+        result = subprocess.run(
+            command,
+            shell=shell,
+            cwd=working_dir,
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return f"Command timed out after {timeout:g}s"
+    except (FileNotFoundError, OSError) as exc:
+        return f"Command could not start: {exc}"
+    return result.returncode, result.stdout or "", result.stderr or ""
+
+
+def _parse_metric(
+    cwd: Path,
+    spec: MetricConstraint,
+    stdout: str,
+    stderr: str,
+) -> float:
+    parser = spec.parser
+    if parser.source == "stdout":
+        raw = stdout
+    elif parser.source == "stderr":
+        raw = stderr
+    else:
+        assert parser.file is not None
+        metric_path = (cwd / parser.file).resolve()
+        try:
+            metric_path.relative_to(cwd.resolve())
+        except ValueError as exc:
+            raise ValueError("metric file escapes the constraint cwd") from exc
+        raw = metric_path.read_text(encoding="utf-8")
+
+    if parser.type == "regex":
+        assert parser.pattern is not None
+        match = re.search(parser.pattern, raw, re.MULTILINE)
+        if not match:
+            raise ValueError("regex did not match")
+        return float(match.group(parser.group))
+
+    assert parser.path is not None
+    value: object = json.loads(raw)
+    for part in parser.path.split("."):
+        if isinstance(value, list):
+            value = value[int(part)]
+        elif isinstance(value, dict):
+            value = value[part]
+        else:
+            raise ValueError(f"path stopped before {part!r}")
+    return float(cast(Any, value))
+
+
+def _output_tail(stdout: str, stderr: str, limit: int) -> str:
+    combined = "\n".join(part for part in (stdout.strip(), stderr.strip()) if part)
+    encoded = combined.encode()
+    if len(encoded) <= limit:
+        return combined
+    return "[output truncated]\n" + encoded[-limit:].decode("utf-8", errors="replace")
+
+
+def _error_result(
+    constraint_id: str,
+    kind: str,
+    enforcement: Enforcement,
+    input_digest: str,
+    message: str,
+    duration: float,
+    output: str | None = None,
+) -> ConstraintResult:
+    return ConstraintResult(
+        constraint_id=constraint_id,
+        kind=kind,
+        verdict=Verdict.ERROR,
+        enforcement=enforcement,
+        input_digest=input_digest,
+        message=message,
+        duration_ms=duration,
+        output_tail=output or None,
+    )

constraintloop/scaffold.py

@@ -0,0 +1,181 @@
+"""Project detection and explicit contract/proposal generation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def initial_contract(project_root: Path) -> dict[str, Any]:
+    constraints: dict[str, Any] = {
+        "diff_hygiene": {
+            "kind": "command",
+            "description": "Reject whitespace errors in the patch",
+            "command": ["git", "diff", "--check"],
+            "phases": ["change", "stop", "ci"],
+            "watch": ["**/*"],
+        }
+    }
+    pyproject = project_root / "pyproject.toml"
+    if pyproject.is_file():
+        uses_uv = (project_root / "uv.lock").is_file()
+        venv_python = project_root / ".venv" / "bin" / "python"
+        venv_pytest = project_root / ".venv" / "bin" / "pytest"
+        uv = ["uv", "--cache-dir", ".constraintloop/uv-cache", "run"]
+        if venv_python.is_file() and venv_pytest.is_file():
+            python = [".venv/bin/python"]
+            pytest = [".venv/bin/pytest"]
+        else:
+            python = [*uv, "python"] if uses_uv else ["python"]
+            pytest = [*uv, "pytest"] if uses_uv else ["python", "-m", "pytest"]
+        constraints["python_syntax"] = {
+            "kind": "command",
+            "command": [*python, "-m", "compileall", "-q", "."],
+            "phases": ["change", "stop", "ci"],
+            "watch": ["**/*.py"],
+        }
+        if (project_root / "tests").is_dir() or "pytest" in pyproject.read_text(
+            encoding="utf-8", errors="ignore"
+        ):
+            constraints["tests"] = {
+                "kind": "command",
+                "command": [*pytest, "-q"],
+                "phases": ["stop", "ci"],
+                "watch": ["**/*.py", "pyproject.toml"],
+                "needs": ["python_syntax"],
+            }
+
+    package_json = project_root / "package.json"
+    if package_json.is_file():
+        try:
+            scripts = json.loads(package_json.read_text(encoding="utf-8")).get("scripts", {})
+        except (OSError, json.JSONDecodeError):
+            scripts = {}
+        for name in ("lint", "typecheck", "test"):
+            if name in scripts:
+                constraint_id = f"npm_{name}"
+                constraints[constraint_id] = {
+                    "kind": "command",
+                    "command": ["npm", "run", name],
+                    "phases": ["stop", "ci"],
+                    "watch": ["src/**/*", "test/**/*", "tests/**/*", "package.json"],
+                }
+
+    return {
+        "version": 1,
+        "settings": {
+            "max_auto_retries": 2,
+            "concurrency": 4,
+            "evidence_output_limit": 65536,
+            "evaluation_bundle_limit": 102400,
+        },
+        "constraints": constraints,
+        "evaluators": {},
+    }
+
+
+def write_initial_contract(project_root: Path) -> Path:
+    path = project_root / "constraintloop.yml"
+    path.write_text(
+        "# Generated by ConstraintLoop. Every gate is explicit and reviewable.\n"
+        + yaml.safe_dump(initial_contract(project_root), sort_keys=False),
+        encoding="utf-8",
+    )
+    return path
+
+
+def enhancement_proposal(project_root: Path) -> dict[str, Any]:
+    suggestions: list[dict[str, Any]] = []
+    if (project_root / "pyproject.toml").is_file():
+        suggestions.extend(
+            [
+                {
+                    "id": "ruff",
+                    "reason": "Fast deterministic linting for Python",
+                    "dependency": "ruff",
+                    "constraint": {
+                        "kind": "command",
+                        "command": ["python", "-m", "ruff", "check", "."],
+                        "phases": ["change", "stop", "ci"],
+                        "watch": ["**/*.py", "pyproject.toml"],
+                    },
+                },
+                {
+                    "id": "coverage",
+                    "reason": "Measure exercised lines; choose the threshold deliberately",
+                    "dependency": "pytest-cov",
+                    "constraint": {
+                        "kind": "command",
+                        "command": ["python", "-m", "pytest", "--cov", "--cov-fail-under=80"],
+                        "phases": ["stop", "ci"],
+                        "watch": ["**/*.py", "pyproject.toml"],
+                    },
+                },
+                {
+                    "id": "mutation",
+                    "reason": "Check whether tests detect behavioral mutations",
+                    "dependency": "mutmut",
+                    "constraint": {
+                        "kind": "command",
+                        "command": ["python", "-m", "mutmut", "run"],
+                        "phases": ["ci"],
+                        "watch": ["**/*.py", "pyproject.toml"],
+                        "timeout_seconds": 1800,
+                    },
+                },
+            ]
+        )
+    if (project_root / "package.json").is_file():
+        suggestions.append(
+            {
+                "id": "mutation",
+                "reason": "Check whether tests detect behavioral mutations",
+                "dependency": "@stryker-mutator/core",
+                "constraint": {
+                    "kind": "command",
+                    "command": ["npx", "stryker", "run"],
+                    "phases": ["ci"],
+                    "watch": ["src/**/*", "test/**/*", "tests/**/*", "package.json"],
+                    "timeout_seconds": 1800,
+                },
+            }
+        )
+    return {"schema_version": 1, "mode": "proposal_only", "suggestions": suggestions}
+
+
+def authoring_proposal(project_root: Path) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "mode": "proposal_only",
+        "rules": [
+            "Generated tests must be reviewed before adoption.",
+            "A generated test may not weaken or replace an existing required gate.",
+            "Prefer behavioral assertions over implementation snapshots.",
+        ],
+        "candidates": [
+            {
+                "type": "acceptance_test",
+                "status": "needs_human_specification",
+                "prompt": "Describe the user-visible behavior and failure cases to encode.",
+            },
+            {
+                "type": "mutation_survivor_test",
+                "status": "needs_mutation_report",
+                "prompt": (
+                    "Add focused tests for surviving mutations without changing "
+                    "production behavior."
+                ),
+            },
+        ],
+    }
+
+
+def write_proposal(project_root: Path, name: str, payload: dict[str, Any]) -> Path:
+    directory = project_root / ".constraintloop" / "proposals"
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{name}.yml"
+    path.write_text(yaml.safe_dump(payload, sort_keys=False), encoding="utf-8")
+    return path

constraintloop/setup_hooks.py

@@ -0,0 +1,191 @@
+"""Idempotent hook installation for supported coding agents."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sys
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+ADAPTERS: dict[str, tuple[Path, dict[str, str]]] = {
+    "claude": (
+        Path(".claude/settings.json"),
+        {
+            "SessionStart": "session-start",
+            "UserPromptSubmit": "user-prompt",
+            "PreToolUse": "pre-tool",
+            "PostToolUse": "post-tool",
+            "PreCompact": "pre-compact",
+            "Stop": "stop",
+        },
+    ),
+    "codex": (
+        Path(".codex/hooks.json"),
+        {
+            "SessionStart": "session-start",
+            "UserPromptSubmit": "user-prompt",
+            "PreToolUse": "pre-tool",
+            "PostToolUse": "post-tool",
+            "PreCompact": "pre-compact",
+            "Stop": "stop",
+        },
+    ),
+    "gemini": (
+        Path(".gemini/settings.json"),
+        {
+            "SessionStart": "session-start",
+            "BeforeAgent": "user-prompt",
+            "BeforeTool": "pre-tool",
+            "AfterTool": "post-tool",
+            "PreCompress": "pre-compact",
+            "AfterAgent": "stop",
+        },
+    ),
+}
+
+
+def install_hooks(project_root: Path, adapter: str) -> Path:
+    relative, events = ADAPTERS[adapter]
+    path = project_root / relative
+    try:
+        data: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        data = {}
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Refusing to overwrite invalid hook settings {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"Refusing to overwrite non-object hook settings {path}")
+    hooks = data.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise ValueError(f"Existing hooks value is not an object in {path}")
+    executable = _portable_executable(project_root)
+    project_argument = '"$(git rev-parse --show-toplevel)"'
+    for native_event, event in events.items():
+        command = (
+            f"{executable} hook --adapter {adapter} --event {event} --project {project_argument}"
+        )
+        groups = hooks.setdefault(native_event, [])
+        _validate_event_groups(path, native_event, groups)
+        if _has_or_update_command(groups, command, adapter, event):
+            continue
+        hook: dict[str, Any] = {
+            "type": "command",
+            "command": command,
+            "statusMessage": f"ConstraintLoop: {event}",
+        }
+        if adapter == "gemini":
+            hook["name"] = f"constraintloop-{event}"
+        group: dict[str, Any] = {"hooks": [hook]}
+        if native_event in {"PreToolUse", "PostToolUse", "BeforeTool", "AfterTool"}:
+            group["matcher"] = (
+                "Bash|Edit|Write"
+                if adapter in {"claude", "codex"}
+                else "run_shell_command|write_file|replace"
+            )
+        groups.append(group)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _write_settings(path, data)
+    return path
+
+
+def _portable_executable(project_root: Path) -> str:
+    """Return a hook executable without embedding machine-specific paths."""
+    executable_path = Path(sys.argv[0]).resolve()
+    if executable_path.name == "__main__.py":
+        return "python -m constraintloop"
+    try:
+        relative = executable_path.relative_to(project_root.resolve())
+    except ValueError:
+        return shlex.quote(executable_path.name)
+    return f'"$(git rev-parse --show-toplevel)/{relative.as_posix()}"'
+
+
+def uninstall_hooks(project_root: Path, adapter: str) -> tuple[Path, int]:
+    """Remove only ConstraintLoop hook entries and preserve all user settings."""
+    relative, _ = ADAPTERS[adapter]
+    path = project_root / relative
+    try:
+        data: Any = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return path, 0
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Refusing to modify invalid hook settings {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"Refusing to modify non-object hook settings {path}")
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return path, 0
+
+    marker = f" hook --adapter {adapter} "
+    removed = 0
+    for event, groups in list(hooks.items()):
+        if not isinstance(groups, list):
+            continue
+        retained_groups: list[Any] = []
+        for group in groups:
+            if not isinstance(group, dict) or not isinstance(group.get("hooks"), list):
+                retained_groups.append(group)
+                continue
+            retained_entries = []
+            for entry in group["hooks"]:
+                command = entry.get("command") if isinstance(entry, dict) else None
+                if isinstance(command, str) and "constraintloop" in command and marker in command:
+                    removed += 1
+                else:
+                    retained_entries.append(entry)
+            if retained_entries:
+                retained_group = dict(group)
+                retained_group["hooks"] = retained_entries
+                retained_groups.append(retained_group)
+        if retained_groups:
+            hooks[event] = retained_groups
+        else:
+            hooks.pop(event)
+    if removed:
+        _write_settings(path, data)
+    return path, removed
+
+
+def _write_settings(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(data, indent=2) + "\n")
+        os.replace(temporary, path)
+    finally:
+        with suppress(FileNotFoundError):
+            os.unlink(temporary)
+
+
+def _validate_event_groups(path: Path, event: str, groups: object) -> None:
+    if not isinstance(groups, list):
+        raise ValueError(f"Existing {event} hooks value is not a list in {path}")
+    for group in groups:
+        if not isinstance(group, dict) or not isinstance(group.get("hooks"), list):
+            raise ValueError(f"Existing {event} hook group is invalid in {path}")
+        if any(not isinstance(entry, dict) for entry in group["hooks"]):
+            raise ValueError(f"Existing {event} hook entry is invalid in {path}")
+
+
+def _has_or_update_command(groups: object, command: str, adapter: str, event: str) -> bool:
+    if not isinstance(groups, list):
+        return False
+    marker = f" hook --adapter {adapter} --event {event}"
+    for group in groups:
+        if not isinstance(group, dict):
+            continue
+        for hook in group.get("hooks", []):
+            if not isinstance(hook, dict):
+                continue
+            existing = hook.get("command")
+            if existing == command:
+                return True
+            if isinstance(existing, str) and "constraintloop" in existing and marker in existing:
+                hook["command"] = command
+                return True
+    return False