constraintloop 0.1.0__py3-none-any.whl

constraintloop/digest.py

@@ -0,0 +1,233 @@
+"""Content-addressed project snapshots and git context."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from collections.abc import Iterable
+from pathlib import Path, PurePosixPath
+
+from constraintloop.models import ConstraintSpec
+
+_IGNORED_PARTS = {
+    ".git",
+    ".constraintloop",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+}
+_SECRET_NAMES = {
+    ".env",
+    ".env.local",
+    ".env.production",
+    "credentials.json",
+    "secrets.env",
+}
+_SECRET_SUFFIXES = {".key", ".pem", ".p12", ".pfx"}
+_CREDENTIAL_ASSIGNMENT = re.compile(
+    r"(?i)\b(api[_-]?key|access[_-]?token|auth[_-]?token|password|secret)"
+    r"(\s*[:=]\s*[\"']?)([^\s,\"']{8,})"
+)
+
+
+def matching_files(project_root: Path, patterns: Iterable[str]) -> list[Path]:
+    """Return stable, unique files matching glob patterns under the project."""
+    found: dict[str, Path] = {}
+    for pattern in patterns:
+        for path in project_root.glob(pattern):
+            if not path.is_file():
+                continue
+            try:
+                relative = path.relative_to(project_root)
+                path.resolve().relative_to(project_root.resolve())
+            except ValueError:
+                continue
+            if any(part in _IGNORED_PARTS for part in relative.parts):
+                continue
+            found[relative.as_posix()] = path
+    return [found[key] for key in sorted(found)]
+
+
+def constraint_input_digest(
+    project_root: Path,
+    constraint_id: str,
+    spec: ConstraintSpec,
+    *,
+    contract_digest: str | None = None,
+) -> str:
+    digest = hashlib.sha256()
+    digest.update(constraint_id.encode())
+    if contract_digest is not None:
+        digest.update(contract_digest.encode())
+    digest.update(
+        json.dumps(spec.model_dump(mode="json"), sort_keys=True, separators=(",", ":")).encode()
+    )
+    for path in matching_files(project_root, spec.watch):
+        relative = path.relative_to(project_root).as_posix()
+        digest.update(relative.encode())
+        try:
+            digest.update(path.read_bytes())
+        except OSError as exc:
+            digest.update(f"<unreadable:{exc}>".encode())
+    return digest.hexdigest()
+
+
+def project_key(project_root: Path) -> str:
+    return hashlib.sha256(str(project_root.resolve()).encode()).hexdigest()[:20]
+
+
+def git_diff(
+    project_root: Path,
+    *,
+    patterns: Iterable[str] = ("**/*",),
+    limit: int | None = None,
+) -> str:
+    """Return staged, unstaged, and untracked changes as a bounded text bundle."""
+    pattern_list = list(patterns)
+    eligible = sorted(
+        {
+            relative
+            for group in _changed_path_groups(project_root, include_untracked=True)
+            if all(_allowed_disclosure_path(path, pattern_list) for path in group)
+            for relative in group
+        }
+    )
+    chunks: list[str] = []
+    for args in (["git", "diff", "--no-ext-diff"], ["git", "diff", "--cached", "--no-ext-diff"]):
+        if not eligible:
+            continue
+        try:
+            result = subprocess.run(
+                [*args, "--", *eligible],
+                cwd=project_root,
+                capture_output=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=15,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        if result.stdout:
+            chunks.append(result.stdout)
+
+    for relative in eligible:
+        path = project_root / relative
+        if not path.is_file() or _is_git_tracked(project_root, relative):
+            continue
+        try:
+            content = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        chunks.append(
+            f"diff --git a/{relative} b/{relative}\nnew file\n+++ b/{relative}\n{content}"
+        )
+
+    output = redact_text("\n".join(chunks))
+    if limit is not None and len(output.encode()) > limit:
+        return output.encode()[:limit].decode("utf-8", errors="ignore") + "\n[diff truncated]"
+    return output
+
+
+def changed_files(project_root: Path, *, include_untracked: bool = True) -> list[str]:
+    return sorted(
+        {
+            relative
+            for group in _changed_path_groups(project_root, include_untracked=include_untracked)
+            for relative in group
+        }
+    )
+
+
+def _changed_path_groups(project_root: Path, *, include_untracked: bool) -> list[tuple[str, ...]]:
+    args = ["git", "status", "--porcelain=v1", "--untracked-files=all", "-z"]
+    try:
+        result = subprocess.run(
+            args,
+            cwd=project_root,
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    changed: list[tuple[str, ...]] = []
+    entries = result.stdout.split("\0")
+    index = 0
+    while index < len(entries):
+        line = entries[index]
+        index += 1
+        if len(line) < 4:
+            continue
+        status = line[:2]
+        if status == "??" and not include_untracked:
+            continue
+        name = line[3:]
+        if any(marker in {"R", "C"} for marker in status) and index < len(entries):
+            previous_name = entries[index]
+            index += 1
+            changed.append((name, previous_name))
+        else:
+            changed.append((name,))
+    return changed
+
+
+def _allowed_disclosure_path(relative: str, patterns: list[str]) -> bool:
+    if not is_disclosable_path(relative):
+        return False
+    path = PurePosixPath(relative)
+    return any(
+        path.match(pattern)
+        or (pattern.startswith("**/") and path.match(pattern.removeprefix("**/")))
+        for pattern in patterns
+    )
+
+
+def is_disclosable_path(relative: str) -> bool:
+    path = PurePosixPath(relative)
+    name = path.name.lower()
+    return not (
+        name in _SECRET_NAMES
+        or (name.startswith(".env.") and name != ".env.example")
+        or path.suffix.lower() in _SECRET_SUFFIXES
+    )
+
+
+def redact_text(value: str) -> str:
+    redacted = value
+    for name, secret in os.environ.items():
+        if (
+            secret
+            and len(secret) >= 8
+            and any(marker in name.upper() for marker in ("KEY", "TOKEN", "SECRET", "PASSWORD"))
+        ):
+            redacted = redacted.replace(secret, "[REDACTED]")
+    return _CREDENTIAL_ASSIGNMENT.sub(
+        lambda match: f"{match.group(1)}{match.group(2)}[REDACTED]",
+        redacted,
+    )
+
+
+def _is_git_tracked(project_root: Path, relative: str) -> bool:
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "--error-unmatch", "--", relative],
+            cwd=project_root,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return result.returncode == 0

constraintloop/engine.py

@@ -0,0 +1,466 @@
+"""Constraint execution, evidence freshness, quorum, and policy decisions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any, cast
+
+from constraintloop.config import contract_digest
+from constraintloop.digest import (
+    changed_files,
+    constraint_input_digest,
+    git_diff,
+    is_disclosable_path,
+    matching_files,
+    redact_text,
+)
+from constraintloop.environment import load_project_environment
+from constraintloop.evaluators import EvaluatorError, build_evaluator
+from constraintloop.models import (
+    ArtifactConstraint,
+    CommandConstraint,
+    ConstraintResult,
+    Contract,
+    EvaluationBundle,
+    EvaluatorCallMetadata,
+    EvidenceRecord,
+    MetricConstraint,
+    Phase,
+    RubricConstraint,
+    Verdict,
+)
+from constraintloop.runners import (
+    run_artifact_constraint,
+    run_command_constraint,
+    run_metric_constraint,
+)
+from constraintloop.state import load_cached_result, save_cached_result, waiver_reason
+
+
+class ConstraintEngine:
+    """Run a strict contract against one project snapshot."""
+
+    def __init__(
+        self,
+        project_root: Path,
+        contract: Contract,
+        *,
+        use_cache: bool = True,
+        allow_waivers: bool = True,
+        goal: str | None = None,
+        agent_adapter: str | None = None,
+        refresh_pending: bool = False,
+    ):
+        self.project_root = project_root.resolve()
+        self.contract = contract
+        self.use_cache = use_cache
+        self.allow_waivers = allow_waivers
+        self.goal = goal
+        self.agent_adapter = agent_adapter
+        self.refresh_pending = refresh_pending
+        self.contract_digest = contract_digest(contract)
+
+    def run(self, phase: Phase) -> EvidenceRecord:
+        """Run applicable constraints in dependency order."""
+        started_at = time.time()
+        results: dict[str, ConstraintResult] = {}
+        pending = {
+            constraint_id
+            for constraint_id, spec in self.contract.constraints.items()
+            if spec.enabled and phase in spec.phases
+        }
+
+        while pending:
+            ready = sorted(
+                constraint_id
+                for constraint_id in pending
+                if all(
+                    dependency not in pending
+                    for dependency in self.contract.constraints[constraint_id].needs
+                )
+            )
+            if not ready:  # Contract validation should make this unreachable.
+                raise RuntimeError("No runnable constraints remain")
+            runnable: list[
+                tuple[
+                    str,
+                    CommandConstraint | MetricConstraint | ArtifactConstraint | RubricConstraint,
+                    str,
+                ]
+            ] = []
+            for constraint_id in ready:
+                spec = self.contract.constraints[constraint_id]
+                pending_dependencies = [
+                    dependency
+                    for dependency in spec.needs
+                    if dependency in results and results[dependency].verdict == Verdict.PENDING
+                ]
+                unavailable = [
+                    dependency
+                    for dependency in spec.needs
+                    if dependency not in results
+                    or results[dependency].verdict
+                    not in {
+                        Verdict.PASS,
+                        Verdict.WAIVED,
+                    }
+                ]
+                digest = constraint_input_digest(
+                    self.project_root,
+                    constraint_id,
+                    spec,
+                    contract_digest=self.contract_digest,
+                )
+                if pending_dependencies:
+                    result = ConstraintResult(
+                        constraint_id=constraint_id,
+                        kind=spec.kind,
+                        verdict=Verdict.PENDING,
+                        enforcement=spec.enforcement,
+                        input_digest=digest,
+                        message=f"Dependencies are pending: {', '.join(pending_dependencies)}",
+                    )
+                elif unavailable:
+                    result = ConstraintResult(
+                        constraint_id=constraint_id,
+                        kind=spec.kind,
+                        verdict=Verdict.ERROR,
+                        enforcement=spec.enforcement,
+                        input_digest=digest,
+                        message=f"Dependencies did not pass: {', '.join(unavailable)}",
+                    )
+                else:
+                    runnable.append((constraint_id, spec, digest))
+                    continue
+                results[constraint_id] = result
+
+            deterministic = [item for item in runnable if not isinstance(item[1], RubricConstraint)]
+            with ThreadPoolExecutor(
+                max_workers=min(self.contract.settings.concurrency, max(1, len(deterministic)))
+            ) as executor:
+                futures = {
+                    constraint_id: executor.submit(
+                        self._run_one,
+                        constraint_id,
+                        spec,
+                        digest,
+                        phase,
+                        [results[key] for key in self.contract.constraints if key in results],
+                    )
+                    for constraint_id, spec, digest in deterministic
+                }
+                for constraint_id, _, _ in deterministic:
+                    results[constraint_id] = futures[constraint_id].result()
+
+            for constraint_id, spec, digest in runnable:
+                if isinstance(spec, RubricConstraint):
+                    results[constraint_id] = self._run_one(
+                        constraint_id,
+                        spec,
+                        digest,
+                        phase,
+                        [results[key] for key in self.contract.constraints if key in results],
+                    )
+            pending.difference_update(ready)
+
+        record = EvidenceRecord(
+            run_id=str(uuid.uuid4()),
+            project_root=str(self.project_root),
+            contract_digest=self.contract_digest,
+            phase=phase,
+            started_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(started_at)),
+            results=[results[key] for key in self.contract.constraints if key in results],
+        )
+        return record
+
+    def _run_one(
+        self,
+        constraint_id: str,
+        spec: CommandConstraint | MetricConstraint | ArtifactConstraint | RubricConstraint,
+        digest: str,
+        phase: Phase,
+        prior_results: list[ConstraintResult],
+    ) -> ConstraintResult:
+        bundle = (
+            self._build_bundle(constraint_id, spec, prior_results)
+            if isinstance(spec, RubricConstraint)
+            else None
+        )
+        cache_digest = _rubric_cache_digest(digest, bundle) if bundle is not None else digest
+        if self.use_cache:
+            cached = load_cached_result(self.project_root, constraint_id, cache_digest)
+            if (
+                cached is not None
+                and cached.enforcement == spec.enforcement
+                and not (self.refresh_pending and cached.verdict == Verdict.PENDING)
+            ):
+                if (
+                    self.allow_waivers
+                    and phase != Phase.CI
+                    and not isinstance(spec, RubricConstraint)
+                ):
+                    reason = waiver_reason(self.project_root, cached, self.contract_digest)
+                    if reason:
+                        return cached.model_copy(
+                            update={
+                                "verdict": Verdict.WAIVED,
+                                "message": f"Locally waived by a human: {reason}",
+                            }
+                        )
+                return cached
+
+        if isinstance(spec, CommandConstraint):
+            result = run_command_constraint(
+                self.project_root,
+                constraint_id,
+                spec,
+                digest,
+                self.contract.settings.evidence_output_limit,
+            )
+        elif isinstance(spec, MetricConstraint):
+            result = run_metric_constraint(
+                self.project_root,
+                constraint_id,
+                spec,
+                digest,
+                self.contract.settings.evidence_output_limit,
+            )
+        elif isinstance(spec, ArtifactConstraint):
+            result = run_artifact_constraint(self.project_root, constraint_id, spec, digest)
+        else:
+            assert bundle is not None
+            result = self._run_rubric(constraint_id, spec, digest, bundle)
+
+        if self.use_cache:
+            save_cached_result(self.project_root, result, cache_digest=cache_digest)
+        return result
+
+    def _run_rubric(
+        self,
+        constraint_id: str,
+        spec: RubricConstraint,
+        digest: str,
+        bundle: EvaluationBundle,
+    ) -> ConstraintResult:
+        started = time.monotonic()
+        try:
+            environment = load_project_environment(self.project_root)
+        except ValueError as exc:
+            return ConstraintResult(
+                constraint_id=constraint_id,
+                kind=spec.kind,
+                verdict=Verdict.UNCERTAIN,
+                enforcement=spec.enforcement,
+                input_digest=digest,
+                message=f"Could not load evaluator environment: {exc}",
+                duration_ms=(time.monotonic() - started) * 1000,
+            )
+        if self.agent_adapter:
+            environment["CONSTRAINTLOOP_CALLER_ADAPTER"] = self.agent_adapter
+        evaluator = build_evaluator(
+            self.contract.evaluators[spec.evaluator],
+            cwd=self.project_root,
+            environment=environment,
+        )
+        verdicts = []
+        errors: list[str] = []
+        evaluator_calls: list[EvaluatorCallMetadata] = []
+        for _ in range(spec.runs):
+            try:
+                verdicts.append(evaluator.evaluate(bundle))
+            except EvaluatorError as exc:
+                errors.append(str(exc))
+            metadata = getattr(evaluator, "last_metadata", None)
+            if isinstance(metadata, EvaluatorCallMetadata):
+                evaluator_calls.append(metadata)
+
+        passes = sum(verdict.verdict == "pass" for verdict in verdicts)
+        fails = sum(verdict.verdict == "fail" for verdict in verdicts)
+        quorum = spec.pass_quorum or 1
+        findings = [finding for verdict in verdicts for finding in verdict.findings]
+        rationales = [verdict.rationale for verdict in verdicts]
+        if passes >= quorum:
+            verdict = Verdict.PASS
+            message = f"Rubric passed quorum ({passes}/{spec.runs}; required {quorum})"
+        elif errors or any(item.verdict == "uncertain" for item in verdicts):
+            verdict = Verdict.UNCERTAIN
+            message = f"Rubric did not reach a reliable quorum ({passes} pass, {fails} fail)"
+        else:
+            verdict = Verdict.FAIL
+            message = f"Rubric failed quorum ({passes}/{spec.runs}; required {quorum})"
+        details = rationales + errors
+        return ConstraintResult(
+            constraint_id=constraint_id,
+            kind=spec.kind,
+            verdict=verdict,
+            enforcement=spec.enforcement,
+            input_digest=digest,
+            message=message,
+            duration_ms=(time.monotonic() - started) * 1000,
+            output_tail="\n\n".join(details)[-self.contract.settings.evidence_output_limit :]
+            or None,
+            findings=findings,
+            evaluator_calls=evaluator_calls,
+        )
+
+    def _build_bundle(
+        self,
+        constraint_id: str,
+        spec: RubricConstraint,
+        deterministic_results: list[ConstraintResult],
+    ) -> EvaluationBundle:
+        limit = self.contract.settings.evaluation_bundle_limit
+        diff = git_diff(self.project_root, patterns=spec.include, limit=limit // 4)
+        used = len(diff.encode())
+        files: dict[str, str] = {}
+        omitted: list[str] = []
+        query = f"{constraint_id} {spec.rubric} {self.goal or ''}".lower()
+        query_tokens = set(re.findall(r"[a-z0-9]{3,}", query))
+        changed = set(changed_files(self.project_root))
+
+        def priority(path: Path) -> tuple[int, int, int, int, str]:
+            relative = path.relative_to(self.project_root).as_posix()
+            path_tokens = set(re.findall(r"[a-z0-9]{3,}", relative.lower()))
+            relevance = len(query_tokens & path_tokens)
+            source = int(relative.startswith(("src/", "lib/", "app/")))
+            try:
+                modified = path.stat().st_mtime_ns
+            except OSError:
+                modified = 0
+            return (-relevance, -int(relative in changed), -source, -modified, relative)
+
+        matched = matching_files(self.project_root, spec.include)
+        for path in matched:
+            relative = path.relative_to(self.project_root).as_posix()
+            if not is_disclosable_path(relative):
+                omitted.append(relative)
+        candidates = sorted(
+            (
+                path
+                for path in matched
+                if is_disclosable_path(path.relative_to(self.project_root).as_posix())
+            ),
+            key=priority,
+        )
+        for path in candidates:
+            relative = path.relative_to(self.project_root).as_posix()
+            try:
+                content = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                omitted.append(relative)
+                continue
+            cost = len(relative.encode()) + len(content.encode())
+            if used + cost > limit:
+                omitted.append(relative)
+                continue
+            files[relative] = redact_text(content)
+            used += cost
+        deterministic = [
+            cast(dict[str, Any], _redact_value(result.model_dump(mode="json")))
+            for result in deterministic_results
+        ]
+        bundle = EvaluationBundle(
+            constraint_id=constraint_id,
+            rubric=spec.rubric,
+            goal=self.goal,
+            diff=diff,
+            deterministic_results=deterministic,
+            files=files,
+            omitted_files=omitted,
+        )
+        while len(bundle.model_dump_json().encode()) > limit and files:
+            relative = next(reversed(files))
+            files.pop(relative)
+            omitted.append(relative)
+            bundle = bundle.model_copy(
+                update={"files": dict(files), "omitted_files": list(omitted)}
+            )
+        if len(bundle.model_dump_json().encode()) > limit and bundle.diff:
+            overflow = len(bundle.model_dump_json().encode()) - limit
+            keep = max(0, len(bundle.diff.encode()) - overflow - 32)
+            bundle = bundle.model_copy(
+                update={
+                    "diff": bundle.diff.encode()[:keep].decode("utf-8", errors="ignore")
+                    + "\n[diff truncated]"
+                }
+            )
+        if len(bundle.model_dump_json().encode()) > limit:
+            compact = []
+            for item in deterministic:
+                compact.append(
+                    {
+                        key: value
+                        for key, value in item.items()
+                        if key
+                        in {
+                            "constraint_id",
+                            "kind",
+                            "verdict",
+                            "enforcement",
+                            "message",
+                            "cached",
+                        }
+                    }
+                )
+            bundle = bundle.model_copy(update={"deterministic_results": compact})
+        return bundle
+
+
+def blocking_results(record: EvidenceRecord) -> list[ConstraintResult]:
+    return [result for result in record.results if result.blocks]
+
+
+def _redact_value(value: object) -> object:
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, list):
+        return [_redact_value(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _redact_value(item) for key, item in value.items()}
+    return value
+
+
+def _rubric_cache_digest(base_digest: str, bundle: EvaluationBundle) -> str:
+    payload = bundle.model_dump(mode="json")
+    for result in payload["deterministic_results"]:
+        for volatile in ("cached", "duration_ms", "evaluator_calls"):
+            result.pop(volatile, None)
+    digest = hashlib.sha256()
+    digest.update(base_digest.encode())
+    digest.update(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode())
+    return digest.hexdigest()
+
+
+def format_summary(record: EvidenceRecord, *, include_output: bool = False) -> str:
+    has_advisories = record.passed and any(
+        result.verdict
+        not in {
+            Verdict.PASS,
+            Verdict.SKIPPED,
+            Verdict.WAIVED,
+        }
+        for result in record.results
+    )
+    outcome = "PASS WITH ADVISORIES" if has_advisories else "PASS" if record.passed else "BLOCKED"
+    lines = [f"ConstraintLoop {record.phase.value}: {outcome} ({len(record.results)} constraints)"]
+    icons = {
+        Verdict.PASS: "PASS",
+        Verdict.PENDING: "PENDING",
+        Verdict.FAIL: "FAIL",
+        Verdict.ERROR: "ERROR",
+        Verdict.SKIPPED: "SKIP",
+        Verdict.UNCERTAIN: "UNCERTAIN",
+        Verdict.WAIVED: "WAIVED",
+    }
+    for result in record.results:
+        cache = " [cached]" if result.cached else ""
+        lines.append(f"- {icons[result.verdict]} {result.constraint_id}{cache}: {result.message}")
+        if include_output and result.output_tail and result.verdict != Verdict.PASS:
+            lines.append(result.output_tail)
+    return "\n".join(lines)