chaffjs 0.19.0 → 0.21.0

package/src/detectors/clause-shape.ts

@@ -0,0 +1,199 @@
+import type { Detector, DetectorOptions, Finding, Lexicon, ProseDocument, Sentence, Token } from "../plugin.ts";
+import { isWithinAny, quotedIn } from "../quoted-span.ts";
+
+// The shape of a clause read from its words: how it ends, a paired word left alone, an adverb that needs a
+// negation, a particle used where another one belongs. Every word comes from a lexicon; this file knows parts of speech.
+
+const findingAt = (sentence: Sentence, offset: number, values: Readonly<Record<string, string | number>>): Finding => ({
+  rule: "",
+  severity: "info",
+  line: 0,
+  column: 0,
+  quote: sentence.text.trim(),
+  values: { ...values, offset },
+});
+
+const patternsOf = (lexicon: Lexicon | undefined, group?: string): ReadonlySet<string> =>
+  new Set((lexicon ?? []).filter((entry) => group === undefined || entry.group === group).map((entry) => entry.pattern));
+
+const isSpace = (token: Token | undefined): boolean => token !== undefined && token.surface.trim() === "";
+
+/** The tokens of a sentence outside anything quoted in 「」『』, with their index in the sentence. */
+const ownTokens = (sentence: Sentence): { readonly token: Token; readonly at: number }[] => {
+  const quoted = quotedIn(sentence);
+  return (sentence.tokens ?? []).flatMap((token, at) => (isWithinAny(quoted, token.span) ? [] : [{ token, at }]));
+};
+
+const wordOf = (token: Token): string => token.lemma ?? token.surface;
+
+const isListed = (words: ReadonlySet<string>, token: Token | undefined): boolean =>
+  token !== undefined && (words.has(token.surface) || words.has(wordOf(token)));
+
+// --- ending-run: sentences in a row that end with the same words ---------------------------------------------
+
+const TRAILING_POS: ReadonlySet<string> = new Set(["PUNCT", "SYM"]);
+const TAIL_POS: ReadonlySet<string> = new Set(["AUX", "PART"]);
+const VERBAL_POS: ReadonlySet<string> = new Set(["VERB"]);
+
+/**
+ * How a sentence ends: its closing auxiliaries, and the verb before them as written (しました, あります, 思います).
+ * A noun before them is left out, so 必要です and 重要です end the same way. No auxiliary, no ending to compare.
+ */
+export const endingOf = (sentence: Sentence): string | undefined => {
+  const tokens = (sentence.tokens ?? []).filter((token) => !isSpace(token));
+  const last = tokens.findLastIndex((token) => !TRAILING_POS.has(token.pos));
+  const head = tokens.slice(0, last + 1).findLastIndex((token) => !TAIL_POS.has(token.pos));
+  if (head === last) return undefined;
+  const headToken = tokens[head];
+  const tail = tokens.slice(head + 1, last + 1).map((token) => token.surface);
+  return [headToken !== undefined && VERBAL_POS.has(headToken.pos) ? headToken.surface : "", ...tail].join("");
+};
+
+type Ended = { readonly sentence: Sentence; readonly ending: string | undefined };
+
+/** Runs of consecutive sentences with the same ending. A sentence with no ending to compare closes a run. */
+export const endingRuns = (sentences: readonly Sentence[]): Ended[][] =>
+  sentences
+    .map((sentence) => ({ sentence, ending: endingOf(sentence) }))
+    .reduce<Ended[][]>((runs, ended) => {
+      const last = runs.at(-1) ?? [];
+      const continues = ended.ending !== undefined && last[0]?.ending === ended.ending;
+      return continues ? [...runs.slice(0, -1), [...last, ended]] : [...runs, [ended]];
+    }, [])
+    .filter((run) => run[0]?.ending !== undefined);
+
+const runFinding = (run: readonly Ended[], limit: number): Finding => {
+  const first = run[0];
+  return {
+    rule: "",
+    severity: "info",
+    line: 0,
+    column: 0,
+    quote: run.map(({ sentence }) => sentence.text.trim()).join(""),
+    values: { word: first?.ending ?? "", count: run.length, limit, offset: first?.sentence.span.start ?? 0 },
+  };
+};
+
+/** More than limit sentences in a row within one paragraph that end with the same words. */
+export const endingRun: Detector = (doc, options): Finding[] =>
+  doc.paragraphs.flatMap((paragraph) =>
+    endingRuns(paragraph.sentences)
+      .filter((run) => run.length > options.limit)
+      .map((run) => runFinding(run, options.limit)),
+  );
+
+// --- unpaired-parallel: a word that lists by pairs (〜たり) used once, followed by another clause -----------------
+
+const CONTENT_POS: ReadonlySet<string> = new Set(["VERB", "ADJ", "NOUN", "PROPN"]);
+
+const nextWord = (tokens: readonly Token[], at: number): Token | undefined => tokens.slice(at + 1).find((token) => !isSpace(token));
+
+/**
+ * The marker is left alone when the sentence holds it once and what follows starts a new clause: a comma,
+ * or a content word other than the lexicon's closer (〜たり、映画を見る / 〜たり見る). 〜たりする and 〜たりもする are whole.
+ */
+const leftAlone = (tokens: readonly Token[], at: number, closers: ReadonlySet<string>, commas: ReadonlySet<string>): boolean => {
+  const next = nextWord(tokens, at);
+  if (next === undefined) return false;
+  if (commas.has(next.surface)) return true;
+  return CONTENT_POS.has(next.pos) && !isListed(closers, next);
+};
+
+const CONJUNCTION = "CCONJ";
+
+const markersIn = (sentence: Sentence, markers: ReadonlySet<string>): { readonly token: Token; readonly at: number }[] =>
+  ownTokens(sentence).filter(({ token }) => token.pos === CONJUNCTION && markers.has(token.surface));
+
+/** A sentence that uses the lexicon's paired marker once and goes on without its partner. */
+export const unpairedParallel: Detector = (doc, options): Finding[] => {
+  const markers = patternsOf(options.lexicon, "marker");
+  const closers = patternsOf(options.lexicon, "closer");
+  const commas = patternsOf(options.lexicon, "comma");
+  return doc.sentences.flatMap((sentence) => {
+    const found = markersIn(sentence, markers);
+    const only = found.length === 1 ? found[0] : undefined;
+    if (only === undefined || !leftAlone(sentence.tokens ?? [], only.at, closers, commas)) return [];
+    return [findingAt(sentence, only.token.span.start, { word: only.token.surface })];
+  });
+};
+
+// --- adverb-polarity: an adverb that wants a negation, in a sentence that has none ------------------------------
+
+type Negations = { readonly words: ReadonlySet<string>; readonly prefixes: readonly string[] };
+
+const negationsOf = (lexicon: Lexicon | undefined): Negations => ({
+  words: new Set((lexicon ?? []).filter((entry) => entry.group === undefined).map((entry) => entry.pattern)),
+  prefixes: [...patternsOf(lexicon, "prefix")],
+});
+
+/** A negating word (ない, 違う) or a word opening with a negating prefix (不十分, 無理). */
+const isNegation = (token: Token, negations: Negations): boolean =>
+  isListed(negations.words, token) || negations.prefixes.some((prefix) => token.surface.length > prefix.length && token.surface.startsWith(prefix));
+
+type Placed = { readonly token: Token; readonly at: number };
+
+/** A negation of the writer's own after the adverb; one inside a quotation does not answer it. */
+const hasNegation = (own: readonly Placed[], from: number, negations: Negations): boolean =>
+  own.some(({ token, at }) => at > from && isNegation(token, negations));
+
+/** Each of the lexicon's adverbs (全然, 決して) with no word of the negation list after it in its sentence. */
+export const adverbPolarity: Detector = (doc, options): Finding[] => {
+  const adverbs = patternsOf(options.lexicon);
+  const negations = negationsOf(doc.lexicons["negation-word"]);
+  return doc.sentences.flatMap((sentence) => {
+    const own = ownTokens(sentence);
+    return own
+      .filter(({ token, at }) => adverbs.has(token.surface) && !hasNegation(own, at, negations))
+      .map(({ token }) => findingAt(sentence, token.span.start, { word: token.surface }));
+  });
+};
+
+// --- origin-particle: a comparison particle (より) used for "from" -------------------------------------------------
+
+/** Adverbs (順次) and punctuation (本日より、発送) stand between the particle and its head. */
+const SKIPPED_POS: ReadonlySet<string> = new Set(["ADV", "PUNCT"]);
+const PARTICLE = "ADP";
+const NOMINAL_POS: ReadonlySet<string> = new Set(["NOUN", "PROPN"]);
+
+/** The first word after the particle, past adverbs (順次) and a bound honorific prefix (ご連絡). */
+const headAfter = (tokens: readonly Token[], at: number): number =>
+  tokens.findIndex((token, index) => index > at && !isSpace(token) && !SKIPPED_POS.has(token.pos) && token.features?.["Bound"] !== "Yes");
+
+/**
+ * The head names a start or a sending (開始, 参る, 連絡). A noun head must be the action itself: followed by an object
+ * marker or a light verb (受付を開始, 開始します), not a noun being compared (昨年より販売が増えた).
+ */
+const isOriginHead = (tokens: readonly Token[], head: number, heads: ReadonlySet<string>, objectMarkers: ReadonlySet<string>): boolean => {
+  const token = tokens[head];
+  if (token === undefined || !isListed(heads, token)) return false;
+  if (!NOMINAL_POS.has(token.pos)) return true;
+  const next = nextWord(tokens, head);
+  return next !== undefined && (objectMarkers.has(next.surface) || next.features?.["VerbType"] === "Light");
+};
+
+type ParticleWords = { readonly particles: ReadonlySet<string>; readonly heads: ReadonlySet<string>; readonly objectMarkers: ReadonlySet<string> };
+
+const originsIn = (sentence: Sentence, words: ParticleWords): Token[] => {
+  const tokens = sentence.tokens ?? [];
+  return ownTokens(sentence)
+    .filter(
+      ({ token, at }) =>
+        token.pos === PARTICLE && words.particles.has(token.surface) && isOriginHead(tokens, headAfter(tokens, at), words.heads, words.objectMarkers),
+    )
+    .map(({ token }) => token);
+};
+
+const particleWords = (doc: ProseDocument, options: DetectorOptions): ParticleWords => ({
+  particles: patternsOf(options.lexicon),
+  heads: patternsOf(doc.lexicons["origin-head"], "head"),
+  objectMarkers: patternsOf(doc.lexicons["origin-head"], "object"),
+});
+
+/** The lexicon's particle where it marks a starting point (4月1日より開始), which the lexicon's rewrite says instead. */
+export const originParticle: Detector = (doc, options): Finding[] => {
+  const words = particleWords(doc, options);
+  const rewrites = new Map((options.lexicon ?? []).map((entry) => [entry.pattern, entry.rewrite ?? ""]));
+  return doc.sentences.flatMap((sentence) =>
+    originsIn(sentence, words).map((token) => findingAt(sentence, token.span.start, { word: token.surface, suggestion: rewrites.get(token.surface) ?? "" })),
+  );
+};

