@jpeakai/prose-gates 0.1.1 → 0.2.0

package/examples/plugin-skills/README.md

@@ -0,0 +1,60 @@
+# prose-gates-plugin-skills
+
+A template plugin for the frontmatter of an agent skill.
+It adds the category `frontmatter` and two rules, under the namespace `skills`.
+[`examples/plugin-skills-typescript`](../plugin-skills-typescript) is the same plugin in TypeScript.
+
+## The rules
+
+| Rule | What it does | Fixer |
+|---|---|---|
+| `skills/frontmatter-description-word-budget` | Reports a sentence over the word budget in any string whose nearest key is `description` | None, because shortening a sentence changes its words |
+| `skills/frontmatter-description-multiline-string` | Reports a multi-sentence description written on one line | Rewrites it as a folded block scalar, one sentence per line |
+
+Both read the whole YAML document through `doc.frontmatter.scalars`.
+A `description` nested under `metadata`, or inside a list, is checked the same as a top-level one.
+Set the `keys` option to look at other keys.
+
+## The fixer
+
+The multiline rule is the worked example of a fixer.
+
+```yaml
+description: Use this skill to format reports. It also checks tables.
+```
+
+becomes
+
+```yaml
+description: >-
+  Use this skill to format reports.
+  It also checks tables.
+```
+
+The edit changes how the value is written and nothing it means.
+It declares that with the `same-frontmatter-data` expectation, so the engine parses the YAML before and after and refuses the edit unless both give identical data.
+The fixer skips a value that is already a block, that sits on the line below its key, or that has a comment after it, because each of those would change the data.
+
+## Use it as a local rule
+
+Copy a file from `rules/` to `.prose-gates/rules/` in your project.
+It loads on its own, and its id is `local/` followed by the file name.
+A rule file exports `categories` and a default rule, so it needs nothing else.
+
+## Use it as a package
+
+Publish this folder as `prose-gates-plugin-skills`, or copy it into your own package.
+List it in `devDependencies` and it loads on its own, under the ids `skills/...`.
+
+## Configure it
+
+```json
+{
+  "rules": {
+    "skills/frontmatter-description-word-budget": ["error", { "keys": ["description", "summary"], "maxWords": 40 }],
+    "skills/frontmatter-description-multiline-string": ["error", { "keys": ["description"] }]
+  }
+}
+```
+
+[docs/plugins.md](../../docs/plugins.md) explains every part of the contract.

package/examples/plugin-skills/index.mjs

@@ -0,0 +1,14 @@
+// The plugin entry: a name, a namespace, the contract version, the categories
+// it adds and its rules. Each rule lives in rules/ so it can also be copied into
+// a project as a local rule.
+
+import multiline, { categories } from "./rules/frontmatter-description-multiline-string.mjs";
+import wordBudget from "./rules/frontmatter-description-word-budget.mjs";
+
+export default {
+  meta: { name: "skills", namespace: "skills", apiVersion: 1, categories },
+  rules: {
+    "frontmatter-description-multiline-string": multiline,
+    "frontmatter-description-word-budget": wordBudget,
+  },
+};

package/examples/plugin-skills/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "prose-gates-plugin-skills",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Template plugin: holds frontmatter descriptions of agent skills to a sentence budget",
+  "type": "module",
+  "main": "index.mjs",
+  "keywords": ["prose-gates-plugin"],
+  "peerDependencies": {
+    "@jpeakai/prose-gates": ">=0.2.0"
+  }
+}

package/examples/plugin-skills/rules/frontmatter-description-multiline-string.mjs

