@jpeakai/prose-gates 0.1.1 → 0.2.0

package/src/plugins/load.ts

@@ -0,0 +1,234 @@
+// Loading: import a plugin module, check it has the shape the contract
+// promises, and turn its rules into ordinary Rules. Every failure is a named
+// PluginLoadError that says which source and why. These functions never skip
+// anything themselves: they return or throw, and the caller decides whether a
+// failed source stops the run (strict) or is reported and left out (lenient).
+
+import { basename, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  PluginConflictError,
+  PluginContractError,
+  PluginFixerError,
+  PluginImportError,
+  PluginLoadError,
+  PluginSourceError,
+} from "../errors.ts";
+import { BUILTIN_CATEGORIES } from "../rules/registry.ts";
+import type { Edit, Finding, OptionType, Rule, RuleId } from "../rules/types.ts";
+import { API_VERSION, CATEGORY_WORD, NAMESPACE, type Plugin, type PluginRule, RULE_KEY } from "./contract.ts";
+import type { PluginSource } from "./discover.ts";
+import { canImportTypeScript, type RuntimeInfo, TYPESCRIPT_HELP } from "./runtime.ts";
+
+export { PluginLoadError };
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+// TypeScript is imported as is, so it needs a runtime that can. CommonJS
+// TypeScript is never supported, because the loader imports modules.
+const checkRuntime = (source: PluginSource, runtime?: RuntimeInfo): void => {
+  const ext = extname(source.path);
+  if (ext === ".cts") {
+    throw new PluginSourceError(source.spec, "a local rule is an ES module, so use .ts or .mts, not .cts");
+  }
+  if ((ext === ".ts" || ext === ".mts") && !canImportTypeScript(runtime)) {
+    throw new PluginSourceError(source.spec, TYPESCRIPT_HELP);
+  }
+};
+
+const importModule = async (source: PluginSource, runtime?: RuntimeInfo): Promise<Record<string, unknown>> => {
+  checkRuntime(source, runtime);
+  try {
+    return (await import(pathToFileURL(source.path).href)) as Record<string, unknown>;
+  } catch (err) {
+    throw new PluginImportError(source.spec, message(err));
+  }
+};
+
+const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string[]"]);
+
+// Checks one rule's declaration and returns it, so a bad rule fails at load
+// rather than the first time it runs.
+const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
+  const where = `rule "${key}"`;
+  if (!isRecord(raw)) throw new PluginContractError(spec, `${where} must be an object`);
+  if (!RULE_KEY.test(key)) {
+    throw new PluginContractError(spec, `${where} is not a valid key; use lower-case words joined by hyphens`);
+  }
+  const { category, summary, options, check, fix } = raw;
+  if (typeof category !== "string" || !CATEGORY_WORD.test(category)) {
+    throw new PluginContractError(spec, `${where} needs a category of one lower-case word`);
+  }
+  if (!BUILTIN_CATEGORIES.has(category) && !own.has(category)) {
+    throw new PluginContractError(
+      spec,
+      `${where} uses the category "${category}", which this plugin does not declare in meta.categories`,
+    );
+  }
+  if (!key.startsWith(`${category}-`)) {
+    throw new PluginContractError(spec, `${where} must start with its category, as "${category}-short-name"`);
+  }
+  if (typeof summary !== "string" || summary === "") throw new PluginContractError(spec, `${where} needs a summary`);
+  if (typeof check !== "function") throw new PluginContractError(spec, `${where} needs a check function`);
+  if (fix !== undefined && typeof fix !== "function") {
+    throw new PluginContractError(spec, `${where} fix must be a function`);
+  }
+  if (options !== undefined) {
+    const valid = isRecord(options) && Object.values(options).every((t) => OPTION_TYPES.has(t as OptionType));
+    if (!valid) {
+      throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
+    }
+  }
+  return raw as unknown as PluginRule;
+};
+
+const checkCategories = (spec: string, raw: unknown): Record<string, string> => {
+  if (raw === undefined) return {};
+  if (!isRecord(raw)) throw new PluginContractError(spec, "categories must map a word to a description");
+  for (const [word, description] of Object.entries(raw)) {
+    if (!CATEGORY_WORD.test(word)) throw new PluginContractError(spec, `category "${word}" is not one lower-case word`);
+    if (BUILTIN_CATEGORIES.has(word)) {
+      throw new PluginContractError(spec, `category "${word}" is built in and cannot be declared`);
+    }
+    if (typeof description !== "string" || description === "") {
+      throw new PluginContractError(spec, `category "${word}" needs a one-line description`);
+    }
+  }
+  return raw as Record<string, string>;
+};
+
+// A plugin object is checked here, apart from how it was imported, so a test
+// can hold the same plugin to the same contract the loader does.
+export const parsePlugin = (spec: string, raw: unknown, reserved: ReadonlySet<string>): Plugin => {
+  if (!isRecord(raw) || !isRecord(raw.meta) || !isRecord(raw.rules)) {
+    throw new PluginContractError(spec, "the default export must be { meta, rules }");
+  }
+  const { name, namespace, apiVersion } = raw.meta;
+  if (apiVersion !== API_VERSION) {
+    throw new PluginContractError(
+      spec,
+      `targets plugin apiVersion ${JSON.stringify(apiVersion)}, but this prose-gates supports ${API_VERSION}`,
+    );
+  }
+  if (typeof name !== "string" || name === "") throw new PluginContractError(spec, "meta.name is required");
+  if (typeof namespace !== "string" || !NAMESPACE.test(namespace)) {
+    throw new PluginContractError(spec, "meta.namespace must be lower-case words joined by hyphens");
+  }
+  if (reserved.has(namespace)) throw new PluginContractError(spec, `meta.namespace "${namespace}" is reserved`);
+  const categories = checkCategories(spec, raw.meta.categories);
+  const own = new Set(Object.keys(categories));
+  const rules = Object.fromEntries(
+    Object.entries(raw.rules).map(([key, rule]) => [key, checkRule(spec, key, rule, own)]),
+  );
+  return { meta: { name, namespace, apiVersion, categories }, rules };
+};
+
+// A package: the default export is a Plugin.
+export const loadPackage = async (source: PluginSource, reserved: ReadonlySet<string>): Promise<Plugin> =>
+  parsePlugin(source.spec, (await importModule(source)).default, reserved);
+
+export interface LocalLoad {
+  // The local files that loaded, as one plugin. Null when none did.
+  plugin: Plugin | null;
+  failures: PluginLoadError[];
+}
+
+// Local files: each default-exports one rule, keyed by its file name. They load
+// as one plugin under the fixed namespace `local`, and a file may export
+// `categories` to declare the word its rule uses. Each file fails on its own,
+// so one bad file does not hide the others, and the caller gets every failure.
+export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo): Promise<LocalLoad> => {
+  const failures: PluginLoadError[] = [];
+  const fail = (err: unknown): void => {
+    if (!(err instanceof PluginLoadError)) throw err;
+    failures.push(err);
+  };
+  const categories: Record<string, string> = {};
+  const owner: Record<string, string> = {};
+  const loaded: { key: string; source: PluginSource; raw: unknown }[] = [];
+  for (const source of sources) {
+    try {
+      const mod = await importModule(source, runtime);
+      if (mod.default === undefined) {
+        throw new PluginContractError(source.spec, "has no default export; export one rule");
+      }
+      const declared = checkCategories(source.spec, mod.categories);
+      for (const [word, description] of Object.entries(declared)) {
+        if (categories[word] !== undefined && categories[word] !== description) {
+          throw new PluginConflictError(
+            source.spec,
+            owner[word] as string,
+            `declares category "${word}" with a different description than another local file`,
+          );
+        }
+        categories[word] = description;
+        owner[word] = source.spec;
+      }
+      loaded.push({ key: basename(source.path, extname(source.path)), source, raw: mod.default });
+    } catch (err) {
+      fail(err);
+    }
+  }
+  const own = new Set(Object.keys(categories));
+  const rules: Record<string, PluginRule> = {};
+  for (const { key, source, raw } of loaded) {
+    try {
+      rules[key] = checkRule(source.spec, key, raw, own);
+    } catch (err) {
+      fail(err);
+    }
+  }
+  const plugin: Plugin | null =
+    Object.keys(rules).length === 0 && failures.length > 0
+      ? null
+      : { meta: { name: "local", namespace: "local", apiVersion: API_VERSION, categories }, rules };
+  return { plugin, failures };
+};
+
+const validFinding = (f: unknown): f is { line: number; message: string } =>
+  isRecord(f) && Number.isInteger(f.line) && (f.line as number) >= 1 && typeof f.message === "string";
+
+const EXPECTATIONS = new Set(["same-tree", "same-shape", "same-frontmatter-data", "replace-paragraph"]);
+
+// A plugin rule becomes a Rule whose id is namespace/key. The plugin function may
+// be synchronous or return a promise, and the wrapper awaits it. Its check cannot
+// take the run down: a throw, a rejection or a malformed finding becomes a finding for that
+// rule, and the other rules carry on. Its fixer is held to the same proof as a
+// built-in, so a fixer that throws or returns nonsense stops the run loudly.
+export const toRule = (namespace: string, key: string, rule: PluginRule): Rule => {
+  const id = `${namespace}/${key}` as RuleId;
+  const check: Rule["check"] = async (ctx) => {
+    const report = (why: string): Finding[] => [{ file: ctx.file, line: 1, rule: id, message: `plugin rule ${why}` }];
+    let found: unknown;
+    try {
+      found = await rule.check(ctx);
+    } catch (err) {
+      return report(`threw: ${message(err)}`);
+    }
+    if (!Array.isArray(found) || !found.every(validFinding)) {
+      return report("returned something other than a list of { line, message } findings");
+    }
+    return found.map((f) => ({ file: ctx.file, line: f.line, rule: id, message: f.message }));
+  };
+  const fix: Rule["fix"] = rule.fix
+    ? async (ctx) => {
+        let edits: unknown;
+        try {
+          edits = await rule.fix?.(ctx);
+        } catch (err) {
+          throw new PluginFixerError(id, `fixer threw: ${message(err)}`);
+        }
+        if (!Array.isArray(edits))
+          throw new PluginFixerError(id, "fixer returned something other than a list of edits");
+        return edits.map((e: Edit) => {
+          if (!isRecord(e) || !isRecord(e.expect) || !EXPECTATIONS.has(e.expect.kind as string)) {
+            throw new PluginFixerError(id, "fixer returned an edit with no valid expectation");
+          }
+          return { ...e, rule: id };
+        });
+      }
+    : undefined;
+  return { id, category: rule.category, summary: rule.summary, options: rule.options, check, ...(fix ? { fix } : {}) };
+};

