@voxlz/graph-gen 0.0.0-stage → 4.5.3

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Torben Nordtorp
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,492 @@
1
- # Temporary Holding Version
1
+ # graph-gen
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Constraint-based graph layout → PNG renderer. Alternative to [PlantUML](https://plantuml.com/) and [Mermaid](https://mermaid.js.org/) when you want to store and generate your graphs from code, but want deterministic constraint control over the layout. Initially conceived to produce the scope and use-case diagrams required by certain threat modeling requirements.
4
+
5
+ ## Example
6
+
7
+ ![Checkout example](renders/demo/showcase/example.png)
8
+
9
+ ```text
10
+ // optional per-graph style overrides (here, a light fill for circles).
11
+ shapes {
12
+ circle {
13
+ color "#EAF4FF" // Blue
14
+ }
15
+ }
16
+
17
+ // the box/circle/actor/database shapes plus the boundaries and groups
18
+ // that contain them.
19
+ nodes {
20
+ actor customer: "Customer"
21
+ box web: "Web App"
22
+ boundary cloud: "Cloud VPC" {
23
+ circle api: "Checkout API"
24
+ group core {
25
+ circle payments: "Payment Service"
26
+ circle orders: "Order Service"
27
+ }
28
+ boundary container: "Filesystem" {
29
+ database db: "PostgreSQL"
30
+ database cache: "Redis"
31
+ }
32
+ }
33
+ box stripe: "Stripe"
34
+ actor attacker: "Attacker"
35
+ }
36
+
37
+ // connections between nodes; labelled ones trace the numbered flow,
38
+ // plain ones show static architecture links.
39
+ edges {
40
+ customer --> web: "1. checkout"
41
+ web --> api: "2. POST /pay {token}"
42
+ api --> payments: "3. charge"
43
+ api --> orders: "4. create order"
44
+ payments --> stripe: "5. charge card"
45
+ payments --- db
46
+ orders --- db
47
+ api --- cache
48
+ attacker ..> api: "spoofed request"
49
+ }
50
+
51
+ // relative-placement rules the layout solver must satisfy.
52
+ constraints {
53
+ customer top web
54
+ web top api
55
+ core right api
56
+ payments top orders
57
+ db bottom api
58
+ cache bottom api
59
+ cache left db
60
+ align row db cache
61
+ orders left payments
62
+ orders bottom api
63
+ stripe right payments
64
+ attacker left api
65
+ }
66
+ ```
67
+
68
+ ## Install and run (npm)
69
+
70
+ The recommended way to run graph-gen is with Node.js 20 or newer and `npx`—no
71
+ repository clone is needed:
72
+
73
+ ```bash
74
+ npx @voxlz/graph-gen path/to/graph.ggn
75
+ npx @voxlz/graph-gen -r .
76
+ npx @voxlz/graph-gen --watch path/to/graphs
77
+ npx @voxlz/graph-gen --help
78
+ ```
79
+
80
+ Or install the `graph-gen` command globally:
81
+
82
+ ```bash
83
+ npm install -g @voxlz/graph-gen
84
+ graph-gen -r .
85
+ ```
86
+
87
+ The package is published under the `@voxlz` scope because npm reserves the
88
+ similar unscoped names for other projects; `npx graphgen` runs a different
89
+ package.
90
+
91
+ The npm package includes the compiled CLI and default styles. Rendering uses
92
+ `canvas`: supported platforms use prebuilt native binaries; other platforms
93
+ need its [native build prerequisites](https://github.com/Automattic/node-canvas#compiling).
94
+ Text uses the system sans-serif font, so measurements and layouts can vary
95
+ between systems.
96
+ Docker remains available if you prefer not to install native dependencies.
97
+
98
+ ## Install and run (Docker)
99
+
100
+ Docker is an alternative that requires no local Node or native image libraries.
101
+ Pull the published image:
102
+
103
+ ```bash
104
+ docker pull ghcr.io/voxlz/graph-gen:latest
105
+ ```
106
+
107
+ Then render, mounting a folder so the PNG lands back on the host:
108
+
109
+ ```bash
110
+ mkdir -p out
111
+ docker run --rm -v "$(pwd)/out:/app/out" ghcr.io/voxlz/graph-gen:latest demo/usecases/bookstore_uc1.ggn out/output.png
112
+ ```
113
+
114
+ The image appears at `./out/output.png` on your machine. Replace the input and
115
+ output paths with your own as needed. Run with `--help` for all arguments and
116
+ environment variables, or `--version` for the installed version.
117
+
118
+ ## Output paths
119
+
120
+ The output argument is optional. If you omit it, graph-gen picks the output path
121
+ in this order:
122
+
123
+ 1. CLI output argument (`npx @voxlz/graph-gen input.ggn out/output.png`)
124
+ 2. Graph-local setting (`graph { outputPath "..." }` inside the rendered `.ggn`)
125
+ 3. Global style setting (`style.jsonc` -> `graph.outputPath`)
126
+ 4. Built-in fallback (`../graphs/{file}`)
127
+
128
+ `{file}` expands to the input filename with a `.png` extension. For example,
129
+ `checkout_scope.ggn` becomes `checkout_scope.png`. Relative paths are resolved
130
+ from the input graph's directory.
131
+
132
+ Example global default in `style.jsonc`:
133
+
134
+ ```jsonc
135
+ {
136
+ "graph": {
137
+ "outputPath": "../graphs/{file}",
138
+ },
139
+ }
140
+ ```
141
+
142
+ Example per-graph override:
143
+
144
+ ```text
145
+ graph {
146
+ outputPath "./renders/{file}"
147
+ }
148
+ ```
149
+
150
+ To override the bundled styles, pass a style file as the third argument:
151
+
152
+ ```bash
153
+ npx @voxlz/graph-gen input.ggn out/output.png my-style.jsonc
154
+ ```
155
+
156
+ With Docker, mount the style file:
157
+
158
+ ```bash
159
+ docker run --rm -v "$(pwd)/out:/app/out" -v "$(pwd)/my-style.jsonc:/app/my-style.jsonc" \
160
+ ghcr.io/voxlz/graph-gen:latest demo/usecases/bookstore_uc1.ggn out/output.png my-style.jsonc
161
+ ```
162
+
163
+ ## Render a directory recursively
164
+
165
+ Use `--recursive` (or `-r`) to regenerate every `.ggn` file under a directory,
166
+ including nested directories, then exit:
167
+
168
+ ```bash
169
+ npx @voxlz/graph-gen -r path/to/graphs
170
+ npx @voxlz/graph-gen -r .
171
+ ```
172
+
173
+ Omitting the path uses the current directory. Each graph uses its configured
174
+ output path or the usual default, and its configured layout (curved by default).
175
+ Like single-file rendering, this also formats the input files and resolves their
176
+ imports. All directories are searched; symbolic links are not followed.
177
+ Rendering continues after a failed render, with a nonzero exit status if any fail.
178
+
179
+ With Docker, mount your project and set the working directory so `.` refers to
180
+ the mounted project:
181
+
182
+ ```bash
183
+ docker run --rm -v "$(pwd):/work" -w /work ghcr.io/voxlz/graph-gen:latest -r .
184
+ ```
185
+
186
+ Mount a parent directory as well if your configured output paths lead outside
187
+ the project directory.
188
+
189
+ ## Watch for changes
190
+
191
+ Use `--watch` (or `-w`) to watch a path while respecting each graph's
192
+ `outputPath`, the global `style.jsonc` setting, and the built-in default:
193
+
194
+ ```bash
195
+ npx @voxlz/graph-gen --watch path/to/graphs
196
+ ```
197
+
198
+ You can also provide an output directory explicitly:
199
+
200
+ ```bash
201
+ npx @voxlz/graph-gen --watch path/to/graphs path/to/renders
202
+ ```
203
+
204
+ With Docker, mount the graphs and keep the container running:
205
+
206
+ ```bash
207
+ docker run --rm -v "$(pwd):/work" ghcr.io/voxlz/graph-gen:latest --watch /work/graphs /work/renders
208
+ ```
209
+
210
+ ## Publishing releases
211
+
212
+ Version tags (`v*`) publish Docker images and the public npm package
213
+ `@voxlz/graph-gen` through separate GitHub Actions workflows. The tag must match
214
+ the version in `package.json`; update the lockfile and changelog before tagging.
215
+ The npm workflow runs lint, typecheck and tests, then builds the CLI through
216
+ `prepack` and publishes it with provenance.
217
+
218
+ Before the first npm release, configure the repository Actions secret
219
+ `NPM_TOKEN` with a granular npm access token authorized to create/publish the
220
+ scoped `@voxlz/graph-gen` package. The token must permit non-interactive
221
+ publishing (including bypassing 2FA where required). Do not commit the token.
222
+
223
+ To inspect the package locally without publishing:
224
+
225
+ ```bash
226
+ npm pack --dry-run
227
+ ```
228
+
229
+ ## Showcase
230
+
231
+ ### Nodes
232
+
233
+ Declare nodes. These are the elements that will make up your graph:
234
+
235
+ ![Node shapes](renders/demo/showcase/example.png)
236
+
237
+ ```text
238
+ nodes {
239
+ box boxNode: "Box"
240
+ circle circleNode: "Circle"
241
+ actor actorNode: "Actor"
242
+ database dbNode: "Database"
243
+ boundary boundaryNode: "Boundary" {
244
+ box inside: "Inside"
245
+ boundary innerBoundary: "Nested boundary" {
246
+ box deep: "Deep"
247
+ }
248
+ }
249
+ }
250
+ ```
251
+
252
+ ### Edges
253
+
254
+ Connect nodes together with edges:
255
+
256
+ ![Edge connectors](renders/demo/showcase/edges.png)
257
+
258
+ ```text
259
+ edges {
260
+ a1 --> b1
261
+ a2 <-- b2
262
+ a3 <--> b3
263
+ a4 --- b4
264
+ a5 ... b5
265
+ a6 ..> b6
266
+ a7 <.. b7
267
+ a8 <..> b8
268
+ }
269
+ ```
270
+
271
+ ### Constraints
272
+
273
+ Apply alignment constraints and relationships between your nodes to force graph to look a certain way:
274
+
275
+ ![Constraints](renders/demo/showcase/compass.png)
276
+
277
+ ```text
278
+ constraints {
279
+ // eight directions around a center
280
+ n top center
281
+ s bottom center
282
+ e right center
283
+ w left center
284
+ ne topRight center
285
+ nw topLeft center
286
+ se bottomRight center
287
+ sw bottomLeft center
288
+
289
+ // the remaining constraint types
290
+ orbit near hub
291
+ align row rowA rowB
292
+ align col colA colB
293
+ }
294
+ ```
295
+
296
+ `align row` requires every listed node to have the same y coordinate, while
297
+ `align col` requires the same x coordinate.
298
+
299
+ **Constraints and alignments can target a whole group or boundary, not just
300
+ single nodes** — the id expands to all its members, so one rule places or aligns
301
+ an entire cluster (e.g. `core right api` puts the whole `core` group to the right
302
+ of `api`). Rules referencing an unknown id are skipped with a warning.
303
+
304
+ ## Labels
305
+
306
+ Add a label to any node or edge with a trailing `: "..."`:
307
+
308
+ ```text
309
+ box api: "Checkout API" // node label (omit it and the id is used)
310
+ api --> db: "READ {rows}" // edge label
311
+ ```
312
+
313
+ See the [Edges](#edges) showcase for the arrow/line styles
314
+ and [Constraints](#constraints) for placement rules.
315
+
316
+ ### Label formatting templates
317
+
318
+ Use `labelFormat` in the `graph { ... }` block to keep edge labels consistent
319
+ and readable.
320
+
321
+ ```text
322
+ graph {
323
+ labelFormat "{index}. {source} -> {target}: {label}"
324
+ }
325
+ ```
326
+
327
+ You can use these placeholders:
328
+
329
+ - `{index}` (1-based edge index)
330
+ - `{source}`, `{target}`, `{label}`
331
+ - `{arrowSource}`, `{arrowTarget}`
332
+ - `{lineStyle}`, `{line}`
333
+
334
+ Behavior:
335
+
336
+ - Formatting is applied only to labelled edges.
337
+ - Unknown placeholders are left unchanged.
338
+ - If `labelFormat` is omitted or empty, labels are rendered as written.
339
+
340
+ ### Edge label placement
341
+
342
+ Edge label lines wider than `labelMaxWidth` (default `220` px) are wrapped at
343
+ spaces; set it to `0` in the `graph { ... }` block to turn wrapping off.
344
+
345
+ With the `curved` and `orthogonal` engines, each edge label touches its own
346
+ edge, centred on it where there is room. A label beside its edge still has its
347
+ edge pass through its middle, so it never drifts far from the edge. Labels keep clear of nodes (so
348
+ arrowheads stay visible), other labels and other edges.
349
+
350
+ With `curved`, a label that can't fit beside its edge stays where there is room
351
+ and the edge bends to reach it, as long as the bend clears nodes, boundaries and
352
+ other labels. With `orthogonal`, the edge similarly reroutes through the label
353
+ when a clear route is available without adding crossings or hiding bends.
354
+
355
+ With either engine, labels that still can't touch their edge become label nodes and
356
+ the graph is laid out again: each such label pushes other nodes away and its
357
+ edge is routed through it. This repeats until every label touches its edge. Control this with `labelNodes` in the
358
+ `graph { ... }` block (or `GRAPH_GEN_LABEL_NODES`):
359
+
360
+ - `auto` (default): only for labels that can't touch their edge otherwise.
361
+ - `true`: always. Every label sits on its edge, at the cost of larger layouts.
362
+ - `false`: never.
363
+
364
+ If an orthogonal edge still cannot reach its label, the renderer warns and keeps
365
+ the original edge and detached label.
366
+
367
+ ### Group labels
368
+
369
+ Visible boundary titles are label obstacles in every render mode: nodes, edges
370
+ and other labels keep clear of them, including edges entering or leaving that
371
+ boundary. Boundaries reserve enough space for long or multiline titles and for
372
+ nested group labels, even when smaller padding is configured. Hidden groups
373
+ (`draw false`) do not reserve title space.
374
+
375
+ Orthogonal edge runs also keep at least 6 px from parallel group borders.
376
+ Edges can still cross a border to enter or leave a group.
377
+ After labels are placed, orthogonal routes are simplified again to remove
378
+ redundant doglegs while preserving label contact and collision clearances.
379
+ This rejects immediate backtracking and prefers fewer bends over 20 px
380
+ interior sections, while retaining the preference for 20 px endpoint approaches.
381
+
382
+ ## Reuse graph with new edges
383
+
384
+ In threat modeling, you often want to reuse a base graph and add new edges to
385
+ describe a specific data flow. Use `import "..."` and then declare the new
386
+ edges:
387
+
388
+ ```text
389
+ import "../scopes/checkout_scope.ggn"
390
+
391
+ edges {
392
+ customer --> api: "1. GET /checkout"
393
+ }
394
+ ```
395
+
396
+ The imported graph contributes its nodes, boundaries, groups, constraints and
397
+ styles; only the file being rendered contributes edges.
398
+
399
+ ## Styling
400
+
401
+ `style.jsonc` holds the global defaults:
402
+
403
+ - `graph.minGap` — minimum spacing enforced by ordering constraints.
404
+ - `graph.nodeGap` — minimum clear space kept between any two nodes (and between
405
+ a node and boundaries it doesn't belong to).
406
+ - `graph.linkLength` — target (ideal) edge length, centre-to-centre. Kept as a
407
+ flat constant so high-degree hubs don't fling their neighbours far away.
408
+ - `graph.iterations` — the three WebCola solver passes
409
+ `[unconstrained, userConstraint, allConstraint]` (also overridable at runtime
410
+ with `GRAPH_GEN_ITERS=a,b,c`).
411
+ - `shapes.<name>` — per-shape `color`, `lineStyle` (`solid`/`dashed`),
412
+ `minWidth`, `minHeight`, `borderRadius`, and optional `borderColor`. Unknown
413
+ shapes fall back to a plain box.
414
+
415
+ ### Layout engines
416
+
417
+ Set `graph.layout` to choose how nodes and edges are arranged:
418
+
419
+ | Engine | Edge style and crossing behavior | Benefits and trade-offs |
420
+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
421
+ | `curved` (default) | Single smooth curves route around obstacles and penalize crossings. | A good general-purpose choice for compact diagrams: edges can bend instead of pushing nodes apart. Labels are placed on or beside their edges. |
422
+ | `orthogonal` | Horizontal and vertical segments with 90° bends route around obstacles and strongly penalize crossings. | A structured, schematic look that makes direction and parallel connections easy to follow. Detours can add bends or space. |
423
+ | `constraint` | Straight edges; the solver rejects crossings between edges without a shared endpoint and edges through unrelated nodes. | Useful when straight, crossing-free connections are important. Nodes may need more space, and the solver can fail if it cannot find a valid layout. |
424
+ | `cola` | Straight edges from WebCola; edges may cross one another, nodes or labels. | A simple stress-based layout and useful baseline for comparison, especially when compactness matters more than avoiding crossings. |
425
+ | `force` | Straight edges from a force-directed starting layout, followed by constraint repair. | Uses attraction and repulsion to find an arrangement before enforcing the straight-edge constraints. If repair fails, it falls back to a constraint grid seed. |
426
+
427
+ `curved` and `orthogonal` try to avoid obstacles and crossings, but routing is
428
+ not a guarantee that every graph can be drawn without them. Both try several
429
+ starting layouts and score the routed results for crossings, obstacle hits,
430
+ size and edge length. They also support automatic label nodes to help labels
431
+ touch their edges; see [Edge label placement](#edge-label-placement).
432
+
433
+ Orthogonal routes favor side-centred connections, separated parallel runs and
434
+ long, balanced sections. Small alignment differences do not introduce extra
435
+ bends, and labels keep a no-turn margin so the edge direction remains visible.
436
+ Choose `curved` for a softer look, `orthogonal` for a diagram-like style, or
437
+ `constraint` when avoiding crossings with straight edges is more important
438
+ than compactness.
439
+
440
+ Environment variables use the `GRAPH_GEN_` prefix. The former `GRAPHGEN_`
441
+ prefix remains supported as a deprecated alias; if both are set, `GRAPH_GEN_`
442
+ takes precedence.
443
+
444
+ If the same setting appears in multiple places, this precedence applies:
445
+
446
+ 1. `GRAPH_GEN_LAYOUT` environment variable
447
+ 2. per-graph `graph { layout "..." }`
448
+ 3. global style `style.jsonc` (`graph.layout`)
449
+ 4. default `curved`
450
+
451
+ Examples:
452
+
453
+ Global default in `style.jsonc`:
454
+
455
+ ```jsonc
456
+ {
457
+ "graph": {
458
+ "layout": "curved",
459
+ },
460
+ }
461
+ ```
462
+
463
+ Per-graph override:
464
+
465
+ ```text
466
+ graph {
467
+ layout "cola"
468
+ }
469
+ ```
470
+
471
+ You can also set `graph.layoutIterations` (or `GRAPH_GEN_LAYOUT_ITERS`) to
472
+ control how many iterations the `constraint` engine can use before stopping.
473
+
474
+ From a repository checkout, to compare engines on a folder of graphs, run
475
+ `npm run benchmark -- <folder>`. It renders every `.ggn` file with each
476
+ engine in `BENCH_ENGINES` (default `curved,cola`) and reports image area,
477
+ edge lengths, crossings, edges through nodes, label collisions, and layout time.
478
+ `BENCH_FILTER` limits the graphs, `BENCH_JOBS=1` gives reliable timings, and
479
+ Cola results are cached (`BENCH_FRESH=1` re-renders them).
480
+
481
+ For development from a repository checkout, `npm run build` precompiles the renderer into
482
+ `dist/index.js`; run it with `node dist/index.js <input> [output]` instead of
483
+ `tsx src/index.ts` to skip TypeScript transpilation on every run. The watcher,
484
+ `render-all`, `generate` and the benchmark do this automatically, rebuilding
485
+ the bundle when the source changes, and the watcher renders up to four changed
486
+ graphs in parallel.
487
+ The npm and Docker packages already include the precompiled renderer.
488
+
489
+ A graph's own `shapes { ... }` block overrides global shape defaults for that
490
+ graph only, and a custom style file can be passed per render (the optional third
491
+ CLI argument).
492
+ Both `style.jsonc` and JSON inputs may contain `//` comments and trailing commas.