chaffjs 0.27.1 → 0.29.0

package/src/detectors/term-extension.ts

@@ -0,0 +1,67 @@
+// A defined term written longer, with a word of its own definition added: 文書管理責任者 where 「管理責任者」とは、…文書の
+// 管理の責任者をいう is defined, the Application where the Pinecone Notes application (the "App") is. The reader cannot tell
+// whether the longer word is the defined thing or another one. Pure.
+import { escapeRegExp } from "../orthography.ts";
+
+/** The letters a Japanese compound is made of: a word written right before the term joins it into one longer word. */
+const COMPOUND_CHAR = /[\p{Script=Han}\p{Script=Katakana}ー]/u;
+const LATIN_LETTER = /\p{Script=Latin}/u;
+const UPPER_START = /^\p{Lu}/u;
+/** An added part shorter than this (書, the s of Services) is an ending or one character, not a word of the definition. */
+const MIN_ADDED = 2;
+/** A term shorter than this (提供, 登録) is an ordinary word that joins other words freely (情報提供, 利用登録). */
+const MIN_COMPOUND_TERM = 3;
+/** A plural ending (Boxes) is the same word, not a longer one. */
+const PLURAL = /^e?s$/u;
+
+/** The whole character that starts at, or ends right before, a position: both halves of 𠮷, not one. */
+const charFrom = (source: string, at: number): string => String.fromCodePoint(source.codePointAt(at) ?? 0);
+const charBefore = (source: string, at: number): string => {
+  const low = source.charCodeAt(at - 1);
+  const isLowHalf = low >= 0xdc00 && low <= 0xdfff && at >= 2;
+  return isLowHalf ? source.slice(at - 2, at) : source.charAt(at - 1);
+};
+
+/** Where the run of compound characters that ends at offset starts. */
+const runStart = (source: string, offset: number): number => {
+  let start = offset;
+  for (let char = charBefore(source, start); start > 0 && COMPOUND_CHAR.test(char); char = charBefore(source, start)) start -= char.length;
+  return start;
+};
+
+/** The endings of a run, longest first, that are long enough to be a word added to the term. */
+const endingsOf = (run: string): string[] => Array.from({ length: Math.max(0, run.length - MIN_ADDED + 1) }, (_, index) => run.slice(index));
+
+/**
+ * The term at offset written with more in front of it in one word (文書管理責任者), when what is in front ends with a word of
+ * the definition (文書). A word that points at one of the defined things (当該管理責任者) does not lengthen it, and a longer
+ * word the definition itself writes (東京都（以下「都」という。）) is the long name, not another form of the term.
+ */
+export const extendedBefore = (source: string, offset: number, term: string, definition: string, pointers: readonly string[] = []): string | undefined => {
+  if ([...term].length < MIN_COMPOUND_TERM || COMPOUND_CHAR.test(charFrom(source, offset + term.length))) return undefined;
+  const run = source.slice(runStart(source, offset), offset);
+  const added = endingsOf(run).find((part) => definition.includes(part) && !pointers.some((pointer) => part.startsWith(pointer)));
+  const written = added === undefined ? undefined : `${added}${term}`;
+  return written === undefined || definition.includes(written) ? undefined : written;
+};
+
+/**
+ * The capitalised term at offset written with more letters after it in one word (App → Application), when the definition
+ * has that longer word (the Pinecone Notes application). A plural or a word joined to letters before it is not one.
+ */
+export const extendedAfter = (source: string, offset: number, term: string, definition: string): string | undefined => {
+  if (!UPPER_START.test(term) || LATIN_LETTER.test(source.charAt(offset - 1))) return undefined;
+  let end = offset + term.length;
+  while (LATIN_LETTER.test(source.charAt(end))) end += 1;
+  const added = source.slice(offset + term.length, end);
+  if (added.length < MIN_ADDED || PLURAL.test(added)) return undefined;
+  const word = source.slice(offset, end);
+  return new RegExp(String.raw`(?<!\p{L})${escapeRegExp(word)}(?!\p{L})`, "iu").test(definition) ? word : undefined;
+};
+
+/** Each place the term is written exactly, in order. */
+export const exactOffsets = (text: string, start: number, term: string): number[] => {
+  const offsets: number[] = [];
+  for (let at = text.indexOf(term); at !== -1 && term !== ""; at = text.indexOf(term, at + term.length)) offsets.push(start + at);
+  return offsets;
+};