package/src/plugins/runtime.ts

@@ -0,0 +1,15 @@
+// What the running JavaScript can import. Bun runs TypeScript directly, and Node
+// strips types from 22.18 (earlier with a flag, and not at all before 22.6). A
+// local rule written in TypeScript therefore works under `bunx --bun` or a recent
+// Node, and anywhere else it fails with a message that says how to fix it.
+
+export interface RuntimeInfo {
+  versions: Record<string, string | undefined>;
+  features: Record<string, unknown>;
+}
+
+export const canImportTypeScript = (runtime: RuntimeInfo = process as unknown as RuntimeInfo): boolean =>
+  typeof runtime.versions.bun === "string" || Boolean(runtime.features.typescript);
+
+export const TYPESCRIPT_HELP =
+  "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/prose-gates), use Node 22.18 or newer, or write a .js or .mjs file";

package/src/project.ts

@@ -0,0 +1,81 @@
+// Setting up a run: find the project root, read its config, load the plugins,
+// and build the registry every check and fix in the run uses. This happens
+// once, before any file is read, so a bad config or plugin stops the run
+// before it touches a document.
+
+import { access } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_FILES, findConfig, loadConfig, NO_CONFIG } from "./config.ts";
+import { ConfigNotFoundError } from "./errors.ts";
+import { loadPlugins, type PluginFailure, type PluginMode } from "./plugins/index.ts";
+import { FIX_ORDER, RULES } from "./rules/index.ts";
+import { buildRegistry, type Registry } from "./rules/registry.ts";
+
+export const LOCAL_DIR = ".prose-gates";
+
+const exists = (path: string): Promise<boolean> =>
+  access(path).then(
+    () => true,
+    () => false,
+  );
+
+// The nearest ancestor of the working directory that marks a project: a
+// package.json, a config file or a .prose-gates directory. With none, the
+// working directory itself, so a loose folder of notes still works.
+export const findProjectRoot = async (cwd: string): Promise<string> => {
+  const markers = ["package.json", LOCAL_DIR, ...CONFIG_FILES];
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    for (const marker of markers) if (await exists(join(dir, marker))) return dir;
+    if (dirname(dir) === dir) return resolve(cwd);
+  }
+};
+
+export interface SetupOptions {
+  cwd: string;
+  configPath?: string;
+  // Built-ins only. Anything discovered is reported as skipped.
+  noPlugins?: boolean;
+  // Skip a plugin that fails to load and say so, instead of stopping the run.
+  lenient?: boolean;
+  // Load every plugin and report every failure, without stopping at the first.
+  collect?: boolean;
+}
+
+export interface Setup {
+  registry: Registry;
+  skipped: string[];
+  // Plugins left out because they failed. Empty unless the run was lenient or collecting.
+  failures: PluginFailure[];
+}
+
+export const setUp = async ({
+  cwd,
+  configPath,
+  noPlugins = false,
+  lenient = false,
+  collect = false,
+}: SetupOptions): Promise<Setup> => {
+  const root = await findProjectRoot(cwd);
+  let file: string | null;
+  if (configPath !== undefined) {
+    file = resolve(cwd, configPath);
+    if (!(await exists(file))) throw new ConfigNotFoundError(configPath);
+  } else {
+    file = await findConfig(root);
+  }
+  const config = file ? await loadConfig(file) : NO_CONFIG;
+  let mode: PluginMode = "strict";
+  if (noPlugins || config.plugins === false) mode = "off";
+  else if (collect) mode = "collect";
+  else if (lenient || config.pluginLoading === "lenient") mode = "lenient";
+  const plugins = await loadPlugins(root, config, mode);
+  const registry = buildRegistry({
+    rules: [...RULES, ...plugins.rules],
+    fixOrder: [...FIX_ORDER, ...plugins.rules.filter((r) => r.fix)],
+    categories: plugins.categories,
+    sources: plugins.sources,
+    config,
+    ignoreUnknownPluginIds: mode === "lenient" || mode === "collect",
+  });
+  return { registry, skipped: plugins.skipped, failures: plugins.failures };
+};

