chaffjs 0.18.0 → 0.20.0

package/src/extension/import-default.ts

@@ -0,0 +1,13 @@
+import { pathToFileURL } from "node:url";
+
+const firstLine = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+
+/** A module's default export, or the first line of why it could not be imported (a syntax error, a missing import). Running it runs its code. */
+export const importDefault = async (file: string): Promise<{ readonly exported: unknown } | { readonly message: string }> => {
+  try {
+    const namespace: unknown = await import(pathToFileURL(file).href);
+    return { exported: typeof namespace === "object" && namespace !== null && "default" in namespace ? namespace.default : undefined };
+  } catch (error) {
+    return { message: firstLine(error) };
+  }
+};

package/src/extension/load.ts

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import type { Config } from "../config/load.ts";
+import type { Detector, Lexicon, RuleDefinition } from "../plugin.ts";
+import type { StyleDefinition } from "../style-parse.ts";
+import { customRulesOf } from "../custom/load.ts";
+import { withStyle } from "../config/style.ts";
+import { moduleDetector } from "./module-detector.ts";
+import { detectorExport, type ExportProblem } from "./rule-export.ts";
+import { importDefault } from "./import-default.ts";
+import { loadPlugins } from "./plugin-load.ts";
+import type { ParsedPlugin, PluginProblem } from "./plugin-parse.ts";
+import { staysInside } from "./real-path.ts";
+
+// The code chaff.yaml names, loaded once before anything runs: each type: module rule's file, and each plugin under
+// plugins:. Loading runs that code, which is why only chaff.yaml can name it. What cannot be loaded stops the run
+// (settingProblems), like a rule in custom_rules that cannot be read: a rule that silently does not run looks like a clean document.
+
+/** A rule whose file could not be loaded. file is the path as chaff.yaml writes it; detail: why, or what ExportProblem says. */
+export type LoadProblem = {
+  readonly kind: "missing-file" | "outside" | "import-failed" | ExportProblem["kind"];
+  readonly rule: string;
+  readonly file: string;
+  readonly detail: string;
+};
+
+/** What was loaded, and what could not be. */
+export type Extensions = {
+  /** The detector of each type: module rule and each plugin rule written in code, by the rule's id. */
+  readonly detectors: Readonly<Record<string, Detector>>;
+  /** The plugins' rules, with their ids under each plugin's name. */
+  readonly rules: readonly RuleDefinition[];
+  /** The plugins' word lists by language, then by name. */
+  readonly lexicons: Readonly<Record<string, Readonly<Record<string, Lexicon>>>>;
+  /** The plugins' house styles. */
+  readonly styles: readonly StyleDefinition[];
+  readonly problems: readonly LoadProblem[];
+  readonly pluginProblems: readonly PluginProblem[];
+};
+
+type Loaded = { readonly detector: Detector } | { readonly problem: LoadProblem };
+
+/** A type: module rule: its id, its file, and the path as chaff.yaml writes it, which every message names. */
+type ModuleRule = { readonly id: string; readonly file: string; readonly written: string };
+
+const loadRule = async ({ id, file, written }: ModuleRule, baseDir: string): Promise<Loaded> => {
+  const at = { rule: id, file: written };
+  if (!existsSync(file)) return { problem: { ...at, kind: "missing-file", detail: "" } };
+  if (!staysInside(written, file, baseDir)) return { problem: { ...at, kind: "outside", detail: "" } };
+  const imported = await importDefault(file);
+  if ("message" in imported) return { problem: { ...at, kind: "import-failed", detail: imported.message } };
+  const read = detectorExport(imported.exported);
+  return "problem" in read ? { problem: { ...at, ...read.problem } } : { detector: moduleDetector(read.detect, written) };
+};
+
+const moduleRulesOf = (rules: readonly RuleDefinition[]): ModuleRule[] =>
+  rules.flatMap((rule) => (rule.custom?.type === "module" ? [{ id: rule.id, file: rule.custom.file, written: rule.custom.module }] : []));
+
+/** Every type: module rule in chaff.yaml, loaded one by one in the order written, so the same chaff.yaml loads the same way. */
+const loadModuleRules = async (config: Config): Promise<readonly { readonly id: string; readonly loaded: Loaded }[]> =>
+  moduleRulesOf(customRulesOf(config).rules).reduce<Promise<{ id: string; loaded: Loaded }[]>>(
+    async (done, rule) => [...(await done), { id: rule.id, loaded: await loadRule(rule, config.baseDir) }],
+    Promise.resolve([]),
+  );
+
+/** A plugin's code rules, each run as one of chaff's; a failure names the plugin as chaff.yaml writes it. */
+const pluginDetectors = (plugin: ParsedPlugin): [string, Detector][] =>
+  Object.entries(plugin.detectors).map(([id, detect]) => [id, moduleDetector(detect, plugin.written)]);
+
+const lexiconsByLanguage = (plugins: readonly ParsedPlugin[]): Record<string, Record<string, Lexicon>> => {
+  const languages = [...new Set(plugins.flatMap((plugin) => Object.keys(plugin.lexicons)))];
+  return Object.fromEntries(
+    languages.map((language) => [language, plugins.reduce<Record<string, Lexicon>>((merged, plugin) => ({ ...merged, ...plugin.lexicons[language] }), {})]),
+  );
+};
+
+/** Everything chaff.yaml names in code, loaded. */
+const loadExtensions = async (config: Config): Promise<Extensions> => {
+  const modules = await loadModuleRules(config);
+  const { plugins, problems: pluginProblems } = await loadPlugins(config);
+  return {
+    detectors: Object.fromEntries([
+      ...modules.flatMap((entry): [string, Detector][] => ("detector" in entry.loaded ? [[entry.id, entry.loaded.detector]] : [])),
+      ...plugins.flatMap(pluginDetectors),
+    ]),
+    rules: plugins.flatMap((plugin) => plugin.rules),
+    lexicons: lexiconsByLanguage(plugins),
+    styles: plugins.flatMap((plugin) => plugin.styles),
+    problems: modules.flatMap((entry) => ("problem" in entry.loaded ? [entry.loaded.problem] : [])),
+    pluginProblems,
+  };
+};
+
+/** chaff.yaml with the code it names loaded, and the style it names applied when a plugin ships it. */
+export const withExtensions = async (config: Config): Promise<Config> => {
+  const extensions = await loadExtensions(config);
+  return withStyle({ ...config, extensions }, extensions.styles);
+};

