donespec 0.1.0__py3-none-any.whl

donespec/__init__.py

@@ -0,0 +1,3 @@
+"""DoneSpec: deterministic validation for AI agent task completion."""
+
+__version__ = "0.1.0"

donespec/__main__.py

@@ -0,0 +1,4 @@
+from donespec.cli import app
+
+if __name__ == "__main__":
+    app()

donespec/checkers/__init__.py

@@ -0,0 +1,3 @@
+from donespec.checkers.registry import CHECKERS, get_checker
+
+__all__ = ["CHECKERS", "get_checker"]

donespec/checkers/base.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from time import perf_counter
+from typing import Any
+
+from donespec.models import CheckGroup, CheckResult, ValidationContext
+
+
+class Checker(ABC):
+    """Base class for deterministic checkers."""
+
+    type_name: str
+
+    def __init__(
+        self, config: dict[str, Any], group: CheckGroup, context: ValidationContext
+    ) -> None:
+        self.config = config
+        self.group = group
+        self.context = context
+
+    @abstractmethod
+    def run(self) -> CheckResult:
+        """Execute the checker and return a structured result."""
+
+    def result(
+        self,
+        *,
+        passed: bool,
+        duration_ms: float,
+        error: str | None = None,
+        details: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> CheckResult:
+        return CheckResult(
+            id=self.config.get("id"),
+            name=self.config.get("name") or self.default_name(),
+            type=self.type_name,
+            group=self.group,
+            passed=passed,
+            duration_ms=duration_ms,
+            error=error,
+            details=details,
+            metadata=metadata or {},
+        )
+
+    def default_name(self) -> str:
+        return self.type_name
+
+
+def timed(fn):
+    """Decorator helper for checker implementations."""
+
+    def wrapper(self: Checker):
+        started = perf_counter()
+        try:
+            return fn(self, started)
+        except Exception as exc:
+            duration_ms = (perf_counter() - started) * 1000
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error=str(exc),
+                metadata={"exception_type": exc.__class__.__name__},
+            )
+
+    return wrapper

donespec/checkers/command.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import subprocess
+from time import perf_counter
+
+from donespec.checkers.base import Checker, timed
+
+
+class CommandChecker(Checker):
+    type_name = "command"
+
+    def default_name(self) -> str:
+        return self.config.get("run", "command")
+
+    @timed
+    def run(self, started: float):
+        command = self.config["run"]
+        expected_exit_code = int(self.config.get("expected_exit_code", 0))
+        timeout_seconds = float(self.config.get("timeout_seconds", 120))
+
+        try:
+            completed = subprocess.run(
+                command,
+                cwd=self.context.root_dir,
+                shell=True,
+                text=True,
+                capture_output=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            duration_ms = (perf_counter() - started) * 1000
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error=f"Command timed out after {timeout_seconds:g}s",
+                metadata={
+                    "command": command,
+                    "timeout_seconds": timeout_seconds,
+                    "stdout": exc.stdout,
+                    "stderr": exc.stderr,
+                },
+            )
+
+        duration_ms = (perf_counter() - started) * 1000
+        passed = completed.returncode == expected_exit_code
+        details = f"exit_code={completed.returncode}, expected_exit_code={expected_exit_code}"
+        return self.result(
+            passed=passed,
+            duration_ms=duration_ms,
+            error=None if passed else details,
+            details=details,
+            metadata={
+                "command": command,
+                "exit_code": completed.returncode,
+                "expected_exit_code": expected_exit_code,
+                "stdout_tail": completed.stdout[-4000:],
+                "stderr_tail": completed.stderr[-4000:],
+            },
+        )

donespec/checkers/file_exists.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from time import perf_counter
+
+from donespec.checkers.base import Checker, timed
+from donespec.pathing import resolve_under_root
+
+
+class FileExistsChecker(Checker):
+    type_name = "file_exists"
+
+    def default_name(self) -> str:
+        return f"{self.config['path']} exists"
+
+    @timed
+    def run(self, started: float):
+        raw_path = self.config["path"]
+        target = resolve_under_root(self.context.root_dir, raw_path)
+        exists = target.exists()
+        duration_ms = (perf_counter() - started) * 1000
+
+        return self.result(
+            passed=exists,
+            duration_ms=duration_ms,
+            error=None if exists else f"File does not exist: {raw_path}",
+            details=f"resolved_path={target}",
+            metadata={"path": raw_path, "resolved_path": str(target), "is_file": target.is_file()},
+        )

