chaffjs 0.28.0 → 0.30.0

package/src/reasons.ts

@@ -9,6 +9,8 @@ export type Reasons = {
   readonly unreadTags: string;
   readonly semantic: string;
   readonly experimental: string;
+  /** A rule of one house style: it runs when chaff.yaml names that style, or gives the rule a level. */
+  readonly optIn: string;
   readonly turnedOff: string;
   readonly presetOff: (genre: string) => string;
   readonly noStructure: (language: string) => string;
@@ -41,6 +43,7 @@ export const REASONS: Texts<Reasons> = {
     unreadTags: "言語のパッケージがこの文書を読めなかったため（品詞の取れない段落があります）",
     semantic: "意味を読む検査のため（npx chaffjs test で動きます）",
     experimental: "まだ試験中のため",
+    optIn: "決まった書き方（chaff.yaml の style）のための rule で、style か rules で動かすため",
     turnedOff: "設定で止めているため",
     presetOff: (genre) => `ジャンル ${genre} では見ないため`,
     noStructure: (language) => `${language} のパッケージは文書の構造を読めないため`,
@@ -63,6 +66,7 @@ export const REASONS: Texts<Reasons> = {
     unreadTags: "the language package could not read this document (some paragraphs have no parts of speech)",
     semantic: "it reads meaning; npx chaffjs test runs it",
     experimental: "still experimental",
+    optIn: "it belongs to a house style, and runs when chaff.yaml names the style or gives it a level",
     turnedOff: "turned off in the settings",
     presetOff: (genre) => `the ${genre} genre does not check it`,
     noStructure: (language) => `the ${language} package cannot read a document's structure`,

package/src/render/rules-json.ts

@@ -21,6 +21,7 @@ const TEXT: Texts<{
   readonly offByGenre: (genre: string) => string;
   readonly offUnsuited: (genre: string) => string;
   readonly offExperimental: string;
+  readonly offOptIn: string;
   readonly valuesNote: string;
   readonly reason: string;
   readonly byFile: string;
@@ -32,6 +33,7 @@ const TEXT: Texts<{
     offByGenre: (genre) => `ジャンル ${genre} では見ない`,
     offUnsuited: (genre) => `ジャンル ${genre} の文書には向かない rule（use_for）`,
     offExperimental: "experimental な rule は既定で動かさない",
+    offOptIn: "決まった書き方（style）のための rule で、chaff.yaml の style か rules で動かす",
     valuesNote: "この 4 語のかわりに数字を直接書いてもよい。4 語のほうを勧める。",
     reason: "<理由>",
     byFile: "chaff.yaml の rules に <rule-id>: <level> を足す。既定のままのものは書かない。",
@@ -49,6 +51,7 @@ const TEXT: Texts<{
     offByGenre: (genre) => `the ${genre} genre does not check it`,
     offUnsuited: (genre) => `not a rule for ${genre} documents (use_for)`,
     offExperimental: "experimental rules do not run by default",
+    offOptIn: "a house style's rule: it runs when chaff.yaml names the style or gives it a level",
     valuesNote: "A number may be written instead of these four words. The words are recommended.",
     reason: "<reason>",
     byFile: "Add <rule-id>: <level> under rules in chaff.yaml. Leave out anything at its default.",
@@ -76,6 +79,7 @@ const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string
   const limit = rule.level_sets === "severity" ? undefined : limits[rule.id];
   if (limit !== undefined) return { level: "normal", limit, set_as: "number" };
   if (explicit !== undefined) return { level: explicit, ...effectAt(rule, explicit, genre) };
+  if (rule.opt_in === true) return { level: "off", why_off: text.offOptIn };
   if (rule.status === "experimental" && !config.experimental) {
     const alone = offOnlyAsExperimental(rule, config, genre, preset, language);
     return { level: "off", why_off: text.offExperimental, ...(alone ? { turn_on_with: `npx chaffjs enable ${rule.id}` } : {}) };

package/src/render/rules-table.ts

@@ -7,7 +7,7 @@ import { nowFor } from "./rules-json.ts";
 // `chaff rules`: every rule, grouped the way the reference groups them, with the level it runs at now.
 // `chaff rules --json` carries the same and more, for an AI to read.
 
-type RunsWhen = "default" | "experimental" | "team" | "test";
+type RunsWhen = "default" | "experimental" | "style" | "team" | "test";
 
 const TEXT: Texts<{
   readonly heading: (genre: string, count: number) => string;
@@ -17,11 +17,12 @@ const TEXT: Texts<{
 }> = {
   ja: {
     heading: (genre, count) => `chaff のルール ${count} 本（ジャンル ${genre}）`,
-    runsWhen: { default: "既定", experimental: "試験中", team: "要設定", test: "AI" },
+    runsWhen: { default: "既定", experimental: "試験中", style: "style", team: "要設定", test: "AI" },
     ungrouped: "（グループ未設定）",
     footer: [
       "既定: 何も書かなくても動く   試験中: --experimental か chaff.yaml で動く",
       "要設定: chaff.yaml に語や見出しを書いたときだけ   AI: npx chaffjs test で動く",
+      "style: chaff.yaml の style（koyobun など）か rules で動く",
       "",
       "詳しく:    npx chaffjs explain <rule>",
       "AI に渡す: npx chaffjs rules --json",
@@ -29,11 +30,12 @@ const TEXT: Texts<{
   },
   en: {
     heading: (genre, count) => `chaff's ${count} rules (genre ${genre})`,
-    runsWhen: { default: "default", experimental: "experimental", team: "needs list", test: "AI" },
+    runsWhen: { default: "default", experimental: "experimental", style: "style", team: "needs list", test: "AI" },
     ungrouped: "(no group yet)",
     footer: [
       "default: runs with no settings   experimental: runs with --experimental or a level in chaff.yaml",
       "needs list: runs only on words or headings listed in chaff.yaml   AI: runs with npx chaffjs test",
+      "style: runs with a style in chaff.yaml (koyobun and others) or a level under rules",
       "",
       "More on one rule:  npx chaffjs explain <rule>",
       "For an AI:         npx chaffjs rules --json",
@@ -44,6 +46,7 @@ const TEXT: Texts<{
 const runsWhenOf = (rule: RuleDefinition): RunsWhen => {
   if (rule.layer === "L4") return "test";
   if (rule.guide?.group === "team") return "team";
+  if (rule.opt_in === true) return "style";
   return rule.status === "experimental" ? "experimental" : "default";
 };
 

package/src/return-type.ts

@@ -0,0 +1,361 @@
+// One function's return type stated two ways on one page: the signature in a code block against a "Returns:" line, a
+// table's return column, or a sentence ("measure returns a string", 「measure は文字列を返します」). Pure; reads the
+// Markdown source. The words (Returns, 戻り値, returns, 返します, は, and the type words string, 文字列) come from the
+// language's lexicons. A statement is compared only with the signatures of the function it names, and only when both
+// sides are readable. The signature reader is small and TypeScript/Python-shaped; it may later be shared with
+// parameter-table.ts.
+
+/** The words of one language that state a return type. `kinds` maps a lower-cased type word to a kind (string, array). */
+export type ReturnWords = {
+  readonly labels: readonly string[];
+  readonly verbs: readonly string[];
+  /** What may follow the function's name before the verb (は, が); none for a language that puts the verb first. */
+  readonly subjects: readonly string[];
+  readonly kinds: ReadonlyMap<string, string>;
+  /** Words opening a clause about when (when, とき): a type word on the far side of one names the input, not the result. */
+  readonly clauses: readonly string[];
+  /** Words making the type word before them one item of the result (per, ごと). */
+  readonly items: readonly string[];
+};
+
+/** A statement that disagrees with every signature of its function: what it says, what a signature says, and where. */
+export type ReturnTypeClash = { readonly fn: string; readonly stated: string; readonly signature: string; readonly offset: number };
+
+/** A return type as written: a type in code (`string[]`), or the kind a type word names (a string → string). */
+type Stated = { readonly code: string; readonly written: string } | { readonly kind: string; readonly written: string };
+
+type Statement = { readonly fn: string; readonly stated: Stated; readonly offset: number };
+type Signature = { readonly fn: string; readonly params: string; readonly returns: string; readonly offset: number };
+type Line = { readonly text: string; readonly start: number; readonly fenced: boolean; readonly section: number };
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/u;
+const HEADING = /^ {0,3}#{1,6}[ \t]/u;
+const TABLE_ROW = /^[ \t]{0,3}\|/u;
+const DELIMITER_ROW = /^[ \t]{0,3}\|?[ \t]*:?-{3,}/u;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*/u;
+const DECLARATION_HEAD = /^(?:(?:export|default|declare|async|public|static)\s+)*(?:(?:function\*?|def|fn|func)\s+)?/u;
+const ARROW_HEAD = /^(?:(?:export|declare)\s+)*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?/u;
+const RETURN_MARK = /^\s*(?::|->)\s*/u;
+/** What may close a declaration line after its return type: an arrow's `=>` or a body's `{` with what follows, `;`, Python's `:`. */
+const withoutDeclarationTail = (text: string): string => {
+  const cut = [text.indexOf("=>"), text.indexOf("{")].filter((at) => at !== -1);
+  const head = (cut.length === 0 ? text : text.slice(0, Math.min(...cut))).trim();
+  return head.endsWith(";") || head.endsWith(":") ? head.slice(0, -1).trim() : head;
+};
+const GENERICS = /^<[^<>()]*>/u;
+const TYPE_NAME = String.raw`[A-Za-z_$][\w$.]*(?:<[\w$.,\s<>[\]|]*>|\[[\w$.,\s[\]|]*\])?(?:\[\])*`;
+/** A type as code writes it: names, generic arguments, array brackets, and unions of those. */
+const TYPE_TEXT = new RegExp(String.raw`^${TYPE_NAME}(?:\s*\|\s*${TYPE_NAME})*$`, "u");
+/** Where a sentence ends, so a type word of the next sentence is not read as this one's. */
+const SENTENCE_END = /[。！？!?;]|\.(?=\s|$)/u;
+const NOTHING_TYPES: ReadonlySet<string> = new Set(["null", "undefined", "void", "None"]);
+/** The kind of a type name in code; a name not listed (a class, a generic parameter, Promise<…>) has none. */
+const CODE_KINDS: ReadonlyMap<string, string> = new Map([
+  ["string", "string"],
+  ["str", "string"],
+  ["number", "number"],
+  ["int", "number"],
+  ["float", "number"],
+  ["bigint", "number"],
+  ["boolean", "boolean"],
+  ["bool", "boolean"],
+  ["list", "array"],
+  ["tuple", "array"],
+]);
+
+const linesOf = (source: string): Line[] => {
+  const state = { start: 0, fence: "", section: 0 };
+  return source.split("\n").map((text) => {
+    const start = state.start;
+    state.start += text.length + 1;
+    const mark = FENCE.exec(text)?.[1];
+    const closes = mark !== undefined && state.fence !== "" && mark[0] === state.fence[0] && mark.length >= state.fence.length;
+    if (mark !== undefined && (state.fence === "" || closes)) {
+      state.fence = closes ? "" : mark;
+      return { text, start, fenced: true, section: state.section };
+    }
+    if (state.fence === "" && HEADING.test(text)) state.section += 1;
+    return { text, start, fenced: state.fence !== "", section: state.section };
+  });
+};
+
+/** The index of the ) that closes the ( at `open`, or -1. */
+const closingParen = (text: string, open: number): number => {
+  const state = { depth: 0, at: -1 };
+  Array.from(text.slice(open)).some((char, index) => {
+    if (char === "(") state.depth += 1;
+    if (char === ")") state.depth -= 1;
+    if (state.depth === 0) state.at = open + index;
+    return state.depth === 0;
+  });
+  return state.at;
+};
+
+const squeeze = (text: string): string => text.replace(/\s+/gu, "");
+
+/** `Array<string>` is `string[]`: the inner generic first, so Array<Array<string>> becomes string[][]. */
+const withoutArrayGenerics = (type: string): string => {
+  const next = type.replace(/(?<![\w$.])Array<([^<>]*)>/u, (_whole, inner: string) => (inner.includes("|") ? `(${inner})[]` : `${inner}[]`));
+  return next === type ? type : withoutArrayGenerics(next);
+};
+
+/** The members of a union at its top level, outside brackets. */
+const unionMembers = (type: string): string[] => {
+  const state = { depth: 0, from: 0 };
+  const members: string[] = [];
+  Array.from(type).forEach((char, index) => {
+    if ("(<[{".includes(char)) state.depth += 1;
+    if (")>]}".includes(char)) state.depth -= 1;
+    if (char !== "|" || state.depth !== 0) return;
+    members.push(type.slice(state.from, index));
+    state.from = index + 1;
+  });
+  return [...members, type.slice(state.from)].filter((member) => member !== "");
+};
+
+/** A code type's members in one spelling: no spaces, Array<T> as T[], sorted. */
+export const typeMembers = (type: string): string[] =>
+  unionMembers(withoutArrayGenerics(squeeze(type))).toSorted((left, right) => left.localeCompare(right, "en"));
+
+/** The kind of one member, or undefined when its name says nothing a type word could (WrapResult, T, Promise<…>). */
+const kindOfMember = (member: string): string | undefined => {
+  if (member.endsWith("[]") || /^(?:list|List|tuple|Tuple)\[/u.test(member)) return "array";
+  return CODE_KINDS.get(member);
+};
+
+/**
+ * A type in a sentence or a cell is read only when it can be a type and not a parameter's name: each member has a kind, is
+ * null or the like, or is a capitalised name (WrapResult). `text` is a name, and `null` alone says when, not what.
+ */
+const isReadableCode = (type: string): boolean => {
+  const members = typeMembers(type);
+  const readable = members.every((member) => kindOfMember(member) !== undefined || NOTHING_TYPES.has(member) || /^[A-Z]/u.test(member));
+  return TYPE_TEXT.test(type.trim()) && readable && members.some((member) => !NOTHING_TYPES.has(member));
+};
+
+const declaredAt = (line: string): { readonly fn: string; readonly afterName: number } | undefined => {
+  const arrow = ARROW_HEAD.exec(line);
+  if (arrow?.[1] !== undefined) return { fn: arrow[1], afterName: arrow[0].length };
+  const headLength = DECLARATION_HEAD.exec(line)?.[0].length ?? 0;
+  const fn = IDENTIFIER.exec(line.slice(headLength))?.[0];
+  return fn === undefined ? undefined : { fn, afterName: headLength + fn.length };
+};
+
+/** A declaration with a return type (`wrap(text: string): string[]`, `def f(x) -> str:`); a call has none. */
+export const signatureOf = (line: string, offset = 0): Signature | undefined => {
+  const declared = declaredAt(line);
+  if (declared === undefined) return undefined;
+  const open = declared.afterName + (GENERICS.exec(line.slice(declared.afterName))?.[0].length ?? 0);
+  const close = line[open] === "(" ? closingParen(line, open) : -1;
+  const mark = close === -1 ? null : RETURN_MARK.exec(line.slice(close + 1));
+  if (close === -1 || mark === null) return undefined;
+  const returns = withoutDeclarationTail(line.slice(close + 1 + mark[0].length));
+  return TYPE_TEXT.test(returns) ? { fn: declared.fn, params: squeeze(line.slice(open + 1, close)), returns, offset } : undefined;
+};
+
+const signaturesOf = (lines: readonly Line[]): Signature[] =>
+  lines.flatMap((line) => {
+    const lead = line.text.length - line.text.trimStart().length;
+    const signature = line.fenced ? signatureOf(line.text.trim(), line.start + lead) : undefined;
+    return signature === undefined ? [] : [signature];
+  });
+
+const escaped = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+
+const isSpaced = (word: string): boolean => /^[A-Za-z]/u.test(word);
+
+/** A word's occurrences: whole words where words are spaced, any occurrence where they are not. */
+const wordPattern = (word: string): RegExp => (isSpaced(word) ? new RegExp(String.raw`\b${escaped(word)}\b`, "giu") : new RegExp(escaped(word), "gu"));
+
+const startsWithWord = (text: string, word: string): boolean =>
+  isSpaced(word) ? new RegExp(String.raw`^${escaped(word)}\b`, "iu").test(text) : text.startsWith(word);
+
+/** "returns true when …" is a boolean: a literal says its kind in any language, in code or not. */
+const LITERAL_KINDS: ReadonlyMap<string, string> = new Map([
+  ["true", "boolean"],
+  ["false", "boolean"],
+]);
+
+/** Whether `word` stands in `text` as a whole value, not followed by a word making it one item (string per line). */
+const namesWhole = (text: string, word: string, items: readonly string[]): boolean =>
+  [...text.matchAll(wordPattern(word))].some((match) => {
+    const next = text.slice(match.index + match[0].length).trimStart();
+    return !items.some((item) => startsWithWord(next, item));
+  });
+
+/** The type words in a stretch of text, outside code spans other than a literal (`false`). */
+const typeWordsIn = (text: string, words: ReturnWords): [string, string][] => {
+  const bare = text.replace(/`([^`]*)`/gu, (_whole, inner: string) => (LITERAL_KINDS.has(inner.toLowerCase()) ? ` ${inner} ` : " "));
+  return [...words.kinds, ...LITERAL_KINDS].filter(([word]) => namesWhole(bare, word, words.items));
+};
+
+/** A language with no subject words (en) puts the verb right after the name, and a clause about when after the result. */
+const isVerbFirst = (words: ReturnWords): boolean => words.subjects.length === 0;
+
+/**
+ * The part of a statement that can name what is returned, without a clause about when (when …, …とき): before the first
+ * clause word where the verb comes first, after the last where the verb comes last.
+ */
+const returnedPart = (text: string, words: ReturnWords): string => {
+  const cuts = words.clauses.flatMap((word) =>
+    [...text.matchAll(wordPattern(word))].map((match) => ({ from: match.index, to: match.index + match[0].length })),
+  );
+  if (cuts.length === 0) return text;
+  return isVerbFirst(words) ? text.slice(0, Math.min(...cuts.map((cut) => cut.from))) : text.slice(Math.max(...cuts.map((cut) => cut.to)));
+};
+
+/** The one kind a stretch's type words name. */
+const kindIn = (text: string, returnWords: ReturnWords): Stated | undefined => {
+  const words = typeWordsIn(text, returnWords);
+  const named = new Set(words.map(([, kind]) => kind));
+  return named.size === 1 && words[0] !== undefined ? { kind: words[0][1], written: words[0][0] } : undefined;
+};
+
+/** What a stretch of text says is returned: one readable code span, else the one kind its type words name. */
+const statedIn = (text: string, words: ReturnWords): Stated | undefined => {
+  const trimmed = returnedPart(text, words).trim();
+  if (TYPE_TEXT.test(trimmed) && isReadableCode(trimmed)) return { code: trimmed, written: trimmed };
+  const spans = new Set([...trimmed.matchAll(/`([^`]+)`/gu)].map((match) => match[1] ?? "").filter(isReadableCode));
+  if (spans.size === 1) return { code: [...spans][0] ?? "", written: [...spans][0] ?? "" };
+  return spans.size === 0 ? kindIn(trimmed, words) : undefined;
+};
+
+const firstSentence = (text: string): string => text.split(SENTENCE_END)[0] ?? "";
+
+const lineOf = (lines: readonly Line[], offset: number): Line | undefined =>
+  lines.find((line) => line.start <= offset && offset <= line.start + line.text.length);
+
+/** The function each section's "Returns:" line is about: the one function its code blocks declare. */
+const sectionFunctions = (lines: readonly Line[], signatures: readonly Signature[]): Map<number, string> => {
+  const bySection = new Map<number, Set<string>>();
+  signatures.forEach((signature) => {
+    const section = lineOf(lines, signature.offset)?.section ?? -1;
+    bySection.set(section, (bySection.get(section) ?? new Set<string>()).add(signature.fn));
+  });
+  return new Map([...bySection].flatMap(([section, names]): [number, string][] => (names.size === 1 ? [[section, [...names].join("")]] : [])));
+};
+
+const labelPattern = (labels: readonly string[]): RegExp =>
+  new RegExp(String.raw`^[ \t]*(?:[-*+][ \t]+)?(?:\*\*|__)?(?:${labels.map(escaped).join("|")})(?:\*\*|__)?[ \t]*[:：](?:\*\*|__)?`, "iu");
+
+/** A "Returns:" line under a heading whose code blocks declare one function. */
+const labelStatements = (lines: readonly Line[], functions: ReadonlyMap<number, string>, words: ReturnWords): Statement[] => {
+  if (words.labels.length === 0) return [];
+  const label = labelPattern(words.labels);
+  return lines.flatMap((line) => {
+    const head = line.fenced ? null : label.exec(line.text);
+    const fn = functions.get(line.section);
+    if (head === null || fn === undefined) return [];
+    const stated = statedIn(firstSentence(line.text.slice(head[0].length)), words);
+    return stated === undefined ? [] : [{ fn, stated, offset: line.start }];
+  });
+};
+
+const cellsOf = (row: string): string[] => row.trim().replace(/^\|/u, "").replace(/\|$/u, "").split("|");
+
+const cellText = (cell: string): string => cell.trim().replace(/^(?:\*\*|__)(.*)(?:\*\*|__)$/u, "$1");
+
+/** The function a table row names in its first cell: `wrap`, wrap(), `measure(text)`. */
+const rowFunction = (cell: string): string => {
+  const name = cellText(cell).replace(/`/gu, "").trim();
+  const open = name.indexOf("(");
+  return name.endsWith(")") && open > 0 ? name.slice(0, open).trim() : name;
+};
+
+/** A table with a return column (Returns, 戻り値) whose rows name functions in their first cell. */
+const tableStatements = (lines: readonly Line[], known: ReadonlySet<string>, words: ReturnWords): Statement[] => {
+  const labels = new Set(words.labels.map((label) => label.toLowerCase()));
+  const state = { column: -1 };
+  return lines.flatMap((line, index) => {
+    if (line.fenced || !TABLE_ROW.test(line.text)) {
+      state.column = -1;
+      return [];
+    }
+    if (DELIMITER_ROW.test(line.text)) {
+      state.column = cellsOf(lines[index - 1]?.text ?? "").findIndex((cell) => labels.has(cellText(cell).toLowerCase()));
+      return [];
+    }
+    const cells = cellsOf(line.text);
+    const fn = rowFunction(cells[0] ?? "");
+    const stated = state.column > 0 && known.has(fn) ? statedIn(cells[state.column] ?? "", words) : undefined;
+    return stated === undefined ? [] : [{ fn, stated, offset: line.start }];
+  });
+};
+
+/** `measure returns …` / 「measure は … 返します」: the function's name, an optional subject word, then the verb. */
+const sentencePattern = (fn: string, words: ReturnWords): RegExp => {
+  const subject = words.subjects.length === 0 ? "" : String.raw`(?:(?:${words.subjects.map(escaped).join("|")})[、,]?)?`;
+  const verbs = words.verbs.map(escaped).join("|");
+  return new RegExp(String.raw`(?<![\w$.])\x60?${escaped(fn)}(?:\(\))?\x60?\s*${subject}([^。！？!?;]*?)(?:${verbs})(?![\p{L}\p{N}])`, "gu");
+};
+
+/** A sentence whose subject is a function's name and whose verb says it returns something. */
+const sentenceStatements = (lines: readonly Line[], known: ReadonlySet<string>, words: ReturnWords): Statement[] => {
+  if (words.verbs.length === 0) return [];
+  const prose = lines.filter((line) => !line.fenced && !HEADING.test(line.text) && !TABLE_ROW.test(line.text));
+  return [...known].flatMap((fn) =>
+    prose.flatMap((line) =>
+      [...line.text.matchAll(sentencePattern(fn, words))].flatMap((match) => {
+        const between = match[1] ?? "";
+        // Where the verb comes first, nothing stands between the name and the verb.
+        const verbFirst = isVerbFirst(words);
+        if (verbFirst && between.trim() !== "") return [];
+        const after = firstSentence(line.text.slice(match.index + match[0].length));
+        const stated = statedIn(verbFirst ? after : between, words);
+        return stated === undefined ? [] : [{ fn, stated, offset: line.start + match.index }];
+      }),
+    ),
+  );
+};
+
+const isSubset = (small: readonly string[], large: readonly string[]): boolean => small.every((member) => large.includes(member));
+
+/** Whether a statement can be the signature's return type; true when either side is too vague to say otherwise. */
+const agrees = (stated: Stated, returns: string): boolean => {
+  const members = typeMembers(returns);
+  if ("code" in stated) {
+    const said = typeMembers(stated.code);
+    return isSubset(said, members);
+  }
+  const kinds = members.filter((member) => !NOTHING_TYPES.has(member)).map(kindOfMember);
+  return kinds.includes(undefined) || kinds.includes(stated.kind);
+};
+
+const clashOf = (fn: string, stated: string, signature: Signature, offset: number): ReturnTypeClash => ({
+  fn,
+  stated,
+  signature: signature.returns,
+  offset,
+});
+
+/** Two declarations with the same parameters and different return types; overloads (other parameters) are left alone. */
+const signatureClashes = (signatures: readonly Signature[]): ReturnTypeClash[] =>
+  signatures.flatMap((later, index) => {
+    const earlier = signatures
+      .slice(0, index)
+      .find(
+        (signature) =>
+          signature.fn === later.fn && signature.params === later.params && typeMembers(signature.returns).join("|") !== typeMembers(later.returns).join("|"),
+      );
+    return earlier === undefined ? [] : [clashOf(later.fn, later.returns, earlier, later.offset)];
+  });
+
+/** Every place on the page that states a function's return type differently from all of the function's signatures. */
+export const returnTypeClashes = (source: string, words: ReturnWords): ReturnTypeClash[] => {
+  const lines = linesOf(source);
+  const signatures = signaturesOf(lines);
+  const known = new Set(signatures.map((signature) => signature.fn));
+  const statements = [
+    ...labelStatements(lines, sectionFunctions(lines, signatures), words),
+    ...tableStatements(lines, known, words),
+    ...sentenceStatements(lines, known, words),
+  ];
+  const statementClashes = statements.flatMap((statement) => {
+    const own = signatures.filter((signature) => signature.fn === statement.fn);
+    const first = own[0];
+    return first === undefined || own.some((signature) => agrees(statement.stated, signature.returns))
+      ? []
+      : [clashOf(statement.fn, statement.stated.written, first, statement.offset)];
+  });
+  return [...signatureClashes(signatures), ...statementClashes].toSorted((left, right) => left.offset - right.offset);
+};

package/src/rule-genres.ts

@@ -2,24 +2,27 @@ import type { Level, RuleDefinition } from "./plugin.ts";
 
 /**
  * How a rule stands in one genre, with no chaff.yaml: the same order of precedence as a run (use_for, then the genre's
- * preset, then the rule's status).
+ * preset, then opt_in, then the rule's status).
  *   unsuited:     the rule is not for this kind of document (use_for), and does not run
  *   genre-off:    the genre's preset turns it off
+ *   opt-in:       it runs only where chaff.yaml's style or rules give it a level
  *   experimental: it runs only with --experimental or a level in chaff.yaml
  *   on:           it runs, at this level
  */
 export type GenreStanding =
   | { readonly kind: "unsuited" }
   | { readonly kind: "genre-off" }
+  | { readonly kind: "opt-in" }
   | { readonly kind: "experimental" }
   | { readonly kind: "on"; readonly level: Exclude<Level, "off">; readonly byPreset: boolean };
 
-type RuleFacts = Pick<RuleDefinition, "id" | "status" | "use_for">;
+type RuleFacts = Pick<RuleDefinition, "id" | "status" | "use_for" | "opt_in">;
 
 export const standingIn = (rule: RuleFacts, genre: string, preset: Readonly<Record<string, Level>>): GenreStanding => {
   if (!rule.use_for.some((target) => genre.startsWith(target))) return { kind: "unsuited" };
   const fromPreset = preset[rule.id];
   if (fromPreset === "off") return { kind: "genre-off" };
   if (fromPreset !== undefined) return { kind: "on", level: fromPreset, byPreset: true };
+  if (rule.opt_in === true) return { kind: "opt-in" };
   return rule.status === "experimental" ? { kind: "experimental" } : { kind: "on", level: "normal", byPreset: false };
 };

package/src/rule-load.ts

@@ -105,10 +105,11 @@ const numberFor = (raw: unknown, language: string): number | undefined => {
 
 const stringList = (value: unknown): string[] | undefined => (Array.isArray(value) ? value.map((entry) => String(entry)) : undefined);
 
-/** What only some rules declare: options beyond the level, and token features the adapter computes on request. */
-const extrasOf = (raw: Record<string, unknown>, file: string): Pick<RuleDefinition, "options" | "token_features"> => ({
+/** What only some rules declare: options beyond the level, token features the adapter computes on request, and opt_in. */
+const extrasOf = (raw: Record<string, unknown>, file: string): Pick<RuleDefinition, "options" | "token_features" | "opt_in"> => ({
   ...(raw["options"] === undefined ? {} : { options: optionsOf(raw["options"], file) }),
   ...(raw["token_features"] === undefined ? {} : { token_features: stringList(raw["token_features"]) ?? [] }),
+  ...(raw["opt_in"] === true ? { opt_in: true } : {}),
 });
 
 /** The table flattenLevels reads, before its severities become numbers. */

package/src/run.ts

@@ -47,14 +47,16 @@ export const levelFor = (rule: RuleDefinition, settings: Settings, experimental:
   // ジャンルの既定は chaff.yaml より弱く、status の既定より強い。--experimental でも、ジャンルが止めたものは止めたまま。
   const fromPreset = preset[rule.id];
   if (fromPreset !== undefined) return fromPreset;
+  if (rule.opt_in === true) return "off";
   if (rule.status === "experimental" && !experimental) return "off";
   return "normal";
 };
 
-/** Why a rule at off did not run: chaff.yaml turned it off, the genre's preset did, or it is experimental. */
+/** Why a rule at off did not run: chaff.yaml turned it off, the genre's preset did, it waits for a style, or it is experimental. */
 const offSkip = (rule: RuleDefinition, settings: Settings, preset: Settings, genre: string, reasons: Reasons): Skipped => {
   if (settings[rule.id] !== undefined) return { rule: rule.id, why: reasons.turnedOff };
   if (preset[rule.id] !== undefined) return { rule: rule.id, why: reasons.presetOff(genre) };
+  if (rule.opt_in === true) return { rule: rule.id, why: reasons.optIn };
   return { rule: rule.id, why: reasons.experimental, offUntilExperimental: true };
 };
 

package/src/spelling.ts

@@ -79,3 +79,11 @@ export const wordsToCheck = (text: string, minLength: number, maxLength: number)
     )
     .map((match) => ({ offset: match.index, word: match[0] }));
 };
+
+/** 頭の字を強調（**G**lobally）や角括弧（引用を変えた [e]xpressions）で分けた語の残りの、直前の形。 */
+const SPLIT_HEAD = /(?:\p{L}[*_~]+|\[\p{L}\])$/u;
+/** 直前を見る字の数。強調の印と頭の字が収まればよい。 */
+const SPLIT_LOOKBACK = 8;
+
+/** source（Markdown のままの文書）の offset から始まる語が、頭の字を分けた語の残りか。 */
+export const isSplitWord = (source: string, offset: number): boolean => SPLIT_HEAD.test(source.slice(Math.max(0, offset - SPLIT_LOOKBACK), offset));