chaffjs 0.17.0 → 0.19.0

package/src/compare/fact-text.ts

@@ -0,0 +1,87 @@
+import { bareUrls, type BareUrl } from "../bare-url.ts";
+import { emphasisSpans, linkChrome } from "../document.ts";
+import { opaqueSpans } from "../markdown-read.ts";
+import { spanOf, type MarkdownNode } from "../markdown-node.ts";
+import { maskSpans } from "../mask.ts";
+import { unmaskedSoftBreaks } from "../soft-break.ts";
+import { eachPreOrder } from "../tree-walk.ts";
+import type { Span } from "../plugin.ts";
+import { overlapsAny, spanIndex, type SpanIndex } from "./spans.ts";
+
+/**
+ * The document as the facts in prose are read from it: the same length as the source, with what is not prose
+ * blanked. Code, HTML and front matter are compared as code or not at all; a link's target and a bare URL are
+ * compared as URLs. Blanking them keeps the digits of a URL from being read again as numbers.
+ */
+export type FactText = {
+  /** The source with code and URLs blanked. Offsets are the source's. */
+  readonly text: string;
+  /** The source with only code blanked: footnote marks are link syntax, so they are read before links are blanked. */
+  readonly codeless: string;
+  /** Where the blanked parts are. A fact the structure reader found there is not a fact of the prose. */
+  readonly blanked: SpanIndex;
+  readonly bareUrls: readonly BareUrl[];
+  /** Ordered-list markers (`1.`): they number the list, they do not state a number. */
+  readonly listMarkers: readonly Span[];
+  /**
+   * What a reader of the rendered Markdown never sees, sorted: a line break between two wide characters (「系の\nシステム」)
+   * and the marks of bold. A plain-text document shows its line breaks, so it has none.
+   */
+  readonly unseen: readonly Span[];
+};
+
+/** Nodes whose whole span is not read as prose: a link reference definition's URL is read as a URL, an image is not text. */
+const WHOLE = new Set(["definition", "image", "imageReference"]);
+const LINKS = new Set(["link", "linkReference"]);
+
+/** `1.` or `1)` at the start of an ordered list item. */
+const ORDERED_MARKER = /^\s*\d{1,9}[.)]/u;
+
+const listMarker = (node: MarkdownNode, source: string): Span[] => {
+  const span = spanOf(node);
+  if (node.type !== "listItem" || span === undefined) return [];
+  const marker = ORDERED_MARKER.exec(source.slice(span.start, span.end));
+  return marker === null ? [] : [{ start: span.start, end: span.start + marker[0].length }];
+};
+
+type MarkdownParts = { readonly chrome: Span[]; readonly linkSpans: Span[]; readonly listMarkers: Span[] };
+
+const markdownParts = (root: MarkdownNode, source: string): MarkdownParts => {
+  const parts: MarkdownParts = { chrome: [], linkSpans: [], listMarkers: [] };
+  eachPreOrder(root, (node) => {
+    const span = spanOf(node);
+    if (span === undefined) return;
+    if (WHOLE.has(node.type)) parts.chrome.push(span);
+    if (LINKS.has(node.type)) {
+      parts.chrome.push(...linkChrome(node));
+      parts.linkSpans.push(span);
+    }
+    parts.listMarkers.push(...listMarker(node, source));
+  });
+  return parts;
+};
+
+/**
+ * Line breaks are read the way the rules read them: one next to blanked code or a link's marks is kept. Bold marks are
+ * read through, as a reader does not see them: 「系の\n**システム**」 joins too. The break and the marks may touch, so the
+ * spans are merged.
+ */
+const unseenOf = (source: string, text: string, root: MarkdownNode | undefined): readonly Span[] => {
+  if (root === undefined) return [];
+  const emphasis = emphasisSpans(root, source);
+  const breaks = unmaskedSoftBreaks(maskSpans(source, emphasis), maskSpans(text, emphasis));
+  return spanIndex([...breaks, ...emphasis]);
+};
+
+/** root is the Markdown tree, or undefined for a plain-text document, where nothing is code and URLs are bare. */
+export const factTextOf = (source: string, root: MarkdownNode | undefined): FactText => {
+  const code = root === undefined ? [] : opaqueSpans(root);
+  const codeless = maskSpans(source, code);
+  const parts = root === undefined ? { chrome: [], linkSpans: [], listMarkers: [] } : markdownParts(root, source);
+  const insideLinks = spanIndex(parts.linkSpans);
+  // An autolink's text is its URL: it is read once, as the link.
+  const bare = bareUrls(codeless).filter((url) => !overlapsAny(insideLinks, url));
+  const blanked = [...code, ...parts.chrome, ...bare];
+  const text = maskSpans(source, blanked);
+  return { text, codeless, blanked: spanIndex(blanked), bareUrls: bare, listMarkers: parts.listMarkers, unseen: unseenOf(source, text, root) };
+};