package/src/detectors/time-order.ts

@@ -0,0 +1,49 @@
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import type { StructureIssue } from "../structure/issues.ts";
+import { inDocumentOrder } from "../structure/issues.ts";
+import { clockTimes } from "../compare/clock-time.ts";
+import { secondsOf, type DateSpan, type Mark, type TimeSpan, type TimeWords } from "../structure/time-marks.ts";
+import { timeOrderBreaks } from "../structure/time-order.ts";
+import { arrivalsBeforeDeparture } from "../structure/leg-times.ts";
+import { quoteAt } from "./structure-tree.ts";
+
+// 一日の予定の時刻の順番（time-order）と、発より前の着（arrival-before-departure）。時刻は compare/clock-time.ts が読み、
+// 発着・翌日・時間帯の語は言語パッケージの語彙表（leg-mark、leg-column、day-shift-mark、time-zone、local-time-mark）から取る。
+
+const marksOf = (doc: ProseDocument, lexicon: string): Mark[] =>
+  (doc.lexicons[lexicon] ?? []).map((entry) => ({ pattern: entry.pattern, position: entry.position, group: entry.group }));
+
+const timeWordsOf = (doc: ProseDocument): TimeWords => ({
+  legs: marksOf(doc, "leg-mark"),
+  columns: marksOf(doc, "leg-column"),
+  dayShifts: marksOf(doc, "day-shift-mark"),
+  zones: [...marksOf(doc, "time-zone"), ...marksOf(doc, "local-time-mark").map((mark) => ({ ...mark, group: "local" }))],
+});
+
+const datesOf = (doc: ProseDocument): DateSpan[] =>
+  doc.structure === undefined
+    ? []
+    : inDocumentOrder(doc.structure).flatMap((node) =>
+        node.kind === "date" ? [{ start: node.span.start, end: node.span.end, value: String(node.attrs["value"]) }] : [],
+      );
+
+const timesOf = (text: string): TimeSpan[] => clockTimes(text).map((time) => ({ start: time.start, end: time.end, seconds: secondsOf(time.key) }));
+
+type Finder = (source: string, times: readonly TimeSpan[], dates: readonly DateSpan[], words: TimeWords) => StructureIssue[];
+
+/** 表と箇条書きを行のまま読むので、原文を渡す（doc.prose は表を覆う）。 */
+const detectorOf =
+  (rule: string, find: Finder): Detector =>
+  (doc): Finding[] =>
+    find(doc.source, timesOf(doc.source), datesOf(doc), timeWordsOf(doc)).map((issue) => ({
+      rule,
+      severity: "warning",
+      line: 0,
+      column: 0,
+      quote: quoteAt(doc.source, issue.offset),
+      values: { ...issue.values, offset: issue.offset },
+      ...("next" in issue.values ? { variant: "first" } : {}),
+    }));
+
+export const timeOrder: Detector = detectorOf("time-order", timeOrderBreaks);
+export const arrivalBeforeDeparture: Detector = detectorOf("arrival-before-departure", arrivalsBeforeDeparture);

package/src/detectors/ui-label.ts

@@ -0,0 +1,17 @@
+// ui-label-variant: one label on the screen written two ways in a manual (ui-labels.ts). The words a label is written with or
+// without come from the language's label-particle lexicon.
+import { quoteAt } from "./structure-tree.ts";
+import { labelsIn, labelVariants } from "../ui-labels.ts";
+import type { Detector, Finding } from "../plugin.ts";
+
+export const uiLabel: Detector = (doc): Finding[] => {
+  const particles = (doc.lexicons["label-particle"] ?? []).map((entry) => entry.pattern);
+  return labelVariants(labelsIn(doc.source, doc.prose ?? doc.source), particles).map(({ label, usual }) => ({
+    rule: "ui-label-variant",
+    severity: "info",
+    line: 0,
+    column: 0,
+    quote: quoteAt(doc.source, label.offset),
+    values: { written: label.surface, usual, offset: label.offset },
+  }));
+};

package/src/detectors/unbalanced-bracket.ts

@@ -4,6 +4,7 @@ import { escapeRegExp } from "../orthography.ts";
 import { quoteAround } from "./quote-around.ts";
 import { mergeSpans } from "../span-merge.ts";
 import { firstEndingAfter } from "../soft-break.ts";
