@grethel-labs/excaliplant 0.1.4 → 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 +20 -14
- package/SECURITY.md +70 -0
- package/THIRD_PARTY_NOTICES.md +29 -0
- package/bin/excaliplant.mjs +263 -0
- package/index.mjs +47 -17
- package/package.json +33 -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 +10 -2
- 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 +144 -48
- package/src/style/colors.mjs +63 -2
- package/src/style/font.mjs +44 -21
- 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
|
|
@@ -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
|
|
|
@@ -179,10 +185,13 @@ excaliplant
|
|
|
179
185
|
│ └── fonts
|
|
180
186
|
│ ├── Excalifont-Regular.woff2
|
|
181
187
|
│ └── LICENSE.txt
|
|
188
|
+
├── bin
|
|
189
|
+
│ └── excaliplant.mjs
|
|
182
190
|
├── docs
|
|
183
191
|
│ ├── ressources
|
|
184
192
|
│ ├── scripts
|
|
185
193
|
│ │ ├── build-docs.mjs
|
|
194
|
+
│ │ ├── check-build-manifest.mjs
|
|
186
195
|
│ │ ├── config.mjs
|
|
187
196
|
│ │ ├── extract-docs.mjs
|
|
188
197
|
│ │ ├── file-tree.mjs
|
|
@@ -190,6 +199,9 @@ excaliplant
|
|
|
190
199
|
│ └── README.template.md.njk
|
|
191
200
|
├── scripts
|
|
192
201
|
│ ├── auto-patch-deps.mjs
|
|
202
|
+
│ ├── bump-release-version.mjs
|
|
203
|
+
│ ├── prepublish-guard.mjs
|
|
204
|
+
│ ├── setup-merge-drivers.mjs
|
|
193
205
|
│ └── smoke.mjs
|
|
194
206
|
├── src
|
|
195
207
|
│ ├── layout
|
|
@@ -211,6 +223,8 @@ excaliplant
|
|
|
211
223
|
│ │ ├── canvas_svg.mjs
|
|
212
224
|
│ │ ├── excalidraw.mjs
|
|
213
225
|
│ │ ├── png.mjs
|
|
226
|
+
│ │ ├── rng.mjs
|
|
227
|
+
│ │ ├── schema.mjs
|
|
214
228
|
│ │ ├── sequence_render.mjs
|
|
215
229
|
│ │ └── svg.mjs
|
|
216
230
|
│ └── style
|
|
@@ -225,6 +239,8 @@ excaliplant
|
|
|
225
239
|
│ └── self_introspection.test.mjs
|
|
226
240
|
├── LICENSE
|
|
227
241
|
├── README.md
|
|
242
|
+
├── SECURITY.md
|
|
243
|
+
├── THIRD_PARTY_NOTICES.md
|
|
228
244
|
├── index.mjs
|
|
229
245
|
├── package.json
|
|
230
246
|
├── tsconfig.json
|
|
@@ -271,16 +287,6 @@ PlantUML syntax; that lives entirely in plugins. Block plugins
|
|
|
271
287
|
(multi-line notes, class bodies) take exclusive ownership of
|
|
272
288
|
subsequent lines until they release.
|
|
273
289
|
|
|
274
|
-
Plugin contract:
|
|
275
|
-
|
|
276
|
-
```js
|
|
277
|
-
{
|
|
278
|
-
name,
|
|
279
|
-
tryStart?(line, ctx): null | { onLine, tryEnd },
|
|
280
|
-
tryLine?(line, ctx): boolean,
|
|
281
|
-
}
|
|
282
|
-
```
|
|
283
|
-
|
|
284
290
|
### render
|
|
285
291
|
|
|
286
292
|
Emits Excalidraw JSON. Each model shape is dispatched to a
|
|
@@ -288,8 +294,8 @@ dedicated `renderXxx()` function that produces one or more
|
|
|
288
294
|
Excalidraw primitive elements (rectangle, ellipse, line, arrow,
|
|
289
295
|
text). The output document is a stand-alone `.excalidraw` file
|
|
290
296
|
that any Excalidraw front-end can open. The companion module
|
|
291
|
-
|
|
292
|
-
|
|
297
|
+
`src/render/svg.mjs` converts the same JSON to SVG for the
|
|
298
|
+
build-time documentation pipeline.
|
|
293
299
|
|
|
294
300
|
## License
|
|
295
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.
|
|
@@ -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
|
}
|
package/package.json
CHANGED
|
@@ -1,32 +1,49 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grethel-labs/excaliplant",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.mjs",
|
|
7
|
+
"bin": {
|
|
8
|
+
"excaliplant": "bin/excaliplant.mjs"
|
|
9
|
+
},
|
|
7
10
|
"files": [
|
|
8
11
|
"index.mjs",
|
|
12
|
+
"bin/",
|
|
9
13
|
"src/",
|
|
10
14
|
"assets/fonts/",
|
|
11
15
|
"README.md",
|
|
12
|
-
"LICENSE"
|
|
16
|
+
"LICENSE",
|
|
17
|
+
"SECURITY.md",
|
|
18
|
+
"THIRD_PARTY_NOTICES.md"
|
|
13
19
|
],
|
|
14
20
|
"exports": {
|
|
15
21
|
".": "./index.mjs",
|
|
16
22
|
"./parser/plantuml": "./src/parser/plantuml.mjs",
|
|
23
|
+
"./parser/engine": "./src/parser/engine.mjs",
|
|
17
24
|
"./layout": "./src/layout/elk_layout.mjs",
|
|
18
25
|
"./render": "./src/render/excalidraw.mjs",
|
|
26
|
+
"./render/excalidraw": "./src/render/excalidraw.mjs",
|
|
19
27
|
"./render/svg": "./src/render/svg.mjs",
|
|
20
28
|
"./render/canvas-svg": "./src/render/canvas_svg.mjs",
|
|
21
29
|
"./render/png": "./src/render/png.mjs",
|
|
30
|
+
"./render/schema": "./src/render/schema.mjs",
|
|
31
|
+
"./render/rng": "./src/render/rng.mjs",
|
|
22
32
|
"./model": "./src/model/diagram.mjs"
|
|
23
33
|
},
|
|
24
34
|
"scripts": {
|
|
25
35
|
"test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs",
|
|
36
|
+
"typecheck": "tsc -p tsconfig.json",
|
|
26
37
|
"build:docs": "node docs/scripts/build-docs.mjs",
|
|
27
38
|
"build:api": "typedoc",
|
|
28
39
|
"build": "npm run build:docs && npm run build:api",
|
|
29
|
-
"
|
|
40
|
+
"format": "prettier --write .",
|
|
41
|
+
"format:check": "prettier --check .",
|
|
42
|
+
"prepare": "husky && node scripts/setup-merge-drivers.mjs",
|
|
43
|
+
"prepublishOnly": "node scripts/prepublish-guard.mjs && npm test && npm run build"
|
|
44
|
+
},
|
|
45
|
+
"lint-staged": {
|
|
46
|
+
"*.{mjs,js,cjs,ts,json,yml,yaml,md}": "prettier --write"
|
|
30
47
|
},
|
|
31
48
|
"repository": {
|
|
32
49
|
"type": "git",
|
|
@@ -39,10 +56,15 @@
|
|
|
39
56
|
"excalidraw",
|
|
40
57
|
"diagram",
|
|
41
58
|
"elk",
|
|
42
|
-
"renderer"
|
|
59
|
+
"renderer",
|
|
60
|
+
"svg",
|
|
61
|
+
"png",
|
|
62
|
+
"uml",
|
|
63
|
+
"sequence-diagram"
|
|
43
64
|
],
|
|
44
65
|
"publishConfig": {
|
|
45
|
-
"access": "public"
|
|
66
|
+
"access": "public",
|
|
67
|
+
"provenance": true
|
|
46
68
|
},
|
|
47
69
|
"dependencies": {
|
|
48
70
|
"@resvg/resvg-js": "^2.6.2",
|
|
@@ -54,8 +76,13 @@
|
|
|
54
76
|
},
|
|
55
77
|
"license": "MIT",
|
|
56
78
|
"devDependencies": {
|
|
79
|
+
"@types/node": "^25.6.0",
|
|
80
|
+
"husky": "^9.1.7",
|
|
81
|
+
"lint-staged": "^16.4.0",
|
|
57
82
|
"nunjucks": "^3.2.4",
|
|
83
|
+
"prettier": "^3.8.3",
|
|
58
84
|
"tree-node-cli": "^1.6.0",
|
|
59
|
-
"typedoc": "^0.28.19"
|
|
85
|
+
"typedoc": "^0.28.19",
|
|
86
|
+
"typescript": "^5.6.0"
|
|
60
87
|
}
|
|
61
88
|
}
|