@jpeakai/prose-gates 0.1.0

package/src/rules/pg007-inline-enum.ts

@@ -0,0 +1,119 @@
+// PG007: parenthesised enumerators inlined in one paragraph are a hidden
+// list. Requiring the first two members of a family keeps citations and a
+// lone "(a)" reference from firing. The fix only trusts a clean sequence:
+// every marker in order, none skipped, none from another family.
+
+import { cleanItem, cleanLeadIn, promote } from "../fix/promote.ts";
+import { sentenceSpan } from "../fix/spans.ts";
+import type { DocModel, Range } from "../model.ts";
+import { type Edit, type Finding, RULE, type Rule } from "./types.ts";
+
+const ENUM_FAMILIES: Array<[string, string]> = [
+  ["(a)", "(b)"],
+  ["(1)", "(2)"],
+  ["(i)", "(ii)"],
+];
+
+const ROMAN = ["i", "ii", "iii", "iv", "v", "vi", "vii", "viii", "ix", "x", "xi", "xii"];
+const LETTERS = [..."abcdefghijklmnopqrstuvwxyz"];
+
+// The expected nth marker for the family the first marker opens.
+const sequenceFor = (first: string): string[] | null => {
+  if (first === "a") return LETTERS;
+  if (first === "1") return Array.from({ length: 99 }, (_, i) => String(i + 1));
+  if (first === "i") return ROMAN;
+  return null;
+};
+
+const MARKER = /\(([a-z]|[ivx]+|\d{1,2})\)(?=\s)/g;
+
+interface Marker {
+  range: Range;
+  label: string;
+}
+
+// Markers that open an item: preceded by whitespace or the start of a direct
+// text node, and followed by whitespace. The parsed value must agree with the
+// source, or an escape is hiding somewhere and the fixer refuses.
+const markersIn = (src: string, texts: DocModel["paragraphs"][number]["directTexts"]): Marker[] | null => {
+  const out: Marker[] = [];
+  for (const t of texts) {
+    const slice = src.slice(t.start, t.end);
+    const opening = (s: string): RegExpMatchArray[] =>
+      [...s.matchAll(MARKER)].filter((m) => (m.index ?? 0) === 0 || /\s/.test(s[(m.index ?? 0) - 1] as string));
+    const inSlice = opening(slice);
+    if (inSlice.length !== opening(t.value).length) return null;
+    for (const m of inSlice) {
+      const start = t.start + (m.index ?? 0);
+      out.push({ range: [start, start + m[0].length], label: m[1] as string });
+    }
+  }
+  return out;
+};
+
+const fix = (doc: DocModel): Edit[] => {
+  const { src } = doc;
+  const edits: Edit[] = [];
+  for (const view of doc.paragraphs) {
+    const markers = markersIn(src, view.directTexts);
+    if (markers === null || markers.length < 2) continue;
+    const sequence = sequenceFor((markers[0] as Marker).label);
+    if (sequence === null || markers.some((m, i) => m.label !== sequence[i])) continue;
+
+    const first = markers[0] as Marker;
+    const last = markers[markers.length - 1] as Marker;
+    // Markers split across sentences are two references, not one list.
+    const between = view.directTexts.map((t) =>
+      src.slice(Math.max(t.start, first.range[1]), Math.min(t.end, last.range[0])),
+    );
+    if (between.some((s) => /[.!?]\s/.test(s))) continue;
+    const span = sentenceSpan(src, view, first.range[0], last.range[1]);
+    // Two markers joined only by a conjunction, with no colon to announce
+    // them, read as cross-references ("see (a) above and (b) below").
+    const announced = /:\s*$/.test(src.slice(span[0], first.range[0]));
+    const separated = /[,;]\s*$/.test(src.slice((markers[0] as Marker).range[1], (markers[1] as Marker).range[0]));
+    if (markers.length === 2 && !announced && !separated) continue;
+    const items = markers.map((m, i) => {
+      const end = i + 1 < markers.length ? (markers[i + 1] as Marker).range[0] : span[1];
+      return { text: cleanItem(src.slice(m.range[1], end), { last: i + 1 === markers.length }) };
+    });
+    const edit = promote({
+      rule: RULE.INLINE_ENUM,
+      src,
+      view,
+      span,
+      leadIn: cleanLeadIn(src.slice(span[0], first.range[0])),
+      items,
+      ordered: true,
+    });
+    if (edit) edits.push(edit);
+  }
+  return edits;
+};
+
+const check: Rule["check"] = ({ doc, file }) => {
+  const findings: Finding[] = [];
+  for (const p of doc.paragraphs) {
+    if (p.inTable) continue;
+    for (const [first, second] of ENUM_FAMILIES) {
+      if (p.prose.includes(first) && p.prose.includes(second)) {
+        findings.push({
+          file,
+          line: p.line,
+          rule: RULE.INLINE_ENUM,
+          message: `enumeration ${first} ${second} ... inlined in prose; promote to a bullet list`,
+        });
+        break;
+      }
+    }
+  }
+  return findings;
+};
+
+export const pg007: Rule = {
+  id: RULE.INLINE_ENUM,
+  category: "list",
+  summary: "enumeration markers (a)/(b) or (1)/(2) inlined in prose",
+  check,
+  fix,
+};

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