@@ -0,0 +1,63 @@
+// frontmatter-description-multiline-string: a description with several
+// sentences written on one line. The fixer rewrites it as a folded block scalar,
+// one sentence per line, which YAML reads back as the same string.
+//
+//   description: First sentence. Second sentence.
+//
+// becomes
+//
+//   description: >-
+//     First sentence.
+//     Second sentence.
+//
+// This is the worked example of a fixer. It proposes an edit that changes how the
+// value is written and nothing it means, and it declares that with the
+// `same-frontmatter-data` expectation, so the engine parses the YAML before and
+// after and refuses the edit unless both give identical data.
+
+export const categories = {
+  frontmatter: "Keys in the leading metadata block of a file",
+};
+
+// The scalars this rule would rewrite: a single-line plain or quoted string, on
+// the same line as its key, with two or more sentences, and no comment after it.
+// Anything else is left alone, and the finding is not raised for it.
+const candidates = ({ doc, options, helpers }) => {
+  const frontmatter = doc.frontmatter;
+  if (!frontmatter) return [];
+  const keys = options.keys ?? ["description"];
+  return frontmatter.scalars.filter((scalar) => {
+    if (scalar.key === null || !keys.includes(scalar.key)) return false;
+    if (scalar.style === "literal" || scalar.style === "folded") return false;
+    if (scalar.keyLine !== scalar.line || scalar.value.includes("\n")) return false;
+    if (helpers.sentences(scalar.value).length < 2) return false;
+    // A comment after the value would become part of the block scalar.
+    const lineEnd = doc.src.indexOf("\n", scalar.end);
+    const rest = doc.src.slice(scalar.end, lineEnd === -1 ? undefined : lineEnd);
+    return rest.trim() === "";
+  });
+};
+
+export default {
+  category: "frontmatter",
+  summary: "multi-sentence frontmatter value on one line; write it as a folded block",
+  options: { keys: "string[]" },
+  check(ctx) {
+    return candidates(ctx).map((scalar) => ({
+      line: scalar.line,
+      message: `${scalar.path.join(".")}: ${ctx.helpers.sentences(scalar.value).length} sentences on one line; write it as a folded block scalar`,
+    }));
+  },
+  fix(ctx) {
+    return candidates(ctx).map((scalar) => {
+      const pad = " ".repeat(scalar.indent + 2);
+      const lines = ctx.helpers.sentences(scalar.value).map((sentence) => `${pad}${sentence}`);
+      return {
+        start: scalar.start,
+        end: scalar.end,
+        text: `>-\n${lines.join("\n")}`,
+        expect: { kind: "same-frontmatter-data" },
+      };
+    });
+  },
+};

package/examples/plugin-skills/rules/frontmatter-description-word-budget.mjs

@@ -0,0 +1,35 @@
+// frontmatter-description-word-budget: a sentence in a frontmatter value that
+// runs past the word budget. It reads every string whose nearest key is in
+// `keys`, which default to `description`, at any depth, so it covers the
+// description of an agent skill and a description nested under a `metadata` key.
+// It is a plain module so the same file works as a local rule in
+// .prose-gates/rules and inside a packaged plugin.
+//
+// It never fixes: shortening a sentence changes its words.
+
+export const categories = {
+  frontmatter: "Keys in the leading metadata block of a file",
+};
+
+export default {
+  category: "frontmatter",
+  summary: "sentence in a frontmatter value longer than the word budget",
+  options: { keys: "string[]", maxWords: "number" },
+  check({ doc, maxWords, options, helpers }) {
+    const keys = options.keys ?? ["description"];
+    const frontmatter = doc.frontmatter;
+    if (!frontmatter) return [];
+    // `scalars` walks the whole YAML document, so a nested key matches too.
+    return frontmatter.scalars
+      .filter((scalar) => scalar.key !== null && keys.includes(scalar.key))
+      .flatMap((scalar) =>
+        helpers
+          .sentences(scalar.value)
+          .filter((sentence) => helpers.words(sentence) > maxWords)
+          .map((sentence) => ({
+            line: scalar.line,
+            message: `${scalar.path.join(".")}: ${helpers.lengthMessage(sentence, maxWords)}`,
+          })),
+      );
+  },
+};

package/examples/plugin-skills-typescript/README.md

