Unions package

.agents/skills/docs-aggregation-rules/SKILL.md

@@ -174,6 +174,13 @@ title per document.
   from `/llms.txt` and from the project page.
 - Staleness: a page is flagged when `lastReviewed` is older than 365 days
   (`src/src/lib/docs/staleness.ts`).
+- A ```` ```likec4 ```` fence in a mirrored page stays **source**, not a diagram:
+  the whole `docs` collection is relaxed through astroc4's `validation:
+  { collections: ['docs'] }` (`astro.config.ts`). Such a page was written for
+  another renderer, so its fence is often a partial snippet; astroc4 logs a
+  warning and leaves it as a highlighted code block instead of failing the build.
+  Pages the site authors (`src/pages/**`) are not in the collection, so they keep
+  strict validation.
 
 ## Verifying
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "purview-dev",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Purview-Dev public website and unified documentation portal (workspace root).",
   "license": "MIT",

src/astro.config.ts

@@ -14,6 +14,7 @@ import starlightSidebarTopics from 'starlight-sidebar-topics';
 
 import discoveryIntegration from './config/discovery-integration';
 import docsRedirectsIntegration from './config/docs-redirects-integration';
+import { siteLanguages } from './config/expressive-code-languages';
 import { mermaidFences } from './config/satteri-mermaid';
 import { projectChannelLlmsUrl, projectLlmsUrl } from './src/lib/discovery/urls';
 import { readDocsManifest } from './src/lib/docs/aggregate';
@@ -168,6 +169,10 @@ export default defineConfig({
       customCss: ['./src/styles/global.css'],
       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
+        // its LikeC4 grammar to this list rather than replacing it.
+        shiki: { langs: [...siteLanguages] },
         styleOverrides: {
           borderRadius: '0.75rem',
           codeFontFamily: 'var(--font-mono)',
@@ -202,6 +207,14 @@ export default defineConfig({
         astroc4({
           vitePlugin: { workspace: 'src/likec4' },
           highlighting: { ref: 'v1.60.0' },
+          // The `docs` collection is the aggregated mirror of other repositories'
+          // Markdown (see .agents/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
+          // 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'] },
         }),
         starlightSidebarTopics(sidebarTopics),
         starlightLinksValidator({

src/config/expressive-code-languages.ts

@@ -0,0 +1,48 @@
+/**
+ * Languages the site registers with Expressive Code itself, alongside the
+ * LikeC4 grammar astroc4 contributes.
+ *
+ * `gitignore` exists because the aggregated documentation mirror contains
+ * `.gitignore` snippets — product repositories fence them as `gitignore` — and
+ * neither Shiki nor Expressive Code bundles an ignore-file grammar: without a
+ * registration Expressive Code warns that it cannot find the language and falls
+ * back to plain text. The grammar covers what a `.gitignore` line actually
+ * contains — a whole-line comment, a leading negation, glob wildcards, an
+ * escaped character, a character class and the directory suffix.
+ *
+ * This is the site's own vocabulary, so it stays deliberately small; it is not
+ * a general ignore-file grammar. Scopes are the usual TextMate ones, so the
+ * theme colours comments and constants the way it colours any other language.
+ */
+export const gitignoreLanguage = {
+  name: 'gitignore',
+  scopeName: 'source.gitignore',
+  aliases: ['ignore', 'git-ignore'],
+  patterns: [{ include: '#comment' }, { include: '#negation' }, { include: '#pattern' }],
+  repository: {
+    /** A `#` at the start of a line (after optional indent) comments out the line. */
+    comment: {
+      match: '^\\s*#.*$',
+      name: 'comment.line.number-sign.gitignore',
+    },
+    /** A leading `!` re-includes what an earlier pattern excluded. */
+    negation: {
+      match: '^\\s*!',
+      name: 'keyword.operator.negation.gitignore',
+    },
+    pattern: {
+      patterns: [
+        /** `\#`, `\!`, `\ ` and friends: the next character is literal. */
+        { match: '\\\\.', name: 'constant.character.escape.gitignore' },
+        { match: '\\*\\*|\\*|\\?', name: 'constant.other.wildcard.gitignore' },
+        { match: '\\[[^\\]]*\\]', name: 'constant.other.character-class.gitignore' },
+        /** A trailing slash matches directories only. */
+        { match: '/$', name: 'punctuation.separator.directory.gitignore' },
+        { match: '/', name: 'punctuation.separator.path.gitignore' },
+      ],
+    },
+  },
+};
+
+/** Everything the site adds to `expressiveCode.shiki.langs` in `astro.config.ts`. */
+export const siteLanguages = [gitignoreLanguage];

