feat(java-render): TemplateGenerator factory + EmittedFile + walk record

Java port of the rc.12 cross-port factory. Lives in the render module
(where Provider + Renderer + RenderRequest already live), not in
codegen-mustache — the render module has no metadata dependency, so
the factory takes a generic <R> root type that the walk callback knows
the actual type of. This keeps the render module's dependency graph
unchanged.

Does NOT implement the legacy com.metaobjects.generator.Generator
interface — that interface has void execute(MetaDataLoader) which
doesn't fit the declarative 'return List<EmittedFile>' cross-port
shape. Adopters who want Maven plugin integration can wrap this in
their own legacy-Generator-conformant glue. Maven plugin surface is
a follow-up.

4 unit tests cover per-entity, aggregator, and format-driven escaping
patterns (text vs html). Cross-port byte equivalence verified via the
conformance adapter (next commit).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dmealing

server/java/render/src/main/java/com/metaobjects/render/templategen/EmittedFile.java

@@ -0,0 +1,12 @@
+package com.metaobjects.render.templategen;
+
+/**
+ * One emitted file produced by {@link TemplateGenerator}.
+ * Cross-port mirror of TS {@code EmittedFile}, Python {@code EmittedFile},
+ * C# {@code record EmittedFile(string Path, string Content)}.
+ *
+ * <p>This is NOT the legacy {@code com.metaobjects.generator.Generator} contract
+ * (which writes via {@code execute()} side-effects); this record exists because
+ * the cross-port template-generator factory returns its files declaratively.
+ */
+public record EmittedFile(String path, String content) {}

server/java/render/src/main/java/com/metaobjects/render/templategen/TemplateGenerator.java

@@ -0,0 +1,73 @@
+package com.metaobjects.render.templategen;
+
+import com.metaobjects.render.Provider;
+import com.metaobjects.render.RenderRequest;
+import com.metaobjects.render.Renderer;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.Function;
+
+/**
+ * Java port of the rc.12 cross-port {@code templateGenerator()} factory.
+ *
+ * <p>Walks a caller-supplied root via the walk callback, renders the shared
+ * Mustache template via {@link Renderer#render}, and returns
+ * {@code List<EmittedFile>} — one entry per walk result.
+ *
+ * <p>The root type is generic ({@code <R>}) so this factory does not pull
+ * the metadata package into the render module's dependency graph — the
+ * walk callback knows the actual root type at the call site (typically
+ * {@code com.metaobjects.MetaRoot}, but conformance tests can use any
+ * test-shape).
+ *
+ * <p>Design: {@code spec/design-docs/2026-05-28-cross-port-template-generator.md}.
+ * Cross-port byte-equivalence verified via the shared fixture corpus at
+ * {@code fixtures/render-conformance/template-generator/}.
+ *
+ * <p>Note: this factory does NOT implement the legacy
+ * {@code com.metaobjects.generator.Generator} interface — that interface
+ * has {@code void execute(MetaDataLoader)} which doesn't fit the
+ * declarative "return files" cross-port shape. Adopters who want Maven
+ * plugin integration can wrap this factory in their own
+ * legacy-Generator-conformant glue.
+ */
+public final class TemplateGenerator {
+
+    private TemplateGenerator() {}
+
+    /** Convenience static factory mirroring TS/Python/C# signatures. */
+    public static <R> List<EmittedFile> generate(
+            String name,
+            String template,
+            Function<R, List<TemplateWalkResult>> walk,
+            Provider provider,
+            String format,
+            R root) {
+        Renderer renderer = new Renderer();
+        List<EmittedFile> out = new ArrayList<>();
+        for (TemplateWalkResult entry : walk.apply(root)) {
+            RenderRequest req = new RenderRequest(
+                /* template */ null,
+                /* ref */ template,
+                /* payload */ entry.data(),
+                /* provider */ provider,
+                /* format */ format,
+                /* verify */ null,
+                /* maxChars */ null);
+            String content = renderer.render(req);
+            out.add(new EmittedFile(entry.outputPath(), content));
+        }
+        return out;
+    }
+
+    /** Overload defaulting format to "text". */
+    public static <R> List<EmittedFile> generate(
+            String name,
+            String template,
+            Function<R, List<TemplateWalkResult>> walk,
+            Provider provider,
+            R root) {
+        return generate(name, template, walk, provider, "text", root);
+    }
+}