@@ -0,0 +1,42 @@
+# prose-gates-plugin-skills-typescript
+
+The [`plugin-skills`](../plugin-skills) example, written in TypeScript.
+It has the same two rules and behaves the same, under the namespace `skills-ts`.
+
+| Rule | What it does | Fixer |
+|---|---|---|
+| `skills-ts/frontmatter-description-word-budget` | Reports a sentence over the word budget in any `description`, at any depth | None |
+| `skills-ts/frontmatter-description-multiline-string` | Reports a multi-sentence description on one line | Rewrites it as a folded block scalar |
+
+## Types
+
+Every type a rule needs comes from `@jpeakai/prose-gates`.
+
+```ts
+import type { FrontmatterScalar, PluginEdit, PluginFinding, PluginRule } from "@jpeakai/prose-gates";
+```
+
+A rule is typed `PluginRule`, so `check` returns `PluginFinding[]` and `fix` returns `PluginEdit[]`.
+The engine adds the rule id and the file, so neither type carries them.
+The repo type-checks this folder with `strict` on, so the example cannot drift from the API.
+
+## Running it
+
+TypeScript is imported as it is, so the runtime must be able to import it.
+
+| How you load it | Runtime that works |
+|---|---|
+| A local rule in `.prose-gates/rules/*.ts` | Bun, or Node 22.18 or newer |
+| A package in `node_modules` | Bun, or any runtime once it is compiled to JavaScript |
+
+Node does not strip types from a file inside `node_modules`.
+Publish a compiled build as the package's `main`, and keep the `.ts` source for local rules.
+`bunx --bun @jpeakai/prose-gates` runs everything under Bun.
+
+Write erasable syntax only, with no enums and no parameter properties, so Node can strip it.
+
+## The fixer
+
+The multiline rule rewrites a one-line, multi-sentence description as a folded block.
+It declares `{ kind: "same-frontmatter-data" }`, so the engine parses the YAML before and after and refuses the edit unless both give identical data.
+[docs/plugins.md](../../docs/plugins.md) explains the expectation and the frontmatter view.

package/examples/plugin-skills-typescript/index.ts

@@ -0,0 +1,21 @@
+// The plugin entry, in TypeScript: a name, a namespace, the contract version, the
+// categories it adds and its rules. Each rule lives in rules/ so it can also be
+// copied into a project as a local rule.
+//
+// Node strips types only outside node_modules, so a package like this one loads
+// under Bun, or after it is compiled. A local rule in .prose-gates/rules loads
+// under Bun and under Node 22.18 or newer.
+
+import type { Plugin } from "@jpeakai/prose-gates";
+import multiline, { categories } from "./rules/frontmatter-description-multiline-string.ts";
+import wordBudget from "./rules/frontmatter-description-word-budget.ts";
+
+const plugin: Plugin = {
+  meta: { name: "skills-ts", namespace: "skills-ts", apiVersion: 1, categories },
+  rules: {
+    "frontmatter-description-multiline-string": multiline,
+    "frontmatter-description-word-budget": wordBudget,
+  },
+};
+
+export default plugin;

package/examples/plugin-skills-typescript/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "prose-gates-plugin-skills-typescript",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Template plugin in TypeScript: holds the frontmatter of agent skills to a sentence budget and rewrites long descriptions as folded blocks",
+  "type": "module",
+  "main": "index.ts",
+  "keywords": ["prose-gates-plugin"],
+  "peerDependencies": {
+    "@jpeakai/prose-gates": ">=0.2.0"
+  }
+}

package/examples/plugin-skills-typescript/rules/frontmatter-description-multiline-string.ts

