@grethel-labs/excaliplant 0.2.0 → 0.3.6
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/CHANGELOG.md +100 -0
- package/README.md +14 -2
- package/SECURITY.md +4 -6
- package/index.mjs +4 -2
- package/package.json +5 -4
- package/src/layout/sequence_layout.mjs +36 -24
- package/src/model/diagram.mjs +4 -0
- package/src/parser/component_context.mjs +7 -4
- package/src/parser/engine.mjs +20 -5
- package/src/parser/plantuml.mjs +107 -9
- package/src/parser/plugins/component/connections.mjs +19 -2
- package/src/parser/sequence_context.mjs +9 -3
- package/src/parser/utils.mjs +30 -9
- package/src/render/canvas_svg.mjs +4 -3
- package/src/render/svg.mjs +10 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@grethel-labs/excaliplant` are documented in this
|
|
4
|
+
file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
5
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [0.3.1] - 2026-05-04
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- Dependabot PRs now automatically receive `release:patch` labels to ensure the
|
|
12
|
+
release version workflow can process them correctly.
|
|
13
|
+
- Auto-patch dependencies workflow now adds `release:patch` label to created/updated PRs.
|
|
14
|
+
- PR release version workflow detects Dependabot PRs and automatically adds
|
|
15
|
+
`release:patch` label if missing.
|
|
16
|
+
- Type-checking now narrows the component-context container stack via a proper
|
|
17
|
+
discriminated union, fixing strict null/undefined errors surfaced by
|
|
18
|
+
TypeScript 6.x.
|
|
19
|
+
- `declareParticipant` resolves the cached lookup once so its return type is a
|
|
20
|
+
non-nullable `Participant`, satisfying stricter type checking.
|
|
21
|
+
- Docs file-tree script imports `tree-node-cli` namespace-style and picks the
|
|
22
|
+
named export (v3+) or default (v1.x) at runtime, so the docs build works
|
|
23
|
+
across both major versions.
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- New `auto-rebase-prs.yml` workflow that automatically rebases open PRs
|
|
28
|
+
when main is updated, and adjusts version numbers if there are conflicts
|
|
29
|
+
from parallel PRs being merged.
|
|
30
|
+
|
|
31
|
+
## [0.3.0] - 2026-05-04
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- Repository-wide editing-agent instructions via `AGENTS.md`, with thin adapter
|
|
36
|
+
files for GitHub Copilot, Claude Code, Gemini CLI, Cursor, Windsurf, Cline,
|
|
37
|
+
and Roo Code. The adapters all point back to `AGENTS.md` so project rules stay
|
|
38
|
+
centralized for future automated editing workflows.
|
|
39
|
+
- A README notice clarifying that the repository was created almost entirely
|
|
40
|
+
with AI assistance and that use remains at the user's own risk under the MIT
|
|
41
|
+
License warranty disclaimer.
|
|
42
|
+
|
|
43
|
+
## [0.2.1] - 2026-05-03
|
|
44
|
+
|
|
45
|
+
### Security
|
|
46
|
+
|
|
47
|
+
- `excalidrawJsonToCanvasSvg`: HTML-escape the user-supplied `background`
|
|
48
|
+
option before interpolating it into the canvas `<rect>` `fill`
|
|
49
|
+
attribute. Previously a string like `'" onload="alert(1)'` could
|
|
50
|
+
break out of the attribute and inject arbitrary markup into the
|
|
51
|
+
emitted SVG. The escape uses the same routine as the rest of
|
|
52
|
+
`src/render/svg.mjs` (`escapeAttr`, now exported) and now also
|
|
53
|
+
escapes `>` for defence in depth.
|
|
54
|
+
- `parsePlantUml` gains opt-in resource limits
|
|
55
|
+
(`maxInputBytes`, `maxLines`, `maxNodes`, `maxEdges`) with sensible
|
|
56
|
+
defaults so the library API enforces the same safety bounds as the
|
|
57
|
+
CLI. `renderPlantUml({ limits })` forwards the option.
|
|
58
|
+
- CI permissions are now `contents: read` by default; only the
|
|
59
|
+
PR-docs auto-amend job re-asserts `contents: write`. The release
|
|
60
|
+
workflow additionally runs `typecheck`, `format:check`, an
|
|
61
|
+
`npm audit --omit=dev --audit-level=high`, and a pack + smoke
|
|
62
|
+
install before publishing.
|
|
63
|
+
|
|
64
|
+
### Fixed
|
|
65
|
+
|
|
66
|
+
- `slug()` keeps Unicode letters and digits instead of replacing
|
|
67
|
+
every non-ASCII character with `_`. Diagrams with German umlauts,
|
|
68
|
+
Japanese identifiers, etc. now resolve their connections correctly.
|
|
69
|
+
- `stripComment()` is now string-aware: an apostrophe inside a
|
|
70
|
+
`"..."` literal no longer truncates the line, so labels like
|
|
71
|
+
`"Bob 's service"` parse intact.
|
|
72
|
+
- Component connections that use bracket / paren / quoted shorthand
|
|
73
|
+
(`[Foo] --> [Bar]`, `(Use case A) --> (Use case B)`) now resolve
|
|
74
|
+
to the matching declared boxes regardless of capitalisation or
|
|
75
|
+
Unicode content.
|
|
76
|
+
- Sequence diagrams interleave notes between messages by declaration
|
|
77
|
+
order. Previously every note was placed below the last message,
|
|
78
|
+
losing temporal context.
|
|
79
|
+
|
|
80
|
+
### Added
|
|
81
|
+
|
|
82
|
+
- `parsePlantUml(text, { unknownLines: "warn" | "strict" })` for
|
|
83
|
+
diagnostics on lines that no plugin consumed (default behaviour
|
|
84
|
+
remains silent for backwards compatibility).
|
|
85
|
+
- `runEngine({ onUnknownLine })` callback so custom pipelines can
|
|
86
|
+
observe unrecognised input.
|
|
87
|
+
- `DEFAULT_PARSE_LIMITS` is exported from the top-level module and
|
|
88
|
+
from `./parser/plantuml`.
|
|
89
|
+
- `CHANGELOG.md` (this file) and a tightened `pre-commit` hook that
|
|
90
|
+
also runs `npm run typecheck`.
|
|
91
|
+
|
|
92
|
+
### Changed
|
|
93
|
+
|
|
94
|
+
- `prepublishOnly` now runs `npm test`, `npm run typecheck`,
|
|
95
|
+
`npm run format:check`, and `npm run build` (in addition to the
|
|
96
|
+
existing prepublish guard) before publishing.
|
|
97
|
+
|
|
98
|
+
## [0.2.0] - 2026-04
|
|
99
|
+
|
|
100
|
+
Initial public release on npm.
|
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
[](https://nodejs.org)
|
|
8
8
|
[](./LICENSE)
|
|
9
9
|
|
|
10
|
-
> PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. · **v0.
|
|
10
|
+
> PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. · **v0.3.6** · 86 tests · MIT
|
|
11
11
|
|
|
12
12
|
`@grethel-labs/excaliplant` takes PlantUML source, runs it through a plugin-based
|
|
13
13
|
parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
|
|
@@ -33,6 +33,13 @@ artefacts.
|
|
|
33
33
|
> [`docs/README.template.md.njk`](./docs/README.template.md.njk) and
|
|
34
34
|
> run `npm run build:docs`.
|
|
35
35
|
|
|
36
|
+
> **AI-generated project notice:** This repository, including source code,
|
|
37
|
+
> documentation, comments, and generated artefacts, was created almost entirely
|
|
38
|
+
> with AI assistance. The maintainer does not adopt every generated sentence,
|
|
39
|
+
> implementation detail, or artefact as a personal statement, endorsement, or
|
|
40
|
+
> guarantee. Review everything carefully and use the code at your own risk; the
|
|
41
|
+
> MIT License warranty disclaimer applies.
|
|
42
|
+
|
|
36
43
|
---
|
|
37
44
|
|
|
38
45
|
## How to use
|
|
@@ -102,7 +109,7 @@ Lower-level entry points are also exported:
|
|
|
102
109
|
npm test
|
|
103
110
|
```
|
|
104
111
|
|
|
105
|
-
Ships with **
|
|
112
|
+
Ships with **86 tests** across functional, edge-case,
|
|
106
113
|
security (XSS / ReDoS / prototype-pollution), and self-introspection
|
|
107
114
|
suites.
|
|
108
115
|
|
|
@@ -237,6 +244,11 @@ excaliplant
|
|
|
237
244
|
│ ├── plantuml.test.mjs
|
|
238
245
|
│ ├── security.test.mjs
|
|
239
246
|
│ └── self_introspection.test.mjs
|
|
247
|
+
├── AGENTS.md
|
|
248
|
+
├── CHANGELOG.md
|
|
249
|
+
├── CLAUDE.md
|
|
250
|
+
├── CONTRIBUTING.md
|
|
251
|
+
├── GEMINI.md
|
|
240
252
|
├── LICENSE
|
|
241
253
|
├── README.md
|
|
242
254
|
├── SECURITY.md
|
package/SECURITY.md
CHANGED
|
@@ -10,12 +10,10 @@ filesystem isolation.
|
|
|
10
10
|
|
|
11
11
|
## Supported versions
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
| ------- | ------------------ |
|
|
18
|
-
| `0.1.x` | :white_check_mark: |
|
|
13
|
+
The **current release on npm — including the latest patch — is fully
|
|
14
|
+
supported**. Older versions may still work, but can show reduced
|
|
15
|
+
functionality, missing fixes, or unaddressed advisories. Please upgrade
|
|
16
|
+
to the latest version before reporting a vulnerability.
|
|
19
17
|
|
|
20
18
|
## Reporting a vulnerability
|
|
21
19
|
|
package/index.mjs
CHANGED
|
@@ -53,7 +53,7 @@ import { excalidrawToSvg } from "./src/render/svg.mjs";
|
|
|
53
53
|
import { excalidrawJsonToCanvasSvg } from "./src/render/canvas_svg.mjs";
|
|
54
54
|
import { svgToPng } from "./src/render/png.mjs";
|
|
55
55
|
|
|
56
|
-
export { parsePlantUml } from "./src/parser/plantuml.mjs";
|
|
56
|
+
export { parsePlantUml, DEFAULT_PARSE_LIMITS } from "./src/parser/plantuml.mjs";
|
|
57
57
|
export { layoutDiagram } from "./src/layout/elk_layout.mjs";
|
|
58
58
|
export { exportDiagram } from "./src/render/excalidraw.mjs";
|
|
59
59
|
export { excalidrawToSvg } from "./src/render/svg.mjs";
|
|
@@ -156,13 +156,15 @@ export class RenderResult {
|
|
|
156
156
|
* @param {string} [opts.sourceLabel] Forwarded to the renderer's
|
|
157
157
|
* appState.name.
|
|
158
158
|
* @param {() => number} [opts.rng] Optional deterministic RNG.
|
|
159
|
+
* @param {Partial<import("./src/parser/plantuml.mjs").DEFAULT_PARSE_LIMITS>} [opts.limits]
|
|
160
|
+
* Optional resource limits forwarded to {@link parsePlantUml}.
|
|
159
161
|
* @returns {RenderResult} Thenable wrapping the Excalidraw
|
|
160
162
|
* JSON document.
|
|
161
163
|
*/
|
|
162
164
|
export function renderPlantUml(plantuml, opts = {}) {
|
|
163
165
|
return new RenderResult(
|
|
164
166
|
(async () => {
|
|
165
|
-
const diagram = parsePlantUml(plantuml);
|
|
167
|
+
const diagram = parsePlantUml(plantuml, { limits: opts.limits });
|
|
166
168
|
await layoutDiagram(diagram);
|
|
167
169
|
return exportDiagram(diagram, {
|
|
168
170
|
sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grethel-labs/excaliplant",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.6",
|
|
4
4
|
"description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.mjs",
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
"src/",
|
|
14
14
|
"assets/fonts/",
|
|
15
15
|
"README.md",
|
|
16
|
+
"CHANGELOG.md",
|
|
16
17
|
"LICENSE",
|
|
17
18
|
"SECURITY.md",
|
|
18
19
|
"THIRD_PARTY_NOTICES.md"
|
|
@@ -40,7 +41,7 @@
|
|
|
40
41
|
"format": "prettier --write .",
|
|
41
42
|
"format:check": "prettier --check .",
|
|
42
43
|
"prepare": "husky && node scripts/setup-merge-drivers.mjs",
|
|
43
|
-
"prepublishOnly": "node scripts/prepublish-guard.mjs && npm test && npm run build"
|
|
44
|
+
"prepublishOnly": "node scripts/prepublish-guard.mjs && npm test && npm run typecheck && npm run format:check && npm run build"
|
|
44
45
|
},
|
|
45
46
|
"lint-staged": {
|
|
46
47
|
"*.{mjs,js,cjs,ts,json,yml,yaml,md}": "prettier --write"
|
|
@@ -81,8 +82,8 @@
|
|
|
81
82
|
"lint-staged": "^16.4.0",
|
|
82
83
|
"nunjucks": "^3.2.4",
|
|
83
84
|
"prettier": "^3.8.3",
|
|
84
|
-
"tree-node-cli": "^
|
|
85
|
+
"tree-node-cli": "^3.0.0",
|
|
85
86
|
"typedoc": "^0.28.19",
|
|
86
|
-
"typescript": "^
|
|
87
|
+
"typescript": "^6.0.3"
|
|
87
88
|
}
|
|
88
89
|
}
|
|
@@ -58,19 +58,20 @@ export function layoutSequenceDiagram(diagram) {
|
|
|
58
58
|
for (const p of diagram.participants) p.lifelineTop = lifelineTop;
|
|
59
59
|
|
|
60
60
|
// 3. Walk messages and notes in their declaration order, assigning y.
|
|
61
|
-
//
|
|
62
|
-
//
|
|
63
|
-
//
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
m.
|
|
67
|
-
|
|
68
|
-
|
|
61
|
+
// Both message and note objects carry a `seq` index assigned by the
|
|
62
|
+
// sequence context; we merge the two streams on that field so notes
|
|
63
|
+
// appear at the temporal position they were declared at, instead of
|
|
64
|
+
// being dumped at the bottom of the diagram.
|
|
65
|
+
const timeline = [
|
|
66
|
+
...diagram.messages.map((m) => ({ kind: "msg", item: m, seq: m.seq ?? Infinity })),
|
|
67
|
+
...diagram.notes.map((n) => ({ kind: "note", item: n, seq: n.seq ?? Infinity })),
|
|
68
|
+
];
|
|
69
|
+
// Stable sort by declaration index. Items without a `seq` (e.g.
|
|
70
|
+
// programmatically-built diagrams) keep their relative order at the
|
|
71
|
+
// tail.
|
|
72
|
+
timeline.sort((a, b) => a.seq - b.seq);
|
|
69
73
|
|
|
70
|
-
//
|
|
71
|
-
// after the last message. This is a pragmatic placement; a future
|
|
72
|
-
// pass could weave them into the message timeline based on parser
|
|
73
|
-
// index.
|
|
74
|
+
// Pre-size notes so we know their height before assigning y.
|
|
74
75
|
for (const n of diagram.notes) {
|
|
75
76
|
const lines = n.text.split("\n");
|
|
76
77
|
n.width = Math.max(
|
|
@@ -78,20 +79,31 @@ export function layoutSequenceDiagram(diagram) {
|
|
|
78
79
|
Math.max(...lines.map((l) => measureLine(l, FONT.sizeDescription).width)) + NOTE_PAD * 2,
|
|
79
80
|
);
|
|
80
81
|
n.height = lines.length * FONT.sizeDescription * FONT.lineHeight + NOTE_PAD * 2;
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
let y = lifelineTop + MESSAGE_FIRST_Y;
|
|
85
|
+
for (const entry of timeline) {
|
|
86
|
+
if (entry.kind === "msg") {
|
|
87
|
+
const m = /** @type {import("../model/diagram.mjs").Message} */ (entry.item);
|
|
88
|
+
m.y = y;
|
|
89
|
+
y += m.isSelf ? SELF_HEIGHT + MESSAGE_GAP : MESSAGE_GAP;
|
|
89
90
|
} else {
|
|
90
|
-
|
|
91
|
-
n.
|
|
91
|
+
const n = /** @type {import("../model/diagram.mjs").SequenceNote} */ (entry.item);
|
|
92
|
+
if (n.side === "over" && n.target2) {
|
|
93
|
+
const x1 = Math.min(n.target.x, n.target2.x);
|
|
94
|
+
const x2 = Math.max(n.target.x, n.target2.x);
|
|
95
|
+
n.x = (x1 + x2) / 2 - n.width / 2;
|
|
96
|
+
} else if (n.side === "left") {
|
|
97
|
+
n.x = n.target.x - n.target.headWidth / 2 - n.width - NOTE_GAP;
|
|
98
|
+
} else if (n.side === "right") {
|
|
99
|
+
n.x = n.target.x + n.target.headWidth / 2 + NOTE_GAP;
|
|
100
|
+
} else {
|
|
101
|
+
// over single
|
|
102
|
+
n.x = n.target.x - n.width / 2;
|
|
103
|
+
}
|
|
104
|
+
n.y = y;
|
|
105
|
+
y += n.height + NOTE_GAP;
|
|
92
106
|
}
|
|
93
|
-
n.y = y;
|
|
94
|
-
y += n.height + NOTE_GAP;
|
|
95
107
|
}
|
|
96
108
|
|
|
97
109
|
const lifelineBottom = y + BOTTOM_MARGIN;
|
package/src/model/diagram.mjs
CHANGED
|
@@ -371,6 +371,8 @@ export class Message {
|
|
|
371
371
|
this.startArrowhead = startArrowhead;
|
|
372
372
|
this.endArrowhead = endArrowhead;
|
|
373
373
|
this.y = 0;
|
|
374
|
+
/** Declaration order index across messages + notes. */
|
|
375
|
+
this.seq = -1;
|
|
374
376
|
}
|
|
375
377
|
/** @returns {boolean} `true` when sender and receiver are the same lifeline. */
|
|
376
378
|
get isSelf() {
|
|
@@ -402,6 +404,8 @@ export class SequenceNote {
|
|
|
402
404
|
this.y = 0;
|
|
403
405
|
this.width = 0;
|
|
404
406
|
this.height = 0;
|
|
407
|
+
/** Declaration order index across messages + notes. */
|
|
408
|
+
this.seq = -1;
|
|
405
409
|
}
|
|
406
410
|
}
|
|
407
411
|
|
|
@@ -29,7 +29,7 @@ import { planeColor, subplaneColor } from "../style/colors.mjs";
|
|
|
29
29
|
*/
|
|
30
30
|
export function createComponentContext() {
|
|
31
31
|
const diagram = new Diagram();
|
|
32
|
-
/** @type {Array<{kind:'plane'
|
|
32
|
+
/** @type {Array<{kind:'plane', plane:Plane, id:string} | {kind:'subplane', subplane:Subplane, id:string}>} */
|
|
33
33
|
const stack = [];
|
|
34
34
|
const planes = new Map();
|
|
35
35
|
const subplanes = new Map();
|
|
@@ -58,7 +58,8 @@ export function createComponentContext() {
|
|
|
58
58
|
|
|
59
59
|
const findPlane = () => {
|
|
60
60
|
for (let i = stack.length - 1; i >= 0; i--) {
|
|
61
|
-
|
|
61
|
+
const entry = stack[i];
|
|
62
|
+
if (entry.kind === "plane") return entry.plane;
|
|
62
63
|
}
|
|
63
64
|
return null;
|
|
64
65
|
};
|
|
@@ -89,9 +90,11 @@ export function createComponentContext() {
|
|
|
89
90
|
planes.set(id, plane);
|
|
90
91
|
stack.push({ kind: "plane", plane, id });
|
|
91
92
|
} else {
|
|
92
|
-
|
|
93
|
+
// findPlane is non-null here because the first stack entry
|
|
94
|
+
// is always a plane (openContainer with empty stack pushes one).
|
|
95
|
+
const parentPlane = /** @type {Plane} */ (findPlane() ?? ensureFloatingPlane());
|
|
93
96
|
const sub = new Subplane({ id, title, kind });
|
|
94
|
-
if (parentPlane
|
|
97
|
+
if (parentPlane.color) sub.color = subplaneColor(parentPlane.color);
|
|
95
98
|
parentPlane.addSubplane(sub);
|
|
96
99
|
subplanes.set(id, sub);
|
|
97
100
|
stack.push({ kind: "subplane", subplane: sub, id });
|
package/src/parser/engine.mjs
CHANGED
|
@@ -52,28 +52,41 @@ import { stripComment, ALWAYS_SKIP } from "./utils.mjs";
|
|
|
52
52
|
* @param {Record<string, any>} args.ctx Mutable context object. Plugins
|
|
53
53
|
* attach state here; the engine never
|
|
54
54
|
* reads it directly.
|
|
55
|
+
* @param {(info: {line: string, index: number}) => void} [args.onUnknownLine]
|
|
56
|
+
* Optional callback invoked for every non-skip, non-empty line that
|
|
57
|
+
* no plugin consumed. Useful for `strict`/`diagnostics` modes; the
|
|
58
|
+
* default behaviour (silent ignore) is preserved when omitted.
|
|
55
59
|
* @returns {object} Whatever `ctx.result` exposes —
|
|
56
60
|
* typically a `Diagram` /
|
|
57
61
|
* `SequenceDiagram` instance.
|
|
58
62
|
* @public
|
|
59
63
|
*/
|
|
60
|
-
export function runEngine({ lines, plugins, ctx }) {
|
|
64
|
+
export function runEngine({ lines, plugins, ctx, onUnknownLine }) {
|
|
61
65
|
/** @type {PluginBlock | null} */
|
|
62
66
|
let block = null;
|
|
67
|
+
let index = 0;
|
|
63
68
|
for (const raw of lines) {
|
|
64
69
|
const line = stripComment(raw).trim();
|
|
65
70
|
|
|
66
71
|
if (block) {
|
|
67
72
|
if (block.tryEnd(line, ctx)) {
|
|
68
73
|
block = null;
|
|
74
|
+
index++;
|
|
69
75
|
continue;
|
|
70
76
|
}
|
|
71
77
|
block.onLine(line, ctx);
|
|
78
|
+
index++;
|
|
72
79
|
continue;
|
|
73
80
|
}
|
|
74
81
|
|
|
75
|
-
if (!line)
|
|
76
|
-
|
|
82
|
+
if (!line) {
|
|
83
|
+
index++;
|
|
84
|
+
continue;
|
|
85
|
+
}
|
|
86
|
+
if (ALWAYS_SKIP.some((re) => re.test(line))) {
|
|
87
|
+
index++;
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
77
90
|
|
|
78
91
|
let consumed = false;
|
|
79
92
|
for (const p of plugins) {
|
|
@@ -90,8 +103,10 @@ export function runEngine({ lines, plugins, ctx }) {
|
|
|
90
103
|
break;
|
|
91
104
|
}
|
|
92
105
|
}
|
|
93
|
-
|
|
94
|
-
|
|
106
|
+
if (!consumed && typeof onUnknownLine === "function") {
|
|
107
|
+
onUnknownLine({ line, index });
|
|
108
|
+
}
|
|
109
|
+
index++;
|
|
95
110
|
}
|
|
96
111
|
ctx.finalize?.();
|
|
97
112
|
return ctx.result;
|
package/src/parser/plantuml.mjs
CHANGED
|
@@ -95,6 +95,21 @@ export const DEFAULT_SEQUENCE_PLUGINS = [
|
|
|
95
95
|
messagePlugin,
|
|
96
96
|
];
|
|
97
97
|
|
|
98
|
+
/**
|
|
99
|
+
* Default upper bounds for `parsePlantUml`. Callers can override any
|
|
100
|
+
* of these via the `limits` option. The defaults are generous (10 MiB
|
|
101
|
+
* source, 100k lines, 10k boxes/edges) so legitimate large diagrams
|
|
102
|
+
* still parse, but malicious or runaway inputs fail fast instead of
|
|
103
|
+
* exhausting memory.
|
|
104
|
+
* @public
|
|
105
|
+
*/
|
|
106
|
+
export const DEFAULT_PARSE_LIMITS = Object.freeze({
|
|
107
|
+
maxInputBytes: 10 * 1024 * 1024,
|
|
108
|
+
maxLines: 100_000,
|
|
109
|
+
maxNodes: 10_000,
|
|
110
|
+
maxEdges: 10_000,
|
|
111
|
+
});
|
|
112
|
+
|
|
98
113
|
/**
|
|
99
114
|
* Parse a PlantUML source string into the input-agnostic diagram model.
|
|
100
115
|
* The parser auto-detects sequence vs. component syntax via the
|
|
@@ -105,6 +120,14 @@ export const DEFAULT_SEQUENCE_PLUGINS = [
|
|
|
105
120
|
* @param {{component?: any[], sequence?: any[]}} [opts.plugins]
|
|
106
121
|
* Override the default plugin lists. Useful for adding support for
|
|
107
122
|
* unsupported PlantUML constructs without forking the library.
|
|
123
|
+
* @param {Partial<typeof DEFAULT_PARSE_LIMITS>} [opts.limits]
|
|
124
|
+
* Override one or more resource limits. Anything omitted keeps the
|
|
125
|
+
* default. Pass `null`/`Infinity` to disable a particular limit.
|
|
126
|
+
* @param {"silent"|"warn"|"strict"} [opts.unknownLines]
|
|
127
|
+
* How to handle PlantUML lines that no plugin consumes. `silent`
|
|
128
|
+
* (the default, preserves existing behaviour) drops them. `warn`
|
|
129
|
+
* emits a `console.warn` per line. `strict` throws a `SyntaxError`
|
|
130
|
+
* listing every unknown line.
|
|
108
131
|
* @returns {import("../model/diagram.mjs").Diagram
|
|
109
132
|
* | import("../model/diagram.mjs").SequenceDiagram}
|
|
110
133
|
* @public
|
|
@@ -112,24 +135,99 @@ export const DEFAULT_SEQUENCE_PLUGINS = [
|
|
|
112
135
|
export function parsePlantUml(text, opts = {}) {
|
|
113
136
|
const componentPlugins = opts.plugins?.component ?? DEFAULT_COMPONENT_PLUGINS;
|
|
114
137
|
const sequencePlugins = opts.plugins?.sequence ?? DEFAULT_SEQUENCE_PLUGINS;
|
|
138
|
+
const limits = { ...DEFAULT_PARSE_LIMITS, ...(opts.limits || {}) };
|
|
139
|
+
const unknownMode = opts.unknownLines ?? "silent";
|
|
140
|
+
|
|
141
|
+
if (typeof text !== "string") {
|
|
142
|
+
throw new TypeError("parsePlantUml: `text` must be a string");
|
|
143
|
+
}
|
|
144
|
+
const byteLen = Buffer.byteLength(text, "utf8");
|
|
145
|
+
if (Number.isFinite(limits.maxInputBytes) && byteLen > limits.maxInputBytes) {
|
|
146
|
+
throw new RangeError(
|
|
147
|
+
`parsePlantUml: input is ${byteLen} bytes, exceeds maxInputBytes=${limits.maxInputBytes}`,
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
const lines = text.split(/\r?\n/);
|
|
151
|
+
if (Number.isFinite(limits.maxLines) && lines.length > limits.maxLines) {
|
|
152
|
+
throw new RangeError(
|
|
153
|
+
`parsePlantUml: input has ${lines.length} lines, exceeds maxLines=${limits.maxLines}`,
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** @type {Array<{line:string,index:number}>} */
|
|
158
|
+
const unknown = [];
|
|
159
|
+
const onUnknownLine =
|
|
160
|
+
unknownMode === "silent"
|
|
161
|
+
? undefined
|
|
162
|
+
: (/** @type {{line:string,index:number}} */ info) => {
|
|
163
|
+
unknown.push(info);
|
|
164
|
+
if (unknownMode === "warn") {
|
|
165
|
+
console.warn(`parsePlantUml: unknown line ${info.index + 1}: ${info.line}`);
|
|
166
|
+
}
|
|
167
|
+
};
|
|
115
168
|
|
|
169
|
+
let diagram;
|
|
116
170
|
if (looksLikeSequence(text)) {
|
|
117
|
-
|
|
171
|
+
diagram = /** @type {import("../model/diagram.mjs").SequenceDiagram} */ (
|
|
118
172
|
runEngine({
|
|
119
|
-
lines
|
|
173
|
+
lines,
|
|
120
174
|
plugins: sequencePlugins,
|
|
121
175
|
ctx: createSequenceContext(),
|
|
176
|
+
onUnknownLine,
|
|
122
177
|
})
|
|
123
178
|
);
|
|
179
|
+
} else {
|
|
180
|
+
diagram = /** @type {import("../model/diagram.mjs").Diagram} */ (
|
|
181
|
+
runEngine({
|
|
182
|
+
lines: explodeBraces(lines),
|
|
183
|
+
plugins: componentPlugins,
|
|
184
|
+
ctx: createComponentContext(),
|
|
185
|
+
onUnknownLine,
|
|
186
|
+
})
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
if (unknownMode === "strict" && unknown.length) {
|
|
190
|
+
const detail = unknown
|
|
191
|
+
.slice(0, 10)
|
|
192
|
+
.map((u) => ` line ${u.index + 1}: ${u.line}`)
|
|
193
|
+
.join("\n");
|
|
194
|
+
const more = unknown.length > 10 ? `\n ...and ${unknown.length - 10} more` : "";
|
|
195
|
+
throw new SyntaxError(`parsePlantUml: ${unknown.length} unknown line(s):\n${detail}${more}`);
|
|
124
196
|
}
|
|
197
|
+
enforceModelLimits(diagram, limits);
|
|
198
|
+
return diagram;
|
|
199
|
+
}
|
|
125
200
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
201
|
+
/**
|
|
202
|
+
* Walk the parsed model and reject diagrams that exceed `limits`.
|
|
203
|
+
* Counts boxes (incl. notes) across all planes/subplanes and the
|
|
204
|
+
* connection list. Sequence diagrams are bounded by participant +
|
|
205
|
+
* message + note counts.
|
|
206
|
+
* @param {any} diagram Parsed model.
|
|
207
|
+
* @param {{maxNodes:number, maxEdges:number}} limits Effective limits.
|
|
208
|
+
*/
|
|
209
|
+
function enforceModelLimits(diagram, limits) {
|
|
210
|
+
let nodes = 0;
|
|
211
|
+
let edges = 0;
|
|
212
|
+
if (Array.isArray(diagram?.planes)) {
|
|
213
|
+
for (const plane of diagram.planes) {
|
|
214
|
+
nodes += plane.allBoxes?.length ?? plane.boxes?.length ?? 0;
|
|
215
|
+
}
|
|
216
|
+
edges = diagram.connections?.length ?? 0;
|
|
217
|
+
} else {
|
|
218
|
+
nodes = (diagram?.participants?.length ?? 0) + (diagram?.notes?.length ?? 0);
|
|
219
|
+
edges = diagram?.messages?.length ?? 0;
|
|
220
|
+
}
|
|
221
|
+
if (Number.isFinite(limits.maxNodes) && nodes > limits.maxNodes) {
|
|
222
|
+
throw new RangeError(
|
|
223
|
+
`parsePlantUml: diagram has ${nodes} nodes, exceeds maxNodes=${limits.maxNodes}`,
|
|
224
|
+
);
|
|
225
|
+
}
|
|
226
|
+
if (Number.isFinite(limits.maxEdges) && edges > limits.maxEdges) {
|
|
227
|
+
throw new RangeError(
|
|
228
|
+
`parsePlantUml: diagram has ${edges} edges, exceeds maxEdges=${limits.maxEdges}`,
|
|
229
|
+
);
|
|
230
|
+
}
|
|
133
231
|
}
|
|
134
232
|
|
|
135
233
|
// Sequence-only keywords trigger the sequence pipeline. `actor` and
|
|
@@ -4,11 +4,26 @@
|
|
|
4
4
|
// decoded by `classifyArrow()`; to support a new arrow operator just
|
|
5
5
|
// extend that classifier.
|
|
6
6
|
|
|
7
|
-
import { classifyArrow, unescapeLabel } from "../../utils.mjs";
|
|
7
|
+
import { classifyArrow, slug, unescapeLabel } from "../../utils.mjs";
|
|
8
8
|
|
|
9
9
|
const CONNECTION_LINE =
|
|
10
10
|
/^(\S+)\s+([-.*o<|>]+(?:up|down|left|right|UP|DOWN|LEFT|RIGHT)?[-.*o<|>]*)\s+(\S+)(?:\s*:\s*(.+))?$/;
|
|
11
11
|
|
|
12
|
+
/**
|
|
13
|
+
* Normalise a connection endpoint so that bracket / paren shorthands
|
|
14
|
+
* (`[Foo]`, `(Use case)`) and quoted labels resolve to the same
|
|
15
|
+
* identifier the corresponding shape declaration uses.
|
|
16
|
+
* @param {string} raw Raw token captured by the connection regex.
|
|
17
|
+
* @returns {string} Identifier suitable for the box-id lookup table.
|
|
18
|
+
*/
|
|
19
|
+
function normaliseEndpoint(raw) {
|
|
20
|
+
let s = raw.trim();
|
|
21
|
+
if (s.startsWith("[") && s.endsWith("]")) return slug(s.slice(1, -1));
|
|
22
|
+
if (s.startsWith("(") && s.endsWith(")")) return slug(s.slice(1, -1));
|
|
23
|
+
if (s.startsWith('"') && s.endsWith('"')) return slug(s.slice(1, -1));
|
|
24
|
+
return s;
|
|
25
|
+
}
|
|
26
|
+
|
|
12
27
|
/**
|
|
13
28
|
* Generic component-style connection: `A op B [: label]`. All arrow
|
|
14
29
|
* flavours are decoded by `classifyArrow()` — extend that to support
|
|
@@ -20,9 +35,11 @@ export const connectionPlugin = {
|
|
|
20
35
|
tryLine(line, ctx) {
|
|
21
36
|
const m = line.match(CONNECTION_LINE);
|
|
22
37
|
if (!m) return false;
|
|
23
|
-
const [,
|
|
38
|
+
const [, rawFrom, op, rawTo, label] = m;
|
|
24
39
|
const arrow = classifyArrow(op);
|
|
25
40
|
if (!arrow) return false;
|
|
41
|
+
const fromId = normaliseEndpoint(rawFrom);
|
|
42
|
+
const toId = normaliseEndpoint(rawTo);
|
|
26
43
|
ctx.queueConnection({
|
|
27
44
|
fromId,
|
|
28
45
|
toId,
|
|
@@ -23,6 +23,7 @@ export function createSequenceContext() {
|
|
|
23
23
|
const diagram = new SequenceDiagram();
|
|
24
24
|
let messageCounter = 0;
|
|
25
25
|
let noteCounter = 0;
|
|
26
|
+
let timelineCounter = 0;
|
|
26
27
|
|
|
27
28
|
const ctx = {
|
|
28
29
|
get result() {
|
|
@@ -66,7 +67,8 @@ export function createSequenceContext() {
|
|
|
66
67
|
stereotype = "",
|
|
67
68
|
},
|
|
68
69
|
) {
|
|
69
|
-
|
|
70
|
+
const existing = diagram.participantById(id);
|
|
71
|
+
if (existing) return existing;
|
|
70
72
|
const p = new Participant({ id, title, shape, stereotype });
|
|
71
73
|
diagram.addParticipant(p);
|
|
72
74
|
return p;
|
|
@@ -86,14 +88,18 @@ export function createSequenceContext() {
|
|
|
86
88
|
* @param {any} spec Plugin-built message record (without id).
|
|
87
89
|
*/
|
|
88
90
|
addMessage(/** @type {any} */ spec) {
|
|
89
|
-
|
|
91
|
+
const msg = new Message({ id: ctx.nextMessageId(), ...spec });
|
|
92
|
+
msg.seq = timelineCounter++;
|
|
93
|
+
diagram.addMessage(msg);
|
|
90
94
|
},
|
|
91
95
|
/**
|
|
92
96
|
* Append a new note to the diagram (id is auto-assigned).
|
|
93
97
|
* @param {any} spec Plugin-built note record (without id).
|
|
94
98
|
*/
|
|
95
99
|
addNote(/** @type {any} */ spec) {
|
|
96
|
-
|
|
100
|
+
const note = new SequenceNote({ id: ctx.nextNoteId(), ...spec });
|
|
101
|
+
note.seq = timelineCounter++;
|
|
102
|
+
diagram.addNote(note);
|
|
97
103
|
},
|
|
98
104
|
};
|
|
99
105
|
return ctx;
|
package/src/parser/utils.mjs
CHANGED
|
@@ -44,10 +44,23 @@ export const ALWAYS_SKIP = [
|
|
|
44
44
|
* @public
|
|
45
45
|
*/
|
|
46
46
|
export function stripComment(line) {
|
|
47
|
-
// PlantUML: ' starts a line comment
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
47
|
+
// PlantUML: `'` starts a line comment, but inside a `"..."` string
|
|
48
|
+
// literal the apostrophe is just a regular character. Walk the line
|
|
49
|
+
// tracking quote state so labels like `"Bob 's service"` survive.
|
|
50
|
+
let inQuotes = false;
|
|
51
|
+
for (let i = 0; i < line.length; i++) {
|
|
52
|
+
const ch = line[i];
|
|
53
|
+
if (ch === '"') {
|
|
54
|
+
inQuotes = !inQuotes;
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
if (inQuotes) continue;
|
|
58
|
+
if (ch === "'") {
|
|
59
|
+
if (i === 0) return "";
|
|
60
|
+
const prev = line[i - 1];
|
|
61
|
+
if (/\s/.test(prev)) return line.slice(0, i);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
51
64
|
return line;
|
|
52
65
|
}
|
|
53
66
|
|
|
@@ -64,17 +77,25 @@ export function stripQuotes(s) {
|
|
|
64
77
|
}
|
|
65
78
|
|
|
66
79
|
/**
|
|
67
|
-
* Convert any string to an identifier-safe slug
|
|
80
|
+
* Convert any string to an identifier-safe slug. Preserves Unicode
|
|
81
|
+
* letters and digits (e.g. `ümlaut`, `日本`) while collapsing every
|
|
82
|
+
* other character to `_`. Falls back to a hashed identifier if the
|
|
83
|
+
* input has no letters/digits at all so that connections never lose
|
|
84
|
+
* their endpoint id.
|
|
68
85
|
*
|
|
69
86
|
* @param {string} s Free-form text to sluggify.
|
|
70
87
|
* @returns {string} Lower-case, underscore-separated identifier.
|
|
71
88
|
* @public
|
|
72
89
|
*/
|
|
73
90
|
export function slug(s) {
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
91
|
+
const raw = String(s).toLowerCase();
|
|
92
|
+
const cleaned = raw.replace(/[^\p{L}\p{N}]+/gu, "_").replace(/^_+|_+$/g, "");
|
|
93
|
+
if (cleaned) return cleaned;
|
|
94
|
+
// No letters/digits at all – derive a stable fallback so that
|
|
95
|
+
// `[***]` and similar still produce a usable id.
|
|
96
|
+
let h = 0;
|
|
97
|
+
for (let i = 0; i < raw.length; i++) h = (h * 31 + raw.charCodeAt(i)) | 0;
|
|
98
|
+
return `id_${(h >>> 0).toString(36)}`;
|
|
78
99
|
}
|
|
79
100
|
|
|
80
101
|
/**
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
// no extra runtime dependencies; the PNG path
|
|
9
9
|
// (`./png.mjs`) needs `@resvg/resvg-js` to be installed.
|
|
10
10
|
|
|
11
|
-
import { excalidrawToSvg } from "./svg.mjs";
|
|
11
|
+
import { excalidrawToSvg, escapeAttr } from "./svg.mjs";
|
|
12
12
|
|
|
13
13
|
export const DEFAULT_CANVAS_WIDTH = 1200;
|
|
14
14
|
export const MIN_CANVAS_WIDTH = 16;
|
|
@@ -40,7 +40,8 @@ export function excalidrawJsonToCanvasSvg(doc, opts = {}) {
|
|
|
40
40
|
|
|
41
41
|
const inner = excalidrawToSvg(doc, { padding });
|
|
42
42
|
const innerVb = parseViewBox(inner);
|
|
43
|
-
|
|
43
|
+
const safeBackground = escapeAttr(background);
|
|
44
|
+
if (!innerVb) return blankCanvas(width, height, safeBackground);
|
|
44
45
|
|
|
45
46
|
const scale = Math.min(width / innerVb.w, height / innerVb.h);
|
|
46
47
|
const drawnW = innerVb.w * scale;
|
|
@@ -54,7 +55,7 @@ export function excalidrawJsonToCanvasSvg(doc, opts = {}) {
|
|
|
54
55
|
`<svg xmlns="http://www.w3.org/2000/svg" ` +
|
|
55
56
|
`width="${width}" height="${height}" ` +
|
|
56
57
|
`viewBox="0 0 ${width} ${height}">`,
|
|
57
|
-
`<rect width="${width}" height="${height}" fill="${
|
|
58
|
+
`<rect width="${width}" height="${height}" fill="${safeBackground}"/>`,
|
|
58
59
|
`<g transform="translate(${offsetX} ${offsetY}) scale(${scale}) ` +
|
|
59
60
|
`translate(${-innerVb.x} ${-innerVb.y})">`,
|
|
60
61
|
innerBody,
|
package/src/render/svg.mjs
CHANGED
|
@@ -351,21 +351,26 @@ function colorOrNone(c) {
|
|
|
351
351
|
return c;
|
|
352
352
|
}
|
|
353
353
|
|
|
354
|
-
/** @internal */
|
|
355
354
|
/**
|
|
356
355
|
* Escape a string for safe interpolation into an SVG attribute value.
|
|
356
|
+
* Escapes `&`, `"`, `<` and `>` so attacker-controlled input cannot
|
|
357
|
+
* break out of the surrounding `"..."` and inject extra attributes
|
|
358
|
+
* or markup.
|
|
357
359
|
* @param {string} s Raw string.
|
|
358
360
|
* @returns {string} Escaped string.
|
|
359
361
|
*/
|
|
360
|
-
function escapeAttr(s) {
|
|
361
|
-
return String(s)
|
|
362
|
+
export function escapeAttr(s) {
|
|
363
|
+
return String(s)
|
|
364
|
+
.replace(/&/g, "&")
|
|
365
|
+
.replace(/"/g, """)
|
|
366
|
+
.replace(/</g, "<")
|
|
367
|
+
.replace(/>/g, ">");
|
|
362
368
|
}
|
|
363
|
-
/** @internal */
|
|
364
369
|
/**
|
|
365
370
|
* Escape a string for safe interpolation into SVG text content.
|
|
366
371
|
* @param {string} s Raw string.
|
|
367
372
|
* @returns {string} Escaped string.
|
|
368
373
|
*/
|
|
369
|
-
function escapeText(s) {
|
|
374
|
+
export function escapeText(s) {
|
|
370
375
|
return String(s).replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
|
|
371
376
|
}
|