chaffjs 0.17.0 → 0.19.0

package/src/rule-guide.ts

@@ -0,0 +1,173 @@
+import type { Localized } from "./plugin.ts";
+
+/** How the rule reference groups rules for a reader who is not an engineer, in the order it lists them. */
+export const RULE_GROUPS = ["readability", "wording", "slips", "consistency", "structure", "facts", "ai-tells", "team"] as const;
+
+export type RuleGroup = (typeof RULE_GROUPS)[number];
+
+/** A group's name and one line on what is in it, as the reference and chaff rules show them. */
+export type GroupText = { readonly name: string; readonly note: string };
+
+const GROUP_TEXT: Readonly<Record<"ja" | "en", Readonly<Record<RuleGroup, GroupText>>>> = {
+  ja: {
+    readability: { name: "読みやすさ", note: "長すぎる文、詰めすぎた段落、読み手がつまずく書き方。" },
+    wording: { name: "言葉づかい", note: "中身を言わずに強める言い方、決まり文句、誰がしたのかを書かない受け身。" },
+    slips: { name: "書き損じ", note: "書き換えの途中で残った語や空白。" },
+    consistency: {
+      name: "表記の揃え",
+      note: "どちらで書いても正しいものが、一つの文書の中で混ざっている所。chaff はどちらが正しいかを決めず、少ないほうを指します。",
+    },
+    structure: { name: "構造", note: "番号の抜け、無い条への参照、同じ語の二重定義、長い前置き。" },
+    facts: { name: "事実の食い違い", note: "日付と曜日、日付の順番、合計と内訳のように、暦や計算で確かめられる食い違い。" },
+    "ai-tells": {
+      name: "AIっぽさ",
+      note: "生成された文章にありがちな特徴。どれも、それだけで生成されたとは言いません。読み返す場所の目印です。",
+    },
+    team: {
+      name: "チームの表記",
+      note: "chaff.yaml にチームが書いた表記・社内用語・必須の見出しだけを見るルール。書かなければ何も言いません。",
+    },
+  },
+  en: {
+    readability: { name: "Readability", note: "Sentences that run too long, packed paragraphs, and other places a reader stumbles." },
+    wording: { name: "Wording", note: "Emphasis that says nothing, stock phrases, and passives that never say who acted." },
+    slips: { name: "Slips", note: "Words and spaces left over from an edit." },
+    consistency: {
+      name: "Consistency",
+      note: "Two ways of writing that are both right, mixed in one document. chaff does not pick a side; it points at whichever the document uses less.",
+    },
+    structure: {
+      name: "Structure",
+      note: "Skipped numbers, references to provisions that are not there, terms defined twice, long preambles.",
+    },
+    facts: {
+      name: "Facts that disagree",
+      note: "A date and its weekday, dates out of order, a total and its items: disagreements a calendar or a sum can settle.",
+    },
+    "ai-tells": {
+      name: "Signs of generated text",
+      note: "Traits common in generated text. None of them alone says the text was generated; they mark places to reread.",
+    },
+    team: {
+      name: "Your team's words",
+      note: "Rules that check only what your team lists in chaff.yaml: spellings, jargon, required headings. With nothing listed, they say nothing.",
+    },
+  },
+};
+
+/** In Japanese for "ja", in English for any other language. */
+export const groupTextOf = (language: string, group: RuleGroup): GroupText => GROUP_TEXT[language === "ja" ? "ja" : "en"][group];
+
+/**
+ * A short text the rule flags and the same text fixed, with the chaff.yaml it needs (jargon, prefer, a level).
+ * pad: the rule measures a whole document of some length (per 1000 words), so the example is tried after an ordinary passage.
+ */
+export type RuleExample = {
+  readonly before: string;
+  readonly after: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+  readonly pad?: boolean;
+};
+
+/** One finding of the rule itself on its example, as the command line reported it. */
+export type ExampleFinding = { readonly line: number; readonly column: number; readonly message: string };
+
+/** What the command line said about a rule on its example, before and after the fix (scripts/rule-examples.ts). */
+export type ExampleOutcome = {
+  readonly rule: string;
+  readonly language: string;
+  readonly before: readonly ExampleFinding[];
+  readonly after: readonly ExampleFinding[];
+};
+
+/** One spot written the way the rule flags it, and the same spot rewritten without adding a fact. */
+export type RewritePair = { readonly before: string; readonly after: string };
+
+/**
+ * How to rewrite a spot the rule flags, for an AI or a person doing the fix (chaff fix-plan prints it).
+ * direction: what to do; keep: what must not change; avoid: the mistakes a rewriter makes here.
+ */
+export type RuleRewrite = {
+  readonly direction: string;
+  readonly pairs: readonly RewritePair[];
+  readonly keep: readonly string[];
+  readonly avoid: readonly string[];
+};
+
+/** The plain-language part of a rule file: what the reference tells a reader, apart from the texts chaff prints. */
+export type RuleGuide = {
+  readonly group: RuleGroup | undefined;
+  /** What the rule finds, in one line. */
+  readonly summary: Localized;
+  /** By language. A rule that runs in one language has an example in that language only. */
+  readonly examples: Readonly<Record<string, RuleExample>>;
+  /** What the rule leaves alone on purpose, so a reader does not take silence for a miss. */
+  readonly notFlagged: Localized;
+  /** What a level's number means, with {limit} for the number ("一文 {limit} 字まで"). None when every level is the same. */
+  readonly levelMeaning: Localized;
+  /** The bibliography entries the rule rests on: the anchors of site/src/content/guide/{ja,en}/bibliography.md. */
+  readonly sources: readonly string[];
+  /** By language, optional per rule. */
+  readonly rewrite: Readonly<Record<string, RuleRewrite>>;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isText = (value: unknown): value is string => typeof value === "string" && value.trim() !== "";
+
+const localizedOf = (value: unknown): Localized =>
+  isRecord(value) ? Object.fromEntries(Object.entries(value).filter((entry): entry is [string, string] => isText(entry[1]))) : {};
+
+const exampleOf = (value: unknown): RuleExample | undefined => {
+  if (!isRecord(value) || !isText(value["before"]) || !isText(value["after"])) return undefined;
+  const config = value["config"];
+  return {
+    before: value["before"],
+    after: value["after"],
+    ...(isRecord(config) ? { config } : {}),
+    ...(value["pad"] === true ? { pad: true } : {}),
+  };
+};
+
+const examplesOf = (value: unknown): Readonly<Record<string, RuleExample>> =>
+  isRecord(value)
+    ? Object.fromEntries(
+        Object.entries(value).flatMap(([language, entry]) => {
+          const example = exampleOf(entry);
+          return example === undefined ? [] : [[language, example] as const];
+        }),
+      )
+    : {};
+
+const textsOf = (value: unknown): string[] => (Array.isArray(value) ? value.filter(isText) : []);
+
+const pairOf = (value: unknown): RewritePair[] =>
+  isRecord(value) && isText(value["before"]) && isText(value["after"]) ? [{ before: value["before"], after: value["after"] }] : [];
+
+/** A block that is written reads field by field; what is missing reads as empty, and the test on rule files names it. */
+const rewriteOf = (value: Readonly<Record<string, unknown>>): RuleRewrite => ({
+  direction: isText(value["direction"]) ? value["direction"] : "",
+  pairs: Array.isArray(value["pairs"]) ? value["pairs"].flatMap(pairOf) : [],
+  keep: textsOf(value["keep"]),
+  avoid: textsOf(value["avoid"]),
+});
+
+const rewritesOf = (value: unknown): Readonly<Record<string, RuleRewrite>> =>
+  isRecord(value)
+    ? Object.fromEntries(Object.entries(value).flatMap(([language, entry]) => (isRecord(entry) ? [[language, rewriteOf(entry)] as const] : [])))
+    : {};
+
+/** A field that is missing or malformed reads as empty; the test on rule files names what a rule lacks. */
+export const ruleGuideOf = (raw: Readonly<Record<string, unknown>>): RuleGuide => ({
+  group: RULE_GROUPS.find((group) => group === raw["group"]),
+  summary: localizedOf(raw["summary"]),
+  examples: examplesOf(raw["example"]),
+  notFlagged: localizedOf(raw["not_flagged"]),
+  levelMeaning: localizedOf(raw["level_meaning"]),
+  sources: textsOf(raw["sources"]),
+  rewrite: rewritesOf(raw["rewrite"]),
+});
+
+/** The rules in each group, in the order the reference lists them. A rule with no group is in none, which the test on rule files reports. */
+export const rulesByGroup = <T>(rules: readonly T[], groupOf: (rule: T) => RuleGroup | undefined): { group: RuleGroup; rules: T[] }[] =>
+  RULE_GROUPS.map((group) => ({ group, rules: rules.filter((rule) => groupOf(rule) === group) }));

package/src/rule-load.ts

@@ -2,7 +2,10 @@ import { readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { parse } from "yaml";
-import type { LevelTable, RuleDefinition, Severity } from "./plugin.ts";
+import type { LanguageLevels, LevelSets, LevelTable, RuleDefinition, Severity } from "./plugin.ts";
+import { rankOfSeverity, severityAt } from "./levels.ts";
+import { optionsOf } from "./rule-options.ts";
+import { ruleGuideOf } from "./rule-guide.ts";
 
 const RULES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "rules");
 
@@ -10,13 +13,8 @@ const isRecord = (value: unknown): value is Record<string, unknown> => typeof va
 
 const isLocalized = (value: unknown): value is Record<string, string> => isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
 
-const SEVERITY_BY_NAME: Readonly<Record<string, number>> = { info: 1, warning: 2, error: 3 };
-
-/** L4 は件数ではなく深刻度を段で持つ。error/warning/info を数に写して同じ器に入れる。 */
-const asNumber = (entry: unknown): number | undefined => {
-  if (typeof entry === "number") return entry;
-  return typeof entry === "string" ? SEVERITY_BY_NAME[entry] : undefined;
-};
+/** 数えるものの無い rule（L4、番号の抜け）は件数ではなく重さを段で持つ。error/warning/info を数に写して同じ器に入れる。 */
+const asNumber = (entry: unknown): number | undefined => (typeof entry === "number" ? entry : rankOfSeverity(entry));
 
 const isLevelTable = (value: unknown): value is LevelTable =>
   isRecord(value) && Object.entries(value).every(([key, entry]) => ["strict", "normal", "relaxed"].includes(key) && asNumber(entry) !== undefined);
@@ -41,6 +39,20 @@ const genreTables = (raw: unknown, language: string): Readonly<Record<string, Le
   return Object.fromEntries(entries);
 };
 
