fix(codegen): C# generators declare what they require; a template spec alone is a selection

Two defects, found while fixing the Python quickstart's routes gap for C#.

1. C# had no `requires`. `--generators entity,routes` emitted handlers that reference
   AppDbContext and <Entity>FilterAllowlist and did not compile, with no warning. The
   registry entry gains `Requires`: routes needs entity, db-context and filter-allowlist;
   db-context needs entity; output-parser, extractor and render-helper need entity
   (ADR-0056). `gen` warns when one is missing, with the text TS and Python use, and
   `--list` shows "(requires: ...)". Advisory, as in the other ports.

2. C# gen and Python gen refused a project that selects generators only through a
   template spec ("no generators selected"), because the empty-selection check ran
   before the spec was resolved. The documented `gen --template-root` examples failed as
   printed. C# verify had the mirror defect: it returned clean before discovering the
   spec, so a spec-only project's drift gate checked nothing. Both checks now run after
   spec resolution. Python verify already did this.

C# `gen` also stops reporting an empty selection as "metadata did not load cleanly"; it is
a usage error, exit 2, as in Python. docs/ports/csharp.md's first gen example named no
generators and wrote nothing; it now names the suite and says what routes requires.

Tests: C# registry (Requires, UnsatisfiedRequires), --list shows requires, and three
spec-only tests (gen not refused, verify catches an edited spec file, no selection is
still refused); Python spec-only gen and refusal. The spec-only tests fail without the
fix. C# CLI 122/0, Codegen 572/0; Python 2299/0; ci-local --quick green.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M1mRRB1K2WdYy82kntMQdx

Author: dmealing

docs/ports/csharp.md

@@ -85,12 +85,18 @@ for a worked example.
 
 ```bash
 # Generate EF Core entities + AppDbContext + CRUD minimal-API routes
-dotnet meta gen ./metadata --out ./Generated --namespace Acme.Blog
+dotnet meta gen ./metadata --out ./Generated --namespace Acme.Blog \
+  --generators entity,db-context,filter-allowlist,routes
 
 # Drift-check templates against payloads (FR-004)
 dotnet meta verify ./metadata --templates ./prompts
 ```
 
+Codegen is opt-in: with no `--generators`, `gen` writes nothing. `dotnet meta gen --list` is
+the catalog, and it shows what each generator requires. `routes` requires `entity`,
+`db-context` and `filter-allowlist`, because the handlers it emits reference their output;
+`gen` warns when one is missing, since the result would not compile.
+
 Schema migrations are owned by the Node `meta` CLI (ADR-0015) — the C# CLI is
 `gen` + `verify` only.
 

server/csharp/MetaObjects.Cli.Tests/GenListAndSelectionTests.cs

@@ -62,6 +62,14 @@ public void ListLines_prints_all_generators_with_stable_names_and_descriptions()
         }
     }
 
+    [Fact]
+    public void ListLines_shows_what_a_generator_requires()
+    {
+        var lines = GenCommand.ListLines(_tmp);
+        Assert.Contains(lines, l => l.Contains(" routes —") && l.Contains("(requires: entity, db-context, filter-allowlist)"));
+        Assert.DoesNotContain(lines, l => l.Contains(" entity —") && l.Contains("requires"));
+    }
+
     [Fact]
     public void There_is_no_default_suite()
     {

server/csharp/MetaObjects.Cli.Tests/VerifyTemplateSpecTests.cs

@@ -113,6 +113,38 @@ public void Verify_codegen_still_catches_an_edited_template_file()
         Assert.NotEqual(0, r.ExitCode);
     }
 
