chaffjs 0.20.0 → 0.22.0

package/src/detectors/request-owner.ts

@@ -0,0 +1,141 @@
+// A request for an action (「資料をご確認ください」 "Please send the report.") with no deadline and no person or role,
+// in its own sentence or the next. The words come from the language's lexicons; the code only combines them.
+import type { Detector, Finding, Lexicon, ProseDocument, Sentence, Span, StructureNode } from "../plugin.ts";
+import { proseText } from "../measure.ts";
+import { comparableWords } from "./lexicon-match.ts";
+import { escapeRegExp } from "../orthography.ts";
+import { inDocumentOrder } from "../structure/issues.ts";
+
+/** The lexicons the rule reads, by name. A language without them checks nothing. */
+export const REQUEST_LEXICONS = {
+  ending: "request-ending",
+  action: "request-action",
+  condition: "request-condition",
+  deadline: "request-deadline",
+  owner: "request-owner",
+  pointer: "request-pointer",
+} as const;
+
+type Words = Readonly<Record<keyof typeof REQUEST_LEXICONS, readonly string[]>>;
+
+/** A clock time (14:00, 14時, 2pm) says when as much as a date does; a duration (3時間) does not. */
+const CLOCK = /\d{1,2}\s*(?:[:：]\d{2}|時(?!間)|\s?[ap]\.?m\.?(?![a-z]))/iu;
+
+const patternsOf = (lexicon: Lexicon | undefined): string[] => (lexicon ?? []).map((entry) => comparableWords(entry.pattern));
+
+const wordsOf = (doc: ProseDocument): Words => ({
+  ending: patternsOf(doc.lexicons[REQUEST_LEXICONS.ending]),
+  action: patternsOf(doc.lexicons[REQUEST_LEXICONS.action]),
+  condition: patternsOf(doc.lexicons[REQUEST_LEXICONS.condition]),
+  deadline: patternsOf(doc.lexicons[REQUEST_LEXICONS.deadline]),
+  owner: patternsOf(doc.lexicons[REQUEST_LEXICONS.owner]),
+  pointer: patternsOf(doc.lexicons[REQUEST_LEXICONS.pointer]),
+});
+
+/** How far apart, in characters, the action word and the request ending may be: the action must be what is requested. */
+const ACTION_REACH = 12;
+
+/** A Latin word matches whole words only ("by" is not in "maybe"); other scripts have no spaces to bound a word. */
+const matcherOf = (pattern: string): RegExp =>
+  /^[\p{Script=Latin}\d]/u.test(pattern)
+    ? new RegExp(`(?<![\\p{L}\\d])${escapeRegExp(pattern)}(?![\\p{L}\\d])`, "gu")
+    : new RegExp(escapeRegExp(pattern), "gu");
+
+type Place = { readonly start: number; readonly end: number };
+
+/** Where the lexicon's words occur in the text (after the comparable form: lower case, straight apostrophes). */
+const placesOf = (text: string, patterns: readonly string[]): Place[] => {
+  const comparable = comparableWords(text);
+  return patterns
+    .filter((pattern) => pattern !== "")
+    .flatMap((pattern) => [...comparable.matchAll(matcherOf(pattern))].map((match) => ({ start: match.index, end: match.index + match[0].length })));
+};
+
+export const containsAny = (text: string, patterns: readonly string[]): boolean => placesOf(text, patterns).length > 0;
+
+const gapBetween = (left: Place, right: Place): number => Math.max(left.start - right.end, right.start - left.end, 0);
+
+/**
+ * A request for an action: an action word next to a request ending (「確認してください」「please send」), not a condition
+ * (「ご不明な点があれば…ください」 is an offer), and not a pointer to where to read more (「詳細は資料をご確認ください」).
+ * The action has to be close to the ending, or a noun like 検討会 or 履修登録 earlier in the sentence would make one.
+ */
+export const isRequest = (text: string, words: Words): boolean => {
+  const endings = placesOf(text, words.ending);
+  const asked = placesOf(text, words.action).some((action) => endings.some((ending) => gapBetween(action, ending) <= ACTION_REACH));
+  return asked && !containsAny(text, words.condition) && !containsAny(text, words.pointer);
+};
+
+const NAMED = new Set(["PROPN"]);
+
+/** A proper noun in the request itself (「Ito, please share」) names who; one in the next sentence may be a product or a place. */
+const namesSomeone = (sentence: Sentence): boolean => (sentence.tokens ?? []).some((token) => NAMED.has(token.pos));
+
+const datedWithin = (dates: readonly Span[], span: Span): boolean => dates.some((date) => date.start >= span.start && date.start < span.end);
+
+type Bounds = { readonly starts: ReadonlySet<number>; readonly ends: ReadonlySet<number> };
+
+/** Where the sentence's words start and end in its comparable text, found by walking the token surfaces in order. */
+const wordBounds = (comparable: string, sentence: Sentence): Bounds | undefined => {
+  const tokens = sentence.tokens;
+  if (tokens === undefined || tokens.length === 0) return undefined;
+  const starts = new Set<number>();
+  const ends = new Set<number>();
+  tokens.reduce((from, token) => {
+    const surface = comparableWords(token.surface);
+    const at = surface === "" ? -1 : comparable.indexOf(surface, from);
+    if (at === -1) return from;
+    starts.add(at);
+    ends.add(at + surface.length);
+    return at + surface.length;
+  }, 0);
+  return { starts, ends };
+};
+
+/**
+ * Whether the sentence holds one of the words as whole words. With parts of speech a word must start and end on a word
+ * boundary, so 様 is not found in 同様, さん in たくさん, or まで in いままで; without them, as text.
+ */
+const holdsWord = (sentence: Sentence, patterns: readonly string[]): boolean => {
+  const comparable = comparableWords(proseText(sentence));
+  const bounds = wordBounds(comparable, sentence);
+  return placesOf(comparable, patterns).some((place) => bounds === undefined || (bounds.starts.has(place.start) && bounds.ends.has(place.end)));
+};
+
+/** Whether a sentence says when (a date, a clock time, a deadline word) or who (a role; a name in the request itself). */
+const saysWhenOrWho = (sentence: Sentence, words: Words, dates: readonly Span[], isRequestItself: boolean): boolean =>
+  datedWithin(dates, sentence.span) ||
+  CLOCK.test(proseText(sentence)) ||
+  holdsWord(sentence, words.deadline) ||
+  holdsWord(sentence, words.owner) ||
+  (isRequestItself && namesSomeone(sentence));
+
+/** A paragraph break or a new list item between two sentences: the second does not continue the first. */
+const BREAK = /\n[^\S\n]*\n|\n[^\S\n]*(?:[-*+]|\d+[.)])[^\S\n]/u;
+
+const continues = (source: string, sentence: Sentence, next: Sentence | undefined): next is Sentence =>
+  next !== undefined && !BREAK.test(source.slice(sentence.span.end, next.span.start));
+
+const dateSpans = (tree: StructureNode | undefined): Span[] =>
+  tree === undefined ? [] : inDocumentOrder(tree).flatMap((node) => (node.kind === "date" ? [node.span] : []));
+
+/** The request sentences with neither a deadline nor a person in them or in the sentence after, in the same paragraph or item. */
+export const ownerlessRequests = (doc: ProseDocument): Sentence[] => {
+  const words = wordsOf(doc);
+  const dates = dateSpans(doc.structure);
+  return doc.sentences.filter((sentence, index) => {
+    if (!isRequest(proseText(sentence), words) || saysWhenOrWho(sentence, words, dates, true)) return false;
+    const next = doc.sentences[index + 1];
+    return !continues(doc.source, sentence, next) || !saysWhenOrWho(next, words, dates, false);
+  });
+};
+
+export const requestWithoutDeadline: Detector = (doc: ProseDocument): Finding[] =>
+  ownerlessRequests(doc).map((sentence) => ({
+    rule: "request-without-deadline",
+    severity: "info",
+    line: 0,
+    column: 0,
+    quote: proseText(sentence),
+    values: { offset: sentence.span.start },
+  }));