+import { isLabelClose, isLabelInAside } from "./bracket-label.ts";
 
 /**
  * 括弧の組。どの言語でも同じ字の決まりなので、語彙表ではなくここに置く。family は形（丸・角）で、全角と半角は同じ形の別の幅。
@@ -48,31 +49,23 @@ export type BracketProblem = {
 type Open = { readonly bracket: Bracket; readonly offset: number };
 type Scan = { readonly open: Open[]; readonly problems: BracketProblem[] };
 
-/**
- * 丸括弧の閉じの前の、行の頭か空白・句読点の後ろに書いた短い印（「1)」「a)」「事例）」「※）」）と、数の後ろの閉じ（「事例2）及び事例3）」）。
- * 箇条の番号や見出しの印で、開きを持たない書き方。顔文字の「:)」も同じ形。印に使うのは丸括弧だけ。
- */
-const LABEL_BEFORE = /(?:^|[\s、。,;:：])[^\s()（）[\]［］「」『』]{1,3}[ \t\u3000]?$|[\d０-９]$/u;
-
-const isLabel = (text: string, bracket: Bracket, offset: number): boolean => {
-  if (bracket.family !== "round") return false;
-  const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
-  return LABEL_BEFORE.test(text.slice(lineStart, offset));
-};
-
 const unclosedOf = (entry: Open): BracketProblem => ({ kind: "unclosed", offset: entry.offset, mark: entry.bracket.open });
 
 const closeWith = (scan: Scan, text: string, bracket: Bracket, offset: number): void => {
   const at = scan.open.findLastIndex((entry) => entry.bracket.family === bracket.family);
+  const round = bracket.family === "round";
   if (at === -1) {
-    if (!isLabel(text, bracket, offset)) scan.problems.push({ kind: "unopened", offset, mark: bracket.close });
+    if (!(round && isLabelClose(text, offset))) scan.problems.push({ kind: "unopened", offset, mark: bracket.close });
     return;
   }
+  if (round && isLabelInAside(text, offset, scan.open.filter((entry) => entry.bracket.family === "round").length)) return;
   const opened = scan.open[at];
-  // 間に残った開きは、この閉じより先に閉じるはずだったもの。
+  // 間に残った開きは、この閉じより先に閉じるはずだったもの。ただし引用の閉じのすぐ前の開きは、括弧の字そのものを
+  // 引いたもの（法令の読替え「取締役（」とあるのは「清算人（」と）で、組を作らない。
   scan.open
     .splice(at)
     .slice(1)
+    .filter((inner) => !(QUOTATIONS.has(bracket.family) && inner.offset === offset - 1))
     .forEach((inner) => scan.problems.push(unclosedOf(inner)));
   if (opened !== undefined && opened.bracket !== bracket) scan.problems.push({ kind: "mismatch", offset, mark: bracket.close, partner: opened.bracket.open });
 };

package/src/detectors/undefined-call.ts

@@ -0,0 +1,19 @@
+// undefined-function-call: a function called in a code example that the page never defines, where the page documents
+// one whose name it extends (wrapText( on a page about wrap) (undefined-call.ts). The functions a programming language
+// provides come from the code-global lexicon.
+import { quoteAt } from "./structure-tree.ts";
+import { undefinedCalls } from "../undefined-call.ts";
+import type { Detector, Finding } from "../plugin.ts";
+
+export const undefinedCall: Detector = (doc): Finding[] => {
+  const headings = (doc.markup?.headings ?? []).map((heading) => heading.text);
+  const globals = (doc.lexicons["code-global"] ?? []).map((entry) => entry.pattern);
+  return undefinedCalls(doc.source, headings, globals).map((call) => ({
+    rule: "undefined-function-call",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAt(doc.source, call.offset),
+    values: { name: call.name, documented: call.documented, offset: call.offset },
+  }));
+};

package/src/detectors/undefined-term.ts

