@avi2dg/checks 0.1.0

package/scripts/backtest.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+import { comments, refused, SYNTAXES } from "./comments.ts";
+
+type Landed = {
+  readonly sha: string;
+  readonly subject: string;
+  readonly added: number;
+  readonly comments: number;
+  readonly refusals: readonly string[];
+};
+
+const USAGE = "usage: backtest.ts [commit-count]";
+
+const EXCLUDED = ["generated/", "vendor/", "repos/", "node_modules/", "dist/"];
+
+function die(message: string): never {
+  console.error(message);
+  process.exit(2);
+}
+
+function git(...args: readonly string[]): string {
+  const result = Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "pipe" });
+  if (!result.success) {
+    die(`backtest: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
+  }
+  return result.stdout.toString();
+}
+
+function readable(path: string): boolean {
+  if (EXCLUDED.some((prefix) => path.startsWith(prefix))) return false;
+  const extension = path.slice(path.lastIndexOf(".") + 1);
+  return extension in SYNTAXES;
+}
+
+async function at(sha: string, path: string): Promise<string | undefined> {
+  const result = Bun.spawnSync(["git", "show", `${sha}:${path}`], { stdout: "pipe", stderr: "pipe" });
+  return result.success ? result.stdout.toString() : undefined;
+}
+
+function withoutLine(refusal: string): string {
+  return refusal.replace(/^(\S+?):\d+ /, "$1 ");
+}
+
+export async function backtest(count: string): Promise<string> {
+  const lines: string[] = [];
+  const commits = git("log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count)
+    .trim()
+    .split("\n")
+    .map((row) => {
+      const [sha = "", parents = "", subject = ""] = row.split("\t");
+      return { sha, parent: parents.split(" ")[0] ?? "", subject };
+    })
+    .filter((commit) => commit.sha !== "" && commit.parent !== "");
+
+  const landed: Landed[] = [];
+
+  for (const { sha, parent, subject } of commits) {
+    const changed = git("diff", "--name-only", "--diff-filter=d", parent, sha)
+      .trim()
+      .split("\n")
+      .filter((path) => path !== "" && readable(path));
+    if (changed.length === 0) continue;
+
+    const numstat = git("diff", "--numstat", parent, sha, "--", ...changed).trim();
+    const added =
+      numstat === ""
+        ? 0
+        : numstat.split("\n").reduce((sum, row) => sum + Number(row.split("\t")[0] ?? 0), 0);
+
+    let commentLines = 0;
+    const refusals: string[] = [];
+
+    for (const path of changed) {
+      const after = await at(sha, path);
+      if (after === undefined) continue;
+      const before = (await at(parent, path)) ?? "";
+
+      const wasRefused = new Set(refused(path, before).map(withoutLine));
+      for (const refusal of refused(path, after)) {
+        if (!wasRefused.has(withoutLine(refusal))) refusals.push(refusal);
+      }
+
+      const wasComment = new Set(comments(path, before).map((one) => one.text));
+      for (const one of comments(path, after)) {
+        if (!wasComment.has(one.text)) commentLines += one.text.split("\n").length;
+      }
+    }
+
+    landed.push({ sha: sha.slice(0, 7), subject, added, comments: commentLines, refusals });
+  }
+
+  const total = (pick: (one: Landed) => number): number => landed.reduce((sum, one) => sum + pick(one), 0);
+  const addedLines = total((one) => one.added);
+  const commentLines = total((one) => one.comments);
+  const refusalCount = total((one) => one.refusals.length);
+
+  for (const one of landed) {
+    lines.push(`${one.sha}\t${one.added}\t${one.comments}\t${one.refusals.length}\t${one.subject.slice(0, 58)}`);
+  }
+  lines.push(`${landed.length} commits touching code, ${addedLines} added lines`);
+  lines.push(
+    `comment lines added: ${commentLines} (${((commentLines / Math.max(addedLines, 1)) * 100).toFixed(1)}% of added lines)`,
+  );
+  lines.push(`refusals introduced: ${refusalCount}`);
+  for (const one of landed) {
+    if (one.refusals.length === 0) continue;
+    lines.push(`\n  ${one.sha} ${one.subject}`);
+    for (const refusal of one.refusals) lines.push(`    ${refusal}`);
+  }
+  return lines.join("\n");
+}
+
+if (import.meta.main) {
+  const [count = "60", ...extra] = process.argv.slice(2);
+  if (extra.length > 0) die(USAGE);
+  console.log(await backtest(count));
+}

package/scripts/comment-gate.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+import { refused, SYNTAXES } from "./comments.ts";
+
+export type GateResult = {
+  readonly files: number;
+  readonly addedLines: number;
+  readonly violations: readonly string[];
+};
+
+const USAGE = "usage: comment-gate.ts <ref> | <base-ref> <head-ref>";
+
+function die(message: string): never {
+  console.error(message);
+  process.exit(2);
+}
+
+function git(root: string, ...args: readonly string[]): string {
+  const result = Bun.spawnSync(["git", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+  if (!result.success) {
+    die(`comment-gate: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
+  }
+  return result.stdout.toString();
+}
+
+function readable(path: string): boolean {
+  return path.slice(path.lastIndexOf(".") + 1) in SYNTAXES;
+}
+
+function newPathOf(line: string): string | undefined {
+  const path = line.startsWith("+++ b/") ? line.slice("+++ b/".length) : line.slice("+++ ".length);
+  return path === "/dev/null" ? undefined : path;
+}
+
+const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+
+export function parseAddedLines(diff: string): Map<string, Set<number>> {
+  const added = new Map<string, Set<number>>();
+  let path: string | undefined;
+  let line = 0;
+  let inHunk = false;
+  for (const row of diff.split("\n")) {
+    if (row.startsWith("+++ ")) {
+      path = newPathOf(row);
+      inHunk = false;
+      continue;
+    }
+    const hunk = HUNK.exec(row);
+    if (hunk !== null) {
+      line = Number(hunk[1]);
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk || path === undefined) continue;
+    if (row.startsWith("+")) {
+      let lines = added.get(path);
+      if (lines === undefined) {
+        lines = new Set<number>();
+        added.set(path, lines);
+      }
+      lines.add(line);
+      line += 1;
+    } else if (row.startsWith("-")) {
+      continue;
+    } else {
+      line += 1;
+    }
+  }
+  return added;
+}
+
+function show(rev: string, path: string, root: string): string | undefined {
+  const result = Bun.spawnSync(["git", "show", `${rev}:${path}`], {
+    cwd: root,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return result.success ? result.stdout.toString() : undefined;
+}
+
+export function runRange(root: string, base: string, head: string): GateResult {
+  const diff = git(root, "-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--no-prefix", base, head);
+  const added = parseAddedLines(diff);
+  const violations: string[] = [];
+  let addedLines = 0;
+  for (const [path, lines] of added) {
+    addedLines += lines.size;
+    if (!readable(path)) continue;
+    const source = show(head, path, root);
+    if (source === undefined) continue;
+    violations.push(...refused(path, source, lines));
+  }
+  return { files: added.size, addedLines, violations };
+}
+
+export function report({ files, addedLines, violations }: GateResult): string {
+  if (violations.length === 0) {
+    return `comment-gate: ${addedLines} added line(s) across ${files} file(s) carry no refused comment`;
+  }
+  return [`comment-gate: ${violations.length} violation(s):`, ...violations.map((one) => `  ${one}`)].join("\n");
+}
+
+function parentOf(root: string, rev: string): string {
+  return git(root, "rev-parse", "--verify", `${rev}^`).trim();
+}
+
+if (import.meta.main) {
+  const [first, second, ...extra] = process.argv.slice(2);
+  if (first === undefined || extra.length > 0) die(USAGE);
+
+  const root = git(process.cwd(), "rev-parse", "--show-toplevel").trim();
+  const result =
+    second !== undefined ? runRange(root, first, second) : runRange(root, parentOf(root, first), first);
+
+  console.log(report(result));
+  process.exit(result.violations.length === 0 ? 0 : 1);
+}

package/scripts/comments.ts

@@ -0,0 +1,298 @@
+export type Comment = { line: number; text: string };
+
+type Marker = { readonly token: string; readonly afterAWordBreak: boolean };
+type Quote = { readonly token: string; readonly backslashEscapes: boolean; readonly opensMidWord: boolean };
+
+type Syntax = {
+  readonly line: readonly Marker[];
+  readonly block: readonly (readonly [open: string, close: string])[];
+  readonly quotes: readonly Quote[];
+  readonly regexLiterals: boolean;
+};
+
+const anywhere = (token: string): Marker => ({ token, afterAWordBreak: false });
+const startingAWord = (token: string): Marker => ({ token, afterAWordBreak: true });
+const escaping = (token: string): Quote => ({ token, backslashEscapes: true, opensMidWord: true });
+const literal = (token: string): Quote => ({ token, backslashEscapes: false, opensMidWord: true });
+const outsideAWord = (quote: Quote): Quote => ({ ...quote, opensMidWord: false });
+
+const SLASHES: readonly (readonly [string, string])[] = [["/*", "*/"]];
+const SLASH_SLASH = [startingAWord("//")];
+const DASHES = [anywhere("--")];
+const STRINGS = [escaping('"'), escaping("'")];
+
+const JS: Syntax = {
+  line: SLASH_SLASH,
+  block: SLASHES,
+  quotes: [escaping('"'), outsideAWord(escaping("'")), escaping("`")],
+  regexLiterals: true,
+};
+const CURLY: Syntax = { ...JS, quotes: [...STRINGS, escaping("`")], regexLiterals: false };
+const PHP: Syntax = { line: [...SLASH_SLASH, anywhere("#")], block: SLASHES, quotes: STRINGS, regexLiterals: false };
+const HASH: Syntax = {
+  line: [startingAWord("#")],
+  block: [],
+  quotes: [escaping('"'), literal("'")],
+  regexLiterals: false,
+};
+const YAML: Syntax = { ...HASH, quotes: [escaping('"'), outsideAWord(literal("'"))] };
+const SQL: Syntax = { line: DASHES, block: SLASHES, quotes: STRINGS, regexLiterals: false };
+const LUA: Syntax = { line: DASHES, block: [["--[[", "]]"]], quotes: STRINGS, regexLiterals: false };
+const HASKELL: Syntax = { line: DASHES, block: [["{-", "-}"]], quotes: [escaping('"')], regexLiterals: false };
+const ML: Syntax = { line: [], block: [["(*", "*)"]], quotes: [escaping('"')], regexLiterals: false };
+
+export const SYNTAXES: Readonly<Record<string, Syntax>> = {
+  ts: JS,
+  tsx: JS,
+  mts: JS,
+  cts: JS,
+  js: JS,
+  jsx: JS,
+  mjs: JS,
+  cjs: JS,
+  go: CURLY,
+  rs: CURLY,
+  java: CURLY,
+  kt: CURLY,
+  swift: CURLY,
+  scala: CURLY,
+  c: CURLY,
+  h: CURLY,
+  cc: CURLY,
+  cpp: CURLY,
+  hpp: CURLY,
+  cs: CURLY,
+  php: PHP,
+  py: HASH,
+  rb: HASH,
+  ex: HASH,
+  exs: HASH,
+  sh: HASH,
+  bash: HASH,
+  zsh: HASH,
+  nix: HASH,
+  sql: SQL,
+  lua: LUA,
+  hs: HASKELL,
+  yaml: YAML,
+  yml: YAML,
+  toml: HASH,
+  ml: ML,
+};
+
+export function syntaxFor(path: string): Syntax {
+  const extension = path.slice(path.lastIndexOf(".") + 1);
+  const syntax = SYNTAXES[extension];
+  if (!syntax) {
+    throw new Error(
+      `${path} is code the comment checks cannot read: add a comment syntax for .${extension} to scripts/comments.ts`,
+    );
+  }
+  return syntax;
+}
+
+const WORD = /[\w$]/;
+
+const KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "case",
+  "do",
+  "else",
+  "yield",
+  "await",
+]);
+
+const AFTER_A_VALUE = /[)\]}"'`]/;
+
+function opensRegex(previous: string): boolean {
+  if (previous === "") return true;
+  if (WORD.test(previous[0]!)) return KEYWORDS.has(previous);
+  return !AFTER_A_VALUE.test(previous);
+}
+
+const WORD_BREAK = /[\s;|&(]/;
+
+function endOfQuoted(source: string, start: number, quote: Quote): number {
+  let i = start + quote.token.length;
+  while (i < source.length) {
+    if (quote.backslashEscapes && source[i] === "\\") i += 2;
+    else if (source.startsWith(quote.token, i)) return i + quote.token.length;
+    else i += 1;
+  }
+  return start + quote.token.length;
+}
+
+function endOfRegex(source: string, start: number): number {
+  let i = start + 1;
+  let inClass = false;
+  while (i < source.length) {
+    const char = source[i]!;
+    if (char === "\\") i += 2;
+    else if (char === "\n") return i;
+    else {
+      if (char === "[") inClass = true;
+      else if (char === "]") inClass = false;
+      else if (char === "/" && !inClass) return i + 1;
+      i += 1;
+    }
+  }
+  return source.length;
+}
+
+export function comments(path: string, source: string): Comment[] {
+  const syntax = syntaxFor(path);
+  const found: Comment[] = [];
+  let i = 0;
+  let line = 1;
+  let previous = "";
+
+  const advance = (to: number): void => {
+    for (let k = i; k < to; k++) if (source[k] === "\n") line += 1;
+    i = to;
+  };
+
+  while (i < source.length) {
+    const char = source[i]!;
+
+    const block = syntax.block.find(([open]) => source.startsWith(open, i));
+    if (block) {
+      const [open, close] = block;
+      const closed = source.indexOf(close, i + open.length);
+      const stop = closed < 0 ? source.length : closed + close.length;
+      found.push({ line, text: source.slice(i, stop) });
+      advance(stop);
+      previous = "";
+      continue;
+    }
+
+    const marker = syntax.line.find(
+      ({ token, afterAWordBreak }) =>
+        source.startsWith(token, i) && (!afterAWordBreak || i === 0 || WORD_BREAK.test(source[i - 1]!)),
+    );
+    if (marker) {
+      const newline = source.indexOf("\n", i);
+      const stop = newline < 0 ? source.length : newline;
+      found.push({ line, text: source.slice(i, stop) });
+      advance(stop);
+      previous = "";
+      continue;
+    }
+
+    const quote = syntax.quotes.find(
+      ({ token, opensMidWord }) =>
+        source.startsWith(token, i) && (opensMidWord || i === 0 || !WORD.test(source[i - 1]!)),
+    );
+    if (quote) {
+      advance(endOfQuoted(source, i, quote));
+      previous = quote.token;
+      continue;
+    }
+
+    if (syntax.regexLiterals && char === "/" && opensRegex(previous)) {
+      advance(endOfRegex(source, i));
+      previous = "/";
+      continue;
+    }
+
+    if (WORD.test(char)) {
+      let end = i;
+      while (end < source.length && WORD.test(source[end]!)) end += 1;
+      previous = source.slice(i, end);
+      advance(end);
+      continue;
+    }
+
+    if (!/\s/.test(char)) previous = char;
+    advance(i + 1);
+  }
+
+  return found;
+}
+
+const LICENCE = /copyright|spdx-license-identifier|all rights reserved|licen[cs]ed under|permission is hereby granted/i;
+
+// A single sentence wraps to at most a few lines at a normal width, so a longer run at the
+// file's own opening is the shape of a paragraph rather than of one fact.
+const A_WRAPPED_SENTENCE_FITS_WITHIN = 3;
+
+function beginsItsLine(comment: Comment, lines: readonly string[]): boolean {
+  return lines[comment.line - 1]!.trimStart().startsWith(comment.text.split("\n")[0]!);
+}
+
+function openingBlock(found: readonly Comment[], source: string): Comment[] {
+  const lines = source.split("\n");
+  if (found.length === 0 || found[0]!.line !== 1 || !beginsItsLine(found[0]!, lines)) return [];
+  const block = [found[0]!];
+  let next = found[0]!.line + found[0]!.text.split("\n").length;
+  for (let i = 1; i < found.length && found[i]!.line === next && beginsItsLine(found[i]!, lines); i++) {
+    block.push(found[i]!);
+    next = found[i]!.line + found[i]!.text.split("\n").length;
+  }
+  return block;
+}
+
+type Check = {
+  readonly find: RegExp;
+  readonly refusal: (match: string) => string;
+};
+
+const CHECKS: readonly Check[] = [
+  {
+    find: /@ts-expect-error|@ts-ignore|\bprettier-ignore\b|\beslint-disable[\w-]*|\bbiome-ignore\b/,
+    refusal: (match) =>
+      `carries the machine-read directive \`${match}\`. Fix what the tool is reporting, or stop running the tool on this file`,
+  },
+  {
+    find: /\bADR[\s-]?\d+|\bdocs\/adr\b|\bRFC[\s-]?\d+|(?:^|[\s(["'`])#\d+\b|[\w.-]+\/[\w.-]+#\d+|\/(?:issues|pull)\/\d+/i,
+    refusal: (match) =>
+      `points at a record or a ticket (${JSON.stringify(match.trim())}). Drop the pointer: a record is reached by searching docs/adr, and the story of the change goes in the commit message`,
+  },
+  {
+    find: /^\/\*\*/,
+    refusal: () =>
+      "opens a doc block. Make the code say it, or put what the types cannot hold on a line comment in the fewest words that carry it",
+  },
+];
+
+function spans(from: number, lineCount: number, within: ReadonlySet<number> | undefined): boolean {
+  if (within === undefined) return true;
+  for (let line = from; line < from + lineCount; line += 1) if (within.has(line)) return true;
+  return false;
+}
+
+export function refused(path: string, source: string, within?: ReadonlySet<number>): string[] {
+  const out: string[] = [];
+  const found = comments(path, source);
+
+  const opening = openingBlock(found, source);
+  const openingText = opening.map((comment) => comment.text).join("\n");
+  const openingLines = opening.reduce((sum, comment) => sum + comment.text.split("\n").length, 0);
+  if (
+    opening.length > 0 &&
+    openingLines > A_WRAPPED_SENTENCE_FITS_WITHIN &&
+    !LICENCE.test(openingText) &&
+    spans(1, openingLines, within)
+  ) {
+    out.push(
+      `${path}:1 opens with a ${openingLines}-line rationale block. A record this long belongs in docs/adr or the repo's decision log, and the code does not point at it`,
+    );
+  }
+
+  for (const comment of found) {
+    if (LICENCE.test(comment.text)) continue;
+    if (!spans(comment.line, comment.text.split("\n").length, within)) continue;
+    for (const check of CHECKS) {
+      const [match] = check.find.exec(comment.text) ?? [];
+      if (match !== undefined) out.push(`${path}:${comment.line} ${check.refusal(match)}`);
+    }
+  }
+  return out;
+}

package/scripts/commit-identity.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync } from "node:fs";
+
+type Identity = { readonly name: string; readonly email: string };
+
+type Commit = {
+  readonly sha: string;
+  readonly subject: string;
+  readonly author: Identity;
+  readonly committer: Identity;
+  readonly coAuthoredBy: readonly string[];
+};
+
+type Offence = { readonly commit: Commit; readonly reasons: readonly string[] };
+
+const DEFAULT_AUTHORS: readonly Identity[] = [{ name: "avi2d", email: "avi2dg@gmail.com" }];
+
+// GitHub writes the squash commit, so it commits what the owner authored and never authors.
+const SQUASH_COMMITTER: Identity = { name: "GitHub", email: "noreply@github.com" };
+
+// git's own trailer parser, so only the trailer block counts and prose never does.
+const CO_AUTHORED_BY_FORMAT = "%(trailers:key=Co-authored-by)";
+
+// argv cannot carry a NUL, so git spells the separators itself.
+const FIELD_FORMAT = "%x00";
+const RECORD_FORMAT = "%x1e";
+const FIELD = "\u0000";
+const RECORD = "\u001e";
+
+const USAGE = "usage: commit-identity.ts <ref> | <base-ref> <head-ref>";
+
+function die(message: string): never {
+  console.error(message);
+  process.exit(2);
+}
+
+function git(...args: readonly string[]): string {
+  const result = Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "pipe" });
+  if (!result.success) {
+    die(`commit-identity: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
+  }
+  return result.stdout.toString();
+}
+
+function render(identity: Identity): string {
+  return `${identity.name} <${identity.email}>`;
+}
+
+function isIdentity(value: unknown): value is Identity {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { name?: unknown; email?: unknown };
+  return typeof candidate.name === "string" && typeof candidate.email === "string";
+}
+
+function allowedAuthors(): readonly Identity[] {
+  const root = git("rev-parse", "--show-toplevel").trim();
+  const manifestPath = `${root}/package.json`;
+  if (!existsSync(manifestPath)) return DEFAULT_AUTHORS;
+
+  const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const configured = (parsed as { commitIdentity?: unknown }).commitIdentity;
+  if (configured === undefined) return DEFAULT_AUTHORS;
+
+  const authors = (configured as { authors?: unknown }).authors;
+  if (!Array.isArray(authors) || authors.length === 0 || !authors.every(isIdentity)) {
+    die(
+      `commit-identity: ${manifestPath} sets commitIdentity without a non-empty authors array of {name, email}`,
+    );
+  }
+  return authors;
+}
+
+function readCommits(revisions: readonly string[]): readonly Commit[] {
+  const format =
+    ["%H", "%an", "%ae", "%cn", "%ce", "%s", CO_AUTHORED_BY_FORMAT].join(FIELD_FORMAT) +
+    RECORD_FORMAT;
+  const log = git("log", `--format=${format}`, ...revisions);
+
+  return log
+    .split(RECORD)
+    .map((record) => record.replace(/^\n/, ""))
+    .filter((record) => record !== "")
+    .map((record) => {
+      const [sha, authorName, authorEmail, committerName, committerEmail, subject, trailers] =
+        record.split(FIELD);
+      if (
+        sha === undefined ||
+        authorName === undefined ||
+        authorEmail === undefined ||
+        committerName === undefined ||
+        committerEmail === undefined ||
+        subject === undefined ||
+        trailers === undefined
+      ) {
+        return die(`commit-identity: cannot parse git log record: ${JSON.stringify(record)}`);
+      }
+      return {
+        sha,
+        subject,
+        author: { name: authorName, email: authorEmail },
+        committer: { name: committerName, email: committerEmail },
+        coAuthoredBy: trailers.split("\n").filter((line) => line !== ""),
+      };
+    });
+}
+
+function allows(allowed: readonly Identity[], identity: Identity): boolean {
+  return allowed.some(
+    (entry) =>
+      entry.name === identity.name &&
+      entry.email.toLowerCase() === identity.email.toLowerCase(),
+  );
+}
+
+function inspect(commit: Commit, allowed: readonly Identity[]): Offence | undefined {
+  const reasons: string[] = [];
+  if (!allows(allowed, commit.author)) {
+    reasons.push(`author ${render(commit.author)}`);
+  }
+  if (!allows([...allowed, SQUASH_COMMITTER], commit.committer)) {
+    reasons.push(`committer ${render(commit.committer)}`);
+  }
+  for (const trailer of commit.coAuthoredBy) {
+    reasons.push(`trailer ${trailer}`);
+  }
+  return reasons.length === 0 ? undefined : { commit, reasons };
+}
+
+const [first, second, ...extra] = process.argv.slice(2);
+if (first === undefined || extra.length > 0) die(USAGE);
+const range = second === undefined ? first : `${first}..${second}`;
+const revisions = second === undefined ? ["-1", range] : [range];
+
+const allowed = allowedAuthors();
+const commits = readCommits(revisions);
+const offences = commits
+  .map((commit) => inspect(commit, allowed))
+  .filter((offence) => offence !== undefined);
+
+if (offences.length > 0) {
+  console.error(
+    `commit-identity: ${offences.length} of ${commits.length} commit(s) in ${range} carry a foreign identity:`,
+  );
+  for (const { commit, reasons } of offences) {
+    console.error(`  ${commit.sha.slice(0, 12)} ${commit.subject}`);
+    for (const reason of reasons) console.error(`    ${reason}`);
+  }
+  console.error(`  allowed: ${allowed.map(render).join(", ")}`);
+  console.error(`  allowed as committer only: ${render(SQUASH_COMMITTER)}`);
+  process.exit(1);
+}
+
+console.log(`commit-identity: ${commits.length} commit(s) in ${range} carry only allowed identities`);