package/src/detectors/code-fences.ts

@@ -0,0 +1,113 @@
+// Fenced code blocks (``` or ~~~) and inline code spans of a Markdown source. Pure. A fence's language is the first word
+// of its info string (```bash, ```{r}); a fence inside a blockquote is someone else's and is not read.
+import { parse } from "../markdown-read.ts";
+import { spanOf } from "../markdown-node.ts";
+import { eachPreOrder } from "../tree-walk.ts";
+
+export type CodeFence = {
+  /** Where the opening fence line starts. */
+  readonly start: number;
+  /** The first word of the info string, lower-cased; "" when the fence names none. */
+  readonly language: string;
+  /** The lines between the fences. */
+  readonly lines: readonly string[];
+  /** Where the block ends: the end of the closing fence line, or of the document. */
+  readonly end: number;
+};
+
+export type CodeSpan = { readonly start: number; readonly text: string };
+
+const MIN_FENCE = 3;
+
+type Opening = { readonly mark: string; readonly length: number };
+
+/** The fence a code block's first line opens, with its info string; undefined for an indented block, which has none. */
+export const fenceOf = (line: string): { readonly fence: Opening; readonly info: string } | undefined => {
+  const mark = line.charAt(0);
+  if (mark !== "`" && mark !== "~") return undefined;
+  const length = [...line].findIndex((char) => char !== mark);
+  const run = length === -1 ? line.length : length;
+  if (run < MIN_FENCE) return undefined;
+  const info = line.slice(run).trim();
+  // A backtick fence's info string has no backtick: ```js``` on one line is an inline span.
+  return mark === "`" && info.includes("`") ? undefined : { fence: { mark, length: run }, info };
+};
+
+/** The language an info string names: its first word, without braces or a leading dot ({r}, {.python}). */
+export const languageOf = (info: string): string => {
+  const word = info.split(/\s/u)[0] ?? "";
+  const opened = word.startsWith("{") ? word.slice(1) : word;
+  const bare = opened.startsWith(".") ? opened.slice(1) : opened;
+  const cut = [...bare].findIndex((char) => char === "{" || char === "}" || char === ",");
+  return (cut === -1 ? bare : bare.slice(0, cut)).toLowerCase();
+};
+
+/** How many backticks run from `at`. */
+const runAt = (text: string, at: number): number => {
+  const state = { end: at };
+  while (text.charAt(state.end) === "`") state.end += 1;
+  return state.end - at;
+};
+
+/** The fences of the last source read: the three rules that read fences parse a document once. */
+const lastRead: { source: string | undefined; fences: readonly CodeFence[] } = { source: undefined, fences: [] };
+
+const isQuoted = (source: string, offset: number): boolean =>
+  source
+    .slice(source.lastIndexOf("\n", offset - 1) + 1, offset)
+    .trimStart()
+    .startsWith(">");
+
+/**
+ * Every fenced code block, in order, as the Markdown parser reads it: a fence in a list item is one, an indented code
+ * block (four spaces, no fence) is not, and an unclosed fence runs to the end. A fence inside a quotation is left out.
+ */
+export const codeFences = (source: string): readonly CodeFence[] => {
+  if (lastRead.source === source) return lastRead.fences;
+  const fences: CodeFence[] = [];
+  eachPreOrder(parse(source), (node) => {
+    const span = node.type === "code" ? spanOf(node) : undefined;
+    if (span === undefined || isQuoted(source, span.start)) return;
+    const lineEnd = source.indexOf("\n", span.start);
+    // A fenced block starts at its fence; an indented block starts at its indentation, which is no fence.
+    const opening = fenceOf(source.slice(span.start, lineEnd === -1 ? source.length : lineEnd).trimEnd());
+    if (opening === undefined) return;
+    fences.push({ start: span.start, language: languageOf(opening.info), lines: (node.value ?? "").split("\n"), end: span.end });
+  });
+  lastRead.source = source;
+  lastRead.fences = fences;
+  return fences;
+};
+
+/** Inline code spans in a stretch of text: a run of backticks closed by a run of the same length. */
+export const codeSpans = (text: string, offset = 0): CodeSpan[] => {
+  const spans: CodeSpan[] = [];
+  const state = { at: 0 };
+  while (state.at < text.length) {
+    const open = text.indexOf("`", state.at);
+    if (open === -1) break;
+    const length = runAt(text, open);
+    const fence = "`".repeat(length);
+    const close = findRun(text, fence, open + length);
+    if (close === -1) {
+      state.at = open + length;
+    } else {
+      spans.push({ start: offset + open, text: text.slice(open + length, close).trim() });
+      state.at = close + length;
+    }
+  }
+  return spans;
+};
+
+/** The next run of exactly this many backticks from `from`, or -1. */
+const findRun = (text: string, run: string, from: number): number => {
+  const state = { at: from };
+  while (state.at < text.length) {
+    const found = text.indexOf(run, state.at);
+    if (found === -1) return -1;
+    if (text.charAt(found + run.length) !== "`" && text.charAt(found - 1) !== "`") return found;
+    state.at = found + run.length;
+    while (text.charAt(state.at) === "`") state.at += 1;
+  }
+  return -1;
+};

