chaffjs 0.16.0 → 0.18.0

package/src/config/style.ts

@@ -0,0 +1,42 @@
+import type { Config } from "./load.ts";
+import type { StyleDefinition } from "../style-parse.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
+
+/** How a style is named where a setting's source is shown (rules --json, explain). */
+export const styleSource = (id: string): string => `style: ${id}`;
+
+/** Where a rule's level came from when the style set it; undefined when chaff.yaml, the genre or the default did. */
+export const styleLevelSource = (config: Pick<Config, "applied">, ruleId: string): string | undefined =>
+  config.applied?.levelsFrom.includes(ruleId) === true ? styleSource(config.applied.style) : undefined;
+
+/**
+ * chaff.yaml with its style applied. A style's levels sit under chaff.yaml's own rules and over the genre's preset, since
+ * they join rules (which run.ts already puts over the preset). Its options become a layer under chaff.yaml's options.
+ * Without a style, or with one chaff does not have (settingProblems stops the run on that), the config is unchanged.
+ */
+export const withStyle = (config: Config, styles: readonly StyleDefinition[]): Config => {
+  const style = styles.find((entry) => entry.id === config.style);
+  if (style === undefined) return config;
+  const fromStyle = Object.keys(style.rules).filter((id) => config.rules[id] === undefined && config.limits[id] === undefined);
+  return {
+    ...config,
+    rules: { ...style.rules, ...config.rules },
+    applied: { style: style.id, levelsFrom: fromStyle, options: style.options },
+  };
+};
+
+const TEXT: Texts<{ readonly unknown: (where: string, style: string, known: string) => string }> = {
+  ja: {
+    unknown: (where, style, known) => `${where}: style: ${style} というスタイルはありません。使えるのは ${known} です`,
+  },
+  en: {
+    unknown: (where, style, known) => `${where}: there is no style named ${style}. The styles are ${known}`,
+  },
+};
+
+/** A style chaff does not have. It stops the run, like an unknown genre: running without it would check less than was asked. */
+export const styleProblems = (config: Pick<Config, "style" | "path">, styles: readonly StyleDefinition[], ui: UiLanguage): string[] => {
+  const written = config.style;
+  if (written === undefined || styles.some((style) => style.id === written)) return [];
+  return [`chaff: ${TEXT[ui].unknown(config.path ?? "chaff.yaml", written, styles.map((style) => style.id).join(", "))}`];
+};

package/src/config/warnings.ts

@@ -0,0 +1,13 @@
+import type { Config } from "./load.ts";
+import type { RuleDefinition } from "../plugin.ts";
+import type { UiLanguage } from "../ui.ts";
+import { ruleProblems } from "./rule-problems.ts";
+import { nameProblems } from "./name-problems.ts";
+import { configOptionProblems } from "./option-problems.ts";
+
+/** Everything in chaff.yaml that has no effect: unknown rules or levels, unreadable names, options that do not apply. Said before the results. */
+export const settingWarnings = (config: Config, rules: readonly RuleDefinition[], ui: UiLanguage): string[] => [
+  ...ruleProblems(config, rules, ui),
+  ...nameProblems(config, ui),
+  ...configOptionProblems(config, rules, ui),
+];

package/src/config/write.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { Scalar, YAMLMap, isMap, isScalar, parseDocument, type Document } from "yaml";
-import { definedLevels } from "../levels.ts";
-import { localized } from "../render/text.ts";
+import { definedLevels, severityAt } from "../levels.ts";
+import { SEVERITY_NAME, withArticle } from "../render/severity-name.ts";
+import { readableText } from "../render/text.ts";
 import type { Level, RuleDefinition } from "../plugin.ts";
 import { uiLanguageOf, type Texts } from "../ui.ts";
 
