openworkproof 1.0.0__py3-none-any.whl

openworkproof/predicates.py

@@ -0,0 +1,333 @@
+"""Finite, fail-closed predicate evaluation for protocol v0.1."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Literal
+
+from openworkproof.models import (
+    ArtifactDigestPredicateInput,
+    HumanSignaturePredicateInput,
+    PathAllowedPredicateInput,
+    PredicateInput,
+    PredicateResult,
+    PredicateSpec,
+    QuotaRemainingPredicateInput,
+    TestsPassedPredicateInput,
+    ToolAllowedPredicateInput,
+    WorkOrder,
+    _jcs_digest,
+)
+
+
+EvaluationOutcome = Literal["pass", "false", "fail_closed"]
+
+
+def _immutable_snapshot(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return MappingProxyType(
+            {key: _immutable_snapshot(item) for key, item in value.items()}
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(_immutable_snapshot(item) for item in value)
+    if isinstance(value, (set, frozenset)):
+        return frozenset(_immutable_snapshot(item) for item in value)
+    return deepcopy(value)
+
+
+@dataclass(frozen=True)
+class EvaluationContext:
+    """Trusted runtime facts and closed actual inputs for one evaluation step."""
+
+    inputs: Mapping[str, Any] = field(default_factory=dict)
+    authoritative_inputs: Mapping[str, Any] = field(default_factory=dict)
+    authoritative_ledger_prefix_digests: Mapping[str, str] = field(
+        default_factory=dict
+    )
+    verified_human_claim_digests: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "inputs", _immutable_snapshot(self.inputs))
+        object.__setattr__(
+            self,
+            "authoritative_inputs",
+            _immutable_snapshot(self.authoritative_inputs),
+        )
+        object.__setattr__(
+            self,
+            "authoritative_ledger_prefix_digests",
+            _immutable_snapshot(self.authoritative_ledger_prefix_digests),
+        )
+        object.__setattr__(
+            self,
+            "verified_human_claim_digests",
+            frozenset(self.verified_human_claim_digests),
+        )
+
+    @classmethod
+    def empty(cls) -> EvaluationContext:
+        return cls()
+
+
+def _is_within(path: str, roots: Sequence[str]) -> bool:
+    return any(path == root or path.startswith(f"{root}/") for root in roots)
+
+
+def evaluate_path_allowed(
+    spec: PredicateSpec,
+    value: PredicateInput,
+    context: EvaluationContext,
+) -> EvaluationOutcome:
+    del context
+    assert isinstance(value, PathAllowedPredicateInput)
+    roots = tuple(spec.arguments["allowed_roots"])
+    if value.resolution_manifest_digest is None:
+        return "false"
+    if any(entry.resolved_relative_path is None for entry in value.resolved_entries):
+        return "fail_closed"
+    if not all(_is_within(path, roots) for path in value.requested_paths):
+        return "false"
+    if not all(
+        _is_within(entry.resolved_relative_path, roots)
+        for entry in value.resolved_entries
+        if entry.resolved_relative_path is not None
+    ):
+        return "false"
+    return "pass"
+
+
+def evaluate_tool_allowed(
+    spec: PredicateSpec,
+    value: PredicateInput,
+    context: EvaluationContext,
+) -> EvaluationOutcome:
+    del context
+    assert isinstance(value, ToolAllowedPredicateInput)
+    actual = value.actual_tool_name
+    return (
+        "pass"
+        if actual == spec.arguments["tool_name"]
+        and actual in spec.arguments["allowed_tools"]
+        else "false"
+    )
+
+
+def evaluate_quota_remaining(
+    spec: PredicateSpec,
+    value: PredicateInput,
+    context: EvaluationContext,
+) -> EvaluationOutcome:
+    assert isinstance(value, QuotaRemainingPredicateInput)
+    authoritative = context.authoritative_ledger_prefix_digests.get(value.grant_id)
+    if authoritative is None or authoritative != value.ledger_prefix_digest:
+        return "fail_closed"
+    if (
+        value.metric != spec.arguments["metric"]
+        or value.amount != spec.arguments["amount"]
+    ):
+        return "false"
+    return (
+        "pass" if value.grant_remaining_before >= value.amount else "false"
+    )
+
+
+def evaluate_tests_passed(
+    spec: PredicateSpec,
+    value: PredicateInput,
+    context: EvaluationContext,
+) -> EvaluationOutcome:
+    del context
+    assert isinstance(value, TestsPassedPredicateInput)
+    if value.actual_exit_code is None or value.test_evidence_digest is None:
+        return "fail_closed"
+    expected = spec.arguments
+    if (
+        value.test_mode != expected["test_mode"]
+        or value.command_digest != expected["command_digest"]
+        or value.expected_exit_code != expected["expected_exit_code"]
+        or value.fixed_test_source_digest
+        != expected["fixed_test_source_digest"]
+    ):
+        return "false"
+    return (
+        "pass"
+        if value.actual_exit_code == value.expected_exit_code
+        else "false"
+    )
+
+
+def evaluate_artifact_digest_matches(
+    spec: PredicateSpec,
+    value: PredicateInput,
+    context: EvaluationContext,
+) -> EvaluationOutcome:
+    del context
+    assert isinstance(value, ArtifactDigestPredicateInput)
+    if (
+        value.actual_digest is None
+        or value.size_bytes is None
+        or value.workspace_manifest_digest is None
+    ):
+        return "fail_closed"
+    if (
+        value.artifact_path != spec.arguments["artifact_path"]
+        or value.expected_digest != spec.arguments["expected_digest"]
+    ):
+        return "false"
+    return (
+        "pass" if value.actual_digest == value.expected_digest else "false"
+    )
+
+
+def evaluate_human_signature_present(
+    spec: PredicateSpec,
+    value: PredicateInput,
+    context: EvaluationContext,
+) -> EvaluationOutcome:
+    assert isinstance(value, HumanSignaturePredicateInput)
+    if value.claim_digest not in context.verified_human_claim_digests:
+        return "fail_closed"
+    if value.required_role != spec.arguments["required_role"]:
+        return "false"
+    if value.expires_at is not None and value.validated_at > value.expires_at:
+        return "false"
+    return "pass"
+
+
+PREDICATE_EVALUATORS = {
+    "path_allowed": evaluate_path_allowed,
+    "tool_allowed": evaluate_tool_allowed,
+    "quota_remaining": evaluate_quota_remaining,
+    "tests_passed": evaluate_tests_passed,
+    "artifact_digest_matches": evaluate_artifact_digest_matches,
+    "human_signature_present": evaluate_human_signature_present,
+}
+
+_INPUT_MODELS = {
+    "path_allowed": PathAllowedPredicateInput,
+    "tool_allowed": ToolAllowedPredicateInput,
+    "quota_remaining": QuotaRemainingPredicateInput,
+    "tests_passed": TestsPassedPredicateInput,
+    "artifact_digest_matches": ArtifactDigestPredicateInput,
+    "human_signature_present": HumanSignaturePredicateInput,
+}
+
+
+def predicate_input_digest(predicate_id: str, value: PredicateInput) -> str:
+    return _jcs_digest(
+        {
+            "domain": "openworkproof/predicate-input/v0.1",
+            "predicate_id": predicate_id,
+            "input": value,
+        }
+    )
+
+
+def evaluate_predicate(
+    spec: PredicateSpec,
+    context: EvaluationContext,
+) -> PredicateResult:
+    spec = PredicateSpec.model_validate(spec.model_dump(mode="json"))
+    evaluator = PREDICATE_EVALUATORS.get(spec.name)
+    input_model = _INPUT_MODELS.get(spec.name)
+    if evaluator is None or input_model is None:
+        raise ValueError("unknown predicate")
+    if spec.predicate_id not in context.inputs:
+        raise ValueError("closed predicate input is required")
+
+    value = input_model.model_validate(context.inputs[spec.predicate_id])
+    authoritative_raw = context.authoritative_inputs.get(spec.predicate_id)
+    if authoritative_raw is None:
+        outcome: EvaluationOutcome = "fail_closed"
+    else:
+        try:
+            authoritative = input_model.model_validate(authoritative_raw)
+        except Exception:
+            outcome = "fail_closed"
+        else:
+            outcome = (
+                "fail_closed"
+                if value != authoritative
+                else "pass"
+            )
+    try:
+        if outcome == "pass":
+            outcome = evaluator(spec, value, context)
+    except Exception:
+        outcome = "fail_closed"
+
+    return PredicateResult(
+        predicate_id=spec.predicate_id,
+        name=spec.name,
+        version=spec.version,
+        arguments_digest=_jcs_digest(spec.arguments),
+        input=value.model_dump(mode="json"),
+        input_digest=predicate_input_digest(spec.predicate_id, value),
+        passed=outcome == "pass",
+        error_code=(
+            None
+            if outcome == "pass"
+            else "PREDICATE_FALSE"
+            if outcome == "false"
+            else "FAIL_CLOSED"
+        ),
+    )
+
+
+def evaluate_required_predicates(
+    specs: Sequence[PredicateSpec],
+    context: EvaluationContext,
+) -> tuple[PredicateResult, ...]:
+    ids = tuple(spec.predicate_id for spec in specs)
+    if ids != tuple(sorted(set(ids))):
+        raise ValueError("predicate specs must be sorted and unique")
+    return tuple(evaluate_predicate(spec, context) for spec in specs)
+
+
+def select_required_predicates(
+    *,
+    work_order: WorkOrder,
+    tool_name: str,
+    policy_decision: str,
+    execution_status: str,
+    test_mode: str,
+) -> tuple[PredicateSpec, ...]:
+    valid_outcomes = {
+        ("deny", "denied"),
+        ("allow", "succeeded"),
+        ("allow", "failed"),
+    }
+    if (policy_decision, execution_status) not in valid_outcomes:
+        raise ValueError("invalid policy/execution outcome")
+    if test_mode not in {"developer", "verifier"}:
+        raise ValueError("invalid test mode")
+
+    selected = [
+        spec
+        for spec in work_order.preconditions + work_order.invariants
+        if tool_name in spec.applies_to_tools
+    ]
+    if (
+        policy_decision == "allow"
+        and test_mode == "verifier"
+        and execution_status in {"succeeded", "failed"}
+    ):
+        selected.extend(
+            spec
+            for spec in work_order.postconditions
+            if tool_name in spec.applies_to_tools
+        )
+    return tuple(sorted(selected, key=lambda spec: spec.predicate_id))
+
+
+__all__ = [
+    "EvaluationContext",
+    "PREDICATE_EVALUATORS",
+    "evaluate_predicate",
+    "evaluate_required_predicates",
+    "predicate_input_digest",
+    "select_required_predicates",
+]

openworkproof/repo_pipeline/__init__.py

@@ -0,0 +1,74 @@
+"""Repository read-and-analysis pipeline.
+
+Public entry point::
+
+    from openworkproof.repo_pipeline import analyze_repository
+
+    analysis = analyze_repository("/path/to/repo")   # local path
+    analysis = analyze_repository(
+        "https://github.com/owner/repo", clone_enabled=True
+    )
+
+Pipeline stages, each decoupled and independently testable:
+
+1. ``sources``   — resolve a local path or remote URL to a repository root
+2. ``traversal`` — recursively walk, filter directories, recognise languages
+3. ``reader``    — read and decode each supported file with guards
+4. ``analysis``  — run the injected analyzers over the immutable scan
+5. ``output``    — render the full result to canonical JSON
+
+Errors are typed (see ``errors``) and logging is graded through
+``openworkproof.repo_pipeline``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .analysis import (
+    DEFAULT_ANALYZERS,
+    RepositoryAnalyzer,
+    analyze_scan,
+)
+from .errors import get_logger
+from .models import RepositoryAnalysis
+from .output import render_json, to_dict
+from .sources import resolve_repository_source
+from .traversal import scan_repository
+
+_logger = get_logger()
+
+__all__ = [
+    "RepositoryAnalysis",
+    "RepositoryAnalyzer",
+    "analyze_repository",
+    "render_json",
+    "resolve_repository_source",
+    "scan_repository",
+    "to_dict",
+]
+
+
+def analyze_repository(
+    source: str | Path,
+    *,
+    analyzers: tuple[RepositoryAnalyzer, ...] = DEFAULT_ANALYZERS,
+    clone_enabled: bool = True,
+    fail_fast: bool = False,
+) -> RepositoryAnalysis:
+    """Run the full pipeline over a local path or remote repository URL.
+
+    Remote sources are cloned into a temporary directory that the caller
+    must remove after consuming the result.
+    """
+    root = resolve_repository_source(source, clone_enabled=clone_enabled)
+    _logger.info("scanning repository root: %s", root)
+    scan = scan_repository(root)
+    results = analyze_scan(scan, analyzers, fail_fast=fail_fast)
+    _logger.info(
+        "scan complete: %d files, %d bytes, %d skipped dirs",
+        scan.total_files,
+        scan.total_bytes,
+        len(scan.skipped),
+    )
+    return RepositoryAnalysis(scan=scan, results=results)