package/src/detectors/cross-definitions.ts

@@ -0,0 +1,49 @@
+import type { CrossDetector, DocumentFinding, ProseDocument, StructureNode } from "../plugin.ts";
+import { inDocumentOrder } from "../structure/issues.ts";
+import { definitionsOutOfStep, type DefinitionOutOfStep, type WrittenDefinition } from "../structure/cross-definitions.ts";
+import { quoteAt } from "./structure-tree.ts";
+
+// cross-doc-duplicate-definition reads definitions as duplicate-definition does (the tree's definition nodes), and compares
+// what each file says after the term: 「X」とは、…をいう / "X" means ….
+
+/**
+ * A definition that stands alone: not one held within an article or section (scope local), and not the inline kind
+ * (以下「X」という, ("X")), whose meaning is written before the term rather than after it.
+ */
+const standsAlone = (node: StructureNode): boolean =>
+  node.kind === "definition" && node.attrs["scope"] !== "local" && node.attrs["placement"] !== "inline" && node.attrs["term"] !== undefined;
+
+/** The language's words of a definition (をいう, means): the definition-statement word list. */
+const statementWordsOf = (doc: ProseDocument): string[] => (doc.lexicons["definition-statement"] ?? []).map((entry) => entry.pattern);
+
+/**
+ * What the sentence says after the term, up to its end. Empty when the sentence has none of the words of a definition:
+ * 「『AI が書いた』とは言いません」 names the term without defining it.
+ */
+const bodyAfter = (doc: ProseDocument, node: StructureNode, statementWords: readonly string[]): string => {
+  const sentence = doc.sentences.find((candidate) => candidate.span.start <= node.span.start && node.span.start < candidate.span.end);
+  if (sentence === undefined || node.span.end > sentence.span.end) return "";
+  const text = doc.source.slice(sentence.span.start, sentence.span.end);
+  return statementWords.some((word) => text.includes(word)) ? doc.source.slice(node.span.end, sentence.span.end) : "";
+};
+
+const definitionsOf = (doc: ProseDocument, tree: StructureNode): WrittenDefinition[] => {
+  const statementWords = statementWordsOf(doc);
+  return inDocumentOrder(tree)
+    .filter(standsAlone)
+    .map((node) => ({ term: String(node.attrs["term"]), body: bodyAfter(doc, node, statementWords), offset: node.span.start }));
+};
+
+const findingOf = (byPath: ReadonlyMap<string, ProseDocument>, odd: DefinitionOutOfStep): DocumentFinding[] => {
+  const doc = byPath.get(odd.path);
+  if (doc === undefined) return [];
+  const values = { term: odd.definition.term, count: odd.files, example: odd.usual.path, offset: odd.definition.offset };
+  return [{ path: odd.path, finding: { rule: "", severity: "warning", line: 0, column: 0, quote: quoteAt(doc.source, odd.definition.offset), values } }];
+};
+
+/** A term defined in other words than in most files of the run that define it: reported in the files of the fewer wording. */
+export const crossDocDuplicateDefinition: CrossDetector = (docs) => {
+  const files = docs.flatMap((doc) => (doc.structure === undefined ? [] : [{ path: doc.path, definitions: definitionsOf(doc, doc.structure) }]));
+  const byPath = new Map(docs.map((doc) => [doc.path, doc]));
+  return definitionsOutOfStep(files).flatMap((odd) => findingOf(byPath, odd));
+};