package/src/compare/facts-render.ts

@@ -0,0 +1,63 @@
+import { ATOM_KINDS, type Atom, type AtomKind, type Extraction, type Unread } from "./atom.ts";
+import { countsOf } from "./outcome.ts";
+import { atomJson, shown } from "./render.ts";
+import type { FactsText } from "./facts-text.ts";
+
+/** One document's facts as `chaff facts` lists them. */
+export type FactList = { readonly path: string; readonly language: string; readonly extraction: Extraction };
+
+/** Kind by kind in compare's order, and within a kind in the order the document states them. */
+export const inChecklistOrder = (atoms: readonly Atom[]): Atom[] =>
+  atoms.toSorted((left, right) => ATOM_KINDS.indexOf(left.kind) - ATOM_KINDS.indexOf(right.kind) || left.line - right.line);
+
+/** Every kind with its count, zeros too: an empty kind reads as "none stated", never as "not looked at". */
+const perKind = (atoms: readonly Atom[], text: FactsText): string => {
+  const counts = countsOf(atoms);
+  return ATOM_KINDS.map((kind) => text.kindCount(text.kinds[kind], counts[kind])).join(text.separator);
+};
+
+const title = (list: FactList, text: FactsText): string => text.title(list.path, list.extraction.atoms.length, perKind(list.extraction.atoms, text));
+
+const checklistLine = (atom: Atom, path: string): string => `  - [ ] ${shown(atom.text)}  (${path}:${String(atom.line)})`;
+
+const kindBlock = (ordered: readonly Atom[], kind: AtomKind, path: string, text: FactsText): string[] => {
+  const ofKind = ordered.filter((atom) => atom.kind === kind);
+  return ofKind.length === 0 ? [] : ["", text.kindHeading(text.kinds[kind], ofKind.length), ...ofKind.map((atom) => checklistLine(atom, path))];
+};
+
+const unreadBlock = (unread: readonly Unread[], text: FactsText): string[] =>
+  unread.length === 0 ? [] : ["", text.unreadHeading, ...unread.map((entry) => `  ${text.unread(entry.kind, entry.reason)}`)];
+
+/** For a person or an AI about to rewrite: a checklist per kind, with the line each fact is on. */
+export const renderFactsFriendly = (list: FactList, text: FactsText): string => {
+  const ordered = inChecklistOrder(list.extraction.atoms);
+  return [
+    title(list, text),
+    ...ATOM_KINDS.flatMap((kind) => kindBlock(ordered, kind, list.path, text)),
+    ...unreadBlock(list.extraction.unread, text),
+    "",
+    text.next(list.path),
+  ].join("\n");
+};
+
+/** For grep: one fact per line with the kind in English, then what was not read, then the counts. */
+export const renderFactsCompact = (list: FactList, text: FactsText): string =>
+  [
+    ...inChecklistOrder(list.extraction.atoms).map((atom) => `${list.path}:${String(atom.line)}: ${atom.kind} ${shown(atom.text)}`),
+    ...list.extraction.unread.map((entry) => `${list.path}: unread ${entry.kind} (${entry.reason})`),
+    title(list, text),
+  ].join("\n");
+
+/** For an AI to keep as its inventory: every fact with its kind, key, text and line, and the counts per kind. */
+export const renderFactsJson = (list: FactList): string =>
+  JSON.stringify(
+    {
+      path: list.path,
+      language: list.language,
+      counts: countsOf(list.extraction.atoms),
+      unread: list.extraction.unread,
+      facts: inChecklistOrder(list.extraction.atoms).map(atomJson),
+    },
+    null,
+    2,
+  );