+    // A spec IS a selection. Both commands used to test for an empty --generators BEFORE
+    // resolving the spec: gen refused a spec-only project, and verify reported it clean
+    // without checking anything.
+    [Fact]
+    public void Gen_with_only_a_spec_is_not_refused()
+    {
+        var outcome = GenCommand.Run(MetaDir, OutDir, "Acme.Generated", emitAbstractShapes: false,
+            generatorNames: null, templateRoot: TemplateRoot);
+        Assert.True(outcome.Ok, string.Join("; ", outcome.LoadErrors));
+        Assert.True(File.Exists(Path.Combine(OutDir, "Widget.summary.txt")));
+    }
+
+    [Fact]
+    public void Verify_with_only_a_spec_still_catches_an_edited_template_file()
+    {
+        Assert.True(GenCommand.Run(MetaDir, OutDir, "Acme.Generated", emitAbstractShapes: false,
+            generatorNames: null, templateRoot: TemplateRoot).Ok);
+        File.WriteAllText(Path.Combine(OutDir, "Widget.summary.txt"), "tampered\n");
+
+        var r = VerifyCommand.RunSubverbs(CodegenOpts() with { Generators = null });
+        Assert.NotEqual(0, r.ExitCode);
+    }
+
+    [Fact]
+    public void Gen_with_neither_generators_nor_a_spec_is_still_refused()
+    {
+        File.Delete(DiscoveredSpec);
+        var outcome = GenCommand.Run(MetaDir, OutDir, "Acme.Generated", emitAbstractShapes: false,
+            generatorNames: null, templateRoot: TemplateRoot);
+        Assert.Equal([GenCommand.NoGeneratorsSelected], outcome.LoadErrors);
+    }
+
     [Fact]
     public void No_spec_file_leaves_behaviour_unchanged()
     {

server/csharp/MetaObjects.Cli/GenCommand.cs

@@ -46,8 +46,9 @@ public sealed record Outcome(IReadOnlyList<string> LoadErrors, CodegenRunner.Run
 
     /// <summary>
     /// Run codegen selecting generators by stable name. There is no default suite:
-    /// a null or empty <paramref name="generatorNames"/> generates nothing and reports
-    /// <see cref="NoGeneratorsSelected"/> — ADR-0034 Amendment 2 made codegen opt-in.
+    /// a null or empty <paramref name="generatorNames"/> with no template spec either
+    /// generates nothing and reports <see cref="NoGeneratorsSelected"/> — ADR-0034
+    /// Amendment 2 made codegen opt-in. A template spec alone is a selection.
     /// An unknown name (or a render-helper selected without a
     /// <paramref name="templateRoot"/>) surfaces as a load-style error in the
     /// returned <see cref="Outcome"/> rather than throwing.
@@ -133,11 +134,7 @@ public static Outcome Run(
         if (loadErrors.Count > 0)
             return new Outcome(loadErrors, null);
 
-        // No default suite — see NoGeneratorsSelected. A caller that names none gets a
-        // usage error and an empty out dir, never a shape this CLI picked.
-        if (generatorNames is not { Count: > 0 })
-            return new Outcome([NoGeneratorsSelected], null);
-        var names = generatorNames;
+        var names = generatorNames ?? [];
         List<IGenerator> generators;
         try
         {
@@ -158,6 +155,13 @@ public static Outcome Run(
             return new Outcome([ex.Message], null);
         }
 
+        // No default suite — see NoGeneratorsSelected. A caller that selects nothing gets a
+        // usage error and an empty out dir, never a shape this CLI picked. A template spec
+        // (flag or the conventional template-spec.json) IS a selection, so this runs after
+        // spec resolution: it used to run before, and refused a spec-only project.
+        if (generators.Count == 0)
+            return new Outcome([NoGeneratorsSelected], null);
+
         // Build-config + CodegenRunner.Run + hash-manifest / overwrite-policy / merge, and
         // the RenderException / ArgumentException-to-clean-error translation, all live in
         // ONE place now (ADR-0034 Amendment 3 / the eject design doc's C# section):
@@ -192,7 +196,8 @@ public static IReadOnlyList<string> ListLines(string cwd) =>
             {
                 var owned = OwnedCopy.Status(cwd, e);
                 var ownedMark = owned is not null ? $" [owned — {owned}]" : "";
-                return $"  {e.Name} — {e.Description}" + (e.Note is not null ? $" [{e.Note}]" : "") + ownedMark;
+                var requires = e.Requires.Count > 0 ? $" (requires: {string.Join(", ", e.Requires)})" : "";
+                return $"  {e.Name} — {e.Description}" + requires + (e.Note is not null ? $" [{e.Note}]" : "") + ownedMark;
             })
             .ToList();
 }

server/csharp/MetaObjects.Cli/Program.cs

@@ -165,10 +165,22 @@ static int RunGen(string[] rest)
     // branches now build a LoadResult up front and share the single
     // GenCommand.Run(LoadResult, ...) overload, exactly as VerifyCommand.LoadMetadata
     // already does.
+    // Advisory, before the run: a generator selected without the ones its output
+    // references still generates, but the result will not compile.
+    if (generatorNames is { Length: > 0 } selectedNames)
+        foreach (var w in GeneratorRegistry.UnsatisfiedRequires(selectedNames))
+            Console.Error.WriteLine($"warning: {w}");
+
     var load = resolvedMeta.Load();
     var outcome = GenCommand.Run(
         load, outDir, ns, emitAbstractShapes, generatorNames, templateRoot, templateSpecPath, projectRoot,
         columnNaming, baseline);
+    if (outcome.LoadErrors is [GenCommand.NoGeneratorsSelected])
+    {
+        // A usage error, not a load failure: say so, and exit 2 as Python does.
+        Console.Error.WriteLine($"error: {GenCommand.NoGeneratorsSelected}");
+        return 2;
+    }
     if (!outcome.Ok)
     {
         foreach (var e in outcome.LoadErrors) Console.Error.WriteLine($"  load error: {e}");

server/csharp/MetaObjects.Cli/VerifyCommand.cs

@@ -258,22 +258,7 @@ private static Codegen.CodegenDrift.Result RunCodegenDrift(Options opts)
                         string.Join("; ", load.Errors.Select(e => e.Code + ": " + e.Message)) + ").",
             };
 
-        // `verify --codegen` re-runs the SELECTION and compares. With no default suite
-        // there is nothing to compare against, so it says so rather than silently
-        // checking nine artifacts this project never generates — which would convict
-        // every one of them as missing.
-        if (opts.Generators is not { Count: > 0 })
-            return new Codegen.CodegenDrift.Result
-            {
-                Clean = true,
-                Lines =
-                [
-                    "verify --codegen: no generators selected, so there is no generated " +
-                    "output to check. Pass --generators <a,b,c> (dotnet meta gen --list " +
-                    "is the catalog).",
-                ],
-            };
-        var names = opts.Generators;
+        var names = opts.Generators ?? [];
         IReadOnlyList<IGenerator> generators;
         try
         {
@@ -302,6 +287,23 @@ private static Codegen.CodegenDrift.Result RunCodegenDrift(Options opts)
             return new Codegen.CodegenDrift.Result { Clean = false, Error = $"verify --codegen: {ex.Message}" };
         }
 
+        // `verify --codegen` re-runs the SELECTION and compares. With no default suite and
+        // nothing selected there is nothing to compare against, so it says so rather than
+        // convicting every committed file as missing. A discovered template-spec.json IS a
+        // selection: this check used to run before discovery, so a project generating only
+        // from a spec passed verify without anything being checked.
+        if (generators.Count == 0)
+            return new Codegen.CodegenDrift.Result
+            {
+                Clean = true,
+                Lines =
+                [
+                    "verify --codegen: no generators selected, so there is no generated " +
+                    "output to check. Pass --generators <a,b,c> (dotnet meta gen --list " +
+                    "is the catalog).",
+                ],
+            };
+
         // The C# namespace is embedded in every generated file (`namespace {ns};`).
         // If the user did NOT pass --namespace, infer it from the committed output so
         // the regen matches output produced with any namespace (otherwise every file

server/csharp/MetaObjects.Codegen.Tests/GeneratorRegistryTests.cs

@@ -104,4 +104,34 @@ public void Render_helper_respects_supplied_template_root()
         }
         finally { Directory.Delete(root, recursive: true); }
     }
