chaffjs 0.21.0 → 0.23.0

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/list-marks.ts

@@ -0,0 +1,106 @@
+// The bullets a document writes its lists with (`-`, `*`, `+`, and `・` typed at a line's start), where each list sits, and
+// the `・` lines Markdown folds into the item above. Pure; reads the source's Markdown tree.
+import { spanOf, type MarkdownNode } from "./markdown-node.ts";
+import type { Span } from "./plugin.ts";
+
+/** One bulleted list as the reader meets it: where its first item starts, how deep it sits among lists, and its bullet. */
+export type ListMark = {
+  readonly start: number;
+  readonly depth: number;
+  readonly mark: string;
+  /** The list written right before it in the same parent, when there is one: Markdown splits a list where the bullet changes. */
+  readonly previous: string | undefined;
+};
+
+/** Bullets Markdown reads as a list. */
+const MARKDOWN_BULLETS = new Set(["-", "*", "+"]);
+
+/** A bullet a Japanese writer types at a line's start. Markdown does not read it as a list, so the lines run together. */
+const TYPED_BULLET = "・";
+
+/** Blocks whose lists are someone else's or are not prose: quotations, code and HTML. */
+const SKIPPED = new Set(["blockquote", "code", "html"]);
+
+const bulletOf = (source: string, list: MarkdownNode): { readonly start: number; readonly mark: string } | undefined => {
+  const first = list.children?.[0];
+  const span = first === undefined ? undefined : spanOf(first);
+  const mark = span === undefined ? undefined : source.charAt(span.start);
+  return span === undefined || mark === undefined || !MARKDOWN_BULLETS.has(mark) ? undefined : { start: span.start, mark };
+};
+
+/** Where each line of a span starts, with the line's text. */
+const linesIn = (source: string, span: Span): { readonly start: number; readonly text: string }[] => {
+  const lines = source.slice(span.start, span.end).split("\n");
+  const read: { start: number; text: string }[] = [];
+  lines.forEach((text) => {
+    const previous = read.at(-1);
+    read.push({ start: previous === undefined ? span.start : previous.start + previous.text.length + 1, text });
+  });
+  return read;
+};
+
+/** The start of each line after the first that begins with a typed bullet. */
+const typedLineStarts = (source: string, paragraph: Span): number[] =>
+  linesIn(source, paragraph).flatMap((line, at) => {
+    const indent = line.text.length - line.text.trimStart().length;
+    return at > 0 && line.text.trimStart().startsWith(TYPED_BULLET) ? [line.start + indent] : [];
+  });
+
+/** Lines of a paragraph that start with a typed bullet; two or more in a row are a list the writer typed. */
+const typedListStart = (source: string, paragraph: Span): number | undefined => {
+  const lines = linesIn(source, paragraph).filter((line) => line.text.trim() !== "");
+  const typed = lines.filter((line) => line.text.trimStart().startsWith(TYPED_BULLET));
+  const first = typed[0];
+  return typed.length >= 2 && first !== undefined ? first.start + first.text.length - first.text.trimStart().length : undefined;
+};
+
+type Frame = { readonly node: MarkdownNode; readonly depth: number; readonly inItem: boolean };
+
+export type ListReading = {
+  readonly lists: readonly ListMark[];
+  /** `・` lines inside a Markdown list item's paragraph: Markdown joins them to the item above. */
+  readonly foldedTyped: readonly number[];
+};
+
+const listsOf = (source: string, node: MarkdownNode, depth: number): ListMark[] => {
+  const children = node.children ?? [];
+  return children.flatMap((child, at) => {
+    if (child.type !== "list") return [];
+    const bullet = bulletOf(source, child);
+    const before = children[at - 1];
+    const previous = before?.type === "list" ? bulletOf(source, before)?.mark : undefined;
+    return bullet === undefined ? [] : [{ ...bullet, depth, previous }];
+  });
+};
+
+const typedOf = (source: string, node: MarkdownNode, depth: number, inItem: boolean): { lists: ListMark[]; folded: number[] } => {
+  const span = spanOf(node);
+  if (node.type !== "paragraph" || span === undefined) return { lists: [], folded: [] };
+  if (inItem) return { lists: [], folded: typedLineStarts(source, span) };
+  const start = typedListStart(source, span);
+  return { lists: start === undefined ? [] : [{ start, depth, mark: TYPED_BULLET, previous: undefined }], folded: [] };
+};
+
+/**
+ * Every bulleted list outside quotations and code, with its depth among lists (a list in a list item is one deeper), in source
+ * order. A paragraph with two or more lines that start with `・` counts as a list at the paragraph's depth; the same lines in a
+ * list item's paragraph are folded into that item.
+ */
+export const readLists = (source: string, root: MarkdownNode): ListReading => {
+  const lists: ListMark[] = [];
+  const folded: number[] = [];
+  const pending: Frame[] = [{ node: root, depth: 0, inItem: false }];
+  for (let frame = pending.pop(); frame !== undefined; frame = pending.pop()) {
+    const { node, depth, inItem } = frame;
+    if (SKIPPED.has(node.type)) continue;
+    lists.push(...listsOf(source, node, depth));
+    const typed = typedOf(source, node, depth, inItem);
+    lists.push(...typed.lists);
+    folded.push(...typed.folded);
+    const childDepth = node.type === "list" ? depth + 1 : depth;
+    const childInItem = node.type === "listItem" || (inItem && node.type !== "list");
+    (node.children ?? []).forEach((child) => pending.push({ node: child, depth: childDepth, inItem: childInItem }));
+  }
+  const byStart = (left: number, right: number): number => left - right;
+  return { lists: lists.toSorted((left, right) => byStart(left.start, right.start)), foldedTyped: folded.toSorted(byStart) };
+};

