chaffjs 0.18.0 → 0.19.0

package/src/extension/plugin-parse.ts

@@ -0,0 +1,229 @@
+import { dirname } from "node:path";
+import { API_VERSION } from "../api.ts";
+import type { Lexicon, LexiconEntry, RuleDefinition } from "../plugin.ts";
+import { parseCustomRules, type CustomProblem } from "../custom/parse.ts";
+import { styleOf, type StyleDefinition } from "../style-parse.ts";
+import type { UntrustedDetector } from "./module-detector.ts";
+import { describeValue } from "./returned-findings.ts";
+import { isPluginName } from "./plugin-name.ts";
+
+// What a plugin package exports (api.ts PluginSpec), read into what chaff runs: its rules with ids under the plugin's
+// name, their detectors, its word lists and its house styles. A rule is read exactly like a rule in custom_rules, with
+// detect in place of type: module. Pure: the module comes in already imported.
+
+/** What can be wrong in finding and loading a plugin (plugin-load.ts), and in what it exports (here). */
+type PluginProblemKind =
+  | "not-a-list"
+  | "bad-specifier"
+  | "outside"
+  | "not-found"
+  | "import-failed"
+  | "duplicate-name"
+  | "bad-export"
+  | "no-api-version"
+  | "api-version"
+  | "bad-name"
+  | "name-mismatch"
+  | "no-detect"
+  | "bad-lexicon"
+  | "bad-style";
+
+/** plugin: as chaff.yaml writes it. detail: what was there instead, the name expected, the rule, list or style at fault. */
+export type PluginProblem =
+  | { readonly kind: PluginProblemKind; readonly plugin: string; readonly detail: string }
+  | { readonly kind: "rule"; readonly plugin: string; readonly problem: CustomProblem };
+
+/** Where a plugin came from: as chaff.yaml writes it, the file imported, and the name its package's name gives (none for a path). */
+export type PluginOrigin = { readonly written: string; readonly file: string; readonly expectedName: string | undefined };
+
+export type ParsedPlugin = {
+  readonly name: string;
+  /** The plugin as chaff.yaml writes it (chaff-plugin-foo, ./local-plugin), which a failing rule's reason names. */
+  readonly written: string;
+  readonly rules: readonly RuleDefinition[];
+  /** Each code rule's detector, by its id with the plugin's prefix. */
+  readonly detectors: Readonly<Record<string, UntrustedDetector>>;
+  /** Word lists by language, then by name with the plugin's prefix. */
+  readonly lexicons: Readonly<Record<string, Readonly<Record<string, Lexicon>>>>;
+  readonly styles: readonly StyleDefinition[];
+};
+
+export type PluginRead = { readonly plugin: ParsedPlugin | undefined; readonly problems: readonly PluginProblem[] };
+
+type Problem = (kind: Exclude<PluginProblem["kind"], "rule">, detail: string) => PluginProblem;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const printed = (value: unknown): string => JSON.stringify(value) ?? describeValue(value);
+
+/** A word list's or a style's own name, before the plugin's prefix. */
+const LOCAL_NAME = /^[a-z][a-z0-9-]*$/u;
+
+/** The plugin's name, checked against the name its package's name gives it. */
+const nameOf = (exported: Record<string, unknown>, origin: PluginOrigin, problem: Problem): { name: string } | { problem: PluginProblem } => {
+  const name = exported["name"];
+  if (typeof name !== "string" || !isPluginName(name)) return { problem: problem("bad-name", printed(name)) };
+  if (origin.expectedName !== undefined && name !== origin.expectedName) return { problem: problem("name-mismatch", origin.expectedName) };
+  return { name };
+};
+
+const versionProblem = (exported: Record<string, unknown>, problem: Problem): PluginProblem | undefined => {
+  const version = exported["apiVersion"];
+  if (version === undefined) return problem("no-api-version", "");
+  return version === API_VERSION ? undefined : problem("api-version", printed(version));
+};
+
+// ───────── rules ─────────
+
+const detectOf = (entry: Record<string, unknown>): UntrustedDetector | undefined => {
+  const detect = entry["detect"];
+  return typeof detect === "function" ? (doc, options): unknown => Reflect.apply(detect, undefined, [doc, options]) : undefined;
+};
+
+/** A rule with detect is read as a type: module rule whose module is the plugin's own file. */
+const asCustomRule = (entry: unknown, file: string): unknown =>
+  isRecord(entry) && detectOf(entry) !== undefined ? { ...entry, type: "module", module: file } : entry;
+
+/** Each code rule's detector by the id the plugin wrote. */
+const detectorsByWrittenId = (entries: readonly unknown[]): ReadonlyMap<string, UntrustedDetector> =>
+  new Map(
+    entries.flatMap((entry): [string, UntrustedDetector][] => {
+      const detect = isRecord(entry) ? detectOf(entry) : undefined;
+      return isRecord(entry) && typeof entry["id"] === "string" && detect !== undefined ? [[entry["id"], detect]] : [];
+    }),
+  );
+
+const withPrefix = (rule: RuleDefinition, name: string, lists: ReadonlySet<string>): RuleDefinition => ({
+  ...rule,
+  id: `${name}/${rule.id}`,
+  plugin: name,
+  word_list: rule.word_list !== undefined && lists.has(rule.word_list) ? `${name}/${rule.word_list}` : rule.word_list,
+});
+
+type RulesContext = { readonly name: string; readonly origin: PluginOrigin; readonly useFor: readonly string[]; readonly lists: ReadonlySet<string> };
+
+type Rules = Pick<ParsedPlugin, "rules" | "detectors"> & { readonly problems: readonly PluginProblem[] };
+
+const rulesOf = (raw: unknown, context: RulesContext): Rules => {
+  const { name, origin } = context;
+  const parsed = parseCustomRules(Array.isArray(raw) ? raw.map((entry: unknown) => asCustomRule(entry, origin.file)) : raw, {
+    builtIn: new Set(),
+    useFor: context.useFor,
+    baseDir: dirname(origin.file),
+  });
+  const detectors = detectorsByWrittenId(Array.isArray(raw) ? raw : []);
+  const runnable = parsed.rules.filter((rule) => rule.custom?.type !== "module" || detectors.has(rule.id));
+  const codeless = parsed.rules.filter((rule) => !runnable.includes(rule));
+  return {
+    rules: runnable.map((rule) => withPrefix(rule, name, context.lists)),
+    detectors: Object.fromEntries(
+      runnable.flatMap((rule) => {
+        const detect = detectors.get(rule.id);
+        return detect === undefined ? [] : [[`${name}/${rule.id}`, detect]];
+      }),
+    ),
+    problems: [
+      ...parsed.problems.map((problem): PluginProblem => ({ kind: "rule", plugin: origin.written, problem })),
+      ...codeless.map((rule): PluginProblem => ({ kind: "no-detect", plugin: origin.written, detail: rule.id })),
+    ],
+  };
+};
+
+// ───────── word lists ─────────
+
+const lexiconEntryOf = (value: unknown): LexiconEntry | undefined => {
+  if (typeof value === "string") return value.trim() === "" ? undefined : { pattern: value.trim() };
+  if (!isRecord(value) || typeof value["pattern"] !== "string" || value["pattern"].trim() === "") return undefined;
+  const insteadOf = value["instead_of"];
+  return { pattern: value["pattern"].trim(), ...(typeof insteadOf === "string" && insteadOf.trim() !== "" ? { instead_of: insteadOf.trim() } : {}) };
+};
+
+const lexiconOf = (words: unknown): Lexicon | undefined => {
+  const entries = Array.isArray(words) ? words.map(lexiconEntryOf) : [undefined];
+  const readable = entries.flatMap((entry) => (entry === undefined ? [] : [entry]));
+  return readable.length === entries.length ? readable : undefined;
+};
+
+type ListInLanguage = { readonly language: string; readonly list: string; readonly lexicon: Lexicon };
+
+/** One word list in each language it has. undefined when any part of it cannot be read. */
+const listOf = (list: string, raw: unknown): ListInLanguage[] | undefined => {
+  if (!LOCAL_NAME.test(list) || !isRecord(raw)) return undefined;
+  const read = Object.entries(raw).map(([language, words]) => ({ language, lexicon: lexiconOf(words) }));
+  const readable = read.flatMap(({ language, lexicon }) => (lexicon === undefined ? [] : [{ language, list, lexicon }]));
+  return readable.length === read.length ? readable : undefined;
+};
+
+type Lexicons = Pick<ParsedPlugin, "lexicons"> & { readonly lists: ReadonlySet<string>; readonly problems: readonly PluginProblem[] };
+
+const byLanguage = (lists: readonly ListInLanguage[], name: string): Record<string, Record<string, Lexicon>> =>
+  Object.fromEntries(
+    [...new Set(lists.map((entry) => entry.language))].map((language) => [
+      language,
+      Object.fromEntries(lists.filter((entry) => entry.language === language).map((entry) => [`${name}/${entry.list}`, entry.lexicon])),
+    ]),
+  );
+
+const lexiconsOf = (raw: unknown, name: string, problem: Problem): Lexicons => {
+  if (raw === undefined) return { lexicons: {}, lists: new Set(), problems: [] };
+  if (!isRecord(raw)) return { lexicons: {}, lists: new Set(), problems: [problem("bad-lexicon", printed(raw))] };
+  const read = Object.entries(raw).map(([list, words]) => ({ list, inLanguages: listOf(list, words) }));
+  const readable = read.flatMap((entry) => entry.inLanguages ?? []);
+  return {
+    lexicons: byLanguage(readable, name),
+    lists: new Set(readable.map((entry) => entry.list)),
+    problems: read.filter((entry) => entry.inLanguages === undefined).map((entry) => problem("bad-lexicon", entry.list)),
+  };
+};
+
+// ───────── styles ─────────
+
+/** One string reads the same in every language; a style's words need ja and en. */
+const bothLanguages = (value: unknown): unknown => (typeof value === "string" ? { ja: value, en: value } : value);
+
+const styleSpecOf = (raw: Record<string, unknown>, id: string, name: string): Record<string, unknown> => {
+  const source = isRecord(raw["source"]) ? { ...raw["source"], title: bothLanguages(raw["source"]["title"]) } : raw["source"];
+  return { ...raw, id: `${name}/${id}`, name: bothLanguages(raw["name"]), summary: bothLanguages(raw["summary"]), source };
+};
+
+const styleOrProblem = (entry: unknown, name: string, problem: Problem): { style: StyleDefinition } | { problem: PluginProblem } => {
+  const id = isRecord(entry) ? entry["id"] : undefined;
+  if (!isRecord(entry) || typeof id !== "string" || !LOCAL_NAME.test(id)) return { problem: problem("bad-style", printed(id)) };
+  try {
+    return { style: styleOf(styleSpecOf(entry, id, name), `${name}/${id}`) };
+  } catch (error) {
+    return { problem: problem("bad-style", error instanceof Error ? error.message : String(error)) };
+  }
+};
+
+type Styles = Pick<ParsedPlugin, "styles"> & { readonly problems: readonly PluginProblem[] };
+
+const stylesOf = (raw: unknown, name: string, problem: Problem): Styles => {
+  if (raw === undefined) return { styles: [], problems: [] };
+  if (!Array.isArray(raw)) return { styles: [], problems: [problem("bad-style", printed(raw))] };
+  const read = raw.map((entry: unknown) => styleOrProblem(entry, name, problem));
+  return {
+    styles: read.flatMap((entry) => ("style" in entry ? [entry.style] : [])),
+    problems: read.flatMap((entry) => ("problem" in entry ? [entry.problem] : [])),
+  };
+};
+
+// ───────── the plugin ─────────
+
+/** A plugin's default export, read. Every problem is reported; a plugin with any is left out whole, and the run is stopped. */
+export const parsePlugin = (exported: unknown, origin: PluginOrigin, useFor: readonly string[]): PluginRead => {
+  const problem: Problem = (kind, detail) => ({ kind, plugin: origin.written, detail });
+  if (!isRecord(exported)) return { plugin: undefined, problems: [problem("bad-export", describeValue(exported))] };
+  const version = versionProblem(exported, problem);
+  if (version !== undefined) return { plugin: undefined, problems: [version] };
+  const named = nameOf(exported, origin, problem);
+  if ("problem" in named) return { plugin: undefined, problems: [named.problem] };
+  const { name } = named;
+  const lexicons = lexiconsOf(exported["lexicons"], name, problem);
+  const rules = rulesOf(exported["rules"], { name, origin, useFor, lists: lexicons.lists });
+  const styles = stylesOf(exported["styles"], name, problem);
+  const problems = [...rules.problems, ...lexicons.problems, ...styles.problems];
+  if (problems.length > 0) return { plugin: undefined, problems };
+  const plugin = { name, written: origin.written, rules: rules.rules, detectors: rules.detectors, lexicons: lexicons.lexicons, styles: styles.styles };
+  return { plugin, problems: [] };
+};

