Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions .github/skills/erd-viewer/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
name: erd-viewer
description: Verifies the generated Entity Framework ER diagram viewer in a real browser. Use this skill when asked to run, drive, screenshot or visually check the ER diagram, the interactive viewer, or the Mermaid preview — or after changing anything under src/src/EntityFrameworkCore/Assets/.
---

## Verifying the ER diagram viewer

The interactive viewer is the default renderer and it is **all browser**: ELK layout, card measurement,
edge markers, search, theming and the complex value-object folds only run once a browser has loaded
`app.js`. A green `just test` says nothing about any of it — the C# suite stops at the model JSON.

Do **not** hand-roll a driver. There is already a Playwright harness.

### The one command

```sh
just erd-check
```

That recipe does both halves: `scripts/erd-vendor.mts` populates `artifacts/erd-viewer-check/vendor`,
then `scripts/erd-viewer-check.mts` assembles the viewer from source, serves it, drives it in Chromium
and prints one `ok`/`FAIL` line per check. It exits non-zero if any check failed.

It defaults to `src/src/TestAppHost/.aspirec4/erd/schema.gen.json` as its model. Pass another:

```sh
just erd-check artifacts/some-other-model.json
just erd-mermaid-check # the Mermaid preview instead
```

Prerequisite, once per machine:

```sh
bunx playwright install chromium
```

### Getting a model to check against

The default model is whatever the sample AppHost last wrote. If it is missing or stale, regenerate it:

```sh
dotnet run --project src/src/TestAppHost
```

Wait for `src/src/TestAppHost/.aspirec4/erd/schema.gen.json` to appear, then stop the AppHost. Stopping
it by killing the process leaves its containers running — `docker ps` and remove them, or they hold
ports the next run wants. `.aspirec4/` is gitignored.

The suite needs a model with some variety in it, because several checks pick their own target from the
model: a self-referencing table, a column name no table name contains, a context holding more than one
table, and at least one flattened complex value object. The `TestAppHost.ComplexData` sample is built to
supply all four — prefer it over a hand-trimmed model.

### Reading the output

Each line is one assertion with the measurement beside it, which is the point — `120px` tells you what
the layout did, not merely that it passed. Artefacts land in `artifacts/erd-viewer-check/`:
`viewer-check.png`, `viewer-check-dark.png`, and the exported `viewer-export.svg` / `.png`.

Two traps that have bitten before:

- **Screen pixels are not layout pixels.** The view is zoomed to fit, so a 56px layout offset is 28
screen pixels at scale 0.5. Every geometric assertion divides by the viewport scale first. A check
that forgets passes on a small schema and fails the moment the diagram grows.
- **`fitContexts` pins a container's top to its topmost table.** Dragging that table carries the whole
container with it, so its offset within the context never changes. Assertions about dragging or about
a remembered arrangement must target a table that is *not* the topmost, or they hold vacuously.

### Adding a check

Add it to `scripts/erd-viewer-check.mts` next to the related section and let it run in the existing
`for (const reducedMotion of ...)` loop. Use `check(name, ok, detail)` — never `throw` — so one failure
does not hide the rest, and put the measurement in `detail`.

Derive targets from the model rather than hard-coding a table name, the way the existing column-search
check does, so the suite survives a change to the sample.

### When a screenshot is the actual question

If the task is "does this *look* right" rather than "does it work", the suite already writes
`viewer-check.png` and `viewer-check-dark.png` on every run — read those first. Only reach for a bespoke
Playwright script when you need an interaction the suite does not perform, and then put it in
`scripts/` and delete it again, or add it to the suite properly.

### Related