package/src/detectors/share-over-hundred.ts

@@ -0,0 +1,75 @@
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import { escapeRegExp } from "../orthography.ts";
+import { quoteAround } from "./quote-around.ts";
+
+// 集まりの一部の割合なのに 100% を超える百分率（回答者の120%、150% of respondents）。一部は全体を超えない。
+// 集まりの語は語彙表 share-whole、百分率とのあいだの語とその側は share-whole-link、百分率の単位は percent-unit が言う。
+
+export type ShareWords = {
+  readonly wholes: readonly string[];
+  readonly links: readonly { readonly pattern: string; readonly position: "before" | "after" }[];
+  readonly units: readonly string[];
+};
+
+/** 100% を超える一部の割合 1 つ。written は百分率、whole は何の一部か。 */
+export type ShareOverHundred = { readonly offset: number; readonly end: number; readonly written: string; readonly whole: string };
+
+const WHOLE_PERCENT = 100;
+/** 集まりの語が、より長い語の頭でないこと（users_2025、回答者数）。漢字やカタカナが続けば別の語（回答者数は人数で、割合の元ではない）。 */
+const NOT_INSIDE_WORD = "(?![A-Za-z0-9_\\p{Script=Han}\\p{Script=Katakana}])";
+const FULLWIDTH_OFFSET = 0xfee0;
+
+const halfWidth = (text: string): string => text.replace(/[０-９．]/gu, (char) => String.fromCharCode(char.charCodeAt(0) - FULLWIDTH_OFFSET));
+
+const alternation = (words: readonly string[]): string =>
+  words
+    .toSorted((left, right) => right.length - left.length)
+    .map(escapeRegExp)
+    .join("|");
+
+/** 集まりの語の前後の英字だけを語の切れ目に見る。日本語は語を続けて書く（アンケートでは回答者の、120%の回答者が）。 */
+const wholeNear = (text: string, start: number, end: number, words: ShareWords): string | undefined => {
+  const wholes = alternation(words.wholes);
+  return words.links
+    .map((link) => {
+      const near =
+        link.position === "after"
+          ? new RegExp(`^\\s*${escapeRegExp(link.pattern)}\\s*(?<whole>${wholes})${NOT_INSIDE_WORD}`, "u").exec(text.slice(end))
+          : new RegExp(`(?<![A-Za-z])(?<whole>${wholes})${escapeRegExp(link.pattern)}\\s*$`, "u").exec(text.slice(0, start));
+      return near?.groups?.["whole"];
+    })
+    .find((whole) => whole !== undefined);
+};
+
+/** 文字列の中の、集まりの一部の割合なのに 100% を超える百分率。 */
+export const sharesOverHundred = (text: string, words: ShareWords): ShareOverHundred[] => {
+  if (words.wholes.length === 0 || words.units.length === 0) return [];
+  const percent = new RegExp(`(?<![\\d.,，０-９])(?<value>[0-9０-９]+(?:[,，][0-9０-９]{3})*(?:[.．][0-9０-９]+)?)\\s?(?:${alternation(words.units)})`, "gu");
+  return [...text.matchAll(percent)].flatMap((match) => {
+    const value = Number(halfWidth(match.groups?.["value"] ?? "").replace(/[,，]/gu, ""));
+    if (value <= WHOLE_PERCENT) return [];
+    const end = match.index + match[0].length;
+    const whole = wholeNear(text, match.index, end, words);
+    return whole === undefined ? [] : [{ offset: match.index, end, written: match[0], whole }];
+  });
+};
+
+const positioned = (doc: ProseDocument): ShareWords["links"] =>
+  (doc.lexicons["share-whole-link"] ?? []).flatMap((entry) => (entry.position === undefined ? [] : [{ pattern: entry.pattern, position: entry.position }]));
+
+export const shareOverHundred: Detector = (doc): Finding[] => {
+  const text = doc.prose ?? doc.source;
+  const words: ShareWords = {
+    wholes: (doc.lexicons["share-whole"] ?? []).map((entry) => entry.pattern),
+    links: positioned(doc),
+    units: (doc.lexicons["percent-unit"] ?? []).map((entry) => entry.pattern),
+  };
+  return sharesOverHundred(text, words).map((found) => ({
+    rule: "",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAround(text, found.offset, found.end),
+    values: { written: found.written, whole: found.whole, offset: found.offset },
+  }));
+};

