chaffjs 0.17.0 → 0.19.0

package/src/custom/bounded-match.ts

@@ -0,0 +1,58 @@
+import { createContext, Script } from "node:vm";
+
+// A team's regular expression, run with a time limit. regex-safety.ts refuses the shapes known to run away before a pattern
+// is used; no reading of the pattern can prove every shape safe, so this is the backstop. V8 can interrupt a regular
+// expression only through vm's timeout, so the matching runs in a vm context.
+
+/** How long one rule's pattern may take over one document. Far above what a sane pattern needs on any real document. */
+export const PATTERN_BUDGET_MS = 1000;
+
+/** A pattern that did not finish within its budget. run.ts lists the rule as not run, with this as the reason. */
+export class PatternTimeout extends Error {
+  readonly budget_ms: number;
+  constructor(budgetMs: number) {
+    super(`the pattern did not finish within ${String(budgetMs)} ms`);
+    this.name = "PatternTimeout";
+    this.budget_ms = budgetMs;
+  }
+}
+
+/** Each text's matches: where it starts and what it matched. Empty matches are left out. */
+export type TextMatches = readonly (readonly { readonly index: number; readonly text: string }[])[];
+
+const SCRIPT = new Script(
+  `texts.map((text) => [...text.matchAll(new RegExp(source, flags))].filter((m) => m[0] !== "").map((m) => ({ index: m.index, text: m[0] })))`,
+);
+
+const isTimeout = (error: unknown): boolean => typeof error === "object" && error !== null && "code" in error && error.code === "ERR_SCRIPT_EXECUTION_TIMEOUT";
+
+const isMatches = (value: unknown): value is TextMatches =>
+  Array.isArray(value) &&
+  value.every(
+    (entry: unknown) =>
+      Array.isArray(entry) &&
+      entry.every(
+        (match: unknown) =>
+          typeof match === "object" &&
+          match !== null &&
+          "index" in match &&
+          typeof match.index === "number" &&
+          "text" in match &&
+          typeof match.text === "string",
+      ),
+  );
+
+/** Every match of the pattern (flags without g) in each text, or PatternTimeout when the whole run takes longer than budgetMs. */
+export const boundedMatches = (source: string, flags: string, texts: readonly string[], budgetMs: number = PATTERN_BUDGET_MS): TextMatches => {
+  const context = createContext({ texts: [...texts], source, flags: `g${flags}` });
+  try {
+    const result: unknown = SCRIPT.runInContext(context, { timeout: budgetMs });
+    // The result is built in another context; copy it through JSON so it holds plain values of this one.
+    const plain: unknown = JSON.parse(JSON.stringify(result));
+    if (!isMatches(plain)) throw new Error("chaff: the pattern's matches came back in an unexpected shape");
+    return plain;
+  } catch (error) {
+    if (isTimeout(error)) throw new PatternTimeout(budgetMs);
+    throw error;
+  }
+};

package/src/custom/load.ts

@@ -0,0 +1,23 @@
+import type { Config } from "../config/load.ts";
+import type { RuleDefinition } from "../plugin.ts";
+import { loadRules } from "../rule-load.ts";
+import { loadGenres } from "../genre-load.ts";
+import { parseCustomRules, type CustomRules } from "./parse.ts";
+
+/** The team's custom_rules as rules, with what could not be read. A team's rule applies to every genre, like the team's words. */
+export const customRulesOf = (config: Pick<Config, "customRules" | "baseDir">): CustomRules =>
+  parseCustomRules(config.customRules, {
+    builtIn: new Set(loadRules("en").map((rule) => rule.id)),
+    useFor: loadGenres().groups.map((group) => group.id),
+    baseDir: config.baseDir,
+  });
+
+/**
+ * Every rule a run knows for a language: chaff's own, the team's, then the plugins'. Where the team's or a plugin's
+ * cannot be read, settingProblems stops the run.
+ */
+export const rulesOf = (language: string, config: Pick<Config, "customRules" | "baseDir" | "extensions">): RuleDefinition[] => [
+  ...loadRules(language),
+  ...customRulesOf(config).rules,
+  ...(config.extensions?.rules ?? []),
+];