@@ -0,0 +1,94 @@
+// PG008: one sentence stringing 3+ comma-separated segments each led by a
+// label (an inline-code span, or an identifier like PG001 / 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 { 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";
+
+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 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;
+  }
+  return collapse(out + src.slice(at, range[1])).trim();
+};
+
+const fix = (doc: DocModel): Edit[] => {
+  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, /:/);
+    if (commas === null || colons === null) continue;
+    for (const span of sentenceSpans(src, view)) {
+      const inside = commas.filter((r) => within(r, 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;
+
+      // 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];
+
+      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,
+        ordered: false,
+      });
+      if (edit) edits.push(edit);
+      break;
+    }
+  }
+  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",
+  summary: "comma-joined labelled run (3+ labelled segments)",
+  check,
+  fix,
+};

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

@@ -0,0 +1,79 @@
+// PG009: interpunct runs stacked on 2+ source lines of one paragraph are a
+// two-level structure, so PG009 replaces PG006 for that paragraph. The fix
+// 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 { type Edit, RULE, type Rule } from "./types.ts";
+
+const fix = (doc: DocModel): Edit[] => {
+  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;
+    }
+
+    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 });
+    }
+    if (parents.length !== lines.length) continue;
+
+    const edit = promote({
+      rule: RULE.STACKED_RUNS,
+      src,
+      view,
+      span: [view.startOffset, view.endOffset],
+      leadIn: null,
+      items: parents,
+      ordered: false,
+    });
+    if (edit) edits.push(edit);
+  }
+  return edits;
+};
+
+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`,
+      })),
+  fix,
+};

package/src/rules/types.ts

@@ -0,0 +1,77 @@
+// The contract every rule implements: a check that reports findings, and an
+// 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";
+
+export const RULE = {
+  WRAP: "PG001",
+  LENGTH: "PG002",
+  SEMICOLON_LIST: "PG003",
+  EM_DASH: "PG004",
+  INTERPUNCT: "PG005",
+  INTERPUNCT_RUN: "PG006",
+  INLINE_ENUM: "PG007",
+  LABELLED_RUN: "PG008",
+  STACKED_RUNS: "PG009",
+} as const;
+
+export type RuleId = (typeof RULE)[keyof typeof RULE];
+
+export interface Finding {
+  file: string;
+  line: number;
+  rule: RuleId;
+  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
+}
+
+export interface CheckContext {
+  doc: DocModel;
+  file: string;
+  maxWords: number;
+  runs: InterpunctRun[];
+}
+
+// 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.
+  | { kind: "same-tree" }
+  // Glyphs swapped inside text: the tree keeps its shape and every word.
+  | { kind: "same-shape" }
+  // One paragraph becomes the blocks parsed from `fragment`, and nothing else
+  // in the document moves.
+  | { kind: "replace-paragraph"; view: ParagraphView; fragment: string; listItems: number };
+
+export interface Edit {
+  rule: RuleId;
+  start: number;
+  end: number;
+  text: string;
+  expect: Expectation;
+}
+
+// What a rule guards, so related rules read as a group in help and RULES.md.
+// sentence: how a sentence is laid out and how long it runs.
+// list: a list hidden in running prose, promoted to a real markdown list.
+// punctuation: a glyph that reads as generated text.
+export const CATEGORIES = ["sentence", "list", "punctuation"] as const;
+
+export type Category = (typeof CATEGORIES)[number];
+
+export interface Rule {
+  id: RuleId;
+  category: Category;
+  summary: string;
+  check: (ctx: CheckContext) => Finding[];
+  // Absent for rules whose fix needs discretion (PG002).
+  fix?: (doc: DocModel) => Edit[];
+}