@avi2dg/checks 0.11.0 → 0.13.0

package/scripts/doc-outline.ts

@@ -0,0 +1,215 @@
+export type Line = {
+  readonly line: number;
+  readonly text: string;
+};
+
+export type Heading = {
+  readonly level: number;
+  readonly title: string;
+  readonly line: number;
+};
+
+export type Section = {
+  readonly heading: Heading;
+  readonly body: readonly Line[];
+  readonly subsections: readonly Section[];
+};
+
+export type Outline = {
+  readonly lines: readonly Line[];
+  readonly prose: readonly Line[];
+  readonly headings: readonly Heading[];
+  readonly lead: readonly Line[];
+  readonly sections: readonly Section[];
+};
+
+export type Violation = {
+  readonly line: number;
+  readonly message: string;
+};
+
+export type HeadingRule = "any" | "version";
+
+export type Presence = { readonly required: true } | { readonly required: false; readonly omitWhen: string };
+
+type SlotShape = {
+  readonly presence: Presence;
+  readonly body: readonly string[];
+  readonly subsections?: readonly Slot[];
+};
+
+export type FixedSlot = SlotShape & {
+  readonly type: "fixed";
+  readonly text: string;
+  readonly also?: readonly string[];
+};
+
+export type OpenSlot = SlotShape & {
+  readonly type: "open";
+  readonly placeholder: string;
+  readonly rule: HeadingRule;
+  readonly interleaved?: true;
+};
+
+export type Slot = FixedSlot | OpenSlot;
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const HEADING = /^ {0,3}(#{1,6})(?:[ \t]+|$)(.*)$/;
+const CLOSING_HASHES = /(?:^|[ \t]+)#+[ \t]*$/;
+
+function fenceCloses(text: string, opener: string): boolean {
+  const closer = FENCE.exec(text)?.[1];
+  return closer !== undefined && closer[0] === opener[0] && closer.length >= opener.length && text.trim() === closer;
+}
+
+function headingOf({ line, text }: Line): Heading | undefined {
+  const match = HEADING.exec(text);
+  if (match === null) return undefined;
+  const [, hashes = "", rest = ""] = match;
+  return { level: hashes.length, title: rest.replace(CLOSING_HASHES, "").trim(), line };
+}
+
+function between(lines: readonly Line[], after: number, before: number): readonly Line[] {
+  return lines.filter(({ line }) => line > after && line < before);
+}
+
+function sectionsAt(level: number, headings: readonly Heading[], lines: readonly Line[], end: number): Section[] {
+  return headings.flatMap((heading, index) => {
+    if (heading.level !== level) return [];
+    const next = headings.slice(index + 1);
+    const close = next.find((other) => other.level <= level)?.line ?? end;
+    const within = next.filter((other) => other.line < close);
+    return [
+      {
+        heading,
+        body: between(lines, heading.line, within[0]?.line ?? close),
+        subsections: sectionsAt(level + 1, within, lines, close),
+      },
+    ];
+  });
+}
+
+export function parseOutline(text: string): Outline {
+  const lines = text.split("\n").map((raw, index) => ({ line: index + 1, text: raw.replace(/\r$/, "") }));
+  const prose: Line[] = [];
+  const headings: Heading[] = [];
+  let fence: string | undefined;
+  for (const line of lines) {
+    if (fence !== undefined) {
+      if (fenceCloses(line.text, fence)) fence = undefined;
+      continue;
+    }
+    const opener = FENCE.exec(line.text)?.[1];
+    if (opener !== undefined) {
+      fence = opener;
+      continue;
+    }
+    prose.push(line);
+    const heading = headingOf(line);
+    if (heading !== undefined) headings.push(heading);
+  }
+  const end = lines.length + 1;
+  const titleLine = headings[0]?.level === 1 ? headings[0].line : 0;
+  return {
+    lines,
+    prose,
+    headings,
+    lead: between(lines, titleLine, headings.find((heading) => heading.line > titleLine)?.line ?? end),
+    sections: sectionsAt(2, headings, lines, end),
+  };
+}
+
+export function firstText(lines: readonly Line[]): Line | undefined {
+  return lines.find(({ text }) => text.trim() !== "");
+}
+
+export function marked(level: number, title: string): string {
+  return `\`${"#".repeat(level)} ${title}\``;
+}
+
+export const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+export function ruleProblem(rule: HeadingRule, title: string): string | undefined {
+  if (rule === "version") return VERSION.test(title) ? undefined : "is not a version such as 1.2.0";
+  return undefined;
+}
+
+export function slotLabel(slot: Slot): string {
+  return slot.type === "fixed" ? slot.text : slot.placeholder;
+}
+
+function fixedIndexOf(slots: readonly Slot[], title: string): number {
+  return slots.findIndex((slot) => slot.type === "fixed" && (slot.text === title || (slot.also ?? []).includes(title)));
+}
+
+function openIndexFrom(slots: readonly Slot[], at: number): { readonly index: number; readonly advances: boolean } {
+  const current = slots[at];
+  if (current?.type === "open") return { index: at, advances: false };
+  const ahead = slots.findIndex((slot, index) => index > at && slot.type === "open");
+  if (ahead !== -1) return { index: ahead, advances: true };
+  const behind = slots.findLastIndex((slot, index) => index < at && slot.type === "open");
+  const reachable = slots[behind];
+  return { index: reachable?.type === "open" && reachable.interleaved === true ? behind : -1, advances: false };
+}
+
+function missing(slot: Slot, level: number): string {
+  return slot.type === "fixed" ? `lacks ${marked(level, slot.text)}` : `lacks a ${marked(level, slot.placeholder)} section`;
+}
+
+export function matchSections(sections: readonly Section[], slots: readonly Slot[], level: number, parentLine: number): Violation[] {
+  const order = `the template's order is ${slots.map(slotLabel).join(", ")}`;
+  const violations: Violation[] = [];
+  const found = slots.map(() => false);
+  let at = -1;
+  for (const { heading, subsections } of sections) {
+    const named = marked(level, heading.title);
+    const fixed = fixedIndexOf(slots, heading.title);
+    if (fixed !== -1 && fixed <= at) {
+      found[fixed] = true;
+      const problem = fixed === at ? "appears twice" : `is out of order, as ${order}`;
+      violations.push({ line: heading.line, message: `${named} ${problem}` });
+      continue;
+    }
+    const open = openIndexFrom(slots, at);
+    const index = fixed !== -1 ? fixed : open.index;
+    const slot = slots[index];
+    if (slot === undefined) {
+      violations.push({ line: heading.line, message: `${named} is not a section the template has there, as ${order}` });
+      continue;
+    }
+    if (fixed !== -1 || open.advances) at = index;
+    found[index] = true;
+    const problem = slot.type === "open" ? ruleProblem(slot.rule, heading.title) : undefined;
+    if (problem !== undefined) violations.push({ line: heading.line, message: `${named} ${problem}` });
+    if (slot.subsections !== undefined) violations.push(...matchSections(subsections, slot.subsections, level + 1, heading.line));
+  }
+  slots.forEach((slot, index) => {
+    if (slot.presence.required && found[index] !== true) violations.push({ line: parentLine, message: missing(slot, level) });
+  });
+  return violations;
+}
+
+const BANNED_TITLES = new Set(["overview", "introduction", "how it works"]);
+
+export function outlineProblems({ headings, lead }: Outline): Violation[] {
+  const violations: Violation[] = [];
+  const [first] = headings;
+  if (first === undefined || first.level !== 1 || first.line !== 1) {
+    violations.push({ line: 1, message: "does not open with a `# ` title on its first line" });
+  }
+  headings.forEach((heading, index) => {
+    const named = marked(heading.level, heading.title);
+    if (heading.level === 1 && index > 0) violations.push({ line: heading.line, message: `${named} is a second title` });
+    const previous = headings[index - 1];
+    if (previous !== undefined && heading.level > previous.level + 1) {
+      violations.push({ line: heading.line, message: `${named} skips a level under ${marked(previous.level, previous.title)}` });
+    }
+    if (BANNED_TITLES.has(heading.title.toLowerCase())) {
+      violations.push({ line: heading.line, message: `${named} names no topic; title it by what the reader does or looks up` });
+    }
+  });
+  if (first?.level === 1 && firstText(lead) === undefined) {
+    violations.push({ line: first.line, message: "has nothing between its title and its first section" });
+  }
+  return violations;
+}

package/scripts/doc-rules.ts

@@ -0,0 +1,176 @@
+import {
+  firstText,
+  marked,
+  matchSections,
+  outlineProblems,
+  parseOutline,
+  ruleProblem,
+  type Heading,
+  type Outline,
+  type Violation,
+  VERSION,
+} from "./doc-outline.ts";
+import { ADR_STATUSES, TEMPLATES, templateFile, type Kind, type Title } from "./doc-templates.ts";
+import { MODES, type Docs, type Mode } from "./quality-file.ts";
+
+export type Placement =
+  | { readonly type: "judged"; readonly kind: Kind }
+  | { readonly type: "undeclared" }
+  | { readonly type: "ambiguous"; readonly modes: readonly Mode[] }
+  | { readonly type: "unjudged" };
+
+export type Doc = {
+  readonly path: string;
+  readonly text: string;
+};
+
+export const ADR_DIRECTORY = "docs/adr/";
+// A generated index takes its shape from its generator.
+const ADR_INDEX = `${ADR_DIRECTORY}README.md`;
+const DOCS_DIRECTORY = "docs/";
+
+const ROOT_FILES = new Map<string, Kind>([
+  ["README.md", "readme"],
+  ["CHANGELOG.md", "changelog"],
+  ["AGENTS.md", "agents"],
+  ["CLAUDE.md", "claude"],
+]);
+
+export function placementOf(path: string, docs: Docs | undefined): Placement {
+  const root = ROOT_FILES.get(path);
+  if (root !== undefined) return { type: "judged", kind: root };
+  if (!path.endsWith(".md") || path === ADR_INDEX) return { type: "unjudged" };
+  if (path.startsWith(ADR_DIRECTORY)) return { type: "judged", kind: "adr" };
+  const modes = MODES.filter((mode) => (docs?.pages?.[mode] ?? []).some((glob) => new Bun.Glob(glob).match(path)));
+  const [mode, ...others] = modes;
+  if (mode !== undefined) return others.length === 0 ? { type: "judged", kind: mode } : { type: "ambiguous", modes };
+  return path.startsWith(DOCS_DIRECTORY) ? { type: "undeclared" } : { type: "unjudged" };
+}
+
+function titleOf({ headings: [first] }: Outline): Heading | undefined {
+  return first?.level === 1 && first.line === 1 ? first : undefined;
+}
+
+function titleProblems(title: Title, heading: Heading): readonly Violation[] {
+  const named = marked(1, heading.title);
+  const at = (message: string) => [{ line: heading.line, message: `${named} ${message}` }];
+  if (title.type === "fixed") return heading.title === title.text ? [] : at(`is not the template's title, ${marked(1, title.text)}`);
+  const prefix = title.prefix ?? "";
+  if (!heading.title.startsWith(prefix)) return at(`does not open with \`${prefix}\``);
+  const problem = ruleProblem(title.rule, heading.title.slice(prefix.length));
+  return problem === undefined ? [] : at(problem);
+}
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+function isDate(text: string | undefined): boolean {
+  if (text === undefined || !ISO_DATE.test(text)) return false;
+  const parsed = new Date(`${text}T00:00:00Z`);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().startsWith(text);
+}
+
+const RECORD_NAME = /^(\d{4})-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+const RECORD_TITLE = /^(\d+)\. \S/;
+const DATE_LINE = /^Date: (\S+)$/;
+
+function recordNumber(path: string): number | undefined {
+  const name = RECORD_NAME.exec(path.slice(ADR_DIRECTORY.length))?.[1];
+  return name === undefined ? undefined : Number(name);
+}
+
+function statusProblem(outline: Outline): Violation | undefined {
+  const status = outline.sections.find(({ heading }) => heading.title === "Status");
+  if (status === undefined) return undefined;
+  const opening = firstText(status.body);
+  const word = opening?.text.trim().split(/\s+/, 1)[0]?.replace(/[.,;:]+$/, "");
+  if (ADR_STATUSES.some((known) => known === word)) return undefined;
+  const found = word === undefined ? "nothing" : `\`${word}\``;
+  return { line: opening?.line ?? status.heading.line, message: `\`## Status\` opens with ${found} where one of ${ADR_STATUSES.join(", ")} goes` };
+}
+
+function adrProblems(path: string, outline: Outline, records: readonly string[]): readonly Violation[] {
+  const violations: Violation[] = [];
+  const filed = recordNumber(path);
+  if (filed === undefined) {
+    violations.push({ line: 1, message: `is not named as a record, a four-digit number and a kebab-case name directly in ${ADR_DIRECTORY}` });
+  }
+  const title = titleOf(outline);
+  const titled = title === undefined ? undefined : RECORD_TITLE.exec(title.title)?.[1];
+  if (title !== undefined && titled === undefined) {
+    violations.push({ line: title.line, message: `${marked(1, title.title)} does not open with the record's number, as in \`# 7. The decision\`` });
+  }
+  if (title !== undefined && titled !== undefined && filed !== undefined && Number(titled) !== filed) {
+    violations.push({ line: title.line, message: `${marked(1, title.title)} carries number ${titled}, and the file name ${filed}` });
+  }
+  const dated = firstText(outline.lead);
+  if (!isDate(DATE_LINE.exec(dated?.text.trim() ?? "")?.[1])) {
+    violations.push({ line: dated?.line ?? 1, message: "does not follow its title with a `Date: YYYY-MM-DD` line" });
+  }
+  const status = statusProblem(outline);
+  if (status !== undefined) violations.push(status);
+  const sharing = records.filter((other) => other !== path && filed !== undefined && recordNumber(other) === filed);
+  if (sharing.length > 0) violations.push({ line: 1, message: `shares number ${filed} with ${sharing.join(", ")}` });
+  return violations;
+}
+
+const RELEASED = /^Released (\S+)\.$/;
+
+function changelogProblems({ sections }: Outline): readonly Violation[] {
+  const releases = sections.filter(({ heading }) => VERSION.test(heading.title));
+  return releases.flatMap(({ heading, body }, index) => {
+    const named = marked(2, heading.title);
+    const dated = firstText(body);
+    const violations: Violation[] = [];
+    if (!isDate(RELEASED.exec(dated?.text.trim() ?? "")?.[1])) {
+      violations.push({ line: dated?.line ?? heading.line, message: `${named} does not open with a \`Released YYYY-MM-DD.\` line` });
+    }
+    const newer = releases[index - 1]?.heading.title;
+    if (newer !== undefined && Bun.semver.order(newer, heading.title) !== 1) {
+      violations.push({ line: heading.line, message: `${named} follows ${marked(2, newer)}, and releases run newest first` });
+    }
+    return violations;
+  });
+}
+
+const STEP = /^ {0,3}\d+[.)][ \t]+\S/;
+
+function stepsProblems(kind: Kind, { prose }: Outline): readonly Violation[] {
+  if (prose.some(({ text }) => STEP.test(text))) return [];
+  return [{ line: 1, message: `numbers no steps, which a ${kind} page lists as \`1.\` items` }];
+}
+
+function kindProblems(kind: Kind, doc: Doc, outline: Outline, records: readonly string[]): readonly Violation[] {
+  if (kind === "adr") return adrProblems(doc.path, outline, records);
+  if (kind === "changelog") return changelogProblems(outline);
+  if (kind === "how-to" || kind === "tutorial") return stepsProblems(kind, outline);
+  return [];
+}
+
+function exactProblems(kind: Kind, expected: string, actual: string): readonly Violation[] {
+  if (actual === expected) return [];
+  const want = expected.split("\n");
+  const have = actual.split("\n");
+  const line = want.findIndex((text, index) => have[index] !== text) + 1 || want.length + 1;
+  return [{ line, message: `differs from ${templateFile(kind)}, which it holds word for word` }];
+}
+
+export function judge(kind: Kind, doc: Doc, records: readonly string[]): readonly Violation[] {
+  const template = TEMPLATES[kind];
+  if (template.shape === "exact") return exactProblems(kind, template.text, doc.text);
+  const outline = parseOutline(doc.text);
+  const title = titleOf(outline);
+  return [
+    ...outlineProblems(outline),
+    ...(title === undefined ? [] : titleProblems(template.title, title)),
+    ...matchSections(outline.sections, template.sections, 2, title?.line ?? 1),
+    ...kindProblems(kind, doc, outline, records),
+  ].toSorted((a, b) => a.line - b.line);
+}
+
+export function placementProblem(placement: Placement): string | undefined {
+  if (placement.type === "undeclared") {
+    return `is a page under ${DOCS_DIRECTORY} with no mode; declare it under docs.pages in quality.json as ${MODES.join(", ")}`;
+  }
+  if (placement.type === "ambiguous") return `is declared under docs.pages as ${placement.modes.join(" and ")}, and a page has one mode`;
+  return undefined;
+}