package/src/compare/facts-text.ts

@@ -0,0 +1,41 @@
+import type { Texts } from "../ui.ts";
+import { counted } from "../render/plural.ts";
+import { COMPARE_TEXT, type CompareText } from "./text.ts";
+
+/** What `chaff facts` says. The names of the kinds and the reasons a kind was not read are compare's own. */
+export type FactsText = Pick<CompareText, "kinds" | "unread" | "unreadHeading" | "separator"> & {
+  readonly usage: string;
+  /** The first line: the file, how many facts, and the count per kind. */
+  readonly title: (path: string, total: number, perKind: string) => string;
+  readonly kindHeading: (kindName: string, count: number) => string;
+  /** How a kind is counted in the first line (数 12 / numbers 12). */
+  readonly kindCount: (kindName: string, count: number) => string;
+  /** The last line: the command that checks a rewrite against this list. */
+  readonly next: (path: string) => string;
+};
+
+const shared = (text: CompareText): Pick<CompareText, "kinds" | "unread" | "unreadHeading" | "separator"> => ({
+  kinds: text.kinds,
+  unread: text.unread,
+  unreadHeading: text.unreadHeading,
+  separator: text.separator,
+});
+
+export const FACTS_TEXT: Texts<FactsText> = {
+  ja: {
+    ...shared(COMPARE_TEXT.ja),
+    usage: "使い方: chaff facts <file> [--compact | --json] [--language ja|en|…] [--genre <ジャンル>]",
+    title: (path, total, perKind) => `${path} の事実 ${String(total)} 件（${perKind}）`,
+    kindHeading: (kindName, count) => `${kindName} ${String(count)} 件`,
+    kindCount: (kindName, count) => `${kindName} ${String(count)}`,
+    next: (path) => `書き直したら npx chaffjs compare ${path} <書き直した後> で、この一覧が残っているかを確かめます`,
+  },
+  en: {
+    ...shared(COMPARE_TEXT.en),
+    usage: "usage: chaff facts <file> [--compact | --json] [--language ja|en|…] [--genre <genre>]",
+    title: (path, total, perKind) => `${path}: ${counted(total, "fact")} (${perKind})`,
+    kindHeading: (kindName, count) => `${kindName}: ${String(count)}`,
+    kindCount: (kindName, count) => `${kindName} ${String(count)}`,
+    next: (path) => `After rewriting, npx chaffjs compare ${path} <rewritten> checks that every fact on this list is still there`,
+  },
+};

package/src/compare/markup-atoms.ts

@@ -0,0 +1,29 @@
+import { spanOf, type MarkdownNode } from "../markdown-node.ts";
+import { eachPreOrder } from "../tree-walk.ts";
+import type { Markup } from "../plugin.ts";
+import type { BareUrl } from "../bare-url.ts";
+import type { Atom } from "./atom.ts";
+
+const CODE = new Set(["code", "inlineCode"]);
+
+/** Inline code and code blocks, compared as written: the key is the code itself, without its backticks or fences. */
+export const codeAtoms = (root: MarkdownNode, lineOf: (offset: number) => number): Atom[] => {
+  const found: Atom[] = [];
+  eachPreOrder(root, (node) => {
+    const span = spanOf(node);
+    if (!CODE.has(node.type) || span === undefined) return;
+    const code = node.value ?? "";
+    found.push({ kind: "code", key: code, text: code, line: lineOf(span.start) });
+  });
+  return found;
+};
+
+/** Where links point (a Markdown link, an autolink, a used reference definition) and URLs written bare. */
+export const urlAtoms = (markup: Markup | undefined, bare: readonly BareUrl[], lineOf: (offset: number) => number): Atom[] => [
+  ...(markup?.links ?? []).map((link) => ({ kind: "url" as const, key: link.destination, text: link.destination, line: lineOf(link.start) })),
+  ...bare.map((url) => ({ kind: "url" as const, key: url.url, text: url.url, line: lineOf(url.start) })),
+];
+
+/** Markdown headings as structure: the key is the level, so a reworded heading is the same heading in another form. */
+export const headingAtoms = (markup: Markup | undefined, lineOf: (offset: number) => number): Atom[] =>
+  (markup?.headings ?? []).map((heading) => ({ kind: "heading", key: "#".repeat(heading.depth), text: heading.text, line: lineOf(heading.start) }));