package/src/extension/module-detector.ts

@@ -0,0 +1,61 @@
+import type * as Api from "../api.ts";
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import { frozenLexiconOf, ruleDocumentOf } from "./document-view.ts";
+import { returnedFindings, type ShapeProblem } from "./returned-findings.ts";
+
+// A detector a team or a plugin wrote, run as one of chaff's. It reads the document through the plugin API, and what it
+// returns is checked before chaff uses it. A throw or a wrong return is that rule's failure only: run.ts lists the rule
+// as not run with the reason, and every other rule still runs.
+
+/** A detector from a plugin. It is JavaScript nobody has type-checked against this chaff, so what it returns is unknown. */
+export type UntrustedDetector = (doc: Api.RuleDocument, options: Api.DetectorOptions) => unknown;
+
+export type RuleFailure = { readonly kind: "threw"; readonly message: string } | { readonly kind: "returned"; readonly problem: ShapeProblem };
+
+/** A plugin's rule that failed on a document. origin is where the detector came from: its file, or its package. */
+export class PluginRuleFailure extends Error {
+  readonly failure: RuleFailure;
+  readonly origin: string;
+  constructor(failure: RuleFailure, origin: string) {
+    super(`${origin}: ${failure.kind === "threw" ? failure.message : failure.problem.kind}`);
+    this.name = "PluginRuleFailure";
+    this.failure = failure;
+    this.origin = origin;
+  }
+}
+
+/** The first line of what was thrown. What a plugin throws is its own object, so printing it may throw too. */
+const messageOf = (error: unknown): string => {
+  try {
+    const text = error instanceof Error ? error.message : String(error);
+    return text.split("\n")[0] ?? text;
+  } catch {
+    return "an error that cannot be printed";
+  }
+};
+
+/**
+ * What the detector returned, as findings, or how it failed. Reading the return can run the plugin's code too (a getter,
+ * a Proxy), so it is checked inside the try. A Promise is a wrong return; its rejection must not end the run later.
+ */
+const findingsOf = (detect: UntrustedDetector, doc: ProseDocument, options: Api.DetectorOptions): { findings: Finding[] } | { failure: RuleFailure } => {
+  const view = ruleDocumentOf(doc);
+  try {
+    const returned: unknown = detect(view, options);
+    if (returned instanceof Promise) returned.catch(() => undefined);
+    const result = returnedFindings(returned, doc.source, doc.sentences);
+    return "problem" in result ? { failure: { kind: "returned", problem: result.problem } } : { findings: [...result.findings] };
+  } catch (error) {
+    return { failure: { kind: "threw", message: messageOf(error) } };
+  }
+};
+
+/** detect as one of chaff's detectors. Throws PluginRuleFailure when it throws or returns anything but findings. */
+export const moduleDetector =
+  (detect: UntrustedDetector, origin: string): Detector =>
+  (doc, options): Finding[] => {
+    const lexicon = options.lexicon === undefined ? undefined : frozenLexiconOf(options.lexicon);
+    const outcome = findingsOf(detect, doc, Object.freeze({ lexicon }));
+    if ("failure" in outcome) throw new PluginRuleFailure(outcome.failure, origin);
+    return outcome.findings;
+  };

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));