package/scripts/doc-templates.ts

@@ -0,0 +1,203 @@
+import { slotLabel, type FixedSlot, type HeadingRule, type OpenSlot, type Presence, type Slot } from "./doc-outline.ts";
+import { MODES } from "./quality-file.ts";
+
+export const KINDS = ["readme", "changelog", "adr", "agents", "claude", ...MODES] as const;
+export type Kind = (typeof KINDS)[number];
+
+export type Title =
+  | { readonly type: "fixed"; readonly text: string }
+  | { readonly type: "open"; readonly placeholder: string; readonly rule: HeadingRule; readonly prefix?: string };
+
+export type Outlined = {
+  readonly shape: "outline";
+  readonly title: Title;
+  readonly lead: readonly string[];
+  readonly sections: readonly Slot[];
+};
+
+export type Exact = {
+  readonly shape: "exact";
+  readonly text: string;
+};
+
+export type Template = Outlined | Exact;
+
+export const TEMPLATE_DIRECTORY = "templates";
+
+export const ADR_STATUSES = ["Proposed", "Accepted", "Rejected", "Deprecated", "Superseded", "Retired"] as const;
+
+const REQUIRED: Presence = { required: true };
+
+function optional(omitWhen: string): Presence {
+  return { required: false, omitWhen };
+}
+
+function fixed(text: string, presence: Presence, body: readonly string[], more: Partial<FixedSlot> = {}): FixedSlot {
+  return { type: "fixed", text, presence, body, ...more };
+}
+
+function open(placeholder: string, rule: HeadingRule, presence: Presence, body: readonly string[], more: Partial<OpenSlot> = {}): OpenSlot {
+  return { type: "open", placeholder, rule, presence, body, ...more };
+}
+
+function listed(words: readonly string[]): string {
+  return words.length < 2 ? words.join("") : `${words.slice(0, -1).join(", ")} or ${words.at(-1) ?? ""}`;
+}
+
+const TROUBLESHOOTING = fixed("Troubleshooting", optional("no reader has met a failure worth naming yet"), [], {
+  subsections: [open("<The symptom, or the error text>", "any", REQUIRED, ["<The cause.>", "<The resolution.>"])],
+});
+
+const RELATED_TOPICS = fixed("Related topics", optional("there is no other page to send the reader to"), [
+  "- [<page title>](<path to the page>)",
+]);
+
+const BEFORE_YOU_BEGIN = fixed("Before you begin", REQUIRED, ["- <each prerequisite, with the version it is tested on>"]);
+
+const STEPS = ["To <do the task>:", "", "1. <step>", "1. <step>"];
+
+const MAINTAINING = [
+  "Keep this file for knowledge useful to almost every future agent session in this project.",
+  "Do not repeat what the codebase already shows.",
+  "Point to the authoritative file or command instead.",
+  "Prefer rewriting or pruning existing entries over appending new ones.",
+  "When updating this file, preserve this bar for all agents and keep entries concise.",
+];
+
+const CHANGE_GROUPS = ["Breaking changes", "Features", "Fixes", "Performance", "Reverts"];
+
+export const TEMPLATES: Readonly<Record<Kind, Template>> = {
+  readme: {
+    shape: "outline",
+    title: { type: "open", placeholder: "<name>", rule: "any" },
+    lead: ["<The concept in two to four sentences: what this is, who it is for, why you would use it.>"],
+    sections: [
+      BEFORE_YOU_BEGIN,
+      fixed("Install", REQUIRED, ["To install <name>:", "", "1. <step>", "1. <step>", "", "<What you see when it worked.>"]),
+      open("<Everyday task, verb first>", "any", REQUIRED, STEPS),
+      fixed("Where things are", REQUIRED, ["| Path | What it holds |", "| --- | --- |"]),
+      TROUBLESHOOTING,
+      RELATED_TOPICS,
+    ],
+  },
+  changelog: {
+    shape: "outline",
+    title: { type: "fixed", text: "Changelog" },
+    lead: ["Every release of <package>, newest first, written by the release from its conventional commits."],
+    sections: [
+      open("<version>", "version", REQUIRED, ["Released <YYYY-MM-DD>."], {
+        subsections: CHANGE_GROUPS.map((group) =>
+          fixed(group, optional("the release holds no such commit"), ["- <the commit's subject>"]),
+        ),
+      }),
+    ],
+  },
+  adr: {
+    shape: "outline",
+    title: { type: "open", placeholder: "<number>. <The decision, as a sentence>", rule: "any" },
+    lead: ["Date: <YYYY-MM-DD, the day the record was written>"],
+    sections: [
+      fixed("Status", REQUIRED, [`<${listed(ADR_STATUSES)} as its first word, then what it amends or what replaced it.>`]),
+      fixed("Context", REQUIRED, ["<What forced a decision, and what was true when it was made.>"]),
+      open("<Another part of the record, such as What was considered and rejected>", "any", optional("the record needs no more"), ["<Its text.>"], {
+        interleaved: true,
+      }),
+      fixed("Decision", REQUIRED, ["<What was decided, stated as what now holds.>"], { also: ["Decisions"] }),
+      fixed("Consequences", optional("nothing follows from the decision but the decision"), [
+        "<What follows from the decision, its cost included.>",
+      ]),
+    ],
+  },
+  agents: {
+    shape: "outline",
+    title: { type: "fixed", text: "Project agent memory" },
+    lead: ["<What this repository is, in one sentence, and that README.md holds what a person reads.>"],
+    sections: [
+      open("<A topic an agent needs>", "any", optional("the lead holds every constraint"), [
+        "- <A constraint an agent cannot infer from the code, and the file that holds its detail.>",
+      ]),
+      fixed("Maintaining this file", REQUIRED, MAINTAINING),
+    ],
+  },
+  claude: {
+    shape: "exact",
+    text: "<!-- Points Claude at AGENTS.md via import. Edit AGENTS.md, not this file. -->\n@AGENTS.md\n",
+  },
+  tutorial: {
+    shape: "outline",
+    title: { type: "open", prefix: "Tutorial: ", placeholder: "<Verb and what the reader builds>", rule: "any" },
+    lead: ["<What the reader builds, and what they learn on the way.>"],
+    sections: [
+      BEFORE_YOU_BEGIN,
+      open("<Step, verb first>", "any", REQUIRED, [...STEPS, "", "<What the reader sees now.>"]),
+      TROUBLESHOOTING,
+      RELATED_TOPICS,
+    ],
+  },
+  "how-to": {
+    shape: "outline",
+    title: { type: "open", placeholder: "<Task, verb first>", rule: "any" },
+    lead: ["<Who does this, and when, in one or two sentences.>"],
+    sections: [
+      fixed("Before you begin", optional("the task needs nothing set up first"), BEFORE_YOU_BEGIN.body),
+      open("<Part of the task, verb first>", "any", optional("the page is one task, whose steps then follow the lead"), STEPS),
+      TROUBLESHOOTING,
+      RELATED_TOPICS,
+    ],
+  },
+  reference: {
+    shape: "outline",
+    title: { type: "open", placeholder: "<The thing this page describes, as a noun>", rule: "any" },
+    lead: ["<What the thing is, in one sentence, and when a reader looks it up.>"],
+    sections: [
+      open("<One part of it, as a noun>", "any", optional("the lead and one table describe all of it"), [
+        "<A table, a list or a short description, with no steps and no opinion.>",
+      ]),
+      RELATED_TOPICS,
+    ],
+  },
+  explanation: {
+    shape: "outline",
+    title: { type: "open", placeholder: "<The idea this page explains, as a noun>", rule: "any" },
+    lead: ["<The question this page answers, and the short answer.>"],
+    sections: [
+      open("<One strand of the answer>", "any", optional("the lead holds the whole answer"), [
+        "<The reasoning, the alternatives, and why they lost.>",
+      ]),
+      RELATED_TOPICS,
+    ],
+  },
+};
+
+function titleText(title: Title): string {
+  return title.type === "fixed" ? title.text : `${title.prefix ?? ""}${title.placeholder}`;
+}
+
+function notes(slot: Slot): readonly string[] {
+  const omit = slot.presence.required ? [] : [`<Leave this section out when ${slot.presence.omitWhen}.>`];
+  const moves = slot.type === "open" && slot.interleaved === true ? ["<A section like this may also follow any section below it.>"] : [];
+  return [...omit, ...moves];
+}
+
+function separated(blocks: readonly (readonly string[])[]): readonly string[] {
+  return blocks.filter((block) => block.length > 0).flatMap((block, index) => (index === 0 ? block : ["", ...block]));
+}
+
+function renderSlot(slot: Slot, level: number): readonly string[] {
+  return separated([
+    [`${"#".repeat(level)} ${slotLabel(slot)}`],
+    ...notes(slot).map((note) => [note]),
+    slot.body,
+    ...(slot.subsections ?? []).map((subsection) => renderSlot(subsection, level + 1)),
+  ]);
+}
+
+export function renderTemplate(template: Template): string {
+  if (template.shape === "exact") return template.text;
+  const lines = separated([[`# ${titleText(template.title)}`], template.lead, ...template.sections.map((slot) => renderSlot(slot, 2))]);
+  return `${lines.join("\n")}\n`;
+}
+
+export function templateFile(kind: Kind): string {
+  return `${TEMPLATE_DIRECTORY}/${kind}.md`;
+}