package/src/render/rules-json.ts

@@ -14,6 +14,7 @@ import { loadStyles } from "../style-load.ts";
 import type { OptionLayer } from "../rule-options.ts";
 import { CUSTOM_TYPES } from "../custom/parse.ts";
 import { DEFAULT_DEPTH, REWRITE_DEPTHS, depthMeaning } from "../rewrite-depth.ts";
+import type { ReportedGuide } from "../genre-guide/report.ts";
 
 const TEXT: Texts<{
   readonly offBySetting: string;
@@ -185,6 +186,7 @@ export const rulesJson = (
   language: string,
   genre: string,
   optionLayers: readonly OptionLayer[] = [],
+  guide?: ReportedGuide,
 ): string => {
   const text = TEXT[uiLanguageOf(language)];
   const preset = presetLevels(genre);
@@ -196,6 +198,8 @@ export const rulesJson = (
       schema_version: 2,
       config_file: "chaff.yaml",
       detected: { genre, language },
+      // What a good document of the genre does: null unless the genre was set (--genre, chaff.yaml) and its guide is on.
+      guide: guide ?? null,
       ...(config.applied === undefined ? {} : { style: styleOf(config) }),
       values_you_can_use: ["strict", "normal", "relaxed", "off"],
       values_note: text.valuesNote,

package/src/render/sarif.ts

@@ -1,5 +1,6 @@
 import { messageOf, readableText } from "./text.ts";
 import type { Finding, RuleDefinition, Severity } from "../plugin.ts";
+import type { RunGuide } from "../genre-guide/report.ts";
 
 /**
  * 指摘を SARIF 2.1.0 で出す。GitHub の code scanning に上げるため。
@@ -114,7 +115,8 @@ const notRunNotifications = (notRun: readonly NotRunOnFile[]): SarifNotification
   }));
 };
 
-export const renderSarif = (located: readonly Located[], version: string, notRun: readonly NotRunOnFile[] = []): string => {
+/** guides: the guides of the genres this run set, each with its language; none adds no run properties. */
+export const renderSarif = (located: readonly Located[], version: string, notRun: readonly NotRunOnFile[] = [], guides: readonly RunGuide[] = []): string => {
   return `${JSON.stringify(
     {
       $schema: SCHEMA,
@@ -124,6 +126,7 @@ export const renderSarif = (located: readonly Located[], version: string, notRun
           tool: { driver: { name: "chaff", version, informationUri: INFORMATION_URI, rules: usedRules(located) } },
           invocations: [{ executionSuccessful: true, toolConfigurationNotifications: notRunNotifications(notRun) }],
           results: located.map(resultOf),
+          ...(guides.length === 0 ? {} : { properties: { guides: guides.map((entry) => ({ ...entry.guide, language: entry.language })) } }),
         },
       ],
     },

package/src/rule-fields.ts

@@ -11,10 +11,14 @@ export type FieldProblem =
   | { readonly kind: "bad-group"; readonly written: string }
   | { readonly kind: "bad-use-for"; readonly written: string }
   | { readonly kind: "bad-summary"; readonly written: string }
+  | { readonly kind: "bad-text"; readonly written: string }
   | { readonly kind: "bad-example"; readonly written: string };
 
 export type FieldKind = FieldProblem["kind"];
 
+/** Every kind, for a caller that reports these among problems of its own. */
+export const FIELD_KINDS: ReadonlySet<string> = new Set<FieldKind>(["bad-depth", "bad-group", "bad-use-for", "bad-summary", "bad-example", "bad-text"]);
+
 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() !== "";
@@ -41,6 +45,25 @@ const useForProblems = (useFor: unknown, genres: readonly string[]): FieldProble
 const summaryProblems = (summary: unknown): FieldProblem[] =>
   summary === undefined || isTextByLanguage(summary) ? [] : [{ kind: "bad-summary", written: printed(summary) }];
 
+/** A language as a key of a text by language: ja, en, pt-br. */
+const LANGUAGE_KEY = /^[a-z]{2,3}(?:-[a-z0-9]+)*$/iu;
+
+/** The texts a reader sees. Each may be one string or one per language. */
+const TEXT_FIELDS = ["name", "why", "how_to_fix", "message", "summary"] as const;
+
+/**
+ * A text by language whose key is not a language, or whose value is not a text. In YAML, { en: Write a date, or a
+ * number of days } is two entries, the second keyed " or a number of days": without this, the text is cut silently.
+ */
+const textProblems = (raw: Readonly<Record<string, unknown>>): FieldProblem[] =>
+  TEXT_FIELDS.flatMap((field) => {
+    const value = raw[field];
+    if (!isRecord(value)) return [];
+    return Object.entries(value)
+      .filter(([key, text]) => !LANGUAGE_KEY.test(key) || typeof text !== "string")
+      .map(([key]) => ({ kind: "bad-text" as const, written: `${field}: ${JSON.stringify(key)}` }));
+  });
+
 /** One example: before and after, each a text in every language or by language. */
 const isExamplePair = (value: unknown): boolean => isRecord(value) && isTextByLanguage(value["before"]) && isTextByLanguage(value["after"]);
 
@@ -68,6 +91,7 @@ export const fieldProblems = (raw: Readonly<Record<string, unknown>>, genres: re
   ...useForProblems(raw["use_for"], genres),
   ...exampleProblems(raw["example"]),
   ...depthProblems(raw["rewrite"]),
+  ...textProblems(raw),
 ];
 
 const TEXT: Texts<Readonly<Record<FieldKind, (written: string) => string>>> = {
@@ -77,6 +101,8 @@ const TEXT: Texts<Readonly<Record<FieldKind, (written: string) => string>>> = {
     "bad-use-for": (written) =>
       `use_for: ${written} はジャンルではありません。ジャンルかその頭（business、business/report）を並べます。一覧は npx chaffjs genres。`,
     "bad-summary": (written) => `summary: ${written} は読めません。一つの文字列か、言語ごとの文字列（{ ja: …, en: … }）で書きます。`,
+    "bad-text": (written) =>
+      `${written} は言語ではありません。{ } の中のカンマは項目の区切りになるので、カンマのある文は引用符で囲みます（en: "Write a date, or a number of days."）。`,
     "bad-example": (written) =>
       `example: ${written} の before と after が揃っていません。{ before, after } か、言語ごとに { ja: { before, after }, en: { before, after } } と書きます。`,
   },
@@ -86,6 +112,8 @@ const TEXT: Texts<Readonly<Record<FieldKind, (written: string) => string>>> = {
     "bad-use-for": (written) =>
       `use_for: ${written} is not a genre. List genres or their first part (business, business/report); npx chaffjs genres lists them.`,
     "bad-summary": (written) => `summary: cannot read ${written}. Write one string, or one per language ({ ja: …, en: … }).`,
+    "bad-text": (written) =>
+      `${written} is not a language. Inside { }, a comma separates entries, so quote a text that has one (en: "Write a date, or a number of days.").`,
     "bad-example": (written) =>
       `example: ${written} lacks a before or an after. Write { before, after }, or one per language: { ja: { before, after }, en: { before, after } }.`,
   },

package/src/style-parse.ts

@@ -1,5 +1,8 @@
 import { isLevel } from "./levels.ts";
 import type { Level, Localized } from "./plugin.ts";
+import { guideLayerOf, type GuideLayer } from "./genre-guide/layer.ts";
+import { guideProblemText } from "./genre-guide/problem-text.ts";
+import { knownGenres } from "./known-genres.ts";
 
 // A house style (styles/*.yaml): a well-known guideline a team picks with style: in chaff.yaml. It sets rule levels and
 // options, and says where they come from. Pure: the YAML comes in already parsed.
@@ -21,6 +24,8 @@ export type StyleDefinition = {
   readonly options: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
   /** The numbers the guideline sets, by language. The rule needs a level under rules too, or the limit decides nothing. */
   readonly limits: StyleLimits;
+  /** Its changes to the genre guides (genre-guide/layer.ts), between a rule pack's and chaff.yaml's. */
+  readonly guide?: GuideLayer | undefined;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -85,6 +90,15 @@ const limitsOf = (value: unknown, rules: Readonly<Record<string, Level>>, where:
   );
 };
 
+/** The style's guide: as a layer named after the style. undefined when it writes none. */
+const guideOf = (value: unknown, id: string, where: string): GuideLayer | undefined => {
+  if (value === undefined) return undefined;
+  const read = guideLayerOf(value, `style: ${id}`, knownGenres());
+  const [problem] = read.problems;
+  if (problem !== undefined) throw new Error(`${where}: ${guideProblemText(problem, "en")}`);
+  return read.layer;
+};
+
 /** One style file. Throws on anything it cannot read: the file ships with chaff, so a wrong entry is chaff's bug. */
 export const parseStyle = (raw: unknown, file: string): StyleDefinition => {
   const id = isRecord(raw) ? raw["id"] : undefined;
@@ -99,7 +113,10 @@ export const styleOf = (raw: unknown, where: string): StyleDefinition => {
   if (typeof id !== "string" || id === "") throw new Error(`${where}: a style needs an id`);
   const rules = levelsOf(raw["rules"], where);
   const options = optionsOf(raw["options"], where);
-  if (Object.keys(rules).length === 0 && Object.keys(options).length === 0) throw new Error(`${where}: a style must set rules or options`);
+  const guide = guideOf(raw["guide"], id, where);
+  if (Object.keys(rules).length === 0 && Object.keys(options).length === 0 && guide === undefined) {
+    throw new Error(`${where}: a style must set rules, options or guide`);
+  }
   return {
     id,
     name: localizedOf(raw["name"], "name", where),
@@ -108,5 +125,6 @@ export const styleOf = (raw: unknown, where: string): StyleDefinition => {
     rules,
     options,
     limits: limitsOf(raw["limits"], rules, where),
+    ...(guide === undefined ? {} : { guide }),
   };
 };