+
+    // A generator whose output imports another generator's output declares it, and
+    // `gen` warns when the dependency is not selected (advisory: an adopter may keep a
+    // hand-written file at that path). Mirrors TS warnUnsatisfiedRequires and Python's
+    // unsatisfied_requires. Before this, `--generators entity,routes` emitted routes that
+    // reference <Entity>FilterAllowlist and AppDbContext and did not compile.
+    [Fact]
+    public void Routes_declares_the_modules_its_output_references()
+    {
+        Assert.Equal(["entity", "db-context", "filter-allowlist"], GeneratorRegistry.Get("routes")!.Requires);
+        Assert.Equal(["entity"], GeneratorRegistry.Get("db-context")!.Requires);
+        foreach (var name in new[] { "output-parser", "extractor", "render-helper" })
+            Assert.Equal(["entity"], GeneratorRegistry.Get(name)!.Requires);
+        Assert.Empty(GeneratorRegistry.Get("entity")!.Requires);
+    }
+
+    [Fact]
+    public void UnsatisfiedRequires_warns_once_per_generator_naming_what_is_missing()
+    {
+        var warnings = GeneratorRegistry.UnsatisfiedRequires(["entity", "routes"]);
+        var w = Assert.Single(warnings);
+        Assert.StartsWith("\"routes\" is selected but \"db-context\", \"filter-allowlist\" are not.", w);
+    }
+
+    [Fact]
+    public void UnsatisfiedRequires_is_silent_when_every_dependency_is_selected()
+    {
+        Assert.Empty(GeneratorRegistry.UnsatisfiedRequires(
+            ["entity", "db-context", "filter-allowlist", "routes", "names"]));
+    }
 }