package/src/compare/match.ts

@@ -0,0 +1,105 @@
+import type { Atom } from "./atom.ts";
+
+/** The same fact written another way: 1,000円 and 1000円, 2026年4月1日 and 2026/4/1, a reworded heading. */
+export type Reformed = { readonly before: Atom; readonly after: Atom };
+
+export type Comparison = {
+  /** In the first document and not in the second. */
+  readonly dropped: readonly Atom[];
+  /** In the second document and not in the first. */
+  readonly added: readonly Atom[];
+  readonly reformed: readonly Reformed[];
+};
+
+export const identity = (atom: Atom): string => `${atom.kind}\u0000${atom.key}`;
+
+const groupBy = <T>(items: readonly T[], keyOf: (item: T) => string): Map<string, T[]> => {
+  const groups = new Map<string, T[]>();
+  items.forEach((item) => {
+    const key = keyOf(item);
+    const group = groups.get(key);
+    if (group === undefined) groups.set(key, [item]);
+    else group.push(item);
+  });
+  return groups;
+};
+
+/** Takes and removes the first item the queue for key holds. */
+type Queues<T> = { readonly groups: Map<string, T[]>; readonly taken: Map<string, number> };
+
+const queuesOf = <T>(items: readonly T[], keyOf: (item: T) => string): Queues<T> => ({ groups: groupBy(items, keyOf), taken: new Map() });
+
+/** The next item not yet taken under key. A cursor, not shift(): shift moves every item left, which is quadratic over a long queue. */
+const takeFrom = <T>(queues: Queues<T>, key: string): T | undefined => {
+  const next = queues.taken.get(key) ?? 0;
+  const item = queues.groups.get(key)?.[next];
+  if (item !== undefined) queues.taken.set(key, next + 1);
+  return item;
+};
+
+/** Atoms of one fact: written the same way they need no report; written differently they pair as reformed; the rest are surplus. */
+const matchGroup = (before: readonly Atom[], after: readonly Atom[]): Comparison => {
+  const afterByText = queuesOf(after, (atom) => atom.text);
+  const sameText = new Set<Atom>();
+  const unmatchedBefore = before.filter((atom) => {
+    const twin = takeFrom(afterByText, atom.text);
+    if (twin !== undefined) sameText.add(twin);
+    return twin === undefined;
+  });
+  const unmatchedAfter = after.filter((atom) => !sameText.has(atom));
+  const pairs = Math.min(unmatchedBefore.length, unmatchedAfter.length);
+  return {
+    reformed: unmatchedBefore.slice(0, pairs).map((atom, index) => ({ before: atom, after: unmatchedAfter[index] ?? atom })),
+    dropped: unmatchedBefore.slice(pairs),
+    added: unmatchedAfter.slice(pairs),
+  };
+};
+
+const unitQueue = (value: string | undefined, unitless: boolean): string => `${value ?? ""}\u0000${unitless ? "bare" : "unit"}`;
+
+/**
+ * A number one side wrote with a unit the language package read (30 ＧＢ) and the other wrote so the unit was not read
+ * (30GB) is one number in another form. Two different units (5 件, 5 人) stay a dropped and an added fact.
+ */
+const pairUnits = (comparison: Comparison): Comparison => {
+  const addedNumbers = queuesOf(
+    comparison.added.filter((atom) => atom.kind === "number"),
+    (atom) => unitQueue(atom.value, atom.unitless === true),
+  );
+  const paired = new Set<Atom>();
+  const reformed = comparison.dropped.flatMap((atom): Reformed[] => {
+    // Two unitless numbers of one value share a key and were already paired; only the other side's kind can match.
+    const found = atom.kind === "number" ? takeFrom(addedNumbers, unitQueue(atom.value, atom.unitless !== true)) : undefined;
+    if (found === undefined) return [];
+    paired.add(atom).add(found);
+    return [{ before: atom, after: found }];
+  });
+  return {
+    dropped: comparison.dropped.filter((atom) => !paired.has(atom)),
+    added: comparison.added.filter((atom) => !paired.has(atom)),
+    reformed: [...comparison.reformed, ...reformed],
+  };
+};
+
+const byLine = (left: Atom, right: Atom): number => left.line - right.line;
+
+/**
+ * The facts of two documents compared as multisets: where a fact is written does not matter, how many times it is
+ * stated does. Pure: the same atoms always give the same comparison.
+ */
+export const compareAtoms = (before: readonly Atom[], after: readonly Atom[]): Comparison => {
+  const beforeGroups = groupBy(before, identity);
+  const afterGroups = groupBy(after, identity);
+  const keys = [...new Set([...beforeGroups.keys(), ...afterGroups.keys()])];
+  const groups = keys.map((key) => matchGroup(beforeGroups.get(key) ?? [], afterGroups.get(key) ?? []));
+  const paired = pairUnits({
+    dropped: groups.flatMap((group) => group.dropped),
+    added: groups.flatMap((group) => group.added),
+    reformed: groups.flatMap((group) => group.reformed),
+  });
+  return {
+    dropped: paired.dropped.toSorted(byLine),
+    added: paired.added.toSorted(byLine),
+    reformed: paired.reformed.toSorted((left, right) => byLine(left.before, right.before)),
+  };
+};

