@jpeakai/prose-gates 0.1.1 → 0.2.0

package/README.md

@@ -19,18 +19,23 @@ npx -y @jpeakai/prose-gates --fix README.md  # apply every fix proven safe, repo
 Installed as a dev dependency, the command is `prose-gates`, and `--json` gives machine-readable output.
 
 `--max-words N` changes the sentence budget, which defaults to 25.
+`--config FILE` reads a config other than the one at the project root.
+`--no-plugins` runs the built-in rules only, and `--lenient-plugins` skips a plugin that fails to load and says so.
+`--validate-plugins` loads and checks every plugin, reports every failure, and runs no check or fix.
+`--list-rules` prints every active rule by category, including plugin rules.
 Exit codes are 0 for clean, 1 for findings, and 2 for a usage error.
 
 ## The rules
 
 Nine rules in three categories.
 [RULES.md](RULES.md) shows a failing example and the fix for each one.
+[docs/DATA_MODEL.md](docs/DATA_MODEL.md) diagrams how a rule is checked, fixed and verified.
 
 | Category | Rules | What it guards |
 |---|---|---|
-| Sentence | PG001, PG002 | How a sentence is laid out and how long it runs |
-| List | PG003, PG006, PG007, PG008, PG009 | A list hidden in running prose, promoted to a real markdown list |
-| Punctuation | PG004, PG005 | A glyph that reads as generated text |
+| Sentence | sentence-one-per-line, sentence-word-budget-exceeded | How a sentence is laid out and how long it runs |
+| List | list-semicolon-delimited-run, list-interpunct-joined-run, list-inline-enumeration-markers, list-comma-labelled-run, list-stacked-interpunct-runs | A list hidden in running prose, promoted to a real markdown list |
+| Punctuation | punctuation-em-dash-in-prose, punctuation-interpunct-in-prose | A glyph that reads as generated text |
 
 Every fix is verified before it is written.
 A fix that would change a word, url or code value is a bug and fails the run.
@@ -40,6 +45,33 @@ The reasoning behind each choice is recorded in [`adrs/`](adrs/index.md).
 Code blocks are exempt.
 Fences tagged `markdown` or `md` are the exception, since they hold templates whose body is audited recursively.
 
+## Plugins and local rules
+
+A project adds its own rules without forking this package.
+Both sources load on their own, with no config, and every run prints a line saying what it loaded.
+
+- **Local rules.** A `.js`, `.mjs`, `.ts` or `.mts` file in `.prose-gates/rules/` exports one rule, and its id is `local/` followed by the file name. TypeScript needs Bun or Node 22.18 or newer.
+- **Plugin packages.** A dependency named `prose-gates-plugin-name` or `@scope/prose-gates-plugin-name` loads under the namespace its own `meta.namespace` declares.
+- **New categories.** A plugin declares a category of its own, such as `frontmatter`, and its rules use it.
+- **Same treatment.** A plugin rule is switched off, given options and listed exactly like a built-in, and its fixer is verified like a built-in fixer.
+
+A config at the project root switches rules off and sets options.
+
+```json
+{
+  "rules": {
+    "list-semicolon-delimited-run": "off",
+    "local/frontmatter-description-word-budget": ["error", { "keys": ["description"], "maxWords": 40 }]
+  }
+}
+```
+
+Plugins are trusted code with no sandbox.
+Running the CLI in a repository runs that repository's local rules and declared plugins, so use `--no-plugins` on one you do not trust.
+[docs/plugins.md](docs/plugins.md) is the authoring guide, and [docs/engines.md](docs/engines.md) shows what the tree provides at each step of a check and a fix.
+[`examples/plugin-skills`](examples/plugin-skills) and [`examples/plugin-skills-typescript`](examples/plugin-skills-typescript) hold the same working plugin in JavaScript and TypeScript.
+It checks any `description` in a file's frontmatter at any depth, and has a fixer that rewrites a long one as a folded block.
+
 ## Consuming it
 
 Each meta repo declares this package and runs it through a `docs-ci` target.
@@ -49,7 +81,8 @@ bun add --dev @jpeakai/prose-gates
 ```
 
 npm works the same way, with `npm install --save-dev @jpeakai/prose-gates`.
-The library exports `checkMarkdown` and `fixMarkdown`.
+The library exports `checkMarkdown` and `fixMarkdown`, which return promises because a rule may be async.
+`@jpeakai/prose-gates/testing` exports the helpers a plugin's tests use.
 Bun imports the TypeScript source, and Node imports the bundle in `dist/`.
 
 Generated markdown is gated too.