server/csharp/MetaObjects.Codegen/GeneratorRegistry.cs

@@ -100,6 +100,13 @@ public sealed record GeneratorRegistryEntry
     /// its own to own — every other Native entry names its file here.
     /// </summary>
     public string? SourceFileName { get; init; }
+    /// <summary>
+    /// Stable names of the generators whose output this one's output references. A run
+    /// that selects this entry without them gets a warning from <c>gen</c> (see
+    /// <see cref="GeneratorRegistry.UnsatisfiedRequires"/>) and <c>--list</c> shows them.
+    /// Advisory, never an error: an adopter may keep a hand-written file at that path.
+    /// </summary>
+    public IReadOnlyList<string> Requires { get; init; } = [];
 }
 
 /// <summary>
@@ -147,6 +154,8 @@ private static IGenerator RenderHelper(GeneratorBuildContext ctx) =>
                 Layer = GeneratorLayer.Persistence,
                 Factory = _ => new DbContextGenerator(),
                 SourceFileName = "DbContextGenerator.cs",
+                // DbSet<Entity> for every entity class EntityGenerator emits.
+                Requires = ["entity"],
             },
             ["routes"] = new()
             {
@@ -156,6 +165,9 @@ private static IGenerator RenderHelper(GeneratorBuildContext ctx) =>
                 Layer = GeneratorLayer.Api,
                 Factory = _ => new RoutesGenerator(),
                 SourceFileName = "RoutesGenerator.cs",
+                // The handlers take AppDbContext, read <Entity>FilterAllowlist and bind the
+                // entity classes; without any of the three the output does not compile.
+                Requires = ["entity", "db-context", "filter-allowlist"],
             },
             ["output-parser"] = new()
             {
@@ -166,6 +178,8 @@ private static IGenerator RenderHelper(GeneratorBuildContext ctx) =>
                 Factory = _ => new OutputParserGenerator(),
                 Note = "Needs `entity` in the same run: it references each value object's own POCO (ADR-0056).",
                 SourceFileName = "OutputParserGenerator.cs",
+                // ADR-0056: the value object's own POCO, which EntityGenerator emits.
+                Requires = ["entity"],
             },
             ["extractor"] = new()
             {
@@ -176,6 +190,8 @@ private static IGenerator RenderHelper(GeneratorBuildContext ctx) =>
                 Factory = _ => new ExtractorGenerator(),
                 Note = "Needs `entity` in the same run: it references each value object's own POCO (ADR-0056).",
                 SourceFileName = "ExtractorGenerator.cs",
+                // ADR-0056: the value object's own POCO, which EntityGenerator emits.
+                Requires = ["entity"],
             },
             ["output-prompt"] = new()
             {
@@ -196,6 +212,8 @@ private static IGenerator RenderHelper(GeneratorBuildContext ctx) =>
                 Options = "template-root (required when selected)",
                 Note = "Needs `entity` in the same run: it references each value object's own POCO (ADR-0056).",
                 SourceFileName = "RenderHelperGenerator.cs",
+                // ADR-0056: the value object's own POCO, which EntityGenerator emits.
+                Requires = ["entity"],
             },
             ["filter-allowlist"] = new()
             {
@@ -271,6 +289,31 @@ public static bool IncludesNames(IReadOnlyList<string> names) =>
     /// Build the generators for the given stable names, in the order requested.
     /// Throws <see cref="ArgumentException"/> naming the first unknown id.
     /// </summary>
+    /// <summary>
+    /// One warning per selected generator whose <see cref="GeneratorRegistryEntry.Requires"/>
+    /// are not all selected too. Advisory, never an error. Mirrors TS
+    /// <c>warnUnsatisfiedRequires</c> and Python <c>unsatisfied_requires</c>.
+    /// </summary>
+    public static IReadOnlyList<string> UnsatisfiedRequires(IReadOnlyList<string> names)
+    {
+        var selected = new HashSet<string>(names, StringComparer.Ordinal);
+        var warnings = new List<string>();
+        foreach (var name in names)
+        {
+            var entry = Get(name);
+            if (entry is null) continue;
+            var missing = entry.Requires.Where(d => !selected.Contains(d)).ToList();
+            if (missing.Count == 0) continue;
+            var listed = string.Join(", ", missing.Select(m => $"\"{m}\""));
+            warnings.Add(
+                $"\"{name}\" is selected but {listed} {(missing.Count == 1 ? "is" : "are")} not. " +
+                $"The code \"{name}\" emits references what {listed} would have emitted, so it " +
+                $"will not compile. Add {listed} to --generators, or keep your own hand-written " +
+                "files at those paths.");
+        }
+        return warnings;
+    }
+
     public static IReadOnlyList<IGenerator> Resolve(IEnumerable<string> names, GeneratorBuildContext? ctx = null)
     {
         var build = ctx ?? new GeneratorBuildContext();

server/python/src/metaobjects/cli.py

@@ -1069,11 +1069,6 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             for msg in gen_errors:
                 print(f"  {msg}", file=sys.stderr)
             return 1
-    else:
-        # Codegen is opt-in: refuse here, at the door, rather than letting the run reach
-        # the generator loop and fail with an empty out dir half-created.
-        print(f"error: {NO_GENERATORS_SELECTED}", file=sys.stderr)
-        return 2
 
     # SP-1: declarative Mustache generators from a JSON template-spec. Their output
     # is format-agnostic (text/markdown/csv/json/xml/html), so they run as a SECOND,
@@ -1088,6 +1083,14 @@ def _cmd_gen(args: argparse.Namespace) -> int:
         print(spec_err, file=sys.stderr)
         return 1
 
+    # Codegen is opt-in: refuse at the door when nothing is selected, rather than letting
+    # the run reach the generator loop and fail with an empty out dir half-created. A
+    # template spec IS a selection (flag or the conventional template-spec.json), so a
+    # project that generates only from one is not refused; verify already agreed.
+    if not generators and not spec_gens:
+        print(f"error: {NO_GENERATORS_SELECTED}", file=sys.stderr)
+        return 2
+
     entities = _parse_entities(getattr(args, "entities", None))
     providers, providers_ok = _providers_from_args(args)
     if not providers_ok:
@@ -1112,7 +1115,7 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             root, args.out, generators, entities,
             gen_state_dir=gen_state, column_naming=column_naming,
             project_root=gen_project_root, baseline=baseline, refused_out=refused,
-        )
+        ) if generators else []
     except ValueError as exc:
         # A generator refused the model — a run_gen output collision, or
         # `render-helper`'s build-time drift gate. The targets path below has caught