+/** levels を言語別に書いた rule の、loaded 以外の言語の段。言語で分けていない rule は空。 */
+const otherLanguages = (raw: Record<string, unknown>, loaded: string): Record<string, LanguageLevels> => {
+  const levels = raw["levels"];
+  if (!isRecord(levels) || isLevelTable(levels)) return {};
+  return Object.fromEntries(
+    Object.keys(levels)
+      .filter((language) => language !== loaded && language !== "default")
+      .flatMap((language) => {
+        const table = flattenLevels(levels, language);
+        return table === undefined ? [] : [[language, { levels: table, by_genre: genreTables(raw["by_genre"], language) }] as const];
+      }),
+  );
+};
+
 const SEVERITIES: readonly Severity[] = ["error", "warning", "info"];
 const isSeverity = (value: unknown): value is Severity => SEVERITIES.some((entry) => entry === value);
 
@@ -68,8 +80,8 @@ const missingFields = (raw: Record<string, unknown>, levels: LevelTable | undefi
 
 const localizedOf = (value: unknown): Record<string, string> => (isLocalized(value) ? value : {});
 
-/** 見つけ方ごとの message。読めないものは捨てる。 */
-const messagesOf = (value: unknown): Record<string, Record<string, string>> =>
+/** 見つけ方ごとの message、置き場所ごとの読みかた。読めないものは捨てる。 */
+const localizedByKey = (value: unknown): Record<string, Record<string, string>> =>
   isRecord(value) ? Object.fromEntries(Object.entries(value).flatMap(([variant, text]) => (isLocalized(text) ? [[variant, text]] : []))) : {};
 
 /**
@@ -92,38 +104,83 @@ const numberFor = (raw: unknown, language: string): number | undefined => {
 
 const stringList = (value: unknown): string[] | undefined => (Array.isArray(value) ? value.map((entry) => String(entry)) : undefined);
 
+/** What only some rules declare: options beyond the level, and token features the adapter computes on request. */
+const extrasOf = (raw: Record<string, unknown>, file: string): Pick<RuleDefinition, "options" | "token_features"> => ({
+  ...(raw["options"] === undefined ? {} : { options: optionsOf(raw["options"], file) }),
+  ...(raw["token_features"] === undefined ? {} : { token_features: stringList(raw["token_features"]) ?? [] }),
+});
+
+/** The table flattenLevels reads, before its severities become numbers. */
+const writtenTable = (raw: unknown, language: string): unknown => {
+  if (isLevelTable(raw) || !isRecord(raw)) return raw;
+  return raw[language] ?? raw["default"];
+};
+
+/** Every level value written for a language: the rule's own table and each genre's. */
+const writtenValues = (raw: Record<string, unknown>, language: string): unknown[] => {
+  const genres = isRecord(raw["by_genre"]) ? Object.values(raw["by_genre"]) : [];
+  return [raw["levels"], ...genres].flatMap((written) => {
+    const table = writtenTable(written, language);
+    return isRecord(table) ? Object.values(table) : [];
+  });
+};
+
+/** Levels written as severities set the severity; a rule that mixes the two would say both. */
+const levelSetsOf = (raw: Record<string, unknown>, language: string, file: string): LevelSets => {
+  const values = writtenValues(raw, language);
+  const severities = values.filter((value) => typeof value === "string").length;
+  if (severities === 0) return "limit";
+  if (severities < values.length) throw new Error(`${file}: levels と by_genre に重さ（error / warning / info）と数を混ぜて書けません`);
+  // A genre's table would give the rule a default severity other than its severity field.
+  if (isRecord(raw["by_genre"])) throw new Error(`${file}: 重さを段に持つ rule は by_genre を持てません`);
+  return "severity";
+};
+
+/** severity は normal の段の重さそのもの。食い違うと、段を書かないときと normal と書いたときで重さが変わる。 */
+const checkedSeverity = (rule: RuleDefinition, file: string): RuleDefinition => {
+  if (rule.level_sets === "limit" || severityAt(rule, "normal") === rule.severity) return rule;
+  throw new Error(`${file}: severity ${rule.severity} が levels の normal（${severityAt(rule, "normal")}）と違います`);
+};
+
 const toRule = (raw: unknown, language: string, file: string): RuleDefinition => {
   if (!isRecord(raw)) throw new Error(`${file}: rule は object であること`);
   const levels = flattenLevels(raw["levels"], language);
   const missing = missingFields(raw, levels);
   if (missing.length > 0) throw new Error(`${file}: 必須フィールドがありません: ${missing.join(", ")}`);
   if (levels === undefined) throw new Error(`${file}: levels を解決できません`);
-  return {
-    id: String(raw["id"]),
-    layer: pick(raw["layer"], LAYERS) ?? "L1",
-    status: pick(raw["status"], STATUSES) ?? "experimental",
-    name: localizedOf(raw["name"]),
-    why: localizedOf(raw["why"]),
-    how_to_fix: localizedOf(raw["how_to_fix"]),
-    message: localizedOf(raw["message"]),
-    messages: messagesOf(raw["messages"]),
-    levels,
-    by_genre: genreTables(raw["by_genre"], language),
-    how_to_find: String(raw["how_to_find"]),
-    word_list: typeof raw["word_list"] === "string" ? raw["word_list"] : undefined,
-    extra_word_lists: stringList(raw["extra_word_lists"]) ?? [],
-    what_to_check: isLocalized(raw["what_to_check"]) ? raw["what_to_check"] : undefined,
-    where: typeof raw["where"] === "string" ? raw["where"] : undefined,
-    full_sentence: numberFor(raw["full_sentence"], language),
-    requires: stringList(raw["requires"]) ?? [],
-    uses: stringList(raw["uses"]) ?? [],
-    from: stringList(raw["from"]) ?? [],
-    languages: stringList(raw["languages"]),
-    use_for: Array.isArray(raw["use_for"]) ? raw["use_for"].map((entry) => String(entry)) : [],
-    severity: severityOf(raw["severity"], language),
-  };
+  return checkedSeverity(ruleOf(raw, levels, levelSetsOf(raw, language, file), language, file), file);
 };
 
+const ruleOf = (raw: Record<string, unknown>, levels: LevelTable, levelSets: LevelSets, language: string, file: string): RuleDefinition => ({
+  id: String(raw["id"]),
+  layer: pick(raw["layer"], LAYERS) ?? "L1",
+  status: pick(raw["status"], STATUSES) ?? "experimental",
+  name: localizedOf(raw["name"]),
+  why: localizedOf(raw["why"]),
+  how_to_fix: localizedOf(raw["how_to_fix"]),
+  message: localizedOf(raw["message"]),
+  messages: localizedByKey(raw["messages"]),
+  placeholders: localizedByKey(raw["placeholders"]),
+  levels,
+  level_sets: levelSets,
+  by_genre: genreTables(raw["by_genre"], language),
+  other_languages: otherLanguages(raw, language),
+  how_to_find: String(raw["how_to_find"]),
+  word_list: typeof raw["word_list"] === "string" ? raw["word_list"] : undefined,
+  extra_word_lists: stringList(raw["extra_word_lists"]) ?? [],
+  what_to_check: isLocalized(raw["what_to_check"]) ? raw["what_to_check"] : undefined,
+  where: typeof raw["where"] === "string" ? raw["where"] : undefined,
+  full_sentence: numberFor(raw["full_sentence"], language),
+  requires: stringList(raw["requires"]) ?? [],
+  uses: stringList(raw["uses"]) ?? [],
+  from: stringList(raw["from"]) ?? [],
+  languages: stringList(raw["languages"]),
+  use_for: Array.isArray(raw["use_for"]) ? raw["use_for"].map((entry) => String(entry)) : [],
+  severity: severityOf(raw["severity"], language),
+  ...extrasOf(raw, file),
+  guide: ruleGuideOf(raw),
+});
+
 /**
  * 読めない rule ファイルは、どれが何で読めないかを言う。
  * yaml の例外をそのまま投げると、スタックトレースだけが出てファイル名が出ない。

package/src/rule-options.ts

@@ -0,0 +1,131 @@
+import type { Localized, OptionValue, RuleOption } from "./plugin.ts";
+
+// A rule's options: what its YAML declares, whether a written value fits, and which setting decides each one.
+// Pure: no file is read here. The settings come in as layers, strongest first (chaff.yaml, then a style, then the default).
+
+const KINDS: readonly RuleOption["kind"][] = ["choice", "count", "words"];
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isLocalized = (value: unknown): value is Localized =>
+  isRecord(value) && Object.keys(value).length > 0 && Object.values(value).every((entry) => typeof entry === "string" && entry !== "");
+
+const isCount = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 1;
+
+const isWords = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim() !== "");
+
+/** Whether value fits the option: one of the choices, a whole number of 1 or more, or a list of words. */
+export const fitsOption = (option: RuleOption, value: unknown): value is OptionValue => {
+  if (option.kind === "count") return isCount(value);
+  if (option.kind === "words") return isWords(value);
+  return typeof value === "string" && option.choices.includes(value);
+};
+
+/** What a value must look like, for a problem message: the choices, or the kind. */
+export const expectedOf = (option: RuleOption): string => (option.kind === "choice" ? option.choices.join(" / ") : option.kind);
+
+const kindOf = (raw: Record<string, unknown>, where: string): RuleOption["kind"] => {
+  const kind = KINDS.find((entry) => entry === raw["kind"]);
+  if (kind === undefined) throw new Error(`${where}: kind must be one of ${KINDS.join(", ")}`);
+  return kind;
+};
+
+const choicesOf = (raw: Record<string, unknown>, kind: RuleOption["kind"], where: string): string[] => {
+  if (kind !== "choice") return [];
+  const choices = raw["choices"];
+  if (!isRecord(choices) || Object.keys(choices).length < 2) throw new Error(`${where}: a choice needs two or more choices, each with its meaning`);
+  return Object.keys(choices);
+};
+
+const choiceNamesOf = (raw: Record<string, unknown>, where: string): Record<string, Localized> => {
+  const choices = raw["choices"];
+  if (!isRecord(choices)) return {};
+  return Object.fromEntries(
+    Object.entries(choices).map(([choice, meaning]) => {
+      if (!isLocalized(meaning)) throw new Error(`${where}: choice ${choice} needs its meaning in ja and/or en`);
+      return [choice, meaning];
+    }),
+  );
+};
+
+const optionOf = (name: string, raw: unknown, file: string): RuleOption => {
+  const where = `${file}: options.${name}`;
+  if (!isRecord(raw)) throw new Error(`${where} must be a map`);
+  const kind = kindOf(raw, where);
+  const about = raw["about"];
+  if (!isLocalized(about)) throw new Error(`${where}: about needs what the option decides, in ja and/or en`);
+  const option: RuleOption = {
+    kind,
+    choices: choicesOf(raw, kind, where),
+    default: kind === "words" ? [] : 0,
+    about,
+    choiceNames: kind === "choice" ? choiceNamesOf(raw, where) : {},
+  };
+  const fallback: unknown = raw["default"] ?? (kind === "words" ? [] : undefined);
+  if (!fitsOption(option, fallback)) throw new Error(`${where}: default must be ${expectedOf(option)}`);
+  return { ...option, default: fallback };
+};
+
+/** The options a rule's YAML declares. A wrong declaration is chaff's own bug, so it throws with the file and the option. */
+export const optionsOf = (raw: unknown, file: string): Record<string, RuleOption> => {
+  if (raw === undefined) return {};
+  if (!isRecord(raw)) throw new Error(`${file}: options must be a map of option names`);
+  return Object.fromEntries(Object.entries(raw).map(([name, option]) => [name, optionOf(name, option, file)]));
+};
+
+/** One place settings come from, and what it sets: { rule id: { option: value } }. */
+export type OptionLayer = { readonly from: string; readonly values: Readonly<Record<string, unknown>> };
+
+export type SettledOption = { readonly value: OptionValue; readonly from: string };
+
+/** The source name of an option left at its default. */
+export const DEFAULT_SOURCE = "default";
+
+const optionMap = (layer: OptionLayer, ruleId: string): Readonly<Record<string, unknown>> => {
+  const values = layer.values[ruleId];
+  return isRecord(values) ? values : {};
+};
+
+/**
+ * Each option of a rule at the value of the strongest layer that sets it with a value that fits, and where that came from.
+ * A value that does not fit falls through to the next layer; optionProblems says so, so it is never silent.
+ */
+export const settleOptions = (ruleId: string, options: Readonly<Record<string, RuleOption>>, layers: readonly OptionLayer[]): Record<string, SettledOption> =>
+  Object.fromEntries(
+    Object.entries(options).map(([name, option]) => {
+      const fitting = layers.flatMap((layer): SettledOption[] => {
+        const value = optionMap(layer, ruleId)[name];
+        return fitsOption(option, value) ? [{ value, from: layer.from }] : [];
+      });
+      return [name, fitting[0] ?? { value: option.default, from: DEFAULT_SOURCE }];
+    }),
+  );
+
+/** The values alone, as the detector gets them. */
+export const optionValues = (settled: Readonly<Record<string, SettledOption>>): Record<string, OptionValue> =>
+  Object.fromEntries(Object.entries(settled).map(([name, entry]) => [name, entry.value]));
+
+/** What a layer sets that has no effect: an unknown rule, a rule with no options, an unknown option, or a value that does not fit. */
+export type OptionProblem =
+  | { readonly kind: "unknown-rule"; readonly rule: string }
+  | { readonly kind: "no-options"; readonly rule: string }
+  | { readonly kind: "not-a-map"; readonly rule: string }
+  | { readonly kind: "unknown-option"; readonly rule: string; readonly option: string; readonly known: readonly string[] }
+  | { readonly kind: "bad-value"; readonly rule: string; readonly option: string; readonly value: string; readonly expected: string };
+
+const printed = (value: unknown): string => JSON.stringify(value) ?? String(value);
+
+const problemsOfRule = (ruleId: string, options: Readonly<Record<string, RuleOption>> | undefined, written: unknown): OptionProblem[] => {
+  if (options === undefined) return [{ kind: "unknown-rule", rule: ruleId }];
+  if (Object.keys(options).length === 0) return [{ kind: "no-options", rule: ruleId }];
+  if (!isRecord(written)) return [{ kind: "not-a-map", rule: ruleId }];
+  return Object.entries(written).flatMap(([name, value]): OptionProblem[] => {
+    const option = options[name];
+    if (option === undefined) return [{ kind: "unknown-option", rule: ruleId, option: name, known: Object.keys(options) }];
+    return fitsOption(option, value) ? [] : [{ kind: "bad-value", rule: ruleId, option: name, value: printed(value), expected: expectedOf(option) }];
+  });
+};
+
+/** Every problem in what a layer sets, given each known rule's options (a rule with none maps to {}). */
+export const optionProblems = (layer: OptionLayer, known: Readonly<Record<string, Readonly<Record<string, RuleOption>>>>): OptionProblem[] =>
+  Object.entries(layer.values).flatMap(([ruleId, written]) => problemsOfRule(ruleId, known[ruleId], written));

package/src/run-semantic.ts

@@ -6,6 +6,7 @@ import { localized } from "./render/text.ts";
 import type { AdapterNeeds, Finding, Level, ProseDocument, RuleDefinition, Severity } from "./plugin.ts";
 import { lineStarts, placeOf } from "./position.ts";
 import { wantsTags } from "./run.ts";
+import { byPosition } from "./finding-order.ts";
 
 export type SemanticResult = {
   readonly findings: readonly Finding[];
@@ -137,7 +138,7 @@ export const runSemantic = async (
     ),
   );
   return {
-    findings: answers.filter((finding) => finding !== undefined).toSorted((left, right) => left.line - right.line),
+    findings: answers.filter((finding) => finding !== undefined).toSorted(byPosition),
     skipped,
     asked: live.reduce((sum, job) => sum + job.candidates.length, 0),
     sentencesSeen: doc.sentences.length,