package/src/extension/problem-text.ts

@@ -0,0 +1,103 @@
+import { API_VERSION } from "../api.ts";
+import type { Config } from "../config/load.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
+import { customProblemSentence } from "../custom/problems.ts";
+import type { LoadProblem } from "./load.ts";
+import type { PluginProblem } from "./plugin-parse.ts";
+
+// What in the code chaff.yaml names could not be loaded, as sentences. Each names the rule or plugin and the file or
+// package, as chaff.yaml writes it.
+
+type ModuleText = Readonly<Record<LoadProblem["kind"], (rule: string, file: string, detail: string) => string>>;
+
+type PluginText = {
+  readonly problems: Readonly<Record<Exclude<PluginProblem["kind"], "rule">, (plugin: string, detail: string) => string>>;
+  /** Where a plugin's rule is, for a problem a rule in custom_rules could have too. */
+  readonly ruleScope: (plugin: string) => string;
+};
+
+const API = String(API_VERSION);
+
+const MODULE_TEXT: Texts<ModuleText> = {
+  ja: {
+    "missing-file": (rule, file) => `custom_rules の ${rule}: module のファイル ${file} がありません`,
+    outside: (rule, file) =>
+      `custom_rules の ${rule}: ${file} はリンクをたどると chaff.yaml のあるフォルダの外です。読み込むとそのコードが動くので、外のファイルは絶対パスで名指ししてください`,
+    "import-failed": (rule, file, detail) => `custom_rules の ${rule}: ${file} を読み込めませんでした（${detail}）`,
+    "bad-export": (rule, file, detail) =>
+      `custom_rules の ${rule}: ${file} の default export が検出器ではありません（${detail}）。関数か defineRule({ detect }) を export default してください`,
+    "api-version": (rule, file, detail) => `custom_rules の ${rule}: ${file} はプラグイン API ${detail} 向けです。この chaff のプラグイン API は ${API} です`,
+  },
+  en: {
+    "missing-file": (rule, file) => `custom_rules ${rule}: the module file ${file} does not exist`,
+    outside: (rule, file) =>
+      `custom_rules ${rule}: ${file} leads outside the folder chaff.yaml is in through a link. Loading a module runs its code, so name a file outside by its absolute path`,
+    "import-failed": (rule, file, detail) => `custom_rules ${rule}: cannot load ${file} (${detail})`,
+    "bad-export": (rule, file, detail) =>
+      `custom_rules ${rule}: the default export of ${file} is not a detector (${detail}); export default a function or defineRule({ detect })`,
+    "api-version": (rule, file, detail) => `custom_rules ${rule}: ${file} was written for plugin API ${detail}; this chaff has plugin API ${API}`,
+  },
+};
+
+const PLUGIN_TEXT: Texts<PluginText> = {
+  ja: {
+    ruleScope: (plugin) => `plugins の ${plugin} の rules`,
+    problems: {
+      "not-a-list": (_plugin, detail) => `plugins はプラグインの並び（- chaff-plugin-foo や - ./local-plugin）で書いてください（${detail}）`,
+      "bad-specifier": (plugin) =>
+        `plugins の ${plugin}: パッケージは chaff-plugin-<名前> か @scope/chaff-plugin-<名前> の名前で、手元のプラグインは ./ で始まるパスで書いてください`,
+      outside: (plugin) =>
+        `plugins の ${plugin}: chaff.yaml のあるフォルダの外です。読み込むとそのコードが動くので、外のプラグインは絶対パスで名指ししてください`,
+      "not-found": (plugin) => `plugins の ${plugin}: 見つかりません。パッケージなら chaff.yaml のあるフォルダで yarn add ${plugin} を実行してください`,
+      "import-failed": (plugin, detail) => `plugins の ${plugin}: 読み込めませんでした（${detail}）`,
+      "duplicate-name": (plugin, detail) => `plugins の ${plugin}: 名前 ${detail} のプラグインがもう一つあります`,
+      "bad-export": (plugin, detail) =>
+        `plugins の ${plugin}: default export がプラグインではありません（${detail}）。definePlugin({ name, rules }) を export default してください`,
+      "no-api-version": (plugin) => `plugins の ${plugin}: 向けているプラグイン API がありません。definePlugin で作ると付きます`,
+      "api-version": (plugin, detail) => `plugins の ${plugin}: プラグイン API ${detail} 向けです。この chaff のプラグイン API は ${API} です`,
+      "bad-name": (plugin, detail) =>
+        `plugins の ${plugin}: name: ${detail} はプラグインの名前として読めません（英小文字・数字・ハイフン。@scope/ を付けてもよい）`,
+      "name-mismatch": (plugin, detail) => `plugins の ${plugin}: name は ${detail} にしてください（パッケージの名前から決まります）`,
+      "no-detect": (plugin, detail) => `plugins の ${plugin}: ルール ${detail} に detect がありません`,
+      "bad-lexicon": (plugin, detail) => `plugins の ${plugin}: 語彙表 ${detail} が読めません（名前: { ja: [語, …], en: [語, …] }）`,
+      "bad-style": (plugin, detail) => `plugins の ${plugin}: スタイルが読めません（${detail}）`,
+    },
+  },
+  en: {
+    ruleScope: (plugin) => `plugins ${plugin} rules`,
+    problems: {
+      "not-a-list": (_plugin, detail) => `write plugins as a list (- chaff-plugin-foo or - ./local-plugin), not ${detail}`,
+      "bad-specifier": (plugin) =>
+        `plugins ${plugin}: name a package chaff-plugin-<name> or @scope/chaff-plugin-<name>, and a plugin of your own by a path starting with ./`,
+      outside: (plugin) =>
+        `plugins ${plugin}: it is outside the folder chaff.yaml is in. Loading a plugin runs its code, so name one outside by its absolute path`,
+      "not-found": (plugin) => `plugins ${plugin}: not found. For a package, run yarn add ${plugin} in the folder chaff.yaml is in`,
+      "import-failed": (plugin, detail) => `plugins ${plugin}: cannot load it (${detail})`,
+      "duplicate-name": (plugin, detail) => `plugins ${plugin}: another plugin is named ${detail}`,
+      "bad-export": (plugin, detail) => `plugins ${plugin}: the default export is not a plugin (${detail}); export default definePlugin({ name, rules })`,
+      "no-api-version": (plugin) => `plugins ${plugin}: it does not say which plugin API it was written for; definePlugin adds that`,
+      "api-version": (plugin, detail) => `plugins ${plugin}: it was written for plugin API ${detail}; this chaff has plugin API ${API}`,
+      "bad-name": (plugin, detail) =>
+        `plugins ${plugin}: cannot read name: ${detail} as a plugin's name (lowercase letters, digits and hyphens, with an optional @scope/)`,
+      "name-mismatch": (plugin, detail) => `plugins ${plugin}: its name must be ${detail}, which the package's name gives`,
+      "no-detect": (plugin, detail) => `plugins ${plugin}: the rule ${detail} has no detect`,
+      "bad-lexicon": (plugin, detail) => `plugins ${plugin}: cannot read the word list ${detail} (name: { ja: [word, …], en: [word, …] })`,
+      "bad-style": (plugin, detail) => `plugins ${plugin}: cannot read a style (${detail})`,
+    },
+  },
+};
+
+const pluginSentence = (problem: PluginProblem, ui: UiLanguage): string => {
+  const text = PLUGIN_TEXT[ui];
+  if (problem.kind === "rule") return customProblemSentence(problem.problem, ui, text.ruleScope(problem.plugin));
+  return text.problems[problem.kind](problem.plugin, problem.detail);
+};
+
+/** What chaff.yaml names in code that could not be loaded: type: module rules, then plugins. Each stops the run. */
+export const extensionProblems = (config: Pick<Config, "extensions" | "path">, ui: UiLanguage): string[] => {
+  const where = `chaff: ${config.path ?? "chaff.yaml"}`;
+  return [
+    ...(config.extensions?.problems ?? []).map((problem) => `${where}: ${MODULE_TEXT[ui][problem.kind](problem.rule, problem.file, problem.detail)}`),
+    ...(config.extensions?.pluginProblems ?? []).map((problem) => `${where}: ${pluginSentence(problem, ui)}`),
+  ];
+};