package/src/detectors/cross-facts.ts

@@ -0,0 +1,60 @@
+import type { CrossDetector, DocumentFinding, ProseDocument, Span, StructureNode } from "../plugin.ts";
+import { nameSpans } from "../compare/proper-nouns.ts";
+import { overlapsAny, spanIndex } from "../compare/spans.ts";
+import { factValues } from "../facts/fact-values.ts";
+import { labelledFacts, type Fact } from "../facts/labelled-facts.ts";
+import { tableFacts } from "../facts/table-facts.ts";
+import { emailSpans, versionSpans } from "../facts/address-values.ts";
+import { scopedFacts, type ScopedFact } from "../facts/fact-scope.ts";
+import { factsOutOfStep, writtenValue, type FactOutOfStep } from "../facts/cross-facts.ts";
+import { factWordsOf } from "./fact-consistency.ts";
+import { quoteAt } from "./structure-tree.ts";
+
+// cross-doc-fact-conflict reads facts as fact-conflict does (fact-consistency.ts), with two more kinds of value that a docs
+// site repeats from page to page: an email address and a version of three parts or more (2.4.1, v3).
+
+/** The proper nouns, and the addresses and versions, read as values named by what they are. A name inside an address is the address. */
+const namedValues = (doc: ProseDocument): Span[] => {
+  const extra = [...emailSpans(doc.source), ...versionSpans(doc.source)];
+  const taken = spanIndex(extra);
+  return [...nameSpans(doc).filter((span) => !overlapsAny(taken, span)), ...extra];
+};
+
+const summaryHeadings = (doc: ProseDocument): string[] => (doc.lexicons["summary-heading"] ?? []).map((entry) => entry.pattern);
+
+/** A colon right before the value, past emphasis marks: "Fee: $12", 「料金：1,200円」, "**Fee:** $12". */
+const COLON_BEFORE = /[:：][\s*_]*$/u;
+
+/**
+ * A fact written as an entry: "Item: value", or a table cell. A fact in a sentence (「指摘は 3 件です」) is about what that
+ * page is saying, and the same words on another page are often about something else; within one file, fact-conflict reads them.
+ */
+const isEntry = (source: string, fact: Fact): boolean => COLON_BEFORE.test(source.slice(source.lastIndexOf("\n", fact.value.start - 1) + 1, fact.value.start));
+
+const factsOf = (doc: ProseDocument, tree: StructureNode): ScopedFact[] => {
+  const values = factValues(tree, doc.source, namedValues(doc));
+  const entries = labelledFacts(doc.source, values, factWordsOf(doc)).filter((fact) => isEntry(doc.source, fact));
+  return scopedFacts([...entries, ...tableFacts(doc.source, values)], tree, doc.source, summaryHeadings(doc));
+};
+
+const findingOf = (byPath: ReadonlyMap<string, ProseDocument>, odd: FactOutOfStep): DocumentFinding[] => {
+  const doc = byPath.get(odd.path);
+  const usualDoc = byPath.get(odd.usual.path);
+  if (doc === undefined || usualDoc === undefined) return [];
+  const values = {
+    label: odd.fact.label,
+    value: writtenValue(doc.source, odd.fact.value),
+    other: writtenValue(usualDoc.source, odd.usual.value.value),
+    count: odd.files,
+    example: odd.usual.path,
+    offset: odd.fact.value.start,
+  };
+  return [{ path: odd.path, finding: { rule: "", severity: "warning", line: 0, column: 0, quote: quoteAt(doc.source, odd.fact.value.start), values } }];
+};
+
+/** A labelled fact given one value in some files of the run and another in the rest: reported in the files of the fewer value. */
+export const crossDocFactConflict: CrossDetector = (docs) => {
+  const files = docs.flatMap((doc) => (doc.structure === undefined ? [] : [{ path: doc.path, facts: factsOf(doc, doc.structure) }]));
+  const byPath = new Map(docs.map((doc) => [doc.path, doc]));
+  return factsOutOfStep(files).flatMap((odd) => findingOf(byPath, odd));
+};

