chaffjs 0.22.0 → 0.24.0

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

package/src/genre-guide/render.ts

@@ -0,0 +1,50 @@
+import type { Texts, UiLanguage } from "../ui.ts";
+import type { ReportedGuide } from "./report.ts";
+import { BUNDLED_GUIDES } from "./resolve.ts";
+
+const TEXT: Texts<{
+  readonly heading: (name: string, genre: string) => string;
+  readonly lead: string;
+  readonly rules: (ids: string) => string;
+  readonly from: (places: string) => string;
+  readonly change: string;
+}> = {
+  ja: {
+    heading: (name, genre) => `指針: ${name}（${genre}）`,
+    lead: "下の指摘より先に、原稿がこれを満たしているかを確かめてください。",
+    rules: (ids) => `このジャンルで特に効く rule: ${ids}`,
+    from: (places) => `書いたところ: ${places}`,
+    change: "chaff.yaml の guide: で書き換えられます。出さないときは --no-guide。",
+  },
+  en: {
+    heading: (name, genre) => `Guide: ${name} (${genre})`,
+    lead: "Before the findings below, check the draft against these.",
+    rules: (ids) => `Rules that matter most for this genre: ${ids}`,
+    from: (places) => `Written in: ${places}`,
+    change: "Change it with guide: in chaff.yaml; leave it out with --no-guide.",
+  },
+};
+
+const RULE = 60;
+
+/** Who wrote the guide, said only when a team changed it: the bundled text alone needs no source line. */
+const fromLines = (guide: ReportedGuide, ui: UiLanguage): string[] =>
+  guide.from.length === 1 && guide.from[0] === BUNDLED_GUIDES ? [] : [`  ${TEXT[ui].from(guide.from.join(" → "))}`];
+
+/** The guide as the text report opens with it, in the document's language: read first, as the instruction to write against. */
+export const renderGuideBlock = (guide: ReportedGuide, ui: UiLanguage): string[] => {
+  const text = TEXT[ui];
+  return [
+    "",
+    text.heading(guide.name, guide.genre),
+    "",
+    `  ${text.lead}`,
+    "",
+    ...guide.lines.map((line) => `  - ${line}`),
+    ...(guide.rules.length === 0 ? [] : ["", `  ${text.rules(guide.rules.join(", "))}`]),
+    ...fromLines(guide, ui),
+    `  ${text.change}`,
+    "",
+    "═".repeat(RULE),
+  ];
+};

package/src/genre-guide/report.ts

@@ -0,0 +1,63 @@
+import { showsGuide } from "../cli-args.ts";
+import type { GenreSource } from "../cli-text.ts";
+import type { Config } from "../config/load.ts";
+import { loadGenres } from "../genre-load.ts";
+import type { RuleDefinition } from "../plugin.ts";
+import { localized } from "../render/text.ts";
+import { uiLanguageOf, type UiLanguage } from "../ui.ts";
+import { keyRulesOf } from "./key-rules.ts";
+import { genreGuideFor } from "./of-config.ts";
+
+/** A genre's guide as chaff reports it: the genre and its name, the lines, the rules that matter most, and who wrote it. */
+export type ReportedGuide = {
+  readonly genre: string;
+  readonly name: string;
+  readonly lines: readonly string[];
+  readonly rules: readonly string[];
+  readonly from: readonly string[];
+};
+
+/**
+ * Where a genre counts as set, so its guide is shown. A defaulted genre is not one, nor one guessed from the path or the
+ * text: a guide for the wrong kind of document misleads more than none.
+ */
+const SET_BY: ReadonlySet<GenreSource> = new Set<GenreSource>(["--genre", "by_path", "config", "front-matter"]);
+
+export const genreWasSet = (from: GenreSource): boolean => SET_BY.has(from);
+
+type GuideSettings = Pick<Config, "guide" | "applied" | "extensions" | "rules">;
+
+/** The guide for a genre in a document's language, with the rules that matter most; undefined when it is off or there is none. */
+export const reportedGuide = (config: GuideSettings, genre: string, language: string, rules: readonly RuleDefinition[]): ReportedGuide | undefined => {
+  const ui = uiLanguageOf(language);
+  const guide = genreGuideFor(config, genre, ui);
+  if (guide === undefined) return undefined;
+  const data = loadGenres();
+  const name = data.genres.find((entry) => entry.id === genre)?.name;
+  return {
+    genre,
+    name: name === undefined ? genre : localized(name, ui),
+    lines: guide.lines,
+    rules: keyRulesOf(rules, data, genre, language, config.rules),
+    from: guide.from,
+  };
+};
+
+/** One checked document, as far as its guide goes. */
+type GuidedDocument = { readonly genre: string; readonly genreFrom: GenreSource; readonly language: string; readonly rules: readonly RuleDefinition[] };
+
+/** A guide with the language it is written in, for output that holds several documents. */
+export type RunGuide = { readonly language: UiLanguage; readonly guide: ReportedGuide };
+
+/** A run's guides: one per genre and language among the documents whose genre was set, first seen first. None with --no-guide. */
+export const guidesOfRun = (documents: readonly GuidedDocument[], config: GuideSettings, args: readonly string[]): RunGuide[] => {
+  if (!showsGuide(args)) return [];
+  const keyed = documents
+    .filter((document) => genreWasSet(document.genreFrom))
+    .map((document) => ({ key: `${document.genre}\n${uiLanguageOf(document.language)}`, document }));
+  const firsts = keyed.filter((entry, index) => keyed.findIndex((other) => other.key === entry.key) === index);
+  return firsts.flatMap(({ document }) => {
+    const guide = reportedGuide(config, document.genre, document.language, document.rules);
+    return guide === undefined ? [] : [{ language: uiLanguageOf(document.language), guide }];
+  });
+};

