@jpeakai/prose-gates 0.1.2 → 0.2.0

package/src/rules/registry.ts

@@ -0,0 +1,133 @@
+// The registry: the rules a run actually uses. It starts from the built-in
+// catalogue, adds whatever plugins loaded, then applies the config, so a rule
+// that is off loses its check and its fixer together. Nothing else reads the
+// catalogue directly, which is what lets a plugin rule behave as a built-in.
+
+import type { Config } from "../config.ts";
+import { RuleOptionError, UnknownRuleError } from "../errors.ts";
+import { interpunctRuns, isFlat } from "../interpunct.ts";
+import type { DocModel } from "../model.ts";
+import { sentences, words } from "../text.ts";
+import { FIX_ORDER, RULES } from "./index.ts";
+import { lengthMessage } from "./sentence-word-budget-exceeded.ts";
+import {
+  isPluginRuleId,
+  type OptionType,
+  RULE,
+  type Rule,
+  type RuleContext,
+  type RuleId,
+  type RuleOptions,
+} from "./types.ts";
+
+export const BUILTIN_CATEGORIES: ReadonlyMap<string, string> = new Map([
+  ["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 TEXT_HELPERS = { words, sentences, lengthMessage } as const;
+
+// Where a group of rules came from, for the line each run prints.
+export interface LoadedSource {
+  kind: "local" | "package" | "config";
+  spec: string;
+  namespace: string;
+  rules: RuleId[];
+}
+
+export interface Registry {
+  rules: Rule[];
+  fixOrder: Rule[];
+  enabled: ReadonlySet<RuleId>;
+  options: ReadonlyMap<RuleId, RuleOptions>;
+  categories: ReadonlyMap<string, string>;
+  sources: LoadedSource[];
+  // Config settings dropped because they name a plugin rule that did not load.
+  ignoredSettings: string[];
+}
+
+export interface RegistryInput {
+  rules: Rule[];
+  fixOrder: Rule[];
+  categories: ReadonlyMap<string, string>;
+  sources?: LoadedSource[];
+  config?: Config;
+  // A lenient run drops a setting for an unknown plugin rule instead of failing.
+  ignoreUnknownPluginIds?: boolean;
+}
+
+const typeOf = (value: unknown): OptionType | null => {
+  if (typeof value === "number" && Number.isFinite(value)) return "number";
+  if (typeof value === "string") return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) return "string[]";
+  return null;
+};
+
+const checkOptions = (where: string, rule: Rule, options: RuleOptions): void => {
+  const accepted = Object.keys(rule.options ?? {});
+  for (const [name, value] of Object.entries(options)) {
+    const want = rule.options?.[name];
+    if (!want) {
+      const list = accepted.length > 0 ? `it accepts ${accepted.join(", ")}` : "it takes no options";
+      throw new RuleOptionError(where, rule.id, name, `rule "${rule.id}" has no option "${name}"; ${list}`);
+    }
+    if (typeOf(value) !== want) {
+      throw new RuleOptionError(where, rule.id, name, `option "${name}" of "${rule.id}" must be a ${want}`);
+    }
+  }
+  if ("maxWords" in options && !((options.maxWords as number) >= 1)) {
+    throw new RuleOptionError(where, rule.id, "maxWords", `option "maxWords" of "${rule.id}" must be at least 1`);
+  }
+};
+
+export const buildRegistry = (input: RegistryInput): Registry => {
+  const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
+  const off = new Set<string>();
+  const options = new Map<RuleId, RuleOptions>();
+  const ignored: string[] = [];
+  const where = config?.file ?? "config";
+  for (const [id, setting] of config?.rules ?? []) {
+    const rule = rules.find((r) => r.id === id);
+    if (!rule) {
+      // A plugin that was skipped cannot have its rules configured, so a lenient
+      // run drops the setting and says so. A built-in id is never forgiven.
+      if (ignoreUnknownPluginIds && isPluginRuleId(id)) {
+        ignored.push(id);
+        continue;
+      }
+      throw new UnknownRuleError(
+        where,
+        id,
+        rules.map((r) => r.id),
+      );
+    }
+    checkOptions(where, rule, setting.options);
+    if (setting.severity === "off") off.add(id);
+    else options.set(rule.id, setting.options);
+  }
+  const active = rules.filter((r) => !off.has(r.id));
+  return {
+    rules: active,
+    fixOrder: fixOrder.filter((r) => !off.has(r.id)),
+    enabled: new Set(active.map((r) => r.id)),
+    options,
+    categories,
+    sources,
+    ignoredSettings: ignored,
+  };
+};
+
+export const BUILTIN: Registry = buildRegistry({ rules: RULES, fixOrder: FIX_ORDER, categories: BUILTIN_CATEGORIES });
+
+// The data every rule shares, derived once per document. Interpunct runs are
+// read by several rules, so computing them here keeps the fix engine from
+// rebuilding them once per rule on every pass of the fixpoint loop. A run is
+// owned by the flat or the stacked list rule, and it counts as reported only
+// while its owner is on.
+export const ruleContext = (doc: DocModel, registry: Registry = BUILTIN): RuleContext => {
+  const runs = interpunctRuns(doc);
+  const reported = runs.filter((run) => registry.enabled.has(isFlat(run) ? RULE.INTERPUNCT_RUN : RULE.STACKED_RUNS));
+  return { doc, runs, reported };
+};

package/src/rules/{pg001-wrap.ts → sentence-one-per-line.ts}

@@ -1,4 +1,4 @@
-// PG001: a newline inside a paragraph whose preceding non-space character
+// sentence-one-per-line: a newline inside a paragraph whose preceding non-space character
 // does not end a sentence is a mid-sentence wrap. The fix reflows the
 // paragraph to one sentence per line.
 
@@ -67,9 +67,9 @@ const check: Rule["check"] = ({ doc, file }) =>
 
 const fix: Rule["fix"] = ({ doc, runs }) => {
   const edits: Edit[] = [];
-  // Interpunct runs stacked on several lines are a nested list PG009 either
+  // Interpunct runs stacked on several lines are a nested list list-stacked-interpunct-runs either
   // promotes or leaves for a human. Joining the lines would destroy the
-  // structure and hand PG006 a flat run it would merge wrongly.
+  // structure and hand list-interpunct-joined-run a flat run it would merge wrongly.
   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
@@ -90,7 +90,7 @@ const fix: Rule["fix"] = ({ doc, runs }) => {
   return edits;
 };
 
-export const pg001: Rule = {
+export const sentenceOnePerLine: Rule = {
   id: RULE.WRAP,
   category: "sentence",
   summary: "mid-sentence line wrap (one sentence per line)",

package/src/rules/{pg002-length.ts → sentence-word-budget-exceeded.ts}

@@ -1,4 +1,4 @@
-// PG002: sentences over the word budget are hard to unpack, especially for
+// sentence-word-budget-exceeded: sentences over the word budget are hard to unpack, especially for
 // ESL readers and translators. Never autofixed: shortening a sentence is a
 // rewrite, and a rewrite needs discretion. The message estimates the clauses
 // in the sentence so the rewrite splits it rather than compressing it.
@@ -37,9 +37,10 @@ const check: Rule["check"] = ({ doc, file, maxWords }) =>
     }));
 
 // No fixer: shortening a sentence changes its words, per PRS-0006.
-export const pg002: Rule = {
+export const sentenceWordBudgetExceeded: Rule = {
   id: RULE.LENGTH,
   category: "sentence",
   summary: "sentence longer than the word budget (default 25)",
+  options: { maxWords: "number" },
   check,
 };

package/src/rules/types.ts

@@ -6,18 +6,30 @@ import type { InterpunctRun } from "../interpunct.ts";
 import type { DocModel, ParagraphView } 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",
+  WRAP: "sentence-one-per-line",
+  LENGTH: "sentence-word-budget-exceeded",
+  SEMICOLON_LIST: "list-semicolon-delimited-run",
+  EM_DASH: "punctuation-em-dash-in-prose",
+  INTERPUNCT: "punctuation-interpunct-in-prose",
+  INTERPUNCT_RUN: "list-interpunct-joined-run",
+  INLINE_ENUM: "list-inline-enumeration-markers",
+  LABELLED_RUN: "list-comma-labelled-run",
+  STACKED_RUNS: "list-stacked-interpunct-runs",
 } as const;
 
-export type RuleId = (typeof RULE)[keyof typeof RULE];
+// A core id has no slash. A plugin id is always namespace/name, so the slash
+// is what tells the two apart.
+export type CoreRuleId = (typeof RULE)[keyof typeof RULE];
+
+// A rule function may be synchronous or return a promise, so a rule can call a tool
+// or a service. The engine awaits every call.
+export type Awaitable<T> = T | Promise<T>;
+
+export type PluginRuleId = `${string}/${string}`;
+
+export const isPluginRuleId = (id: string): id is PluginRuleId => id.includes("/");
+
+export type RuleId = CoreRuleId | PluginRuleId;
 
 export interface Finding {
   file: string;
@@ -26,23 +38,47 @@ export interface Finding {
   message: string;
 }
 
-// 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.
+// The data every rule shares, 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. `runs` is every interpunct
+// run. `reported` is the runs some enabled rule owns, so a rule that defers
+// to another stops deferring when that rule is switched off.
 export interface RuleContext {
   doc: DocModel;
   runs: InterpunctRun[];
+  reported: InterpunctRun[];
+}
+
+// What a rule may be configured with. A rule names each option it accepts
+// and the type of its value, and the config is checked against that.
+export type OptionType = "number" | "string" | "boolean" | "string[]";
+
+export type OptionSpec = Readonly<Record<string, OptionType>>;
+
+export type RuleOptions = Readonly<Record<string, unknown>>;
+
+// Plain functions a plugin can use without importing this package, so a plugin
+// never depends on resolving the host from its own location.
+export interface TextHelpers {
+  words: (text: string) => number;
+  sentences: (text: string) => string[];
+  lengthMessage: (sentence: string, maxWords: number) => string;
 }
 
 // A check also names the file it reports against, and the sentence budget.
 export interface CheckContext extends RuleContext {
   file: string;
   maxWords: number;
+  options: RuleOptions;
+  helpers: TextHelpers;
 }
 
-// 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;
+// A fix needs nothing beyond the shared context and its own options. It
+// proposes edits, and the engine alone decides which of them survive.
+export interface FixContext extends RuleContext {
+  options: RuleOptions;
+  helpers: TextHelpers;
+}
 
 // What the engine must be able to prove about the document after an edit.
 export type Expectation =
@@ -50,6 +86,9 @@ export type Expectation =
   | { kind: "same-tree" }
   // Glyphs swapped inside text: the tree keeps its shape and every word.
   | { kind: "same-shape" }
+  // The frontmatter is written differently and means the same: the YAML parses to
+  // identical data before and after, and nothing outside it moves.
+  | { kind: "same-frontmatter-data" }
   // One paragraph becomes the blocks parsed from `fragment`, and nothing else
   // in the document moves.
   | { kind: "replace-paragraph"; view: ParagraphView; fragment: string; listItems: number };
@@ -66,15 +105,18 @@ export interface Edit {
 // 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.
+// A plugin may add a category of its own by declaring it.
 export const CATEGORIES = ["sentence", "list", "punctuation"] as const;
 
 export type Category = (typeof CATEGORIES)[number];
 
 export interface Rule {
   id: RuleId;
-  category: Category;
+  category: string;
   summary: string;
-  check: (ctx: CheckContext) => Finding[];
-  // Absent for rules whose fix needs discretion (PG002).
-  fix?: (ctx: FixContext) => Edit[];
+  // The options the rule accepts. Absent when it takes none.
+  options?: OptionSpec;
+  check: (ctx: CheckContext) => Awaitable<Finding[]>;
+  // Absent for rules whose fix needs discretion (sentence-word-budget-exceeded).
+  fix?: (ctx: FixContext) => Awaitable<Edit[]>;
 }

package/src/testing.ts

@@ -0,0 +1,60 @@
+// A test helper for plugin authors: run one plugin rule over real strings, with
+// the same loader checks, the same context and the same verified fix engine as
+// a real run. It is a separate entry point so a plugin's tests import it and
+// production code never does.
+
+import { checkMarkdown } from "./check.ts";
+import { type FixReport, fixMarkdownReport } from "./fix/engine.ts";
+import type { Plugin, PluginRule } from "./plugins/contract.ts";
+import { parsePlugin, toRule } from "./plugins/load.ts";
+import { BUILTIN_CATEGORIES, buildRegistry, type Registry } from "./rules/registry.ts";
+import type { Finding, RuleOptions } from "./rules/types.ts";
+
+export interface RunOptions {
+  // The rule's own options, as a config would give them.
+  options?: RuleOptions;
+  // The sentence budget, as --max-words would give it.
+  maxWords?: number;
+}
+
+// Wraps a local rule module, with its optional `categories` export, as the
+// plugin the loader would build from the file under the `local` namespace.
+export const localPlugin = (key: string, mod: { default: PluginRule; categories?: Record<string, string> }): Plugin =>
+  parsePlugin(
+    "local",
+    {
+      meta: { name: "local", namespace: "local", apiVersion: 1, categories: mod.categories },
+      rules: { [key]: mod.default },
+    },
+    new Set(),
+  );
+
+const registryFor = (plugin: Plugin, key: string, options: RuleOptions): Registry => {
+  const checked = parsePlugin(plugin.meta.name, plugin, new Set());
+  const rule = checked.rules[key];
+  if (!rule)
+    throw new Error(
+      `plugin "${plugin.meta.name}" has no rule "${key}"; it has ${Object.keys(checked.rules).join(", ")}`,
+    );
+  const built = toRule(checked.meta.namespace, key, rule);
+  return buildRegistry({
+    rules: [built],
+    fixOrder: built.fix ? [built] : [],
+    categories: new Map([...BUILTIN_CATEGORIES, ...Object.entries(checked.meta.categories ?? {})]),
+    config: {
+      plugins: [],
+      pluginLoading: "strict",
+      file: null,
+      rules: new Map([[built.id, { severity: "error", options }]]),
+    },
+  });
+};
+
+// The findings one rule of the plugin reports for a document.
+export const checkRule = async (plugin: Plugin, key: string, src: string, run: RunOptions = {}): Promise<Finding[]> =>
+  checkMarkdown(src, "test.md", run.maxWords, registryFor(plugin, key, run.options ?? {}));
+
+// The document after the rule's fixer has run to a fixpoint, and what was
+// applied or refused. A fixer that loses a word throws, exactly as in a real run.
+export const fixRule = async (plugin: Plugin, key: string, src: string, run: RunOptions = {}): Promise<FixReport> =>
+  fixMarkdownReport(src, registryFor(plugin, key, run.options ?? {}));