package/src/compare/outcome.ts

@@ -0,0 +1,80 @@
+import { type Atom, type AtomKind, type Extraction, type Unread } from "./atom.ts";
+import { compareAtoms, type Reformed } from "./match.ts";
+import { unwrittenNames } from "./written-names.ts";
+import { unstatedChanges } from "./distinct.ts";
+
+/** One document as compared: where it is, how many facts of each kind it states, and what could not be read. */
+export type Side = {
+  readonly path: string;
+  readonly counts: Readonly<Record<AtomKind, number>>;
+  readonly unread: readonly Unread[];
+};
+
+/** A dropped or added fact, and whether the command line allowed its kind to change. */
+export type Change = Atom & { readonly allowed: boolean };
+
+export type Outcome = {
+  readonly before: Side;
+  readonly after: Side;
+  readonly dropped: readonly Change[];
+  readonly added: readonly Change[];
+  readonly reformed: readonly Reformed[];
+  /** No fact dropped or added, other than of a kind allowed to be. */
+  readonly ok: boolean;
+};
+
+/** Kinds whose facts may be dropped or added on purpose (--allow-dropped, --allow-added). */
+export type Allowed = { readonly dropped: ReadonlySet<AtomKind>; readonly added: ReadonlySet<AtomKind> };
+
+const NOTHING_ALLOWED: Allowed = { dropped: new Set(), added: new Set() };
+
+/** How facts are counted: as-stated compares how many times each is stated, distinct only whether it is stated (--distinct). */
+export type Counting = "as-stated" | "distinct";
+
+const NO_FACTS: Readonly<Record<AtomKind, number>> = {
+  number: 0,
+  date: 0,
+  time: 0,
+  url: 0,
+  code: 0,
+  name: 0,
+  quote: 0,
+  heading: 0,
+  reference: 0,
+  footnote: 0,
+};
+
+export const countsOf = (atoms: readonly Atom[]): Record<AtomKind, number> => {
+  const counts = { ...NO_FACTS };
+  atoms.forEach((atom) => {
+    counts[atom.kind] += 1;
+  });
+  return counts;
+};
+
+const sideOf = (path: string, extraction: Extraction): Side => ({ path, counts: countsOf(extraction.atoms), unread: extraction.unread });
+
+const marked = (atoms: readonly Atom[], allowed: ReadonlySet<AtomKind>): Change[] => atoms.map((atom) => ({ ...atom, allowed: allowed.has(atom.kind) }));
+
+export type Compared = { readonly path: string; readonly extraction: Extraction };
+
+/** The changes of one side that the other side does not state: as many times (as-stated), or at all (distinct). */
+const changesOf = (changes: readonly Atom[], own: Extraction, other: Extraction, counting: Counting): Atom[] => {
+  const unwritten = unwrittenNames(changes, own.atoms, other.nameText);
+  return counting === "distinct" ? unstatedChanges(unwritten, other.atoms, other.nameText) : unwritten;
+};
+
+/** What `chaff compare` reports: the comparison of two documents' facts, with the allowed kinds set aside. */
+export const outcomeOf = (before: Compared, after: Compared, allowed: Allowed = NOTHING_ALLOWED, counting: Counting = "as-stated"): Outcome => {
+  const comparison = compareAtoms(before.extraction.atoms, after.extraction.atoms);
+  const dropped = marked(changesOf(comparison.dropped, before.extraction, after.extraction, counting), allowed.dropped);
+  const added = marked(changesOf(comparison.added, after.extraction, before.extraction, counting), allowed.added);
+  return {
+    before: sideOf(before.path, before.extraction),
+    after: sideOf(after.path, after.extraction),
+    dropped,
+    added,
+    reformed: comparison.reformed,
+    ok: [...dropped, ...added].every((change) => change.allowed),
+  };
+};