package/src/detectors/step-reference.ts

@@ -0,0 +1,83 @@
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import { escapeRegExp } from "../orthography.ts";
+import { quoteAround } from "./quote-around.ts";
+
+// 本文が指す手順の番号（「手順5を参照」「see step 5」）が、文書のどの手順にも無い所。
+// 手順は、手順の語（語彙表 step-word）と番号で始まる見出しと、番号付きの箇条書きの項目。手順が一つも無い文書では言わない。
+// 番号のすぐ後ろの語（語彙表 figure-elsewhere の of・in）や前の文書の名前が、ほかの文書の手順だと言えば数えない。
+
+/** 無い手順を指す参照 1 つ。label は書いたままの参照、last は文書の手順の最後の番号。 */
+export type MissingStep = { readonly offset: number; readonly label: string; readonly last: number };
+
+/**
+ * 手順を読むのに要るもの。source は見出しの印（#）を残した文書、prose はコードを覆った本文（位置は source と同じ）。
+ * elsewhere は参照がほかの文書の手順を指すか（参照の始まりと終わりの位置で）。
+ */
+export type StepText = { readonly source: string; readonly prose: string; readonly elsewhere: (start: number, end: number) => boolean };
+
+const FULLWIDTH_OFFSET = 0xfee0;
+const LIST_ITEM = /^[ \t]*(?<number>\d{1,3})[.)][ \t]/u;
+const HEADING = /^#{1,6}[ \t]+/u;
+
+const halfWidth = (text: string): string => text.replace(/[０-９]/gu, (char) => String.fromCharCode(char.charCodeAt(0) - FULLWIDTH_OFFSET));
+
+type Mention = { readonly offset: number; readonly label: string; readonly number: number; readonly heading: boolean };
+
+const mentionPattern = (words: readonly string[]): RegExp =>
+  new RegExp(`(?<![A-Za-z])(?:${words.map(escapeRegExp).join("|")})[ \\t\\u3000]?(?<number>[0-9０-９]{1,3})(?![0-9０-９A-Za-z])`, "gu");
+
+const isHeadingAt = (source: string, offset: number): boolean => HEADING.test(source.slice(source.lastIndexOf("\n", offset - 1) + 1, offset));
+
+/** 本文の参照（コードを覆った prose から）と、見出しの手順（prose は見出しも覆うので source から）。 */
+const mentionsOf = ({ source, prose }: StepText, words: readonly string[]): Mention[] => {
+  const toMention = (match: RegExpExecArray | RegExpMatchArray, heading: boolean): Mention => ({
+    offset: match.index ?? 0,
+    label: match[0],
+    number: Number(halfWidth(match.groups?.["number"] ?? "")),
+    heading,
+  });
+  const headings = [...source.matchAll(mentionPattern(words))].filter((match) => isHeadingAt(source, match.index)).map((match) => toMention(match, true));
+  const references = [...prose.matchAll(mentionPattern(words))].filter((match) => !isHeadingAt(source, match.index)).map((match) => toMention(match, false));
+  return [...headings, ...references];
+};
+
+const listNumbers = (prose: string): number[] =>
+  prose.split("\n").flatMap((line) => {
+    const number = LIST_ITEM.exec(line)?.groups?.["number"];
+    return number === undefined ? [] : [Number(number)];
+  });
+
+/** 文書のどの手順にも無い番号を指す参照。手順の最後の番号を超えるものだけ（箇条書きが二つあれば、番号はどちらかにある）。 */
+export const missingSteps = (text: StepText, words: readonly string[]): MissingStep[] => {
+  if (words.length === 0) return [];
+  const mentions = mentionsOf(text, words);
+  const steps = [...mentions.filter((mention) => mention.heading).map((mention) => mention.number), ...listNumbers(text.prose)];
+  if (steps.length === 0) return [];
+  const last = Math.max(...steps);
+  return mentions
+    .filter((mention) => !mention.heading && mention.number > last && !text.elsewhere(mention.offset, mention.offset + mention.label.length))
+    .map((mention) => ({ offset: mention.offset, label: mention.label, last }));
+};
+
+/** 番号のすぐ後ろが figure-elsewhere の語か、すぐ前がこの文書でない文書の名前なら、ほかの文書の手順。 */
+const elsewhereOf =
+  (doc: ProseDocument, text: string) =>
+  (start: number, end: number): boolean => {
+    const after = text.slice(end).trimStart();
+    const placed = (doc.lexicons["figure-elsewhere"] ?? []).some((entry) => after.startsWith(`${entry.pattern} `) && /^\s/u.test(text.slice(end)));
+    const named = doc.namedDocument?.(text, start);
+    return placed || (named !== undefined && !named.self);
+  };
+
+export const stepReference: Detector = (doc): Finding[] => {
+  const prose = doc.prose ?? doc.source;
+  const words = (doc.lexicons["step-word"] ?? []).map((entry) => entry.pattern);
+  return missingSteps({ source: doc.source, prose, elsewhere: elsewhereOf(doc, prose) }, words).map((missing) => ({
+    rule: "",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAround(prose, missing.offset, missing.offset + missing.label.length),
+    values: { label: missing.label, last: missing.last, offset: missing.offset },
+  }));
+};

