@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 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
  [![node](https://img.shields.io/node/v/@grethel-labs/excaliplant.svg)](https://nodejs.org)
8
8
  [![license](https://img.shields.io/npm/l/@grethel-labs/excaliplant.svg)](./LICENSE)
9
9
 
10
- > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. &nbsp;·&nbsp; **v0.3.5** &nbsp;·&nbsp; 86 tests &nbsp;·&nbsp; MIT
10
+ > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. &nbsp;·&nbsp; **v0.4.0** &nbsp;·&nbsp; 98 tests &nbsp;·&nbsp; 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 **86 tests** across functional, edge-case,
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
- We support **the latest published minor** on npm. Older lines do not
14
- receive backports.
15
-
16
- | Version | Supported |
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.5",
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",
@@ -143,7 +143,16 @@ function sizeBox(box, width) {
143
143
  shapeMin = Math.max(shapeMin, 110 + titleHeight);
144
144
  break;
145
145
  case "interface":
146
- shapeMin = Math.max(shapeMin, 70 + titleHeight);
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,
@@ -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 = boxes.get(c.fromId);
162
- const toBox = boxes.get(c.toId);
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
  }
@@ -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
- shapeKeywordPlugin, // owns the class-block start
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
- const CONNECTION_LINE =
10
- /^(\S+)\s+([-.*o<|>]+(?:up|down|left|right|UP|DOWN|LEFT|RIGHT)?[-.*o<|>]*)\s+(\S+)(?:\s*:\s*(.+))?$/;
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 the box-id lookup table.
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 fromId = normaliseEndpoint(rawFrom);
42
- const toId = normaliseEndpoint(rawTo);
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;
@@ -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
- const titleLines = String(box.title || "").split("\n").length;
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
- const ty = box.y + SIZING.boxPaddingY;
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: box.title,
1130
+ value: titleValue,
1103
1131
  fontSize: FONT.sizeTitle,
1104
1132
  color: color.stroke,
1105
1133
  align: "center",