bin/check-trailers.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1#!/usr/bin/env node
2// REFUSES A COMMIT WHOSE MESSAGE CARRIES AN AI ATTRIBUTION TRAILER, AND, ON A PULL REQUEST, A COMMIT AUTHORED OR COMMITTED
3// AS CLAUDE.
4//
5// The no AI trailer rule. The global attribution setting covers two of the three forms, so the repositories check it
6// themselves.
7//
8// The second check exists because a squash merge builds its message from the branch commits' AUTHORS: a clean message
9// authored as `Claude <noreply@anthropic.com>` comes out of the squash with `Co-authored-by: Claude <noreply@anthropic.com>`,
10// and the push run on the default branch then fails after the merge (capsid, 2026-10-04, PRs 233 to 236; deploy skipped for
11// about ten hours). Catching the author on the pull request catches it before the merge. A push is checked on messages alone.
12//
13// Only the commits a push or pull request adds are checked; history is not rewritten.
14//
15// Usage:
16//   npx devkit-check-trailers <base> <head>             checks base..head (messages)
17//   npx devkit-check-trailers <base> <head> --authors   also author/committer
18//   npx devkit-check-trailers                           reads the range from the GitHub event: EVENT, PR_BASE, PR_HEAD,
19//     PUSH_BEFORE, PUSH_AFTER (set by .github/workflows/ai-author.yml)
20//
21// Exit 0: no commit in the range carries a trailer, or the event adds no commits.
22// Exit 1: at least one does; each is printed. Exit 2: the check could not run, which is a failure, not a pass.
23
24import { execFileSync } from "node:child_process";
25import { realpathSync } from "node:fs";
26import { pathToFileURL } from "node:url";
27
28// The three named forms, matched at the start of any line of the message.
29const NAMED = [
30  { re: /^\s*co-authored-by:.*\b(claude|anthropic)\b/i, what: "Co-Authored-By naming Claude" },
31  { re: /^\W*generated with \[?claude\b/i, what: "Generated with Claude Code" },
32  { re: /^\s*claude-session:/i, what: "Claude-Session link" },
33];
34
35// Any other trailer naming Claude: a line in the message's final paragraph, when every line of that paragraph is
36// trailer-shaped (git's own trailer block), whose key or value names Claude or Anthropic. "CLAUDE.md" is a file in these
37// repositories and does not count.
38const TRAILER_LINE = /^[A-Za-z][A-Za-z0-9-]*:\s/;
39const NAMES_AGENT = /\b(claude(?!\.md)|anthropic)\b/i;
40
41/**
42 * @param {string} message a full commit message
43 * @returns {string[]} one entry per trailer found; empty when the message is clean
44 */
45export function trailerViolations(message) {
46  const text = String(message ?? "").replace(/\r\n/g, "\n").trim();
47  /** @type {string[]} */
48  const found = [];
49  /** @type {Set<string>} */
50  const seen = new Set();
51  for (const line of text.split("\n")) {
52    const named = NAMED.find(({ re }) => re.test(line));
53    if (named) {
54      found.push(`${named.what}: ${line.trim()}`);
55      seen.add(line);
56    }
57  }
58  const paragraphs = text.split(/\n\s*\n/);
59  const last = paragraphs.length > 1 ? paragraphs[paragraphs.length - 1].split("\n") : [];
60  if (last.length > 0 && last.every((line) => TRAILER_LINE.test(line))) {
61    for (const line of last) {
62      if (NAMES_AGENT.test(line) && !seen.has(line)) found.push(`trailer naming Claude: ${line.trim()}`);
63    }
64  }
65  return found;
66}
67
68// An identity that is an AI agent rather than a person: Anthropic's address or domain, the `claude[bot]` GitHub app, or a
69// name that is Claude or Claude plus a product or model word ("Claude", "Claude Code", "Claude Opus 4"). A person whose name
70// merely begins with Claude ("Claude Dupont") or whose address contains it is not flagged; a person named exactly "Claude"
71// is, and can re-author.
72const AGENT_NAME = /^claude(?:\[bot\]|\s+(?:code|opus|sonnet|haiku|fable)\b.*)?$/i;
73const AGENT_EMAIL = /(?:@(?:[\w-]+\.)*anthropic\.com|\+claude\[bot\]@users\.noreply\.github\.com)$/i;
74
75/**
76 * @param {string} name
77 * @param {string} email
78 * @returns {boolean}
79 */
80export function isAgentIdentity(name, email) {
81  const n = String(name ?? "").trim();
82  const e = String(email ?? "").trim();
83  return AGENT_NAME.test(n) || /\banthropic\b/i.test(n) || AGENT_EMAIL.test(e);
84}
85
86const ZERO = /^0+$/;
87
88/**
89 * Which commits to check for a GitHub event. `null` means the event adds no commits.
90 * @param {Record<string, string | undefined>} env
91 * @returns {{ base: string | null, head: string, authors: boolean } | null}
92 */
93export function rangeFromEvent(env) {
94  const event = env.EVENT ?? "";
95  if (event === "pull_request" || event === "pull_request_target") {
96    if (!env.PR_BASE || !env.PR_HEAD) throw new Error(`${event} event without PR_BASE and PR_HEAD`);
97    return { base: env.PR_BASE, head: env.PR_HEAD, authors: true };
98  }
99  if (event === "push") {
100    if (!env.PUSH_AFTER) throw new Error("push event without PUSH_AFTER");
101    // A new branch has no before sha: check the head commit alone.
102    const before = env.PUSH_BEFORE && !ZERO.test(env.PUSH_BEFORE) ? env.PUSH_BEFORE : null;
103    return { base: before, head: env.PUSH_AFTER, authors: false };
104  }
105  return null;
106}
107
108/**
109 * @param {string | null} base
110 * @param {string} head
111 * @param {string} [cwd]
112 * @param {boolean} [authors] also refuse a commit authored or committed as Claude
113 * @returns {Array<{ sha: string, found: string[], identities: string[] }>}
114 */
115export function checkRange(base, head, cwd, authors = false) {
116  const git = (/** @type {string[]} */ args) => execFileSync("git", args, { cwd, encoding: "utf8" });
117  // Fails closed: an unknown sha (a shallow clone, a force-pushed-over base) throws.
118  for (const sha of base ? [base, head] : [head]) git(["cat-file", "-e", `${sha}^{commit}`]);
119  const range = base ? [`${base}..${head}`] : ["-1", head];
120  const out = git(["log", "--format=%H%x00%an%x00%ae%x00%cn%x00%ce%x00%B%x1e", ...range]);
121  /** @type {Array<{ sha: string, found: string[], identities: string[] }>} */
122  const bad = [];
123  for (const record of out.split("\x1e")) {
124    const [sha, an, ae, cn, ce, ...rest] = record.split("\x00");
125    if (rest.length === 0) continue;
126    const found = trailerViolations(rest.join("\x00"));
127    /** @type {string[]} */
128    const identities = [];
129    if (authors) {
130      if (isAgentIdentity(an, ae)) identities.push(`author ${an} <${ae}>`);
131      if (isAgentIdentity(cn, ce)) identities.push(`committer ${cn} <${ce}>`);
132    }
133    if (found.length || identities.length) bad.push({ sha: sha.trim(), found, identities });
134  }
135  return bad;
136}
137
138function main() {
139  let range;
140  try {
141    const args = process.argv.slice(2);
142    const authors = args.includes("--authors");
143    const [base, head] = args.filter((a) => a !== "--authors");
144    range = head ? { base, head, authors } : rangeFromEvent(process.env);
145  } catch (err) {
146    console.error(`check-trailers: could not work out the range: ${/** @type {Error} */ (err).message}`);
147    process.exit(2);
148  }
149  if (!range) {
150    console.log(`check-trailers: event '${process.env.EVENT ?? ""}' adds no commits; nothing to check`);
151    return;
152  }
153  let bad;
154  try {
155    bad = checkRange(range.base, range.head, undefined, range.authors);
156  } catch (err) {
157    console.error(`check-trailers: could not read commits ${range.base ?? "(none)"}..${range.head}: ${/** @type {Error} */ (err).message}`);
158    process.exit(2);
159  }
160  if (bad.length === 0) {
161    console.log(`check-trailers: no AI trailer${range.authors ? " and no AI author" : ""} in ${range.base ? `${range.base}..${range.head}` : range.head}`);
162    return;
163  }
164  for (const { sha, found, identities } of bad) {
165    for (const f of found) console.error(`::error::commit ${sha} carries an AI trailer (${f})`);
166    for (const id of identities) {
167      console.error(
168        `::error::commit ${sha} has an AI identity (${id}). A squash merge turns a Claude author into "Co-authored-by: Claude", which the push check then refuses after the merge.`,
169      );
170    }
171  }
172  if (bad.some((b) => b.found.length)) console.error("Rewrite those commit messages without the trailer (the no AI trailer rule).");
173  if (bad.some((b) => b.identities.length)) {
174    console.error(
175      "Re-author those commits as yourself: `git config user.name` and `user.email`, then `git rebase -r <base> --exec 'git commit --amend --no-edit --reset-author'`, or `git commit --amend --reset-author` for the last one, and force-push the branch.",
176    );
177  }
178  process.exit(1);
179}
180
181// Run through node_modules/.bin, argv[1] is the link and import.meta.url the file it points to.
182if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) main();