src/fixtures/github/releases/unions.json

@@ -0,0 +1 @@
+[{"url":"https://api.github.com/repos/purview-dev/unions/releases/441984033","assets_url":"https://api.github.com/repos/purview-dev/unions/releases/441984033/assets","upload_url":"https://uploads.github.com/repos/purview-dev/unions/releases/441984033/assets{?name,label}","html_url":"https://github.com/purview-dev/unions/releases/tag/v1.0.0-prerelease.1","id":441984033,"author":{"login":"github-actions[bot]","id":41898282,"node_id":"MDM6Qm90NDE4OTgyODI=","avatar_url":"https://avatars.githubusercontent.com/in/15368?v=4","gravatar_id":"","url":"https://api.github.com/users/github-actions%5Bbot%5D","html_url":"https://github.com/apps/github-actions","followers_url":"https://api.github.com/users/github-actions%5Bbot%5D/followers","following_url":"https://api.github.com/users/github-actions%5Bbot%5D/following{/other_user}","gists_url":"https://api.github.com/users/github-actions%5Bbot%5D/gists{/gist_id}","starred_url":"https://api.github.com/users/github-actions%5Bbot%5D/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/github-actions%5Bbot%5D/subscriptions","organizations_url":"https://api.github.com/users/github-actions%5Bbot%5D/orgs","repos_url":"https://api.github.com/users/github-actions%5Bbot%5D/repos","events_url":"https://api.github.com/users/github-actions%5Bbot%5D/events{/privacy}","received_events_url":"https://api.github.com/users/github-actions%5Bbot%5D/received_events","type":"Bot","user_view_type":"public","site_admin":false},"node_id":"RE_kwDOVp0H5c4aWCQh","tag_name":"v1.0.0-prerelease.1","target_commitish":"main","name":"v1.0.0-prerelease.1","draft":false,"immutable":false,"prerelease":true,"created_at":"2026-11-11T17:12:10Z","updated_at":"2026-11-11T17:14:20Z","published_at":"2026-11-11T17:14:20Z","assets":[],"tarball_url":"https://api.github.com/repos/purview-dev/unions/tarball/v1.0.0-prerelease.1","zipball_url":"https://api.github.com/repos/purview-dev/unions/zipball/v1.0.0-prerelease.1","body":"## What's Changed\n* Net11 update by @kieronlanning in https://github.com/purview-dev/unions/pull/1\n\n## New Contributors\n* @kieronlanning made their first contribution in https://github.com/purview-dev/unions/pull/1\n\n**Full Changelog**: https://github.com/purview-dev/unions/commits/v1.0.0-prerelease.1","mentions_count":1}]

src/fixtures/github/repos/unions.json

