diff --git a/.agents/agents/catalogue-auditor.agent.md b/.agents/agents/catalogue-auditor.agent.md index c6ac824..11604f2 100644 --- a/.agents/agents/catalogue-auditor.agent.md +++ b/.agents/agents/catalogue-auditor.agent.md @@ -18,7 +18,7 @@ You are a specialist for auditing (and repairing) the Purview-Dev project catalo ## Primary objective -Prove that every project defined in the catalogue (`src/src/data/projects/`) is correct and report the evidence, +Prove that every catalogue record — the project-owned ones at `.config/purview-docs.yml` (ADR 0013) and the ones under `src/src/data/projects/` — is correct and report the evidence, then fix the drift that is unambiguous and safe to fix. ## Background knowledge diff --git a/.agents/agents/catalogue-onboarder.agent.md b/.agents/agents/catalogue-onboarder.agent.md index 48acbc2..a18e901 100644 --- a/.agents/agents/catalogue-onboarder.agent.md +++ b/.agents/agents/catalogue-onboarder.agent.md @@ -19,7 +19,7 @@ You are a specialist for onboarding repositories into the Purview-Dev website ca ## Primary objective Take a repository (`purview-dev/` or a collaboration repository) and deliver a complete, -validated integration: a correct catalogue record under `src/src/data/projects/`, a working documentation +validated integration: a correct catalogue record (`.config/purview-docs.yml` in the project's own repository, ADR 0013), a working documentation configuration, concrete use cases, tags/metadata, and a green `just validate`. ## Background knowledge diff --git a/.agents/skills/add-catalogue-project/SKILL.md b/.agents/skills/add-catalogue-project/SKILL.md index 963fe0b..1b6dbd2 100644 --- a/.agents/skills/add-catalogue-project/SKILL.md +++ b/.agents/skills/add-catalogue-project/SKILL.md @@ -76,7 +76,9 @@ description/topics. ## Step 3 — author the record -Add the entry as `src/src/data/projects/.yml` (see `project-manifest-reference` for every field): +Add the record as `.config/purview-docs.yml` in the project's repository (ADR 0013), or as +`src/src/data/projects/.yml` here until the project owns one (see `project-manifest-reference` for +every field): ```yaml - id: diff --git a/.agents/skills/audit-catalogue-projects/SKILL.md b/.agents/skills/audit-catalogue-projects/SKILL.md index 90328d7..2f1d7a0 100644 --- a/.agents/skills/audit-catalogue-projects/SKILL.md +++ b/.agents/skills/audit-catalogue-projects/SKILL.md @@ -1,6 +1,6 @@ --- name: audit-catalogue-projects -description: Use when auditing or repairing the catalogue records under src/src/data/ — the invariant checklist for documentation, stability, metadata, tags, packages, relationships, use cases and ordering, plus the findings report format. +description: Use when auditing or repairing the catalogue records — each project's own .config/purview-docs.yml (ADR 0013) and the ones still under src/src/data/ — the invariant checklist for documentation, stability, metadata, tags, packages, relationships, use cases and ordering, plus the findings report format. category: purview-dev-website roles: - catalogue diff --git a/.agents/skills/project-manifest-reference/SKILL.md b/.agents/skills/project-manifest-reference/SKILL.md index d02ca06..4a6302d 100644 --- a/.agents/skills/project-manifest-reference/SKILL.md +++ b/.agents/skills/project-manifest-reference/SKILL.md @@ -1,6 +1,6 @@ --- name: project-manifest-reference -description: Field-by-field reference for the catalogue records under src/src/data/projects/ (schema vocabulary, defaults, loader-enforced rules, and the invariants the site build depends on). Use whenever authoring or reviewing a catalogue record. +description: Field-by-field reference for the catalogue records a project publishes at .config/purview-docs.yml and the ones still under src/src/data/projects/ (schema vocabulary, defaults, loader-enforced rules, and the invariants the site build depends on). Use whenever authoring or reviewing a catalogue record. category: purview-dev-website roles: - catalogue @@ -13,9 +13,13 @@ tags: # project-manifest-reference Skill -The catalogue is one file per project under `src/src/data/projects/` (plus -`src/src/data/external-projects.yml` for collaborations), typed by `src/src/lib/manifest/schema.ts` and validated -by `src/src/lib/manifest/load.ts`. `$schema: ../lib/manifest/schema.ts` is the first line of the file. +The catalogue is one record per project. A project publishes its own at `.config/purview-docs.yml` in +its repository, and that is what the site reads at build time (ADR 0013); the records a project does +not own yet are under `src/src/data/projects/`, and `src/src/data/external-projects.yml` holds the +collaborations. All of them are typed by `src/src/lib/manifest/schema.ts` and validated by +`src/src/lib/manifest/load.ts`. A record held here opens with `$schema: ../lib/manifest/schema.ts`; +a project-owned record names the schema by absolute URL, because the relative path resolves to nothing +from another repository. ## Vocabularies (do not invent values) diff --git a/.agents/skills/use-case-authoring/SKILL.md b/.agents/skills/use-case-authoring/SKILL.md index 84279ef..517fe1a 100644 --- a/.agents/skills/use-case-authoring/SKILL.md +++ b/.agents/skills/use-case-authoring/SKILL.md @@ -14,7 +14,7 @@ tags: # use-case-authoring Skill Use cases are the "what does it actually do for me" evidence on the home page, on each project page, -and on `/use-cases/`. They are authored in the catalogue records (`src/src/data/projects/.yml`) and validated by the manifest +and on `/use-cases/`. They are authored in the catalogue records (`src/src/data/projects/.yml` here, or a project's own `.config/purview-docs.yml`) and validated by the manifest schema. The governing decision is `docs/decisions/0002-concrete-use-cases.md`. ## Shape diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d8b9124..9bb461b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -16,7 +16,7 @@ package is `src/`. - Treat `just validate` as the definition of done. It chains format-check, lint, typecheck, unit tests, asset checks, build, link crawl, generated-output checks, built-output tests, and the catalogue guard (`just check-projects`). -- Edit the catalogue under `src/src/data/` only (one file per project, plus `external-projects.yml`), and keep every invariant listed in +- Catalogue records live in each project repository at `.config/purview-docs.yml` (ADR 0013), in `src/src/data/projects/` for projects that do not own one yet, and in `src/src/data/external-projects.yml` for collaborations. Keep every invariant listed in `AGENTS.md` (unique ids/orders/packages, `name` slugifying to `id` for documented projects, at least one use case per non-archived project, `code` paired with `language`, resolvable `docsPage`). - Keep declared `status` and `targetFrameworks` honest: `just check-projects` prints advisory diff --git a/AGENTS.md b/AGENTS.md index 657ba38..7018465 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,9 +10,10 @@ Two agent tasks recur here, and both have a dedicated agent plus skills under `. 1. **Add a project** — given a `purview-dev/` (or a collaboration repository), build its documentation, use cases, tags and metadata so it is fully integrated into the site. -2. **Audit the catalogue** — prove that every project defined in `src/src/data/projects/` (one file per project, plus - `external-projects.yml` for collaborations) is - correct: documentation configuration, lifecycle stability, metadata and relationships. +2. **Audit the catalogue** — prove that every project record is correct: the ones the project + repositories own at `.config/purview-docs.yml` (ADR 0013) and the ones still here under + `src/src/data/projects/`, plus `src/src/data/external-projects.yml` for collaborations — + documentation configuration, lifecycle stability, metadata and relationships. ## Technology and tooling context @@ -26,9 +27,10 @@ from the repository root and delegated to the package. `oxfmt` does **not** support `.astro` yet (oxc-project/oxc#15665) — format those by hand and rely on `astro check` + oxlint. - **Task runner:** Just (`justfile`; switches to pwsh on Windows). -- **All external data is fetched at build time**, never by the visitor's browser: GitHub releases, - NuGet and npm registry data, the documentation mirror, and any `assets:` a project mirrors into - `public/`, cached under `src/.cache/` with committed fixtures as the offline fallback. The one +- **All external data is fetched at build time**, never by the visitor's browser: the project-owned + catalogue records (ADR 0013), GitHub releases, NuGet and npm registry data, the documentation + mirror, and any `assets:` a project mirrors into `public/`, cached under `src/.cache/` with + committed fixtures as the offline fallback. The one exception is the package **version numbers** the page already displays: the browser re-checks them against the registry that publishes the package (NuGet or npm), applies any higher version, and stores it (ADR 0008, ADR 0012). @@ -39,6 +41,7 @@ from the repository root and delegated to the package. | --- | --- | --- | | `src/src/content/docs/**` | Aggregated documentation mirror (gitignored) | `just data-sync` | | `src/.cache/docs`, `src/.cache/releases` | Typed docs/release caches (gitignored) | `just data-sync` / `just fetch-releases` | +| `src/.cache/manifests` | Project-owned catalogue records fetched from their repositories (gitignored) | `just data-sync` / `just refresh-fixtures` | | `src/public/schemas/**` | Mirrored project assets declared in `assets:` (gitignored) | `just data-sync` | | `src/public/skills/**` | Mirrored Agent Skills declared in `skills:` (gitignored) | `just data-sync` | | `src/dist/**` | Production build output (gitignored) | `just build` | @@ -58,8 +61,10 @@ prints advisory observations (which never fail the build) when a project's decla ## Ecosystem model — what "a project" means here -- `projects:` entries — one file per project under `src/src/data/projects/` — are Purview-owned catalogue entries. Their `repository` - **must** be `purview-dev/` (enforced by the loader). +- `projects:` records — the ones under `src/src/data/projects/` here and the ones a project publishes + at `.config/purview-docs.yml` (ADR 0013) — are Purview-owned catalogue entries. Their `repository` + **must** be `purview-dev/` (enforced by the loader). A record declared in both places is + reported by `just check-projects`: the project's own copy wins, and the local one is deleted. - `externalProjects:` are collaborations the organisation contributes to but does not own (for example `likec4/likec4`). They link out to their own site/repository: no documentation aggregation, no NuGet packages, no `/projects//` page. @@ -175,7 +180,8 @@ src/src/data/projects/.yml` against a clone of its repository. | Concern | Location | | --- | --- | -| Catalogue manifest | `src/src/data/projects/.yml` (one per project) + `src/src/data/external-projects.yml` | +| Catalogue records | `.config/purview-docs.yml` in each project repository (ADR 0013), plus `src/src/data/projects/.yml` for projects that have not moved, plus `src/src/data/external-projects.yml` for collaborations | +| Manifest fetch and cache | `src/src/lib/manifest/{remote,runtime}.ts`, `src/scripts/sync-manifests.ts` | | Manifest schema / loader | `src/src/lib/manifest/{schema,load}.ts` | | Docs aggregation | `src/src/lib/docs/aggregate.ts` (+ `frontmatter`, `links`, `sidebar`, `staleness`, `diagrams`, `redirect-file`) | | Consumer skills for product repositories | `skills/purview-site-{integration,docs,assessment}/` | diff --git a/README.md b/README.md index 2854260..9c163d8 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ purview-dev/ # workspace root ├── src/ │ ├── content.config.ts # Starlight docs collection schema │ ├── content/docs/ # GENERATED documentation mirror (gitignored) - │ ├── data/projects/ # Typed, validated catalogue: one file per project + │ ├── data/projects/ # Records this repo still owns (a project owns its own - ADR 0013) │ ├── data/external-projects.yml # Collaborations the organisation does not own │ ├── lib/ # manifest, releases, docs, urls, site constants │ ├── components/ # shared chrome, Starlight overrides, islands @@ -173,7 +173,9 @@ just dev ``` The dev server starts after a data sync. Edit `src/src/pages/` for marketing -pages and `src/src/data/projects/.yml` for catalogue content. Documentation pages +pages and a project's own `.config/purview-docs.yml` for that project's catalogue record — +the records a project does not own yet are still under `src/src/data/projects/`, and are edited here. +Documentation pages are generated under `src/src/content/docs/` and should not be edited by hand — change the source repository instead and re-run `just data-sync`. @@ -198,15 +200,20 @@ generated copies. ## Project catalogue -`src/src/data/projects/.yml` (one file per project, plus -`src/src/data/external-projects.yml` for collaborations) is the single source of truth for the catalogue. It -is validated at build time by a typed Zod schema -(`src/src/lib/manifest/schema.ts`). Validation failures report the source file, -the offending property, the expected shape, and a remediation hint. +Every project publishes its catalogue record at `.config/purview-docs.yml` in its own repository +(ADR 0013), which the site reads at build time from that repository's default branch, so a record +changes in the same pull request as the project it describes. Records a project does not own yet live +under `src/src/data/projects/` — a project-owned record wins when both exist — and +`src/src/data/external-projects.yml` holds the collaborations the organisation does not own. + +Everything is validated at build time by a typed Zod schema +(`src/src/lib/manifest/schema.ts`). Validation failures name the record's owner, the +offending property, the expected shape, and a remediation hint. ### Adding a new Purview-Dev project -1. Add a record at `src/src/data/projects/.yml` with a unique `id`, `name`, +1. Add the record at `.config/purview-docs.yml` in the project's repository (or under + `src/src/data/projects/.yml` here, until the project owns one) with a unique `id`, `name`, `shortDescription`, `description`, `repository` (a purview-dev repo), `category`, `status`, and optional `order`. Set `experimental: true` for an exploratory project — it is a flag orthogonal to `status` (ADR 0004). diff --git a/docs/decisions/0013-project-owned-manifests.md b/docs/decisions/0013-project-owned-manifests.md new file mode 100644 index 0000000..2389efa --- /dev/null +++ b/docs/decisions/0013-project-owned-manifests.md @@ -0,0 +1,102 @@ +# ADR 0013 — Project-owned catalogue records + +- Status: accepted +- Date: 2026-11-15 + +## Context + +ADR 0005 split the catalogue into one file per project, `src/src/data/projects/.yml`, and the +split worked: a project's history and review are self-contained, and two concurrent additions no +longer conflict. What it did not change is **who owns the words**. + +Every one of those files is written and reviewed here, in `purview-dev/purview-dev`, by the site +maintainers, while the project it describes lives in another repository and moves without asking. +That is a drift engine with no detector: `zodsharp`'s record still listed `net8.0` and `net9.0` two +releases after the project dropped them, and its `status`, `docs.channels` and package descriptions +are all facts the project knows better than the site does. Correcting any of it is a cross-repository +pull request, which is exactly the friction that makes a record stale in the first place. + +Everything else the site reads for a project is already pulled from the project at build time — the +release data, the documentation tree, the agent skills, the mirrored assets — each with a cache under +`src/.cache/` and a committed fixture under `src/fixtures/` as the offline fallback. The catalogue is +the one input that is still copy-pasted in. + +## Decisions + +### 1. `.config/purview-docs.yml`, published by the project + +A project repository publishes its catalogue record at `.config/purview-docs.yml`: the same record, +the same fields, one file, no wrapper. A repository that publishes the file is a catalogue project; +a repository that does not is not one, and no list anywhere else says which is which. + +### 2. Discovery is the organisation's repository list + +`sync-manifests` lists the `purview-dev` organisation's repositories (one API call, paged) and tries +`raw.githubusercontent.com////.config/purview-docs.yml` for each. A 404 +is not an error: it means that repository is not a catalogue project. Adding a project to the site is +therefore one file in the project's repository and no pull request here; removing it is deleting the +file. + +The record is read at the **default branch**, the same source and ref the documentation mirror uses, +so the site shows what the project actually publishes rather than what a pull request once said. + +### 3. A project's record wins, and the clash is reported + +`readRawManifest()` still reads `src/src/data/projects/*.yml`, and merges the project-owned records +over them: same id means the owner's record wins. This is the migration path — moving a record is a +change in the project repository plus the deletion of the local copy — and it means a project with no +published record keeps working exactly as before. + +The clash is not silent. `readRawManifest()` reports the ids declared twice, and `just check-projects` +prints an observation naming the local file to delete. It is an observation rather than a blocker +because the move is two pull requests in two repositories and the site must not fail in the gap +between them. + +### 4. `.config/` rather than a top-level file + +The record is site plumbing, not project source, and `.config/` is where a project already keeps its +other tool configuration (`lefthook.yml`, `dotnet-tools.json`, `purview-build.json`). One file, one +purpose, out of the way of the project's own documentation. + +### 5. The same cache and fixture model as the release data + +`sync-manifests` writes `src/.cache/manifests/manifests.json`, and `just refresh-fixtures` writes +`src/fixtures/manifests/index.json`. `getManifestIndex()` reads the cache, then the fixture, and +never performs network I/O, so rendering is unaffected and an offline build still resolves the whole +catalogue. `DATA_MODE` selects the source exactly as it does for releases: `live` always fetches, +`cache` and `fixture` never do, and `auto` prefers the cache. + +The fixture is a snapshot, not a second source of truth: a record that changed in its project +repository is picked up by the next `just data-sync` (or `just refresh-fixtures`). + +### 6. The `$schema` hint stays advisory + +The record may open with a `$schema` pointing at this repository's schema module. It is an editor +affordance, as ADR 0005 §5 says, and the enforcing validation remains `loadProjects()` here plus +`just check-projects`. A project-owned record names the schema by absolute URL, because the relative +path it used to carry resolves to nothing from another repository. + +### 7. Validation failures name the owner + +`parseManifest()` takes the provenance of each record, so a failure reads +`projects[zodsharp] (purview-dev/zodsharp (.config/purview-docs.yml at main))` rather than naming a +file that does not exist here. A schema error in a project-owned record is a build failure with the +repository named: the project owns the record, so it owns fixing it. + +## Consequences + +- The catalogue is complete without this repository holding any project's words. What is left here is + `src/src/data/external-projects.yml` (collaborations, which are not ours to own) and the records of + projects that have not migrated. +- Editorial fields — `status`, `featured`, `order`, `category`, the docs channels and the redirects — + move to the project with the rest of the record: the record is the project's, whole. +- The site's build now depends on files it does not control. A malformed record fails the build with + the repository named, and the fetch reports *every* unreadable record at once rather than skipping + it, because a catalogue that silently lost a project is worse than a failed build. +- `just fix-projects` can no longer auto-fix a project-owned record: the observation is printed with + the repository to edit, and the write to a local file is skipped. +- Discovery is organisation-wide, so a new repository that publishes a record appears on the site on + the next build. That is the intent: the organisation's repositories are the catalogue's scope. +- The record is read at the default branch while the documentation mirror still honours per-channel + refs (`docs.channels`), so a project that publishes docs from a tag keeps its record at the head of + the branch. diff --git a/src/fixtures/manifests/index.json b/src/fixtures/manifests/index.json new file mode 100644 index 0000000..474fcdf --- /dev/null +++ b/src/fixtures/manifests/index.json @@ -0,0 +1,1530 @@ +{ + "schema": 1, + "retrievedAt": "2026-11-15T10:12:08.054Z", + "manifests": [ + { + "repository": "purview-dev/architests", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "architests", + "name": "Architests", + "shortDescription": "Enforce a repository's architecture policy as TUnit tests.", + "description": "Architecture tests for .NET. A repository declares its responsibilities and the dependency directions they may and may not use in a policy file, then derives one test class from PurviewArchitectureTests and gets the standard rule set as separate TUnit tests. The project-level rules read declared ProjectReferences; the type-level rule reads the compiled assemblies' metadata, so a reference that only arrives transitively or through a package is caught too, and nothing is loaded or executed. The set covers dependency direction, sibling independence, composition boundaries, forbidden packages and framework references, cycles, test references and project naming, with reviewed per-project waivers and an extension point for bespoke rules.", + "origin": "The standard architecture checks were being written into each repository's own test project, so the same dependency-direction and forbidden-reference rules existed in several places and drifted apart. Defining them once — the policy as data, the rule set as a package — means a repository states its architecture rather than re-deriving the tests, and the schema and the rules version together.", + "useWhen": "You have an agreed layering — domain, application, infrastructure, composition — and want it held by the build rather than by review: at the project-reference level and at the type level, including dependencies that arrive transitively or through a package.", + "avoidWhen": "Your architecture is still moving or the layering is not agreed, so a failing dependency rule would be noise rather than a decision — or you need a single repository-specific assertion that a few lines in a test express more directly than a policy file.", + "repository": "purview-dev/architests", + "category": "developer-tooling", + "status": "stable", + "order": 85, + "docs": { + "source": "github-path", + "path": "docs" + }, + "targetFrameworks": [ + "net10.0", + "net11.0" + ], + "packages": [ + { + "id": "Purview.Architecture.Testing", + "description": "The policy reader, project and assembly graph, rule evaluator, and the TUnit base class.", + "primary": true + } + ], + "related": [ + "engineering-playbook", + "build-sdk" + ], + "useCases": [ + { + "audience": "developer", + "title": "The whole rule set from a policy file and one derived class", + "scenario": "You want your layering enforced by the build, but you do not want to hand-write the same dependency-direction and forbidden-reference tests in every repository.", + "code": "// .config/architecture-policy.json declares the responsibilities.\n// This is the entire test suite.\n[InheritsTests]\npublic sealed class ArchitectureTests : PurviewArchitectureTests;\n", + "language": "csharp", + "outcome": "One policy file plus one derived test class is the whole suite. Each rule is a separate test, so a failure names the rule rather than collapsing the set into one assertion.", + "evidence": "The base class ships twelve rule ids as separate [Test]s — graph discovery, naming, discouraged name, dependency matrix, assembly matrix, sibling independence, composition boundary, forbidden package, forbidden framework, cycle, test reference and waiver integrity — plus a schema-validation test that runs first. [InheritsTests] is required: without it TUnit discovers nothing, the run is green and nothing is enforced, which TUnit's own analyzer reports as TUnit0030.", + "docsPage": "getting-started" + }, + { + "audience": "developer", + "title": "Catch a type-level dependency a ProjectReference never shows", + "scenario": "A project file only shows declared ProjectReferences. A type that arrives transitively through another project, or through a package, is invisible to a project-level check.", + "code": "\"assemblyRules\": {\n \"enabled\": true,\n \"assemblyRoots\": [],\n \"assemblyGlobs\": [\"*.dll\"]\n}\n", + "language": "json", + "outcome": "The same mayDependOn/mustNotDependOn matrix is applied to the types each compiled assembly actually references. An empty assemblyRoots scans the test output directory, which already holds every project the test project references.", + "evidence": "The reader opens each assembly with System.Reflection.Metadata and walks the TypeReference table — nothing is loaded, executed, or resolved through a probing path, so a type initialiser never runs. Enabling the rule with no production assemblies found is a failure, not a silent pass.", + "docsPage": "type-level-rules" + }, + { + "audience": "architect", + "title": "A dependency the policy is silent about is a violation, not permission", + "scenario": "Your layering is agreed and documented, and you want a reference that points the wrong way to fail the build rather than erode the design one reasonable-looking reference at a time.", + "code": "{\n \"version\": 2,\n \"sourceRoots\": [\"src\"],\n \"responsibilities\": [\n {\n \"name\": \"Domain\",\n \"category\": \"domain\",\n \"purpose\": \"The domain model, its invariants and its rules.\",\n \"mayDependOn\": [],\n \"mustNotDependOn\": [\"Application\", \"Persistence\", \"Composition\"]\n }\n ]\n}\n", + "language": "json", + "outcome": "The matrix is applied three ways: the same responsibility is always allowed, mustNotDependOn is a violation, and a reference the matrix neither permits nor forbids is also a violation — so a gap in the policy is surfaced instead of passing.", + "evidence": "A project name is classified by its first segment only, so Persistence.SqlServer and Persistence follow the same rules and qualification is a naming choice rather than a different set of rules.", + "docsPage": "policy-reference" + }, + { + "audience": "team-lead", + "title": "A reviewed waiver instead of switching a rule off", + "scenario": "One project legitimately departs from the architecture policy, and you do not want to answer that by disabling the rule for the whole repository.", + "code": "{\n \"waivers\": [\n {\n \"project\": \"Persistence.Legacy\",\n \"mapsTo\": \"Persistence\",\n \"rules\": [\"forbiddenPackage\"],\n \"reason\": \"The legacy EF6 store is being replaced and still needs EntityFramework.\",\n \"reviewedOn\": \"2026-10-16\"\n }\n ]\n}\n", + "language": "json", + "outcome": "The departure is per project, carries a reason and a review date, keeps every other rule in force, and is itself checked. SkipRule opts a whole repository out with no record, so a waiver is the narrower choice.", + "evidence": "Any rule id may be waived, including siblingIndependence and assemblyDependencyMatrix, but an unknown id is a waiverIntegrity failure — a typo cannot silently excuse nothing — and only graphDiscovery and waiverIntegrity are not waivable.", + "docsPage": "policy-reference" + }, + { + "audience": "contributor", + "title": "Add a bespoke rule to the same reporting and waiver model", + "scenario": "You need a repository-specific check — a banned API, a required convention — and do not want a second architecture framework to maintain alongside the standard set.", + "code": "[InheritsTests]\npublic sealed class ArchitectureTests : PurviewArchitectureTests\n{\n protected override IReadOnlyList AdditionalRules => [new NoConsoleLoggingRule()];\n\n sealed class NoConsoleLoggingRule : IArchitectureRule\n {\n public string Rule => \"noConsoleLogging\";\n\n public IReadOnlyList Evaluate(ArchitectureContext context) =>\n context.Projects.Values\n .Where(project => !project.IsTestProject)\n .Select(project => new ArchitectureViolation(Rule, project.Name, \"Console logging is banned here.\"))\n .ToArray();\n }\n}\n", + "language": "csharp", + "outcome": "An additional rule runs as its own test, honours SkipRule by its rule id, and is excused by a matching waiver without any extra plumbing — the same reporting the built-in rules use.", + "evidence": "The evaluator takes the parsed policy, the project graph and the assemblies as constructor arguments, so a rule is testable as a small in-memory fixture rather than a repository on disk — which is how the package's own rules are tested.", + "docsPage": "extending" + } + ] + } + }, + { + "repository": "purview-dev/aspire-resourcekit", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "aspire-resourcekit", + "name": "Aspire ResourceKit", + "shortDescription": "Strongly typed, source-generated resource kits for .NET Aspire.", + "description": "A source-generator-powered framework for structuring .NET Aspire AppHost resource composition as strongly typed, test-friendly classes. Generated host wiring, typed options, and enablement toggles keep large AppHosts maintainable and discoverable.", + "origin": "Large Aspire AppHosts repeatedly accumulated procedural resource wiring and configuration, creating a need for a typed, testable way to package those conventions.", + "useWhen": "Your Aspire AppHost has reusable resource groups, configuration, or enablement rules that should be strongly typed, discoverable, and testable.", + "avoidWhen": "Your AppHost is small and direct resource declarations remain clearer than introducing a resource-kit abstraction.", + "repository": "purview-dev/aspire-resourcekit", + "category": "aspire", + "status": "stable", + "order": 50, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net10.0" + ], + "packages": [ + { + "id": "Purview.Aspire.ResourceKit", + "description": "Runtime and source generator for resource kits.", + "primary": true + } + ], + "useCases": [ + { + "audience": "architect", + "title": "Typed, testable resource groups in a large AppHost", + "scenario": "A large Aspire AppHost accumulates procedural resource wiring and configuration that is hard to test and easy to misconfigure.", + "code": "[HostKit]\npartial class ShopHostKit;\n\n[ResourceDefinition(\"api\")]\npartial class ApiResourceKit\n{\n protected override IResourceBuilder BuildResource(\n IDistributedApplicationBuilder builder)\n => builder.AddProject(Name);\n}\n", + "language": "csharp", + "outcome": "Resource definitions become strongly typed, source-generated classes with generated host wiring and typed options.", + "evidence": "One [HostKit] plus one [ResourceDefinition] per resource replaces procedural AppHost code, and the analyzer validates the wiring at compile time.", + "docsPage": "examples" + }, + { + "audience": "team-lead", + "title": "Configure and toggle resources without editing the AppHost", + "scenario": "You want enablement rules and configuration to be declarative and discoverable instead of buried in the AppHost entry point.", + "outcome": "Typed options and enablement toggles are generated for each resource kit, so behaviour is configured rather than coded.", + "evidence": "Resource kits can be unit tested with the testing helpers, independent of a running AppHost.", + "docsPage": "configuration-and-options" + } + ] + } + }, + { + "repository": "purview-dev/aspirec4", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "aspirec4", + "name": "AspireC4", + "shortDescription": "Live LikeC4 architecture diagrams from the Aspire resource graph.", + "description": "An Aspire extension that generates live LikeC4 architectural diagrams from the Aspire resource graph, with a Roslyn source generator for compile-time validation of tags, kinds, groups, and metadata.", + "origin": "Aspire already holds a useful model of a distributed application, so manually maintaining a separate architecture diagram was repetition that could be removed.", + "useWhen": "You use .NET Aspire and want live LikeC4 diagrams derived from the resource graph, with compile-time checks for architectural metadata.", + "avoidWhen": "You do not use Aspire, need a manually curated architecture model, or require diagrams that intentionally differ from the running application topology.", + "repository": "purview-dev/aspirec4", + "category": "aspire", + "status": "stable", + "order": 55, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net8.0" + ], + "packages": [ + { + "id": "AspireC4.Hosting", + "description": "Aspire hosting extension for the AspireC4 plugin, generating a dynamic LikeC4 architecture diagram for your Aspire application.", + "primary": true + } + ], + "useCases": [ + { + "audience": "developer", + "title": "A live architecture diagram with three lines of code", + "scenario": "You already describe your distributed application in Aspire and do not want to maintain a separate architecture diagram that drifts from reality.", + "code": "var builder = DistributedApplication.CreateBuilder(args);\n\nbuilder.AddAspireC4();\n\nbuilder.Build().Run();\n", + "language": "csharp", + "outcome": "AspireC4 writes the generated LikeC4 model, starts the LikeC4 sidecar, and refreshes the diagram whenever the Aspire application changes.", + "evidence": "The diagram is derived from the running resource graph, so it cannot silently fall out of date the way a hand-drawn one can.", + "docsPage": "dashboard-integration" + }, + { + "audience": "architect", + "title": "Validate architectural metadata at compile time", + "scenario": "You want tags, kinds, groups, and metadata in your architecture model checked before the application even runs.", + "outcome": "A Roslyn source generator validates the architectural metadata while the AppHost compiles.", + "evidence": "Architectural metadata mistakes fail the build instead of surfacing in a diagram nobody reads.", + "docsPage": "generated-output" + } + ] + } + }, + { + "repository": "purview-dev/astroc4", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "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.", + "useWhen": "Your documentation is an Astro/Starlight site and the architecture it describes is already, or should be, a LikeC4 model in the repository: you want the diagram and the prose to be reviewed together, and code fences in the LikeC4 language to be coloured without owning an ec.config.mjs.", + "avoidWhen": "Your site is not Astro (both entry points compile the model through LikeC4's Vite plugin and ship React islands), or the architecture diagram is drawn once and does not need to stay in step with the code — a static image is cheaper than a model, a compiler and a browser island.", + "repository": "purview-dev/astroc4", + "category": "developer-tooling", + "status": "preview", + "order": 75, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "redirects": { + "architecture": "contributing/architecture", + "components": "guide/components", + "configuration-reference": "guide/configuration-reference", + "fences": "guide/fences", + "getting-started": "guide/getting-started", + "icons": "guide/icons", + "internationalization": "guide/internationalization", + "local-development": "contributing/local-development", + "repository-ci-cd": "contributing/repository-ci-cd", + "syntax-highlighting": "guide/syntax-highlighting" + } + }, + "skills": true, + "packages": [ + { + "id": "@purview-dev/astroc4", + "registry": "npm", + "description": "The Starlight plugin, the plain-Astro integration, the fence transform, the grammar pipeline and the Astro components.", + "primary": true + } + ], + "related": [ + "aspirec4", + "engineering-playbook" + ], + "acknowledgments": [ + { + "name": "LikeC4", + "url": "https://github.com/likec4/likec4", + "description": "The C4 modelling language, compiler and renderer the plugin embeds; the highlighting grammar is derived at build time from its Langium language definition." + } + ], + "useCases": [ + { + "audience": "developer", + "title": "A diagram and the prose around it in the same diff", + "scenario": "A page explains a request path, and the diagram beside it lives in a design tool that nobody updates when the path changes, so the two disagree and a reviewer cannot see it.", + "code": "````mdx\n---\ntitle: Request path\n---\n\n```likec4 title=\"Request path\" height=360\nspecification { element box }\nmodel {\n browser = box 'Browser'\n api = box 'API'\n store = box 'Postgres'\n browser -> api 'GET /orders'\n api -> store 'select'\n}\nviews { view index { include * } }\n```\n````\n", + "language": "mdx", + "outcome": "The diagram is the page: the fence is compiled and laid out during the build, the layout is passed to the island as serialised JSON, and a change to the model is a line in the pull request a reviewer can read next to the prose.", + "evidence": "The fence runs LikeC4.fromSource plus layoutedModel at build time, so nothing is laid out in the browser; a typo fails astro build with the file name and parser message rather than shipping a blank frame, and layouts are memoised by a hash of the snippet so a page re-rendered on every dev edit pays for it once. The same fence in a .md page stays a code block deliberately, because Astro cannot put a component there." + }, + { + "audience": "developer", + "title": "The same diagrams in a plain Astro site, without Starlight", + "scenario": "The documentation site is plain Astro rather than Starlight, so a Starlight plugin would be inert there and the diagrams have no way to reach the page.", + "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." + }, + { + "audience": "developer", + "title": "Highlighting that follows LikeC4, with no ec.config.mjs", + "scenario": "You want ```c4 and ```likec4 fences coloured in your docs, but Shiki has no LikeC4 grammar and the community TextMate file is missing the shapes and keywords upstream added this year.", + "code": "// astro.config.mjs — there is no ec.config.mjs anywhere in the site\nimport { defineConfig } from 'astro/config';\nimport starlight from '@astrojs/starlight';\nimport react from '@astrojs/react';\nimport astroc4 from '@purview-dev/astroc4';\n\nexport default defineConfig({\n integrations: [\n starlight({ plugins: [astroc4({ highlighting: { ref: 'v1.60.0' } })] }),\n react(),\n ],\n});\n", + "language": "js", + "outcome": "The plugin derives a TextMate grammar from likec4/likec4's Langium language definition and injects it into Starlight's Expressive Code options from the config:setup hook, so every LikeC4 fence is coloured and an existing ec.config.mjs keeps its own languages untouched.", + "evidence": "Only the word lists are generated; the structure (comments, triple-quoted strings, #tag versus #hex, tech:astro icons, -[https]-> connectors) is a curated layer on top. The difference is testable: ElementShape gained agent after v1.59.4, so a build pinned to that tag paints agent as a plain identifier while main paints it as a shape. Expressive Code concatenates shiki.langs, which is why a site with its own grammar ends up with both." + }, + { + "audience": "architect", + "title": "One model in the repository, many diagram views in the docs", + "scenario": "Several documentation pages describe different slices of the same system, and you want them to read from one model so a change to a dependency cannot leave three diagrams telling three stories.", + "code": "```mdx\n---\ntitle: Deployment\n---\n\nimport LikeC4View from '@purview-dev/astroc4/components/LikeC4View.astro';\n\n\n```\n", + "language": "mdx", + "outcome": "The .c4 model lives in src/likec4 and each page selects a view of it; the model is compiled once by LikeC4's Vite plugin, and every page hydrates the same islands, so a view cannot describe a system the model does not contain.", + "evidence": "The plugin compiles every likec4.config.json project under the site root into likec4:model, likec4:icons and likec4:projects virtual modules, and the first project found is the default for a view that omits projectId — which is also the failure mode, since a vendored example model can silently become the default. An unresolvable element kind fails the build instead of rendering a partial diagram." + }, + { + "audience": "team-lead", + "title": "Prove the diagrams actually hydrate before calling the docs built", + "scenario": "A static build exits 0 even when every island fails to hydrate, so the pipeline is green and the published page shows empty frames.", + "code": "bun run build\nbun scripts/smoke.ts http://localhost:4321\nbun run test:site\n", + "language": "shell", + "outcome": "The browser smoke test and the packed-consumer build are the evidence: one drives a real page and checks hydration, icons, highlighting and translations, the other installs the tarball into a throwaway Starlight site so publishing mistakes surface before npm does.", + "evidence": "The smoke test asserts at least four distinct colour variables per highlighted block, counts prerendered pack icons and icons, and fails on a file:// URL in an — the build-machine path that LikeC4's imageAliases bakes into the bundle. test:site catches the cases the playground cannot see: a file missing from files, an exports subpath pointing at an unpublished file, or an undeclared peer dependency.", + "docsPage": "troubleshooting" + }, + { + "audience": "contributor", + "title": "Regenerate the grammar instead of hand-editing it", + "scenario": "Upstream LikeC4 adds a shape or a keyword, and the highlighting has to follow without someone patching a TextMate JSON file and hoping the next release does not overwrite it.", + "code": "bun run grammar:sync # from main\nbun run grammar:sync --ref v1.60.0 # or pin the tag you ship against\nbun run grammar:check # fail if the committed snapshot is stale\n", + "language": "shell", + "outcome": "The Langium snapshot and the TextMate grammar are generated artefacts: the working tree says so, grammar:check fails when they drift from the pinned ref, and the next upstream addition reaches highlighting without a code change.", + "evidence": "src/grammar/likec4.tmLanguage.json is re-derived from the committed Langium text on every run (single-digit milliseconds), and snapshot.test.ts re-derives it again and compares, so a change to the derivation that is not followed by a regeneration fails bun run test. Because the icon packs come from LikeC4's LIB_ICON terminal, a pack upstream adds is highlighted and rendered without an edit here either." + } + ] + } + }, + { + "repository": "purview-dev/build", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "build", + "name": "Build", + "shortDescription": "The shared build, test, and release system for purview-dev.", + "description": "The shared build/test/release system for the purview-dev organisation. A Modular Pipelines based .NET tool packaged as a pinned dotnet tool, exposed through a GitHub composite action and thin reusable workflows. Consuming repositories own configuration; they do not own pipeline source code.", + "origin": "Maintaining near-identical build, test, pack, and release logic across repositories turned the pipeline itself into reusable tooling.", + "useWhen": "You maintain a Purview repository and want the shared, centrally versioned build and release conventions used across the organisation.", + "avoidWhen": "Your repository is outside that convention set or needs a substantially different pipeline whose lifecycle should remain independent.", + "repository": "purview-dev/build", + "category": "build-tooling", + "status": "stable", + "order": 60, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net10.0" + ], + "install": "dotnet-tool", + "packages": [ + { + "id": "Purview.Build", + "description": "Pinned dotnet tool implementing the shared pipeline.", + "primary": true + } + ], + "assets": [ + { + "path": "purview-build.schema.json", + "output": "schemas/purview-build.json", + "description": "The purview-build.json configuration schema, served from a stable purview.dev URL." + } + ], + "useCases": [ + { + "audience": "team-lead", + "title": "One reusable pipeline for every repository", + "scenario": "You maintain several repositories that each repeat the same build, test, pack, and release logic, and the copies drift apart.", + "code": "# .github/workflows/pr.yml\njobs:\n build:\n uses: purview-dev/build/.github/workflows/purview-build.yml@main\n secrets: inherit\n", + "language": "yaml", + "outcome": "Consumers reference the reusable workflow or composite action and configure behaviour with purview-build.json instead of owning pipeline source.", + "evidence": "Pipeline code lives in one repository; a consuming repository is a short workflow file plus configuration.", + "docsPage": "repository-ci-cd" + }, + { + "audience": "contributor", + "title": "Dogfood the same pipeline the organisation uses", + "scenario": "You want local commands, pull-request CI, and releases to run the exact same tool and conventions, rather than three approximations.", + "outcome": "The pipeline is a Modular Pipelines .NET tool packaged as a pinned dotnet tool, callable from a composite action, reusable workflows, or the local command line.", + "evidence": "Purview's own repositories use the published pipeline, so the tool is exercised on every build.", + "docsPage": "pipeline-modules" + } + ] + } + }, + { + "repository": "purview-dev/build-sdk", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "build-sdk", + "name": "Build SDK", + "shortDescription": "Convention-driven MSBuild SDK for .NET project defaults.", + "description": "A reusable MSBuild SDK NuGet package that delivers standardised .NET project defaults, code-style enforcement, test-framework wiring, and Central Package Management integration. Install it once per repo; every project beneath the repo root inherits everything automatically.", + "origin": "Repeating project properties, analyzers, test wiring, and package-management conventions in every repository made a centrally maintained MSBuild SDK the simpler option.", + "useWhen": "You want Purview's standard .NET project defaults applied consistently across an entire repository from one versioned SDK declaration.", + "avoidWhen": "Your repository follows different conventions or needs project-by-project control over the settings the SDK intentionally standardises.", + "repository": "purview-dev/build-sdk", + "category": "build-tooling", + "status": "stable", + "order": 70, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "msbuild" + ], + "install": "msbuild-sdk", + "packages": [ + { + "id": "Purview.BuildSdk", + "description": "MSBuild SDK for standardised project defaults.", + "primary": true + } + ], + "useCases": [ + { + "audience": "team-lead", + "title": "Apply repository-wide defaults from one declaration", + "scenario": "You want standard .NET project defaults, code-style enforcement, test wiring, and central package management without repeating the same properties in every project.", + "code": "{\n \"msbuild-sdks\": {\n \"Purview.BuildSdk\": \"1.0.0\"\n }\n}\n", + "language": "json", + "outcome": "Install the SDK once via global.json and Directory.Build.props; every project beneath the repository root inherits everything automatically.", + "evidence": "One versioned SDK declaration replaces per-project property groups, so conventions are upgraded in one place.", + "docsPage": "configuration-reference" + }, + { + "audience": "contributor", + "title": "Bootstrap a new repository", + "scenario": "You are starting a repository and want the organisation's conventions in place before the first project exists.", + "outcome": "The SDK can bootstrap a global.json at the repository root when one is missing, then applies project-type detection, analyzers, and test wiring.", + "evidence": "Repository bootstrap, analyzers, and testing wiring are documented and generated, not copied between repos by hand.", + "docsPage": "repository-bootstrap" + } + ] + } + }, + { + "repository": "purview-dev/containers", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "containers", + "name": "Containers", + "shortDescription": "Throwaway Linux containers for .NET integration tests — on WSL Containers with no Docker installation, or on Docker.", + "description": "A Testcontainers-style library for .NET with one API and two interchangeable backends: Microsoft WSL Containers (WSLC) with no Docker installation, or Docker through Testcontainers. Containers are created through backend-neutral abstractions (Purview.Containers.Core) and the backend is resolved at run time, so the same test code runs on WSLC (Purview.Containers.Wsl) or Docker (Purview.Containers.Docker) unchanged. The WSLC backend talks to the WSLC managed C# API directly — no wslc.exe, no docker CLI, no Docker.DotNet. Typed service modules add PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, and NATS, each with its own defaults, configuration, readiness wait strategy, and connection-string helper. The umbrella package Purview.Containers brings the abstractions plus both backends in a single reference.", + "origin": "Integration tests that use real infrastructure on Windows needed a Docker daemon installed and running first. WSL Containers makes the container runtime a Windows feature, so the same throwaway-container workflow could be built straight on its managed API — and the same abstractions could fall back to Docker wherever WSLC is not available, which is why the library grew a portable net10.0 facade and a Docker backend rather than staying Windows-only.", + "useWhen": "You want real PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, or NATS instances in integration tests, and you want the same suite to run on WSL Containers on a Windows developer machine and on Docker in CI without changing a line of test code.", + "avoidWhen": "You need a container runtime other than WSL Containers or Docker, or you require API stability: the public API, defaults, and packaging rules can change between prereleases and there is no production support guarantee.", + "repository": "purview-dev/containers", + "category": "developer-tooling", + "status": "preview", + "experimental": true, + "order": 90, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "exclude": [ + "_Sidebar.md", + "Home.md" + ] + }, + "targetFrameworks": [ + "net10.0", + "net10.0-windows10.0.19041.0", + "net11.0", + "net11.0-windows10.0.19041.0" + ], + "packages": [ + { + "id": "Purview.Containers", + "description": "The umbrella — references the abstractions and both backends, so one reference runs the same tests on WSLC on Windows and Docker elsewhere.", + "primary": true + }, + { + "id": "Purview.Containers.Core", + "description": "Backend-neutral abstractions — the container contract, builders, wait strategies, images, mounts, networking, diagnostics, and backend selection." + }, + { + "id": "Purview.Containers.Wsl", + "description": "WSL Containers backend — sessions, images, ports, mounts, exec, logs, and diagnostics for WSLC; a portable facade plus the Windows implementation.", + "targetFrameworks": [ + "net10.0", + "net10.0-windows10.0.19041.0", + "net11.0", + "net11.0-windows10.0.19041.0" + ] + }, + { + "id": "Purview.Containers.Docker", + "description": "Docker backend — the same containers on any reachable Docker daemon, driven by Testcontainers." + }, + { + "id": "Purview.Containers.PostgreSql", + "description": "PostgreSQL module — defaults, configuration, pg_isready readiness, and Npgsql connection string." + }, + { + "id": "Purview.Containers.Redis", + "description": "Redis module — defaults, configuration, redis-cli ping readiness, and connection string." + }, + { + "id": "Purview.Containers.MsSql", + "description": "SQL Server module — defaults, licence acceptance, configuration, and connection string." + }, + { + "id": "Purview.Containers.MySql", + "description": "MySQL module — defaults, configuration, readiness wait strategy, and connection string." + }, + { + "id": "Purview.Containers.RabbitMq", + "description": "RabbitMQ module — defaults, credentials, configuration, and AMQP connection string." + }, + { + "id": "Purview.Containers.Azurite", + "description": "Azurite module — defaults, account key, and Azure Storage connection string." + }, + { + "id": "Purview.Containers.Nats", + "description": "NATS module — defaults, configuration, and client endpoint." + } + ], + "acknowledgments": [ + { + "name": "Testcontainers for .NET", + "url": "https://github.com/testcontainers/testcontainers-dotnet", + "description": "The Docker backend is driven by Testcontainers and the module connection-string shapes follow it; Purview.Containers is not affiliated with or endorsed by the Testcontainers project." + }, + { + "name": "Microsoft WSL Containers", + "url": "https://www.nuget.org/packages/Microsoft.WSL.Containers", + "description": "The managed C# API behind WSLC that the WSL Containers backend is built against directly, with no wslc.exe or docker CLI." + } + ], + "useCases": [ + { + "audience": "developer", + "title": "The same test on WSL Containers or Docker", + "scenario": "Your integration suite needs real infrastructure, but the machines it runs on differ: a Windows developer laptop with WSL Containers and a Linux CI runner with a Docker daemon.", + "code": "await using var container = new ContainerBuilder()\n .WithImage(\"docker.io/library/redis:latest\")\n .WithPortBinding(6379, assignRandomHostPort: true)\n .WithWaitStrategy(Wait.ForTcpPort(6379))\n .Build();\n\nawait container.StartAsync();\nushort port = container.GetMappedPublicPort(6379);\n", + "language": "csharp", + "outcome": "The test never names a backend. Automatic selection prefers WSLC where it is usable and falls through to Docker everywhere else; PURVIEW_CONTAINERS_BACKEND pins one (wsl or docker) when a job should fail loudly instead of falling back.", + "evidence": "One API, two backends: the same builder, wait strategies, and connection-string helpers run on both Purview.Containers.Wsl and Purview.Containers.Docker with no code change.", + "docsPage": "backends" + }, + { + "audience": "developer", + "title": "Zero-config tests that pick a backend themselves", + "scenario": "You want real PostgreSQL and Redis in your tests and would rather not choose a container runtime, add a backend package explicitly, or write any registration or environment configuration.", + "code": "await using var postgres = new PostgreSqlBuilder().WithDatabase(\"app\").Build();\nawait postgres.StartAsync(); // waits for pg_isready\n\nawait using var connection = new NpgsqlConnection(postgres.GetConnectionString());\nawait connection.OpenAsync();\n", + "language": "csharp", + "outcome": "Add the umbrella Purview.Containers to a plain net10.0 project: each backend package's buildTransitive assets generate the registration in your assembly, so WSLC is used on a Windows machine and Docker everywhere else with no code or configuration.", + "evidence": "Each backend package ships buildTransitive assets that generate a module initializer in the consumer's assembly, so no registration line and no environment variable are required; those assets flow transitively through the umbrella.", + "docsPage": "using-in-your-tests" + }, + { + "audience": "developer", + "title": "A typed service module instead of a bare image", + "scenario": "You need a throwaway PostgreSQL (or Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS) and do not want to look up its image, port, environment, and readiness probe every time.", + "code": "await using var postgres = new PostgreSqlBuilder()\n .WithDatabase(\"tests\")\n .WithPassword(\"postgres\")\n .Build();\n\nawait postgres.StartAsync(); // returns once pg_isready succeeds\n", + "language": "csharp", + "outcome": "The module supplies the default image, port mapping, and readiness wait strategy, so StartAsync() returns once the instance is genuinely ready, and GetConnectionString() points at the mapped host port — the same shape Testcontainers modules use.", + "evidence": "Seven service modules ship (PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS), and a module contributes only its image, ports, environment, wait strategy, and connection string — never the shared runtime.", + "docsPage": "modules" + }, + { + "audience": "architect", + "title": "One Windows prerequisite, Docker in CI", + "scenario": "You want integration tests that use real infrastructure on Windows developer machines and CI agents, without making Docker Desktop a requirement of the minimum Windows toolchain.", + "code": "foreach (var backend in await ContainerBackends.ProbeAllAsync())\n{\n Console.WriteLine($\"{backend.Name}: usable={backend.IsUsable} version={backend.Version}\");\n}\n", + "language": "csharp", + "outcome": "The abstractions and modules are portable net10.0, so a platform-neutral project binds the WSLC facade on Windows and behaves as Docker-only everywhere else; ProbeAllAsync() reports exactly which runtime a machine has before a test runs.", + "evidence": "Purview.Containers.Wsl ships a portable net10.0 facade and a net10.0-windows10.0.19041.0 implementation, and the repository builds twenty-one throwaway consumer projects to prove the target-framework contract and the PCC0001/PCC0002 guards.", + "docsPage": "consumer-requirements" + }, + { + "audience": "contributor", + "title": "Add a service module", + "scenario": "You want to add a module for another service, or fix one of the existing seven, and need to know exactly what a module is allowed to contribute.", + "outcome": "A module supplies only the default image, ports, environment, its own WithXxx configuration, a wait strategy, and connection-string helpers; the generic builder snapshots the accumulated state into an immutable configuration, so modules never duplicate container runtime infrastructure.", + "evidence": "Every module references Purview.Containers.Core only — never a backend package — which is what lets one module package run on WSLC or Docker, and each module has its own unit and integration test project to prove itself.", + "docsPage": "contributing-modules" + } + ] + } + }, + { + "repository": "purview-dev/dotnet-logging-source-generators", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "dotnet-logging-source-generators", + "name": "Logging Source Generators", + "shortDescription": "Early interface-based logging generation (archived).", + "description": "The original experiment in interface-based logging generation for .NET. Archived and superseded by the Purview Telemetry SourceGenerator, which generates logging together with Activities and Metrics from the same interfaces.", + "origin": "This was the original exploration of interface-driven logging generation and established the approach that later grew into the broader Telemetry SourceGenerator.", + "useWhen": "Use it only when maintaining an existing dependency that cannot yet move to its successor.", + "avoidWhen": "For new work, use Telemetry SourceGenerator instead; this project is archived and no longer actively developed.", + "repository": "purview-dev/dotnet-logging-source-generators", + "category": "source-generation", + "status": "archived", + "supersededBy": "telemetry-sourcegenerator", + "order": 80, + "targetFrameworks": [ + "net6.0", + "net7.0" + ], + "packages": [], + "useCases": [ + { + "audience": "developer", + "title": "Move to the supported successor", + "scenario": "You depend on the original interface-based logging generator and want logging, activities, and metrics generated together.", + "outcome": "Telemetry SourceGenerator generates logging alongside Activities and Metrics from the same interfaces, with DI registration and multi-targeting.", + "evidence": "This project is archived and no longer developed; the successor covers a superset of its behaviour from one interface." + } + ] + } + }, + { + "repository": "purview-dev/engineering-playbook", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev.github.io/main/src/src/lib/manifest/schema.ts", + "id": "engineering-playbook", + "name": "Engineering Playbook", + "shortDescription": "The reusable Purview engineering conventions — repository shape, architecture as tests, verification tiers, and agent enablement.", + "description": "The conventions the Purview projects are built on, written down once with the failure each one prevents, the mechanism that makes it true, and what a smaller repository does instead. It covers how a repository is laid out and named, how the architecture is held by tests that read the compiled assemblies, which checks run in which verification tier, how value objects, schemas and results cross a boundary, how tests are written and where their data comes from, how a repository is made legible to a coding agent, and how its documentation is published. It is documentation-first and ships no library: it holds the conventions, ready-to-copy templates, and a small layered reference implementation whose dependency-direction rules fail the build, so the rules are demonstrated rather than asserted.", + "origin": "The conventions were already real and already enforced, but they were only discoverable by reading the repositories and inferring the pattern from the repetition. That worked while one person held the whole picture and stopped working as soon as a second contributor or a coding agent had to decide which of two plausible patterns was the intended one. Writing them down in one place — with the evidence attached, and scaled so a smaller repository can take the part that fits — turned an oral tradition into something a repository can be pointed at.", + "useWhen": "You are starting a repository that should look and behave like the Purview projects, adopting the SDK into an existing one, or deciding which of the conventions are worth the cost at your size. The playbook's profiles, templates and reference implementation are all meant to be taken in part.", + "avoidWhen": "You want the SDK's own behaviour documented rather than the conventions built on top of it — read the Build SDK's wiki instead — or you are looking for a scaffolding tool: the templates are files to read and copy, not a generator.", + "repository": "purview-dev/engineering-playbook", + "category": "developer-tooling", + "status": "preview", + "experimental": true, + "order": 95, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Home.md", + "exclude": [ + "_Sidebar.md" + ], + "redirects": { + "dependency-versions": "foundations/dependency-versions" + } + }, + "related": [ + "build-sdk", + "containers", + "value-objects", + "results", + "zodsharp" + ], + "useCases": [ + { + "audience": "developer", + "title": "A repository that satisfies every convention on its first build", + "scenario": "You are starting a repository and want the project defaults, code style, test wiring and assembly identity to be right from the first commit, instead of discovering the conventions one review comment at a time.", + "code": "{\n \"sdk\": { \"version\": \"LATEST\", \"allowPrerelease\": false },\n \"msbuild-sdks\": { \"Purview.BuildSdk\": \"LATEST\" },\n \"test\": { \"runner\": \"Microsoft.Testing.Platform\" }\n}\n", + "language": "json", + "outcome": "A pinned SDK plus a `Directory.Build.props` that sets one namespace prefix is the whole of the repository's build configuration. Every project beneath it inherits the target framework, language version, nullable context, analyzers and assembly identity, so a project file is two lines and a test project file is empty. `LATEST` is the playbook's own placeholder for the newest version the runtime supports — the file requires a number, so the snippet shows a lookup rather than a claim that expires with the next release.", + "evidence": "Getting Started walks the steps in the order you would create the files, and every repository-level file has a copy-paste version in the templates folder with a comment explaining the one thing about it that is easy to get wrong.", + "docsPage": "getting-started" + }, + { + "audience": "architect", + "title": "Architecture that fails the build when a dependency points the wrong way", + "scenario": "Your layering is documented and agreed, and you want it to stay true — rather than being eroded one convenient project reference at a time, each of which looks reasonable in isolation.", + "code": "[Test]\npublic async Task Application_GivenItsReferences_DependsOnTheDomainAndNotOnInfrastructure()\n{\n // Arrange\n var application = typeof(ConventionCatalogue).Assembly;\n\n // Act\n var referenced = ReferencedAssemblyNames(application);\n\n // Assert\n await Assert.That(referenced).Contains($\"{RepositoryPrefix}.Domain\");\n await Assert.That(referenced).DoesNotContain($\"{RepositoryPrefix}.Infrastructure\");\n}\n", + "language": "csharp", + "outcome": "The allowed dependency directions are data in a test that reads the compiled assemblies' metadata references, so a reference that points the wrong way fails the build with the offending assembly named — no diagram to keep in step and no separate tool to run.", + "evidence": "The reference implementation's Architecture.UnitTests project asserts four rules against three real assemblies and is built by the same pipeline as everything else. The page also records the two traps found by writing it, including a source generator that emits public types into its own namespace." + }, + { + "audience": "team-lead", + "title": "A verification gate that stays credible", + "scenario": "The pull-request build has started needing a database and four minutes of waiting, and somebody is about to make it optional — at which point nothing is gated at all.", + "code": "{\n \"Build\": {\n \"Solution\": \"src/Acme.slnx\",\n \"TestRoot\": \"src/tests\",\n \"TestPatterns\": \"*UnitTests.csproj\",\n \"TestFilter\": \"/*/*/*/*[Category=Unit]\"\n }\n}\n", + "language": "json", + "outcome": "Tiers are expressed by where a test lives rather than by an attribute: the SDK reads the test project's name suffix and emits the assembly-level category the pipeline filters on, so adding a slow suite keeps it out of the fast tier without editing a filter or remembering an attribute.", + "evidence": "The verification model page documents the shared workflow's inputs, the configuration probe order, and the two ways a repository and the shared workflow quietly disagree about what a green build means — and names the repository that runs its container-backed suites as a second job on the same runner." + }, + { + "audience": "developer", + "title": "One builder for every test's domain content", + "scenario": "You are writing a test, need a domain object, and do not want to spell out a constructor that will change — nor leave the reader guessing which of the values you passed actually matter to the assertion.", + "code": "public static Domain.Convention Convention(\n Domain.ConventionId? id = null,\n string? title = null,\n VerificationTier? tier = null,\n bool? enforcedByBuild = null) =>\n Domain.Convention.Create(\n id ?? ConventionId(),\n title ?? Faker.Lorem.Sentence(4),\n tier ?? Faker.Random.Enum(),\n enforcedByBuild ?? Faker.Random.Bool());\n", + "language": "csharp", + "outcome": "An omitted argument is generated and a supplied argument is used exactly, so a test reads as a list of the values it is actually proving and everything else is realistic without the test saying so. One constructor change is one edit rather than a repository-wide one.", + "evidence": "TestBuilder lives in a shared testing project the SDK references from every test project automatically. The page also explains the two SDK rules that shaped its flat, ungrouped shape, and the value-object exception where a test must name the rejected input itself." + }, + { + "audience": "contributor", + "title": "A repository an agent can work in without hand-holding", + "scenario": "You want a coding agent to make a change that follows the repository's conventions rather than confidently generalising from whichever pattern it found first.", + "code": "| Path | Purpose |\n| -- | -- |\n| src/src/Domain | The reference implementation's value objects and aggregate |\n| src/src/Application | The port and the service that owns the rules |\n| src/tests/Architecture.UnitTests | Dependency-direction rules; a wrong reference fails the build |\n", + "language": "markdown", + "outcome": "AGENTS.md states the purpose, the layout, the conventions and the definition of done, and the build mirrors the SDK's own skills into the repository so the agent-facing guidance tracks the SDK version rather than the repository's memory of it.", + "evidence": "The agent enablement page documents the layout of the agent folder, why the SDK's mirror writes a generated .gitignore that lists exactly the files it owns, and why the guidance that makes a repository obvious to an agent is the same guidance that makes it obvious to a new joiner." + }, + { + "audience": "architect", + "title": "Take only the part of the playbook that fits", + "scenario": "You are convinced by some of the conventions and not others, and you want to know which ones are worth the cost in a repository the size of yours — rather than adopting everything and discovering the ceremony.", + "outcome": "Three profiles — one project, a few layers, several packages — each list what to take and what to leave, and every page ends with an \"at your scale\" section that names the smaller version of the rule explicitly. The templates are mapped to the profile that needs them.", + "evidence": "The playbook also documents what not to adopt early, with the reason each one is more expensive out of order, and a migration order for an existing repository that keeps each step cheap and the build green." + }, + { + "audience": "team-lead", + "title": "Data that crosses a boundary once, and is trusted after that", + "scenario": "Inbound payloads are validated in several places, an identifier is a string in one layer and a type in another, and expected failures are thrown as exceptions that callers catch by message.", + "code": "[Scalar]\npublic readonly partial record struct EmailAddress\n{\n public string Value { get; }\n\n static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!;\n}\n", + "language": "csharp", + "outcome": "A value is a type rather than a primitive, `Create` validates at the boundary and `Hydrate` trusts everything past it, normalisation runs before validation so there is exactly one canonical form, and expected failures are values while exceptional circumstances still throw.", + "evidence": "The contracts page names the three public repositories that implement the rules — source-generated value objects, result types with union errors, and a schema layer that also exports and imports JSON Schema — and shows how a validation result is read rather than parsed." + }, + { + "audience": "contributor", + "title": "Extend the playbook without turning it into a second source of truth", + "scenario": "You have found a convention that is real, enforced and not written down, and you want to add it without duplicating something the SDK already documents.", + "outcome": "Four tests decide whether a rule belongs: it came from a real repository and a real failure, it is reusable at more than one size, it is not the SDK's to state, and it is either enforced or explicitly labelled a review obligation.", + "evidence": "The contributing page also sets the expectations for changing an existing rule — update every page that states it, check the reference implementation still demonstrates it, and re-check whether the enforcement moved between the build and review." + } + ] + } + }, + { + "repository": "purview-dev/event-sourcing", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "event-sourcing", + "name": "Event Sourcing", + "shortDescription": "Aggregate-based event sourcing for .NET across any store.", + "description": "A .NET event sourcing framework for building aggregate-based applications. Provider-agnostic store facades, source-generated aggregates and events, transaction coordination for multi-aggregate saves, queryable snapshots and read models, and storage providers for SQL Server, PostgreSQL, MongoDB, Azure Storage, Azure Cosmos DB, and in-memory.", + "origin": "Aggregate, event, persistence, and transaction patterns kept recurring across applications, so the reusable parts were separated from any one storage provider.", + "useWhen": "Your domain benefits from aggregate-based event sourcing and you want storage choices, snapshots, read models, and transactions behind consistent abstractions.", + "avoidWhen": "A conventional state-based model is sufficient, or your application does not need the operational and modelling trade-offs that come with event sourcing.", + "repository": "purview-dev/event-sourcing", + "category": "application-framework", + "status": "preview", + "featured": true, + "order": 20, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net10.0" + ], + "packages": [ + { + "id": "Purview.EventSourcing", + "description": "Core abstractions, aggregates, facades, transactions, DI, and source generation.", + "primary": true + }, + { + "id": "Purview.EventSourcing.SqlServer", + "description": "Azure SQL / SQL Server event stream and queryable snapshot stores." + }, + { + "id": "Purview.EventSourcing.Postgres", + "description": "PostgreSQL event stream and queryable snapshot stores." + }, + { + "id": "Purview.EventSourcing.AzureStorage", + "description": "Azure Table / Blob event store." + }, + { + "id": "Purview.EventSourcing.MongoDB", + "description": "MongoDB event stream and queryable snapshot stores." + }, + { + "id": "Purview.EventSourcing.CosmosDb", + "description": "Azure Cosmos DB queryable snapshot store." + }, + { + "id": "Purview.EventSourcing.InMemory", + "description": "In-memory event and snapshot stores for local and test scenarios." + }, + { + "id": "Purview.EventSourcing.Validation.FluentValidation", + "description": "FluentValidation adapter for aggregate save-time validation." + }, + { + "id": "Purview.EventSourcing.Validation.ZodSharp", + "description": "Purview.ZodSharp adapter for aggregate save-time validation." + } + ], + "useCases": [ + { + "audience": "developer", + "title": "An aggregate that persists as events", + "scenario": "You want aggregate-based event sourcing without hand-writing the event stream, snapshot, and transaction plumbing.", + "code": "[Aggregate]\npublic partial class OrderAggregate : AggregateBase\n{\n public string CustomerId { get; private set; } = default!;\n public decimal Total { get; private set; }\n\n [Event]\n public partial void CreateOrder(string customerId);\n\n [Event]\n public partial void AddLineItem(string productId, string productName, int quantity, decimal unitPrice);\n}\n", + "language": "csharp", + "outcome": "The source generator produces the aggregate plumbing; provider packages add stores for SQL Server, PostgreSQL, MongoDB, Azure Storage, Cosmos DB, or in-memory.", + "evidence": "One [Aggregate] declaration, and switching storage means swapping a provider package rather than rewriting the domain.", + "docsPage": "solution-design-guide" + }, + { + "audience": "architect", + "title": "Choose the store late, keep the domain stable", + "scenario": "You need to start on one database and move providers later, but you do not want persistence choices to leak into the domain model.", + "code": "builder.Services.AddSqlServerEventStore();\nbuilder.Services.AddSqlServerSnapshotQueryableEventStore();\n", + "language": "csharp", + "outcome": "Domain code depends on provider-agnostic facades, while concrete stores live behind separate packages and registration extensions.", + "evidence": "SQL Server, PostgreSQL, MongoDB, Azure Storage, and Cosmos DB are interchangeable at the registration level, so the domain never references a store.", + "docsPage": "sql-server-guide" + } + ], + "related": [ + "zodsharp", + "value-objects" + ], + "discussions": false + } + }, + { + "repository": "purview-dev/openapi-xmlcomments", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "openapi-xmlcomments", + "name": "OpenAPI XmlComments", + "shortDescription": "Keeps the ASP.NET Core OpenAPI XML-comment generator working when one documentation ID arrives twice.", + "description": "An MSBuild package for APIs that reference Microsoft.AspNetCore.OpenApi. The XML-comment source generator builds one dictionary from the documentation of every project reference and of the API's own compilation, and de-duplicates neither, so a documented type that arrives from more than one assembly makes /openapi/v1.json answer 500 with \"An item with the same key has already been added\". This package removes every colliding documentation ID from the referenced XML documentation before compile, and warns (POAX001) about an ID it can only see once the API has been built. The generator stays on, so every XML description stays in the OpenAPI document.", + "origin": "The same 500 appeared in several APIs at once as soon as a source generator started injecting the same attribute into every assembly (dotnet/aspnetcore#67192). The usual workaround — removing the generator — also removed every description from the document, so the fix became two MSBuild targets that filter only what actually collides.", + "useWhen": "Your API references Microsoft.AspNetCore.OpenApi with its XML-comment generator on, and a documented type with the same full name is compiled into more than one of its project references — typically an attribute or polyfill a source generator injects into every assembly.", + "avoidWhen": "The duplicate never passes through AdditionalFiles, or both copies come from the API's own compilation: the package cannot see those, and a type that is genuinely duplicated public API needs one of the declarations renamed rather than filtered.", + "repository": "purview-dev/openapi-xmlcomments", + "category": "build-tooling", + "status": "preview", + "order": 65, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "skills": true, + "targetFrameworks": [ + "msbuild" + ], + "packages": [ + { + "id": "Purview.OpenAPI.XmlComments", + "description": "The deduplication and overlap-check MSBuild tasks, their props and targets, and POAX001; a development dependency with no runtime footprint.", + "primary": true, + "targetFrameworks": [ + "netstandard2.0" + ] + } + ], + "related": [ + "results" + ], + "useCases": [ + { + "audience": "developer", + "title": "Keep the generator on and filter only what collides", + "scenario": "/openapi/v1.json answers 500 with \"An item with the same key has already been added\" because a type your API documents is also documented in more than one referenced project, and the only workaround you have found turns the XML-comment generator off.", + "code": "\n\n", + "language": "xml", + "outcome": "Every colliding documentation ID is removed from the referenced documentation before compile, the generator runs on the filtered copies, and the description of every other endpoint and schema stays in the document.", + "evidence": "Every occurrence of a colliding ID goes, not all but the first, because the API usually declares the injected type as well: keeping a reference's copy would still collide with it. A duplicated ID is ambient code rather than API surface, and a copy is only rewritten when its content changes, so a no-change build still skips CoreCompile." + }, + { + "audience": "developer", + "title": "List every colliding ID rather than the first one", + "scenario": "The exception names one documentation ID, and the build says nothing about the rest, so you do not know whether one exclude is enough or whether the generator fails again on the next build.", + "code": "pwsh skills/purview-openapi-xmlcomments-duplicates/scripts/find-duplicate-documentation-ids.ps1 `\n -Project path/to/Api\n", + "language": "powershell", + "outcome": "The script asks MSBuild for exactly the documentation files the generator reads and reports every colliding ID, where each copy comes from, whether the current configuration already handles it, and the item to add when it does not.", + "evidence": "Each finding is classified: BetweenReferences is handled automatically by the package, while ReferenceAndProject needs the PurviewOpenAPIXmlCommentExclude item the script prints. It exits 0 when nothing would throw, 1 when something would, and 2 when it could not inspect the project.", + "docsPage": "troubleshooting" + }, + { + "audience": "team-lead", + "title": "Fail the build on a collision instead of a 500 in production", + "scenario": "The overlap is only visible after the API compiles, so a warning is easy to ship, and the failure then surfaces as a 500 on the OpenAPI document rather than as a red build.", + "code": "\n \n $(MSBuildWarningsAsErrors);POAX001\n\n", + "language": "xml", + "outcome": "POAX001 fails the build and names the exact PurviewOpenAPIXmlCommentExclude item to add, so an unhandled collision is a pull-request failure instead of a runtime error.", + "evidence": "The check runs after CoreCompile and compares the API's fresh documentation file with the filtered reference documentation, which is the one case the before-compile pass cannot see: an ID documented in the API and in exactly one referenced project.", + "docsPage": "diagnostics" + }, + { + "audience": "architect", + "title": "One repository-wide reference that costs nothing at run time", + "scenario": "Several API projects in the same repository reference the same generators, and you do not want per-project wiring or a build fix that becomes a runtime dependency.", + "code": "\n\n", + "language": "xml", + "outcome": "One declaration covers every project and does nothing in a project that does not reference Microsoft.AspNetCore.OpenApi, so libraries in the same repository need no exemption.", + "evidence": "The package ships only props, targets and a netstandard2.0 task assembly under tasks/; lib/, ref/ and runtimes/ are forbidden by pack validation, so it adds no runtime dependency and copies nothing into the consumer's build output.", + "docsPage": "configuration" + } + ] + } + }, + { + "repository": "purview-dev/pm-skills", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev.github.io/main/src/src/lib/manifest/schema.ts", + "id": "pm-skills", + "name": "PM Skills", + "shortDescription": "Project-management skills that decide which feature an AI coding agent works on next.", + "description": "Twenty-four agent skills that give a solo developer a parking lot, challenged shaping, strategy, a roadmap, a task board, a risk register, and memory across sessions — installed above a development workflow skill set such as Superpowers. They decide which feature is worked on; the workflow skills decide how it is built. Ideas are captured in one line at any time, shaped into a brief whose ramifications are challenged before they reach the roadmap, and every decision is written to a file as it is made so a compacted session can resume from it. The skills write only to the configured planning directory, commit only that directory, and create no branch except the item's own.", + "origin": "The bottleneck on a solo project driven by a coding agent was not the code but the decision about what to build next: ideas arrived mid-task and were lost, a half-formed feature reached the roadmap unchallenged, and after a context compaction the thread of what was in flight had to be rebuilt from the conversation. Writing that discipline down as skills — a capture that works at any moment, a shaping step that argues with the idea first, and state files that survive compaction — turned it into something the agent runs rather than something the developer has to remember.", + "useWhen": "You drive a project with an AI coding agent and want the product decisions — what is next, what was dropped, and why a bet was taken — kept in files that outlive the session rather than in the conversation. It fits a solo developer or a small team that already has a development workflow skill set and wants the layer above it.", + "avoidWhen": "You want a hosted planning tool, a shared backlog for a large team, or a portfolio view: the state is plain markdown in your repository and the skills assume one developer plus an agent. With no agent workflow to sit above, there is nothing for the PM skills to hand off to.", + "repository": "purview-dev/pm-skills", + "category": "developer-tooling", + "status": "stable", + "order": 100, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Home.md", + "exclude": [ + "_Sidebar.md" + ] + }, + "related": [ + "engineering-playbook" + ], + "acknowledgments": [ + { + "name": "Superpowers", + "url": "https://github.com/obra/superpowers", + "description": "The development workflow skill set the PM skills are installed above." + } + ], + "useCases": [ + { + "audience": "developer", + "title": "Capture a bug or an idea in one line, mid-task", + "scenario": "You are in the middle of an implementation when you spot an unrelated bug, or an idea arrives that you cannot act on now but do not want to lose.", + "code": "park this: the export button does nothing in Safari\n\nParked: planning/inbox/2026-11-01-0912-export-button-safari.md (bug). Back to step 3.\n", + "language": "plaintext", + "outcome": "One inbox file is written under the configured planning directory and the reply is a single line, so the agent resumes the step it was on. Only capture (pm-park, pm-risk) and checkpoint writes may run during an active workflow, so nothing else interrupts the build.", + "evidence": "pm-park writes in the main worktree rather than the current feature worktree, and its Output section allows exactly one line plus — only when no workflow is active — a single choice question, `Shape \"\" now, or keep it parked?`, whose recommended answer is to keep it parked." + }, + { + "audience": "team-lead", + "title": "A board and a roadmap that come from the same files", + "scenario": "You want to see what is in progress, what the agent will pick up next, and what is waiting on you, without maintaining a second copy of the plan in a tracker.", + "code": "| Column | ID | Title | Owner | Size | Detail |\n| --- | --- | --- | --- | --- | --- |\n| Now | R-007 | Tenant billing | agent | M | execute, 4/9 steps |\n| Next (agent) | R-008 | Invoice email | agent | S | ready |\n| For you | R-009 | Open a Stripe account | user | S | blocks R-008 |\n| Waiting | R-010 | Usage export | agent | M | needs R-008 |\n| Done | R-006 | Tenant model | agent | M | 2026-10-28 |\n", + "language": "markdown", + "outcome": "pm-board, pm-roadmap, and pm-status render the task board, the milestone roadmap, or just your own queue from the same state files the agent works from, and viewing is read-only: asking for the board or the status never changes the plan.", + "evidence": "The board's \"For you\" column is every Owner: user item in Next plus the open questions, and \"Waiting\" names the blocking item — the same roadmap items pm-next claims work from, so the board cannot drift from what is actually being built." + }, + { + "audience": "architect", + "title": "The idea is challenged before it reaches the roadmap", + "scenario": "An idea sounds obviously good, and you want it argued with — the alternatives, the ramifications across data, security, performance, cost and maintenance, and the smallest version that still delivers the outcome — before it becomes work.", + "code": "## Who and evidence\n## Alternatives considered\n## Challenges and answers\n## Ramifications\n## Proposal\n## Done when\n## Open questions\n## Decision\n", + "language": "markdown", + "outcome": "A brief is written to the planning directory after every answer, so the discussion survives compaction and a later session resumes it from the first empty heading, and the run ends with one decision: add to Next, add to Later, build it now, keep it parked, or drop it.", + "evidence": "pm-shape writes at least three alternatives — do nothing, the smallest version, and the full idea — and completes a ramifications row for each of the eight Challenge protocol areas, writing \"none found\" rather than leaving one out; a dropped idea appends its reason to Dropped in LOG.md." + }, + { + "audience": "contributor", + "title": "Add a skill without breaking the consistency checks", + "scenario": "You want to add a new pm-* skill, and the repository has to stay consistent: the README table, the managed section, the pm-setup inventory and the pm-help guide all have to describe the same set.", + "code": "just validate\njust lint-check\n", + "language": "bash", + "outcome": "Adding a skill is a directory plus the four listings that reference it. just validate checks skill frontmatter, the README and managed-section tables, the pm-setup inventory, the section markers and the template placeholders, and fails when one listing is missed.", + "evidence": "CI runs the same checks on every push and pull request to main, and lefthook runs commitlint on commit and just lint-check on push, so a half-registered skill cannot be merged." + } + ] + } + }, + { + "repository": "purview-dev/results", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "results", + "name": "Results", + "shortDescription": "Result for .NET — expected failures as values the caller must handle.", + "description": "A small, dependency-free Result<TValue, TError> for .NET that makes expected failures part of a method's contract: not found, invalid, and conflict are values rather than exceptions. A Roslyn source generator adds C# 15 union ergonomics for the error cases, and companion packages carry the result into ASP.NET Core responses and ZodSharp validation problems.", + "origin": "Services kept re-declaring their own error types and hand-writing the same failure helpers and HTTP mapping, so the result type, the generated helpers, and the adapter packages became one shared package family.", + "useWhen": "Expected failures are part of your domain model and you want them returned as values the caller must handle, with a strongly typed error case that still reaches the client as a standard HTTP problem response.", + "avoidWhen": "You target a runtime below .NET 11 with C# 15 preview, or the failures you are modelling are exceptional circumstances that belong in exceptions.", + "repository": "purview-dev/results", + "category": "application-framework", + "status": "stable", + "order": 45, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net10.0", + "net11.0" + ], + "packages": [ + { + "id": "Purview.Results", + "description": "The result type, its factories, IResultValue, and the bundled union source generator. No dependencies.", + "primary": true + }, + { + "id": "Purview.Results.AspNetCore", + "description": "Result-to-response mapping, endpoint filter, and dependency-injection registration." + }, + { + "id": "Purview.Results.ZodSharp", + "description": "Bridges ZodSharp validation results into results." + }, + { + "id": "Purview.Results.ZodSharp.AspNetCore", + "description": "Renders validation-carrying failures as HttpValidationProblemDetails." + } + ], + "related": [ + "zodsharp", + "sourcegenerator-framework" + ], + "useCases": [ + { + "audience": "developer", + "title": "Return expected failures as values", + "scenario": "You call a store that can fail in ways you expect — not found, disabled, already exists — and you do not want a thrown exception or a generic error string to be the only way the caller learns what happened.", + "code": "Result<Tenant, TenantError> GetTenant(TenantId tenantId) =>\n _tenants.TryGet(tenantId, out var tenant)\n ? Result<Tenant, TenantError>.Success(tenant)\n : new TenantNotFound(tenantId).AsFailure<Tenant>();\n", + "language": "csharp", + "outcome": "The caller branches on the error value itself, so TenantNotFound keeps carrying its TenantId instead of being flattened into a message.", + "evidence": "The core package has no dependencies: it ships the result type, its factories, and IResultValue without pulling anything else in.", + "docsPage": "core-concepts" + }, + { + "audience": "developer", + "title": "Generate the failure helper for every union case", + "scenario": "You model errors as a C# 15 union and need each case to become the failure side of a result without writing one conversion helper per case by hand.", + "code": "[GenerateResult]\npublic readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists);\n", + "language": "csharp", + "outcome": "The generator emits AsFailure<TValue>() for every case of an annotated union, plus a code fix and a CA1815 suppression, so the declaration needs no pragma.", + "evidence": "C# forbids the implicit conversion a bare case value would need — no operators in static classes, no conversion operators in extension members, one user-defined conversion per sequence — which is why the helper is per case.", + "docsPage": "union-errors" + }, + { + "audience": "architect", + "title": "Map one error union onto HTTP responses", + "scenario": "The same domain error union surfaces from many minimal-API endpoints, and you do not want a hand-written switch deciding the status code at each one.", + "code": "builder.Services.AddResultsHttp(options => options\n .Map<TenantNotFound>(error => TypedResults.NotFound())\n .Map<TenantError>(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict))\n);\n\napp.MapGet(\"/tenants/{id:int}\", (int id) => GetTenant(id)).WithResultsHttp();\n", + "language": "csharp", + "outcome": "The mapping is declared once at startup, WithResultsHttp() applies it to the endpoints, and a host can replace IResultsHttpMapper when it needs different behaviour.", + "evidence": "Mappings resolve in declaration order — any mapping or failure mapper the host declared earlier always wins — so the most specific rule is registered first.", + "docsPage": "aspnetcore-integration" + }, + { + "audience": "team-lead", + "title": "Let ZodSharp validation failures become validation problems", + "scenario": "Endpoints validate input with ZodSharp, and a failed validation should reach the client as the standard ASP.NET Core validation-problem payload rather than an error shape the API has to document separately.", + "code": "{\n \"title\": \"One or more validation errors occurred.\",\n \"status\": 400,\n \"errors\": { \"TenantId\": [\"Required field 'TenantId' is null\"] },\n \"issues\": [{ \"code\": \"missing_field\", \"path\": [\"TenantId\"], \"message\": \"Required field 'TenantId' is null\" }]\n}\n", + "language": "json", + "outcome": "A failure that implements IValidationErrorCarrier becomes HttpValidationProblemDetails without the host mapping it, unless a per-code or per-category rule answers that failure first.", + "evidence": "The response is ASP.NET Core's own HttpValidationProblemDetails contract, so API clients keep the error shape they already parse.", + "docsPage": "zodsharp-problemdetails" + } + ] + } + }, + { + "repository": "purview-dev/sourcegenerator-framework", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "sourcegenerator-framework", + "name": "SourceGenerator Framework", + "shortDescription": "A typed framework for building incremental C# source generators.", + "description": "A strongly typed framework for building, testing, and maintaining incremental C# source generators with Roslyn. Includes structured code generation, attribute data models, type libraries, and a step-cache test runner for verifying incremental behaviour.", + "origin": "Building several incremental generators exposed the same needs for typed models, structured output, testing, and cache verification, so those foundations became a shared framework.", + "useWhen": "You are building a non-trivial incremental C# source generator and want reusable modelling, code-writing, packaging, and testing infrastructure.", + "avoidWhen": "Your generator is small enough for the Roslyn APIs directly, or adopting a framework would hide behaviour your implementation needs to control precisely.", + "repository": "purview-dev/sourcegenerator-framework", + "category": "source-generation", + "status": "stable", + "featured": true, + "order": 40, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net10.0", + "net11.0" + ], + "packages": [ + { + "id": "Purview.SourceGeneratorFramework", + "description": "Core helpers, models, and MSBuild integration for incremental generators.", + "primary": true, + "targetFrameworks": [ + "netstandard2.0" + ] + }, + { + "id": "Purview.SourceGeneratorFramework.Testing", + "description": "Framework-agnostic test runner and assertions for generator tests." + }, + { + "id": "Purview.SourceGeneratorFramework.Testing.TUnit", + "description": "TUnit-specific test base classes and assertions." + } + ], + "useCases": [ + { + "audience": "contributor", + "title": "Build an incremental generator on typed foundations", + "scenario": "You are writing a non-trivial incremental C# source generator and need typed attribute models, structured code output, and packaging that Roslyn will actually load.", + "code": "<ProjectReference\n Include=\"..\\MyGenerator\\MyGenerator.csproj\"\n PrivateAssets=\"all\"\n OutputItemType=\"Analyzer\"\n ReferenceOutputAssembly=\"false\"\n/>\n", + "language": "xml", + "outcome": "The framework supplies attribute-data models, a structured code writer, a type library, and packaging helpers so the generator stays focused on its own logic.", + "evidence": "The Purview generators themselves are built on the framework, so it is exercised by real generators rather than being an untested abstraction.", + "docsPage": "guide" + }, + { + "audience": "contributor", + "title": "Verify incremental behaviour in tests", + "scenario": "You need to prove a generator is incremental and produces the code you expect, without assembling a Roslyn driver by hand in every test.", + "outcome": "The testing package provides SourceGeneratorTestRunner<TGenerator>, a framework-agnostic test base, and assertions such as AssertSingleGeneratedSource and AssertNoCompilationErrors.", + "evidence": "Step-cache tests and a TUnit integration ship alongside the runner, so incremental regressions surface in CI.", + "docsPage": "testing" + } + ] + } + }, + { + "repository": "purview-dev/telemetry-sourcegenerator", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "telemetry-sourcegenerator", + "name": "Telemetry SourceGenerator", + "shortDescription": "Interface-based telemetry for .NET with zero boilerplate.", + "description": "A source generator that turns simple interface methods into OpenTelemetry-aligned Activities, structured ILogger logging, and Metrics. Define telemetry once on an interface; the generator emits the implementation, DI registration helpers, and multi-target generation — no runtime reflection, no boilerplate.", + "origin": "Repeating the same logging, activity, and metric wiring across services made telemetry a strong candidate for one interface-driven, compile-time implementation.", + "useWhen": "You want strongly typed OpenTelemetry-aligned telemetry from interfaces, with generated implementations and dependency-injection registration.", + "avoidWhen": "Your telemetry is highly dynamic, cannot be described at compile time, or is already handled consistently by another instrumentation layer.", + "repository": "purview-dev/telemetry-sourcegenerator", + "category": "observability", + "status": "stable", + "featured": true, + "order": 10, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net8.0", + "net9.0", + "net10.0" + ], + "packages": [ + { + "id": "Purview.Telemetry.SourceGenerator", + "description": "Core package with the Roslyn source generator and attribute library.", + "primary": true, + "targetFrameworks": [ + "netstandard2.0" + ] + } + ], + "useCases": [ + { + "audience": "developer", + "title": "Tracing, logging, and metrics from a single interface", + "scenario": "You want OpenTelemetry activities, structured logs, and metrics around an order service, but you do not want to hand-write the ActivitySource, ILogger, and Meter wiring in every class.", + "code": "[ActivitySource]\n[Logger]\n[Meter]\npublic interface IOrderServiceTelemetry\n{\n [Activity]\n [Info]\n [AutoCounter]\n Activity? PlacingOrder(int orderId, [Baggage] string region);\n}\n", + "language": "csharp", + "outcome": "The generator emits the implementation and an AddOrderServiceTelemetry() DI extension; you register it once and inject the interface wherever telemetry is needed.", + "evidence": "One interface replaces the ActivitySource, ILogger, and Meter boilerplate you would otherwise repeat in every service." + }, + { + "audience": "architect", + "title": "Standardise telemetry names across services", + "scenario": "You want consistent OpenTelemetry meter and activity-source names across many services instead of ad-hoc string literals scattered through the codebase.", + "code": "builder.AddServiceDefaults(\n TelemetryNames.MeterNames,\n TelemetryNames.ActivitySourceNames);\n", + "language": "csharp", + "outcome": "A generated TelemetryNames static class holds the names, so registration happens once at startup rather than in every service.", + "evidence": "Naming conventions are generated, so snake_case tags and hierarchical metrics stay consistent without a review checklist.", + "docsPage": "generation" + } + ], + "discussions": false + } + }, + { + "repository": "purview-dev/unions", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "unions", + "name": "Unions", + "shortDescription": "Dependency-free C# 15 unions that do not box value-type cases.", + "description": "The C# 15 `union` keyword lowers to a single `object?` field, so every value-type case is boxed on entry. Purview.Unions generates the language's non-boxing custom-union shape instead: each case gets its own typed field, a public constructor, and a `TryGetValue` that never allocates. The compiler still sees a union — implicit conversions, exhaustive `switch`, and `is`/`null` patterns all work — plus a hand-written `Union<T1, T2>` for the two-case shape.", + "origin": "Discriminated unions were needed for error modelling and optional values, and the language's own `union` declaration boxes every value-type case on entry. The compiler already exposes the custom-union contract the boxing-free shape needs, so the generator that emits it became a shared package instead of a hand-written type in each project.", + "useWhen": "You model a closed set of cases — expected errors, optional results, a small state machine — and either the value-type cases are allocation-sensitive or you want one type the whole team matches on exhaustively.", + "avoidWhen": "You target a runtime below .NET 11 with C# 15, or a single shape with two reference-type cases is enough: the built-in `union` declaration is simpler and the boxing cost does not apply to reference types.", + "repository": "purview-dev/unions", + "category": "source-generation", + "status": "preview", + "order": 25, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net10.0", + "net11.0" + ], + "packages": [ + { + "id": "Purview.Unions", + "description": "The [GenerateUnion] attribute, the source generator with its code fixes, and the hand-written Union<T1, T2>.", + "primary": true + } + ], + "skills": true, + "related": [ + "results", + "zodsharp", + "sourcegenerator-framework" + ], + "useCases": [ + { + "audience": "developer", + "title": "Match a value-type union without boxing a case", + "scenario": "A method returns one of a handful of value-type outcomes, and the caller must branch on which one it received — but the `union` keyword boxes every value-type case on entry and again while matching.", + "code": "[GenerateUnion(typeof(int), typeof(string))]\npublic readonly partial struct IntOrString;\n\nIntOrString value = 42;\n\nvar message = value switch\n{\n int number => $\"int {number}\",\n string text => $\"string {text}\",\n null => \"empty\",\n};\n", + "language": "csharp", + "outcome": "The compiler treats the generated type as a union, so implicit conversions, exhaustive `switch` and `is`/`null` patterns all work, while construction, `TryGetValue`, `is` and `switch` never allocate.", + "evidence": "The committed BenchmarkDotNet suite measures construction, both `TryGetValue` directions, the miss path, `HasValue`, `is` and both `switch` shapes at 0 B; only reading `Value` allocates the 24-byte box for the `int` case, which is inherent to the union contract.", + "docsPage": "performance" + }, + { + "audience": "developer", + "title": "Declare a union whose cases are type parameters", + "scenario": "You want a generic option or outcome type, but `typeof(T)` is not a legal attribute argument, so an ordinary `[GenerateUnion(typeof(…))]` list cannot name a type parameter.", + "code": "[GenerateUnion]\npublic readonly partial struct Option<T>\n{\n internal static partial Option<T> Some(Some<T> value);\n internal static partial Option<T> None(None value);\n}\n", + "language": "csharp", + "outcome": "Each partial factory signature names a case, the generator supplies the bodies and derives the public constructors from them, and the compiler reports `CS0416` only if you try to use a `typeof(T)` list instead.", + "evidence": "A generic union must name its cases in source because `CS0416` rejects `typeof(T)` in an attribute; a `typeof` list on a generic union is reported as `UNI0011`.", + "docsPage": "union-design" + }, + { + "audience": "architect", + "title": "Let a second source generator see the union's cases", + "scenario": "Another Purview generator — Results, or the telemetry generator unwrapping a parameter — must read the case list, but Roslyn generators never see each other's generated output.", + "code": "[GenerateUnion]\npublic readonly partial struct Outcome<T> : Outcome<T>.IUnionMembers\n{\n public interface IUnionMembers\n {\n static Outcome<T> Create(T? value) => Outcome<T>.CreateCase0(value);\n static Outcome<T> Create(Exception? error) => Outcome<T>.CreateCase1(error);\n\n bool TryGetValue(out T value);\n bool TryGetValue(out Exception value);\n }\n}\n", + "language": "csharp", + "outcome": "A public nested `IUnionMembers` provider exposes the case list in the source the other generator compiles against, while this generator still emits the storage and `CreateCaseN` methods.", + "evidence": "`Purview.Telemetry.SourceGenerator` 6.0.0 reads the source-visible case list in the same order as this package, and a `[GenerateUnion]` target with no source-visible case list is reported as `UNI0003` rather than unwrapped.", + "docsPage": "interop" + }, + { + "audience": "contributor", + "title": "Fail fast on a malformed union declaration", + "scenario": "A union is declared without `partial`, with a duplicate case, or with a case type less accessible than the union, and the generated shape cannot be emitted coherently.", + "code": "error UNI0001: The union declaration is not partial\nerror UNI0004: Duplicate case type\nerror UNI0005: A case type is less accessible than the union\n", + "language": "plaintext", + "outcome": "Every error blocks its union's output rather than emitting a partial shape, and the package ships code fixes for the common declarations — add `partial` (`UNI0001`), widen an inaccessible case type (`UNI0005`), add `[Union]` on the fallback path (`UNI0007`).", + "evidence": "`UNI0015` (a single-case union) is the only warning; every other `UNI` rule blocks emission, so a malformed union fails the build instead of producing half a type.", + "docsPage": "diagnostics" + } + ] + } + }, + { + "repository": "purview-dev/value-objects", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "value-objects", + "name": "Value Objects", + "shortDescription": "Source-generated scalar and complex value objects for .NET.", + "description": "F#-style single-case types for C#. Mark a partial struct or class with [Scalar] or [ValueObject] and an incremental source generator produces Create/Hydrate factories with normalization and validation, equality, comparison, implicit conversions, JSON converters, and contextual creation. Value objects serialize as their underlying value, map cleanly onto Entity Framework JSON columns, and can be validated with Purview.ZodSharp schemas.", + "origin": "Hand-writing the same factories, equality rules, conversions, serializers, and persistence integration for domain values made the pattern an obvious source-generation target.", + "useWhen": "Your domain uses meaningful scalar or complex value types and you want their repetitive implementation generated from a small, explicit declaration.", + "avoidWhen": "A primitive or record already expresses the concept clearly, or generated conversion and serialization behaviour would be more machinery than the domain needs.", + "repository": "purview-dev/value-objects", + "category": "source-generation", + "status": "stable", + "featured": true, + "order": 35, + "docs": { + "source": "github-path", + "path": "docs", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ] + }, + "targetFrameworks": [ + "net8.0", + "net9.0", + "net10.0", + "net11.0" + ], + "packages": [ + { + "id": "Purview.ValueObjects", + "description": "Runtime contracts, source generator, and analyzer for scalar and complex value objects.", + "primary": true + } + ], + "useCases": [ + { + "audience": "developer", + "title": "A domain scalar without the boilerplate", + "scenario": "You want a strong EmailAddress type with normalisation and validation, without hand-writing factories, equality, conversions, and a JSON converter.", + "code": "[Scalar]\npublic readonly partial record struct EmailAddress\n{\n public string Value { get; }\n\n static partial void OnNormalize(ref string value)\n => value = value?.Trim().ToLowerInvariant()!;\n}\n", + "language": "csharp", + "outcome": "The generator adds Create, Hydrate, TryCreate, and Empty, plus equality, comparison, implicit conversions, and a JSON converter.", + "evidence": "One declaration replaces the factory, equality, comparison, conversion, and serialization code you would otherwise maintain by hand.", + "docsPage": "value-object-design" + }, + { + "audience": "developer", + "title": "Map a value object onto an Entity Framework column", + "scenario": "You use a value object in your domain and want it to persist transparently instead of writing converters at every mapping site.", + "code": "var email = EmailAddress.Create(\" Demo@Example.COM \");\n// email.Value == \"demo@example.com\"\n\nbool ok = EmailAddress.TryCreate(\"not-an-email\", out _);\n// ok == false\n", + "language": "csharp", + "outcome": "Value objects serialize as their underlying value and map onto Entity Framework JSON columns, with optional Purview.ZodSharp validation.", + "evidence": "Persistence and serialization come from the generated type, so mapping code is not duplicated per entity.", + "docsPage": "entity-framework" + } + ], + "related": [ + "zodsharp", + "event-sourcing" + ] + } + }, + { + "repository": "purview-dev/zodsharp", + "ref": "main", + "record": { + "$schema": "https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts", + "id": "zodsharp", + "name": "ZodSharp", + "shortDescription": "Zero-allocation schema validation for C# — a Zod port.", + "description": "A high-performance schema validation library for C#, ported from TypeScript Zod by way of the guinhx/ZodSharp C# port. Struct-based rules, a fluent API, JSON Schema export and import, source-generated validators, and zero-allocation validation on every valid input path. Integrates with System.Text.Json, Newtonsoft.Json, and ASP.NET Core ProblemDetails.", + "origin": "Schema validation was repeatedly needed at application boundaries, but existing approaches did not combine a fluent Zod-style model with predictable, allocation-conscious execution.", + "useWhen": "You want composable C# schemas, compile-time validator generation, or JSON Schema interop with tight control over validation behaviour and allocations.", + "avoidWhen": "Data annotations or an existing validation library already cover your requirements, or Zod-style schemas would add an unnecessary second validation model.", + "repository": "purview-dev/zodsharp", + "category": "validation", + "status": "stable", + "featured": true, + "order": 30, + "docs": { + "source": "github-path", + "path": "docs/wiki", + "rootPage": "Getting-Started.md", + "exclude": [ + "_Sidebar.md", + "Home.md", + "index.md" + ], + "channels": { + "live": { + "ref": "latest-stable" + }, + "prerelease": { + "ref": "default" + } + }, + "redirects": { + "core-concepts": "concepts/core-concepts", + "composition-and-transforms": "concepts/composition-and-transforms", + "string-validation": "schemas/string-validation", + "number-validation": "schemas/number-validation", + "object-validation": "schemas/object-validation", + "arrays-and-other-schemas": "schemas/arrays-and-other-schemas", + "unions-and-discriminated-unions": "schemas/unions-and-discriminated-unions", + "validation-rules-reference": "schemas/validation-rules-reference", + "custom-rules": "schemas/custom-rules", + "value-objects-integration": "schemas/value-objects-integration", + "compiled-validators-and-caching": "schemas/compiled-validators-and-caching", + "source-generator": "generator/source-generator", + "source-generator-dataannotations": "generator/source-generator-dataannotations", + "source-generator-diagnostics": "generator/source-generator-diagnostics", + "jsonschema-export": "serialization/jsonschema-export", + "jsonschema-import": "serialization/jsonschema-import", + "systemtextjson-integration": "serialization/systemtextjson-integration", + "newtonsoftjson-integration": "serialization/newtonsoftjson-integration", + "microsoft-extensions-validation": "hosting/microsoft-extensions-validation", + "openapi-integration": "hosting/openapi-integration", + "blazor-integration": "hosting/blazor-integration", + "http-integration": "hosting/http-integration", + "dependency-injection": "hosting/dependency-injection", + "localization": "hosting/localization", + "guarantees-and-limitations": "quality/guarantees-and-limitations", + "performance": "quality/performance", + "trimming-and-aot": "quality/trimming-and-aot", + "cross-platform-interop": "quality/cross-platform-interop", + "contributing": "development/contributing", + "release-flow": "development/release-flow" + } + }, + "targetFrameworks": [ + "net8.0", + "net9.0", + "net10.0", + "net11.0" + ], + "packages": [ + { + "id": "Purview.ZodSharp", + "description": "Core validation library and source generator.", + "primary": true + }, + { + "id": "Purview.ZodSharp.SystemTextJson", + "description": "System.Text.Json integration and JSON Schema import." + }, + { + "id": "Purview.ZodSharp.NewtonsoftJson", + "description": "Newtonsoft.Json integration and JSON Schema import." + }, + { + "id": "Purview.ZodSharp.AspNetCore", + "description": "ASP.NET Core ProblemDetails integration." + }, + { + "id": "Purview.ZodSharp.Http", + "description": "HttpClient integration — validates request and response bodies and maps validation problems back to ZodSharp errors." + }, + { + "id": "Purview.ZodSharp.Blazor", + "description": "Blazor EditForm validation on Server, WebAssembly and Auto render modes." + }, + { + "id": "Purview.ZodSharp.AspNetCore.OpenApi", + "description": "OpenAPI transformers for the constraints, formats and error contract ZodSharp enforces." + }, + { + "id": "Purview.ZodSharp.Extensions.Validation", + "description": "Microsoft.Extensions.Validation resolver so minimal APIs and Blazor validate with ZodSharp." + } + ], + "related": [ + "value-objects" + ], + "acknowledgments": [ + { + "name": "Zod", + "url": "https://github.com/colinhacks/zod", + "description": "The original JavaScript/TypeScript schema validation library." + }, + { + "name": "ZodSharp (guinhx)", + "url": "https://github.com/guinhx/ZodSharp", + "description": "The C# port of Zod, and the fork this project is based on." + } + ], + "useCases": [ + { + "audience": "developer", + "title": "Validate input without exceptions or allocations", + "scenario": "You need to validate values at an application boundary and prefer a result you can inspect over exception-driven control flow.", + "code": "var nameSchema = Z.String().Min(3).Max(50);\nvar result = nameSchema.Validate(\"John\");\n\nif (result.IsSuccess)\n Console.WriteLine($\"Valid name: {result.Value}\");\n", + "language": "csharp", + "outcome": "Validate/SafeParse return a ValidationResult<T> with no exceptions, while Parse still throws ZodException when you want that behaviour.", + "evidence": "Validation is zero-allocation on every valid input path, so the performance claim is a property of the code rather than an aspiration.", + "docsPage": "fluent-schema-api" + }, + { + "audience": "team-lead", + "title": "Return standard ProblemDetails for invalid requests", + "scenario": "You want failed validation in ASP.NET Core to surface as standard ProblemDetails payloads rather than a bespoke error shape that clients must learn.", + "code": "dotnet add package Purview.ZodSharp.AspNetCore\n", + "language": "bash", + "outcome": "The AspNetCore adapter converts failed validation results into the standard ProblemDetails / HttpValidationProblemDetails payloads.", + "evidence": "One adapter package, and API consumers keep the error contract they already expect.", + "docsPage": "aspnetcore-integration" + } + ] + } + } + ] +} diff --git a/src/scripts/check-projects.ts b/src/scripts/check-projects.ts index e493ba8..78d00ca 100644 --- a/src/scripts/check-projects.ts +++ b/src/scripts/check-projects.ts @@ -10,6 +10,7 @@ import { ManifestValidationError, loadExternalProjects, loadProjects, + readRawManifest, } from '../src/lib/manifest/load'; import { readReleaseCache, readReleaseFixture } from '../src/lib/releases/cache'; import { selectStableVersion } from '../src/lib/releases/normalize'; @@ -29,10 +30,11 @@ import { listMirroredSkills } from '../src/lib/skills'; /** * Deterministic catalogue guard (ADR 0003). * - * Proves the invariants of the catalogue (`src/src/data/projects/*.yml` plus - * `src/src/data/external-projects.yml`) against the generated - * docs mirror/cache and the release cache/fixtures. Offline only: it never - * performs network I/O, so it can run inside `just validate` and CI. + * Proves the invariants of the catalogue — the records under + * `src/src/data/projects/*.yml` that this repository still owns, the records the + * project repositories own (ADR 0013), plus `src/src/data/external-projects.yml` — + * against the generated docs mirror/cache and the release cache/fixtures. Offline + * only: it never performs network I/O, so it can run inside `just validate` and CI. * * It fails (exit 1) on blockers and drift; quality observations are printed as * warnings so they do not break the build. @@ -746,6 +748,22 @@ export function checkProjects(): { errors: Finding[]; warnings: Finding[] } { throw error; } + // A project that owns its record (ADR 0013) wins over a local file with the same + // id, so a leftover local copy is a second record that is no longer read. It is an + // observation rather than a blocker because the move is two pull requests in two + // repositories, and the site must not fail in the gap between them. + for (const id of readRawManifest().duplicatedIds) { + warn({ + project: id, + field: 'manifest', + observed: `record declared both here and by ${OWNER}/${id}`, + expected: 'one record, owned by the project repository', + remediation: + `delete src/src/data/projects/${id}.yml: the project's own ` + + '.config/purview-docs.yml wins', + }); + } + const data = readReleaseCache() ?? readReleaseFixture('index'); const docsManifest = readDocsManifest(); const documented = projects.filter((project) => project.docs); diff --git a/src/scripts/data-sync.ts b/src/scripts/data-sync.ts index 48185cd..ab22691 100644 --- a/src/scripts/data-sync.ts +++ b/src/scripts/data-sync.ts @@ -1,12 +1,14 @@ import { existsSync } from 'node:fs'; import { resolve } from 'node:path'; +import { readManifestCache, readManifestFixture } from '../src/lib/manifest/remote'; import { readReleaseCache, readReleaseFixture } from '../src/lib/releases/cache'; import { publishReleaseData } from '../src/lib/releases/runtime'; import { fetchReleaseData } from './fetch-releases'; import { processBranding } from './process-branding'; import { syncAssets } from './sync-assets'; import { hasCurrentDocsMirror, hasDocsMirror, syncDocs } from './sync-docs'; +import { syncManifests } from './sync-manifests'; import { syncSkills } from './sync-skills'; const RELEASES_CACHE_FILE = resolve('.cache/releases/releases.json'); @@ -68,6 +70,59 @@ async function syncReleases(mode: Mode): Promise<void> { ); } +/** + * Prepare the project-owned catalogue records (ADR 0013) before anything reads + * the catalogue: releases, documentation, skills and assets all iterate the + * projects, so a record that is not in hand yet is a project that is missing. + * + * The modes mirror the release data exactly: `fixture` and `cache` never touch + * the network, `live` always fetches, and `auto` prefers the cache and only + * fetches when there is none. + */ +async function syncManifestRecords(mode: Mode): Promise<void> { + if (mode === 'fixture') { + if (!readManifestFixture('index')) { + throw new Error( + 'DATA_MODE=fixture but no manifest fixture exists at fixtures/manifests/index.json', + ); + } + console.log('Manifests: using committed fixtures.'); + return; + } + if (mode === 'cache') { + if (!readManifestCache()) { + throw new Error( + 'DATA_MODE=cache but no manifest cache exists. Run `just data-sync` (live) first.', + ); + } + console.log('Manifests: using existing cache.'); + return; + } + if (mode === 'live') { + await syncManifests(); + return; + } + // auto: cache-first, then live, then committed fixtures. + if (readManifestCache()) { + console.log('Manifests: using existing cache.'); + return; + } + try { + await syncManifests(); + return; + } catch (error) { + console.warn(`Manifests: live fetch failed (${(error as Error).message}).`); + } + if (readManifestFixture('index')) { + console.warn('Manifests: falling back to committed fixtures.'); + return; + } + throw new Error( + 'No project-owned catalogue records available: the cache is missing, the live fetch failed, ' + + 'and no fixtures are present. Check GitHub access and retry.', + ); +} + async function syncDocsMirror(mode: Mode): Promise<void> { const current = hasCurrentDocsMirror(); if (mode === 'cache' || mode === 'fixture') { @@ -99,7 +154,10 @@ export async function dataSync(): Promise<void> { const mode = resolveMode(); console.log(`Data sync (mode=${mode})`); await processBranding(); - // Releases are fetched first so the docs aggregation can enrich content with + // Project-owned catalogue records come first: every later step iterates the + // catalogue, so it has to be complete before releases are fetched. + await syncManifestRecords(mode); + // Releases are fetched next so the docs aggregation can enrich content with // repository descriptions and topics (tags) from the release cache. await syncReleases(mode); await syncDocsMirror(mode); diff --git a/src/scripts/fix-projects.ts b/src/scripts/fix-projects.ts index ebb0b59..6c283bf 100644 --- a/src/scripts/fix-projects.ts +++ b/src/scripts/fix-projects.ts @@ -1,6 +1,6 @@ import type { Autofix } from './check-projects'; -import { readFileSync, writeFileSync } from 'node:fs'; +import { existsSync, readFileSync, writeFileSync } from 'node:fs'; import { join } from 'node:path'; import { DEFAULT_PROJECTS_DIR } from '../src/lib/manifest/load'; @@ -8,7 +8,9 @@ import { checkProjects } from './check-projects'; /** * Apply the catalogue guard's machine-applicable fixes to the project records - * under `src/src/data/projects/`. + * under `src/src/data/projects/`. A record a project owns (ADR 0013) is not one of + * them — it lives in that project's repository — so such a fix is reported as + * skipped rather than written here. * * The advisory observations in `check-projects.ts` carry an optional structured * `autofix`; this script applies those and leaves everything else (blockers, @@ -143,6 +145,13 @@ function run(): number { let changed = 0; for (const [projectId, autofixes] of byProject) { const file = join(DEFAULT_PROJECTS_DIR, `${projectId}.yml`); + if (!existsSync(file)) { + console.log( + ` skipped ${projectId}: the record is owned by its repository ` + + `(.config/purview-docs.yml, ADR 0013)`, + ); + continue; + } const original = readFileSync(file, 'utf8'); let lines = original.split('\n'); for (const autofix of autofixes) { diff --git a/src/scripts/refresh-fixtures.ts b/src/scripts/refresh-fixtures.ts index 3065c34..a5c06ab 100644 --- a/src/scripts/refresh-fixtures.ts +++ b/src/scripts/refresh-fixtures.ts @@ -4,6 +4,11 @@ import { mkdirSync, writeFileSync } from 'node:fs'; import { dirname, resolve } from 'node:path'; import { loadProjects } from '../src/lib/manifest/load'; +import { + MANIFEST_CACHE_SCHEMA_VERSION, + fetchProjectManifests, + listOrganizationRepositories, +} from '../src/lib/manifest/remote'; import { fetchGitHubReleasesRaw, fetchGitHubRepoRaw, @@ -20,6 +25,7 @@ const GITHUB_FIXTURES = resolve('fixtures', 'github'); const NUGET_FIXTURES = resolve('fixtures', 'nuget'); const NUGET_NUSPEC_FIXTURES = resolve(NUGET_FIXTURES, 'nuspec'); const NPM_FIXTURES = resolve('fixtures', 'npm'); +const MANIFEST_FIXTURES = resolve('fixtures', 'manifests'); const RELEASE_FIXTURES = resolve('fixtures', 'releases'); /** A package name safe for a fixture file name (`@scope/name` → `scope-name`). */ @@ -47,6 +53,21 @@ function writeText(file: string, data: string): void { * themselves, so no test updates are required after a refresh. */ async function main(): Promise<void> { + // Project-owned catalogue records (ADR 0013) come first: everything below is keyed + // by the repositories the catalogue resolves, and on a machine with no manifest + // cache — a fresh clone — the fixture written here is what `loadProjects()` reads. + try { + const manifests = await fetchProjectManifests(await listOrganizationRepositories()); + writeJson(resolve(MANIFEST_FIXTURES, 'index.json'), { + schema: MANIFEST_CACHE_SCHEMA_VERSION, + retrievedAt: new Date().toISOString(), + manifests, + }); + console.log(` manifests: ${manifests.length} project-owned record(s)`); + } catch (error) { + console.warn(` manifests: ${(error as Error).message}`); + } + const projects = loadProjects(); const data: ReleaseCacheData = { schema: RELEASE_CACHE_SCHEMA_VERSION, diff --git a/src/scripts/sync-manifests.ts b/src/scripts/sync-manifests.ts new file mode 100644 index 0000000..20ebae9 --- /dev/null +++ b/src/scripts/sync-manifests.ts @@ -0,0 +1,63 @@ +import type { ManifestCacheData } from '../src/lib/manifest/remote'; + +import { + MANIFEST_CACHE_SCHEMA_VERSION, + PROJECT_MANIFEST_PATH, + fetchProjectManifests, + listOrganizationRepositories, + readManifestCache, +} from '../src/lib/manifest/remote'; +import { publishManifestData } from '../src/lib/manifest/runtime'; + +/** + * Fetch every project-owned catalogue record (ADR 0013). + * + * The organisation's repository list is the discovery root: a repository that + * publishes `.config/purview-docs.yml` is a catalogue project. This is why the + * sync runs *first* in `just data-sync` — releases, documentation, skills and + * assets all iterate the catalogue, so the records have to be in hand before + * anything reads it. + * + * A repository that cannot be read fails the sync rather than being skipped: the + * site would otherwise silently publish a catalogue that is missing a project. + */ +export async function syncManifests(): Promise<ManifestCacheData> { + const previous = readManifestCache(); + const repositories = await listOrganizationRepositories(); + const manifests = await fetchProjectManifests(repositories); + + // A repository that stopped publishing its record is a project leaving the + // catalogue. Say so here, where it can be explained: the catalogue's own + // invariants otherwise report it as an unknown id in some *other* project's + // relationships, which names the symptom rather than the cause. + const fetched = new Set(manifests.map((manifest) => manifest.repository)); + for (const manifest of previous?.manifests ?? []) { + if (!fetched.has(manifest.repository)) { + console.warn( + `Manifests: ${manifest.repository} no longer publishes ${PROJECT_MANIFEST_PATH}; ` + + 'its project has left the catalogue.', + ); + } + } + + const data: ManifestCacheData = { + schema: MANIFEST_CACHE_SCHEMA_VERSION, + retrievedAt: new Date().toISOString(), + manifests, + }; + publishManifestData(data); + console.log( + `Manifests synced: ${manifests.length} project-owned record(s) from ${repositories.length} ` + + `repositor${repositories.length === 1 ? 'y' : 'ies'}` + + `${manifests.length > 0 ? ` (${manifests.map((item) => item.repository).join(', ')})` : ''}.`, + ); + return data; +} + +if (import.meta.main) { + await syncManifests(); +} + +if (import.meta.main) { + await syncManifests(); +} diff --git a/src/src/data/projects/architests.yml b/src/src/data/projects/architests.yml deleted file mode 100644 index 61f0e8f..0000000 --- a/src/src/data/projects/architests.yml +++ /dev/null @@ -1,178 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: architests -name: Architests -shortDescription: Enforce a repository's architecture policy as TUnit tests. -description: >- - Architecture tests for .NET. A repository declares its responsibilities and the dependency - directions they may and may not use in a policy file, then derives one test class from - PurviewArchitectureTests and gets the standard rule set as separate TUnit tests. The - project-level rules read declared ProjectReferences; the type-level rule reads the compiled - assemblies' metadata, so a reference that only arrives transitively or through a package is - caught too, and nothing is loaded or executed. The set covers dependency direction, sibling - independence, composition boundaries, forbidden packages and framework references, cycles, test - references and project naming, with reviewed per-project waivers and an extension point for - bespoke rules. -origin: >- - The standard architecture checks were being written into each repository's own test project, so - the same dependency-direction and forbidden-reference rules existed in several places and drifted - apart. Defining them once — the policy as data, the rule set as a package — means a repository - states its architecture rather than re-deriving the tests, and the schema and the rules version - together. -useWhen: >- - You have an agreed layering — domain, application, infrastructure, composition — and want it held - by the build rather than by review: at the project-reference level and at the type level, - including dependencies that arrive transitively or through a package. -avoidWhen: >- - Your architecture is still moving or the layering is not agreed, so a failing dependency rule - would be noise rather than a decision — or you need a single repository-specific assertion that a - few lines in a test express more directly than a policy file. -repository: purview-dev/architests -category: developer-tooling -status: stable -order: 85 -docs: - source: github-path - path: docs -targetFrameworks: - - net10.0 - - net11.0 -packages: - - id: Purview.Architecture.Testing - description: The policy reader, project and assembly graph, rule evaluator, and the TUnit base class. - primary: true -related: - - engineering-playbook - - build-sdk -useCases: - - audience: developer - title: The whole rule set from a policy file and one derived class - scenario: >- - You want your layering enforced by the build, but you do not want to hand-write the same - dependency-direction and forbidden-reference tests in every repository. - code: | - // .config/architecture-policy.json declares the responsibilities. - // This is the entire test suite. - [InheritsTests] - public sealed class ArchitectureTests : PurviewArchitectureTests; - language: csharp - outcome: >- - One policy file plus one derived test class is the whole suite. Each rule is a separate test, - so a failure names the rule rather than collapsing the set into one assertion. - evidence: >- - The base class ships twelve rule ids as separate [Test]s — graph discovery, naming, - discouraged name, dependency matrix, assembly matrix, sibling independence, composition - boundary, forbidden package, forbidden framework, cycle, test reference and waiver integrity — - plus a schema-validation test that runs first. [InheritsTests] is required: without it TUnit - discovers nothing, the run is green and nothing is enforced, which TUnit's own analyzer - reports as TUnit0030. - docsPage: getting-started - - audience: developer - title: Catch a type-level dependency a ProjectReference never shows - scenario: >- - A project file only shows declared ProjectReferences. A type that arrives transitively through - another project, or through a package, is invisible to a project-level check. - code: | - "assemblyRules": { - "enabled": true, - "assemblyRoots": [], - "assemblyGlobs": ["*.dll"] - } - language: json - outcome: >- - The same mayDependOn/mustNotDependOn matrix is applied to the types each compiled assembly - actually references. An empty assemblyRoots scans the test output directory, which already - holds every project the test project references. - evidence: >- - The reader opens each assembly with System.Reflection.Metadata and walks the TypeReference - table — nothing is loaded, executed, or resolved through a probing path, so a type initialiser - never runs. Enabling the rule with no production assemblies found is a failure, not a silent - pass. - docsPage: type-level-rules - - audience: architect - title: A dependency the policy is silent about is a violation, not permission - scenario: >- - Your layering is agreed and documented, and you want a reference that points the wrong way to - fail the build rather than erode the design one reasonable-looking reference at a time. - code: | - { - "version": 2, - "sourceRoots": ["src"], - "responsibilities": [ - { - "name": "Domain", - "category": "domain", - "purpose": "The domain model, its invariants and its rules.", - "mayDependOn": [], - "mustNotDependOn": ["Application", "Persistence", "Composition"] - } - ] - } - language: json - outcome: >- - The matrix is applied three ways: the same responsibility is always allowed, mustNotDependOn is - a violation, and a reference the matrix neither permits nor forbids is also a violation — so a - gap in the policy is surfaced instead of passing. - evidence: >- - A project name is classified by its first segment only, so Persistence.SqlServer and - Persistence follow the same rules and qualification is a naming choice rather than a different - set of rules. - docsPage: policy-reference - - audience: team-lead - title: A reviewed waiver instead of switching a rule off - scenario: >- - One project legitimately departs from the architecture policy, and you do not want to answer - that by disabling the rule for the whole repository. - code: | - { - "waivers": [ - { - "project": "Persistence.Legacy", - "mapsTo": "Persistence", - "rules": ["forbiddenPackage"], - "reason": "The legacy EF6 store is being replaced and still needs EntityFramework.", - "reviewedOn": "2026-10-16" - } - ] - } - language: json - outcome: >- - The departure is per project, carries a reason and a review date, keeps every other rule in - force, and is itself checked. SkipRule opts a whole repository out with no record, so a waiver - is the narrower choice. - evidence: >- - Any rule id may be waived, including siblingIndependence and assemblyDependencyMatrix, but an - unknown id is a waiverIntegrity failure — a typo cannot silently excuse nothing — and only - graphDiscovery and waiverIntegrity are not waivable. - docsPage: policy-reference - - audience: contributor - title: Add a bespoke rule to the same reporting and waiver model - scenario: >- - You need a repository-specific check — a banned API, a required convention — and do not want a - second architecture framework to maintain alongside the standard set. - code: | - [InheritsTests] - public sealed class ArchitectureTests : PurviewArchitectureTests - { - protected override IReadOnlyList<IArchitectureRule> AdditionalRules => [new NoConsoleLoggingRule()]; - - sealed class NoConsoleLoggingRule : IArchitectureRule - { - public string Rule => "noConsoleLogging"; - - public IReadOnlyList<ArchitectureViolation> Evaluate(ArchitectureContext context) => - context.Projects.Values - .Where(project => !project.IsTestProject) - .Select(project => new ArchitectureViolation(Rule, project.Name, "Console logging is banned here.")) - .ToArray(); - } - } - language: csharp - outcome: >- - An additional rule runs as its own test, honours SkipRule by its rule id, and is excused by a - matching waiver without any extra plumbing — the same reporting the built-in rules use. - evidence: >- - The evaluator takes the parsed policy, the project graph and the assemblies as constructor - arguments, so a rule is testable as a small in-memory fixture rather than a repository on - disk — which is how the package's own rules are tested. - docsPage: extending diff --git a/src/src/data/projects/aspire-resourcekit.yml b/src/src/data/projects/aspire-resourcekit.yml deleted file mode 100644 index 5064cc7..0000000 --- a/src/src/data/projects/aspire-resourcekit.yml +++ /dev/null @@ -1,73 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: aspire-resourcekit -name: Aspire ResourceKit -shortDescription: Strongly typed, source-generated resource kits for .NET Aspire. -description: >- - A source-generator-powered framework for structuring .NET Aspire AppHost - resource composition as strongly typed, test-friendly classes. Generated - host wiring, typed options, and enablement toggles keep large AppHosts - maintainable and discoverable. -origin: >- - Large Aspire AppHosts repeatedly accumulated procedural resource wiring and configuration, - creating a need for a typed, testable way to package those conventions. -useWhen: >- - Your Aspire AppHost has reusable resource groups, configuration, or enablement rules that - should be strongly typed, discoverable, and testable. -avoidWhen: >- - Your AppHost is small and direct resource declarations remain clearer than introducing a - resource-kit abstraction. -repository: purview-dev/aspire-resourcekit -category: aspire -status: stable -order: 50 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net10.0 -packages: - - id: Purview.Aspire.ResourceKit - description: Runtime and source generator for resource kits. - primary: true -useCases: - - audience: architect - title: Typed, testable resource groups in a large AppHost - scenario: >- - A large Aspire AppHost accumulates procedural resource wiring and configuration that is hard - to test and easy to misconfigure. - code: | - [HostKit] - partial class ShopHostKit; - - [ResourceDefinition<Projects.Example_Service>("api")] - partial class ApiResourceKit - { - protected override IResourceBuilder<ProjectResource> BuildResource( - IDistributedApplicationBuilder builder) - => builder.AddProject<Projects.Example_Service>(Name); - } - language: csharp - outcome: >- - Resource definitions become strongly typed, source-generated classes with generated host - wiring and typed options. - evidence: >- - One [HostKit] plus one [ResourceDefinition] per resource replaces procedural AppHost code, and - the analyzer validates the wiring at compile time. - docsPage: examples - - audience: team-lead - title: Configure and toggle resources without editing the AppHost - scenario: >- - You want enablement rules and configuration to be declarative and discoverable instead of - buried in the AppHost entry point. - outcome: >- - Typed options and enablement toggles are generated for each resource kit, so behaviour is - configured rather than coded. - evidence: >- - Resource kits can be unit tested with the testing helpers, independent of a running AppHost. - docsPage: configuration-and-options diff --git a/src/src/data/projects/aspirec4.yml b/src/src/data/projects/aspirec4.yml deleted file mode 100644 index 25d6be1..0000000 --- a/src/src/data/projects/aspirec4.yml +++ /dev/null @@ -1,66 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: aspirec4 -name: AspireC4 -shortDescription: Live LikeC4 architecture diagrams from the Aspire resource graph. -description: >- - An Aspire extension that generates live LikeC4 architectural diagrams - from the Aspire resource graph, with a Roslyn source generator for - compile-time validation of tags, kinds, groups, and metadata. -origin: >- - Aspire already holds a useful model of a distributed application, so manually maintaining a - separate architecture diagram was repetition that could be removed. -useWhen: >- - You use .NET Aspire and want live LikeC4 diagrams derived from the resource graph, with - compile-time checks for architectural metadata. -avoidWhen: >- - You do not use Aspire, need a manually curated architecture model, or require diagrams that - intentionally differ from the running application topology. -repository: purview-dev/aspirec4 -category: aspire -status: stable -order: 55 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net8.0 -packages: - - id: AspireC4.Hosting - description: Aspire hosting extension for the AspireC4 plugin, generating a dynamic LikeC4 architecture diagram for your Aspire application. - primary: true -useCases: - - audience: developer - title: A live architecture diagram with three lines of code - scenario: >- - You already describe your distributed application in Aspire and do not want to maintain a - separate architecture diagram that drifts from reality. - code: | - var builder = DistributedApplication.CreateBuilder(args); - - builder.AddAspireC4(); - - builder.Build().Run(); - language: csharp - outcome: >- - AspireC4 writes the generated LikeC4 model, starts the LikeC4 sidecar, and refreshes the - diagram whenever the Aspire application changes. - evidence: >- - The diagram is derived from the running resource graph, so it cannot silently fall out of date - the way a hand-drawn one can. - docsPage: dashboard-integration - - audience: architect - title: Validate architectural metadata at compile time - scenario: >- - You want tags, kinds, groups, and metadata in your architecture model checked before the - application even runs. - outcome: >- - A Roslyn source generator validates the architectural metadata while the AppHost compiles. - evidence: >- - Architectural metadata mistakes fail the build instead of surfacing in a diagram nobody reads. - docsPage: generated-output diff --git a/src/src/data/projects/astroc4.yml b/src/src/data/projects/astroc4.yml deleted file mode 100644 index d05e90f..0000000 --- a/src/src/data/projects/astroc4.yml +++ /dev/null @@ -1,230 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: 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. -useWhen: >- - Your documentation is an Astro/Starlight site and the architecture it describes is already, or - should be, a LikeC4 model in the repository: you want the diagram and the prose to be reviewed - together, and code fences in the LikeC4 language to be coloured without owning an - ec.config.mjs. -avoidWhen: >- - Your site is not Astro (both entry points compile the model through LikeC4's Vite plugin and - ship React islands), or the architecture diagram is drawn once and does not need to stay in - step with the code — a static image is cheaper than a model, a compiler and a browser island. -repository: purview-dev/astroc4 -category: developer-tooling -status: preview -order: 75 -docs: - source: github-path - path: docs/wiki - # The guide pages moved into a topic folder, so their published URLs gain a - # `guide/` segment. The old flat addresses keep working through a meta-refresh - # redirect, written only once the destination page is published (ADR 0011). - redirects: - architecture: contributing/architecture - components: guide/components - configuration-reference: guide/configuration-reference - fences: guide/fences - getting-started: guide/getting-started - icons: guide/icons - internationalization: guide/internationalization - local-development: contributing/local-development - repository-ci-cd: contributing/repository-ci-cd - syntax-highlighting: guide/syntax-highlighting -skills: true -packages: - - id: '@purview-dev/astroc4' - registry: npm - description: The Starlight plugin, the plain-Astro integration, the fence transform, the grammar pipeline and the Astro components. - primary: true -related: - - aspirec4 - - engineering-playbook -acknowledgments: - - name: LikeC4 - url: https://github.com/likec4/likec4 - description: >- - The C4 modelling language, compiler and renderer the plugin embeds; the highlighting grammar - is derived at build time from its Langium language definition. -useCases: - - audience: developer - title: A diagram and the prose around it in the same diff - scenario: >- - A page explains a request path, and the diagram beside it lives in a design tool that nobody - updates when the path changes, so the two disagree and a reviewer cannot see it. - code: | - ````mdx - --- - title: Request path - --- - - ```likec4 title="Request path" height=360 - specification { element box } - model { - browser = box 'Browser' - api = box 'API' - store = box 'Postgres' - browser -> api 'GET /orders' - api -> store 'select' - } - views { view index { include * } } - ``` - ```` - language: mdx - outcome: >- - The diagram is the page: the fence is compiled and laid out during the build, the layout is - passed to the island as serialised JSON, and a change to the model is a line in the pull - request a reviewer can read next to the prose. - evidence: >- - The fence runs LikeC4.fromSource plus layoutedModel at build time, so nothing is laid out in - the browser; a typo fails astro build with the file name and parser message rather than - shipping a blank frame, and layouts are memoised by a hash of the snippet so a page - re-rendered on every dev edit pays for it once. The same fence in a .md page stays a code - block deliberately, because Astro cannot put a component there. - - audience: developer - title: The same diagrams in a plain Astro site, without Starlight - scenario: >- - The documentation site is plain Astro rather than Starlight, so a Starlight plugin would be - inert there and the diagrams have no way to reach the page. - code: | - // astro.config.mjs - import { defineConfig } from 'astro/config'; - import mdx from '@astrojs/mdx'; - import expressiveCode from 'astro-expressive-code'; - import astroc4 from '@purview-dev/astroc4/integration'; - - export default defineConfig({ - integrations: [astroc4(), expressiveCode(), mdx()], - }); - 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. - - audience: developer - title: Highlighting that follows LikeC4, with no ec.config.mjs - scenario: >- - You want ```c4 and ```likec4 fences coloured in your docs, but Shiki has no LikeC4 grammar - and the community TextMate file is missing the shapes and keywords upstream added this year. - code: | - // astro.config.mjs — there is no ec.config.mjs anywhere in the site - import { defineConfig } from 'astro/config'; - import starlight from '@astrojs/starlight'; - import react from '@astrojs/react'; - import astroc4 from '@purview-dev/astroc4'; - - export default defineConfig({ - integrations: [ - starlight({ plugins: [astroc4({ highlighting: { ref: 'v1.60.0' } })] }), - react(), - ], - }); - language: js - outcome: >- - The plugin derives a TextMate grammar from likec4/likec4's Langium language definition and - injects it into Starlight's Expressive Code options from the config:setup hook, so every - LikeC4 fence is coloured and an existing ec.config.mjs keeps its own languages untouched. - evidence: >- - Only the word lists are generated; the structure (comments, triple-quoted strings, #tag - versus #hex, tech:astro icons, -[https]-> connectors) is a curated layer on top. The - difference is testable: ElementShape gained agent after v1.59.4, so a build pinned to that - tag paints agent as a plain identifier while main paints it as a shape. Expressive Code - concatenates shiki.langs, which is why a site with its own grammar ends up with both. - - audience: architect - title: One model in the repository, many diagram views in the docs - scenario: >- - Several documentation pages describe different slices of the same system, and you want them - to read from one model so a change to a dependency cannot leave three diagrams telling three - stories. - code: | - ```mdx - --- - title: Deployment - --- - - import LikeC4View from '@purview-dev/astroc4/components/LikeC4View.astro'; - - <LikeC4View viewId="production" projectId="platform" height={560} /> - ``` - language: mdx - outcome: >- - The .c4 model lives in src/likec4 and each page selects a view of it; the model is compiled - once by LikeC4's Vite plugin, and every page hydrates the same islands, so a view cannot - describe a system the model does not contain. - evidence: >- - The plugin compiles every likec4.config.json project under the site root into likec4:model, - likec4:icons and likec4:projects virtual modules, and the first project found is the default - for a view that omits projectId — which is also the failure mode, since a vendored example - model can silently become the default. An unresolvable element kind fails the build instead - of rendering a partial diagram. - - audience: team-lead - title: Prove the diagrams actually hydrate before calling the docs built - scenario: >- - A static build exits 0 even when every island fails to hydrate, so the pipeline is green and - the published page shows empty frames. - code: | - bun run build - bun scripts/smoke.ts http://localhost:4321 - bun run test:site - language: shell - outcome: >- - The browser smoke test and the packed-consumer build are the evidence: one drives a real - page and checks hydration, icons, highlighting and translations, the other installs the - tarball into a throwaway Starlight site so publishing mistakes surface before npm does. - evidence: >- - The smoke test asserts at least four distinct colour variables per highlighted block, counts - prerendered pack icons and <img> icons, and fails on a file:// URL in an <img src> — the - build-machine path that LikeC4's imageAliases bakes into the bundle. test:site catches the - cases the playground cannot see: a file missing from files, an exports subpath pointing at an - unpublished file, or an undeclared peer dependency. - docsPage: troubleshooting - - audience: contributor - title: Regenerate the grammar instead of hand-editing it - scenario: >- - Upstream LikeC4 adds a shape or a keyword, and the highlighting has to follow without someone - patching a TextMate JSON file and hoping the next release does not overwrite it. - code: | - bun run grammar:sync # from main - bun run grammar:sync --ref v1.60.0 # or pin the tag you ship against - bun run grammar:check # fail if the committed snapshot is stale - language: shell - outcome: >- - The Langium snapshot and the TextMate grammar are generated artefacts: the working tree says - so, grammar:check fails when they drift from the pinned ref, and the next upstream addition - reaches highlighting without a code change. - evidence: >- - src/grammar/likec4.tmLanguage.json is re-derived from the committed Langium text on every run - (single-digit milliseconds), and snapshot.test.ts re-derives it again and compares, so a - change to the derivation that is not followed by a regeneration fails bun run test. Because - the icon packs come from LikeC4's LIB_ICON terminal, a pack upstream adds is highlighted and - rendered without an edit here either. diff --git a/src/src/data/projects/build-sdk.yml b/src/src/data/projects/build-sdk.yml deleted file mode 100644 index 8f3e048..0000000 --- a/src/src/data/projects/build-sdk.yml +++ /dev/null @@ -1,70 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: build-sdk -name: Build SDK -shortDescription: Convention-driven MSBuild SDK for .NET project defaults. -description: >- - A reusable MSBuild SDK NuGet package that delivers standardised .NET - project defaults, code-style enforcement, test-framework wiring, and - Central Package Management integration. Install it once per repo; every - project beneath the repo root inherits everything automatically. -origin: >- - Repeating project properties, analyzers, test wiring, and package-management conventions in - every repository made a centrally maintained MSBuild SDK the simpler option. -useWhen: >- - You want Purview's standard .NET project defaults applied consistently across an entire - repository from one versioned SDK declaration. -avoidWhen: >- - Your repository follows different conventions or needs project-by-project control over the - settings the SDK intentionally standardises. -repository: purview-dev/build-sdk -category: build-tooling -status: stable -order: 70 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - msbuild -install: msbuild-sdk -packages: - - id: Purview.BuildSdk - description: MSBuild SDK for standardised project defaults. - primary: true -useCases: - - audience: team-lead - title: Apply repository-wide defaults from one declaration - scenario: >- - You want standard .NET project defaults, code-style enforcement, test wiring, and central - package management without repeating the same properties in every project. - code: | - { - "msbuild-sdks": { - "Purview.BuildSdk": "1.0.0" - } - } - language: json - outcome: >- - Install the SDK once via global.json and Directory.Build.props; every project beneath the - repository root inherits everything automatically. - evidence: >- - One versioned SDK declaration replaces per-project property groups, so conventions are - upgraded in one place. - docsPage: configuration-reference - - audience: contributor - title: Bootstrap a new repository - scenario: >- - You are starting a repository and want the organisation's conventions in place before the - first project exists. - outcome: >- - The SDK can bootstrap a global.json at the repository root when one is missing, then applies - project-type detection, analyzers, and test wiring. - evidence: >- - Repository bootstrap, analyzers, and testing wiring are documented and generated, not copied - between repos by hand. - docsPage: repository-bootstrap diff --git a/src/src/data/projects/build.yml b/src/src/data/projects/build.yml deleted file mode 100644 index a31ac04..0000000 --- a/src/src/data/projects/build.yml +++ /dev/null @@ -1,74 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: build -name: Build -shortDescription: The shared build, test, and release system for purview-dev. -description: >- - The shared build/test/release system for the purview-dev organisation. A - Modular Pipelines based .NET tool packaged as a pinned dotnet tool, exposed - through a GitHub composite action and thin reusable workflows. Consuming - repositories own configuration; they do not own pipeline source code. -origin: >- - Maintaining near-identical build, test, pack, and release logic across repositories turned - the pipeline itself into reusable tooling. -useWhen: >- - You maintain a Purview repository and want the shared, centrally versioned build and release - conventions used across the organisation. -avoidWhen: >- - Your repository is outside that convention set or needs a substantially different pipeline - whose lifecycle should remain independent. -repository: purview-dev/build -category: build-tooling -status: stable -order: 60 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net10.0 -install: dotnet-tool -packages: - - id: Purview.Build - description: Pinned dotnet tool implementing the shared pipeline. - primary: true -assets: - - path: purview-build.schema.json - output: schemas/purview-build.json - description: The purview-build.json configuration schema, served from a stable purview.dev URL. -useCases: - - audience: team-lead - title: One reusable pipeline for every repository - scenario: >- - You maintain several repositories that each repeat the same build, test, pack, and release - logic, and the copies drift apart. - code: | - # .github/workflows/pr.yml - jobs: - build: - uses: purview-dev/build/.github/workflows/purview-build.yml@main - secrets: inherit - language: yaml - outcome: >- - Consumers reference the reusable workflow or composite action and configure behaviour with - purview-build.json instead of owning pipeline source. - evidence: >- - Pipeline code lives in one repository; a consuming repository is a short workflow file plus - configuration. - docsPage: repository-ci-cd - - audience: contributor - title: Dogfood the same pipeline the organisation uses - scenario: >- - You want local commands, pull-request CI, and releases to run the exact same tool and - conventions, rather than three approximations. - outcome: >- - The pipeline is a Modular Pipelines .NET tool packaged as a pinned dotnet tool, callable from - a composite action, reusable workflows, or the local command line. - evidence: >- - Purview's own repositories use the published pipeline, so the tool is exercised on every - build. - docsPage: pipeline-modules diff --git a/src/src/data/projects/containers.yml b/src/src/data/projects/containers.yml deleted file mode 100644 index 21b1931..0000000 --- a/src/src/data/projects/containers.yml +++ /dev/null @@ -1,182 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: containers -name: Containers -shortDescription: Throwaway Linux containers for .NET integration tests — on WSL Containers with no Docker installation, or on Docker. -description: >- - A Testcontainers-style library for .NET with one API and two interchangeable backends: Microsoft - WSL Containers (WSLC) with no Docker installation, or Docker through Testcontainers. Containers are - created through backend-neutral abstractions (Purview.Containers.Core) and the backend is resolved at - run time, so the same test code runs on WSLC (Purview.Containers.Wsl) or Docker - (Purview.Containers.Docker) unchanged. The WSLC backend talks to the WSLC managed C# API directly — - no wslc.exe, no docker CLI, no Docker.DotNet. - Typed service modules add PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, and NATS, each - with its own defaults, configuration, readiness wait strategy, and connection-string helper. The - umbrella package Purview.Containers brings the abstractions plus both backends in a single reference. -origin: >- - Integration tests that use real infrastructure on Windows needed a Docker daemon installed and - running first. WSL Containers makes the container runtime a Windows feature, so the same - throwaway-container workflow could be built straight on its managed API — and the same abstractions - could fall back to Docker wherever WSLC is not available, which is why the library grew a portable - net10.0 facade and a Docker backend rather than staying Windows-only. -useWhen: >- - You want real PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, or NATS instances in - integration tests, and you want the same suite to run on WSL Containers on a Windows developer - machine and on Docker in CI without changing a line of test code. -avoidWhen: >- - You need a container runtime other than WSL Containers or Docker, or you require API stability: the - public API, defaults, and packaging rules can change between prereleases and there is no production - support guarantee. -repository: purview-dev/containers -category: developer-tooling -status: preview -experimental: true -order: 90 -docs: - source: github-path - path: docs/wiki - exclude: - - _Sidebar.md - - Home.md -targetFrameworks: - - net10.0 - - net10.0-windows10.0.19041.0 - - net11.0 - - net11.0-windows10.0.19041.0 -packages: - - id: Purview.Containers - description: The umbrella — references the abstractions and both backends, so one reference runs the same tests on WSLC on Windows and Docker elsewhere. - primary: true - - id: Purview.Containers.Core - description: Backend-neutral abstractions — the container contract, builders, wait strategies, images, mounts, networking, diagnostics, and backend selection. - - id: Purview.Containers.Wsl - description: WSL Containers backend — sessions, images, ports, mounts, exec, logs, and diagnostics for WSLC; a portable facade plus the Windows implementation. - targetFrameworks: - - net10.0 - - net10.0-windows10.0.19041.0 - - net11.0 - - net11.0-windows10.0.19041.0 - - id: Purview.Containers.Docker - description: Docker backend — the same containers on any reachable Docker daemon, driven by Testcontainers. - - id: Purview.Containers.PostgreSql - description: PostgreSQL module — defaults, configuration, pg_isready readiness, and Npgsql connection string. - - id: Purview.Containers.Redis - description: Redis module — defaults, configuration, redis-cli ping readiness, and connection string. - - id: Purview.Containers.MsSql - description: SQL Server module — defaults, licence acceptance, configuration, and connection string. - - id: Purview.Containers.MySql - description: MySQL module — defaults, configuration, readiness wait strategy, and connection string. - - id: Purview.Containers.RabbitMq - description: RabbitMQ module — defaults, credentials, configuration, and AMQP connection string. - - id: Purview.Containers.Azurite - description: Azurite module — defaults, account key, and Azure Storage connection string. - - id: Purview.Containers.Nats - description: NATS module — defaults, configuration, and client endpoint. -acknowledgments: - - name: Testcontainers for .NET - url: https://github.com/testcontainers/testcontainers-dotnet - description: The Docker backend is driven by Testcontainers and the module connection-string shapes follow it; Purview.Containers is not affiliated with or endorsed by the Testcontainers project. - - name: Microsoft WSL Containers - url: https://www.nuget.org/packages/Microsoft.WSL.Containers - description: The managed C# API behind WSLC that the WSL Containers backend is built against directly, with no wslc.exe or docker CLI. -useCases: - - audience: developer - title: The same test on WSL Containers or Docker - scenario: >- - Your integration suite needs real infrastructure, but the machines it runs on differ: a Windows - developer laptop with WSL Containers and a Linux CI runner with a Docker daemon. - code: | - await using var container = new ContainerBuilder() - .WithImage("docker.io/library/redis:latest") - .WithPortBinding(6379, assignRandomHostPort: true) - .WithWaitStrategy(Wait.ForTcpPort(6379)) - .Build(); - - await container.StartAsync(); - ushort port = container.GetMappedPublicPort(6379); - language: csharp - outcome: >- - The test never names a backend. Automatic selection prefers WSLC where it is usable and falls - through to Docker everywhere else; PURVIEW_CONTAINERS_BACKEND pins one (wsl or docker) when a job - should fail loudly instead of falling back. - evidence: >- - One API, two backends: the same builder, wait strategies, and connection-string helpers run on both - Purview.Containers.Wsl and Purview.Containers.Docker with no code change. - docsPage: backends - - audience: developer - title: Zero-config tests that pick a backend themselves - scenario: >- - You want real PostgreSQL and Redis in your tests and would rather not choose a container runtime, - add a backend package explicitly, or write any registration or environment configuration. - code: | - await using var postgres = new PostgreSqlBuilder().WithDatabase("app").Build(); - await postgres.StartAsync(); // waits for pg_isready - - await using var connection = new NpgsqlConnection(postgres.GetConnectionString()); - await connection.OpenAsync(); - language: csharp - outcome: >- - Add the umbrella Purview.Containers to a plain net10.0 project: each backend package's - buildTransitive assets generate the registration in your assembly, so WSLC is used on a Windows - machine and Docker everywhere else with no code or configuration. - evidence: >- - Each backend package ships buildTransitive assets that generate a module initializer in the - consumer's assembly, so no registration line and no environment variable are required; those - assets flow transitively through the umbrella. - docsPage: using-in-your-tests - - audience: developer - title: A typed service module instead of a bare image - scenario: >- - You need a throwaway PostgreSQL (or Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS) and do not - want to look up its image, port, environment, and readiness probe every time. - code: | - await using var postgres = new PostgreSqlBuilder() - .WithDatabase("tests") - .WithPassword("postgres") - .Build(); - - await postgres.StartAsync(); // returns once pg_isready succeeds - language: csharp - outcome: >- - The module supplies the default image, port mapping, and readiness wait strategy, so StartAsync() - returns once the instance is genuinely ready, and GetConnectionString() points at the mapped host - port — the same shape Testcontainers modules use. - evidence: >- - Seven service modules ship (PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS), and a - module contributes only its image, ports, environment, wait strategy, and connection string — - never the shared runtime. - docsPage: modules - - audience: architect - title: One Windows prerequisite, Docker in CI - scenario: >- - You want integration tests that use real infrastructure on Windows developer machines and CI - agents, without making Docker Desktop a requirement of the minimum Windows toolchain. - code: | - foreach (var backend in await ContainerBackends.ProbeAllAsync()) - { - Console.WriteLine($"{backend.Name}: usable={backend.IsUsable} version={backend.Version}"); - } - language: csharp - outcome: >- - The abstractions and modules are portable net10.0, so a platform-neutral project binds the WSLC - facade on Windows and behaves as Docker-only everywhere else; ProbeAllAsync() reports exactly - which runtime a machine has before a test runs. - evidence: >- - Purview.Containers.Wsl ships a portable net10.0 facade and a net10.0-windows10.0.19041.0 - implementation, and the repository builds twenty-one throwaway consumer projects to prove the - target-framework contract and the PCC0001/PCC0002 guards. - docsPage: consumer-requirements - - audience: contributor - title: Add a service module - scenario: >- - You want to add a module for another service, or fix one of the existing seven, and need to know - exactly what a module is allowed to contribute. - outcome: >- - A module supplies only the default image, ports, environment, its own WithXxx configuration, a - wait strategy, and connection-string helpers; the generic builder snapshots the accumulated state - into an immutable configuration, so modules never duplicate container runtime infrastructure. - evidence: >- - Every module references Purview.Containers.Core only — never a backend package — which is what lets - one module package run on WSLC or Docker, and each module has its own unit and integration test - project to prove itself. - docsPage: contributing-modules diff --git a/src/src/data/projects/dotnet-logging-source-generators.yml b/src/src/data/projects/dotnet-logging-source-generators.yml deleted file mode 100644 index 63fece8..0000000 --- a/src/src/data/projects/dotnet-logging-source-generators.yml +++ /dev/null @@ -1,39 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: dotnet-logging-source-generators -name: Logging Source Generators -shortDescription: Early interface-based logging generation (archived). -description: >- - The original experiment in interface-based logging generation for .NET. - Archived and superseded by the Purview Telemetry SourceGenerator, which - generates logging together with Activities and Metrics from the same - interfaces. -origin: >- - This was the original exploration of interface-driven logging generation and established the - approach that later grew into the broader Telemetry SourceGenerator. -useWhen: >- - Use it only when maintaining an existing dependency that cannot yet move to its successor. -avoidWhen: >- - For new work, use Telemetry SourceGenerator instead; this project is archived and no longer - actively developed. -repository: purview-dev/dotnet-logging-source-generators -category: source-generation -status: archived -supersededBy: telemetry-sourcegenerator -order: 80 -targetFrameworks: - - net6.0 - - net7.0 -packages: [] -useCases: - - audience: developer - title: Move to the supported successor - scenario: >- - You depend on the original interface-based logging generator and want logging, activities, and - metrics generated together. - outcome: >- - Telemetry SourceGenerator generates logging alongside Activities and Metrics from the same - interfaces, with DI registration and multi-targeting. - evidence: >- - This project is archived and no longer developed; the successor covers a superset of its - behaviour from one interface. diff --git a/src/src/data/projects/engineering-playbook.yml b/src/src/data/projects/engineering-playbook.yml deleted file mode 100644 index 197043d..0000000 --- a/src/src/data/projects/engineering-playbook.yml +++ /dev/null @@ -1,226 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: engineering-playbook -name: Engineering Playbook -shortDescription: The reusable Purview engineering conventions — repository shape, architecture as tests, verification tiers, and agent enablement. -description: >- - The conventions the Purview projects are built on, written down once with the failure each one prevents, - the mechanism that makes it true, and what a smaller repository does instead. It covers how a repository - is laid out and named, how the architecture is held by tests that read the compiled assemblies, which - checks run in which verification tier, how value objects, schemas and results cross a boundary, how tests - are written and where their data comes from, how a repository is made legible to a coding agent, and how - its documentation is published. It is documentation-first and ships no library: it holds the conventions, - ready-to-copy templates, and a small layered reference implementation whose dependency-direction rules - fail the build, so the rules are demonstrated rather than asserted. -origin: >- - The conventions were already real and already enforced, but they were only discoverable by reading the - repositories and inferring the pattern from the repetition. That worked while one person held the whole - picture and stopped working as soon as a second contributor or a coding agent had to decide which of two - plausible patterns was the intended one. Writing them down in one place — with the evidence attached, and - scaled so a smaller repository can take the part that fits — turned an oral tradition into something a - repository can be pointed at. -useWhen: >- - You are starting a repository that should look and behave like the Purview projects, adopting the SDK into - an existing one, or deciding which of the conventions are worth the cost at your size. The playbook's - profiles, templates and reference implementation are all meant to be taken in part. -avoidWhen: >- - You want the SDK's own behaviour documented rather than the conventions built on top of it — read the - Build SDK's wiki instead — or you are looking for a scaffolding tool: the templates are files to read and - copy, not a generator. -repository: purview-dev/engineering-playbook -category: developer-tooling -status: preview -experimental: true -order: 95 -docs: - source: github-path - path: docs/wiki - rootPage: Home.md - # `_Sidebar.md` is the wiki's navigation, not a page. Nothing else is - # excluded: the wiki is plain Markdown with no site configuration, so - # `Home.md` is the hub (`rootPage` above) and is published as the landing page. - exclude: - - _Sidebar.md - # A page's folder is part of its URL (ADR 0011), so `Dependency-Versions.md` - # publishes at `/docs/engineering-playbook/foundations/dependency-versions/`. - # The flat address is kept as an alias for anyone who looks for that page at - # the docs root: the build writes a meta-refresh redirect there, and only once - # the nested page it forwards to actually exists. - redirects: - dependency-versions: foundations/dependency-versions -related: - - build-sdk - - containers - - value-objects - - results - - zodsharp -useCases: - - audience: developer - title: A repository that satisfies every convention on its first build - scenario: >- - You are starting a repository and want the project defaults, code style, test wiring and assembly - identity to be right from the first commit, instead of discovering the conventions one review comment - at a time. - code: | - { - "sdk": { "version": "LATEST", "allowPrerelease": false }, - "msbuild-sdks": { "Purview.BuildSdk": "LATEST" }, - "test": { "runner": "Microsoft.Testing.Platform" } - } - language: json - outcome: >- - A pinned SDK plus a `Directory.Build.props` that sets one namespace prefix is the whole of the - repository's build configuration. Every project beneath it inherits the target framework, language - version, nullable context, analyzers and assembly identity, so a project file is two lines and a test - project file is empty. `LATEST` is the playbook's own placeholder for the newest version the runtime - supports — the file requires a number, so the snippet shows a lookup rather than a claim that expires - with the next release. - evidence: >- - Getting Started walks the steps in the order you would create the files, and every repository-level - file has a copy-paste version in the templates folder with a comment explaining the one thing about it - that is easy to get wrong. - docsPage: getting-started - - audience: architect - title: Architecture that fails the build when a dependency points the wrong way - scenario: >- - Your layering is documented and agreed, and you want it to stay true — rather than being eroded one - convenient project reference at a time, each of which looks reasonable in isolation. - code: | - [Test] - public async Task Application_GivenItsReferences_DependsOnTheDomainAndNotOnInfrastructure() - { - // Arrange - var application = typeof(ConventionCatalogue).Assembly; - - // Act - var referenced = ReferencedAssemblyNames(application); - - // Assert - await Assert.That(referenced).Contains($"{RepositoryPrefix}.Domain"); - await Assert.That(referenced).DoesNotContain($"{RepositoryPrefix}.Infrastructure"); - } - language: csharp - outcome: >- - The allowed dependency directions are data in a test that reads the compiled assemblies' metadata - references, so a reference that points the wrong way fails the build with the offending assembly - named — no diagram to keep in step and no separate tool to run. - evidence: >- - The reference implementation's Architecture.UnitTests project asserts four rules against three real - assemblies and is built by the same pipeline as everything else. The page also records the two traps - found by writing it, including a source generator that emits public types into its own namespace. - - audience: team-lead - title: A verification gate that stays credible - scenario: >- - The pull-request build has started needing a database and four minutes of waiting, and somebody is - about to make it optional — at which point nothing is gated at all. - code: | - { - "Build": { - "Solution": "src/Acme.slnx", - "TestRoot": "src/tests", - "TestPatterns": "*UnitTests.csproj", - "TestFilter": "/*/*/*/*[Category=Unit]" - } - } - language: json - outcome: >- - Tiers are expressed by where a test lives rather than by an attribute: the SDK reads the test project's - name suffix and emits the assembly-level category the pipeline filters on, so adding a slow suite keeps - it out of the fast tier without editing a filter or remembering an attribute. - evidence: >- - The verification model page documents the shared workflow's inputs, the configuration probe order, and - the two ways a repository and the shared workflow quietly disagree about what a green build means — and - names the repository that runs its container-backed suites as a second job on the same runner. - - audience: developer - title: One builder for every test's domain content - scenario: >- - You are writing a test, need a domain object, and do not want to spell out a constructor that will - change — nor leave the reader guessing which of the values you passed actually matter to the assertion. - code: | - public static Domain.Convention Convention( - Domain.ConventionId? id = null, - string? title = null, - VerificationTier? tier = null, - bool? enforcedByBuild = null) => - Domain.Convention.Create( - id ?? ConventionId(), - title ?? Faker.Lorem.Sentence(4), - tier ?? Faker.Random.Enum<VerificationTier>(), - enforcedByBuild ?? Faker.Random.Bool()); - language: csharp - outcome: >- - An omitted argument is generated and a supplied argument is used exactly, so a test reads as a list of - the values it is actually proving and everything else is realistic without the test saying so. One - constructor change is one edit rather than a repository-wide one. - evidence: >- - TestBuilder lives in a shared testing project the SDK references from every test project - automatically. The page also explains the two SDK rules that shaped its flat, ungrouped shape, and the - value-object exception where a test must name the rejected input itself. - - audience: contributor - title: A repository an agent can work in without hand-holding - scenario: >- - You want a coding agent to make a change that follows the repository's conventions rather than - confidently generalising from whichever pattern it found first. - code: | - | Path | Purpose | - | -- | -- | - | src/src/Domain | The reference implementation's value objects and aggregate | - | src/src/Application | The port and the service that owns the rules | - | src/tests/Architecture.UnitTests | Dependency-direction rules; a wrong reference fails the build | - language: markdown - outcome: >- - AGENTS.md states the purpose, the layout, the conventions and the definition of done, and the build - mirrors the SDK's own skills into the repository so the agent-facing guidance tracks the SDK version - rather than the repository's memory of it. - evidence: >- - The agent enablement page documents the layout of the agent folder, why the SDK's mirror writes a - generated .gitignore that lists exactly the files it owns, and why the guidance that makes a repository - obvious to an agent is the same guidance that makes it obvious to a new joiner. - - audience: architect - title: Take only the part of the playbook that fits - scenario: >- - You are convinced by some of the conventions and not others, and you want to know which ones are worth - the cost in a repository the size of yours — rather than adopting everything and discovering the - ceremony. - outcome: >- - Three profiles — one project, a few layers, several packages — each list what to take and what to - leave, and every page ends with an "at your scale" section that names the smaller version of the rule - explicitly. The templates are mapped to the profile that needs them. - evidence: >- - The playbook also documents what not to adopt early, with the reason each one is more expensive out of - order, and a migration order for an existing repository that keeps each step cheap and the build green. - - audience: team-lead - title: Data that crosses a boundary once, and is trusted after that - scenario: >- - Inbound payloads are validated in several places, an identifier is a string in one layer and a type in - another, and expected failures are thrown as exceptions that callers catch by message. - code: | - [Scalar] - public readonly partial record struct EmailAddress - { - public string Value { get; } - - static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; - } - language: csharp - outcome: >- - A value is a type rather than a primitive, `Create` validates at the boundary and `Hydrate` trusts - everything past it, normalisation runs before validation so there is exactly one canonical form, and - expected failures are values while exceptional circumstances still throw. - evidence: >- - The contracts page names the three public repositories that implement the rules — source-generated - value objects, result types with union errors, and a schema layer that also exports and imports JSON - Schema — and shows how a validation result is read rather than parsed. - - audience: contributor - title: Extend the playbook without turning it into a second source of truth - scenario: >- - You have found a convention that is real, enforced and not written down, and you want to add it without - duplicating something the SDK already documents. - outcome: >- - Four tests decide whether a rule belongs: it came from a real repository and a real failure, it is - reusable at more than one size, it is not the SDK's to state, and it is either enforced or explicitly - labelled a review obligation. - evidence: >- - The contributing page also sets the expectations for changing an existing rule — update every page that - states it, check the reference implementation still demonstrates it, and re-check whether the - enforcement moved between the build and review. diff --git a/src/src/data/projects/event-sourcing.yml b/src/src/data/projects/event-sourcing.yml deleted file mode 100644 index e229d56..0000000 --- a/src/src/data/projects/event-sourcing.yml +++ /dev/null @@ -1,102 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: event-sourcing -name: Event Sourcing -shortDescription: Aggregate-based event sourcing for .NET across any store. -description: >- - A .NET event sourcing framework for building aggregate-based applications. - Provider-agnostic store facades, source-generated aggregates and events, - transaction coordination for multi-aggregate saves, queryable snapshots - and read models, and storage providers for SQL Server, PostgreSQL, - MongoDB, Azure Storage, Azure Cosmos DB, and in-memory. -origin: >- - Aggregate, event, persistence, and transaction patterns kept recurring across applications, - so the reusable parts were separated from any one storage provider. -useWhen: >- - Your domain benefits from aggregate-based event sourcing and you want storage choices, - snapshots, read models, and transactions behind consistent abstractions. -avoidWhen: >- - A conventional state-based model is sufficient, or your application does not need the - operational and modelling trade-offs that come with event sourcing. -repository: purview-dev/event-sourcing -category: application-framework -status: preview -featured: true -order: 20 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net10.0 -packages: - - id: Purview.EventSourcing - description: Core abstractions, aggregates, facades, transactions, DI, and source generation. - primary: true - - id: Purview.EventSourcing.SqlServer - description: Azure SQL / SQL Server event stream and queryable snapshot stores. - - id: Purview.EventSourcing.Postgres - description: PostgreSQL event stream and queryable snapshot stores. - - id: Purview.EventSourcing.AzureStorage - description: Azure Table / Blob event store. - - id: Purview.EventSourcing.MongoDB - description: MongoDB event stream and queryable snapshot stores. - - id: Purview.EventSourcing.CosmosDb - description: Azure Cosmos DB queryable snapshot store. - - id: Purview.EventSourcing.InMemory - description: In-memory event and snapshot stores for local and test scenarios. - - id: Purview.EventSourcing.Validation.FluentValidation - description: FluentValidation adapter for aggregate save-time validation. - - id: Purview.EventSourcing.Validation.ZodSharp - description: Purview.ZodSharp adapter for aggregate save-time validation. -useCases: - - audience: developer - title: An aggregate that persists as events - scenario: >- - You want aggregate-based event sourcing without hand-writing the event stream, snapshot, and - transaction plumbing. - code: | - [Aggregate] - public partial class OrderAggregate : AggregateBase - { - public string CustomerId { get; private set; } = default!; - public decimal Total { get; private set; } - - [Event] - public partial void CreateOrder(string customerId); - - [Event] - public partial void AddLineItem(string productId, string productName, int quantity, decimal unitPrice); - } - language: csharp - outcome: >- - The source generator produces the aggregate plumbing; provider packages add stores for SQL - Server, PostgreSQL, MongoDB, Azure Storage, Cosmos DB, or in-memory. - evidence: >- - One [Aggregate] declaration, and switching storage means swapping a provider package rather - than rewriting the domain. - docsPage: solution-design-guide - - audience: architect - title: Choose the store late, keep the domain stable - scenario: >- - You need to start on one database and move providers later, but you do not want persistence - choices to leak into the domain model. - code: | - builder.Services.AddSqlServerEventStore(); - builder.Services.AddSqlServerSnapshotQueryableEventStore(); - language: csharp - outcome: >- - Domain code depends on provider-agnostic facades, while concrete stores live behind separate - packages and registration extensions. - evidence: >- - SQL Server, PostgreSQL, MongoDB, Azure Storage, and Cosmos DB are interchangeable at the - registration level, so the domain never references a store. - docsPage: sql-server-guide -related: - - zodsharp - - value-objects -discussions: false diff --git a/src/src/data/projects/openapi-xmlcomments.yml b/src/src/data/projects/openapi-xmlcomments.yml deleted file mode 100644 index 7e27232..0000000 --- a/src/src/data/projects/openapi-xmlcomments.yml +++ /dev/null @@ -1,123 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: openapi-xmlcomments -name: OpenAPI XmlComments -shortDescription: Keeps the ASP.NET Core OpenAPI XML-comment generator working when one documentation ID arrives twice. -description: >- - An MSBuild package for APIs that reference Microsoft.AspNetCore.OpenApi. The XML-comment source - generator builds one dictionary from the documentation of every project reference and of the API's - own compilation, and de-duplicates neither, so a documented type that arrives from more than one - assembly makes /openapi/v1.json answer 500 with "An item with the same key has already been - added". This package removes every colliding documentation ID from the referenced XML - documentation before compile, and warns (POAX001) about an ID it can only see once the API has - been built. The generator stays on, so every XML description stays in the OpenAPI document. -origin: >- - The same 500 appeared in several APIs at once as soon as a source generator started injecting the - same attribute into every assembly (dotnet/aspnetcore#67192). The usual workaround — removing the - generator — also removed every description from the document, so the fix became two MSBuild - targets that filter only what actually collides. -useWhen: >- - Your API references Microsoft.AspNetCore.OpenApi with its XML-comment generator on, and a - documented type with the same full name is compiled into more than one of its project references — - typically an attribute or polyfill a source generator injects into every assembly. -avoidWhen: >- - The duplicate never passes through AdditionalFiles, or both copies come from the API's own - compilation: the package cannot see those, and a type that is genuinely duplicated public API needs - one of the declarations renamed rather than filtered. -repository: purview-dev/openapi-xmlcomments -category: build-tooling -status: preview -order: 65 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -skills: true -targetFrameworks: - - msbuild -packages: - - id: Purview.OpenAPI.XmlComments - description: The deduplication and overlap-check MSBuild tasks, their props and targets, and POAX001; a development dependency with no runtime footprint. - primary: true - targetFrameworks: - - netstandard2.0 -related: - - results -useCases: - - audience: developer - title: Keep the generator on and filter only what collides - scenario: >- - /openapi/v1.json answers 500 with "An item with the same key has already been added" because a - type your API documents is also documented in more than one referenced project, and the only - workaround you have found turns the XML-comment generator off. - code: | - <!-- the project that calls AddOpenApi() --> - <PackageReference Include="Purview.OpenAPI.XmlComments" Version="1.0.0" PrivateAssets="all" /> - language: xml - outcome: >- - Every colliding documentation ID is removed from the referenced documentation before compile, the - generator runs on the filtered copies, and the description of every other endpoint and schema - stays in the document. - evidence: >- - Every occurrence of a colliding ID goes, not all but the first, because the API usually declares - the injected type as well: keeping a reference's copy would still collide with it. A duplicated - ID is ambient code rather than API surface, and a copy is only rewritten when its content - changes, so a no-change build still skips CoreCompile. - - audience: developer - title: List every colliding ID rather than the first one - scenario: >- - The exception names one documentation ID, and the build says nothing about the rest, so you do - not know whether one exclude is enough or whether the generator fails again on the next build. - code: | - pwsh skills/purview-openapi-xmlcomments-duplicates/scripts/find-duplicate-documentation-ids.ps1 ` - -Project path/to/Api - language: powershell - outcome: >- - The script asks MSBuild for exactly the documentation files the generator reads and reports every - colliding ID, where each copy comes from, whether the current configuration already handles it, - and the item to add when it does not. - evidence: >- - Each finding is classified: BetweenReferences is handled automatically by the package, while - ReferenceAndProject needs the PurviewOpenAPIXmlCommentExclude item the script prints. It exits 0 - when nothing would throw, 1 when something would, and 2 when it could not inspect the project. - docsPage: troubleshooting - - audience: team-lead - title: Fail the build on a collision instead of a 500 in production - scenario: >- - The overlap is only visible after the API compiles, so a warning is easy to ship, and the failure - then surfaces as a 500 on the OpenAPI document rather than as a red build. - code: | - <PropertyGroup> - <!-- fail the build instead of leaving the collision to run time --> - <MSBuildWarningsAsErrors>$(MSBuildWarningsAsErrors);POAX001</MSBuildWarningsAsErrors> - </PropertyGroup> - language: xml - outcome: >- - POAX001 fails the build and names the exact PurviewOpenAPIXmlCommentExclude item to add, so an - unhandled collision is a pull-request failure instead of a runtime error. - evidence: >- - The check runs after CoreCompile and compares the API's fresh documentation file with the filtered - reference documentation, which is the one case the before-compile pass cannot see: an ID - documented in the API and in exactly one referenced project. - docsPage: diagnostics - - audience: architect - title: One repository-wide reference that costs nothing at run time - scenario: >- - Several API projects in the same repository reference the same generators, and you do not want - per-project wiring or a build fix that becomes a runtime dependency. - code: | - <!-- Directory.Packages.props: once for every project in the repository --> - <GlobalPackageReference Include="Purview.OpenAPI.XmlComments" Version="1.0.0" /> - language: xml - outcome: >- - One declaration covers every project and does nothing in a project that does not reference - Microsoft.AspNetCore.OpenApi, so libraries in the same repository need no exemption. - evidence: >- - The package ships only props, targets and a netstandard2.0 task assembly under tasks/; lib/, ref/ - and runtimes/ are forbidden by pack validation, so it adds no runtime dependency and copies - nothing into the consumer's build output. - docsPage: configuration diff --git a/src/src/data/projects/pm-skills.yml b/src/src/data/projects/pm-skills.yml deleted file mode 100644 index b08b5af..0000000 --- a/src/src/data/projects/pm-skills.yml +++ /dev/null @@ -1,129 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: pm-skills -name: PM Skills -shortDescription: Project-management skills that decide which feature an AI coding agent works on next. -description: >- - Twenty-four agent skills that give a solo developer a parking lot, challenged shaping, strategy, a - roadmap, a task board, a risk register, and memory across sessions — installed above a development - workflow skill set such as Superpowers. They decide which feature is worked on; the workflow skills - decide how it is built. Ideas are captured in one line at any time, shaped into a brief whose - ramifications are challenged before they reach the roadmap, and every decision is written to a file - as it is made so a compacted session can resume from it. The skills write only to the configured - planning directory, commit only that directory, and create no branch except the item's own. -origin: >- - The bottleneck on a solo project driven by a coding agent was not the code but the decision about - what to build next: ideas arrived mid-task and were lost, a half-formed feature reached the roadmap - unchallenged, and after a context compaction the thread of what was in flight had to be rebuilt - from the conversation. Writing that discipline down as skills — a capture that works at any moment, - a shaping step that argues with the idea first, and state files that survive compaction — turned it - into something the agent runs rather than something the developer has to remember. -useWhen: >- - You drive a project with an AI coding agent and want the product decisions — what is next, what was - dropped, and why a bet was taken — kept in files that outlive the session rather than in the - conversation. It fits a solo developer or a small team that already has a development workflow - skill set and wants the layer above it. -avoidWhen: >- - You want a hosted planning tool, a shared backlog for a large team, or a portfolio view: the state - is plain markdown in your repository and the skills assume one developer plus an agent. With no - agent workflow to sit above, there is nothing for the PM skills to hand off to. -repository: purview-dev/pm-skills -category: developer-tooling -status: stable -order: 100 -docs: - source: github-path - path: docs/wiki - rootPage: Home.md - exclude: - - _Sidebar.md -related: - - engineering-playbook -acknowledgments: - - name: Superpowers - url: https://github.com/obra/superpowers - description: The development workflow skill set the PM skills are installed above. -useCases: - - audience: developer - title: Capture a bug or an idea in one line, mid-task - scenario: >- - You are in the middle of an implementation when you spot an unrelated bug, or an idea arrives - that you cannot act on now but do not want to lose. - code: | - park this: the export button does nothing in Safari - - Parked: planning/inbox/2026-11-01-0912-export-button-safari.md (bug). Back to step 3. - language: plaintext - outcome: >- - One inbox file is written under the configured planning directory and the reply is a single - line, so the agent resumes the step it was on. Only capture (pm-park, pm-risk) and checkpoint - writes may run during an active workflow, so nothing else interrupts the build. - evidence: >- - pm-park writes in the main worktree rather than the current feature worktree, and its Output - section allows exactly one line plus — only when no workflow is active — a single choice - question, `Shape "<title>" now, or keep it parked?`, whose recommended answer is to keep it - parked. - - audience: team-lead - title: A board and a roadmap that come from the same files - scenario: >- - You want to see what is in progress, what the agent will pick up next, and what is waiting on - you, without maintaining a second copy of the plan in a tracker. - code: | - | Column | ID | Title | Owner | Size | Detail | - | --- | --- | --- | --- | --- | --- | - | Now | R-007 | Tenant billing | agent | M | execute, 4/9 steps | - | Next (agent) | R-008 | Invoice email | agent | S | ready | - | For you | R-009 | Open a Stripe account | user | S | blocks R-008 | - | Waiting | R-010 | Usage export | agent | M | needs R-008 | - | Done | R-006 | Tenant model | agent | M | 2026-10-28 | - language: markdown - outcome: >- - pm-board, pm-roadmap, and pm-status render the task board, the milestone roadmap, or just your - own queue from the same state files the agent works from, and viewing is read-only: asking for - the board or the status never changes the plan. - evidence: >- - The board's "For you" column is every Owner: user item in Next plus the open questions, and - "Waiting" names the blocking item — the same roadmap items pm-next claims work from, so the - board cannot drift from what is actually being built. - - audience: architect - title: The idea is challenged before it reaches the roadmap - scenario: >- - An idea sounds obviously good, and you want it argued with — the alternatives, the - ramifications across data, security, performance, cost and maintenance, and the smallest - version that still delivers the outcome — before it becomes work. - code: | - ## Who and evidence - ## Alternatives considered - ## Challenges and answers - ## Ramifications - ## Proposal - ## Done when - ## Open questions - ## Decision - language: markdown - outcome: >- - A brief is written to the planning directory after every answer, so the discussion survives - compaction and a later session resumes it from the first empty heading, and the run ends with - one decision: add to Next, add to Later, build it now, keep it parked, or drop it. - evidence: >- - pm-shape writes at least three alternatives — do nothing, the smallest version, and the full - idea — and completes a ramifications row for each of the eight Challenge protocol areas, - writing "none found" rather than leaving one out; a dropped idea appends its reason to Dropped - in LOG.md. - - audience: contributor - title: Add a skill without breaking the consistency checks - scenario: >- - You want to add a new pm-* skill, and the repository has to stay consistent: the README table, - the managed section, the pm-setup inventory and the pm-help guide all have to describe the - same set. - code: | - just validate - just lint-check - language: bash - outcome: >- - Adding a skill is a directory plus the four listings that reference it. just validate checks - skill frontmatter, the README and managed-section tables, the pm-setup inventory, the section - markers and the template placeholders, and fails when one listing is missed. - evidence: >- - CI runs the same checks on every push and pull request to main, and lefthook runs commitlint - on commit and just lint-check on push, so a half-registered skill cannot be merged. diff --git a/src/src/data/projects/results.yml b/src/src/data/projects/results.yml deleted file mode 100644 index f8d5356..0000000 --- a/src/src/data/projects/results.yml +++ /dev/null @@ -1,132 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: results -name: Results -shortDescription: Result for .NET — expected failures as values the caller must handle. -description: >- - A small, dependency-free Result<TValue, TError> for .NET that makes - expected failures part of a method's contract: not found, invalid, and - conflict are values rather than exceptions. A Roslyn source generator adds - C# 15 union ergonomics for the error cases, and companion packages carry - the result into ASP.NET Core responses and ZodSharp validation problems. -origin: >- - Services kept re-declaring their own error types and hand-writing the same - failure helpers and HTTP mapping, so the result type, the generated - helpers, and the adapter packages became one shared package family. -useWhen: >- - Expected failures are part of your domain model and you want them returned - as values the caller must handle, with a strongly typed error case that - still reaches the client as a standard HTTP problem response. -avoidWhen: >- - You target a runtime below .NET 11 with C# 15 preview, or the failures you - are modelling are exceptional circumstances that belong in exceptions. -repository: purview-dev/results -category: application-framework -status: stable -order: 45 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net10.0 - - net11.0 -packages: - - id: Purview.Results - description: The result type, its factories, IResultValue, and the bundled union source generator. No dependencies. - primary: true - # Purview.Results.SourceGenerator was published by mistake and is now packed - # into Purview.Results as an analyzer, so it is deliberately not declared here. - - id: Purview.Results.AspNetCore - description: Result-to-response mapping, endpoint filter, and dependency-injection registration. - - id: Purview.Results.ZodSharp - description: Bridges ZodSharp validation results into results. - - id: Purview.Results.ZodSharp.AspNetCore - description: Renders validation-carrying failures as HttpValidationProblemDetails. -related: - - zodsharp - - sourcegenerator-framework -useCases: - - audience: developer - title: Return expected failures as values - scenario: >- - You call a store that can fail in ways you expect — not found, disabled, - already exists — and you do not want a thrown exception or a generic error - string to be the only way the caller learns what happened. - code: | - Result<Tenant, TenantError> GetTenant(TenantId tenantId) => - _tenants.TryGet(tenantId, out var tenant) - ? Result<Tenant, TenantError>.Success(tenant) - : new TenantNotFound(tenantId).AsFailure<Tenant>(); - language: csharp - outcome: >- - The caller branches on the error value itself, so TenantNotFound keeps carrying - its TenantId instead of being flattened into a message. - evidence: >- - The core package has no dependencies: it ships the result type, its factories, - and IResultValue without pulling anything else in. - docsPage: core-concepts - - audience: developer - title: Generate the failure helper for every union case - scenario: >- - You model errors as a C# 15 union and need each case to become the failure side - of a result without writing one conversion helper per case by hand. - code: | - [GenerateResult] - public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists); - language: csharp - outcome: >- - The generator emits AsFailure<TValue>() for every case of an annotated union, - plus a code fix and a CA1815 suppression, so the declaration needs no pragma. - evidence: >- - C# forbids the implicit conversion a bare case value would need — no operators - in static classes, no conversion operators in extension members, one - user-defined conversion per sequence — which is why the helper is per case. - docsPage: union-errors - - audience: architect - title: Map one error union onto HTTP responses - scenario: >- - The same domain error union surfaces from many minimal-API endpoints, and you do - not want a hand-written switch deciding the status code at each one. - code: | - builder.Services.AddResultsHttp(options => options - .Map<TenantNotFound>(error => TypedResults.NotFound()) - .Map<TenantError>(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict)) - ); - - app.MapGet("/tenants/{id:int}", (int id) => GetTenant(id)).WithResultsHttp(); - language: csharp - outcome: >- - The mapping is declared once at startup, WithResultsHttp() applies it to the - endpoints, and a host can replace IResultsHttpMapper when it needs different - behaviour. - evidence: >- - Mappings resolve in declaration order — any mapping or failure mapper the host - declared earlier always wins — so the most specific rule is registered first. - docsPage: aspnetcore-integration - - audience: team-lead - title: Let ZodSharp validation failures become validation problems - scenario: >- - Endpoints validate input with ZodSharp, and a failed validation should reach the - client as the standard ASP.NET Core validation-problem payload rather than an - error shape the API has to document separately. - code: | - { - "title": "One or more validation errors occurred.", - "status": 400, - "errors": { "TenantId": ["Required field 'TenantId' is null"] }, - "issues": [{ "code": "missing_field", "path": ["TenantId"], "message": "Required field 'TenantId' is null" }] - } - language: json - outcome: >- - A failure that implements IValidationErrorCarrier becomes - HttpValidationProblemDetails without the host mapping it, unless a per-code or - per-category rule answers that failure first. - evidence: >- - The response is ASP.NET Core's own HttpValidationProblemDetails contract, so API - clients keep the error shape they already parse. - docsPage: zodsharp-problemdetails diff --git a/src/src/data/projects/sourcegenerator-framework.yml b/src/src/data/projects/sourcegenerator-framework.yml deleted file mode 100644 index b1e2a77..0000000 --- a/src/src/data/projects/sourcegenerator-framework.yml +++ /dev/null @@ -1,78 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: sourcegenerator-framework -name: SourceGenerator Framework -shortDescription: A typed framework for building incremental C# source generators. -description: >- - A strongly typed framework for building, testing, and maintaining - incremental C# source generators with Roslyn. Includes structured code - generation, attribute data models, type libraries, and a step-cache test - runner for verifying incremental behaviour. -origin: >- - Building several incremental generators exposed the same needs for typed models, structured - output, testing, and cache verification, so those foundations became a shared framework. -useWhen: >- - You are building a non-trivial incremental C# source generator and want reusable modelling, - code-writing, packaging, and testing infrastructure. -avoidWhen: >- - Your generator is small enough for the Roslyn APIs directly, or adopting a framework would - hide behaviour your implementation needs to control precisely. -repository: purview-dev/sourcegenerator-framework -category: source-generation -status: stable -featured: true -order: 40 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net10.0 - - net11.0 -packages: - - id: Purview.SourceGeneratorFramework - description: Core helpers, models, and MSBuild integration for incremental generators. - primary: true - targetFrameworks: - - netstandard2.0 - - id: Purview.SourceGeneratorFramework.Testing - description: Framework-agnostic test runner and assertions for generator tests. - - id: Purview.SourceGeneratorFramework.Testing.TUnit - description: TUnit-specific test base classes and assertions. -useCases: - - audience: contributor - title: Build an incremental generator on typed foundations - scenario: >- - You are writing a non-trivial incremental C# source generator and need typed attribute - models, structured code output, and packaging that Roslyn will actually load. - code: | - <ProjectReference - Include="..\MyGenerator\MyGenerator.csproj" - PrivateAssets="all" - OutputItemType="Analyzer" - ReferenceOutputAssembly="false" - /> - language: xml - outcome: >- - The framework supplies attribute-data models, a structured code writer, a type library, and - packaging helpers so the generator stays focused on its own logic. - evidence: >- - The Purview generators themselves are built on the framework, so it is exercised by real - generators rather than being an untested abstraction. - docsPage: guide - - audience: contributor - title: Verify incremental behaviour in tests - scenario: >- - You need to prove a generator is incremental and produces the code you expect, without - assembling a Roslyn driver by hand in every test. - outcome: >- - The testing package provides SourceGeneratorTestRunner<TGenerator>, a framework-agnostic test - base, and assertions such as AssertSingleGeneratedSource and AssertNoCompilationErrors. - evidence: >- - Step-cache tests and a TUnit integration ship alongside the runner, so incremental regressions - surface in CI. - docsPage: testing diff --git a/src/src/data/projects/telemetry-sourcegenerator.yml b/src/src/data/projects/telemetry-sourcegenerator.yml deleted file mode 100644 index 680482a..0000000 --- a/src/src/data/projects/telemetry-sourcegenerator.yml +++ /dev/null @@ -1,85 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: telemetry-sourcegenerator -name: Telemetry SourceGenerator -shortDescription: Interface-based telemetry for .NET with zero boilerplate. -description: >- - A source generator that turns simple interface methods into - OpenTelemetry-aligned Activities, structured ILogger logging, and Metrics. - Define telemetry once on an interface; the generator emits the - implementation, DI registration helpers, and multi-target generation — - no runtime reflection, no boilerplate. -origin: >- - Repeating the same logging, activity, and metric wiring across services made telemetry a - strong candidate for one interface-driven, compile-time implementation. -useWhen: >- - You want strongly typed OpenTelemetry-aligned telemetry from interfaces, with generated - implementations and dependency-injection registration. -avoidWhen: >- - Your telemetry is highly dynamic, cannot be described at compile time, or is already handled - consistently by another instrumentation layer. -repository: purview-dev/telemetry-sourcegenerator -category: observability -status: stable -featured: true -order: 10 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net8.0 - - net9.0 - - net10.0 -packages: - - id: Purview.Telemetry.SourceGenerator - description: Core package with the Roslyn source generator and attribute library. - primary: true - targetFrameworks: - - netstandard2.0 -useCases: - - audience: developer - title: Tracing, logging, and metrics from a single interface - scenario: >- - You want OpenTelemetry activities, structured logs, and metrics around an order service, but - you do not want to hand-write the ActivitySource, ILogger, and Meter wiring in every class. - code: | - [ActivitySource] - [Logger] - [Meter] - public interface IOrderServiceTelemetry - { - [Activity] - [Info] - [AutoCounter] - Activity? PlacingOrder(int orderId, [Baggage] string region); - } - language: csharp - outcome: >- - The generator emits the implementation and an AddOrderServiceTelemetry() DI extension; you - register it once and inject the interface wherever telemetry is needed. - evidence: >- - One interface replaces the ActivitySource, ILogger, and Meter boilerplate you would otherwise - repeat in every service. - - audience: architect - title: Standardise telemetry names across services - scenario: >- - You want consistent OpenTelemetry meter and activity-source names across many services instead - of ad-hoc string literals scattered through the codebase. - code: | - builder.AddServiceDefaults( - TelemetryNames.MeterNames, - TelemetryNames.ActivitySourceNames); - language: csharp - outcome: >- - A generated TelemetryNames static class holds the names, so registration happens once at - startup rather than in every service. - evidence: >- - Naming conventions are generated, so snake_case tags and hierarchical metrics stay consistent - without a review checklist. - docsPage: generation -discussions: false diff --git a/src/src/data/projects/unions.yml b/src/src/data/projects/unions.yml deleted file mode 100644 index c58e4f9..0000000 --- a/src/src/data/projects/unions.yml +++ /dev/null @@ -1,153 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: unions -name: Unions -shortDescription: Dependency-free C# 15 unions that do not box value-type cases. -description: >- - The C# 15 `union` keyword lowers to a single `object?` field, so every - value-type case is boxed on entry. Purview.Unions generates the language's - non-boxing custom-union shape instead: each case gets its own typed field, a - public constructor, and a `TryGetValue` that never allocates. The compiler - still sees a union — implicit conversions, exhaustive `switch`, and `is`/`null` - patterns all work — plus a hand-written `Union<T1, T2>` for the two-case shape. -origin: >- - Discriminated unions were needed for error modelling and optional values, and - the language's own `union` declaration boxes every value-type case on entry. - The compiler already exposes the custom-union contract the boxing-free shape - needs, so the generator that emits it became a shared package instead of a - hand-written type in each project. -useWhen: >- - You model a closed set of cases — expected errors, optional results, a - small state machine — and either the value-type cases are allocation-sensitive - or you want one type the whole team matches on exhaustively. -avoidWhen: >- - You target a runtime below .NET 11 with C# 15, or a single shape with two - reference-type cases is enough: the built-in `union` declaration is simpler - and the boxing cost does not apply to reference types. -repository: purview-dev/unions -category: source-generation -status: preview -order: 25 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net10.0 - - net11.0 -packages: - - id: Purview.Unions - description: The [GenerateUnion] attribute, the source generator with its code fixes, and the hand-written Union<T1, T2>. - primary: true -skills: true -related: - - results - - zodsharp - - sourcegenerator-framework -useCases: - - audience: developer - title: Match a value-type union without boxing a case - scenario: >- - A method returns one of a handful of value-type outcomes, and the caller must - branch on which one it received — but the `union` keyword boxes every - value-type case on entry and again while matching. - code: | - [GenerateUnion(typeof(int), typeof(string))] - public readonly partial struct IntOrString; - - IntOrString value = 42; - - var message = value switch - { - int number => $"int {number}", - string text => $"string {text}", - null => "empty", - }; - language: csharp - outcome: >- - The compiler treats the generated type as a union, so implicit conversions, - exhaustive `switch` and `is`/`null` patterns all work, while construction, - `TryGetValue`, `is` and `switch` never allocate. - evidence: >- - The committed BenchmarkDotNet suite measures construction, both - `TryGetValue` directions, the miss path, `HasValue`, `is` and both `switch` - shapes at 0 B; only reading `Value` allocates the 24-byte box for the `int` - case, which is inherent to the union contract. - docsPage: performance - - audience: developer - title: Declare a union whose cases are type parameters - scenario: >- - You want a generic option or outcome type, but `typeof(T)` is not a legal - attribute argument, so an ordinary `[GenerateUnion(typeof(…))]` list cannot - name a type parameter. - code: | - [GenerateUnion] - public readonly partial struct Option<T> - { - internal static partial Option<T> Some(Some<T> value); - internal static partial Option<T> None(None value); - } - language: csharp - outcome: >- - Each partial factory signature names a case, the generator supplies the - bodies and derives the public constructors from them, and the compiler reports - `CS0416` only if you try to use a `typeof(T)` list instead. - evidence: >- - A generic union must name its cases in source because `CS0416` rejects - `typeof(T)` in an attribute; a `typeof` list on a generic union is reported - as `UNI0011`. - docsPage: union-design - - audience: architect - title: Let a second source generator see the union's cases - scenario: >- - Another Purview generator — Results, or the telemetry generator unwrapping a - parameter — must read the case list, but Roslyn generators never see each - other's generated output. - code: | - [GenerateUnion] - public readonly partial struct Outcome<T> : Outcome<T>.IUnionMembers - { - public interface IUnionMembers - { - static Outcome<T> Create(T? value) => Outcome<T>.CreateCase0(value); - static Outcome<T> Create(Exception? error) => Outcome<T>.CreateCase1(error); - - bool TryGetValue(out T value); - bool TryGetValue(out Exception value); - } - } - language: csharp - outcome: >- - A public nested `IUnionMembers` provider exposes the case list in the source - the other generator compiles against, while this generator still emits the - storage and `CreateCaseN` methods. - evidence: >- - `Purview.Telemetry.SourceGenerator` 6.0.0 reads the source-visible case list in - the same order as this package, and a `[GenerateUnion]` target with no - source-visible case list is reported as `UNI0003` rather than unwrapped. - docsPage: interop - - audience: contributor - title: Fail fast on a malformed union declaration - scenario: >- - A union is declared without `partial`, with a duplicate case, or with a case - type less accessible than the union, and the generated shape cannot be emitted - coherently. - code: | - error UNI0001: The union declaration is not partial - error UNI0004: Duplicate case type - error UNI0005: A case type is less accessible than the union - language: plaintext - outcome: >- - Every error blocks its union's output rather than emitting a partial shape, - and the package ships code fixes for the common declarations — add `partial` - (`UNI0001`), widen an inaccessible case type (`UNI0005`), add `[Union]` on the - fallback path (`UNI0007`). - evidence: >- - `UNI0015` (a single-case union) is the only warning; every other `UNI` rule - blocks emission, so a malformed union fails the build instead of producing - half a type. - docsPage: diagnostics diff --git a/src/src/data/projects/value-objects.yml b/src/src/data/projects/value-objects.yml deleted file mode 100644 index 0dbd44b..0000000 --- a/src/src/data/projects/value-objects.yml +++ /dev/null @@ -1,89 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: value-objects -name: Value Objects -shortDescription: Source-generated scalar and complex value objects for .NET. -description: >- - F#-style single-case types for C#. Mark a partial struct or class with - [Scalar] or [ValueObject] and an incremental source generator produces - Create/Hydrate factories with normalization and validation, equality, - comparison, implicit conversions, JSON converters, and contextual - creation. Value objects serialize as their underlying value, map cleanly - onto Entity Framework JSON columns, and can be validated with - Purview.ZodSharp schemas. -origin: >- - Hand-writing the same factories, equality rules, conversions, serializers, and persistence - integration for domain values made the pattern an obvious source-generation target. -useWhen: >- - Your domain uses meaningful scalar or complex value types and you want their repetitive - implementation generated from a small, explicit declaration. -avoidWhen: >- - A primitive or record already expresses the concept clearly, or generated conversion and - serialization behaviour would be more machinery than the domain needs. -repository: purview-dev/value-objects -category: source-generation -status: stable -featured: true -order: 35 -docs: - source: github-path - path: docs - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md -targetFrameworks: - - net8.0 - - net9.0 - - net10.0 - - net11.0 -packages: - - id: Purview.ValueObjects - description: Runtime contracts, source generator, and analyzer for scalar and complex value objects. - primary: true -useCases: - - audience: developer - title: A domain scalar without the boilerplate - scenario: >- - You want a strong EmailAddress type with normalisation and validation, without hand-writing - factories, equality, conversions, and a JSON converter. - code: | - [Scalar] - public readonly partial record struct EmailAddress - { - public string Value { get; } - - static partial void OnNormalize(ref string value) - => value = value?.Trim().ToLowerInvariant()!; - } - language: csharp - outcome: >- - The generator adds Create, Hydrate, TryCreate, and Empty, plus equality, comparison, implicit - conversions, and a JSON converter. - evidence: >- - One declaration replaces the factory, equality, comparison, conversion, and serialization code - you would otherwise maintain by hand. - docsPage: value-object-design - - audience: developer - title: Map a value object onto an Entity Framework column - scenario: >- - You use a value object in your domain and want it to persist transparently instead of writing - converters at every mapping site. - code: | - var email = EmailAddress.Create(" Demo@Example.COM "); - // email.Value == "demo@example.com" - - bool ok = EmailAddress.TryCreate("not-an-email", out _); - // ok == false - language: csharp - outcome: >- - Value objects serialize as their underlying value and map onto Entity Framework JSON columns, - with optional Purview.ZodSharp validation. - evidence: >- - Persistence and serialization come from the generated type, so mapping code is not duplicated - per entity. - docsPage: entity-framework -related: - - zodsharp - - event-sourcing diff --git a/src/src/data/projects/zodsharp.yml b/src/src/data/projects/zodsharp.yml deleted file mode 100644 index 8bea64f..0000000 --- a/src/src/data/projects/zodsharp.yml +++ /dev/null @@ -1,149 +0,0 @@ -$schema: ../../lib/manifest/schema.ts - -id: zodsharp -name: ZodSharp -shortDescription: Zero-allocation schema validation for C# — a Zod port. -description: >- - A high-performance schema validation library for C#, ported from - TypeScript Zod by way of the guinhx/ZodSharp C# port. Struct-based rules, - a fluent API, JSON Schema export and import, source-generated validators, - and zero-allocation validation on every valid input path. Integrates with - System.Text.Json, Newtonsoft.Json, and ASP.NET Core ProblemDetails. -origin: >- - Schema validation was repeatedly needed at application boundaries, but existing approaches - did not combine a fluent Zod-style model with predictable, allocation-conscious execution. -useWhen: >- - You want composable C# schemas, compile-time validator generation, or JSON Schema interop with - tight control over validation behaviour and allocations. -avoidWhen: >- - Data annotations or an existing validation library already cover your requirements, or Zod-style - schemas would add an unnecessary second validation model. -repository: purview-dev/zodsharp -category: validation -status: stable -featured: true -order: 30 -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - exclude: - - _Sidebar.md - - Home.md - - index.md - # Two views of the same documentation (ADR 0009): the published release a - # reader can install today (`live`, the canonical /docs/zodsharp/ URLs) and - # the line that has not shipped yet (`prerelease`, /docs/zodsharp/prerelease/). - # `main` is ahead of the latest release, so the pinned tag is the honest - # source for the live docs. Promotion is automatic: the prerelease channel - # stops being published as soon as a stable release catches up with the - # prerelease line, and returns with the next prerelease. - channels: - live: - ref: latest-stable - prerelease: - ref: default - # The documentation was reorganised into topic folders, which makes each page's folder part of its published URL. - # Every page that moved keeps its old flat URL working: the site writes a meta-refresh redirect for each pair once - # the default channel publishes that page's new address (and only while the old slug is no longer a page), so these - # entries stay dormant while `live` still reads a tag that predates the move and activate per page at promotion. - redirects: - core-concepts: concepts/core-concepts - composition-and-transforms: concepts/composition-and-transforms - string-validation: schemas/string-validation - number-validation: schemas/number-validation - object-validation: schemas/object-validation - arrays-and-other-schemas: schemas/arrays-and-other-schemas - unions-and-discriminated-unions: schemas/unions-and-discriminated-unions - validation-rules-reference: schemas/validation-rules-reference - custom-rules: schemas/custom-rules - value-objects-integration: schemas/value-objects-integration - compiled-validators-and-caching: schemas/compiled-validators-and-caching - source-generator: generator/source-generator - source-generator-dataannotations: generator/source-generator-dataannotations - source-generator-diagnostics: generator/source-generator-diagnostics - jsonschema-export: serialization/jsonschema-export - jsonschema-import: serialization/jsonschema-import - systemtextjson-integration: serialization/systemtextjson-integration - newtonsoftjson-integration: serialization/newtonsoftjson-integration - microsoft-extensions-validation: hosting/microsoft-extensions-validation - openapi-integration: hosting/openapi-integration - blazor-integration: hosting/blazor-integration - http-integration: hosting/http-integration - dependency-injection: hosting/dependency-injection - localization: hosting/localization - guarantees-and-limitations: quality/guarantees-and-limitations - performance: quality/performance - trimming-and-aot: quality/trimming-and-aot - cross-platform-interop: quality/cross-platform-interop - contributing: development/contributing - release-flow: development/release-flow -targetFrameworks: - - net8.0 - - net9.0 - - net10.0 - - net11.0 -packages: - - id: Purview.ZodSharp - description: Core validation library and source generator. - primary: true - - id: Purview.ZodSharp.SystemTextJson - description: System.Text.Json integration and JSON Schema import. - - id: Purview.ZodSharp.NewtonsoftJson - description: Newtonsoft.Json integration and JSON Schema import. - - id: Purview.ZodSharp.AspNetCore - description: ASP.NET Core ProblemDetails integration. - # Published only as prereleases today, but published all the same: the package - # listing must show every package a project ships, not only the ones that have - # reached a stable version. - - id: Purview.ZodSharp.Http - description: HttpClient integration — validates request and response bodies and maps validation problems back to ZodSharp errors. - - id: Purview.ZodSharp.Blazor - description: Blazor EditForm validation on Server, WebAssembly and Auto render modes. - - id: Purview.ZodSharp.AspNetCore.OpenApi - description: OpenAPI transformers for the constraints, formats and error contract ZodSharp enforces. - - id: Purview.ZodSharp.Extensions.Validation - description: Microsoft.Extensions.Validation resolver so minimal APIs and Blazor validate with ZodSharp. -related: - - value-objects -acknowledgments: - - name: Zod - url: https://github.com/colinhacks/zod - description: The original JavaScript/TypeScript schema validation library. - - name: ZodSharp (guinhx) - url: https://github.com/guinhx/ZodSharp - description: The C# port of Zod, and the fork this project is based on. -useCases: - - audience: developer - title: Validate input without exceptions or allocations - scenario: >- - You need to validate values at an application boundary and prefer a result you can inspect - over exception-driven control flow. - code: | - var nameSchema = Z.String().Min(3).Max(50); - var result = nameSchema.Validate("John"); - - if (result.IsSuccess) - Console.WriteLine($"Valid name: {result.Value}"); - language: csharp - outcome: >- - Validate/SafeParse return a ValidationResult<T> with no exceptions, while Parse still throws - ZodException when you want that behaviour. - evidence: >- - Validation is zero-allocation on every valid input path, so the performance claim is a - property of the code rather than an aspiration. - docsPage: fluent-schema-api - - audience: team-lead - title: Return standard ProblemDetails for invalid requests - scenario: >- - You want failed validation in ASP.NET Core to surface as standard ProblemDetails payloads - rather than a bespoke error shape that clients must learn. - code: | - dotnet add package Purview.ZodSharp.AspNetCore - language: bash - outcome: >- - The AspNetCore adapter converts failed validation results into the standard ProblemDetails / - HttpValidationProblemDetails payloads. - evidence: >- - One adapter package, and API consumers keep the error contract they already expect. - docsPage: aspnetcore-integration diff --git a/src/src/lib/discovery/resources.ts b/src/src/lib/discovery/resources.ts index 20b347a..a455a22 100644 --- a/src/src/lib/discovery/resources.ts +++ b/src/src/lib/discovery/resources.ts @@ -5,7 +5,7 @@ import type { ReleaseCacheData } from '../releases/types'; import type { DiscoverableKind, DiscoverableResource } from './types'; import { existsSync, readdirSync, readFileSync } from 'node:fs'; -import { join } from 'node:path'; +import { join, resolve } from 'node:path'; import { DOCS_OUTPUT_DIR, readDocsManifest } from '../docs/aggregate'; import { loadProjects } from '../manifest/load'; @@ -46,9 +46,14 @@ export const PAGE_SOURCES: Readonly<Record<string, string>> = { 'use-cases': 'src/src/pages/use-cases/index.astro', }; -/** Repo-relative catalogue file for a project id. */ -export function projectManifestFile(id: string): string { - return `src/src/data/projects/${id}.yml`; +/** + * Repo-relative catalogue file for a project id, or `null` when the project owns + * its record in its own repository (ADR 0013). This repository then has no commit + * to date the record from, so the caller falls back to the release date. + */ +export function projectManifestFile(id: string): string | null { + const file = `src/src/data/projects/${id}.yml`; + return existsSync(resolve(file)) ? file : null; } export interface DiscoveryContext { @@ -187,9 +192,10 @@ function latestReleaseDate(data: ReleaseCacheData, repository: string | undefine /** `lastmod` for a project's HTML page: manifest commit or latest release. */ export function projectLastModified(id: string, ctx: DiscoveryContext): string | undefined { const project = ctx.projects.find((candidate) => candidate.id === id); + const manifestFile = projectManifestFile(id); return preferTimestamp( [ - ctx.fileDates.get(projectManifestFile(id)), + manifestFile === null ? undefined : ctx.fileDates.get(manifestFile), latestReleaseDate(ctx.releaseData, project?.repository), ], ctx.fallbackDate, @@ -209,9 +215,10 @@ export function documentationLastModified( channelId?: string, ): string | undefined { const key = channelId ? `${projectId}/${channelId}/${slug}` : `${projectId}/${slug}`; + const manifestFile = projectManifestFile(projectId); return firstTimestamp([ ctx.docsLastReviewed.get(key), - ctx.fileDates.get(projectManifestFile(projectId)), + manifestFile === null ? undefined : ctx.fileDates.get(manifestFile), ctx.fallbackDate, ]); } diff --git a/src/src/lib/manifest/load.ts b/src/src/lib/manifest/load.ts index bc3de49..f0c26d2 100644 --- a/src/src/lib/manifest/load.ts +++ b/src/src/lib/manifest/load.ts @@ -15,14 +15,17 @@ import { z } from 'zod'; import { getReleaseIndex } from '../releases/runtime'; import { OWNER } from '../site'; +import { PROJECT_MANIFEST_PATH } from './remote'; +import { getManifestIndex } from './runtime'; import { PROJECT_DEFAULTS, manifestSchema } from './schema'; /** - * The catalogue is one file per project (ADR 0005): `src/data/projects/<id>.yml`, + * The catalogue records this repository still owns (ADR 0005): `src/data/projects/<id>.yml`, * plus `src/data/external-projects.yml` for the collaborations the organisation * does not own. One file per project keeps a project's history and review * self-contained, and stops concurrent catalogue pull requests from conflicting - * on one growing list. + * on one growing list. A project that publishes its own record at + * `.config/purview-docs.yml` wins over the file here (ADR 0013). */ export const DEFAULT_PROJECTS_DIR = resolve('src/data/projects'); export const DEFAULT_EXTERNAL_PROJECTS_PATH = resolve('src/data/external-projects.yml'); @@ -66,6 +69,17 @@ export type ResolvedExternalProject = Omit< order: number; }; +/** The raw catalogue records, with the provenance of each one. */ +export interface RawManifest { + /** One record per `src/src/data/projects/*.yml` and per owning repository. */ + projects: unknown[]; + externalProjects: unknown[]; + /** Project id → the file or repository that owns the record, for error messages. */ + sources: Map<string, string>; + /** Project ids declared both here and by the repository that owns them. */ + duplicatedIds: string[]; +} + export class ManifestValidationError extends Error { constructor(message: string) { super(message); @@ -127,7 +141,7 @@ function withDefaults(record: ProjectRecord, repositories: RepositoryFlags): Res /** * Label an issue with the project id rather than its array index, so a schema - * failure names the project whose file is wrong (`projects[containers].name`) + * failure names the project whose record is wrong (`projects[containers].name`) * instead of a position the author has to map back to a file. */ function issuePath(raw: unknown, path: readonly PropertyKey[]): string { @@ -135,12 +149,22 @@ function issuePath(raw: unknown, path: readonly PropertyKey[]): string { if (head !== 'projects' || typeof index !== 'number') { return path.join('.'); } + const id = issueProjectId(raw, path); + const label = `projects[${id ?? index}]`; + return rest.length > 0 ? `${label}.${rest.join('.')}` : label; +} + +/** The project id a schema issue path names, when it names one. */ +function issueProjectId(raw: unknown, path: readonly PropertyKey[]): string | undefined { + const [head, index] = path; + if (head !== 'projects' || typeof index !== 'number') { + return undefined; + } const entries = (raw as { projects?: unknown[] } | null)?.projects; const entry = Array.isArray(entries) ? entries[index] : undefined; const id = typeof entry === 'object' && entry !== null ? (entry as { id?: unknown }).id : undefined; - const label = `projects[${typeof id === 'string' ? id : index}]`; - return rest.length > 0 ? `${label}.${rest.join('.')}` : label; + return typeof id === 'string' ? id : undefined; } /** @@ -151,19 +175,31 @@ function issuePath(raw: unknown, path: readonly PropertyKey[]): string { * `repositories` feeds the values that are detected from GitHub rather than * authored (today: whether Discussions are enabled); it defaults to the release * cache, so a record never repeats what the repository already says. + * + * `sources` maps a project id to the file or repository that owns its record, so + * a failure points at the record the author has to edit: a local + * `src/src/data/projects/<id>.yml` here, or a project's own + * `.config/purview-docs.yml` in the repository that publishes it (ADR 0013). */ export function parseManifest( raw: unknown, source: string, repositories: RepositoryFlags = getReleaseIndex().data.repos, + sources: ReadonlyMap<string, string> = new Map(), ): ResolvedProject[] { + const sourceOf = (id: string): string => sources.get(id) ?? source; let parsed: ProjectManifest; try { parsed = manifestSchema.parse(raw); } catch (error) { if (error instanceof z.ZodError) { const issues = error.issues - .map((issue) => ` ${issuePath(raw, issue.path)}: ${issue.message}`) + .map((issue) => { + const id = issueProjectId(raw, issue.path); + const owner = id === undefined ? undefined : sources.get(id); + const label = issuePath(raw, issue.path); + return ` ${owner === undefined ? label : `${label} (${owner})`}: ${issue.message}`; + }) .join('\n'); throw new ManifestValidationError( [ @@ -186,7 +222,7 @@ export function parseManifest( if (project.repository.split('/')[0] !== OWNER) { throw new ManifestValidationError( [ - `Invalid project manifest: ${source}`, + `Invalid project manifest: ${sourceOf(project.id)}`, ` projects[${project.id}].repository: Expected the repository to belong to the "${OWNER}" organisation.`, ` Got: ${project.repository}`, '', @@ -202,7 +238,7 @@ export function parseManifest( if (!ids.has(ref)) { throw new ManifestValidationError( [ - `Invalid project manifest: ${source}`, + `Invalid project manifest: ${sourceOf(project.id)}`, ` projects[${project.id}]: Relationship references "${ref}", which is not a known project id.`, '', `Remediation: add a project with id "${ref}" or remove the relationship.`, @@ -216,7 +252,7 @@ export function parseManifest( if (existing !== undefined) { throw new ManifestValidationError( [ - `Invalid project manifest: ${source}`, + `Invalid project manifest: ${sourceOf(project.id)}`, ` projects[${project.id}].packages: Package "${pkg.id}" (${pkg.registry}) is also declared by "${existing}".`, '', `Remediation: associate each package with exactly one project.`, @@ -230,7 +266,7 @@ export function parseManifest( if (existing !== undefined) { throw new ManifestValidationError( [ - `Invalid project manifest: ${source}`, + `Invalid project manifest: ${sourceOf(project.id)}`, ` projects[${project.id}].assets: output "${asset.output}" is also declared by "${existing}".`, '', `Remediation: give each mirrored asset a distinct output path.`, @@ -263,30 +299,50 @@ function stripSchemaHint(value: unknown): unknown { } /** - * Read the catalogue from disk into the raw shape `manifestSchema` validates: - * one record per `*.yml` file in the projects directory, sorted by file name so - * the result is deterministic whatever order the filesystem reports, plus the - * collaborations file. Validation (including every cross-record invariant) - * stays in `parseManifest`. + * Read the catalogue into the raw shape `manifestSchema` validates: one record per + * `*.yml` file in the projects directory, sorted by file name so the result is + * deterministic whatever order the filesystem reports, plus the collaborations + * file — and one record per project repository that publishes + * `.config/purview-docs.yml` (ADR 0013). + * + * A project that owns its record wins over a local file with the same id, which is + * the migration path: moving a record into the project repository is a change to + * that repository, and the local copy is deleted in the same commit. The clash is + * reported in `duplicatedIds` rather than merged silently, so the catalogue guard + * can say that a leftover local copy has stopped being the source of truth. + * + * Validation (including every cross-record invariant) stays in `parseManifest`. */ export function readRawManifest( projectsDir = DEFAULT_PROJECTS_DIR, externalProjectsPath = DEFAULT_EXTERNAL_PROJECTS_PATH, -): { projects: unknown[]; externalProjects: unknown[] } { - const files = readdirSync(projectsDir) - .filter((file) => file.endsWith('.yml') || file.endsWith('.yaml')) - .toSorted(); +): RawManifest { + // The directory may be absent: once every project owns its own record (ADR 0013) there is + // nothing left to read here, and git does not keep an empty directory. + const files = existsSync(projectsDir) + ? readdirSync(projectsDir) + .filter((file) => file.endsWith('.yml') || file.endsWith('.yaml')) + .toSorted() + : []; - const projects = files.map((file) => { + const sources = new Map<string, string>(); + const projects: unknown[] = []; + for (const file of files) { const text = readFileSync(join(projectsDir, file), 'utf8'); + let record: unknown; try { - return stripSchemaHint(parse(text)); + record = stripSchemaHint(parse(text)); } catch (error) { throw new ManifestValidationError( `Invalid YAML in ${file}: ${error instanceof Error ? error.message : String(error)}`, ); } - }); + const id = recordId(record); + if (id !== undefined) { + sources.set(id, file); + } + projects.push(record); + } const externalProjects: unknown[] = []; if (existsSync(externalProjectsPath)) { @@ -296,12 +352,44 @@ export function readRawManifest( externalProjects.push(...(parsed.externalProjects ?? [])); } - return { projects, externalProjects }; + const duplicatedIds: string[] = []; + const owned = getManifestIndex().data.manifests.toSorted((a, b) => + a.repository.localeCompare(b.repository), + ); + for (const manifest of owned) { + const record = stripSchemaHint(manifest.record); + const id = recordId(record); + if (id === undefined) { + continue; + } + if (sources.has(id)) { + duplicatedIds.push(id); + // The owner wins, so validation sees one record: drop the local copy. + const index = projects.findIndex((entry) => recordId(entry) === id); + if (index !== -1) { + projects.splice(index, 1); + } + } + sources.set(id, `${manifest.repository} (${PROJECT_MANIFEST_PATH} at ${manifest.ref})`); + projects.push(record); + } + + return { projects, externalProjects, sources, duplicatedIds }; +} + +/** The id of a raw record, when it declares one. */ +function recordId(record: unknown): string | undefined { + const id = (record as { id?: unknown } | null)?.id; + return typeof id === 'string' ? id : undefined; } -/** Load, parse and validate the catalogue (one file per project) from disk. */ +/** + * Load, parse and validate the catalogue from this repository and from the + * project repositories that own their records (ADR 0013). + */ export function loadProjects(): ResolvedProject[] { - return parseManifest(readRawManifest(), DEFAULT_PROJECTS_DIR); + const raw = readRawManifest(); + return parseManifest(raw, DEFAULT_PROJECTS_DIR, undefined, raw.sources); } function withExternalDefaults(record: ExternalProjectRecord): ResolvedExternalProject { diff --git a/src/src/lib/manifest/remote.ts b/src/src/lib/manifest/remote.ts new file mode 100644 index 0000000..e7ec73e --- /dev/null +++ b/src/src/lib/manifest/remote.ts @@ -0,0 +1,258 @@ +import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { parse } from 'yaml'; + +import { resolveGitHubToken } from '../github/token'; +import { OWNER } from '../site'; + +/** + * Project-owned catalogue records (ADR 0013). + * + * A project repository publishes its own catalogue record at + * `.config/purview-docs.yml` — the record that used to live here under + * `src/src/data/projects/<id>.yml` — and this repository reads it at build time. + * The project owns its words and pointers, so they change in the same pull + * request as the thing they describe and cannot drift behind it. + * + * Discovery is the organisation's repository list: a repository that publishes + * the file is a catalogue project, so joining the catalogue is one file in the + * project repository and needs no pull request here. A repository without the + * file is skipped, which is what the 404 means. + * + * Records are read from `raw.githubusercontent.com` at the repository's default + * branch — the same source and ref the documentation mirror uses. Like every + * other external input they are cached under `.cache/` and snapshotted into + * `fixtures/manifests/index.json`, so rendering never performs network I/O and an + * offline build keeps working (`getManifestIndex`). + */ + +/** Where a project publishes its own catalogue record. */ +export const PROJECT_MANIFEST_PATH = '.config/purview-docs.yml'; + +export const MANIFEST_CACHE_SCHEMA_VERSION = 1; + +export const CACHE_DIR = resolve('.cache', 'manifests'); +export const CACHE_FILE = resolve(CACHE_DIR, 'manifests.json'); +export const FIXTURE_DIR = resolve('fixtures', 'manifests'); + +const API = 'https://api.github.com'; +const RAW = 'https://raw.githubusercontent.com'; + +/** One catalogue record fetched from the repository that owns it. */ +export interface RemoteManifest { + /** `owner/repository`, as the record's own `repository` field should read. */ + repository: string; + /** The ref the record was read at — the repository's default branch. */ + ref: string; + /** The parsed record. The loader strips the `$schema` hint. */ + record: Record<string, unknown>; +} + +export interface ManifestCacheData { + schema: number; + retrievedAt: string; + manifests: RemoteManifest[]; +} + +/** A repository that publishes a catalogue record. */ +export interface ManifestRepository { + name: string; + fullName: string; + defaultBranch: string; + archived: boolean; +} + +export class ManifestFetchError extends Error { + constructor(message: string) { + super(message); + this.name = 'ManifestFetchError'; + } +} + +function githubToken(): string | undefined { + return resolveGitHubToken(); +} + +/** Structural guard so a corrupt or stale cache can never be silently consumed. */ +export function isManifestCache(data: unknown): data is ManifestCacheData { + if (typeof data !== 'object' || data === null) { + return false; + } + const candidate = data as Record<string, unknown>; + if (candidate.schema !== MANIFEST_CACHE_SCHEMA_VERSION) { + return false; + } + if (typeof candidate.retrievedAt !== 'string') { + return false; + } + if (!Array.isArray(candidate.manifests)) { + return false; + } + return candidate.manifests.every((entry) => { + if (typeof entry !== 'object' || entry === null) { + return false; + } + const manifest = entry as Record<string, unknown>; + return ( + typeof manifest.repository === 'string' && + typeof manifest.ref === 'string' && + typeof manifest.record === 'object' && + manifest.record !== null + ); + }); +} + +function readCacheFile(file: string): ManifestCacheData | null { + if (!existsSync(file)) { + return null; + } + try { + const parsed: unknown = JSON.parse(readFileSync(file, 'utf8')); + return isManifestCache(parsed) ? parsed : null; + } catch { + return null; + } +} + +export function readManifestCache(file = CACHE_FILE): ManifestCacheData | null { + return readCacheFile(file); +} + +export function writeManifestCache(data: ManifestCacheData, file = CACHE_FILE): void { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, 'utf8'); +} + +/** Read a committed fixture (`fixtures/manifests/<name>.json`). */ +export function readManifestFixture(name = 'index'): ManifestCacheData | null { + return readCacheFile(resolve(FIXTURE_DIR, `${name}.json`)); +} + +/** + * List every repository the organisation publishes, including archived ones: an + * archived project still owns the record that says so, and its `status` is + * checked against the archived flag (ADR 0004). Dotfolders such as `.github` are + * skipped — they are organisation plumbing, not catalogue projects. + */ +export async function listOrganizationRepositories(): Promise<ManifestRepository[]> { + const token = githubToken(); + const headers: Record<string, string> = { + Accept: 'application/vnd.github+json', + 'X-GitHub-Api-Version': '2022-11-28', + 'User-Agent': 'purview-dev-website', + }; + if (token) { + headers.Authorization = `Bearer ${token}`; + } + + const repositories: ManifestRepository[] = []; + const perPage = 100; + for (let page = 1; page <= 10; page += 1) { + const response = await fetch( + `${API}/orgs/${OWNER}/repos?per_page=${perPage}&page=${page}&type=public`, + { headers }, + ); + if (!response.ok) { + throw new ManifestFetchError( + `GitHub request failed (${response.status}) listing ${OWNER}'s repositories. ` + + 'Run `gh auth login` or set GITHUB_TOKEN when the rate limit is exhausted.', + ); + } + const batch = (await response.json()) as unknown; + if (!Array.isArray(batch)) { + break; + } + for (const entry of batch as Record<string, unknown>[]) { + const name = String(entry.name ?? ''); + if (name === '' || name.startsWith('.')) { + continue; + } + repositories.push({ + name, + fullName: String(entry.full_name ?? `${OWNER}/${name}`), + defaultBranch: String(entry.default_branch ?? 'main'), + archived: Boolean(entry.archived), + }); + } + if (batch.length < perPage) { + break; + } + } + + return repositories.toSorted((a, b) => a.fullName.localeCompare(b.fullName)); +} + +/** + * Fetch one repository's record, or null when it does not publish one (404), + * which is how a repository that is not a catalogue project is skipped. + */ +export async function fetchProjectManifest( + repository: ManifestRepository, +): Promise<RemoteManifest | null> { + const url = `${RAW}/${repository.fullName}/${repository.defaultBranch}/${PROJECT_MANIFEST_PATH}`; + const response = await fetch(url, { headers: { 'User-Agent': 'purview-dev-website' } }); + if (response.status === 404) { + return null; + } + if (!response.ok) { + throw new ManifestFetchError( + `${repository.fullName}: ${PROJECT_MANIFEST_PATH} could not be read (${response.status}).`, + ); + } + + const text = await response.text(); + let record: unknown; + try { + record = parse(text); + } catch (error) { + throw new ManifestFetchError( + `${repository.fullName}: ${PROJECT_MANIFEST_PATH} is not valid YAML ` + + `(${error instanceof Error ? error.message : String(error)}).`, + ); + } + if (typeof record !== 'object' || record === null || Array.isArray(record)) { + throw new ManifestFetchError( + `${repository.fullName}: ${PROJECT_MANIFEST_PATH} must hold one project record.`, + ); + } + + return { + repository: repository.fullName, + ref: repository.defaultBranch, + record: record as Record<string, unknown>, + }; +} + +/** + * Read the record of every repository that publishes one. An unreadable record + * fails the sync rather than being skipped, because the alternative is publishing + * a catalogue that is silently missing a project: the message names every + * repository that has to be fixed. + */ +export async function fetchProjectManifests( + repositories: ManifestRepository[], +): Promise<RemoteManifest[]> { + const manifests: RemoteManifest[] = []; + const failures: string[] = []; + + for (const repository of repositories) { + try { + const manifest = await fetchProjectManifest(repository); + if (manifest) { + manifests.push(manifest); + } + } catch (error) { + failures.push(error instanceof Error ? error.message : String(error)); + } + } + + if (failures.length > 0) { + throw new ManifestFetchError( + ['Unreadable project catalogue record(s):', ...failures.map((line) => ` ${line}`)].join( + '\n', + ), + ); + } + + return manifests; +} diff --git a/src/src/lib/manifest/runtime.ts b/src/src/lib/manifest/runtime.ts new file mode 100644 index 0000000..3b24c10 --- /dev/null +++ b/src/src/lib/manifest/runtime.ts @@ -0,0 +1,75 @@ +import type { ManifestCacheData } from './remote'; + +import { + MANIFEST_CACHE_SCHEMA_VERSION, + readManifestCache, + readManifestFixture, + writeManifestCache, +} from './remote'; + +export type ManifestSource = 'cache' | 'fixture'; + +export interface ManifestIndex { + data: ManifestCacheData; + source: ManifestSource; +} + +let cached: ManifestIndex | null = null; + +/** + * Forget the memoized index so the next call re-reads the cache and fixture. + * + * The memo makes rendering cheap, but it also snapshots whichever source existed + * at the *first* call. `loadProjects()` resolves project-owned records through + * this accessor, so during `just data-sync` a process that never reset would keep + * aggregating documentation, skills and assets from the previous snapshot after + * `sync-manifests` had written a new one — a fresh record would not be seen until + * the next process. + */ +export function resetManifestIndex(): void { + cached = null; +} + +/** + * Publish freshly fetched records: write the cache and make this process read it. + * Every writer must go through here — a bare `writeManifestCache` leaves the memo + * pointing at the previous source. + */ +export function publishManifestData(data: ManifestCacheData): ManifestIndex { + writeManifestCache(data); + cached = { data, source: 'cache' }; + return cached; +} + +/** + * Build-time accessor for project-owned records. Prefers the local cache written + * by `just data-sync`, then the committed fixture. Never triggers network I/O + * during rendering, which is what lets an offline `just build` keep working: a + * repository whose record is missing from both sources simply contributes no + * remote record, and its local record (if any) still applies. + */ +export function getManifestIndex(): ManifestIndex { + if (cached) { + return cached; + } + const fromCache = readManifestCache(); + if (fromCache) { + cached = { data: fromCache, source: 'cache' }; + return cached; + } + const fromFixture = readManifestFixture('index'); + if (fromFixture) { + cached = { data: fromFixture, source: 'fixture' }; + return cached; + } + cached = { + data: { schema: MANIFEST_CACHE_SCHEMA_VERSION, retrievedAt: '', manifests: [] }, + source: 'fixture', + }; + return cached; +} + +/** True when nothing has published project-owned records in this process or run. */ +export function hasManifestData(): boolean { + return getManifestIndex().data.manifests.length > 0; +} diff --git a/src/tests/unit/manifest-remote.test.ts b/src/tests/unit/manifest-remote.test.ts new file mode 100644 index 0000000..897c9b6 --- /dev/null +++ b/src/tests/unit/manifest-remote.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, test } from 'bun:test'; +import { mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { + MANIFEST_CACHE_SCHEMA_VERSION, + PROJECT_MANIFEST_PATH, + isManifestCache, + readManifestCache, + writeManifestCache, +} from '../../src/lib/manifest/remote'; + +/** + * Project-owned catalogue records (ADR 0013) are fetched from the repositories + * that own them, so what decides whether a build sees the catalogue at all is the + * cache: a schema bump must read as "absent" (and force a sync) rather than as an + * empty catalogue, which would publish a site with no projects on it. + */ +function makeCache(overrides: Record<string, unknown> = {}): unknown { + return { + schema: MANIFEST_CACHE_SCHEMA_VERSION, + retrievedAt: '2026-11-15T00:00:00.000Z', + manifests: [ + { + repository: 'purview-dev/example', + ref: 'main', + record: { id: 'example', repository: 'purview-dev/example' }, + }, + ], + ...overrides, + }; +} + +describe('project-owned catalogue records', () => { + test('round-trips a cache through disk', () => { + const folder = mkdtempSync(join(tmpdir(), 'purview-manifests-')); + try { + const file = join(folder, 'manifests.json'); + writeManifestCache(makeCache() as Parameters<typeof writeManifestCache>[0], file); + + const read = readManifestCache(file); + expect(read?.schema).toBe(MANIFEST_CACHE_SCHEMA_VERSION); + expect(read?.manifests[0]?.repository).toBe('purview-dev/example'); + expect(read?.manifests[0]?.record.id).toBe('example'); + } finally { + rmSync(folder, { recursive: true, force: true }); + } + }); + + test('reads a cache written by an older schema as absent', () => { + const folder = mkdtempSync(join(tmpdir(), 'purview-manifests-')); + try { + const file = join(folder, 'manifests.json'); + writeManifestCache( + makeCache({ schema: MANIFEST_CACHE_SCHEMA_VERSION - 1 }) as Parameters< + typeof writeManifestCache + >[0], + file, + ); + + expect(readManifestCache(file)).toBeNull(); + } finally { + rmSync(folder, { recursive: true, force: true }); + } + }); + + test('rejects a record that is not an object', () => { + expect(isManifestCache(makeCache({ manifests: [{ repository: 'a/b', ref: 'main' }] }))).toBe( + false, + ); + expect(isManifestCache(makeCache({ manifests: 'not-an-array' }))).toBe(false); + expect(isManifestCache(makeCache())).toBe(true); + }); + + test('accepts a cache with no records', () => { + expect(isManifestCache(makeCache({ manifests: [] }))).toBe(true); + }); + + test('names the file a project publishes its record in', () => { + expect(PROJECT_MANIFEST_PATH).toBe('.config/purview-docs.yml'); + }); +}); diff --git a/src/tests/unit/manifest.test.ts b/src/tests/unit/manifest.test.ts index 554120f..30354b3 100644 --- a/src/tests/unit/manifest.test.ts +++ b/src/tests/unit/manifest.test.ts @@ -1,7 +1,15 @@ import { describe, expect, test } from 'bun:test'; - -import { loadExternalProjects, loadProjects, parseManifest } from '../../src/lib/manifest/load'; -import { ManifestValidationError, readRawManifest } from '../../src/lib/manifest/load'; +import { existsSync } from 'node:fs'; +import { join } from 'node:path'; + +import { + DEFAULT_PROJECTS_DIR, + ManifestValidationError, + loadExternalProjects, + loadProjects, + parseManifest, + readRawManifest, +} from '../../src/lib/manifest/load'; import { AUDIENCES } from '../../src/lib/manifest/schema'; describe('catalogue records', () => { @@ -37,6 +45,18 @@ describe('project manifest', () => { expect(ids).toContain('aspirec4'); }); + test('resolves a project that owns its record in its own repository (ADR 0013)', () => { + const projects = loadProjects(); + const zodsharp = projects.find((project) => project.id === 'zodsharp'); + expect(zodsharp).toBeDefined(); + expect(zodsharp?.repository).toBe('purview-dev/zodsharp'); + // The record is the project's: nothing of it is written here any more, and a + // second copy would be reported as a duplicate rather than merged. + const local = join(DEFAULT_PROJECTS_DIR, 'zodsharp.yml'); + expect(readRawManifest().duplicatedIds).toEqual([]); + expect(existsSync(local)).toBe(false); + }); + test('loads external (collaboration) projects', () => { const external = loadExternalProjects(); const likec4 = external.find((project) => project.id === 'likec4');