openworkproof/repo_pipeline/analysis.py

@@ -0,0 +1,152 @@
+"""Extensible analysis layer.
+
+Analyzers implement ``RepositoryAnalyzer`` and receive the immutable
+``RepositoryScan``; each returns one ``AnalysisResult``. The pipeline runs
+analyzers in order and never lets one analyzer's failure abort the others
+unless ``fail_fast`` is set.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .errors import AnalysisError, get_logger
+from .models import AnalysisResult, RepositoryScan
+
+_logger = get_logger()
+
+
+class RepositoryAnalyzer(Protocol):
+    name: str
+
+    def analyze(self, scan: RepositoryScan) -> AnalysisResult: ...
+
+
+class LanguageStatsAnalyzer:
+    """Summarise files and bytes per programming language."""
+
+    name = "language_stats"
+
+    def analyze(self, scan: RepositoryScan) -> AnalysisResult:
+        per_language: dict[str, dict[str, int]] = {}
+        for entry in scan.entries:
+            if entry.language is None:
+                continue
+            bucket = per_language.setdefault(
+                entry.language, {"files": 0, "bytes": 0}
+            )
+            bucket["files"] += 1
+            bucket["bytes"] += entry.size_bytes
+        return AnalysisResult(
+            analyzer=self.name,
+            data={
+                "languages": {
+                    language: {"files": counts["files"], "bytes": counts["bytes"]}
+                    for language, counts in sorted(per_language.items())
+                }
+            },
+        )
+
+
+class LineCountAnalyzer:
+    """Count total source lines and per-language lines."""
+
+    name = "line_counts"
+
+    def analyze(self, scan: RepositoryScan) -> AnalysisResult:
+        total_lines = 0
+        per_language: dict[str, int] = {}
+        for entry in scan.entries:
+            lines = entry.content.count("\n")
+            total_lines += lines
+            if entry.language is not None:
+                per_language[entry.language] = (
+                    per_language.get(entry.language, 0) + lines
+                )
+        return AnalysisResult(
+            analyzer=self.name,
+            data={
+                "total_lines": total_lines,
+                "lines_by_language": dict(
+                    sorted(per_language.items(), key=lambda item: item[0])
+                ),
+            },
+        )
+
+
+class DependencySnifferAnalyzer:
+    """Lightweight dependency-import sniffing for common ecosystems.
+
+    This is intentionally shallow and heuristic: it detects import/require
+    statements and package manifests without resolving the dependency graph.
+    """
+
+    name = "dependency_sniff"
+
+    def analyze(self, scan: RepositoryScan) -> AnalysisResult:
+        imports: dict[str, list[str]] = {}
+        for entry in scan.entries:
+            if entry.language == "Python":
+                kind = "python"
+            elif entry.language == "JavaScript":
+                kind = "javascript"
+            else:
+                continue
+            names = _sniff_imports(entry.content, kind)
+            if names:
+                imports.setdefault(kind, []).extend(names)
+        return AnalysisResult(
+            analyzer=self.name,
+            data={
+                "imports_by_kind": {
+                    kind: sorted(set(names))
+                    for kind, names in sorted(imports.items())
+                }
+            },
+        )
+
+
+def _sniff_imports(content: str, kind: str) -> list[str]:
+    names: list[str] = []
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("#", "//", "/*", "*")):
+            continue
+        if kind == "python":
+            if stripped.startswith(("import ", "from ")):
+                token = stripped.split()[1]
+                names.append(token.split(".")[0])
+        elif kind == "javascript":
+            if stripped.startswith(("import ", "from ", "require(")):
+                token = stripped.split()[1].strip("'\"")
+                names.append(token.split("/")[0])
+    return names
+
+
+def analyze_scan(
+    scan: RepositoryScan,
+    analyzers: tuple[RepositoryAnalyzer, ...],
+    *,
+    fail_fast: bool = False,
+) -> tuple[AnalysisResult, ...]:
+    """Run every analyzer over the scan, isolating per-analyzer failures."""
+    results: list[AnalysisResult] = []
+    for analyzer in analyzers:
+        try:
+            results.append(analyzer.analyze(scan))
+        except AnalysisError:
+            raise
+        except Exception as error:  # noqa: BLE001
+            _logger.error("analyzer %s failed: %s", analyzer.name, error)
+            if fail_fast:
+                raise AnalysisError(
+                    f"analyzer {analyzer.name} failed"
+                ) from error
+    return tuple(results)
+
+
+DEFAULT_ANALYZERS: tuple[RepositoryAnalyzer, ...] = (
+    LanguageStatsAnalyzer(),
+    LineCountAnalyzer(),
+    DependencySnifferAnalyzer(),
+)

openworkproof/repo_pipeline/errors.py

@@ -0,0 +1,64 @@
+"""Typed errors and graded logging for the repository pipeline.
+
+Every failure path raises a ``RepoPipelineError`` subclass so callers can
+handle categories (missing path, permission, unsupported source, parse
+failure, output failure) without inspecting message strings. Logging uses the
+``openworkproof.repo_pipeline`` namespace with severity levels suitable for
+operator triage.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+class RepoPipelineError(Exception):
+    """Base class for all repository pipeline failures."""
+
+
+class SourceError(RepoPipelineError):
+    """The input source could not be resolved or reached."""
+
+
+class PathNotFoundError(SourceError):
+    """A local repository path does not exist or is not a directory."""
+
+
+class PermissionDeniedError(SourceError):
+    """The pipeline cannot read the repository path or a file inside it."""
+
+
+class UnsupportedSourceError(SourceError):
+    """The input is neither a local path nor a supported remote URL."""
+
+
+class RemoteCloneError(SourceError):
+    """A remote repository could not be cloned or fetched."""
+
+
+class TraversalError(RepoPipelineError):
+    """The traversal stage failed while walking the repository."""
+
+
+class ReadError(RepoPipelineError):
+    """A file could not be read or decoded."""
+
+
+class DecodeError(ReadError):
+    """A file could not be decoded as UTF-8 text."""
+
+
+class AnalysisError(RepoPipelineError):
+    """An analyzer failed while processing a scan."""
+
+
+class OutputError(RepoPipelineError):
+    """The structured output could not be rendered."""
+
+
+_logger = logging.getLogger("openworkproof.repo_pipeline")
+
+
+def get_logger() -> logging.Logger:
+    """Return the shared graded logger for the pipeline stages."""
+    return _logger