package/src/compare/proper-nouns.ts

@@ -0,0 +1,65 @@
+import type { ProseDocument, Span, Token } from "../plugin.ts";
+import type { Atom } from "./atom.ts";
+import { overlapsAny, type SpanIndex } from "./spans.ts";
+import { factKey } from "./fact-key.ts";
+
+const PROPER_NOUN = "PROPN";
+
+/** Two proper nouns with at most one space between them are one name: New York, 日本 銀行. */
+const MAX_GAP = 1;
+
+type Run = Span & { readonly words: number };
+
+const joins = (run: Run | undefined, token: Token, text: string): run is Run =>
+  run !== undefined && token.span.start - run.end <= MAX_GAP && text.slice(run.end, token.span.start).trim() === "";
+
+/** Adjacent proper nouns, each run one name. */
+const runsOf = (tokens: readonly Token[], text: string): Run[] =>
+  tokens.reduce<Run[]>((runs, token) => {
+    if (token.pos !== PROPER_NOUN) return runs;
+    const last = runs.at(-1);
+    if (joins(last, token, text)) runs[runs.length - 1] = { start: last.start, end: token.span.end, words: last.words + 1 };
+    else runs.push({ start: token.span.start, end: token.span.end, words: 1 });
+    return runs;
+  }, []);
+
+/** Words written in lower case. A capitalised word the same document also writes this way is a common word that began a sentence. */
+const LOWER_CASE_WORD = /(?<![\p{L}\p{M}])\p{Ll}[\p{L}\p{M}]*/gu;
+
+const lowerCaseWords = (source: string): ReadonlySet<string> => new Set(source.match(LOWER_CASE_WORD) ?? []);
+
+const withLowerFirst = (word: string): string => `${word.charAt(0).toLowerCase()}${word.slice(1)}`;
+
+/** A one-word name the document also writes in lower case ("Scammers" opening a sentence, "scammers" elsewhere). */
+const isCommonWord = (run: Run, written: string, lowerCase: ReadonlySet<string>): boolean => {
+  const lowered = withLowerFirst(written);
+  return run.words === 1 && lowered !== written && lowerCase.has(lowered);
+};
+
+export type NounInput = {
+  readonly doc: ProseDocument;
+  /** Facts other readers took and what is not prose: a proper noun inside one is read as that, not again here. */
+  readonly taken: SpanIndex;
+  readonly lineOf: (offset: number) => number;
+  /** What a reader never sees (FactText.unseen): a line break inside a name does not make another name. */
+  readonly unseen: readonly Span[];
+};
+
+/** Whether the language package tagged parts of speech: without them, a document with sentences has no proper nouns to read. */
+export const readsProperNouns = (doc: ProseDocument): boolean => doc.sentences.length === 0 || doc.sentences.some((sentence) => sentence.tokens !== undefined);
+
+/**
+ * Proper nouns as the part-of-speech tagger reads them in sentences. Headings are left out: they are compared as
+ * headings, may be reworded, and a title-case heading makes every word look like a name.
+ */
+export const properNouns = (input: NounInput): Atom[] => {
+  const { source } = input.doc;
+  const lowerCase = lowerCaseWords(source);
+  return input.doc.sentences.flatMap((sentence) =>
+    runsOf(sentence.tokens ?? [], source).flatMap((run): Atom[] => {
+      const text = source.slice(run.start, run.end);
+      if (overlapsAny(input.taken, run) || isCommonWord(run, text, lowerCase)) return [];
+      return [{ kind: "name", key: factKey(source, run, input.unseen), text, line: input.lineOf(run.start) }];
+    }),
+  );
+};

