@jpeakai/mermaidjs-lint 0.7.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -104
- package/dist/bin.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,29 +1,37 @@
|
|
|
1
|
-
#
|
|
1
|
+
# mermaidjs-lint
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
Deterministic checks and verified fixes for Mermaid diagrams in markdown.
|
|
3
|
+
Catch Mermaid diagrams in your markdown that fail to parse, turn unreadable in light or dark themes, or grow too big to follow.
|
|
5
4
|
|
|
6
|
-
**[Docs](https://jpeakai.github.io/jpai-mermaidjs-lint/)** | **[Rules](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/)** | **[Changelog](CHANGELOG.md)** | **[
|
|
5
|
+
**[Docs](https://jpeakai.github.io/jpai-mermaidjs-lint/)** | **[Rules](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/)** | **[Changelog](CHANGELOG.md)** | **[npm](https://www.npmjs.com/package/@jpeakai/mermaidjs-lint)**
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
This README, read on GitHub, describes the `main` branch.
|
|
10
|
-
A change on `main` that is not yet released is listed under `Unreleased` in the [changelog](CHANGELOG.md).
|
|
11
|
-
|
|
12
|
-
## Usage
|
|
7
|
+
## Lint your docs with one command
|
|
13
8
|
|
|
14
9
|
```sh
|
|
15
|
-
|
|
16
|
-
|
|
10
|
+
npx -y @jpeakai/mermaidjs-lint docs/
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
docs/architecture.md:6 contrast-text-below-aa classDef warn: text 1.43:1 < 4.5 (#ffffff on #ffd400)
|
|
15
|
+
docs/login.md:3-7 parse-diagram-unparseable sequenceDiagram did not parse (parser: mermaid-core) (its line numbers count within the diagram, not the file): Parse error on line 3: Expecting 'TXT', got 'NEWLINE'
|
|
16
|
+
docs/pipeline.md:3-41 complexity-node-count-acceptable-exceeded 37 nodes > 35 acceptable threshold
|
|
17
|
+
3 finding(s) in 3 file(s)
|
|
17
18
|
```
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
The run exits 1 while any finding remains, so it works as a CI gate.
|
|
21
|
+
|
|
22
|
+
## Fix unreadable label text and unclosed fences
|
|
23
|
+
|
|
24
|
+
Add `--fix` to apply the fixes that pass verification:
|
|
25
|
+
|
|
26
|
+
```diff
|
|
27
|
+
- classDef warn fill:#ffd400,color:#ffffff
|
|
28
|
+
+ classDef warn fill:#ffd400,color:#000000
|
|
29
|
+
```
|
|
23
30
|
|
|
24
|
-
|
|
31
|
+
A fix is kept only if the markdown around the diagrams is unchanged and each diagram reparses with the same node ids, subgraphs and counts.
|
|
32
|
+
Edge endpoints, edge labels and node text are not compared, so review the diff.
|
|
25
33
|
|
|
26
|
-
##
|
|
34
|
+
## Four tenets define the tool
|
|
27
35
|
|
|
28
36
|
Three tenets are guarantees about every diagram the tool passes, and the fourth is a commitment about the tool.
|
|
29
37
|
|
|
@@ -32,101 +40,28 @@ Three tenets are guarantees about every diagram the tool passes, and the fourth
|
|
|
32
40
|
- **Simple enough to follow.** Node count and visual complexity are scored against a density preset, so an oversized diagram is flagged to be split.
|
|
33
41
|
- **Extensible.** A plugin adds rules of your own, which run through the same config, fix engine and verification as the built-ins.
|
|
34
42
|
|
|
35
|
-
|
|
36
|
-
|---|---|
|
|
37
|
-
| Readable in light and dark | The contrast rules |
|
|
38
|
-
| Renders | The parse rules |
|
|
39
|
-
| Simple enough to follow | The complexity rules |
|
|
40
|
-
| Extensible | Local rules and plugin packages |
|
|
43
|
+
## Go further in the docs site
|
|
41
44
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
Every finding fails the run, and a rule you do not want is switched off in the config.
|
|
47
|
-
Node, edge and subgraph counts come from mermaid's own parsers.
|
|
48
|
-
Style directives are read line by line, so a style joined to other statements by a semicolon is not seen.
|
|
49
|
-
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.
|
|
50
|
-
The check holds the markdown outside the diagrams unchanged, and each diagram's type, node ids, subgraph names and counts, and whether it parses.
|
|
51
|
-
It does not compare edge endpoints, edge labels or node text, so review the diff a fix writes.
|
|
52
|
-
|
|
53
|
-
## Requirements and compatibility
|
|
54
|
-
|
|
55
|
-
- **Runtime:** Bun, or Node `>=20` as the `engines` field of `package.json` states.
|
|
56
|
-
- **Mermaid:** the parse and contrast rules use the `mermaid` package at exactly `11.17.2`, and `@mermaid-js/parser`, both installed with this package. The pin holds sequence diagram colours, which change between mermaid releases.
|
|
57
|
-
- **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.
|
|
58
|
-
|
|
59
|
-
`npm ls mermaid` in your project prints the mermaid version a run uses.
|
|
60
|
-
[Reference](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/#requirements-and-compatibility) lists which parser reads each diagram type.
|
|
61
|
-
|
|
62
|
-
## Configure and extend
|
|
63
|
-
|
|
64
|
-
- [Configure the rules](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/configure/): switch a rule off, change the complexity preset, set options.
|
|
65
|
-
- [Lint a MkDocs Material site](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/mkdocs/): score diagrams the way the theme renders them.
|
|
66
|
-
- [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.
|
|
67
|
-
- [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.
|
|
45
|
+
- [Get started](https://jpeakai.github.io/jpai-mermaidjs-lint/get-started/): run it, fix a diagram, and add the gate to your project.
|
|
46
|
+
- [Gate diagrams in CI](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/ci/) or [before each commit](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/pre-commit/).
|
|
47
|
+
- [Configure the rules](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/configure/), or [write a local rule](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/local-rule/).
|
|
68
48
|
|
|
69
49
|
## Use it from an AI agent
|
|
70
50
|
|
|
71
|
-
[`skills/mermaidjs-lint
|
|
72
|
-
|
|
73
|
-
The skill is the one file `SKILL.md`.
|
|
74
|
-
Its `evals/` folder holds deliberately failing fixtures for this repository's own tests, so never copy it.
|
|
75
|
-
For Claude Code, run these in your project:
|
|
51
|
+
The agent skill in [`skills/mermaidjs-lint/SKILL.md`](skills/mermaidjs-lint/SKILL.md) runs the tool, applies the safe fixes, and fixes the rest by judgement.
|
|
52
|
+
Copy it into a Claude Code project:
|
|
76
53
|
|
|
77
54
|
```sh
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
-o .claude/skills/mermaidjs-lint/SKILL.md
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
Use `~/.claude/skills/mermaidjs-lint` instead to use it in every project.
|
|
84
|
-
Another agent can follow `SKILL.md` as plain instructions.
|
|
85
|
-
[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.
|
|
86
|
-
|
|
87
|
-
## Library use
|
|
88
|
-
|
|
89
|
-
```ts
|
|
90
|
-
import { checkMarkdown, fixSource } from "@jpeakai/mermaidjs-lint";
|
|
91
|
-
|
|
92
|
-
const findings = await checkMarkdown(src, "README.md");
|
|
93
|
-
const fixed = await fixSource(src, "README.md");
|
|
55
|
+
curl -fsSL --create-dirs -o .claude/skills/mermaidjs-lint/SKILL.md \
|
|
56
|
+
https://raw.githubusercontent.com/jpeakai/jpai-mermaidjs-lint/main/skills/mermaidjs-lint/SKILL.md
|
|
94
57
|
```
|
|
95
58
|
|
|
96
|
-
|
|
97
|
-
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.
|
|
98
|
-
|
|
99
|
-
## Versioning
|
|
100
|
-
|
|
101
|
-
The package follows semantic versioning, and while it is at `0.x` a minor release may break the public surface.
|
|
102
|
-
[Versioning](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/#versioning) lists what that surface is.
|
|
103
|
-
[CHANGELOG.md](CHANGELOG.md) lists what changed in each release, and what is on `main` but not yet released.
|
|
104
|
-
|
|
105
|
-
## Security
|
|
106
|
-
|
|
107
|
-
A plugin is code that runs on your machine, and plugins load on their own once a project depends on them.
|
|
108
|
-
[SECURITY.md](SECURITY.md) covers the supported versions, the trust model and how to report a vulnerability privately.
|
|
109
|
-
|
|
110
|
-
## Support
|
|
111
|
-
|
|
112
|
-
Report a bug or ask a question in [GitHub issues](https://github.com/jpeakai/jpai-mermaidjs-lint/issues).
|
|
113
|
-
A bug report needs:
|
|
114
|
-
|
|
115
|
-
- The version, from `mermaidjs-lint --version`, or from `npm ls @jpeakai/mermaidjs-lint` on 0.1.1 and earlier.
|
|
116
|
-
- The command you ran.
|
|
117
|
-
- The diagram, or the smallest file that shows the problem.
|
|
118
|
-
- The output of the same command with `--json`.
|
|
119
|
-
|
|
120
|
-
## Origin
|
|
121
|
-
|
|
122
|
-
The checks port an earlier set of diagram-checking scripts, which measured complexity and contrast for Mermaid diagrams.
|
|
123
|
-
The package shape, the plugin mechanism and the fix verification follow [jpai-prose-gates](https://github.com/jpeakai/jpai-prose-gates).
|
|
124
|
-
The reasoning behind each choice is recorded in [`adrs/`](adrs/index.md).
|
|
125
|
-
|
|
126
|
-
## Contributing
|
|
59
|
+
## Runs on Bun or Node
|
|
127
60
|
|
|
128
|
-
|
|
61
|
+
It needs Bun, or Node `>=20`.
|
|
62
|
+
The package installs mermaid `11.17.2` to parse diagrams, and your host may draw with another version.
|
|
129
63
|
|
|
130
|
-
##
|
|
64
|
+
## Contribute
|
|
131
65
|
|
|
132
|
-
|
|
66
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) covers setup.
|
|
67
|
+
Licensed under [MIT](LICENSE).
|
package/dist/bin.js
CHANGED
|
@@ -9,7 +9,7 @@ import { parseArgs } from "node:util";
|
|
|
9
9
|
// package.json
|
|
10
10
|
var package_default = {
|
|
11
11
|
name: "@jpeakai/mermaidjs-lint",
|
|
12
|
-
version: "0.7.
|
|
12
|
+
version: "0.7.1",
|
|
13
13
|
type: "module",
|
|
14
14
|
description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
|
|
15
15
|
license: "MIT",
|
package/dist/index.js
CHANGED
|
@@ -2050,7 +2050,7 @@ import { parseArgs } from "node:util";
|
|
|
2050
2050
|
// package.json
|
|
2051
2051
|
var package_default = {
|
|
2052
2052
|
name: "@jpeakai/mermaidjs-lint",
|
|
2053
|
-
version: "0.7.
|
|
2053
|
+
version: "0.7.1",
|
|
2054
2054
|
type: "module",
|
|
2055
2055
|
description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
|
|
2056
2056
|
license: "MIT",
|