@@ -10,6 +11,7 @@ const TEXT: Texts<{
   readonly noSuchLevel: (id: string, level: string) => string;
   readonly hasReason: (id: string, previous: string) => string;
   readonly done: (id: string, level: string, path: string) => string;
+  readonly severityMoved: (from: string, to: string) => string;
 }> = {
   ja: {
     template: `# chaff.yaml — このチームの文章規範
@@ -22,6 +24,7 @@ rules:
     noSuchLevel: (id, level) => `${id} に ${level} はありません。normal と同じ設定です。\n設定は変更しませんでした。`,
     hasReason: (id, previous) => `${id} には既に理由が書かれています:\n  ${previous}\n値を変えるときは --why で新しい理由を書いてください。`,
     done: (id, level, path) => `${id} を ${level} にしました（${path}）`,
+    severityMoved: (from, to) => `このルールに数の上限はありません。指摘は消えず、${from} ではなく ${to} として出ます。`,
   },
   en: {
     template: `# chaff.yaml — this team's writing rules
@@ -34,6 +37,7 @@ rules:
     noSuchLevel: (id, level) => `${id} has no ${level} level; it is the same as normal.\nThe settings were not changed.`,
     hasReason: (id, previous) => `${id} already has a reason:\n  ${previous}\nTo change the level, give a new reason with --why.`,
     done: (id, level, path) => `Set ${id} to ${level} (${path})`,
+    severityMoved: (from, to) => `This rule has no numeric limit: its findings still show, as ${withArticle(to)} instead of ${withArticle(from)}.`,
   },
 };
 
@@ -47,7 +51,8 @@ const reasonOf = (value: unknown): string | undefined => {
   return text.length === 0 ? undefined : text;
 };
 
-const ruleComment = (rule: RuleDefinition, language: string): string => ` ${localized(rule.name, language)}\n ${localized(rule.why, language)}`;
+const ruleComment = (rule: RuleDefinition, language: string): string =>
+  ` ${readableText(rule, rule.name, language)}\n ${readableText(rule, rule.why, language)}`;
 
 const load = (path: string, language: string): Document => parseDocument(existsSync(path) ? readFileSync(path, "utf8") : TEXT[uiLanguageOf(language)].template);
 
@@ -83,5 +88,14 @@ export const applyLevel = (path: string, rule: RuleDefinition, level: Level, why
     existing.value = value;
   }
   writeFileSync(path, String(doc), "utf8");
-  return { ok: true, message: text.done(rule.id, level, path) };
+  return { ok: true, message: [text.done(rule.id, level, path), ...severityNote(rule, level, language)].join("\n") };
+};
+
+/** relax on a rule with nothing to count keeps its findings and lowers them; say so, or the change looks like it did nothing. */
+const severityNote = (rule: RuleDefinition, level: Level, language: string): string[] => {
+  if (level === "off") return [];
+  const [from, to] = [severityAt(rule, "normal"), severityAt(rule, level)];
+  if (from === to) return [];
+  const ui = uiLanguageOf(language);
+  return [TEXT[ui].severityMoved(SEVERITY_NAME[ui][from], SEVERITY_NAME[ui][to])];
 };

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,15 @@
+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">): CustomRules =>
+  parseCustomRules(config.customRules, {
+    builtIn: new Set(loadRules("en").map((rule) => rule.id)),
+    useFor: loadGenres().groups.map((group) => group.id),
+  });
+
+/** Every rule a run knows for a language: chaff's own, then the team's. Where the team's cannot be read, settingProblems stops the run. */
+export const rulesOf = (language: string, config: Pick<Config, "customRules">): RuleDefinition[] => [...loadRules(language), ...customRulesOf(config).rules];

package/src/custom/parse.ts