@@ -0,0 +1 @@
+{"id":1453131749,"node_id":"R_kgDOVp0H5Q","name":"unions","full_name":"purview-dev/unions","private":false,"owner":{"login":"purview-dev","id":96894084,"node_id":"O_kgDOBcZ8hA","avatar_url":"https://avatars.githubusercontent.com/u/96894084?v=4","gravatar_id":"","url":"https://api.github.com/users/purview-dev","html_url":"https://github.com/purview-dev","followers_url":"https://api.github.com/users/purview-dev/followers","following_url":"https://api.github.com/users/purview-dev/following{/other_user}","gists_url":"https://api.github.com/users/purview-dev/gists{/gist_id}","starred_url":"https://api.github.com/users/purview-dev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/purview-dev/subscriptions","organizations_url":"https://api.github.com/users/purview-dev/orgs","repos_url":"https://api.github.com/users/purview-dev/repos","events_url":"https://api.github.com/users/purview-dev/events{/privacy}","received_events_url":"https://api.github.com/users/purview-dev/received_events","type":"Organization","user_view_type":"public","site_admin":false},"html_url":"https://github.com/purview-dev/unions","description":"Dependency-free C# 15 unions that do not box value-type cases - a source generator emits the non-boxing custom-union shape with typed storage, TryGetValue, exhaustive switch and UNI diagnostics, plus a hand-written Union<T1, T2>.","fork":false,"url":"https://api.github.com/repos/purview-dev/unions","forks_url":"https://api.github.com/repos/purview-dev/unions/forks","keys_url":"https://api.github.com/repos/purview-dev/unions/keys{/key_id}","collaborators_url":"https://api.github.com/repos/purview-dev/unions/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/purview-dev/unions/teams","hooks_url":"https://api.github.com/repos/purview-dev/unions/hooks","issue_events_url":"https://api.github.com/repos/purview-dev/unions/issues/events{/number}","events_url":"https://api.github.com/repos/purview-dev/unions/events","assignees_url":"https://api.github.com/repos/purview-dev/unions/assignees{/user}","branches_url":"https://api.github.com/repos/purview-dev/unions/branches{/branch}","tags_url":"https://api.github.com/repos/purview-dev/unions/tags","blobs_url":"https://api.github.com/repos/purview-dev/unions/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/purview-dev/unions/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/purview-dev/unions/git/refs{/sha}","trees_url":"https://api.github.com/repos/purview-dev/unions/git/trees{/sha}","statuses_url":"https://api.github.com/repos/purview-dev/unions/statuses/{sha}","languages_url":"https://api.github.com/repos/purview-dev/unions/languages","stargazers_url":"https://api.github.com/repos/purview-dev/unions/stargazers","contributors_url":"https://api.github.com/repos/purview-dev/unions/contributors","subscribers_url":"https://api.github.com/repos/purview-dev/unions/subscribers","subscription_url":"https://api.github.com/repos/purview-dev/unions/subscription","commits_url":"https://api.github.com/repos/purview-dev/unions/commits{/sha}","git_commits_url":"https://api.github.com/repos/purview-dev/unions/git/commits{/sha}","comments_url":"https://api.github.com/repos/purview-dev/unions/comments{/number}","issue_comment_url":"https://api.github.com/repos/purview-dev/unions/issues/comments{/number}","contents_url":"https://api.github.com/repos/purview-dev/unions/contents/{+path}","compare_url":"https://api.github.com/repos/purview-dev/unions/compare/{base}...{head}","merges_url":"https://api.github.com/repos/purview-dev/unions/merges","archive_url":"https://api.github.com/repos/purview-dev/unions/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/purview-dev/unions/downloads","issues_url":"https://api.github.com/repos/purview-dev/unions/issues{/number}","pulls_url":"https://api.github.com/repos/purview-dev/unions/pulls{/number}","milestones_url":"https://api.github.com/repos/purview-dev/unions/milestones{/number}","notifications_url":"https://api.github.com/repos/purview-dev/unions/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/purview-dev/unions/labels{/name}","releases_url":"https://api.github.com/repos/purview-dev/unions/releases{/id}","deployments_url":"https://api.github.com/repos/purview-dev/unions/deployments","created_at":"2026-11-10T20:00:01Z","updated_at":"2026-11-11T17:15:01Z","pushed_at":"2026-11-11T17:14:20Z","git_url":"git://github.com/purview-dev/unions.git","ssh_url":"git@github.com:purview-dev/unions.git","clone_url":"https://github.com/purview-dev/unions.git","svn_url":"https://github.com/purview-dev/unions","homepage":"https://purview.dev/projects/unions/","size":364,"stargazers_count":1,"watchers_count":1,"language":"C#","has_issues":true,"has_projects":false,"has_downloads":false,"has_wiki":false,"has_pages":false,"has_discussions":false,"forks_count":0,"mirror_url":null,"archived":false,"disabled":false,"open_issues_count":0,"license":{"key":"mit","name":"MIT License","spdx_id":"MIT","url":"https://api.github.com/licenses/mit","node_id":"MDc6TGljZW5zZTEz"},"allow_forking":true,"is_template":false,"web_commit_signoff_required":false,"has_pull_requests":true,"pull_request_creation_policy":"all","topics":["boxing","c-sharp","code-generation","csharp","csharp-15","discriminated-unions","dotnet","net10","net11","nuget","performance","roslyn","source-generator","union","union-types","unions","value-types","zero-allocation"],"visibility":"public","forks":0,"open_issues":0,"watchers":1,"default_branch":"main","temp_clone_token":null,"custom_properties":{},"organization":{"login":"purview-dev","id":96894084,"node_id":"O_kgDOBcZ8hA","avatar_url":"https://avatars.githubusercontent.com/u/96894084?v=4","gravatar_id":"","url":"https://api.github.com/users/purview-dev","html_url":"https://github.com/purview-dev","followers_url":"https://api.github.com/users/purview-dev/followers","following_url":"https://api.github.com/users/purview-dev/following{/other_user}","gists_url":"https://api.github.com/users/purview-dev/gists{/gist_id}","starred_url":"https://api.github.com/users/purview-dev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/purview-dev/subscriptions","organizations_url":"https://api.github.com/users/purview-dev/orgs","repos_url":"https://api.github.com/users/purview-dev/repos","events_url":"https://api.github.com/users/purview-dev/events{/privacy}","received_events_url":"https://api.github.com/users/purview-dev/received_events","type":"Organization","user_view_type":"public","site_admin":false},"network_count":0,"subscribers_count":0}

