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
2 changes: 1 addition & 1 deletion docs/decisions/0006-local-path-check.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ and the dist test suite, so the script and the tests cannot drift apart.
### 4. Cache and dependency directories must sit on an absolute path

*(Amendment, 2026-11-09.)* The `.cache`/`node_modules` rule originally matched those segments anywhere.
Aggregated documentation legitimately names a location relative to the reader's own project — astroc4
Aggregated documentation legitimately names a location relative to the reader's own project — AstroC4
documents its cache as `node_modules/.cache/astroc4` — and that is content, not a build-machine path.
The rule now requires an absolute path (a drive prefix or a root `/`) before the segment, so a real
leak such as `/home/runner/work/…/node_modules/…` or `D:\build\node_modules\…` is still caught while
Expand Down
6 changes: 3 additions & 3 deletions docs/decisions/0012-npm-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ NuGet id, every version came from the NuGet flat-container index and its search
the install panel offered .NET tooling, and `/releases/` listed NuGet rows. `install`
distinguished a plain package from an MSBuild SDK and a .NET tool.

Astroc4 is published to npm, not NuGet. Before this decision its catalogue record had to
AstroC4 is published to npm, not NuGet. Before this decision its catalogue record had to
declare no package at all: the project page rendered no install panel, `/releases/` never
listed it, and the browser's live version check (ADR 0008) had nothing to check. That is
not a property of astroc4 — the product family now includes a TypeScript package consumed
not a property of AstroC4 — the product family now includes a TypeScript package consumed
by a JavaScript build, and the catalogue has to say so without pretending it is NuGet.

The two registries agree on the part that matters: both return a list of published
Expand Down Expand Up @@ -71,7 +71,7 @@ comparable and must not be presented as if they were.
- The release cache schema moves to version 3 and carries `npmPackages`; the committed
fixtures are regenerated by `just refresh-fixtures`, and the offline fallback keeps
working.
- Astroc4 declares `@purview-dev/astroc4` with `registry: npm`, so it now has an install
- AstroC4 declares `@purview-dev/astroc4` with `registry: npm`, so it now has an install
panel, a row on `/releases/`, a package link on its project page, and a live version
check — with `status: preview`, because npm has published prereleases only.
- `registry` is vocabulary: adding a third registry (Maven, crates.io) is another
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
Three gaps showed up as more repositories reorganised their documentation for the portal:

