@jpeakai/mermaidjs-lint 0.1.1 → 0.3.0

package/README.md

@@ -3,7 +3,10 @@
 Diagrams in documentation should be readable.
 Deterministic checks and verified fixes for Mermaid diagrams in markdown.
 
-**[Rules](RULES.md)** | **[GitHub](https://github.com/jpeakai/jpai-mermaidjs-lint)** | **[npm](https://www.npmjs.com/package/@jpeakai/mermaidjs-lint)**
+**[Docs](https://jpeakai.github.io/jpai-mermaidjs-lint/)** | **[Rules](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/)** | **[Changelog](CHANGELOG.md)** | **[GitHub](https://github.com/jpeakai/jpai-mermaidjs-lint)** | **[npm](https://www.npmjs.com/package/@jpeakai/mermaidjs-lint)**
+
+This README and the docs site describe the `main` branch.
+A feature on `main` but not yet on npm is listed under `Unreleased` in the [changelog](CHANGELOG.md).
 
 ## Usage
 
@@ -12,73 +15,74 @@ bunx @jpeakai/mermaidjs-lint README.md docs/     # report findings, exit 1 if an
 npx -y @jpeakai/mermaidjs-lint --fix docs/       # apply every fix proven safe, report the rest
 ```
 
-A path is a `.mmd` file, a markdown file whose mermaid fences are checked, or a directory.
-A directory is walked for both, and it skips `node_modules`, `dist`, `tmp` and dot-directories.
+Pass your own paths: every path you name must exist, or the run stops with a usage error and exit 2.
+A `.mmd` or `.mermaid` file is read as one diagram, and any other file you name is read as markdown.
+A directory is walked for `.mmd`, `.mermaid`, `.md` and `.markdown` files.
+The walk skips dot-folders and any folder named `node_modules`, `vendor`, `dist`, `build`, `tmp` or `__pycache__`, at any depth.
+Installed as a dev dependency, the command is `mermaidjs-lint`, and `--help` lists every flag.
 
-Installed as a dev dependency, the command is `mermaidjs-lint`, and `--json` gives machine-readable output with a remediation for each finding.
+[Get started](https://jpeakai.github.io/jpai-mermaidjs-lint/get-started/) walks through a first run, a fix, and adding the check to a project.
 
-`--preset NAME` sets the density for every complexity rule, as `low`, `medium` or `high`.
-`--profile NAME` sets how contrast is read, as `auto`, `github` or `mkdocs-material`.
-`--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 four tenets
 
-## The rules
+Three tenets are guarantees about every diagram the tool passes, and the fourth is a commitment about the tool.
 
-Eleven rules in three categories.
-[RULES.md](RULES.md) shows a failing example for each one, and the fix where there is one.
-There is no warning level, so every finding fails the run.
-A rule you do not want is switched off in the config.
+- **Readable in light and dark.** Declared fills, label colours and borders are scored as the host draws them, on nodes, erDiagram rows and edge labels, in both themes.
+- **Renders.** Every diagram parses with the mermaid parsers this package ships, and every mermaid fence is closed.
+- **Simple enough to follow.** Node count and visual complexity are scored against a density preset, so an oversized diagram is flagged to be split.
+- **Extensible.** A plugin adds rules of your own, which run through the same config, fix engine and verification as the built-ins.
 
-| Category | Rules | What it guards |
-|---|---|---|
-| Parse | parse-diagram-unparseable, parse-fence-unterminated | Whether mermaid can read the diagram, and whether its fence is whole |
-| Complexity | complexity-node-count-hard-limit, complexity-node-count-cognitive-limit, complexity-node-count-acceptable-exceeded, complexity-visual-score-critical, complexity-visual-score-acceptable-exceeded, complexity-subgraph-nesting-too-deep | How much a reader must hold in mind at once |
-| Contrast | contrast-text-below-aa, contrast-border-below-ui-minimum, contrast-directive-unauditable | Whether labels and borders can be read against their fills |
+| Tenet | Delivered by |
+|---|---|
+| Readable in light and dark | The contrast rules |
+| Renders | The parse rules |
+| Simple enough to follow | The complexity rules |
+| Extensible | Local rules and plugin packages |
 
-Structure comes from mermaid's own parsers, never from patterns over the text.
-Every fix is verified by parsing the document again.
-A fix that would change the markdown or the structure of a diagram is refused, so the finding stays for a human.
-The reasoning behind each choice is recorded in [`adrs/`](adrs/index.md).
+The [concepts page](https://jpeakai.github.io/jpai-mermaidjs-lint/concepts/) states the limit of each tenet.
+`mermaidjs-lint --list-rules` prints every rule.
+The [rules page](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/) draws each one before and after `--fix`, and [RULES.md](RULES.md) holds the same examples as plain markdown.
 
-## Density presets
+Every finding fails the run, and a rule you do not want is switched off in the config.
+Node, edge and subgraph counts come from mermaid's own parsers.
+Style directives are read line by line, so a style joined to other statements by a semicolon is not seen.
+Every fix is verified by parsing the document again, and a fix that fails the check is refused, so the finding stays for a human.
+The check holds the markdown outside the diagrams unchanged, and each diagram's type, node ids, subgraph names and counts.
+It does not compare edge endpoints, edge labels or node text, so review the diff a fix writes.
 
-Complexity rules measure the nodes and a visual complexity score, and compare them with a preset.
+## Requirements and compatibility
 
-| Preset | Acceptable nodes | Cognitive limit | Hard limit |
-|---|---|---|---|
-| low-density | 12 | 20 | 35 |
-| medium-density | 20 | 35 | 60 |
-| high-density | 35 | 50 | 100 |
+- **Runtime:** Bun, or Node `>=20` as the `engines` field of `package.json` states.
+- **Mermaid:** the parse rules use the `mermaid` package, at `^11.14.0`, and `@mermaid-js/parser`, both installed with this package.
+- **Your host's mermaid may differ.** GitHub and other hosts draw diagrams with their own mermaid version. A diagram type newer than the host's may parse here and still fail to draw there.
 
-The default is `high-density`, which follows the research that 50 nodes is where a diagram becomes hard to read.
-Each threshold is also a rule option, such as `nodeAcceptable` or `vcsCritical`.
+`npm ls mermaid` in your project prints the mermaid version a run uses.
+[Reference](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/#requirements-and-compatibility) lists which parser reads each diagram type.
 
-## Plugins and local rules
+## Configure and extend
 
-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.
+- [Configure the rules](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/configure/): switch a rule off, change the complexity preset, set options.
+- [Lint a MkDocs Material site](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/mkdocs/): score diagrams the way the theme renders them.
+- [Write a local rule](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/local-rule/) or [publish a plugin package](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/plugin-package/): add rules of your own, which load with no config.
+- [Troubleshooting](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/troubleshooting/): a README that fails after adding `mkdocs.yml`, skipping a diagram, and other common questions.
 
-- **Local rules.** A `.js`, `.mjs`, `.ts` or `.mts` file in `.mermaidjs-lint/rules/` exports one rule, and its id is `local/` followed by the file name.
-- **Plugin packages.** A dependency named `mermaidjs-lint-plugin-name` or `@scope/mermaidjs-lint-plugin-name` loads under the namespace its own `meta.namespace` declares.
-- **New categories.** A plugin declares a category of its own, 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.
+## Use it from an AI agent
 
-A config at the project root switches rules off and sets options.
+[`skills/mermaidjs-lint/`](skills/mermaidjs-lint/SKILL.md) is an agent skill that runs the linter, applies the safe fixes, then fixes what remains by judgement.
+It is not in the npm package, so copy it from this repository.
+The skill is the one file `SKILL.md`.
+Its `evals/` folder holds deliberately failing fixtures for this repository's own tests, so never copy it.
+For Claude Code, run these in your project:
 
-```json
-{
-  "rules": {
-    "complexity-subgraph-nesting-too-deep": "off",
-    "complexity-node-count-acceptable-exceeded": ["error", { "preset": "medium" }],
-    "contrast-text-below-aa": ["error", { "profile": "mkdocs-material" }]
-  }
-}
+```sh
+mkdir -p .claude/skills/mermaidjs-lint
+curl -fsSL https://raw.githubusercontent.com/jpeakai/jpai-mermaidjs-lint/main/skills/mermaidjs-lint/SKILL.md \
+  -o .claude/skills/mermaidjs-lint/SKILL.md
 ```
 
-[docs/plugins.md](docs/plugins.md) is the guide to writing a rule.
+Use `~/.claude/skills/mermaidjs-lint` instead to use it in every project.
+Another agent can follow `SKILL.md` as plain instructions.
+[Agent evals](https://jpeakai.github.io/jpai-mermaidjs-lint/gallery/agent-evals/) shows how well agents fixed the failing fixtures it lists, and which skill revision they used.
 
 ## Library use
 
@@ -89,13 +93,40 @@ const findings = await checkMarkdown(src, "README.md");
 const fixed = await fixSource(src, "README.md");
 ```
 
-A plugin author tests a rule with `@jpeakai/mermaidjs-lint/testing`, which runs the same loader checks and verified fixer as a real run.
+These calls run the built-in rules only, and read no config file and no plugin.
+The [Library API](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/library-api/) page lists every export, and shows how to run with the config and plugins as the command does.
+
+## Versioning
+
+The package follows semantic versioning, and while it is at `0.x` a minor release may break the public surface.
+[Versioning](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/#versioning) lists what that surface is.
+[CHANGELOG.md](CHANGELOG.md) lists what changed in each release, and what is on `main` but not yet released.
+
+## Security
+
+A plugin is code that runs on your machine, and plugins load on their own once a project depends on them.
+[SECURITY.md](SECURITY.md) covers the supported versions, the trust model and how to report a vulnerability privately.
+
+## Support
+
+Report a bug or ask a question in [GitHub issues](https://github.com/jpeakai/jpai-mermaidjs-lint/issues).
+A bug report needs:
+
+- The version, from `mermaidjs-lint --version`, or from `npm ls @jpeakai/mermaidjs-lint` on 0.1.1 and earlier.
+- The command you ran.
+- The diagram, or the smallest file that shows the problem.
+- The output of the same command with `--json`.
 
 ## Origin
 
-The checks port the logic of the `mermaidjs-diagrams` skill scripts, which measured complexity and contrast for Mermaid diagrams.
+The checks port an earlier set of diagram-checking scripts, which measured complexity and contrast for Mermaid diagrams.
 The package shape, the plugin mechanism and the fix verification follow [jpai-prose-gates](https://github.com/jpeakai/jpai-prose-gates).
+The reasoning behind each choice is recorded in [`adrs/`](adrs/index.md).
 
 ## Contributing
 
 [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and how a change is accepted.
+
+## Licence
+
+MIT, as stated in [LICENSE](LICENSE).