src/fixtures/nuget/nuspec/purview.unions.nuspec

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
+  <metadata>
+    <id>Purview.Unions</id>
+    <version>1.0.0-prerelease.1</version>
+    <title>Purview Unions</title>
+    <authors>Kieron Lanning</authors>
+    <license type="expression">MIT</license>
+    <licenseUrl>https://licenses.nuget.org/MIT</licenseUrl>
+    <icon>purview-logo-light.png</icon>
+    <readme>README.md</readme>
+    <projectUrl>https://purview.dev/projects/unions/</projectUrl>
+    <description>Dependency-free C# 15 unions that do not box value-type cases: a source generator emits the non-boxing custom-union shape, plus a hand-written Union&lt;T1, T2&gt; for .NET 10 and for projects that do not use a generator.</description>
+    <copyright>Copyright © 2026 Purview-Dev</copyright>
+    <tags>unions union discriminated-union csharp-15 net10 net11 source-generator boxing purview</tags>
+    <repository type="git" url="https://github.com/purview-dev/unions.git" branch="refs/heads/main" commit="7430ebe00b3fa42b8ac5c50510f5f312acac0d07" />
+    <dependencies>
+      <group targetFramework="net10.0" />
+      <group targetFramework="net11.0" />
+    </dependencies>
+  </metadata>
+</package>

src/fixtures/nuget/purview.unions.json

@@ -0,0 +1,5 @@
+{
+  "versions": [
+    "1.0.0-prerelease.1"
+  ]
+}

src/fixtures/nuget/search/Purview.Unions.json

@@ -0,0 +1,8 @@
+{
+  "@context": {
+    "@vocab": "http://schema.nuget.org/schema#",
+    "@base": "https://api.nuget.org/v3/registration5-semver1/"
+  },
+  "totalHits": 0,
+  "data": []
+}

src/fixtures/releases/index.json

@@ -67,6 +67,38 @@
       "updatedAt": "2026-11-02T23:13:45Z",
       "hasDiscussions": false
     },
+    "purview-dev/unions": {
+      "name": "unions",
+      "fullName": "purview-dev/unions",
+      "description": "Dependency-free C# 15 unions that do not box value-type cases - a source generator emits the non-boxing custom-union shape with typed storage, TryGetValue, exhaustive switch and UNI diagnostics, plus a hand-written Union<T1, T2>.",
+      "archived": false,
+      "homepage": "https://purview.dev/projects/unions/",
+      "topics": [
+        "boxing",
+        "c-sharp",
+        "code-generation",
+        "csharp",
+        "csharp-15",
+        "discriminated-unions",
+        "dotnet",
+        "net10",
+        "net11",
+        "nuget",
+        "performance",
+        "roslyn",
+        "source-generator",
+        "union",
+        "union-types",
+        "unions",
+        "value-types",
+        "zero-allocation"
+      ],
+      "stargazersCount": 1,
+      "openIssuesCount": 0,
+      "defaultBranch": "main",
+      "updatedAt": "2026-11-11T17:15:01Z",
+      "hasDiscussions": false
+    },
     "purview-dev/zodsharp": {
       "name": "zodsharp",
       "fullName": "purview-dev/zodsharp",
@@ -966,6 +998,17 @@
         "htmlUrl": "https://github.com/purview-dev/event-sourcing/releases/tag/v1.0.0"
       }
     ],