donespec/checkers/git.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import subprocess
+from time import perf_counter
+
+from donespec.checkers.base import Checker, timed
+
+
+class FileNotModifiedChecker(Checker):
+    type_name = "file_not_modified"
+
+    def default_name(self) -> str:
+        return f"{self.config['path']} not modified"
+
+    @timed
+    def run(self, started: float):
+        raw_path = self.config["path"]
+
+        repo_check = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=self.context.root_dir,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if repo_check.returncode != 0:
+            duration_ms = (perf_counter() - started) * 1000
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error="file_not_modified requires a Git work tree",
+                metadata={"path": raw_path, "stderr": repo_check.stderr.strip()},
+            )
+
+        status = subprocess.run(
+            ["git", "status", "--porcelain", "--", raw_path],
+            cwd=self.context.root_dir,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        duration_ms = (perf_counter() - started) * 1000
+
+        if status.returncode != 0:
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error=status.stderr.strip() or "git status failed",
+                metadata={"path": raw_path, "exit_code": status.returncode},
+            )
+
+        porcelain = status.stdout.strip()
+        passed = porcelain == ""
+
+        return self.result(
+            passed=passed,
+            duration_ms=duration_ms,
+            error=None if passed else f"Forbidden path modified: {raw_path}",
+            details="clean" if passed else porcelain,
+            metadata={"path": raw_path, "git_status": porcelain},
+        )

donespec/checkers/http.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from time import perf_counter
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from donespec.checkers.base import Checker, timed
+
+
+class HttpCheckChecker(Checker):
+    type_name = "http_check"
+
+    def default_name(self) -> str:
+        return f"{self.config.get('method', 'GET')} {self.config['url']} returns expected status"
+
+    @timed
+    def run(self, started: float):
+        url = self.config["url"]
+        method = self.config.get("method", "GET")
+        expected_status = int(self.config.get("expected_status", 200))
+        timeout_seconds = float(self.config.get("timeout_seconds", 10))
+        headers = self.config.get("headers", {})
+
+        request = Request(url, method=method, headers=headers)
+        status: int | None = None
+        reason: str | None = None
+
+        try:
+            with urlopen(request, timeout=timeout_seconds) as response:
+                status = int(response.status)
+                reason = response.reason
+        except HTTPError as exc:
+            status = int(exc.code)
+            reason = exc.reason
+        except URLError as exc:
+            duration_ms = (perf_counter() - started) * 1000
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error=f"HTTP request failed: {exc.reason}",
+                metadata={"url": url, "method": method, "expected_status": expected_status},
+            )
+
+        duration_ms = (perf_counter() - started) * 1000
+        passed = status == expected_status
+        return self.result(
+            passed=passed,
+            duration_ms=duration_ms,
+            error=None if passed else f"Expected HTTP {expected_status}, got {status}",
+            details=f"status={status}, reason={reason}",
+            metadata={
+                "url": url,
+                "method": method,
+                "status": status,
+                "reason": reason,
+                "expected_status": expected_status,
+            },
+        )

donespec/checkers/regex.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import re
+from time import perf_counter
+
+from donespec.checkers.base import Checker, timed
+from donespec.pathing import resolve_under_root
+
+_FLAG_MAP = {
+    "IGNORECASE": re.IGNORECASE,
+    "MULTILINE": re.MULTILINE,
+    "DOTALL": re.DOTALL,
+}
+
+
+def compile_flags(raw_flags: list[str] | None) -> re.RegexFlag:
+    flags = re.NOFLAG
+    for raw_flag in raw_flags or []:
+        flags |= _FLAG_MAP[raw_flag]
+    return flags
+
+
+class RegexInFileChecker(Checker):
+    type_name = "regex_in_file"
+
+    def default_name(self) -> str:
+        return f"{self.config['pattern']} exists in {self.config['path']}"
+
+    @timed
+    def run(self, started: float):
+        raw_path = self.config["path"]
+        pattern = self.config["pattern"]
+        target = resolve_under_root(self.context.root_dir, raw_path)
+
+        if not target.exists():
+            duration_ms = (perf_counter() - started) * 1000
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error=f"File does not exist: {raw_path}",
+                metadata={"path": raw_path, "pattern": pattern},
+            )
+
+        content = target.read_text(encoding="utf-8", errors="replace")
+        match = re.search(pattern, content, flags=compile_flags(self.config.get("flags")))
+        duration_ms = (perf_counter() - started) * 1000
+
+        return self.result(
+            passed=match is not None,
+            duration_ms=duration_ms,
+            error=None if match else f"Pattern not found: {pattern}",
+            details=f"file={raw_path}",
+            metadata={
+                "path": raw_path,
+                "pattern": pattern,
+                "match_start": match.start() if match else None,
+                "match_end": match.end() if match else None,
+            },
+        )
+
+
+class RegexAbsentChecker(Checker):
+    type_name = "regex_absent"
+
+    def default_name(self) -> str:
+        return f"{self.config['pattern']} absent from {self.config['path']}"
+
+    @timed
+    def run(self, started: float):
+        raw_path = self.config["path"]
+        pattern = self.config["pattern"]
+        target = resolve_under_root(self.context.root_dir, raw_path)
+
+        if not target.exists():
+            duration_ms = (perf_counter() - started) * 1000
+            return self.result(
+                passed=False,
+                duration_ms=duration_ms,
+                error=f"File does not exist: {raw_path}",
+                metadata={"path": raw_path, "pattern": pattern},
+            )
+
+        content = target.read_text(encoding="utf-8", errors="replace")
+        match = re.search(pattern, content, flags=compile_flags(self.config.get("flags")))
+        duration_ms = (perf_counter() - started) * 1000
+        passed = match is None
+
+        return self.result(
+            passed=passed,
+            duration_ms=duration_ms,
+            error=None if passed else f"Forbidden pattern found: {pattern}",
+            details=f"file={raw_path}",
+            metadata={
+                "path": raw_path,
+                "pattern": pattern,
+                "match_start": match.start() if match else None,
+                "match_end": match.end() if match else None,
+            },
+        )

