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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 47 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,25 @@ generates live [LikeC4](https://likec4.dev) architecture diagrams from the Aspir
- The `AspireC4.Hosting` library (the Aspire integration).
- An incremental Roslyn source generator (`AspireC4.SourceGenerators`) that validates registry constants and
`.c4` DSL files against `.WithTag()`, `.WithKind()`, `.WithLikeC4Group()`, and `.WithMetadata()` call sites.
- An optional Entity Framework Core ER diagram: the `AspireC4.Hosting.EntityFrameworkCore` AppHost library,
the analyzer-only `AspireC4.EntityFrameworkCore` package and the `AspireC4.EntityFrameworkCore.ModelDump`
build-time tool. It is **additive** — `WithEntityFrameworkDiagram()` extends the builder `AddAspireC4()`
returns, so consumers run the architecture diagram alone or both diagrams, never the ER diagram alone.
- A `TestAppHost` sample AppHost and a TypeScript AppHost sample.

### Packages and target frameworks

| Package | Project | Target framework | Shipped as |
|---|---|---|---|
| `AspireC4.Hosting` | `src/src/AspireC4/` | `net10.0` | `lib/net10.0/` + `analyzers/dotnet/cs/` + `build/` |
| `AspireC4.Hosting.EntityFrameworkCore` | `src/src/EntityFrameworkCore/` | `net10.0` | `lib/net10.0/` |
| `AspireC4.EntityFrameworkCore` | `src/src/EntityFrameworkCore.Analyzers/` | `netstandard2.0` | `analyzers/dotnet/cs/` only (no runtime assembly) |
| `AspireC4.EntityFrameworkCore.ModelDump` | `src/src/EntityFrameworkCore.ModelDump/` | `net10.0` | `tools/` + `build/` |

AppHosts therefore target `net10.0`. `src/Directory.Build.props` owns the framework; the two Roslyn
projects override it to `netstandard2.0`. The packed content is pinned to `lib/net10.0/...` in
`.config/purview-build.json`, so a framework change has to update that manifest too.

### Layout

| Path | Purpose |
Expand Down Expand Up @@ -44,6 +61,15 @@ one about its own package, and update it when that package's public API or setup
link the root `README.md` into a project with `Link="Sdk/README.md"`, which would override it. Use
absolute URLs in package READMEs, because relative links do not resolve on nuget.org.

### Documentation screenshots

Screenshots embedded in the root `README.md`, the wiki pages under `docs/wiki/` and the package READMEs
live in `docs/images/screenshots/`; its own `README.md` records provenance, consumers and how to refresh
them. Use a relative path from the root README, and absolute `raw.githubusercontent.com` URLs from
`docs/wiki/` (published from a separate repository) and from package READMEs (nuget.org). Skills under
`skills/` install on their own, so they never embed these files — name the diagram's export folder
(`./.aspirec4/images/`) in prose instead.

## Toolchain

| Tool | Purpose | Version source |
Expand Down Expand Up @@ -122,8 +148,9 @@ just erd-svg <input> # Render an emitted Mermaid .mmd to SVG in a one-shot
```

`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.
`dotnet run --project src/src/TestAppHost`. Requires `bunx playwright install chromium` once. The checks
live in `scripts/erd-viewer-check.mts` and `scripts/erd-vendor.mts`; read them, and the viewer under
`src/src/EntityFrameworkCore/Assets/viewer/`, before changing either.

### Other

Expand Down Expand Up @@ -290,8 +317,9 @@ headline.

## LikeC4 DSL work

When writing or validating `.c4`/`.likec4` files, load `.agents/skills/likec4-dsl/SKILL.md` and its
`references/*.md`. Key contracts:
When writing or validating `.c4`/`.likec4` files, load the `likec4-dsl` skill
(`.agents/skills/likec4-dsl/SKILL.md` plus its `references/*.md`) — install it first if it is missing, since
`.agents/skills/` is gitignored. Key contracts:

- Validate with `likec4 validate` (never `check`/`lint`/`build`), prefer
`likec4 validate --json --no-layout --file <edited-file> <project-dir>`.
Expand All @@ -305,23 +333,25 @@ When writing or validating `.c4`/`.likec4` files, load `.agents/skills/likec4-ds
(`.github/workflows/release.yml`, delegating to the `purview-dev/build` reusable `purview-release.yml` with
`release-mode: NuGet`) reads and validates it, builds, tests, packs, builds release notes from conventional
commits, and creates a GitHub Release with the `.nupkg`/`.snupkg`. It does **not** push to nuget.org.
- `.github/skills/release/SKILL.md` reflects the current pipeline correctly — keep it in sync when the release
process changes. Prefer `just pipeline-release` / `pipeline-local-release`.
- [Release Flow](docs/wiki/Release-Flow.md) and `.config/purview-build.json` describe the current pipeline —
keep both in sync when the release process changes. Prefer `just pipeline-release` / `pipeline-local-release`.
- Roslyn diagnostics (`ASPIREC4001`–`ASPIREC4007`) are tracked in
`src/src/SourceGenerators/AnalyzerReleases.Shipped.md` / `AnalyzerReleases.Unshipped.md`. Move unshipped rows into
a new `## Release <version>` shipped section when cutting a release that adds, removes, or changes a rule. See
[Release Flow](docs/wiki/Release-Flow.md) for details.

## Skills

Relevant bundled skills in `.agents/skills/`:
Skills installed from other repositories live in `.agents/skills/` (gitignored); `skills-lock.json`
records what is installed. The families:

- `likec4-dsl` — LikeC4 DSL/CLI work.
- `project-placement-defaults`, `sdk-configuration-reference`, `sdk-project-behavior-and-detection` —
Purview.BuildSdk behaviour and configuration.
- `source-generator-codewriter-modernization`, `source-generator-testing`, `tunit-test-authoring` —
Roslyn generator work and tests.
- `telemetry-sourcegenerator-*` — Purview.Telemetry.SourceGenerator usage (library telemetry).
- `purview-architecture*`, `purview-engineering-principles`, `purview-testing-conventions` — architecture
and test conventions.
- `purview-buildsdk-*` — Purview.BuildSdk behaviour and configuration.
- `purview-containers-*` — the Purview.Containers packages this library consumes.
- `purview-sourcegenerator-*` — Roslyn generator authoring, packaging and tests.
- `purview-telemetry*` — Purview.Telemetry.SourceGenerator usage (library telemetry).
- `purview-persistence` — the EF Core conventions the ER diagram is drawn from.
- Agents and prompts live in `.agents/agents/` and `.agents/prompts/`.

## Agent skills
Expand All @@ -337,8 +367,8 @@ own skills are never installed into it - that would leave two copies to drift ap
their authored path, `skills/<name>/SKILL.md`.

`.github/skills/` is a third, separate place: skills about working *in* this repository, which would
be meaningless to a consumer who installed the published set. `release` and `erd-viewer` live there.
A skill that tells you how to run this repo's own tooling belongs in `.github/skills/`, never in
be meaningless to a consumer who installed the published set. 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.

Expand All @@ -348,9 +378,10 @@ npx skills add purview-dev/aspirec4

| Skill | Answers |
| -- | -- |
| `skills/purview-aspirec4-quickstart/` | installing, `AddAspireC4`, what happens on startup, Docker sidecar versus local CLI |
| `skills/purview-aspirec4-quickstart/` | installing, `AddAspireC4`, what happens on startup, Docker sidecar versus local CLI, and when to add the ER diagram as well |
| `skills/purview-aspirec4-configuration/` | every `AspireC4DiagramOptions` property and its fluent method |
| `skills/purview-aspirec4-resources/` | `WithLikeC4Details`, `WithLikeC4Reference`, `WithLikeC4Group`, and exclusion |
| `skills/purview-aspirec4-entityframework/` | `WithEntityFrameworkDiagram`, the three model-discovery sources, renderers, domain types, and ER image export |
| `skills/purview-aspirec4-validation/` | the `[LikeC4Registry]` class, severity levels, and the `ASPIREC4xxx` diagnostics |

Every skill carries the `purview-aspirec4` prefix. Skills install into one flat directory per agent,
Expand Down
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,14 @@ config.Item("AppHost:BrowserToken").Returns("value");
|---|---|
| `AspireC4.UnitTests` | `LikeC4ModelBuilder`, `LikeC4DslGenerator`, annotations, options — no Docker required |
| `AspireC4.IntegrationTests` | Full Aspire lifecycle: container startup, file generation, endpoint availability |
| `EntityFrameworkCore.UnitTests` | d2 model builder, d2 DSL generator and descriptor loader — no Docker required |
| `EntityFrameworkCore.Analyzers.UnitTests` | EF model generator, plus the generator→assembly→AppHost round-trip |
| `SourceGenerators.UnitTests` | The registry/DSL strict-validation generator |
| `Repository.UnitTests` | Repository-level rules, including the authored skills in `skills/` |

Every project targets `net10.0` except the two Roslyn components (`SourceGenerators` and
`EntityFrameworkCore.Analyzers`), which target `netstandard2.0`. The framework is set once in
`src/Directory.Build.props`, which is also where the `Aspire.Hosting.AspireC4` namespace prefix lives.

Integration tests require Docker to be running. They pull `ghcr.io/likec4/likec4` on first run.

Expand Down
60 changes: 55 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,40 @@

Each package ships its own README on NuGet; this document is the complete reference.

### Use one diagram or both

`AspireC4.Hosting` is the **base** package: it is what registers AspireC4, generates the LikeC4
architecture diagram and owns the dashboard integration. Everything else hangs off it.

- **Architecture only** (the common case): install `AspireC4.Hosting` and call `AddAspireC4()`.
- **Architecture and ER diagram**: additionally install `AspireC4.Hosting.EntityFrameworkCore` and call
`.WithEntityFrameworkDiagram()` on the builder `AddAspireC4()` returns. `WithEntityFrameworkDiagram()`
is an extension on `IResourceBuilder<AspireC4Resource>`, so the architecture diagram is always present
— the ER diagram is additive, never a replacement.
- **ER diagram at full fidelity**: optionally add `AspireC4.EntityFrameworkCore` (to the project that
declares the `DbContext`) and/or `AspireC4.EntityFrameworkCore.ModelDump` (to the project that owns
the EF Core provider). Both are opt-in by package reference alone.

The same split applies to dependencies: the ER diagram needs the projects that own your `DbContext`
types to be registered with `AddProject<Projects.X>(...)`.

### Target frameworks

| Package | Target framework | Shipped as |
| --- | --- | --- |
| `AspireC4.Hosting` | `net10.0` | `lib/net10.0/` library |
| `AspireC4.Hosting.EntityFrameworkCore` | `net10.0` | `lib/net10.0/` library |
| `AspireC4.EntityFrameworkCore` | `netstandard2.0` | `analyzers/dotnet/cs/` — analyzer-only, no runtime assembly |
| `AspireC4.EntityFrameworkCore.ModelDump` | `net10.0` | `tools/` — a build-time tool invoked by MSBuild |

The AppHost consumes the two libraries, so an AppHost must target **`net10.0`**. The analyzer package is
`netstandard2.0` so it loads into any compiler, and it adds no assembly to your output; the model dump is
a `net10.0` tool run by the build, so the build machine needs a .NET 10 runtime.

## Prerequisites

- **.NET 8 or later**.
- **.NET 10 SDK or later.** Every shipping package targets `net10.0`, and an Aspire 13.5 AppHost
targets `net10.0` too.
- **Aspire 13.5.3 or later**. Aspire AppHost projects must reference both the AppHost SDK and
`Aspire.Hosting.AppHost`.
- **Docker** is used by default to run the LikeC4 sidecar container.
Expand Down Expand Up @@ -63,6 +94,20 @@ This writes `./.aspirec4/likec4/model.gen.c4`, starts the LikeC4 server, and ref
> (`./likec4/gen/`, `./erd/gen/`) and the flat `aspirec4` / `aspirec4-er` names. See
> [Upgrading from before 13.6](#upgrading-from-before-136).

## Screenshots

Both are captured from the sample AppHost in this repository (`src/src/TestAppHost`) and stored in
[`docs/images/screenshots/`](docs/images/screenshots/), so the links below stay valid however often the
diagrams are regenerated. Run `dotnet run --project src/src/TestAppHost` to refresh them.

| Architecture diagram (`AddAspireC4()`) | ER diagram (`WithEntityFrameworkDiagram()`) |
| --- | --- |
| ![AspireC4 architecture diagram of the sample AppHost: a Node app referencing Redis Commander, local Redis and Postgres in a local dev group, PgWeb, Azure Redis and Azure Postgres, with labelled relationships](docs/images/screenshots/architecture-diagram.png) | ![AspireC4 interactive ER diagram of the sample AppHost: five DbContext groups of tables with primary and foreign key badges and crow's-foot relationship edges](docs/images/screenshots/entity-framework-er-diagram.png) |

Every diagram also exports its views on startup, to `./.aspirec4/images/` beside the AppHost — see
[Export the views as images](#export-the-views-as-images). Those exported files are the simplest way to
add your own screenshots to a pull request, a wiki or a design document.

## Configuration

Configure the diagram through `AspireC4DiagramOptions`:
Expand Down Expand Up @@ -268,11 +313,16 @@ Only tags, links, metadata, relationships and nested elements are applied — Li
nothing else, so your project stays the single source of each element's title, technology, description and
icon. See [Generated Output](docs/wiki/Generated-Output.md) for the details.

## Entity Framework Core ER diagrams (d2)
## Entity Framework Core ER diagrams

This is an **optional second diagram** on top of the architecture one: `AddAspireC4()` is always required,
and `.WithEntityFrameworkDiagram()` adds the ER diagram to it. Install nothing else and you still get the
architecture diagram; install this only where you want the schema view too.

`AspireC4.Hosting.EntityFrameworkCore` adds a second, complementary diagram: a live
[d2](https://d2lang.com) `sql_table` ER diagram generated from your Entity Framework Core `DbContext`
types, hosted alongside the architecture diagram and linked from it.
`AspireC4.Hosting.EntityFrameworkCore` adds a live ER diagram generated from your Entity Framework Core
`DbContext` types, hosted alongside the architecture diagram and linked from it. The default `Interactive`
renderer draws a browser viewer; `Mermaid`, `Dbml` and `D2` emit text formats instead (see
[Renderers](#renderers)).

The AppHost package is all that is required. `WithEntityFrameworkDiagram()` finds every associated
`DbContext` automatically — reading a build-time dump or a source-generated descriptor where a project
Expand Down
39 changes: 39 additions & 0 deletions docs/images/screenshots/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Screenshots

The images the READMEs and wiki pages embed. They live here — not in the sample's generated output —
so a documentation link never breaks when a diagram is regenerated.

| File | Shows | Used by |
| --- | --- | --- |
| `architecture-diagram.png` | the LikeC4 architecture diagram generated by `AddAspireC4()` for the sample AppHost, with a group, relationships and per-resource technologies | root `README.md`, `docs/wiki/Home.md`, `src/src/AspireC4/README.md` |
| `entity-framework-er-diagram.png` | the interactive ER diagram from `WithEntityFrameworkDiagram()`, one group per `DbContext`, key badges and relationship edges | root `README.md`, `docs/wiki/Home.md`, `docs/wiki/Entity-Framework-Diagrams.md`, `src/src/EntityFrameworkCore/README.md` |

## Refreshing them

Both are captured from the sample AppHost at `src/src/TestAppHost`:

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

That run exports the architecture view as one PNG per view (`architecture-index.png`, …) and the ER diagram
as `schema.svg` / `schema.png`, which is the d2 render. The image used here is the **interactive viewer**
instead: capture it with the viewer's own **Save as PNG** button, or turn on `UseViewerFidelityExport` to
have the AppHost produce the identical file. Copy whichever you want over the file here, keeping the name
above so no documentation link has to change.

If a file has to be renamed, update every reference. The paths appear in:

- `README.md`
- `docs/wiki/Home.md`
- `docs/wiki/Entity-Framework-Diagrams.md`
- `src/src/AspireC4/README.md`
- `src/src/EntityFrameworkCore/README.md`

## Rules

- **Relative links** from the root `README.md` (`docs/images/screenshots/<file>`).
- **Absolute `raw.githubusercontent.com` URLs** from `docs/wiki/*.md`, because the wiki is published from a
separate repository, and from package READMEs, because relative links do not resolve on nuget.org.
- Skills under `skills/` are installed on their own, so they never embed these files — name the export
folder (`./.aspirec4/images/`) in prose instead.
Binary file added docs/images/screenshots/architecture-diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 8 additions & 0 deletions docs/wiki/Contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,10 @@ Fix: Correct HMR port fallback on Windows.

All tests in this repository **must use [TUnit](https://github.com/thomhurst/TUnit)**. Do not use xUnit, NUnit, or MSTest. Test projects declare just `<Project Sdk="Microsoft.NET.Sdk" />`; the SDK (Purview.BuildSdk) wires TUnit, TUnit.Mocks, and Bogus into them automatically.

Every project targets `net10.0` except the two Roslyn components (`SourceGenerators` and
`EntityFrameworkCore.Analyzers`), which target `netstandard2.0`. The framework is set once in
`src/Directory.Build.props`.

```csharp
[Test]
public async Task Something_Should_DoX()
Expand All @@ -173,6 +177,10 @@ Mocking uses TUnit.Mocks (`.Returns(...)` API); NSubstitute is not referenced.
|---|---|
| `AspireC4.UnitTests` | `LikeC4ModelBuilder`, `LikeC4DslGenerator`, annotations, options — no Docker required |
| `AspireC4.IntegrationTests` | Full Aspire lifecycle: container startup, file generation, endpoint availability |
| `EntityFrameworkCore.UnitTests` | d2 model builder, d2 DSL generator and descriptor loader — no Docker required |
| `EntityFrameworkCore.Analyzers.UnitTests` | EF model generator, plus the generator→assembly→AppHost round-trip |
| `SourceGenerators.UnitTests` | The registry/DSL strict-validation generator |
| `Repository.UnitTests` | Repository-level rules, including the authored skills in `skills/` |

Integration tests require Docker to be running. They pull `ghcr.io/likec4/likec4` on first run.

Expand Down
1 change: 1 addition & 0 deletions docs/wiki/Dashboard-Integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,4 +57,5 @@ HMR keeps the diagram up to date in the browser as the file regenerates. The HMR
## Next pages

- [Generated Output](Generated-Output.md)
- [Entity Framework Core ER Diagrams](Entity-Framework-Diagrams.md)
- [Configuration](Configuration.md)
Loading
Loading