package/src/query.ts

@@ -0,0 +1,131 @@
+// Read-only questions about one document. Everything here takes the model, or
+// a view out of it, and answers where something is or what may be read; none
+// of it builds an edit. Both halves of a rule ask the same questions here, so
+// a check and its fix can never disagree about what the document holds.
+
+import type { DirectText, DocModel, ParagraphView, TextView } from "./model.ts";
+import { countOf, type Range, sentences, within } from "./text.ts";
+
+// --- what a rule may read -------------------------------------------------
+
+// Table cells are exempt by construction, so every rule that reads running
+// prose starts here rather than filtering for itself.
+export const proseParagraphs = (doc: DocModel): ParagraphView[] => doc.paragraphs.filter((view) => !view.inTable);
+
+// One sentence with the paragraph it came from, so a finding can name the
+// line without the rule tracking it through a nested loop.
+export interface ProseSentence {
+  view: ParagraphView;
+  sentence: string;
+}
+
+export const proseSentences = (doc: DocModel): ProseSentence[] =>
+  proseParagraphs(doc).flatMap((view) => sentences(view.prose).map((sentence) => ({ view, sentence })));
+
+// The prose text nodes holding a glyph. This is how a punctuation rule finds
+// what it reports, and it reads headings and list items as well as
+// paragraphs, because a stray glyph is wrong wherever it sits.
+export const textsContaining = (doc: DocModel, glyph: string): TextView[] =>
+  doc.texts.filter((text) => text.value.includes(glyph));
+
+// --- where something sits in the source -----------------------------------
+
+// Absolute offsets of every match of `pattern` inside a text node, or null
+// when the source slice and the parsed value disagree (an entity like
+// `·` or an escape). A rule that cannot map a glyph back to the
+// source refuses rather than guesses.
+export const matchesIn = (src: string, text: DirectText, pattern: RegExp): Range[] | null => {
+  const slice = src.slice(text.start, text.end);
+  const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+  const inSlice = [...slice.matchAll(new RegExp(pattern.source, flags))];
+  const inValue = [...text.value.matchAll(new RegExp(pattern.source, flags))];
+  if (inSlice.length !== inValue.length) return null;
+  return inSlice.map((m) => [text.start + (m.index ?? 0), text.start + (m.index ?? 0) + m[0].length]);
+};
+
+export const matchesInAll = (src: string, texts: DirectText[], pattern: RegExp): Range[] | null => {
+  const out: Range[] = [];
+  for (const t of texts) {
+    const found = matchesIn(src, t, pattern);
+    if (found === null) return null;
+    out.push(...found);
+  }
+  return out;
+};
+
+// A glyph the author escaped is literal text, never a separator to rewrite.
+export const escaped = (src: string, offset: number): boolean => src[offset - 1] === "\\";
+
+// Every separator in a paragraph that a fixer may split on, or null when one
+// of them cannot be trusted. A separator is untrustworthy when the parsed
+// value and the source slice disagree (an entity like `·`), when the
+// author escaped it, or when it sits inside a link or emphasis rather than
+// direct text. Splitting on a subset would silently drop an item, so the
+// fixer refuses instead.
+export const splittableSeparators = (
+  src: string,
+  view: ParagraphView,
+  separator: RegExp,
+  glyph: RegExp,
+): Range[] | null => {
+  const found = matchesInAll(src, view.directTexts, separator);
+  if (found === null) return null;
+  if (found.length !== countOf(view.prose, glyph)) return null;
+  if (found.some(([start]) => escaped(src, start))) return null;
+  return found;
+};
+
+// --- sentences, as source offsets -----------------------------------------
+
+// Sentence boundaries a fixer trusts: a terminal followed by whitespace,
+// inside a direct text node. Terminals inside links, emphasis or code never
+// split a sentence. Each boundary is [end of terminal, start of next sentence].
+const boundaries = (src: string, view: ParagraphView): Range[] => {
+  const out: Range[] = [];
+  for (const t of view.directTexts) {
+    const slice = src.slice(t.start, t.end);
+    for (const m of slice.matchAll(/[.!?]+(\s+)/g)) {
+      const at = t.start + (m.index ?? 0);
+      out.push([at + m[0].length - (m[1]?.length ?? 0), at + m[0].length]);
+    }
+  }
+  return out.sort((a, b) => a[0] - b[0]);
+};
+
+// The sentence span that covers [from, to): from the start of the sentence
+// holding `from` to the end of the sentence holding `to`.
+export const sentenceSpan = (src: string, view: ParagraphView, from: number, to: number): Range => {
+  let start = view.startOffset;
+  let end = view.endOffset;
+  for (const [terminalEnd, nextStart] of boundaries(src, view)) {
+    if (nextStart <= from) start = nextStart;
+    if (terminalEnd >= to && end === view.endOffset) end = terminalEnd;
+  }
+  return [start, end];
+};
+
+// Every sentence span of a paragraph, in order.
+export const sentenceSpans = (src: string, view: ParagraphView): Range[] => {
+  const spans: Range[] = [];
+  let start = view.startOffset;
+  for (const [terminalEnd, nextStart] of boundaries(src, view)) {
+    spans.push([start, terminalEnd]);
+    start = nextStart;
+  }
+  spans.push([start, view.endOffset]);
+  return spans;
+};
+
+// --- lead-ins -------------------------------------------------------------
+
+// The colons of a paragraph as source ranges, or null when one of them
+// cannot be trusted. Every rule that promotes a list needs these to find the
+// lead-in that announces it.
+export const colonsIn = (src: string, view: ParagraphView): Range[] | null => matchesInAll(src, view.directTexts, /:/);
+
+// The colons that could announce a list: inside `range`, and closing before
+// the first item starts. Which one a rule takes is the only thing the list
+// rules disagree about, so they pick from this rather than each writing the
+// filter again.
+export const colonsBefore = (colons: Range[], range: Range, item: number): Range[] =>
+  colons.filter((colon) => within(colon, range) && colon[1] <= item);