+    "purview-dev/unions": [
+      {
+        "tagName": "v1.0.0-prerelease.1",
+        "name": "v1.0.0-prerelease.1",
+        "body": "## What's Changed\n* Net11 update by @kieronlanning in https://github.com/purview-dev/unions/pull/1\n\n## New Contributors\n* @kieronlanning made their first contribution in https://github.com/purview-dev/unions/pull/1\n\n**Full Changelog**: https://github.com/purview-dev/unions/commits/v1.0.0-prerelease.1",
+        "prerelease": true,
+        "draft": false,
+        "publishedAt": "2026-11-11T17:14:20Z",
+        "htmlUrl": "https://github.com/purview-dev/unions/releases/tag/v1.0.0-prerelease.1"
+      }
+    ],
     "purview-dev/zodsharp": [
       {
         "tagName": "v3.0.0-prerelease.2",
@@ -3474,6 +3517,17 @@
       ],
       "targetFrameworksVersion": "2.0.0-prerelease.39"
     },
+    "Purview.Unions": {
+      "id": "Purview.Unions",
+      "versions": [
+        "1.0.0-prerelease.1"
+      ],
+      "targetFrameworks": [
+        "net10.0",
+        "net11.0"
+      ],
+      "targetFrameworksVersion": "1.0.0-prerelease.1"
+    },
     "Purview.ZodSharp": {
       "id": "Purview.ZodSharp",
       "versions": [
@@ -4467,6 +4521,7 @@
     "Purview.EventSourcing.InMemory": null,
     "Purview.EventSourcing.Validation.FluentValidation": null,
     "Purview.EventSourcing.Validation.ZodSharp": null,
+    "Purview.Unions": null,
     "Purview.ZodSharp": {
       "id": "Purview.ZodSharp",
       "version": "2.4.2",

src/package.json

@@ -31,31 +31,31 @@
     "typecheck": "astro check"
   },
   "dependencies": {
-    "@astrojs/markdown-satteri": "0.4.6",
-    "@astrojs/mdx": "8.1.2",
-    "@astrojs/react": "7.1.2",
+    "@astrojs/markdown-satteri": "0.4.9",
+    "@astrojs/mdx": "8.1.5",
+    "@astrojs/react": "7.1.8",
     "@likec4/core": "1.60.0",
     "@pagefind/default-ui": "1.5.2",
-    "@purview-dev/astroc4": "1.0.0-prerelease.5",
+    "@purview-dev/astroc4": "1.0.0-prerelease.8",
     "likec4": "1.60.0",
     "preact": "10.29.8",
     "react": "19.3.1",
     "react-dom": "19.3.1",
-    "satteri": "0.10.5"
+    "satteri": "0.11.7"
   },
   "devDependencies": {
-    "@astrojs/check": "0.9.10",
-    "@astrojs/preact": "6.0.5",
+    "@astrojs/check": "0.9.12",
+    "@astrojs/preact": "6.1.5",
     "@astrojs/sitemap": "3.7.4",
-    "@astrojs/starlight": "0.42.8",
+    "@astrojs/starlight": "0.42.10",
     "@astrojs/starlight-tailwind": "5.0.0",
     "@shikijs/themes": "4.4.3",
     "@tailwindcss/vite": "4.3.3",
     "@types/bun": "1.4.4",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@types/semver": "^7.8.0",
-    "astro": "7.4.5",
+    "astro": "7.4.11",
     "fast-glob": "3.3.3",
     "lefthook": "2.1.14",
     "mermaid": "^11.17.2",