donespec/checkers/registry.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from donespec.checkers.base import Checker
+from donespec.checkers.command import CommandChecker
+from donespec.checkers.file_exists import FileExistsChecker
+from donespec.checkers.git import FileNotModifiedChecker
+from donespec.checkers.http import HttpCheckChecker
+from donespec.checkers.regex import RegexAbsentChecker, RegexInFileChecker
+
+CHECKERS: dict[str, type[Checker]] = {
+    CommandChecker.type_name: CommandChecker,
+    FileExistsChecker.type_name: FileExistsChecker,
+    RegexInFileChecker.type_name: RegexInFileChecker,
+    RegexAbsentChecker.type_name: RegexAbsentChecker,
+    FileNotModifiedChecker.type_name: FileNotModifiedChecker,
+    HttpCheckChecker.type_name: HttpCheckChecker,
+}
+
+
+def get_checker(type_name: str) -> type[Checker]:
+    try:
+        return CHECKERS[type_name]
+    except KeyError as exc:
+        available = ", ".join(sorted(CHECKERS))
+        msg = f"Unknown checker type: {type_name}. Available: {available}"
+        raise ValueError(msg) from exc

donespec/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from donespec import __version__
+from donespec.engine import validate_payload
+from donespec.exceptions import SpecValidationError
+from donespec.loader import load_spec
+from donespec.output import error_to_json, print_human_report, report_to_json
+
+app = typer.Typer(
+    name="donespec",
+    help="Deterministic validation for AI agent task completion.",
+    no_args_is_help=True,
+)
+console = Console(stderr=False)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"donespec {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version_callback, help="Show version and exit."),
+    ] = False,
+) -> None:
+    _ = version
+
+
+@app.command()
+def validate(
+    spec: Annotated[Path, typer.Argument(help="Path to done.json")],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Emit machine-readable JSON output."),
+    ] = False,
+    root: Annotated[
+        Path | None,
+        typer.Option("--root", help="Project root. Defaults to the spec file directory."),
+    ] = None,
+    fail_fast: Annotated[
+        bool,
+        typer.Option("--fail-fast", help="Stop after the first failed check."),
+    ] = False,
+) -> None:
+    """Validate a DoneSpec task file."""
+    spec_path = spec.resolve()
+    root_dir = root.resolve() if root else spec_path.parent.resolve()
+
+    try:
+        payload = load_spec(spec_path)
+        report = validate_payload(
+            payload,
+            spec_path=spec_path,
+            root_dir=root_dir,
+            fail_fast=fail_fast,
+        )
+    except SpecValidationError as exc:
+        if json_output:
+            sys.stdout.write(error_to_json(str(exc)) + "\n")
+        else:
+            console.print(f"[bold red]Spec error:[/bold red] {exc}")
+        raise typer.Exit(code=2) from exc
+    except Exception as exc:
+        if json_output:
+            sys.stdout.write(error_to_json(str(exc)) + "\n")
+        else:
+            console.print(f"[bold red]Runtime error:[/bold red] {exc}")
+        raise typer.Exit(code=2) from exc
+
+    if json_output:
+        sys.stdout.write(report_to_json(report) + "\n")
+    else:
+        print_human_report(report, console=console)
+
+    raise typer.Exit(code=report.exit_code)

