@jpeakai/prose-gates 0.1.1 → 0.2.0

package/src/cli.ts

@@ -3,13 +3,20 @@
 
 import { readFile, writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
-import { checkModel, DEFAULT_MAX_WORDS } from "./check.ts";
-import { fixMarkdown } from "./fix/engine.ts";
+import { checkModel } from "./check.ts";
+import { FlagError, ProseGatesError, UsageError } from "./errors.ts";
+import { fixMarkdownReport } from "./fix/engine.ts";
 import { buildDocModel } from "./model.ts";
+import type { PluginFailure } from "./plugins/index.ts";
+import { setUp } from "./project.ts";
 import { RULES } from "./rules/index.ts";
+import type { LoadedSource, Registry } from "./rules/registry.ts";
 import { CATEGORIES } from "./rules/types.ts";
 
-const USAGE = `usage: prose-gates <file.md> [...more] [--fix] [--json] [--max-words N]
+const USAGE = `usage: prose-gates <file.md> [...more] [--fix] [--json] [--max-words N] [--config FILE]
+                   [--no-plugins | --lenient-plugins]
+       prose-gates --list-rules
+       prose-gates --validate-plugins [--json] [--config FILE]
 
 Deterministic prose gates (* = autofixable):
 ${CATEGORIES.map((c) =>
@@ -25,58 +32,220 @@ markdown templates and their body is audited recursively (check-only).
 
 --fix applies every fix it can prove safe, then reports what remains.
 A fixer that is unsure leaves the text alone and the finding stays.
-Exits 1 when findings remain, 2 on usage error.`;
+--config FILE reads that config instead of prose-gates.config.json or .mjs at the project root.
+Plugins load on their own from .prose-gates/rules and from dependencies named prose-gates-plugin-*.
+--no-plugins runs the built-in rules only, for a baseline or a repo you do not trust.
+--lenient-plugins skips a plugin that fails to load and says so, instead of stopping the run.
+--validate-plugins loads and checks every plugin, reports every failure, and runs no check or fix.
+--list-rules prints every active rule by category, including plugin rules, and where each plugin came from.
+Exits 1 when findings remain or a plugin fails to load, 2 on usage error.`;
 
-export const main = async (argv: string[] = process.argv.slice(2)): Promise<number> => {
-  let values: { fix?: boolean; json?: boolean; help?: boolean; "max-words"?: string };
-  let positionals: string[];
+interface Parsed {
+  values: {
+    fix?: boolean;
+    json?: boolean;
+    help?: boolean;
+    "max-words"?: string;
+    config?: string;
+    "no-plugins"?: boolean;
+    "lenient-plugins"?: boolean;
+    "validate-plugins"?: boolean;
+    "list-rules"?: boolean;
+  };
+  positionals: string[];
+}
+
+const parse = (argv: string[]): Parsed =>
+  parseArgs({
+    args: argv,
+    options: {
+      fix: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      "max-words": { type: "string" },
+      config: { type: "string" },
+      "no-plugins": { type: "boolean", default: false },
+      "lenient-plugins": { type: "boolean", default: false },
+      "validate-plugins": { type: "boolean", default: false },
+      "list-rules": { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+const plural = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+const namesOf = (sources: LoadedSource[]): string =>
+  sources.map((s) => `${s.namespace} (${plural(s.rules.length, "rule")})`).join(", ");
+
+// The one line every run prints about third-party code, because loading it is
+// automatic. It says what ran, or what was skipped, and prints nothing when the
+// project has no plugins.
+export const loadedLine = (sources: LoadedSource[], skipped: string[]): string | null => {
+  if (skipped.length > 0) return `prose-gates: plugins off; skipped ${skipped.join(", ")}`;
+  if (sources.length === 0) return null;
+  return `prose-gates: loaded ${namesOf(sources)}`;
+};
+
+// One line for each plugin a lenient run left out, with the named reason, and
+// one for each config setting dropped because its plugin did not load.
+export const skippedLines = (failures: PluginFailure[], ignored: string[]): string[] => [
+  ...failures.map((f) => `prose-gates: skipped plugin ${f.source} [${f.error.code}]: ${reasonOf(f)}`),
+  ...ignored.map((id) => `prose-gates: ignored config setting for ${id}, whose plugin did not load`),
+];
+
+// The reason without the "plugin <source>:" the error message begins with.
+const reasonOf = (f: PluginFailure): string => f.error.message.replace(`plugin ${f.source}: `, "");
+
+// Every active rule under its category, then where each plugin came from.
+// Built-in categories come first, in their fixed order, then plugin ones.
+export const listRules = (registry: Registry): string => {
+  const lines: string[] = [];
+  for (const [category, description] of registry.categories) {
+    const rules = registry.rules.filter((r) => r.category === category);
+    if (rules.length === 0) continue;
+    lines.push(`${category}: ${description}`);
+    for (const r of rules) lines.push(`  ${r.id}${r.fix ? "*" : " "} ${r.summary}`);
+  }
+  if (registry.sources.length > 0) {
+    lines.push("", "plugins:");
+    for (const s of registry.sources) lines.push(`  ${s.namespace} (${s.kind}) ${s.spec}`);
+  }
+  return lines.join("\n");
+};
+
+// The result of --validate-plugins: what loaded, every failure, and the exit
+// code. Nothing here runs a check or a fix.
+const validate = (
+  registry: Registry,
+  failures: PluginFailure[],
+  json: boolean,
+): { code: number; stdout: string | null; stderr: string[] } => {
+  const sources = registry.sources.map((s) => ({ ...s }));
+  const failed = failures.map((f) => ({ source: f.source, kind: f.kind, code: f.error.code, message: reasonOf(f) }));
+  const code = failures.length > 0 ? 1 : 0;
+  if (json)
+    return {
+      code,
+      stdout: JSON.stringify({ valid: code === 0, plugins: sources, failures: failed }, null, 2),
+      stderr: [],
+    };
+  if (failures.length > 0) {
+    const total = failures.length + sources.length;
+    return {
+      code,
+      stdout: null,
+      stderr: [
+        `prose-gates: plugin validation failed, ${failures.length} of ${plural(total, "source")}`,
+        ...failed.map((f) => `  [${f.code}] ${f.source}: ${f.message}`),
+      ],
+    };
+  }
+  const line =
+    sources.length === 0 ? "prose-gates: no plugins found" : `prose-gates: plugins valid: ${namesOf(registry.sources)}`;
+  return { code, stdout: line, stderr: [] };
+};
+
+const run = async (argv: string[], cwd: string): Promise<number> => {
+  let parsed: Parsed;
   try {
-    ({ values, positionals } = parseArgs({
-      args: argv,
-      options: {
-        fix: { type: "boolean", default: false },
-        json: { type: "boolean", default: false },
-        help: { type: "boolean", short: "h", default: false },
-        "max-words": { type: "string" },
-      },
-      allowPositionals: true,
-      strict: true,
-    }));
+    parsed = parse(argv);
   } catch (err) {
-    console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
-    console.error(USAGE);
-    return 2;
+    throw new FlagError("argv", err instanceof Error ? err.message : String(err));
   }
+  const { values, positionals } = parsed;
   if (values.help) {
     console.log(USAGE);
     return 0;
   }
-  const maxWords = values["max-words"] === undefined ? DEFAULT_MAX_WORDS : Number(values["max-words"]);
-  if (positionals.length === 0 || Number.isNaN(maxWords) || maxWords < 1) {
-    console.error(USAGE);
-    return 2;
+  // Absent means the rule's own option, then the default. Present is a flag
+  // that wins for this run.
+  const maxWords = values["max-words"] === undefined ? undefined : Number(values["max-words"]);
+  const listing = values["list-rules"];
+  const validating = values["validate-plugins"];
+  if (maxWords !== undefined && (Number.isNaN(maxWords) || maxWords < 1)) {
+    throw new FlagError("--max-words", `--max-words must be a number of at least 1, not "${values["max-words"]}"`);
+  }
+  if (values["no-plugins"] && values["lenient-plugins"]) {
+    throw new FlagError("--lenient-plugins", "--no-plugins and --lenient-plugins contradict each other");
+  }
+  if (validating && (values["no-plugins"] || values.fix || listing)) {
+    throw new FlagError("--validate-plugins", "--validate-plugins takes no --no-plugins, --fix or --list-rules");
   }
+  if (validating && positionals.length > 0) {
+    throw new FlagError("files", "--validate-plugins runs no check, so it takes no files");
+  }
+  if (positionals.length === 0 && !listing && !validating) throw new FlagError("files", "no files given");
+
+  const { registry, skipped, failures } = await setUp({
+    cwd,
+    configPath: values.config,
+    noPlugins: values["no-plugins"],
+    lenient: values["lenient-plugins"],
+    collect: validating,
+  });
 
+  if (validating) {
+    const result = validate(registry, failures, Boolean(values.json));
+    for (const line of result.stderr) console.error(line);
+    if (result.stdout) console.log(result.stdout);
+    return result.code;
+  }
+
+  const note = loadedLine(registry.sources, skipped);
+  if (note) console.error(note);
+  for (const line of skippedLines(failures, registry.ignoredSettings)) console.error(line);
+  if (listing) {
+    console.log(listRules(registry));
+    return 0;
+  }
   const perFile = await Promise.all(
     positionals.map(async (file) => {
       let src = await readFile(file, "utf8");
       if (values.fix) {
-        const fixed = fixMarkdown(src);
+        const fixed = (await fixMarkdownReport(src, registry)).output;
         if (fixed !== src) {
           await writeFile(file, fixed);
           src = fixed;
         }
       }
-      return checkModel(buildDocModel(src), file, maxWords);
+      return await checkModel(buildDocModel(src), file, maxWords, registry);
     }),
   );
   const all = perFile.flat();
 
   if (values.json) {
-    console.log(JSON.stringify({ findings: all, files: positionals.length }, null, 2));
+    const skippedPlugins = failures.map((f) => ({
+      source: f.source,
+      kind: f.kind,
+      code: f.error.code,
+      message: reasonOf(f),
+    }));
+    console.log(
+      JSON.stringify({ findings: all, files: positionals.length, plugins: registry.sources, skippedPlugins }, null, 2),
+    );
   } else {
     for (const f of all) console.log(`${f.file}:${f.line} ${f.rule} ${f.message}`);
     console.log(`${all.length} finding(s) in ${positionals.length} file(s)`);
   }
   return all.length > 0 ? 1 : 0;
 };
+
+// The line printed for a failure: its stable code, then the reason.
+export const describeError = (err: unknown): string =>
+  err instanceof ProseGatesError
+    ? `error[${err.code}]: ${err.message}`
+    : `error: ${err instanceof Error ? err.message : String(err)}`;
+
+// A usage error prints its reason and the usage, and exits 2. Anything else is
+// a runtime failure and propagates to bin.ts, which exits 1.
+export const main = async (argv: string[] = process.argv.slice(2), cwd: string = process.cwd()): Promise<number> => {
+  try {
+    return await run(argv, cwd);
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err;
+    console.error(describeError(err));
+    console.error(USAGE);
+    return 2;
+  }
+};

package/src/config.ts

@@ -0,0 +1,119 @@
+// The config file: which rules are off, what options each takes, and how
+// strictly plugins load. It is optional, because everything auto-detected loads
+// without it. A mistake in it is a named usage error, so a stale or misspelt
+// rule id fails the run instead of silently doing nothing.
+
+import { access, readFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { AmbiguousConfigError, ConfigFileError, ConfigShapeError, RuleSettingError, UsageError } from "./errors.ts";
+import type { RuleOptions } from "./rules/types.ts";
+
+export { UsageError };
+
+export type Severity = "error" | "off";
+
+// How a plugin that fails to load is treated. Strict stops the run. Lenient
+// skips that plugin, says so, and carries on with the rest.
+export type PluginLoading = "strict" | "lenient";
+
+export interface RuleSetting {
+  severity: Severity;
+  options: RuleOptions;
+}
+
+export interface Config {
+  // Extra plugin paths or package names beyond what is auto-detected, or
+  // `false` for a built-ins-only run.
+  plugins: string[] | false;
+  pluginLoading: PluginLoading;
+  rules: Map<string, RuleSetting>;
+  // The file it came from, for messages. Null when there is no config.
+  file: string | null;
+}
+
+export const NO_CONFIG: Config = { plugins: [], pluginLoading: "strict", rules: new Map(), file: null };
+
+export const CONFIG_FILES = ["prose-gates.config.json", "prose-gates.config.mjs"] as const;
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+const parseSetting = (file: string, id: string, raw: unknown): RuleSetting => {
+  const [severity, options = {}] = Array.isArray(raw) ? raw : [raw];
+  if (Array.isArray(raw) && (raw.length < 1 || raw.length > 2)) {
+    throw new RuleSettingError(file, id, 'must be "error", "off" or [severity, options]');
+  }
+  if (severity !== "error" && severity !== "off") {
+    throw new RuleSettingError(file, id, `has severity ${JSON.stringify(severity)}; use "error" or "off"`);
+  }
+  if (!isRecord(options)) throw new RuleSettingError(file, id, "options must be an object");
+  return { severity, options };
+};
+
+export const parseConfig = (file: string, raw: unknown): Config => {
+  if (!isRecord(raw)) throw new ConfigShapeError(file, "the config must be an object");
+  for (const key of Object.keys(raw)) {
+    if (key !== "plugins" && key !== "pluginLoading" && key !== "rules") {
+      throw new ConfigShapeError(
+        file,
+        `unknown key "${key}"; a config has "plugins", "pluginLoading" and "rules"`,
+        key,
+      );
+    }
+  }
+  const { plugins = [], pluginLoading = "strict", rules = {} } = raw;
+  const validPlugins = plugins === false || (Array.isArray(plugins) && plugins.every((p) => typeof p === "string"));
+  if (!validPlugins) throw new ConfigShapeError(file, '"plugins" must be a list of strings, or false', "plugins");
+  if (pluginLoading !== "strict" && pluginLoading !== "lenient") {
+    throw new ConfigShapeError(file, '"pluginLoading" must be "strict" or "lenient"', "pluginLoading");
+  }
+  if (!isRecord(rules)) throw new ConfigShapeError(file, '"rules" must be an object', "rules");
+  return {
+    plugins: plugins as string[] | false,
+    pluginLoading,
+    rules: new Map(Object.entries(rules).map(([id, value]) => [id, parseSetting(file, id, value)])),
+    file,
+  };
+};
+
+// The first config file at the root, or null. Two at once is ambiguous, so it
+// is an error rather than a pick.
+export const findConfig = async (root: string): Promise<string | null> => {
+  const found: string[] = [];
+  for (const name of CONFIG_FILES) {
+    const path = join(root, name);
+    if (
+      await access(path).then(
+        () => true,
+        () => false,
+      )
+    )
+      found.push(path);
+  }
+  if (found.length > 1) throw new AmbiguousConfigError(root, found);
+  return found[0] ?? null;
+};
+
+const reason = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+export const loadConfig = async (file: string): Promise<Config> => {
+  if (extname(file) === ".json") {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(await readFile(file, "utf8"));
+    } catch (err) {
+      throw new ConfigFileError(file, reason(err));
+    }
+    return parseConfig(file, raw);
+  }
+  if (extname(file) === ".mjs") {
+    let mod: { default?: unknown };
+    try {
+      mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
+    } catch (err) {
+      throw new ConfigFileError(file, `could not be imported: ${reason(err)}`);
+    }
+    return parseConfig(file, mod.default);
+  }
+  throw new ConfigFileError(file, "a config is a .json or .mjs file");
+};

package/src/errors.ts

@@ -0,0 +1,191 @@
+// Every way a run can fail on purpose, as a class that says what went wrong.
+// A usage error is the caller's to fix and exits 2. A plugin error exits 1.
+// Each class carries a stable `code` and the fields a tool needs to act on it,
+// so a wrapper can branch on the type instead of reading the message.
+
+export class ProseGatesError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    this.name = new.target.name;
+  }
+}
+
+// --- usage: the invocation or the config is wrong -------------------------
+
+export class UsageError extends ProseGatesError {
+  constructor(message: string, code = "usage") {
+    super(code, message);
+  }
+}
+
+// A flag that is missing or has a value it cannot take.
+export class FlagError extends UsageError {
+  readonly flag: string;
+
+  constructor(flag: string, message: string) {
+    super(message, "flag");
+    this.flag = flag;
+  }
+}
+
+// A config file that cannot be read or parsed, or is the wrong kind of file.
+export class ConfigFileError extends UsageError {
+  readonly file: string;
+
+  constructor(file: string, message: string) {
+    super(`${file}: ${message}`, "config-file");
+    this.file = file;
+  }
+}
+
+// --config named a file that is not there.
+export class ConfigNotFoundError extends UsageError {
+  readonly path: string;
+
+  constructor(path: string) {
+    super(`--config ${path}: no such file`, "config-not-found");
+    this.path = path;
+  }
+}
+
+// Two config files at one root, so neither can be picked.
+export class AmbiguousConfigError extends UsageError {
+  readonly files: string[];
+
+  constructor(root: string, files: string[]) {
+    super(`more than one config file at ${root}: ${files.join(", ")}`, "config-ambiguous");
+    this.files = files;
+  }
+}
+
+// The config parsed, but its top-level shape is wrong.
+export class ConfigShapeError extends UsageError {
+  readonly file: string;
+  readonly key: string | null;
+
+  constructor(file: string, message: string, key: string | null = null) {
+    super(`${file}: ${message}`, "config-shape");
+    this.file = file;
+    this.key = key;
+  }
+}
+
+// One rule's setting is not a severity, or a severity and options.
+export class RuleSettingError extends UsageError {
+  readonly file: string;
+  readonly rule: string;
+
+  constructor(file: string, rule: string, message: string) {
+    super(`${file}: rule "${rule}" ${message}`, "rule-setting");
+    this.file = file;
+    this.rule = rule;
+  }
+}
+
+// The config names a rule that is not loaded, which also catches a retired id.
+export class UnknownRuleError extends UsageError {
+  readonly file: string;
+  readonly rule: string;
+  readonly known: string[];
+
+  constructor(file: string, rule: string, known: string[]) {
+    super(
+      `${file}: unknown rule "${rule}"; a retired or misspelt id cannot be switched off. Known rules: ${known.join(", ")}`,
+      "unknown-rule",
+    );
+    this.file = file;
+    this.rule = rule;
+    this.known = known;
+  }
+}
+
+// A rule option the rule does not take, or a value of the wrong type or range.
+export class RuleOptionError extends UsageError {
+  readonly file: string;
+  readonly rule: string;
+  readonly option: string;
+
+  constructor(file: string, rule: string, option: string, message: string) {
+    super(`${file}: ${message}`, "rule-option");
+    this.file = file;
+    this.rule = rule;
+    this.option = option;
+  }
+}
+
+// --- plugins: a source could not be loaded --------------------------------
+
+// A source that failed to load. `source` is what the user would recognise, a
+// package name or a path under the project root.
+export class PluginLoadError extends ProseGatesError {
+  readonly source: string;
+
+  constructor(source: string, reason: string, code = "plugin") {
+    super(code, `plugin ${source}: ${reason}`);
+    this.source = source;
+  }
+}
+
+// The module threw, or could not be found, when it was imported.
+export class PluginImportError extends PluginLoadError {
+  constructor(source: string, reason: string) {
+    super(source, `could not be imported: ${reason}`, "plugin-import");
+  }
+}
+
+// The module loaded but does not meet the contract: shape, version, namespace,
+// category, or a rule's declaration.
+export class PluginContractError extends PluginLoadError {
+  constructor(source: string, reason: string) {
+    super(source, reason, "plugin-contract");
+  }
+}
+
+// Two plugins claim one namespace or one new category.
+export class PluginConflictError extends PluginLoadError {
+  readonly other: string;
+
+  constructor(source: string, other: string, reason: string) {
+    super(source, reason, "plugin-conflict");
+    this.other = other;
+  }
+}
+
+// A dependency the project declares, or a config lists, that is not installed.
+export class PluginNotInstalledError extends PluginLoadError {
+  readonly root: string;
+
+  constructor(source: string, root: string) {
+    super(
+      source,
+      `is declared or listed but not installed; looked from ${root} upward. Install it, or remove it`,
+      "plugin-not-installed",
+    );
+    this.root = root;
+  }
+}
+
+// A file the loader cannot read in this runtime, such as TypeScript on a
+// runtime that cannot strip types.
+export class PluginSourceError extends PluginLoadError {
+  constructor(source: string, reason: string) {
+    super(source, reason, "plugin-source");
+  }
+}
+
+// --- plugins: a loaded plugin misbehaved while running --------------------
+
+// A fixer threw or returned something that is not a list of valid edits.
+// Unlike a check, this stops the run, because carrying on after a corrupt edit
+// is worse than stopping.
+export class PluginFixerError extends ProseGatesError {
+  readonly rule: string;
+
+  constructor(rule: string, reason: string) {
+    super("plugin-fixer", `plugin rule ${rule} ${reason}`);
+    this.rule = rule;
+  }
+}

package/src/fix/engine.ts

@@ -4,7 +4,7 @@
 // source they were computed from, so every accepted edit restarts the pass.
 
 import { buildDocModel, parse } from "../model.ts";
-import { FIX_ORDER } from "../rules/index.ts";
+import { BUILTIN, type Registry, ruleContext, TEXT_HELPERS } from "../rules/registry.ts";
 import type { Edit } from "../rules/types.ts";
 import { verify } from "./verify.ts";
 
@@ -27,7 +27,17 @@ const overlaps = (edits: Edit[]): boolean => {
   return sorted.some((e, i) => i > 0 && e.start < (sorted[i - 1] as Edit).end);
 };
 
-export const fixMarkdownReport = (src: string): FixReport => {
+// Offsets are whole numbers inside the source, in order, and the replacement
+// is text. Anything else is a malformed edit from a fixer that miscounted.
+const wellFormed = (e: Edit, length: number): boolean =>
+  Number.isInteger(e.start) &&
+  Number.isInteger(e.end) &&
+  e.start >= 0 &&
+  e.start <= e.end &&
+  e.end <= length &&
+  typeof e.text === "string";
+
+export const fixMarkdownReport = async (src: string, registry: Registry = BUILTIN): Promise<FixReport> => {
   const applied: Edit[] = [];
   const refused: Edit[] = [];
   // An edit refused once stays refused while its source slice is unchanged.
@@ -35,8 +45,8 @@ export const fixMarkdownReport = (src: string): FixReport => {
   let current = src;
 
   for (let pass = 0; pass < MAX_PASSES; pass++) {
-    const doc = buildDocModel(current);
-    const before = { src: current, tree: doc.tree };
+    const ctx = ruleContext(buildDocModel(current), registry);
+    const before = { src: current, tree: ctx.doc.tree };
     const keyOf = (e: Edit): string => `${e.rule}\u0000${current.slice(e.start, e.end)}\u0000${e.text}`;
 
     const attempt = (edits: Edit[]): boolean => {
@@ -51,10 +61,21 @@ export const fixMarkdownReport = (src: string): FixReport => {
     };
 
     let progressed = false;
-    for (const rule of FIX_ORDER) {
-      const edits = (rule.fix?.(doc) ?? []).filter(
-        (e) => current.slice(e.start, e.end) !== e.text && !refusedKeys.has(keyOf(e)),
-      );
+    for (const rule of registry.fixOrder) {
+      const proposed =
+        (await rule.fix?.({ ...ctx, options: registry.options.get(rule.id) ?? {}, helpers: TEXT_HELPERS })) ?? [];
+      // An edit that points outside the source cannot be proven, so it is
+      // refused before it is ever spliced. A built-in never proposes one.
+      const sound = proposed.filter((e) => {
+        if (wellFormed(e, current.length)) return true;
+        const key = `${e.rule}\u0000malformed\u0000${e.start}:${e.end}`;
+        if (!refusedKeys.has(key)) {
+          refusedKeys.add(key);
+          refused.push(e);
+        }
+        return false;
+      });
+      const edits = sound.filter((e) => current.slice(e.start, e.end) !== e.text && !refusedKeys.has(keyOf(e)));
       if (edits.length === 0) continue;
 
       // Whitespace and glyph edits leave the tree's shape alone, so a rule's
@@ -81,4 +102,5 @@ export const fixMarkdownReport = (src: string): FixReport => {
   throw new Error(`fix did not converge after ${MAX_PASSES} passes; a fixer keeps proposing edits`);
 };
 
-export const fixMarkdown = (src: string): string => fixMarkdownReport(src).output;
+export const fixMarkdown = async (src: string, registry: Registry = BUILTIN): Promise<string> =>
+  (await fixMarkdownReport(src, registry)).output;

package/src/fix/promote.ts

@@ -3,9 +3,9 @@
 // markdown list. Item text is sliced from the source, never re-serialised,
 // so links, emphasis, escapes and code spans travel unchanged.
 
-import type { ParagraphView, Range } from "../model.ts";
+import type { ParagraphView } from "../model.ts";
 import type { Edit, RuleId } from "../rules/types.ts";
-import { collapse } from "./spans.ts";
+import { collapse, type Range, spansBetween } from "../text.ts";
 
 export interface PromotedItem {
   text: string;
@@ -46,6 +46,18 @@ export const cleanItem = (raw: string, { last }: { last: boolean }): string => {
   return s;
 };
 
+// A run of source spans as cleaned item text, ready to promote. Only the
+// last item may shed a joining conjunction or a trailing full stop, so the
+// spans must arrive in document order.
+export const itemsOf = (src: string, spans: Range[]): string[] =>
+  spans.map((span, i) => cleanItem(src.slice(span[0], span[1]), { last: i + 1 === spans.length }));
+
+// The spans between a run of cut points, as cleaned item text. This is the
+// shared body of every hidden-list fixer: the rule decides where the cuts
+// are, and this decides what each item says.
+export const itemsBetween = (src: string, cuts: Range[], end: number): string[] =>
+  itemsOf(src, spansBetween(cuts, end));
+
 export const cleanLeadIn = (raw: string): string | null => {
   const s = collapse(raw)
     .trim()