chaffjs 0.21.0 → 0.23.0

package/src/detectors/toc-heading.ts

@@ -0,0 +1,125 @@
+import type { Detector, Finding } from "../plugin.ts";
+import { headingWords } from "../structure-shape/heading-words.ts";
+import { quoteAround } from "./quote-around.ts";
+
+// 目次の項目が、文書のどの見出しとも合わない所。目次の見出しは語彙表 toc-heading が言う。
+// 項目と見出しは、空白・記号・大文字小文字を無視して比べ、頭の番号（1.2、2-1、第3章）を外しても比べる。
+
+/** 見出しの無い目次の項目 1 つ。entry は項目の言葉（リンクなら字の部分）。 */
+export type StrayTocEntry = { readonly offset: number; readonly entry: string };
+
+type Line = { readonly text: string; readonly offset: number };
+type Heading = { readonly title: string; readonly offset: number };
+
+const HEADING = /^[ \t]{0,3}#{1,6}[ \t]/u;
+const FENCE = /^[ \t]*(?:```|~~~)/u;
+const LIST_ITEM = /^[ \t]*(?:[-*+]|\d{1,3}[.)])[ \t]/u;
+const LINK_TEXT = /^\[(?<text>[^\]]*)\]\([^)]*\)/u;
+const ATTRIBUTES = /\{#[^}]*\}/gu;
+const DIGIT = /[\d０-９]/u;
+const LEADER_DOTS = new Set([".", "…", "・"]);
+const MIN_LEADER = 2;
+/** 目次の項目のうち見出しに合わないものがこれより多ければ、目次は別の書き方の見出し（本文に無い章立て）と読んで言わない。 */
+const MAX_STRAY_SHARE = 0.5;
+
+const linesOf = (source: string): Line[] => [...source.matchAll(/^.*$/gmu)].map((match) => ({ text: match[0], offset: match.index }));
+
+/** コードの囲みの外の行。 */
+const outsideFences = (lines: readonly Line[]): Line[] => {
+  const fence = { open: false };
+  return lines.filter((line) => {
+    if (FENCE.test(line.text)) {
+      fence.open = !fence.open;
+      return false;
+    }
+    return !fence.open;
+  });
+};
+
+/** 比べるための形。全角を半角にそろえ（４ と 4）、空白・記号を消し、小文字にする。 */
+const comparable = (text: string): string =>
+  text
+    .replace(ATTRIBUTES, "")
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[\s\p{P}\p{S}]/gu, "");
+
+/** 頭の番号（1.2、2-1、第3章）と飾りを外した、比べるための形。 */
+const withoutNumber = (text: string): string => comparable(headingWords(text));
+
+/** text の終わりから、isTail に当たる字を外したもの。 */
+const trimTail = (text: string, isTail: (char: string) => boolean): string => {
+  const chars = [...text];
+  return chars.slice(0, chars.findLastIndex((char) => !isTail(char)) + 1).join("");
+};
+
+/** 見出しの行の題（頭と終わりの # を外す）。見出しでなければ undefined。 */
+const headingTitle = (line: string): string | undefined => {
+  if (!HEADING.test(line)) return undefined;
+  const withoutMarks = line.trim().replace(/^#+/u, "").trim();
+  return trimTail(withoutMarks, (char) => char === "#").trim();
+};
+
+/** 終わりのページ番号（「背景 ........ 3」の 3 と点線）。点線の無い数（Step 3）は題のうち。 */
+const withoutPageNumber = (text: string): string => {
+  const before = trimTail(text, (char) => DIGIT.test(char)).trimEnd();
+  if (before === text.trimEnd()) return text;
+  const title = trimTail(before, (char) => LEADER_DOTS.has(char));
+  return before.length - title.length >= MIN_LEADER ? title.trim() : text;
+};
+
+/** 項目の言葉と、項目の行の中でそれが始まる所。リンクなら字の部分（番号の後ろのリンク「1. [概要](#…)」も）。 */
+const entryOf = (item: string): { readonly text: string; readonly start: number } => {
+  const bracket = item.indexOf("[");
+  const link = bracket === -1 ? undefined : LINK_TEXT.exec(item.slice(bracket))?.groups?.["text"];
+  if (link !== undefined) return { text: withoutPageNumber(link), start: bracket + 1 };
+  return { text: withoutPageNumber(item.trim()), start: item.length - item.trimStart().length };
+};
+
+const matchesHeading = (entry: string, headings: readonly Heading[]): boolean =>
+  headings.some(
+    (heading) => comparable(heading.title) === comparable(entry) || (withoutNumber(entry) !== "" && withoutNumber(heading.title) === withoutNumber(entry)),
+  );
+
+/** 目次の見出しの下（次の見出しまで）の箇条書きの項目。 */
+const entriesUnder = (lines: readonly Line[], tocAt: number): Line[] => {
+  const after = lines.filter((line) => line.offset > tocAt);
+  const end = after.findIndex((line) => HEADING.test(line.text));
+  return (end === -1 ? after : after.slice(0, end)).flatMap((line) => {
+    const marker = LIST_ITEM.exec(line.text)?.[0];
+    if (marker === undefined) return [];
+    const entry = entryOf(line.text.slice(marker.length));
+    return [{ text: entry.text, offset: line.offset + marker.length + entry.start }];
+  });
+};
+
+/** 文書の目次の項目のうち、どの見出しとも合わないもの。 */
+export const strayTocEntries = (source: string, tocWords: readonly string[]): StrayTocEntry[] => {
+  const lines = outsideFences(linesOf(source));
+  const headings = lines.flatMap((line) => {
+    const title = headingTitle(line.text);
+    return title === undefined ? [] : [{ title, offset: line.offset }];
+  });
+  const tocNames = new Set(tocWords.map(comparable));
+  return headings
+    .filter((heading) => tocNames.has(comparable(heading.title)))
+    .flatMap((toc) => {
+      const entries = entriesUnder(lines, toc.offset).filter((entry) => entry.text !== "");
+      const others = headings.filter((heading) => heading !== toc);
+      const stray = entries.filter((entry) => !matchesHeading(entry.text, others));
+      return stray.length > entries.length * MAX_STRAY_SHARE ? [] : stray.map((entry) => ({ offset: entry.offset, entry: entry.text }));
+    });
+};
+
+export const tocHeading: Detector = (doc): Finding[] =>
+  strayTocEntries(
+    doc.source,
+    (doc.lexicons["toc-heading"] ?? []).map((entry) => entry.pattern),
+  ).map((stray) => ({
+    rule: "",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAround(doc.source, stray.offset, stray.offset + stray.entry.length),
+    values: { entry: stray.entry, offset: stray.offset },
+  }));

package/src/extension/load.ts

@@ -2,6 +2,7 @@ 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 type { GuideLayer } from "../genre-guide/layer.ts";
 import { customRulesOf } from "../custom/load.ts";
 import { withStyle } from "../config/style.ts";
 import { moduleDetector } from "./module-detector.ts";
@@ -33,6 +34,8 @@ export type Extensions = {
   readonly lexicons: Readonly<Record<string, Readonly<Record<string, Lexicon>>>>;
   /** The plugins' house styles. */
   readonly styles: readonly StyleDefinition[];
+  /** The plugins' changes to the genre guides, in the order chaff.yaml lists the plugins. */
+  readonly guides?: readonly GuideLayer[];
   readonly problems: readonly LoadProblem[];
   readonly pluginProblems: readonly PluginProblem[];
 };
@@ -85,6 +88,7 @@ const loadExtensions = async (config: Config): Promise<Extensions> => {
     rules: plugins.flatMap((plugin) => plugin.rules),
     lexicons: lexiconsByLanguage(plugins),
     styles: plugins.flatMap((plugin) => plugin.styles),
+    guides: plugins.flatMap((plugin) => (plugin.guide === undefined ? [] : [plugin.guide])),
     problems: modules.flatMap((entry) => ("problem" in entry.loaded ? [entry.loaded.problem] : [])),
     pluginProblems,
   };

package/src/extension/pack-read.ts

@@ -123,6 +123,7 @@ export const readPack = (dir: string, manifest: Readonly<Record<string, unknown>
       rules: rules.value,
       lexicons: lexicons.value,
       styles: styles.value,
+      ...(manifest["guide"] === undefined ? {} : { guide: manifest["guide"] }),
     },
   };
 };

package/src/extension/plugin-load.ts

@@ -19,7 +19,7 @@ export type LoadedPlugins = { readonly plugins: readonly ParsedPlugin[]; readonl
 /** pack: the folder of a rule pack (YAML only), which is read rather than imported. */
 type Located = { readonly origin: PluginOrigin; readonly pack?: string } | { readonly problem: PluginProblem };
 
-const problemOf = (kind: Exclude<PluginProblem["kind"], "rule">, plugin: string, detail = ""): { problem: PluginProblem } => ({
+const problemOf = (kind: Exclude<PluginProblem["kind"], "rule" | "guide">, plugin: string, detail = ""): { problem: PluginProblem } => ({
   problem: { kind, plugin, detail },
 });
 

package/src/extension/plugin-parse.ts

@@ -7,6 +7,7 @@ import type { UntrustedDetector } from "./module-detector.ts";
 import { describeValue } from "./returned-findings.ts";
 import { isPluginName } from "./plugin-name.ts";
 import { knownGenres } from "../known-genres.ts";
+import { guideLayerOf, type GuideLayer, type GuideProblem } from "../genre-guide/layer.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
@@ -32,7 +33,8 @@ type PluginProblemKind =
 /** 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 };
+  | { readonly kind: "rule"; readonly plugin: string; readonly problem: CustomProblem }
+  | { readonly kind: "guide"; readonly plugin: string; readonly problem: GuideProblem };
 
 /** 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 };
@@ -47,11 +49,13 @@ export type ParsedPlugin = {
   /** 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[];
+  /** Its changes to the genre guides, applied whenever the plugin is loaded: under a style's and chaff.yaml's. */
+  readonly guide?: GuideLayer | undefined;
 };
 
 export type PluginRead = { readonly plugin: ParsedPlugin | undefined; readonly problems: readonly PluginProblem[] };
 
-type Problem = (kind: Exclude<PluginProblem["kind"], "rule">, detail: string) => PluginProblem;
+type Problem = (kind: Exclude<PluginProblem["kind"], "rule" | "guide">, detail: string) => PluginProblem;
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -215,6 +219,16 @@ const stylesOf = (raw: unknown, name: string, problem: Problem): Styles => {
   };
 };
 
+// ───────── guide ─────────
+
+type Guide = { readonly guide: GuideLayer | undefined; readonly problems: readonly PluginProblem[] };
+
+const guideOf = (raw: unknown, name: string, written: string): Guide => {
+  if (raw === undefined) return { guide: undefined, problems: [] };
+  const read = guideLayerOf(raw, `plugins: ${name}`, knownGenres());
+  return { guide: read.layer, problems: read.problems.map((problem) => ({ kind: "guide", plugin: written, 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. */
@@ -229,8 +243,17 @@ export const parsePlugin = (exported: unknown, origin: PluginOrigin, useFor: rea
   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];
+  const guide = guideOf(exported["guide"], name, origin.written);
+  const problems = [...rules.problems, ...lexicons.problems, ...styles.problems, ...guide.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 };
+  const plugin = {
+    name,
+    written: origin.written,
+    rules: rules.rules,
+    detectors: rules.detectors,
+    lexicons: lexicons.lexicons,
+    styles: styles.styles,
+    ...(guide.guide === undefined ? {} : { guide: guide.guide }),
+  };
   return { plugin, problems: [] };
 };

package/src/extension/problem-text.ts

@@ -4,6 +4,7 @@ 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";
+import { guideProblemText } from "../genre-guide/problem-text.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.
@@ -11,7 +12,9 @@ import type { PluginProblem } from "./plugin-parse.ts";
 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>>;
+  readonly problems: Readonly<Record<Exclude<PluginProblem["kind"], "rule" | "guide">, (plugin: string, detail: string) => string>>;
+  /** Where a plugin's guide is, for a problem chaff.yaml's guide could have too. */
+  readonly guideScope: (plugin: string) => string;
   /** Where a plugin's rule is, for a problem a rule in custom_rules could have too. */
   readonly ruleScope: (plugin: string) => string;
 };
@@ -42,6 +45,7 @@ const MODULE_TEXT: Texts<ModuleText> = {
 const PLUGIN_TEXT: Texts<PluginText> = {
   ja: {
     ruleScope: (plugin) => `plugins の ${plugin} の rules`,
+    guideScope: (plugin) => `plugins の ${plugin}`,
     problems: {
       "not-a-list": (_plugin, detail) => `plugins はプラグインの並び（- chaff-plugin-foo や - ./local-plugin）で書いてください（${detail}）`,
       "bad-specifier": (plugin) =>
@@ -65,6 +69,7 @@ const PLUGIN_TEXT: Texts<PluginText> = {
   },
   en: {
     ruleScope: (plugin) => `plugins ${plugin} rules`,
+    guideScope: (plugin) => `plugins ${plugin}`,
     problems: {
       "not-a-list": (_plugin, detail) => `write plugins as a list (- chaff-plugin-foo or - ./local-plugin), not ${detail}`,
       "bad-specifier": (plugin) =>
@@ -90,6 +95,7 @@ const PLUGIN_TEXT: Texts<PluginText> = {
 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));
+  if (problem.kind === "guide") return `${text.guideScope(problem.plugin)}: ${guideProblemText(problem.problem, ui)}`;
   return text.problems[problem.kind](problem.plugin, problem.detail);
 };
 

package/src/fix-plan/plan.ts

@@ -8,6 +8,7 @@ import { COMPOSITE_RULE, recommendMode, type ModeChoice } from "./mode.ts";
 import type { StructureScore } from "../structure-shape/score.ts";
 import { structureTargetsOf, type StructureTarget } from "./structure-targets.ts";
 import { DEFAULT_DEPTH, depthIncludes, type RewriteDepth } from "../rewrite-depth.ts";
+import type { ReportedGuide } from "../genre-guide/report.ts";
 
 /** One flagged spot, where it is and what chaff said about it. */
 export type PlanSpot = { readonly line: number; readonly column: number; readonly quote: string; readonly message: string };
@@ -46,6 +47,8 @@ export type FixPlan = {
   readonly rewrittenPath: string;
   readonly language: string;
   readonly genre: string;
+  /** What a good document of the genre does, to rewrite against; null when the genre was not set or the guide is off. */
+  readonly guide: ReportedGuide | null;
   readonly experimental: boolean;
   readonly mode: ModeChoice;
   /** None when chaff recommends the depth itself. */
@@ -80,6 +83,7 @@ export type PlanInput = {
   /** The ai-tell lexicon of the document's language, whose entries may carry their own hint. */
   readonly phrases: Lexicon;
   readonly chosenDepth?: ChosenDepth | undefined;
+  readonly guide?: ReportedGuide | undefined;
 };
 
 const BOLD_DENSITY_RULE = "bold-density";
@@ -220,6 +224,7 @@ export const buildFixPlan = (input: PlanInput): FixPlan => {
     rewrittenPath: rewrittenPathOf(input.path),
     language: input.language,
     genre: input.genre,
+    guide: input.guide ?? null,
     experimental: input.experimental,
     mode,
     chosenDepth: input.chosenDepth,

package/src/fix-plan/render.ts

@@ -129,6 +129,14 @@ const checkLines = (plan: FixPlan, text: FixPlanText): string[] => [
   text.checksNote,
 ];
 
+/** The genre's guide, first: the instruction the rewrite is held to. Nothing when the genre was not set or the guide is off. */
+const guideLines = (plan: FixPlan, text: FixPlanText): string[] => {
+  const { guide } = plan;
+  if (guide === null) return [];
+  const rules = guide.rules.length === 0 ? [] : ["", text.guideRules(guide.rules.map((rule) => `\`${rule}\``).join(", "))];
+  return [`## ${text.guideHeading(guide.name, guide.genre)}`, "", text.guideLead, "", ...bullets(guide.lines), ...rules, ""];
+};
+
 const textOf = (plan: FixPlan): FixPlanText => FIX_PLAN_TEXT[uiLanguageOf(plan.language)];
 
 /** The plan as Markdown, in the document's language: what an agent reads before rewriting. */