- `just erd-vendor` rebuilds the viewer's bundled JavaScript; pass `--embed` to refresh the copies
shipped inside the package after a dependency bump.
- `just erd-svg <input>` renders an emitted Mermaid `.mmd` to SVG through a one-shot container.
12 changes: 11 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -674,4 +674,14 @@ BenchmarkDotNet.Artifacts/
# AspireC4 generated diagram output (architecture diagram, ER diagram, and the ER viewer's bundled
# JS dependencies). Regenerated on every AppHost run, and the LikeC4 model embeds ephemeral localhost
# ports, so tracking it guarantees a dirty tree after every run.
**/.aspirec4/
#
# The exported images are the exception, and are tracked deliberately: they are the artefact the
# export exists to produce, and a diagram that is reviewable in a pull request is worth having in
# source control. Written only when the diagram actually changes, so they do not churn — and the
# stamp beside them ignores the ephemeral ports that would otherwise redraw them on every run.
# Note the trailing /* rather than /: git will not descend into an excluded directory, so the
# children have to be excluded individually for the re-include below to be reachable.
**/.aspirec4/*
!**/.aspirec4/images/
# The stamp recording what the images were rendered from is a local cache, not documentation.
**/.aspirec4/images/.aspirec4-*
22 changes: 22 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,22 @@ just test-e2e-cli # All local CLI runtimes only
just test-e2e-npm # Single CLI runtime (also -pnpm, -yarn, -bun, -deno)
```

### ER diagram viewer

The interactive viewer under `src/src/EntityFrameworkCore/Assets/viewer/` only runs in a browser, so
`just test` proves nothing about it. Drive it with Playwright instead — **never hand-roll a driver**:

```sh
just erd-check # Drive the viewer in Chromium and assert it renders, lays out and searches
just erd-mermaid-check # The same for the Mermaid preview
just erd-vendor # Rebuild the viewer's bundled JavaScript (--embed refreshes the shipped copies)
just erd-svg <input> # Render an emitted Mermaid .mmd to SVG in a one-shot container
```

`erd-check` defaults to the model at `src/src/TestAppHost/.aspirec4/erd/schema.gen.json`, written by
`dotnet run --project src/src/TestAppHost`. Requires `bunx playwright install chromium` once. See the
`erd-viewer` skill in `.github/skills/` before changing the viewer or its checks.

### Other

```sh
Expand Down Expand Up @@ -312,6 +328,12 @@ gitignored; `skills-lock.json` is the tracked record of what was installed there
own skills are never installed into it - that would leave two copies to drift apart. Read them at
their authored path, `skills/<name>/SKILL.md`.

`.github/skills/` is a third, separate place: skills about working *in* this repository, which would
be meaningless to a consumer who installed the published set. `release` and `erd-viewer` live there.
A skill that tells you how to run this repo's own tooling belongs in `.github/skills/`, never in
`skills/` - `SkillTests` requires everything under `skills/` to carry the `purview-aspirec4` prefix
because those names land in a directory shared with every skill a developer has installed.