package/src/detectors/cross-link.ts

@@ -0,0 +1,82 @@
+import { dirname, extname, join, normalize, sep } from "node:path";
+import type { CrossDetector, DocumentFinding, MarkupLink, ProseDocument } from "../plugin.ts";
+import { anchorsOf, reachesAnchor } from "./broken-link.ts";
+import { findingAt, markupOf, quoteOf } from "./markup-finding.ts";
+
+// A relative link from one file of a run to another (`[Fees](./pricing.md#monthly-fee)`) whose file is not in the run,
+// or whose heading is not in that file. A link to a URL, to a site-absolute path, or within the page is not this rule's.
+
+const SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+const MARKDOWN = [".md", ".markdown", ".mdx"];
+/** The page a folder link opens, as docs sites and code hosts serve it. */
+const FOLDER_PAGES = ["index.md", "index.mdx", "README.md"];
+
+/** A link's file part, resolved against the linking file's folder, and its fragment (without #). */
+export type LinkTarget = { readonly file: string; readonly folder: boolean; readonly fragment: string | undefined };
+
+const decoded = (text: string): string => {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+};
+
+/**
+ * Where a destination leads, from the file at `from`. undefined when it is not a relative link to a page: a URL, a path
+ * from the site's root, a link within the page, or a file that is not Markdown (an image, a script).
+ */
+export const linkTarget = (from: string, destination: string): LinkTarget | undefined => {
+  const written = destination.trim();
+  if (written === "" || written.startsWith("#") || written.startsWith("/") || written.startsWith("\\") || SCHEME.test(written)) return undefined;
+  const hashAt = written.indexOf("#");
+  const pathPart = decoded((hashAt === -1 ? written : written.slice(0, hashAt)).split("?")[0] ?? "");
+  const extension = extname(pathPart).toLowerCase();
+  if (extension !== "" && !MARKDOWN.includes(extension)) return undefined;
+  const fragment = hashAt === -1 ? undefined : decoded(written.slice(hashAt + 1));
+  return { file: normalize(join(dirname(from), pathPart)), folder: pathPart.endsWith("/") || pathPart === "", fragment };
+};
+
+/** The paths a target may name: itself with an extension, a page of that name, or the page a folder opens. */
+const candidatesOf = (target: LinkTarget): string[] => {
+  if (extname(target.file) !== "") return [target.file];
+  return [...MARKDOWN.map((extension) => `${target.file}${extension}`), ...FOLDER_PAGES.map((page) => join(target.file, page))];
+};
+
+/** The run's files by normalized path, and the folders they sit in. */
+type Run = { readonly byPath: ReadonlyMap<string, ProseDocument>; readonly folders: ReadonlySet<string> };
+
+const runOf = (docs: readonly ProseDocument[]): Run => ({
+  byPath: new Map(docs.map((doc) => [normalize(doc.path), doc])),
+  folders: new Set(docs.map((doc) => normalize(dirname(doc.path)))),
+});
+
+/** Whether a missing target is one the run would hold: in a folder the run's files are in, and not a folder the run has files under. */
+const runCovers = (target: LinkTarget, run: Run): boolean => {
+  if (target.folder || !run.folders.has(normalize(dirname(target.file)))) return false;
+  const under = `${target.file}${sep}`;
+  return ![...run.byPath.keys()].some((path) => path.startsWith(under));
+};
+
+const findingOf = (doc: ProseDocument, link: MarkupLink, variant: "file" | "anchor"): DocumentFinding => ({
+  path: doc.path,
+  finding: findingAt(doc, link, { link: quoteOf(doc.source, link), target: link.destination.trim() }, variant),
+});
+
+const brokenIn = (doc: ProseDocument, link: MarkupLink, run: Run): DocumentFinding | undefined => {
+  const target = linkTarget(doc.path, link.destination);
+  if (target === undefined) return undefined;
+  const found = candidatesOf(target)
+    .map((path) => run.byPath.get(path))
+    .find((candidate) => candidate !== undefined);
+  if (found === undefined) return runCovers(target, run) ? findingOf(doc, link, "file") : undefined;
+  const markup = markupOf(found);
+  if (target.fragment === undefined || target.fragment === "" || markup === undefined) return undefined;
+  return reachesAnchor(`#${target.fragment}`, anchorsOf(markup)) ? undefined : findingOf(doc, link, "anchor");
+};
+
+/** Relative links between the run's Markdown files that lead to a file the run does not have, or to a heading its file does not have. */
+export const crossDocBrokenLink: CrossDetector = (docs) => {
+  const run = runOf(docs);
+  return docs.flatMap((doc) => (markupOf(doc)?.links ?? []).flatMap((link) => brokenIn(doc, link, run) ?? []));
+};