@@ -0,0 +1,103 @@
+// A term written as a defined term but defined nowhere: 本成果物 in a contract that defines 本業務 and 本契約 but no
+// 本成果物. The document's own prefix for its defined terms (本, 本件: the language package's defined-term-prefix list)
+// marks a word as one of its terms; a term with that prefix and no definition leaves the reader asking what it is.
+// Only the document's own references (本条, 本契約: self-reference-noun and document-kind) are left. Pure; the parts of
+// speech decide where a prefix is a prefix (本 in 本成果物) and not part of a word (本人, 本日).
+import { definedTerms } from "../structure/definition-use.ts";
+import { prefixGroupsOf, prefixVariants } from "../structure/term-prefix.ts";
+import { quoteAt } from "./structure-tree.ts";
+import type { Detector, Finding, ProseDocument, Token } from "../plugin.ts";
+
+export type UndefinedTerm = { readonly offset: number; readonly term: string };
+
+const NOUNS = new Set(["NOUN", "PROPN"]);
+const QUOTE_PAIRS = [
+  ["「", "」"],
+  ["『", "』"],
+  ['"', '"'],
+  ["“", "”"],
+] as const;
+
+const isNoun = (token: Token | undefined): token is Token => token !== undefined && NOUNS.has(token.pos);
+
+/** A defined term whose rest after the prefix is shorter than this (本人, 本日) is a word, not the document's way of naming terms. */
+const MIN_REST = 2;
+
+/** A prefix written right after a noun is inside a longer word, not a prefix. */
+const continuesWord = (before: Token | undefined, token: Token): boolean => isNoun(before) && before.span.end === token.span.start;
+
+/** The term a prefix token starts: the prefix and the nouns written right after it (本 成果 物). */
+const termAt = (source: string, tokens: readonly Token[], index: number): { readonly offset: number; readonly term: string } | undefined => {
+  const prefix = tokens[index];
+  if (prefix === undefined) return undefined;
+  const run = tokens.slice(index + 1);
+  const length = run.findIndex((token, at) => !isNoun(token) || token.span.start !== (run[at - 1] ?? prefix).span.end);
+  const last = run[(length === -1 ? run.length : length) - 1];
+  return last === undefined ? undefined : { offset: prefix.span.start, term: source.slice(prefix.span.start, last.span.end) };
+};
+
+/** What the decision needs from the document and its word lists. */
+export type TermWords = {
+  readonly prefixes: readonly string[];
+  readonly prefixGroups: readonly (readonly string[])[];
+  /** What the document calls itself and its parts after a prefix (本条, 本契約, 本利用規約); never one of its terms. */
+  readonly selfNouns: readonly string[];
+  /** The term is set in quotes somewhere (「本情報」): defined in a form the structure did not read, or named on purpose. */
+  readonly isQuoted: (term: string) => boolean;
+};
+
+/** The defined terms and their other-prefix forms (本件業務 for 本業務), which defined-term-form reads. */
+const knownForms = (defined: readonly string[], groups: TermWords["prefixGroups"]): string[] => [
+  ...defined,
+  ...defined.flatMap((term) => prefixVariants(term, groups)),
+];
+
+/**
+ * The first use of each term written with the document's prefix and defined nowhere, when the document defines at
+ * least one term with that prefix (else the prefix is not its way of naming terms). A use that starts with a known
+ * form (本サービス上 where 本サービス is defined) is that term.
+ */
+export const undefinedTerms = (source: string, sentences: readonly (readonly Token[])[], defined: readonly string[], words: TermWords): UndefinedTerm[] => {
+  const prefixes = words.prefixes.filter((prefix) => prefix !== "");
+  const prefixed = defined.filter((term) => prefixes.some((prefix) => term.startsWith(prefix) && Array.from(term.slice(prefix.length)).length >= MIN_REST));
+  if (prefixed.length === 0) return [];
+  const known = knownForms(defined, words.prefixGroups);
+  const isSelf = (term: string, prefix: string): boolean => {
+    const rest = term.slice(prefix.length);
+    return words.selfNouns.some((noun) => noun !== "" && (rest.startsWith(noun) || rest.endsWith(noun)));
+  };
+  const uses = sentences.flatMap((tokens) =>
+    tokens.flatMap((token, index) => {
+      if (!prefixes.includes(token.surface) || !isNoun(tokens[index + 1]) || continuesWord(tokens[index - 1], token)) return [];
+      const use = termAt(source, tokens, index);
+      if (use === undefined || isSelf(use.term, token.surface) || words.isQuoted(use.term)) return [];
+      if (known.some((form) => use.term.startsWith(form) || form.startsWith(use.term))) return [];
+      return [use];
+    }),
+  );
+  return uses.filter((use, index) => uses.findIndex((other) => other.term === use.term) === index);
+};
+
+const patternsOf = (doc: ProseDocument, lexicon: string): string[] => (doc.lexicons[lexicon] ?? []).map((entry) => entry.pattern);
+
+const findingOf = (doc: ProseDocument, use: UndefinedTerm): Finding => ({
+  rule: "undefined-term",
+  severity: "info",
+  line: 0,
+  column: 0,
+  quote: quoteAt(doc.source, use.offset),
+  values: { term: use.term, offset: use.offset },
+});
+
+export const undefinedTerm: Detector = (doc): Finding[] => {
+  if (doc.structure === undefined) return [];
+  const prefixEntries = doc.lexicons["defined-term-prefix"] ?? [];
+  const sentences = doc.sentences.map((sentence) => sentence.tokens ?? []);
+  const defined = definedTerms(doc.structure).map((term) => term.term);
+  return undefinedTerms(doc.source, sentences, defined, {
+    prefixes: prefixEntries.map((entry) => entry.pattern),
+    prefixGroups: prefixGroupsOf(prefixEntries),
+    selfNouns: [...patternsOf(doc, "self-reference-noun"), ...patternsOf(doc, "document-kind")],
+    isQuoted: (term) => QUOTE_PAIRS.some(([open, close]) => doc.source.includes(`${open}${term}${close}`)),
+  }).map((use) => findingOf(doc, use));
+};

