chaffjs 0.20.0 → 0.21.0

package/src/detectors/technical-docs.ts

@@ -0,0 +1,230 @@
+// Checks a README or a manual needs: code fences tagged with a language or not, shell commands written with and without
+// a prompt, a heading that names a command its section's code never shows, and a step of a numbered procedure written
+// as a statement among instructions. Pure. Shell languages and prompt marks come from the shell-fence-language and
+// shell-prompt lexicons.
+import { codeFences, codeSpans, type CodeFence } from "./code-fences.ts";
+import { quoteAt } from "./structure-tree.ts";
+import type { Detector, Finding, ProseDocument, Span, Token } from "../plugin.ts";
+
+const patternsOf = (doc: ProseDocument, id: string): string[] => (doc.lexicons[id] ?? []).map((entry) => entry.pattern);
+
+/** The members of the less used of two kinds: at most limit of them, and fewer than the other kind. */
+export const minorityOf = <T>(first: readonly T[], second: readonly T[], limit: number): readonly T[] => {
+  const [fewer, more] = first.length <= second.length ? [first, second] : [second, first];
+  return fewer.length > 0 && fewer.length < more.length && fewer.length <= limit ? fewer : [];
+};
+
+const finding = (doc: ProseDocument, rule: string, offset: number, values: Readonly<Record<string, string | number>> = {}): Finding => ({
+  rule,
+  severity: "info",
+  line: 0,
+  column: 0,
+  quote: quoteAt(doc.source, offset),
+  values: { ...values, offset },
+});
+
+/** Fences without a language, when they are the fewer kind: a document that mostly leaves the language out is not reported. */
+export const untaggedFewer = (fences: readonly CodeFence[], limit: number): readonly CodeFence[] => {
+  const untagged = fences.filter((fence) => fence.language === "");
+  const tagged = fences.filter((fence) => fence.language !== "");
+  return untagged.length > 0 && untagged.length < tagged.length && untagged.length <= limit ? untagged : [];
+};
+
+export const codeFenceLanguage: Detector = (doc, options): Finding[] => {
+  const fences = codeFences(doc.source);
+  const tagged = fences.filter((fence) => fence.language !== "").length;
+  return untaggedFewer(fences, options.limit).map((fence) =>
+    finding(doc, "code-fence-language-mix", fence.start, { tagged, untagged: fences.length - tagged }),
+  );
+};
+
+export type PromptStyle = "prompt" | "bare" | undefined;
+
+/**
+ * Whether a shell block writes its commands after a prompt ($ npm install) or bare (npm install). A block that mixes
+ * prompted and unprompted lines shows a command with its output, and is neither. Comment lines (#) are skipped.
+ */
+export const promptStyleOf = (fence: CodeFence, prompts: readonly string[]): PromptStyle => {
+  const lines = fence.lines.map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#"));
+  if (lines.length === 0) return undefined;
+  const prompted = lines.filter((line) => prompts.some((prompt) => line.startsWith(`${prompt} `))).length;
+  if (prompted === lines.length) return "prompt";
+  return prompted === 0 ? "bare" : undefined;
+};
+
+export const shellPrompt: Detector = (doc, options): Finding[] => {
+  const languages = new Set(patternsOf(doc, "shell-fence-language").map((language) => language.toLowerCase()));
+  const prompts = patternsOf(doc, "shell-prompt");
+  const shells = codeFences(doc.source).filter((fence) => languages.has(fence.language));
+  const prompted = shells.filter((fence) => promptStyleOf(fence, prompts) === "prompt");
+  const bare = shells.filter((fence) => promptStyleOf(fence, prompts) === "bare");
+  const minority = minorityOf(prompted, bare, options.limit);
+  const style = minority === prompted ? "prompt" : "bare";
+  return minority.map((fence) => finding(doc, "shell-prompt-mix", fence.start, { majority: style === "prompt" ? bare.length : prompted.length }));
+};
+
+/**
+ * A code span that names a command or an option: a flag (--force, -f) or a command with its arguments (npm install). A
+ * single plain word (net, init) is as often a package, an endpoint or a type as a command, and is left out.
+ */
+const COMMAND_WORD = /^[a-z][a-z0-9_-]*$/u;
+const FLAG = /^--?[A-Za-z][\w-]*$/u;
+
+export const isCommandName = (text: string): boolean => {
+  const words = text.trim().split(/\s+/u);
+  const first = words[0] ?? "";
+  return words.length === 1 ? FLAG.test(first) : COMMAND_WORD.test(first);
+};
+
+/** The heading without its links' text: [`net`](/pkg/net/) names the page it links to, not a command shown below. */
+export const withoutLinks = (heading: string): string => {
+  const pieces: string[] = [];
+  const state = { at: 0 };
+  while (state.at < heading.length) {
+    const open = heading.indexOf("[", state.at);
+    const close = open === -1 ? -1 : heading.indexOf("]", open);
+    if (close === -1) break;
+    pieces.push(heading.slice(state.at, open), " ");
+    state.at = close + 1 + targetLength(heading, close + 1);
+  }
+  pieces.push(heading.slice(state.at));
+  return pieces.join("");
+};
+
+/** The length of a link's target right after its text: (url), [label] or [] (a reference link); 0 when there is none. */
+const targetLength = (heading: string, at: number): number => {
+  const pair: Readonly<Record<string, string>> = { "(": ")", "[": "]" };
+  const closer = pair[heading.charAt(at)];
+  const end = closer === undefined ? -1 : heading.indexOf(closer, at);
+  return end === -1 ? 0 : end - at + 1;
+};
+
+/** The commands and options a heading names: its code spans that read as one, and bare flags (--force). */
+export const commandsIn = (heading: string): string[] => {
+  const spans = codeSpans(withoutLinks(heading)).map((span) => span.text);
+  const flags = heading
+    .replace(/`[^`]*`/gu, " ")
+    .split(/\s+/u)
+    .filter((word) => FLAG.test(word) && word.startsWith("--"));
+  return [...new Set([...spans.filter(isCommandName), ...flags])];
+};
+
+const collapse = (text: string): string => text.replace(/\s+/gu, " ");
+const OPTION_CHAR = /[A-Za-z0-9_-]/u;
+
+/** Whether the code holds the command as a whole word: --force is not --force-with-lease, init is not initial. */
+export const showsCommand = (code: string, command: string): boolean => {
+  const text = collapse(code);
+  const wanted = collapse(command.trim());
+  const state = { at: text.indexOf(wanted) };
+  while (state.at !== -1) {
+    const before = text.charAt(state.at - 1);
+    const after = text.charAt(state.at + wanted.length);
+    if (!OPTION_CHAR.test(before) && !OPTION_CHAR.test(after)) return true;
+    state.at = text.indexOf(wanted, state.at + 1);
+  }
+  return false;
+};
+
+type Section = { readonly heading: string; readonly start: number; readonly body: Span };
+
+const sectionsOf = (doc: ProseDocument): Section[] => {
+  const headings = doc.markup?.headings ?? [];
+  return headings.map((heading, index) => {
+    const next = headings.slice(index + 1).find((later) => later.depth <= heading.depth);
+    return { heading: doc.source.slice(heading.start, heading.end), start: heading.start, body: { start: heading.end, end: next?.start ?? doc.source.length } };
+  });
+};
+
+/** The code a section shows: its fenced blocks and its inline code spans. Empty when it shows none. */
+const codeOf = (doc: ProseDocument, fences: readonly CodeFence[], body: Span): string => {
+  const inFences = fences.filter((fence) => fence.start >= body.start && fence.start < body.end);
+  const outside = inFences.reduceRight(
+    (text, fence) => `${text.slice(0, fence.start - body.start)}${text.slice(Math.min(fence.end, body.end) - body.start)}`,
+    doc.source.slice(body.start, body.end),
+  );
+  return [...inFences.flatMap((fence) => fence.lines), ...codeSpans(outside).map((span) => span.text)].join("\n");
+};
+
+export const headingCommand: Detector = (doc): Finding[] => {
+  const fences = codeFences(doc.source);
+  return sectionsOf(doc).flatMap((section) => {
+    const commands = commandsIn(section.heading);
+    if (commands.length === 0) return [];
+    const code = codeOf(doc, fences, section.body);
+    if (code.trim() === "") return [];
+    return commands.filter((command) => !showsCommand(code, command)).map((command) => finding(doc, "heading-command-missing", section.start, { command }));
+  });
+};
+
+const ORDERED_ITEM = /^\s*\d{1,3}[.)]\s/u;
+/** What opens a statement: an article or a pronoun (The installer asks, You click, It opens). */
+const SUBJECT_OPENER = new Set(["DET", "PRON"]);
+/** What a subject opens with when it is a name or a noun phrase (Docker builds, Each user gets). */
+const SUBJECT_HEAD = new Set(["DET", "PRON", "PROPN", "NOUN", "ADJ"]);
+/** What may stand between the opener and the verb: the rest of the subject. */
+const SUBJECT_PART = new Set(["DET", "PRON", "PROPN", "NOUN", "ADJ", "ADP"]);
+/** What opens an instruction. The tagger reads a sentence-initial imperative as a noun, an adjective or a name (Click, Open, Restart). */
+const INSTRUCTION_OPENER = new Set(["VERB", "NOUN", "ADJ", "PROPN"]);
+const PREDICATE = new Set(["VERB", "AUX"]);
+const SKIPPED = new Set(["PUNCT", "NUM", "SYM", "X", "SPACE"]);
+/** Steps shorter than this are labels (1. Setup), not instructions or statements. */
+const MIN_STEP_TOKENS = 3;
+/** A list needs this many steps to have a form to keep. */
+const MIN_STEPS = 3;
+
+/** A verb in a finite, inflected form (starts, built): it has a subject before it. A base form (Save) may be an imperative's object. */
+const isInflected = (token: Token): boolean =>
+  token.lemma !== undefined && token.lemma !== "" && token.surface.toLowerCase() !== token.lemma && token.features?.["VerbForm"] !== "Part";
+
+/**
+ * A step written as a statement: a subject, then its verb. The subject opens with an article or a pronoun (The installer
+ * asks, You click), or it is a name or a noun whose verb is inflected (Docker builds). A noun before a base-form verb is
+ * not enough: the tagger reads Click and Press there as nouns (Click Save).
+ */
+export const isStatement = (tokens: readonly Token[]): boolean => {
+  const words = tokens.filter((token) => !SKIPPED.has(token.pos));
+  const [head, ...rest] = words;
+  if (head === undefined || words.length < MIN_STEP_TOKENS || !SUBJECT_HEAD.has(head.pos)) return false;
+  const verbAt = rest.findIndex((token) => PREDICATE.has(token.pos));
+  const verb = rest[verbAt];
+  if (verb === undefined || !rest.slice(0, verbAt).every((token) => SUBJECT_PART.has(token.pos))) return false;
+  // Punctuation before the verb is no subject: a label (Guests: the users who …) or an opening phrase (On the left bar, select …).
+  const interrupted = tokens.some((token) => token.pos === "PUNCT" && token.span.start > head.span.start && token.span.start < verb.span.start);
+  return !interrupted && (SUBJECT_OPENER.has(head.pos) || isInflected(verb));
+};
+
+type Step = { readonly start: number; readonly kind: "statement" | "instruction" | "other" };
+
+/** A step that opens with its verb: an instruction (Run the installer). */
+export const isInstruction = (tokens: readonly Token[]): boolean => INSTRUCTION_OPENER.has(tokens.find((token) => !SKIPPED.has(token.pos))?.pos ?? "");
+
+const kindOf = (tokens: readonly Token[]): Step["kind"] => {
+  if (isStatement(tokens)) return "statement";
+  return isInstruction(tokens) ? "instruction" : "other";
+};
+
+/** The steps of each numbered list: each item's first sentence, read as a statement or not. */
+const stepLists = (doc: ProseDocument): Step[][] =>
+  doc.lists
+    .filter((list) => ORDERED_ITEM.test(doc.source.slice(list.span.start, list.span.end)))
+    .map((list) =>
+      list.itemSpans.flatMap((item): Step[] => {
+        const sentence = doc.sentences.find((candidate) => candidate.span.start >= item.start && candidate.span.start < item.end);
+        // Only the sentence on the item's own line: a note paragraph under it (**NOTE:** …) is not the step.
+        const onItemLine = sentence !== undefined && !doc.source.slice(item.start, sentence.span.start).includes("\n");
+        return sentence?.tokens === undefined || !onItemLine ? [] : [{ start: sentence.span.start, kind: kindOf(sentence.tokens) }];
+      }),
+    )
+    .filter((steps) => steps.length >= MIN_STEPS);
+
+export const stepStatement: Detector = (doc, options): Finding[] =>
+  stepLists(doc).flatMap((steps) => {
+    const statements = steps.filter((step) => step.kind === "statement");
+    const instructions = steps.filter((step) => step.kind === "instruction");
+    // A procedure is a list most of whose steps are instructions; a numbered list of terms and definitions is not one.
+    const isProcedure = instructions.length * 2 > steps.length;
+    return isProcedure && statements.length > 0 && statements.length < instructions.length && statements.length <= options.limit
+      ? statements.map((step) => finding(doc, "step-statement-mix", step.start, { count: instructions.length }))
+      : [];
+  });

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