chaffjs 0.20.0 → 0.22.0

package/src/extension/pack-read.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parse } from "yaml";
+import { API_VERSION } from "../api.ts";
+import { isInside } from "../custom/module-path.ts";
+
+// A rule pack: a plugin written in YAML alone. Its folder holds a manifest (chaff-plugin.yaml, or a chaff field in
+// package.json), rules/*.yaml, lexicons/<language>/<list>.yaml and styles/*.yaml. Read here into the shape a code
+// plugin's default export has, so plugin-parse.ts checks a pack exactly as it checks a code plugin. Nothing is run.
+
+export const PACK_MANIFEST = "chaff-plugin.yaml";
+
+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) ?? typeof value;
+
+const firstLine = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+
+/** A YAML file, or why it cannot be read, naming it as the pack's own path (rules/no-tbd.yaml). */
+const readYaml = (dir: string, path: string): { readonly value: unknown } | { readonly message: string } => {
+  try {
+    // A link inside the pack that points out of it would read a file the pack does not hold.
+    if (!isInside(realpathSync(dir), realpathSync(join(dir, path)))) return { message: `${path}: it links to a file outside the pack` };
+    return { value: parse(readFileSync(join(dir, path), "utf8")) };
+  } catch (error) {
+    return { message: `${path}: ${firstLine(error)}` };
+  }
+};
+
+const yamlFilesIn = (dir: string, folder: string): string[] => {
+  const full = join(dir, folder);
+  if (!existsSync(full) || !statSync(full).isDirectory()) return [];
+  return readdirSync(full)
+    .filter((file) => file.endsWith(".yaml") || file.endsWith(".yml"))
+    .toSorted((left, right) => left.localeCompare(right, "en"))
+    .map((file) => `${folder}/${file}`);
+};
+
+const foldersIn = (dir: string, folder: string): string[] => {
+  const full = join(dir, folder);
+  if (!existsSync(full) || !statSync(full).isDirectory()) return [];
+  return readdirSync(full)
+    .filter((name) => statSync(join(full, name)).isDirectory())
+    .toSorted((left, right) => left.localeCompare(right, "en"));
+};
+
+const packageJsonOf = (dir: string): Record<string, unknown> | undefined => {
+  const read = existsSync(join(dir, "package.json")) ? readYaml(dir, "package.json") : undefined;
+  return read !== undefined && "value" in read && isRecord(read.value) ? read.value : undefined;
+};
+
+/** The name in the folder's package.json, if it has one. */
+export const packageNameOf = (dir: string): string | undefined => {
+  const name = packageJsonOf(dir)?.["name"];
+  return typeof name === "string" ? name : undefined;
+};
+
+/**
+ * The manifest of a pack folder: chaff-plugin.yaml, else package.json's chaff field. undefined when the folder is not
+ * a pack (a code plugin, loaded by importing it). A manifest that cannot be read is reported, not taken for "not a pack".
+ */
+export const packManifestOf = (dir: string): { readonly manifest: Record<string, unknown> } | { readonly message: string } | undefined => {
+  if (existsSync(join(dir, PACK_MANIFEST))) {
+    const read = readYaml(dir, PACK_MANIFEST);
+    if ("message" in read) return read;
+    // An empty manifest only marks the folder; anything else must be a map.
+    if (read.value === null || read.value === undefined) return { manifest: {} };
+    return isRecord(read.value) ? { manifest: read.value } : { message: `${PACK_MANIFEST}: write a map (apiVersion: 1), not ${printed(read.value)}` };
+  }
+  const chaff = packageJsonOf(dir)?.["chaff"];
+  if (chaff === undefined) return undefined;
+  return isRecord(chaff) ? { manifest: chaff } : { message: `package.json: chaff must be a map ({ "apiVersion": 1 }), not ${printed(chaff)}` };
+};
+
+type Read<T> = { readonly value: T } | { readonly message: string };
+
+/** Every file's value in the order of the files, or the first that cannot be read. */
+const readAll = (dir: string, paths: readonly string[]): Read<unknown[]> =>
+  paths.reduce<Read<unknown[]>>(
+    (done, path) => {
+      if ("message" in done) return done;
+      const read = readYaml(dir, path);
+      return "message" in read ? read : { value: [...done.value, read.value] };
+    },
+    { value: [] },
+  );
+
+/** rules/*.yaml: each file holds one rule, or a list of them. */
+const rulesOf = (dir: string): Read<unknown[]> => {
+  const read = readAll(dir, yamlFilesIn(dir, "rules"));
+  return "message" in read ? read : { value: read.value.flatMap((value) => (Array.isArray(value) ? value.map((rule: unknown) => rule) : [value])) };
+};
+
+/** lexicons/<language>/<list>.yaml, as a code plugin writes its lexicons: { list: { language: entries } }. */
+const lexiconsOf = (dir: string): Read<Record<string, Record<string, unknown>>> =>
+  foldersIn(dir, "lexicons").reduce<Read<Record<string, Record<string, unknown>>>>(
+    (done, language) => {
+      if ("message" in done) return done;
+      const paths = yamlFilesIn(dir, `lexicons/${language}`);
+      const read = readAll(dir, paths);
+      if ("message" in read) return read;
+      const merged = paths.reduce<Record<string, Record<string, unknown>>>((acc, path, index) => {
+        const list = basename(path).replace(/\.ya?ml$/u, "");
+        return { ...acc, [list]: { ...acc[list], [language]: read.value[index] } };
+      }, done.value);
+      return { value: merged };
+    },
+    { value: {} },
+  );
+
+/** The pack as a plugin's default export: its name and API version from the manifest, its rules, lexicons and styles from its folders. */
+export const readPack = (dir: string, manifest: Readonly<Record<string, unknown>>, expectedName: string | undefined): Read<Record<string, unknown>> => {
+  const rules = rulesOf(dir);
+  if ("message" in rules) return rules;
+  const lexicons = lexiconsOf(dir);
+  if ("message" in lexicons) return lexicons;
+  const styles = readAll(dir, yamlFilesIn(dir, "styles"));
+  if ("message" in styles) return styles;
+  return {
+    value: {
+      apiVersion: manifest["apiVersion"] ?? API_VERSION,
+      name: manifest["name"] ?? expectedName,
+      rules: rules.value,
+      lexicons: lexicons.value,
+      styles: styles.value,
+    },
+  };
+};

