@jpeakai/prose-gates 0.1.0 → 0.1.2

package/src/rules/pg008-labelled-run.ts

@@ -8,83 +8,90 @@
 // 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 { cleanItem, cleanLeadIn, promote } from "../fix/promote.ts";
-import { collapse, matchesInAll, sentenceSpans, within } from "../fix/spans.ts";
-import { type DocModel, type ParagraphView, type Range, sentences } from "../model.ts";
-import { type Edit, type Finding, RULE, type Rule } from "./types.ts";
+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";
 
-const LABELLED_SEGMENT = /^(?:and\s+|or\s+)?(?:[A-Za-z][\w\s-]{0,24}:\s*)?(?:CODE|[A-Z][A-Za-z]*\d[\w/-]*)\s+\S/;
+// 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 [a, b] of view.codeRanges) {
-    if (b <= range[0] || a >= range[1]) continue;
-    out += `${src.slice(at, a)}CODE`;
-    at = b;
+  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 fix = (doc: DocModel): Edit[] => {
+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 = matchesInAll(src, view.directTexts, /:/);
+    const colons = colonsIn(src, view);
     if (commas === null || colons === null) continue;
     for (const span of sentenceSpans(src, view)) {
-      const inside = commas.filter((r) => within(r, span));
+      const inside = commas.filter((comma) => within(comma, span));
       if (inside.length < 2) continue;
-      const bounds: Range[] = inside.map((c, i) => [i === 0 ? span[0] : (inside[i - 1] as Range)[1], c[0]]);
-      bounds.push([(inside[inside.length - 1] as Range)[1], span[1]]);
-      if (!bounds.every((b) => LABELLED_SEGMENT.test(asProse(src, view, b)))) 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.
-      const firstBound = bounds[0] as Range;
-      const colon = colons.find((c) => within(c, firstBound));
-      const intro = colon && /^[A-Za-z][\w\s-]{0,24}$/.test(collapse(src.slice(span[0], colon[0])).trim());
-      if (intro && colon) firstBound[0] = colon[1];
+      // 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 items = bounds.map((b, i) => ({
-        text: cleanItem(src.slice(b[0], b[1]), { last: i + 1 === bounds.length }),
-      }));
       const edit = promote({
         rule: RULE.LABELLED_RUN,
         src,
         view,
         span,
         leadIn: intro && colon ? cleanLeadIn(src.slice(span[0], colon[0])) : null,
-        items,
+        items: itemsOf(src, items).map((text) => ({ text })),
         ordered: false,
       });
       if (edit) edits.push(edit);
-      break;
+      break; // one promotion per paragraph; the engine re-parses and comes back
     }
   }
   return edits;
 };
 
