From cdfd82b6f1fa2858cdcdbd14fd75007745bb5827 Mon Sep 17 00:00:00 2001 From: Juan Sugg Date: Tue, 10 Nov 2026 02:52:58 -0300 Subject: [PATCH] ci: add attribution guard Adds a required "Attribution Guard" check that refetches pull request metadata (title, body, head ref, labels, every commit message and author/committer email) on every PR event, including edits and label changes, and audits each push to main. The helper runs from the base commit, falling back to the PR head only while bootstrapping. Local layer: a pre-commit commit-msg hook and a pre-push check of the pushed refs and introduced commits. The pattern block is vendored byte-for-byte from the shared source and pinned by a digest test, and every golden vector is asserted. --- .github/workflows/attribution-guard.yml | 77 +++ .pre-commit-config.yaml | 14 + CONTRIBUTING.md | 19 +- scripts/attribution_guard.py | 439 ++++++++++++++++ scripts/install_git_hooks.sh | 7 +- .../test_ci_workflow_contracts.py | 46 ++ .../unit/scripts/test_attribution_guard.py | 482 ++++++++++++++++++ 7 files changed, 1082 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/attribution-guard.yml create mode 100755 scripts/attribution_guard.py create mode 100644 tests/suites/unit/scripts/test_attribution_guard.py diff --git a/.github/workflows/attribution-guard.yml b/.github/workflows/attribution-guard.yml new file mode 100644 index 00000000..a03bdbe9 --- /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 bbf59c07..5938f361 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 89d6bc99..03255b55 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 00000000..06de3fc1 --- /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 90cb945e..b94a7c3a 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 65129e70..bab64b25 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 00000000..9a06a86e --- /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