c4studio 0.3.0__tar.gz → 0.4.0__tar.gz

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.
Files changed (60) hide show
  1. {c4studio-0.3.0 → c4studio-0.4.0}/PKG-INFO +224 -7
  2. {c4studio-0.3.0 → c4studio-0.4.0}/README.md +219 -6
  3. {c4studio-0.3.0 → c4studio-0.4.0}/pyproject.toml +5 -1
  4. c4studio-0.4.0/src/c4studio/cli/main.py +890 -0
  5. c4studio-0.4.0/src/c4studio/diff.py +417 -0
  6. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/json_export.py +15 -2
  7. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/graph/view_graph.py +350 -18
  8. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/icons.py +36 -1
  9. c4studio-0.4.0/src/c4studio/impact.py +288 -0
  10. c4studio-0.4.0/src/c4studio/layout_sidecar.py +342 -0
  11. c4studio-0.4.0/src/c4studio/lint.py +437 -0
  12. c4studio-0.4.0/src/c4studio/markdown.py +259 -0
  13. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/views.py +8 -0
  14. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/dsl.py +665 -68
  15. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/json_parser.py +2 -0
  16. c4studio-0.4.0/src/c4studio/publish.py +479 -0
  17. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/render.py +82 -1
  18. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/renderer/diagram-render.mjs +983 -666
  19. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/themes.py +9 -3
  20. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/graph.py +80 -2
  21. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/model_graph.py +3 -0
  22. c4studio-0.4.0/src/c4studio/webapp/perspectives.py +164 -0
  23. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/server.py +397 -174
  24. c4studio-0.4.0/src/c4studio/webapp/static/assets/index-BWKhqzG-.js +95 -0
  25. c4studio-0.4.0/src/c4studio/webapp/static/assets/index-CJj5SYQu.css +1 -0
  26. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/static/index.html +2 -2
  27. c4studio-0.3.0/src/c4studio/cli/main.py +0 -447
  28. c4studio-0.3.0/src/c4studio/webapp/static/assets/index-B7IeVhQr.js +0 -80
  29. c4studio-0.3.0/src/c4studio/webapp/static/assets/index-BosnE_L9.css +0 -1
  30. {c4studio-0.3.0 → c4studio-0.4.0}/LICENSE +0 -0
  31. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/__init__.py +0 -0
  32. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/__main__.py +0 -0
  33. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/cli/__init__.py +0 -0
  34. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/diagnostics.py +0 -0
  35. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/__init__.py +0 -0
  36. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/flowchart.py +0 -0
  37. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/mermaid.py +0 -0
  38. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/mermaid_common.py +0 -0
  39. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/graph/__init__.py +0 -0
  40. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/__init__.py +0 -0
  41. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/deployment.py +0 -0
  42. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/documentation.py +0 -0
  43. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/elements.py +0 -0
  44. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/enums.py +0 -0
  45. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/workspace.py +0 -0
  46. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/__init__.py +0 -0
  47. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/docs.py +0 -0
  48. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/expressions.py +0 -0
  49. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/implied.py +0 -0
  50. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/locations.py +0 -0
  51. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/sourcemap.py +0 -0
  52. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/py.typed +0 -0
  53. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/deployment.dsl +0 -0
  54. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/full-c4.dsl +0 -0
  55. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/minimal.dsl +0 -0
  56. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/system-context.dsl +0 -0
  57. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates.py +0 -0
  58. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/__init__.py +0 -0
  59. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/assistant.py +0 -0
  60. {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/loader.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: c4studio
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Parse Structurizr DSL/JSON and generate C4 diagrams in Mermaid, with a CLI and a React web app
5
5
  Keywords: structurizr,c4,architecture,diagrams,dsl
6
6
  Author: Geoffrey Koh
@@ -21,7 +21,11 @@ Requires-Dist: pytest>=8.0 ; extra == 'dev'
21
21
  Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
22
22
  Requires-Dist: anthropic>=1.0 ; extra == 'dev'
23
23
  Requires-Python: >=3.13
24
+ Project-URL: Homepage, https://github.com/geoffkoh/c4studio
24
25
  Project-URL: Repository, https://github.com/geoffkoh/c4studio
26
+ Project-URL: Documentation, https://github.com/geoffkoh/c4studio/blob/main/docs/dsl-reference.md
27
+ Project-URL: Issues, https://github.com/geoffkoh/c4studio/issues
28
+ Project-URL: Migration guide, https://github.com/geoffkoh/c4studio/blob/main/docs/MIGRATION.md
25
29
  Provides-Extra: assistant
26
30
  Provides-Extra: dev
27
31
  Description-Content-Type: text/markdown
@@ -57,7 +61,11 @@ Requires Python 3.13+ (uv/uvx can provision it automatically).
57
61
  - ✅ Mermaid diagram generation — C4 syntax or `flowchart`/`subgraph`
58
62
  - ✅ Headless SVG rendering for CI and docs-as-code
59
63
  - ✅ Comprehensive type hints
60
- - ✅ Custom properties and perspectives on all elements
64
+ - ✅ **Perspectives** — annotate elements and relationships with security,
65
+ ownership or anything else, then show one over the diagram
66
+ - ✅ **`c4 lint`** — model standards in CI: orphans, missing descriptions,
67
+ duplicate relationships, styles that match nothing
68
+ - ✅ Custom properties on all elements
61
69
  - ✅ Deployment infrastructure modeling
62
70
  - ✅ Style and configuration management
63
71
  - ⚙️ Optional AI assistant — off by default, and the only feature that
@@ -90,8 +98,11 @@ uv run c4 webapp samples/ --viewer # read-only, for a kiosk or an embed
90
98
 
91
99
  ### Editing
92
100
 
93
- The **Source** tab is a [CodeMirror 6](https://codemirror.net/) editor with
94
- the diagram beside it:
101
+ The source editor is a [CodeMirror 6](https://codemirror.net/) panel that
102
+ opens beside the diagram — from the **Source** button at the right of the
103
+ top bar, the `e` key, the rail on the diagram's right edge, or *Open in
104
+ Source* on any element. The diagram stays put while it opens, and a ● on
105
+ the button marks unsaved work behind a closed editor.
95
106
 
96
107
  - **Syntax highlighting and autocomplete** for DSL keywords, your own element
97
108
  identifiers, and view keys — drawn from the loaded workspace, so it knows
@@ -127,11 +138,12 @@ independent of any curated view — at a selectable abstraction level
127
138
  (systems / containers / components), with search across every element
128
139
  (press `/`), and a details panel showing an element's metadata,
129
140
  relationships, the views it appears in (click to jump) and a
130
- show-definition link into the Source pane.
141
+ show-definition link that opens the source editor.
131
142
 
132
143
  The built SPA ships inside the package (`c4studio/webapp/static/`),
133
144
  so end users need no Node toolchain. To rebuild the frontend after
134
- changes (requires Node 18+):
145
+ changes (requires Node 20.19+ or 22.12+, what Vite asks for — distinct
146
+ from the Node 18+ that `c4 render` needs at runtime, below):
135
147
 
136
148
  The frontend is an npm workspace: `packages/diagram-core` holds the
137
149
  diagram layer (layout, node/edge components, image export) and
@@ -274,6 +286,211 @@ uv run c4 generate architecture.dsl -f flowchart # flowchart
274
286
  uv run c4 generate architecture.dsl -f flowchart -o out # one .mmd per view
275
287
  ```
276
288
 
289
+ ## Perspectives
290
+ A perspective is a named annotation you hang on elements and
291
+ relationships — security, ownership, cost, anything — and then **show over
292
+ the diagram**. What carries it keeps its place and gets a badge with its
293
+ value; everything else fades. The legend follows, listing the values
294
+ rather than the element styles the diagram is no longer painted with.
295
+
296
+ ```
297
+ api = container "Payments API" "Authorises and captures." "Python, FastAPI" {
298
+ perspectives {
299
+ "security" "mTLS to the ledger, PCI DSS scope." "High"
300
+ }
301
+ }
302
+ ```
303
+
304
+ ![The security perspective shown over a container diagram: two containers
305
+ badged "High", a person badged "Medium", the rest faded, and a legend of
306
+ the values](https://raw.githubusercontent.com/geoffkoh/c4studio/main/docs/images/perspective-overlay.png)
307
+
308
+ Colour comes from ordinary styles, matched on the perspective and
309
+ optionally on its value:
310
+
311
+ ```
312
+ element "Perspective:security[value==High]" {
313
+ background #2e7d32
314
+ color #ffffff
315
+ }
316
+ ```
317
+
318
+ The same overlay is available everywhere the diagram is:
319
+
320
+ ```bash
321
+ uv run c4 render architecture.dsl --perspective security -o diagrams/
322
+ ```
323
+
324
+ and in the VS Code preview through **C4Studio: Show Perspective…**. A
325
+ perspective carrying a `url` instead of a value has that value **read
326
+ live** — off by default, because the addresses come from the workspace
327
+ file; `c4 webapp --dynamic-perspectives` turns it on.
328
+
329
+ ## Publish a site
330
+ Turn the model into something people read without installing anything:
331
+
332
+ ```bash
333
+ uv run c4 publish architecture.dsl -o site/
334
+ ```
335
+
336
+ Every view becomes its own page — not one page with a switcher, so a link
337
+ to a diagram survives being pasted into a ticket — with the `!docs` prose
338
+ and the ADRs beside them and navigation between. The result is
339
+ **self-contained**: diagrams are inlined SVG and theme icons are embedded
340
+ as `data:` URIs, so it works from a `file://` path, on an air-gapped
341
+ machine, or on any static host.
342
+
343
+ Published diagrams follow the layout you arranged in the Studio
344
+ (`--no-layout` for a fresh one), and `--perspective security` draws the
345
+ whole site through one perspective.
346
+
347
+ To publish on every merge, add the site to a Pages workflow:
348
+
349
+ ```yaml
350
+ - uses: actions/checkout@v7
351
+ - uses: actions/setup-node@v6 # c4 render needs Node
352
+ with:
353
+ node-version: "20"
354
+ - run: pipx install c4studio
355
+ - run: c4 publish architecture.dsl -o site/
356
+ - uses: actions/upload-pages-artifact@v4
357
+ with:
358
+ path: site/
359
+ - uses: actions/deploy-pages@v4
360
+ ```
361
+
362
+ ## What changed (`c4 diff`)
363
+ A pull request that changes the architecture should say what it changed:
364
+
365
+ ```bash
366
+ uv run c4 diff architecture.dsl # working tree vs HEAD
367
+ uv run c4 diff architecture.dsl --from main --to HEAD --json
368
+ ```
369
+
370
+ Elements and relationships added, removed and changed — and **the views a
371
+ reviewer has to look at again**. A comment-only edit produces nothing,
372
+ which is the signal worth having.
373
+
374
+ Renaming an element that has an alias is reported as a change. Renaming
375
+ one *without* an alias reads as a removal and an addition, because its id
376
+ comes from its name and nothing ties the two together; when a removal and
377
+ an addition share a name, the pair is flagged as a **possible** rename
378
+ rather than assumed. A diff that invents a rename hides a deletion.
379
+
380
+ ### On every pull request
381
+
382
+ `c4 diff` needs no Node, so a short workflow can post the answer on each
383
+ pull request that touches the model, updating its own comment on every
384
+ push rather than adding one per push:
385
+
386
+ ```yaml
387
+ name: Architecture diff
388
+
389
+ on:
390
+ pull_request:
391
+ paths:
392
+ - "architecture/**"
393
+
394
+ permissions:
395
+ contents: read
396
+ pull-requests: write # to comment
397
+
398
+ jobs:
399
+ diff:
400
+ runs-on: ubuntu-latest
401
+ steps:
402
+ - uses: actions/checkout@v7
403
+ with:
404
+ fetch-depth: 0 # c4 diff reads the base revision from git history
405
+
406
+ - run: pipx install c4studio # no Node needed: diff compares models
407
+
408
+ - name: Diff the model against the target branch
409
+ env:
410
+ BASE: origin/${{ github.base_ref }}
411
+ run: |
412
+ {
413
+ echo "### Architecture changes"
414
+ echo
415
+ echo '```text'
416
+ # A failure is shown rather than failing the job: a workspace
417
+ # the base branch does not have yet cannot be compared.
418
+ c4 diff architecture/workspace.dsl --from "$BASE" --to HEAD 2>&1 \
419
+ || echo "c4 diff could not compare these revisions (exit $?)"
420
+ echo '```'
421
+ } > architecture-diff.md
422
+ # The job summary works where a comment cannot: a pull request
423
+ # from a fork gets a read-only token.
424
+ cat architecture-diff.md >> "$GITHUB_STEP_SUMMARY"
425
+
426
+ - name: Comment on the pull request
427
+ env:
428
+ GH_TOKEN: ${{ github.token }}
429
+ PR: ${{ github.event.pull_request.number }}
430
+ run: gh pr comment "$PR" --body-file architecture-diff.md --edit-last --create-if-none
431
+ ```
432
+
433
+ It reads the base branch from git history, hence `fetch-depth: 0`. A
434
+ workspace the base branch does not have yet cannot be compared, and the
435
+ comment says so instead of failing the job. `--edit-last` edits the
436
+ latest comment made with the workflow's token, so keep this the only
437
+ step that comments with it — or give it a token of its own. Diagrams are
438
+ the action's job (`mode: comment`); this posts the model change, which is
439
+ what a reviewer needs before looking at any of them.
440
+
441
+ ## Impact analysis
442
+ What else is involved when one element changes — asked of the model
443
+ rather than of whoever remembers:
444
+
445
+ ```bash
446
+ uv run c4 impact architecture.dsl paymentsApi
447
+ uv run c4 impact architecture.dsl paymentsApi --json --depth 2
448
+ ```
449
+
450
+ Dependents (what reaches it, and so may break when it changes),
451
+ dependencies (what it reaches, and so may break it), each with how many
452
+ relationships away it is, plus **the views that draw it** — so a change
453
+ advisory board knows which diagrams to open.
454
+
455
+ Containment counts in both directions: a relationship declared against a
456
+ container is one its software system takes part in, which is the same
457
+ rule the views apply when they lift an edge to the nearest visible
458
+ ancestor. An answer that ignored the hierarchy would disagree with the
459
+ diagrams it is about.
460
+
461
+ The same answer is on the Diagrams page: select an element, open its
462
+ details (`i`), and choose **Show impact**. The view repaints — the element
463
+ and whatever contains it marked *Changed*, what depends on it and what it
464
+ depends on in their own colours, the rest faded — and the card gives the
465
+ model-wide counts and how many views draw it. It stays on as you move
466
+ between views; the chip in the toolbar clears it, and choosing a
467
+ perspective replaces it.
468
+
469
+ ## Model standards (`c4 lint`)
470
+ Where `c4 check` asks whether a file parses, `c4 lint` asks whether it is
471
+ a good model — the review comments someone would otherwise have to make
472
+ every time:
473
+
474
+ ```bash
475
+ uv run c4 lint architecture.dsl
476
+ ```
477
+
478
+ Orphaned elements, missing descriptions and technologies, relationships
479
+ declared twice, and styles whose tag nothing carries (invisible
480
+ otherwise, because the legend only lists styles in use). Every finding is
481
+ a warning — a model that breaks a house style still parses and renders —
482
+ so the **exit code** is what gates CI: 1 on any finding, `--exit-zero` to
483
+ report without failing on a model nobody has linted before.
484
+
485
+ Configure it in `c4studio.lint.json` beside the workspace:
486
+
487
+ ```json
488
+ {"ignore": ["missing-technology"], "naming": {"container": "^[A-Z]"}}
489
+ ```
490
+
491
+ `--json` emits the same shape editors already read, so findings land in
492
+ the Studio's problems list and the VS Code Problems panel.
493
+
277
494
  ## Headless SVG Rendering
278
495
  `c4 render` draws diagrams as standalone SVG with no browser
279
496
  and no server — for CI, docs-as-code pipelines and static sites. Layout is
@@ -361,8 +578,8 @@ code --install-extension c4studio-vscode-*.vsix
361
578
  ```
362
579
 
363
580
  ## Documentation
581
+ - **[DSL Reference](./docs/dsl-reference.md)** - **How to write DSL for c4studio**: every construct, the `c4studio.*` extensions, and what is silently ignored. Examples are parsed by the test suite
364
582
  - **[DSL Language Support](./docs/dsl-support.md)** - Every keyword in the Structurizr DSL and whether c4studio supports it
365
- - **[Data Models Reference](./docs/data-models.md)** - Complete guide to all Structurizr models and their fields
366
583
  - **[Getting Started](./docs/README.md)** - Workflow and common patterns
367
584
  - **[Studio Editor Plan](./docs/studio-editor-plan.md)** - How the editor was designed and built, and the decisions behind it
368
585
  - **[Migration Guide](./docs/MIGRATION.md)** - Breaking changes, including the 0.3.0 Studio-by-default flip
@@ -29,7 +29,11 @@ Requires Python 3.13+ (uv/uvx can provision it automatically).
29
29
  - ✅ Mermaid diagram generation — C4 syntax or `flowchart`/`subgraph`
30
30
  - ✅ Headless SVG rendering for CI and docs-as-code
31
31
  - ✅ Comprehensive type hints
32
- - ✅ Custom properties and perspectives on all elements
32
+ - ✅ **Perspectives** — annotate elements and relationships with security,
33
+ ownership or anything else, then show one over the diagram
34
+ - ✅ **`c4 lint`** — model standards in CI: orphans, missing descriptions,
35
+ duplicate relationships, styles that match nothing
36
+ - ✅ Custom properties on all elements
33
37
  - ✅ Deployment infrastructure modeling
34
38
  - ✅ Style and configuration management
35
39
  - ⚙️ Optional AI assistant — off by default, and the only feature that
@@ -62,8 +66,11 @@ uv run c4 webapp samples/ --viewer # read-only, for a kiosk or an embed
62
66
 
63
67
  ### Editing
64
68
 
65
- The **Source** tab is a [CodeMirror 6](https://codemirror.net/) editor with
66
- the diagram beside it:
69
+ The source editor is a [CodeMirror 6](https://codemirror.net/) panel that
70
+ opens beside the diagram — from the **Source** button at the right of the
71
+ top bar, the `e` key, the rail on the diagram's right edge, or *Open in
72
+ Source* on any element. The diagram stays put while it opens, and a ● on
73
+ the button marks unsaved work behind a closed editor.
67
74
 
68
75
  - **Syntax highlighting and autocomplete** for DSL keywords, your own element
69
76
  identifiers, and view keys — drawn from the loaded workspace, so it knows
@@ -99,11 +106,12 @@ independent of any curated view — at a selectable abstraction level
99
106
  (systems / containers / components), with search across every element
100
107
  (press `/`), and a details panel showing an element's metadata,
101
108
  relationships, the views it appears in (click to jump) and a
102
- show-definition link into the Source pane.
109
+ show-definition link that opens the source editor.
103
110
 
104
111
  The built SPA ships inside the package (`c4studio/webapp/static/`),
105
112
  so end users need no Node toolchain. To rebuild the frontend after
106
- changes (requires Node 18+):
113
+ changes (requires Node 20.19+ or 22.12+, what Vite asks for — distinct
114
+ from the Node 18+ that `c4 render` needs at runtime, below):
107
115
 
108
116
  The frontend is an npm workspace: `packages/diagram-core` holds the
109
117
  diagram layer (layout, node/edge components, image export) and
@@ -246,6 +254,211 @@ uv run c4 generate architecture.dsl -f flowchart # flowchart
246
254
  uv run c4 generate architecture.dsl -f flowchart -o out # one .mmd per view
247
255
  ```
248
256
 
257
+ ## Perspectives
258
+ A perspective is a named annotation you hang on elements and
259
+ relationships — security, ownership, cost, anything — and then **show over
260
+ the diagram**. What carries it keeps its place and gets a badge with its
261
+ value; everything else fades. The legend follows, listing the values
262
+ rather than the element styles the diagram is no longer painted with.
263
+
264
+ ```
265
+ api = container "Payments API" "Authorises and captures." "Python, FastAPI" {
266
+ perspectives {
267
+ "security" "mTLS to the ledger, PCI DSS scope." "High"
268
+ }
269
+ }
270
+ ```
271
+
272
+ ![The security perspective shown over a container diagram: two containers
273
+ badged "High", a person badged "Medium", the rest faded, and a legend of
274
+ the values](https://raw.githubusercontent.com/geoffkoh/c4studio/main/docs/images/perspective-overlay.png)
275
+
276
+ Colour comes from ordinary styles, matched on the perspective and
277
+ optionally on its value:
278
+
279
+ ```
280
+ element "Perspective:security[value==High]" {
281
+ background #2e7d32
282
+ color #ffffff
283
+ }
284
+ ```
285
+
286
+ The same overlay is available everywhere the diagram is:
287
+
288
+ ```bash
289
+ uv run c4 render architecture.dsl --perspective security -o diagrams/
290
+ ```
291
+
292
+ and in the VS Code preview through **C4Studio: Show Perspective…**. A
293
+ perspective carrying a `url` instead of a value has that value **read
294
+ live** — off by default, because the addresses come from the workspace
295
+ file; `c4 webapp --dynamic-perspectives` turns it on.
296
+
297
+ ## Publish a site
298
+ Turn the model into something people read without installing anything:
299
+
300
+ ```bash
301
+ uv run c4 publish architecture.dsl -o site/
302
+ ```
303
+
304
+ Every view becomes its own page — not one page with a switcher, so a link
305
+ to a diagram survives being pasted into a ticket — with the `!docs` prose
306
+ and the ADRs beside them and navigation between. The result is
307
+ **self-contained**: diagrams are inlined SVG and theme icons are embedded
308
+ as `data:` URIs, so it works from a `file://` path, on an air-gapped
309
+ machine, or on any static host.
310
+
311
+ Published diagrams follow the layout you arranged in the Studio
312
+ (`--no-layout` for a fresh one), and `--perspective security` draws the
313
+ whole site through one perspective.
314
+
315
+ To publish on every merge, add the site to a Pages workflow:
316
+
317
+ ```yaml
318
+ - uses: actions/checkout@v7
319
+ - uses: actions/setup-node@v6 # c4 render needs Node
320
+ with:
321
+ node-version: "20"
322
+ - run: pipx install c4studio
323
+ - run: c4 publish architecture.dsl -o site/
324
+ - uses: actions/upload-pages-artifact@v4
325
+ with:
326
+ path: site/
327
+ - uses: actions/deploy-pages@v4
328
+ ```
329
+
330
+ ## What changed (`c4 diff`)
331
+ A pull request that changes the architecture should say what it changed:
332
+
333
+ ```bash
334
+ uv run c4 diff architecture.dsl # working tree vs HEAD
335
+ uv run c4 diff architecture.dsl --from main --to HEAD --json
336
+ ```
337
+
338
+ Elements and relationships added, removed and changed — and **the views a
339
+ reviewer has to look at again**. A comment-only edit produces nothing,
340
+ which is the signal worth having.
341
+
342
+ Renaming an element that has an alias is reported as a change. Renaming
343
+ one *without* an alias reads as a removal and an addition, because its id
344
+ comes from its name and nothing ties the two together; when a removal and
345
+ an addition share a name, the pair is flagged as a **possible** rename
346
+ rather than assumed. A diff that invents a rename hides a deletion.
347
+
348
+ ### On every pull request
349
+
350
+ `c4 diff` needs no Node, so a short workflow can post the answer on each
351
+ pull request that touches the model, updating its own comment on every
352
+ push rather than adding one per push:
353
+
354
+ ```yaml
355
+ name: Architecture diff
356
+
357
+ on:
358
+ pull_request:
359
+ paths:
360
+ - "architecture/**"
361
+
362
+ permissions:
363
+ contents: read
364
+ pull-requests: write # to comment
365
+
366
+ jobs:
367
+ diff:
368
+ runs-on: ubuntu-latest
369
+ steps:
370
+ - uses: actions/checkout@v7
371
+ with:
372
+ fetch-depth: 0 # c4 diff reads the base revision from git history
373
+
374
+ - run: pipx install c4studio # no Node needed: diff compares models
375
+
376
+ - name: Diff the model against the target branch
377
+ env:
378
+ BASE: origin/${{ github.base_ref }}
379
+ run: |
380
+ {
381
+ echo "### Architecture changes"
382
+ echo
383
+ echo '```text'
384
+ # A failure is shown rather than failing the job: a workspace
385
+ # the base branch does not have yet cannot be compared.
386
+ c4 diff architecture/workspace.dsl --from "$BASE" --to HEAD 2>&1 \
387
+ || echo "c4 diff could not compare these revisions (exit $?)"
388
+ echo '```'
389
+ } > architecture-diff.md
390
+ # The job summary works where a comment cannot: a pull request
391
+ # from a fork gets a read-only token.
392
+ cat architecture-diff.md >> "$GITHUB_STEP_SUMMARY"
393
+
394
+ - name: Comment on the pull request
395
+ env:
396
+ GH_TOKEN: ${{ github.token }}
397
+ PR: ${{ github.event.pull_request.number }}
398
+ run: gh pr comment "$PR" --body-file architecture-diff.md --edit-last --create-if-none
399
+ ```
400
+
401
+ It reads the base branch from git history, hence `fetch-depth: 0`. A
402
+ workspace the base branch does not have yet cannot be compared, and the
403
+ comment says so instead of failing the job. `--edit-last` edits the
404
+ latest comment made with the workflow's token, so keep this the only
405
+ step that comments with it — or give it a token of its own. Diagrams are
406
+ the action's job (`mode: comment`); this posts the model change, which is
407
+ what a reviewer needs before looking at any of them.
408
+
409
+ ## Impact analysis
410
+ What else is involved when one element changes — asked of the model
411
+ rather than of whoever remembers:
412
+
413
+ ```bash
414
+ uv run c4 impact architecture.dsl paymentsApi
415
+ uv run c4 impact architecture.dsl paymentsApi --json --depth 2
416
+ ```
417
+
418
+ Dependents (what reaches it, and so may break when it changes),
419
+ dependencies (what it reaches, and so may break it), each with how many
420
+ relationships away it is, plus **the views that draw it** — so a change
421
+ advisory board knows which diagrams to open.
422
+
423
+ Containment counts in both directions: a relationship declared against a
424
+ container is one its software system takes part in, which is the same
425
+ rule the views apply when they lift an edge to the nearest visible
426
+ ancestor. An answer that ignored the hierarchy would disagree with the
427
+ diagrams it is about.
428
+
429
+ The same answer is on the Diagrams page: select an element, open its
430
+ details (`i`), and choose **Show impact**. The view repaints — the element
431
+ and whatever contains it marked *Changed*, what depends on it and what it
432
+ depends on in their own colours, the rest faded — and the card gives the
433
+ model-wide counts and how many views draw it. It stays on as you move
434
+ between views; the chip in the toolbar clears it, and choosing a
435
+ perspective replaces it.
436
+
437
+ ## Model standards (`c4 lint`)
438
+ Where `c4 check` asks whether a file parses, `c4 lint` asks whether it is
439
+ a good model — the review comments someone would otherwise have to make
440
+ every time:
441
+
442
+ ```bash
443
+ uv run c4 lint architecture.dsl
444
+ ```
445
+
446
+ Orphaned elements, missing descriptions and technologies, relationships
447
+ declared twice, and styles whose tag nothing carries (invisible
448
+ otherwise, because the legend only lists styles in use). Every finding is
449
+ a warning — a model that breaks a house style still parses and renders —
450
+ so the **exit code** is what gates CI: 1 on any finding, `--exit-zero` to
451
+ report without failing on a model nobody has linted before.
452
+
453
+ Configure it in `c4studio.lint.json` beside the workspace:
454
+
455
+ ```json
456
+ {"ignore": ["missing-technology"], "naming": {"container": "^[A-Z]"}}
457
+ ```
458
+
459
+ `--json` emits the same shape editors already read, so findings land in
460
+ the Studio's problems list and the VS Code Problems panel.
461
+
249
462
  ## Headless SVG Rendering
250
463
  `c4 render` draws diagrams as standalone SVG with no browser
251
464
  and no server — for CI, docs-as-code pipelines and static sites. Layout is
@@ -333,8 +546,8 @@ code --install-extension c4studio-vscode-*.vsix
333
546
  ```
334
547
 
335
548
  ## Documentation
549
+ - **[DSL Reference](./docs/dsl-reference.md)** - **How to write DSL for c4studio**: every construct, the `c4studio.*` extensions, and what is silently ignored. Examples are parsed by the test suite
336
550
  - **[DSL Language Support](./docs/dsl-support.md)** - Every keyword in the Structurizr DSL and whether c4studio supports it
337
- - **[Data Models Reference](./docs/data-models.md)** - Complete guide to all Structurizr models and their fields
338
551
  - **[Getting Started](./docs/README.md)** - Workflow and common patterns
339
552
  - **[Studio Editor Plan](./docs/studio-editor-plan.md)** - How the editor was designed and built, and the decisions behind it
340
553
  - **[Migration Guide](./docs/MIGRATION.md)** - Breaking changes, including the 0.3.0 Studio-by-default flip
@@ -4,7 +4,7 @@
4
4
  # project. C4 is the notation, not a vendor's product, so the name stays
5
5
  # honest even if support broadens beyond Structurizr DSL.
6
6
  name = "c4studio"
7
- version = "0.3.0"
7
+ version = "0.4.0"
8
8
  description = "Parse Structurizr DSL/JSON and generate C4 diagrams in Mermaid, with a CLI and a React web app"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -28,7 +28,11 @@ dependencies = [
28
28
  ]
29
29
 
30
30
  [project.urls]
31
+ Homepage = "https://github.com/geoffkoh/c4studio"
31
32
  Repository = "https://github.com/geoffkoh/c4studio"
33
+ Documentation = "https://github.com/geoffkoh/c4studio/blob/main/docs/dsl-reference.md"
34
+ Issues = "https://github.com/geoffkoh/c4studio/issues"
35
+ "Migration guide" = "https://github.com/geoffkoh/c4studio/blob/main/docs/MIGRATION.md"
32
36
 
33
37
  [project.optional-dependencies]
34
38
  # The assistant is the one feature that leaves the machine, and the only