@jpeakai/prose-gates 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/prose-gates",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Deterministic prose gates for markdown documentation",
   "license": "MIT",

package/src/check.ts

@@ -2,14 +2,13 @@
 // embedded markdown fences as documents of their own.
 
 import { buildDocModel, type DocModel } from "./model.ts";
-import { RULES } from "./rules/index.ts";
-import { interpunctRuns } from "./rules/interpunct.ts";
+import { RULES, ruleContext } from "./rules/index.ts";
 import type { Finding } from "./rules/types.ts";
 
 export const DEFAULT_MAX_WORDS = 25;
 
 export const checkModel = (doc: DocModel, file: string, maxWords: number): Finding[] => {
-  const ctx = { doc, file, maxWords, runs: interpunctRuns(doc) };
+  const ctx = { ...ruleContext(doc), file, maxWords };
   const findings = RULES.flatMap((rule) => rule.check(ctx));
   // The fence body starts one line below the opening fence.
   for (const fence of doc.fences) {

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 { FIX_ORDER, ruleContext } from "../rules/index.ts";
 import type { Edit } from "../rules/types.ts";
 import { verify } from "./verify.ts";
 
@@ -35,8 +35,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));
+    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 => {
@@ -52,7 +52,7 @@ export const fixMarkdownReport = (src: string): FixReport => {
 
     let progressed = false;
     for (const rule of FIX_ORDER) {
-      const edits = (rule.fix?.(doc) ?? []).filter(
+      const edits = (rule.fix?.(ctx) ?? []).filter(
         (e) => current.slice(e.start, e.end) !== e.text && !refusedKeys.has(keyOf(e)),
       );
       if (edits.length === 0) continue;

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()

package/src/interpunct.ts

@@ -0,0 +1,48 @@
+// The interpunct run: the one piece of data derived from a whole document
+// that more than one rule reads. PG006 and PG009 report a run, PG005 stays
+// quiet inside one, and PG001 leaves a stacked one unreflowed, so it is
+// derived once per document and handed to every rule as data.
+
+import type { DocModel, ParagraphView } from "./model.ts";
+import { proseParagraphs } from "./query.ts";
+import { countOf, type Range } from "./text.ts";
+
+export const INTERPUNCT = "·";
+
+// The glyph on its own, for counting, and the glyph with the space a run
+// puts around it, for splitting. PG006 and PG009 both cut on the separator;
+// PG005 is stricter and needs space on both sides, so it keeps its own.
+export const GLYPH = /·/g;
+export const RUN_SEPARATOR = /[ \t]*·[ \t]*/;
+
+// A paragraph whose prose joins a run of items with 2+ interpunct separators.
+export interface InterpunctRun {
+  range: Range;
+  line: number;
+  separators: number;
+  lines: number; // source lines of the paragraph that carry a separator
+}
+
+export const interpunctRuns = (doc: DocModel): InterpunctRun[] => {
+  const runs: InterpunctRun[] = [];
+  for (const view of proseParagraphs(doc)) {
+    const separators = countOf(view.prose, GLYPH);
+    if (separators < 2) continue;
+    const lines = view.raw.split("\n").filter((line) => line.includes(INTERPUNCT)).length;
+    runs.push({ range: [view.startOffset, view.endOffset], line: view.line, separators, lines });
+  }
+  return runs;
+};
+
+// A run on one source line is a flat list, which PG006 owns. A run spread
+// over two or more lines is a two-level structure, which PG009 owns and
+// PG001 leaves unreflowed. The two predicates partition every run.
+export const isFlat = (run: InterpunctRun): boolean => run.lines === 1;
+
+export const isStacked = (run: InterpunctRun): boolean => run.lines >= 2;
+
+// The paragraphs those runs were derived from. A run is keyed by the
+// paragraph it spans, so this is how a rule gets from the runs it was handed
+// back to the views its fixer needs.
+export const paragraphsOf = (doc: DocModel, runs: InterpunctRun[]): ParagraphView[] =>
+  doc.paragraphs.filter((view) => runs.some((run) => run.range[0] === view.startOffset));

package/src/model.ts

@@ -9,6 +9,7 @@ import { gfmFromMarkdown } from "mdast-util-gfm";
 import { frontmatter } from "micromark-extension-frontmatter";
 import { gfm } from "micromark-extension-gfm";
 import { visitParents } from "unist-util-visit-parents";
+import type { Range } from "./text.ts";
 
 // Fenced blocks in these languages hold markdown templates (a conventions or
 // skeleton file shown verbatim): their prose is audited as embedded markdown
@@ -16,8 +17,6 @@ import { visitParents } from "unist-util-visit-parents";
 // fence boundary.
 const MARKDOWN_FENCE_LANGS = new Set(["markdown", "md"]);
 
-export type Range = [number, number];
-
 // A text node that is a direct child of its paragraph. Only these carry
 // separators a fixer may split on: text inside a link, emphasis or code is
 // cargo and moves whole.
@@ -48,7 +47,6 @@ export interface ParagraphView {
 export interface TextView {
   value: string;
   line: number;
-  offset: number | undefined;
   start: number | undefined;
   end: number | undefined;
   block: Node | undefined; // nearest paragraph, heading or table cell
@@ -128,7 +126,6 @@ export const buildDocModel = (src: string): DocModel => {
       texts.push({
         value: t.value,
         line: t.position?.start.line ?? 0,
-        offset: start,
         start,
         end,
         block: ancestors.findLast((a) => a.type === "paragraph" || a.type === "heading" || a.type === "tableCell"),
@@ -154,12 +151,3 @@ export const buildDocModel = (src: string): DocModel => {
   }
   return { src, tree, paragraphs, texts, fences };
 };
-
-export const inRanges = (offset: number, ranges: Range[]): boolean =>
-  ranges.some(([a, b]) => offset >= a && offset < b);
-
-export const sentences = (text: string): string[] =>
-  text
-    .split(/(?<=[.!?])\s+/)
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);

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,6 +2,8 @@
 // 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 { interpunctRuns } from "../interpunct.ts";
+import type { DocModel } from "../model.ts";
 import { pg001 } from "./pg001-wrap.ts";
 import { pg002 } from "./pg002-length.ts";
 import { pg003 } from "./pg003-semicolon-list.ts";
@@ -11,10 +13,15 @@ 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 type { Rule } from "./types.ts";
+import type { Rule, RuleContext } from "./types.ts";
 
 export const RULES: Rule[] = [pg001, pg002, pg003, pg004, pg005, pg006, pg007, pg008, pg009];
 
+// The data every rule shares, derived once per document. Interpunct runs are
+// read by four rules, so computing them here keeps the fix engine from
+// rebuilding them once per rule on every pass of the fixpoint loop.
+export const ruleContext = (doc: DocModel): RuleContext => ({ doc, runs: interpunctRuns(doc) });
+
 // 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
 // turns interpuncts into commas. Reflow runs last, over the settled blocks.

package/src/rules/pg001-wrap.ts

@@ -2,70 +2,90 @@
 // does not end a sentence is a mid-sentence wrap. The fix reflows the
 // paragraph to one sentence per line.
 
-import { type DocModel, inRanges } from "../model.ts";
-import { interpunctRuns } from "./interpunct.ts";
-import { type Edit, type Finding, RULE, type Rule } from "./types.ts";
+import { isStacked, paragraphsOf } from "../interpunct.ts";
+import type { ParagraphView } from "../model.ts";
+import { proseParagraphs } from "../query.ts";
+import { collapse, inRanges } from "../text.ts";
+import { type Edit, RULE, type Rule } from "./types.ts";
 
+// A line break after one of these ends a sentence, so it is authored layout.
 const TERMINALS = new Set([".", "!", "?", ":", ";"]);
 
-const check: Rule["check"] = ({ doc, file }) => {
-  const findings: Finding[] = [];
-  for (const p of doc.paragraphs) {
-    if (p.inTable) continue;
-    for (let i = 0; i < p.raw.length; i++) {
-      if (p.raw[i] !== "\n") continue;
-      if (inRanges(p.startOffset + i, p.codeRanges)) continue;
-      let j = i - 1;
-      while (j >= 0 && (p.raw[j] === " " || p.raw[j] === "\t" || p.raw[j] === "\r" || p.raw[j] === "\\")) j--;
-      if (j >= 0 && !TERMINALS.has(p.raw[j] as string)) {
-        const line = p.line + p.raw.slice(0, i).split("\n").length - 1;
-        findings.push({ file, line, rule: RULE.WRAP, message: "mid-sentence line wrap; write one sentence per line" });
-      }
-    }
+// What may sit between the terminal and the break: trailing space, a carriage
+// return, or the backslash form of a hard break.
+const TRAILING = new Set([" ", "\t", "\r", "\\"]);
+
+// A sentence ends at a terminal followed by space, and the next one opens with
+// a capital or an opening delimiter. Anything else is an abbreviation.
+const SENTENCE_BREAK = /[.!?]\s+(?=[A-Z`"'([])/g;
+
+// Offsets within the paragraph where a line break interrupts a sentence.
+const wrapsIn = (view: ParagraphView): number[] => {
+  const wraps: number[] = [];
+  for (let i = 0; i < view.raw.length; i++) {
+    if (view.raw[i] !== "\n") continue;
+    if (inRanges(view.startOffset + i, view.codeRanges)) continue;
+    let j = i - 1;
+    while (j >= 0 && TRAILING.has(view.raw.charAt(j))) j--;
+    if (j >= 0 && !TERMINALS.has(view.raw.charAt(j))) wraps.push(i);
   }
-  return findings;
+  return wraps;
 };
 
-const fix = (doc: DocModel): Edit[] => {
+// The paragraph rewritten with one sentence per line. Code spans are masked
+// character for character before the split, keeping whitespace, so offsets
+// stay aligned and a terminal inside a code span never starts a new line.
+const reflow = (view: ParagraphView): string => {
+  const indent = " ".repeat(view.startColumn - 1);
+  const eol = view.raw.includes("\r\n") ? "\r\n" : "\n";
+  const masked = [...view.raw]
+    .map((ch, i) => (inRanges(view.startOffset + i, view.codeRanges) && !/\s/.test(ch) ? "x" : ch))
+    .join("");
+  const joined = collapse(view.raw);
+  const joinedMask = collapse(masked);
+
+  const lines: string[] = [];
+  let from = 0;
+  for (const match of joinedMask.matchAll(SENTENCE_BREAK)) {
+    const at = match.index ?? 0;
+    lines.push(joined.slice(from, at + 1));
+    from = at + match[0].length;
+  }
+  lines.push(joined.slice(from));
+  return lines.map((line, i) => (i === 0 ? line.trim() : indent + line.trim())).join(eol);
+};
+
+const check: Rule["check"] = ({ doc, file }) =>
+  proseParagraphs(doc).flatMap((view) =>
+    wrapsIn(view).map((at) => ({
+      file,
+      line: view.line + view.raw.slice(0, at).split("\n").length - 1,
+      rule: RULE.WRAP,
+      message: "mid-sentence line wrap; write one sentence per line",
+    })),
+  );
+
+const fix: Rule["fix"] = ({ doc, runs }) => {
   const edits: Edit[] = [];
   // Interpunct runs stacked on several lines are a nested list PG009 either
   // promotes or leaves for a human. Joining the lines would destroy the
   // structure and hand PG006 a flat run it would merge wrongly.
-  const stacked = interpunctRuns(doc)
-    .filter((r) => r.lines >= 2)
-    .map((r) => r.range[0]);
-  for (const p of doc.paragraphs) {
+  const stacked = new Set(paragraphsOf(doc, runs.filter(isStacked)));
+  for (const view of proseParagraphs(doc)) {
     // A hard break is structure the author chose, so the paragraph is left
     // exactly as written.
-    if (p.inTable || p.inBlockquote || p.hasBreak || stacked.includes(p.startOffset)) continue;
-
-    // Continuation lines keep the paragraph's own indent column, and the
-    // paragraph's own line ending.
-    const indent = " ".repeat(p.startColumn - 1);
-    const eol = p.raw.includes("\r\n") ? "\r\n" : "\n";
-
-    // Mask code spans character for character, keeping whitespace, so the
-    // same join applies to both strings and offsets stay aligned. A terminal
-    // inside a code span then never splits a sentence.
-    const masked = [...p.raw]
-      .map((ch, i) => (inRanges(p.startOffset + i, p.codeRanges) && !/\s/.test(ch) ? "x" : ch))
-      .join("");
-    const join = (s: string): string => s.replace(/[ \t]*\r?\n[ \t]*/g, " ");
-    const joined = join(p.raw);
-    const joinedMask = join(masked);
+    if (view.inBlockquote || view.hasBreak) continue;
+    if (stacked.has(view)) continue;
 
-    const out: string[] = [];
-    let last = 0;
-    for (const m of joinedMask.matchAll(/[.!?]\s+(?=[A-Z`"'([])/g)) {
-      const at = m.index ?? 0;
-      out.push(joined.slice(last, at + 1));
-      last = at + m[0].length;
-    }
-    out.push(joined.slice(last));
-    const text = out.map((s, i) => (i === 0 ? s.trim() : indent + s.trim())).join(eol);
-    if (text !== p.raw) {
-      edits.push({ rule: RULE.WRAP, start: p.startOffset, end: p.endOffset, text, expect: { kind: "same-tree" } });
-    }
+    const text = reflow(view);
+    if (text === view.raw) continue;
+    edits.push({
+      rule: RULE.WRAP,
+      start: view.startOffset,
+      end: view.endOffset,
+      text,
+      expect: { kind: "same-tree" },
+    });
   }
   return edits;
 };

package/src/rules/pg002-length.ts

@@ -3,8 +3,9 @@
 // rewrite, and a rewrite needs discretion. The message estimates the clauses
 // in the sentence so the rewrite splits it rather than compressing it.
 
-import { sentences } from "../model.ts";
-import { type Finding, RULE, type Rule } from "./types.ts";
+import { proseSentences } from "../query.ts";
+import { words } from "../text.ts";
+import { RULE, type Rule } from "./types.ts";
 
 // A clause boundary is a semicolon or colon with text after it, a comma
 // before a coordinating conjunction, or a subordinating or relative word.
@@ -15,30 +16,30 @@ const CLAUSE_BOUNDARY =
 
 export const countClauses = (sentence: string): number => 1 + [...sentence.matchAll(CLAUSE_BOUNDARY)].length;
 
-const excerpt = (s: string): string => (s.length > 60 ? `${s.slice(0, 60)}...` : s);
+const excerpt = (sentence: string): string => (sentence.length > 60 ? `${sentence.slice(0, 60)}...` : sentence);
 
 export const lengthMessage = (sentence: string, maxWords: number): string => {
-  const words = sentence.split(/\s+/).length;
+  const count = words(sentence);
   const clauses = countClauses(sentence);
-  const target = Math.max(2, clauses, Math.ceil(words / maxWords));
+  const target = Math.max(2, clauses, Math.ceil(count / maxWords));
   const clauseNote = `${clauses} potential clause${clauses === 1 ? "" : "s"}`;
-  return `sentence has ${words} words (budget ${maxWords}) and ${clauseNote}; split it into about ${target} shorter sentences, one idea each, rather than compressing the wording: "${excerpt(sentence)}"`;
+  return `sentence has ${count} words (budget ${maxWords}) and ${clauseNote}; split it into about ${target} shorter sentences, one idea each, rather than compressing the wording: "${excerpt(sentence)}"`;
 };
 
+const check: Rule["check"] = ({ doc, file, maxWords }) =>
+  proseSentences(doc)
+    .filter(({ sentence }) => words(sentence) > maxWords)
+    .map(({ view, sentence }) => ({
+      file,
+      line: view.line,
+      rule: RULE.LENGTH,
+      message: lengthMessage(sentence, maxWords),
+    }));
+
+// No fixer: shortening a sentence changes its words, per PRS-0006.
 export const pg002: Rule = {
   id: RULE.LENGTH,
   category: "sentence",
   summary: "sentence longer than the word budget (default 25)",
-  check: ({ doc, file, maxWords }) => {
-    const findings: Finding[] = [];
-    for (const p of doc.paragraphs) {
-      if (p.inTable) continue;
-      for (const s of sentences(p.prose)) {
-        if (s.split(/\s+/).length > maxWords) {
-          findings.push({ file, line: p.line, rule: RULE.LENGTH, message: lengthMessage(s, maxWords) });
-        }
-      }
-    }
-    return findings;
-  },
+  check,
 };

package/src/rules/pg003-semicolon-list.ts

@@ -2,54 +2,46 @@
 // list. The fix needs a colon lead-in to know where the list starts, and
 // refuses without one.
 
-import { cleanItem, cleanLeadIn, promote } from "../fix/promote.ts";
-import { matchesInAll, sentenceSpans, within } from "../fix/spans.ts";
-import { type DocModel, sentences } from "../model.ts";
-import { type Edit, type Finding, RULE, type Rule } from "./types.ts";
+import { cleanLeadIn, itemsBetween, promote } from "../fix/promote.ts";
+import { colonsBefore, colonsIn, matchesInAll, proseSentences, sentenceSpans } from "../query.ts";
+import { countOf, first, within } from "../text.ts";
+import { type Edit, RULE, type Rule } from "./types.ts";
 
-const check: Rule["check"] = ({ doc, file }) => {
-  const findings: Finding[] = [];
-  for (const p of doc.paragraphs) {
-    if (p.inTable) continue;
-    for (const s of sentences(p.prose)) {
-      const semis = (s.match(/;/g) ?? []).length;
-      if (semis >= 2) {
-        findings.push({
-          file,
-          line: p.line,
-          rule: RULE.SEMICOLON_LIST,
-          message: `semicolon-delimited list (${semis} ';'); promote to a bullet list`,
-        });
-      }
-    }
-  }
-  return findings;
-};
+const SEMICOLON = /;/g;
 
-const fix = (doc: DocModel): Edit[] => {
-  const edits: Edit[] = [];
+const check: Rule["check"] = ({ doc, file }) =>
+  proseSentences(doc)
+    .map(({ view, sentence }) => ({ view, semicolons: countOf(sentence, SEMICOLON) }))
+    .filter(({ semicolons }) => semicolons >= 2)
+    .map(({ view, semicolons }) => ({
+      file,
+      line: view.line,
+      rule: RULE.SEMICOLON_LIST,
+      message: `semicolon-delimited list (${semicolons} ';'); promote to a bullet list`,
+    }));
+
+const fix: Rule["fix"] = ({ doc }) => {
   const { src } = doc;
+  const edits: Edit[] = [];
   for (const view of doc.paragraphs) {
-    const semis = matchesInAll(src, view.directTexts, /;/);
-    const colons = matchesInAll(src, view.directTexts, /:/);
-    if (semis === null || colons === null) continue;
+    const semicolons = matchesInAll(src, view.directTexts, SEMICOLON);
+    const colons = colonsIn(src, view);
+    if (semicolons === null || colons === null) continue;
     for (const span of sentenceSpans(src, view)) {
-      const inside = semis.filter((r) => within(r, span));
+      const inside = semicolons.filter((semicolon) => within(semicolon, span));
       if (inside.length < 2) continue;
-      const colon = colons.find((r) => within(r, span) && r[1] <= (inside[0] as [number, number])[0]);
+      // The outermost colon before the first item opens the lead-in, so a
+      // "Note: the rules: a; b; c" keeps the whole of "Note: the rules".
+      const colon = colonsBefore(colons, span, first(inside)[0])[0];
       if (!colon) continue;
-      const cuts = [colon, ...inside];
-      const items = cuts.map((cut, i) => {
-        const end = i + 1 < cuts.length ? (cuts[i + 1] as [number, number])[0] : span[1];
-        return { text: cleanItem(src.slice(cut[1], end), { last: i + 1 === cuts.length }) };
-      });
+
       const edit = promote({
         rule: RULE.SEMICOLON_LIST,
         src,
         view,
         span,
         leadIn: cleanLeadIn(src.slice(span[0], colon[0])),
-        items,
+        items: itemsBetween(src, [colon, ...inside], span[1]).map((text) => ({ text })),
         ordered: false,
       });
       if (edit) edits.push(edit);