@@ -0,0 +1,274 @@
+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";
+
+// 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"] as const;
+
+/** Reserved for a small Node function a team writes. Refused with its own message until it is supported. */
+const RESERVED_TYPES: readonly string[] = ["module"];
+
+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: "not-yet"; 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) and the genres a rule applies to. */
+export type CustomContext = { readonly builtIn: ReadonlySet<string>; readonly useFor: readonly 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 specOf = (raw: Record<string, unknown>, type: string, at: string): Checked<CustomSpec> => {
+  if (type === "words") return wordsOf(raw["words"], at);
+  if (type === "pattern") return patternOf(raw, at);
+  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" });
+  if (RESERVED_TYPES.includes(type)) return failed({ kind: "not-yet", at, written: 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 });
+};
+
+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" },
+};
+
+const HOW_TO_FIND: Readonly<Record<CustomSpec["type"], string>> = { words: "custom-words", pattern: "custom-pattern", tokens: "custom-tokens" };
+
+type Example = { readonly before: string; readonly after: string };
+
+type Parts = {
+  readonly spec: CustomSpec;
+  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.spec.type === "tokens" ? "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: undefined,
+  extra_word_lists: [],
+  what_to_check: undefined,
+  where: undefined,
+  full_sentence: undefined,
+  requires: parts.spec.type === "tokens" ? ["pos"] : [],
+  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: {},
+  },
+});
+
+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);
+  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, severity, texts, languages].flatMap((checked) => checked.problems), ...unpaired];
+  if (id.value === undefined || spec.value === undefined || severity.value === undefined || texts.value === undefined || problems.length > 0)
+    return failed(...problems);
+  const parts = { spec: spec.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,89 @@
+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";
+
+/** 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>> };
+
+const TEXT: Texts<Text> = {
+  ja: {
+    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": "custom_rules はルールの並び（- id: …）で書いてください",
+      "not-a-map": "custom_rules の {at}: id や type を持つ項目として書いてください",
+      "bad-id": "custom_rules の {at}: id は英小文字で始まり、英小文字・数字・ハイフンだけで書きます（例: team-no-tbd）",
+      "duplicate-id": "custom_rules の {at}: 同じ id のルールがもう一つあります",
+      "built-in-id": "custom_rules の {at}: chaff のルールと同じ id です。別の id にしてください",
+      "unknown-type": "custom_rules の {at}: type: {written} は使えません（words / pattern / tokens）",
+      "not-yet": "custom_rules の {at}: type: {written} はまだ使えません（words / pattern / tokens）",
+      missing: "custom_rules の {at}: {field} がありません",
+      "unpaired-example": "custom_rules の {at}: example の before と after を、ルールが見る言語の同じ言語で書いてください",
+      "bad-level": "custom_rules の {at}: level: {written} は読めません（error / warning / info）",
+      "bad-languages": "custom_rules の {at}: languages は言語の並びで書いてください（[ja] や [ja, en]）",
+      "no-words": "custom_rules の {at}: words に語がありません（「使わない書き方: 使う書き方」か語の並び）",
+      "no-tokens": "custom_rules の {at}: tokens に語の条件がありません（- { pos: 名詞 } のように並べます）",
+      "bad-token": "custom_rules の {at}: tokens の {index} 番目に pos・base・surface のどれもありません",
+      "unknown-pos": "custom_rules の {at}: 品詞 {written} は知りません（{names}）",
+      "bad-pattern": "custom_rules の {at}: pattern を使えません。{refusal}",
+    },
+  },
+  en: {
+    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 custom_rules as a list of rules (- id: …)",
+      "not-a-map": "custom_rules {at}: write each rule as an entry with id and type",
+      "bad-id": "custom_rules {at}: an id starts with a lowercase letter and has only lowercase letters, digits and hyphens (team-no-tbd)",
+      "duplicate-id": "custom_rules {at}: another rule has the same id",
+      "built-in-id": "custom_rules {at}: chaff has a rule with this id; choose another",
+      "unknown-type": "custom_rules {at}: type: {written} is not a type (words / pattern / tokens)",
+      "not-yet": "custom_rules {at}: type: {written} is not supported yet (words / pattern / tokens)",
+      missing: "custom_rules {at}: {field} is missing",
+      "unpaired-example": "custom_rules {at}: write example's before and after in the same language, one the rule checks",
+      "bad-level": "custom_rules {at}: cannot read level: {written} (error / warning / info)",
+      "bad-languages": "custom_rules {at}: write languages as a list ([en] or [ja, en])",
+      "no-words": "custom_rules {at}: words has no words (avoid: use pairs, or a list)",
+      "no-tokens": "custom_rules {at}: tokens has no conditions (- { pos: noun } and so on)",
+      "bad-token": "custom_rules {at}: token {index} has none of pos, base and surface",
+      "unknown-pos": "custom_rules {at}: unknown part of speech {written} ({names})",
+      "bad-pattern": "custom_rules {at}: the pattern cannot be used: {refusal}",
+    },
+  },
+};
+
+const PLACEHOLDER = /\{(at|written|field|index|refusal|names)\}/gu;
+
+/** The values a problem's sentence names. Each kind carries only some of them. */
+const valuesOf = (problem: CustomProblem, text: Text): Readonly<Record<string, string>> => ({
+  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: "refusal" in problem ? text.refusal[problem.refusal] : "",
+  names: POS_WRITTEN_NAMES.join(" / "),
+});
+
+const sentenceOf = (problem: CustomProblem, text: Text): string => {
+  const values = valuesOf(problem, text);
+  return text.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">, ui: UiLanguage): string[] =>
+  customRulesOf(config).problems.map((problem) => `chaff: ${config.path ?? "chaff.yaml"}: ${sentenceOf(problem, TEXT[ui])}`);