package/src/rules/index.ts

@@ -2,20 +2,39 @@
 // a Rule with its category, register it here, and add its section and
 // examples to RULES.md, which tests/rules-doc.test.ts holds to the code.
 
-import { pg001 } from "./pg001-wrap.ts";
-import { pg002 } from "./pg002-length.ts";
-import { pg003 } from "./pg003-semicolon-list.ts";
-import { pg004 } from "./pg004-em-dash.ts";
-import { pg005 } from "./pg005-interpunct.ts";
-import { pg006 } from "./pg006-interpunct-run.ts";
-import { pg007 } from "./pg007-inline-enum.ts";
-import { pg008 } from "./pg008-labelled-run.ts";
-import { pg009 } from "./pg009-stacked-runs.ts";
+import { listCommaLabelledRun } from "./list-comma-labelled-run.ts";
+import { listInlineEnumerationMarkers } from "./list-inline-enumeration-markers.ts";
+import { listInterpunctJoinedRun } from "./list-interpunct-joined-run.ts";
+import { listSemicolonDelimitedRun } from "./list-semicolon-delimited-run.ts";
+import { listStackedInterpunctRuns } from "./list-stacked-interpunct-runs.ts";
+import { punctuationEmDashInProse } from "./punctuation-em-dash-in-prose.ts";
+import { punctuationInterpunctInProse } from "./punctuation-interpunct-in-prose.ts";
+import { sentenceOnePerLine } from "./sentence-one-per-line.ts";
+import { sentenceWordBudgetExceeded } from "./sentence-word-budget-exceeded.ts";
 import type { Rule } from "./types.ts";
 
