@avi2dg/checks 0.8.0 → 0.10.0

package/scripts/ci-wiring.ts

@@ -2,7 +2,15 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { git } from "./git.ts";
 import { runMain } from "./main.ts";
-import { DEFAULT_BRANCH, ENTRY_POINT, KIT_GATES } from "./gates.ts";
+import {
+  DEFAULT_BRANCH,
+  ENTRY_POINT,
+  EVERY_REPOSITORY,
+  KIT_GATES,
+  LintWiring,
+  selectedGates,
+  type KitGate,
+} from "./gates.ts";
 
 export type Command = readonly string[];
 
@@ -13,7 +21,9 @@ export type Gate = {
 
 export type Declaration = {
   readonly gates: readonly Gate[];
+  readonly scheduled: readonly Gate[];
   readonly defaultBranch: string;
+  readonly lintGates: readonly KitGate[];
 };
 
 export type Workflow = {
@@ -26,6 +36,12 @@ export type BlockedInvocation = {
   readonly blocker: string;
 };
 
+export type Omission = {
+  readonly gate: string;
+  readonly content: string;
+  readonly files: readonly [string, ...string[]];
+};
+
 export type Gap = {
   readonly gate: string;
   readonly entryPoint?: string;
@@ -38,6 +54,8 @@ type RunStep = {
   readonly script: string;
 };
 
+type Trigger = (workflow: Workflow) => string | undefined;
+
 export class WiringError extends Schema.TaggedError<WiringError>()("WiringError", {
   message: Schema.String,
 }) {}
@@ -146,7 +164,7 @@ function selects(patterns: readonly string[], branch: string): boolean {
   return selected;
 }
 
-function triggerBlocker(workflow: Workflow, branch: string): string | undefined {
+const pullRequestTrigger = (branch: string): Trigger => (workflow) => {
   const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
   const events = isRecord(on) ? Object.keys(on) : (names(on) ?? []);
   if (!events.includes("pull_request")) return `${workflow.path} does not trigger on pull_request`;
@@ -168,7 +186,14 @@ function triggerBlocker(workflow: Workflow, branch: string): string | undefined
   const missing = types === undefined ? [] : GATING_TYPES.filter((type) => !types.includes(type));
   if (missing.length > 0) return `${workflow.path} limits pull_request to types without ${missing.join(", ")}`;
   return undefined;
-}
+};
+
+const scheduleTrigger: Trigger = (workflow) => {
+  const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+  const schedule = isRecord(on) ? on["schedule"] : undefined;
+  const crons = Array.isArray(schedule) ? schedule.filter((entry) => isRecord(entry) && typeof entry["cron"] === "string") : [];
+  return crons.length > 0 ? undefined : `${workflow.path} does not trigger on a schedule`;
+};
 
 // GitHub prefixes any other if: with success(), so only a status function overrides a needed job's skip.
 function skippedBy(jobs: Readonly<Record<string, unknown>>, id: string, seen: readonly string[]): string | undefined {
@@ -187,7 +212,7 @@ function localCall(uses: unknown): string | undefined {
   return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
 }
 
-function runSteps(workflows: readonly Workflow[], branch: string): readonly RunStep[] {
+function runSteps(workflows: readonly Workflow[], trigger: Trigger): readonly RunStep[] {
   const documents = new Map(workflows.map((workflow) => [workflow.path, workflow.document]));
   const steps: RunStep[] = [];
 
@@ -225,20 +250,19 @@ function runSteps(workflows: readonly Workflow[], branch: string): readonly RunS
   };
 
   for (const workflow of workflows) {
-    visit(workflow.document, workflow.path, triggerBlocker(workflow, branch), [workflow.path]);
+    visit(workflow.document, workflow.path, trigger(workflow), [workflow.path]);
   }
   return steps;
 }
 
-function entryPointCommand(gate: Command): Command | undefined {
-  const index = gate.findIndex((word) => KIT_GATES.some((kitGate) => kitGate.bin === word));
+function entryPointCommand(gate: Command, lintGates: readonly KitGate[]): Command | undefined {
+  const index = gate.findIndex((word) => lintGates.some((kitGate) => kitGate.bin === word));
   return index === -1 ? undefined : [...gate.slice(0, index), ENTRY_POINT.bin];
 }
 
-export function findGaps(declaration: Declaration, workflows: readonly Workflow[]): readonly Gap[] {
-  const steps = runSteps(workflows, declaration.defaultBranch);
-  return declaration.gates.flatMap((gate) => {
-    const entryPoint = entryPointCommand(gate.words);
+function gapsAmong(gates: readonly Gate[], steps: readonly RunStep[], lintGates: readonly KitGate[]): readonly Gap[] {
+  return gates.flatMap((gate) => {
+    const entryPoint = entryPointCommand(gate.words, lintGates);
     const commands = [
       { command: gate.command, words: gate.words },
       ...(entryPoint === undefined ? [] : [{ command: entryPoint.join(" "), words: entryPoint }]),
@@ -259,10 +283,16 @@ export function findGaps(declaration: Declaration, workflows: readonly Workflow[
   });
 }
 
-export function formatReport(declaration: Declaration, gaps: readonly Gap[]): string {
-  const target = `pull requests to ${declaration.defaultBranch}`;
-  if (gaps.length === 0) return `ci-wiring: ${declaration.gates.length} gate(s) run on ${target}`;
-  const lines = [`ci-wiring: ${gaps.length} of ${declaration.gates.length} gate(s) do not run on ${target}:`];
+export function findGaps(declaration: Declaration, workflows: readonly Workflow[]): readonly Gap[] {
+  return gapsAmong(declaration.gates, runSteps(workflows, pullRequestTrigger(declaration.defaultBranch)), declaration.lintGates);
+}
+
+export function findScheduledGaps(declaration: Declaration, workflows: readonly Workflow[]): readonly Gap[] {
+  return gapsAmong(declaration.scheduled, runSteps(workflows, scheduleTrigger), declaration.lintGates);
+}
+
+function gapLines(gaps: readonly Gap[]): readonly string[] {
+  const lines: string[] = [];
   for (const gap of gaps) {
     lines.push(`  ${gap.gate}`);
     if (gap.blocked.length === 0) {
@@ -270,9 +300,38 @@ export function formatReport(declaration: Declaration, gaps: readonly Gap[]): st
     }
     for (const { location, blocker } of gap.blocked) lines.push(`    ${location}: ${blocker}`);
   }
-  return lines.join("\n");
+  return lines;
+}
+
+const decodeWiring = Schema.decodeUnknownEffect(LintWiring);
+
+export function formatReport(declaration: Declaration, gaps: readonly Gap[]): string {
+  const target = `pull requests to ${declaration.defaultBranch}`;
+  if (gaps.length === 0) return `ci-wiring: ${declaration.gates.length} gate(s) run on ${target}`;
+  return [`ci-wiring: ${gaps.length} of ${declaration.gates.length} gate(s) do not run on ${target}:`, ...gapLines(gaps)].join("\n");
+}
+
+export function formatScheduledReport(declaration: Declaration, gaps: readonly Gap[]): string {
+  const total = declaration.scheduled.length;
+  if (gaps.length === 0) return `ci-wiring: ${total} scheduled command(s) run on a schedule`;
+  return [`ci-wiring: ${gaps.length} of ${total} scheduled command(s) do not run on a schedule:`, ...gapLines(gaps)].join("\n");
 }
 
+const plainCommands = Effect.fnUntraced(function* (
+  listed: readonly unknown[],
+  subject: string,
+): Effect.fn.Return<readonly Gate[], WiringError> {
+  const gates: Gate[] = [];
+  for (const command of listed) {
+    const words = typeof command === "string" ? plainCommand(command) : undefined;
+    if (typeof command !== "string" || words === undefined) {
+      return yield* new WiringError({ message: `${subject} ${JSON.stringify(command)} is not one plain command` });
+    }
+    gates.push({ command, words });
+  }
+  return gates;
+});
+
 export const parseDeclaration = Effect.fnUntraced(function* (
   manifest: unknown,
   source: string,
@@ -282,24 +341,56 @@ export const parseDeclaration = Effect.fnUntraced(function* (
   if (!Array.isArray(listed) || listed.length === 0) {
     return yield* new WiringError({ message: `${source} sets no ciWiring.gates, a non-empty array of commands` });
   }
-  const commands: readonly unknown[] = listed;
-  const gates: Gate[] = [];
-  for (const command of commands) {
-    const words = typeof command === "string" ? plainCommand(command) : undefined;
-    if (typeof command !== "string" || words === undefined) {
-      return yield* new WiringError({
-        message: `${source} ciWiring gate ${JSON.stringify(command)} is not one plain command`,
-      });
-    }
-    gates.push({ command, words });
+  const gates = yield* plainCommands(listed, `${source} ciWiring gate`);
+  const scheduledListed = configured["scheduled"] ?? [];
+  if (!Array.isArray(scheduledListed)) {
+    return yield* new WiringError({ message: `${source} ciWiring.scheduled is not an array of commands` });
   }
-  const defaultBranch = configured["defaultBranch"] ?? DEFAULT_BRANCH;
-  if (typeof defaultBranch !== "string" || defaultBranch === "") {
-    return yield* new WiringError({ message: `${source} ciWiring.defaultBranch is not a branch name` });
+  const scheduled = yield* plainCommands(scheduledListed, `${source} ciWiring scheduled command`);
+  const { ciWiring } = yield* decodeWiring(manifest).pipe(
+    Effect.mapError((cause) => new WiringError({ message: `${source}: ${cause.message}` })),
+  );
+  return {
+    gates,
+    scheduled,
+    defaultBranch: ciWiring?.defaultBranch ?? DEFAULT_BRANCH,
+    lintGates: selectedGates(ciWiring?.lintGates),
+  };
+});
+
+function omittedFrom(lintGates: readonly KitGate[]): readonly KitGate[] {
+  return KIT_GATES.filter((gate) => !lintGates.includes(gate));
+}
+
+export const findOmissions = Effect.fn("findOmissions")(function* (root: string, lintGates: readonly KitGate[]) {
+  const omissions: Omission[] = [];
+  for (const gate of omittedFrom(lintGates)) {
+    // LintGates refuses a selection that leaves out a gate every repository runs.
+    if (gate.appliesTo === EVERY_REPOSITORY) continue;
+    const { pathspecs, content } = gate.appliesTo;
+    const [first, ...rest] = (yield* git(["ls-files", "-z", "--", ...pathspecs], root)).split("\0").filter(Boolean);
+    if (first !== undefined) omissions.push({ gate: gate.bin, content, files: [first, ...rest] });
   }
-  return { gates, defaultBranch };
+  return omissions;
 });
 
+function sample([first, ...rest]: Omission["files"]): string {
+  return rest.length === 0 ? first : `${first} and ${rest.length} more`;
+}
+
+export function formatOmissions(lintGates: readonly KitGate[], omissions: readonly Omission[]): string | undefined {
+  const omitted = omittedFrom(lintGates);
+  if (omitted.length === 0) return undefined;
+  if (omissions.length === 0) {
+    const bins = omitted.map((gate) => gate.bin).join(", ");
+    return `ci-wiring: ciWiring.lintGates leaves out ${bins}, none of which this repository's contents make applicable`;
+  }
+  return [
+    `ci-wiring: ciWiring.lintGates leaves out ${omissions.length} gate(s) this repository's contents make applicable:`,
+    ...omissions.map(({ gate, content, files }) => `  ${gate}: the repository tracks ${content} (${sample(files)})`),
+  ].join("\n");
+}
+
 export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
   Effect.try({
     try: () => ({ path, document: Bun.YAML.parse(text) }),
@@ -336,13 +427,20 @@ export const readWorkflows = Effect.fn("readWorkflows")(function* (root: string)
 const wiring = Effect.gen(function* () {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
   const declaration = yield* readDeclaration(root);
-  const gaps = findGaps(declaration, yield* readWorkflows(root));
-  if (gaps.length > 0) {
-    yield* Console.error(formatReport(declaration, gaps));
-    return false;
+  const workflows = yield* readWorkflows(root);
+  const gaps = findGaps(declaration, workflows);
+  const omissions = yield* findOmissions(root, declaration.lintGates);
+  const gapReport = formatReport(declaration, gaps);
+  yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
+  const omissionReport = formatOmissions(declaration.lintGates, omissions);
+  if (omissionReport !== undefined) {
+    yield* omissions.length > 0 ? Console.error(omissionReport) : Console.log(omissionReport);
   }
-  yield* Console.log(formatReport(declaration, gaps));
-  return true;
+  if (declaration.scheduled.length === 0) return gaps.length === 0 && omissions.length === 0;
+  const scheduledGaps = findScheduledGaps(declaration, workflows);
+  const scheduledReport = formatScheduledReport(declaration, scheduledGaps);
+  yield* scheduledGaps.length > 0 ? Console.error(scheduledReport) : Console.log(scheduledReport);
+  return gaps.length === 0 && omissions.length === 0 && scheduledGaps.length === 0;
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/scripts/comment-gate.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
-import { refused, SYNTAXES } from "./comments.ts";
-import { git } from "./git.ts";
+import { refused, syntaxOf } from "./comments.ts";
+import { git, parentOrEmptyTree } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
 export type GateResult = {
@@ -13,7 +13,7 @@ export type GateResult = {
 const USAGE = "usage: comment-gate.ts <ref> | <base-ref> <head-ref>";
 
 function readable(path: string): boolean {
-  return path.slice(path.lastIndexOf(".") + 1) in SYNTAXES;
+  return syntaxOf(path) !== undefined;
 }
 
 function newPathOf(line: string): string | undefined {
@@ -83,15 +83,12 @@ export function report({ files, addedLines, violations }: GateResult): string {
   return [`comment-gate: ${violations.length} violation(s):`, ...violations.map((one) => `  ${one}`)].join("\n");
 }
 
-const parentOf = (root: string, rev: string) =>
-  git(["rev-parse", "--verify", `${rev}^`], root).pipe(Effect.map((parent) => parent.trim()));
-
 const gate = Effect.gen(function* () {
   const [first, second, ...extra] = process.argv.slice(2);
   if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
 
   const root = (yield* git(["rev-parse", "--show-toplevel"], process.cwd())).trim();
-  const base = second === undefined ? yield* parentOf(root, first) : first;
+  const base = second === undefined ? yield* parentOrEmptyTree(first, root) : first;
   const result = yield* runRange(root, base, second ?? first);
 
   yield* Console.log(report(result));

package/scripts/comment-matchers.ts

@@ -0,0 +1,309 @@
+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 };
+
+export 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,
+};
+
+const extensionOf = (path: string): string => path.slice(path.lastIndexOf(".") + 1);
+
+export function syntaxOf(path: string): Syntax | undefined {
+  const extension = extensionOf(path);
+  return Object.hasOwn(SYNTAXES, extension) ? SYNTAXES[extension] : undefined;
+}
+
+export function unreadable(path: string): string {
+  return `${path} is code the comment checks cannot read: add a comment syntax for .${extensionOf(path)} to scripts/comment-matchers.ts`;
+}
+
+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.charAt(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.charAt(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 commentsIn(source: string, syntax: Syntax): Comment[] {
+  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.charAt(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.charAt(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.charAt(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.charAt(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 firstLine(text: string): string {
+  const newline = text.indexOf("\n");
+  return newline < 0 ? text : text.slice(0, newline);
+}
+
+function beginsItsLine(comment: Comment, lines: readonly string[]): boolean {
+  const line = lines[comment.line - 1];
+  return line !== undefined && line.trimStart().startsWith(firstLine(comment.text));
+}
+
+function openingBlock(found: readonly Comment[], source: string): Comment[] {
+  const lines = source.split("\n");
+  const block: Comment[] = [];
+  let next = 1;
+  for (const comment of found) {
+    if (comment.line !== next || !beginsItsLine(comment, lines)) break;
+    block.push(comment);
+    next = comment.line + comment.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 refusalsIn(path: string, source: string, syntax: Syntax, within?: ReadonlySet<number>): string[] {
+  const out: string[] = [];
+  const found = commentsIn(source, syntax);
+
+  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;
+}
+
+export function refused(path: string, source: string, within?: ReadonlySet<number>): string[] {
+  const syntax = syntaxOf(path);
+  if (syntax === undefined) throw new Error(unreadable(path));
+  return refusalsIn(path, source, syntax, within);
+}