diff --git a/.github/workflows/attribution-guard.yml b/.github/workflows/attribution-guard.yml new file mode 100644 index 0000000..a03bdbe --- /dev/null +++ b/.github/workflows/attribution-guard.yml @@ -0,0 +1,77 @@ +name: Attribution Guard + +on: + pull_request: + types: [opened, reopened, synchronize, edited, labeled, unlabeled, ready_for_review] + push: + branches: [main] + +permissions: + contents: read + pull-requests: read + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: true + +jobs: + attribution-guard: + name: Attribution Guard + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Checkout trusted helper from base commit + if: github.event_name == 'pull_request' + uses: actions/checkout@v7 + with: + ref: ${{ github.event.pull_request.base.sha }} + path: trusted + persist-credentials: false + + - name: Locate helper + id: helper + if: github.event_name == 'pull_request' + run: | + if [[ -f trusted/scripts/attribution_guard.py ]]; then + echo "path=trusted/scripts/attribution_guard.py" >> "$GITHUB_OUTPUT" + else + echo "::notice::Base commit has no guard helper; bootstrapping from the pull request head." + echo "path=bootstrap/scripts/attribution_guard.py" >> "$GITHUB_OUTPUT" + echo "bootstrap=true" >> "$GITHUB_OUTPUT" + fi + + - name: Checkout pull request helper (bootstrap only) + if: github.event_name == 'pull_request' && steps.helper.outputs.bootstrap == 'true' + uses: actions/checkout@v7 + with: + ref: ${{ github.event.pull_request.head.sha }} + path: bootstrap + persist-credentials: false + + - name: Checkout pushed history + if: github.event_name == 'push' + uses: actions/checkout@v7 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@v7 + with: + python-version: "3.12" + + - name: Check pull request metadata + if: github.event_name == 'pull_request' + env: + GITHUB_TOKEN: ${{ github.token }} + HELPER: ${{ steps.helper.outputs.path }} + PR_NUMBER: ${{ github.event.pull_request.number }} + run: python "$HELPER" pull-request --repo "$GITHUB_REPOSITORY" --number "$PR_NUMBER" + + - name: Audit pushed commits + if: github.event_name == 'push' + env: + BEFORE_SHA: ${{ github.event.before }} + AFTER_SHA: ${{ github.sha }} + run: python scripts/attribution_guard.py push --before "$BEFORE_SHA" --after "$AFTER_SHA" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bbf59c0..5938f36 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,3 +1,5 @@ +default_install_hook_types: [commit-msg] + repos: - repo: https://github.com/asottile/pyupgrade rev: v3.22.0 @@ -51,6 +53,18 @@ repos: language: system pass_filenames: false stages: [pre-push] + - id: attribution-guard-commit-msg + name: attribution-guard (commit message) + entry: python scripts/attribution_guard.py commit-msg + language: python + stages: [commit-msg] + - id: attribution-guard-pre-push + name: attribution-guard (pushed refs and commits) + entry: python scripts/attribution_guard.py pre-push + language: python + pass_filenames: false + always_run: true + stages: [pre-push] - id: pyright name: pyright entry: uv run --frozen --extra dev pyright --pythonversion 3.12 ser tests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89d6bc9..03255b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,12 +51,29 @@ Install or refresh git hooks manually: ./scripts/install_git_hooks.sh ``` -The generated `.git/hooks/pre-push` runs `bash ./scripts/run_prepush_gate.sh`, which: +The generated `.git/hooks/pre-push` first runs the attribution guard on the pushed refs (see below), then runs `bash ./scripts/run_prepush_gate.sh`, which: - runs `make prepush` to attempt formatter/linter auto-fixes first - reruns the canonical pre-push verification lane - aborts the push if non-fixable issues remain - aborts the push if the hook changed the working tree, so you can review, stage, and commit the fixes first +The installer also runs `pre-commit install --hook-type commit-msg` (the only type in `default_install_hook_types`; the pre-push hook stays owned by the installer). + +## Attribution Guard +`scripts/attribution_guard.py` rejects AI-tool attribution in branch and tag names, commit messages, +author/committer emails, pull request titles and bodies, and labels. Naming a provider or dependency +as the subject of a change stays allowed; only attribution (co-author trailers, "generated with" +footers, session links, tool-namespaced refs) is rejected. Its pattern block is vendored +byte-for-byte from the shared source and pinned by a digest test; re-vendor it, never edit it. + +- `commit-msg` stage: checks the message being committed. +- `pre-push`: checks every pushed ref name and each commit it introduces. Under + `pre-commit run --hook-stage pre-push` it checks the current branch and its unpushed commits. +- CI: `.github/workflows/attribution-guard.yml` publishes the `Attribution Guard` check. It + refetches pull request metadata from the API on every PR event (including edits and label + changes) and audits each push to `main`. It is a separate required status check on the `main` + ruleset, alongside `required-ci`, so metadata-only events re-evaluate it without new commits. + ## Boundary Commands (When Required) Run the boundary lane whenever your change touches `ser/api.py`, `ser/_internal/api/*`, `ser/__main__.py`, or boundary contract tests: diff --git a/scripts/attribution_guard.py b/scripts/attribution_guard.py new file mode 100755 index 0000000..06de3fc --- /dev/null +++ b/scripts/attribution_guard.py @@ -0,0 +1,439 @@ +#!/usr/bin/env python3 +"""Reject AI-tool attribution in refs, commit metadata, and pull request metadata. + +Modes: + commit-msg FILE git commit-msg hook (pre-commit `commit-msg` stage). + pre-push [REMOTE] [--stdin] git pre-push hook. Reads git's ref lines from stdin with + `--stdin`, else pre-commit's `PRE_COMMIT_*` variables, else + checks the current branch and its unpushed commits. + push --before SHA --after SHA Post-merge audit of the commits pushed to a branch. + pull-request --repo O/R --number N Refetches pull request metadata from the GitHub API. + +The pattern block below is a byte-identical copy of the shared attribution source that the +repository rulesets and local agent hooks also use. Re-vendor it; never edit it in place. +""" + +from __future__ import annotations + +import argparse +import json +import os +import re +import subprocess +import sys +import urllib.error +import urllib.request +from collections.abc import Sequence +from dataclasses import dataclass +from pathlib import Path +from typing import cast + +# --- Vendored attribution patterns (byte-identical; do not edit) --- +AGENT_NAMES = r"(?:claude|anthropic|codex|openai|chatgpt|copilot)" +TOOL_NAMES = ( + r"(?:claude|anthropic|codex|openai|chatgpt|copilot|gemini|cursor|windsurf|devin|aider|cline)" +) + +# Tool name used as a namespace (claude/..., ai-codex/...), not as the subject of the work. +REF_NAME = rf"(?i)^(?:refs/(?:heads|tags)/)?(?:(?:ai|agents?|assistants?|bots?|llm)[/._-])?{AGENT_NAMES}(?:/|\n?$)" + +COMMIT_MESSAGE = ( + r"(?im)" + rf"(?:^[ \t]*(?:co-authored-by|assisted-by|generated-by|ai-assisted-by)[ \t]*:[^\n]*{TOOL_NAMES})" + rf"|(?:^[^a-z0-9\n]{{0,8}}(?:generated|created|written|authored|produced|assisted)[ \t]+(?:by|with|using|via)[ \t]+(?:an?[ \t]+|the[ \t]+)?\[?{TOOL_NAMES}(?:[^a-z0-9\n-]|\n?$))" + r"|(?:claude\.ai/(?:code|share)|claude\.com/claude-code|chatgpt\.com/(?:codex|share))" + r"|(?:noreply@(?:anthropic|openai)\.com)" + rf"|(?:^merge pull request #[0-9]+ from [^ \n]+/{AGENT_NAMES}/)" +) + +EMAIL = r"(?i)@(?:anthropic|openai)\.com\n?$" +LABEL = r"(?i)(?:claude|anthropic|codex|openai)" +# --- End vendored attribution patterns --- + +REF_RE = re.compile(REF_NAME) +MSG_RE = re.compile(COMMIT_MESSAGE) +EMAIL_RE = re.compile(EMAIL) +LABEL_RE = re.compile(LABEL) + +SCISSORS_MARKER = "------------------------ >8 ------------------------" +COMMENT_PREFIX = "#" +API_PAGE_SIZE = 100 +API_TIMEOUT_SECONDS = 30 +EXIT_CLEAN = 0 +EXIT_VIOLATION = 1 +EXIT_ERROR = 2 + + +class GuardError(RuntimeError): + """Raised when the guard cannot gather the data it must verify.""" + + +@dataclass(frozen=True) +class Violation: + """One metadata field that matched an attribution pattern.""" + + field: str + match: str + + def render(self) -> str: + """Returns a single-line description naming the offending field.""" + return f"{self.field}: matched {self.match!r}" + + +@dataclass(frozen=True) +class Commit: + """Commit metadata subject to the attribution policy.""" + + sha: str + message: str + author_email: str + committer_email: str + + +@dataclass(frozen=True) +class RefUpdate: + """One ref update as reported by git's pre-push protocol.""" + + local_sha: str + remote_ref: str + remote_sha: str + + +@dataclass(frozen=True) +class PullRequestSnapshot: + """Pull request metadata refetched from the API at check time.""" + + title: str + body: str + head_ref: str + labels: tuple[str, ...] + commits: tuple[Commit, ...] + + +def _search(pattern: re.Pattern[str], value: str, field: str) -> list[Violation]: + match = pattern.search(value) + return [] if match is None else [Violation(field=field, match=match.group(0).strip())] + + +def check_ref_name(name: str, field: str) -> list[Violation]: + """Checks one branch or tag name.""" + return _search(REF_RE, name, field) + + +def check_message(text: str, field: str) -> list[Violation]: + """Checks one full message text (commit message, PR title, or PR body).""" + return _search(MSG_RE, text, field) + + +def check_email(email: str, field: str) -> list[Violation]: + """Checks one author or committer email.""" + return _search(EMAIL_RE, email, field) + + +def check_label(name: str) -> list[Violation]: + """Checks one pull request label name.""" + return _search(LABEL_RE, name, f"label {name!r}") + + +def check_commit(commit: Commit) -> list[Violation]: + """Checks a commit's message plus its author and committer emails.""" + prefix = f"commit {commit.sha[:12]}" + return [ + *check_message(commit.message, f"{prefix} message"), + *check_email(commit.author_email, f"{prefix} author email"), + *check_email(commit.committer_email, f"{prefix} committer email"), + ] + + +def check_pull_request(snapshot: PullRequestSnapshot) -> list[Violation]: + """Checks every attribution-bearing field of one pull request.""" + violations = [ + *check_message(snapshot.title, "pull request title"), + *check_message(snapshot.body, "pull request body"), + *check_ref_name(snapshot.head_ref, f"head ref {snapshot.head_ref!r}"), + ] + for label in snapshot.labels: + violations.extend(check_label(label)) + for commit in snapshot.commits: + violations.extend(check_commit(commit)) + return violations + + +def strip_commit_message_comments(text: str) -> str: + """Drops what git strips before committing: comment lines and the verbose-diff tail.""" + kept: list[str] = [] + for line in text.splitlines(keepends=True): + if line.startswith(COMMENT_PREFIX) and SCISSORS_MARKER in line: + break + if line.startswith(COMMENT_PREFIX): + continue + kept.append(line) + return "".join(kept) + + +def _is_null_sha(sha: str) -> bool: + return bool(sha) and set(sha) == {"0"} + + +def _git(args: Sequence[str]) -> subprocess.CompletedProcess[str]: + return subprocess.run(["git", *args], capture_output=True, text=True, check=False) + + +def _commit_exists(sha: str) -> bool: + return _git(["cat-file", "-e", f"{sha}^{{commit}}"]).returncode == 0 + + +def read_commits(revisions: Sequence[str]) -> list[Commit]: + """Reads commit metadata for a `git log` revision selection.""" + completed = _git(["log", "-z", "--format=%H%n%ae%n%ce%n%B", *revisions, "--"]) + if completed.returncode != 0: + raise GuardError(f"git log {' '.join(revisions)} failed: {completed.stderr.strip()}") + commits: list[Commit] = [] + for record in completed.stdout.split("\0"): + record = record.lstrip("\n") + if not record: + continue + sha, author_email, committer_email, message = (record.split("\n", 3) + ["", "", ""])[:4] + commits.append(Commit(sha, message, author_email, committer_email)) + return commits + + +def _remote_exclusion(remote: str | None) -> str: + configured = set(_git(["remote"]).stdout.split()) + return f"--remotes={remote}" if remote in configured else "--remotes" + + +def _introduced_revisions(update: RefUpdate, remote: str | None) -> list[str]: + if not _is_null_sha(update.remote_sha) and _commit_exists(update.remote_sha): + return [f"{update.remote_sha}..{update.local_sha}"] + return [update.local_sha, "--not", _remote_exclusion(remote)] + + +def parse_pre_push_lines(lines: Sequence[str]) -> list[RefUpdate]: + """Parses ` ` lines from git.""" + updates: list[RefUpdate] = [] + for raw_line in lines: + parts = raw_line.split() + if not parts: + continue + if len(parts) != 4: + raise GuardError(f"Malformed pre-push line: {raw_line.strip()!r}") + _, local_sha, remote_ref, remote_sha = parts + updates.append(RefUpdate(local_sha=local_sha, remote_ref=remote_ref, remote_sha=remote_sha)) + return updates + + +def check_ref_updates(updates: Sequence[RefUpdate], remote: str | None) -> list[Violation]: + """Checks pushed ref names and every commit each update introduces.""" + violations: list[Violation] = [] + for update in updates: + if _is_null_sha(update.local_sha): + continue + violations.extend(check_ref_name(update.remote_ref, f"pushed ref {update.remote_ref!r}")) + for commit in read_commits(_introduced_revisions(update, remote)): + violations.extend(check_commit(commit)) + return violations + + +def _pre_commit_ref_update() -> RefUpdate | None: + to_ref = os.environ.get("PRE_COMMIT_TO_REF", "") + if not to_ref: + return None + return RefUpdate( + local_sha=to_ref, + remote_ref=os.environ.get("PRE_COMMIT_REMOTE_BRANCH", ""), + remote_sha=os.environ.get("PRE_COMMIT_FROM_REF", ""), + ) + + +def check_unpushed_head() -> list[Violation]: + """Fallback for `pre-commit run`: the current branch and commits on no remote.""" + if _git(["rev-parse", "--verify", "--quiet", "HEAD"]).returncode != 0: + return [] + violations: list[Violation] = [] + branch = _git(["symbolic-ref", "--quiet", "--short", "HEAD"]) + if branch.returncode == 0: + name = branch.stdout.strip() + violations.extend(check_ref_name(name, f"current branch {name!r}")) + for commit in read_commits(["HEAD", "--not", "--remotes"]): + violations.extend(check_commit(commit)) + return violations + + +def _api_get(url: str, token: str) -> object: + request = urllib.request.Request( + url, + headers={ + "Accept": "application/vnd.github+json", + "Authorization": f"Bearer {token}", + "User-Agent": "attribution-guard", + "X-GitHub-Api-Version": "2022-11-28", + }, + ) + try: + with urllib.request.urlopen(request, timeout=API_TIMEOUT_SECONDS) as response: + return cast(object, json.load(response)) + except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as error: + raise GuardError(f"GitHub API request failed for {url}: {error}") from error + + +def _mapping(value: object, context: str) -> dict[str, object]: + if not isinstance(value, dict): + raise GuardError(f"Unexpected API payload: {context} is not an object.") + return cast(dict[str, object], value) + + +def _string(value: object, context: str) -> str: + if not isinstance(value, str): + raise GuardError(f"Unexpected API payload: {context} is not a string.") + return value + + +def _sequence(value: object, context: str) -> list[object]: + if not isinstance(value, list): + raise GuardError(f"Unexpected API payload: {context} is not a list.") + return cast(list[object], value) + + +def _api_commit(item: object) -> Commit: + entry = _mapping(item, "commit entry") + sha = _string(entry.get("sha"), "commit sha") + details = _mapping(entry.get("commit"), f"commit {sha}") + return Commit( + sha=sha, + message=_string(details.get("message"), f"commit {sha} message"), + author_email=_string(_mapping(details.get("author"), "author").get("email"), "email"), + committer_email=_string( + _mapping(details.get("committer"), "committer").get("email"), "email" + ), + ) + + +def fetch_pull_request(api_url: str, repo: str, number: int, token: str) -> PullRequestSnapshot: + """Refetches title, body, head ref, labels, and every commit of one pull request.""" + base_url = f"{api_url.rstrip('/')}/repos/{repo}/pulls/{number}" + pull = _mapping(_api_get(base_url, token), "pull request") + raw_body = pull.get("body") + labels = tuple( + _string(_mapping(label, "label").get("name"), "label name") + for label in _sequence(pull.get("labels"), "labels") + ) + expected_commits = pull.get("commits") + if not isinstance(expected_commits, int): + raise GuardError("Unexpected API payload: pull request commit count is missing.") + + commits: list[Commit] = [] + page = 1 + while True: + batch = _sequence( + _api_get(f"{base_url}/commits?per_page={API_PAGE_SIZE}&page={page}", token), + "commits page", + ) + commits.extend(_api_commit(item) for item in batch) + if len(batch) < API_PAGE_SIZE: + break + page += 1 + if len(commits) != expected_commits: + raise GuardError( + f"Fetched {len(commits)} of {expected_commits} pull request commits; " + "refusing to pass an incomplete check." + ) + return PullRequestSnapshot( + title=_string(pull.get("title"), "title"), + body="" if raw_body is None else _string(raw_body, "body"), + head_ref=_string(_mapping(pull.get("head"), "head").get("ref"), "head ref"), + labels=labels, + commits=tuple(commits), + ) + + +def _report(violations: Sequence[Violation], scope: str) -> int: + annotate = os.environ.get("GITHUB_ACTIONS") == "true" + for violation in violations: + line = f"attribution guard: {violation.render()}" + print(f"::error title=Attribution Guard::{line}" if annotate else line, file=sys.stderr) + if violations: + print(f"attribution guard: {len(violations)} violation(s) in {scope}.", file=sys.stderr) + return EXIT_VIOLATION + print(f"attribution guard: {scope}: clean.") + return EXIT_CLEAN + + +def _run_commit_msg(args: argparse.Namespace) -> int: + text = Path(args.message_file).read_text(encoding="utf-8", errors="replace") + return _report(check_message(strip_commit_message_comments(text), "commit message"), "commit") + + +def _run_pre_push(args: argparse.Namespace) -> int: + remote = cast(str | None, args.remote) or os.environ.get("PRE_COMMIT_REMOTE_NAME") + if args.stdin: + updates = parse_pre_push_lines(sys.stdin.read().splitlines()) + return _report(check_ref_updates(updates, remote), "push") + pre_commit_update = _pre_commit_ref_update() + if pre_commit_update is not None: + return _report(check_ref_updates([pre_commit_update], remote), "push") + return _report(check_unpushed_head(), "unpushed commits") + + +def _run_push(args: argparse.Namespace) -> int: + before = cast(str, args.before) + after = cast(str, args.after) + if _is_null_sha(before) or not _commit_exists(before): + print(f"attribution guard: base {before!r} unavailable; checking {after} only.") + revisions = ["-1", after] + else: + revisions = [f"{before}..{after}"] + violations: list[Violation] = [] + for commit in read_commits(revisions): + violations.extend(check_commit(commit)) + return _report(violations, f"push {before[:12]}..{after[:12]}") + + +def _run_pull_request(args: argparse.Namespace) -> int: + token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN") + if not token: + raise GuardError("GITHUB_TOKEN or GH_TOKEN is required for pull-request mode.") + api_url = os.environ.get("GITHUB_API_URL", "https://api.github.com") + snapshot = fetch_pull_request(api_url, cast(str, args.repo), cast(int, args.number), token) + scope = f"pull request #{args.number} ({len(snapshot.commits)} commits)" + return _report(check_pull_request(snapshot), scope) + + +def _build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0] if __doc__ else None) + modes = parser.add_subparsers(dest="mode", required=True) + + commit_msg = modes.add_parser("commit-msg", help="Check a commit message file.") + commit_msg.add_argument("message_file") + commit_msg.set_defaults(handler=_run_commit_msg) + + pre_push = modes.add_parser("pre-push", help="Check refs and commits about to be pushed.") + pre_push.add_argument("remote", nargs="?", default=None) + pre_push.add_argument("url", nargs="?", default=None) + pre_push.add_argument("--stdin", action="store_true", help="Read git pre-push ref lines.") + pre_push.set_defaults(handler=_run_pre_push) + + push = modes.add_parser("push", help="Audit commits pushed to a branch.") + push.add_argument("--before", required=True) + push.add_argument("--after", required=True) + push.set_defaults(handler=_run_push) + + pull_request = modes.add_parser("pull-request", help="Check pull request metadata.") + pull_request.add_argument("--repo", required=True) + pull_request.add_argument("--number", required=True, type=int) + pull_request.set_defaults(handler=_run_pull_request) + return parser + + +def main(argv: Sequence[str] | None = None) -> int: + """Runs one guard mode and returns its process exit status.""" + args = _build_parser().parse_args(argv) + try: + return cast(int, args.handler(args)) + except GuardError as error: + print(f"attribution guard: error: {error}", file=sys.stderr) + return EXIT_ERROR + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/install_git_hooks.sh b/scripts/install_git_hooks.sh index 90cb945..b94a7c3 100755 --- a/scripts/install_git_hooks.sh +++ b/scripts/install_git_hooks.sh @@ -15,8 +15,13 @@ mkdir -p .git/hooks cat > .git/hooks/pre-push <<'EOF' #!/usr/bin/env bash set -euo pipefail +# git passes the pushed refs on stdin; only the attribution guard consumes them. +uv run --frozen --extra dev python ./scripts/attribution_guard.py pre-push --stdin "$@" exec bash ./scripts/run_prepush_gate.sh EOF chmod +x .git/hooks/pre-push -printf '[hooks] installed .git/hooks/pre-push -> bash ./scripts/run_prepush_gate.sh\n' +uv run --frozen --extra dev pre-commit install --hook-type commit-msg + +printf '[hooks] installed .git/hooks/pre-push -> attribution guard + bash ./scripts/run_prepush_gate.sh\n' +printf '[hooks] installed .git/hooks/commit-msg -> pre-commit commit-msg stage (attribution guard)\n' diff --git a/tests/suites/integration/architecture/test_ci_workflow_contracts.py b/tests/suites/integration/architecture/test_ci_workflow_contracts.py index 65129e7..bab64b2 100644 --- a/tests/suites/integration/architecture/test_ci_workflow_contracts.py +++ b/tests/suites/integration/architecture/test_ci_workflow_contracts.py @@ -119,6 +119,7 @@ def test_no_workflow_uses_pull_request_target(repo_root: Path) -> None: def test_workflow_permissions_are_least_privilege(repo_root: Path) -> None: """Workflow permissions should stay explicit and narrow.""" expected_permissions = { + "attribution-guard.yml": {"contents": "read", "pull-requests": "read"}, "ci.yml": {"contents": "read"}, "codeql.yml": {"actions": "read", "contents": "read", "security-events": "write"}, "darwin-x86_64-validation.yml": {"contents": "read"}, @@ -312,3 +313,48 @@ def test_advisory_code_scanning_and_scorecard_are_configured(repo_root: Path) -> assert {"schedule", "workflow_dispatch"} == _event_names(scorecard) scorecard_steps = _steps(_job(scorecard, "scorecard")) assert any(_uses_action_major(step, "ossf/scorecard-action", 2) for step in scorecard_steps) + + +def test_attribution_guard_is_a_standalone_metadata_gate(repo_root: Path) -> None: + """The guard must re-run on PR metadata events and stay outside the CI aggregate.""" + workflow = _workflow(repo_root, "attribution-guard.yml") + triggers = _as_mapping(workflow["on"], context="attribution-guard triggers") + pull_request = _as_mapping(triggers["pull_request"], context="pull_request trigger") + push = _as_mapping(triggers["push"], context="push trigger") + + assert set(triggers) == {"pull_request", "push"} + assert set(_as_sequence(pull_request["types"], context="pull_request types")) == { + "opened", + "reopened", + "synchronize", + "edited", + "labeled", + "unlabeled", + "ready_for_review", + } + assert _as_sequence(push["branches"], context="push branches") == ["main"] + for trigger in (pull_request, push): + assert not {"paths", "paths-ignore", "branches-ignore"} & set(trigger) + + jobs = _jobs(workflow) + assert set(jobs) == {"attribution-guard"} + job = _job(workflow, "attribution-guard") + assert job["name"] == "Attribution Guard" + assert "if" not in job + assert "continue-on-error" not in job + steps = _steps(job) + checkouts = [ + step for step in steps if str(step.get("uses", "")).startswith("actions/checkout@") + ] + assert checkouts + for step in checkouts: + assert ( + _as_mapping(step["with"], context="checkout inputs")["persist-credentials"] == "false" + ) + assert not any("continue-on-error" in step for step in steps) + assert "pull-request --repo" in _run_commands(job) + assert "push --before" in _run_commands(job) + + ci_jobs = _jobs(_workflow(repo_root, "ci.yml")) + assert "attribution-guard" not in ci_jobs + assert "attribution-guard" not in _needs(_job(_workflow(repo_root, "ci.yml"), "required-ci")) diff --git a/tests/suites/unit/scripts/test_attribution_guard.py b/tests/suites/unit/scripts/test_attribution_guard.py new file mode 100644 index 0000000..9a06a86 --- /dev/null +++ b/tests/suites/unit/scripts/test_attribution_guard.py @@ -0,0 +1,482 @@ +"""Contracts for the attribution guard helper, its shared patterns, and its golden vectors.""" + +from __future__ import annotations + +import hashlib +import importlib.util +import json +import os +import re +import subprocess +import sys +import threading +from collections.abc import Callable, Iterator, Mapping, Sequence +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from types import ModuleType +from typing import Protocol, cast +from urllib.parse import urlsplit + +import pytest + +# Digest of REF_NAME, COMMIT_MESSAGE, EMAIL and LABEL joined by NUL, from the shared source. +SHARED_PATTERN_DIGEST = "0035aae603cfb855a7ed152d97ddc396646ed62b418b80c165bcec85eac1e7bd" + +# Golden vectors vendored verbatim from the shared attribution source. +GOLDEN = { + "ref_deny": [ + "codex/security-audit-remediation", + "claude/fix-tests", + "copilot/fix-123", + "ai-codex/x", + "agent/claude/y", + "openai", + "Codex/Foo", + "refs/heads/claude/x", + "chatgpt/idea", + ], + "ref_allow": [ + "fix/openai-provider-validation-fixtures", + "dependabot/uv/openai-whisper-20250625", + "openai-whisper-bump", + "fix/claude-adapter-timeout", + "chore/remove-codex-label", + "main", + "feat/training-readiness-contract", + "v1.2.0", + ], + "msg_deny": [ + "fix: x\n\nCo-Authored-By: Claude Opus 4.8 \n", + "fix: x\n\nCo-authored-by: Codex ", + "feat: y\n\n\N{ROBOT FACE} Generated with [Claude Code](https://claude.com/claude-code)\n", + "chore: z\n\nGenerated by Codex", + "docs: w\n\nAssisted-by: GitHub Copilot", + "fix: v\n\nSession: https://claude.ai/code/session_123", + "fix: u\n\nhttps://chatgpt.com/codex/tasks/task_e_1", + "Merge pull request #37 from jsugg/codex/refactor-hotspots-coverage-gates\n\nRefactor", + "fix: t\n\nWritten with OpenAI Codex.", + ], + "msg_allow": [ + "refactor: x\n\nparentheses, so the public API snapshot is regenerated with no", + "chore(deps): bump openai-whisper from 20250625 to 20260101", + "fix(provider): handle openai timeout", + "chore(deps): bump x\n\nCo-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>", + "test: fixtures\n\nGenerated with openai-whisper large model", + "build(deps): bump y\n\nSigned-off-by: dependabot[bot] ", + "docs: explain codex label cleanup", + "Merge pull request #136 from jsugg/fix/openai-provider-validation-fixtures", + "fix(claude-adapter): retry on 529", + ], + "email_deny": ["noreply@anthropic.com", "codex@openai.com\n"], + "email_allow": ["juanpedrosugg@gmail.com", "49699333+dependabot[bot]@users.noreply.github.com"], +} + +LABEL_DENY = ["codex", "claude-generated", "Anthropic", "openai-review"] +LABEL_ALLOW = ["dependencies", "python", "github_actions", "security"] + +CLEAN_EMAIL = "dev@example.com" +DENIED_MESSAGE = GOLDEN["msg_deny"][3] +DENIED_REF = "refs/heads/" + GOLDEN["ref_deny"][1] + + +class _Guard(Protocol): + REF_NAME: str + COMMIT_MESSAGE: str + EMAIL: str + LABEL: str + REF_RE: re.Pattern[str] + MSG_RE: re.Pattern[str] + EMAIL_RE: re.Pattern[str] + LABEL_RE: re.Pattern[str] + + def strip_commit_message_comments(self, text: str) -> str: ... + + +@pytest.fixture(scope="module") +def guard_path(repo_root: Path) -> Path: + """Returns the guard helper path inside the repository under test.""" + return repo_root / "scripts" / "attribution_guard.py" + + +@pytest.fixture(scope="module") +def guard(guard_path: Path) -> Iterator[_Guard]: + """Loads the helper as a module; dataclasses need it registered in `sys.modules`.""" + spec = importlib.util.spec_from_file_location("attribution_guard_under_test", guard_path) + assert spec is not None and spec.loader is not None + module: ModuleType = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + try: + spec.loader.exec_module(module) + yield cast(_Guard, module) + finally: + sys.modules.pop(spec.name, None) + + +def test_vendored_patterns_match_shared_source(guard: _Guard) -> None: + """The pattern strings must stay byte-identical to the shared source.""" + joined = "\0".join((guard.REF_NAME, guard.COMMIT_MESSAGE, guard.EMAIL, guard.LABEL)) + assert hashlib.sha256(joined.encode("utf-8")).hexdigest() == SHARED_PATTERN_DIGEST + + +@pytest.mark.parametrize("value", GOLDEN["ref_deny"]) +def test_ref_pattern_denies_golden_vector(guard: _Guard, value: str) -> None: + assert guard.REF_RE.search(value) is not None + + +@pytest.mark.parametrize("value", GOLDEN["ref_allow"]) +def test_ref_pattern_allows_golden_vector(guard: _Guard, value: str) -> None: + assert guard.REF_RE.search(value) is None + + +@pytest.mark.parametrize("value", GOLDEN["msg_deny"]) +def test_message_pattern_denies_golden_vector(guard: _Guard, value: str) -> None: + assert guard.MSG_RE.search(value) is not None + + +@pytest.mark.parametrize("value", GOLDEN["msg_allow"]) +def test_message_pattern_allows_golden_vector(guard: _Guard, value: str) -> None: + assert guard.MSG_RE.search(value) is None + + +@pytest.mark.parametrize("value", GOLDEN["email_deny"]) +def test_email_pattern_denies_golden_vector(guard: _Guard, value: str) -> None: + assert guard.EMAIL_RE.search(value) is not None + + +@pytest.mark.parametrize("value", GOLDEN["email_allow"]) +def test_email_pattern_allows_golden_vector(guard: _Guard, value: str) -> None: + assert guard.EMAIL_RE.search(value) is None + + +@pytest.mark.parametrize("value", LABEL_DENY) +def test_label_pattern_denies_banned_words(guard: _Guard, value: str) -> None: + assert guard.LABEL_RE.search(value) is not None + + +@pytest.mark.parametrize("value", LABEL_ALLOW) +def test_label_pattern_allows_plain_labels(guard: _Guard, value: str) -> None: + assert guard.LABEL_RE.search(value) is None + + +def test_comment_stripping_ignores_git_template_and_verbose_diff(guard: _Guard) -> None: + """Only text git keeps is checked, so verbose diffs of fixtures cannot trip the hook.""" + message = ( + "test: add fixtures\n" + "# Please enter the commit message for your changes.\n" + "# ------------------------ >8 ------------------------\n" + f"+{DENIED_MESSAGE}\n" + ) + assert guard.strip_commit_message_comments(message) == "test: add fixtures\n" + + +def _run_guard( + guard_path: Path, + args: Sequence[str], + *, + cwd: Path, + stdin: str = "", + env: Mapping[str, str] | None = None, +) -> subprocess.CompletedProcess[str]: + environment = {key: value for key, value in os.environ.items() if key != "GITHUB_ACTIONS"} + environment.update(env or {}) + return subprocess.run( + [sys.executable, str(guard_path), *args], + cwd=cwd, + input=stdin, + capture_output=True, + text=True, + env=environment, + check=False, + ) + + +def _git(repo: Path, *args: str, email: str = CLEAN_EMAIL) -> str: + environment = { + **os.environ, + "GIT_AUTHOR_NAME": "Dev", + "GIT_AUTHOR_EMAIL": email, + "GIT_COMMITTER_NAME": "Dev", + "GIT_COMMITTER_EMAIL": email, + "GIT_CONFIG_NOSYSTEM": "1", + "HOME": str(repo), + } + completed = subprocess.run( + ["git", *args], cwd=repo, capture_output=True, text=True, env=environment, check=True + ) + return completed.stdout.strip() + + +def _commit(repo: Path, message: str, *, email: str = CLEAN_EMAIL) -> str: + _git(repo, "commit", "--allow-empty", "--no-verify", "-q", "-m", message, email=email) + return _git(repo, "rev-parse", "HEAD") + + +@pytest.fixture +def git_repo(tmp_path: Path) -> Path: + """Creates a work repository with a bare `origin` holding one clean commit.""" + origin = tmp_path / "origin.git" + repo = tmp_path / "work" + subprocess.run(["git", "init", "-q", "--bare", str(origin)], check=True) + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _git(repo, "remote", "add", "origin", str(origin)) + _commit(repo, "chore: initial commit") + _git(repo, "push", "-q", "--no-verify", "origin", "main") + return repo + + +def test_commit_msg_mode_passes_subject_mentions(guard_path: Path, tmp_path: Path) -> None: + message_file = tmp_path / "COMMIT_EDITMSG" + message_file.write_text(GOLDEN["msg_allow"][1] + "\n", encoding="utf-8") + + completed = _run_guard(guard_path, ["commit-msg", str(message_file)], cwd=tmp_path) + + assert completed.returncode == 0, completed.stderr + + +def test_commit_msg_mode_rejects_attribution(guard_path: Path, tmp_path: Path) -> None: + message_file = tmp_path / "COMMIT_EDITMSG" + message_file.write_text(DENIED_MESSAGE, encoding="utf-8") + + completed = _run_guard(guard_path, ["commit-msg", str(message_file)], cwd=tmp_path) + + assert completed.returncode == 1 + assert "commit message: matched" in completed.stderr + + +def test_pre_push_stdin_rejects_tool_namespaced_remote_ref( + guard_path: Path, git_repo: Path +) -> None: + head = _commit(git_repo, "feat: clean change") + line = f"refs/heads/main {head} {DENIED_REF} {'0' * 40}\n" + + completed = _run_guard(guard_path, ["pre-push", "origin", "--stdin"], cwd=git_repo, stdin=line) + + assert completed.returncode == 1 + assert f"pushed ref {DENIED_REF!r}" in completed.stderr + + +def test_pre_push_stdin_rejects_introduced_commit_metadata( + guard_path: Path, git_repo: Path +) -> None: + base = _git(git_repo, "rev-parse", "HEAD") + _commit(git_repo, DENIED_MESSAGE) + head = _commit(git_repo, "fix: clean follow-up", email=GOLDEN["email_deny"][0]) + line = f"refs/heads/main {head} refs/heads/main {base}\n" + + completed = _run_guard(guard_path, ["pre-push", "origin", "--stdin"], cwd=git_repo, stdin=line) + + assert completed.returncode == 1 + assert "message: matched" in completed.stderr + assert "author email: matched" in completed.stderr + assert "committer email: matched" in completed.stderr + + +def test_pre_push_stdin_checks_only_commits_new_to_the_remote( + guard_path: Path, git_repo: Path +) -> None: + """A new branch must not re-audit history the remote already has.""" + _commit(git_repo, DENIED_MESSAGE) + _git(git_repo, "push", "-q", "--no-verify", "origin", "main") + head = _commit(git_repo, "feat: clean change") + lines = ( + f"refs/heads/main {head} refs/heads/feat/clean {'0' * 40}\n" + f"(delete) {'0' * 40} {DENIED_REF} {'1' * 40}\n" + ) + + completed = _run_guard(guard_path, ["pre-push", "origin", "--stdin"], cwd=git_repo, stdin=lines) + + assert completed.returncode == 0, completed.stderr + + +def test_pre_push_reads_pre_commit_environment(guard_path: Path, git_repo: Path) -> None: + base = _git(git_repo, "rev-parse", "HEAD") + head = _commit(git_repo, DENIED_MESSAGE) + env = { + "PRE_COMMIT_FROM_REF": base, + "PRE_COMMIT_TO_REF": head, + "PRE_COMMIT_REMOTE_BRANCH": "refs/heads/main", + "PRE_COMMIT_REMOTE_NAME": "origin", + } + + completed = _run_guard(guard_path, ["pre-push"], cwd=git_repo, env=env) + + assert completed.returncode == 1 + assert "message: matched" in completed.stderr + + +def test_pre_push_fallback_checks_current_branch_and_unpushed_commits( + guard_path: Path, git_repo: Path +) -> None: + clean = _run_guard(guard_path, ["pre-push"], cwd=git_repo) + _git(git_repo, "checkout", "-q", "-b", GOLDEN["ref_deny"][0]) + + flagged = _run_guard(guard_path, ["pre-push"], cwd=git_repo) + + assert clean.returncode == 0, clean.stderr + assert flagged.returncode == 1 + assert "current branch" in flagged.stderr + + +def test_push_mode_audits_only_the_pushed_range(guard_path: Path, git_repo: Path) -> None: + """Commits already on the branch before the push are not re-judged.""" + _commit(git_repo, GOLDEN["msg_deny"][7]) + before = _commit(git_repo, "chore: clean base") + clean_after = _commit(git_repo, GOLDEN["msg_allow"][7]) + clean = _run_guard( + guard_path, ["push", "--before", before, "--after", clean_after], cwd=git_repo + ) + dirty_after = _commit(git_repo, DENIED_MESSAGE) + + dirty = _run_guard( + guard_path, ["push", "--before", clean_after, "--after", dirty_after], cwd=git_repo + ) + + assert clean.returncode == 0, clean.stderr + assert dirty.returncode == 1 + assert f"commit {dirty_after[:12]} message" in dirty.stderr + + +type _Routes = dict[str, object] + + +@pytest.fixture +def api_server() -> Iterator[Callable[[_Routes], str]]: + """Serves canned GitHub API JSON keyed by request path plus query.""" + servers: list[ThreadingHTTPServer] = [] + + def _start(routes: _Routes) -> str: + class _Handler(BaseHTTPRequestHandler): + def do_GET(self) -> None: + parts = urlsplit(self.path) + key = f"{parts.path}?{parts.query}" if parts.query else parts.path + if key not in routes: + self.send_error(404) + return + payload = json.dumps(routes[key]).encode("utf-8") + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(payload))) + self.end_headers() + self.wfile.write(payload) + + def log_message(self, format: str, *args: object) -> None: + return + + server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler) + servers.append(server) + threading.Thread(target=server.serve_forever, daemon=True).start() + return f"http://127.0.0.1:{server.server_address[1]}" + + yield _start + for server in servers: + server.shutdown() + server.server_close() + + +def _api_commit(index: int, message: str = "fix: clean", email: str = CLEAN_EMAIL) -> object: + return { + "sha": f"{index:040x}", + "commit": { + "message": message, + "author": {"email": email}, + "committer": {"email": CLEAN_EMAIL}, + }, + } + + +def _pull_routes( + *, + title: str = "ci: add guard", + body: str | None = "Plain description.", + head_ref: str = "ci/guard", + labels: Sequence[str] = ("dependencies",), + commits: Sequence[object] = (), + reported_commits: int | None = None, +) -> _Routes: + base = "/repos/acme/widgets/pulls/7" + pages = [list(commits[start : start + 100]) for start in range(0, len(commits), 100)] or [[]] + routes: _Routes = { + base: { + "title": title, + "body": body, + "head": {"ref": head_ref}, + "labels": [{"name": label} for label in labels], + "commits": len(commits) if reported_commits is None else reported_commits, + } + } + for page_number, page in enumerate(pages, start=1): + routes[f"{base}/commits?per_page=100&page={page_number}"] = page + if len(pages[-1]) == 100: + routes[f"{base}/commits?per_page=100&page={len(pages) + 1}"] = [] + return routes + + +def _run_pull_request( + guard_path: Path, api_url: str, cwd: Path +) -> subprocess.CompletedProcess[str]: + return _run_guard( + guard_path, + ["pull-request", "--repo", "acme/widgets", "--number", "7"], + cwd=cwd, + env={"GITHUB_API_URL": api_url, "GITHUB_TOKEN": "test-token"}, + ) + + +def test_pull_request_mode_paginates_and_passes_clean_metadata( + guard_path: Path, tmp_path: Path, api_server: Callable[[_Routes], str] +) -> None: + commits = [_api_commit(index) for index in range(150)] + api_url = api_server(_pull_routes(body=None, commits=commits)) + + completed = _run_pull_request(guard_path, api_url, tmp_path) + + assert completed.returncode == 0, completed.stderr + assert "(150 commits): clean" in completed.stdout + + +def test_pull_request_mode_reports_every_offending_field( + guard_path: Path, tmp_path: Path, api_server: Callable[[_Routes], str] +) -> None: + routes = _pull_routes( + title=GOLDEN["msg_deny"][4], + body=GOLDEN["msg_deny"][5], + head_ref=GOLDEN["ref_deny"][0], + labels=("dependencies", LABEL_DENY[0]), + commits=[_api_commit(1, message=DENIED_MESSAGE, email=GOLDEN["email_deny"][0])], + ) + + completed = _run_pull_request(guard_path, api_server(routes), tmp_path) + + assert completed.returncode == 1 + for field in ( + "pull request title", + "pull request body", + "head ref", + f"label {LABEL_DENY[0]!r}", + "message: matched", + "author email: matched", + ): + assert field in completed.stderr + + +def test_pull_request_mode_fails_closed_on_incomplete_commit_listing( + guard_path: Path, tmp_path: Path, api_server: Callable[[_Routes], str] +) -> None: + routes = _pull_routes(commits=[_api_commit(1)], reported_commits=300) + + completed = _run_pull_request(guard_path, api_server(routes), tmp_path) + + assert completed.returncode == 2 + assert "Fetched 1 of 300" in completed.stderr + + +def test_hook_installer_feeds_pushed_refs_to_the_guard(repo_root: Path) -> None: + installer = (repo_root / "scripts" / "install_git_hooks.sh").read_text(encoding="utf-8") + config = (repo_root / ".pre-commit-config.yaml").read_text(encoding="utf-8") + + assert 'attribution_guard.py pre-push --stdin "$@"' in installer + assert "pre-commit install --hook-type commit-msg" in installer + assert "default_install_hook_types: [commit-msg]" in config + assert "entry: python scripts/attribution_guard.py commit-msg" in config + assert "entry: python scripts/attribution_guard.py pre-push" in config