package/src/genre-guide/resolve.ts

@@ -0,0 +1,36 @@
+import type { GenreData } from "../genre-parse.ts";
+import type { GuideEdit, GuideLayer } from "./layer.ts";
+
+/** Where the bundled guides come from, as a resolved guide names it. */
+export const BUNDLED_GUIDES = "genres.yaml";
+
+/** A genre's guide in one language, and every place that wrote it, weakest first. */
+export type ResolvedGuide = { readonly genre: string; readonly lines: readonly string[]; readonly from: readonly string[] };
+
+type Current = { readonly lines: readonly string[]; readonly from: readonly string[] };
+
+const applied = (current: Current, edit: GuideEdit | undefined, language: string, from: string): Current => {
+  if (edit === undefined) return current;
+  if (edit.kind === "off") return { lines: [], from: [...current.from, from] };
+  const replaced = edit.replace?.[language];
+  const added = edit.add?.[language] ?? [];
+  if (replaced === undefined && added.length === 0) return current;
+  return { lines: [...(replaced ?? current.lines), ...added], from: [...current.from, from] };
+};
+
+/**
+ * A genre's guide in a language: genres.yaml's for the genre, else its group's, then each layer in order (weakest first):
+ * its guide: off, then its group's entry, then its genre's. undefined for a genre chaff does not know, or when no lines are left.
+ */
+export const resolveGuide = (data: GenreData, genre: string, language: string, layers: readonly GuideLayer[]): ResolvedGuide | undefined => {
+  const own = data.genres.find((entry) => entry.id === genre);
+  if (own === undefined) return undefined;
+  const group = data.groups.find((entry) => genre.startsWith(`${entry.id}/`));
+  const bundled = own.guide ?? group?.guide;
+  const start: Current = { lines: bundled?.[language] ?? [], from: bundled === undefined ? [] : [BUNDLED_GUIDES] };
+  const end = layers.reduce((current, layer) => {
+    const cleared = applied(current, layer.allOff ? { kind: "off" } : undefined, language, layer.from);
+    return applied(applied(cleared, group === undefined ? undefined : layer.edits[group.id], language, layer.from), layer.edits[genre], language, layer.from);
+  }, start);
+  return end.lines.length === 0 ? undefined : { genre, lines: end.lines, from: end.from };
+};

package/src/genre-parse.ts

@@ -1,12 +1,13 @@
 import { isLevel } from "./levels.ts";
 import type { Level, Localized } from "./plugin.ts";
 import type { RuleOff } from "./rule-offs.ts";
+import { bundledGuideOf, type GuideLines } from "./genre-guide/lines.ts";
 
 /** A preset's rules: the level each named rule runs at, under whatever chaff.yaml's rules say. */
 export type PresetLevels = Readonly<Record<string, Level>>;
 