package/src/detectors/unknown-word.ts

@@ -1,5 +1,5 @@
 import type { Detector, Finding, ProseDocument } from "../plugin.ts";
-import { isKnownWord, suggestionFor, wordsToCheck, type CheckedWord, type Speller } from "../spelling.ts";
+import { isKnownWord, isSplitWord, suggestionFor, wordsToCheck, type CheckedWord, type Speller } from "../spelling.ts";
 import { quoteAt } from "./structure-tree.ts";
 
 /** これより短い語は見ない。短い語は一字違いの語が多すぎて言い直しが決まらず（tost は test か toast か）、略した語（impl）も多い。 */
@@ -26,13 +26,13 @@ const usedOnce = (words: readonly CheckedWord[]): CheckedWord[] => {
 
 /**
  * 辞書に無い英語の語で、一字違いの辞書の語があるもの（recieve → receive）。辞書は adapter が持ち、無い言語では動かない。
- * 大文字を含む語（固有名詞・略語）、コード・URL の中、二度以上使う語、言い直しの無い語は言わない。
+ * 大文字を含む語（固有名詞・略語）、コード・URL の中、頭の字を分けた語の残り、二度以上使う語、言い直しの無い語は言わない。
  */
 export const unknownWord: Detector = (doc): Finding[] => {
   if (doc.dictionary === undefined) return [];
   const speller = spellerOf(doc, doc.dictionary());
   const known = new Set(patternsOf(doc, "known-misspelling"));
-  const words = wordsToCheck(doc.prose ?? doc.source, MIN_LENGTH, MAX_LENGTH);
+  const words = wordsToCheck(doc.prose ?? doc.source, MIN_LENGTH, MAX_LENGTH).filter(({ offset }) => !isSplitWord(doc.source, offset));
   const used = new Set(words.map(({ word }) => word).filter((word) => isKnownWord(word, speller)));
   return usedOnce(words).flatMap(({ offset, word }) => {
     if (known.has(word) || isKnownWord(word, speller)) return [];

package/src/detectors/vague-deadline.ts

@@ -68,12 +68,12 @@ const concreteIn = (lower: string, entry: string): boolean => {
   );
 };
 
-const statesConcrete = (text: Text, concrete: readonly string[]): boolean => {
+export const statesConcrete = (text: Text, concrete: readonly string[]): boolean => {
   const lower = text.text.toLowerCase();
   return concrete.some((entry) => concreteIn(lower, entry));
 };
 
-const grantsRight = (text: Text, permissions: readonly LexiconEntry[]): boolean => {
+export const grantsRight = (text: Text, permissions: readonly LexiconEntry[]): boolean => {
   const lower = text.text.toLowerCase();
   const ending = withoutEnding(lower);
   return permissions
@@ -86,7 +86,7 @@ const isInsideLonger = (hit: Hit, hits: readonly Hit[]): boolean =>
   hits.some((other) => other.word.length > hit.word.length && other.at <= hit.at && hit.at + hit.word.length <= other.at + other.word.length);
 
 /** The vague limits in one sentence, in order. Matching ignores case. */
-const vagueIn = (text: Text, vague: readonly string[]): VagueDeadline[] => {
+export const vagueIn = (text: Text, vague: readonly string[]): VagueDeadline[] => {
   const lower = text.text.toLowerCase();
   const hits = vague
     .filter((word) => word !== "")

package/src/detectors/version-mismatch.ts

@@ -1,12 +1,16 @@
-// version-mismatch: the version a code block's lead-in names against the one the block shows (structure/version-mismatch.ts).
-// The words that make a version a bound (「から」「以上」, "from", "or later") are the lexicon version-range; the words that
-// lead to the version installed (version, install) are version-lead.
-import type { Detector, Finding } from "../plugin.ts";
+// version-mismatch: the version a code block's lead-in names against the one the block shows (structure/version-mismatch.ts),
+// and an install command that pins the document's own package to a version its release list does not say is current
+// (structure/install-pin.ts). The words that make a version a bound (「から」「以上」, "from", "or later") are the lexicon
+// version-range; the words that lead to the version installed (version, install) are version-lead; the install commands
+// are install-command.
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
 import { versionMismatches, type RangeWord, type VersionWords } from "../structure/version-mismatch.ts";
+import { installPinMismatches, ownTextOf, pinsIn } from "../structure/install-pin.ts";
+import { releasesOf } from "../structure/release-list.ts";
 import { codeFences } from "./code-fences.ts";
 import { quoteAt } from "./structure-tree.ts";
 
-export const versionMismatch: Detector = (doc): Finding[] => {
+const leadInFindings = (doc: ProseDocument): Finding[] => {
   const words: VersionWords = {
     ranges: (doc.lexicons["version-range"] ?? []).map((entry): RangeWord => ({ word: entry.pattern, position: entry.position ?? "before" })),
     versionWords: (doc.lexicons["version-lead"] ?? []).map((entry) => entry.pattern),
@@ -21,3 +25,20 @@ export const versionMismatch: Detector = (doc): Finding[] => {
     values: { ...issue.values, offset: issue.offset },
   }));
 };
+
+const installPinFindings = (doc: ProseDocument): Finding[] => {
+  const shapes = (doc.lexicons["install-command"] ?? []).map((entry) => entry.pattern);
+  const headings = doc.markup?.headings ?? [];
+  const releases = releasesOf(doc.source, headings, codeFences(doc.source));
+  return installPinMismatches(pinsIn(doc.source, shapes), releases, ownTextOf(doc.source, headings)).map((issue) => ({
+    rule: "version-mismatch",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAt(doc.source, issue.offset),
+    variant: issue.variant,
+    values: { ...issue.values, offset: issue.offset },
+  }));
+};
+
+export const versionMismatch: Detector = (doc): Finding[] => [...leadInFindings(doc), ...installPinFindings(doc)];

package/src/detectors/version-order.ts

@@ -0,0 +1,50 @@
+// version-order: a changelog's version headings, or a list or table of releases, with one version out of order
+// (structure/version-order.ts).
+import { quoteAt } from "./structure-tree.ts";
+import { codeFences } from "./code-fences.ts";
+import { siblingHeadingRunsOf } from "../structure/heading-runs.ts";
+import { runsOf, type Line } from "../structure/runs.ts";
+import { isVersionHistory, leadingVersion, versionOrderBreaks, type VersionPoint } from "../structure/version-order.ts";
+import type { Detector, Finding, MarkupHeading, ProseDocument } from "../plugin.ts";
+
+const headingPoint = (source: string, heading: MarkupHeading): VersionPoint | undefined => {
+  const label = leadingVersion(heading.text);
+  if (label === undefined) return undefined;
+  const at = source.indexOf(label, heading.start);
+  return { offset: at === -1 ? heading.start : at, label };
+};
+
+/** The marker of a list item or the first pipe of a table row, before the item's text. */
+const ITEM_MARKER = /^[ \t]*(?:[-*+]|\d{1,3}[.)]|\|)[ \t]*/u;
+
+const itemVersions = (source: string, run: readonly Line[]): VersionPoint[] =>
+  run.flatMap((line) => {
+    const text = source.slice(line.start, line.end);
+    const marker = ITEM_MARKER.exec(text)?.[0] ?? "";
+    const label = leadingVersion(text.slice(marker.length));
+    return label === undefined ? [] : [{ offset: line.start + marker.length, label }];
+  });
+
+/** A list in a code fence (an example changelog) is not the document's. */
+const outsideFences = (source: string, run: readonly Line[]): Line[] => {
+  const fences = codeFences(source);
+  return run.filter((line) => !fences.some((fence) => line.start >= fence.start && line.start < fence.end));
+};
+
+const pointRuns = (doc: ProseDocument): VersionPoint[][] => [
+  ...siblingHeadingRunsOf(doc.markup?.headings ?? [], (heading) => headingPoint(doc.source, heading)),
+  ...runsOf(doc.source).map((run) => itemVersions(doc.source, outsideFences(doc.source, run))),
+];
+
+export const versionOrder: Detector = (doc): Finding[] =>
+  pointRuns(doc)
+    .filter((run) => isVersionHistory(run.map((point) => point.label)))
+    .flatMap(versionOrderBreaks)
+    .map((issue) => ({
+      rule: "version-order",
+      severity: "warning",
+      line: 0,
+      column: 0,
+      quote: quoteAt(doc.source, issue.offset),
+      values: { ...issue.values, offset: issue.offset },
+    }));

package/src/detectors/warning-action.ts

@@ -0,0 +1,49 @@
+// warning-without-action: a warning paragraph (Warning:, 注意：, > [!WARNING]) none of whose sentences tells the reader what
+// to do (warning-action.ts). In English a sentence that opens with its verb (Export today's orders first) is an action too.
+// A GitHub alert (> [!WARNING]) is read to the end of its block quote.
+import { isInstruction, isStatement } from "./technical-docs.ts";
+import { quoteAt } from "./structure-tree.ts";
+import { namesAction, quoteBlockEnd, warningTextStart, type WarningWords } from "../warning-action.ts";
+import type { Detector, Finding, Paragraph, ProseDocument, Sentence } from "../plugin.ts";
+
+const wordsOf = (doc: ProseDocument): WarningWords => ({
+  labels: (doc.lexicons["warning-label"] ?? []).map((entry) => entry.pattern),
+  actions: (doc.lexicons["warning-action"] ?? []).map((entry) => entry.pattern),
+});
+
+/** An English sentence that opens with its verb, read from the parts of speech past the label: an instruction. */
+const opensWithVerb = (doc: ProseDocument, sentence: Sentence, from: number): boolean => {
+  const tokens = (sentence.tokens ?? []).filter((token) => token.span.start >= from);
+  return doc.language === "en" && tokens.length > 0 && isInstruction(tokens) && !isStatement(tokens);
+};
+
+const isAction = (doc: ProseDocument, sentence: Sentence, from: number, words: WarningWords): boolean => {
+  const start = Math.max(sentence.span.start, from);
+  if (start >= sentence.span.end) return false;
+  return namesAction(doc.source.slice(start, sentence.span.end), words.actions) || opensWithVerb(doc, sentence, start);
+};
+
+const warningWithoutAction = (doc: ProseDocument, paragraph: Paragraph, words: WarningWords): Finding[] => {
+  const textStart = warningTextStart(doc.source.slice(paragraph.span.start, paragraph.span.end), words.labels);
+  if (textStart === undefined) return [];
+  const from = paragraph.span.start + textStart;
+  const end = quoteBlockEnd(doc.source, paragraph.span.start) ?? paragraph.span.end;
+  const said = doc.sentences.filter((sentence) => sentence.span.end > from && sentence.span.start < end);
+  if (said.length === 0 || said.some((sentence) => isAction(doc, sentence, from, words))) return [];
+  return [
+    {
+      rule: "warning-without-action",
+      severity: "info",
+      line: 0,
+      column: 0,
+      quote: quoteAt(doc.source, paragraph.span.start),
+      values: { offset: paragraph.span.start },
+    },
+  ];
+};
+
+export const warningAction: Detector = (doc): Finding[] => {
+  const words = wordsOf(doc);
+  if (words.labels.length === 0) return [];
+  return doc.paragraphs.flatMap((paragraph) => warningWithoutAction(doc, paragraph, words));
+};