feat(csharp): outputParser generator — template.output parser-on-receipt codegen [FR6]

dmealing · claude · dmealing · commit 7d3a1c794315 · 2026-05-26T22:27:01.000-04:00
For every template.output declaration, the meta gen pipeline now emits a
&lt;TemplateName&gt;.output.cs file declaring a static &lt;TemplateName&gt;Parser class
with the .NET BCL Parse/TryParse dual API (ADR-0010):

  TName Parse(string text)                                  // throws JsonException
  bool TryParse(string, out TName?, out string?)            // Result-style

The parser returns the payload-VO record already emitted by PayloadCodegen
— it does not redeclare the payload shape. Validation is System.Text.Json
deserialization plus the C# required keyword on the payload record
(.NET 7+); no DataAnnotations layer, no extra deps.

Wired into GenCommand.DefaultGenerators() alongside Entity/DbContext/Routes.
Mirrors typescript/packages/codegen-ts/src/generators/output-parser-file.ts
functionally, with BCL idioms instead of Zod.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/server/csharp/MetaObjects.Cli/GenCommand.cs b/server/csharp/MetaObjects.Cli/GenCommand.cs
@@ -20,7 +20,7 @@ public sealed record Outcome(IReadOnlyList<string> LoadErrors, CodegenRunner.Run
 
     /// <summary>The default generator set. Extended as more generators land.</summary>
     public static IReadOnlyList<IGenerator> DefaultGenerators() =>
-        [new EntityGenerator(), new DbContextGenerator(), new RoutesGenerator()];
+        [new EntityGenerator(), new DbContextGenerator(), new RoutesGenerator(), new OutputParserGenerator()];
 
     public static Outcome Run(string metadataDir, string outDir, string ns)
     {
diff --git a/server/csharp/MetaObjects.Codegen.Tests/OutputParserGeneratorTests.cs b/server/csharp/MetaObjects.Codegen.Tests/OutputParserGeneratorTests.cs
@@ -0,0 +1,169 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using MetaObjects.Codegen;
+using MetaObjects.Codegen.Generators;
+using MetaObjects.Loader;
+using MetaObjects.Meta;
+using Xunit;
+
+namespace MetaObjects.Codegen.Tests;
+
+/// <summary>
+/// OutputParserGenerator emission tests (FR6, ADR-0010). Mirrors
+/// server/typescript/packages/codegen-ts/test/generators/output-parser-file.test.ts —
+/// asserts the file-per-template emit, the Parse / TryParse dual-API shape, and
+/// that the generator stays out of template.prompt's lane.
+/// </summary>
+public sealed class OutputParserGeneratorTests
+{
+    private static MetaRoot Load(string model)
+    {
+        var r = new MetaDataLoader().Load([new InMemoryStringSource(model, id: "outputs.json")]);
+        Assert.Empty(r.Errors);
+        return r.Root;
+    }
+
+    private static GenContext Ctx(MetaRoot root) => new()
+    {
+        Entities = root.Objects(),
+        Root = root,
+        Config = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Generated" },
+    };
+
+    [Fact]
+    public void Emits_no_files_when_no_template_output_nodes()
+    {
+        // A model with only a template.prompt; the output-parser generator stays silent.
+        const string m = """
+        { "metadata.root": { "package": "acme::ai", "children": [
+          { "object.value": { "name": "Payload", "children": [ { "field.string": { "name": "x" } } ] } },
+          { "template.prompt": { "name": "promptOnly", "@payloadRef": "Payload", "@textRef": "p/x", "@format": "text" } }
+        ]}}
+        """;
+        var files = new OutputParserGenerator().Generate(Ctx(Load(m))).ToList();
+        Assert.Empty(files);
+    }
+
+    [Fact]
+    public void Emits_one_file_per_template_output_with_expected_path_and_class()
+    {
+        const string m = """
+        { "metadata.root": { "package": "acme::ai", "children": [
+          { "object.value": { "name": "AlphaPayload", "children": [ { "field.string": { "name": "name" } } ] } },
+          { "object.value": { "name": "BetaPayload",  "children": [ { "field.int":    { "name": "n" } } ] } },
+          { "template.output": { "name": "Alpha", "@payloadRef": "AlphaPayload", "@textRef": "a/x", "@format": "json" } },
+          { "template.output": { "name": "Beta",  "@payloadRef": "BetaPayload",  "@textRef": "b/x", "@format": "json" } }
+        ]}}
+        """;
+        var files = new OutputParserGenerator().Generate(Ctx(Load(m))).OrderBy(f => f.Path).ToList();
+        Assert.Equal(2, files.Count);
+        Assert.Equal("Alpha.output.cs", files[0].Path);
+        Assert.Equal("Beta.output.cs",  files[1].Path);
+        Assert.Contains("public static class AlphaParser", files[0].Content);
+        Assert.Contains("public static class BetaParser",  files[1].Content);
+    }
+
+    [Fact]
+    public void Emits_dual_api_returning_the_payload_ref_type()
+    {
+        const string m = """
+        { "metadata.root": { "package": "acme::ai", "children": [
+          { "object.value": { "name": "NpcResponsePayload", "children": [
+            { "field.string": { "name": "name" } },
+            { "field.int":    { "name": "age" } }
+          ]}},
+          { "template.output": { "name": "NpcResponseOutput", "@payloadRef": "NpcResponsePayload",
+                                  "@textRef": "npc/output", "@format": "json" } }
+        ]}}
+        """;
+        var file = Assert.Single(new OutputParserGenerator().Generate(Ctx(Load(m))));
+        Assert.Equal("NpcResponseOutput.output.cs", file.Path);
+
+        var src = file.Content;
+        Assert.Contains("using System.Text.Json;", src);
+        Assert.Contains("namespace Acme.Generated;", src);
+        Assert.Contains("public static class NpcResponseOutputParser", src);
+
+        // Parse returns the payload-VO type and throws on failure.
+        Assert.Contains("public static NpcResponsePayload Parse(string text)", src);
+        Assert.Contains("throw new JsonException", src);
+
+        // TryParse returns bool + nullable out + error out.
+        Assert.Contains("public static bool TryParse(string text,", src);
+        Assert.Contains("[NotNullWhen(true)] out NpcResponsePayload? value", src);
+        Assert.Contains("[NotNullWhen(false)] out string? error", src);
+    }
+
+    [Fact]
+    public void Emitted_source_compiles_alongside_the_payload_record()
+    {
+        // End-to-end: payload-VO codegen + output-parser codegen should compile
+        // together with no errors. Guards against C# language-level regressions
+        // in the emitted shape (required keyword, nullable annotations, etc.).
+        const string m = """
+        { "metadata.root": { "package": "acme::ai", "children": [
+          { "object.value": { "name": "NpcResponsePayload", "children": [
+            { "field.string": { "name": "name" } },
+            { "field.int":    { "name": "age" } }
+          ]}},
+          { "template.output": { "name": "NpcResponseOutput", "@payloadRef": "NpcResponsePayload",
+                                  "@textRef": "npc/output", "@format": "json" } }
+        ]}}
+        """;
+        var root = Load(m);
+        var parserSrc = Assert.Single(new OutputParserGenerator().Generate(Ctx(root))).Content;
+        var payloadSrc = PayloadCodegen.GeneratePayloadRecords(root, "NpcResponsePayload");
+
+        // Wrap the payload record in a namespace matching the parser's.
+        var wrappedPayload = "namespace Acme.Generated;\n" + payloadSrc;
+
+        var trees = new[]
+        {
+            CSharpSyntaxTree.ParseText(parserSrc,     new CSharpParseOptions(LanguageVersion.CSharp12)),
+            CSharpSyntaxTree.ParseText(wrappedPayload, new CSharpParseOptions(LanguageVersion.CSharp12)),
+        };
+        var refs = ((string)AppContext.GetData("TRUSTED_PLATFORM_ASSEMBLIES")!)
+            .Split(Path.PathSeparator).Where(p => p.Length > 0)
+            .Select(p => (MetadataReference)MetadataReference.CreateFromFile(p)).ToList();
+        var comp = CSharpCompilation.Create("outparse_" + Guid.NewGuid().ToString("N"),
+            trees, refs, new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));
+        var errors = comp.GetDiagnostics().Where(d => d.Severity == DiagnosticSeverity.Error)
+            .Select(d => $"{d.Id}: {d.GetMessage()}").ToList();
+        Assert.True(errors.Count == 0, "parser + payload should compile, got: " + string.Join("; ", errors));
+    }
+
+    [Fact]
+    public void Emitted_source_matches_the_template_output_simple_fixture()
+    {
+        // Conformance-adjacent check: the same fixture used by the TS port should
+        // drive the C# emit (different output shape — TS = Zod, C# = STJ — but
+        // same metadata in).
+        var repoRoot = LocateRepoRoot();
+        var fixtureDir = Path.Combine(repoRoot, "fixtures", "conformance", "template-output-simple", "input");
+        Assert.True(Directory.Exists(fixtureDir), $"fixture dir not found at {fixtureDir}");
+
+        var load = MetaDataLoader.FromDirectory(fixtureDir);
+        Assert.Empty(load.Errors);
+
+        var ctx = new GenContext
+        {
+            Entities = load.Root.Objects(),
+            Root = load.Root,
+            Config = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Generated" },
+        };
+        var file = Assert.Single(new OutputParserGenerator().Generate(ctx));
+        Assert.Equal("NpcResponseOutput.output.cs", file.Path);
+        Assert.Contains("public static NpcResponsePayload Parse(string text)", file.Content);
+        Assert.Contains("public static bool TryParse(string text,", file.Content);
+    }
+
+    // Walk upward from the test assembly to the repo root (contains a fixtures/ dir).
+    private static string LocateRepoRoot()
+    {
+        var dir = new DirectoryInfo(AppContext.BaseDirectory);
+        while (dir is not null && !Directory.Exists(Path.Combine(dir.FullName, "fixtures")))
+            dir = dir.Parent;
+        Assert.NotNull(dir);
+        return dir!.FullName;
+    }
+}
diff --git a/server/csharp/MetaObjects.Codegen/Generators/OutputParserGenerator.cs b/server/csharp/MetaObjects.Codegen/Generators/OutputParserGenerator.cs
@@ -0,0 +1,110 @@
+// output-parser-generator — for each `template.output` declaration, emits a
+// `<TemplateName>.output.cs` file declaring a static `<TemplateName>Parser`
+// class with the .NET BCL `Parse`/`TryParse` dual API (ADR-0010). `Parse`
+// throws on bad input; `TryParse` returns a bool and an out-error.
+//
+// The emitted parser RETURNS the payload-VO record already emitted by
+// PayloadCodegen (same metadata model). It does NOT redeclare the payload
+// shape; this generator emits parser glue only.
+//
+// Ported from typescript/packages/codegen-ts/src/generators/output-parser-file.ts
+// (renderer in typescript/packages/codegen-ts/src/templates/output-parser.ts).
+// TS uses Zod; C# uses System.Text.Json + the `required` keyword for
+// presence enforcement (.NET 7+). No DataAnnotations / Validator pass —
+// `required`-keyword construction + STJ's strict deserialization cover
+// presence + type in BCL-native form.
+
+using System.Text;
+using MetaObjects.Meta;
+using static MetaObjects.Shared.BaseTypes;
+using static MetaObjects.Template.TemplateConstants;
+
+namespace MetaObjects.Codegen.Generators;
+
+/// <summary>
+/// Emits one parser file per <c>template.output</c> node, with a static class
+/// exposing <c>Parse(string)</c> + <c>TryParse(string, out T?, out string?)</c>.
+/// </summary>
+public sealed class OutputParserGenerator : IGenerator
+{
+    public string Name => "output-parser-generator";
+
+    public IEnumerable<EmittedFile> Generate(GenContext ctx)
+    {
+        var outputs = ctx.Root.OwnChildren()
+            .Where(c => c.Type == TYPE_TEMPLATE && c.SubType == TEMPLATE_SUBTYPE_OUTPUT)
+            .OrderBy(t => t.Name, StringComparer.Ordinal)
+            .ToList();
+
+        var files = new List<EmittedFile>();
+        foreach (var tmpl in outputs)
+        {
+            if (tmpl.OwnAttr(TEMPLATE_ATTR_PAYLOAD_REF) is not string payloadRef)
+            {
+                // Loader passes treat missing @payloadRef as a load error; defensively skip.
+                ctx.Warn($"{Name}: template.output \"{tmpl.Name}\" missing @payloadRef — skipped.");
+                continue;
+            }
+            files.Add(EmitParser(tmpl.Name, payloadRef, ctx));
+        }
+        return files;
+    }
+
+    private static EmittedFile EmitParser(string templateName, string payloadRef, GenContext ctx)
+    {
+        var parserClass = $"{templateName}Parser";
+        var payloadType = payloadRef;
+
+        var sb = new StringBuilder();
+        sb.AppendLine("// <auto-generated/>");
+        sb.AppendLine("// Generated by MetaObjects output-parser-generator. Do not edit by hand.");
+        sb.AppendLine("#nullable enable");
+        sb.AppendLine("using System;");
+        sb.AppendLine("using System.Diagnostics.CodeAnalysis;");
+        sb.AppendLine("using System.Text.Json;");
+        sb.AppendLine();
+        sb.AppendLine($"namespace {ctx.Config.Namespace};");
+        sb.AppendLine();
+        sb.AppendLine($"/// <summary>Parser for LLM responses matching the <c>{templateName}</c> template.output.</summary>");
+        sb.AppendLine($"public static class {parserClass}");
+        sb.AppendLine("{");
+        sb.AppendLine("    private static readonly JsonSerializerOptions Options = new()");
+        sb.AppendLine("    {");
+        // Case-sensitive (default) — the payload-VO property names are emitted as
+        // the exact metadata field names (typically camelCase), which matches the
+        // JSON the LLM is expected to produce.
+        sb.AppendLine("        PropertyNameCaseInsensitive = false,");
+        sb.AppendLine("    };");
+        sb.AppendLine();
+        sb.AppendLine($"    /// <summary>Parse an LLM response into a typed <see cref=\"{payloadType}\"/>.</summary>");
+        sb.AppendLine($"    /// <param name=\"text\">The raw response text — expected to be JSON.</param>");
+        sb.AppendLine("    /// <returns>The deserialized, validated payload.</returns>");
+        sb.AppendLine("    /// <exception cref=\"JsonException\">JSON is malformed, missing a <c>required</c> property, or has a type mismatch.</exception>");
+        sb.AppendLine($"    public static {payloadType} Parse(string text) =>");
+        sb.AppendLine($"        JsonSerializer.Deserialize<{payloadType}>(text, Options)");
+        sb.AppendLine($"            ?? throw new JsonException(\"deserialized to null\");");
+        sb.AppendLine();
+        sb.AppendLine($"    /// <summary>Parse with explicit error handling — does not throw on validation failure.</summary>");
+        sb.AppendLine("    /// <param name=\"text\">The raw response text — expected to be JSON.</param>");
+        sb.AppendLine("    /// <param name=\"value\">On success, the deserialized payload; otherwise null.</param>");
+        sb.AppendLine("    /// <param name=\"error\">On failure, a human-readable error message; otherwise null.</param>");
+        sb.AppendLine("    /// <returns><c>true</c> on success; <c>false</c> on validation failure.</returns>");
+        sb.AppendLine($"    public static bool TryParse(string text, [NotNullWhen(true)] out {payloadType}? value, [NotNullWhen(false)] out string? error)");
+        sb.AppendLine("    {");
+        sb.AppendLine("        try");
+        sb.AppendLine("        {");
+        sb.AppendLine("            value = Parse(text);");
+        sb.AppendLine("            error = null;");
+        sb.AppendLine("            return true;");
+        sb.AppendLine("        }");
+        sb.AppendLine("        catch (JsonException ex)");
+        sb.AppendLine("        {");
+        sb.AppendLine("            value = null;");
+        sb.AppendLine("            error = ex.Message;");
+        sb.AppendLine("            return false;");
+        sb.AppendLine("        }");
+        sb.AppendLine("    }");
+        sb.AppendLine("}");
+        return new EmittedFile($"{templateName}.output.cs", sb.ToString());
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ public sealed record Outcome(IReadOnlyList<string> LoadErrors, CodegenRunner.Run`
`20`	`20`
`21`	`21`	`/// <summary>The default generator set. Extended as more generators land.</summary>`
`22`	`22`	`public static IReadOnlyList<IGenerator> DefaultGenerators() =>`
`23`		`- [new EntityGenerator(), new DbContextGenerator(), new RoutesGenerator()];`
	`23`	`+ [new EntityGenerator(), new DbContextGenerator(), new RoutesGenerator(), new OutputParserGenerator()];`
`24`	`24`
`25`	`25`	`public static Outcome Run(string metadataDir, string outDir, string ns)`
`26`	`26`	`{`