package/src/compare/render.ts

@@ -0,0 +1,102 @@
+import { ATOM_KINDS, type Atom, type AtomKind } from "./atom.ts";
+import type { Reformed } from "./match.ts";
+import type { Change, Outcome, Side } from "./outcome.ts";
+import type { CompareText } from "./text.ts";
+
+/** How much of a fact is shown: a code block is shown by its first line. */
+const SHOWN_WIDTH = 60;
+
+/** One line of a fact as written: a code block or a wrapped quotation is shown on one line, cut at SHOWN_WIDTH. */
+export const shown = (text: string): string => {
+  const oneLine = text.replace(/\s+/gu, " ").trim();
+  return oneLine.length > SHOWN_WIDTH ? `${oneLine.slice(0, SHOWN_WIDTH)}…` : oneLine;
+};
+
+const totalOf = (side: Side): number => ATOM_KINDS.reduce((sum, kind) => sum + side.counts[kind], 0);
+
+/** The count line. Every kind is listed, zeros too: "nothing dropped" reads as N facts checked, never as nothing looked at. */
+const checkedLine = (outcome: Outcome, text: CompareText): string => {
+  const perKind = ATOM_KINDS.map((kind) => `${text.kinds[kind]} ${String(outcome.before.counts[kind])}→${String(outcome.after.counts[kind])}`);
+  return text.checked(totalOf(outcome.before), totalOf(outcome.after), perKind.join(text.separator));
+};
+
+const failing = (changes: readonly Change[]): number => changes.filter((change) => !change.allowed).length;
+
+const verdict = (outcome: Outcome, text: CompareText): string => (outcome.ok ? text.clean : text.failed(failing(outcome.dropped), failing(outcome.added)));
+
+const kindColumn = (kind: AtomKind, text: CompareText): string => `${text.kind[kind]}: `;
+
+const changeLine = (change: Change, path: string, flag: string, text: CompareText): string =>
+  `  ${kindColumn(change.kind, text)}${shown(change.text)}  (${path}:${String(change.line)})${change.allowed ? text.allowed(flag) : ""}`;
+
+const reformedLine = (pair: Reformed, text: CompareText): string =>
+  `  ${kindColumn(pair.before.kind, text)}${shown(pair.before.text)} → ${shown(pair.after.text)}  (${text.lines(pair.before.line, pair.after.line)})`;
+
+const block = (heading: string, lines: readonly string[]): string[] => (lines.length === 0 ? [] : ["", heading, ...lines]);
+
+const unreadBlock = (outcome: Outcome, text: CompareText): string[] => {
+  const sides = [outcome.before, outcome.after];
+  const lines = sides.flatMap((side) => side.unread.map((unread) => `  ${side.path}: ${text.unread(unread.kind, unread.reason)}`));
+  return block(text.unreadHeading, lines);
+};
+
+/** For a person: what was dropped and added, with the line in each file, then what only changed its form. */
+export const renderFriendly = (outcome: Outcome, text: CompareText): string => {
+  const { before, after } = outcome;
+  return [
+    `${before.path} → ${after.path}`,
+    ...block(
+      text.droppedHeading(outcome.dropped.length, before.path, after.path),
+      outcome.dropped.map((change) => changeLine(change, before.path, "--allow-dropped", text)),
+    ),
+    ...block(
+      text.addedHeading(outcome.added.length, after.path),
+      outcome.added.map((change) => changeLine(change, after.path, "--allow-added", text)),
+    ),
+    ...block(
+      text.reformedHeading(outcome.reformed.length),
+      outcome.reformed.map((pair) => reformedLine(pair, text)),
+    ),
+    ...unreadBlock(outcome, text),
+    "",
+    checkedLine(outcome, text),
+    verdict(outcome, text),
+  ].join("\n");
+};
+
+const compactChange = (change: Change, path: string, word: string): string =>
+  `${path}:${String(change.line)}: ${word} ${change.kind} ${shown(change.text)}${change.allowed ? " (allowed)" : ""}`;
+
+/** For an engineer and grep: one line per fact, the words dropped / added / reformed and the kind in English. */
+export const renderCompact = (outcome: Outcome, text: CompareText): string => {
+  const { before, after } = outcome;
+  return [
+    ...outcome.dropped.map((change) => compactChange(change, before.path, "dropped")),
+    ...outcome.added.map((change) => compactChange(change, after.path, "added")),
+    ...outcome.reformed.map(
+      (pair) =>
+        `${before.path}:${String(pair.before.line)} → ${after.path}:${String(pair.after.line)}: reformed ${pair.before.kind} ${shown(pair.before.text)} → ${shown(pair.after.text)}`,
+    ),
+    ...before.unread.map((unread) => `${before.path}: unread ${unread.kind} (${unread.reason})`),
+    ...after.unread.map((unread) => `${after.path}: unread ${unread.kind} (${unread.reason})`),
+    checkedLine(outcome, text),
+    text.tally(failing(outcome.dropped), failing(outcome.added), outcome.reformed.length),
+  ].join("\n");
+};
+
+export const atomJson = (atom: Atom): Readonly<Record<string, string | number>> => ({ kind: atom.kind, key: atom.key, text: atom.text, line: atom.line });
+
+/** For an AI to act on: every dropped and added fact with its line, the reformed pairs, and the counts per kind. */
+export const renderJson = (outcome: Outcome): string =>
+  JSON.stringify(
+    {
+      ok: outcome.ok,
+      before: outcome.before,
+      after: outcome.after,
+      dropped: outcome.dropped.map((change) => ({ ...atomJson(change), allowed: change.allowed })),
+      added: outcome.added.map((change) => ({ ...atomJson(change), allowed: change.allowed })),
+      reformed: outcome.reformed.map((pair) => ({ kind: pair.before.kind, key: pair.before.key, before: atomJson(pair.before), after: atomJson(pair.after) })),
+    },
+    null,
+    2,
+  );

package/src/compare/spans.ts

@@ -0,0 +1,17 @@
+import type { Span } from "../plugin.ts";
+import { firstEndingAfter } from "../soft-break.ts";
+import { mergeSpans } from "../span-merge.ts";
+
+/** Spans made ready for lookups: sorted and merged, so each lookup is a binary search, not a scan of every span. */
+export type SpanIndex = readonly Span[];
+
+export const spanIndex = (spans: readonly Span[]): SpanIndex => mergeSpans(spans, false);
+
+/** Whether span shares at least one character with a span in the index. */
+export const overlapsAny = (index: SpanIndex, span: Span): boolean => {
+  const region = index[firstEndingAfter(index, span.start)];
+  return region !== undefined && region.start < span.end;
+};
+
+/** Whether the character at offset is inside a span in the index. */
+export const coversOffset = (index: SpanIndex, offset: number): boolean => overlapsAny(index, { start: offset, end: offset + 1 });