fix(codegen-ts): byte-identical duplicate emissions collapse instead of failing the build (#266)

A root-level abstract field.enum makes EVERY entityFile() instance emit the shared
enums.ts at its target root -- the module is rendered from the whole loaded root,
not from the instance's filtered subset. A config running more than one entityFile()
against one target (the normal way to split a model across generated areas) therefore
died on `Output path collision: enums.ts emitted by both "entity-file" and
"entity-file"` -- an emission colliding with a byte-identical copy of itself.

That made shared enums unusable in any multi-entityFile config, and the workaround
distorted the model: the closed set ends up "owned" by whichever field happened to be
written first, with every other usage inheriting from that field rather than from a
named shared concept.

The runner now keeps the first of two byte-identical emissions at the same path and
moves on. Differing content is STILL a hard error -- there the result would depend on
generator order, which is exactly the ambiguity the guard exists to catch. Existing
single-entityFile output is byte-identical.

Tests: the reported repro end-to-end (two filtered entityFile() instances + a shared
abstract enum in one target, watched failing against the unfixed runner first) plus a
runner unit case; the pre-existing differing-content collision test is unchanged and
still throws. codegen-ts 1035 pass, cli 416 pass, workspace build + typecheck green.

Also documents the Java meta:verify per-unique-outputDir fix (eed4a6b) in CHANGELOG.

Author: dmealing

CHANGELOG.md

@@ -7,7 +7,36 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
-**npm-only** — `metadata` + `codegen-ts`; PyPI / NuGet / Maven Central unchanged.
+**npm** — `metadata` + `codegen-ts`; **Maven Central** — `maven-plugin`; PyPI / NuGet
+unchanged.
+
+### Fixed — a shared `enums.ts` no longer collides across `entityFile()` instances (#266)
+
+Declaring a root-level abstract `field.enum` made **every** `entityFile()` instance emit
+the shared `enums.ts` at its target root — the module is rendered from the whole loaded
+root, not from the instance's filtered subset — so a config running more than one
+`entityFile()` against one target (the normal way to split a model across generated
+areas) failed the build with `Output path collision: enums.ts emitted by both
+"entity-file" and "entity-file"`: an emission colliding with a byte-identical copy of
+itself. Shared enums were therefore unusable in any multi-`entityFile` config, and the
+only workaround distorted the model (declare the enum inline on an arbitrary "owner"
+field, every other field `extends` it).
+
+The runner now collapses byte-identical duplicate emissions to one file. Content that
+genuinely **differs** at the same path is still a hard error — there the result would
+depend on generator order, which is the ambiguity the guard exists to catch. Existing
+single-`entityFile` output is byte-identical.
+
+### Fixed — `mvn meta:verify` diffs per unique `outputDir`, not per generator
+
+`MetaDataVerifyMojo`'s codegen mode minted a temp output dir per `<generator>` and
+compared each against the shared committed tree, so two file-emitting generators
+configured with the same `outputDir` each saw only their own half of it and reported the
+other's committed files as `[stale-in-repo]` — permanent, unfixable false drift. The temp
+dir is now minted per unique `outputDir` (normalized absolute path) and compared once per
+output dir over the union of every generator writing there, matching the TypeScript
+`computeCodegenDrift` and the Python `verify --codegen` (#267) semantics. Byte-identical
+for the idiomatic one-`outputDir`-per-generator pom.
 
 ### Fixed — a reference to a non-`object` top-level node now resolves (#194)
 

CLAUDE.md

@@ -306,9 +306,12 @@ README, "Multiple output targets".
 
 The runner `runGen()` (1) loads metadata, (2) resolves targets + derives the
 entity-module target, (3) precomputes shared render state once, (4) runs each
-generator with a per-target `RenderContext`, (5) errors on duplicate full output
-paths, unknown target, missing `importBase` for cross-target imports, or any
-generator throw, (6) writes each file under its target's `outDir` (overwriting only
+generator with a per-target `RenderContext`, (5) errors on *conflicting* duplicate
+full output paths — two emissions of the same path whose CONTENT differs, where the
+result would depend on generator order — while byte-identical duplicates collapse to
+one file (#266: a shared artifact rendered from the whole loaded root, like the shared
+`enums.ts`, is emitted by every `entityFile()` instance); also errors on an unknown
+target, missing `importBase` for cross-target imports, or any generator throw, (6) writes each file under its target's `outDir` (overwriting only
 files carrying the `@generated` header; refusing others).
 
 ### Filter syntax + sort (Project D)

server/typescript/packages/codegen-ts/src/runner.ts

@@ -319,6 +319,15 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       const fullPath = join(writeOutDir, file.path);
       const collision = emitted.find((prev) => prev.fullPath === fullPath);
       if (collision) {
+        // #266 — identical bytes at the same path are not a conflict: either
+        // emission produces exactly the same file, so keep the first and move on.
+        // This is what makes a SHARED artifact rendered from the whole loaded root
+        // (the shared `enums.ts`, emitted by every entityFile() instance) work in a
+        // config that runs more than one instance against one target — previously
+        // the build failed on an emission colliding with a copy of itself. Content
+        // that genuinely DIFFERS is still a hard error: the outcome would depend on
+        // generator order, which is exactly the ambiguity this guard exists to catch.
+        if (collision.content === file.content) continue;
         throw new Error(
           `Output path collision: "${fullPath}" emitted by both ` +
           `"${collision.generatedBy}" and "${generator.name}". ` +

server/typescript/packages/codegen-ts/test/runner.test.ts

@@ -84,6 +84,33 @@ describe("runGen — error paths", () => {
     })).rejects.toThrow(/Output path collision.*Post\.ts".*alpha.*beta/);
   });
 
+  // #266 — a shared artifact rendered from the whole loaded root (the shared
+  // `enums.ts`) is emitted by EVERY entityFile() instance, so a config running more
+  // than one instance against one target collided an emission with a byte-identical
+  // copy of itself. Identical bytes at the same path are not a conflict: whichever
+  // "wins" produces the same file, so emit once instead of failing the build.
+  test("byte-identical duplicate emissions collapse to one file instead of throwing", async () => {
+    const loader = new MetaDataLoader();
+    const { root } = await loader.load([new FileSource(FIXTURE)]);
+
+    const shared = "// shared artifact\n";
+    const a: Generator = { name: "alpha", generate: oncePerRun(() => ({ path: "enums.ts", content: shared })) };
+    const b: Generator = { name: "beta",  generate: oncePerRun(() => ({ path: "enums.ts", content: shared })) };
+
+    const result = await runGen({
+      config: defineConfig({
+        outDir: tmp, extStyle: "none", dbImport: "../db", dialect: "sqlite",
+        generators: [a, b],
+      }),
+      metadata: root,
+    });
+
+    const enumFiles = result.files.filter((f) => f.path.endsWith("enums.ts"));
+    expect(enumFiles.length).toBe(1);
+    expect(readFileSync(join(tmp, "enums.ts"), "utf-8")).toBe(shared);
+    expect(result.warnings).toEqual([]);
+  });
+
   test("generator throws -> error prefixed with [generator.name]", async () => {
     const loader = new MetaDataLoader();
     const { root } = await loader.load([new FileSource(FIXTURE)]);

server/typescript/packages/codegen-ts/test/templates/enum-shared-provided.test.ts

@@ -118,6 +118,50 @@ describe("FR-019 enum-shared-materialized-once", () => {
   });
 });
 
+describe("#266 shared enums across multiple entityFile() instances", () => {
+  // The reported repro: splitting a model across generated areas is done by running
+  // several entityFile() instances against one target with disjoint filters. Every
+  // instance renders the shared enums module from the WHOLE loaded root, so each
+  // emitted a byte-identical `enums.ts` and the runner failed the build on the
+  // collision — making a root-level abstract field.enum unusable in any such config.
+  test("two filtered entityFile() instances in one target emit the shared enums module once", async () => {
+    const root = await loadRoot(sharedModel());
+    const tmp = mkdtempSync(join(tmpdir(), "enum-266-"));
+    try {
+      const result = await runGen({
+        config: defineConfig({
+          outDir: tmp,
+          extStyle: "none",
+          dbImport: "~/db",
+          dialect: "sqlite",
+          generators: [
+            entityFile({ filter: (e) => e.name === "Order" }),
+            entityFile({ filter: (e) => e.name === "Article" }),
+          ],
+        }),
+        metadata: root,
+      });
+
+      // Both areas generated, and the shared module was emitted exactly once.
+      expect(existsSync(join(tmp, "Order.ts"))).toBe(true);
+      expect(existsSync(join(tmp, "Article.ts"))).toBe(true);
+      expect(result.files.filter((f) => f.path.endsWith("enums.ts")).length).toBe(1);
+
+      // Its content is the full shared declaration — rendered from the whole root,
+      // NOT narrowed to one instance's filtered subset.
+      const enums = readFileSync(join(tmp, "enums.ts"), "utf-8");
+      expect(enums).toContain('export type Status = "DRAFT" | "PUBLISHED" | "ARCHIVED";');
+
+      // Both entity files reference the one shared module.
+      for (const name of ["Order.ts", "Article.ts"]) {
+        expect(readFileSync(join(tmp, name), "utf-8")).toContain('from "./enums"');
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("FR-019 enum-provided", () => {
   test("@provided: true emits NO type anywhere; entities import from the configured module", async () => {
     const root = await loadRoot(sharedModel({ provided: true }));