chaffjs 0.22.0 → 0.23.0

package/rules/figurative-density.yaml

@@ -0,0 +1,84 @@
+id: figurative-density
+layer: L2
+status: stable
+how_to_find: phrase-density
+word_list: figurative-phrase
+uses: [pos]
+severity: info
+
+name:
+  ja: 飾りのたとえが多い
+  en: Too many decorative figures
+
+why:
+  ja: 「まるで魔法のように動く」「呪文のようなコマンド」「おまじないとして書く」のようなたとえは、一つなら文に色を付けますが、重なると何がどう動くのかが書かれないまま文書が進みます。読み手は仕組みを知りたいのに、たとえしか受け取れません。一つ一つは誤りではないので、文書の長さあたりの数で見ます。たとえの一覧は語彙表 figurative-phrase にあり、語ごとに代わりに書くことの例が付いています。
+  en: 'A figure such as "works like magic", "a one-line incantation" or "our secret sauce" adds colour once. Piled up, the document goes on without saying what actually happens, and a reader who wants the mechanism gets only the figure. None of them is wrong alone, so the rule counts them per length of the document. The figures are in the lexicon figurative-phrase, each with what to write instead.'
+
+message:
+  ja: 「{matched}」など、飾りのたとえが 1000 字あたり {density} 個あります
+  en: '"{matched}" and other decorative figures: {density} per 1000 words'
+
+how_to_fix:
+  ja: たとえの代わりに、何がどう動くのか、何ができるのかを書いてください（まるで魔法のように設定が済む → 設定ファイルを読んで自動で済ませる）。
+  en: Replace the figure with what happens ("the config sets itself up like magic" becomes "the tool reads the config file and fills in the defaults").
+
+# 「まるで魔法のように」は一つのたとえに二語が当たるので、既定は 1000 字あたり 2 個まで。
+levels: { strict: 1, normal: 2, relaxed: 3 }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  literature: "Figures are the writer's material in literature."
+  speech: "A speaker's figures are part of the talk."
+
+group: ai-tells
+summary:
+  ja: 「まるで魔法のように」「呪文のような」「おまじない」のような、仕組みの代わりのたとえが多い所
+  en: Decorative figures such as "like magic", "incantation" and "secret sauce" piled up in place of the mechanism
+
+example:
+  ja:
+    pad: true
+    before: |
+      このツールを入れると、まるで魔法のように設定が終わります。最初の一行は呪文のようなものなので、おまじないとして書いておいてください。
+    after: |
+      このツールを入れると、設定ファイルを読んで既定の値を自動で埋めます。最初の一行は文字コードを指定する行なので、消さずに残してください。
+  en:
+    pad: true
+    before: |
+      The installer works like magic. Our secret sauce is a one-line incantation that magically fixes every path.
+    after: |
+      The installer reads your config file and fills in the defaults. The fix is one command that rewrites every path to an absolute one.
+
+not_flagged:
+  ja: 一つ一つは誤りではないので、短い文書は測りません。例を挙げる「〜のような」（A や B のような製品）は数えません。文学と講演のジャンルでは止めています。
+  en: None of these is wrong alone, so short documents are not measured. A plain comparison or example ("tools such as A and B") is not counted. The literature and speech genres turn it off.
+level_meaning:
+  ja: 1000 字あたり飾りのたとえ {limit} 個まで
+  en: up to {limit} decorative figures per 1000 words
+
+rewrite:
+  depth: register
+  ja:
+    direction: たとえを、何がどう動くのか、何ができるのかの説明に替えてください。語彙表の語ごとの書き換えの例に従い、文書に書かれていない仕組みは作りません。
+    pairs:
+      - before: このツールを入れると、まるで魔法のように設定が終わります。
+        after: このツールを入れると、設定ファイルを読んで既定の値を自動で埋めます。
+      - before: 最初の一行はおまじないとして書いておいてください。
+        after: 最初の一行は文字コードを指定する行なので、消さずに残してください。
+    keep:
+      - 書いてある事実と手順
+    avoid:
+      - 文書に書かれていない仕組みを作って書く
+      - たとえを別のたとえに替える
+  en:
+    direction: Replace each figure with what actually happens or what the thing does, following the lexicon's hint for the phrase. Do not invent a mechanism the document does not give.
+    pairs:
+      - before: The installer works like magic.
+        after: The installer reads your config file and fills in the defaults.
+      - before: Our secret sauce is a one-line incantation that fixes every path.
+        after: The fix is one command that rewrites every path to an absolute one.
+    keep:
+      - the facts and steps the document gives
+    avoid:
+      - inventing a mechanism the document does not describe
+      - swapping one figure for another

