greenproof 0.1.0__py3-none-any.whl

greenproof/__init__.py

@@ -0,0 +1,5 @@
+"""greenproof: a definition-of-done gate for code written by LLM coding agents."""
+
+from greenproof._version import __version__
+
+__all__ = ["__version__"]

greenproof/_version.py

@@ -0,0 +1,3 @@
+"""The package version: the single place it is written. pyproject.toml reads it at build time."""
+
+__version__ = "0.1.0"

greenproof/accept.py

@@ -0,0 +1,142 @@
+"""Local acceptances (SPEC 6.6): `greenproof accept`, `--list`, `--revoke`.
+
+Advisory only: the file is writable by anything running as the user, an agent included.
+Local and hook modes honour it; ci mode ignores it (CI reads PR comments instead, see
+`github.py`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from greenproof import gitops
+from greenproof.errors import UsageError
+from greenproof.findings import FINGERPRINT_LENGTH
+
+ACCEPTED_FILE = "accepted.json"
+_FINGERPRINT = re.compile(rf"[0-9a-f]{{{FINGERPRINT_LENGTH}}}")
+
+
+@dataclass(frozen=True)
+class Acceptance:
+    by: str
+    at: str
+    source: str  # "local" or "github"
+    reason: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"by": self.by, "at": self.at, "source": self.source, "reason": self.reason}
+
+
+def is_fingerprint(text: str) -> bool:
+    return _FINGERPRINT.fullmatch(text) is not None
+
+
+def accepted_path(repo: Path) -> Path:
+    return gitops.greenproof_dir(repo) / ACCEPTED_FILE
+
+
+def load_local(repo: Path) -> dict[str, Acceptance]:
+    """Fingerprint to acceptance. A missing or malformed file counts as empty."""
+    try:
+        data = json.loads(accepted_path(repo).read_text())
+        table = data["accepted"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return {}
+    if not isinstance(table, dict):
+        return {}
+    out: dict[str, Acceptance] = {}
+    for fp, entry in table.items():
+        if not (isinstance(fp, str) and is_fingerprint(fp) and isinstance(entry, dict)):
+            continue
+        by, at, reason = entry.get("by"), entry.get("at"), entry.get("reason")
+        if (
+            isinstance(by, str)
+            and isinstance(at, str)
+            and (reason is None or isinstance(reason, str))
+        ):
+            out[fp] = Acceptance(by, at, "local", reason)
+    return out
+
+
+def _save(repo: Path, table: dict[str, Acceptance]) -> None:
+    path = accepted_path(repo)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "accepted": {
+            fp: {"by": a.by, "at": a.at, "reason": a.reason} for fp, a in sorted(table.items())
+        }
+    }
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix="accepted-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as handle:
+            json.dump(payload, handle, indent=2)
+            handle.write("\n")
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def identity(repo: Path) -> str:
+    """`Name <email>` from git config; whichever part is missing is left out."""
+
+    def config(key: str) -> str:
+        proc = gitops.git(repo, "config", key, check=False)
+        return proc.stdout.decode(errors="replace").strip() if proc.returncode == 0 else ""
+
+    name, email = config("user.name"), config("user.email")
+    if name and email:
+        return f"{name} <{email}>"
+    return name or email or "unknown"
+
+
+def _check_fingerprints(fingerprints: Iterable[str]) -> list[str]:
+    out = list(fingerprints)
+    for fp in out:
+        if not is_fingerprint(fp):
+            raise UsageError(
+                f"{fp!r} is not a fingerprint: expected {FINGERPRINT_LENGTH} lowercase hex digits"
+                " (shown as [fp ...] in the report)"
+            )
+    return out
+
+
+def accept(repo: Path, fingerprints: Iterable[str], reason: str | None) -> list[str]:
+    fps = _check_fingerprints(fingerprints)
+    if not fps:
+        raise UsageError("accept: give at least one fingerprint (or --list, or --revoke FP)")
+    table = load_local(repo)
+    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    who = identity(repo)
+    for fp in fps:
+        table[fp] = Acceptance(who, now, "local", reason or None)
+    _save(repo, table)
+    return fps
+
+
+def revoke(repo: Path, fingerprint: str) -> None:
+    (fp,) = _check_fingerprints([fingerprint])
+    table = load_local(repo)
+    if fp not in table:
+        raise UsageError(f"{fp} is not accepted")
+    del table[fp]
+    _save(repo, table)
+
+
+def render_list(table: dict[str, Acceptance]) -> str:
+    if not table:
+        return "greenproof: no accepted findings\n"
+    lines = []
+    for fp, a in sorted(table.items()):
+        reason = f"  {a.reason}" if a.reason else ""
+        lines.append(f"{fp}  {a.at}  {a.by}{reason}")
+    return "\n".join(lines) + "\n"

greenproof/cache.py

@@ -0,0 +1,85 @@
+"""Remember passes so an unchanged candidate is not re-verified (SPEC 3.1 step 7).
+
+Stored in `<git-common-dir>/greenproof/cache.json`, last 50 entries, passes only. A
+failure is never cached, and a corrupt file is treated as empty (a miss just re-runs).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+import time
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+MAX_ENTRIES = 50
+
+
+def cache_key(
+    tree: str,
+    base_sha: str,
+    policy_sha256: str,
+    version: str,
+    mode: str,
+    checks: Sequence[str],
+    flags: Sequence[str] = (),
+) -> str:
+    """sha256 over everything that determines the verdict.
+
+    `flags` carries options that change it beyond the spec's list, e.g. allow-policy-change:
+    without it a pass obtained with the flag would be replayed for a run without it.
+    """
+    material = {
+        "tree": tree,
+        "base": base_sha,
+        "policy": policy_sha256,
+        "version": version,
+        "mode": mode,
+        "checks": list(checks),
+        "flags": sorted(flags),
+    }
+    blob = json.dumps(material, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(blob.encode()).hexdigest()
+
+
+class PassCache:
+    def __init__(self, directory: Path) -> None:
+        self.path = directory / "cache.json"
+
+    def _load(self) -> list[dict[str, Any]]:
+        try:
+            data = json.loads(self.path.read_text())
+            entries = data["entries"]
+        except (OSError, ValueError, KeyError, TypeError):
+            return []
+        if not isinstance(entries, list):
+            return []
+        return [e for e in entries if isinstance(e, dict) and isinstance(e.get("key"), str)]
+
+    def get_pass(self, key: str) -> list[dict[str, Any]] | None:
+        """The check statuses of the original passing run, or None on a miss."""
+        for entry in self._load():
+            checks = entry.get("checks")
+            if entry["key"] == key and isinstance(checks, list):
+                return [c for c in checks if isinstance(c, dict)]
+        return None
+
+    def has_pass(self, key: str) -> bool:
+        return self.get_pass(key) is not None
+
+    def record_pass(self, key: str, checks: Sequence[Mapping[str, Any]]) -> None:
+        entries = [e for e in self._load() if e["key"] != key]
+        entries.append({"key": key, "at": int(time.time()), "checks": [dict(c) for c in checks]})
+        entries = entries[-MAX_ENTRIES:]
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self.path.parent, prefix="cache-", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as handle:
+                json.dump({"entries": entries}, handle)
+            os.replace(tmp, self.path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise

greenproof/changeset.py

@@ -0,0 +1,138 @@
+"""The change set: files that differ between base and candidate, with both-side contents."""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from greenproof import gitops
+
+_JS_TEST = re.compile(r".*\.(test)\.(js|jsx|ts|tsx|mjs|cjs)$")
+_JS_SPEC = re.compile(r".*\.spec\.[^/]+$")
+
+
+@dataclass(frozen=True)
+class ChangedFile:
+    path: str
+    status: str  # A, M, D, R
+    old_path: str | None
+    old_content: bytes | None
+    new_content: bytes | None
+    is_test: bool
+    was_test: bool  # whether the old path (or the path itself) was a test file at base
+
+    @property
+    def old_text(self) -> str | None:
+        return None if self.old_content is None else self.old_content.decode(errors="replace")
+
+    @property
+    def new_text(self) -> str | None:
+        return None if self.new_content is None else self.new_content.decode(errors="replace")
+
+
+@dataclass(frozen=True)
+class ChangeSet:
+    files: list[ChangedFile] = field(default_factory=list)
+    skipped_binary: list[str] = field(default_factory=list)
+    # Reads any file as it was at the base revision (None when absent), changed or not.
+    read_base: Callable[[str], bytes | None] | None = None
+
+    def base_text(self, path: str) -> str | None:
+        """The file's text at the base revision, or None when it did not exist there."""
+        if self.read_base is not None:
+            blob = self.read_base(path)
+            return None if blob is None else blob.decode(errors="replace")
+        for f in self.files:
+            if (f.old_path or f.path) == path:
+                return f.old_text
+        return None
+
+    def tests(self) -> list[ChangedFile]:
+        return [f for f in self.files if f.is_test or f.was_test]
+
+    def non_tests(self) -> list[ChangedFile]:
+        return [f for f in self.files if not f.is_test and not f.was_test]
+
+
+def _glob_to_regex(pattern: str) -> re.Pattern[str]:
+    """`*` and `?` stay inside one path segment; `**` crosses segments; `**/` may be empty."""
+    out: list[str] = []
+    i = 0
+    while i < len(pattern):
+        char = pattern[i]
+        if char == "*":
+            if pattern[i : i + 2] == "**":
+                if pattern[i : i + 3] == "**/":
+                    out.append("(?:.*/)?")
+                    i += 3
+                    continue
+                out.append(".*")
+                i += 2
+                continue
+            out.append("[^/]*")
+        elif char == "?":
+            out.append("[^/]")
+        else:
+            out.append(re.escape(char))
+        i += 1
+    return re.compile("".join(out) + r"\Z")
+
+
+def matches_glob(path: str, pattern: str) -> bool:
+    """A pattern without a slash matches the file name at any depth; otherwise the full path."""
+    target = path if "/" in pattern else posixpath.basename(path)
+    return _glob_to_regex(pattern.lstrip("/")).match(target) is not None
+
+
+def is_test_path(path: str, patterns: Sequence[str] = ()) -> bool:
+    """Whether `path` is a test file: the policy's `tests.paths`, else the language defaults."""
+    if patterns:
+        return any(matches_glob(path, p) for p in patterns)
+    name = posixpath.basename(path)
+    dirs = posixpath.dirname(path).split("/")
+    in_test_dir = "tests" in dirs or "test" in dirs
+    if name.endswith(".py"):
+        return (
+            name.startswith("test_")
+            or name.endswith("_test.py")
+            or name == "conftest.py"
+            or in_test_dir
+        )
+    if name.endswith(".go"):
+        return name.endswith("_test.go")
+    if name.endswith(".rs"):
+        return "tests" in dirs
+    return bool(_JS_TEST.match(name) or _JS_SPEC.match(name) or "__tests__" in dirs)
+
+
+def _is_binary(*blobs: bytes | None) -> bool:
+    return any(b is not None and b"\0" in b[:8000] for b in blobs)
+
+
+def build_changeset(
+    repo: Path, base_sha: str, tree: str, test_patterns: Sequence[str] = ()
+) -> ChangeSet:
+    files: list[ChangedFile] = []
+    skipped: list[str] = []
+    for entry in gitops.diff_name_status(repo, base_sha, tree):
+        old_path = entry.old_path or entry.path
+        old = None if entry.status == "A" else gitops.read_blob(repo, base_sha, old_path)
+        new = None if entry.status == "D" else gitops.read_blob(repo, tree, entry.path)
+        if _is_binary(old, new):
+            skipped.append(entry.path)
+            continue
+        files.append(
+            ChangedFile(
+                path=entry.path,
+                status=entry.status,
+                old_path=entry.old_path,
+                old_content=old,
+                new_content=new,
+                is_test=is_test_path(entry.path, test_patterns),
+                was_test=entry.status != "A" and is_test_path(old_path, test_patterns),
+            )
+        )
+    return ChangeSet(files, skipped, lambda p: gitops.read_blob(repo, base_sha, p))

greenproof/cli.py

@@ -0,0 +1,255 @@
+"""Command-line entry point. Maps every outcome to an exit code and fails closed."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import NoReturn
+
+from greenproof import __version__, accept, gitops, hooks, pipeline
+from greenproof.errors import EXIT_INTERNAL, EXIT_USAGE, GreenproofError, UsageError
+from greenproof.registry import RULES, rule_ids
+from greenproof.report import (
+    Report,
+    error_report,
+    render_annotations,
+    render_markdown,
+    render_text,
+    to_json_dict,
+)
+
+HOOKS = hooks.HOOK_AGENTS
+
+
+class _Parser(argparse.ArgumentParser):
+    """argparse exits 2 on bad usage; greenproof reserves 2 for a failed command."""
+
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(EXIT_USAGE, f"{self.prog}: error: {message}\n")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(prog="greenproof", description="Is the green real?")
+    parser.add_argument("--version", action="version", version=f"greenproof {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, parser_class=_Parser)
+
+    check = sub.add_parser("check", help="verify the current change")
+    check.add_argument("--base", metavar="REF")
+    check.add_argument("--mode", choices=pipeline.MODES, default=None)
+    check.add_argument("--hook", choices=HOOKS)
+    check.add_argument(
+        "--checks",
+        metavar="LIST",
+        help=f"comma-separated subset of {','.join(pipeline.IMPLEMENTED_CHECKS)}",
+    )
+    check.add_argument("--json", metavar="PATH", dest="json_path")
+    check.add_argument("--markdown", metavar="PATH", dest="markdown_path")
+    check.add_argument("--github-annotations", action="store_true")
+    check.add_argument("--github-accept", action="store_true")
+    check.add_argument("--allow-policy-change", action="store_true")
+    check.add_argument("--no-cache", action="store_true")
+    check.add_argument("--isolate", action="store_true")
+
+    start = sub.add_parser("session-start", help="record the revision the session started from")
+    start.add_argument("--hook", choices=HOOKS)
+
+    acc = sub.add_parser("accept", help="accept findings by fingerprint (advisory, local)")
+    acc.add_argument("fingerprints", nargs="*", metavar="FINGERPRINT")
+    acc.add_argument("--reason", metavar="TEXT")
+    acc.add_argument("--list", action="store_true", dest="list_accepted")
+    acc.add_argument("--revoke", metavar="FINGERPRINT")
+
+    explain = sub.add_parser("explain", help="describe a rule")
+    explain.add_argument("rule_id", metavar="RULE_ID")
+
+    init = sub.add_parser("init", help="set up greenproof in a repository")
+    init.add_argument(
+        "--yes", action="store_true", help="overwrite an existing policy and workflow"
+    )
+    init.add_argument(
+        "--agents",
+        default="auto",
+        metavar="auto|none|LIST",
+        help="agents to install hooks for: auto, none or a list of claude,cursor,codex,gemini",
+    )
+    init.add_argument("--ci", choices=("github", "none"), default="none")
+    init.add_argument("--no-verify", action="store_true", help="do not run the proposed commands")
+    init.add_argument("--hook-command", metavar="CMD", help="how the hooks invoke greenproof")
+    return parser
+
+
+def _write(path: str, text: str) -> None:
+    Path(path).write_text(text)
+
+
+def _write_files(report: Report, args: argparse.Namespace) -> None:
+    if getattr(args, "json_path", None):
+        _write(args.json_path, json.dumps(to_json_dict(report), indent=2) + "\n")
+    if getattr(args, "markdown_path", None):
+        with open(args.markdown_path, "a") as handle:  # GITHUB_STEP_SUMMARY is appended to
+            handle.write(render_markdown(report))
+
+
+def _emit(report: Report, args: argparse.Namespace) -> None:
+    sys.stdout.write(render_text(report))
+    if getattr(args, "github_annotations", False):
+        sys.stdout.write(render_annotations(report))
+    _write_files(report, args)
+
+
+def _resolve_mode(args: argparse.Namespace) -> str:
+    """`--hook` implies `--mode hook`; an explicit other mode with it is a usage error."""
+    if args.hook:
+        if args.mode not in (None, "hook"):
+            raise UsageError(
+                f"--hook implies --mode hook; it cannot be combined with --mode {args.mode}"
+            )
+        return "hook"
+    return args.mode or "local"
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    mode = _resolve_mode(args)
+    checks = None
+    if args.checks is not None:
+        checks = [c.strip() for c in args.checks.split(",") if c.strip()]
+        if not checks:
+            raise UsageError("--checks: expected a comma-separated list")
+    opts = pipeline.CheckOptions(
+        cwd=Path.cwd(),
+        base=args.base,
+        mode=mode,
+        hook=args.hook,
+        checks=checks,
+        allow_policy_change=args.allow_policy_change,
+        no_cache=args.no_cache,
+        isolate=args.isolate,
+        github_accept=args.github_accept,
+        env=dict(os.environ),
+    )
+    if args.hook:
+        return _run_hook(args, opts)
+    report = pipeline.run_check(opts)
+    _emit(report, args)
+    return report.exit_code
+
+
+def _run_hook(args: argparse.Namespace, opts: pipeline.CheckOptions) -> int:
+    payload = hooks.parse_payload(args.hook, hooks.read_payload(sys.stdin))
+    result = hooks.run_hook(args.hook, payload, opts)
+    # In hook mode stdout carries only the protocol output; files are still written.
+    if result.report is not None:
+        try:
+            _write_files(result.report, args)
+        except OSError as exc:
+            sys.stderr.write(f"greenproof: could not write the report: {exc}\n")
+    sys.stdout.write(result.stdout)
+    sys.stderr.write(result.stderr)
+    return result.exit_code
+
+
+def _cmd_session_start(args: argparse.Namespace) -> int:
+    if args.hook:
+        # Session start never blocks: any error is exit 0, nothing on stdout, one line on stderr.
+        try:
+            payload = hooks.parse_payload(args.hook, hooks.read_payload(sys.stdin))
+            output = hooks.run_session_start(args.hook, payload, Path.cwd())
+        except Exception as exc:
+            sys.stderr.write(f"greenproof: session-start: {exc}\n")
+            return 0
+        sys.stdout.write(output)
+        return 0
+    repo = gitops.find_repo(Path.cwd())
+    gitops.require_commits(repo)
+    marker = gitops.write_session_marker(repo)
+    sys.stdout.write(f"greenproof: session base recorded in {marker}\n")
+    return 0
+
+
+def _cmd_accept(args: argparse.Namespace) -> int:
+    repo = gitops.find_repo(Path.cwd())
+    if args.list_accepted or args.revoke:
+        if args.fingerprints or args.reason or (args.list_accepted and args.revoke):
+            raise UsageError("accept: --list and --revoke take no other arguments")
+        if args.revoke:
+            accept.revoke(repo, args.revoke)
+            sys.stdout.write(f"greenproof: revoked {args.revoke}\n")
+        else:
+            sys.stdout.write(accept.render_list(accept.load_local(repo)))
+        return 0
+    done = accept.accept(repo, args.fingerprints, args.reason)
+    who = accept.identity(repo)
+    for fp in done:
+        sys.stdout.write(f"greenproof: accepted {fp} as {who}\n")
+    return 0
+
+
+def _cmd_explain(args: argparse.Namespace) -> int:
+    info = RULES.get(args.rule_id)
+    if info is None:
+        raise UsageError(f"unknown rule id {args.rule_id!r}; known: {', '.join(rule_ids())}")
+    sys.stdout.write(
+        f"{info.id} (default severity: {info.default_severity})\n\n{info.description}\n"
+    )
+    return 0
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    from greenproof.init.command import InitOptions, run_init
+
+    summary = run_init(
+        InitOptions(
+            cwd=Path.cwd(),
+            yes=args.yes,
+            agents=args.agents,
+            ci=args.ci,
+            no_verify=args.no_verify,
+            hook_command=args.hook_command,
+        )
+    )
+    sys.stdout.write(summary)
+    return 0
+
+
+def _fail(args: argparse.Namespace, message: str, code: int) -> int:
+    """Report an error on stderr (and as a JSON error report when --json was given)."""
+    sys.stderr.write(f"greenproof: error: {message}\n")
+    json_path = getattr(args, "json_path", None)
+    if json_path:
+        mode = getattr(args, "mode", None) or ("hook" if getattr(args, "hook", None) else "local")
+        try:
+            report = error_report(__version__, mode, message, code)
+            _write(json_path, json.dumps(to_json_dict(report), indent=2) + "\n")
+        except OSError:
+            pass
+    return code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        return exc.code if isinstance(exc.code, int) else 0
+    handlers = {
+        "check": _cmd_check,
+        "session-start": _cmd_session_start,
+        "accept": _cmd_accept,
+        "explain": _cmd_explain,
+        "init": _cmd_init,
+    }
+    try:
+        return handlers[args.command](args)
+    except GreenproofError as exc:
+        return _fail(args, str(exc), exc.exit_code)
+    except Exception as exc:  # fail closed: never exit 0 on an unexpected error
+        return _fail(args, f"internal error: {type(exc).__name__}: {exc}", EXIT_INTERNAL)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

greenproof/errors.py

@@ -0,0 +1,26 @@
+"""Errors that map to exit codes. Anything else that escapes is an internal error (exit 5)."""
+
+from __future__ import annotations
+
+EXIT_PASS = 0
+EXIT_INTEGRITY = 1
+EXIT_COMMAND = 2
+EXIT_SMOKE = 3
+EXIT_USAGE = 4
+EXIT_INTERNAL = 5
+
+
+class GreenproofError(Exception):
+    """Base class for errors greenproof raises on purpose."""
+
+    exit_code = EXIT_INTERNAL
+
+
+class UsageError(GreenproofError):
+    """Usage or configuration error: not a repo, base unresolvable, bad policy (exit 4)."""
+
+    exit_code = EXIT_USAGE
+
+
+class PolicyError(UsageError):
+    """The policy file is invalid; the message names the offending key."""