[Mpdreamz]

Configuration files load into typed domain records, and the rules about them are named constraints that the loaders check once and a generator tests. The build reports more problems it used to accept silently, as warnings and hints, and the tests found and fixed several real bugs on the way.

Affects: Configuration, Assembler builds, Release notes

Prompt summary: Make the domain model of docs-builder explicit. Each configuration file loads once into a typed record, its rules become named constraints instead of scattered checks, and those rules are tested against generated data. What is accepted, reported and written stays the same unless a change is called out: an error stays an error, and a new check starts as a warning.

Why

Rules about configuration live in loaders, validators and constructors, each written a little differently. They drift apart, so one command can accept a file that another rejects, and nothing tests properties such as "loading twice gives the same result" or "the order of the entries does not change the output". A typed record with named rules puts each rule in one place and lets a generator exercise it.

Writing the rules as tests found defects that example-based tests had not: an infinite loop and null references in the navigation and assembly loaders, an ordering bug in SemVersion, and mount resolution at path-segment boundaries.

What

Configuration files load into typed records

docset.yml, assembler.yml, navigation.yml, changelog.yml, codex.yml, the product catalog, search tuning and links.json (now LinkManifest) are read into a *Dto, then into a domain record with value equality. Golden snapshots over a frozen baseline check that the new loaders produce what the old ones did, and a test fails when a DTO field is not accounted for in its projection.

Rules are named constraints, checked once

Rules are Constraint<T> values collected in 32 [Constraints] classes, described in src/Elastic.Documentation/Constraints-Conventions.md. A loader checks a set once and reports each violation under the rule's id. New rules start as warnings or hints, for example an empty Markdown page in a table of contents is D108 (a warning). ConstraintSeverityLedgerTests pins the declared severity of all 287 rules, so a rule weakened from error to warning shows up as a diff.

Rules are tested on generated data

Each constraint set is tested on nine axes by Nullean.Entities.CsCheck, which generates records with hostile values (blank strings, duplicate ids, undefined enum values) and reports a failing case as the smallest one with a seed that replays it. Hand-written counter-examples remain only where a machine cannot find one. Four rules (CodexGroupKnown, GroupIdsUnique, QueryRuleIdUnique, BundleEntryFilesUnique) are declared once as relations, so the rule and the data generator cannot drift apart.

Nullean.Entities comes from NuGet

Six PackageReference entries at 0.1.0 replace project references to a checkout at a fixed path on one machine, with their versions in Directory.Packages.props. The source generator ships inside the Nullean.Entities package, and Nullean.Entities.props is gone.

Main is merged in

The branch contains main as of the SharpYaml migration. Main's readers feed the typed loaders, unknown keys in applies_to are errors as on main, and the S3 retained-assets plan, the changelog cache and the unified release-notes commands run on the domain records.

Verify

dotnet test tests/Elastic.Documentation.Tests/
dotnet test tests/Elastic.Documentation.Configuration.Tests/
dotnet test tests/Documentation.Builder.Tests/
dotnet test tests/Elastic.Documentation.Deploying.Tests/
dotnet test tests/Elastic.Documentation.OpenApiIndex.Tests/
dotnet test tests/Elastic.Documentation.Api.Tests/

The unit suites pass on the merge commit. ./build.sh unit-test restores again now that main pins MessagePack 2.5.303.

🤖 Generated with Claude Code

[theletterf]

Big one! Woof!

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4530/

Sample changed pages:

• src/Elastic.Documentation/Constraints-Conventions.md
• tests/Elastic.Documentation.Configuration.Tests/Baseline/README.md
• AGENTS.md
• docs/documentation/assembler/environments.md