server/java/render/src/main/java/com/metaobjects/render/templategen/TemplateWalkResult.java

@@ -0,0 +1,7 @@
+package com.metaobjects.render.templategen;
+
+/**
+ * One walk entry: a payload + the output path the rendered template should
+ * be emitted to (relative to whatever output root the caller chooses).
+ */
+public record TemplateWalkResult(Object data, String outputPath) {}

server/java/render/src/test/java/com/metaobjects/render/templategen/TemplateGeneratorTest.java

@@ -0,0 +1,104 @@
+package com.metaobjects.render.templategen;
+
+import com.metaobjects.render.InMemoryProvider;
+import com.metaobjects.render.Provider;
+import org.junit.Test;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * Unit tests for the Java TemplateGenerator factory.
+ * Mirrors C# TemplateGeneratorTests, Python test_template_generator.py,
+ * TS template-generator.test.ts.
+ *
+ * <p>These tests use plain Map-based "root" payloads instead of
+ * com.metaobjects.MetaRoot because (a) the factory is generic over root
+ * type, and (b) the render module doesn't depend on the metadata module.
+ * The cross-port conformance harness in TemplateGeneratorConformanceTest
+ * uses the same approach.
+ */
+public class TemplateGeneratorTest {
+
+    private static Provider provider(Map<String, String> map) {
+        return new InMemoryProvider(map);
+    }
+
+    @Test
+    public void perEntityWalkEmitsOneFilePerEntity() {
+        // The "root" here is a simple list of entities — mirrors what a real
+        // MetaRoot.getChildrenOfType("object") would yield, without dragging
+        // in the metadata module.
+        List<String> entityNames = List.of("Post");
+
+        List<EmittedFile> files = TemplateGenerator.generate(
+            "hello",
+            "custom/hello",
+            (List<String> names) -> names.stream()
+                .map(n -> new TemplateWalkResult(Map.of("name", n), n + ".txt"))
+                .toList(),
+            provider(Map.of("custom/hello", "Hello {{name}}!\n")),
+            entityNames);
+
+        assertEquals(1, files.size());
+        assertEquals("Post.txt", files.get(0).path());
+        assertEquals("Hello Post!\n", files.get(0).content());
+    }
+
+    @Test
+    public void aggregatorWalkEmitsSingleFileFromAllEntities() {
+        List<String> entityNames = List.of("Post", "Comment");
+
+        List<EmittedFile> files = TemplateGenerator.generate(
+            "index",
+            "custom/index",
+            (List<String> names) -> {
+                List<Map<String, String>> entities = names.stream()
+                    .map(n -> Map.of("name", n))
+                    .toList();
+                return List.of(new TemplateWalkResult(
+                    Map.of("entities", entities), "index.txt"));
+            },
+            provider(Map.of("custom/index",
+                "Entities:\n{{#entities}}- {{name}}\n{{/entities}}")),
+            entityNames);
+
+        assertEquals(1, files.size());
+        assertEquals("index.txt", files.get(0).path());
+        assertEquals("Entities:\n- Post\n- Comment\n", files.get(0).content());
+    }
+
+    @Test
+    public void formatTextDoesNotEscapeHtml() {
+        List<EmittedFile> files = TemplateGenerator.generate(
+            "raw-text",
+            "custom/raw",
+            (Object root) -> List.of(new TemplateWalkResult(
+                Map.of("snippet", "<p>hi</p>"), "out.txt")),
+            provider(Map.of("custom/raw", "{{snippet}}\n")),
+            "text",
+            new Object());
+        assertEquals("<p>hi</p>\n", files.get(0).content());
+    }
+
+    @Test
+    public void formatHtmlEscapesHtmlInPayload() {
+        List<EmittedFile> files = TemplateGenerator.generate(
+            "raw-html",
+            "custom/raw",
+            (Object root) -> List.of(new TemplateWalkResult(
+                Map.of("snippet", "<p>hi</p>"), "out.html")),
+            provider(Map.of("custom/raw", "{{snippet}}\n")),
+            "html",
+            new Object());
+        String content = files.get(0).content();
+        assertNotEquals("<p>hi</p>\n", content);
+        assertTrue("expected HTML escape in: " + content,
+            content.contains("&lt;") || content.contains("&#60;"));
+    }
+}