package/src/extension/real-path.ts

@@ -0,0 +1,10 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { isInside } from "../custom/module-path.ts";
+
+// The path check of custom/module-path.ts reads only the path as written, so a symbolic link inside the project can
+// still point outside it. Before code is loaded, the same check runs on the real paths.
+
+/** Whether a file written as a relative path is really inside baseDir once links are followed. An absolute path was written on purpose. */
+export const staysInside = (written: string, file: string, baseDir: string): boolean =>
+  isAbsolute(written) || isInside(realpathSync(baseDir), realpathSync(file));

package/src/extension/returned-findings.ts

@@ -0,0 +1,62 @@
+import type { Finding, Sentence } from "../plugin.ts";
+
+// What a plugin's detector returned, checked and turned into chaff's findings. Anything else than a list of
+// { start, end?, values? } inside the document is refused as a whole, with what was wrong: a rule that half works
+// would report some places and silently drop others. Pure.
+
+/** What was wrong, at which finding (from 1; 0 for the whole return), and what was there instead. */
+export type ShapeProblem = {
+  readonly kind: "not-a-list" | "not-a-finding" | "bad-start" | "bad-end" | "bad-values";
+  readonly index: number;
+  readonly written: string;
+};
+
+export type Returned = { readonly findings: readonly Finding[] } | { readonly problem: ShapeProblem };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** What came back instead of a list, in a few words: "a Promise", "undefined", "an object". */
+export const describeValue = (value: unknown): string => {
+  if (value === null || value === undefined) return String(value);
+  if (value instanceof Promise) return "a Promise";
+  if (Array.isArray(value)) return "a list";
+  return typeof value === "object" ? "an object" : `a ${typeof value}`;
+};
+
+const isOffsetIn = (value: unknown, low: number, high: number): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value >= low && value <= high;
+
+const isValue = (value: unknown): value is string | number => typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+
+const printed = (value: unknown): string => JSON.stringify(value) ?? String(value);
+
+/** The sentence the finding is in, or the line when it is in none (a heading, a table). */
+const quoteAt = (source: string, sentences: readonly Sentence[], offset: number): string => {
+  const sentence = sentences.find((entry) => entry.span.start <= offset && offset < entry.span.end);
+  if (sentence !== undefined) return sentence.text.trim();
+  const lineStart = source.lastIndexOf("\n", offset - 1) + 1;
+  const lineEnd = source.indexOf("\n", offset);
+  return source.slice(lineStart, lineEnd === -1 ? source.length : lineEnd).trim();
+};
+
+type Checked = { readonly finding: Finding } | { readonly problem: ShapeProblem };
+
+const checkedFinding = (entry: unknown, index: number, source: string, sentences: readonly Sentence[]): Checked => {
+  if (!isRecord(entry)) return { problem: { kind: "not-a-finding", index, written: describeValue(entry) } };
+  const { start, end = start, values = {} } = entry;
+  if (!isOffsetIn(start, 0, source.length)) return { problem: { kind: "bad-start", index, written: printed(start) } };
+  if (!isOffsetIn(end, start, source.length)) return { problem: { kind: "bad-end", index, written: printed(end) } };
+  if (!isRecord(values) || !Object.values(values).every(isValue)) return { problem: { kind: "bad-values", index, written: printed(values) } };
+  const filled = { matched: source.slice(start, end), ...values, offset: start };
+  return { finding: { rule: "", severity: "warning", line: 0, column: 0, quote: quoteAt(source, sentences, start), values: filled } };
+};
+
+/** The findings a detector returned, placed in the document, or the first thing wrong with them. index counts from 1. */
+export const returnedFindings = (returned: unknown, source: string, sentences: readonly Sentence[]): Returned => {
+  if (!Array.isArray(returned)) return { problem: { kind: "not-a-list", index: 0, written: describeValue(returned) } };
+  // Array.from reads a hole in a sparse list as undefined, so it is refused rather than skipped.
+  const checked = Array.from(returned, (entry: unknown, at) => checkedFinding(entry, at + 1, source, sentences));
+  const wrong = checked.find((entry) => "problem" in entry);
+  if (wrong !== undefined && "problem" in wrong) return { problem: wrong.problem };
+  return { findings: checked.flatMap((entry) => ("finding" in entry ? [entry.finding] : [])) };
+};