donespec/engine.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+from donespec.checkers import get_checker
+from donespec.models import CheckGroup, CheckResult, ValidationContext, ValidationReport
+
+
+def run_check(config: dict[str, Any], group: CheckGroup, context: ValidationContext) -> CheckResult:
+    checker_class = get_checker(config["type"])
+    checker = checker_class(config=config, group=group, context=context)
+    return checker.run()
+
+
+def validate_payload(
+    payload: dict[str, Any], *, spec_path: Path, root_dir: Path, fail_fast: bool = False
+) -> ValidationReport:
+    started = perf_counter()
+    context = ValidationContext(root_dir=root_dir, spec_path=spec_path)
+    results: list[CheckResult] = []
+
+    for group in ("must_pass", "must_not"):
+        for config in payload.get(group, []):
+            result = run_check(config=config, group=group, context=context)  # type: ignore[arg-type]
+            results.append(result)
+            if fail_fast and not result.passed:
+                break
+        if fail_fast and results and not results[-1].passed:
+            break
+
+    duration_ms = (perf_counter() - started) * 1000
+    failed_checks = sum(1 for result in results if not result.passed)
+
+    return ValidationReport(
+        version=payload["version"],
+        task_id=payload["task_id"],
+        passed=failed_checks == 0,
+        total_checks=len(results),
+        failed_checks=failed_checks,
+        duration_ms=duration_ms,
+        results=results,
+    )

donespec/exceptions.py

@@ -0,0 +1,6 @@
+class DoneSpecError(Exception):
+    """Base DoneSpec exception."""
+
+
+class SpecValidationError(DoneSpecError):
+    """Raised when done.json is invalid."""

donespec/loader.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from donespec.exceptions import SpecValidationError
+from donespec.schema import validate_spec_payload
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise SpecValidationError(f"Spec file not found: {path}")
+
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError as exc:
+        raise SpecValidationError(f"Invalid JSON in {path}: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise SpecValidationError("Invalid done.json: root value must be an object")
+
+    validate_spec_payload(payload)
+    payload.setdefault("must_pass", [])
+    payload.setdefault("must_not", [])
+    return payload

donespec/models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+CheckGroup = Literal["must_pass", "must_not"]
+
+
+class ValidationContext(BaseModel):
+    """Runtime context shared by every checker."""
+
+    root_dir: Path
+    spec_path: Path
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class CheckResult(BaseModel):
+    """Structured result returned by every checker."""
+
+    id: str | None = None
+    name: str
+    type: str
+    group: CheckGroup
+    passed: bool
+    duration_ms: float = Field(ge=0)
+    error: str | None = None
+    details: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ValidationReport(BaseModel):
+    """Complete validation report emitted by the engine."""
+
+    version: str
+    task_id: str
+    passed: bool
+    total_checks: int
+    failed_checks: int
+    duration_ms: float = Field(ge=0)
+    results: list[CheckResult]
+
+    @property
+    def exit_code(self) -> int:
+        return 0 if self.passed else 1

donespec/output.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.text import Text
+
+from donespec.models import ValidationReport
+
+
+def report_to_json(report: ValidationReport) -> str:
+    return json.dumps(report.model_dump(mode="json"), indent=2, sort_keys=True)
+
+
+def _symbol(passed: bool) -> str:
+    return "✓" if passed else "✗"
+
+
+def _style(passed: bool) -> str:
+    return "green" if passed else "red"
+
+
+def print_human_report(report: ValidationReport, console: Console | None = None) -> None:
+    console = console or Console()
+    console.print(f"DoneSpec validation: [bold]{report.task_id}[/bold]")
+    console.print()
+
+    for result in report.results:
+        line = Text()
+        line.append(_symbol(result.passed), style=f"bold {_style(result.passed)}")
+        line.append(" ")
+        line.append(result.name)
+        line.append(f"  ({result.duration_ms:.1f}ms)", style="dim")
+        console.print(line)
+        if not result.passed and result.error:
+            console.print(f"  [red]{result.error}[/red]")
+
+    console.print()
+    if report.passed:
+        console.print(
+            f"[bold green]Validation passed.[/bold green] {report.total_checks} checks passed."
+        )
+        console.print("Exit code: 0", style="dim")
+        return
+
+    plural = "check" if report.failed_checks == 1 else "checks"
+    console.print("[bold red]Validation failed.[/bold red]")
+    console.print(f"{report.failed_checks} {plural} failed.")
+    console.print("Exit code: 1", style="dim")
+
+
+def error_to_json(error: str) -> str:
+    payload: dict[str, Any] = {"passed": False, "error": error}
+    return json.dumps(payload, indent=2, sort_keys=True)