-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 labelled = s.split(/,\s+/).filter((seg) => LABELLED_SEGMENT.test(seg)).length;
-      if (labelled >= 3) {
-        findings.push({
-          file,
-          line: p.line,
-          rule: RULE.LABELLED_RUN,
-          message: `comma-joined run of ${labelled} labelled items; promote to a bullet list`,
-        });
-      }
-    }
-  }
-  return findings;
-};
-
 export const pg008: Rule = {
   id: RULE.LABELLED_RUN,
   category: "list",

package/src/rules/pg009-stacked-runs.ts

@@ -3,49 +3,58 @@
 // needs every line to read `Label: a · b · c`, and builds one parent bullet
 // per label with the items nested beneath it.
 
-import { cleanItem, type PromotedItem, promote } from "../fix/promote.ts";
-import { collapse, escaped, matchesInAll, within } from "../fix/spans.ts";
-import type { DocModel, Range } from "../model.ts";
-import { interpunctRuns } from "./interpunct.ts";
+import { itemsBetween, type PromotedItem, promote } from "../fix/promote.ts";
+import { GLYPH, isStacked, paragraphsOf, RUN_SEPARATOR } from "../interpunct.ts";
+import type { ParagraphView } from "../model.ts";
+import { colonsBefore, colonsIn, splittableSeparators } from "../query.ts";
+import { collapse, first, type Range, within } from "../text.ts";
 import { type Edit, RULE, type Rule } from "./types.ts";
 
-const fix = (doc: DocModel): Edit[] => {
+// The source lines of a paragraph, as absolute ranges.
+const linesOf = (view: ParagraphView): Range[] => {
+  const lines: Range[] = [];
+  let at = view.startOffset;
+  for (const line of view.raw.split("\n")) {
+    lines.push([at, at + line.length]);
+    at += line.length + 1;
+  }
+  return lines;
+};
+
+// One line read as `Label: a · b · c`, or null when it is not that shape.
+// Every line of the paragraph has to parse, or the fix has no nested list to
+// build and leaves the whole paragraph reported.
+const parentOf = (src: string, line: Range, separators: Range[], colons: Range[]): PromotedItem | null => {
+  const inside = separators.filter((separator) => within(separator, line));
+  if (inside.length === 0) return null;
+  const colon = colonsBefore(colons, line, first(inside)[0])[0];
+  if (!colon) return null;
+  return {
+    text: collapse(src.slice(line[0], colon[0])).trim(),
+    children: itemsBetween(src, [colon, ...inside], line[1]),
+  };
+};
+
+const check: Rule["check"] = ({ file, runs }) =>
+  runs.filter(isStacked).map((run) => ({
+    file,
+    line: run.line,
+    rule: RULE.STACKED_RUNS,
+    message: `interpunct runs stacked on ${run.lines} lines; promote to a nested list`,
+  }));
+
+const fix: Rule["fix"] = ({ doc, runs }) => {
   const { src } = doc;
   const edits: Edit[] = [];
-  const runs = interpunctRuns(doc).filter((r) => r.lines >= 2);
-  for (const view of doc.paragraphs) {
-    if (!runs.some((r) => r.range[0] === view.startOffset)) continue;
-    const seps = matchesInAll(src, view.directTexts, /[ \t]*·[ \t]*/);
-    const colons = matchesInAll(src, view.directTexts, /:/);
-    if (
-      seps === null ||
-      colons === null ||
-      seps.length !== (view.prose.match(/·/g) ?? []).length ||
-      seps.some(([s]) => escaped(src, s))
-    )
-      continue;
-
-    // Source lines of the paragraph, as absolute ranges.
-    const lines: Range[] = [];
-    let at = view.startOffset;
-    for (const line of view.raw.split("\n")) {
-      lines.push([at, at + line.length]);
-      at += line.length + 1;
-    }
+  for (const view of paragraphsOf(doc, runs.filter(isStacked))) {
+    const separators = splittableSeparators(src, view, RUN_SEPARATOR, GLYPH);
+    const colons = colonsIn(src, view);
+    if (separators === null || colons === null) continue;
 
-    const parents: PromotedItem[] = [];
-    for (const line of lines) {
-      const lineSeps = seps.filter((s) => within(s, line));
-      const colon = colons.find((c) => within(c, line));
-      if (lineSeps.length === 0 || !colon || colon[1] > (lineSeps[0] as Range)[0]) break;
-      const label = collapse(src.slice(line[0], colon[0])).trim();
-      const cuts: Range[] = [colon, ...lineSeps];
-      const children = cuts.map((cut, i) => {
-        const end = i + 1 < cuts.length ? (cuts[i + 1] as Range)[0] : line[1];
-        return cleanItem(src.slice(cut[1], end), { last: i + 1 === cuts.length });
-      });
-      parents.push({ text: label, children });
-    }
+    const lines = linesOf(view);
+    const parents = lines
+      .map((line) => parentOf(src, line, separators, colons))
+      .filter((parent): parent is PromotedItem => parent !== null);
     if (parents.length !== lines.length) continue;
 
     const edit = promote({
@@ -66,14 +75,6 @@ export const pg009: Rule = {
   id: RULE.STACKED_RUNS,
   category: "list",
   summary: "interpunct runs stacked on several lines (nested list)",
-  check: ({ file, runs }) =>
-    runs
-      .filter((r) => r.lines >= 2)
-      .map((r) => ({
-        file,
-        line: r.line,
-        rule: RULE.STACKED_RUNS,
-        message: `interpunct runs stacked on ${r.lines} lines; promote to a nested list`,
-      })),
+  check,
   fix,
 };

package/src/rules/types.ts

@@ -2,7 +2,8 @@
 // optional fixer that proposes edits. The fix engine, not the fixer, decides
 // whether an edit is safe to keep.
 
-import type { DocModel, ParagraphView, Range } from "../model.ts";
+import type { InterpunctRun } from "../interpunct.ts";
+import type { DocModel, ParagraphView } from "../model.ts";
 
 export const RULE = {
   WRAP: "PG001",
@@ -25,22 +26,24 @@ export interface Finding {
   message: string;
 }
 
-// Paragraphs whose prose joins a run of items with 2+ interpunct separators.
-// Shared by PG005, PG006 and PG009 as an explicit data dependency.
-export interface InterpunctRun {
-  range: Range;
-  line: number;
-  separators: number;
-  lines: number; // source lines of the paragraph that carry a separator
+// What every rule reads, computed once per document and handed to it. Shared
+// data is passed in rather than recomputed, so a check and a fix can never
+// disagree about what the document holds.
+export interface RuleContext {
+  doc: DocModel;
+  runs: InterpunctRun[];
 }
 
-export interface CheckContext {
-  doc: DocModel;
+// A check also names the file it reports against, and the sentence budget.
+export interface CheckContext extends RuleContext {
   file: string;
   maxWords: number;
-  runs: InterpunctRun[];
 }
 
+// A fix needs nothing beyond the shared context. It proposes edits, and the
+// engine alone decides which of them survive verification.
+export type FixContext = RuleContext;
+
 // What the engine must be able to prove about the document after an edit.
 export type Expectation =
   // Whitespace only: the tree is unchanged once text whitespace is collapsed.
@@ -73,5 +76,5 @@ export interface Rule {
   summary: string;
   check: (ctx: CheckContext) => Finding[];
   // Absent for rules whose fix needs discretion (PG002).
-  fix?: (doc: DocModel) => Edit[];
+  fix?: (ctx: FixContext) => Edit[];
 }

package/src/text.ts

@@ -0,0 +1,50 @@
+// Text and range arithmetic that knows nothing about markdown. Everything
+// here is a pure function of its arguments, so it is the one layer that can
+// be read without the document model in mind.
+
+// A half-open span of absolute offsets into a source string. Every range in
+// this package is [start, end), and is only valid for the source it was
+// computed from.
+export type Range = [number, number];
+
+// The ends of a list the caller has already proved non-empty. Written once
+// here so `noUncheckedIndexedAccess` costs the package two casts rather than
+// one per rule.
+export const first = <T>(xs: readonly T[]): T => xs[0] as T;
+
+export const last = <T>(xs: readonly T[]): T => xs[xs.length - 1] as T;
+
+export const within = (r: Range, span: Range): boolean => r[0] >= span[0] && r[1] <= span[1];
+
+// Soft line breaks collapse to single spaces; nothing else in the slice moves.
+export const collapse = (s: string): string => s.replace(/[ \t]*\r?\n[ \t]*/g, " ");
+
+// How many times a pattern matches. The pattern must be global: matchAll
+// throws otherwise, which is the loud failure we want over a silent count
+// of one.
+export const countOf = (text: string, pattern: RegExp): number => [...text.matchAll(pattern)].length;
+
+// The spans a run of cut points carves out of a sentence. Each span runs from
+// the end of its own cut to the start of the next one, and the last runs to
+// `end`. Every hidden-list fixer needs exactly this, so the fencepost is
+// written once here rather than once per rule.
+export const spansBetween = (cuts: Range[], end: number): Range[] =>
+  cuts.map((cut, i) => {
+    const next = cuts[i + 1];
+    return [cut[1], next ? next[0] : end];
+  });
+
+// Words of a sentence or an item, counted the one way for every rule.
+export const words = (text: string): number => text.split(/\s+/).filter(Boolean).length;
+
+// Whether an offset falls inside any of the ranges.
+export const inRanges = (offset: number, ranges: Range[]): boolean =>
+  ranges.some(([a, b]) => offset >= a && offset < b);
+
+// Prose split on terminals. A check reads sentences this way; a fixer needs
+// the source offsets instead and asks `sentenceSpans` for them.
+export const sentences = (text: string): string[] =>
+  text
+    .split(/(?<=[.!?])\s+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);

package/src/fix/spans.ts

@@ -1,75 +0,0 @@
-// Source-offset helpers shared by fixers. Everything here works on absolute
-// offsets into the document source, and only ever looks inside text the
-// parser proved is prose.
-
-import type { DirectText, ParagraphView, Range } from "../model.ts";
-
-// 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 fixer 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;
-};
-
-// 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;
-};
-
-export const within = (r: Range, span: Range): boolean => r[0] >= span[0] && r[1] <= span[1];
-
-// Soft line breaks collapse to single spaces; nothing else in the slice moves.
-export const collapse = (s: string): string => s.replace(/[ \t]*\r?\n[ \t]*/g, " ");
-
-// A glyph the author escaped is literal text, never a separator to rewrite.
-export const escaped = (src: string, offset: number): boolean => src[offset - 1] === "\\";

package/src/rules/interpunct.ts

@@ -1,19 +0,0 @@
-// Paragraphs whose prose joins a run of items with 2+ interpunct separators.
-// PG006 and PG009 report the run, and PG005 stays quiet inside one, so the
-// runs are computed once and passed to every check as data.
-
-import type { DocModel } from "../model.ts";
-import type { InterpunctRun } from "./types.ts";
-
-export const interpunctRuns = (doc: DocModel): InterpunctRun[] => {
-  const runs: InterpunctRun[] = [];
-  for (const p of doc.paragraphs) {
-    if (p.inTable) continue;
-    const separators = (p.prose.match(/·/g) ?? []).length;
-    if (separators >= 2) {
-      const lines = p.raw.split("\n").filter((l) => l.includes("·")).length;
-      runs.push({ range: [p.startOffset, p.endOffset], line: p.line, separators, lines });
-    }
-  }
-  return runs;
-};