@@ -0,0 +1,68 @@
+// frontmatter-description-multiline-string, written in TypeScript. A description
+// with several sentences written on one line. The fixer rewrites it as a folded
+// block scalar, one sentence per line, which YAML reads back as the same string.
+//
+//   description: First sentence. Second sentence.
+//
+// becomes
+//
+//   description: >-
+//     First sentence.
+//     Second sentence.
+//
+// The edit changes how the value is written and nothing it means, and it says so
+// with the `same-frontmatter-data` expectation. The engine parses the YAML before
+// and after and refuses the edit unless both give identical data.
+
+import type { CheckContext, FixContext, FrontmatterScalar, PluginEdit, PluginFinding, PluginRule } from "@jpeakai/prose-gates";
+
+export const categories: Record<string, string> = {
+  frontmatter: "Keys in the leading metadata block of a file",
+};
+
+type Context = Pick<CheckContext | FixContext, "doc" | "options" | "helpers">;
+
+// The scalars this rule would rewrite: a single-line plain or quoted string, on
+// the same line as its key, with two or more sentences, and no comment after it.
+// Anything else is left alone, and no finding is raised for it.
+const candidates = ({ doc, options, helpers }: Context): FrontmatterScalar[] => {
+  const frontmatter = doc.frontmatter;
+  if (!frontmatter) return [];
+  const keys = (options.keys as string[] | undefined) ?? ["description"];
+  return frontmatter.scalars.filter((scalar) => {
+    if (scalar.key === null || !keys.includes(scalar.key)) return false;
+    if (scalar.style === "literal" || scalar.style === "folded") return false;
+    if (scalar.keyLine !== scalar.line || scalar.value.includes("\n")) return false;
+    if (helpers.sentences(scalar.value).length < 2) return false;
+    // A comment after the value would become part of the block scalar.
+    const lineEnd = doc.src.indexOf("\n", scalar.end);
+    const rest = doc.src.slice(scalar.end, lineEnd === -1 ? undefined : lineEnd);
+    return rest.trim() === "";
+  });
+};
+
+const rule: PluginRule = {
+  category: "frontmatter",
+  summary: "multi-sentence frontmatter value on one line; write it as a folded block",
+  options: { keys: "string[]" },
+  check(ctx): PluginFinding[] {
+    return candidates(ctx).map((scalar) => ({
+      line: scalar.line,
+      message: `${scalar.path.join(".")}: ${ctx.helpers.sentences(scalar.value).length} sentences on one line; write it as a folded block scalar`,
+    }));
+  },
+  fix(ctx): PluginEdit[] {
+    return candidates(ctx).map((scalar) => {
+      const pad = " ".repeat(scalar.indent + 2);
+      const lines = ctx.helpers.sentences(scalar.value).map((sentence) => `${pad}${sentence}`);
+      return {
+        start: scalar.start,
+        end: scalar.end,
+        text: `>-\n${lines.join("\n")}`,
+        expect: { kind: "same-frontmatter-data" },
+      };
+    });
+  },
+};
+
+export default rule;

package/examples/plugin-skills-typescript/rules/frontmatter-description-word-budget.ts

@@ -0,0 +1,40 @@
+// frontmatter-description-word-budget, written in TypeScript. A sentence in a
+// frontmatter value that runs past the word budget, for any string whose nearest
+// key is in `keys` (default `description`), at any depth.
+//
+// It never fixes: shortening a sentence changes its words.
+//
+// The file is a plain module, so it works as a local rule in .prose-gates/rules
+// and inside the packaged plugin. The type import is erased at run time, so the
+// runtime only has to be able to import TypeScript.
+
+import type { PluginFinding, PluginRule } from "@jpeakai/prose-gates";
+
+export const categories: Record<string, string> = {
+  frontmatter: "Keys in the leading metadata block of a file",
+};
+
+const rule: PluginRule = {
+  category: "frontmatter",
+  summary: "sentence in a frontmatter value longer than the word budget",
+  options: { keys: "string[]", maxWords: "number" },
+  check({ doc, maxWords, options, helpers }): PluginFinding[] {
+    const keys = (options.keys as string[] | undefined) ?? ["description"];
+    const frontmatter = doc.frontmatter;
+    if (!frontmatter) return [];
+    // `scalars` walks the whole YAML document, so a nested key matches too.
+    return frontmatter.scalars
+      .filter((scalar) => scalar.key !== null && keys.includes(scalar.key))
+      .flatMap((scalar) =>
+        helpers
+          .sentences(scalar.value)
+          .filter((sentence) => helpers.words(sentence) > maxWords)
+          .map((sentence) => ({
+            line: scalar.line,
+            message: `${scalar.path.join(".")}: ${helpers.lengthMessage(sentence, maxWords)}`,
+          })),
+      );
+  },
+};
+
+export default rule;