-export const RULES: Rule[] = [pg001, pg002, pg003, pg004, pg005, pg006, pg007, pg008, pg009];
+export const RULES: Rule[] = [
+  sentenceOnePerLine,
+  sentenceWordBudgetExceeded,
+  listSemicolonDelimitedRun,
+  punctuationEmDashInProse,
+  punctuationInterpunctInProse,
+  listInterpunctJoinedRun,
+  listInlineEnumerationMarkers,
+  listCommaLabelledRun,
+  listStackedInterpunctRuns,
+];
 
 // The order fixers run in. Structure first: a promotion needs the separators
-// a glyph swap would erase, so PG009 and the list rules run before PG005
+// a glyph swap would erase, so list-stacked-interpunct-runs and the list rules run before punctuation-interpunct-in-prose
 // turns interpuncts into commas. Reflow runs last, over the settled blocks.
-export const FIX_ORDER: Rule[] = [pg009, pg007, pg008, pg006, pg003, pg005, pg004, pg001];
+export const FIX_ORDER: Rule[] = [
+  listStackedInterpunctRuns,
+  listInlineEnumerationMarkers,
+  listCommaLabelledRun,
+  listInterpunctJoinedRun,
+  listSemicolonDelimitedRun,
+  punctuationInterpunctInProse,
+  punctuationEmDashInProse,
+  sentenceOnePerLine,
+];