package/skills/chaff/SKILL.md

@@ -23,6 +23,10 @@ read. A contract checked as a blog post gets wrong findings, so choose the genre
    `npx chaffjs init --genre legal/contract` writes it into `chaff.yaml` (always pass `--genre`: without it,
    `init` asks at a terminal).
 4. The header's first line shows the genre used and where it came from. Check it before trusting the findings.
+5. With the genre set, the report opens with the genre's guide: what a good document of that kind does, and the
+   rules that matter most for it. Read it first, before any finding, and hold the draft (or your rewrite) to each
+   line; most of it is what no rule can check. The team may have changed it with `guide:` in `chaff.yaml`. A
+   guessed or default genre shows no guide.
 
 A rule the genre turns off is listed under "did not run" with the genre as the reason. That is the preset's
 choice, not a gap; turn it back on (`rules:` in `chaff.yaml`) only when the person asks.
@@ -112,6 +116,8 @@ generated. chaff never rewrites; the rewriting is yours.
 **Start with the plan.** Run `npx chaffjs fix-plan <file>` (with the genre's `--genre`; `--json` to
 read it as data). It prints, in the document's language:
 
+- the genre's guide first, when the genre is set: what a good document of the kind does, the lines your rewrite
+  is held to;
 - the constraints: keep facts, numbers, conditions and names; add no fact; ask the writer instead of inventing a
   specific; two passes at most;
 - the recommended mode and why, and the document-level signals with the outline's numbers;

package/src/api.ts

