pr-policy 0.1.0__py3-none-any.whl

pr_policy/__init__.py

@@ -0,0 +1,5 @@
+"""pr-policy: check a pull request against the policy the project wrote down."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

pr_policy/__main__.py

@@ -0,0 +1,4 @@
+from pr_policy.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pr_policy/cli.py

@@ -0,0 +1,225 @@
+"""Command line interface for pr-policy."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from pr_policy import __version__
+from pr_policy.config import DEFAULTS, ConfigError, load_config
+from pr_policy.context import GitError, from_git, load_event
+from pr_policy.infer import render, scan
+from pr_policy.report import ERROR, INFO, WARN, Report, summarise
+from pr_policy.rules import evaluate
+
+MARKS = {ERROR: "error", WARN: "warn", INFO: "info"}
+COLOURS = {ERROR: "31", WARN: "33", INFO: "36"}
+
+
+class Style:
+    def __init__(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def paint(self, code: str, text: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if self.enabled else text
+
+    def severity(self, severity: str) -> str:
+        return self.paint(COLOURS.get(severity, "0"), MARKS.get(severity, severity))
+
+    def bold(self, text: str) -> str:
+        return self.paint("1", text)
+
+    def dim(self, text: str) -> str:
+        return self.paint("2", text)
+
+    def green(self, text: str) -> str:
+        return self.paint("32", text)
+
+
+def _colour_enabled(stream) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def render_text(report: Report, style: Style, skipped: list[str]) -> str:
+    lines = [style.bold("pr-policy"), ""]
+
+    if report.clean:
+        lines.append(style.green("  No findings. This pull request follows the policy."))
+    else:
+        for finding in report.ordered:
+            lines.append(f"  {style.severity(finding.severity)}  {finding.message}")
+            if finding.hint:
+                lines.append(f"        {style.dim(finding.hint)}")
+            lines.append("")
+        lines.pop()
+
+    lines += ["", style.dim(f"  rules run: {', '.join(report.checked) or 'none'}")]
+    if skipped:
+        lines.append(
+            style.dim(f"  skipped (no pull request title or body available): {', '.join(skipped)}")
+        )
+    lines.append(f"  {summarise(report)}")
+
+    if report.errors and not report.enforce:
+        lines.append(
+            style.dim("  reporting only — set 'enforce: true' to fail the build on errors")
+        )
+    return "\n".join(lines)
+
+
+def render_markdown(report: Report, skipped: list[str]) -> str:
+    """A comment body suitable for posting on the pull request."""
+    if report.clean:
+        return (
+            "### pr-policy\n\nNo findings — this pull request follows the project's "
+            "contribution policy.\n"
+        )
+
+    icons = {ERROR: "🔴", WARN: "🟡", INFO: "🔵"}
+    lines = ["### pr-policy", "", f"Found {summarise(report)}.", ""]
+    for finding in report.ordered:
+        lines.append(f"- {icons.get(finding.severity, '•')} **{finding.message}**")
+        if finding.hint:
+            lines.append(f"  {finding.hint}")
+    lines.append("")
+    lines.append(
+        f"<sub>Rules run: {', '.join(report.checked) or 'none'}."
+        + (f" Skipped: {', '.join(skipped)}." if skipped else "")
+        + " These are signals for the maintainer, not a verdict on your change.</sub>"
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _add_check_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--repo", type=Path, default=Path("."), help="repository root")
+    parser.add_argument("--base", default="origin/HEAD", help="base ref to compare against")
+    parser.add_argument("--head", default="HEAD", help="head ref of the pull request")
+    parser.add_argument("--config", type=Path, default=None, help="path to pr-policy.yml")
+    parser.add_argument("--title", default=None, help="pull request title")
+    parser.add_argument(
+        "--body-file",
+        type=Path,
+        default=None,
+        help="file holding the pull request body, or - for stdin",
+    )
+    parser.add_argument("-f", "--format", choices=("text", "json", "markdown"), default="text")
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="fail on error findings even if the configuration does not enforce",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pr-policy",
+        description=(
+            "Check a pull request against the contribution policy the project "
+            "wrote down. Deterministic: it never tries to detect AI."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"pr-policy {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    check = sub.add_parser("check", help="check a pull request against the policy")
+    _add_check_arguments(check)
+
+    init = sub.add_parser(
+        "init", help="write a starter config inferred from CONTRIBUTING.md and the PR template"
+    )
+    init.add_argument("--repo", type=Path, default=Path("."), help="repository root")
+    init.add_argument(
+        "--stdout", action="store_true", help="print the configuration instead of writing it"
+    )
+    init.add_argument("--force", action="store_true", help="overwrite an existing config")
+    return parser
+
+
+def run_check(args: argparse.Namespace) -> int:
+    try:
+        config = load_config(args.repo, args.config)
+    except ConfigError as exc:
+        print(f"pr-policy: {exc}", file=sys.stderr)
+        return 2
+
+    body = None
+    if args.body_file is not None:
+        try:
+            # Read rather than stat: the body often arrives through a pipe or a
+            # process substitution, neither of which is a regular file.
+            if str(args.body_file) == "-":
+                body = sys.stdin.read()
+            else:
+                body = args.body_file.read_text(encoding="utf-8")
+        except OSError as exc:
+            print(f"pr-policy: cannot read {args.body_file}: {exc.strerror}", file=sys.stderr)
+            return 2
+
+    try:
+        pr = from_git(
+            args.repo, args.base, args.head, event=load_event(), title=args.title, body=body
+        )
+    except GitError as exc:
+        print(f"pr-policy: {exc}", file=sys.stderr)
+        return 2
+
+    findings, checked, skipped = evaluate(pr, config)
+    report = Report(findings=findings, enforce=config.enforce or args.strict, checked=checked)
+
+    if args.format == "json":
+        print(report.to_json())
+    elif args.format == "markdown":
+        print(render_markdown(report, skipped), end="")
+    else:
+        print(render_text(report, Style(_colour_enabled(sys.stdout)), skipped))
+    return report.exit_code
+
+
+def run_init(args: argparse.Namespace) -> int:
+    if not args.repo.is_dir():
+        print(f"pr-policy: {args.repo} is not a directory", file=sys.stderr)
+        return 2
+
+    signals = scan(args.repo)
+    content = render(args.repo, signals, DEFAULTS)
+
+    if args.stdout:
+        print(content, end="")
+        return 0
+
+    target = args.repo / ".github" / "pr-policy.yml"
+    if target.exists() and not args.force:
+        print(f"pr-policy: {target} already exists (use --force to overwrite)", file=sys.stderr)
+        return 2
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+
+    print(f"Wrote {target}")
+    if signals:
+        print("\nInferred from this project's own documentation:")
+        for signal in signals:
+            print(f"  {signal.rule}.{signal.option}  <-  {signal.source}")
+    else:
+        print("\nNo project-specific policy found; wrote the defaults.")
+    print("\nReview it, then run: pr-policy check --base origin/main")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "check":
+        return run_check(args)
+    if args.command == "init":
+        return run_init(args)
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

pr_policy/config.py

@@ -0,0 +1,182 @@
+"""Configuration loading for pr-policy.
+
+The configuration is deliberately small. Every rule has an ``enabled`` flag, a
+``severity``, and its own options; anything not set falls back to the defaults
+below. Defaults are chosen so that a repository which installs pr-policy and
+writes no configuration at all gets useful signal without ever failing a build.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_PATHS = (
+    ".github/pr-policy.yml",
+    ".github/pr-policy.yaml",
+    "pr-policy.yml",
+    "pr-policy.yaml",
+)
+
+SEVERITIES = ("error", "warn", "info")
+
+# Identity fragments that coding agents put in their own commit trailers.
+# This is not AI detection: it matches text the agent writes about itself, and
+# a contributor who does not want to be matched simply does not add the trailer.
+AGENT_IDENTITIES = (
+    "claude",
+    "copilot",
+    "codex",
+    "chatgpt",
+    "cursor",
+    "devin",
+    "aider",
+    "gemini",
+    "windsurf",
+    "amazon q",
+    "noreply@anthropic.com",
+    "noreply@openai.com",
+)
+
+DEFAULTS: dict[str, dict[str, Any]] = {
+    "attribution": {
+        "enabled": True,
+        "severity": "warn",
+        # The kernel policy: agents must never certify the DCO.
+        "forbid_agent_sign_off": True,
+        # Prefer `Assisted-by:` over `Co-authored-by:` for tool assistance.
+        "prefer_assisted_by": True,
+        # Off by default: only projects that actually run the DCO want this.
+        "require_signed_off": False,
+        "agent_identities": list(AGENT_IDENTITIES),
+    },
+    "disclosure": {
+        "enabled": False,
+        "severity": "warn",
+        # Any one of these, present and ticked, satisfies the rule.
+        "checkbox_patterns": [
+            r"generative ai",
+            r"\bai\b.*(tool|assist|generat)",
+            r"(tool|assist|generat).*\bai\b",
+        ],
+    },
+    "template": {
+        "enabled": True,
+        "severity": "warn",
+        "min_body_chars": 30,
+        "forbid_unedited_comments": True,
+    },
+    "linked_issue": {
+        "enabled": False,
+        "severity": "warn",
+        "keywords": ["closes", "fixes", "resolves", "refs", "part of"],
+    },
+    "size": {
+        "enabled": True,
+        "severity": "info",
+        "max_lines": 1000,
+        "max_files": 100,
+    },
+}
+
+
+class ConfigError(ValueError):
+    """Raised when a configuration file is present but cannot be used."""
+
+
+@dataclass(frozen=True)
+class RuleConfig:
+    name: str
+    enabled: bool
+    severity: str
+    options: dict[str, Any] = field(default_factory=dict)
+
+    def get(self, key: str, fallback: Any = None) -> Any:
+        return self.options.get(key, fallback)
+
+
+@dataclass(frozen=True)
+class Config:
+    enforce: bool = False
+    rules: dict[str, RuleConfig] = field(default_factory=dict)
+    source: str | None = None
+
+    def rule(self, name: str) -> RuleConfig:
+        return self.rules[name]
+
+
+def _merge(name: str, defaults: dict[str, Any], overrides: Any) -> RuleConfig:
+    if overrides is None:
+        overrides = {}
+    if isinstance(overrides, bool):  # `attribution: false` is a natural shorthand
+        overrides = {"enabled": overrides}
+    if not isinstance(overrides, dict):
+        raise ConfigError(f"rule '{name}' must be a mapping or a boolean")
+
+    unknown = set(overrides) - set(defaults)
+    if unknown:
+        raise ConfigError(f"rule '{name}' has unknown option(s): {', '.join(sorted(unknown))}")
+
+    merged = {**defaults, **overrides}
+    severity = merged["severity"]
+    if severity not in SEVERITIES:
+        raise ConfigError(
+            f"rule '{name}' has severity '{severity}', expected one of {', '.join(SEVERITIES)}"
+        )
+
+    options = {k: v for k, v in merged.items() if k not in ("enabled", "severity")}
+    return RuleConfig(
+        name=name, enabled=bool(merged["enabled"]), severity=severity, options=options
+    )
+
+
+def default_config() -> Config:
+    return Config(
+        enforce=False,
+        rules={name: _merge(name, defaults, {}) for name, defaults in DEFAULTS.items()},
+    )
+
+
+def find_config(root: Path) -> Path | None:
+    for candidate in CONFIG_PATHS:
+        path = root / candidate
+        if path.is_file():
+            return path
+    return None
+
+
+def load_config(root: Path, explicit: Path | None = None) -> Config:
+    """Load configuration from ``explicit``, or from the first conventional path."""
+    path = explicit or find_config(root)
+    if path is None:
+        return default_config()
+    if not path.is_file():
+        raise ConfigError(f"no such configuration file: {path}")
+
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{path}: top level must be a mapping")
+
+    unknown_top = set(raw) - {"version", "enforce", "rules"}
+    if unknown_top:
+        raise ConfigError(f"{path}: unknown top-level key(s): {', '.join(sorted(unknown_top))}")
+
+    rules_raw = raw.get("rules") or {}
+    if not isinstance(rules_raw, dict):
+        raise ConfigError(f"{path}: 'rules' must be a mapping")
+
+    unknown_rules = set(rules_raw) - set(DEFAULTS)
+    if unknown_rules:
+        raise ConfigError(f"{path}: unknown rule(s): {', '.join(sorted(unknown_rules))}")
+
+    rules = {
+        name: _merge(name, defaults, rules_raw.get(name)) for name, defaults in DEFAULTS.items()
+    }
+    return Config(enforce=bool(raw.get("enforce", False)), rules=rules, source=str(path))

pr_policy/context.py

@@ -0,0 +1,182 @@
+"""The pull request under inspection.
+
+Everything pr-policy evaluates comes from two places: the git history of the
+branch, and — when running inside a GitHub Action — the event payload, which is
+the only source for the pull request's title, body and labels.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# A git trailer: "Key: value", where the key has no whitespace.
+TRAILER = re.compile(r"^(?P<key>[A-Za-z][A-Za-z0-9-]*):[ \t]*(?P<value>.+?)\s*$")
+
+UNIT = "\x1f"
+RECORD = "\x1e"
+
+
+class GitError(RuntimeError):
+    """Raised when git is unavailable or a revision cannot be resolved."""
+
+
+def _git(root: Path, *args: str) -> str:
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:  # pragma: no cover - depends on the host
+        raise GitError("git is not installed or not on PATH") from exc
+    if proc.returncode != 0:
+        raise GitError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def parse_trailers(message: str) -> dict[str, list[str]]:
+    """Return the trailers from a commit message, keyed by lowercased name.
+
+    Git treats only the final paragraph as the trailer block, and so do we: a
+    line reading "Note: see below" halfway through a commit body is prose, not
+    a trailer.
+    """
+    paragraphs = [p for p in re.split(r"\n\s*\n", message.strip()) if p.strip()]
+    if not paragraphs:
+        return {}
+
+    trailers: dict[str, list[str]] = {}
+    for line in paragraphs[-1].splitlines():
+        match = TRAILER.match(line)
+        if match:
+            trailers.setdefault(match.group("key").lower(), []).append(match.group("value"))
+    return trailers
+
+
+@dataclass(frozen=True)
+class Commit:
+    sha: str
+    author_name: str
+    author_email: str
+    message: str
+
+    @property
+    def subject(self) -> str:
+        return self.message.strip().splitlines()[0] if self.message.strip() else ""
+
+    @property
+    def short_sha(self) -> str:
+        return self.sha[:8]
+
+    @property
+    def trailers(self) -> dict[str, list[str]]:
+        return parse_trailers(self.message)
+
+    def trailer(self, name: str) -> list[str]:
+        return self.trailers.get(name.lower(), [])
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    """A pull request, as far as pr-policy can see it."""
+
+    title: str = ""
+    body: str = ""
+    author: str = ""
+    commits: list[Commit] = field(default_factory=list)
+    changed_files: list[str] = field(default_factory=list)
+    additions: int = 0
+    deletions: int = 0
+    labels: list[str] = field(default_factory=list)
+    # False when nothing supplied the title and body — running over a local
+    # branch rather than inside a pull request. Rules that read the body are
+    # skipped rather than guessing, because an absent body is not an empty one.
+    metadata_available: bool = False
+
+    @property
+    def total_lines(self) -> int:
+        return self.additions + self.deletions
+
+
+def commits_between(root: Path, base: str, head: str) -> list[Commit]:
+    raw = _git(
+        root,
+        "log",
+        f"--format=%H{UNIT}%an{UNIT}%ae{UNIT}%B{RECORD}",
+        f"{base}..{head}",
+    )
+    commits = []
+    for record in raw.split(RECORD):
+        record = record.strip("\n")
+        if not record.strip():
+            continue
+        sha, name, email, message = record.split(UNIT, 3)
+        commits.append(Commit(sha=sha, author_name=name, author_email=email, message=message))
+    return commits
+
+
+def diff_stats(root: Path, base: str, head: str) -> tuple[list[str], int, int]:
+    """Return changed files and line counts for ``base...head`` (merge base)."""
+    raw = _git(root, "diff", "--numstat", f"{base}...{head}")
+    files: list[str] = []
+    additions = deletions = 0
+    for line in raw.splitlines():
+        parts = line.split("\t")
+        if len(parts) != 3:
+            continue
+        added, removed, path = parts
+        files.append(path)
+        # Binary files report "-" rather than a count.
+        additions += int(added) if added.isdigit() else 0
+        deletions += int(removed) if removed.isdigit() else 0
+    return files, additions, deletions
+
+
+def load_event(path: str | None = None) -> dict:
+    """Read the GitHub Actions event payload, if this is running in one."""
+    event_path = path or os.environ.get("GITHUB_EVENT_PATH")
+    if not event_path or not Path(event_path).is_file():
+        return {}
+    try:
+        return json.loads(Path(event_path).read_text(encoding="utf-8")) or {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def from_git(
+    root: Path,
+    base: str,
+    head: str = "HEAD",
+    event: dict | None = None,
+    title: str | None = None,
+    body: str | None = None,
+) -> PullRequest:
+    """Build a :class:`PullRequest` from the repository and, optionally, an event.
+
+    ``title`` and ``body`` override the event payload, which is what makes the
+    body rules runnable outside a pull request.
+    """
+    commits = commits_between(root, base, head)
+    files, additions, deletions = diff_stats(root, base, head)
+
+    payload = (event or {}).get("pull_request") or {}
+    has_metadata = bool(payload) or title is not None or body is not None
+
+    return PullRequest(
+        title=title if title is not None else (payload.get("title") or ""),
+        body=body if body is not None else (payload.get("body") or ""),
+        author=(payload.get("user") or {}).get("login") or "",
+        commits=commits,
+        changed_files=files,
+        additions=payload.get("additions", additions),
+        deletions=payload.get("deletions", deletions),
+        labels=[label.get("name", "") for label in payload.get("labels") or []],
+        metadata_available=has_metadata,
+    )