@@ -141,6 +149,7 @@ export const renderFixPlanMarkdown = (plan: FixPlan): string => {
     "",
     text.intro,
     "",
+    ...guideLines(plan, text),
     `## ${text.constraintsHeading}`,
     "",
     ...text.constraints.map((constraint, index) => `${String(index + 1)}. ${constraint}`),

package/src/fix-plan/text.ts

@@ -7,6 +7,10 @@ export type FixPlanText = {
   readonly title: (path: string) => string;
   readonly about: (language: string, genre: string) => string;
   readonly intro: string;
+  /** The genre's guide, as the first section: what the rewrite is held to. */
+  readonly guideHeading: (name: string, genre: string) => string;
+  readonly guideLead: string;
+  readonly guideRules: (ids: string) => string;
   readonly constraintsHeading: string;
   readonly constraints: readonly string[];
   readonly modeHeading: string;
@@ -43,12 +47,15 @@ export type FixPlanText = {
 
 export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
   ja: {
-    usage: "使い方: chaff fix-plan <file> [--depth light|structure|register] [--experimental] [--genre <ジャンル>] [--json]",
+    usage: "使い方: chaff fix-plan <file> [--depth light|structure|register] [--experimental] [--genre <ジャンル>] [--no-guide] [--json]",
     notFound: (path) => `${path} がありません。`,
     title: (path) => `直す計画: ${path}`,
     about: (language, genre) => `言語 ${language}、ジャンル ${genre}`,
     intro:
       "chaff が機械で見つけた箇所と、それぞれの直す方向です。chaff は書き直しません。書き直すのは、この計画を読む人か AI です。直したら、最後の確かめのコマンドを実行してください。",
+    guideHeading: (name, genre) => `指針: ${name}（${genre}）`,
+    guideLead: "このジャンルのよい文書が満たすことです。書き直しはこれに沿わせ、書き終えたら一つずつ確かめてください。",
+    guideRules: (ids) => `このジャンルで特に効く rule: ${ids}`,
     constraintsHeading: "守ること",
     constraints: [
       "事実、数、日付、条件、名前を変えない。",
@@ -109,12 +116,15 @@ export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
       "1 つめは書き直した文書の指摘、2 つめは事実が落ちていないか・足されていないか、3 つめは構成の変化です。数は chaff の出力から取り、形容詞で言わないでください。",
   },
   en: {
-    usage: "usage: chaff fix-plan <file> [--depth light|structure|register] [--experimental] [--genre <genre>] [--json]",
+    usage: "usage: chaff fix-plan <file> [--depth light|structure|register] [--experimental] [--genre <genre>] [--no-guide] [--json]",
     notFound: (path) => `${path} does not exist.`,
     title: (path) => `Fix plan: ${path}`,
     about: (language, genre) => `language ${language}, genre ${genre}`,
     intro:
       "What chaff found by machine, and how to rewrite each kind of spot. chaff does not rewrite; whoever reads this plan does, a person or an AI. When done, run the checks at the end.",
+    guideHeading: (name, genre) => `Guide: ${name} (${genre})`,
+    guideLead: "What a good document of this genre does. Rewrite toward it, and check the result against each line when done.",
+    guideRules: (ids) => `Rules that matter most for this genre: ${ids}`,
     constraintsHeading: "Constraints",
     constraints: [
       "Keep every fact, number, date, condition and name.",

package/src/genre-guide/key-rules.ts

@@ -0,0 +1,37 @@
+import { presetLevelsOf, type GenreData } from "../genre-parse.ts";
+import type { Level, RuleDefinition } from "../plugin.ts";
+import { standingIn } from "../rule-genres.ts";
+
+/** A rule that runs in at most this share of the genres speaks for the few it runs in. */
+const RARE_SHARE = 0.25;
+
+type RuleFacts = Pick<RuleDefinition, "id" | "status" | "use_for" | "languages">;
+
+const runsIn = (rule: RuleFacts, data: GenreData, genre: string): boolean => standingIn(rule, genre, presetLevelsOf(data, genre)).kind === "on";
+
+const isRare = (rule: RuleFacts, data: GenreData): boolean =>
+  data.genres.filter((entry) => runsIn(rule, data, entry.id)).length <= data.genres.length * RARE_SHARE;
+
+const readsLanguage = (rule: RuleFacts, language: string): boolean => rule.languages === undefined || rule.languages.includes(language);
+
+/**
+ * The rules that matter most for a genre, by id: those its preset turns on, and those that run in it but in few other
+ * genres. A rule the team's settings turn off is left out. Pure: the genres and the settings come in.
+ */
+export const keyRulesOf = (
+  rules: readonly RuleFacts[],
+  data: GenreData,
+  genre: string,
+  language: string,
+  settings: Readonly<Record<string, Level>>,
+): string[] => {
+  const preset = presetLevelsOf(data, genre);
+  const matters = (rule: RuleFacts): boolean => {
+    const standing = standingIn(rule, genre, preset);
+    return standing.kind === "on" && (standing.byPreset || isRare(rule, data));
+  };
+  return rules
+    .filter((rule) => readsLanguage(rule, language) && settings[rule.id] !== "off" && matters(rule))
+    .map((rule) => rule.id)
+    .toSorted((left, right) => left.localeCompare(right, "en"));
+};

package/src/genre-guide/layer.ts

@@ -0,0 +1,77 @@
+import { guideLinesOf, type GuideLines } from "./lines.ts";
+
+// A team's changes to the genre guides, as chaff.yaml, a style or a rule pack writes them under guide:
+//
+//   guide:
+//     blog/tech:                # a genre, or a group (legal) for every genre in it
+//       add: { ja: [...], en: [...] }
+//     legal/contract:
+//       replace: { ja: [...], en: [...] }
+//     business/email: off
+//
+// replace sets the lines for the languages it gives (the others keep theirs); add puts lines after them; off leaves the
+// genre with no guide. A text or a list alone, without ja: or en:, is the same in every language. guide: off turns every
+// genre's guide off; a stronger layer may still add lines back.
+
+export type GuideEdit = { readonly kind: "off" } | { readonly kind: "edit"; readonly replace?: GuideLines; readonly add?: GuideLines };
+
+/**
+ * One place's changes, by genre or group, and the place as a reader is told it (chaff.yaml, style: house, plugins: foo).
+ * allOff: guide: off, which empties every genre's guide before this layer's own entries.
+ */
+export type GuideLayer = { readonly from: string; readonly allOff: boolean; readonly edits: Readonly<Record<string, GuideEdit>> };
+
+/** What could not be read: the genre or group it was written under (none when guide: itself is wrong), and what was there. */
+export type GuideProblem =
+  | { readonly kind: "not-a-map"; readonly written: string }
+  | { readonly kind: "unknown-genre"; readonly genre: string }
+  | { readonly kind: "bad-entry"; readonly genre: string; readonly written: string }
+  | { readonly kind: "bad-lines"; readonly genre: string; readonly field: "replace" | "add" };
+
+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) ?? String(value);
+
+/** Whether guide: as written turns every guide off (guide: off, or false). */
+export const turnsGuidesOff = (raw: unknown): boolean => raw === "off" || raw === false;
+
+const EDIT_FIELDS: ReadonlySet<string> = new Set(["replace", "add"]);
+
+type Read = { readonly edit: GuideEdit } | { readonly problem: GuideProblem };
+
+type LinesRead = { readonly lines: GuideLines | undefined } | { readonly problem: GuideProblem };
+
+const linesIn = (raw: Record<string, unknown>, field: "replace" | "add", genre: string): LinesRead => {
+  if (raw[field] === undefined) return { lines: undefined };
+  const lines = guideLinesOf(raw[field]);
+  return lines === undefined ? { problem: { kind: "bad-lines", genre, field } } : { lines };
+};
+
+const editOf = (genre: string, value: unknown): Read => {
+  if (turnsGuidesOff(value)) return { edit: { kind: "off" } };
+  const fields = isRecord(value) ? Object.keys(value) : [];
+  if (!isRecord(value) || fields.length === 0 || fields.some((field) => !EDIT_FIELDS.has(field))) {
+    return { problem: { kind: "bad-entry", genre, written: printed(value) } };
+  }
+  const replace = linesIn(value, "replace", genre);
+  if ("problem" in replace) return replace;
+  const add = linesIn(value, "add", genre);
+  if ("problem" in add) return add;
+  return { edit: { kind: "edit", ...(replace.lines === undefined ? {} : { replace: replace.lines }), ...(add.lines === undefined ? {} : { add: add.lines }) } };
+};
+
+/**
+ * guide: as written, read into a layer. known: the genres and groups an entry may name. An entry that cannot be read is
+ * left out and reported; the rest still apply. Nothing written is an empty layer.
+ */
+export const guideLayerOf = (raw: unknown, from: string, known: readonly string[]): { layer: GuideLayer; problems: GuideProblem[] } => {
+  if (raw === undefined || raw === null || turnsGuidesOff(raw)) return { layer: { from, allOff: turnsGuidesOff(raw), edits: {} }, problems: [] };
+  if (!isRecord(raw)) return { layer: { from, allOff: false, edits: {} }, problems: [{ kind: "not-a-map", written: printed(raw) }] };
+  const read = Object.entries(raw).map(([genre, value]): readonly [string, Read] =>
+    known.includes(genre) ? [genre, editOf(genre, value)] : [genre, { problem: { kind: "unknown-genre", genre } }],
+  );
+  return {
+    layer: { from, allOff: false, edits: Object.fromEntries(read.flatMap(([genre, entry]) => ("edit" in entry ? [[genre, entry.edit]] : []))) },
+    problems: read.flatMap(([, entry]) => ("problem" in entry ? [entry.problem] : [])),
+  };
+};

package/src/genre-guide/lines.ts

@@ -0,0 +1,41 @@
+// What a good document of a genre looks like, as lines an AI or a person checks a draft against: genres.yaml's guide:,
+// and the replace / add a team writes over it. Pure: the YAML comes in already parsed.
+
+/** The guide's lines by language: { ja: [...], en: [...] }. */
+export type GuideLines = Readonly<Record<string, readonly string[]>>;
+
+/** The languages a guide is written in: chaff's. A text written without ja: or en: is given to each. */
+export const GUIDE_LANGUAGES: readonly string[] = ["ja", "en"];
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isLine = (value: unknown): value is string => typeof value === "string" && value.trim() !== "";
+
+/** One line, or a list of them. undefined when anything in it is not a line of text. */
+export const linesOf = (value: unknown): string[] | undefined => {
+  if (isLine(value)) return [value.trim()];
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const entries: unknown[] = value;
+  return entries.every(isLine) ? entries.map((entry) => entry.trim()) : undefined;
+};
+
+/**
+ * Lines by language as a team writes them: { ja: ..., en: ... }, each one line or a list; or one line or a list alone,
+ * which reads the same in every language. undefined when it cannot be read, a language chaff has no guide in included:
+ * lines in it would never be shown.
+ */
+export const guideLinesOf = (value: unknown): GuideLines | undefined => {
+  const everywhere = linesOf(value);
+  if (everywhere !== undefined) return Object.fromEntries(GUIDE_LANGUAGES.map((language) => [language, everywhere]));
+  if (!isRecord(value) || Object.keys(value).length === 0 || Object.keys(value).some((key) => !GUIDE_LANGUAGES.includes(key))) return undefined;
+  const read = Object.entries(value).map(([language, lines]) => [language, linesOf(lines)] as const);
+  return read.every((entry): entry is readonly [string, string[]] => entry[1] !== undefined) ? Object.fromEntries(read) : undefined;
+};
+
+/** A bundled guide: a list of lines in ja and in en. Throws, since the file ships with chaff and a wrong entry is chaff's bug. */
+export const bundledGuideOf = (value: unknown, where: string): GuideLines | undefined => {
+  if (value === undefined) return undefined;
+  const lines = isRecord(value) ? guideLinesOf(value) : undefined;
+  if (lines?.["ja"] === undefined || lines["en"] === undefined) throw new Error(`${where}: guide needs a list of lines in ja and in en`);
+  return lines;
+};

package/src/genre-guide/of-config.ts

@@ -0,0 +1,26 @@
+import { CONFIG_FILE, type Config } from "../config/load.ts";
+import { loadGenres } from "../genre-load.ts";
+import { knownGenres } from "../known-genres.ts";
+import type { UiLanguage } from "../ui.ts";
+import { guideLayerOf, type GuideLayer } from "./layer.ts";
+import { guideProblemText } from "./problem-text.ts";
+import { resolveGuide, type ResolvedGuide } from "./resolve.ts";
+
+type GuideSettings = Pick<Config, "guide" | "applied" | "extensions">;
+
+const configLayer = (config: Pick<Config, "guide">): ReturnType<typeof guideLayerOf> => guideLayerOf(config.guide, CONFIG_FILE, knownGenres());
+
+/** Every place that changes the bundled guides, weakest first: the rule packs, then the chosen style, then chaff.yaml. */
+export const guideLayersOf = (config: GuideSettings): GuideLayer[] => [
+  ...(config.extensions?.guides ?? []),
+  ...(config.applied?.guide === undefined ? [] : [config.applied.guide]),
+  configLayer(config).layer,
+];
+
+/** The guide a document of this genre is checked against, in its language; undefined when it is turned off or the genre has none. */
+export const genreGuideFor = (config: GuideSettings, genre: string, language: UiLanguage): ResolvedGuide | undefined =>
+  resolveGuide(loadGenres(), genre, language, guideLayersOf(config));
+
+/** What chaff.yaml's guide: says that cannot be read. The rest of it still applies, so these are warnings, not a stop. */
+export const configGuideProblems = (config: Pick<Config, "guide" | "path">, ui: UiLanguage): string[] =>
+  configLayer(config).problems.map((problem) => `${config.path ?? CONFIG_FILE}: ${guideProblemText(problem, ui)}`);

package/src/genre-guide/problem-text.ts

@@ -0,0 +1,34 @@
+import type { Texts, UiLanguage } from "../ui.ts";
+import type { GuideProblem } from "./layer.ts";
+
+type ProblemText = Readonly<{ [K in GuideProblem["kind"]]: (problem: Extract<GuideProblem, { kind: K }>) => string }>;
+
+const TEXT: Texts<ProblemText> = {
+  ja: {
+    "not-a-map": (problem) => `guide の ${problem.written} は読めません。ジャンルか群の名前の下に replace・add・off を書くか、guide: off と書いてください`,
+    "unknown-genre": (problem) => `guide の ${problem.genre} というジャンルや群はありません（npx chaffjs genres で一覧が出ます）`,
+    "bad-entry": (problem) => `guide の ${problem.genre}: ${problem.written} は読めません。replace か add に行を書くか、off と書いてください`,
+    "bad-lines": (problem) => `guide の ${problem.genre}: ${problem.field} は 1 行か行の並びで、言語ごとなら ja: と en: の下に書いてください`,
+  },
+  en: {
+    "not-a-map": (problem) => `guide ${problem.written} cannot be read; write replace, add or off under a genre or group, or guide: off`,
+    "unknown-genre": (problem) => `guide names ${problem.genre}, which is no genre or group (npx chaffjs genres lists them)`,
+    "bad-entry": (problem) => `guide ${problem.genre}: ${problem.written} cannot be read; write lines under replace or add, or off`,
+    "bad-lines": (problem) => `guide ${problem.genre}: write ${problem.field} as a line or a list of lines, under ja: and en: for each language`,
+  },
+};
+
+/** One guide problem as a sentence, without the place it was written (the caller names chaff.yaml, a style or a plugin). */
+export const guideProblemText = (problem: GuideProblem, ui: UiLanguage): string => {
+  const text = TEXT[ui];
+  switch (problem.kind) {
+    case "not-a-map":
+      return text["not-a-map"](problem);
+    case "unknown-genre":
+      return text["unknown-genre"](problem);
+    case "bad-entry":
+      return text["bad-entry"](problem);
+    case "bad-lines":
+      return text["bad-lines"](problem);
+  }
+};