1. **Diagrams had no good form.** GitHub renders Mermaid but shows LikeC4 as source; the portal renders
LikeC4 (through astroc4) and Mermaid. Repositories fell back to ASCII art (`pm-skills`' "The loop",
LikeC4 (through AstroC4) and Mermaid. Repositories fell back to ASCII art (`pm-skills`' "The loop",
the engineering playbook's architecture sketches) or to Mermaid source inside a ```` ```text ````
fence, which neither side draws. A ```` ```likec4 ```` fence in a mirrored page renders here but is
unreadable on GitHub.
Expand All @@ -35,7 +35,7 @@ Three gaps showed up as more repositories reorganised their documentation for th
GitHub hides the comments. The docs sync (`src/lib/docs/diagrams.ts`) replaces the whole block with
a ```` ```likec4 ```` fence whose body is the `.c4` file, read from the repository at the channel's
ref, so the portal shows only the LikeC4 view. The model is one self-contained file per diagram,
because astroc4 compiles a fence on its own. A block whose model is missing or lacks the view keeps
because AstroC4 compiles a fence on its own. A block whose model is missing or lacks the view keeps
its Mermaid and the sync logs why: an upstream mistake costs fidelity, never the page or the build.
Markers inside code fences are ignored.
2. **`_redirects.yml` in the docs root.** A repository records its own moves as `previous: current`
Expand Down
14 changes: 7 additions & 7 deletions src/astro.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -129,14 +129,14 @@ export default defineConfig({
},
compressHTML: true,
markdown: {
// Astro 7.4 made Sätteri the default processor. Astroc4's ```likec4 fence
// Astro 7.4 made Sätteri the default processor. AstroC4's ```likec4 fence
// transform is a Sätteri mdast plugin appended to this processor, and the
// Mermaid bridge had to move with it (see config/satteri-mermaid.ts).
processor: satteri({ mdastPlugins: [mermaidFences] }),
},
integrations: [
// Two JSX renderers are in play: Preact for the site's own islands, React
// for astroc4's LikeC4 islands. Without include/exclude each integration
// for AstroC4's LikeC4 islands. Without include/exclude each integration
// claims every .tsx file and Astro warns that behaviour is undefined.
preact({ exclude: ['**/node_modules/**'] }),
react({ include: ['**/node_modules/**'] }),
Expand Down Expand Up @@ -170,7 +170,7 @@ export default defineConfig({
expressiveCode: {
themes: ['starlight-light', 'starlight-dark'],
// Languages Shiki does not bundle, which the mirrored documentation
// uses anyway (see config/expressive-code-languages.ts). astroc4 appends
// uses anyway (see config/expressive-code-languages.ts). AstroC4 appends
// its LikeC4 grammar to this list rather than replacing it.
shiki: { langs: [...siteLanguages] },
styleOverrides: {
Expand Down Expand Up @@ -198,7 +198,7 @@ export default defineConfig({
Sidebar: './src/components/starlight/Sidebar.astro',
},
plugins: [
// The live astroc4 demo (src/pages/examples/astroc4.mdx) is the site
// The live AstroC4 demo (src/pages/examples/astroc4.mdx) is the site
// dogfooding the plugin it catalogues: real fences and real views.
//
// This is the Starlight entry point, so it belongs in `plugins` — the
Expand All @@ -211,7 +211,7 @@ export default defineConfig({
// Markdown (see skills/docs-aggregation-rules). Those pages were
// written for GitHub or mkdocs, so a ```likec4 fence there is often a
// partial snippet rather than a diagram: relax validation for the
// collection so one cannot fail this site's build — astroc4 warns and
// collection so one cannot fail this site's build — AstroC4 warns and
// leaves the fence as a highlighted code block. Pages the site authors
// are not in the collection, so they keep strict validation.
validation: { collections: ['docs'] },
Expand Down Expand Up @@ -296,7 +296,7 @@ export default defineConfig({
}),
// MDX must come after Starlight: Starlight registers
// astro-expressive-code, and the MDX integration has to see it to
// highlight code blocks on .mdx pages (the live astroc4 example).
// highlight code blocks on .mdx pages (the live AstroC4 example).
mdx(),
],
vite: {
Expand All @@ -306,7 +306,7 @@ export default defineConfig({
// and the React runtime means a cold dev start pre-bundles them instead
// of serving them raw and producing "504 Outdated Optimize Dep".
//
// `react/compiler-runtime` is deliberately absent: astroc4 1.0.0-prerelease.5
// `react/compiler-runtime` is deliberately absent: AstroC4 1.0.0-prerelease.5
// adds it to this list itself (only when the site has not), which is what
// keeps the LikeC4 islands hydrating in `astro dev`.
include: [
Expand Down
2 changes: 1 addition & 1 deletion src/config/expressive-code-languages.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/**
* Languages the site registers with Expressive Code itself, alongside the
* LikeC4 grammar astroc4 contributes.
* LikeC4 grammar AstroC4 contributes.
*
* `gitignore` exists because the aggregated documentation mirror contains
* `.gitignore` snippets — product repositories fence them as `gitignore` — and
Expand Down
2 changes: 1 addition & 1 deletion src/config/satteri-mermaid.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import { defineMdastPlugin } from 'satteri';
* deliberate — the output is exactly the element the Mermaid runtime expects,
* and it does not depend on the converter honouring `data.hName`.
*
* `markdown.processor` is the site's own; astroc4 appends its ```likec4 fence
* `markdown.processor` is the site's own; AstroC4 appends its ```likec4 fence
* transform to whatever processor the site registered, so the two coexist.
*/
function escapeHtml(value: string): string {
Expand Down
4 changes: 2 additions & 2 deletions src/fixtures/manifests/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@
"record": {
"$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts",
"id": "astroc4",
"name": "Astroc4",
"name": "AstroC4",
"shortDescription": "Interactive LikeC4 architecture diagrams for Astro and Starlight, with fences and syntax highlighting.",
"description": "A Starlight plugin and a plain-Astro integration that put LikeC4 architecture diagrams inside an Astro site. A ```likec4 fence in an .mdx page becomes a laid-out, interactive diagram at build time, an empty fence or <LikeC4View> renders a view of the site's own .c4 model, and Expressive Code gains LikeC4 syntax highlighting derived from the language's Langium grammar rather than a hand-maintained TextMate file. The Starlight entry point also injects the component UI strings through Starlight's i18n; the plain-Astro entry point supplies the same compiler and fence transform without Starlight. The grammar is resolved while Astro loads its configuration, cached per repo@ref, and can be pinned, run offline from a bundled snapshot, or allowed to degrade to a warning, so a docs build is as reproducible as the package versions beside it.",
"origin": "Documentation about a system drifts from the system as soon as the diagram is a picture that someone has to redraw. LikeC4 keeps the diagram as a model in the repository, but a docs site that embeds it still had to wire the Vite plugin, write a transform for fences, and maintain a community TextMate grammar that fell behind every upstream release. Doing that once in a plugin, and deriving the grammar from the language definition itself, turned three per-site chores into one dependency and made the highlighting follow LikeC4 instead of being updated after it.",
Expand Down Expand Up @@ -276,7 +276,7 @@
"code": "// astro.config.mjs\nimport { defineConfig } from 'astro/config';\nimport mdx from '@astrojs/mdx';\nimport expressiveCode from 'astro-expressive-code';\nimport astroc4 from '@purview-dev/astroc4/integration';\n\nexport default defineConfig({\n integrations: [astroc4(), expressiveCode(), mdx()],\n});\n",
"language": "js",
"outcome": "The same <LikeC4View> component and ```likec4 fences work without Starlight: the integration compiles the site's .c4 model, appends the fence transform to the Markdown processor, and pre-bundles what the React island needs. The site keeps the parts that are its own decision — @astrojs/mdx and, when it wants ```c4 highlighting, Expressive Code with an ec.config.mjs that registers likec4Language.",
"evidence": "Both entry points call the same likec4Integration(): the plain-Astro example in the repository builds with astro check and astro build, and its dev server is driven in a browser to prove the island hydrates. @astrojs/react is the one integration astroc4 adds itself when the site has not — the islands are client:only=\"react\" — and React is not added twice when the site already configures it. What a plain site gives up is documented: Astro.locals.t is Starlight's, so the components render English, and the highlighting option exists only on the Starlight plugin."
"evidence": "Both entry points call the same likec4Integration(): the plain-Astro example in the repository builds with astro check and astro build, and its dev server is driven in a browser to prove the island hydrates. @astrojs/react is the one integration AstroC4 adds itself when the site has not — the islands are client:only=\"react\" — and React is not added twice when the site already configures it. What a plain site gives up is documented: Astro.locals.t is Starlight's, so the components render English, and the highlighting option exists only on the Starlight plugin."
},
{
"audience": "developer",
Expand Down
4 changes: 2 additions & 2 deletions src/src/lib/docs/diagrams.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { posix } from 'node:path';
*
* A product repository's documentation is read in two places — on GitHub, which
* renders Mermaid but not LikeC4, and on purview.dev, which renders LikeC4
* through astroc4. A repository marks a Mermaid fence as the GitHub rendering of
* through AstroC4. A repository marks a Mermaid fence as the GitHub rendering of
* a LikeC4 view by wrapping it in a pair of HTML comments:
*
* ````md
Expand All @@ -30,7 +30,7 @@ export const DIAGRAM_OPEN = /^ {0,3}<!--\s*purview:likec4\b(.*?)-->\s*$/;
export const DIAGRAM_CLOSE = /^ {0,3}<!--\s*\/purview:likec4\s*-->\s*$/;
const FENCE = /^ {0,3}(`{3,}|~{3,})/;

/** Fence options astroc4 understands; `file` is consumed by the sync instead. */
/** Fence options AstroC4 understands; `file` is consumed by the sync instead. */
const PASSTHROUGH_OPTIONS = [
'view',
'project',
Expand Down
2 changes: 1 addition & 1 deletion src/src/likec4/demo.c4
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// The model behind the live astroc4 demo (/examples/astroc4/).
// The model behind the live AstroC4 demo (/examples/astroc4/).
// It is a real model of this site, so the diagrams on that page are not
// decoration: change the model and the demo changes with it.

Expand Down
20 changes: 10 additions & 10 deletions src/src/pages/examples/astroc4.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: ../../layouts/SiteLayout.astro
title: Astroc4 in action — Purview Dev
description: A live LikeC4 model, an inline fence, a deployment view and LikeC4 syntax highlighting, rendered by astroc4 on this page.
title: AstroC4 in action — Purview Dev
description: A live LikeC4 model, an inline fence, a deployment view and LikeC4 syntax highlighting, rendered by AstroC4 on this page.
---

import LikeC4View from '@purview-dev/astroc4/components/LikeC4View.astro';
Expand All @@ -12,17 +12,17 @@ import { withBase } from '~/lib/urls';
<nav aria-label="Breadcrumb" class="text-muted mb-6 text-sm">
<a href={withBase('/projects/')} class="pv-link">Projects</a>
<span aria-hidden="true"> / </span>
<a href={withBase('/projects/astroc4/')} class="pv-link">Astroc4</a>
<a href={withBase('/projects/astroc4/')} class="pv-link">AstroC4</a>
<span aria-hidden="true"> / </span>
<span class="text-foreground">Live example</span>
</nav>

<div class="max-w-3xl">
<p class="pv-chip border-brand/30 bg-brand/5 text-brand mb-4">Live example</p>
<h1 class="text-3xl font-bold tracking-tight md:text-4xl">Astroc4 in action</h1>
<h1 class="text-3xl font-bold tracking-tight md:text-4xl">AstroC4 in action</h1>
<p class="text-muted mt-4 text-lg">
This page is the plugin dogfooding itself. Every diagram below is compiled by
<a class="pv-link" href={withBase('/projects/astroc4/')}>astroc4</a> during this site's
<a class="pv-link" href={withBase('/projects/astroc4/')}>AstroC4</a> during this site's
build, from a real <code>.c4</code> model of purview.dev, and hydrated as a React island in
your browser. Nothing here is a screenshot.
</p>
Expand Down Expand Up @@ -51,7 +51,7 @@ import { withBase } from '~/lib/urls';
<section>
<h2 class="text-2xl font-bold tracking-tight">1. One component, the site's own model</h2>
<p class="text-muted mt-2">
The model lives in <code>src/likec4</code>. Astroc4 compiles it once with LikeC4's Vite
The model lives in <code>src/likec4</code>. AstroC4 compiles it once with LikeC4's Vite
plugin, and <code>&lt;LikeC4View&gt;</code> picks a view from it. The view is interactive:
hover a node, scroll to zoom, click an element to open its details.
</p>
Expand Down Expand Up @@ -129,7 +129,7 @@ views { view index { include * } }
4. LikeC4 source, highlighted without config
</h2>
<p class="text-muted mt-2">
Shiki has no LikeC4 grammar, so astroc4 derives one from LikeC4's own Langium language
Shiki has no LikeC4 grammar, so AstroC4 derives one from LikeC4's own Langium language
definition and injects it into Starlight's Expressive Code options. There is no
<code>ec.config.mjs</code> in this repository. A <code>```c4</code> fence shows the source
rather than drawing it.
Expand Down Expand Up @@ -193,7 +193,7 @@ model {
<p class="text-muted mt-2 text-sm">
The diagram has no useful server-rendered form, so it is a
<code>client:only="react"</code> island with a placeholder that carries the frame
height. A static build passes even when islands fail to hydrate, which is why astroc4's
height. A static build passes even when islands fail to hydrate, which is why AstroC4's
own CI runs a browser smoke test rather than trusting the exit code.
</p>
</div>
Expand All @@ -203,7 +203,7 @@ model {
<section>
<h2 class="text-2xl font-bold tracking-tight">Use it in your own site</h2>
<p class="text-muted mt-2">
Astroc4 is published to npm. The full set of options — fences, the Vite plugin workspace,
AstroC4 is published to npm. The full set of options — fences, the Vite plugin workspace,
highlighting, cache and failure policy — is in the
<a class="pv-link" href={withBase('/docs/astroc4/guide/configuration-reference/')}>
configuration reference
Expand All @@ -218,7 +218,7 @@ model {
Get started
</a>
<a class="pv-btn pv-btn-secondary pv-btn-sm" href={withBase('/projects/astroc4/')}>
Back to Astroc4
Back to AstroC4
</a>
</div>
</section>
Expand Down
2 changes: 1 addition & 1 deletion src/src/pages/projects/[project].astro
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ const structuredData: Record<string, unknown> = {
description: project.shortDescription,
url: absoluteUrl(`/projects/${project.id}/`),
codeRepository: project.sourceUrl,
// A NuGet package is a .NET claim. A project that publishes none (astroc4
// A NuGet package is a .NET claim. A project that publishes none (AstroC4
// is an npm package) may be written in another language, so the field is
// omitted rather than asserted.
...(primaryPackage?.registry === 'nuget' ? { programmingLanguage: 'C#' } : {}),
Expand Down
2 changes: 1 addition & 1 deletion src/tests/dist/built-output.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ describe('built per-project llms outputs', () => {
// The full bundle is the header plus every aggregated page, so it must be
// longer than the concise index. Asserting a word such as "Purview" only
// holds for projects whose documentation happens to mention the
// organisation: astroc4 documents an npm package and never does.
// organisation: AstroC4 documents an npm package and never does.
expect(full.length, `${project.id} llms-full.txt lacks aggregated content`).toBeGreaterThan(
summary.length,
);
Expand Down
Loading