server/python/tests/codegen/test_cli.py

@@ -199,6 +199,24 @@ def test_gen_auto_discovers_template_spec(tmp_path: Path) -> None:
     assert (out / "_model.txt").exists()
 
 
+def test_gen_with_only_a_template_spec_is_not_refused(tmp_path: Path) -> None:
+    """A template spec is a selection. A project that generates only from one used to be
+    refused with "no generators selected", while verify already honoured it."""
+    root = _spec_project(tmp_path)
+    out = root / "out"
+    rc = main(["gen", str(root / "meta"), "--out", str(out), "--templates", str(root / "templates")])
+    assert rc == 0
+    assert (out / "Product.txt").exists()
+    assert not (out / "__init__.py").exists(), "no Python suite ran, so no package init"
+
+
+def test_gen_with_neither_generators_nor_spec_is_refused(tmp_path: Path, capsys) -> None:
+    root = _spec_project(tmp_path, spec_name=None)
+    rc = main(["gen", str(root / "meta"), "--out", str(root / "out")])
+    assert rc == 2
+    assert "no generators selected" in capsys.readouterr().err
+
+
 def test_gen_without_spec_file_emits_no_template_output(tmp_path: Path) -> None:
     """No spec file ⇒ today's behaviour exactly: the default suite only."""
     root = _spec_project(tmp_path, spec_name=None)