package/scripts/docs.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+import { Console, Effect } from "effect";
+import { ADR_DIRECTORY, judge, placementOf, placementProblem, type Placement } from "./doc-rules.ts";
+import { changedPaths, git, pathsAt, rangeEnds } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+import { readQuality } from "./quality-file.ts";
+
+type Finding = {
+  readonly path: string;
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+type Judged = {
+  readonly held: readonly string[];
+  readonly findings: readonly Finding[];
+  readonly advisory: ReadonlyMap<string, number>;
+};
+
+const NAME = "docs";
+const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
+const MARKDOWN = [":(glob)**/*.md"];
+
+const judgeFile = Effect.fn("judgeFile")(function* (
+  root: string,
+  head: string,
+  path: string,
+  placement: Placement,
+  records: readonly string[],
+) {
+  const misplaced = placementProblem(placement);
+  if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
+  if (placement.type !== "judged") return [];
+  const text = yield* git(["show", `${head}:${path}`], root);
+  return judge(placement.kind, { path, text }, records).map(({ line, message }) => ({ path, line, message }));
+});
+
+const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head: string) {
+  const { quality } = yield* readQuality(root);
+  const touched = new Set(
+    (yield* changedPaths(base, head, MARKDOWN, root)).flatMap((change) => (change.kind === "deleted" ? [] : [change.path])),
+  );
+  const present = yield* pathsAt(head, MARKDOWN, root);
+  const records = present.filter((path) => path.startsWith(ADR_DIRECTORY));
+  const placed = present.map((path) => ({ path, placement: placementOf(path, quality.docs) }));
+  const judged = placed.filter(({ placement }) => placement.type !== "unjudged");
+  const findings = (yield* Effect.forEach(judged, ({ path, placement }) => judgeFile(root, head, path, placement, records), {
+    concurrency: 8,
+  })).flat();
+  const advisory = new Map<string, number>();
+  for (const { path } of findings.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
+  return {
+    held: judged.map(({ path }) => path).filter((path) => touched.has(path)),
+    findings: findings.filter((finding) => touched.has(finding.path)),
+    advisory,
+  } satisfies Judged;
+});
+
+function describe({ path, line, message }: Finding): string {
+  return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
+}
+
+export function report({ held, findings, advisory }: Judged): string {
+  const verdict =
+    findings.length === 0
+      ? [`${NAME}: ${held.length} doc file(s) the range touches hold to their templates`]
+      : [`${NAME}: ${findings.length} violation(s) in the doc files the range touches:`, ...findings.map(describe)];
+  const notice =
+    advisory.size === 0
+      ? []
+      : [
+          `${NAME}: advisory, ${advisory.size} doc file(s) the range leaves alone do not hold to their templates yet:`,
+          ...[...advisory].map(([path, count]) => `  ${path}: ${count} violation(s)`),
+        ];
+  return [...verdict, ...notice].join("\n");
+}
+
+const docs = 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"])).trim();
+  const { base, head } = yield* rangeEnds(first, second, root);
+  const judged = yield* runDocs(root, base, head);
+
+  yield* Console.log(report(judged));
+  return judged.findings.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, docs);