chaffjs 0.17.0 → 0.19.0

package/src/extension/plugin-load.ts

@@ -0,0 +1,82 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { CONFIG_FILE, type Config } from "../config/load.ts";
+import { modulePathOf } from "../custom/module-path.ts";
+import { loadGenres } from "../genre-load.ts";
+import { importDefault } from "./import-default.ts";
+import { staysInside } from "./real-path.ts";
+import { isPluginPath, pluginNameOfPackage } from "./plugin-name.ts";
+import { parsePlugin, type ParsedPlugin, type PluginOrigin, type PluginProblem } from "./plugin-parse.ts";
+
+// The plugins chaff.yaml lists under plugins:, found and loaded. A package is found from the folder chaff.yaml is in,
+// as Node finds it (node_modules); a path is the project's own plugin and, like a module rule, may not leave that
+// folder unless written as an absolute path. What cannot be found or read stops the run.
+
+export type LoadedPlugins = { readonly plugins: readonly ParsedPlugin[]; readonly problems: readonly PluginProblem[] };
+
+type Located = { readonly origin: PluginOrigin } | { readonly problem: PluginProblem };
+
+const problemOf = (kind: Exclude<PluginProblem["kind"], "rule">, plugin: string, detail = ""): { problem: PluginProblem } => ({
+  problem: { kind, plugin, detail },
+});
+
+/** The file Node would load for specifier from the folder chaff.yaml is in, or undefined when there is none. */
+const resolveFrom = (baseDir: string, specifier: string): string | undefined => {
+  try {
+    return createRequire(join(baseDir, CONFIG_FILE)).resolve(specifier);
+  } catch {
+    return undefined;
+  }
+};
+
+const locate = (written: string, baseDir: string): Located => {
+  if (isPluginPath(written)) {
+    const path = modulePathOf(written, baseDir);
+    if ("refusal" in path) return problemOf("outside", written);
+    const file = resolveFrom(baseDir, path.file);
+    if (file === undefined) return problemOf("not-found", written);
+    return staysInside(written, file, baseDir) ? { origin: { written, file, expectedName: undefined } } : problemOf("outside", written);
+  }
+  const expectedName = pluginNameOfPackage(written);
+  if (expectedName === undefined) return problemOf("bad-specifier", written);
+  const file = resolveFrom(baseDir, written);
+  return file === undefined ? problemOf("not-found", written) : { origin: { written, file, expectedName } };
+};
+
+const loadPlugin = async (written: string, baseDir: string, useFor: readonly string[]): Promise<LoadedPlugins> => {
+  const located = locate(written, baseDir);
+  if ("problem" in located) return { plugins: [], problems: [located.problem] };
+  const imported = await importDefault(located.origin.file);
+  if ("message" in imported) return { plugins: [], problems: [problemOf("import-failed", written, imported.message).problem] };
+  const read = parsePlugin(imported.exported, located.origin, useFor);
+  return { plugins: read.plugin === undefined ? [] : [read.plugin], problems: read.problems };
+};
+
+/** A second plugin with a name already taken is refused: its rules' ids would be the first one's. */
+const withoutDuplicates = (loaded: readonly { written: string; result: LoadedPlugins }[]): LoadedPlugins =>
+  loaded.reduce<{ plugins: ParsedPlugin[]; problems: PluginProblem[] }>(
+    (acc, { written, result }) => {
+      const taken = result.plugins.filter((plugin) => acc.plugins.some((seen) => seen.name === plugin.name));
+      return {
+        plugins: [...acc.plugins, ...result.plugins.filter((plugin) => !taken.includes(plugin))],
+        problems: [...acc.problems, ...result.problems, ...taken.map((plugin) => problemOf("duplicate-name", written, plugin.name).problem)],
+      };
+    },
+    { plugins: [], problems: [] },
+  );
+
+const isStringList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim() !== "");
+
+/** Every plugin chaff.yaml lists, loaded one by one in the order written. */
+export const loadPlugins = async (config: Pick<Config, "plugins" | "baseDir">): Promise<LoadedPlugins> => {
+  const written: unknown = config.plugins;
+  if (written === undefined || written === null) return { plugins: [], problems: [] };
+  if (!isStringList(written)) return { plugins: [], problems: [problemOf("not-a-list", "plugins", JSON.stringify(written) ?? "").problem] };
+  const useFor = loadGenres().groups.map((group) => group.id);
+  const loaded = await written.reduce<Promise<{ written: string; result: LoadedPlugins }[]>>(
+    async (done, entry) => [...(await done), { written: entry.trim(), result: await loadPlugin(entry.trim(), config.baseDir, useFor) }],
+    Promise.resolve([]),
+  );
+  return withoutDuplicates(loaded);
+};

package/src/extension/plugin-name.ts

@@ -0,0 +1,26 @@
+import { isAbsolute } from "node:path";
+
+// The names a plugin goes by. A package is chaff-plugin-<name> or @scope/chaff-plugin-<name>, and its rules are named
+// <name>/<rule> or @scope/<name>/<rule>, so they cannot take a built-in rule's id or another plugin's. Pure.
+
+/** A plugin's name, the prefix of its ids: foo, @scope/foo, or @scope for @scope/chaff-plugin. */
+const PLUGIN_NAME = /^(?:@[a-z0-9][a-z0-9._-]*(?:\/[a-z][a-z0-9-]*)?|[a-z][a-z0-9-]*)$/u;
+
+const PACKAGE = /^(?:(@[a-z0-9][a-z0-9._-]*)\/)?chaff-plugin(?:-([a-z][a-z0-9-]*))?$/u;
+
+/** A rule id as chaff.yaml, stet and baseline may write it: a built-in or team id, or a plugin's id with its prefix. */
+export const RULE_ID = /^(?:@[a-z0-9][a-z0-9._-]*\/)?(?:[a-z][a-z0-9-]*\/)?[a-z][a-z0-9-]*$/u;
+
+export const isPluginName = (name: string): boolean => PLUGIN_NAME.test(name);
+
+/** The name a plugin package must declare: chaff-plugin-foo → foo, @scope/chaff-plugin-foo → @scope/foo. undefined for a name that is not a plugin package's. */
+export const pluginNameOfPackage = (packageName: string): string | undefined => {
+  const match = PACKAGE.exec(packageName);
+  if (match === null) return undefined;
+  const [, scope, name] = match;
+  if (scope === undefined) return name;
+  return name === undefined ? scope : `${scope}/${name}`;
+};
+
+/** A path to a plugin of the project's own (./local-plugin), rather than a package's name. */
+export const isPluginPath = (written: string): boolean => written.startsWith(".") || isAbsolute(written);

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}`)]),