chaffjs 0.17.0 → 0.19.0

package/src/markup.ts

@@ -0,0 +1,212 @@
+import { spanOf, type MarkdownNode } from "./markdown-node.ts";
+import { atxHeadingText, headingText } from "./heading-text.ts";
+import { eachPreOrder } from "./tree-walk.ts";
+import { alertReader } from "./template-syntax.ts";
+import { cutSpans } from "./span-cut.ts";
+import { mergeSpans } from "./span-merge.ts";
+import { firstEndingAfter } from "./soft-break.ts";
+import type { Markup, MarkupHeading, MarkupImage, MarkupLink, Span } from "./plugin.ts";
+
+/** mdast の節のうち、ここで読む値。MarkdownNode の型には無いものを、型を見て取り出す。 */
+const fieldOf = (node: MarkdownNode, field: string): unknown => (field in node ? Reflect.get(node, field) : undefined);
+
+const numberField = (node: MarkdownNode, field: string): number | undefined => {
+  const value = fieldOf(node, field);
+  return typeof value === "number" ? value : undefined;
+};
+
+const stringField = (node: MarkdownNode, field: string): string | undefined => {
+  const value = fieldOf(node, field);
+  return typeof value === "string" ? value : undefined;
+};
+
+// 見出しの末尾に付けた名前。属性（`{#step1 .class}`）と、MDX のコメント（`{/*step1*/}`）。
+type NamedHeading = { readonly text: string; readonly id: string | undefined };
+
+const MDX_COMMENT_OPEN = "/*";
+const MDX_COMMENT_CLOSE = "*/";
+
+/** 見出しの言葉（textOf の結果）から、末尾の名前を外す。名前が無ければ id は undefined。 */
+export const namedHeading = (written: string): NamedHeading => {
+  const trimmed = written.trim();
+  const open = trimmed.lastIndexOf("{");
+  if (!trimmed.endsWith("}") || open === -1) return { text: trimmed, id: undefined };
+  const inner = trimmed.slice(open + 1, -1).trim();
+  const before = trimmed.slice(0, open).trim();
+  if (inner.startsWith("#")) return { text: before, id: inner.slice(1).split(/\s/u)[0] };
+  const isComment = inner.startsWith(MDX_COMMENT_OPEN) && inner.endsWith(MDX_COMMENT_CLOSE);
+  return isComment ? { text: before, id: inner.slice(MDX_COMMENT_OPEN.length, -MDX_COMMENT_CLOSE.length).trim() } : { text: trimmed, id: undefined };
+};
+
+/** HTML の id・name 属性の値。属性の前は空白なので、data-id は数えない。 */
+const HTML_ID = /\s(?:id|name)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/giu;
+
+/** `<img …>`。引用符の中の `>`（title="2 > 1"）では閉じない。 */
+const IMG_TAG = /<img\b(?:"[^"]*"|'[^']*'|[^"'>])*>/giu;
+const ALT_ATTRIBUTE = /\salt\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))?/iu;
+
+/** 中の字が、字のまま見える範囲にならない節。リンクの字はリンクで（中の画像は読む）。 */
+const LINKS = new Set(["link", "linkReference"]);
+
+type Walk = {
+  readonly headings: MarkupHeading[];
+  readonly images: MarkupImage[];
+  readonly links: MarkupLink[];
+  readonly ids: Set<string>;
+  readonly texts: Span[];
+  /** 参照の定義（`[label]: url`）を名前ごとに。使われた定義だけが、読み手の押すリンクになる。 */
+  readonly definitions: Map<string, MarkupLink>;
+  /** 参照の形のリンクと画像が使った名前。 */
+  readonly referenced: Set<string>;
+};
+
+const plainText = (node: MarkdownNode, source: string): string => {
+  const parts: string[] = [];
+  eachPreOrder(node, (child) => {
+    const span = spanOf(child);
+    if ((child.type === "text" || child.type === "inlineCode") && span !== undefined) parts.push(source.slice(span.start, span.end));
+  });
+  return parts.join("");
+};
+
+/** ATX の見出しの閉じの `#`。 */
+const ATX_CLOSING = /\s#+\s*$/u;
+
+/** MDX のコメントの `*` を強調の印として外した後に残る `{/…/}` を外す。 */
+const withoutMdxComment = (text: string): string => {
+  const open = text.lastIndexOf("{/");
+  return text.endsWith("/}") && open !== -1 ? text.slice(0, open).trimEnd() : text;
+};
+
+const firstLineOf = (text: string): string => text.split("\n", 1)[0] ?? "";
+
+const readHeading = (node: MarkdownNode, span: Span, source: string, walk: Walk): void => {
+  // 名前は書いたままの行から読む。MDX のコメントの `*` は、解析すると強調の印になって消える。
+  const { id } = namedHeading(firstLineOf(source.slice(span.start, span.end)).replace(ATX_CLOSING, ""));
+  if (id !== undefined && id !== "") walk.ids.add(id);
+  // ATX（行頭が #）なら閉じの # も外す。`## Install ## {#install}` の言葉は「Install」。
+  const read = source.startsWith("#", span.start) ? atxHeadingText : headingText;
+  const text = withoutMdxComment(read(plainText(node, source)));
+  walk.headings.push({ depth: numberField(node, "depth") ?? 1, text, start: span.start, end: span.end });
+};
+
+/** 属性の値の文字参照のうち、名前に書かれるもの。ほかの名前の参照は id にまず現れない。 */
+const NAMED_REFERENCES: Readonly<Record<string, string>> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+const CHARACTER_REFERENCE = /&(?:#(\d+)|#x([\da-f]+)|([a-z]+));/giu;
+
+const HEX = 16;
+
+/** Unicode の字の番号の上限。 */
+const LAST_CODE_POINT = 0x10ffff;
+
+/** 番号の字。字の番号でなければ（&#999999999;）undefined で、参照は書いたまま残す。 */
+const characterOf = (codePoint: number): string | undefined =>
+  Number.isSafeInteger(codePoint) && codePoint > 0 && codePoint <= LAST_CODE_POINT ? String.fromCodePoint(codePoint) : undefined;
+
+/** 属性の値の文字参照（&amp;、&#38;、&#x26;）を字に戻す。ブラウザが名前として読むのは戻した字。 */
+export const decodedAttribute = (value: string): string =>
+  value.replace(CHARACTER_REFERENCE, (whole: string, decimal?: string, hex?: string, name?: string) => {
+    if (decimal !== undefined) return characterOf(Number(decimal)) ?? whole;
+    if (hex !== undefined) return characterOf(Number.parseInt(hex, HEX)) ?? whole;
+    return NAMED_REFERENCES[(name ?? "").toLowerCase()] ?? whole;
+  });
+
+/** HTML のコメント。中の要素は表示されない。 */
+const HTML_COMMENT = /<!--[\s\S]*?-->/gu;
+
+/** コメントを同じ長さの空白にする。位置は変えない。 */
+const withoutComments = (html: string): string => html.replace(HTML_COMMENT, (comment) => " ".repeat(comment.length));
+
+/** 中身が表示されない要素（`<script>`、`<style>`）で始まる HTML。中の `<img>` や id は字の並びで、ページの要素ではない。 */
+const SOURCE_ELEMENT = /^\s*<(?:script|style)\b/iu;
+
+const readHtml = (written: string, span: Span, walk: Walk): void => {
+  if (SOURCE_ELEMENT.test(written)) return;
+  const value = withoutComments(written);
+  [...value.matchAll(HTML_ID)].forEach((match) => walk.ids.add(decodedAttribute(match[1] ?? match[2] ?? match[3] ?? "")));
+  [...value.matchAll(IMG_TAG)].forEach((match) => {
+    const alt = ALT_ATTRIBUTE.exec(match[0]);
+    const start = span.start + match.index;
+    walk.images.push({ alt: alt === null ? undefined : (alt[1] ?? alt[2] ?? alt[3] ?? ""), start, end: start + match[0].length });
+  });
+};
+
+/** 同じ名前の定義が二つあれば、CommonMark は先のものを使う。後のものは使われない。 */
+const defineOnce = (walk: Walk, name: string, link: MarkupLink): void => {
+  if (!walk.definitions.has(name)) walk.definitions.set(name, link);
+};
+
+/** リンクと参照の定義。定義は、使われたかを最後に見るので別に持つ。 */
+const readLink = (node: MarkdownNode, span: Span, walk: Walk): void => {
+  if (node.type === "link") walk.links.push({ destination: node.url ?? "", ...span });
+  else if (node.type === "definition") defineOnce(walk, node.identifier ?? "", { destination: node.url ?? "", ...span });
+  else if (node.type === "linkReference") walk.referenced.add(node.identifier ?? "");
+};
+
+const LINK_NODES = new Set(["link", "definition", "linkReference"]);
+
+const readNode = (node: MarkdownNode, span: Span, source: string, walk: Walk, inLink: boolean): void => {
+  if (node.type === "heading") readHeading(node, span, source, walk);
+  else if (node.type === "image" || node.type === "imageReference") walk.images.push({ alt: stringField(node, "alt") ?? "", ...span });
+  else if (LINK_NODES.has(node.type)) readLink(node, span, walk);
+  else if (node.type === "html") readHtml(node.value ?? "", span, walk);
+  else if (node.type === "text" && !inLink) walk.texts.push(span);
+};
+
+/** sorted（昇順・重ならない）のどれかの中で始まるか。記法の範囲が何千あっても、節ごとに全部をなめない。 */
+const startsInside = (span: Span, sorted: readonly Span[]): boolean => {
+  const region = sorted[firstEndingAfter(sorted, span.start)];
+  return region !== undefined && region.start <= span.start;
+};
+
+type Pending = { readonly node: MarkdownNode; readonly inLink: boolean };
+
+/**
+ * Markdown の記法の手がかりを集める。outside（メールの引用した返信と、MDX の import やテンプレートの記法）と、
+ * 引用（`>`）の中は読まない。返信と引用はほかの人の文書で、記法は読み手に見えない。
+ * GitHub の注記（`> [!NOTE]`）は書き手の言葉なので読む。本文の組み立て（document.ts）と同じ線引き。
+ */
+export const markdownMarkup = (root: MarkdownNode, source: string, outside: readonly Span[] = []): Markup => {
+  const walk: Walk = { headings: [], images: [], links: [], ids: new Set(), texts: [], definitions: new Map(), referenced: new Set() };
+  const alertOf = alertReader(source);
+  const skipped = mergeSpans(outside, false);
+  const pending: Pending[] = [{ node: root, inLink: false }];
+  while (pending.length > 0) {
+    const next = pending.pop();
+    if (next === undefined) break;
+    const { node, inLink } = next;
+    const span = spanOf(node);
+    if (span !== undefined && startsInside(span, skipped)) continue;
+    if (node.type === "blockquote" && alertOf(node) === undefined) continue;
+    if (span !== undefined) readNode(node, span, source, walk, inLink);
+    const childInLink = inLink || LINKS.has(node.type);
+    (node.children ?? []).toReversed().forEach((child) => pending.push({ node: child, inLink: childInLink }));
+  }
+  const { definitions, referenced, ...found } = walk;
+  const used = [...definitions].filter(([name]) => referenced.has(name)).map(([, link]) => link);
+  // 字の節の途中から始まる記法（`{{ … }}`）も、字のまま見える範囲から切り取る。
+  const texts = cutSpans(found.texts, skipped);
+  return { markdown: true, ...found, texts, links: [...found.links, ...used].toSorted((left, right) => left.start - right.start) };
+};
+
+/** Markdown でない文書。記法は無く、文書全体が字のまま見える。 */
+export const plainMarkup = (source: string): Markup => ({
+  markdown: false,
+  headings: [],
+  images: [],
+  links: [],
+  ids: new Set(),
+  texts: [{ start: 0, end: source.length }],
+});
+
+const built = new WeakMap<MarkdownNode, Markup>();
+
+/** 文書の記法を、文書ごとに一度だけ作る。root は文書を解析した木で、文書ごとに一つ。 */
+export const documentMarkup = (root: MarkdownNode, source: string, markdown: boolean, outside: readonly Span[]): Markup => {
+  const cached = built.get(root);
+  if (cached !== undefined) return cached;
+  const markup = markdown ? markdownMarkup(root, source, outside) : plainMarkup(source);
+  built.set(root, markup);
+  return markup;
+};

package/src/mask.ts

@@ -19,12 +19,12 @@ const blankOut = (text: string): string => text.replace(/[^\n]/gu, (char) => " "
 
 export const maskSpans = (source: string, spans: readonly Span[]): string => {
   const merged = mergeSpans(spans, true);
-  const { parts, cursor } = merged.reduce<{ parts: string[]; cursor: number }>(
-    (acc, span) => ({
-      parts: [...acc.parts, source.slice(acc.cursor, span.start), blankOut(source.slice(span.start, span.end))],
-      cursor: span.end,
-    }),
-    { parts: [], cursor: 0 },
-  );
-  return [...parts, source.slice(cursor)].join("");
+  // 部品は配列に足していく。範囲ごとに配列を作り直すと、範囲が何万もある文書で二乗に遅くなる。
+  const parts: string[] = [];
+  const cursor = merged.reduce((at, span) => {
+    parts.push(source.slice(at, span.start), blankOut(source.slice(span.start, span.end)));
+    return span.end;
+  }, 0);
+  parts.push(source.slice(cursor));
+  return parts.join("");
 };

package/src/name-variants.ts

@@ -0,0 +1,217 @@
+import type { Token } from "./plugin.ts";
+
+// 同じ名前（人・会社・製品）を、文書の中で少しだけ違う形に書いた所。どの形が正しいかは決めず、少ないほうを指す。
+// 三通りで同じ名前と見る。書き方の違いだけ（GitHub と Github、Mac OS と macOS）、読みが同じ（山田太郎 と 山田太朗）、
+// 英字の一字違い（Microsoft と Microsft）。一字違いは別の名前でもありうるので、多いほうが二度以上、少ないほうが一度だけのときに限る。
+
+/** words は名前の語（記号を除く）。読みが同じ二つの名前が、どの語で違うかを見るため。 */
+export type NameMention = { readonly surface: string; readonly offset: number; readonly reading: string | undefined; readonly words: readonly string[] };
+
+export type NameVariant = { readonly mention: NameMention; readonly usual: string; readonly kind: "spelling" | "reading" | "near" };
+
+const NAME = "PROPN";
+/**
+ * 名前の語のあいだに挟まってよい記号（AT&T、Rolls-Royce、ジョン・スミス）。読点は挟まない。
+ * 並べた名前（Zeebrugge, Kerk、Cook, Lisa）を一つの名前にしてしまう。
+ */
+const JOINERS: ReadonlySet<string> = new Set(["&", "-", "・"]);
+const LETTER = /\p{L}/u;
+
+/** 名前の語。字を含むもの。記号だけの語（wiki の '' ）を固有名詞と読む解析器がある。 */
+const isName = (token: Token | undefined): boolean => token?.pos === NAME && LETTER.test(token.surface);
+
+/** 固有名詞の続き。記号一つを挟んで固有名詞が続けば、一つの名前。 */
+const runsOf = (tokens: readonly Token[]): Token[][] => {
+  const runs: Token[][] = [];
+  const current: Token[] = [];
+  const close = (): void => {
+    if (current.length > 0) runs.push(current.splice(0));
+  };
+  tokens.forEach((token, index) => {
+    const bridges = JOINERS.has(token.surface) && current.length > 0 && isName(tokens[index + 1]);
+    if (isName(token) || bridges) current.push(token);
+    else close();
+  });
+  close();
+  return runs;
+};
+
+const LOWER = /\p{Ll}/u;
+const UPPER = /\p{Lu}/u;
+const isUpperOnly = (text: string): boolean => UPPER.test(text) && !LOWER.test(text);
+/** 小文字の英字だけの語（the、issue）。日本語の解析器は英単語を固有名詞と読むので、ふつうの語と名前の区別がつかない。 */
+const LOWER_LATIN_ONLY = /^[a-z\s-]+$/u;
+/** 行末で切った語のハイフン（Internet-⏎Drafts）。空白をまとめると "Internet- Drafts" になる。 */
+const WRAPPED_HYPHEN = /-\s+/gu;
+/** 名前の前後に付いた引用の印（wiki の斜体 ''、Hbase'）。名前の一部ではない。 */
+const QUOTE_MARKS: ReadonlySet<string> = new Set(["'", "’", '"', "“", "”"]);
+
+const withoutEdgeQuotes = (text: string): string => {
+  const chars = [...text];
+  const start = chars.findIndex((char) => !QUOTE_MARKS.has(char));
+  const end = chars.findLastIndex((char) => !QUOTE_MARKS.has(char));
+  return start < 0 ? "" : chars.slice(start, end + 1).join("");
+};
+/**
+ * 名前として比べないもの。@ で始まる SNS のアカウント（@SpaceX は SpaceX の別の書き方ではない）と、一字の語を含むもの
+ * （Attachment S、Appendix B は札で、空白を詰めると Attachments と同じ形になる）。
+ */
+const NOT_COMPARED = /@|(?:^|\s)\p{L}(?:\s|$)/u;
+
+/**
+ * 文の語から、名前の現れ。surface は source の上の書いたまま（折り返しの空白は一つにまとめる）。
+ * 大文字だけの名前（ACME INC、NASA）は外す。契約書の署名欄や略語で、ふつうの書き方の別の形ではない。小文字の英字だけの語も外す。
+ */
+export const mentionsIn = (tokens: readonly Token[], source: string): NameMention[] =>
+  runsOf(tokens).flatMap((run) => {
+    const first = run[0];
+    const last = run.at(-1);
+    if (first === undefined || last === undefined) return [];
+    const written = source.slice(first.span.start, last.span.end).replaceAll(WRAPPED_HYPHEN, "-").replaceAll(/\s+/gu, " ");
+    const surface = withoutEdgeQuotes(written);
+    if (surface === "" || isUpperOnly(surface) || LOWER_LATIN_ONLY.test(surface) || NOT_COMPARED.test(surface)) return [];
+    const words = run.filter((token) => !JOINERS.has(token.surface));
+    const readings = words.map((token) => token.reading);
+    const reading = readings.every((value) => value !== undefined && value !== "") ? readings.join("") : undefined;
+    return [{ surface, offset: first.span.start, reading, words: words.map((token) => token.surface) }];
+  });
+
+/** 比べる形。幅（ＡＷＳ と AWS）、大文字小文字、空白と記号は名前を変えない。 */
+export const nameKey = (surface: string): string =>
+  surface
+    .normalize("NFKC")
+    .toLowerCase()
+    .replaceAll(/[\s\p{P}\p{S}]/gu, "");
+
+type Tally = { readonly surface: string; readonly first: NameMention; readonly count: number };
+
+const talliesOf = (mentions: readonly NameMention[]): Tally[] => {
+  const tallies = new Map<string, { surface: string; first: NameMention; count: number }>();
+  mentions.forEach((mention) => {
+    const tally = tallies.get(mention.surface);
+    if (tally === undefined) tallies.set(mention.surface, { surface: mention.surface, first: mention, count: 1 });
+    else tally.count += 1;
+  });
+  return [...tallies.values()];
+};
+
+/** 多いほう。同数なら先に書いたほう。 */
+const usualOf = (group: readonly Tally[]): Tally | undefined =>
+  group.toSorted((left, right) => right.count - left.count || left.first.offset - right.first.offset)[0];
+
+const groupBy = (tallies: readonly Tally[], keysOf: (tally: Tally) => readonly string[]): Tally[][] => {
+  const groups = new Map<string, Tally[]>();
+  tallies.forEach((tally) =>
+    keysOf(tally).forEach((key) => {
+      const group = groups.get(key);
+      if (group === undefined) groups.set(key, [tally]);
+      else group.push(tally);
+    }),
+  );
+  return [...groups.values()].filter((group) => group.length > 1);
+};
+
+/**
+ * 組の中で、それぞれの書き方を、同じ名前と言える相手（alike）のうち多いほうと比べる。組全体で一番多いものとだけ比べると、
+ * 同じ読みの別の名前（山田太郎 と 矢間田多労）が多ければ、本当の書き分け（山田太朗）が隠れる。
+ */
+const variantsIn = (groups: readonly Tally[][], kind: NameVariant["kind"], alike: (tally: Tally, other: Tally) => boolean = () => true): NameVariant[] =>
+  groups.flatMap((group) =>
+    group.flatMap((tally) => {
+      const usual = usualOf([tally, ...group.filter((other) => other !== tally && alike(tally, other))]);
+      return usual === undefined || usual === tally ? [] : [{ mention: tally.first, usual: usual.surface, kind }];
+    }),
+  );
+
+/**
+ * 読みが同じでも、別の名前のことが多い（毅 と 敦士、札幌 と サッポロ）。語が二つ以上あり、違うのが一語だけのとき
+ * （山田太郎 と 山田太朗）に限る。
+ */
+const oneWordApart = (tally: Tally, usual: Tally): boolean => {
+  const words = tally.first.words;
+  const others = usual.first.words;
+  return words.length >= 2 && words.length === others.length && words.filter((word, index) => word !== others[index]).length === 1;
+};
+
+/** 一字違いを比べる語の長さ。短い語（Iran と Iraq、RET と REU、II と VI）は一字違いでも別の語。 */
+const MIN_NEAR_LENGTH = 5;
+const LATIN_WORD = /^[a-z]+$/u;
+
+const wordsOf = (surface: string): string[] => surface.toLowerCase().split(/[\s-]+/u);
+
+/** 一字の置き換えか、隣どうしの入れ替え（Microsfot）。 */
+const isSwapOrReplace = (left: string, right: string): boolean => {
+  const differ = [...left].flatMap((char, index) => (char === right.charAt(index) ? [] : [index]));
+  const [first, second] = differ;
+  if (differ.length === 1) return true;
+  return (
+    differ.length === 2 &&
+    first !== undefined &&
+    second === first + 1 &&
+    left.charAt(first) === right.charAt(second) &&
+    left.charAt(second) === right.charAt(first)
+  );
+};
+
+/**
+ * 語の中の一字の抜け。語の終わりの抜け（Service と Services、America と American）は語の形の違い、頭の抜け（State と XState）は
+ * 別の名前で、書き損じではない。
+ */
+const isInnerDrop = (longer: string, shorter: string): boolean =>
+  [...longer].some((_char, index) => index > 0 && index < longer.length - 1 && longer.slice(0, index) + longer.slice(index + 1) === shorter);
+
+/** 二つの語が一字違いか。英字だけの、長さ 5 以上の語で。 */
+export const isNearWord = (left: string, right: string): boolean => {
+  if (left === right || !LATIN_WORD.test(left) || !LATIN_WORD.test(right) || Math.min(left.length, right.length) < MIN_NEAR_LENGTH) return false;
+  if (left.length === right.length) return isSwapOrReplace(left, right);
+  if (left.length === right.length + 1) return isInnerDrop(left, right);
+  return right.length === left.length + 1 && isInnerDrop(right, left);
+};
+
+/** 語の一つを伏せた形。ほかの語が同じ二つの名前は、同じ形を一つ持つ。 */
+const maskedKeys = (tally: Tally): string[] => {
+  const words = wordsOf(tally.surface);
+  return words.map((_word, index) => words.map((word, at) => (at === index ? "*" : word)).join(" "));
+};
+
+const differingWords = (left: Tally, right: Tally): readonly [string, string] | undefined => {
+  const leftWords = wordsOf(left.surface);
+  const rightWords = wordsOf(right.surface);
+  const at = leftWords.findIndex((word, index) => word !== rightWords[index]);
+  const [leftWord, rightWord] = [leftWords[at], rightWords[at]];
+  return leftWords.length === rightWords.length && leftWord !== undefined && rightWord !== undefined ? [leftWord, rightWord] : undefined;
+};
+
+/** 一語だけが一字違いで、相手が二度以上、こちらが一度だけ。 */
+const isSlipOf = (tally: Tally, other: Tally): boolean => {
+  if (tally.count !== 1 || other.count < 2) return false;
+  const words = differingWords(tally, other);
+  return words !== undefined && isNearWord(...words);
+};
+
+const nearVariants = (tallies: readonly Tally[]): NameVariant[] => variantsIn(groupBy(tallies, maskedKeys), "near", isSlipOf);
+
+/** 同じ名前の、少ないほうの書き方。書き方ごとに最初の現れを一つ。同じ現れを二つの見方が言えば、先の見方だけ。 */
+export const nameVariants = (mentions: readonly NameMention[]): NameVariant[] => {
+  const tallies = talliesOf(mentions);
+  const found = [
+    ...variantsIn(
+      groupBy(tallies, (tally) => [nameKey(tally.surface)]),
+      "spelling",
+    ),
+    ...variantsIn(
+      groupBy(tallies, (tally) => (tally.first.reading === undefined ? [] : [tally.first.reading])),
+      "reading",
+      oneWordApart,
+    ),
+    ...nearVariants(tallies),
+  ];
+  const reported = new Set<string>();
+  return found
+    .filter((variant) => {
+      if (reported.has(variant.mention.surface)) return false;
+      reported.add(variant.mention.surface);
+      return true;
+    })
+    .toSorted((left, right) => left.mention.offset - right.mention.offset);
+};

package/src/node-version.ts

@@ -0,0 +1,22 @@
+// bin/chaff.js loads this before the CLI, on whatever Node.js the person has. Keep it free of imports and of syntax
+// that old releases cannot parse (`??`, `?.`): running there is its whole job.
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** The lowest major version an engines range such as ">=24" names, or undefined for a range of another shape. */
+export const requiredMajorOf = (range: unknown): number | undefined => {
+  const match = /^\s*>=\s*v?(\d+)/u.exec(String(range));
+  return match === null ? undefined : Number(match[1]);
+};
+
+const isJapaneseLocale = (env: Env): boolean => /^ja/iu.test(env["LC_ALL"] || env["LC_MESSAGES"] || env["LANG"] || "");
+
+/** What to print before stopping when this Node.js is older than the engines range; undefined when it is new enough. */
+export const tooOldMessage = (version: string, range: unknown, env: Env): string | undefined => {
+  const required = requiredMajorOf(range);
+  const major = Number(version.split(".")[0]);
+  if (required === undefined || Number.isNaN(major) || major >= required) return undefined;
+  return isJapaneseLocale(env)
+    ? `chaff は Node.js ${String(required)} 以上で動きます。いまは v${version} です。https://nodejs.org/ja から LTS を入れてください。`
+    : `chaff needs Node.js ${String(required)} or later. This is v${version}. Install the LTS from https://nodejs.org/en`;
+};

package/src/not-run.ts

@@ -0,0 +1,16 @@
+import type { Skipped } from "./run.ts";
+
+/** A rule someone asked about that did not run in this check, with why, and whether --experimental would run it. */
+export type NotRun = { readonly rule: string; readonly why: string; readonly needsExperimental: boolean };
+
+/**
+ * Pure: of the rules named in `ruleIds`, those this check skipped. A command that looks a rule's findings up (feedback,
+ * suppressions) says this instead of "none": no findings from a rule that did not run is not "checked and fine".
+ * --experimental is suggested only where it is the reason, not for a rule chaff.yaml or the genre turned off.
+ */
+export const notRunAmong = (ruleIds: readonly string[], skipped: readonly Skipped[]): NotRun[] => {
+  const asked = new Set(ruleIds);
+  return skipped
+    .filter((entry) => asked.has(entry.rule))
+    .map((entry) => ({ rule: entry.rule, why: entry.why, needsExperimental: entry.offUntilExperimental === true }));
+};