package/src/extension/rule-export.ts

@@ -0,0 +1,23 @@
+import { API_VERSION } from "../api.ts";
+import { describeValue } from "./returned-findings.ts";
+import type { UntrustedDetector } from "./module-detector.ts";
+
+// What a type: module file exports, read as a detector. The default export is the detector itself, or a rule made with
+// defineRule ({ apiVersion, detect }). A function carries no version and is read against this chaff's API; a rule that
+// names another version is refused, since its detector expects another document. Pure.
+
+/** bad-export: detail says what was exported instead. api-version: detail is the version the rule names. */
+export type ExportProblem = { readonly kind: "bad-export" | "api-version"; readonly detail: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isDetector = (value: unknown): value is UntrustedDetector => typeof value === "function";
+
+/** The detector a module's default export gives, or what is wrong with it. */
+export const detectorExport = (exported: unknown): { readonly detect: UntrustedDetector } | { readonly problem: ExportProblem } => {
+  if (isDetector(exported)) return { detect: exported };
+  if (!isRecord(exported) || !isDetector(exported["detect"])) return { problem: { kind: "bad-export", detail: describeValue(exported) } };
+  const version = exported["apiVersion"];
+  if (version !== undefined && version !== API_VERSION) return { problem: { kind: "api-version", detail: JSON.stringify(version) ?? describeValue(version) } };
+  return { detect: exported["detect"] };
+};

package/src/feedback/draft.ts

@@ -12,6 +12,8 @@ export type FeedbackInput = {
   readonly fileName: string;
   readonly language: string;
   readonly genre: string;
+  /** How the check was run (--experimental, --genre …), so the reader can run the same check. */
+  readonly conditions: readonly string[];
   readonly findings: readonly ReportedFinding[];
   /** The line the person reported: the finding's line, or for a miss the line they named. */
   readonly line: number;
@@ -26,6 +28,7 @@ const TEXT: Texts<{
   readonly titleMissed: (fileName: string, line: number) => string;
   readonly what: Readonly<Record<FeedbackKind, string>>;
   readonly environment: string;
+  readonly ranWith: string;
   readonly findings: string;
   readonly excerpt: string;
   readonly config: string;
@@ -38,6 +41,7 @@ const TEXT: Texts<{
     titleMissed: (fileName, line) => `見逃し: ${fileName} の ${String(line)} 行目`,
     what: { "false-positive": "この指摘は誤りだと思います。", missed: "ここで chaff は何か言うべきだと思います。" },
     environment: "環境",
+    ranWith: "実行の条件",
     findings: "指摘",
     excerpt: "文書の該当箇所（この部分だけを載せています）",
     config: "chaff.yaml",
@@ -53,6 +57,7 @@ const TEXT: Texts<{
     titleMissed: (fileName, line) => `Missed: ${fileName} line ${String(line)}`,
     what: { "false-positive": "I think this finding is wrong.", missed: "I think chaff should say something here." },
     environment: "Environment",
+    ranWith: "Run with",
     findings: "Findings",
     excerpt: "The part of the document (only these lines are included)",
     config: "chaff.yaml",
@@ -85,6 +90,7 @@ export const feedbackDraft = (input: FeedbackInput, ui: UiLanguage): FeedbackDra
     `- chaffjs ${input.version}`,
     `- ${input.runtime}`,
     `- ${input.fileName} · ${input.language} · ${input.genre}`,
+    ...(input.conditions.length === 0 ? [] : [`- ${text.ranWith}: ${input.conditions.join(" ")}`]),
     ...(input.findings.length === 0
       ? []
       : ["", `## ${text.findings}`, "", ...input.findings.map((finding) => `- \`${finding.rule}\` (${String(finding.line)}): ${finding.message}`)]),

package/src/figure-references.ts

@@ -1,5 +1,6 @@
 import { escapeRegExp } from "./orthography.ts";
-import type { Span } from "./plugin.ts";
+import { lowerBound } from "./detectors/token-column.ts";
+import type { DocumentNamer, Span } from "./plugin.ts";
 
 /**
  * 本文で番号を指した図・表・付録（図3、Table 2、Appendix B）と、それを行の頭に書いた所（キャプション、見出し）。
@@ -27,17 +28,22 @@ type Mention = { readonly start: number; readonly end: number; readonly written:
 /** 語の前の字が漢字・カタカナ・英数字なら、長い語の一部（地図3、一覧表2、法別表第二、SubFigure）。 */
 const INSIDE_WORD = "(?<![\\p{Script=Han}\\p{Script=Katakana}\\p{N}A-Za-z])";
 /** 番号。数字（3、3.2、第3）、「第」の後の漢数字（別表第一）、大文字一つかローマ数字（Appendix B、Annex II）。 */
-const NUMBER = "[ \\t\\u00a0]?(?:第?(\\p{Nd}+(?:[.\\-－]\\p{Nd}+)*)|第([一二三四五六七八九十百]+)|([IVX]{2,5}|[A-ZＡ-Ｚ])(?![A-Za-z]))";
+export const FIGURE_NUMBER = "[ \\t\\u00a0]?(?:第?(\\p{Nd}+(?:[.\\-－]\\p{Nd}+)*)|第([一二三四五六七八九十百]+)|([IVX]{2,5}|[A-ZＡ-Ｚ])(?![A-Za-z]))";
 
 const forms = (word: string): string[] => [...new Set([word, word.toUpperCase()])];
 
-const mentionPattern = (labels: readonly LabelWord[]): RegExp => {
-  const words = labels
+const labelAlternation = (labels: readonly LabelWord[]): string =>
+  labels
     .flatMap((label) => forms(label.word))
     .toSorted((a, b) => b.length - a.length)
-    .map(escapeRegExp);
-  return new RegExp(`${INSIDE_WORD}(${words.join("|")})${NUMBER}`, "gu");
-};
+    .map(escapeRegExp)
+    .join("|");
+
+const mentionPattern = (labels: readonly LabelWord[]): RegExp => new RegExp(`${INSIDE_WORD}(${labelAlternation(labels)})${FIGURE_NUMBER}`, "gu");
+
+/** 番号の付いた図か、番号の無い図（「…の別表に」）。番号が無ければ後ろが長い語の続きでない（表示、別表第一の「第」は番号）。 */
+const labelPattern = (labels: readonly LabelWord[]): RegExp =>
+  new RegExp(`${INSIDE_WORD}(${labelAlternation(labels)})(?:${FIGURE_NUMBER}|(?![\\p{Script=Han}\\p{Script=Katakana}A-Za-z]))`, "gu");
 
 const kindOf = (written: string, labels: readonly LabelWord[]): string => labels.find((label) => forms(label.word).includes(written))?.kind ?? written;
 
@@ -95,18 +101,73 @@ const pointsHere = (text: string, mention: Mention, words: LabelWords): boolean
   return !elsewhere && !words.counters.some((word) => after.startsWith(word));
 };
 
+/** 行の頭に書いた番号（キャプションや見出し）。図の置き場所。 */
+const labelledIn = (source: string, labels: readonly LabelWord[]): Mention[] => mentionsIn(source, labels).filter((mention) => isLabelled(source, mention));
+
+/** 文書が行の頭に番号を書いている種類（図、Table）。番号で名指しできる種類。 */
+export const labelledKindsIn = (source: string, words: LabelWords): ReadonlySet<string> =>
+  new Set(labelledIn(source, words.labels).map((mention) => mention.kind));
+
+/** 文書の名前を読む言語の知識と、その名前が届く範囲（文）。 */
+export type Citations = { readonly namedDocument: DocumentNamer; readonly sentences: readonly Span[] };
+
+type NamedLabel = { readonly start: number; readonly kind: string; readonly self: boolean };
+
+/** 文書の名前のすぐ後ろに書いた図の語（「…(平成二十年厚生労働省告示第五十九号)別表第一」「…号)の別表」「この規則の別表第三」）。 */
+const namedLabelsIn = (prose: string, labels: readonly LabelWord[], namedDocument: DocumentNamer): NamedLabel[] =>
+  [...prose.matchAll(labelPattern(labels))].flatMap((match) => {
+    const named = namedDocument(prose, match.index);
+    return named === undefined ? [] : [{ start: match.index, kind: kindOf(match[1] ?? "", labels), self: named.self }];
+  });
+
+/** offset を含む文の頭。文の外（見出し）なら offset。文は文書の順に並んでいる。 */
+const sentenceStartAt = (sentences: readonly Span[], starts: readonly number[], offset: number): number => {
+  const sentence = sentences[lowerBound(starts, offset + 1) - 1];
+  return sentence !== undefined && offset < sentence.end ? sentence.start : offset;
+};
+
+/**
+ * 他の文書の図か。同じ文の中で、その番号の位置までに名前を添えて書いた同じ種類の図のうち、いちばん近いものが他の文書のもの。
+ * 「(…告示第五十九号)別表第一…及び別表第二」「…別表第一から別表第三まで」の後ろの番号も、その告示の別表。
+ * 「…手数料規則の別表第二により、この規則の別表第三による」の別表第三は、この文書のものと名指している。
+ * 文と名前の位置は二分探索で引く。参照先の無い番号が何万あっても、文書の長さの二乗にしない。
+ */
+const citedElsewhere = (named: readonly NamedLabel[], sentences: readonly Span[]): ((mention: Mention) => boolean) => {
+  const starts = sentences.map((sentence) => sentence.start);
+  const byKind = new Map(
+    [...new Set(named.map((label) => label.kind))].map((kind) => {
+      const labels = named.filter((label) => label.kind === kind);
+      return [kind, { labels, starts: labels.map((label) => label.start) }];
+    }),
+  );
+  return (mention) => {
+    const ofKind = byKind.get(mention.kind);
+    const nearest = ofKind?.labels[lowerBound(ofKind.starts, mention.start + 1) - 1];
+    return nearest !== undefined && !nearest.self && nearest.start >= sentenceStartAt(sentences, starts, mention.start);
+  };
+};
+
 /**
  * 参照先の無い番号。source は行の頭を読み、prose（コードを覆った本文）は参照を読む。位置は同じ。
  * 番号は、キャプションが 1 と書けば 1a や 1(b) の参照も 1 に当たる（番号の後ろの字は読まない）。
  * リンクの字（[Figure 2](figures.md)）は、そのリンクが行き先を持つので参照として見ない。
  */
-export const danglingFigures = (source: string, prose: string, words: LabelWords, links: readonly Span[] = []): DanglingFigure[] => {
+export const danglingFigures = (
+  source: string,
+  prose: string,
+  words: LabelWords,
+  links: readonly Span[] = [],
+  citations: Citations | undefined = undefined,
+): DanglingFigure[] => {
   if (words.labels.length === 0) return [];
-  const labelled = mentionsIn(source, words.labels).filter((mention) => isLabelled(source, mention));
+  const labelled = labelledIn(source, words.labels);
   const labelledKeys = new Set(labelled.map((mention) => mention.key));
   const labelledKinds = new Set(labelled.map((mention) => mention.kind));
-  return mentionsIn(prose, words.labels)
+  const dangling = mentionsIn(prose, words.labels)
     .filter((mention) => labelledKinds.has(mention.kind) && !labelledKeys.has(mention.key))
-    .filter((mention) => pointsHere(prose, mention, words) && !links.some((link) => link.start <= mention.start && mention.end <= link.end))
-    .map((mention) => ({ offset: mention.start, label: mention.written }));
+    .filter((mention) => pointsHere(prose, mention, words) && !links.some((link) => link.start <= mention.start && mention.end <= link.end));
+  // 他の文書の名前は、参照先の無い番号があるときだけ読む。図の語のたびに名前を後ろ向きに読む代金を、ふつうの文書に払わせない。
+  const named = dangling.length === 0 || citations === undefined ? [] : namedLabelsIn(prose, words.labels, citations.namedDocument);
+  const elsewhere = named.length === 0 || citations === undefined ? () => false : citedElsewhere(named, citations.sentences);
+  return dangling.filter((mention) => !elsewhere(mention)).map((mention) => ({ offset: mention.start, label: mention.written }));
 };

package/src/finding-order.ts

@@ -0,0 +1,3 @@
+/** 指摘を文書の中の位置の順に並べる。同じ行では桁の順。rule ごとの並びを残さない。 */
+export const byPosition = (left: { readonly line: number; readonly column: number }, right: { readonly line: number; readonly column: number }): number =>
+  left.line - right.line || left.column - right.column;

package/src/fix-plan/mode.ts

@@ -0,0 +1,34 @@
+/**
+ * Which of the three ways to rewrite (the guide's Light, Bold and Full) chaff recommends, from what it found alone.
+ * A request that says "from scratch" also means Full; chaff cannot read the request, so the plan says so in words.
+ */
+export type FixMode = "none" | "light" | "bold" | "full";
+
+/** Why the mode was chosen, so the plan can say it. */
+export type ModeReason = "nothing-found" | "composite" | "genre" | "signals" | "spots";
+
+export type ModeChoice = { readonly mode: FixMode; readonly reason: ModeReason };
+
+export type ModeInput = {
+  readonly genre: string;
+  /** The rules with at least one finding. */
+  readonly firedRules: ReadonlySet<string>;
+  /** The rules that measure the whole document: ai-generated-composite's inputs and bold-density. */
+  readonly signalRules: ReadonlySet<string>;
+};
+
+export const COMPOSITE_RULE = "ai-generated-composite";
+
+/** Two document-wide signals mean the prose of the sections is the problem, not a spot or two. */
+const MIN_SIGNALS_FOR_BOLD = 2;
+
+/** A blog post or an essay is rewritten from its structure up: what the writer wants changed there is the structure. */
+const isFreeFormGenre = (genre: string): boolean => genre.startsWith("blog/") || genre === "literature/essay";
+
+export const recommendMode = (input: ModeInput): ModeChoice => {
+  if (input.firedRules.size === 0) return { mode: "none", reason: "nothing-found" };
+  if (input.firedRules.has(COMPOSITE_RULE)) return { mode: "full", reason: "composite" };
+  if (isFreeFormGenre(input.genre)) return { mode: "full", reason: "genre" };
+  const signals = [...input.firedRules].filter((rule) => input.signalRules.has(rule)).length;
+  return signals >= MIN_SIGNALS_FOR_BOLD ? { mode: "bold", reason: "signals" } : { mode: "light", reason: "spots" };
+};