openworkproof/repo_pipeline/models.py

@@ -0,0 +1,80 @@
+"""Unified data models for the repository read-and-analysis pipeline.
+
+Every stage of the pipeline exchanges immutable dataclasses from this module,
+so stages stay decoupled: traversal produces ``RepositoryScan``, analyzers
+consume it and emit ``AnalysisResult``, and the output layer renders results
+to JSON.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import stat
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class RepoFileEntry:
+    """One file discovered by the traversal stage."""
+
+    relative_path: str
+    language: str | None
+    size_bytes: int
+    content: str
+    sha256: str
+
+    @property
+    def is_text(self) -> bool:
+        return self.language is not None
+
+
+@dataclass(frozen=True, slots=True)
+class SkippedDirectory:
+    """One directory skipped by a traversal filter rule."""
+
+    relative_path: str
+    rule: str
+
+
+@dataclass(frozen=True, slots=True)
+class RepositoryScan:
+    """The complete immutable result of one repository traversal."""
+
+    root: str
+    entries: tuple[RepoFileEntry, ...] = ()
+    skipped: tuple[SkippedDirectory, ...] = ()
+    total_files: int = 0
+    total_bytes: int = 0
+    languages: Mapping[str, int] = field(default_factory=dict)
+
+    def language_counts(self) -> Mapping[str, int]:
+        counts: dict[str, int] = {}
+        for entry in self.entries:
+            if entry.language is not None:
+                counts[entry.language] = counts.get(entry.language, 0) + 1
+        return counts
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisResult:
+    """One analyzer's structured output for a scan."""
+
+    analyzer: str
+    data: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class RepositoryAnalysis:
+    """The full pipeline output: scan plus every analyzer result."""
+
+    scan: RepositoryScan
+    results: tuple[AnalysisResult, ...] = ()
+
+
+def entry_mode_is_regular(mode: int) -> bool:
+    return stat.S_ISREG(mode)
+
+
+def is_supported_source_path(path: object) -> bool:
+    return isinstance(path, (str, Path)) and bool(path)