-/** A group of genres (legal, literature): its name, and the levels every genre in it shares. */
-export type GenreGroup = { readonly id: string; readonly name: Localized; readonly rules: PresetLevels };
+/** A group of genres (legal, literature): its name, the levels every genre in it shares, and the guide a genre without its own reads. */
+export type GenreGroup = { readonly id: string; readonly name: Localized; readonly rules: PresetLevels; readonly guide?: GuideLines | undefined };
 
 /** One genre of genres.yaml: what it is for, the levels it sets on top of its group's, and the profile it reads with. */
 export type GenreDefinition = {
@@ -16,6 +17,8 @@ export type GenreDefinition = {
   readonly rules: PresetLevels;
   readonly profile: string | undefined;
   readonly suggest: GenreSuggest;
+  /** What a good document of this genre does, as lines to check a draft against (genre-guide/). */
+  readonly guide?: GuideLines | undefined;
 };
 
 /** A line shape that marks the genre, and how many lines must have it. */
@@ -59,10 +62,16 @@ const idOf = (value: unknown, index: number): string => {
   return id;
 };
 
+/** guide: as a field only when written, so an entry without one reads as it did before guides. */
+const guideField = (raw: Record<string, unknown>, id: string): { guide?: GuideLines } => {
+  const guide = bundledGuideOf(raw["guide"], id);
+  return guide === undefined ? {} : { guide };
+};
+
 const groupOf = (value: unknown, index: number): GenreGroup => {
   const id = idOf(value, index);
   const raw = isRecord(value) ? value : {};
-  return { id, name: localizedOf(raw["name"], "name", id), rules: levelsOf(raw["rules"], id) };
+  return { id, name: localizedOf(raw["name"], "name", id), rules: levelsOf(raw["rules"], id), ...guideField(raw, id) };
 };
 
 const patternOf = (value: unknown, flags: string, where: string): RegExp => {
@@ -121,6 +130,7 @@ const genreOf = (value: unknown, index: number): GenreDefinition => {
     rules: levelsOf(raw["rules"], id),
     profile,
     suggest: suggestOf(raw["suggest"], id),
+    ...guideField(raw, id),
   };
 };
 

package/src/init.ts

@@ -41,6 +41,13 @@ genre: ${genre}
 # names:
 #   - 個人情報保護委員会
 
+# このジャンルの指針（よい文書が満たすこと）。検査の結果より先に出て、AI が書き直すときの指示になる。
+# 既定は chaff に入っている文。replace で置き換え、add で足し、off で出さない。
+# guide:
+#   ${genre}:
+#     add:
+#       - 金額は税込みか税抜きかを書いているか
+
 # 既定から変えたものだけを書く。
 rules:
 `,
@@ -80,6 +87,13 @@ genre: ${genre}
 # names:
 #   - Bank of England
 
+# This genre's guide: what a good document of this kind does. It comes before the findings, and an AI
+# rewriting the text works to it. chaff ships one; replace it, add lines, or turn it off.
+# guide:
+#   ${genre}:
+#     add:
+#       - Does each amount say whether tax is included?
+
 # Only what differs from the defaults.
 rules:
 `,

package/src/quoted-span.ts

@@ -41,5 +41,30 @@ export const quotedSpans = (text: string, marks: Marks = KAGI_MARKS): Span[] =>
 export const quotedIn = (sentence: Sentence, marks: Marks = KAGI_MARKS): Span[] =>
   quotedSpans(sentence.text, marks).map((span) => ({ start: sentence.span.start + span.start - 1, end: sentence.span.start + span.end + 1 }));
 
+const MARKS = /[\s\p{P}]+/u;
+const LETTERS = /^\p{L}+$/u;
+
+/** 記号と空白のあいだに残る語が、字だけの語で、多くとも allowed 個か。 */
+const holdsAtMost = (text: string, allowed: number): boolean => {
+  const words = text.split(MARKS).filter((word) => word !== "");
+  return words.length <= allowed && words.every((word) => LETTERS.test(word));
+};
+
+/**
+ * span だけを引いた引用符（"delves"、"?utm_source=chatgpt.com"、"October 26, 2026 – October 19, 2026"）の中か。
+ * 引用符が語だけを囲めば、その語は使ったのではなく例として挙げたもの。周りの記号と空白は語の一部に数えない。
+ * wordsBesides は、span のほかに引用符の中にあってよい語の数（日付なら曜日の一語）。
+ * 話した言葉の引用（"We ship on Monday, October 26," she said.）は語のほかの字を持つので当たらない。引用は一行の中だけを見る。
+ */
+export const isQuotedAlone = (text: string, span: Span, wordsBesides = 0): boolean => {
+  const lineStart = text.lastIndexOf("\n", span.start - 1) + 1;
+  const newline = text.indexOf("\n", span.end);
+  const line = text.slice(lineStart, newline === -1 ? text.length : newline);
+  const [start, end] = [span.start - lineStart, span.end - lineStart];
+  return quotedSpans(line, QUOTATION_MARKS).some(
+    (quoted) => quoted.start <= start && end <= quoted.end && holdsAtMost(`${line.slice(quoted.start, start)} ${line.slice(end, quoted.end)}`, wordsBesides),
+  );
+};
+
 /** inner が、spans のどれかにまるごと入っているか。 */
 export const isWithinAny = (spans: readonly Span[], inner: Span): boolean => spans.some((span) => inner.start >= span.start && inner.end <= span.end);