@grethel-labs/excaliplant 0.9.0 → 0.10.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
@@ -85,6 +85,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
85
85
  primary files.
86
86
  - Shared parser helpers now cover reusable title-line parsing and block-line
87
87
  accumulation for note-style block plugins.
88
+ - Built-in object diagrams now parse object declarations, aliases,
89
+ body/colon field rows, maps with row anchors, diamonds, notes, and
90
+ class-like relationships through a dedicated `object` diagram module.
88
91
 
89
92
  ### Changed
90
93
 
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.  ·  **v0.9.0**  ·  194 tests  ·  MIT
10
+ > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.  ·  **v0.10.0**  ·  200 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
@@ -131,7 +131,7 @@ See the full [Sequence Diagram Component Coverage](./docs/sequence-components.md
131
131
  npm test
132
132
  ```
133
133
 
134
- Ships with **194 tests** across functional, edge-case,
134
+ Ships with **200 tests** across functional, edge-case,
135
135
  security (XSS / ReDoS / prototype-pollution), and self-introspection
136
136
  suites.
137
137
 
@@ -308,6 +308,18 @@ excaliplant
308
308
  │ │ │ ├── render.mjs
309
309
  │ │ │ ├── security.mjs
310
310
  │ │ │ └── tests.mjs
311
+ │ │ ├── object
312
+ │ │ │ ├── docs
313
+ │ │ │ ├── plugins
314
+ │ │ │ ├── tests
315
+ │ │ │ ├── assets.mjs
316
+ │ │ │ ├── docs.mjs
317
+ │ │ │ ├── layout.mjs
318
+ │ │ │ ├── module.mjs
319
+ │ │ │ ├── parser.mjs
320
+ │ │ │ ├── render.mjs
321
+ │ │ │ ├── security.mjs
322
+ │ │ │ └── tests.mjs
311
323
  │ │ ├── sequence
312
324
  │ │ │ ├── docs
313
325
  │ │ │ ├── plugins
@@ -332,6 +344,7 @@ excaliplant
332
344
  │ │ │ └── graph_runtime.mjs
333
345
  │ │ ├── use-case
334
346
  │ │ │ ├── plugins
347
+ │ │ │ ├── tests
335
348
  │ │ │ ├── assets.mjs
336
349
  │ │ │ ├── docs.mjs
337
350
  │ │ │ ├── layout.mjs
@@ -385,6 +398,7 @@ excaliplant
385
398
  │ ├── functional_more.test.mjs
386
399
  │ ├── merge_driver.test.mjs
387
400
  │ ├── modular_architecture.test.mjs
401
+ │ ├── object_components.test.mjs
388
402
  │ ├── plantuml.test.mjs
389
403
  │ ├── security.test.mjs
390
404
  │ ├── self_introspection.test.mjs
@@ -571,6 +585,46 @@ generated by the same command from JSDoc.
571
585
 
572
586
 
573
587
 
588
+ ### diagrams/object/assets
589
+
590
+
591
+
592
+ ### diagrams/object/docs
593
+
594
+
595
+
596
+ ### diagrams/object/docs/coverage_examples
597
+
598
+
599
+
600
+ ### diagrams/object/layout
601
+
602
+
603
+
604
+ ### diagrams/object/module
605
+
606
+
607
+
608
+ ### diagrams/object/parser
609
+
610
+
611
+
612
+ ### diagrams/object/plugins/syntax
613
+
614
+
615
+
616
+ ### diagrams/object/render
617
+
618
+
619
+
620
+ ### diagrams/object/security
621
+
622
+
623
+
624
+ ### diagrams/object/tests
625
+
626
+
627
+
574
628
  ### diagrams/sequence/assets
575
629
 
576
630
 
package/index.mjs CHANGED
@@ -106,8 +106,29 @@ export {
106
106
  componentDiagramModule,
107
107
  DEFAULT_CLASS_PLUGINS,
108
108
  DEFAULT_COMPONENT_PLUGINS,
109
+ DEFAULT_DEPLOYMENT_PLUGINS,
110
+ DEFAULT_OBJECT_PLUGINS,
109
111
  DEFAULT_SEQUENCE_PLUGINS,
112
+ DEFAULT_USE_CASE_PLUGINS,
110
113
  defaultDiagramModuleRegistry,
114
+ DeploymentDiagramAssets,
115
+ DeploymentDiagramDocs,
116
+ DeploymentDiagramLayout,
117
+ DeploymentDiagramModule,
118
+ DeploymentDiagramParser,
119
+ DeploymentDiagramRenderer,
120
+ DeploymentDiagramSecurity,
121
+ DeploymentDiagramTests,
122
+ deploymentDiagramModule,
123
+ ObjectDiagramAssets,
124
+ ObjectDiagramDocs,
125
+ ObjectDiagramLayout,
126
+ ObjectDiagramModule,
127
+ ObjectDiagramParser,
128
+ ObjectDiagramRenderer,
129
+ ObjectDiagramSecurity,
130
+ ObjectDiagramTests,
131
+ objectDiagramModule,
111
132
  SequenceDiagramAssets,
112
133
  SequenceDiagramDocs,
113
134
  SequenceDiagramLayout,
@@ -117,6 +138,15 @@ export {
117
138
  SequenceDiagramSecurity,
118
139
  SequenceDiagramTests,
119
140
  sequenceDiagramModule,
141
+ UseCaseDiagramAssets,
142
+ UseCaseDiagramDocs,
143
+ UseCaseDiagramLayout,
144
+ UseCaseDiagramModule,
145
+ UseCaseDiagramParser,
146
+ UseCaseDiagramRenderer,
147
+ UseCaseDiagramSecurity,
148
+ UseCaseDiagramTests,
149
+ useCaseDiagramModule,
120
150
  } from "./src/main/builtin.mjs";
121
151
  export {
122
152
  resolveModuleDependencies,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@grethel-labs/excaliplant",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
5
5
  "type": "module",
6
6
  "main": "index.mjs",
@@ -51,7 +51,7 @@
51
51
  },
52
52
  "scripts": {
53
53
  "pretest": "node scripts/clean-test-output.mjs",
54
- "test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/merge_driver.test.mjs tests/modular_architecture.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs tests/sequence_components.test.mjs tests/class_components.test.mjs tests/component_components.test.mjs tests/style.test.mjs",
54
+ "test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/merge_driver.test.mjs tests/modular_architecture.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs tests/sequence_components.test.mjs tests/class_components.test.mjs tests/component_components.test.mjs tests/deployment_components.test.mjs tests/usecase_components.test.mjs tests/object_components.test.mjs tests/style.test.mjs",
55
55
  "typecheck": "tsc -p tsconfig.json",
56
56
  "build:docs": "node docs/scripts/build-docs.mjs",
57
57
  "build:api": "node docs/scripts/build-docs.mjs",
@@ -106,12 +106,32 @@ export {
106
106
  export { UseCaseDiagramRenderer, useCaseDiagramRenderer } from "./use-case/render.mjs";
107
107
  export { UseCaseDiagramSecurity, useCaseDiagramSecurity } from "./use-case/security.mjs";
108
108
  export { UseCaseDiagramTests, useCaseDiagramTests } from "./use-case/tests.mjs";
109
+ export { ObjectDiagramModule, objectDiagramModule } from "./object/module.mjs";
110
+ export { ObjectDiagramAssets, objectDiagramAssets } from "./object/assets.mjs";
111
+ export { ObjectDiagramDocs, objectDiagramDocs } from "./object/docs.mjs";
112
+ export { ObjectDiagramLayout, layoutObjectDiagram, objectDiagramLayout } from "./object/layout.mjs";
113
+ export {
114
+ ObjectDiagramParser,
115
+ DEFAULT_OBJECT_PLUGINS,
116
+ createObjectParseContext,
117
+ detectObjectDiagram,
118
+ prepareObjectLines,
119
+ objectDiagramParser,
120
+ } from "./object/parser.mjs";
121
+ export {
122
+ OBJECT_RENDERERS,
123
+ ObjectDiagramRenderer,
124
+ objectDiagramRenderer,
125
+ } from "./object/render.mjs";
126
+ export { ObjectDiagramSecurity, objectDiagramSecurity } from "./object/security.mjs";
127
+ export { ObjectDiagramTests, objectDiagramTests } from "./object/tests.mjs";
109
128
 
110
129
  import { sequenceDiagramModule } from "./sequence/module.mjs";
111
130
  import { classDiagramModule } from "./class/module.mjs";
112
131
  import { componentDiagramModule } from "./component/module.mjs";
113
132
  import { deploymentDiagramModule } from "./deployment/module.mjs";
114
133
  import { useCaseDiagramModule } from "./use-case/module.mjs";
134
+ import { objectDiagramModule } from "./object/module.mjs";
115
135
 
116
136
  /** @public */
117
137
  export const BUILTIN_DIAGRAM_MODULES = Object.freeze([
@@ -120,4 +140,5 @@ export const BUILTIN_DIAGRAM_MODULES = Object.freeze([
120
140
  componentDiagramModule,
121
141
  deploymentDiagramModule,
122
142
  useCaseDiagramModule,
143
+ objectDiagramModule,
123
144
  ]);
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Object diagram asset contract.
3
+ * @module diagrams/object/assets
4
+ */
5
+
6
+ import { BaseModuleAssets } from "../base/assets.mjs";
7
+
8
+ /** @public */
9
+ export class ObjectDiagramAssets extends BaseModuleAssets {
10
+ constructor() {
11
+ super({
12
+ fonts: ["Excalifont"],
13
+ sprites: [],
14
+ icons: [],
15
+ fixtures: [],
16
+ allowsRemoteAssets: false,
17
+ });
18
+ }
19
+ }
20
+
21
+ /** @public */
22
+ export const objectDiagramAssets = new ObjectDiagramAssets();
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Object-diagram coverage examples owned by the object module.
3
+ * @module diagrams/object/docs/coverage_examples
4
+ */
5
+
6
+ /**
7
+ * @type {readonly {id:string,title:string,description:string,source:string}[]}
8
+ * @public
9
+ */
10
+ export const OBJECT_COMPONENT_EXAMPLES = Object.freeze([
11
+ {
12
+ id: "objects-fields",
13
+ title: "Objects and fields",
14
+ description: "Object declarations, aliases, body fields and colon field syntax.",
15
+ source: `@startobject
16
+ object user {
17
+ name = "Dummy"
18
+ id = 123
19
+ }
20
+ object "Session Token" as session
21
+ session : value = "abc"
22
+ user --> session : owns
23
+ @endobject`,
24
+ },
25
+ {
26
+ id: "maps-anchors",
27
+ title: "Maps and row anchors",
28
+ description: "Map rows, row anchors and class-like relationships between objects.",
29
+ source: `@startobject
30
+ map CapitalCity {
31
+ UK => London
32
+ USA => Washington
33
+ }
34
+ object Traveler
35
+ Traveler --> CapitalCity::UK : visits
36
+ @endobject`,
37
+ },
38
+ {
39
+ id: "diamond-relationships",
40
+ title: "Diamonds and relationships",
41
+ description: "Object diagrams share class-style relationship operators and diamonds.",
42
+ source: `@startobject
43
+ object Order
44
+ object LineItem
45
+ diamond Aggregation
46
+ Order *-- LineItem : contains
47
+ Order --> Aggregation
48
+ @endobject`,
49
+ },
50
+ ]);
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Object diagram documentation contract.
3
+ * @module diagrams/object/docs
4
+ */
5
+
6
+ import { BaseModuleDocs } from "../base/docs.mjs";
7
+
8
+ /** @public */
9
+ export class ObjectDiagramDocs extends BaseModuleDocs {
10
+ constructor() {
11
+ super({
12
+ examples: ["objects", "maps", "diamonds", "relationships", "notes"],
13
+ generatedPages: [],
14
+ knownGaps: ["json-block-mixing", "object-title-underlining"],
15
+ });
16
+ }
17
+ }
18
+
19
+ /** @public */
20
+ export const objectDiagramDocs = new ObjectDiagramDocs();
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Object diagram layout adapter.
3
+ * @module diagrams/object/layout
4
+ */
5
+
6
+ import { BaseModuleLayout } from "../base/layout.mjs";
7
+ import { layoutGraphModel } from "../shared/graph_runtime.mjs";
8
+
9
+ /** @public */
10
+ export const layoutObjectDiagram = layoutGraphModel;
11
+
12
+ /** @public */
13
+ export class ObjectDiagramLayout extends BaseModuleLayout {
14
+ constructor() {
15
+ super({ layoutStrategy: "elkGraph", layout: layoutObjectDiagram });
16
+ }
17
+ }
18
+
19
+ /** @public */
20
+ export const objectDiagramLayout = new ObjectDiagramLayout();
@@ -0,0 +1,99 @@
1
+ /**
2
+ * Built-in object diagram module.
3
+ * @module diagrams/object/module
4
+ */
5
+
6
+ import { GraphModuleBase } from "../base/module.mjs";
7
+ import { objectDiagramAssets } from "./assets.mjs";
8
+ import { objectDiagramDocs } from "./docs.mjs";
9
+ import { objectDiagramLayout } from "./layout.mjs";
10
+ import { objectDiagramParser } from "./parser.mjs";
11
+ import { objectDiagramRenderer } from "./render.mjs";
12
+ import { objectDiagramSecurity } from "./security.mjs";
13
+ import { objectDiagramTests } from "./tests.mjs";
14
+
15
+ /** @public */
16
+ export class ObjectDiagramModule extends GraphModuleBase {
17
+ constructor() {
18
+ super({
19
+ kind: "object",
20
+ artifactRoot: "src/diagrams/object",
21
+ ownedArtifacts: {
22
+ parser: [
23
+ "src/diagrams/object/parser.mjs",
24
+ "src/diagrams/object/plugins/syntax.mjs",
25
+ "src/diagrams/shared/graph_parser.mjs",
26
+ "src/diagrams/shared/graph_plugins/connections.mjs",
27
+ "src/diagrams/shared/graph_plugins/containers.mjs",
28
+ "src/diagrams/shared/graph_plugins/filters.mjs",
29
+ "src/diagrams/shared/graph_plugins/notes.mjs",
30
+ "src/diagrams/shared/graph_plugins/ports.mjs",
31
+ "src/diagrams/shared/graph_plugins/preamble.mjs",
32
+ "src/diagrams/shared/graph_plugins/shapes.mjs",
33
+ ],
34
+ model: ["src/diagrams/shared/graph_context.mjs", "src/general/model/diagram.mjs"],
35
+ style: [],
36
+ layout: ["src/diagrams/object/layout.mjs"],
37
+ render: ["src/diagrams/object/render.mjs", "src/general/render/excalidraw.mjs"],
38
+ security: ["src/diagrams/object/security.mjs"],
39
+ assets: ["src/diagrams/object/assets.mjs"],
40
+ docs: ["src/diagrams/object/docs.mjs", "src/diagrams/object/docs/coverage_examples.mjs"],
41
+ tests: [
42
+ "src/diagrams/object/tests.mjs",
43
+ "src/diagrams/object/tests/object_components.test.mjs",
44
+ "src/diagrams/object/tests/output.mjs",
45
+ "tests/object_components.test.mjs",
46
+ ],
47
+ },
48
+ startDirectives: ["@startobject"],
49
+ parser: objectDiagramParser,
50
+ layout: objectDiagramLayout,
51
+ renderer: objectDiagramRenderer,
52
+ docs: objectDiagramDocs,
53
+ tests: objectDiagramTests,
54
+ security: objectDiagramSecurity,
55
+ assets: objectDiagramAssets,
56
+ dependencies: [
57
+ {
58
+ kind: "security-base",
59
+ versionRange: "^1.0.0",
60
+ capabilities: ["sanitize", "limits"],
61
+ optional: false,
62
+ },
63
+ {
64
+ kind: "style-base",
65
+ versionRange: "^1.0.0",
66
+ capabilities: ["style-cascade"],
67
+ optional: false,
68
+ },
69
+ {
70
+ kind: "text-base",
71
+ versionRange: "^1.0.0",
72
+ capabilities: ["inline-text"],
73
+ optional: false,
74
+ },
75
+ {
76
+ kind: "arrow-base",
77
+ versionRange: "^1.0.0",
78
+ capabilities: ["diagram-arrow"],
79
+ optional: false,
80
+ },
81
+ {
82
+ kind: "asset-base",
83
+ versionRange: "^1.0.0",
84
+ capabilities: ["packaged-assets"],
85
+ optional: false,
86
+ },
87
+ {
88
+ kind: "graph-structure",
89
+ versionRange: "^1.0.0",
90
+ capabilities: ["boxes", "containers", "connections"],
91
+ optional: false,
92
+ },
93
+ ],
94
+ });
95
+ }
96
+ }
97
+
98
+ /** @public */
99
+ export const objectDiagramModule = new ObjectDiagramModule();
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Object diagram parser contract.
3
+ * @module diagrams/object/parser
4
+ */
5
+
6
+ import { explodeBraces, stripComment } from "../../util/plantuml_utils.mjs";
7
+ import { BaseModuleParser } from "../base/parser.mjs";
8
+ import { DEFAULT_GRAPH_PLUGINS, createGraphParseContext } from "../shared/graph_parser.mjs";
9
+ import { connectionPlugin } from "../shared/graph_plugins/connections.mjs";
10
+ import {
11
+ diamondDeclarationPlugin,
12
+ mapDeclarationPlugin,
13
+ objectDeclarationPlugin,
14
+ objectFieldPlugin,
15
+ } from "./plugins/syntax.mjs";
16
+
17
+ const graphPluginsBeforeConnections = DEFAULT_GRAPH_PLUGINS.filter(
18
+ (plugin) => plugin.name !== connectionPlugin.name,
19
+ );
20
+
21
+ /** @public */
22
+ export const DEFAULT_OBJECT_PLUGINS = Object.freeze([
23
+ ...graphPluginsBeforeConnections,
24
+ objectDeclarationPlugin,
25
+ mapDeclarationPlugin,
26
+ diamondDeclarationPlugin,
27
+ objectFieldPlugin,
28
+ connectionPlugin,
29
+ ]);
30
+
31
+ /** @public */
32
+ export const createObjectParseContext = createGraphParseContext;
33
+
34
+ /**
35
+ * @param {string[]} lines Raw PlantUML lines.
36
+ * @returns {string[]} Lines prepared for object-diagram parsing.
37
+ * @public
38
+ */
39
+ export function prepareObjectLines(lines) {
40
+ return explodeBraces(lines).filter((line) => !/^@(start|end)object\b/i.test(line.trim()));
41
+ }
42
+
43
+ /** @public */
44
+ export class ObjectDiagramParser extends BaseModuleParser {
45
+ constructor() {
46
+ super({
47
+ plugins: DEFAULT_OBJECT_PLUGINS,
48
+ createParseContext: createObjectParseContext,
49
+ prepareLines: prepareObjectLines,
50
+ detect: detectObjectDiagram,
51
+ });
52
+ }
53
+ }
54
+
55
+ /** @public */
56
+ export const objectDiagramParser = new ObjectDiagramParser();
57
+
58
+ /**
59
+ * @param {string} text Raw PlantUML source.
60
+ * @returns {boolean}
61
+ */
62
+ export function detectObjectDiagram(text) {
63
+ for (const raw of text.split(/\r?\n/)) {
64
+ const line = stripComment(raw).trim();
65
+ if (!line) continue;
66
+ if (/^skinparam\s+object\b/i.test(line)) return true;
67
+ if (/^(?:object|map|diamond)\b/i.test(line)) return true;
68
+ }
69
+ return false;
70
+ }
@@ -0,0 +1,244 @@
1
+ /**
2
+ * Object-diagram specific syntax plugins.
3
+ * @module diagrams/object/plugins/syntax
4
+ */
5
+
6
+ import {
7
+ classifyArrow,
8
+ slug,
9
+ stripQuotes,
10
+ STEREOTYPE,
11
+ unescapeLabel,
12
+ } from "../../../util/plantuml_utils.mjs";
13
+
14
+ const OBJECT_HEADER = /^object\s+(.+?)(\s*\{)?$/i;
15
+ const MAP_HEADER = /^map\s+(.+?)(\s*\{)?$/i;
16
+ const DIAMOND_DECLARATION = /^diamond\s+(.+)$/i;
17
+ const OBJECT_FIELD = /^("[^"]+"|[A-Za-z_][\w.-]*)\s*:\s*(.+)$/;
18
+ const MAP_ASSIGNMENT = /^(.+?)\s*=>\s*(.*)$/;
19
+ const MAP_ROW_CONNECTION =
20
+ /^(.+?)\s+([-.*o<|>]+(?:\[[^\]]+\])?(?:up|down|left|right|UP|DOWN|LEFT|RIGHT)?[-.*o<|>]*)\s+(.+)$/;
21
+
22
+ /**
23
+ * @typedef {{id:string,title:string,stereotype:string}} ParsedDeclaration
24
+ */
25
+
26
+ /**
27
+ * Parse an aliasable PlantUML declaration tail such as `"User One" as u1`.
28
+ * @param {string} raw Raw declaration body after the keyword.
29
+ * @returns {ParsedDeclaration|null}
30
+ */
31
+ function parseDeclaration(raw) {
32
+ let body = raw.replace(/\s*\{\s*$/, "").trim();
33
+ if (!body) return null;
34
+
35
+ let stereotype = "";
36
+ const stereotypeMatch = body.match(STEREOTYPE);
37
+ if (stereotypeMatch) {
38
+ stereotype = stereotypeMatch[1].trim();
39
+ body = body.replace(stereotypeMatch[0], "").trim();
40
+ }
41
+
42
+ const aliasMatch = body.match(/^("[^"]+"|.+?)\s+as\s+([A-Za-z_][\w.-]*)$/i);
43
+ if (aliasMatch) {
44
+ const title = stripQuotes(aliasMatch[1].trim());
45
+ return { id: aliasMatch[2], title, stereotype };
46
+ }
47
+
48
+ const title = stripQuotes(body);
49
+ const id = body.startsWith('"') ? slug(title) : body.split(/\s+/)[0];
50
+ return { id, title, stereotype };
51
+ }
52
+
53
+ /**
54
+ * @param {string} raw Raw endpoint token.
55
+ * @returns {{id:string,shorthand:boolean,portId:string|null}}
56
+ */
57
+ function normaliseEndpoint(raw) {
58
+ const token = raw.trim();
59
+ const portMatch = token.match(/^([^:]+)::(.+)$/);
60
+ if (portMatch) return { id: portMatch[1], shorthand: false, portId: portMatch[2] };
61
+ if (token.startsWith("[") && token.endsWith("]")) {
62
+ return { id: slug(token.slice(1, -1)), shorthand: true, portId: null };
63
+ }
64
+ if (token.startsWith("(") && token.endsWith(")")) {
65
+ return { id: slug(token.slice(1, -1)), shorthand: true, portId: null };
66
+ }
67
+ if (token.startsWith('"') && token.endsWith('"')) {
68
+ return { id: slug(token.slice(1, -1)), shorthand: true, portId: null };
69
+ }
70
+ return { id: token, shorthand: false, portId: null };
71
+ }
72
+
73
+ /**
74
+ * @param {string} raw Raw map key.
75
+ * @returns {string}
76
+ */
77
+ function portId(raw) {
78
+ return stripQuotes(raw.trim());
79
+ }
80
+
81
+ /**
82
+ * @param {Record<string, any>} ctx Parse context.
83
+ * @param {string} id Box id.
84
+ * @param {string} member Member row to append.
85
+ * @param {"object"|"map"} shape Shape used if the box must be auto-declared.
86
+ * @returns {void}
87
+ */
88
+ function appendMember(ctx, id, member, shape) {
89
+ const title = stripQuotes(id);
90
+ const box = ctx.boxes.get(id) || ctx.addBox({ id, title, shape });
91
+ if (!box.members.includes(member)) box.members.push(member);
92
+ }
93
+
94
+ /**
95
+ * @param {Record<string, any>} ctx Parse context.
96
+ * @param {string} boxId Owning map id.
97
+ * @param {string} key Raw row key.
98
+ * @returns {void}
99
+ */
100
+ function addMapPort(ctx, boxId, key) {
101
+ const id = portId(key);
102
+ if (!id) return;
103
+ ctx.addPort({ boxId, portId: id, side: "right", direction: "out" });
104
+ }
105
+
106
+ /**
107
+ * Handle an object body member line.
108
+ * @param {string} line Input line inside an object block.
109
+ * @param {Record<string, any>} ctx Parse context.
110
+ * @param {string} objectId Owning object id.
111
+ * @returns {void}
112
+ */
113
+ function handleObjectBodyLine(line, ctx, objectId) {
114
+ if (!line || line === "--") return;
115
+ appendMember(ctx, objectId, unescapeLabel(line), "object");
116
+ }
117
+
118
+ /**
119
+ * Handle a map body row.
120
+ * @param {string} line Input line inside a map block.
121
+ * @param {Record<string, any>} ctx Parse context.
122
+ * @param {string} mapId Owning map id.
123
+ * @returns {void}
124
+ */
125
+ function handleMapBodyLine(line, ctx, mapId) {
126
+ if (!line || line === "--") return;
127
+
128
+ const assignment = line.match(MAP_ASSIGNMENT);
129
+ if (assignment) {
130
+ const [, key, value] = assignment;
131
+ const row = `${key.trim()} => ${value.trim()}`.trim();
132
+ appendMember(ctx, mapId, unescapeLabel(row), "map");
133
+ addMapPort(ctx, mapId, key);
134
+ return;
135
+ }
136
+
137
+ const rowConnection = line.match(MAP_ROW_CONNECTION);
138
+ if (rowConnection) {
139
+ const [, key, op, rawTarget] = rowConnection;
140
+ const arrow = classifyArrow(op);
141
+ if (arrow) {
142
+ const target = normaliseEndpoint(rawTarget);
143
+ appendMember(ctx, mapId, unescapeLabel(key.trim()), "map");
144
+ addMapPort(ctx, mapId, key);
145
+ ctx.queueConnection({
146
+ fromId: mapId,
147
+ toId: target.id,
148
+ fromPort: portId(key),
149
+ toPort: target.portId,
150
+ fromShorthand: false,
151
+ toShorthand: target.shorthand,
152
+ label: "",
153
+ ...arrow,
154
+ });
155
+ return;
156
+ }
157
+ }
158
+
159
+ appendMember(ctx, mapId, unescapeLabel(line), "map");
160
+ addMapPort(ctx, mapId, line);
161
+ }
162
+
163
+ /** @type {import("../../../util/parser_engine.mjs").Plugin} */
164
+ export const objectDeclarationPlugin = {
165
+ name: "object.object",
166
+ tryStart(line, ctx) {
167
+ const match = line.match(OBJECT_HEADER);
168
+ if (!match || !match[2]) return null;
169
+ const parsed = parseDeclaration(match[1]);
170
+ if (!parsed) return null;
171
+ ctx.addBox({ ...parsed, shape: "object" });
172
+ return {
173
+ onLine(bodyLine, bodyCtx) {
174
+ handleObjectBodyLine(bodyLine, bodyCtx, parsed.id);
175
+ },
176
+ tryEnd(bodyLine) {
177
+ return /^}$/.test(bodyLine);
178
+ },
179
+ };
180
+ },
181
+ tryLine(line, ctx) {
182
+ const match = line.match(OBJECT_HEADER);
183
+ if (!match || match[2]) return false;
184
+ const parsed = parseDeclaration(match[1]);
185
+ if (!parsed) return false;
186
+ ctx.addBox({ ...parsed, shape: "object" });
187
+ return true;
188
+ },
189
+ };
190
+
191
+ /** @type {import("../../../util/parser_engine.mjs").Plugin} */
192
+ export const mapDeclarationPlugin = {
193
+ name: "object.map",
194
+ tryStart(line, ctx) {
195
+ const match = line.match(MAP_HEADER);
196
+ if (!match || !match[2]) return null;
197
+ const parsed = parseDeclaration(match[1]);
198
+ if (!parsed) return null;
199
+ ctx.addBox({ ...parsed, shape: "map" });
200
+ return {
201
+ onLine(bodyLine, bodyCtx) {
202
+ handleMapBodyLine(bodyLine, bodyCtx, parsed.id);
203
+ },
204
+ tryEnd(bodyLine) {
205
+ return /^}$/.test(bodyLine);
206
+ },
207
+ };
208
+ },
209
+ tryLine(line, ctx) {
210
+ const match = line.match(MAP_HEADER);
211
+ if (!match || match[2]) return false;
212
+ const parsed = parseDeclaration(match[1]);
213
+ if (!parsed) return false;
214
+ ctx.addBox({ ...parsed, shape: "map" });
215
+ return true;
216
+ },
217
+ };
218
+
219
+ /** @type {import("../../../util/parser_engine.mjs").Plugin} */
220
+ export const objectFieldPlugin = {
221
+ name: "object.field",
222
+ tryLine(line, ctx) {
223
+ const match = line.match(OBJECT_FIELD);
224
+ if (!match) return false;
225
+ const [, rawTarget, field] = match;
226
+ const target = stripQuotes(rawTarget.trim());
227
+ const id = rawTarget.startsWith('"') ? slug(target) : target;
228
+ appendMember(ctx, id, unescapeLabel(field.trim()), "object");
229
+ return true;
230
+ },
231
+ };
232
+
233
+ /** @type {import("../../../util/parser_engine.mjs").Plugin} */
234
+ export const diamondDeclarationPlugin = {
235
+ name: "object.diamond",
236
+ tryLine(line, ctx) {
237
+ const match = line.match(DIAMOND_DECLARATION);
238
+ if (!match) return false;
239
+ const parsed = parseDeclaration(match[1]);
240
+ if (!parsed) return false;
241
+ ctx.addBox({ ...parsed, shape: "diamond" });
242
+ return true;
243
+ },
244
+ };
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Object diagram renderer adapters.
3
+ * @module diagrams/object/render
4
+ */
5
+
6
+ import { BaseModuleRenderer } from "../base/renderer.mjs";
7
+ import { GRAPH_RENDERERS } from "../shared/graph_runtime.mjs";
8
+
9
+ /** @public */
10
+ export const OBJECT_RENDERERS = GRAPH_RENDERERS;
11
+
12
+ /** @public */
13
+ export class ObjectDiagramRenderer extends BaseModuleRenderer {
14
+ constructor() {
15
+ super({ renderers: OBJECT_RENDERERS });
16
+ }
17
+ }
18
+
19
+ /** @public */
20
+ export const objectDiagramRenderer = new ObjectDiagramRenderer();
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Object diagram security contract.
3
+ * @module diagrams/object/security
4
+ */
5
+
6
+ import { BaseModuleSecurity } from "../base/security.mjs";
7
+
8
+ /** @public */
9
+ export class ObjectDiagramSecurity extends BaseModuleSecurity {
10
+ constructor() {
11
+ super({
12
+ capabilities: ["sanitize", "limits", "inline-text", "diagram-arrow"],
13
+ securityTestCases: ["object-xss", "object-limits"],
14
+ });
15
+ }
16
+ }
17
+
18
+ /** @public */
19
+ export const objectDiagramSecurity = new ObjectDiagramSecurity();
@@ -0,0 +1,71 @@
1
+ import test from "node:test";
2
+ import assert from "node:assert/strict";
3
+
4
+ import { parsePlantUml, renderPlantUml, SequenceDiagram } from "../../../../index.mjs";
5
+ import { excalidrawToSvg } from "../../../general/render/svg.mjs";
6
+ import { OBJECT_COMPONENT_EXAMPLES } from "../docs/coverage_examples.mjs";
7
+ import { writeObjectOutput } from "./output.mjs";
8
+
9
+ const exampleById = new Map(OBJECT_COMPONENT_EXAMPLES.map((example) => [example.id, example]));
10
+
11
+ test("object component examples parse, render, and write review artifacts", async () => {
12
+ for (const example of OBJECT_COMPONENT_EXAMPLES) {
13
+ const diagram = parsePlantUml(example.source, { unknownLines: "strict" });
14
+ assert.ok(!(diagram instanceof SequenceDiagram), `${example.id} should parse as graph diagram`);
15
+ assert.ok(diagram.allBoxes().length >= 1, `${example.id} should have boxes`);
16
+
17
+ const doc = await renderPlantUml(example.source, { sourceLabel: `object/${example.id}` });
18
+ assert.equal(doc.type, "excalidraw");
19
+ assert.ok(doc.elements.length > 0, `${example.id} should render elements`);
20
+
21
+ const svg = excalidrawToSvg(doc);
22
+ assert.match(svg, /<svg\b/);
23
+ await writeObjectOutput(`${example.id}.puml`, example.source);
24
+ await writeObjectOutput(`${example.id}.excalidraw.json`, JSON.stringify(doc, null, 2));
25
+ await writeObjectOutput(`${example.id}.svg`, svg);
26
+ }
27
+ });
28
+
29
+ test("object declarations keep aliases and field rows", () => {
30
+ const example = exampleById.get("objects-fields");
31
+ assert.ok(example);
32
+ const diagram = parsePlantUml(example.source, { unknownLines: "strict" });
33
+
34
+ const user = diagram.boxById("user");
35
+ assert.ok(user);
36
+ assert.equal(user.shape, "object");
37
+ assert.deepEqual(user.members, ['name = "Dummy"', "id = 123"]);
38
+
39
+ const session = diagram.boxById("session");
40
+ assert.ok(session);
41
+ assert.equal(session.title, "Session Token");
42
+ assert.deepEqual(session.members, ['value = "abc"']);
43
+ assert.ok(diagram.connections.some((connection) => connection.label === "owns"));
44
+ });
45
+
46
+ test("object maps expose row ports for Map::key references", () => {
47
+ const example = exampleById.get("maps-anchors");
48
+ assert.ok(example);
49
+ const diagram = parsePlantUml(example.source, { unknownLines: "strict" });
50
+
51
+ const map = diagram.boxById("CapitalCity");
52
+ assert.ok(map);
53
+ assert.equal(map.shape, "map");
54
+ assert.deepEqual(map.members, ["UK => London", "USA => Washington"]);
55
+ assert.ok(map.ports.right.some((port) => port.id === "UK"));
56
+
57
+ const visits = diagram.connections.find((connection) => connection.label === "visits");
58
+ assert.ok(visits);
59
+ assert.equal(visits.arrow.end.anchor, "port");
60
+ assert.equal(visits.arrow.end.label, "UK");
61
+ });
62
+
63
+ test("object diamonds and class-like relationships are modeled", () => {
64
+ const example = exampleById.get("diamond-relationships");
65
+ assert.ok(example);
66
+ const diagram = parsePlantUml(example.source, { unknownLines: "strict" });
67
+
68
+ assert.equal(diagram.boxById("Aggregation")?.shape, "diamond");
69
+ assert.ok(diagram.connections.some((connection) => connection.kind === "composition"));
70
+ assert.ok(diagram.connections.some((connection) => connection.to.id === "Aggregation"));
71
+ });
@@ -0,0 +1,2 @@
1
+ *
2
+ !.gitignore
@@ -0,0 +1,22 @@
1
+ // Write object generated test-review artifacts.
2
+
3
+ import { mkdir, writeFile } from "node:fs/promises";
4
+ import { dirname, join } from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+
7
+ const __dirname = dirname(fileURLToPath(import.meta.url));
8
+
9
+ /** @type {string} */
10
+ export const OBJECT_TEST_OUTPUT_DIR = join(__dirname, "output");
11
+
12
+ /**
13
+ * Write a file to the object test output directory.
14
+ * @param {string} filename
15
+ * @param {string} content
16
+ * @returns {Promise<void>}
17
+ */
18
+ export async function writeObjectOutput(filename, content) {
19
+ const path = join(OBJECT_TEST_OUTPUT_DIR, filename);
20
+ await mkdir(dirname(path), { recursive: true });
21
+ await writeFile(path, content, "utf8");
22
+ }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Object diagram test contract.
3
+ * @module diagrams/object/tests
4
+ */
5
+
6
+ import { BaseModuleTests } from "../base/tests.mjs";
7
+
8
+ /** @public */
9
+ export class ObjectDiagramTests extends BaseModuleTests {
10
+ constructor() {
11
+ super({
12
+ unit: ["src/diagrams/object/tests/object_components.test.mjs"],
13
+ integration: ["tests/object_components.test.mjs", "tests/plantuml.test.mjs"],
14
+ security: ["tests/security.test.mjs"],
15
+ });
16
+ }
17
+ }
18
+
19
+ /** @public */
20
+ export const objectDiagramTests = new ObjectDiagramTests();
@@ -38,7 +38,11 @@ export class UseCaseDiagramModule extends GraphModuleBase {
38
38
  security: ["src/diagrams/use-case/security.mjs"],
39
39
  assets: ["src/diagrams/use-case/assets.mjs"],
40
40
  docs: ["src/diagrams/use-case/docs.mjs"],
41
- tests: ["src/diagrams/use-case/tests.mjs", "tests/usecase_components.test.mjs"],
41
+ tests: [
42
+ "src/diagrams/use-case/tests.mjs",
43
+ "src/diagrams/use-case/tests/usecase_components.test.mjs",
44
+ "tests/usecase_components.test.mjs",
45
+ ],
42
46
  },
43
47
  genericFallback: true,
44
48
  startDirectives: ["@startuml", "@startusecase"],
@@ -0,0 +1,28 @@
1
+ import test from "node:test";
2
+ import assert from "node:assert/strict";
3
+
4
+ import { parsePlantUml, renderPlantUml, SequenceDiagram } from "../../../../index.mjs";
5
+
6
+ const BASIC_USECASE = `@startuml
7
+ left to right direction
8
+ actor "Customer" as Customer
9
+ usecase "Place Order" as PlaceOrder
10
+ Customer --> PlaceOrder : starts
11
+ @enduml`;
12
+
13
+ test("use-case diagrams parse actors, use cases and relationships", () => {
14
+ const diagram = parsePlantUml(BASIC_USECASE, { unknownLines: "strict" });
15
+
16
+ assert.ok(!(diagram instanceof SequenceDiagram));
17
+ assert.equal(diagram.layoutDirection, "RIGHT");
18
+ assert.equal(diagram.boxById("Customer")?.shape, "actor");
19
+ assert.equal(diagram.boxById("PlaceOrder")?.shape, "usecase");
20
+ assert.ok(diagram.connections.some((connection) => connection.label === "starts"));
21
+ });
22
+
23
+ test("use-case diagrams render through the module-aware pipeline", async () => {
24
+ const doc = await renderPlantUml(BASIC_USECASE, { sourceLabel: "use-case/basic" });
25
+
26
+ assert.equal(doc.type, "excalidraw");
27
+ assert.ok(doc.elements.length > 0);
28
+ });
@@ -9,8 +9,8 @@ import { BaseModuleTests } from "../base/tests.mjs";
9
9
  export class UseCaseDiagramTests extends BaseModuleTests {
10
10
  constructor() {
11
11
  super({
12
- unit: [],
13
- integration: [],
12
+ unit: ["src/diagrams/use-case/tests/usecase_components.test.mjs"],
13
+ integration: ["tests/usecase_components.test.mjs", "tests/plantuml.test.mjs"],
14
14
  security: [],
15
15
  });
16
16
  }
@@ -222,6 +222,8 @@ function sizeBox(box, width) {
222
222
  break;
223
223
  case "class":
224
224
  case "enum":
225
+ case "object":
226
+ case "map":
225
227
  if (box.members && box.members.length) {
226
228
  // Wrap each member signature at semantically meaningful break
227
229
  // points (commas, parentheses, etc.) so long method signatures
@@ -257,6 +259,9 @@ function sizeBox(box, width) {
257
259
  );
258
260
  }
259
261
  break;
262
+ case "diamond":
263
+ shapeMin = Math.max(shapeMin, 72);
264
+ break;
260
265
  case "note":
261
266
  shapeMin = Math.max(shapeMin, 50);
262
267
  break;
@@ -38,6 +38,9 @@ export const SHAPES = [
38
38
  "entity",
39
39
  "class",
40
40
  "enum",
41
+ "object",
42
+ "map",
43
+ "diamond",
41
44
  "note",
42
45
  ];
43
46
 
@@ -732,11 +732,16 @@ function renderBox(box, parentColor, elements) {
732
732
  renderNodeShape(box, color, elements);
733
733
  break;
734
734
  case "class":
735
+ case "object":
736
+ case "map":
735
737
  renderClass(box, color, elements);
736
738
  break;
737
739
  case "enum":
738
740
  renderClass(box, color, elements);
739
741
  break;
742
+ case "diamond":
743
+ renderDiamondShape(box, color, elements);
744
+ break;
740
745
  case "note":
741
746
  renderNote(box, elements);
742
747
  break;
@@ -868,6 +873,31 @@ function renderRectangleShape(box, color, elements) {
868
873
  renderBoxText(box, color, elements);
869
874
  }
870
875
 
876
+ /**
877
+ * Render a PlantUML object-diagram diamond node.
878
+ * @param {Box} box Box to draw.
879
+ * @param {ColorTriple} color Colour triple to apply.
880
+ * @param {ExcalElement[]} elements Excalidraw element list — mutated in place.
881
+ * @returns {void}
882
+ */
883
+ function renderDiamondShape(box, color, elements) {
884
+ const cx = box.x + box.width / 2;
885
+ const cy = box.y + box.height / 2;
886
+ elements.push(
887
+ line({
888
+ points: [
889
+ { x: cx, y: box.y },
890
+ { x: box.x + box.width, y: cy },
891
+ { x: cx, y: box.y + box.height },
892
+ { x: box.x, y: cy },
893
+ { x: cx, y: box.y },
894
+ ],
895
+ strokeColor: color.stroke,
896
+ }),
897
+ );
898
+ renderBoxText(box, color, elements);
899
+ }
900
+
871
901
  /**
872
902
  * @param {Box} box
873
903
  * @param {{ stroke: string, fill: string, titleFill: string }} color
@@ -32,7 +32,9 @@ export {
32
32
  DEFAULT_CLASS_PLUGINS,
33
33
  DEFAULT_COMPONENT_PLUGINS,
34
34
  DEFAULT_DEPLOYMENT_PLUGINS,
35
+ DEFAULT_OBJECT_PLUGINS,
35
36
  DEFAULT_SEQUENCE_PLUGINS,
37
+ DEFAULT_USE_CASE_PLUGINS,
36
38
  DeploymentDiagramAssets,
37
39
  DeploymentDiagramDocs,
38
40
  DeploymentDiagramLayout,
@@ -42,6 +44,15 @@ export {
42
44
  DeploymentDiagramSecurity,
43
45
  DeploymentDiagramTests,
44
46
  deploymentDiagramModule,
47
+ ObjectDiagramAssets,
48
+ ObjectDiagramDocs,
49
+ ObjectDiagramLayout,
50
+ ObjectDiagramModule,
51
+ ObjectDiagramParser,
52
+ ObjectDiagramRenderer,
53
+ ObjectDiagramSecurity,
54
+ ObjectDiagramTests,
55
+ objectDiagramModule,
45
56
  SequenceDiagramAssets,
46
57
  SequenceDiagramDocs,
47
58
  SequenceDiagramLayout,
@@ -51,6 +62,15 @@ export {
51
62
  SequenceDiagramSecurity,
52
63
  SequenceDiagramTests,
53
64
  sequenceDiagramModule,
65
+ UseCaseDiagramAssets,
66
+ UseCaseDiagramDocs,
67
+ UseCaseDiagramLayout,
68
+ UseCaseDiagramModule,
69
+ UseCaseDiagramParser,
70
+ UseCaseDiagramRenderer,
71
+ UseCaseDiagramSecurity,
72
+ UseCaseDiagramTests,
73
+ useCaseDiagramModule,
54
74
  } from "../diagrams/index.mjs";
55
75
 
56
76
  /** @public */
@@ -34,7 +34,9 @@ import { runEngine } from "../util/parser_engine.mjs";
34
34
  import {
35
35
  DEFAULT_CLASS_PLUGINS,
36
36
  DEFAULT_COMPONENT_PLUGINS,
37
+ DEFAULT_OBJECT_PLUGINS,
37
38
  DEFAULT_SEQUENCE_PLUGINS,
39
+ DEFAULT_USE_CASE_PLUGINS,
38
40
  defaultDiagramModuleRegistry,
39
41
  } from "./builtin.mjs";
40
42
  import { ensureDiagramModuleRegistry } from "./registry.mjs";
@@ -61,6 +63,18 @@ export { DEFAULT_CLASS_PLUGINS } from "./builtin.mjs";
61
63
  */
62
64
  export { DEFAULT_DEPLOYMENT_PLUGINS } from "./builtin.mjs";
63
65
 
66
+ /**
67
+ * Default plugin pipeline for object diagrams.
68
+ * @public
69
+ */
70
+ export { DEFAULT_OBJECT_PLUGINS } from "./builtin.mjs";
71
+
72
+ /**
73
+ * Default plugin pipeline for use-case diagrams.
74
+ * @public
75
+ */
76
+ export { DEFAULT_USE_CASE_PLUGINS } from "./builtin.mjs";
77
+
64
78
  /**
65
79
  * Default plugin pipeline for sequence diagrams.
66
80
  * @public