Epic: extract and generalize the code generation stack so other projects can share it

[matt-edmondson]

Summary

Semantics.SourceGenerators had grown a general-purpose code-generation stack that has nothing to do with physical quantities. Roughly half of the project — the C# syntax template object model, the JSON-metadata-driven IIncrementalGenerator base, deterministic output handling, diagnostics plumbing, and the generator test harness — would work unchanged for any metadata-driven generator, but was only usable by this repository.

This epic tracks pulling that infrastructure out into shared packages and migrating Semantics.SourceGenerators onto them.

Status

Every task on the original list is merged. One piece of the goal remains, tracked as #192.

PR	Issues	State
ktsu-dev/CodeBlocker#87	#81–#86	Merged, shipped as ktsu.CodeBlocker 1.3.0
#188	#182, #183, #185, #186	Merged
#190	#184, #187	Merged

Tasks

Layer 1 — ktsu.CodeBlocker, no Roslyn dependency:

• Make output line endings deterministic and configurable CodeBlocker#81 — Deterministic, configurable line endings
• Accept any TextWriter, not just StringWriter CodeBlocker#82 — Accept any TextWriter
• Add scope and preprocessor-directive helpers for common code-gen shapes CodeBlocker#83 — Scope and preprocessor-directive helpers
• Adopt the C# syntax template object model from ktsu.Semantics CodeBlocker#84 — The C# syntax template object model
• Close the correctness and coverage gaps in the C# template object model CodeBlocker#85 — Close the template model's correctness gaps
• Model XML documentation comments as structured data CodeBlocker#86 — XML documentation as structured data

Layer 2 + cutover, here:

• Extract GeneratorBase<T> and JSON metadata loading into a reusable Roslyn generator toolkit #182 — GeneratorBase and JSON metadata loading, shaped for extraction in CodeGen/
• Split Emit into generic C# fragments and Semantics-specific constants #183 — Emit split into generic C# fragments and Semantics-specific constants
• Retire GeneratedSource once CodeBlocker emits deterministic newlines #184 — GeneratedSource retired; the terminator is pinned at construction
• Extract a reusable generator diagnostics helper #185 — Reusable generator diagnostics helper
• Extract a reusable source-generator test harness and committed-output drift check #186 — Reusable generator test harness and committed-output drift check
• Migrate Semantics.SourceGenerators onto the extracted code-generation packages #187 — Generators emit through ktsu.CodeBlocker.Templates
• Move CodeGen/ into a shared source-generator toolkit package #192 — Move CodeGen/ into a shared toolkit package

What #192 still needs

CodeGen/ is shaped for extraction — one-way dependency, nothing physics-specific, public where it needs to be — but it lives here, so a second project cannot use it without depending on ktsu.Semantics. It needs a home first:

• (a) A new ktsu-dev/SourceGeneratorToolkit repo — recommended. Keeps the Roslyn dependency and analyzer-packaging rules out of CodeBlocker.
• (b) A second package in the CodeBlocker repo — fewer repos, but couples CodeBlocker's release cadence to Roslyn's.

What changed, in short

• The template model is a package, and it now emits valid C# for shapes it never handled: types close with } not };, bodies are re-indented to where they are spliced, accessors are data rather than callbacks compared by reference, and operators, generics, enums, interfaces and positional records are expressible at all.
• Two generators — not one — had each reimplemented multi-file metadata loading around the base's single-file limit. Both now just declare the files they read.
• Three silent failures became diagnostics: a swallowed JsonException on a second metadata file, a missing metadata file that produced no output and no explanation, and parse failures reported under a stray CONV001/SourceGenerator identity.
• Generated output is written with LF, matching .gitattributes. The pass that rewrote it to CRLF was working from a premise that stopped being true at the LF migration in Unblock the build (header + LF migration) and fix 66 SonarCloud issues #157; git had been normalising the difference away on every commit since. verify-generated consequently runs on Linux now.

Follow-ups found along the way

All now tracked:

Issue	What
#191	92 Semantics.Paths tests fail on Linux; main red since the matrix added it. Some may be real library bugs, not test assumptions.
#193	SEM001 and SEM003 still report without a source location; SEM004 got one in #182.
#194	RS2002 fires once per SEM diagnostic on every build — generator diagnostics cannot satisfy the release-tracking analyzer.
#195	The local Sonar reproduction reaches one of six projects; CustomAfterMicrosoftCommonProps fixes that.
ktsu-dev/CodeBlocker#88	CodeBlocker has no local Sonar reproduction, which is why one finding on #87 could not be identified.
ktsu-dev/CodeBlocker#89	Whether ktsu.CodeBlocker should default to LF rather than Environment.NewLine — deferred from #81.

Definition of done

Semantics.SourceGenerators contains only Models/, Metadata/, and Generators/ with physics-specific emission logic; everything above comes from packages a second project could consume without taking a dependency on this repository.

Layer 1 meets this. Layer 2 will once #192 lands.