package/examples/plugin-skills-typescript/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["index.ts", "rules/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/prose-gates",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Deterministic prose gates for markdown documentation",
   "license": "MIT",
@@ -32,6 +32,11 @@
       "bun": "./src/index.ts",
       "types": "./src/index.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "bun": "./src/testing.ts",
+      "types": "./src/testing.ts",
+      "default": "./dist/testing.js"
     }
   },
   "engines": {
@@ -39,7 +44,8 @@
   },
   "files": [
     "src",
-    "dist"
+    "dist",
+    "examples"
   ],
   "dependencies": {
     "mdast-util-from-markdown": "^2.0.3",
@@ -47,7 +53,8 @@
     "mdast-util-gfm": "^3.1.0",
     "micromark-extension-frontmatter": "^2.0.0",
     "micromark-extension-gfm": "^3.0.0",
-    "unist-util-visit-parents": "^6.0.2"
+    "unist-util-visit-parents": "^6.0.2",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2",

package/src/bin.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { main } from "./cli.ts";
+import { describeError, main } from "./cli.ts";
 
 main().then(
   (code) => process.exit(code),
   (err: unknown) => {
-    console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(describeError(err));
     process.exit(1);
   },
 );

package/src/check.ts

@@ -1,24 +1,51 @@
-// Checking: build the model once, run every rule over it, and audit
+// Checking: build the model once, run every active rule over it, and audit
 // embedded markdown fences as documents of their own.
+//
+// Nothing is modified in check mode and no rule reads another's result, so every
+// rule is started at once and the engine waits for all of them. A rule may be
+// synchronous or return a promise, so concurrency is as good as parallelism
+// here: a rule that waits on a tool or a service overlaps with the others.
 
 import { buildDocModel, type DocModel } from "./model.ts";
-import { RULES } from "./rules/index.ts";
-import { interpunctRuns } from "./rules/interpunct.ts";
+import { BUILTIN, type Registry, ruleContext, TEXT_HELPERS } from "./rules/registry.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 findings = RULES.flatMap((rule) => rule.check(ctx));
+// The sentence budget of a run: the flag wins, then the rule's own option,
+// then the default.
+const budgetFor = (flag: number | undefined, option: unknown): number =>
+  flag ?? (typeof option === "number" ? option : DEFAULT_MAX_WORDS);
+
+export const checkModel = async (
+  doc: DocModel,
+  file: string,
+  maxWords: number | undefined,
+  registry: Registry = BUILTIN,
+): Promise<Finding[]> => {
+  const shared = ruleContext(doc, registry);
+  const perRule = registry.rules.map(async (rule) => {
+    const options = registry.options.get(rule.id) ?? {};
+    return rule.check({
+      ...shared,
+      file,
+      maxWords: budgetFor(maxWords, options.maxWords),
+      options,
+      helpers: TEXT_HELPERS,
+    });
+  });
   // The fence body starts one line below the opening fence.
-  for (const fence of doc.fences) {
-    for (const f of checkModel(buildDocModel(fence.value), file, maxWords)) {
-      findings.push({ ...f, line: fence.line + f.line });
-    }
-  }
+  const perFence = doc.fences.map(async (fence) => {
+    const inner = await checkModel(buildDocModel(fence.value), file, maxWords, registry);
+    return inner.map((f) => ({ ...f, line: fence.line + f.line }));
+  });
+  const findings = (await Promise.all([...perRule, ...perFence])).flat();
   return findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
 };
 
-export const checkMarkdown = (src: string, file: string, maxWords: number = DEFAULT_MAX_WORDS): Finding[] =>
-  checkModel(buildDocModel(src), file, maxWords);
+export const checkMarkdown = (
+  src: string,
+  file: string,
+  maxWords?: number,
+  registry: Registry = BUILTIN,
+): Promise<Finding[]> => checkModel(buildDocModel(src), file, maxWords, registry);