package/src/custom/module-path.ts

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+// Where a type: module rule's file is. Loading it runs its code, so a relative path may not leave the folder chaff.yaml
+// is in: a chaff.yaml copied from elsewhere cannot reach for ../../somewhere. An absolute path is written on purpose and
+// is used as written. Pure: no file is read.
+
+export type ModulePathRefusal = "outside";
+
+export type ModulePath = { readonly file: string } | { readonly refusal: ModulePathRefusal };
+
+/** Whether file is inside dir (dir itself is not). Reads no file: the same check runs on real paths at load time. */
+export const isInside = (dir: string, file: string): boolean => {
+  const fromDir = relative(dir, file);
+  const leaves = fromDir === ".." || fromDir.startsWith(`..${sep}`);
+  return fromDir !== "" && !leaves && !isAbsolute(fromDir);
+};
+
+/** The file a module path names, relative to baseDir (where chaff.yaml is) unless it is absolute. */
+export const modulePathOf = (written: string, baseDir: string): ModulePath => {
+  if (isAbsolute(written)) return { file: written };
+  const file = resolve(baseDir, written);
+  return isInside(baseDir, file) ? { file } : { refusal: "outside" };
+};

package/src/custom/parse.ts

@@ -0,0 +1,323 @@
+import type { CustomSpec, LevelTable, Localized, RuleDefinition, Severity, TokenCondition } from "../plugin.ts";
+import { regexRefusal, type RegexRefusal } from "./regex-safety.ts";
+import { posTags } from "./token-pattern.ts";
+import { modulePathOf, type ModulePathRefusal } from "./module-path.ts";
+
+// custom_rules in chaff.yaml: a team's own deterministic rules, written without code. Each becomes a RuleDefinition like the
+// built-in ones, so findings, explain, rules --json, stet, the baseline and SARIF treat it the same. Pure: the YAML comes in parsed.
+
+export const CUSTOM_TYPES = ["words", "pattern", "tokens", "module"] as const;
+
+export type CustomProblem =
+  | { readonly kind: "not-a-list" }
+  | { readonly kind: "not-a-map"; readonly at: string }
+  | { readonly kind: "bad-id"; readonly at: string }
+  | { readonly kind: "duplicate-id"; readonly at: string }
+  | { readonly kind: "built-in-id"; readonly at: string }
+  | { readonly kind: "unknown-type"; readonly at: string; readonly written: string }
+  | { readonly kind: "bad-module"; readonly at: string; readonly written: string; readonly refusal: ModulePathRefusal }
+  | { readonly kind: "bad-requires"; readonly at: string; readonly written: string }
+  | { readonly kind: "bad-word-list"; readonly at: string; readonly written: string }
+  | { readonly kind: "missing"; readonly at: string; readonly field: string }
+  | { readonly kind: "unpaired-example"; readonly at: string }
+  | { readonly kind: "bad-level"; readonly at: string; readonly written: string }
+  | { readonly kind: "bad-languages"; readonly at: string }
+  | { readonly kind: "no-words"; readonly at: string }
+  | { readonly kind: "bad-pattern"; readonly at: string; readonly refusal: RegexRefusal }
+  | { readonly kind: "no-tokens"; readonly at: string }
+  | { readonly kind: "bad-token"; readonly at: string; readonly index: number }
+  | { readonly kind: "unknown-pos"; readonly at: string; readonly written: string };
+
+export type CustomRules = { readonly rules: readonly RuleDefinition[]; readonly problems: readonly CustomProblem[] };
+
+/**
+ * What parsing needs to know: the built-in rule ids (a team's rule may not take one), the genres a rule applies to, and
+ * the folder a module's path is relative to (where chaff.yaml is).
+ */
+export type CustomContext = { readonly builtIn: ReadonlySet<string>; readonly useFor: readonly string[]; readonly baseDir: string };
+
+const RULE_ID = /^[a-z][a-z0-9-]*$/u;
+const SEVERITIES: readonly Severity[] = ["info", "warning", "error"];
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const nonEmpty = (value: unknown): value is string => typeof value === "string" && value.trim() !== "";
+
+/** Texts by language ({ ja, en } or any language's id). undefined when there is none. */
+const byLanguageOf = (value: unknown): Localized | undefined => {
+  if (!isRecord(value)) return undefined;
+  const entries = Object.entries(value).filter((entry): entry is [string, string] => nonEmpty(entry[1]));
+  return entries.length === 0 ? undefined : Object.fromEntries(entries.map(([language, text]) => [language, text.trim()]));
+};
+
+/** A text by language, or one string for ja and en (and, through the "en" fallback, for any other language). */
+const localizedOf = (value: unknown): Localized | undefined => (nonEmpty(value) ? { ja: value.trim(), en: value.trim() } : byLanguageOf(value));
+
+/** The key an example side written as one string is kept under: it reads the same in every language. */
+const EVERY_LANGUAGE = "*";
+
+const exampleSideOf = (value: unknown): Localized | undefined => (nonEmpty(value) ? { [EVERY_LANGUAGE]: value.trim() } : byLanguageOf(value));
+
+/** One rule's own problems, with the rule's id (or its place in the list) as where. */
+type Checked<T> = { readonly value: T | undefined; readonly problems: readonly CustomProblem[] };
+
+const ok = <T>(value: T): Checked<T> => ({ value, problems: [] });
+const failed = <T>(...problems: CustomProblem[]): Checked<T> => ({ value: undefined, problems });
+
+type Pair = { readonly avoid: string; readonly use: string };
+
+/** words as a map (avoid: use) or a list (words to point at, with nothing to use instead). */
+const pairsOf = (raw: unknown): Pair[] => {
+  if (Array.isArray(raw)) return raw.filter(nonEmpty).map((avoid) => ({ avoid: avoid.trim(), use: "" }));
+  if (!isRecord(raw)) return [];
+  return Object.entries(raw).flatMap(([avoid, use]) => (avoid.trim() === "" ? [] : [{ avoid: avoid.trim(), use: nonEmpty(use) ? use.trim() : "" }]));
+};
+
+const printed = (value: unknown): string => JSON.stringify(value) ?? "undefined";
+
+const wordsOf = (raw: unknown, at: string): Checked<CustomSpec> => {
+  const usable = pairsOf(raw).filter((pair) => pair.avoid !== pair.use);
+  return usable.length === 0 ? failed({ kind: "no-words", at }) : ok({ type: "words", words: usable });
+};
+
+const patternOf = (raw: Record<string, unknown>, at: string): Checked<CustomSpec> => {
+  const pattern = raw["pattern"];
+  if (!nonEmpty(pattern)) return failed({ kind: "missing", at, field: "pattern" });
+  const flags = raw["ignore_case"] === true ? "iu" : "u";
+  const refusal = regexRefusal(pattern, flags);
+  return refusal === undefined ? ok({ type: "pattern", pattern, flags }) : failed({ kind: "bad-pattern", at, refusal });
+};
+
+const posOf = (raw: unknown, at: string): Checked<readonly string[]> => {
+  if (raw === undefined) return ok([]);
+  const written = (Array.isArray(raw) ? raw : [raw]).map((entry: unknown) => (typeof entry === "string" ? entry : printed(entry)));
+  const unknown = written.find((name) => posTags(name) === undefined);
+  if (unknown !== undefined) return failed({ kind: "unknown-pos", at, written: unknown });
+  return ok([...new Set(written.flatMap((name) => posTags(name) ?? []))]);
+};
+
+const conditionOf = (raw: unknown, index: number, at: string): Checked<TokenCondition> => {
+  if (!isRecord(raw)) return failed({ kind: "bad-token", at, index });
+  const pos = posOf(raw["pos"], at);
+  if (pos.value === undefined) return failed(...pos.problems);
+  // lemma is the linguists' word for the base form; either may be written.
+  const written = raw["base"] ?? raw["lemma"];
+  const base = nonEmpty(written) ? written.trim() : undefined;
+  const surface = nonEmpty(raw["surface"]) ? raw["surface"].trim() : undefined;
+  if (pos.value.length === 0 && base === undefined && surface === undefined) return failed({ kind: "bad-token", at, index });
+  return ok({ ...(pos.value.length === 0 ? {} : { pos: pos.value }), ...(base === undefined ? {} : { base }), ...(surface === undefined ? {} : { surface }) });
+};
+
+const tokensOf = (raw: unknown, at: string): Checked<CustomSpec> => {
+  if (!Array.isArray(raw) || raw.length === 0) return failed({ kind: "no-tokens", at });
+  const checked = raw.map((entry: unknown, index) => conditionOf(entry, index + 1, at));
+  const problems = checked.flatMap((entry) => entry.problems);
+  const tokens = checked.flatMap((entry) => (entry.value === undefined ? [] : [entry.value]));
+  return problems.length > 0 ? failed(...problems) : ok({ type: "tokens", tokens });
+};
+
+const moduleOf = (raw: Record<string, unknown>, at: string, baseDir: string): Checked<CustomSpec> => {
+  const written = raw["module"];
+  if (!nonEmpty(written)) return failed({ kind: "missing", at, field: "module" });
+  const path = modulePathOf(written.trim(), baseDir);
+  if ("refusal" in path) return failed({ kind: "bad-module", at, written, refusal: path.refusal });
+  return ok({ type: "module", module: written.trim(), file: path.file });
+};
+
+const specOf = (raw: Record<string, unknown>, type: string, at: string, baseDir: string): Checked<CustomSpec> => {
+  if (type === "words") return wordsOf(raw["words"], at);
+  if (type === "pattern") return patternOf(raw, at);
+  if (type === "module") return moduleOf(raw, at, baseDir);
+  return tokensOf(raw["tokens"], at);
+};
+
+const typeOf = (raw: Record<string, unknown>, at: string): Checked<string> => {
+  const type = raw["type"];
+  if (!nonEmpty(type)) return failed({ kind: "missing", at, field: "type" });
+  return CUSTOM_TYPES.some((known) => known === type) ? ok(type) : failed({ kind: "unknown-type", at, written: type });
+};
+
+const severityOf = (raw: unknown, at: string): Checked<Severity> => {
+  if (raw === undefined) return ok("warning");
+  const severity = SEVERITIES.find((entry) => entry === raw);
+  return severity === undefined ? failed({ kind: "bad-level", at, written: typeof raw === "string" ? raw : printed(raw) }) : ok(severity);
+};
+
+/** The four words as severities: normal is the rule's own level, relaxed one lower, strict one higher, where there is one. */
+const levelsFor = (severity: Severity): LevelTable => {
+  const rank = SEVERITIES.indexOf(severity) + 1;
+  return { ...(rank < SEVERITIES.length ? { strict: rank + 1 } : {}), normal: rank, ...(rank > 1 ? { relaxed: rank - 1 } : {}) };
+};
+
+type Texts = { readonly name: Localized; readonly why: Localized; readonly how_to_fix: Localized; readonly before: Localized; readonly after: Localized };
+
+const textsOf = (raw: Record<string, unknown>, at: string): Checked<Texts> => {
+  const example = isRecord(raw["example"]) ? raw["example"] : {};
+  const found = {
+    name: localizedOf(raw["name"]),
+    why: localizedOf(raw["why"]),
+    how_to_fix: localizedOf(raw["how_to_fix"]),
+    before: exampleSideOf(example["before"]),
+    after: exampleSideOf(example["after"]),
+  };
+  const missing = Object.entries(found).flatMap(([field, text]) =>
+    text === undefined ? [{ kind: "missing" as const, at, field: field === "before" || field === "after" ? `example.${field}` : field }] : [],
+  );
+  const { name, why, how_to_fix: howToFix, before, after } = found;
+  if (name === undefined || why === undefined || howToFix === undefined || before === undefined || after === undefined) return failed(...missing);
+  return ok({ name, why, how_to_fix: howToFix, before, after });
+};
+
+/** What a module's detector may ask the adapter for. Only parts of speech: without them, sentences have no tokens. */
+const REQUIRABLE: readonly string[] = ["pos"];
+
+const requiresOf = (raw: unknown, type: string, at: string): Checked<readonly string[]> => {
+  if (type === "tokens") return ok(["pos"]);
+  if (raw === undefined || type !== "module") return ok([]);
+  const written = (Array.isArray(raw) ? raw : [raw]).map((entry: unknown) => (typeof entry === "string" ? entry : printed(entry)));
+  const unknown = written.find((need) => !REQUIRABLE.includes(need));
+  return unknown === undefined ? ok([...new Set(written)]) : failed({ kind: "bad-requires", at, written: unknown });
+};
+
+/** A module's word list by name; its detector gets it as options.lexicon. The other types carry their words themselves. */
+const wordListOf = (raw: unknown, type: string, at: string): Checked<string | undefined> => {
+  if (raw === undefined || type !== "module") return ok(undefined);
+  return nonEmpty(raw) ? ok(raw.trim()) : failed({ kind: "bad-word-list", at, written: printed(raw) });
+};
+
+/** What a rule's detector needs besides the document: tokens from the adapter, and a word list. */
+type Needs = { readonly requires: readonly string[]; readonly wordList: string | undefined };
+
+const needsOf = (raw: Record<string, unknown>, type: string, at: string): Checked<Needs> => {
+  const requires = requiresOf(raw["requires"], type, at);
+  const wordList = wordListOf(raw["word_list"], type, at);
+  if (requires.value === undefined || wordList.problems.length > 0) return failed(...requires.problems, ...wordList.problems);
+  return ok({ requires: requires.value, wordList: wordList.value });
+};
+
+const languagesOf = (raw: unknown, at: string): Checked<readonly string[] | undefined> => {
+  if (raw === undefined) return ok(undefined);
+  const list = Array.isArray(raw) ? raw : [raw];
+  return list.length > 0 && list.every(nonEmpty) ? ok(list.map((entry: string) => entry.trim())) : failed({ kind: "bad-languages", at });
+};
+
+/** The message when a rule does not write one: the replacement for a word list, else the rule's name and what was found. */
+const defaultMessage = (spec: CustomSpec, name: Localized): Localized => {
+  if (spec.type === "words" && spec.words.every((pair) => pair.use !== ""))
+    return { ja: "「{matched}」は「{preferred}」と書きます", en: 'Write "{preferred}", not "{matched}"' };
+  return Object.fromEntries(Object.entries(name).map(([language, text]) => [language, language === "ja" ? `${text}:「{matched}」` : `${text}: "{matched}"`]));
+};
+
+const PLACEHOLDERS: Readonly<Record<string, Localized>> = {
+  matched: { ja: "見つけた語句", en: "the text found" },
+  preferred: { ja: "使う書き方", en: "the spelling to use" },
+};
+
+/** A module's detector is not in chaff's table: it is loaded from the module and found by the rule's id. */
+const HOW_TO_FIND: Readonly<Record<CustomSpec["type"], string>> = {
+  words: "custom-words",
+  pattern: "custom-pattern",
+  tokens: "custom-tokens",
+  module: "module",
+};
+
+type Example = { readonly before: string; readonly after: string };
+
+type Parts = {
+  readonly spec: CustomSpec;
+  readonly needs: Needs;
+  readonly severity: Severity;
+  readonly texts: Texts;
+  readonly languages: readonly string[] | undefined;
+  readonly examples: Readonly<Record<string, Example>>;
+};
+
+const READER_LANGUAGES: readonly string[] = ["ja", "en"];
+
+/** The example in each language the rule checks, where both before and after are written in it. A string counts for both. */
+const examplesOf = (texts: Texts, languages: readonly string[] | undefined): Record<string, Example> =>
+  Object.fromEntries(
+    (languages ?? READER_LANGUAGES).flatMap((language) => {
+      const [before, after] = [texts.before[language] ?? texts.before[EVERY_LANGUAGE], texts.after[language] ?? texts.after[EVERY_LANGUAGE]];
+      return before === undefined || after === undefined ? [] : [[language, { before, after }]];
+    }),
+  );
+
+const definitionOf = (id: string, raw: Record<string, unknown>, parts: Parts, useFor: readonly string[]): RuleDefinition => ({
+  id,
+  layer: parts.needs.requires.includes("pos") ? "L3" : "L2",
+  status: "stable",
+  name: parts.texts.name,
+  why: parts.texts.why,
+  how_to_fix: parts.texts.how_to_fix,
+  message: localizedOf(raw["message"]) ?? defaultMessage(parts.spec, parts.texts.name),
+  messages: {},
+  placeholders: PLACEHOLDERS,
+  levels: levelsFor(parts.severity),
+  level_sets: "severity",
+  by_genre: {},
+  how_to_find: HOW_TO_FIND[parts.spec.type],
+  word_list: parts.needs.wordList,
+  extra_word_lists: [],
+  what_to_check: undefined,
+  where: undefined,
+  full_sentence: undefined,
+  requires: parts.needs.requires,
+  uses: [],
+  from: [],
+  languages: parts.languages,
+  use_for: useFor,
+  severity: parts.severity,
+  custom: parts.spec,
+  // The reference and explain read a rule's plain-language fields from guide; a team's rule is listed with the team's words.
+  guide: {
+    group: "team",
+    summary: parts.texts.name,
+    examples: parts.examples,
+    notFlagged: {},
+    levelMeaning: {},
+    sources: [],
+    rewrite: {},
+  },
+});
+
+const idOf = (raw: Record<string, unknown>, index: number, seen: ReadonlySet<string>, builtIn: ReadonlySet<string>): Checked<string> => {
+  const id = raw["id"];
+  const at = typeof id === "string" && id !== "" ? id : `#${String(index + 1)}`;
+  if (typeof id !== "string" || !RULE_ID.test(id)) return failed({ kind: "bad-id", at });
+  if (builtIn.has(id)) return failed({ kind: "built-in-id", at });
+  return seen.has(id) ? failed({ kind: "duplicate-id", at }) : ok(id);
+};
+
+const ruleOf = (raw: unknown, index: number, seen: ReadonlySet<string>, context: CustomContext): Checked<RuleDefinition> => {
+  if (!isRecord(raw)) return failed({ kind: "not-a-map", at: `#${String(index + 1)}` });
+  const id = idOf(raw, index, seen, context.builtIn);
+  const at = id.value ?? (nonEmpty(raw["id"]) ? raw["id"] : `#${String(index + 1)}`);
+  const type = typeOf(raw, at);
+  const spec = type.value === undefined ? failed<CustomSpec>() : specOf(raw, type.value, at, context.baseDir);
+  const needs = needsOf(raw, type.value ?? "", at);
+  const severity = severityOf(raw["level"], at);
+  const texts = textsOf(raw, at);
+  const languages = languagesOf(raw["languages"], at);
+  const examples = texts.value === undefined ? {} : examplesOf(texts.value, languages.value);
+  const unpaired: CustomProblem[] = texts.value !== undefined && Object.keys(examples).length === 0 ? [{ kind: "unpaired-example", at }] : [];
+  const problems = [...[id, type, spec, needs, severity, texts, languages].flatMap((checked) => checked.problems), ...unpaired];
+  if (problems.length > 0) return failed(...problems);
+  if (id.value === undefined || spec.value === undefined || needs.value === undefined || severity.value === undefined || texts.value === undefined)
+    return failed();
+  const parts = { spec: spec.value, needs: needs.value, severity: severity.value, texts: texts.value, languages: languages.value, examples };
+  return ok(definitionOf(id.value, raw, parts, context.useFor));
+};
+
+/** custom_rules as written. Every problem is reported; a rule with a problem is left out, and the run is stopped by the caller. */
+export const parseCustomRules = (raw: unknown, context: CustomContext): CustomRules => {
+  if (raw === undefined || raw === null) return { rules: [], problems: [] };
+  if (!Array.isArray(raw)) return { rules: [], problems: [{ kind: "not-a-list" }] };
+  return raw.reduce<{ rules: RuleDefinition[]; problems: CustomProblem[] }>(
+    (acc, entry: unknown, index) => {
+      const checked = ruleOf(entry, index, new Set(acc.rules.map((rule) => rule.id)), context);
+      return { rules: checked.value === undefined ? acc.rules : [...acc.rules, checked.value], problems: [...acc.problems, ...checked.problems] };
+    },
+    { rules: [], problems: [] },
+  );
+};