@@ -138,6 +138,15 @@ export const defineRule = (spec: RuleSpec): Rule => ({ ...spec, apiVersion: API_
 /** A word list in each language it has words for: { ja: [...], en: [...] }. A string is an entry with only a pattern. */
 export type LexiconSpec = Readonly<Record<string, readonly (string | LexiconEntry)[]>>;
 
+/** Lines of a genre guide: one line or a list, the same in every language, or by language ({ ja: [...], en: [...] }). */
+export type GuideText = string | readonly string[] | Readonly<Record<string, string | readonly string[]>>;
+
+/**
+ * Changes to the genre guides chaff prints before the findings, by genre or group (blog/tech, legal): replace sets the
+ * lines, add puts lines after them, off leaves the genre with none.
+ */
+export type GuideSpec = Readonly<Record<string, "off" | { readonly replace?: GuideText; readonly add?: GuideText }>>;
+
 /** A house style a plugin ships: rule levels and options, and the guideline it follows. */
 export type StyleSpec = {
   readonly id: string;
@@ -146,6 +155,8 @@ export type StyleSpec = {
   readonly source: { readonly title: Text; readonly url: string };
   readonly rules?: Readonly<Record<string, "strict" | "normal" | "relaxed" | "off">>;
   readonly options?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  /** Its changes to the genre guides, while the style is chosen. */
+  readonly guide?: GuideSpec;
 };
 
 /**
@@ -158,6 +169,8 @@ export type PluginSpec = {
   readonly rules?: readonly (Rule | RuleSpec | Readonly<Record<string, unknown>>)[];
   readonly lexicons?: Readonly<Record<string, LexiconSpec>>;
   readonly styles?: readonly StyleSpec[];
+  /** Its changes to the genre guides, whenever the plugin is loaded. */
+  readonly guide?: GuideSpec;
 };
 
 export type Plugin = PluginSpec & { readonly apiVersion: number };

package/src/cli-args.ts

@@ -14,6 +14,9 @@ export const withExperimental = <T extends { readonly experimental: boolean }>(c
   experimental: config.experimental || args.includes("--experimental"),
 });
 
+/** Whether this run shows the genre's guide: everywhere it would, unless --no-guide leaves it out. */
+export const showsGuide = (args: readonly string[]): boolean => !args.includes("--no-guide");
+
 /** The settings with each --include <glob> added to chaff.yaml's include: the command line widens a directory walk as chaff.yaml can. */
 export const withIncludes = <T extends { readonly include?: readonly string[] | undefined }>(config: T, args: readonly string[]): T => {
   const given = args.flatMap((arg, index) => (index > 0 && args[index - 1] === "--include" && !arg.startsWith("--") ? [arg] : []));

package/src/cli-text.ts

@@ -56,6 +56,7 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
                                  誤った指摘・見逃しの報告の下書きを作る（何も送らない。--with-config で chaff.yaml 全体も載せる）
 
   --compact         エンジニア向けの 1 行形式
+  --no-guide        ジャンルを決めたときに最初に出す、そのジャンルの指針を出さない
   --experimental    試験中の rule も動かす
   --genre <ジャンル>  この実行だけジャンルを決める（chaff.yaml より優先）
   --show-baseline   棚上げした分も含めて全部見る
@@ -101,6 +102,7 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
                                  draft a report of a wrong or missed finding (sends nothing; --with-config adds all of chaff.yaml)
 
   --compact         one line per finding, for engineers
+  --no-guide        leave out the genre's guide, which comes first when the genre is set
   --experimental    run the experimental rules too
   --genre <genre>   the genre for this run only (wins over chaff.yaml)
   --show-baseline   show the shelved findings too

package/src/cli.ts

@@ -15,7 +15,10 @@ import { GENRES } from "./genre.ts";
 import { resolveGenre } from "./resolve-genre.ts";
 import { runInitCommand } from "./commands/init-command.ts";
 import { runPluginTest } from "./commands/plugin-test.ts";
-import { targetsOf, withExperimental, withIncludes } from "./cli-args.ts";
+import { targetsOf, withIncludes } from "./cli-args.ts";
+import { guidesOfRun, type RunGuide } from "./genre-guide/report.ts";
+import { showRules } from "./commands/rules.ts";
+import { renderGuideBlock } from "./genre-guide/render.ts";
 import { rulesOf } from "./custom/load.ts";
 import { renderCompact } from "./render/compact.ts";
 import { renderExplain } from "./render/explain.ts";
@@ -23,8 +26,6 @@ import { renderFriendly } from "./render/friendly.ts";
 import { renderGenres } from "./render/genres.ts";
 import { loadGenres, presetLevels } from "./genre-load.ts";
 import { fileHeader } from "./file-header.ts";
-import { rulesJson } from "./render/rules-json.ts";
-import { rulesTable } from "./render/rules-table.ts";
 import { renderSarif } from "./render/sarif.ts";
 import { VERSION, VERSION_LINES } from "./version.ts";
 import type { TreeContext } from "./commands/tree.ts";
@@ -38,7 +39,7 @@ import { runConditions, runFeedback, settingsOf, type Checked } from "./commands
 import { homedir } from "node:os";
 import { settingWarnings } from "./config/warnings.ts";
 import { readConfigIn } from "./config/read.ts";
-import { optionLayersOf, settingSourcesOf } from "./config/option-problems.ts";
+import { settingSourcesOf } from "./config/option-problems.ts";
 import { renderSummary, type FileOutcome } from "./render/summary.ts";
 
 import type { Finding, Level, RuleDefinition } from "./plugin.ts";
@@ -117,7 +118,7 @@ const present = (check: SourceCheck, argv: readonly string[]): Inspected => {
     genre,
     outcome: { path, findings: split.fresh, notRun: raw.skipped.length },
     perFile: { path, suppressed: applied.suppressed, reasonless: applied.unusedReasonless, notRun },
-    checked: { findings: split.fresh, rules, language, genre, skipped: raw.skipped },
+    checked: { findings: split.fresh, rules, language, genre, genreFrom: from, skipped: raw.skipped },
     kept: applied.kept,
   };
 };
@@ -132,7 +133,7 @@ const inspectRun = async (paths: readonly string[], config: Config, argv: readon
  * 指摘を PR の変更行に出すための出口。--sarif <path> を書いたときだけ作る。
  * 端末の出力は変えない。CI で上げるためのファイルが増えるだけ。
  */
-const writeSarif = (results: readonly Inspected[], argv: readonly string[], config: Config): void => {
+const writeSarif = (results: readonly Inspected[], argv: readonly string[], config: Config, guides: readonly RunGuide[]): void => {
   const path = flag(argv, "--sarif");
   if (path === undefined) return;
   // 文言はファイルの言語で描く。by_path で 1 つの repo に 2 言語が混ざるため。
@@ -141,7 +142,7 @@ const writeSarif = (results: readonly Inspected[], argv: readonly string[], conf
   );
   const notRun = results.flatMap((result) => result.checked.skipped.map((entry) => ({ path: result.outcome.path, rule: entry.rule, why: entry.why })));
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, renderSarif(located, VERSION, notRun), "utf8");
+  writeFileSync(path, renderSarif(located, VERSION, notRun, guides), "utf8");
   console.log(hostText(config).sarifWritten(path, located.length));
 };
 
@@ -169,7 +170,13 @@ const lint = async (targets: readonly string[], argv: readonly string[], config:
   }
   warnRuleProblems(config, language);
   const results = await inspectRun(paths, config, argv);
-  writeSarif(results, argv, config);
+  const guides = guidesOfRun(
+    results.map((result) => result.checked),
+    config,
+    argv,
+  );
+  writeSarif(results, argv, config, guides);
+  if (!argv.includes("--compact")) guides.forEach((entry) => console.log(renderGuideBlock(entry.guide, entry.language).join("\n")));
   results.filter((result) => result.outcome.findings.length > 0 || paths.length === 1).forEach((result) => console.log(result.text));
   renderSummary(
     results.map((result) => result.outcome),
@@ -255,17 +262,6 @@ type Handler = (argv: readonly string[], config: Config) => number | Promise<num
 /** `--` で始まらない引数。対象のパス。 */
 const positional = (argv: readonly string[]): string[] => targetsOf(argv.slice(1));
 
-/** `rules --json` for an AI to read; `rules` alone, a table for a person. */
-const showRules = (argv: readonly string[], written: Config): number => {
-  const config = withExperimental(written, argv);
-  const language = config.language ?? hostLanguage(undefined, process.env);
-  warnRuleProblems(config, language);
-  const genre = flag(argv, "--genre") ?? config.genre ?? "blog/tech";
-  const rules = rulesOf(language, config);
-  console.log(argv.includes("--json") ? rulesJson(rules, config, language, genre, optionLayersOf(config)) : rulesTable(rules, config, language, genre));
-  return 0;
-};
-
 const showGenres = (config: Config): number => {
   console.log(renderGenres(loadGenres(), hostLanguage(config.language, process.env)));
   return 0;
@@ -284,7 +280,7 @@ const measureContext = (argv: readonly string[], config: Config): { config: Conf
 const HANDLERS: Readonly<Record<string, Handler>> = {
   init: (argv, config) => runInitCommand((name) => flag(argv, name), argv.includes("--plugin"), hostLanguage(config.language, process.env), process.cwd()),
   genres: (_argv, config) => showGenres(config),
-  rules: showRules,
+  rules: (argv, config) => showRules(argv, config, { flag, warn: warnRuleProblems }),
   explain: (argv, config) => explain(config, argv[1], flag(argv, "--genre")),
   eval: (argv, config) => runEval(positional(argv), argv, { ...measureContext(argv, config), flag }),
   ...Object.fromEntries(Object.entries(DOCUMENT_COMMANDS).map(([name, run]): [string, Handler] => [name, (argv, config) => run(argv, treeContext(config))])),

package/src/commands/feedback.ts

@@ -9,6 +9,7 @@ import { excerptsAround } from "../feedback/excerpt.ts";
 import { feedbackDraft, type FeedbackDraft, type FeedbackKind, type ReportedFinding } from "../feedback/draft.ts";
 import { notRunAmong } from "../not-run.ts";
 import type { Skipped } from "../run.ts";
+import type { GenreSource } from "../cli-text.ts";
 
 export const FEEDBACK_FILE = ".chaff-feedback.md";
 const NEW_ISSUE = "https://github.com/isamu/lab/issues/new";
@@ -20,6 +21,8 @@ export type Checked = {
   readonly rules: readonly RuleDefinition[];
   readonly language: string;
   readonly genre: string;
+  /** Where the genre came from: set (--genre, chaff.yaml, by_path, front matter), guessed or defaulted. */
+  readonly genreFrom: GenreSource;
   /** The rules this check did not run, and why. */
   readonly skipped: readonly Skipped[];
   /** How the check was run, as the reader of a report would repeat it (runConditions). */

package/src/commands/fix-plan.ts

@@ -8,6 +8,9 @@ import { chosenDepthOf } from "../fix-plan/chosen-depth.ts";
 import type { Checked } from "./feedback.ts";
 import { readDocument } from "./read-document.ts";
 import type { TreeContext } from "./tree.ts";
+import { genreWasSet, reportedGuide, type ReportedGuide } from "../genre-guide/report.ts";
+import { showsGuide } from "../cli-args.ts";
+import type { Config } from "../config/load.ts";
 
 /** Options whose value is the next argument. That value is not a file. */
 const VALUED: ReadonlySet<string> = new Set(["--language", "--genre", "--depth"]);
@@ -24,6 +27,10 @@ export type FixPlanContext = TreeContext & {
   readonly check: (path: string) => Promise<Omit<Checked, "conditions">>;
 };
 
+/** The genre's guide, the plan's first section; none when the genre was not set or the guide is off. */
+const guideOf = (checked: Omit<Checked, "conditions">, config: Config, argv: readonly string[]): ReportedGuide | undefined =>
+  genreWasSet(checked.genreFrom) && showsGuide(argv) ? reportedGuide(config, checked.genre, checked.language, checked.rules) : undefined;
+
 /**
  * An instruction document for whoever rewrites the file: the findings grouped by rule, each rule's rewrite direction,
  * the document-level signals, the structure targets from human articles, a recommended mode and the checks to run after. Deterministic; sends nothing anywhere.
@@ -61,6 +68,7 @@ export const runFixPlan = async (targets: readonly string[], argv: readonly stri
     structure: structureOf(prose.doc),
     phrases: prose.doc.lexicons["ai-tell"] ?? [],
     chosenDepth: depth.chosen,
+    guide: guideOf(checked, context.config, argv),
   });
   console.log(argv.includes("--json") ? renderFixPlanJson(plan) : renderFixPlanMarkdown(plan));
   return 0;

package/src/commands/rules.ts

@@ -0,0 +1,34 @@
+import { showsGuide, withExperimental } from "../cli-args.ts";
+import type { Config } from "../config/load.ts";
+import { optionLayersOf } from "../config/option-problems.ts";
+import { rulesOf } from "../custom/load.ts";
+import { reportedGuide } from "../genre-guide/report.ts";
+import { rulesJson } from "../render/rules-json.ts";
+import { rulesTable } from "../render/rules-table.ts";
+import { hostLanguage } from "../ui.ts";
+
+/** The genre the rules are shown for when none is set. */
+const SHOWN_GENRE = "blog/tech";
+
+export type RulesContext = {
+  readonly flag: (argv: readonly string[], name: string) => string | undefined;
+  /** Says once, on stderr, what in the settings has no effect. */
+  readonly warn: (config: Config, language: string) => void;
+};
+
+/** `rules --json` for an AI to read, with the guide of a genre that was set; `rules` alone, a table for a person. */
+export const showRules = (argv: readonly string[], written: Config, context: RulesContext): number => {
+  const config = withExperimental(written, argv);
+  const language = config.language ?? hostLanguage(undefined, process.env);
+  context.warn(config, language);
+  const setGenre = context.flag(argv, "--genre") ?? config.genre;
+  const genre = setGenre ?? SHOWN_GENRE;
+  const rules = rulesOf(language, config);
+  if (!argv.includes("--json")) {
+    console.log(rulesTable(rules, config, language, genre));
+    return 0;
+  }
+  const guide = setGenre !== undefined && showsGuide(argv) ? reportedGuide(config, genre, language, rules) : undefined;
+  console.log(rulesJson(rules, config, language, genre, optionLayersOf(config), guide));
+  return 0;
+};

package/src/config/load.ts

@@ -7,6 +7,7 @@ import type { Level } from "../plugin.ts";
 import type { PathRule } from "./by-path.ts";
 import type { Extensions } from "../extension/load.ts";
 import type { StyleLimits } from "../style-parse.ts";
+import type { GuideLayer } from "../genre-guide/layer.ts";
 
 export const CONFIG_FILE = "chaff.yaml";
 
@@ -46,7 +47,7 @@ export type Config = {
   readonly unreadableOptions?: string | undefined;
   /** The house style chaff.yaml names (styles/*.yaml), as written. A value that is not a name is kept printed, to be reported. */
   readonly style?: string | undefined;
-  /** The style once applied (config/style.ts): its id, the rules whose level it decided, and its options. */
+  /** The style once applied (config/style.ts): its id, the rules whose level it decided, its options and its guide. */
   readonly applied?: AppliedStyle | undefined;
   /** custom_rules as written: the team's own rules. custom/parse.ts reads and checks them. */
   readonly customRules?: unknown;
@@ -54,6 +55,8 @@ export type Config = {
   readonly grade?: unknown;
   /** fix_plan as written: the depth chaff fix-plan rewrites to (fix-plan/chosen-depth.ts reads and checks it). */
   readonly fixPlan?: unknown;
+  /** guide as written: the team's changes to the genre guides, or off (genre-guide/of-config.ts reads it). */
+  readonly guide?: unknown;
   /** plugins as written: package names and paths. extension/plugin-load.ts reads and checks them. */
   readonly plugins?: unknown;
   /** The code chaff.yaml names, once loaded (extension/load.ts). Reading chaff.yaml does not load it. */
@@ -66,6 +69,8 @@ export type AppliedStyle = {
   readonly options: Readonly<Record<string, unknown>>;
   /** The style's numbers, by rule and language, for the rules whose level it decided. */
   readonly limits: StyleLimits;
+  /** The style's changes to the genre guides, when it has any. */
+  readonly guide?: GuideLayer | undefined;
 };
 
 /** 判定の質が誤検知に直結するので、既定は最上位のモデル。cost は絞り込みで削る。spec §14。 */
@@ -200,6 +205,7 @@ export const loadConfig = (path: string): Config => {
     customRules: raw["custom_rules"],
     grade: raw["grade"],
     fixPlan: raw["fix_plan"],
+    guide: raw["guide"],
     plugins: raw["plugins"],
   };
 };

package/src/config/style.ts

@@ -22,7 +22,7 @@ export const withStyle = (config: Config, styles: readonly StyleDefinition[]): C
   return {
     ...config,
     rules: { ...style.rules, ...config.rules },
-    applied: { style: style.id, levelsFrom: fromStyle, options: style.options, limits },
+    applied: { style: style.id, levelsFrom: fromStyle, options: style.options, limits, guide: style.guide },
   };
 };
 

package/src/config/warnings.ts

@@ -4,10 +4,12 @@ import type { UiLanguage } from "../ui.ts";
 import { ruleProblems } from "./rule-problems.ts";
 import { nameProblems } from "./name-problems.ts";
 import { configOptionProblems } from "./option-problems.ts";
+import { configGuideProblems } from "../genre-guide/of-config.ts";
 
-/** Everything in chaff.yaml that has no effect: unknown rules or levels, unreadable names, options that do not apply. Said before the results. */
+/** Everything in chaff.yaml that has no effect: unknown rules or levels, unreadable names, options that do not apply, guides that cannot be read. Said before the results. */
 export const settingWarnings = (config: Config, rules: readonly RuleDefinition[], ui: UiLanguage): string[] => [
   ...ruleProblems(config, rules, ui),
   ...nameProblems(config, ui),
   ...configOptionProblems(config, rules, ui),
+  ...configGuideProblems(config, ui),
 ];

package/src/detectors/ellipsis.ts

@@ -0,0 +1,74 @@
+import type { Detector, Finding } from "../plugin.ts";
+import { escapeRegExp } from "../orthography.ts";
+import { formMinority } from "./form-minority.ts";
+import { quoteAround } from "./quote-around.ts";
+
+// One document writing an ellipsis two ways ("..." and "…", "……" and "・・・"). Neither is called right; the less common is
+// reported. The forms come from each language's lexicon "ellipsis".
+
+/** One ellipsis as written. form is the lexicon's pattern it matched. */
+export type WrittenEllipsis = { readonly offset: number; readonly form: string };
+
+/** Characters an ellipsis is made of. A longer run ("....", "…・") is not read, since its form is unclear. */
+const ELLIPSIS_PART = "[.．…・‥]";
+
+/** A digit or a slash beside the dots: a range (1...10), a path (docs/.../index.md) or a page number after a leader (第1章・・・3). */
+const NOT_PROSE_BESIDE = /[\p{N}/]/u;
+/** The rest of a line after a leader in a table of contents ("Intro ... 12"). */
+const PAGE_NUMBER_LINE = /^\s*\p{N}+\s*(?:\n|$)/u;
+/** A word holding a scheme or a slash around the dots is an address (https://example.com/a...b). */
+const ADDRESS_WORD = /:\/\/|\//u;
+
+const SPACE = /\s/u;
+
+/** The run of non-space characters holding the dots. */
+const wordAround = (text: string, start: number, end: number): string => {
+  const from =
+    text
+      .slice(0, start)
+      .split("")
+      .findLastIndex((char) => SPACE.test(char)) + 1;
+  const after = text
+    .slice(end)
+    .split("")
+    .findIndex((char) => SPACE.test(char));
+  return text.slice(from, after === -1 ? text.length : end + after);
+};
+
+/** Dots that are not an ellipsis in running text: a range, a path or address, a table of contents leader. */
+const isNotProse = (text: string, start: number, end: number): boolean =>
+  NOT_PROSE_BESIDE.test(text.charAt(start - 1)) ||
+  NOT_PROSE_BESIDE.test(text.charAt(end)) ||
+  PAGE_NUMBER_LINE.test(text.slice(end)) ||
+  ADDRESS_WORD.test(wordAround(text, start, end));
+
+/** The ellipses in a text, matched longest form first, standing alone (not part of a longer run of dots). */
+export const ellipsesIn = (text: string, forms: readonly string[]): WrittenEllipsis[] => {
+  if (forms.length === 0) return [];
+  const alternatives = forms
+    .toSorted((left, right) => right.length - left.length)
+    .map(escapeRegExp)
+    .join("|");
+  const pattern = new RegExp(`(?<!${ELLIPSIS_PART})(?:${alternatives})(?!${ELLIPSIS_PART})`, "gu");
+  return [...text.matchAll(pattern)].flatMap((match) =>
+    isNotProse(text, match.index, match.index + match[0].length) ? [] : [{ offset: match.index, form: match[0] }],
+  );
+};
+
+export const ellipsisConsistency: Detector = (doc, options): Finding[] => {
+  const text = doc.prose ?? doc.source;
+  const ellipses = ellipsesIn(
+    text,
+    (doc.lexicons["ellipsis"] ?? []).map((entry) => entry.pattern),
+  );
+  const minority = formMinority(ellipses, options.limit);
+  if (minority === undefined) return [];
+  return minority.odd.map((ellipsis) => ({
+    rule: "",
+    severity: "info",
+    line: 0,
+    column: 0,
+    quote: quoteAround(text, ellipsis.offset, ellipsis.offset + ellipsis.form.length),
+    values: { written: ellipsis.form, usual: minority.usual.form, count: minority.odd.length, of: ellipses.length, offset: ellipsis.offset },
+  }));
+};

package/src/detectors/registry/ellipsis-consistency.ts

@@ -0,0 +1,4 @@
+import type { Detector } from "../../plugin.ts";
+import { ellipsisConsistency } from "../ellipsis.ts";
+
+export const detector: Detector = ellipsisConsistency;

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: [] };
 };