diff --git a/.github/skills/erd-viewer/SKILL.md b/.github/skills/erd-viewer/SKILL.md new file mode 100644 index 0000000..6488790 --- /dev/null +++ b/.github/skills/erd-viewer/SKILL.md @@ -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 ` renders an emitted Mermaid `.mmd` to SVG through a one-shot container. diff --git a/.gitignore b/.gitignore index 2efc2cc..67df78d 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ \ No newline at end of file +# +# 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-* \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index c549ddd..1e1ad44 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 # 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 @@ -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//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 ``` diff --git a/README.md b/README.md index 73ad0c3..6ea74f8 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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: @@ -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 @@ -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 @@ -806,3 +960,5 @@ should review the following changes when upgrading: - [Homepage](https://purview.dev/projects/aspirec4/) - [Documentation](https://purview.dev/docs/aspirec4/) + + diff --git a/package.json b/package.json index 1895230..04b4929 100644 --- a/package.json +++ b/package.json @@ -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": { diff --git a/scripts/erd-viewer-check.mts b/scripts/erd-viewer-check.mts index 39c5ac3..f2c899e 100644 --- a/scripts/erd-viewer-check.mts +++ b/scripts/erd-viewer-check.mts @@ -238,9 +238,13 @@ try { : `${tightest.id} has ${tightest.pad}px`, ); + // The gap between stacked tables is where the relationship labels sit, so it has to clear a + // label rather than merely separate two borders. Tables no relationship connects are laid + // out as separate components and packed, a seam that needs its own spacing: at ELK's default + // of 20 those groups all but touch. check( "stacked tables stay visually separate", - spacing.closest.gap >= 40, + spacing.closest.gap >= 100, `${spacing.closest.pair} — ${spacing.closest.gap}px`, ); @@ -284,6 +288,10 @@ try { // A table's offset within its context box, which is what a remembered arrangement has to // preserve — and what a reload must reproduce. + // + // Divided back out by the viewport scale, so the result is in layout pixels: the view is + // zoomed to fit, so a screen-pixel offset shrinks as the schema grows and any threshold + // against it would hold only for diagrams small enough to render at 1:1. const offsetInContext = (target: any, id: string) => target.evaluate((wanted: string) => { const node = document.querySelector(`.react-flow__node-entity[data-id="${wanted}"]`); @@ -303,13 +311,48 @@ try { if (!context) return null; + const viewport = document.querySelector(".react-flow__viewport")!; + const scale = viewport.getBoundingClientRect().width / viewport.offsetWidth; const box = (context as HTMLElement).getBoundingClientRect(); - return { x: Math.round(n.left - box.left), y: Math.round(n.top - box.top) }; + return { + x: Math.round((n.left - box.left) / scale), + y: Math.round((n.top - box.top) / scale), + }; }, id); - const card = page.locator(".react-flow__node-entity").first(); - const draggedId = (await card.getAttribute("data-id"))!; + // Deliberately not the topmost table in its container: fitContexts pins a container's top to + // whichever table is highest, so dragging that one carries the whole container with it and + // its offset never changes — which would leave the reload check below passing whether or not + // anything was actually remembered. + const draggedId = (await page.evaluate(() => { + const cards = [...document.querySelectorAll(".react-flow__node-entity")].map((n) => ({ + id: n.dataset.id ?? "?", + box: n.getBoundingClientRect(), + })); + + for (const container of document.querySelectorAll(".react-flow__node-context")) { + const rect = container.getBoundingClientRect(); + const own = cards.filter( + (n) => + n.box.left >= rect.left && + n.box.right <= rect.right && + n.box.top >= rect.top && + n.box.bottom <= rect.bottom, + ); + + if (own.length < 2) continue; + + return own.reduce((lowest, n) => (n.box.top > lowest.box.top ? n : lowest)).id; + } + + return null; + }))!; + + check("a container holds more than one table to drag", draggedId !== null, draggedId ?? "none found"); + + const card = page.locator(`.react-flow__node-entity[data-id="${draggedId}"]`); + const origin = await offsetInContext(page, draggedId); const start = (await card.boundingBox())!; await page.mouse.move(start.x + 40, start.y + 12); @@ -320,7 +363,11 @@ try { const before = await offsetInContext(page, draggedId); - check("a table can be dragged", (before?.y ?? 0) > 40, `offset ${before?.y ?? "?"}px in its context`); + check( + "a table can be dragged", + origin !== null && before !== null && before.y - origin.y > 40, + `offset ${origin?.y ?? "?"}px → ${before?.y ?? "?"}px in its context`, + ); check( "the context box follows the table it holds", @@ -371,6 +418,168 @@ try { check("columns mode restores the columns", (await page.locator(".entity .col").count()) > 0); + // ── Complex value objects ───────────────────────────────────────────────────────── + // + // EF flattens a complex value object into one column per member, named {Property}_{Member}, + // so a card otherwise shows a run of prefixed rows that says nothing about what they are. + // They are folded under the property that owns them, which only means anything if the fold + // opens, closes, survives a reload, and does not disturb the layout around it. + + const groups = await page.locator(".entity .col.group").count(); + + if (groups === 0) { + check("the model flattens a complex value object", false, "no group rows — nothing to check"); + } else { + const group = page.locator(".entity .col.group").first(); + const groupCard = page.locator(".react-flow__node-entity", { has: page.locator(".col.group") }).first(); + const groupCardId = (await groupCard.getAttribute("data-id"))!; + + check("complex value objects are folded under their property", groups > 0, `${groups} group rows`); + + check( + "a folded group starts closed", + (await page.locator(".entity .col.member").count()) === 0 && + (await page.locator(".entity .col.group.open").count()) === 0, + ); + + // The count is what a closed group says about what it is holding: without it the row + // claims a value object and gives no reason to open it. + const closedLabel = await group.locator(".type").innerText(); + + check("a closed group reports how many members it holds", /\(\d+\)$/.test(closedLabel), closedLabel); + + const widthBefore = (await groupCard.boundingBox())!.width; + const heightBefore = (await groupCard.boundingBox())!.height; + + await group.locator(".chevron").click(); + await page.waitForTimeout(350); + + const members = await page.locator(".entity .col.member").count(); + + check("the chevron opens one group", members > 0, `${members} member rows`); + + const openLabel = await group.locator(".type").innerText(); + + check( + "an open group drops the count", + !/\(\d+\)$/.test(openLabel) && openLabel.length > 0, + openLabel, + ); + + // A member of an open group is shown as its database type alone: the group row above it + // already names the value object, and repeating it on every member crowds out the one + // thing those rows exist to say. + const repeated = await page + .locator(".entity .col.member .type") + .evaluateAll((els, name) => els.map((e) => e.textContent ?? "").filter((t) => t.includes(name)), openLabel); + + check( + "a member does not repeat its group's value object", + repeated.length === 0, + repeated.slice(0, 2).join(", ") || `members read as plain types beside ${openLabel}`, + ); + + // Members are indented so the card still reads as a list of the table's own columns. + const indented = await page.evaluate(() => { + const member = document.querySelector(".entity .col.member .col-name"); + const column = document.querySelector(".entity .col:not(.member):not(.group) .col-name"); + if (!member || !column) return null; + + return Math.round(member.getBoundingClientRect().left - column.getBoundingClientRect().left); + }); + + check("members are indented beneath their property", (indented ?? 0) > 0, `${indented ?? "?"}px`); + + const opened = (await groupCard.boundingBox())!; + + // The card is measured as though every group were open, so opening one only ever changes + // its height. A width that moved would mean the arrangement around it has to shift too. + check( + "opening a group does not re-widen the card", + Math.abs(opened.width - widthBefore) < 2, + `${Math.round(widthBefore)}px → ${Math.round(opened.width)}px`, + ); + + check( + "opening a group makes room for the members", + opened.height > heightBefore + 2, + `${Math.round(heightBefore)}px → ${Math.round(opened.height)}px`, + ); + + // The open set rides with the saved arrangement, so a reload reopens what the reader left + // open rather than folding the card back up under them. + await page.reload({ waitUntil: "networkidle" }); + await page.waitForSelector(".entity", { timeout: 20000 }); + + check( + "an opened group survives a reload", + (await page.locator(".entity .col.member").count()) > 0, + `${await page.locator(".entity .col.member").count()} member rows`, + ); + + // ── Expand all / Collapse all ───────────────────────────────────────────────── + + const COMPLEX = '[aria-label="Complex value objects"]'; + + await chooseIn(page, COMPLEX, "Collapse all"); + await page.waitForTimeout(350); + + check( + "Collapse all folds every group", + (await page.locator(".entity .col.member").count()) === 0, + "no member rows", + ); + + await chooseIn(page, COMPLEX, "Expand all"); + await page.waitForTimeout(350); + + const allOpen = await page.locator(".entity .col.group.open").count(); + + check("Expand all opens every group", allOpen === groups, `${allOpen} of ${groups} open`); + + await chooseIn(page, COMPLEX, "Collapse all"); + await page.waitForTimeout(350); + + // ── Search reaches a folded member ──────────────────────────────────────────── + // + // A hit inside a closed group would otherwise be counted and then not shown. The groups + // opened this way are held apart from the reader's own, so clearing the search folds + // them back rather than leaving the card as the search left it. + + const memberColumn = await page.evaluate((id) => { + const card = document.querySelector(`.react-flow__node-entity[data-id="${id}"]`); + const name = card?.querySelector(".col.group .col-name")?.textContent ?? ""; + + return name ? `${name}_` : ""; + }, groupCardId); + + if (memberColumn) { + // Searching the flattened column's own prefix can only be satisfied by a folded member. + await page.fill(".toolbar input", memberColumn); + await page.waitForTimeout(400); + + check( + "a search match inside a folded group opens it", + (await page.locator(".entity .col.member").count()) > 0, + `searching "${memberColumn}"`, + ); + + check( + "the revealed member is marked as the hit", + (await page.locator(".entity .col.member.hit").count()) > 0, + ); + + await page.locator(".toolbar input").press("Escape"); + await page.waitForTimeout(400); + + check( + "clearing the search folds it back", + (await page.locator(".entity .col.member").count()) === 0, + "back to closed", + ); + } + } + // ── Search ──────────────────────────────────────────────────────────────────────── // // Search is the only way into a schema too large to read at a glance, so it is checked as diff --git a/skills/purview-aspirec4-configuration/SKILL.md b/skills/purview-aspirec4-configuration/SKILL.md index 50e2a8a..3b7a485 100644 --- a/skills/purview-aspirec4-configuration/SKILL.md +++ b/skills/purview-aspirec4-configuration/SKILL.md @@ -3,8 +3,8 @@ name: purview-aspirec4-configuration description: >- Use when tuning AspireC4DiagramOptions - the view and title settings, output directory and generated file, the LikeC4 container tag and HMR, icon inference, Aspire metadata injection and - dashboard links, run-state tags and styles, additional DSL files and image aliases, and the - security note on embedding the Aspire token. + dashboard links, run-state tags and styles, additional DSL files and image aliases, exporting the + views as images on startup, and the security note on embedding the Aspire token. metadata: product: AspireC4 repository: purview-dev/aspirec4 @@ -124,6 +124,99 @@ puts passwords and secrets. | `ImageAliases` | `{}` | alias definitions (keys begin with `@`) written to `imageAliases` in the generated config | | `ConfigFileMetadata` | `{}` | extra metadata for the generated `likec4.config.json` | +## Image export + +Every view is written out as an image whenever the generated model changes — on by default. + +| Property | Default | Description | +| --- | --- | --- | +| `ExportImages` | `true` | write each view out as an image when the generated model changes | +| `ImageFormats` | `{Png}` | `Png` and/or `Jpg`. **There is no SVG** — see below | +| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | where images are written; relative paths resolve against the **AppHost directory** | +| `ImageExportTimeoutSeconds` | `300` | cap on one `likec4 export` invocation | +| `ContainerRuntimeCommand` | `"docker"` | the runtime for the one-shot export container; set to `podman` where that is what Aspire uses | + +**Both diagrams export into the same folder**, `./.aspirec4/images/`, so there is one place to look +rather than one per diagram: + +```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 a file +after its view id and a bare `index.png` says nothing in a shared folder. The ER diagram row in the +dashboard carries an **Images** property with the resolved path and an **Open Diagram Images** command +that opens the folder. + +Because the default is resolved from the AppHost directory rather than from `OutputDirectory`, setting +`ImageExportDirectory` on only one of the two diagrams splits them apart again. + +**`likec4 export` has no SVG format.** It renders by screenshotting each view in a headless browser, and +offers only `png` and `jpg`. For a vector, export the model and render it with another tool. The ER +diagram *does* export SVG, because it renders through d2 — see `purview-aspirec4-entityframework`. + +Two consequences follow from the headless browser: + +- 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; **`WithLocalCLI()` mode needs a Playwright + Chromium installed on the host.** +- It runs in the background, so startup is never delayed. + +Nothing is rendered, and **no container is started**, unless the output would differ: + +| Situation | Exports? | +| --- | --- | +| Identical model regenerated by state churn | no | +| AppHost restarted over an unchanged model | no — a stamp file beside the images records what they were rendered from | +| Model changed, or a format added | yes | +| Images deleted | yes — the stamp is only trusted when the files it describes still exist | +| `aspire publish` | **never** | + +Publish is skipped outright: an export is fire-and-forget, so it would be killed part-way through when +publish exits, and publish is expected to be hermetic rather than reaching for a container runtime a +build agent may not have. + +### 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 they do not churn because export only runs when the diagram changes. +Ignore the generated directory but carve them out of it: + +```gitignore +# /* 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-* +``` + +Both diagrams are stable in source control, but they cache differently: + +- **ER diagram** — fully cached. From the EF model alone, so a restart over an unchanged schema renders + nothing. +- **Architecture diagram** — re-rendered on each run, to identical bytes. Its model is a picture of a + *running* system: ports and run-state tags settle during startup, so the first export sees a slightly + different model from the last. The stamp ignores the ephemeral ports; the run states are left in + because they genuinely change the picture. Measured across restarts the PNGs are byte-for-byte the + same, so git sees nothing — the cost is a background render, not a dirty tree. + +Failures are best-effort: they are reported and the generated `.c4` model is unaffected. + +```csharp +builder.AddAspireC4(options => options.WithoutImageExport()); +builder.AddAspireC4(options => options + .WithImageExport(LikeC4ImageFormat.Png, LikeC4ImageFormat.Jpg) + .WithImageExportDirectory("docs/diagrams") // relative to the AppHost directory +); +``` + +`WithImageExport()` with no format turns export off, the same as `WithoutImageExport()`. + ## The fluent surface ```csharp @@ -149,6 +242,8 @@ WithImageAliasFolder(string, string) WithExcludedResourceType() WithoutExcludedResourceType() WithIncludeAspireC4InternalResource(bool) WithLegacyLayout() WithLikeC4ProjectFolder(string) +WithImageExport(params LikeC4ImageFormat[]) +WithImageExportDirectory(string) WithoutImageExport() ``` ## Related skills diff --git a/skills/purview-aspirec4-entityframework/SKILL.md b/skills/purview-aspirec4-entityframework/SKILL.md index dd0dd92..e241cfa 100644 --- a/skills/purview-aspirec4-entityframework/SKILL.md +++ b/skills/purview-aspirec4-entityframework/SKILL.md @@ -5,7 +5,7 @@ description: >- installing AspireC4.Hosting.EntityFrameworkCore, calling WithEntityFrameworkDiagram, how the model is discovered (assembly metadata, an analyzer descriptor, or the opt-in build-time dump), filtering and excluding DbContexts, domain types (value objects and enums) and the DomainTypeDisplay option, the - renderers, and the dashboard integration. + renderers, exporting the diagram as SVG and PNG on startup, and the dashboard integration. metadata: product: AspireC4 repository: purview-dev/aspirec4 @@ -143,6 +143,15 @@ Options bind from the **`AspireC4:EntityFramework`** section, applied on top of | `ViewerServerImageTag` | `null` | pin the viewer `nginx` image tag | | `HideFromDashboard` | `false` | hide the sidecar and surface it as a link | | `DashboardLinkDisplayName` | `"ER Diagram"` | the link name when hidden | +| `ExportImages` | `true` | write the diagram out as an image when it changes | +| `ImageFormats` | `{Svg, Png}` | `Svg` and/or `Png` | +| `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 | +| `ContainerRuntimeCommand` | `"docker"` | the runtime for the one-shot export container; `podman` where that is what Aspire uses | +| `ExportTimeoutSeconds` | `120` | cap on one d2 invocation | +| `UseViewerFidelityExport` | `false` | render through the viewer in a headless browser so images match its own export. Pulls a ~3.7 GB image; `Interactive` only | +| `ViewerExportImage` | `null` | override the browser image, including its tag | +| `ViewerExportTimeoutSeconds` | `600` | cap on one viewer-fidelity export | The output path follows the architecture diagram: `WithLegacyLayout()` on `AddAspireC4` restores `./erd/gen/` as well, because there is no separate ER switch. An `OutputDirectory` set on @@ -167,6 +176,82 @@ builder.AddAspireC4().WithEntityFrameworkDiagram().WithLocalD2CLI(); d2 ships as a Go binary, so it must be on `PATH`; there is no npm fallback. Call `WithLocalD2CLI()` **after** `WithEntityFrameworkDiagram()`. +## Image export + +On by default, so a schema can go into a pull request or a wiki without opening the viewer. Images are +written to **`./.aspirec4/images/`** — the same folder the architecture diagram exports to, so there is +one place to look: + +```text +apphost/.aspirec4/images/ + schema.svg <- this diagram + schema.png + architecture-index.png <- architecture diagram +``` + +The name drops the `.gen` marker: `schema.gen` produces `schema.svg`, not `schema.gen.svg`. The marker +earns its place on a generated source file sitting in a directory you also hand-edit, which an image in +the shared folder never is. The dashboard row carries an **Images** property with the resolved path and +an **Open Diagram Images** command that opens the folder. + +```csharp +builder.AddAspireC4().WithEntityFrameworkDiagram(configure: options => options.WithoutImageExport()); +builder.AddAspireC4().WithEntityFrameworkDiagram(configure: options => + options.WithImageExport(ErdImageFormat.Svg) +); +``` + +`WithImageExport()` with no format turns export off, the same as `WithoutImageExport()`. + +**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. Two +things follow: + +- Export needs either the `d2lang/d2` container or a local `d2` binary (`D2Command`, which + `WithLocalD2CLI()` sets for you). Where neither is available, call `WithoutImageExport()`. +- `{FileName}.d2` is written alongside the diagram even for the other renderers, purely to be + rendered. It is identical to what the `D2` renderer writes. + +Export runs in the background, so startup is never delayed, and nothing is rendered — **no container is +started** — unless the output would differ: + +| Situation | Exports? | +| --- | --- | +| Identical model regenerated | no | +| AppHost restarted over an unchanged model | no — a stamp file beside the images records what they were rendered from | +| Model changed, or a format added | yes | +| Images deleted | yes — the stamp is only trusted when the files it describes still exist | +| `aspire publish` | **never** | + +Publish is skipped outright: an export is fire-and-forget, so it would be killed part-way through when +publish exits, and publish is expected to be hermetic rather than reaching for a container runtime a +build agent may not have. + +Failures are best-effort: they are logged to the diagram resource and the diagram itself is unaffected. + +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, the viewer draws React Flow cards with context colours, key badges, +complex-type groups and crow's-foot markers. To get the file the viewer's own export produces: + +```csharp +builder.AddAspireC4() + .WithEntityFrameworkDiagram(configure: options => options.WithViewerFidelityExport()); +``` + +This loads the generated viewer in a headless browser and calls the same function the toolbar button +calls, so the output is identical. **Off by default**: it pulls `mcr.microsoft.com/playwright` (around +3.7 GB) and an export takes seconds rather than milliseconds. `ViewerExportImage` overrides the image +for a mirror or a cached one. + +Applies only to `Interactive`, the renderer that has a viewer. Any other renderer exports through d2 +regardless and logs why. + ## Using the viewer The interactive viewer is for reading a schema, not just looking at one. @@ -191,3 +276,4 @@ The interactive viewer is for reading a schema, not just looking at one. `purview-aspirec4-quickstart` for installing AspireC4 and running the architecture diagram, `purview-aspirec4-configuration` for the LikeC4 options reference, and `purview-aspirec4-resources` for per-resource labels, relationships and grouping. + diff --git a/src/src/AspireC4/AspireC4DiagramOptions.cs b/src/src/AspireC4/AspireC4DiagramOptions.cs index b4320f5..2cdc4be 100644 --- a/src/src/AspireC4/AspireC4DiagramOptions.cs +++ b/src/src/AspireC4/AspireC4DiagramOptions.cs @@ -1,5 +1,6 @@ using Aspire.Hosting.AspireC4.LikeC4.Icons; using Aspire.Hosting.AspireC4.LikeC4.Models; +using Aspire.Hosting.AspireC4.LikeC4.Runtime; namespace Aspire.Hosting.AspireC4; @@ -179,6 +180,79 @@ public sealed class AspireC4DiagramOptions /// public bool CheckLatestImageVersion { get; set; } = true; + /// + /// When (default), every LikeC4 view is written out as an image each time the + /// generated model changes. + /// + /// + /// + /// The images land in , one file per view named after the view's + /// id, so a diagram can be attached to a pull request or pasted into a wiki without running the + /// server. Export runs in the background, so it never delays startup, and only when it would + /// actually change something: the resource state churn that regenerates an identical model exports + /// nothing, and a stamp beside the images means a restart runs nothing either — not even a + /// container. It is also skipped entirely during a publish, which generates its output and exits. + /// + /// + /// likec4 export screenshots each view in a headless browser, so this takes tens of seconds + /// and needs a Chromium. The default container mode gets one from the + /// ghcr.io/likec4/likec4 image, which already carries it; + /// mode needs a Playwright Chromium installed + /// on the host instead. Set to , or use + /// , to opt out. + /// + /// + public bool ExportImages { get; set; } = true; + + /// + /// The formats written when is set. Defaults to + /// . + /// + /// + /// There is no SVG option: likec4 export offers only png and jpg, because it + /// renders by screenshotting the view rather than emitting vector output. Emptying this disables + /// export as surely as clearing . Populate with + /// . + /// + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Usage", + "CA2227:Collection properties should be read only", + Justification = "Settable for configuration binding and direct assignment in user code" + )] + public HashSet ImageFormats { get; set; } = [LikeC4ImageFormat.Png]; + + /// + /// Where exported images are written. Relative paths are resolved against the AppHost directory; + /// (the default) uses ./.aspirec4/images/. + /// + /// + /// The ER diagram writes to the same folder by default, so every image AspireC4 produces is in one + /// place rather than buried in whichever generated-output directory produced it. The architecture + /// diagram's files are prefixed architecture- to keep the two apart. Setting this on only one + /// of the two diagrams splits them again, which is why the default is resolved from the AppHost + /// directory rather than from . + /// + public string? ImageExportDirectory { get; set; } + + /// + /// Maximum number of seconds to wait for one likec4 export invocation. Defaults to 300. + /// + /// + /// Much larger than , which caps the formatter: export + /// starts a LikeC4 server and a browser before it renders anything, so a cold run takes far longer + /// than a format pass. Export runs in the background, so this never caps startup. + /// + public int ImageExportTimeoutSeconds { get; set; } = 300; + + /// + /// The container runtime used to run the one-shot export container. Defaults to docker. + /// + /// + /// Set to podman where that is the runtime Aspire itself is using. Ignored in local CLI mode, + /// which runs no container. + /// + public string ContainerRuntimeCommand { get; set; } = "docker"; + /// /// Enables automatic icon inference for known resource types and technologies. /// Defaults to . diff --git a/src/src/AspireC4/AspireC4ImageExport.cs b/src/src/AspireC4/AspireC4ImageExport.cs new file mode 100644 index 0000000..ec55027 --- /dev/null +++ b/src/src/AspireC4/AspireC4ImageExport.cs @@ -0,0 +1,54 @@ +namespace Aspire.Hosting.AspireC4; + +/// +/// The single directory both diagrams export their images to, and how it is resolved. +/// +/// +/// +/// One folder for the whole integration rather than one per diagram: the images exist to be picked up +/// and attached to something, which is a poor fit for hunting through two generated-output directories +/// — and worse for the ER diagram, whose images would otherwise sit among the viewer's own +/// index.html, app.js and vendor/. +/// +/// +/// Resolved against the AppHost directory rather than either diagram's OutputDirectory, so the +/// two cannot drift apart when only one of them is overridden. Shared with the EF Core package through +/// InternalsVisibleTo. +/// +/// +static class AspireC4ImageExport +{ + /// Where images are written when neither diagram configures a directory. + /// + /// Beneath the same .aspirec4/ root as everything else AspireC4 generates, so a consumer + /// still has exactly one directory to ignore in source control. + /// + internal const string DefaultDirectory = "./.aspirec4/images/"; + + /// + /// Prefix applied to the architecture diagram's images. + /// + /// + /// likec4 export names a file after its view id, which in a folder shared with the ER + /// diagram's images says nothing about where it came from — and an index view would produce a + /// bare index.png. The prefix also keeps the two diagrams from colliding on a common view name. + /// + internal const string ArchitecturePrefix = "architecture-"; + + /// Resolves the configured image directory to an absolute path. + /// + /// The configured directory, or /blank for . + /// A relative path is resolved against . + /// + /// The AppHost directory. + internal static string Resolve(string? configured, string baseDirectory) + { + ArgumentException.ThrowIfNullOrWhiteSpace(baseDirectory); + + var directory = string.IsNullOrWhiteSpace(configured) ? DefaultDirectory : configured; + + return Path.TrimEndingDirectorySeparator( + Path.GetFullPath(Path.IsPathRooted(directory) ? directory : Path.Combine(baseDirectory, directory)) + ); + } +} diff --git a/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs b/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs index fa51c96..dc4ecfd 100644 --- a/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs +++ b/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs @@ -2,6 +2,7 @@ using System.Diagnostics.CodeAnalysis; using Aspire.Hosting.AspireC4.LikeC4.Icons; using Aspire.Hosting.AspireC4.LikeC4.Models; +using Aspire.Hosting.AspireC4.LikeC4.Runtime; namespace Aspire.Hosting; @@ -554,4 +555,68 @@ bool include return options; } + + /// + /// Restricts image export to the listed formats, replacing the PNG default. + /// + /// + /// Also sets , so naming a format is enough to turn + /// export on. Passing no format turns it off, the same as . + /// + /// + /// The formats to export. + /// The same for further configuration. + /// + [AspireExport] + public static AspireC4DiagramOptions WithImageExport( + [NotNull] this AspireC4DiagramOptions options, + params LikeC4ImageFormat[] formats + ) + { + ArgumentNullException.ThrowIfNull(formats); + + options.ImageFormats = [.. formats]; + options.ExportImages = formats.Length > 0; + + return options; + } + + /// Sets the directory exported images are written to. + /// + /// + /// Absolute, or relative to . + /// + /// The same for further configuration. + /// + [AspireExport] + public static AspireC4DiagramOptions WithImageExportDirectory( + [NotNull] this AspireC4DiagramOptions options, + string directory + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(directory); + + options.ImageExportDirectory = directory; + + return options; + } + + /// + /// Stops the views being exported as images, leaving only the generated .c4 model. + /// + /// + /// Export drives a headless browser; see for what + /// that needs. This is how a consumer who cannot, or would rather not, pay for it opts out. + /// + /// + /// The same for further configuration. + [AspireExport] + public static AspireC4DiagramOptions WithoutImageExport([NotNull] this AspireC4DiagramOptions options) + { + ArgumentNullException.ThrowIfNull(options); + + options.ExportImages = false; + + return options; + } } diff --git a/src/src/AspireC4/ImageExportStamp.cs b/src/src/AspireC4/ImageExportStamp.cs new file mode 100644 index 0000000..d3d718e --- /dev/null +++ b/src/src/AspireC4/ImageExportStamp.cs @@ -0,0 +1,119 @@ +using System.Security.Cryptography; +using System.Text; +using System.Text.RegularExpressions; + +namespace Aspire.Hosting.AspireC4; + +/// +/// Records what the images in a directory were rendered from, so an export that would reproduce them +/// byte for byte can be skipped before anything is run. +/// +/// +/// +/// The in-memory "has the diagram changed" check cannot answer this on its own: it starts empty every +/// time the AppHost does, so the first write of each run always looks like a change and would re-export +/// images that are already correct on disk. For the viewer-fidelity path that means pulling and +/// starting a multi-gigabyte browser container to produce files identical to the ones already sitting +/// there. +/// +/// +/// Modelled on the viewer's own .aspirec4-vendor stamp. Named per diagram because both diagrams +/// now export into the same directory, so a single file would have them overwriting each other's. +/// +/// +static partial class ImageExportStamp +{ + /// The stamp file for a diagram, named so it sorts away from the images themselves. + internal static string FileName(string diagram) => $".aspirec4-{diagram}-images"; + + /// + /// Hashes everything that decides what the images look like. + /// + /// The rendered source — the model or DSL the images are produced from. + /// + /// Every other input that changes the output: the formats, the file name, the renderer, and whether + /// the viewer or d2 is doing the rendering. A change to any of them has to re-export. + /// + internal static string Compute(string content, params string[] parts) + { + ArgumentNullException.ThrowIfNull(content); + ArgumentNullException.ThrowIfNull(parts); + + var payload = string.Join("\u0000", [Normalise(content), .. parts]); + + return Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(payload))); + } + + /// + /// Removes the parts of a generated model that differ between runs without changing the picture. + /// + /// + /// The architecture model embeds the endpoint URLs Aspire allocated, and those ports are different + /// on every run. Hashing them verbatim would invalidate the stamp every single time, which for this + /// diagram means starting a LikeC4 server and a headless browser to redraw something that has not + /// changed. The port is replaced rather than the whole URL so that a host or a scheme actually + /// changing is still noticed. + /// + /// This does not make the architecture diagram fully cached across restarts, and is not meant to: + /// the run-state tags also settle during startup, and those genuinely change the picture, so + /// normalising them away would hide a real difference. The exported images come out byte-identical + /// either way; what is left is a background render, not changed output. + /// + /// + internal static string Normalise(string content) => EphemeralPort().Replace(content, ":"); + + [GeneratedRegex(@"(?<=://[^/\s""']+):\d{2,5}\b")] + private static partial Regex EphemeralPort(); + + /// + /// Whether already holds exactly these images. + /// + /// + /// Both halves matter. A matching stamp alone would skip the export after someone deleted the + /// images; the files existing alone would keep a stale image after the model changed. + /// + /// The images directory. + /// Which diagram's stamp to read. + /// The stamp the current inputs produce. + /// The files the export would write. + /// Cancelled on shutdown. + internal static async Task IsCurrentAsync( + string directory, + string diagram, + string stamp, + IEnumerable expected, + CancellationToken cancellationToken + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(directory); + ArgumentNullException.ThrowIfNull(expected); + + if (!expected.All(File.Exists)) + { + return false; + } + + var path = Path.Combine(directory, FileName(diagram)); + + if (!File.Exists(path)) + { + return false; + } + + var existing = await File.ReadAllTextAsync(path, cancellationToken).ConfigureAwait(false); + + return string.Equals(existing.Trim(), stamp, StringComparison.Ordinal); + } + + /// Records the stamp, once the images it describes have actually been written. + /// + /// Written last for the same reason the vendor stamp is: a run interrupted part-way through leaves + /// no stamp, so the next one re-exports rather than trusting a half-written directory. + /// + internal static Task WriteAsync( + string directory, + string diagram, + string stamp, + CancellationToken cancellationToken + ) => File.WriteAllTextAsync(Path.Combine(directory, FileName(diagram)), stamp, cancellationToken); +} diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs index 0592bf0..6079e1a 100644 --- a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs +++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs @@ -10,5 +10,7 @@ public void Dispose() _debounceCts?.Dispose(); _debounceCts = null; } + + _exportGate.Dispose(); } } diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs index f255e19..73f278d 100644 --- a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs +++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs @@ -55,7 +55,8 @@ async Task WriteC4FileAsync(DistributedApplicationModel appModel, CancellationTo // is identical to what was last written. This prevents needless git noise when state // changes bounce resources through transitional states that end up back where they started. var newRawBody = StripHeader(dsl); - if (!string.Equals(_lastRawBody, newRawBody, StringComparison.Ordinal)) + var changed = !string.Equals(_lastRawBody, newRawBody, StringComparison.Ordinal); + if (changed) { _lastRawBody = newRawBody; await File.WriteAllTextAsync(outputPath, dsl, cancellationToken); @@ -93,6 +94,22 @@ async Task WriteC4FileAsync(DistributedApplicationModel appModel, CancellationTo } telemetry.LikeC4ModelWritten(outputPath); + + // Gated on the same comparison as the write itself: exporting is expensive enough that it is + // worth doing only when there is a new model to render. Fire-and-forget, because the export + // starts a LikeC4 server and a browser and must not sit between the application and its startup. + // Never on publish, which generates the model and exits — see _isPublishMode. + if (ShouldExportImages(changed, opts.ExportImages, _isPublishMode)) + { + // The same base directory the output and serve directories were resolved from, so the images + // land beside the ER diagram's rather than wherever this AppHost happens to have been started. + var appHostDirectory = Environment.CurrentDirectory; + + _ = Task.Run( + () => ExportImagesAsync(outputDir, serveDir, appHostDirectory, newRawBody, cancellationToken), + cancellationToken + ); + } } /// diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.ImageExport.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.ImageExport.cs new file mode 100644 index 0000000..2911696 --- /dev/null +++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.ImageExport.cs @@ -0,0 +1,101 @@ +using Aspire.Hosting.AspireC4.LikeC4.Runtime; + +namespace Aspire.Hosting.AspireC4.Lifecycle; + +sealed partial class AspireC4LifecycleHook +{ + /// Serialises export runs so two invocations never write the same image at once. + readonly SemaphoreSlim _exportGate = new(1, 1); + + /// + /// Whether this run is a publish rather than a run, in which case nothing is exported. + /// + /// + /// Publish generates the model and the manifest and then exits. An export starts a container and is + /// fire-and-forget, so on publish it would either be killed part-way through — leaving a truncated + /// image where a good one used to be — or hold the process open well past the work it was asked to + /// do. Publish is also expected to be hermetic: reaching for a container runtime that a build agent + /// may not have turns a working publish into a failing one. + /// + volatile bool _isPublishMode; + + /// + /// Whether a write that has just happened should be followed by an image export. + /// + /// + /// Extracted so the rule can be asserted directly. Driving it through a publish proves nothing: the + /// export is fire-and-forget and publish exits immediately afterwards, so the images are missing at + /// the end of a publish whether this returns false or the export simply had not finished — which is + /// the very race that makes exporting on publish the wrong thing to do. + /// + /// Whether the generated model differs from the last one written. + /// The configured . + /// Whether this run is a publish rather than a run. + internal static bool ShouldExportImages(bool changed, bool exportImages, bool isPublishMode) => + changed && exportImages && !isPublishMode; + + /// + /// Incremented for every requested export, so a run that is still queued when a newer model arrives + /// can stand down rather than render a model that has already been superseded. + /// + long _exportVersion; + + /// + /// Renders the views to images, unless a newer model arrived while this run was waiting its turn. + /// + /// + /// Called fire-and-forget from , which has already established that the + /// generated model changed. The resource-state watcher regenerates the model on every state + /// transition, so a long export can easily be overtaken; superseded runs stand down rather than + /// queueing up behind each other and writing older output last. + /// + async Task ExportImagesAsync( + string outputDirectory, + string serveDirectory, + string appHostDirectory, + string modelBody, + CancellationToken cancellationToken + ) + { + var version = Interlocked.Increment(ref _exportVersion); + + try + { + await _exportGate.WaitAsync(cancellationToken); + } + catch (OperationCanceledException) + { + // Shutdown. + return; + } + + try + { + if (Interlocked.Read(ref _exportVersion) != version) + { + return; + } + + // In container mode the export runs in the LikeC4 image, which already carries the Chromium + // and Graphviz binaries it needs; only WithLocalCLI() shifts it onto the host's own CLI. + var localCLI = workspaceOptions.Value.LocalCLIRuntime is { } runtime + ? AspireC4Builder.BuildLikeC4CLIPrefix(runtime) + : ((string Command, string[] Prefix)?)null; + + await LikeC4ImageExporter.ExportAsync( + options.Value, + outputDirectory, + serveDirectory, + appHostDirectory, + modelBody, + localCLI, + telemetry, + cancellationToken + ); + } + finally + { + _exportGate.Release(); + } + } +} diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs index 661d9e5..18a9ca4 100644 --- a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs +++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs @@ -73,6 +73,10 @@ public Task SubscribeAsync( CancellationToken cancellationToken ) { + // Recorded before anything subscribes, because WriteC4FileAsync is reached from the publish path + // too and has no other way to tell the two apart. + _isPublishMode = executionContext.IsPublishMode; + eventing.Subscribe( async (evt, ct) => { diff --git a/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs b/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs index 1713aa8..14fa178 100644 --- a/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs +++ b/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs @@ -46,4 +46,16 @@ interface IAspireC4LifecycleHookTelemetry [Debug] void DiagramOptionsSnapshotApplied(string outputDirectoryName, bool formatGeneratedFile, bool disableHmr); + + [Debug] + void ExportingImages(string format, string imageDirectory); + + [Info] + void ImagesExported(string format, string imageDirectory); + + [Warning] + void FailedToExportImages(string format, string reason); + + [Debug] + void ImagesUnchanged(string imageDirectory); } diff --git a/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageExporter.cs b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageExporter.cs new file mode 100644 index 0000000..8c57fd1 --- /dev/null +++ b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageExporter.cs @@ -0,0 +1,430 @@ +using System.Diagnostics; +using Aspire.Hosting.AspireC4.ApplicationModel; +using Aspire.Hosting.AspireC4.Lifecycle; + +namespace Aspire.Hosting.AspireC4.LikeC4.Runtime; + +/// +/// Renders the LikeC4 views to image files with likec4 export. +/// +/// +/// +/// Export drives a headless browser, which is why it runs in the ghcr.io/likec4/likec4 image by +/// default: that image already carries the Chromium build and the Graphviz binaries LikeC4 lays out +/// with. In local CLI mode the host's own likec4 is used instead, which needs a Playwright +/// Chromium installed on the host. +/// +/// +/// Every view in the project is exported, not only the generated one — a hand-authored project's views +/// are part of the same model and are laid out by the same pass, so excluding them would mean asking +/// LikeC4 to do the work and then discarding most of it. +/// +/// +static class LikeC4ImageExporter +{ + /// The directory the images mount is exposed at inside the export container. + internal const string ContainerOutputPath = "/out"; + + /// + /// How long, in seconds, the headless browser is given per view. The CLI's own default of 15 is + /// tight for a large generated view on a cold start. + /// + internal const int PerViewTimeoutSeconds = 60; + + /// The likec4 export format name for a given image format. + internal static string FormatName(LikeC4ImageFormat format) => format == LikeC4ImageFormat.Jpg ? "jpg" : "png"; + + /// + /// The formats to export, in a stable order. + /// + /// + /// is a set, whose enumeration order depends on + /// insertion and on whether configuration binding appended to it. + /// + internal static IReadOnlyList FormatsToExport(AspireC4DiagramOptions options) + { + ArgumentNullException.ThrowIfNull(options); + + return [.. options.ImageFormats.Distinct().Order()]; + } + + /// Resolves the directory images are written to, as an absolute path. + internal static string ResolveImageDirectory(AspireC4DiagramOptions options, string appHostDirectory) + { + ArgumentNullException.ThrowIfNull(options); + + return AspireC4ImageExport.Resolve(options.ImageExportDirectory, appHostDirectory); + } + + /// + /// Builds the command, arguments and working directory for one likec4 export invocation. + /// + /// The diagram options. + /// Where the generated model was written. + /// The LikeC4 project root, which is what gets exported. + /// Where the images are written. + /// The format to export. + /// + /// The host command and argument prefix when running the local CLI, or to run + /// the one-shot container. + /// + internal static (string Command, IReadOnlyList Arguments, string WorkingDirectory) BuildInvocation( + AspireC4DiagramOptions options, + string outputDirectory, + string serveDirectory, + string imageDirectory, + LikeC4ImageFormat format, + (string Command, string[] Prefix)? localCLI + ) + { + ArgumentNullException.ThrowIfNull(options); + ArgumentException.ThrowIfNullOrWhiteSpace(outputDirectory); + ArgumentException.ThrowIfNullOrWhiteSpace(serveDirectory); + ArgumentException.ThrowIfNullOrWhiteSpace(imageDirectory); + + if (localCLI is { } cli) + { + return ( + cli.Command, + [.. cli.Prefix, .. ExportArguments(FormatName(format), imageDirectory, serveDirectory)], + // LikeC4 resolves the relative include paths and image aliases in likec4.config.json + // against the process working directory, so this has to match what the server and the + // formatter use or those paths climb out of the project. + outputDirectory + ); + } + + // The container sees the host tree through a single bind mount, exactly as the server does, so + // the config's relative paths resolve to the same files either way. + var workspaceRoot = AspireC4LifecycleHook.ComputeCommonAncestor([ + outputDirectory, + serveDirectory, + .. options.AdditionalDSLFolders.Select(Path.GetFullPath), + .. options.ImageAliases.Values.Select(Path.GetFullPath), + ]); + + var containerServePath = ToContainerPath(workspaceRoot, serveDirectory); + var tag = options.ContainerImageTag ?? LikeC4ServerResource.DefaultTag; + + return ( + options.ContainerRuntimeCommand, + [ + "run", + "--rm", + // Read-only, like the server's mount: nothing in the source tree should be written by an + // export. The images land on their own writable mount instead. + // + // --mount rather than -v: a Windows host path already contains a colon, so + // "C:\…\likec4:/data:ro" leaves the runtime guessing where the drive letter ends and the + // mode begins, and it guesses wrong. --mount parses key=value and cannot be ambiguous. + "--mount", + $"type=bind,source={workspaceRoot},target={LikeC4ServerResource.WorkspacePath},readonly", + "--mount", + $"type=bind,source={imageDirectory},target={ContainerOutputPath}", + "--workdir", + ToContainerPath(workspaceRoot, outputDirectory), + LikeC4ServerResource.GetImageReference(tag), + .. ExportArguments(FormatName(format), ContainerOutputPath, containerServePath), + ], + workspaceRoot + ); + } + + static IReadOnlyList ExportArguments(string format, string imageDirectory, string serveDirectory) => + [ + "export", + format, + "-o", + imageDirectory, + // Without this the output mirrors the source tree, so an image's path depends on where the + // .c4 file happened to live rather than on the view it came from. + "--flat", + // One view that fails to render should not discard the ones that succeeded. + "-i", + "-t", + PerViewTimeoutSeconds.ToString(System.Globalization.CultureInfo.InvariantCulture), + serveDirectory, + ]; + + /// Maps a host path beneath the workspace root onto its path inside the container. + static string ToContainerPath(string workspaceRoot, string path) + { + var relative = Path.GetRelativePath(workspaceRoot, path).Replace('\\', '/'); + + return relative is "." or "" + ? LikeC4ServerResource.WorkspacePath + : $"{LikeC4ServerResource.WorkspacePath}/{relative}"; + } + + /// Renders every configured format, returning how many invocations succeeded. + /// + /// Best-effort throughout, like the formatter: a failed export leaves the generated model untouched, + /// so the only correct response is to report it and carry on. + /// + /// The diagram options. + /// Where the generated model was written. + /// The LikeC4 project root, which is what gets exported. + /// The AppHost directory the images directory is resolved against. + /// + /// The generated model, with its timestamp header stripped, recorded so an unchanged model renders + /// nothing on the next run. + /// + /// The host CLI to run, or for the container. + /// Where export progress and failures are reported. + /// Cancelled on shutdown. + public static async Task ExportAsync( + AspireC4DiagramOptions options, + string outputDirectory, + string serveDirectory, + string appHostDirectory, + string modelBody, + (string Command, string[] Prefix)? localCLI, + IAspireC4LifecycleHookTelemetry telemetry, + CancellationToken cancellationToken + ) + { + ArgumentNullException.ThrowIfNull(options); + ArgumentNullException.ThrowIfNull(telemetry); + + var formats = FormatsToExport(options); + + if (formats.Count == 0) + { + return 0; + } + + var imageDirectory = ResolveImageDirectory(options, appHostDirectory); + + // Checked before anything is run. The AppHost's own change detection resets every time it + // restarts, so without this a restart re-renders views that are already correct on disk — and + // an export starts a LikeC4 server and a headless browser to do it. + var stamp = ImageExportStamp.Compute(modelBody, string.Join(",", formats.Select(FormatName))); + + if ( + await ImageExportStamp + .IsCurrentAsync(imageDirectory, StampName, stamp, ExistingImages(imageDirectory), cancellationToken) + .ConfigureAwait(false) + ) + { + telemetry.ImagesUnchanged(imageDirectory); + + return 0; + } + + // Created here rather than left to the container runtime: a missing bind-mount source is created + // by the daemon as root, which a later host-side write could not then touch. + Directory.CreateDirectory(imageDirectory); + + var exported = 0; + + foreach (var format in formats) + { + var name = FormatName(format); + + // Exported into a staging directory and moved in afterwards, because the CLI names each file + // after its view id with no say in the matter. In a folder shared with the ER diagram a bare + // "index.png" says nothing about which diagram it came from, and could collide outright. + var staging = Path.Combine(Path.GetTempPath(), $"aspirec4-export-{Guid.NewGuid():N}"); + + Directory.CreateDirectory(staging); + + try + { + var (command, arguments, workingDirectory) = BuildInvocation( + options, + outputDirectory, + serveDirectory, + staging, + format, + localCLI + ); + + telemetry.ExportingImages(name, imageDirectory); + + if ( + await RunAsync(command, arguments, workingDirectory, options, name, telemetry, cancellationToken) + .ConfigureAwait(false) + ) + { + exported++; + + MoveWithPrefix(staging, imageDirectory); + + telemetry.ImagesExported(name, imageDirectory); + } + } + finally + { + TryDelete(staging); + } + } + + // Only once every requested format landed: a partial export must not be mistaken for a current + // one, or the formats that failed would never be retried. + if (exported == formats.Count) + { + await ImageExportStamp + .WriteAsync(imageDirectory, StampName, stamp, cancellationToken) + .ConfigureAwait(false); + } + + return exported; + } + + /// Distinguishes this diagram's stamp from the ER diagram's in the shared folder. + internal const string StampName = "architecture"; + + /// + /// The images this diagram has already written, which the stamp alone cannot stand in for. + /// + /// + /// The view names are only known once the CLI has run, so unlike the ER diagram there is no list of + /// expected files to check against — the test is whether this diagram left anything behind at all. + /// Deleting one view's image and keeping the rest is therefore not noticed; deleting the folder is. + /// + static string[] ExistingImages(string imageDirectory) + { + var missing = Path.Combine(imageDirectory, "(none)"); + + if (!Directory.Exists(imageDirectory)) + { + return [missing]; + } + + var existing = Directory + .EnumerateFiles(imageDirectory, $"{AspireC4ImageExport.ArchitecturePrefix}*") + .Take(1) + .ToArray(); + + return existing.Length == 0 ? [missing] : existing; + } + + /// Moves every staged image into the shared folder under its prefixed name. + /// + /// Overwrites, so a view that has been re-exported replaces its previous image rather than + /// accumulating. A view removed from the model leaves its last image behind, which is the lesser + /// evil: emptying the folder would also delete the ER diagram's images sitting beside them. + /// + static void MoveWithPrefix(string staging, string imageDirectory) + { + foreach (var file in Directory.EnumerateFiles(staging)) + { + var destination = Path.Combine( + imageDirectory, + AspireC4ImageExport.ArchitecturePrefix + Path.GetFileName(file) + ); + + File.Move(file, destination, overwrite: true); + } + } + + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Design", + "CA1031:Do not catch general exception types", + Justification = "Cleaning up a temporary directory must never fail an export that otherwise succeeded" + )] + static void TryDelete(string directory) + { + try + { + if (Directory.Exists(directory)) + { + Directory.Delete(directory, recursive: true); + } + } + catch + { + // A leftover temp directory is harmless. + } + } + + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Design", + "CA1031:Do not catch general exception types", + Justification = "Image export is best-effort; failures are reported via telemetry and never block startup" + )] + static async Task RunAsync( + string command, + IReadOnlyList arguments, + string workingDirectory, + AspireC4DiagramOptions options, + string format, + IAspireC4LifecycleHookTelemetry telemetry, + CancellationToken cancellationToken + ) + { + try + { + ProcessStartInfo startInfo = new() + { + FileName = command, + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false, + CreateNoWindow = true, + WorkingDirectory = workingDirectory, + }; + + foreach (var argument in arguments) + { + startInfo.ArgumentList.Add(argument); + } + + using var process = Process.Start(startInfo); + + if (process is null) + { + telemetry.FailedToExportImages(format, "the process could not be started"); + + return false; + } + + using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + cts.CancelAfter(TimeSpan.FromSeconds(options.ImageExportTimeoutSeconds)); + + // Drained before waiting: likec4 export is verbose, and a full pipe would deadlock the wait. + var error = await process.StandardError.ReadToEndAsync(cts.Token).ConfigureAwait(false); + + try + { + await process.WaitForExitAsync(cts.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + try + { + process.Kill(entireProcessTree: true); + } + catch + { + // Best-effort kill. + } + + throw; + } + + if (process.ExitCode == 0) + { + return true; + } + + telemetry.FailedToExportImages( + format, + string.IsNullOrWhiteSpace(error) ? $"it exited with code {process.ExitCode}" : error.Trim() + ); + + return false; + } + catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) + { + // Shutdown. + return false; + } + catch (Exception ex) + { + telemetry.FailedToExportImages(format, ex.Message); + + return false; + } + } +} diff --git a/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageFormat.cs b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageFormat.cs new file mode 100644 index 0000000..7e0d95e --- /dev/null +++ b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageFormat.cs @@ -0,0 +1,21 @@ +namespace Aspire.Hosting.AspireC4.LikeC4.Runtime; + +/// +/// The image formats the architecture diagram is exported to on startup. +/// +/// +/// There is deliberately no SVG member: the LikeC4 CLI renders its views by screenshotting them in a +/// headless browser, and likec4 export offers only png and jpg as image formats. +/// For a vector of the architecture, export the model instead and render it with another tool. +/// +public enum LikeC4ImageFormat +{ + /// Portable network graphic. The default, and the better of the two for a diagram. + Png, + + /// + /// JPEG. Smaller than a PNG of the same view, at the cost of compression artefacts around the text + /// and borders a diagram is almost entirely made of. + /// + Jpg, +} diff --git a/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs b/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs index 11365d9..c0aaed2 100644 --- a/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs +++ b/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs @@ -29,7 +29,7 @@ public static Result Analyse(INamedTypeSymbol context, SemanticModel semanticMod // Entity -> the name the table takes before attributes and fluent config are applied. Dictionary entities = [with(SymbolEqualityComparer.Default)]; - foreach (var property in context.GetMembers().OfType()) + foreach (var property in Properties(context)) { if ( property.Type is INamedTypeSymbol { IsGenericType: true } set @@ -60,6 +60,34 @@ public static Result Analyse(INamedTypeSymbol context, SemanticModel semanticMod return new Result(context.Name, context.ToDisplayString(), fluent.DefaultSchema, tables, diagnostics); } + /// Every property a type exposes, including the ones it inherits. + /// + /// A base entity carrying the key, timestamps and audit columns — and a base context declaring the + /// DbSet properties — are both ordinary shapes, but Roslyn's GetMembers returns only + /// what a type declares itself. Without walking the chain those properties are invisible, and with + /// them go the keys, columns and navigations among them. A derived property hides a base one of the + /// same name, which is how the compiler resolves it too. + /// + static List Properties(INamedTypeSymbol type) + { + List properties = []; + HashSet declared = [with(StringComparer.Ordinal)]; + + // Stops at object, ValueType and Enum: a special type declares no mapped property of its own. + for (var current = type; current is { SpecialType: SpecialType.None }; current = current.BaseType) + { + foreach (var property in current.GetMembers().OfType()) + { + if (declared.Add(property.Name)) + { + properties.Add(property); + } + } + } + + return properties; + } + static FluentConfiguration ReadFluentConfiguration( INamedTypeSymbol context, SemanticModel semanticModel, @@ -113,7 +141,7 @@ static void AddReachableEntities(Dictionary entities) while (queue.Count > 0) { - foreach (var property in queue.Dequeue().GetMembers().OfType()) + foreach (var property in Properties(queue.Dequeue())) { var target = GetNavigationTarget(property.Type); @@ -148,7 +176,7 @@ static TableShape BuildTable( var uniqueFromIndexes = ReadUniqueIndexProperties(entity); List navigations = []; - foreach (var property in entity.GetMembers().OfType()) + foreach (var property in Properties(entity)) { if ( property.DeclaredAccessibility != Accessibility.Public @@ -264,7 +292,7 @@ static void AddComplexColumns(TableShape table, string prefix, ITypeSymbol compl return; } - foreach (var member in named.GetMembers().OfType()) + foreach (var member in Properties(named)) { if ( member.DeclaredAccessibility != Accessibility.Public @@ -354,11 +382,7 @@ static void ApplyPrimaryKeys(INamedTypeSymbol entity, TableShape table, EntityCo else { keyProperties.AddRange( - entity - .GetMembers() - .OfType() - .Where(p => HasAttribute(p, EfTypes.Attributes.Key)) - .Select(p => p.Name) + Properties(entity).Where(p => HasAttribute(p, EfTypes.Attributes.Key)).Select(p => p.Name) ); } @@ -414,7 +438,8 @@ Dictionary entities var column = (explicitName is null ? null : table.Columns.FirstOrDefault(c => c.PropertyName == explicitName)) ?? table.Columns.FirstOrDefault(c => c.PropertyName == navigation.Name + "Id") - ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id"); + ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id") + ?? SharedPrimaryKeyColumn(table, target); if (column is null) { @@ -423,14 +448,16 @@ Dictionary entities column.IsForeignKey = true; + // A foreign key that is also the whole key, or is uniquely indexed, can only match one + // principal row — that is what makes a relationship one-to-one rather than one-to-many. + var isUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique; + ForeignKeyShape foreignKey = new() { PrincipalEntity = target.ToDisplayString(), NavigationName = navigation.Name, - PrincipalNavigationName = PrincipalNavigation(target, dependent), - // A foreign key that is also the whole key, or is uniquely indexed, can only match one - // principal row — that is what makes a relationship one-to-one rather than one-to-many. - IsUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique, + PrincipalNavigationName = PrincipalNavigation(target, dependent, isUnique), + IsUnique = isUnique, IsRequired = !column.IsNullable, }; @@ -439,12 +466,92 @@ Dictionary entities } } + /// + /// The dependent's own primary key, when that key doubles as the foreign key to the principal. + /// + /// + /// A shared-primary-key one-to-one — RepositoryState.Id being the Asset it describes — + /// declares no <Navigation>Id property, so the usual column lookup finds nothing and the + /// relationship disappears entirely. What identifies it is the dependent having borrowed the + /// principal's identity: the principal's key type is its own identifier, and the dependent is keyed by + /// that same type. A primitive key is deliberately not enough, because every entity keyed by + /// Guid or int would then match every other one. + /// + static ColumnShape? SharedPrimaryKeyColumn(TableShape table, INamedTypeSymbol principal) + { + var keyColumns = table.Columns.Where(c => c.IsPrimaryKey).ToList(); + + if (keyColumns.Count != 1 || PrimaryKeyType(principal) is not { } principalKeyType) + { + return null; + } + + return + StoreTypeMap.ValueObjectType(principalKeyType) is not null + && IsOwnIdentifier(principal.Name, principalKeyType.Name) + && keyColumns[0].ClrTypeName == principalKeyType.ToDisplayString() + ? keyColumns[0] + : null; + } + + /// + /// Whether a key type is the entity's own identifier, judged by name: AssetId belongs to + /// Asset — or AssetEntity — and so marks that entity as the owner of the identity + /// rather than a borrower of someone else's. + /// + static bool IsOwnIdentifier(string entityName, string keyTypeName) + { + const string idSuffix = "Id"; + const string entitySuffix = "Entity"; + + if (!keyTypeName.EndsWith(idSuffix, StringComparison.Ordinal)) + { + return false; + } + + var stem = keyTypeName.Substring(0, keyTypeName.Length - idSuffix.Length); + var owner = entityName.EndsWith(entitySuffix, StringComparison.Ordinal) + ? entityName.Substring(0, entityName.Length - entitySuffix.Length) + : entityName; + + return stem.Length > 0 && string.Equals(stem, owner, StringComparison.Ordinal); + } + + /// The type of an entity's single primary key property, following the same conventions as + /// ; for a composite or unrecognised key. + static ITypeSymbol? PrimaryKeyType(INamedTypeSymbol entity) + { + var properties = Properties(entity); + var keyed = properties.Where(p => HasAttribute(p, EfTypes.Attributes.Key)).ToList(); + + if (keyed.Count > 0) + { + return keyed.Count == 1 ? keyed[0].Type : null; + } + + return properties + .FirstOrDefault(p => + string.Equals(p.Name, "Id", StringComparison.OrdinalIgnoreCase) + || string.Equals(p.Name, entity.Name + "Id", StringComparison.OrdinalIgnoreCase) + ) + ?.Type; + } + /// /// The principal-side navigation: a collection on the principal whose element is the dependent. /// - static string? PrincipalNavigation(INamedTypeSymbol principal, INamedTypeSymbol dependent) + /// The entity the foreign key points at. + /// The entity the foreign key lives on. + /// + /// Whether the foreign key is unique. A one-to-one has no collection to find, so its inverse is a + /// reference to the dependent — which is only safe to read as the inverse when the key says the + /// relationship is one-to-one, otherwise any two entities that point at each other would pair up. + /// + static string? PrincipalNavigation(INamedTypeSymbol principal, INamedTypeSymbol dependent, bool isUnique) { - foreach (var property in principal.GetMembers().OfType()) + var properties = Properties(principal); + + foreach (var property in properties) { if ( IsCollection(property.Type) @@ -456,7 +563,11 @@ Dictionary entities } } - return null; + return isUnique + ? properties + .FirstOrDefault(p => SymbolEqualityComparer.Default.Equals(StoreTypeMap.Unwrap(p.Type), dependent)) + ?.Name + : null; } /// @@ -544,10 +655,43 @@ static HashSet ReadUniqueIndexProperties(INamedTypeSymbol entity) return null; } + // A framework type is never an entity in someone's model. Any class this analyser does not + // recognise as a scalar would otherwise be taken for a navigation and gain a table of its own, + // named after the framework type — so a single unmapped type turns into a phantom entity, and + // the walk then follows its properties into more of them. + if (IsFrameworkType(named)) + { + return null; + } + // A class that maps to a column (string, byte[], ...) is not a navigation. return named.SpecialType == SpecialType.None && !StoreTypeMap.IsScalar(named) ? Normalise(named) : null; } + /// + /// Whether a type belongs to the framework rather than to the model being analysed. + /// + /// + /// Matched on the namespace root, so a user type is only ever caught by this if it was declared + /// directly in System or Microsoft — which EF would not map as an entity either. + /// + static bool IsFrameworkType(INamedTypeSymbol type) + { + var root = type.ContainingNamespace; + + if (root is null || root.IsGlobalNamespace) + { + return false; + } + + while (root.ContainingNamespace is { IsGlobalNamespace: false } parent) + { + root = parent; + } + + return root.Name is "System" or "Microsoft"; + } + /// /// Strips the nullable annotation from a navigation's target type. /// diff --git a/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs b/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs index 71bc627..2dbdf3d 100644 --- a/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs +++ b/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs @@ -83,8 +83,19 @@ public void Initialize(IncrementalGeneratorInitializationContext context) ); } + /// Whether a type is a DbContext the diagram should show. + /// + /// An abstract or open-generic context — the DbContextBase<T> a real context derives from + /// — is never instantiated and owns no tables of its own, so describing it adds an empty node to the + /// diagram beside the context that actually has the model, and reports it as having no entity types. + /// static bool DerivesFromDbContext(INamedTypeSymbol symbol) { + if (symbol.IsAbstract || symbol.IsUnboundGenericType || symbol.TypeParameters.Length > 0) + { + return false; + } + for (var current = symbol.BaseType; current is not null; current = current.BaseType) { if (current.ToDisplayString() == EfTypes.DbContext) diff --git a/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs b/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs index 6a98c8f..9be5d74 100644 --- a/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs +++ b/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs @@ -57,6 +57,15 @@ public static string Resolve(ITypeSymbol type) "System.TimeSpan" => "time", "System.DateOnly" => "date", "System.TimeOnly" => "time", + // A JSON document is a column, not a table. Without these it resolves to Unknown, and an + // unknown class is taken for a navigation — which is how a property such as + // `JsonDocument Payload` used to invent an entity named after the framework type. + "System.Text.Json.JsonDocument" + or "System.Text.Json.JsonElement" + or "System.Text.Json.Nodes.JsonNode" + or "System.Text.Json.Nodes.JsonObject" + or "System.Text.Json.Nodes.JsonArray" + or "System.Text.Json.Nodes.JsonValue" => "json", _ => Unknown, }; } diff --git a/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs b/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs index 2f75da0..0a12cd7 100644 --- a/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs +++ b/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs @@ -124,6 +124,115 @@ internal static bool IsDefaultOutputDirectory(string? outputDirectory) => /// Pin the d2lang/d2 image tag. uses the package default. public string? ContainerImageTag { get; set; } + /// + /// Whether the diagram is also written out as an image each time it changes. On by default. + /// + /// + /// + /// The images are written beside the diagram as {FileName}.svg and {FileName}.png, so a + /// schema can be attached to a pull request or pasted into a wiki without opening the viewer. Export + /// runs in the background, so it never delays startup, and only when it would actually change + /// something: a stamp beside the images records what they were rendered from, so a restart that + /// produces the same model runs nothing at all — not even a container. It is also skipped entirely + /// during a publish, which generates its output and exits. + /// + /// + /// Rendering always goes through d2, whatever is in use: the interactive + /// renderer is a browser application with no headless path, so an image of it could only be produced + /// by driving a browser. That means export needs either the d2lang/d2 container or a local + /// d2 binary (), and that the {FileName}.d2 source is written + /// alongside the diagram even for the other renderers. Set to , or use + /// , where neither is available. + /// + /// + public bool ExportImages { get; set; } = true; + + /// + /// The formats written when is set. Defaults to both SVG and PNG. + /// + /// + /// Emptying this disables export as surely as clearing . Populate with + /// . + /// + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Usage", + "CA2227:Collection properties should be read only", + Justification = "Settable for configuration binding and direct assignment in user code" + )] + public HashSet ImageFormats { get; set; } = [ErdImageFormat.Svg, ErdImageFormat.Png]; + + /// + /// Where exported images are written. Relative paths are resolved against the AppHost directory; + /// (the default) uses ./.aspirec4/images/. + /// + /// + /// The architecture diagram writes to the same folder by default, so every image AspireC4 produces is + /// in one place. It matters most here: the interactive renderer writes its own index.html, + /// app.js and vendor/ into , and an image among those is + /// easy to miss. + /// + public string? ImageExportDirectory { get; set; } + + /// + /// A local d2 executable to render exported images with. (the default) + /// runs the d2lang/d2 container instead. + /// + /// + /// Set by , which also replaces the + /// sidecar. Set it here to render images locally while leaving the sidecar — or the renderer's own + /// viewer — as it is. + /// + public string? D2Command { get; set; } + + /// + /// The container runtime used to run the one-shot export container. Defaults to docker. + /// + /// Set to podman where that is the runtime Aspire itself is using. + public string ContainerRuntimeCommand { get; set; } = "docker"; + + /// Seconds to wait for an image export before abandoning it. Defaults to 120. + public int ExportTimeoutSeconds { get; set; } = 120; + + /// + /// Whether exported images are produced by the interactive viewer itself rather than by d2. Off by + /// default. + /// + /// + /// + /// The d2 export 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. Setting this makes the exported + /// file identical to the one the viewer's own Save as SVG / PNG control produces. + /// + /// + /// The cost is a browser: the viewer only runs in one, so this pulls the Playwright image — around + /// 3.7 GB — and an export takes seconds rather than milliseconds. That is why it is opt-in. + /// Applies only to , the renderer that has a viewer; every other + /// renderer exports through d2 whatever this is set to. + /// + /// + /// + public bool UseViewerFidelityExport { get; set; } + + /// + /// Overrides the image used for the viewer-fidelity export, including its tag. + /// uses the pinned Playwright image. + /// + /// + /// The image has to supply both node and a chromium Playwright can drive. Pointing this at + /// something else is how a consumer uses a mirror, or an image they have already cached. + /// + public string? ViewerExportImage { get; set; } + + /// + /// Seconds to wait for a viewer-fidelity export. Defaults to 600. + /// + /// + /// Far longer than because the first run may be pulling the + /// browser image. Export runs in the background, so this never caps startup. + /// + public int ViewerExportTimeoutSeconds { get; set; } = 600; + /// /// Whether the file-based renderers serve their viewer over HTTP so the dashboard can link to it. /// @@ -179,6 +288,54 @@ public AspireC4EfDiagramOptions WithProjectOptInOnly() return this; } + /// Restricts image export to the listed formats, replacing the SVG and PNG default. + /// + /// Also sets , so naming a format is enough to turn export on. Passing no + /// format turns it off, the same as . + /// + /// The formats to export. + /// This options instance, for chaining. + public AspireC4EfDiagramOptions WithImageExport(params ErdImageFormat[] formats) + { + ArgumentNullException.ThrowIfNull(formats); + + ImageFormats = [.. formats]; + ExportImages = formats.Length > 0; + + return this; + } + + /// + /// Exports images by rendering the interactive viewer in a headless browser, so the file matches + /// the viewer's own Save as SVG / PNG output exactly. + /// + /// + /// Pulls a browser image of around 3.7 GB and makes each export take seconds rather than + /// milliseconds; see . Only affects + /// . + /// + /// Whether to render through the viewer. + /// This options instance, for chaining. + public AspireC4EfDiagramOptions WithViewerFidelityExport(bool use = true) + { + UseViewerFidelityExport = use; + + return this; + } + + /// Stops the diagram being exported as an image, leaving only the generated diagram. + /// + /// This is how a consumer with no container runtime and no local d2 opts out; see + /// for why export needs one of the two. + /// + /// This options instance, for chaining. + public AspireC4EfDiagramOptions WithoutImageExport() + { + ExportImages = false; + + return this; + } + /// Sets how a column shows its domain type next to the database type. /// The display mode. /// This options instance, for chaining. diff --git a/src/src/EntityFrameworkCore/Assets/export/viewer-export.mjs b/src/src/EntityFrameworkCore/Assets/export/viewer-export.mjs new file mode 100644 index 0000000..f73e1af --- /dev/null +++ b/src/src/EntityFrameworkCore/Assets/export/viewer-export.mjs @@ -0,0 +1,245 @@ +// Renders the generated interactive ER viewer in a real browser and saves the image it produces. +// +// The viewer is a React Flow application, so the only way to get an image that matches what a reader +// sees is to let the viewer produce it: this calls the very function the toolbar's Save as SVG/PNG +// control calls. A d2 render, or a screenshot of the window, is a different picture. +// +// Driven over the Chrome DevTools Protocol using nothing but Node's own APIs. The Playwright image +// ships the browsers but not the `playwright` package, and installing one at export time would mean a +// network fetch on a path that is meant to be hermetic. +// +// Invoked as: node viewer-export.mjs +// with the viewer mounted read-only at /data and the destination at /out. +import { spawn } from "node:child_process"; +import { createServer } from "node:http"; +import { mkdtemp, readdir, readFile, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { extname, join, normalize } from "node:path"; + +const VIEWER = "/data"; +const OUTPUT = "/out"; +const BROWSERS = "/ms-playwright"; + +const formats = (process.argv[2] ?? "svg").split(",").filter(Boolean); +const baseName = process.argv[3] ?? "schema"; + +const TYPES = { + ".html": "text/html; charset=utf-8", + ".js": "text/javascript; charset=utf-8", + ".mjs": "text/javascript; charset=utf-8", + ".json": "application/json; charset=utf-8", + ".css": "text/css; charset=utf-8", + ".svg": "image/svg+xml", +}; + +const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); + +/** Locates the chromium the image shipped, whatever revision it happens to be. */ +async function findChrome() { + for (const entry of await readdir(BROWSERS)) { + if (entry.startsWith("chromium-")) { + return join(BROWSERS, entry, "chrome-linux", "chrome"); + } + } + + throw new Error(`No chromium found under ${BROWSERS}.`); +} + +/** + * Serves the viewer over HTTP. + * + * Not opened from file://, because the viewer fetches its model JSON and that fetch is blocked under + * the file:// origin. The server is local to this container, so nothing is exposed anywhere. + */ +async function serveViewer() { + const server = createServer(async (request, response) => { + try { + const url = new URL(request.url ?? "/", "http://127.0.0.1"); + const relative = + url.pathname === "/" ? "index.html" : decodeURIComponent(url.pathname).replace(/^\/+/, ""); + const path = join(VIEWER, normalize(relative)); + + // normalize() collapses any "..", so a path that still escapes the root was trying to. + if (!path.startsWith(VIEWER)) { + response.writeHead(403).end(); + + return; + } + + const body = await readFile(path); + + response.writeHead(200, { "content-type": TYPES[extname(path)] ?? "application/octet-stream" }).end(body); + } catch { + response.writeHead(404).end(); + } + }); + + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + + return server; +} + +/** Waits for the browser to publish its DevTools endpoint, then returns the page's socket URL. */ +async function connect(port) { + for (let attempt = 0; attempt < 100; attempt++) { + try { + const targets = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json(); + const page = targets.find((t) => t.type === "page"); + + if (page?.webSocketDebuggerUrl) { + return page.webSocketDebuggerUrl; + } + } catch { + // The browser is still starting. + } + + await sleep(100); + } + + throw new Error("The browser never published a DevTools endpoint."); +} + +/** A minimal CDP client: send a command, await its reply. */ +function client(socket) { + let nextId = 0; + const pending = new Map(); + + socket.addEventListener("message", (event) => { + const message = JSON.parse(event.data); + const waiter = pending.get(message.id); + + if (!waiter) return; + + pending.delete(message.id); + + if (message.error) waiter.reject(new Error(message.error.message)); + else waiter.resolve(message.result); + }); + + return (method, params = {}) => + new Promise((resolve, reject) => { + const id = ++nextId; + + pending.set(id, { resolve, reject }); + socket.send(JSON.stringify({ id, method, params })); + }); +} + +/** Evaluates an expression in the page and returns its value, surfacing a page-side throw. */ +async function evaluate(send, expression) { + const result = await send("Runtime.evaluate", { + expression, + awaitPromise: true, + returnByValue: true, + }); + + if (result.exceptionDetails) { + throw new Error(result.exceptionDetails.exception?.description ?? "evaluation failed"); + } + + return result.result.value; +} + +/** + * Decodes the renderer's data URL into the bytes to write. + * + * The two formats arrive differently: a PNG comes back base64, while an SVG comes back as percent- + * encoded text. Treating the SVG as base64 produces a file that is the right size and entirely + * corrupt, so the declared encoding is what decides, not the format. + */ +function decodeDataUrl(dataUrl) { + const comma = dataUrl.indexOf(","); + const header = dataUrl.slice(0, comma); + const payload = dataUrl.slice(comma + 1); + + return header.includes(";base64") + ? Buffer.from(payload, "base64") + : Buffer.from(decodeURIComponent(payload), "utf8"); +} + +const server = await serveViewer(); +const port = server.address().port; +const profile = await mkdtemp(join(tmpdir(), "aspirec4-chrome-")); + +const chrome = spawn( + await findChrome(), + [ + "--headless=new", + "--remote-debugging-port=0", + // The container is not privileged, and the page is one this package generated from the + // consumer's own model rather than anything fetched from the network. + "--no-sandbox", + "--disable-dev-shm-usage", + "--hide-scrollbars", + "--window-size=1600,1000", + `--user-data-dir=${profile}`, + `http://127.0.0.1:${port}/`, + ], + { stdio: ["ignore", "ignore", "pipe"] }, +); + +// The chosen debugging port is only discoverable from the browser's own startup banner. +const debugPort = await new Promise((resolve, reject) => { + let banner = ""; + + chrome.stderr.on("data", (chunk) => { + banner += chunk; + + const match = banner.match(/DevTools listening on ws:\/\/127\.0\.0\.1:(\d+)/); + + if (match) resolve(Number(match[1])); + }); + + chrome.on("exit", (code) => reject(new Error(`chromium exited with code ${code}: ${banner}`))); +}); + +let failure = null; + +try { + const socket = new WebSocket(await connect(debugPort)); + + await new Promise((resolve, reject) => { + socket.addEventListener("open", resolve, { once: true }); + socket.addEventListener("error", () => reject(new Error("could not attach to the page")), { once: true }); + }); + + const send = client(socket); + + await send("Runtime.enable"); + + // The hook is published once the nodes are laid out, so its presence is the diagram being ready. + // Polled rather than waited on with an event, because ELK lays out asynchronously after load. + let ready = false; + + for (let attempt = 0; attempt < 600 && !ready; attempt++) { + ready = await evaluate(send, "typeof globalThis.__aspirec4RenderImage === 'function'"); + + if (!ready) await sleep(100); + } + + if (!ready) { + throw new Error("The viewer never finished laying out the diagram."); + } + + for (const format of formats) { + const dataUrl = await evaluate(send, `globalThis.__aspirec4RenderImage(${JSON.stringify(format)})`); + + if (typeof dataUrl !== "string" || !dataUrl.includes(",")) { + throw new Error(`The viewer produced no ${format}.`); + } + + await writeFile(join(OUTPUT, `${baseName}.${format}`), decodeDataUrl(dataUrl)); + } + + socket.close(); +} catch (error) { + failure = error; +} finally { + chrome.kill(); + server.close(); +} + +if (failure) { + console.error(failure.message); + process.exit(1); +} diff --git a/src/src/EntityFrameworkCore/Assets/viewer/app.js b/src/src/EntityFrameworkCore/Assets/viewer/app.js index 4de1614..99171fd 100644 --- a/src/src/EntityFrameworkCore/Assets/viewer/app.js +++ b/src/src/EntityFrameworkCore/Assets/viewer/app.js @@ -65,17 +65,19 @@ function dependentMarker(fk) { * The relationship's name, in both directions. * * A foreign key has a navigation on the dependent and usually an inverse collection on the principal. - * Where the model declares only one, the other is marked "?" rather than hidden — an unnamed - * direction is information. Only when neither is declared does it fall back to the constraint name, - * and then to the columns. + * Edges here are drawn principal -> dependent, so the principal's navigation is named first and the + * arrow in the label agrees with the arrow on the edge. Where the model declares only one end, only + * that one is named: a single arrow says which way it can be travelled, and nothing claims the other + * direction exists. Only when neither is declared does it fall back to the constraint name, and then + * to the columns. */ function relationshipLabel(fk) { - const dependent = fk.navigationName; - const principal = fk.principalNavigationName; + const forward = fk.principalNavigationName; + const reverse = fk.navigationName; - if (dependent && principal) return `${dependent} ⇄ ${principal}`; - if (dependent) return `${dependent} → ?`; - if (principal) return `? → ${principal}`; + if (forward && reverse) return `${forward} ⇄ ${reverse}`; + if (forward) return `${forward} →`; + if (reverse) return `← ${reverse}`; if (fk.constraintName) return fk.constraintName; return (fk.columns ?? []).join(", "); @@ -166,6 +168,93 @@ const columnBadges = (col) => { const isEnumColumn = (col) => col.domainTypeKind === "Enum"; +const COMPLEX_KIND = "ComplexValueObject"; + +/** The property a flattened complex member belongs to: the segment before the first underscore. */ +const complexOwner = (col) => col.name.split("_")[0]; + +/** + * Folds a table's flattened complex value-object columns under the property that owns them. + * + * EF maps a complex value object into its owner's table as one column per member, named + * `{Property}_{Member}`, so a card otherwise shows a run of rows that belong together while saying + * nothing about what they are. The owning prefixes are collected first, because a member whose own + * type is an enum or a nested value object carries that type rather than the enclosing one and would + * not be recognised on its own. + * + * @returns rows in model order: a column row per ordinary column, a group row per complex property. + */ +function rowPlan(table) { + const columns = table.columns ?? []; + const owners = new Set(columns.filter((c) => c.domainTypeKind === COMPLEX_KIND).map(complexOwner)); + const rows = []; + const groups = new Map(); + + for (const col of columns) { + const owner = complexOwner(col); + + if (!col.name.includes("_") || !owners.has(owner)) { + rows.push({ kind: "column", key: col.name, col }); + + continue; + } + + let group = groups.get(owner); + + if (!group) { + group = { kind: "group", key: owner, name: owner, typeName: null, columns: [] }; + + groups.set(owner, group); + rows.push(group); + } + + // The outermost member names the group: a nested value object's own members carry the inner type, + // so the shallowest member is the one that reports the property's own type. + const shallow = !col.name.slice(owner.length + 1).includes("_"); + + if (group.typeName === null && col.domainTypeKind === COMPLEX_KIND && shallow) { + group.typeName = col.domainTypeName; + } + + group.columns.push(col); + } + + for (const group of groups.values()) { + group.typeName ??= group.columns[0]?.domainTypeName ?? ""; + } + + return rows; +} + +/** Whether any table flattens a complex value object, and so has anything to expand. */ +const hasComplexColumns = (tables) => + tables.some((t) => (t.columns ?? []).some((c) => c.domainTypeKind === COMPLEX_KIND)); + +/** The member name shown inside its group, with the owning property's prefix removed. */ +const memberName = (group, col) => col.name.slice(group.name.length + 1); + +/** A group row's type cell: the value object, and when it is closed what it is holding. */ +const groupType = (group, open) => (open ? group.typeName : `${group.typeName} (${group.columns.length})`); + +/** The group keys a card is showing: the reader's own, plus any opened to reveal a search match. */ +const expandedOf = (data) => new Set([...(data.expanded ?? []), ...(data.forced ?? [])]); + +/** + * A row's type cell and the tooltip beside it. + * + * A member of an open group whose domain type is the group's own value object is shown as its database + * type alone: the group row above it already names the value object, and repeating it on every member + * crowds out the one thing those rows are there to say. + * + * @param group the group the row belongs to, or null for a column of the table itself. + */ +function rowType(col, group) { + const own = group && col.domainTypeKind === COMPLEX_KIND && col.domainTypeName === group.typeName; + const shown = own ? { ...col, domainTypeName: null, domainTypeKind: null } : col; + + return { text: columnType(shown), annotation: columnAnnotation(shown) }; +} + const bothShown = () => DOMAIN_TYPE_DISPLAY === "DomainTypeFirst" || DOMAIN_TYPE_DISPLAY === "DatabaseFirst"; @@ -202,7 +291,132 @@ const columnType = (col) => { return t; }; -function EntityNode({ data, selected }) { +/** One ordinary column row, or one member of an opened complex value object. */ +function ColumnRow({ col, name, type, needle, className }) { + return h( + "div", + { + // A table can match on a column the reader cannot see the reason for, so the row that caused + // the hit is marked rather than only the card around it. + className: `col${className}${needle && col.name.toLowerCase().includes(needle) ? " hit" : ""}`, + }, + h( + "span", + { className: "name" }, + h("span", { className: "col-name" }, name), + ...columnBadges(col).map((k) => h("span", { className: `badge ${k}`, key: k }, k.toUpperCase())), + ), + h( + "span", + { + className: "type", + // The database type stays reachable even when the domain type is the headline. + title: !bothShown() && type.annotation ? type.annotation : undefined, + }, + type.text, + ), + ); +} + +/** + * The rows a card draws, with each complex value object folded under a row that opens it. + * + * The group's own row is a button rather than a decoration: a reader following a relationship into a + * table wants the flattened members on demand, not a run of prefixed columns they have to reassemble. + */ +function cardRowElements(data, onToggle) { + const expanded = expandedOf(data); + const elements = []; + + for (const row of rowPlan(data.table)) { + if (row.kind === "column") { + elements.push( + h(ColumnRow, { + key: row.key, + col: row.col, + name: row.col.name, + type: rowType(row.col, null), + needle: data.needle, + className: "", + }), + ); + + continue; + } + + const open = expanded.has(row.key); + + elements.push( + h( + "div", + { key: row.key, className: `col group${open ? " open" : ""}` }, + h( + "span", + { className: "name" }, + h( + "button", + { + type: "button", + className: "chevron", + "aria-expanded": open, + title: `${open ? "Collapse" : "Expand"} ${row.name}`, + onClick: (event) => { + // The card is draggable and selectable; neither should happen on a disclosure. + event.stopPropagation(); + onToggle(row.key); + }, + }, + open ? "▾" : "▸", + ), + h("span", { className: "col-name" }, row.name), + ), + h("span", { className: "type" }, groupType(row, open)), + ), + ); + + if (!open) continue; + + for (const col of row.columns) { + elements.push( + h(ColumnRow, { + key: col.name, + col, + name: memberName(row, col), + type: rowType(col, row), + needle: data.needle, + className: " member", + }), + ); + } + } + + return elements; +} + +function EntityNode({ id, data, selected }) { + const { setNodes } = useReactFlow(); + + /** Opens or closes one group on this card, and re-sizes it to what it now draws. */ + const onToggle = useCallback( + (key) => + setNodes((nodes) => + saveFrom( + fitContexts( + nodes.map((node) => { + if (node.id !== id) return node; + + const expanded = new Set(node.data.expanded ?? []); + + if (!expanded.delete(key)) expanded.add(key); + + return resizeEntity({ ...node, data: { ...node.data, expanded: [...expanded] } }); + }), + ), + ), + ), + [id, setNodes], + ); + return h( "div", { @@ -226,34 +440,7 @@ function EntityNode({ data, selected }) { data.table.schema ? h("span", { className: "schema" }, data.table.schema) : null, ), // "names" mode is the overview: the header alone, so a large schema can be read at a glance. - data.tables === "names" - ? null - : (data.table.columns ?? []).map((col) => - h( - "div", - { - // A table can match on a column the reader cannot see the reason for, so the row - // that caused the hit is marked rather than only the card around it. - className: `col${data.needle && col.name.toLowerCase().includes(data.needle) ? " hit" : ""}`, - key: col.name, - }, - h( - "span", - { className: "name" }, - h("span", { className: "col-name" }, col.name), - ...columnBadges(col).map((k) => h("span", { className: `badge ${k}`, key: k }, k.toUpperCase())), - ), - h( - "span", - { - className: "type", - // The database type stays reachable even when the domain type is the headline. - title: !bothShown() && columnAnnotation(col) ? columnAnnotation(col) : undefined, - }, - columnType(col), - ), - ), - ), + data.tables === "names" ? null : cardRowElements(data, onToggle), h(Handle, { type: "source", position: Position.Bottom, isConnectable: false }), ); } @@ -304,6 +491,11 @@ const BADGE_PADDING = 8; const BADGE_LETTER_SPACING = 0.04; const MEASURE_BUFFER = 3; +// Mirroring index.html: the chevron's box and the indent a grouped member row carries. +const CHEVRON_WIDTH = 14; +const CHEVRON_GAP = 4; +const MEMBER_INDENT = 18; + const textWidth = (text, font) => { if (!text) return 0; @@ -312,7 +504,24 @@ const textWidth = (text, font) => { return measureContext.measureText(text).width; }; -/** The width a table's card needs for every column name, badge and type to fit. */ +/** The width one column row needs, as a name, its badges and its type. */ +function columnRowWidth(col, name, indent, type) { + let row = indent + textWidth(name, FONT_SANS); + + for (const badge of columnBadges(col)) { + const text = badge.toUpperCase(); + row += BADGE_GAP + textWidth(text, FONT_BADGE) + BADGE_PADDING + text.length * 9 * BADGE_LETTER_SPACING; + } + + return row + COLUMN_GAP + textWidth(type, FONT_TYPE); +} + +/** + * The width a table's card needs for every column name, badge and type to fit. + * + * A collapsed group is measured as though it were open, so expanding one never re-widens the card and + * nothing has to be laid out again to accommodate it. + */ function cardWidth(table, tables) { let widest = textWidth(table.name, FONT_HEADER); @@ -320,22 +529,48 @@ function cardWidth(table, tables) { // In names mode only the header is drawn, so only the header has to fit. if (tables !== "names") { - for (const col of table.columns ?? []) { - let row = textWidth(col.name, FONT_SANS); + for (const row of rowPlan(table)) { + if (row.kind === "column") { + widest = Math.max(widest, columnRowWidth(row.col, row.col.name, 0, rowType(row.col, null).text)); - for (const badge of columnBadges(col)) { - const text = badge.toUpperCase(); - row += BADGE_GAP + textWidth(text, FONT_BADGE) + BADGE_PADDING + text.length * 9 * BADGE_LETTER_SPACING; + continue; } - row += COLUMN_GAP + textWidth(columnType(col), FONT_TYPE); - widest = Math.max(widest, row); + // The closed form carries the member count, so it is the wider of the two. + widest = Math.max( + widest, + CHEVRON_WIDTH + + CHEVRON_GAP + + textWidth(row.name, FONT_SANS) + + COLUMN_GAP + + textWidth(groupType(row, false), FONT_TYPE), + ); + + for (const col of row.columns) { + widest = Math.max( + widest, + columnRowWidth(col, memberName(row, col), MEMBER_INDENT, rowType(col, row).text), + ); + } } } return Math.ceil(widest + CARD_PADDING * 2 + ENTITY_BORDER + MEASURE_BUFFER); } +/** How many rows a card draws: a closed group is one row, an open one is itself plus its members. */ +function cardRows(table, tables, expanded) { + if (tables === "names") return 0; + + let rows = 0; + + for (const row of rowPlan(table)) { + rows += row.kind === "column" ? 1 : 1 + (expanded.has(row.key) ? row.columns.length : 0); + } + + return rows; +} + /** * The rendered card's size — measured for the width, fixed per row for the height. * @@ -343,13 +578,11 @@ function cardWidth(table, tables) { * references itself, because the self-loop needs a gutter beside the card. * * @param tables the table display mode: "columns" draws every column, "names" only the header. + * @param expanded the complex value-object groups this card is showing the members of. */ -const cardSize = (table, tables) => ({ +const cardSize = (table, tables, expanded = new Set()) => ({ width: Math.max(ENTITY_MIN_WIDTH, cardWidth(table, tables)), - height: - ENTITY_BORDER + - ENTITY_HEADER_HEIGHT + - (tables === "names" ? 0 : (table.columns?.length ?? 0) * ENTITY_ROW_HEIGHT), + height: ENTITY_BORDER + ENTITY_HEADER_HEIGHT + cardRows(table, tables, expanded) * ENTITY_ROW_HEIGHT, }); const SELF_LOOP_REACH = 280; @@ -419,7 +652,7 @@ const entitySize = (table, selfReferencing, tables) => { * what ELK returns. */ /** The container's own margin around its tables, mirroring the ELK padding above. */ -const CONTEXT_PADDING = { top: 52, right: 28, bottom: 28, left: 28 }; +const CONTEXT_PADDING = { top: 56, right: 32, bottom: 32, left: 32 }; /** * A node's current size. A manual resize sets the node's own width and height, which then wins over @@ -430,6 +663,30 @@ const nodeWidth = (node) => const nodeHeight = (node) => node.height ?? node.measured?.height ?? node.data?.card?.height ?? 0; +/** + * Re-sizes an entity for the groups it is currently showing. + * + * Only the height moves: a card is measured as though every group were open, so opening one never + * changes its width and the arrangement around it stays put. A card the reader has resized by hand + * keeps the size they gave it. + */ +function resizeEntity(node) { + if (node.type !== "entity" || node.height != null) return node; + + // Only the row count changes, so the height is recomputed directly rather than re-measuring every + // name and type through the canvas — this runs for every card on every keystroke of a search. + const rows = cardRows(node.data.table, node.data.tables, expandedOf(node.data)); + const height = ENTITY_BORDER + ENTITY_HEADER_HEIGHT + rows * ENTITY_ROW_HEIGHT; + + if (node.data.card?.height === height && node.style?.height === height) return node; + + return { + ...node, + style: { ...node.style, height }, + data: { ...node.data, card: { ...node.data.card, height } }, + }; +} + /** * Resizes and moves each context container so it wraps its own tables, preserving every table's * absolute position. @@ -541,6 +798,9 @@ function saveLayout(nodes, tables, mode) { entry.height = node.height; } + // Which groups the reader opened, but not the ones a search opened for them. + if (node.data?.expanded?.length > 0) entry.expanded = node.data.expanded; + entities[node.id] = entry; } } @@ -568,6 +828,29 @@ function loadLayout(tables, mode) { } } +/** + * Persists the arrangement using the tables carried by the nodes themselves. + * + * Folding a group changes a card's height, so it has to be saved like a drag or a resize — but it is + * toggled from inside the card, which has no access to the model. Every entity node holds its own + * table and the display mode, which is all the fingerprint needs. + * + * @returns the nodes it was given, so a caller can save and return in one step. + */ +function saveFrom(nodes) { + const entities = nodes.filter((node) => node.type === "entity"); + + if (entities.length > 0) { + saveLayout( + nodes, + entities.map((node) => node.data.table), + entities[0].data.tables, + ); + } + + return nodes; +} + /** Rebuilds the graph from a saved arrangement, dropping anything the model no longer has. */ function restoreLayout(saved, tables, colourOf, mode) { const nodes = []; @@ -592,7 +875,8 @@ function restoreLayout(saved, tables, colourOf, mode) { if (!table || !known.has(id)) continue; - const card = cardSize(table, mode); + const expanded = position.expanded ?? []; + const card = cardSize(table, mode, new Set(expanded)); const manual = position.width != null || position.height != null; const width = manual ? position.width : card.width; const height = manual ? position.height : card.height; @@ -606,7 +890,16 @@ function restoreLayout(saved, tables, colourOf, mode) { // stays un-sized and keeps following its content. ...(manual ? { width, height } : {}), style: { width, height }, - data: { table, colour: colourOf(table.context), match: "", needle: "", card, tables: mode }, + data: { + table, + colour: colourOf(table.context), + match: "", + needle: "", + card, + tables: mode, + expanded, + forced: [], + }, }); } @@ -639,7 +932,7 @@ async function layout(tables, edges, colourOf, mode) { // one row was already closer to that ratio than wrapping would be, and 1.4 produced a // ragged three-plus-one. A target squarer than the viewport is what actually wraps. "elk.aspectRatio": "1.1", - "elk.spacing.nodeNode": "60", + "elk.spacing.nodeNode": "88", }, children: contexts.map((context) => ({ id: `ctx:${context}`, @@ -648,9 +941,23 @@ async function layout(tables, edges, colourOf, mode) { "elk.direction": "DOWN", // Top carries the label that sits on the border line; the other three are even, so the // container reads as a frame around its tables rather than a box they are pushed into. - "elk.padding": "[top=52,left=28,bottom=28,right=28]", - "elk.spacing.nodeNode": "48", - "elk.layered.spacing.nodeNodeBetweenLayers": "76", + "elk.padding": "[top=56,left=32,bottom=32,right=32]", + // The gap between layers carries the relationship labels, which are drawn at the middle + // of an edge over their own background: too little room and a label lands on the card + // below it. The sideways gap only has to separate two cards, so it is smaller. + "elk.spacing.nodeNode": "72", + "elk.layered.spacing.nodeNodeBetweenLayers": "120", + // Tables that no relationship connects form separate components, which ELK lays out one + // by one and then packs — a seam the between-layer spacing never reaches. Left at its + // default of 20 those groups sit almost touching, which reads as one crowded block + // rather than as the unrelated groups they are. + "elk.spacing.componentComponent": "120", + // Edges routed around a card keep clear of it rather than running along its border, and + // parallel edges stay far enough apart to be followed individually. + "elk.spacing.edgeNode": "40", + "elk.layered.spacing.edgeNodeBetweenLayers": "40", + "elk.spacing.edgeEdge": "24", + "elk.layered.spacing.edgeEdgeBetweenLayers": "24", }, children: tables .filter((t) => t.context === context) @@ -694,7 +1001,8 @@ async function layout(tables, edges, colourOf, mode) { parentId: container.id, position: { x: child.x ?? 0, y: child.y ?? 0 }, style: { width: card.width, height: card.height }, - data: { table, colour, match: "", needle: "", card, tables: mode }, + // Complex value objects start folded: a fresh card shows the table, not its interiors. + data: { table, colour, match: "", needle: "", card, tables: mode, expanded: [], forced: [] }, }); } } @@ -834,17 +1142,23 @@ async function save(dataUrl, fileName) { } /** - * Renders the current diagram to an image and downloads it. + * Renders the current diagram to an image and returns it as a data URL. * * The crow's-foot markers are defined in a stand-alone <svg> outside the viewport, so a capture * of the viewport alone resolves every `url(#erd-…)` to nothing and loses the cardinality. A copy * rides along for the duration of the capture. + * + * Separate from {@link exportImage} so the AppHost's image export can render the diagram without + * downloading it: a headless browser has nowhere to put a download, and intercepting one to get at + * the bytes is a great deal of machinery for something the renderer already has in hand. + * + * @returns the data URL, or null when there is nothing laid out to capture. */ -async function exportImage(format, nodes, title) { +async function renderImage(format, nodes, title) { const viewport = document.querySelector(".react-flow__viewport"); const bounds = drawingBounds(nodes); - if (!viewport || !bounds) return false; + if (!viewport || !bounds) return null; const natural = Math.max(bounds.width, bounds.height) + EXPORT_PADDING * 2; const scale = Math.min(1, EXPORT_MAX_SIDE / natural); @@ -872,16 +1186,26 @@ async function exportImage(format, nodes, title) { }, }); - await save(dataUrl, `${(title || "erd").replaceAll(/[^\w.-]+/g, "-").toLowerCase()}.${format}`); - - return true; + return dataUrl; } finally { markers?.remove(); } } +/** Renders the current diagram to an image and downloads it. */ +async function exportImage(format, nodes, title) { + const dataUrl = await renderImage(format, nodes, title); + + if (!dataUrl) return false; + + await save(dataUrl, `${(title || "erd").replaceAll(/[^\w.-]+/g, "-").toLowerCase()}.${format}`); + + return true; +} + function Diagram({ model }) { const tables = useMemo(() => flatten(model), [model]); + const complex = useMemo(() => hasComplexColumns(tables), [tables]); const [nodes, setNodes, onNodesChange] = useNodesState([]); const [edges, setEdges, onEdgesChange] = useEdgesState([]); const [query, setQuery] = useState(""); @@ -963,16 +1287,37 @@ function Diagram({ model }) { const hits = new Set(matches); setNodes((nodes) => - nodes.map((n) => { - // Containers are never dimmed; doing so would wash out the tables inside them. - if (n.type !== "entity") return n; - - const match = !needle ? "" : n.id === current ? "hit current" : hits.has(n.id) ? "hit" : "dimmed"; - - if (n.data.match === match && n.data.needle === needle) return n; + fitContexts( + nodes.map((n) => { + // Containers are never dimmed; doing so would wash out the tables inside them. + if (n.type !== "entity") return n; + + const match = !needle ? "" : n.id === current ? "hit current" : hits.has(n.id) ? "hit" : "dimmed"; + + // A match inside a folded complex value object would otherwise be reported and then not + // shown. The groups opened this way are held apart from the reader's own, so clearing + // the search folds them back rather than leaving the card as the search left it. + const forced = !needle + ? [] + : rowPlan(n.data.table) + .filter( + (row) => + row.kind === "group" && row.columns.some((c) => c.name.toLowerCase().includes(needle)), + ) + .map((row) => row.key); + + if ( + n.data.match === match && + n.data.needle === needle && + n.data.forced?.length === forced.length && + forced.every((key) => n.data.forced.includes(key)) + ) { + return n; + } - return { ...n, data: { ...n.data, match, needle } }; - }), + return resizeEntity({ ...n, data: { ...n.data, match, needle, forced } }); + }), + ), ); // A relationship is only fully in play when both of its ends are, so an edge recedes with @@ -1048,6 +1393,52 @@ function Diagram({ model }) { [nodes], ); + // The hook the AppHost's viewer-fidelity export calls, so an image produced headlessly is the same + // one this toolbar produces. Published only once the nodes are laid out, which is what makes its + // presence the signal that the diagram is ready to capture. + useEffect(() => { + if (nodes.length === 0) return undefined; + + globalThis.__aspirec4RenderImage = (format) => renderImage(format, nodes, document.title); + + return () => { + delete globalThis.__aspirec4RenderImage; + }; + }, [nodes]); + + /** + * Opens or folds every complex value object on every card. + * + * The arrangement is saved straight away: the cards have changed height, so a reload that restored + * the previous one would reopen the diagram with the containers fitted to the wrong sizes. + */ + const groupKeys = useCallback( + (table) => + rowPlan(table) + .filter((row) => row.kind === "group") + .map((row) => row.key), + [], + ); + + const setAllExpanded = useCallback( + (open) => + setNodes((current) => + saveFrom( + fitContexts( + current.map((node) => + node.type === "entity" + ? resizeEntity({ + ...node, + data: { ...node.data, expanded: open ? groupKeys(node.data.table) : [] }, + }) + : node, + ), + ), + ), + ), + [setNodes, groupKeys], + ); + /** A segmented choice over a settings key, shared by the toolbar and the settings panel. */ const segmented = (key, options, label) => h( @@ -1137,6 +1528,36 @@ function Diagram({ model }) { h("span", { className: "sep" }), h("span", { className: "count" }, "View"), segmented("tables", TABLES, "View"), + // Only shown when the model has something to fold, so it is not dead chrome on a diagram + // whose tables are all plain columns. + ...(complex && settings.tables !== "names" + ? [ + h("span", { className: "sep" }), + h("span", { className: "count" }, "Complex"), + h( + "div", + { className: "segmented", role: "group", "aria-label": "Complex value objects" }, + h( + "button", + { + type: "button", + title: "Show the members of every complex value object", + onClick: () => setAllExpanded(true), + }, + "Expand all", + ), + h( + "button", + { + type: "button", + title: "Fold every complex value object back to its property", + onClick: () => setAllExpanded(false), + }, + "Collapse all", + ), + ), + ] + : []), h("span", { className: "sep" }), h("span", { className: "count" }, "Export"), ...["png", "svg"].map((format) => diff --git a/src/src/EntityFrameworkCore/Assets/viewer/index.html b/src/src/EntityFrameworkCore/Assets/viewer/index.html index dc837ce..3574891 100644 --- a/src/src/EntityFrameworkCore/Assets/viewer/index.html +++ b/src/src/EntityFrameworkCore/Assets/viewer/index.html @@ -345,6 +345,41 @@ font-size: 11px; } + /* + * A complex value object is folded under the property that owns it: the group row discloses + * its members, which are indented and set in the muted colour so the card still reads as a + * list of the table's own columns. + */ + .entity .col.group .name { + gap: 4px; + } + + /* Sized for the glyph, not for the text beside it: a 9px triangle reads as a speck. */ + .entity .col .chevron { + flex: none; + width: 14px; + padding: 0; + border: 0; + background: none; + color: var(--muted); + font-size: 11px; + line-height: 1; + text-align: left; + cursor: pointer; + } + + .entity .col .chevron:hover { + color: var(--fg); + } + + .entity .col.member { + padding-left: 30px; + } + + .entity .col.member .col-name { + color: var(--muted); + } + /* Colour separates what a column does: key, reference, uniqueness. */ .badge { flex: none; diff --git a/src/src/EntityFrameworkCore/D2/D2LayoutEngineNames.cs b/src/src/EntityFrameworkCore/D2/D2LayoutEngineNames.cs new file mode 100644 index 0000000..d0bf303 --- /dev/null +++ b/src/src/EntityFrameworkCore/D2/D2LayoutEngineNames.cs @@ -0,0 +1,19 @@ +namespace Aspire.Hosting.AspireC4.EntityFrameworkCore.D2; + +/// Maps onto the names the d2 CLI accepts for --layout. +/// +/// Shared by the sidecar resources and the image exporter so a diagram's exported image is laid out by +/// the same engine as the one being served. +/// +static class D2LayoutEngineNames +{ +#pragma warning disable IDE0072 // Add missing cases + public static string ToEngineName(this D2LayoutEngine engine) => + engine switch + { + D2LayoutEngine.Dagre => "dagre", + D2LayoutEngine.Tala => "tala", + _ => "elk", + }; +#pragma warning restore IDE0072 // Add missing cases +} diff --git a/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs b/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs index f364a38..7acaa85 100644 --- a/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs +++ b/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs @@ -152,7 +152,9 @@ static List BuildEdges(EfModel model, Dictionary pathsBy SourceColumn = foreignKey.Columns[i], TargetTable = targetPath, TargetColumn = foreignKey.PrincipalColumns[i], - Label = EfRelationshipName.Label(foreignKey), + // The edge is attached to the column holding the foreign key, so it runs from + // the dependent and its label reads in that order. + Label = EfRelationshipName.Label(foreignKey, EfRelationshipDirection.DependentToPrincipal), }; // Composite keys and multiple navigations can describe the same column pair. diff --git a/src/src/EntityFrameworkCore/EfModelMetadataReader.cs b/src/src/EntityFrameworkCore/EfModelMetadataReader.cs index 32cdbc4..9c70165 100644 --- a/src/src/EntityFrameworkCore/EfModelMetadataReader.cs +++ b/src/src/EntityFrameworkCore/EfModelMetadataReader.cs @@ -250,8 +250,19 @@ static IEnumerable GetLoadableTypes(Assembly assembly) } } + /// Whether a type is a DbContext the diagram should show. + /// + /// An abstract or open-generic context — the DbContextBase<T> a real context derives from + /// — is never instantiated and owns no tables of its own, so reading it adds an empty node to the + /// diagram beside the context that actually has the model. + /// static bool IsDbContext(Type type) { + if (type.IsAbstract || type.IsGenericTypeDefinition || type.ContainsGenericParameters) + { + return false; + } + try { for (var current = type.BaseType; current is not null; current = current.BaseType) @@ -516,7 +527,8 @@ Dictionary entities var column = (explicitName is null ? null : table.Columns.FirstOrDefault(c => c.PropertyName == explicitName)) ?? table.Columns.FirstOrDefault(c => c.PropertyName == navigation.Name + "Id") - ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id"); + ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id") + ?? SharedPrimaryKeyColumn(table, target); if (column is null) { @@ -525,13 +537,15 @@ Dictionary entities column.IsForeignKey = true; + var isUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique; + table.ForeignKeys.Add( new ForeignKeyShape { PrincipalEntity = target.FullName ?? target.Name, NavigationName = navigation.Name, - PrincipalNavigationName = PrincipalNavigation(target, dependent), - IsUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique, + PrincipalNavigationName = PrincipalNavigation(target, dependent, isUnique), + IsUnique = isUnique, IsRequired = !column.IsNullable, Columns = [column.Name], } @@ -539,12 +553,89 @@ Dictionary entities } } + /// + /// The dependent's own primary key, when that key doubles as the foreign key to the principal. + /// + /// + /// A shared-primary-key one-to-one — RepositoryState.Id being the Asset it describes — + /// declares no <Navigation>Id property, so the usual column lookup finds nothing and the + /// relationship disappears entirely. What identifies it is the dependent having borrowed the + /// principal's identity: the principal's key type is its own identifier, and the dependent is keyed by + /// that same type. A primitive key is deliberately not enough, because every entity keyed by + /// Guid or int would then match every other one. + /// + static ColumnShape? SharedPrimaryKeyColumn(TableShape table, Type principal) + { + var keyColumns = table.Columns.Where(c => c.IsPrimaryKey).ToList(); + + if (keyColumns.Count != 1 || PrimaryKeyType(principal) is not { } principalKeyType) + { + return null; + } + + return + ValueObjectType(principalKeyType) is not null + && IsOwnIdentifier(principal.Name, principalKeyType.Name) + && keyColumns[0].ClrTypeName == principalKeyType.FullName + ? keyColumns[0] + : null; + } + + /// + /// Whether a key type is the entity's own identifier, judged by name: AssetId belongs to + /// Asset — or AssetEntity — and so marks that entity as the owner of the identity + /// rather than a borrower of someone else's. + /// + static bool IsOwnIdentifier(string entityName, string keyTypeName) + { + if (!keyTypeName.EndsWith("Id", StringComparison.Ordinal)) + { + return false; + } + + var stem = keyTypeName[..^"Id".Length]; + var owner = entityName.EndsWith("Entity", StringComparison.Ordinal) + ? entityName[..^"Entity".Length] + : entityName; + + return stem.Length > 0 && string.Equals(stem, owner, StringComparison.Ordinal); + } + + /// The type of an entity's single primary key property, following the same conventions as + /// ; for a composite or unrecognised key. + static Type? PrimaryKeyType(Type entity) + { + List properties = [.. entity.GetProperties(BindingFlags.Public | BindingFlags.Instance)]; + List keyed = [.. properties.Where(p => HasAttribute(p, "Key"))]; + + if (keyed.Count > 0) + { + return keyed.Count == 1 ? keyed[0].PropertyType : null; + } + + return properties + .FirstOrDefault(p => + string.Equals(p.Name, "Id", StringComparison.OrdinalIgnoreCase) + || string.Equals(p.Name, entity.Name + "Id", StringComparison.OrdinalIgnoreCase) + ) + ?.PropertyType; + } + /// /// The principal-side navigation: a collection on the principal whose element is the dependent. /// - static string? PrincipalNavigation(Type principal, Type dependent) + /// The entity the foreign key points at. + /// The entity the foreign key lives on. + /// + /// Whether the foreign key is unique. A one-to-one has no collection to find, so its inverse is a + /// reference to the dependent — which is only safe to read as the inverse when the key says the + /// relationship is one-to-one, otherwise any two entities that point at each other would pair up. + /// + static string? PrincipalNavigation(Type principal, Type dependent, bool isUnique) { - foreach (var property in principal.GetProperties(BindingFlags.Public | BindingFlags.Instance)) + List properties = [.. principal.GetProperties(BindingFlags.Public | BindingFlags.Instance)]; + + foreach (var property in properties) { if (IsCollection(property.PropertyType) && property.PropertyType.GetGenericArguments()[0] == dependent) { @@ -552,7 +643,7 @@ Dictionary entities } } - return null; + return isUnique ? properties.FirstOrDefault(p => p.PropertyType == dependent)?.Name : null; } /// @@ -632,10 +723,39 @@ static HashSet ReadUniqueIndexProperties(Type entity) return null; } + // A framework type is never an entity in someone's model. Any class this reader does not + // recognise as a scalar would otherwise be taken for a navigation and gain a table of its own, + // named after the framework type — and because AddReachableEntities walks a navigation's own + // properties, one unmapped type drags a tree of them into the diagram behind it. + if (IsFrameworkType(type)) + { + return null; + } + // A class that maps to a column (string, byte[], ...) is not a navigation. return !IsScalar(type) ? type : null; } + /// + /// Whether a type belongs to the framework rather than to the model being read. + /// + /// + /// Matched on the namespace root, so a user type is only ever caught by this if it was declared + /// directly in System or Microsoft — which EF would not map as an entity either. + /// + static bool IsFrameworkType(Type type) + { + var @namespace = type.Namespace; + + return @namespace is not null + && ( + @namespace.Equals("System", StringComparison.Ordinal) + || @namespace.StartsWith("System.", StringComparison.Ordinal) + || @namespace.Equals("Microsoft", StringComparison.Ordinal) + || @namespace.StartsWith("Microsoft.", StringComparison.Ordinal) + ); + } + static bool IsCollection(Type type) => type.IsGenericType && CollectionFullNames.Contains(type.GetGenericTypeDefinition().FullName ?? string.Empty); @@ -805,6 +925,15 @@ static string ResolveStoreType(Type type) "System.TimeSpan" => "time", "System.DateOnly" => "date", "System.TimeOnly" => "time", + // A JSON document is a column, not a table. Without these it resolves to unknown, and an + // unknown class is taken for a navigation — which is how a property such as + // `JsonDocument Payload` used to invent an entity named after the framework type. + "System.Text.Json.JsonDocument" + or "System.Text.Json.JsonElement" + or "System.Text.Json.Nodes.JsonNode" + or "System.Text.Json.Nodes.JsonObject" + or "System.Text.Json.Nodes.JsonArray" + or "System.Text.Json.Nodes.JsonValue" => "json", _ => UnknownStoreType, }; } diff --git a/src/src/EntityFrameworkCore/EfRelationshipDirection.cs b/src/src/EntityFrameworkCore/EfRelationshipDirection.cs new file mode 100644 index 0000000..278b2f6 --- /dev/null +++ b/src/src/EntityFrameworkCore/EfRelationshipDirection.cs @@ -0,0 +1,19 @@ +namespace Aspire.Hosting.AspireC4.EntityFrameworkCore; + +/// +/// Which end of a relationship a renderer draws the edge from. +/// +/// +/// The renderers disagree, and legitimately so: d2 attaches an edge to the column that holds the +/// foreign key, so it runs from the dependent, while the interactive viewer and Mermaid run from the +/// principal so the line flows toward the many end. A relationship label names a direction of travel, +/// so it only reads correctly when it is ordered to match the edge it sits on. +/// +enum EfRelationshipDirection +{ + /// The edge starts at the table holding the foreign key. + DependentToPrincipal, + + /// The edge starts at the table the foreign key points at. + PrincipalToDependent, +} diff --git a/src/src/EntityFrameworkCore/EfRelationshipName.cs b/src/src/EntityFrameworkCore/EfRelationshipName.cs index 7c805d0..479f57c 100644 --- a/src/src/EntityFrameworkCore/EfRelationshipName.cs +++ b/src/src/EntityFrameworkCore/EfRelationshipName.cs @@ -7,33 +7,38 @@ namespace Aspire.Hosting.AspireC4.EntityFrameworkCore; /// /// /// Both ends are named, because a relationship reads in both directions: a foreign key has a -/// navigation on the dependent and usually an inverse collection on the principal. Where the model -/// declares only one, the other is marked ? rather than hidden — an unnamed direction is -/// information. Only when neither is declared does it fall back to the constraint name, and then to -/// the columns. +/// navigation on the dependent and usually an inverse collection on the principal. The declared end +/// nearest the start of the edge is named first, so the arrow in the label and the arrow on the edge +/// agree. Where the model declares only one end, only that one is named — a single arrow says which +/// way it can be travelled, and nothing claims the other direction exists. Only when neither end is +/// declared does it fall back to the constraint name, and then to the columns. /// static class EfRelationshipName { /// The label a renderer shows on a relationship. - public static string Label(EfForeignKey foreignKey) + /// The relationship to name. + /// Which end the renderer draws the edge from. + public static string Label(EfForeignKey foreignKey, EfRelationshipDirection direction) { ArgumentNullException.ThrowIfNull(foreignKey); - var dependent = foreignKey.NavigationName; - var principal = foreignKey.PrincipalNavigationName; + var (forward, reverse) = + direction == EfRelationshipDirection.DependentToPrincipal + ? (foreignKey.NavigationName, foreignKey.PrincipalNavigationName) + : (foreignKey.PrincipalNavigationName, foreignKey.NavigationName); - if (!string.IsNullOrEmpty(dependent) && !string.IsNullOrEmpty(principal)) + if (!string.IsNullOrEmpty(forward) && !string.IsNullOrEmpty(reverse)) { - return $"{dependent} ⇄ {principal}"; + return $"{forward} ⇄ {reverse}"; } - if (!string.IsNullOrEmpty(dependent)) + if (!string.IsNullOrEmpty(forward)) { - return $"{dependent} → ?"; + return $"{forward} →"; } - if (!string.IsNullOrEmpty(principal)) - return $"? → {principal}"; + if (!string.IsNullOrEmpty(reverse)) + return $"← {reverse}"; // If neither end is named, fall back to the constraint name, and then to the columns. return !string.IsNullOrEmpty(foreignKey.ConstraintName) diff --git a/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj b/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj index 749eafc..2161b83 100644 --- a/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj +++ b/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj @@ -34,6 +34,8 @@ + +