package/src/extension/plugin-load.ts

@@ -1,3 +1,4 @@
+import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { CONFIG_FILE, type Config } from "../config/load.ts";
@@ -7,6 +8,7 @@ import { importDefault } from "./import-default.ts";
 import { staysInside } from "./real-path.ts";
 import { isPluginPath, pluginNameOfPackage } from "./plugin-name.ts";
 import { parsePlugin, type ParsedPlugin, type PluginOrigin, type PluginProblem } from "./plugin-parse.ts";
+import { PACK_MANIFEST, packManifestOf, packageNameOf, readPack } from "./pack-read.ts";
 
 // The plugins chaff.yaml lists under plugins:, found and loaded. A package is found from the folder chaff.yaml is in,
 // as Node finds it (node_modules); a path is the project's own plugin and, like a module rule, may not leave that
@@ -14,7 +16,8 @@ import { parsePlugin, type ParsedPlugin, type PluginOrigin, type PluginProblem }
 
 export type LoadedPlugins = { readonly plugins: readonly ParsedPlugin[]; readonly problems: readonly PluginProblem[] };
 
-type Located = { readonly origin: PluginOrigin } | { readonly problem: PluginProblem };
+/** 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 } => ({
   problem: { kind, plugin, detail },
@@ -29,24 +32,61 @@ const resolveFrom = (baseDir: string, specifier: string): string | undefined =>
   }
 };
 
+const isFolder = (path: string): boolean => existsSync(path) && statSync(path).isDirectory();
+
+/** A folder that is a rule pack: it has a manifest. A folder that is a code plugin is imported as Node imports it. */
+const isPack = (dir: string): boolean => packManifestOf(dir) !== undefined;
+
+/** The folder Node would find package name in from the folder chaff.yaml is in, whatever the package exports. */
+const packageFolder = (baseDir: string, name: string): string | undefined =>
+  (createRequire(join(baseDir, CONFIG_FILE)).resolve.paths(name) ?? [])
+    .map((nodeModules) => join(nodeModules, name))
+    .find((dir) => existsSync(join(dir, "package.json")));
+
+const packAt = (written: string, dir: string, expectedName: string | undefined): Located => ({
+  origin: { written, file: join(dir, PACK_MANIFEST), expectedName },
+  pack: dir,
+});
+
+/** A pack of the project's own takes its name from its package.json (chaff-plugin-foo is foo) when its manifest does not give one. */
+const localPackName = (dir: string): string | undefined => {
+  const name = packageNameOf(dir);
+  return name === undefined ? undefined : pluginNameOfPackage(name);
+};
+
+/** A plugin of the project's own, by its path: a pack folder, or a file (or folder) Node imports. Neither may leave the project. */
+const locatePath = (written: string, baseDir: string): Located => {
+  const path = modulePathOf(written, baseDir);
+  if ("refusal" in path) return problemOf("outside", written);
+  if (isFolder(path.file) && isPack(path.file))
+    return staysInside(written, path.file, baseDir) ? packAt(written, path.file, localPackName(path.file)) : problemOf("outside", written);
+  const file = resolveFrom(baseDir, path.file);
+  if (file === undefined) return problemOf("not-found", written);
+  return staysInside(written, file, baseDir) ? { origin: { written, file, expectedName: undefined } } : problemOf("outside", written);
+};
+
 const locate = (written: string, baseDir: string): Located => {
-  if (isPluginPath(written)) {
-    const path = modulePathOf(written, baseDir);
-    if ("refusal" in path) return problemOf("outside", written);
-    const file = resolveFrom(baseDir, path.file);
-    if (file === undefined) return problemOf("not-found", written);
-    return staysInside(written, file, baseDir) ? { origin: { written, file, expectedName: undefined } } : problemOf("outside", written);
-  }
+  if (isPluginPath(written)) return locatePath(written, baseDir);
   const expectedName = pluginNameOfPackage(written);
   if (expectedName === undefined) return problemOf("bad-specifier", written);
+  const folder = packageFolder(baseDir, written);
+  if (folder !== undefined && isPack(folder)) return packAt(written, folder, expectedName);
   const file = resolveFrom(baseDir, written);
   return file === undefined ? problemOf("not-found", written) : { origin: { written, file, expectedName } };
 };
 