package/src/detectors/technical-docs.ts

@@ -0,0 +1,230 @@
+// Checks a README or a manual needs: code fences tagged with a language or not, shell commands written with and without
+// a prompt, a heading that names a command its section's code never shows, and a step of a numbered procedure written
+// as a statement among instructions. Pure. Shell languages and prompt marks come from the shell-fence-language and
+// shell-prompt lexicons.
+import { codeFences, codeSpans, type CodeFence } from "./code-fences.ts";
+import { quoteAt } from "./structure-tree.ts";
+import type { Detector, Finding, ProseDocument, Span, Token } from "../plugin.ts";
+
+const patternsOf = (doc: ProseDocument, id: string): string[] => (doc.lexicons[id] ?? []).map((entry) => entry.pattern);
+
+/** The members of the less used of two kinds: at most limit of them, and fewer than the other kind. */
+export const minorityOf = <T>(first: readonly T[], second: readonly T[], limit: number): readonly T[] => {
+  const [fewer, more] = first.length <= second.length ? [first, second] : [second, first];
+  return fewer.length > 0 && fewer.length < more.length && fewer.length <= limit ? fewer : [];
+};
+
+const finding = (doc: ProseDocument, rule: string, offset: number, values: Readonly<Record<string, string | number>> = {}): Finding => ({
+  rule,
+  severity: "info",
+  line: 0,
+  column: 0,
+  quote: quoteAt(doc.source, offset),
+  values: { ...values, offset },
+});
+
+/** Fences without a language, when they are the fewer kind: a document that mostly leaves the language out is not reported. */
+export const untaggedFewer = (fences: readonly CodeFence[], limit: number): readonly CodeFence[] => {
+  const untagged = fences.filter((fence) => fence.language === "");
+  const tagged = fences.filter((fence) => fence.language !== "");
+  return untagged.length > 0 && untagged.length < tagged.length && untagged.length <= limit ? untagged : [];
+};
+
+export const codeFenceLanguage: Detector = (doc, options): Finding[] => {
+  const fences = codeFences(doc.source);
+  const tagged = fences.filter((fence) => fence.language !== "").length;
+  return untaggedFewer(fences, options.limit).map((fence) =>
+    finding(doc, "code-fence-language-mix", fence.start, { tagged, untagged: fences.length - tagged }),
+  );
+};
+
+export type PromptStyle = "prompt" | "bare" | undefined;
+
+/**
+ * Whether a shell block writes its commands after a prompt ($ npm install) or bare (npm install). A block that mixes
+ * prompted and unprompted lines shows a command with its output, and is neither. Comment lines (#) are skipped.
+ */
+export const promptStyleOf = (fence: CodeFence, prompts: readonly string[]): PromptStyle => {
+  const lines = fence.lines.map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#"));
+  if (lines.length === 0) return undefined;
+  const prompted = lines.filter((line) => prompts.some((prompt) => line.startsWith(`${prompt} `))).length;
+  if (prompted === lines.length) return "prompt";
+  return prompted === 0 ? "bare" : undefined;
+};
+
+export const shellPrompt: Detector = (doc, options): Finding[] => {
+  const languages = new Set(patternsOf(doc, "shell-fence-language").map((language) => language.toLowerCase()));
+  const prompts = patternsOf(doc, "shell-prompt");
+  const shells = codeFences(doc.source).filter((fence) => languages.has(fence.language));
+  const prompted = shells.filter((fence) => promptStyleOf(fence, prompts) === "prompt");
+  const bare = shells.filter((fence) => promptStyleOf(fence, prompts) === "bare");
+  const minority = minorityOf(prompted, bare, options.limit);
+  const style = minority === prompted ? "prompt" : "bare";
+  return minority.map((fence) => finding(doc, "shell-prompt-mix", fence.start, { majority: style === "prompt" ? bare.length : prompted.length }));
+};
+
+/**
+ * A code span that names a command or an option: a flag (--force, -f) or a command with its arguments (npm install). A
+ * single plain word (net, init) is as often a package, an endpoint or a type as a command, and is left out.
+ */
+const COMMAND_WORD = /^[a-z][a-z0-9_-]*$/u;
+const FLAG = /^--?[A-Za-z][\w-]*$/u;
+
+export const isCommandName = (text: string): boolean => {
+  const words = text.trim().split(/\s+/u);
+  const first = words[0] ?? "";
+  return words.length === 1 ? FLAG.test(first) : COMMAND_WORD.test(first);
+};
+
+/** The heading without its links' text: [`net`](/pkg/net/) names the page it links to, not a command shown below. */
+export const withoutLinks = (heading: string): string => {
+  const pieces: string[] = [];
+  const state = { at: 0 };
+  while (state.at < heading.length) {
+    const open = heading.indexOf("[", state.at);
+    const close = open === -1 ? -1 : heading.indexOf("]", open);
+    if (close === -1) break;
+    pieces.push(heading.slice(state.at, open), " ");
+    state.at = close + 1 + targetLength(heading, close + 1);
+  }
+  pieces.push(heading.slice(state.at));
+  return pieces.join("");
+};
+
+/** The length of a link's target right after its text: (url), [label] or [] (a reference link); 0 when there is none. */
+const targetLength = (heading: string, at: number): number => {
+  const pair: Readonly<Record<string, string>> = { "(": ")", "[": "]" };
+  const closer = pair[heading.charAt(at)];
+  const end = closer === undefined ? -1 : heading.indexOf(closer, at);
+  return end === -1 ? 0 : end - at + 1;
+};
+
+/** The commands and options a heading names: its code spans that read as one, and bare flags (--force). */
+export const commandsIn = (heading: string): string[] => {
+  const spans = codeSpans(withoutLinks(heading)).map((span) => span.text);
+  const flags = heading
+    .replace(/`[^`]*`/gu, " ")
+    .split(/\s+/u)
+    .filter((word) => FLAG.test(word) && word.startsWith("--"));
+  return [...new Set([...spans.filter(isCommandName), ...flags])];
+};
+
+const collapse = (text: string): string => text.replace(/\s+/gu, " ");
+const OPTION_CHAR = /[A-Za-z0-9_-]/u;
+
+/** Whether the code holds the command as a whole word: --force is not --force-with-lease, init is not initial. */
+export const showsCommand = (code: string, command: string): boolean => {
+  const text = collapse(code);
+  const wanted = collapse(command.trim());
+  const state = { at: text.indexOf(wanted) };
+  while (state.at !== -1) {
+    const before = text.charAt(state.at - 1);
+    const after = text.charAt(state.at + wanted.length);
+    if (!OPTION_CHAR.test(before) && !OPTION_CHAR.test(after)) return true;
+    state.at = text.indexOf(wanted, state.at + 1);
+  }
+  return false;
+};
+
+type Section = { readonly heading: string; readonly start: number; readonly body: Span };
+
+const sectionsOf = (doc: ProseDocument): Section[] => {
+  const headings = doc.markup?.headings ?? [];
+  return headings.map((heading, index) => {
+    const next = headings.slice(index + 1).find((later) => later.depth <= heading.depth);
+    return { heading: doc.source.slice(heading.start, heading.end), start: heading.start, body: { start: heading.end, end: next?.start ?? doc.source.length } };
+  });
+};
+
+/** The code a section shows: its fenced blocks and its inline code spans. Empty when it shows none. */
+const codeOf = (doc: ProseDocument, fences: readonly CodeFence[], body: Span): string => {
+  const inFences = fences.filter((fence) => fence.start >= body.start && fence.start < body.end);
+  const outside = inFences.reduceRight(
+    (text, fence) => `${text.slice(0, fence.start - body.start)}${text.slice(Math.min(fence.end, body.end) - body.start)}`,
+    doc.source.slice(body.start, body.end),
+  );
+  return [...inFences.flatMap((fence) => fence.lines), ...codeSpans(outside).map((span) => span.text)].join("\n");
+};
+
+export const headingCommand: Detector = (doc): Finding[] => {
+  const fences = codeFences(doc.source);
+  return sectionsOf(doc).flatMap((section) => {
+    const commands = commandsIn(section.heading);
+    if (commands.length === 0) return [];
+    const code = codeOf(doc, fences, section.body);
+    if (code.trim() === "") return [];
+    return commands.filter((command) => !showsCommand(code, command)).map((command) => finding(doc, "heading-command-missing", section.start, { command }));
+  });
+};
+
+const ORDERED_ITEM = /^\s*\d{1,3}[.)]\s/u;
+/** What opens a statement: an article or a pronoun (The installer asks, You click, It opens). */
+const SUBJECT_OPENER = new Set(["DET", "PRON"]);
+/** What a subject opens with when it is a name or a noun phrase (Docker builds, Each user gets). */
+const SUBJECT_HEAD = new Set(["DET", "PRON", "PROPN", "NOUN", "ADJ"]);
+/** What may stand between the opener and the verb: the rest of the subject. */
+const SUBJECT_PART = new Set(["DET", "PRON", "PROPN", "NOUN", "ADJ", "ADP"]);
+/** What opens an instruction. The tagger reads a sentence-initial imperative as a noun, an adjective or a name (Click, Open, Restart). */
+const INSTRUCTION_OPENER = new Set(["VERB", "NOUN", "ADJ", "PROPN"]);
+const PREDICATE = new Set(["VERB", "AUX"]);
+const SKIPPED = new Set(["PUNCT", "NUM", "SYM", "X", "SPACE"]);
+/** Steps shorter than this are labels (1. Setup), not instructions or statements. */
+const MIN_STEP_TOKENS = 3;
+/** A list needs this many steps to have a form to keep. */
+const MIN_STEPS = 3;
+
+/** A verb in a finite, inflected form (starts, built): it has a subject before it. A base form (Save) may be an imperative's object. */
+const isInflected = (token: Token): boolean =>
+  token.lemma !== undefined && token.lemma !== "" && token.surface.toLowerCase() !== token.lemma && token.features?.["VerbForm"] !== "Part";
+
+/**
+ * A step written as a statement: a subject, then its verb. The subject opens with an article or a pronoun (The installer
+ * asks, You click), or it is a name or a noun whose verb is inflected (Docker builds). A noun before a base-form verb is
+ * not enough: the tagger reads Click and Press there as nouns (Click Save).
+ */
+export const isStatement = (tokens: readonly Token[]): boolean => {
+  const words = tokens.filter((token) => !SKIPPED.has(token.pos));
+  const [head, ...rest] = words;
+  if (head === undefined || words.length < MIN_STEP_TOKENS || !SUBJECT_HEAD.has(head.pos)) return false;
+  const verbAt = rest.findIndex((token) => PREDICATE.has(token.pos));
+  const verb = rest[verbAt];
+  if (verb === undefined || !rest.slice(0, verbAt).every((token) => SUBJECT_PART.has(token.pos))) return false;
+  // Punctuation before the verb is no subject: a label (Guests: the users who …) or an opening phrase (On the left bar, select …).
+  const interrupted = tokens.some((token) => token.pos === "PUNCT" && token.span.start > head.span.start && token.span.start < verb.span.start);
+  return !interrupted && (SUBJECT_OPENER.has(head.pos) || isInflected(verb));
+};
+
+type Step = { readonly start: number; readonly kind: "statement" | "instruction" | "other" };
+
+/** A step that opens with its verb: an instruction (Run the installer). */
+export const isInstruction = (tokens: readonly Token[]): boolean => INSTRUCTION_OPENER.has(tokens.find((token) => !SKIPPED.has(token.pos))?.pos ?? "");
+
+const kindOf = (tokens: readonly Token[]): Step["kind"] => {
+  if (isStatement(tokens)) return "statement";
+  return isInstruction(tokens) ? "instruction" : "other";
+};
+
+/** The steps of each numbered list: each item's first sentence, read as a statement or not. */
+const stepLists = (doc: ProseDocument): Step[][] =>
+  doc.lists
+    .filter((list) => ORDERED_ITEM.test(doc.source.slice(list.span.start, list.span.end)))
+    .map((list) =>
+      list.itemSpans.flatMap((item): Step[] => {
+        const sentence = doc.sentences.find((candidate) => candidate.span.start >= item.start && candidate.span.start < item.end);
+        // Only the sentence on the item's own line: a note paragraph under it (**NOTE:** …) is not the step.
+        const onItemLine = sentence !== undefined && !doc.source.slice(item.start, sentence.span.start).includes("\n");
+        return sentence?.tokens === undefined || !onItemLine ? [] : [{ start: sentence.span.start, kind: kindOf(sentence.tokens) }];
+      }),
+    )
+    .filter((steps) => steps.length >= MIN_STEPS);
+
+export const stepStatement: Detector = (doc, options): Finding[] =>
+  stepLists(doc).flatMap((steps) => {
+    const statements = steps.filter((step) => step.kind === "statement");
+    const instructions = steps.filter((step) => step.kind === "instruction");
+    // A procedure is a list most of whose steps are instructions; a numbered list of terms and definitions is not one.
+    const isProcedure = instructions.length * 2 > steps.length;
+    return isProcedure && statements.length > 0 && statements.length < instructions.length && statements.length <= options.limit
+      ? statements.map((step) => finding(doc, "step-statement-mix", step.start, { count: instructions.length }))
+      : [];
+  });

package/src/detectors/toc-heading.ts

@@ -0,0 +1,125 @@
+import type { Detector, Finding } from "../plugin.ts";
+import { headingWords } from "../structure-shape/heading-words.ts";
+import { quoteAround } from "./quote-around.ts";
+
+// 目次の項目が、文書のどの見出しとも合わない所。目次の見出しは語彙表 toc-heading が言う。
+// 項目と見出しは、空白・記号・大文字小文字を無視して比べ、頭の番号（1.2、2-1、第3章）を外しても比べる。
+
+/** 見出しの無い目次の項目 1 つ。entry は項目の言葉（リンクなら字の部分）。 */
+export type StrayTocEntry = { readonly offset: number; readonly entry: string };
+
+type Line = { readonly text: string; readonly offset: number };
+type Heading = { readonly title: string; readonly offset: number };
+
+const HEADING = /^[ \t]{0,3}#{1,6}[ \t]/u;
+const FENCE = /^[ \t]*(?:```|~~~)/u;
+const LIST_ITEM = /^[ \t]*(?:[-*+]|\d{1,3}[.)])[ \t]/u;
+const LINK_TEXT = /^\[(?<text>[^\]]*)\]\([^)]*\)/u;
+const ATTRIBUTES = /\{#[^}]*\}/gu;
+const DIGIT = /[\d０-９]/u;
+const LEADER_DOTS = new Set([".", "…", "・"]);
+const MIN_LEADER = 2;
+/** 目次の項目のうち見出しに合わないものがこれより多ければ、目次は別の書き方の見出し（本文に無い章立て）と読んで言わない。 */
+const MAX_STRAY_SHARE = 0.5;
+
+const linesOf = (source: string): Line[] => [...source.matchAll(/^.*$/gmu)].map((match) => ({ text: match[0], offset: match.index }));
+
+/** コードの囲みの外の行。 */
+const outsideFences = (lines: readonly Line[]): Line[] => {
+  const fence = { open: false };
+  return lines.filter((line) => {
+    if (FENCE.test(line.text)) {
+      fence.open = !fence.open;
+      return false;
+    }
+    return !fence.open;
+  });
+};
+
+/** 比べるための形。全角を半角にそろえ（４ と 4）、空白・記号を消し、小文字にする。 */
+const comparable = (text: string): string =>
+  text
+    .replace(ATTRIBUTES, "")
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[\s\p{P}\p{S}]/gu, "");
+
+/** 頭の番号（1.2、2-1、第3章）と飾りを外した、比べるための形。 */
+const withoutNumber = (text: string): string => comparable(headingWords(text));
+
+/** text の終わりから、isTail に当たる字を外したもの。 */
+const trimTail = (text: string, isTail: (char: string) => boolean): string => {
+  const chars = [...text];
+  return chars.slice(0, chars.findLastIndex((char) => !isTail(char)) + 1).join("");
+};
+
+/** 見出しの行の題（頭と終わりの # を外す）。見出しでなければ undefined。 */
+const headingTitle = (line: string): string | undefined => {
+  if (!HEADING.test(line)) return undefined;
+  const withoutMarks = line.trim().replace(/^#+/u, "").trim();
+  return trimTail(withoutMarks, (char) => char === "#").trim();
+};
+
+/** 終わりのページ番号（「背景 ........ 3」の 3 と点線）。点線の無い数（Step 3）は題のうち。 */
+const withoutPageNumber = (text: string): string => {
+  const before = trimTail(text, (char) => DIGIT.test(char)).trimEnd();
+  if (before === text.trimEnd()) return text;
+  const title = trimTail(before, (char) => LEADER_DOTS.has(char));
+  return before.length - title.length >= MIN_LEADER ? title.trim() : text;
+};
+
+/** 項目の言葉と、項目の行の中でそれが始まる所。リンクなら字の部分（番号の後ろのリンク「1. [概要](#…)」も）。 */
+const entryOf = (item: string): { readonly text: string; readonly start: number } => {
+  const bracket = item.indexOf("[");
+  const link = bracket === -1 ? undefined : LINK_TEXT.exec(item.slice(bracket))?.groups?.["text"];
+  if (link !== undefined) return { text: withoutPageNumber(link), start: bracket + 1 };
+  return { text: withoutPageNumber(item.trim()), start: item.length - item.trimStart().length };
+};
+
+const matchesHeading = (entry: string, headings: readonly Heading[]): boolean =>
+  headings.some(
+    (heading) => comparable(heading.title) === comparable(entry) || (withoutNumber(entry) !== "" && withoutNumber(heading.title) === withoutNumber(entry)),
+  );
+
+/** 目次の見出しの下（次の見出しまで）の箇条書きの項目。 */
+const entriesUnder = (lines: readonly Line[], tocAt: number): Line[] => {
+  const after = lines.filter((line) => line.offset > tocAt);
+  const end = after.findIndex((line) => HEADING.test(line.text));
+  return (end === -1 ? after : after.slice(0, end)).flatMap((line) => {
+    const marker = LIST_ITEM.exec(line.text)?.[0];
+    if (marker === undefined) return [];
+    const entry = entryOf(line.text.slice(marker.length));
+    return [{ text: entry.text, offset: line.offset + marker.length + entry.start }];
+  });
+};
+
+/** 文書の目次の項目のうち、どの見出しとも合わないもの。 */
+export const strayTocEntries = (source: string, tocWords: readonly string[]): StrayTocEntry[] => {
+  const lines = outsideFences(linesOf(source));
+  const headings = lines.flatMap((line) => {
+    const title = headingTitle(line.text);
+    return title === undefined ? [] : [{ title, offset: line.offset }];
+  });
+  const tocNames = new Set(tocWords.map(comparable));
+  return headings
+    .filter((heading) => tocNames.has(comparable(heading.title)))
+    .flatMap((toc) => {
+      const entries = entriesUnder(lines, toc.offset).filter((entry) => entry.text !== "");
+      const others = headings.filter((heading) => heading !== toc);
+      const stray = entries.filter((entry) => !matchesHeading(entry.text, others));
+      return stray.length > entries.length * MAX_STRAY_SHARE ? [] : stray.map((entry) => ({ offset: entry.offset, entry: entry.text }));
+    });
+};
+
+export const tocHeading: Detector = (doc): Finding[] =>
+  strayTocEntries(
+    doc.source,
+    (doc.lexicons["toc-heading"] ?? []).map((entry) => entry.pattern),
+  ).map((stray) => ({
+    rule: "",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAround(doc.source, stray.offset, stray.offset + stray.entry.length),
+    values: { entry: stray.entry, offset: stray.offset },
+  }));