package/src/custom/problems.ts

@@ -0,0 +1,111 @@
+import type { Config } from "../config/load.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
+import type { CustomProblem } from "./parse.ts";
+import { customRulesOf } from "./load.ts";
+import { MAX_PATTERN_LENGTH, MAX_REPEATS, type RegexRefusal } from "./regex-safety.ts";
+import { POS_WRITTEN_NAMES } from "./token-pattern.ts";
+import type { ModulePathRefusal } from "./module-path.ts";
+
+/** Each problem's sentence, with {at}, {written}, {field}, {index}, {refusal} and {names} filled in from the problem. */
+type Text = {
+  readonly problems: Readonly<Record<CustomProblem["kind"], string>>;
+  readonly refusal: Readonly<Record<RegexRefusal, string>>;
+  readonly modulePath: Readonly<Record<ModulePathRefusal, string>>;
+};
+
+const TEXT: Texts<Text> = {
+  ja: {
+    modulePath: {
+      outside: "chaff.yaml のあるフォルダの外です。読み込むとそのコードが動くので、外のファイルは絶対パスで名指ししてください",
+    },
+    refusal: {
+      "too-long": `${String(MAX_PATTERN_LENGTH)} 字を超えています。いくつかのルールに分けてください`,
+      "nested-quantifier": "繰り返しの中に繰り返しがあります（(a+)+ のような形）。長い行で止まらなくなるので使えません",
+      "too-many-repeats": `回数の決まらない繰り返し（* や + や {1,9}）が ${String(MAX_REPEATS)} つを超えています。長い行で止まらなくなることがあります`,
+      backreference: "後方参照（\\1）は使えません。長い行で止まらなくなることがあるためです",
+      "empty-match": "何も無い所にも当たります。すべての文で指摘が出てしまいます",
+      invalid: "正規表現として読めません",
+    },
+    problems: {
+      "not-a-list": "{scope} はルールの並び（- id: …）で書いてください",
+      "not-a-map": "{scope} の {at}: id や type を持つ項目として書いてください",
+      "bad-id": "{scope} の {at}: id は英小文字で始まり、英小文字・数字・ハイフンだけで書きます（例: team-no-tbd）",
+      "duplicate-id": "{scope} の {at}: 同じ id のルールがもう一つあります",
+      "built-in-id": "{scope} の {at}: chaff のルールと同じ id です。別の id にしてください",
+      "unknown-type": "{scope} の {at}: type: {written} は使えません（words / pattern / tokens / module）",
+      "bad-module": "{scope} の {at}: module: {written} は使えません。{refusal}",
+      "bad-requires": "{scope} の {at}: requires: {written} は求められません（求められるのは pos だけです）",
+      "bad-word-list": "{scope} の {at}: word_list: {written} は語彙表の名前として読めません",
+      missing: "{scope} の {at}: {field} がありません",
+      "unpaired-example": "{scope} の {at}: example の before と after を、ルールが見る言語の同じ言語で書いてください",
+      "bad-level": "{scope} の {at}: level: {written} は読めません（error / warning / info）",
+      "bad-languages": "{scope} の {at}: languages は言語の並びで書いてください（[ja] や [ja, en]）",
+      "no-words": "{scope} の {at}: words に語がありません（「使わない書き方: 使う書き方」か語の並び）",
+      "no-tokens": "{scope} の {at}: tokens に語の条件がありません（- { pos: 名詞 } のように並べます）",
+      "bad-token": "{scope} の {at}: tokens の {index} 番目に pos・base・surface のどれもありません",
+      "unknown-pos": "{scope} の {at}: 品詞 {written} は知りません（{names}）",
+      "bad-pattern": "{scope} の {at}: pattern を使えません。{refusal}",
+    },
+  },
+  en: {
+    modulePath: {
+      outside: "it is outside the folder chaff.yaml is in. Loading a module runs its code, so name a file outside by its absolute path",
+    },
+    refusal: {
+      "too-long": `it is longer than ${String(MAX_PATTERN_LENGTH)} characters; split it into several rules`,
+      "nested-quantifier": "it repeats something that repeats (a shape like (a+)+), which can run for minutes on a long line",
+      "too-many-repeats": `it has more than ${String(MAX_REPEATS)} repeats of varying count (*, + or {1,9}), which can run for minutes on a long line`,
+      backreference: "backreferences (\\1) are not allowed, since they can run for minutes on a long line",
+      "empty-match": "it matches an empty string, so it would report every sentence",
+      invalid: "it is not a regular expression",
+    },
+    problems: {
+      "not-a-list": "write {scope} as a list of rules (- id: …)",
+      "not-a-map": "{scope} {at}: write each rule as an entry with id and type",
+      "bad-id": "{scope} {at}: an id starts with a lowercase letter and has only lowercase letters, digits and hyphens (team-no-tbd)",
+      "duplicate-id": "{scope} {at}: another rule has the same id",
+      "built-in-id": "{scope} {at}: chaff has a rule with this id; choose another",
+      "unknown-type": "{scope} {at}: type: {written} is not a type (words / pattern / tokens / module)",
+      "bad-module": "{scope} {at}: module: {written} cannot be used: {refusal}",
+      "bad-requires": "{scope} {at}: requires: {written} cannot be asked for (only pos can)",
+      "bad-word-list": "{scope} {at}: cannot read word_list: {written} as the name of a word list",
+      missing: "{scope} {at}: {field} is missing",
+      "unpaired-example": "{scope} {at}: write example's before and after in the same language, one the rule checks",
+      "bad-level": "{scope} {at}: cannot read level: {written} (error / warning / info)",
+      "bad-languages": "{scope} {at}: write languages as a list ([en] or [ja, en])",
+      "no-words": "{scope} {at}: words has no words (avoid: use pairs, or a list)",
+      "no-tokens": "{scope} {at}: tokens has no conditions (- { pos: noun } and so on)",
+      "bad-token": "{scope} {at}: token {index} has none of pos, base and surface",
+      "unknown-pos": "{scope} {at}: unknown part of speech {written} ({names})",
+      "bad-pattern": "{scope} {at}: the pattern cannot be used: {refusal}",
+    },
+  },
+};
+
+const PLACEHOLDER = /\{(scope|at|written|field|index|refusal|names)\}/gu;
+
+const refusalOf = (problem: CustomProblem, text: Text): string => {
+  if (problem.kind === "bad-pattern") return text.refusal[problem.refusal];
+  return problem.kind === "bad-module" ? text.modulePath[problem.refusal] : "";
+};
+
+/** The values a problem's sentence names. Each kind carries only some of them. */
+const valuesOf = (problem: CustomProblem, text: Text, scope: string): Readonly<Record<string, string>> => ({
+  scope,
+  at: "at" in problem ? problem.at : "",
+  written: "written" in problem ? problem.written : "",
+  field: "field" in problem ? problem.field : "",
+  index: "index" in problem ? String(problem.index) : "",
+  refusal: refusalOf(problem, text),
+  names: POS_WRITTEN_NAMES.join(" / "),
+});
+
+/** One problem as a sentence. scope names the list the rule is in: custom_rules, or a plugin's rules. */
+export const customProblemSentence = (problem: CustomProblem, ui: UiLanguage, scope = "custom_rules"): string => {
+  const values = valuesOf(problem, TEXT[ui], scope);
+  return TEXT[ui].problems[problem.kind].replace(PLACEHOLDER, (_whole, key: string) => values[key] ?? "");
+};
+
+/** What in custom_rules cannot run. Each stops the run: a team's rule that silently does not run looks like a clean document. */
+export const customRuleProblems = (config: Pick<Config, "customRules" | "path" | "baseDir">, ui: UiLanguage): string[] =>
+  customRulesOf(config).problems.map((problem) => `chaff: ${config.path ?? "chaff.yaml"}: ${customProblemSentence(problem, ui)}`);