```bash
npx skills add purview-dev/aspirec4
```
Expand Down
156 changes: 156 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,11 @@ Configure the diagram through `AspireC4DiagramOptions`:
| `HideFromDashboard` | `false` | Hide the LikeC4 sidecar from the Aspire dashboard |
| `DashboardLinkDisplayName` | `"Architecture Diagram"` | Name used for the diagram link when hidden from the dashboard |
| `IncludeAspireDashboardLinks` | `true` | Add Aspire dashboard links to diagram elements |
| `ExportImages` | `true` | Write every view out as an image whenever the model changes — see [Export the views as images](#export-the-views-as-images) |
| `ImageFormats` | `{Png}` | `Png` and/or `Jpg`. **No SVG** — `likec4 export` does not offer one |
| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | Where images are written; relative paths resolve against the AppHost directory. Shared with the ER diagram |
| `ImageExportTimeoutSeconds` | `300` | How long to wait for one `likec4 export` invocation |
| `ContainerRuntimeCommand` | `"docker"` | Runtime for the one-shot export container; `podman` where that is what Aspire uses |

## Common options

Expand All @@ -97,6 +102,91 @@ builder.AddAspireC4(options => options.WithHMRDisabled());

The LikeC4 sidecar is excluded automatically. Set `WithIncludeAspireC4InternalResource(true)` in the options callback if you want to inspect it.

### Export the views as images

On by default. Every view is written out as a PNG whenever the generated model changes, so a diagram can
be attached to a pull request or pasted into a wiki without running the server.

**Both diagrams export into one folder**, `./.aspirec4/images/`, so there is a single place to look:

```text
apphost/.aspirec4/images/
architecture-index.png <- architecture diagram, one file per view
architecture-services.png
schema.svg <- ER diagram
schema.png
```

The architecture diagram's files carry an `architecture-` prefix, because `likec4 export` names each
file after its view id and a bare `index.png` says nothing in a shared folder. The ER diagram's row in
the dashboard carries an **Images** property with the resolved path, and an **Open Diagram Images**
command that opens the folder — the dashboard cannot navigate to a `file://` path itself, so the
AppHost opens it for you.

`ImageExportDirectory` is resolved from the **AppHost directory**, not from `OutputDirectory`, which is
what lets both diagrams land in the same place. Setting it on only one of the two splits them apart.

```csharp
builder.AddAspireC4(options => options.WithoutImageExport()); // opt out
builder.AddAspireC4(options => options
.WithImageExport(LikeC4ImageFormat.Png, LikeC4ImageFormat.Jpg)
.WithImageExportDirectory("docs/diagrams") // relative to the AppHost directory
);
```

**There is no SVG option for the architecture diagram.** `likec4 export` renders by screenshotting each
view in a headless browser and offers only `png` and `jpg`. The ER diagram *does* export SVG, because it
renders through d2 instead.

That headless browser has two consequences. Export takes tens of seconds and needs a Chromium: container
mode (the default) gets one from the `ghcr.io/likec4/likec4` image, which already carries it, while
`WithLocalCLI()` mode needs a Playwright Chromium installed on the host. And it runs in the background,
so startup is never delayed. A failure is reported and leaves the generated `.c4` file untouched.

#### When export actually runs

Nothing is rendered — and **no container is started** — unless the output would differ:

- **Unchanged model, same session.** The resource state churn that regenerates an identical model
exports nothing.
- **Restart.** A stamp file beside the images records what they were rendered from, so restarting the
AppHost over an unchanged model runs nothing. Without it, every restart would re-render, because the
in-memory change detection starts empty each time.
- **Changed formats, or deleted images.** Both re-export: the stamp covers the requested formats, and
is only trusted when the files it describes are still there.
- **Publish.** `aspire publish` generates the model and manifest and exports nothing at all. An export
is fire-and-forget, so on publish it would be killed part-way through — and publish is expected to be
hermetic, which reaching for a container runtime a build agent may not have would break.

#### Committing the images

The images are the one piece of generated output worth tracking: a diagram that shows up in a pull
request is documentation, and because export only runs when the diagram changes they do not churn.
Ignore the generated directory but carve the images out of it:

```gitignore
# Note the trailing /* rather than /: git will not descend into an excluded directory, so the
# children have to be excluded individually for the re-include to be reachable.
**/.aspirec4/*
!**/.aspirec4/images/
# The stamp recording what the images were rendered from is a local cache, not documentation.
**/.aspirec4/images/.aspirec4-*
```

The two diagrams differ in how well they cache, though both are stable in source control:

- **ER diagram** — fully cached. Derived from your EF model alone, so restarting the AppHost over an
unchanged schema renders nothing at all. This is the one that matters most, since it is also the one
that can pull a browser image under `WithViewerFidelityExport()`.
- **Architecture diagram** — re-rendered on each run, but to identical bytes. Its model is a picture of
a *running* system: the endpoint ports and the run-state tags settle during startup, so the model the
first export sees is not quite the one the last export sees. The stamp already ignores the ephemeral
ports; the remaining difference is the run states, and those genuinely change the picture, so they
are not normalised away. Measured across restarts the exported PNGs are byte-for-byte the same, so
git sees no change — the cost is a background render, not a dirty tree.

Set `ContainerRuntimeCommand` to `podman` where that is the runtime Aspire itself is using.

## Upgrading from before 13.6

13.6 changed two things, both breaking:
Expand Down Expand Up @@ -252,6 +342,15 @@ aspirec4 # parent row, added only when there is more than one di
| `ViewerServerImageTag` | `null` (`1.29-alpine`) | Pin the `nginx` image tag used to serve the viewer |
| `HideFromDashboard` | `false` | Hide the d2 sidecar from the Aspire dashboard |
| `DashboardLinkDisplayName` | `"ER Diagram"` | Name used for the diagram link |
| `ExportImages` | `true` | Write the diagram out as an image whenever it changes — see [Exporting the ER diagram as an image](#exporting-the-er-diagram-as-an-image) |
| `ImageFormats` | `{Svg, Png}` | Formats to export. `WithImageExport(...)` |
| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | Where images are written; relative paths resolve against the AppHost directory. Shared with the architecture diagram |
| `D2Command` | `null` | A local `d2` binary to export with; `null` runs the container. Set by `WithLocalD2CLI()` |
| `ContainerRuntimeCommand` | `"docker"` | Runtime for the one-shot export container; `podman` where that is what Aspire uses |
| `ExportTimeoutSeconds` | `120` | How long to wait for one d2 invocation before abandoning it |
| `UseViewerFidelityExport` | `false` | Render images through the viewer in a headless browser so they match its own export. Pulls a ~3.7 GB browser image; `Interactive` only |
| `ViewerExportImage` | `null` | Override the browser image, including its tag |
| `ViewerExportTimeoutSeconds` | `600` | How long to wait for a viewer-fidelity export, which may be pulling the image |

### Renderers

Expand Down Expand Up @@ -473,6 +572,61 @@ d2 ships as a Go binary. Unlike the LikeC4 sidecar, there is **no npm CLI fallba
`install.sh`, or `go install`) so it is on `PATH`, or pass an explicit path:
`WithLocalD2CLI("/opt/d2/bin/d2")`.

### Exporting the ER diagram as an image

On by default. `schema.svg` and `schema.png` are written to `./.aspirec4/images/` — the same folder the
architecture diagram exports to — whenever the diagram changes. The name drops the `.gen` marker, which
earns its place on a generated source file you hand-edit beside but not on an image.

```csharp
builder.AddAspireC4()
.WithEntityFrameworkDiagram(configure: options => options.WithoutImageExport());

builder.AddAspireC4()
.WithEntityFrameworkDiagram(configure: options => options.WithImageExport(ErdImageFormat.Svg));
```

**Export always renders through d2, whatever `Renderer` is set to.** The interactive renderer is a
browser application with no headless path, so an image of it could only be produced by driving a
browser; d2 is the only format that both renders images itself and keeps column-level edges, so routing
every renderer through it gives one toolchain and one appearance. Two things follow:

- Export needs either the `d2lang/d2` container or a local `d2` binary. `WithLocalD2CLI()` sets
`D2Command` for you; set it directly to render locally while leaving the sidecar or viewer alone.
Where neither is available, call `WithoutImageExport()`.
- `schema.gen.d2` is written alongside the diagram even for the other renderers, purely to be rendered.
It is byte-identical to what the `D2` renderer writes.

Export runs in the background, so startup is never delayed, and only when it would change something — a
stamp beside the images means a restart over an unchanged model runs nothing at all, not even a
container. It is skipped entirely during `aspire publish`. See
[When export actually runs](#when-export-actually-runs). Failures are logged to the diagram resource
and leave the diagram itself untouched.

Prefer SVG for a large schema — a raster of the whole thing is unreadable at any sensible size. The
viewer also has **Save as SVG / PNG** buttons for exporting what is currently on screen.

#### Matching the viewer exactly

The d2 render is a *different diagram*, not a differently-styled one: d2 draws `sql_table` shapes with
its own theme and layout, while the viewer draws React Flow cards with context colours, key badges,
complex-type groups and crow's-foot markers. If the exported file must be the one the viewer's own
**Save as SVG / PNG** control produces, opt into the viewer render:

```csharp
builder.AddAspireC4()
.WithEntityFrameworkDiagram(configure: options => options.WithViewerFidelityExport());
```

That loads the generated viewer in a headless browser and calls the very function the toolbar button
calls, so the file is identical. It is **off by default** because the viewer only runs in a browser:
turning it on pulls `mcr.microsoft.com/playwright` (around 3.7 GB) and makes an export take seconds
rather than milliseconds. Point `ViewerExportImage` at a mirror or an image you have already cached if
the default is inconvenient.

It applies only to the `Interactive` renderer — the one that has a viewer. Any other renderer exports
through d2 regardless, and says so in the log rather than failing.

### Overriding the output directory

Prefer the `configure` callback over configuration for `OutputDirectory`. The sidecar's bind mount is
Expand Down Expand Up @@ -806,3 +960,5 @@ should review the following changes when upgrading:

- [Homepage](https://purview.dev/projects/aspirec4/)
- [Documentation](https://purview.dev/docs/aspirec4/)


2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "aspirec4",
"version": "13.6.0-preview.2",
"version": "13.6.0-preview.3",
"license": "MIT",
"description": "Aspire LikeC4 Visualization - version manifest for CD pipeline",
"author": {
Expand Down
Loading
Loading