package/src/detectors/cross-registry/cross-doc-broken-link.ts

@@ -0,0 +1,4 @@
+import type { CrossDetector } from "../../plugin.ts";
+import { crossDocBrokenLink } from "../cross-link.ts";
+
+export const detector: CrossDetector = crossDocBrokenLink;

package/src/detectors/cross-registry/cross-doc-duplicate-definition.ts

@@ -0,0 +1,4 @@
+import type { CrossDetector } from "../../plugin.ts";
+import { crossDocDuplicateDefinition } from "../cross-definitions.ts";
+
+export const detector: CrossDetector = crossDocDuplicateDefinition;

package/src/detectors/cross-registry/cross-doc-fact-conflict.ts

@@ -0,0 +1,4 @@
+import type { CrossDetector } from "../../plugin.ts";
+import { crossDocFactConflict } from "../cross-facts.ts";
+
+export const detector: CrossDetector = crossDocFactConflict;

package/src/detectors/cross-registry/cross-doc-term-variant.ts

@@ -0,0 +1,4 @@
+import type { CrossDetector } from "../../plugin.ts";
+import { crossDocTermVariant } from "../cross-variant.ts";
+
+export const detector: CrossDetector = crossDocTermVariant;

package/src/detectors/cross-variant.ts

@@ -0,0 +1,77 @@
+import type { CrossDetector, DocumentFinding, ProseDocument } from "../plugin.ts";
+import { oddSpellings, type DocumentWords, type KeyedWord, type OddSpelling } from "../cross-variants.ts";
+import { stemMorae, stemOf } from "../long-vowel.ts";
+import { DEFAULT_MIN_MORAE, distinctWordsOf, exemptStems, kanaWordsOf } from "./long-vowel.ts";
+import { spelledWordsIn, spellingsOf } from "./spelling-variety.ts";
+import { isWithinAny, quotedIn } from "../quoted-span.ts";
+
+// The words read for cross-doc-term-variant, each with the key both its spellings share. Three ways of spelling one word
+// that chaff already reads in one document: the final ー of a katakana word (katakana-long-vowel), British and American
+// spellings (spelling-consistency's word lists), and a Latin word written with and without a hyphen (e-mail, email).
+
+/**
+ * Katakana nouns as the language package split them, keyed by the word without its final ー. Short words keep their ー.
+ * A word in 「」 is named, not used (「サーバ」ではなく「サーバー」と書く), and does not count.
+ */
+const kanaWords = (doc: ProseDocument): KeyedWord[] => {
+  const exempt = exemptStems(distinctWordsOf(doc));
+  return doc.sentences.flatMap((sentence) => {
+    const quoted = quotedIn(sentence);
+    return kanaWordsOf(sentence, doc.names ?? [], exempt)
+      .filter((word) => stemMorae(word.surface) >= DEFAULT_MIN_MORAE)
+      .filter((word) => !isWithinAny(quoted, { start: word.offset, end: word.offset + word.surface.length }))
+      .map((word) => ({ key: `kana:${stemOf(word.surface)}`, form: word.surface, offset: word.offset }));
+  });
+};
+
+/** Words of the language's spelling lists (colour / color), keyed by the pair. */
+const listedWords = (doc: ProseDocument): KeyedWord[] => {
+  const spellings = spellingsOf(doc.lexicons);
+  return doc.sentences.flatMap((sentence) =>
+    spelledWordsIn(sentence, spellings).map((word) => {
+      const pair = [word.written.toLowerCase(), word.spelling.other.toLowerCase()].toSorted((left, right) => left.localeCompare(right, "en")).join("/");
+      return { key: `listed:${pair}`, form: word.written.toLowerCase(), offset: word.offset };
+    }),
+  );
+};
+
+const LATIN_WORD = /(?<![\p{L}\p{N}_-])\p{Script=Latin}+(?:-\p{Script=Latin}+)*(?![\p{L}\p{N}_-])/gu;
+const HYPHEN = "-";
+
+/** A Latin word's key: lower case, hyphens out. e-mail and Email share it with email. */
+const latinKey = (word: string): string => `latin:${word.toLowerCase().replaceAll(HYPHEN, "")}`;
+
+const latinWordsOf = (doc: ProseDocument): KeyedWord[] =>
+  doc.sentences.flatMap((sentence) =>
+    [...sentence.text.matchAll(LATIN_WORD)].map((match) => ({
+      key: latinKey(match[0]),
+      form: match[0].toLowerCase(),
+      offset: sentence.span.start + match.index,
+    })),
+  );
+
+/** The Latin words of every document whose key some document of the run writes with a hyphen. Other words are not variants. */
+const hyphenWords = (docs: readonly ProseDocument[]): readonly KeyedWord[][] => {
+  const words = docs.map(latinWordsOf);
+  const hyphenated = new Set(words.flat().flatMap((word) => (word.form.includes(HYPHEN) ? [word.key] : [])));
+  return words.map((ofDoc) => ofDoc.filter((word) => hyphenated.has(word.key)));
+};
+
+const quoteAt = (doc: ProseDocument, offset: number): string =>
+  doc.sentences.find((sentence) => sentence.span.start <= offset && offset < sentence.span.end)?.text.trim() ?? "";
+
+const findingOf = (byPath: ReadonlyMap<string, ProseDocument>, odd: OddSpelling): DocumentFinding[] => {
+  const doc = byPath.get(odd.path);
+  if (doc === undefined) return [];
+  const matched = doc.source.slice(odd.word.offset, odd.word.offset + odd.word.form.length);
+  const values = { matched, preferred: odd.usual, count: odd.files, other: odd.example, offset: odd.word.offset };
+  return [{ path: odd.path, finding: { rule: "", severity: "warning", line: 0, column: 0, quote: quoteAt(doc, odd.word.offset), values } }];
+};
+
+/** A word spelled one way in some files of the run and another way in the rest: reported in the files of the fewer way. */
+export const crossDocTermVariant: CrossDetector = (docs) => {
+  const latin = hyphenWords(docs);
+  const words: DocumentWords[] = docs.map((doc, index) => ({ path: doc.path, words: [...kanaWords(doc), ...listedWords(doc), ...(latin[index] ?? [])] }));
+  const byPath = new Map(docs.map((doc) => [doc.path, doc]));
+  return oddSpellings(words).flatMap((odd) => findingOf(byPath, odd));
+};