package/src/rules/list-comma-labelled-run.ts

@@ -0,0 +1,101 @@
+// list-comma-labelled-run: one sentence stringing 3+ comma-separated segments each led by a
+// label (an inline-code span, or an identifier like sentence-one-per-line / MD025 / S4)
+// WITH content after it is a hidden list of labelled items. Bare labels
+// ("A, B, and C are interchangeable") are a subject enumeration, not a
+// list. An optional "Rules: " style intro on the first segment, and a
+// joining "and"/"or", are tolerated.
+//
+// The check counts labelled segments; the fix is stricter and needs every
+// segment of the sentence to be one, so no stray clause becomes a bullet.
+
+import { cleanLeadIn, itemsOf, promote } from "../fix/promote.ts";
+import type { ParagraphView } from "../model.ts";
+import { colonsIn, matchesInAll, proseSentences, sentenceSpans } from "../query.ts";
+import { collapse, first, type Range, spansBetween, within } from "../text.ts";
+import { type Edit, RULE, type Rule } from "./types.ts";
+
+// A labelled segment, built from its parts so each one can be read on its
+// own: the conjunction that joins the final segment, an optional "Rules: "
+// intro on the first, the label itself, and the content that makes it an
+// item rather than a bare mention.
+const JOINER = "(?:and\\s+|or\\s+)?";
+const INTRO = "(?:[A-Za-z][\\w\\s-]{0,24}:\\s*)?";
+const LABEL = "(?:CODE|[A-Z][A-Za-z]*\\d[\\w/-]*)";
+const CONTENT = "\\s+\\S";
+const LABELLED_SEGMENT = new RegExp(`^${JOINER}${INTRO}${LABEL}${CONTENT}`);
+
+// The intro that may precede the first label, as the lead-in test reads it.
+const INTRO_ONLY = /^[A-Za-z][\w\s-]{0,24}$/;
+
+// A source slice as the check sees it: code spans become one CODE token.
+const asProse = (src: string, view: ParagraphView, range: Range): string => {
+  let out = "";
+  let at = range[0];
+  for (const [start, end] of view.codeRanges) {
+    if (end <= range[0] || start >= range[1]) continue;
+    out += `${src.slice(at, start)}CODE`;
+    at = end;
+  }
+  return collapse(out + src.slice(at, range[1])).trim();
+};
+
+const labelledSegments = (sentence: string): number =>
+  sentence.split(/,\s+/).filter((segment) => LABELLED_SEGMENT.test(segment)).length;
+
+const check: Rule["check"] = ({ doc, file }) =>
+  proseSentences(doc)
+    .map(({ view, sentence }) => ({ view, labelled: labelledSegments(sentence) }))
+    .filter(({ labelled }) => labelled >= 3)
+    .map(({ view, labelled }) => ({
+      file,
+      line: view.line,
+      rule: RULE.LABELLED_RUN,
+      message: `comma-joined run of ${labelled} labelled items; promote to a bullet list`,
+    }));
+
+const fix: Rule["fix"] = ({ doc }) => {
+  const { src } = doc;
+  const edits: Edit[] = [];
+  for (const view of doc.paragraphs) {
+    const commas = matchesInAll(src, view.directTexts, /,(?=\s)/);
+    const colons = colonsIn(src, view);
+    if (commas === null || colons === null) continue;
+    for (const span of sentenceSpans(src, view)) {
+      const inside = commas.filter((comma) => within(comma, span));
+      if (inside.length < 2) continue;
+      // The sentence start is the cut before the first segment, so the spans
+      // between the cuts are exactly the comma-separated segments.
+      const segments = spansBetween([[span[0], span[0]], ...inside], span[1]);
+      if (!segments.every((segment) => LABELLED_SEGMENT.test(asProse(src, view, segment)))) continue;
+
+      // An intro colon in the first segment, before its label, is the lead-in.
+      // The first item then starts after it, so the intro is not repeated as
+      // both the lead-in and the head of the first bullet.
+      const opening = first(segments);
+      const colon = colons.find((c) => within(c, opening));
+      const intro = colon !== undefined && INTRO_ONLY.test(collapse(src.slice(span[0], colon[0])).trim());
+      const items: Range[] = intro && colon ? [[colon[1], opening[1]], ...segments.slice(1)] : segments;
+
+      const edit = promote({
+        rule: RULE.LABELLED_RUN,
+        src,
+        view,
+        span,
+        leadIn: intro && colon ? cleanLeadIn(src.slice(span[0], colon[0])) : null,
+        items: itemsOf(src, items).map((text) => ({ text })),
+        ordered: false,
+      });
+      if (edit) edits.push(edit);
+      break; // one promotion per paragraph; the engine re-parses and comes back
+    }
+  }
+  return edits;
+};
+
+export const listCommaLabelledRun: Rule = {
+  id: RULE.LABELLED_RUN,
+  category: "list",
+  summary: "comma-joined labelled run (3+ labelled segments)",
+  check,
+  fix,
+};