From 14785ad3b739ec2716fd8aeeef96112cb6287488 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 16 Nov 2026 07:29:14 +0000 Subject: [PATCH] docs: name the product AstroC4 --- docs/decisions/0006-local-path-check.md | 2 +- docs/decisions/0012-npm-packages.md | 6 +++--- ...repository-owned-diagrams-and-redirects.md | 4 ++-- src/astro.config.ts | 14 ++++++------- src/config/expressive-code-languages.ts | 2 +- src/config/satteri-mermaid.ts | 2 +- src/fixtures/manifests/index.json | 4 ++-- src/src/lib/docs/diagrams.ts | 4 ++-- src/src/likec4/demo.c4 | 2 +- src/src/pages/examples/astroc4.mdx | 20 +++++++++---------- src/src/pages/projects/[project].astro | 2 +- src/tests/dist/built-output.test.ts | 2 +- 12 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/decisions/0006-local-path-check.md b/docs/decisions/0006-local-path-check.md index 9dbda91..c60c1ab 100644 --- a/docs/decisions/0006-local-path-check.md +++ b/docs/decisions/0006-local-path-check.md @@ -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 diff --git a/docs/decisions/0012-npm-packages.md b/docs/decisions/0012-npm-packages.md index e24665d..ccc6891 100644 --- a/docs/decisions/0012-npm-packages.md +++ b/docs/decisions/0012-npm-packages.md @@ -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 @@ -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 diff --git a/docs/decisions/0013-repository-owned-diagrams-and-redirects.md b/docs/decisions/0013-repository-owned-diagrams-and-redirects.md index b8e40a8..b841acc 100644 --- a/docs/decisions/0013-repository-owned-diagrams-and-redirects.md +++ b/docs/decisions/0013-repository-owned-diagrams-and-redirects.md @@ -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. @@ -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` diff --git a/src/astro.config.ts b/src/astro.config.ts index 8345b6b..9f01dcb 100644 --- a/src/astro.config.ts +++ b/src/astro.config.ts @@ -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/**'] }), @@ -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: { @@ -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 @@ -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'] }, @@ -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: { @@ -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: [ diff --git a/src/config/expressive-code-languages.ts b/src/config/expressive-code-languages.ts index b2b9336..0224f2c 100644 --- a/src/config/expressive-code-languages.ts +++ b/src/config/expressive-code-languages.ts @@ -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 diff --git a/src/config/satteri-mermaid.ts b/src/config/satteri-mermaid.ts index f2e719a..38f16cf 100644 --- a/src/config/satteri-mermaid.ts +++ b/src/config/satteri-mermaid.ts @@ -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 { diff --git a/src/fixtures/manifests/index.json b/src/fixtures/manifests/index.json index 474fcdf..bbd0e5e 100644 --- a/src/fixtures/manifests/index.json +++ b/src/fixtures/manifests/index.json @@ -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 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.", @@ -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 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", diff --git a/src/src/lib/docs/diagrams.ts b/src/src/lib/docs/diagrams.ts index 9ab8a40..93ea21f 100644 --- a/src/src/lib/docs/diagrams.ts +++ b/src/src/lib/docs/diagrams.ts @@ -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 @@ -30,7 +30,7 @@ export const DIAGRAM_OPEN = /^ {0,3}\s*$/; export const DIAGRAM_CLOSE = /^ {0,3}\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', diff --git a/src/src/likec4/demo.c4 b/src/src/likec4/demo.c4 index ded3d29..6d820d3 100644 --- a/src/src/likec4/demo.c4 +++ b/src/src/likec4/demo.c4 @@ -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. diff --git a/src/src/pages/examples/astroc4.mdx b/src/src/pages/examples/astroc4.mdx index f071cbd..e1a0982 100644 --- a/src/src/pages/examples/astroc4.mdx +++ b/src/src/pages/examples/astroc4.mdx @@ -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'; @@ -12,17 +12,17 @@ import { withBase } from '~/lib/urls';

Live example

-

Astroc4 in action

+

AstroC4 in action

This page is the plugin dogfooding itself. Every diagram below is compiled by - astroc4 during this site's + AstroC4 during this site's build, from a real .c4 model of purview.dev, and hydrated as a React island in your browser. Nothing here is a screenshot.

@@ -51,7 +51,7 @@ import { withBase } from '~/lib/urls';

1. One component, the site's own model

- The model lives in src/likec4. Astroc4 compiles it once with LikeC4's Vite + The model lives in src/likec4. AstroC4 compiles it once with LikeC4's Vite plugin, and <LikeC4View> picks a view from it. The view is interactive: hover a node, scroll to zoom, click an element to open its details.

@@ -129,7 +129,7 @@ views { view index { include * } } 4. LikeC4 source, highlighted without config

- 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 ec.config.mjs in this repository. A ```c4 fence shows the source rather than drawing it. @@ -193,7 +193,7 @@ model {

The diagram has no useful server-rendered form, so it is a client:only="react" 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.

@@ -203,7 +203,7 @@ model {

Use it in your own site

- 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 configuration reference @@ -218,7 +218,7 @@ model { Get started - Back to Astroc4 + Back to AstroC4

diff --git a/src/src/pages/projects/[project].astro b/src/src/pages/projects/[project].astro index 8e1b664..0c6b530 100644 --- a/src/src/pages/projects/[project].astro +++ b/src/src/pages/projects/[project].astro @@ -125,7 +125,7 @@ const structuredData: Record = { 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#' } : {}), diff --git a/src/tests/dist/built-output.test.ts b/src/tests/dist/built-output.test.ts index a8ab072..f908055 100644 --- a/src/tests/dist/built-output.test.ts +++ b/src/tests/dist/built-output.test.ts @@ -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, );