@grethel-labs/excaliplant 0.3.5 → 0.4.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/CHANGELOG.md +35 -0
- package/README.md +4 -2
- package/SECURITY.md +4 -7
- package/package.json +2 -2
- package/src/layout/sizing.mjs +11 -1
- package/src/model/diagram.mjs +17 -0
- package/src/parser/component_context.mjs +28 -2
- package/src/parser/plantuml.mjs +7 -1
- package/src/parser/plugins/component/class_block.mjs +379 -0
- package/src/parser/plugins/component/connections.mjs +29 -12
- package/src/parser/utils.mjs +15 -0
- package/src/render/excalidraw.mjs +33 -5
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,41 @@ All notable changes to `@grethel-labs/excaliplant` are documented in this
|
|
|
4
4
|
file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
5
5
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.3.7] - 2026-05-04
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Class-diagram support for tplant-style PlantUML sources. The parser now
|
|
14
|
+
understands `class | abstract class | interface | enum` blocks with
|
|
15
|
+
generic type parameters (`Container<T extends Base>`), `extends`, and
|
|
16
|
+
`implements` clauses, so headers like
|
|
17
|
+
`class Child extends Parent` or `abstract class Foo implements Bar`
|
|
18
|
+
produce inheritance / realisation edges automatically.
|
|
19
|
+
- Connection multiplicity labels: `A "1" o-- "0..*" B : contains` is now
|
|
20
|
+
parsed and exposed as `Connection.fromMul` / `Connection.toMul`.
|
|
21
|
+
- New `enum` shape rendered as a UML class compartment with the
|
|
22
|
+
`«enumeration»` stereotype; `interface` boxes carrying members render
|
|
23
|
+
as compartment boxes with the `«interface»` stereotype.
|
|
24
|
+
- Member modifier tags (`{abstract}`, `{static}`, `{field}`, `{method}`)
|
|
25
|
+
survive `explodeBraces` and stay attached to the surrounding member
|
|
26
|
+
line.
|
|
27
|
+
- Class-diagram inheritance / realisation edges (`extends`,
|
|
28
|
+
`implements`) auto-vivify undeclared parents as stub class boxes,
|
|
29
|
+
matching PlantUML's implicit-declaration behaviour. Generic
|
|
30
|
+
component-style connections (`A --> B`) and bracket / paren / quoted
|
|
31
|
+
shorthand references (`[A]`, `(B)`, `"C"`) continue to drop silently
|
|
32
|
+
when undeclared, preserving existing component-diagram semantics.
|
|
33
|
+
- New `prefer-higher-version` git merge driver auto-resolves conflicts
|
|
34
|
+
on `package.json` / `package-lock.json` whose only disagreement is a
|
|
35
|
+
`"version": "x.y.z"` line by keeping the higher semver. Real
|
|
36
|
+
(non-version) conflicts are still surfaced for human review. Driver
|
|
37
|
+
is registered by `npm install` (via the `prepare` lifecycle hook) and
|
|
38
|
+
applied through `.gitattributes`. The auto-rebase workflow now runs
|
|
39
|
+
`npm ci` before rebasing so the driver is configured on the runner,
|
|
40
|
+
and regenerates docs after a successful rebase.
|
|
41
|
+
|
|
7
42
|
## [0.3.1] - 2026-05-04
|
|
8
43
|
|
|
9
44
|
### Fixed
|
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.4.0** · 98 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
|
|
@@ -109,7 +109,7 @@ Lower-level entry points are also exported:
|
|
|
109
109
|
npm test
|
|
110
110
|
```
|
|
111
111
|
|
|
112
|
-
Ships with **
|
|
112
|
+
Ships with **98 tests** across functional, edge-case,
|
|
113
113
|
security (XSS / ReDoS / prototype-pollution), and self-introspection
|
|
114
114
|
suites.
|
|
115
115
|
|
|
@@ -207,6 +207,7 @@ excaliplant
|
|
|
207
207
|
├── scripts
|
|
208
208
|
│ ├── auto-patch-deps.mjs
|
|
209
209
|
│ ├── bump-release-version.mjs
|
|
210
|
+
│ ├── merge-driver-prefer-higher-version.mjs
|
|
210
211
|
│ ├── prepublish-guard.mjs
|
|
211
212
|
│ ├── setup-merge-drivers.mjs
|
|
212
213
|
│ └── smoke.mjs
|
|
@@ -241,6 +242,7 @@ excaliplant
|
|
|
241
242
|
├── tests
|
|
242
243
|
│ ├── edge_cases.test.mjs
|
|
243
244
|
│ ├── functional_more.test.mjs
|
|
245
|
+
│ ├── merge_driver.test.mjs
|
|
244
246
|
│ ├── plantuml.test.mjs
|
|
245
247
|
│ ├── security.test.mjs
|
|
246
248
|
│ └── self_introspection.test.mjs
|
package/SECURITY.md
CHANGED
|
@@ -10,13 +10,10 @@ filesystem isolation.
|
|
|
10
10
|
|
|
11
11
|
## Supported versions
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
| ------- | ------------------ |
|
|
18
|
-
| `0.2.x` | :white_check_mark: |
|
|
19
|
-
| `0.1.x` | :x: |
|
|
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.
|
|
20
17
|
|
|
21
18
|
## Reporting a vulnerability
|
|
22
19
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grethel-labs/excaliplant",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.mjs",
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"./model": "./src/model/diagram.mjs"
|
|
34
34
|
},
|
|
35
35
|
"scripts": {
|
|
36
|
-
"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
|
+
"test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/merge_driver.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs",
|
|
37
37
|
"typecheck": "tsc -p tsconfig.json",
|
|
38
38
|
"build:docs": "node docs/scripts/build-docs.mjs",
|
|
39
39
|
"build:api": "typedoc",
|
package/src/layout/sizing.mjs
CHANGED
|
@@ -143,7 +143,16 @@ function sizeBox(box, width) {
|
|
|
143
143
|
shapeMin = Math.max(shapeMin, 110 + titleHeight);
|
|
144
144
|
break;
|
|
145
145
|
case "interface":
|
|
146
|
-
|
|
146
|
+
// Class-diagram interface: sized like a class once it has
|
|
147
|
+
// members or an explicit stereotype.
|
|
148
|
+
if ((box.members && box.members.length) || box.stereotype) {
|
|
149
|
+
shapeMin = Math.max(
|
|
150
|
+
shapeMin,
|
|
151
|
+
textHeight + (box.members?.length ?? 0) * FONT.sizeDescription * FONT.lineHeight + 12,
|
|
152
|
+
);
|
|
153
|
+
} else {
|
|
154
|
+
shapeMin = Math.max(shapeMin, 70 + titleHeight);
|
|
155
|
+
}
|
|
147
156
|
break;
|
|
148
157
|
case "usecase":
|
|
149
158
|
shapeMin = Math.max(shapeMin, 70);
|
|
@@ -159,6 +168,7 @@ function sizeBox(box, width) {
|
|
|
159
168
|
shapeMin = Math.max(shapeMin, textHeight + 8);
|
|
160
169
|
break;
|
|
161
170
|
case "class":
|
|
171
|
+
case "enum":
|
|
162
172
|
if (box.members && box.members.length) {
|
|
163
173
|
shapeMin = Math.max(
|
|
164
174
|
shapeMin,
|
package/src/model/diagram.mjs
CHANGED
|
@@ -36,6 +36,7 @@ export const SHAPES = [
|
|
|
36
36
|
"interface",
|
|
37
37
|
"entity",
|
|
38
38
|
"class",
|
|
39
|
+
"enum",
|
|
39
40
|
"note",
|
|
40
41
|
];
|
|
41
42
|
|
|
@@ -221,6 +222,8 @@ export class Connection {
|
|
|
221
222
|
* @param {string|null} [spec.startArrowhead] Excalidraw arrowhead at the source side.
|
|
222
223
|
* @param {string|null} [spec.endArrowhead] Excalidraw arrowhead at the target side.
|
|
223
224
|
* @param {string|null} [spec.directionHint] Layout hint: up | down | left | right.
|
|
225
|
+
* @param {string} [spec.fromMul] Multiplicity label rendered next to the source endpoint.
|
|
226
|
+
* @param {string} [spec.toMul] Multiplicity label rendered next to the target endpoint.
|
|
224
227
|
*/
|
|
225
228
|
constructor({
|
|
226
229
|
id,
|
|
@@ -232,6 +235,8 @@ export class Connection {
|
|
|
232
235
|
startArrowhead = null,
|
|
233
236
|
endArrowhead = "arrow",
|
|
234
237
|
directionHint = null,
|
|
238
|
+
fromMul = "",
|
|
239
|
+
toMul = "",
|
|
235
240
|
}) {
|
|
236
241
|
this.id = id;
|
|
237
242
|
this.from = from;
|
|
@@ -245,6 +250,18 @@ export class Connection {
|
|
|
245
250
|
this.endArrowhead = endArrowhead;
|
|
246
251
|
/** @type {string|null} */
|
|
247
252
|
this.directionHint = directionHint; // up|down|left|right|null
|
|
253
|
+
/**
|
|
254
|
+
* Multiplicity label rendered next to the source endpoint (e.g. `1`).
|
|
255
|
+
* Empty when no multiplicity was declared.
|
|
256
|
+
* @type {string}
|
|
257
|
+
*/
|
|
258
|
+
this.fromMul = fromMul;
|
|
259
|
+
/**
|
|
260
|
+
* Multiplicity label rendered next to the target endpoint (e.g. `0..*`).
|
|
261
|
+
* Empty when no multiplicity was declared.
|
|
262
|
+
* @type {string}
|
|
263
|
+
*/
|
|
264
|
+
this.toMul = toMul;
|
|
248
265
|
/** @type {string|null} */
|
|
249
266
|
this.fromSide = null;
|
|
250
267
|
/** @type {string|null} */
|
|
@@ -156,15 +156,39 @@ export function createComponentContext() {
|
|
|
156
156
|
},
|
|
157
157
|
|
|
158
158
|
finalize() {
|
|
159
|
+
// Auto-vivify endpoints for connections that explicitly opted in
|
|
160
|
+
// (currently: class-diagram inheritance/realisation edges queued
|
|
161
|
+
// by `classBlockPlugin` for headers like
|
|
162
|
+
// `class Child extends Parent`, where the parent is implicitly
|
|
163
|
+
// declared). Generic component-style connections (`A --> B`) do
|
|
164
|
+
// *not* opt in, so the long-standing behaviour of dropping edges
|
|
165
|
+
// to undeclared boxes is preserved. Bracket/paren/quoted shorthand
|
|
166
|
+
// references (`[A]`, `(B)`, `"C"`) also never auto-vivify.
|
|
167
|
+
const ensureEndpoint = (
|
|
168
|
+
/** @type {string} */ id,
|
|
169
|
+
/** @type {boolean} */ shorthand,
|
|
170
|
+
/** @type {boolean} */ allowVivify,
|
|
171
|
+
) => {
|
|
172
|
+
const existing = boxes.get(id);
|
|
173
|
+
if (existing) return existing;
|
|
174
|
+
if (shorthand || !allowVivify) return null;
|
|
175
|
+
const box = new Box({ id, title: id, shape: "class" });
|
|
176
|
+
boxes.set(id, box);
|
|
177
|
+
ensureFloatingPlane().addBox(box);
|
|
178
|
+
return box;
|
|
179
|
+
};
|
|
159
180
|
// Resolve connections.
|
|
160
181
|
for (const c of pendingConnections) {
|
|
161
|
-
const fromBox =
|
|
162
|
-
const toBox =
|
|
182
|
+
const fromBox = ensureEndpoint(c.fromId, !!c.fromShorthand, !!c.allowVivify);
|
|
183
|
+
const toBox = ensureEndpoint(c.toId, !!c.toShorthand, !!c.allowVivify);
|
|
163
184
|
if (!fromBox || !toBox || fromBox === toBox) continue;
|
|
164
185
|
const [from, to] = c.reversed ? [toBox, fromBox] : [fromBox, toBox];
|
|
165
186
|
const [startAh, endAh] = c.reversed
|
|
166
187
|
? [c.endArrowhead, c.startArrowhead]
|
|
167
188
|
: [c.startArrowhead, c.endArrowhead];
|
|
189
|
+
const [fromMul, toMul] = c.reversed
|
|
190
|
+
? [c.toMul || "", c.fromMul || ""]
|
|
191
|
+
: [c.fromMul || "", c.toMul || ""];
|
|
168
192
|
diagram.addConnection(
|
|
169
193
|
new Connection({
|
|
170
194
|
id: `${c.fromId}->${c.toId}#${diagram.connections.length}`,
|
|
@@ -176,6 +200,8 @@ export function createComponentContext() {
|
|
|
176
200
|
startArrowhead: startAh,
|
|
177
201
|
endArrowhead: endAh,
|
|
178
202
|
directionHint: c.directionHint,
|
|
203
|
+
fromMul,
|
|
204
|
+
toMul,
|
|
179
205
|
}),
|
|
180
206
|
);
|
|
181
207
|
}
|
package/src/parser/plantuml.mjs
CHANGED
|
@@ -45,6 +45,7 @@ import {
|
|
|
45
45
|
usecaseParensPlugin,
|
|
46
46
|
shapeKeywordPlugin,
|
|
47
47
|
} from "./plugins/component/shapes.mjs";
|
|
48
|
+
import { classBlockPlugin } from "./plugins/component/class_block.mjs";
|
|
48
49
|
import { connectionPlugin } from "./plugins/component/connections.mjs";
|
|
49
50
|
import { noteOfPlugin, noteFreePlugin, noteBlockPlugin } from "./plugins/component/notes.mjs";
|
|
50
51
|
|
|
@@ -74,7 +75,12 @@ export const DEFAULT_COMPONENT_PLUGINS = [
|
|
|
74
75
|
noteBlockPlugin,
|
|
75
76
|
noteOfPlugin,
|
|
76
77
|
noteFreePlugin,
|
|
77
|
-
|
|
78
|
+
// class-diagram declarations (incl. `abstract class`, `interface`,
|
|
79
|
+
// `enum`, generics, `extends`, `implements`) — must run before the
|
|
80
|
+
// legacy `shapeKeywordPlugin` so the brace-form variants enter
|
|
81
|
+
// member-collection mode instead of being treated as containers.
|
|
82
|
+
classBlockPlugin,
|
|
83
|
+
shapeKeywordPlugin, // owns the legacy class-block start
|
|
78
84
|
containerPlugin,
|
|
79
85
|
bracketBoxPlugin,
|
|
80
86
|
usecaseParensPlugin,
|
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
// UML class-diagram declarations.
|
|
2
|
+
//
|
|
3
|
+
// Handles the `class` / `abstract class` / `interface` / `enum` family of
|
|
4
|
+
// PlantUML lines, including the bits that the legacy keyword-shape plugin
|
|
5
|
+
// doesn't speak: generic type parameters, `extends`, `implements`, and the
|
|
6
|
+
// `{abstract}` / `{static}` member modifier tags. Block forms enter
|
|
7
|
+
// member-collection mode (the same model field as `class { … }`); inline
|
|
8
|
+
// forms with `extends` / `implements` still queue the corresponding
|
|
9
|
+
// inheritance / realisation connections so headers like
|
|
10
|
+
// `class Child extends Parent` (the canonical tplant output) work even
|
|
11
|
+
// without an explicit arrow line.
|
|
12
|
+
//
|
|
13
|
+
// This plugin only takes ownership of lines whose first non-modifier
|
|
14
|
+
// token is one of `class | interface | enum`; other shape keywords
|
|
15
|
+
// (`component`, `entity`, `database`, …) flow through to the legacy
|
|
16
|
+
// `shapeKeywordPlugin`, preserving existing behaviour.
|
|
17
|
+
|
|
18
|
+
import { slug, unescapeLabel, normaliseShape } from "../../utils.mjs";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Parsed pieces of a class-diagram declaration line.
|
|
22
|
+
* @typedef {{
|
|
23
|
+
* shape: "class"|"interface"|"enum",
|
|
24
|
+
* isAbstract: boolean,
|
|
25
|
+
* name: string,
|
|
26
|
+
* alias: string|null,
|
|
27
|
+
* generics: string,
|
|
28
|
+
* stereotype: string,
|
|
29
|
+
* extendsList: string[],
|
|
30
|
+
* implementsList: string[],
|
|
31
|
+
* description: string,
|
|
32
|
+
* opensBrace: boolean,
|
|
33
|
+
* }} ClassHeader
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Walk `<…>` from `s[0]` and return the index just past the matching
|
|
38
|
+
* `>`. Returns `-1` when the angle brackets are unbalanced. Used so the
|
|
39
|
+
* generic parameter list of a declaration (which can itself contain
|
|
40
|
+
* `<>` and spaces) survives whitespace-aware parsing.
|
|
41
|
+
* @param {string} s
|
|
42
|
+
* @returns {number}
|
|
43
|
+
*/
|
|
44
|
+
function scanAngles(s) {
|
|
45
|
+
if (s[0] !== "<") return -1;
|
|
46
|
+
let depth = 0;
|
|
47
|
+
for (let i = 0; i < s.length; i++) {
|
|
48
|
+
const c = s[i];
|
|
49
|
+
if (c === "<") depth++;
|
|
50
|
+
else if (c === ">") {
|
|
51
|
+
depth--;
|
|
52
|
+
if (depth === 0) return i + 1;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
return -1;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Capture a comma-separated parent list (used for both `extends` and
|
|
60
|
+
* `implements`). Stops at `{`, `:`, `<<` or another `extends`/`implements`
|
|
61
|
+
* keyword. Generic parameters in parent names are tolerated.
|
|
62
|
+
* @param {string} rest
|
|
63
|
+
* @returns {{parents: string[], rest: string}}
|
|
64
|
+
*/
|
|
65
|
+
function scanParents(rest) {
|
|
66
|
+
/** @type {string[]} */
|
|
67
|
+
const parents = [];
|
|
68
|
+
let depth = 0;
|
|
69
|
+
let start = 0;
|
|
70
|
+
let i = 0;
|
|
71
|
+
while (i < rest.length) {
|
|
72
|
+
const c = rest[i];
|
|
73
|
+
if (depth === 0) {
|
|
74
|
+
if (c === "{" || c === ":") break;
|
|
75
|
+
if (c === "<" && rest[i + 1] === "<") break;
|
|
76
|
+
if (/\s/.test(c)) {
|
|
77
|
+
const tail = rest.slice(i).trimStart();
|
|
78
|
+
if (/^(extends|implements)\b/.test(tail)) break;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
if (c === "<") depth++;
|
|
82
|
+
else if (c === ">") depth--;
|
|
83
|
+
if (depth === 0 && c === ",") {
|
|
84
|
+
parents.push(rest.slice(start, i).trim());
|
|
85
|
+
start = i + 1;
|
|
86
|
+
}
|
|
87
|
+
i++;
|
|
88
|
+
}
|
|
89
|
+
const last = rest.slice(start, i).trim();
|
|
90
|
+
if (last) parents.push(last);
|
|
91
|
+
return { parents: parents.filter(Boolean), rest: rest.slice(i) };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Strip the optional generic parameter list from a parent type so the
|
|
96
|
+
* extends/implements target resolves against the box id table.
|
|
97
|
+
* @param {string} parent
|
|
98
|
+
* @returns {string}
|
|
99
|
+
*/
|
|
100
|
+
function bareParentName(parent) {
|
|
101
|
+
const lt = parent.indexOf("<");
|
|
102
|
+
return (lt >= 0 ? parent.slice(0, lt) : parent).trim();
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Parse a class-diagram header line. Returns `null` when the line does
|
|
107
|
+
* not start with `class | interface | enum` (optionally preceded by an
|
|
108
|
+
* `abstract` modifier). Designed to be lenient about ordering of the
|
|
109
|
+
* `<<stereo>>`, `extends` and `implements` clauses since PlantUML itself
|
|
110
|
+
* accepts them in either order.
|
|
111
|
+
* @param {string} line
|
|
112
|
+
* @returns {ClassHeader|null}
|
|
113
|
+
*/
|
|
114
|
+
export function parseClassHeader(line) {
|
|
115
|
+
let rest = line.trim();
|
|
116
|
+
let isAbstract = false;
|
|
117
|
+
const absM = rest.match(/^abstract\s+/);
|
|
118
|
+
if (absM) {
|
|
119
|
+
isAbstract = true;
|
|
120
|
+
rest = rest.slice(absM[0].length);
|
|
121
|
+
}
|
|
122
|
+
const kwM = rest.match(/^(class|interface|enum)\s+/);
|
|
123
|
+
if (!kwM) return null;
|
|
124
|
+
const shape = /** @type {"class"|"interface"|"enum"} */ (kwM[1]);
|
|
125
|
+
rest = rest.slice(kwM[0].length).trimStart();
|
|
126
|
+
|
|
127
|
+
// Name (quoted or bare identifier).
|
|
128
|
+
let name = "";
|
|
129
|
+
if (rest.startsWith('"')) {
|
|
130
|
+
const end = rest.indexOf('"', 1);
|
|
131
|
+
if (end < 0) return null;
|
|
132
|
+
name = rest.slice(1, end);
|
|
133
|
+
rest = rest.slice(end + 1).trimStart();
|
|
134
|
+
} else {
|
|
135
|
+
const m = rest.match(/^[A-Za-z_][\w.]*/);
|
|
136
|
+
if (!m) return null;
|
|
137
|
+
name = m[0];
|
|
138
|
+
rest = rest.slice(m[0].length);
|
|
139
|
+
}
|
|
140
|
+
// Optional generic parameter list.
|
|
141
|
+
let generics = "";
|
|
142
|
+
if (rest.startsWith("<")) {
|
|
143
|
+
const end = scanAngles(rest);
|
|
144
|
+
if (end < 0) return null;
|
|
145
|
+
generics = rest.slice(0, end);
|
|
146
|
+
rest = rest.slice(end);
|
|
147
|
+
}
|
|
148
|
+
rest = rest.trimStart();
|
|
149
|
+
|
|
150
|
+
// Optional `as alias`.
|
|
151
|
+
let alias = null;
|
|
152
|
+
const asM = rest.match(/^as\s+(\S+)\s*/);
|
|
153
|
+
if (asM) {
|
|
154
|
+
alias = asM[1];
|
|
155
|
+
rest = rest.slice(asM[0].length);
|
|
156
|
+
}
|
|
157
|
+
// Optional <<stereotype>> (may also follow extends/implements; loop below).
|
|
158
|
+
let stereotype = "";
|
|
159
|
+
const eatStereo = () => {
|
|
160
|
+
const m = rest.match(/^<<\s*([^>]+?)\s*>>\s*/);
|
|
161
|
+
if (m) {
|
|
162
|
+
if (!stereotype) stereotype = m[1];
|
|
163
|
+
rest = rest.slice(m[0].length);
|
|
164
|
+
return true;
|
|
165
|
+
}
|
|
166
|
+
return false;
|
|
167
|
+
};
|
|
168
|
+
eatStereo();
|
|
169
|
+
|
|
170
|
+
/** @type {string[]} */
|
|
171
|
+
const extendsList = [];
|
|
172
|
+
/** @type {string[]} */
|
|
173
|
+
const implementsList = [];
|
|
174
|
+
let progress = true;
|
|
175
|
+
while (progress) {
|
|
176
|
+
progress = false;
|
|
177
|
+
if (eatStereo()) {
|
|
178
|
+
progress = true;
|
|
179
|
+
continue;
|
|
180
|
+
}
|
|
181
|
+
if (/^extends\s+/.test(rest)) {
|
|
182
|
+
rest = rest.replace(/^extends\s+/, "");
|
|
183
|
+
const got = scanParents(rest);
|
|
184
|
+
extendsList.push(...got.parents);
|
|
185
|
+
rest = got.rest.trimStart();
|
|
186
|
+
progress = true;
|
|
187
|
+
continue;
|
|
188
|
+
}
|
|
189
|
+
if (/^implements\s+/.test(rest)) {
|
|
190
|
+
rest = rest.replace(/^implements\s+/, "");
|
|
191
|
+
const got = scanParents(rest);
|
|
192
|
+
implementsList.push(...got.parents);
|
|
193
|
+
rest = got.rest.trimStart();
|
|
194
|
+
progress = true;
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
// Optional `: description`.
|
|
199
|
+
let description = "";
|
|
200
|
+
const descM = rest.match(/^:\s*([^{]*?)\s*(\{)?\s*$/);
|
|
201
|
+
if (descM) {
|
|
202
|
+
description = descM[1].trim();
|
|
203
|
+
const opensBrace = !!descM[2];
|
|
204
|
+
return {
|
|
205
|
+
shape,
|
|
206
|
+
isAbstract,
|
|
207
|
+
name,
|
|
208
|
+
alias,
|
|
209
|
+
generics,
|
|
210
|
+
stereotype,
|
|
211
|
+
extendsList,
|
|
212
|
+
implementsList,
|
|
213
|
+
description,
|
|
214
|
+
opensBrace,
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
// Trailing `{` only?
|
|
218
|
+
if (rest === "{") {
|
|
219
|
+
return {
|
|
220
|
+
shape,
|
|
221
|
+
isAbstract,
|
|
222
|
+
name,
|
|
223
|
+
alias,
|
|
224
|
+
generics,
|
|
225
|
+
stereotype,
|
|
226
|
+
extendsList,
|
|
227
|
+
implementsList,
|
|
228
|
+
description: "",
|
|
229
|
+
opensBrace: true,
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
if (rest === "") {
|
|
233
|
+
return {
|
|
234
|
+
shape,
|
|
235
|
+
isAbstract,
|
|
236
|
+
name,
|
|
237
|
+
alias,
|
|
238
|
+
generics,
|
|
239
|
+
stereotype,
|
|
240
|
+
extendsList,
|
|
241
|
+
implementsList,
|
|
242
|
+
description: "",
|
|
243
|
+
opensBrace: false,
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
return null;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/**
|
|
250
|
+
* Queue inheritance / realisation connections derived from `extends` /
|
|
251
|
+
* `implements` clauses on a class-diagram header. The arrow shapes here
|
|
252
|
+
* mirror the PlantUML defaults: solid triangle for inheritance, dashed
|
|
253
|
+
* triangle for realisation.
|
|
254
|
+
* @param {ClassHeader} hdr
|
|
255
|
+
* @param {string} childId
|
|
256
|
+
* @param {any} ctx
|
|
257
|
+
*/
|
|
258
|
+
function queueInheritance(hdr, childId, ctx) {
|
|
259
|
+
for (const parent of hdr.extendsList) {
|
|
260
|
+
const parentId = bareParentName(parent);
|
|
261
|
+
if (!parentId) continue;
|
|
262
|
+
ctx.queueConnection({
|
|
263
|
+
fromId: childId,
|
|
264
|
+
toId: parentId,
|
|
265
|
+
label: "",
|
|
266
|
+
kind: "inheritance",
|
|
267
|
+
dashed: false,
|
|
268
|
+
reversed: false,
|
|
269
|
+
startArrowhead: null,
|
|
270
|
+
endArrowhead: "triangle_outline",
|
|
271
|
+
directionHint: null,
|
|
272
|
+
// Class-diagram parents are implicitly declared per PlantUML
|
|
273
|
+
// semantics — opt this edge into endpoint auto-vivification.
|
|
274
|
+
allowVivify: true,
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
for (const parent of hdr.implementsList) {
|
|
278
|
+
const parentId = bareParentName(parent);
|
|
279
|
+
if (!parentId) continue;
|
|
280
|
+
ctx.queueConnection({
|
|
281
|
+
fromId: childId,
|
|
282
|
+
toId: parentId,
|
|
283
|
+
label: "",
|
|
284
|
+
kind: "realization",
|
|
285
|
+
dashed: true,
|
|
286
|
+
reversed: false,
|
|
287
|
+
startArrowhead: null,
|
|
288
|
+
endArrowhead: "triangle_outline",
|
|
289
|
+
directionHint: null,
|
|
290
|
+
allowVivify: true,
|
|
291
|
+
});
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* Build the box title from the parsed header. Generics are kept on the
|
|
297
|
+
* title so users still see `Container<T>`, while the box id is derived
|
|
298
|
+
* from the bare name to match arrow endpoints (`Container --> Item`).
|
|
299
|
+
* @param {ClassHeader} hdr
|
|
300
|
+
* @returns {string}
|
|
301
|
+
*/
|
|
302
|
+
function headerTitle(hdr) {
|
|
303
|
+
return unescapeLabel(hdr.name + (hdr.generics || ""));
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
/**
|
|
307
|
+
* Pick the stereotype shown on the box. Honour any explicit
|
|
308
|
+
* `<<stereo>>` first; otherwise synthesise a class-diagram default
|
|
309
|
+
* (`<<interface>>`, `<<enumeration>>`, `<<abstract>>`) so the rendered
|
|
310
|
+
* shape carries the same visual hint PlantUML draws.
|
|
311
|
+
* @param {ClassHeader} hdr
|
|
312
|
+
* @returns {string}
|
|
313
|
+
*/
|
|
314
|
+
function headerStereotype(hdr) {
|
|
315
|
+
if (hdr.stereotype) return hdr.stereotype;
|
|
316
|
+
if (hdr.shape === "interface") return "interface";
|
|
317
|
+
if (hdr.shape === "enum") return "enumeration";
|
|
318
|
+
if (hdr.isAbstract) return "abstract";
|
|
319
|
+
return "";
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* Class-diagram block plugin. Runs before the legacy keyword-shape
|
|
324
|
+
* plugin so `class | interface | enum [extends|implements] [{ … }]` is
|
|
325
|
+
* routed here, while everything else (`component`, `database`, …)
|
|
326
|
+
* keeps flowing through {@link shapeKeywordPlugin}.
|
|
327
|
+
* @type {import("../../engine.mjs").Plugin}
|
|
328
|
+
*/
|
|
329
|
+
export const classBlockPlugin = {
|
|
330
|
+
name: "component.classBlock",
|
|
331
|
+
tryStart(line, ctx) {
|
|
332
|
+
const hdr = parseClassHeader(line);
|
|
333
|
+
if (!hdr || !hdr.opensBrace) return null;
|
|
334
|
+
// Match the legacy shape plugin's id convention: prefer the explicit
|
|
335
|
+
// alias, otherwise use the bare type name verbatim so arrow lines
|
|
336
|
+
// like `Child --> Parent` resolve against it. Quoted titles fall
|
|
337
|
+
// back to a slug since they are free-form labels.
|
|
338
|
+
const id = hdr.alias || (/^[A-Za-z_][\w.]*$/.test(hdr.name) ? hdr.name : slug(hdr.name));
|
|
339
|
+
const box = ctx.addBox({
|
|
340
|
+
id,
|
|
341
|
+
title: headerTitle(hdr),
|
|
342
|
+
description: hdr.description,
|
|
343
|
+
shape: normaliseShape(hdr.shape),
|
|
344
|
+
stereotype: headerStereotype(hdr),
|
|
345
|
+
members: [],
|
|
346
|
+
});
|
|
347
|
+
queueInheritance(hdr, id, ctx);
|
|
348
|
+
/** @type {string[]} */
|
|
349
|
+
const collected = [];
|
|
350
|
+
return {
|
|
351
|
+
onLine(memberLine) {
|
|
352
|
+
// Drop blank separators inside the body but keep all real
|
|
353
|
+
// member lines verbatim — the renderer prints them as-is so
|
|
354
|
+
// visibility prefixes (`+`, `-`, `#`, `~`) and modifier tags
|
|
355
|
+
// (`{static}`, `{abstract}`) survive.
|
|
356
|
+
if (memberLine !== "") collected.push(memberLine);
|
|
357
|
+
},
|
|
358
|
+
tryEnd(memberLine) {
|
|
359
|
+
if (memberLine !== "}") return false;
|
|
360
|
+
box.members = collected;
|
|
361
|
+
return true;
|
|
362
|
+
},
|
|
363
|
+
};
|
|
364
|
+
},
|
|
365
|
+
tryLine(line, ctx) {
|
|
366
|
+
const hdr = parseClassHeader(line);
|
|
367
|
+
if (!hdr || hdr.opensBrace) return false;
|
|
368
|
+
const id = hdr.alias || (/^[A-Za-z_][\w.]*$/.test(hdr.name) ? hdr.name : slug(hdr.name));
|
|
369
|
+
ctx.addBox({
|
|
370
|
+
id,
|
|
371
|
+
title: headerTitle(hdr),
|
|
372
|
+
description: hdr.description,
|
|
373
|
+
shape: normaliseShape(hdr.shape),
|
|
374
|
+
stereotype: headerStereotype(hdr),
|
|
375
|
+
});
|
|
376
|
+
queueInheritance(hdr, id, ctx);
|
|
377
|
+
return true;
|
|
378
|
+
},
|
|
379
|
+
};
|
|
@@ -6,22 +6,35 @@
|
|
|
6
6
|
|
|
7
7
|
import { classifyArrow, slug, unescapeLabel } from "../../utils.mjs";
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
// Endpoint can be a bare identifier, a bracket/paren/quoted shorthand,
|
|
10
|
+
// or a quoted name. The arrow may be flanked by quoted multiplicity
|
|
11
|
+
// labels: `Container "1" o-- "0..*" Item : "contains"`.
|
|
12
|
+
const CONNECTION_LINE = new RegExp(
|
|
13
|
+
'^(\\[[^\\]]+\\]|\\([^)]+\\)|"[^"]+"|\\S+)' + // from endpoint
|
|
14
|
+
'(?:\\s+"([^"]*)")?' + // optional from-side multiplicity
|
|
15
|
+
"\\s+([-.*o<|>]+(?:up|down|left|right|UP|DOWN|LEFT|RIGHT)?[-.*o<|>]*)" + // arrow
|
|
16
|
+
'(?:\\s+"([^"]*)")?' + // optional to-side multiplicity
|
|
17
|
+
'\\s+(\\[[^\\]]+\\]|\\([^)]+\\)|"[^"]+"|\\S+)' + // to endpoint
|
|
18
|
+
"(?:\\s*:\\s*(.+))?$", // optional label
|
|
19
|
+
);
|
|
11
20
|
|
|
12
21
|
/**
|
|
13
22
|
* Normalise a connection endpoint so that bracket / paren shorthands
|
|
14
23
|
* (`[Foo]`, `(Use case)`) and quoted labels resolve to the same
|
|
15
24
|
* identifier the corresponding shape declaration uses.
|
|
16
25
|
* @param {string} raw Raw token captured by the connection regex.
|
|
17
|
-
* @returns {string} Identifier suitable for
|
|
26
|
+
* @returns {{id: string, shorthand: boolean}} Identifier suitable for
|
|
27
|
+
* the box-id lookup table, plus a flag indicating whether the source
|
|
28
|
+
* used a bracket/paren/quoted shorthand (those should not auto-vivify
|
|
29
|
+
* a stub class box if the identifier is unknown — they are meant to
|
|
30
|
+
* reference a previously declared shape).
|
|
18
31
|
*/
|
|
19
32
|
function normaliseEndpoint(raw) {
|
|
20
33
|
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;
|
|
34
|
+
if (s.startsWith("[") && s.endsWith("]")) return { id: slug(s.slice(1, -1)), shorthand: true };
|
|
35
|
+
if (s.startsWith("(") && s.endsWith(")")) return { id: slug(s.slice(1, -1)), shorthand: true };
|
|
36
|
+
if (s.startsWith('"') && s.endsWith('"')) return { id: slug(s.slice(1, -1)), shorthand: true };
|
|
37
|
+
return { id: s, shorthand: false };
|
|
25
38
|
}
|
|
26
39
|
|
|
27
40
|
/**
|
|
@@ -35,15 +48,19 @@ export const connectionPlugin = {
|
|
|
35
48
|
tryLine(line, ctx) {
|
|
36
49
|
const m = line.match(CONNECTION_LINE);
|
|
37
50
|
if (!m) return false;
|
|
38
|
-
const [, rawFrom, op, rawTo, label] = m;
|
|
51
|
+
const [, rawFrom, fromMul, op, toMul, rawTo, label] = m;
|
|
39
52
|
const arrow = classifyArrow(op);
|
|
40
53
|
if (!arrow) return false;
|
|
41
|
-
const
|
|
42
|
-
const
|
|
54
|
+
const from = normaliseEndpoint(rawFrom);
|
|
55
|
+
const to = normaliseEndpoint(rawTo);
|
|
43
56
|
ctx.queueConnection({
|
|
44
|
-
fromId,
|
|
45
|
-
toId,
|
|
57
|
+
fromId: from.id,
|
|
58
|
+
toId: to.id,
|
|
59
|
+
fromShorthand: from.shorthand,
|
|
60
|
+
toShorthand: to.shorthand,
|
|
46
61
|
label: unescapeLabel(label?.trim() || ""),
|
|
62
|
+
fromMul: fromMul || "",
|
|
63
|
+
toMul: toMul || "",
|
|
47
64
|
...arrow,
|
|
48
65
|
});
|
|
49
66
|
return true;
|
package/src/parser/utils.mjs
CHANGED
|
@@ -132,6 +132,19 @@ export function explodeBraces(lines) {
|
|
|
132
132
|
buf += c;
|
|
133
133
|
continue;
|
|
134
134
|
}
|
|
135
|
+
// Preserve PlantUML class-diagram modifier tags (`{abstract}`,
|
|
136
|
+
// `{static}`, `{field}`, `{method}`, …) as part of the surrounding
|
|
137
|
+
// line. These are written `{word}` and must not be split off as
|
|
138
|
+
// their own brace lines, otherwise members like `+{abstract} foo()`
|
|
139
|
+
// disintegrate.
|
|
140
|
+
if (!inStr && c === "{") {
|
|
141
|
+
const m = raw.slice(i).match(/^\{([A-Za-z_][\w-]*)\}/);
|
|
142
|
+
if (m) {
|
|
143
|
+
buf += m[0];
|
|
144
|
+
i += m[0].length - 1;
|
|
145
|
+
continue;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
135
148
|
if (!inStr && (c === "{" || c === "}")) {
|
|
136
149
|
if (buf.trim()) out.push(buf);
|
|
137
150
|
out.push(c);
|
|
@@ -187,6 +200,8 @@ export function normaliseShape(kw) {
|
|
|
187
200
|
return "entity";
|
|
188
201
|
case "class":
|
|
189
202
|
return "class";
|
|
203
|
+
case "enum":
|
|
204
|
+
return "enum";
|
|
190
205
|
case "rectangle":
|
|
191
206
|
return "rectangle";
|
|
192
207
|
case "boundary":
|
|
@@ -656,6 +656,12 @@ function renderBox(box, parentColor, elements) {
|
|
|
656
656
|
case "cloud":
|
|
657
657
|
return renderCloud(box, color, elements);
|
|
658
658
|
case "interface":
|
|
659
|
+
// An interface declaration with member content is part of a UML
|
|
660
|
+
// class diagram, so render it as a two-compartment class box
|
|
661
|
+
// rather than the standalone "lollipop" interface symbol.
|
|
662
|
+
if ((box.members && box.members.length) || box.stereotype) {
|
|
663
|
+
return renderClass(box, color, elements);
|
|
664
|
+
}
|
|
659
665
|
return renderInterface(box, color, elements);
|
|
660
666
|
case "entity":
|
|
661
667
|
return renderEntity(box, color, elements);
|
|
@@ -663,6 +669,8 @@ function renderBox(box, parentColor, elements) {
|
|
|
663
669
|
return renderNodeShape(box, color, elements);
|
|
664
670
|
case "class":
|
|
665
671
|
return renderClass(box, color, elements);
|
|
672
|
+
case "enum":
|
|
673
|
+
return renderClass(box, color, elements);
|
|
666
674
|
case "note":
|
|
667
675
|
return renderNote(box, elements);
|
|
668
676
|
default:
|
|
@@ -1090,16 +1098,36 @@ function renderClass(box, color, elements) {
|
|
|
1090
1098
|
backgroundColor: color.fill,
|
|
1091
1099
|
}),
|
|
1092
1100
|
);
|
|
1093
|
-
|
|
1101
|
+
// Prefer the wrapped title cached by the sizing pass so long names
|
|
1102
|
+
// (notably class-diagram generics like `Container<T extends Base>`)
|
|
1103
|
+
// do not overflow the box width. Falls back to the raw title for
|
|
1104
|
+
// callers that bypass sizing.
|
|
1105
|
+
const titleValue = box._wrappedTitle ?? String(box.title || "");
|
|
1106
|
+
const titleLines = titleValue.split("\n").length;
|
|
1094
1107
|
const titleH = FONT.sizeTitle * FONT.lineHeight * titleLines;
|
|
1095
|
-
|
|
1108
|
+
let ty = box.y + SIZING.boxPaddingY;
|
|
1109
|
+
if (box.stereotype) {
|
|
1110
|
+
elements.push(
|
|
1111
|
+
text({
|
|
1112
|
+
x: box.x + SIZING.boxPaddingX,
|
|
1113
|
+
y: ty - 4,
|
|
1114
|
+
width: box.width - SIZING.boxPaddingX * 2,
|
|
1115
|
+
height: FONT.sizeDescription * FONT.lineHeight,
|
|
1116
|
+
value: `«${box.stereotype}»`,
|
|
1117
|
+
fontSize: FONT.sizeDescription,
|
|
1118
|
+
color: color.stroke,
|
|
1119
|
+
align: "center",
|
|
1120
|
+
}),
|
|
1121
|
+
);
|
|
1122
|
+
ty += FONT.sizeDescription * FONT.lineHeight;
|
|
1123
|
+
}
|
|
1096
1124
|
elements.push(
|
|
1097
1125
|
text({
|
|
1098
|
-
x: box.x,
|
|
1126
|
+
x: box.x + SIZING.boxPaddingX,
|
|
1099
1127
|
y: ty,
|
|
1100
|
-
width: box.width,
|
|
1128
|
+
width: box.width - SIZING.boxPaddingX * 2,
|
|
1101
1129
|
height: titleH,
|
|
1102
|
-
value:
|
|
1130
|
+
value: titleValue,
|
|
1103
1131
|
fontSize: FONT.sizeTitle,
|
|
1104
1132
|
color: color.stroke,
|
|
1105
1133
|
align: "center",
|