package/src/detectors/custom.ts

@@ -1,4 +1,4 @@
-import type { Detector, Finding, Sentence, Span } from "../plugin.ts";
+import type { Detector, DetectorOptions, Finding, Sentence, Span } from "../plugin.ts";
 import { occurrencesOutside } from "../orthography.ts";
 import { tokenRuns } from "../custom/token-pattern.ts";
 import { joinedView, type JoinedView } from "../joined-view.ts";
@@ -43,13 +43,21 @@ const withoutBreaks = (source: string, start: number, end: number, breaks: reado
     .toReversed()
     .reduce((text, span) => `${text.slice(0, span.start - start)}${text.slice(span.end - start)}`, source.slice(start, end));
 
+/** A words rule's own words, or its word list's in the document's language: each entry's pattern, and its rewrite as the spelling to use. */
+const pairsOf = (
+  spec: { readonly words: readonly { readonly avoid: string; readonly use: string }[] },
+  options: DetectorOptions,
+): readonly { avoid: string; use: string }[] =>
+  spec.words.length > 0 ? spec.words : (options.lexicon ?? []).map((entry) => ({ avoid: entry.pattern, use: entry.rewrite ?? "" }));
+
 /** words: each spelling to avoid, outside the spelling to use (「ユーザ」 inside 「ユーザー」 is not reported). */
 export const customWords: Detector = (doc, options): Finding[] => {
   const spec = options.custom;
   if (spec?.type !== "words") return [];
+  const pairs = pairsOf(spec, options).filter((pair) => pair.avoid !== "" && pair.avoid !== pair.use);
   return doc.sentences.flatMap((sentence) => {
     const view = readAsWritten(sentence);
-    return spec.words.flatMap((pair) =>
+    return pairs.flatMap((pair) =>
       occurrencesOutside(view.text, pair.avoid, pair.use).map((start) => findingOf(hitAt(sentence, view, start, start + pair.avoid.length, pair.use))),
     );
   });