@voxlz/graph-gen 0.0.0-stage → 4.5.2
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 +21 -0
- package/README.md +485 -2
- package/dist/index.js +13283 -0
- package/package.json +60 -4
- package/style.jsonc +72 -0
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,486 @@
|
|
|
1
|
-
#
|
|
1
|
+
# graph-gen
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+

|
|
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 graphgen 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, graphgen 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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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 `GRAPHGEN_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 `GRAPHGEN_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 are positioned:
|
|
418
|
+
|
|
419
|
+
- `curved` (default) — each edge is a single curve routed around nodes and
|
|
420
|
+
boundaries, so nodes don't have to be pushed apart to make room for straight
|
|
421
|
+
edges. Edges never cross each other or pass through nodes, and labels are
|
|
422
|
+
placed beside their edge. Several starting layouts (WebCola variants and a
|
|
423
|
+
grid) are compacted and the most compact routed result is kept.
|
|
424
|
+
- `orthogonal` — like `curved`, but edges are horizontal and vertical segments
|
|
425
|
+
joined by as few 90° bends as possible, connecting at the centre of each
|
|
426
|
+
node's side. Parallel runs aim to stay at least 6 px apart, except for short
|
|
427
|
+
shared attachment stubs. Routes favour straight sections of at least 20 px
|
|
428
|
+
(including beside arrowheads) and balanced bends where obstacles allow.
|
|
429
|
+
Subpixel alignment differences below 0.5 px do not introduce bends; straight
|
|
430
|
+
connections stay within 0.25 px of the side centres. Labels keep a 10 px
|
|
431
|
+
no-turn margin around their padded chips, so edge direction remains visible.
|
|
432
|
+
- `constraint` — straight edges that never cross each other, nodes, or labels.
|
|
433
|
+
It solves from both a grid and a WebCola starting layout and keeps the more
|
|
434
|
+
compact result.
|
|
435
|
+
- `cola` — plain WebCola layout pass (edges may cross nodes and labels).
|
|
436
|
+
- `force` — force-directed layout.
|
|
437
|
+
|
|
438
|
+
If the same setting appears in multiple places, this precedence applies:
|
|
439
|
+
|
|
440
|
+
1. `GRAPHGEN_LAYOUT` environment variable
|
|
441
|
+
2. per-graph `graph { layout "..." }`
|
|
442
|
+
3. global style `style.jsonc` (`graph.layout`)
|
|
443
|
+
4. default `curved`
|
|
444
|
+
|
|
445
|
+
Examples:
|
|
446
|
+
|
|
447
|
+
Global default in `style.jsonc`:
|
|
448
|
+
|
|
449
|
+
```jsonc
|
|
450
|
+
{
|
|
451
|
+
"graph": {
|
|
452
|
+
"layout": "curved",
|
|
453
|
+
},
|
|
454
|
+
}
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
Per-graph override:
|
|
458
|
+
|
|
459
|
+
```text
|
|
460
|
+
graph {
|
|
461
|
+
layout "cola"
|
|
462
|
+
}
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
You can also set `graph.layoutIterations` (or `GRAPHGEN_LAYOUT_ITERS`) to
|
|
466
|
+
control how many iterations the `constraint` engine can use before stopping.
|
|
467
|
+
|
|
468
|
+
From a repository checkout, to compare engines on a folder of graphs, run
|
|
469
|
+
`npm run benchmark -- <folder>`. It renders every `.ggn` file with each
|
|
470
|
+
engine in `BENCH_ENGINES` (default `curved,cola`) and reports image area,
|
|
471
|
+
edge lengths, crossings, edges through nodes, label collisions, and layout time.
|
|
472
|
+
`BENCH_FILTER` limits the graphs, `BENCH_JOBS=1` gives reliable timings, and
|
|
473
|
+
Cola results are cached (`BENCH_FRESH=1` re-renders them).
|
|
474
|
+
|
|
475
|
+
For development from a repository checkout, `npm run build` precompiles the renderer into
|
|
476
|
+
`dist/index.js`; run it with `node dist/index.js <input> [output]` instead of
|
|
477
|
+
`tsx src/index.ts` to skip TypeScript transpilation on every run. The watcher,
|
|
478
|
+
`render-all`, `generate` and the benchmark do this automatically, rebuilding
|
|
479
|
+
the bundle when the source changes, and the watcher renders up to four changed
|
|
480
|
+
graphs in parallel.
|
|
481
|
+
The npm and Docker packages already include the precompiled renderer.
|
|
482
|
+
|
|
483
|
+
A graph's own `shapes { ... }` block overrides global shape defaults for that
|
|
484
|
+
graph only, and a custom style file can be passed per render (the optional third
|
|
485
|
+
CLI argument).
|
|
486
|
+
Both `style.jsonc` and JSON inputs may contain `//` comments and trailing commas.
|