An AST that can describe a header: all three sections of the exemplar

[matt-edmondson]

The exemplar in matt-edmondson/Holotype#5 specifies the schema compiler being moved into this stack by writing its output rather than describing it. Nothing here could express any of it: no struct, no enumeration, no field distinct from a local, no documentation, no namespace, no file, no constructor, no operator, no way to say a declaration has no definition.

All three sections now generate, and the acceptance test is that document:

Section	Test
A component	ExemplarHeaderTests
A semantic type	ExemplarSemanticTypeTests
An interface	ExemplarInterfaceTests

Each builds the declaration as an AST and asserts the generated C++ character for character against the document's own text.

---

1. What a generated header is made of

TypeDeclarationKind on ClassDeclaration (class, struct, interface), EnumDeclaration, FieldDeclaration, IHasDocumentation, NamespaceDeclaration, SourceFile.

FieldDeclaration is deliberately not VariableDeclaration. The two are spelled almost identically and differ in the one way that matters:

BodyKind body_kind{};    // a field with no initialiser is value-initialised
int x;                   // a local with none is ordinary

A default-constructed instance is then the instance the declaration described — the whole point for a type whose values come from a save file or the wire.

Documentation is lines, not prose, because most of what ends up there isn't:

/// Linear velocity in world space.
/// unit: m/s
/// interpolated between states
/// network: quantised to 0.01, delta encoded
holo::Vec3<holo::MetresPerSecond> velocity{};

Imports are the one part of the AST that does not translate. A C++ include path, a C# namespace and a Python module are different kinds of thing that share a position, so each is carried as text and a file is built for a language. An empty import is a group separator rather than an import of nothing.

2. Declaring behaviour for someone else to implement

FunctionKind (method, constructor, destructor, operator, conversion) and FunctionDefinition (provided, defaulted, deleted) — a declaration with no statements is otherwise ambiguous between a function that does nothing, one the language supplies, and one that exists to be refused.

Four modifiers beside them: IsVirtual, IsAbstract, IsReadOnly, MustUseResult.

IsAbstract is C++'s pure virtual, which is a different thing from IsPure: one says a declaration has no definition, the other that a call has no effect. Both earn [[nodiscard]] in the end, but for different reasons — purity implies it, and so does returning something that may be a failure.

A constructor and destructor are named after the type, so the name comes from the class emitter rather than the declaration holding a second copy that can desynchronise on rename.

3. A distinct name for something already representable

UsingAlias, MemberInitialiser, ConstructionExpression, plus IsExplicit, IsCompileTimeEvaluable, IsNoThrow, IsFriend.

A member is initialised, not assigned. That is the only way to start a member that cannot be assigned at all, and is the difference between building a value and building an empty one and then overwriting it. C#, Python and JavaScript have no initialiser list, so they assign at the top of the constructor in declaration order — which is what the initialiser means there.

ConstructionExpression is the one expression that needs a type rather than a name, which is why it could not exist before TypeReference did. C++ braces it: braces will not narrow silently, and a one-argument construction written with parentheses can be read as a declaration instead.

---

Each language says as much as it can

C++ says all of it. C# says most, and expresses a defaulted or deleted member by not declaring one — so it declares neither and writes a line naming which member went and why, because a generated file that silently drops one looks complete and is not.

Python and JavaScript have no declaration without a definition at all, so a method a derived type must supply becomes a body that refuses — raise NotImplementedError and throw. Python names a constructor __init__ rather than after its type; neither has any spelling for an operator, which they say rather than drop.

Spacing is a rule, not an accident

A blank line goes between two members when either is documented, when they are different kinds of thing, or where the access changes. That reproduces all three sections: a run of aliases is one group, so is a run of defaulted and deleted declarations, and private: always gets air above it.

The separator is NewLine rather than WriteLine, because a blank line carrying the current indent is trailing whitespace that every formatter strips and every diff then shows.

Two defects the exemplar exposed

Both predate this branch, and neither was visible until there was a specification to compare against:

• A C++ access label was indented with the members. It sits at the class's own indentation, which is what makes it read as dividing them rather than as one of them.
• A parameter with an empty name emitted a trailing space. An unnamed parameter is exactly what a deleted copy declaration wants. An empty name is now deliberately unnamed; a null one still has one invented, because nobody said.

Deliberate differences from the document

Three, all recorded in the tests:

1. The two static_asserts below the component and the semantic type. They are an assertion about a generated type rather than something the schema asked for, and where they belong is still open.
2. Indentation is spaces where the document has tabs — a setting of the writer, and Holotype's .clang-format (UseTab: true) converts it on the way past.
3. The short accessor. The document writes { return value_; } on the signature's line; the generator writes a braced block. I expected clang-format to reconcile these and it does not — run over each, it leaves both exactly as written. So this is the generator's choice, not the formatter's, and copying the inline style would mean a generator guessing at when a body is short enough to fold.

The expectation in each acceptance test is the document's own text. The semantic type's is the document with exactly one line rewritten — the accessor above — and the test names that substitution so a reader can see it is the only one.

Verification

• dotnet build -c Release — 0 warnings, 0 errors across the solution
• 477 tests pass (413 before, 64 new), 0 failures
• SonarCloud quality gate passed: 0 new issues, 92.5% coverage on new code, 0 duplication

Everything new round-trips through YAML, appears in AstSchema's slots and AstFields' rows, and writes nothing to a document for what a declaration does not say — so a file written before any of this still opens.

The gate failed three times on coverage before it passed, and the fix was to test the two things that were genuinely untested rather than whatever was cheapest. AstSchema had 37 of its 41 new lines uncovered — the slots the editor reaches every new declaration through were reached by nothing — and the Clone methods were the other gap, which matters because the editor clones to undo and a clone sharing a collection with its original shows up as an edit landing in two places at once, far from where the clone was made. The shim vocabulary was exercised only by the C++ acceptance test, so its C#, Python and JavaScript paths and its whole YAML round trip had no test at all.

Writing those found a real gap: a UsingAlias had no inspector rows, so it could be moved around the graph but its name and type could not be edited.

What is next

The bridge from a ktsu.Schema model to these nodes, and the gaps in holotype/core that the document's type table names: Result and Handle do not exist yet, so an interface returning one cannot be generated until they do.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AhoPJ5AbxP8QEBNxPQYEPk

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud