@grethel-labs/excaliplant 0.1.3 → 0.2.0
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 +30 -19
- package/SECURITY.md +70 -0
- package/THIRD_PARTY_NOTICES.md +29 -0
- package/assets/fonts/Excalifont-Regular.woff2 +0 -0
- package/assets/fonts/LICENSE.txt +20 -0
- package/bin/excaliplant.mjs +263 -0
- package/index.mjs +47 -17
- package/package.json +34 -6
- package/src/layout/elk_layout.mjs +141 -19
- package/src/layout/sequence_layout.mjs +21 -7
- package/src/layout/sizing.mjs +71 -11
- package/src/model/diagram.mjs +317 -64
- package/src/parser/component_context.mjs +108 -27
- package/src/parser/engine.mjs +47 -37
- package/src/parser/plantuml.mjs +47 -22
- package/src/parser/plugins/component/connections.mjs +10 -2
- package/src/parser/plugins/component/containers.mjs +8 -3
- package/src/parser/plugins/component/notes.mjs +25 -9
- package/src/parser/plugins/component/preamble.mjs +8 -0
- package/src/parser/plugins/component/shapes.mjs +36 -7
- package/src/parser/plugins/sequence/messages.mjs +8 -2
- package/src/parser/plugins/sequence/notes.mjs +30 -2
- package/src/parser/plugins/sequence/participants.mjs +6 -1
- package/src/parser/plugins/sequence/preamble.mjs +4 -0
- package/src/parser/sequence_context.mjs +69 -8
- package/src/parser/utils.mjs +129 -28
- package/src/render/canvas_svg.mjs +30 -9
- package/src/render/excalidraw.mjs +847 -276
- package/src/render/png.mjs +21 -3
- package/src/render/rng.mjs +52 -0
- package/src/render/schema.mjs +35 -0
- package/src/render/sequence_render.mjs +213 -83
- package/src/render/svg.mjs +149 -44
- package/src/style/colors.mjs +63 -2
- package/src/style/font.mjs +62 -0
- package/src/style/text.mjs +73 -11
package/README.md
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
|
|
2
2
|
# excaliplant
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
[](https://www.npmjs.com/package/@grethel-labs/excaliplant)
|
|
5
|
+
[](https://www.npmjs.com/package/@grethel-labs/excaliplant)
|
|
6
|
+
[](https://github.com/grethel-labs/excaliplant/actions/workflows/ci.yml)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
|
|
10
|
+
> PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. · **v0.2.0** · 78 tests · MIT
|
|
5
11
|
|
|
6
12
|
`@grethel-labs/excaliplant` takes PlantUML source, runs it through a plugin-based
|
|
7
13
|
parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
|
|
@@ -13,11 +19,11 @@ artefacts.
|
|
|
13
19
|
<table>
|
|
14
20
|
<tr>
|
|
15
21
|
<td align="center" width="50%">
|
|
16
|
-
<a href="docs/ressources/generated/
|
|
22
|
+
<a href="docs/ressources/generated/svg/modules.svg"><img src="docs/ressources/generated/svg/modules.svg" alt="Module structure" width="380"/></a><br/>
|
|
17
23
|
<sub><b>Module structure</b> — rendered by excaliplant itself</sub>
|
|
18
24
|
</td>
|
|
19
25
|
<td align="center" width="50%">
|
|
20
|
-
<a href="docs/ressources/generated/
|
|
26
|
+
<a href="docs/ressources/generated/svg/sequence.svg"><img src="docs/ressources/generated/svg/sequence.svg" alt="renderPlantUml flow" width="380"/></a><br/>
|
|
21
27
|
<sub><b>renderPlantUml flow</b> — rendered by excaliplant itself</sub>
|
|
22
28
|
</td>
|
|
23
29
|
</tr>
|
|
@@ -96,7 +102,7 @@ Lower-level entry points are also exported:
|
|
|
96
102
|
npm test
|
|
97
103
|
```
|
|
98
104
|
|
|
99
|
-
Ships with **
|
|
105
|
+
Ships with **78 tests** across functional, edge-case,
|
|
100
106
|
security (XSS / ReDoS / prototype-pollution), and self-introspection
|
|
101
107
|
suites.
|
|
102
108
|
|
|
@@ -111,7 +117,7 @@ JSDoc tags.
|
|
|
111
117
|
|
|
112
118
|
### Module structure
|
|
113
119
|
|
|
114
|
-

|
|
115
121
|
|
|
116
122
|
_Sources: [PlantUML](docs/ressources/generated/puml/modules.puml) · [SVG](docs/ressources/generated/svg/modules.svg)_
|
|
117
123
|
|
|
@@ -122,7 +128,7 @@ each plugin handling one PlantUML construct.
|
|
|
122
128
|
|
|
123
129
|
### renderPlantUml flow
|
|
124
130
|
|
|
125
|
-

|
|
126
132
|
|
|
127
133
|
_Sources: [PlantUML](docs/ressources/generated/puml/sequence.puml) · [SVG](docs/ressources/generated/svg/sequence.svg)_
|
|
128
134
|
|
|
@@ -141,7 +147,7 @@ The call graph for `renderPlantUml(text)` walks three subsystems:
|
|
|
141
147
|
|
|
142
148
|
### Parser plugins
|
|
143
149
|
|
|
144
|
-

|
|
145
151
|
|
|
146
152
|
_Sources: [PlantUML](docs/ressources/generated/puml/plugins.puml) · [SVG](docs/ressources/generated/svg/plugins.svg)_
|
|
147
153
|
|
|
@@ -175,10 +181,17 @@ PlantUML text
|
|
|
175
181
|
|
|
176
182
|
```text
|
|
177
183
|
excaliplant
|
|
184
|
+
├── assets
|
|
185
|
+
│ └── fonts
|
|
186
|
+
│ ├── Excalifont-Regular.woff2
|
|
187
|
+
│ └── LICENSE.txt
|
|
188
|
+
├── bin
|
|
189
|
+
│ └── excaliplant.mjs
|
|
178
190
|
├── docs
|
|
179
191
|
│ ├── ressources
|
|
180
192
|
│ ├── scripts
|
|
181
193
|
│ │ ├── build-docs.mjs
|
|
194
|
+
│ │ ├── check-build-manifest.mjs
|
|
182
195
|
│ │ ├── config.mjs
|
|
183
196
|
│ │ ├── extract-docs.mjs
|
|
184
197
|
│ │ ├── file-tree.mjs
|
|
@@ -186,6 +199,9 @@ excaliplant
|
|
|
186
199
|
│ └── README.template.md.njk
|
|
187
200
|
├── scripts
|
|
188
201
|
│ ├── auto-patch-deps.mjs
|
|
202
|
+
│ ├── bump-release-version.mjs
|
|
203
|
+
│ ├── prepublish-guard.mjs
|
|
204
|
+
│ ├── setup-merge-drivers.mjs
|
|
189
205
|
│ └── smoke.mjs
|
|
190
206
|
├── src
|
|
191
207
|
│ ├── layout
|
|
@@ -207,10 +223,13 @@ excaliplant
|
|
|
207
223
|
│ │ ├── canvas_svg.mjs
|
|
208
224
|
│ │ ├── excalidraw.mjs
|
|
209
225
|
│ │ ├── png.mjs
|
|
226
|
+
│ │ ├── rng.mjs
|
|
227
|
+
│ │ ├── schema.mjs
|
|
210
228
|
│ │ ├── sequence_render.mjs
|
|
211
229
|
│ │ └── svg.mjs
|
|
212
230
|
│ └── style
|
|
213
231
|
│ ├── colors.mjs
|
|
232
|
+
│ ├── font.mjs
|
|
214
233
|
│ └── text.mjs
|
|
215
234
|
├── tests
|
|
216
235
|
│ ├── edge_cases.test.mjs
|
|
@@ -220,6 +239,8 @@ excaliplant
|
|
|
220
239
|
│ └── self_introspection.test.mjs
|
|
221
240
|
├── LICENSE
|
|
222
241
|
├── README.md
|
|
242
|
+
├── SECURITY.md
|
|
243
|
+
├── THIRD_PARTY_NOTICES.md
|
|
223
244
|
├── index.mjs
|
|
224
245
|
├── package.json
|
|
225
246
|
├── tsconfig.json
|
|
@@ -266,16 +287,6 @@ PlantUML syntax; that lives entirely in plugins. Block plugins
|
|
|
266
287
|
(multi-line notes, class bodies) take exclusive ownership of
|
|
267
288
|
subsequent lines until they release.
|
|
268
289
|
|
|
269
|
-
Plugin contract:
|
|
270
|
-
|
|
271
|
-
```js
|
|
272
|
-
{
|
|
273
|
-
name,
|
|
274
|
-
tryStart?(line, ctx): null | { onLine, tryEnd },
|
|
275
|
-
tryLine?(line, ctx): boolean,
|
|
276
|
-
}
|
|
277
|
-
```
|
|
278
|
-
|
|
279
290
|
### render
|
|
280
291
|
|
|
281
292
|
Emits Excalidraw JSON. Each model shape is dispatched to a
|
|
@@ -283,8 +294,8 @@ dedicated `renderXxx()` function that produces one or more
|
|
|
283
294
|
Excalidraw primitive elements (rectangle, ellipse, line, arrow,
|
|
284
295
|
text). The output document is a stand-alone `.excalidraw` file
|
|
285
296
|
that any Excalidraw front-end can open. The companion module
|
|
286
|
-
|
|
287
|
-
|
|
297
|
+
`src/render/svg.mjs` converts the same JSON to SVG for the
|
|
298
|
+
build-time documentation pipeline.
|
|
288
299
|
|
|
289
300
|
## License
|
|
290
301
|
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
`@grethel-labs/excaliplant` parses untrusted PlantUML text and emits
|
|
4
|
+
Excalidraw JSON / SVG / PNG. We treat the parser surface as a trust
|
|
5
|
+
boundary and ship a dedicated security test suite
|
|
6
|
+
([`tests/security.test.mjs`](tests/security.test.mjs)) covering XSS,
|
|
7
|
+
ReDoS, prototype pollution, deeply nested input, oversized input, null
|
|
8
|
+
bytes, RTL override / zero-width characters, surrogate pairs, and
|
|
9
|
+
filesystem isolation.
|
|
10
|
+
|
|
11
|
+
## Supported versions
|
|
12
|
+
|
|
13
|
+
We support **the latest published minor** on npm. Older lines do not
|
|
14
|
+
receive backports.
|
|
15
|
+
|
|
16
|
+
| Version | Supported |
|
|
17
|
+
| ------- | ------------------ |
|
|
18
|
+
| `0.1.x` | :white_check_mark: |
|
|
19
|
+
|
|
20
|
+
## Reporting a vulnerability
|
|
21
|
+
|
|
22
|
+
Please **do not** open a public issue.
|
|
23
|
+
|
|
24
|
+
1. Use GitHub's [private vulnerability reporting](https://github.com/grethel-labs/excaliplant/security/advisories/new).
|
|
25
|
+
2. Include a minimal PlantUML reproducer if possible.
|
|
26
|
+
|
|
27
|
+
We aim to acknowledge reports within 5 working days and to ship a
|
|
28
|
+
patched release within 30 days for confirmed high/critical issues.
|
|
29
|
+
|
|
30
|
+
## Disclosure policy
|
|
31
|
+
|
|
32
|
+
- Confirmed vulnerabilities are tracked as GitHub Security Advisories.
|
|
33
|
+
- A CVE is requested for any issue with a CVSS ≥ 7.0.
|
|
34
|
+
- Fixes ship as a patch release on npm; the advisory is published
|
|
35
|
+
simultaneously.
|
|
36
|
+
|
|
37
|
+
## Hardening recommendations for consumers
|
|
38
|
+
|
|
39
|
+
- Treat `renderPlantUml(input)` like any other untrusted-input parser.
|
|
40
|
+
Run it inside a worker / isolated process if your input source is
|
|
41
|
+
hostile.
|
|
42
|
+
- The SVG output **inlines the Excalifont woff2** as a `data:` URL.
|
|
43
|
+
Some sandboxing environments restrict data URLs in fonts; if that
|
|
44
|
+
applies, post-process the SVG to drop the `<style>` block.
|
|
45
|
+
- The PNG path uses `@resvg/resvg-js` which executes as native code
|
|
46
|
+
(Rust → N-API). Keep that dependency on `npm audit` watch.
|
|
47
|
+
|
|
48
|
+
## Built-in hardening
|
|
49
|
+
|
|
50
|
+
These limits are enforced automatically and don't need to be enabled:
|
|
51
|
+
|
|
52
|
+
- **CLI stdin / file input cap**: `bin/excaliplant.mjs` rejects input
|
|
53
|
+
larger than `--max-input-bytes` (default 10 MiB, ceiling 200 MiB).
|
|
54
|
+
- **Render-width bounds**: PNG and canvas-SVG widths are clamped to
|
|
55
|
+
`[16, 16000]` px to bound `@resvg/resvg-js` memory.
|
|
56
|
+
- **Stack-trace gating**: the CLI prints a one-line error by default.
|
|
57
|
+
Set `DEBUG=1` to opt back into full stack traces.
|
|
58
|
+
- **No install scripts**: the npm package declares no
|
|
59
|
+
`pre/install/postinstall` hooks; nothing executes at `npm install`
|
|
60
|
+
time beyond the bundled JS being placed on disk.
|
|
61
|
+
- **Provenance**: releases are published with `npm publish
|
|
62
|
+
--provenance`. Consumers can verify the package origin via
|
|
63
|
+
`npm audit signatures`.
|
|
64
|
+
- **Pinned third-party Actions**: `softprops/action-gh-release` and
|
|
65
|
+
`peaceiris/actions-gh-pages` are pinned by commit SHA in
|
|
66
|
+
`.github/workflows/release.yml`.
|
|
67
|
+
- **Auto-patch dependency PRs require human review**: the
|
|
68
|
+
`auto-patch-deps` workflow opens a PR but no longer auto-merges, so
|
|
69
|
+
a malicious patch release that passes audit/tests still cannot land
|
|
70
|
+
on `main` without an approving review.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
This package bundles or depends on the following third-party works.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Excalifont (Latin subset, woff2)
|
|
8
|
+
|
|
9
|
+
- Path: [`assets/fonts/Excalifont-Regular.woff2`](assets/fonts/Excalifont-Regular.woff2)
|
|
10
|
+
- Upstream: <https://github.com/excalidraw/excalidraw>
|
|
11
|
+
- License: SIL Open Font License 1.1 (OFL-1.1)
|
|
12
|
+
- Reproduction of the OFL notice is bundled alongside the binary at
|
|
13
|
+
[`assets/fonts/LICENSE.txt`](assets/fonts/LICENSE.txt).
|
|
14
|
+
|
|
15
|
+
The font is embedded into exported SVG / PNG documents as a `data:`
|
|
16
|
+
URL so they render with the same hand-drawn Excalidraw look in any
|
|
17
|
+
context (GitHub README rendering, sandboxed `<img>` hosts, …).
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Runtime dependencies
|
|
22
|
+
|
|
23
|
+
| Package | License | Purpose |
|
|
24
|
+
| ----------------- | ------- | --------------------------------- |
|
|
25
|
+
| `elkjs` | EPL-2.0 | Layered + orthogonal graph layout |
|
|
26
|
+
| `@resvg/resvg-js` | MPL-2.0 | SVG → PNG rasterisation |
|
|
27
|
+
| `roughjs` | MIT | Hand-drawn stroke generation |
|
|
28
|
+
|
|
29
|
+
Run `npm ls --omit=dev` for the resolved versions in your install.
|
|
Binary file
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
Excalifont
|
|
2
|
+
==========
|
|
3
|
+
|
|
4
|
+
The Excalifont woff2 font file in this directory is bundled into
|
|
5
|
+
@grethel-labs/excaliplant so SVG and PNG exports render text in the
|
|
6
|
+
same hand-drawn typeface that Excalidraw uses on screen.
|
|
7
|
+
|
|
8
|
+
Origin: https://github.com/excalidraw/excalidraw (packages/excalidraw/fonts/Excalifont)
|
|
9
|
+
License: SIL Open Font License, Version 1.1 (OFL-1.1)
|
|
10
|
+
https://scripts.sil.org/OFL
|
|
11
|
+
|
|
12
|
+
Copyright (c) 2024 by Excalidraw. All rights reserved.
|
|
13
|
+
Excalifont is a trademark of Excalidraw.
|
|
14
|
+
|
|
15
|
+
Manufacturer/designer:
|
|
16
|
+
- Your Own Font Foundry (Virgil)
|
|
17
|
+
- Ján Filípek / DizajnDesign (Excalifont, modifications)
|
|
18
|
+
|
|
19
|
+
The font is redistributed under the OFL-1.1; see the upstream LICENSE
|
|
20
|
+
for the full text. This bundling is permitted by §2 of the OFL.
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// excaliplant CLI.
|
|
3
|
+
//
|
|
4
|
+
// Usage:
|
|
5
|
+
// excaliplant [--svg|--png|--excalidraw] [-o <out>] [--width N] [<input>]
|
|
6
|
+
//
|
|
7
|
+
// If <input> is omitted, PlantUML is read from stdin.
|
|
8
|
+
// If -o is omitted, output is written to stdout (binary for PNG).
|
|
9
|
+
//
|
|
10
|
+
// Examples:
|
|
11
|
+
// excaliplant diagram.puml # excalidraw → stdout
|
|
12
|
+
// excaliplant -o diagram.excalidraw diagram.puml
|
|
13
|
+
// excaliplant --svg diagram.puml > out.svg
|
|
14
|
+
// cat diagram.puml | excaliplant --png -o out.png --width 4800
|
|
15
|
+
|
|
16
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
17
|
+
import { renderPlantUml } from "../index.mjs";
|
|
18
|
+
|
|
19
|
+
// Hard limits to keep the CLI from being weaponised as a memory bomb.
|
|
20
|
+
const DEFAULT_MAX_INPUT_BYTES = 10 * 1024 * 1024; // 10 MiB of PlantUML
|
|
21
|
+
const MAX_INPUT_BYTES_CEILING = 200 * 1024 * 1024; // hard ceiling for --max-input-bytes
|
|
22
|
+
const MAX_RENDER_WIDTH = 16000; // PNG/SVG canvas width upper bound
|
|
23
|
+
const MIN_RENDER_WIDTH = 16;
|
|
24
|
+
|
|
25
|
+
const HELP = `excaliplant — PlantUML → Excalidraw / SVG / PNG renderer.
|
|
26
|
+
|
|
27
|
+
Usage:
|
|
28
|
+
excaliplant [options] [<input>]
|
|
29
|
+
|
|
30
|
+
Options:
|
|
31
|
+
--excalidraw Emit Excalidraw JSON (default).
|
|
32
|
+
--svg Emit a sketchy SVG.
|
|
33
|
+
--png Emit a sketchy PNG.
|
|
34
|
+
-o, --out <f> Write to file <f> instead of stdout.
|
|
35
|
+
--width <n> PNG width (default 4800) / SVG canvas width (default 1200).
|
|
36
|
+
Clamped to [${MIN_RENDER_WIDTH}, ${MAX_RENDER_WIDTH}].
|
|
37
|
+
--label <s> Source label written to appState.name.
|
|
38
|
+
--no-canvas For --svg: emit a tightly-cropped SVG without the 4:3 letterbox.
|
|
39
|
+
--rng-seed <n> Override the deterministic seed (use --rng-seed=random for non-determinism).
|
|
40
|
+
--max-input-bytes <N>
|
|
41
|
+
Reject stdin/file input larger than N bytes
|
|
42
|
+
(default ${DEFAULT_MAX_INPUT_BYTES}, ceiling ${MAX_INPUT_BYTES_CEILING}).
|
|
43
|
+
-h, --help Show this message.
|
|
44
|
+
-v, --version Show package version.
|
|
45
|
+
|
|
46
|
+
Exit codes:
|
|
47
|
+
0 success
|
|
48
|
+
1 input error (oversized, parse error, render failure)
|
|
49
|
+
2 CLI argument error
|
|
50
|
+
64 unexpected internal error
|
|
51
|
+
|
|
52
|
+
Set DEBUG=1 to print full stack traces on failure.
|
|
53
|
+
`;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Print a one-line error and exit with the given code.
|
|
57
|
+
* @param {number} code
|
|
58
|
+
* @param {string} msg
|
|
59
|
+
* @internal
|
|
60
|
+
*/
|
|
61
|
+
function die(code, msg) {
|
|
62
|
+
process.stderr.write(`excaliplant: ${msg}\n`);
|
|
63
|
+
process.exit(code);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Parse a CLI argument that must be a positive integer.
|
|
68
|
+
* @param {string} raw
|
|
69
|
+
* @param {string} flag
|
|
70
|
+
* @returns {number}
|
|
71
|
+
* @internal
|
|
72
|
+
*/
|
|
73
|
+
function parsePositiveInt(raw, flag) {
|
|
74
|
+
const n = Number(raw);
|
|
75
|
+
if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
|
|
76
|
+
die(2, `${flag} expects a positive integer (got ${JSON.stringify(raw)})`);
|
|
77
|
+
}
|
|
78
|
+
return n;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Parse `process.argv.slice(2)` into a normalised options object.
|
|
83
|
+
* Validates ranges and exits with code 2 on bad input.
|
|
84
|
+
* @param {string[]} argv
|
|
85
|
+
* @returns {object}
|
|
86
|
+
* @internal
|
|
87
|
+
*/
|
|
88
|
+
function parseArgs(argv) {
|
|
89
|
+
const opts = { format: "excalidraw", canvas: true, maxInputBytes: DEFAULT_MAX_INPUT_BYTES };
|
|
90
|
+
const positional = [];
|
|
91
|
+
for (let i = 0; i < argv.length; i++) {
|
|
92
|
+
const a = argv[i];
|
|
93
|
+
switch (a) {
|
|
94
|
+
case "--excalidraw":
|
|
95
|
+
opts.format = "excalidraw";
|
|
96
|
+
break;
|
|
97
|
+
case "--svg":
|
|
98
|
+
opts.format = "svg";
|
|
99
|
+
break;
|
|
100
|
+
case "--png":
|
|
101
|
+
opts.format = "png";
|
|
102
|
+
break;
|
|
103
|
+
case "-o":
|
|
104
|
+
case "--out":
|
|
105
|
+
opts.out = argv[++i];
|
|
106
|
+
break;
|
|
107
|
+
case "--width": {
|
|
108
|
+
const w = parsePositiveInt(argv[++i], "--width");
|
|
109
|
+
if (w < MIN_RENDER_WIDTH || w > MAX_RENDER_WIDTH) {
|
|
110
|
+
die(2, `--width out of range [${MIN_RENDER_WIDTH}, ${MAX_RENDER_WIDTH}] (got ${w})`);
|
|
111
|
+
}
|
|
112
|
+
opts.width = w;
|
|
113
|
+
break;
|
|
114
|
+
}
|
|
115
|
+
case "--label":
|
|
116
|
+
opts.label = argv[++i];
|
|
117
|
+
break;
|
|
118
|
+
case "--no-canvas":
|
|
119
|
+
opts.canvas = false;
|
|
120
|
+
break;
|
|
121
|
+
case "--rng-seed":
|
|
122
|
+
opts.rngSeed = argv[++i];
|
|
123
|
+
break;
|
|
124
|
+
case "--max-input-bytes": {
|
|
125
|
+
const n = parsePositiveInt(argv[++i], "--max-input-bytes");
|
|
126
|
+
if (n > MAX_INPUT_BYTES_CEILING) {
|
|
127
|
+
die(2, `--max-input-bytes exceeds ceiling ${MAX_INPUT_BYTES_CEILING}`);
|
|
128
|
+
}
|
|
129
|
+
opts.maxInputBytes = n;
|
|
130
|
+
break;
|
|
131
|
+
}
|
|
132
|
+
case "-h":
|
|
133
|
+
case "--help":
|
|
134
|
+
opts.help = true;
|
|
135
|
+
break;
|
|
136
|
+
case "-v":
|
|
137
|
+
case "--version":
|
|
138
|
+
opts.versionFlag = true;
|
|
139
|
+
break;
|
|
140
|
+
default:
|
|
141
|
+
if (a.startsWith("-")) die(2, `unknown option: ${a}`);
|
|
142
|
+
positional.push(a);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
if (positional.length > 1) die(2, "expected at most one positional <input> path");
|
|
146
|
+
opts.input = positional[0];
|
|
147
|
+
return opts;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Read the PlantUML source either from the named file or from stdin,
|
|
152
|
+
* enforcing the configured byte cap.
|
|
153
|
+
* @param {string|undefined} file
|
|
154
|
+
* @param {number} maxBytes
|
|
155
|
+
* @returns {Promise<string>}
|
|
156
|
+
* @internal
|
|
157
|
+
*/
|
|
158
|
+
async function readInput(file, maxBytes) {
|
|
159
|
+
if (file) {
|
|
160
|
+
// Stat first so we don't load multi-GB files into memory.
|
|
161
|
+
const { stat } = await import("node:fs/promises");
|
|
162
|
+
const st = await stat(file);
|
|
163
|
+
if (st.size > maxBytes) {
|
|
164
|
+
die(
|
|
165
|
+
1,
|
|
166
|
+
`input file ${file} is ${st.size} bytes, exceeds limit ${maxBytes} (raise with --max-input-bytes)`,
|
|
167
|
+
);
|
|
168
|
+
}
|
|
169
|
+
return readFile(file, "utf8");
|
|
170
|
+
}
|
|
171
|
+
return new Promise((resolve, reject) => {
|
|
172
|
+
let total = 0;
|
|
173
|
+
const chunks = [];
|
|
174
|
+
process.stdin.on("data", (chunk) => {
|
|
175
|
+
total += chunk.length;
|
|
176
|
+
if (total > maxBytes) {
|
|
177
|
+
process.stdin.destroy();
|
|
178
|
+
reject(
|
|
179
|
+
new Error(
|
|
180
|
+
`stdin exceeded ${maxBytes} bytes (raise with --max-input-bytes); aborted at ${total}`,
|
|
181
|
+
),
|
|
182
|
+
);
|
|
183
|
+
return;
|
|
184
|
+
}
|
|
185
|
+
chunks.push(chunk);
|
|
186
|
+
});
|
|
187
|
+
process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
|
|
188
|
+
process.stdin.on("error", reject);
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* CLI entry point. Wired into `bin/excaliplant.mjs` shebang.
|
|
194
|
+
* @returns {Promise<void>}
|
|
195
|
+
* @internal
|
|
196
|
+
*/
|
|
197
|
+
async function main() {
|
|
198
|
+
const opts = parseArgs(process.argv.slice(2));
|
|
199
|
+
if (opts.help) {
|
|
200
|
+
process.stdout.write(HELP);
|
|
201
|
+
return;
|
|
202
|
+
}
|
|
203
|
+
if (opts.versionFlag) {
|
|
204
|
+
const { readFile: rf } = await import("node:fs/promises");
|
|
205
|
+
const url = new URL("../package.json", import.meta.url);
|
|
206
|
+
const pkg = JSON.parse(await rf(url, "utf8"));
|
|
207
|
+
process.stdout.write(`${pkg.version}\n`);
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
let text;
|
|
212
|
+
try {
|
|
213
|
+
text = await readInput(opts.input, opts.maxInputBytes);
|
|
214
|
+
} catch (e) {
|
|
215
|
+
die(1, e?.message || String(e));
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
// Build deterministic / overridable RNG.
|
|
219
|
+
let rng;
|
|
220
|
+
if (opts.rngSeed === "random") {
|
|
221
|
+
rng = Math.random;
|
|
222
|
+
} else if (opts.rngSeed != null) {
|
|
223
|
+
const { createSeededRng } = await import("../src/render/rng.mjs");
|
|
224
|
+
rng = createSeededRng(Number(opts.rngSeed) >>> 0);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
const result = renderPlantUml(text, {
|
|
228
|
+
sourceLabel: opts.label ?? opts.input ?? "stdin",
|
|
229
|
+
rng,
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
let payload;
|
|
233
|
+
if (opts.format === "excalidraw") {
|
|
234
|
+
const doc = await result;
|
|
235
|
+
payload = JSON.stringify(doc, null, 2);
|
|
236
|
+
} else if (opts.format === "svg") {
|
|
237
|
+
const svgOpts = { canvas: opts.canvas };
|
|
238
|
+
if (opts.width) svgOpts.width = opts.width;
|
|
239
|
+
payload = await result.toSvg(svgOpts);
|
|
240
|
+
} else if (opts.format === "png") {
|
|
241
|
+
const pngOpts = {};
|
|
242
|
+
if (opts.width) pngOpts.width = opts.width;
|
|
243
|
+
payload = await result.toPng(pngOpts);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (opts.out) {
|
|
247
|
+
await writeFile(opts.out, payload);
|
|
248
|
+
} else if (opts.format === "png") {
|
|
249
|
+
process.stdout.write(payload);
|
|
250
|
+
} else {
|
|
251
|
+
process.stdout.write(`${payload}\n`);
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
main().catch((e) => {
|
|
256
|
+
if (process.env.DEBUG) {
|
|
257
|
+
console.error(e?.stack || e);
|
|
258
|
+
} else {
|
|
259
|
+
console.error(`excaliplant: ${e?.message || e}`);
|
|
260
|
+
console.error(" (set DEBUG=1 to see the full stack trace)");
|
|
261
|
+
}
|
|
262
|
+
process.exit(64);
|
|
263
|
+
});
|
package/index.mjs
CHANGED
|
@@ -63,9 +63,18 @@ export {
|
|
|
63
63
|
DEFAULT_ASPECT_RATIO,
|
|
64
64
|
} from "./src/render/canvas_svg.mjs";
|
|
65
65
|
export { svgToPng } from "./src/render/png.mjs";
|
|
66
|
+
export { EXCALIDRAW_SCHEMA, ROUNDNESS } from "./src/render/schema.mjs";
|
|
67
|
+
export { createSeededRng, stableHash32 } from "./src/render/rng.mjs";
|
|
66
68
|
export {
|
|
67
|
-
Box,
|
|
68
|
-
|
|
69
|
+
Box,
|
|
70
|
+
Connection,
|
|
71
|
+
Diagram,
|
|
72
|
+
Plane,
|
|
73
|
+
Subplane,
|
|
74
|
+
Participant,
|
|
75
|
+
Message,
|
|
76
|
+
SequenceDiagram,
|
|
77
|
+
SequenceNote,
|
|
69
78
|
SHAPES,
|
|
70
79
|
} from "./src/model/diagram.mjs";
|
|
71
80
|
|
|
@@ -86,6 +95,8 @@ export {
|
|
|
86
95
|
*
|
|
87
96
|
* Both helpers lazily await the underlying document — so calling
|
|
88
97
|
* `toSvg()` / `toPng()` directly on the unawaited result works too.
|
|
98
|
+
*
|
|
99
|
+
* @public
|
|
89
100
|
*/
|
|
90
101
|
export class RenderResult {
|
|
91
102
|
/** @param {Promise<object>} docPromise */
|
|
@@ -93,7 +104,14 @@ export class RenderResult {
|
|
|
93
104
|
this._doc = docPromise;
|
|
94
105
|
}
|
|
95
106
|
|
|
96
|
-
/**
|
|
107
|
+
/**
|
|
108
|
+
* Thenable: `await result` yields the Excalidraw JSON document.
|
|
109
|
+
* @template T
|
|
110
|
+
* @template R
|
|
111
|
+
* @param {(value: object) => T | Promise<T>} [onFulfilled]
|
|
112
|
+
* @param {(reason: any) => R | Promise<R>} [onRejected]
|
|
113
|
+
* @returns {Promise<T | R>}
|
|
114
|
+
*/
|
|
97
115
|
then(onFulfilled, onRejected) {
|
|
98
116
|
return this._doc.then(onFulfilled, onRejected);
|
|
99
117
|
}
|
|
@@ -108,7 +126,7 @@ export class RenderResult {
|
|
|
108
126
|
*/
|
|
109
127
|
async toSvg(opts = {}) {
|
|
110
128
|
const doc = await this._doc;
|
|
111
|
-
if (opts.canvas === false) return excalidrawToSvg(doc, opts);
|
|
129
|
+
if (/** @type {any} */ (opts).canvas === false) return excalidrawToSvg(doc, opts);
|
|
112
130
|
return excalidrawJsonToCanvasSvg(doc, opts);
|
|
113
131
|
}
|
|
114
132
|
|
|
@@ -137,30 +155,42 @@ export class RenderResult {
|
|
|
137
155
|
* @param {object} [opts]
|
|
138
156
|
* @param {string} [opts.sourceLabel] Forwarded to the renderer's
|
|
139
157
|
* appState.name.
|
|
158
|
+
* @param {() => number} [opts.rng] Optional deterministic RNG.
|
|
140
159
|
* @returns {RenderResult} Thenable wrapping the Excalidraw
|
|
141
160
|
* JSON document.
|
|
142
161
|
*/
|
|
143
162
|
export function renderPlantUml(plantuml, opts = {}) {
|
|
144
|
-
return new RenderResult(
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
163
|
+
return new RenderResult(
|
|
164
|
+
(async () => {
|
|
165
|
+
const diagram = parsePlantUml(plantuml);
|
|
166
|
+
await layoutDiagram(diagram);
|
|
167
|
+
return exportDiagram(diagram, {
|
|
168
|
+
sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
|
|
169
|
+
rng: opts.rng,
|
|
170
|
+
});
|
|
171
|
+
})(),
|
|
172
|
+
);
|
|
151
173
|
}
|
|
152
174
|
|
|
153
175
|
/**
|
|
154
176
|
* Render an already-built Diagram model. Useful for callers that want
|
|
155
177
|
* to bypass the PlantUML parser and feed shapes programmatically.
|
|
156
178
|
*
|
|
179
|
+
* @param {import("./src/model/diagram.mjs").Diagram
|
|
180
|
+
* | import("./src/model/diagram.mjs").SequenceDiagram} diagram
|
|
181
|
+
* @param {object} [opts]
|
|
182
|
+
* @param {string} [opts.sourceLabel]
|
|
183
|
+
* @param {() => number} [opts.rng]
|
|
157
184
|
* @returns {RenderResult}
|
|
158
185
|
*/
|
|
159
186
|
export function renderDiagram(diagram, opts = {}) {
|
|
160
|
-
return new RenderResult(
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
187
|
+
return new RenderResult(
|
|
188
|
+
(async () => {
|
|
189
|
+
await layoutDiagram(diagram);
|
|
190
|
+
return exportDiagram(diagram, {
|
|
191
|
+
sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
|
|
192
|
+
rng: opts.rng,
|
|
193
|
+
});
|
|
194
|
+
})(),
|
|
195
|
+
);
|
|
166
196
|
}
|