+/** A rule pack read into what a code plugin's default export would be. Nothing in it runs. */
+const readPackAt = (dir: string, expectedName: string | undefined): { readonly exported: unknown } | { readonly message: string } => {
+  const manifest = packManifestOf(dir);
+  if (manifest !== undefined && "message" in manifest) return manifest;
+  const read = readPack(dir, manifest?.manifest ?? {}, expectedName);
+  return "message" in read ? read : { exported: read.value };
+};
+
 const loadPlugin = async (written: string, baseDir: string, useFor: readonly string[]): Promise<LoadedPlugins> => {
   const located = locate(written, baseDir);
   if ("problem" in located) return { plugins: [], problems: [located.problem] };
-  const imported = await importDefault(located.origin.file);
+  const imported = located.pack === undefined ? await importDefault(located.origin.file) : readPackAt(located.pack, located.origin.expectedName);
   if ("message" in imported) return { plugins: [], problems: [problemOf("import-failed", written, imported.message).problem] };
   const read = parsePlugin(imported.exported, located.origin, useFor);
   return { plugins: read.plugin === undefined ? [] : [read.plugin], problems: read.problems };

package/src/extension/plugin-parse.ts

@@ -6,6 +6,7 @@ import { styleOf, type StyleDefinition } from "../style-parse.ts";
 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";
 
 // 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
@@ -109,6 +110,7 @@ const rulesOf = (raw: unknown, context: RulesContext): Rules => {
   const parsed = parseCustomRules(Array.isArray(raw) ? raw.map((entry: unknown) => asCustomRule(entry, origin.file)) : raw, {
     builtIn: new Set(),
     useFor: context.useFor,
+    genres: knownGenres(),
     baseDir: dirname(origin.file),
   });
   const detectors = detectorsByWrittenId(Array.isArray(raw) ? raw : []);
@@ -134,14 +136,19 @@ const rulesOf = (raw: unknown, context: RulesContext): Rules => {
 const lexiconEntryOf = (value: unknown): LexiconEntry | undefined => {
   if (typeof value === "string") return value.trim() === "" ? undefined : { pattern: value.trim() };
   if (!isRecord(value) || typeof value["pattern"] !== "string" || value["pattern"].trim() === "") return undefined;
-  const insteadOf = value["instead_of"];
-  return { pattern: value["pattern"].trim(), ...(typeof insteadOf === "string" && insteadOf.trim() !== "" ? { instead_of: insteadOf.trim() } : {}) };
+  const [insteadOf, rewrite] = [value["instead_of"], value["rewrite"]];
+  return {
+    pattern: value["pattern"].trim(),
+    ...(typeof insteadOf === "string" && insteadOf.trim() !== "" ? { instead_of: insteadOf.trim() } : {}),
+    ...(typeof rewrite === "string" && rewrite.trim() !== "" ? { rewrite: rewrite.trim() } : {}),
+  };
 };
 
 const lexiconOf = (words: unknown): Lexicon | undefined => {
   const entries = Array.isArray(words) ? words.map(lexiconEntryOf) : [undefined];
   const readable = entries.flatMap((entry) => (entry === undefined ? [] : [entry]));
-  return readable.length === entries.length ? readable : undefined;
+  // An empty list would leave its rules running and finding nothing, which reads as a clean document.
+  return readable.length === entries.length && readable.length > 0 ? readable : undefined;
 };
 
 type ListInLanguage = { readonly language: string; readonly list: string; readonly lexicon: Lexicon };

package/src/facts/address-values.ts

@@ -0,0 +1,74 @@
+import type { Span } from "../plugin.ts";
+
+// Two kinds of value a docs site repeats from page to page, read by scanning rather than by a backtracking pattern:
+// an email address (help@example.com) and a version of three parts or more, or one written with v (2.4.1, v3).
+
+const LOCAL_CHAR = /[\p{L}\p{N}._%+-]/u;
+const DOMAIN_CHAR = /[\p{L}\p{N}.-]/u;
+const DOT = ".";
+
+/** The longest address there is (RFC 5321), so a scan from one @ never reads the whole document. */
+const MAX_ADDRESS = 254;
+
+/** Where the run of isPart characters that ends at from begins (UTF-16 units, like the offsets). */
+const extendLeft = (source: string, from: number, isPart: RegExp): number => {
+  const windowStart = Math.max(0, from - MAX_ADDRESS);
+  const stop = source
+    .slice(windowStart, from)
+    .split("")
+    .findLastIndex((char) => !isPart.test(char));
+  return windowStart + stop + 1;
+};
+
+/** Where the run of isPart characters that starts at from ends. */
+const extendRight = (source: string, from: number, isPart: RegExp): number => {
+  const stop = source
+    .slice(from, from + MAX_ADDRESS)
+    .split("")
+    .findIndex((char) => !isPart.test(char));
+  return stop === -1 ? Math.min(source.length, from + MAX_ADDRESS) : from + stop;
+};
+
+/** A sentence's full stop after an address or a version is not part of it. */
+const withoutTrailingDots = (text: string): string => text.slice(0, text.split("").findLastIndex((char) => char !== DOT) + 1);
+
+/** The address around one @: a local part, and the labels of the domain up to the first empty one, two or more. */
+const addressAt = (source: string, at: number): Span | undefined => {
+  const start = extendLeft(source, at, LOCAL_CHAR);
+  const written = source.slice(at + 1, extendRight(source, at + 1, DOMAIN_CHAR)).split(DOT);
+  const empty = written.indexOf("");
+  const labels = empty === -1 ? written : written.slice(0, empty);
+  if (start === at || labels.length < 2) return undefined;
+  return { start, end: at + 1 + labels.join(DOT).length };
+};
+
+/** The addresses in the text, left to right. An @ inside the address before it starts none. */
+export const emailSpans = (source: string): Span[] =>
+  [...source.matchAll(/@/gu)].reduce<Span[]>((found, match) => {
+    const span = addressAt(source, match.index);
+    const previous = found.at(-1);
+    return span === undefined || (previous !== undefined && span.start < previous.end) ? found : [...found, span];
+  }, []);
+
+/** A run of digits and dots, with a v before it or not, that starts a word. */
+const VERSION_RUN = /(?<![\p{L}\p{N}.])v?\d[\d.]*/gu;
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+const MIN_PARTS = 3;
+const MAX_PARTS = 4;
+const DIGITS = /^\d+$/u;
+
+/** A version: v and one part or more (v3, v2.1), or three or four parts without it (2.4.1). Not a run that a word continues. */
+const versionIn = (written: string, next: string): string | undefined => {
+  const run = withoutTrailingDots(written);
+  const prefixed = run.startsWith("v");
+  const parts = (prefixed ? run.slice(1) : run).split(DOT);
+  if (WORD_CHAR.test(next) && run === written) return undefined;
+  if (!parts.every((part) => DIGITS.test(part))) return undefined;
+  return prefixed || (parts.length >= MIN_PARTS && parts.length <= MAX_PARTS) ? run : undefined;
+};
+
+export const versionSpans = (source: string): Span[] =>
+  [...source.matchAll(VERSION_RUN)].flatMap((match) => {
+    const run = versionIn(match[0], source.charAt(match.index + match[0].length));
+    return run === undefined ? [] : [{ start: match.index, end: match.index + run.length }];
+  });

package/src/facts/cross-facts.ts

@@ -0,0 +1,54 @@
+import { comparable, sameValue, type FactValue } from "./fact-values.ts";
+import type { ScopedFact } from "./fact-scope.ts";
+import { tallyVotes, type Vote } from "../cross-votes.ts";
+
+// The same labelled fact given different values in different files of one run ("Monthly fee: $12" in one page, "$15" in
+// another). Pure: the facts come in already read from each file. Within a file, fact-conflict compares section by section.
+
+/** A file's labelled facts, by its path. */
+export type FileFacts = { readonly path: string; readonly facts: readonly ScopedFact[] };
+
+/** A file whose value for a label differs from the value most files give it: its first fact, and one file of the usual value. */
+export type FactOutOfStep = { readonly path: string; readonly fact: ScopedFact; readonly usual: Vote<ScopedFact>; readonly files: number };
+
+/** Two values the files can be said to agree or disagree on: comparable, and the same. */
+const sameFact = (left: ScopedFact, right: ScopedFact): boolean => sameValue(left.value, right.value);
+
+/**
+ * A file's vote for a label: its first fact, when every fact of the label in the file gives the same value. A file giving
+ * the label two values is either a list (a fee per plan) or a conflict within the file, which fact-conflict reports.
+ */
+const voteOf = (file: FileFacts, key: string): Vote<ScopedFact>[] => {
+  const facts = file.facts.filter((fact) => fact.key === key && !fact.record);
+  const [first] = facts;
+  if (first === undefined) return [];
+  return facts.every((fact) => comparable(first.value, fact.value) && sameFact(first, fact)) ? [{ path: file.path, value: first }] : [];
+};
+
+/** The votes split into groups whose values can be compared at all (one unit, overlapping date precision). */
+const comparableGroups = (votes: readonly Vote<ScopedFact>[]): Vote<ScopedFact>[][] =>
+  votes.reduce<Vote<ScopedFact>[][]>((groups, vote) => {
+    const home = groups.find((group) => group[0] !== undefined && comparable(group[0].value.value, vote.value.value));
+    if (home === undefined) groups.push([vote]);
+    else home.push(vote);
+    return groups;
+  }, []);
+
+/** Two values across the files, as with fact-conflict in one section: three or more is read as a list, and left alone. */
+const MAX_VALUES = 2;
+
+const outOfStep = (votes: readonly Vote<ScopedFact>[]): FactOutOfStep[] => {
+  const tally = tallyVotes(votes, sameFact);
+  const [usual] = tally?.usual ?? [];
+  if (tally === undefined || usual === undefined || tally.values !== MAX_VALUES) return [];
+  return tally.odd.map((vote) => ({ path: vote.path, fact: vote.value, usual, files: tally.usual.length }));
+};
+
+/** The files whose value for a label differs from the value most files of the run give it. */
+export const factsOutOfStep = (files: readonly FileFacts[]): FactOutOfStep[] => {
+  const keys = [...new Set(files.flatMap((file) => file.facts.map((fact) => fact.key)))];
+  return keys.flatMap((key) => comparableGroups(files.flatMap((file) => voteOf(file, key))).flatMap(outOfStep));
+};
+
+/** The value as written, for a message. */
+export const writtenValue = (source: string, value: FactValue): string => source.slice(value.start, value.end);

package/src/fix-plan/chosen-depth.ts

@@ -0,0 +1,28 @@
+import { readDepth, unknownDepthSentence } from "../rewrite-depth.ts";
+import type { UiLanguage } from "../ui.ts";
+import type { ChosenDepth } from "./plan.ts";
+
+// The depth a fix plan goes to: --depth, else chaff.yaml's fix_plan.depth, else none (chaff recommends one). Pure.
+
+export type DepthChoice = { readonly chosen: ChosenDepth | undefined } | { readonly problem: string };
+
+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);
+
+/** fix_plan as chaff.yaml writes it: nothing, or a map whose depth is a depth. */
+const configured = (fixPlan: unknown, ui: UiLanguage): DepthChoice => {
+  if (fixPlan === undefined || fixPlan === null) return { chosen: undefined };
+  if (!isRecord(fixPlan)) return { problem: unknownDepthSentence("chaff.yaml fix_plan", printed(fixPlan), ui) };
+  const read = readDepth(fixPlan["depth"]);
+  if ("unknown" in read) return { problem: unknownDepthSentence("chaff.yaml fix_plan.depth", read.unknown, ui) };
+  return { chosen: read.depth === undefined ? undefined : { depth: read.depth, from: "config" } };
+};
+
+/** flag: --depth's value, or undefined when it is not given. An empty value is a value, and not a depth. */
+export const chosenDepthOf = (flag: string | undefined, fixPlan: unknown, ui: UiLanguage): DepthChoice => {
+  if (flag === undefined) return configured(fixPlan, ui);
+  const read = readDepth(flag);
+  if ("depth" in read && read.depth !== undefined) return { chosen: { depth: read.depth, from: "flag" } };
+  return { problem: unknownDepthSentence("--depth", flag, ui) };
+};

package/src/fix-plan/mode.ts

@@ -1,13 +1,22 @@
+import { depthIncludes, type RewriteDepth } from "../rewrite-depth.ts";
+
 /**
- * Which of the three ways to rewrite (the guide's Light, Bold and Full) chaff recommends, from what it found alone.
+ * Which way to rewrite: the guide's Light, Bold and Full, and Register. Each is a rewrite depth (rewrite-depth.ts):
+ * Light and Bold keep the structure (light), Full reorganises it (structure), Register converts the style (register).
+ * chaff recommends a way from what it found; --depth or chaff.yaml's fix_plan.depth chooses the depth instead.
  * A request that says "from scratch" also means Full; chaff cannot read the request, so the plan says so in words.
  */
-export type FixMode = "none" | "light" | "bold" | "full";
+export type FixMode = "none" | "light" | "bold" | "full" | "register";
 
-/** Why the mode was chosen, so the plan can say it. */
-export type ModeReason = "nothing-found" | "composite" | "structure" | "genre" | "signals" | "spots";
+/** Why the mode was chosen, so the plan can say it. chosen: the depth was given; depth-limit: chaff would go deeper than the depth given. */
+export type ModeReason = "nothing-found" | "all-deeper" | "composite" | "structure" | "genre" | "signals" | "spots" | "chosen" | "depth-limit";
 
-export type ModeChoice = { readonly mode: FixMode; readonly reason: ModeReason };
+export type ModeChoice = {
+  readonly mode: FixMode;
+  readonly reason: ModeReason;
+  /** How deep the rewrite goes. None when there is nothing to fix. */
+  readonly depth: RewriteDepth | undefined;
+};
 
 export type ModeInput = {
   readonly genre: string;
@@ -17,10 +26,25 @@ export type ModeInput = {
   readonly signalRules: ReadonlySet<string>;
   /** The structure score (measures past 90% of human articles) and the count at which the outline itself is the problem. */
   readonly structure?: { readonly score: number; readonly limit: number };
+  /** The depth --depth or chaff.yaml chose. Without one, chaff recommends. */
+  readonly chosen?: RewriteDepth | undefined;
+  /** How many fired rules the chosen depth sets apart; they are not in firedRules. */
+  readonly setApart?: number;
 };
 
 export const COMPOSITE_RULE = "ai-generated-composite";
 
+const DEPTH_OF: Readonly<Record<FixMode, RewriteDepth | undefined>> = {
+  none: undefined,
+  light: "light",
+  bold: "light",
+  full: "structure",
+  register: "register",
+};
+
+/** The way that goes exactly as deep as a chosen depth, beyond light, where chaff's recommendation picks Light or Bold. */
+const MODE_AT: Readonly<Record<Exclude<RewriteDepth, "light">, FixMode>> = { structure: "full", register: "register" };
+
 /** Two document-wide signals mean the prose of the sections is the problem, not a spot or two. */
 const MIN_SIGNALS_FOR_BOLD = 2;
 
@@ -30,11 +54,33 @@ const isFreeFormGenre = (genre: string): boolean => genre.startsWith("blog/") ||
 /** An outline far from human articles is rewritten from the outline, in any genre and whether or not a rule fired. */
 const hasStructureToFix = (input: ModeInput): boolean => input.structure !== undefined && input.structure.score >= input.structure.limit;
 
-export const recommendMode = (input: ModeInput): ModeChoice => {
-  if (input.firedRules.has(COMPOSITE_RULE)) return { mode: "full", reason: "composite" };
-  if (hasStructureToFix(input)) return { mode: "full", reason: "structure" };
-  if (input.firedRules.size === 0) return { mode: "none", reason: "nothing-found" };
-  if (isFreeFormGenre(input.genre)) return { mode: "full", reason: "genre" };
+const choice = (mode: FixMode, reason: ModeReason): ModeChoice => ({ mode, reason, depth: DEPTH_OF[mode] });
+
+/** Two document-wide signals mean Bold, else Light: the deepest way that keeps the structure. */
+const lightOrBold = (input: ModeInput): ModeChoice => {
   const signals = [...input.firedRules].filter((rule) => input.signalRules.has(rule)).length;
-  return signals >= MIN_SIGNALS_FOR_BOLD ? { mode: "bold", reason: "signals" } : { mode: "light", reason: "spots" };
+  return signals >= MIN_SIGNALS_FOR_BOLD ? choice("bold", "signals") : choice("light", "spots");
+};
+
+/** What chaff recommends from its findings alone. */
+const recommended = (input: ModeInput): ModeChoice => {
+  if (input.firedRules.has(COMPOSITE_RULE)) return choice("full", "composite");
+  if (hasStructureToFix(input)) return choice("full", "structure");
+  if (input.firedRules.size === 0) return choice("none", (input.setApart ?? 0) > 0 ? "all-deeper" : "nothing-found");
+  if (isFreeFormGenre(input.genre)) return choice("full", "genre");
+  return lightOrBold(input);
+};
+
+/** A chosen depth sets how deep the rewrite goes. At light, chaff still picks Light or Bold, and says when it would go deeper. */
+const atChosenDepth = (input: ModeInput, chosen: RewriteDepth, ownChoice: ModeChoice): ModeChoice => {
+  if (chosen !== "light") return ownChoice.depth === chosen ? ownChoice : choice(MODE_AT[chosen], "chosen");
+  if (ownChoice.depth !== undefined && depthIncludes(chosen, ownChoice.depth)) return ownChoice;
+  const within = lightOrBold(input);
+  return { ...within, reason: "depth-limit" };
+};
+
+export const recommendMode = (input: ModeInput): ModeChoice => {
+  const ownChoice = recommended(input);
+  if (input.chosen === undefined || ownChoice.mode === "none") return ownChoice;
+  return atChosenDepth(input, input.chosen, ownChoice);
 };

package/src/fix-plan/plan.ts

@@ -7,6 +7,7 @@ import { splitWords } from "../detectors/word-list.ts";
 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";
 
 /** 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 };
@@ -18,6 +19,8 @@ export type PhraseHint = { readonly phrase: string; readonly rewrite: string };
 export type RulePlan = {
   readonly rule: string;
   readonly name: string;
+  /** How deep the rule's direction reaches (rewrite.depth); light when the rule does not say. */
+  readonly depth: RewriteDepth;
   /** The rule's rewrite direction, or its how_to_fix when it has no rewrite block. */
   readonly direction: string;
   readonly keep: readonly string[];
@@ -31,6 +34,12 @@ export type RulePlan = {
 /** A rule that measures the whole document, with what it said. */
 type DocumentSignal = { readonly rule: string; readonly message: string };
 
+/** A rule that fired but reaches deeper than the chosen depth: named, not planned, so its silence is not read as fixed. */
+export type DeeperRule = { readonly rule: string; readonly name: string; readonly depth: RewriteDepth; readonly spots: number };
+
+/** The depth chosen for the plan, and where: --depth on the command line, or fix_plan.depth in chaff.yaml. */
+export type ChosenDepth = { readonly depth: RewriteDepth; readonly from: "flag" | "config" };
+
 export type FixPlan = {
   readonly path: string;
   /** Where the plan suggests saving the rewrite, so the check commands can be pasted as they are. */
@@ -39,6 +48,8 @@ export type FixPlan = {
   readonly genre: string;
   readonly experimental: boolean;
   readonly mode: ModeChoice;
+  /** None when chaff recommends the depth itself. */
+  readonly chosenDepth: ChosenDepth | undefined;
   readonly signals: readonly DocumentSignal[];
   readonly outline: { readonly unit: LengthUnit; readonly shape: Shape };
   /** The structure score, the count at which the plan rewrites from the outline, and how many measures were compared. */
@@ -46,6 +57,8 @@ export type FixPlan = {
   /** The structure measures past 90% of human articles, each with the human numbers to bring it back to. */
   readonly targets: readonly StructureTarget[];
   readonly rules: readonly RulePlan[];
+  /** The rules that fired but reach deeper than the chosen depth. Empty without a chosen depth. */
+  readonly deeper: readonly DeeperRule[];
   /** The rewrite and signal rules that did not run, and why: silence from them is not "checked and fine". */
   readonly notRun: readonly Skipped[];
   readonly checks: readonly string[];
@@ -66,6 +79,7 @@ export type PlanInput = {
   readonly structure: StructureScore;
   /** The ai-tell lexicon of the document's language, whose entries may carry their own hint. */
   readonly phrases: Lexicon;
+  readonly chosenDepth?: ChosenDepth | undefined;
 };
 
 const BOLD_DENSITY_RULE = "bold-density";
@@ -114,6 +128,7 @@ const rulePlanOf = (rule: RuleDefinition, findings: readonly Finding[], input: P
   return {
     rule: rule.id,
     name: localized(rule.name, input.language),
+    depth: depthOfRule(rule),
     direction: rewrite?.direction ?? localized(rule.how_to_fix, input.language),
     keep: rewrite?.keep ?? [],
     avoid: rewrite?.avoid ?? [],
@@ -123,6 +138,18 @@ const rulePlanOf = (rule: RuleDefinition, findings: readonly Finding[], input: P
   };
 };
 
+const depthOfRule = (rule: RuleDefinition): RewriteDepth => rule.guide?.rewriteDepth ?? DEFAULT_DEPTH;
+
+/** Every rule that fired, planned; then the ones a chosen depth leaves out, set apart. */
+const byDepth = (plans: readonly RulePlan[], chosen: ChosenDepth | undefined): Pick<FixPlan, "rules" | "deeper"> => {
+  if (chosen === undefined) return { rules: plans, deeper: [] };
+  const within = (plan: RulePlan): boolean => depthIncludes(chosen.depth, plan.depth);
+  return {
+    rules: plans.filter(within),
+    deeper: plans.filter((plan) => !within(plan)).map((plan) => ({ rule: plan.rule, name: plan.name, depth: plan.depth, spots: plan.spots.length })),
+  };
+};
+
 /** The rules in the order their first finding appears; the composite has no spot of its own and is a signal only. */
 const rulePlansOf = (input: PlanInput): RulePlan[] => {
   const order = [...new Set(input.findings.map((finding) => finding.rule))].filter((id) => id !== COMPOSITE_RULE);
@@ -159,12 +186,12 @@ const notRunOf = (input: PlanInput, signalRules: ReadonlySet<string>): Skipped[]
   return input.skipped.filter((skipped) => watched.has(skipped.rule));
 };
 
-/** The commands to run on the rewrite. A full rewrite cuts repeats and rebuilds headings, which compare is told. */
+/** The commands to run on the rewrite. A rewrite past light cuts repeats and rebuilds headings, which compare is told. */
 const checksOf = (input: PlanInput, choice: ModeChoice): string[] => {
   const original = shellPath(input.path);
   const rewritten = shellPath(rewrittenPathOf(input.path));
   const lintFlags = [...(input.experimental ? ["--experimental"] : []), ...(input.genreFlag === undefined ? [] : ["--genre", input.genreFlag])];
-  const compareFlags = choice.mode === "full" ? ["--distinct", "--allow-dropped heading", "--allow-added heading"] : [];
+  const compareFlags = choice.depth !== undefined && choice.depth !== "light" ? ["--distinct", "--allow-dropped heading", "--allow-added heading"] : [];
   return [
     ["npx chaffjs", rewritten, ...lintFlags].join(" "),
     ["npx chaffjs compare", original, rewritten, ...compareFlags].join(" "),
@@ -182,8 +209,12 @@ const documentLength = (outline: Outline): number => outline.entries.reduce((sum
 export const buildFixPlan = (input: PlanInput): FixPlan => {
   const signalRules = signalRulesOf(input.rules);
   const structure = { score: input.structure.score, limit: structureLimitOf(input.rules), compared: input.structure.compared };
-  const firedRules = new Set(input.findings.map((finding) => finding.rule));
-  const mode = recommendMode({ genre: input.genre, firedRules, signalRules, structure });
+  const planned = byDepth(rulePlansOf(input), input.chosenDepth);
+  // A rule the depth sets apart is not something this rewrite fixes, so it does not decide the way either.
+  const setApart = new Set(planned.deeper.map((rule) => rule.rule));
+  const firedRules = new Set(input.findings.map((finding) => finding.rule).filter((rule) => !setApart.has(rule)));
+  const chosen = input.chosenDepth?.depth;
+  const mode = recommendMode({ genre: input.genre, firedRules, signalRules, structure, chosen, setApart: setApart.size });
   return {
     path: input.path,
     rewrittenPath: rewrittenPathOf(input.path),
@@ -191,11 +222,12 @@ export const buildFixPlan = (input: PlanInput): FixPlan => {
     genre: input.genre,
     experimental: input.experimental,
     mode,
+    chosenDepth: input.chosenDepth,
     signals: signalsOf(input, signalRules),
     outline: { unit: input.outline.unit, shape: input.outline.shape },
     structure,
     targets: structureTargetsOf(input.structure, documentLength(input.outline)),
-    rules: rulePlansOf(input),
+    ...planned,
     notRun: notRunOf(input, signalRules),
     checks: checksOf(input, mode),
   };