feat(codegen-ts): add perPackage scope helper + perModel (alias oncePerRun)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuZWKnWzYGVnESijL7uuky

Author: dmealing

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

@@ -73,7 +73,9 @@ export function perEntity(
   };
 }
 
-/** Called once with all matching entities. Use for barrels and cross-entity files. */
+/** Called once with all matching entities. Use for barrels and cross-entity files.
+ *  @deprecated Use {@link perModel} — "run" is ambiguous under multi-target output
+ *  (it reads as "per target"); `perModel` names the data scope (the whole model). */
 export function oncePerRun(
   fn: (entities: MetaObject[], ctx: GenContext) =>
     | EmittedFile
@@ -86,3 +88,35 @@ export function oncePerRun(
     return Array.isArray(result) ? result : [result];
   };
 }
+
+/** App-scope convenience — run `fn` once over the whole model (all matched
+ *  entities). The canonical name for the one-shot scope (replaces `oncePerRun`). */
+export const perModel = oncePerRun;
+
+/** One-file-per-package convenience. Groups matched entities by `package`, runs
+ *  `fn` once per package — packages ascending, entities keeping `ctx.entities`
+ *  order. The package scope from codegen-concepts §10 (object + model already
+ *  exist via perEntity + perModel). */
+export function perPackage(
+  fn: (pkg: string, entities: MetaObject[], ctx: GenContext) =>
+    | EmittedFile
+    | EmittedFile[]
+    | Promise<EmittedFile | EmittedFile[]>,
+): (ctx: GenContext) => Promise<EmittedFile[]> {
+  return async (ctx) => {
+    const matched = ctx.entities.filter(ctx.matches);
+    const byPkg = new Map<string, MetaObject[]>();
+    for (const e of matched) {
+      const pkg = e.package ?? "";
+      let bucket = byPkg.get(pkg);
+      if (bucket === undefined) { bucket = []; byPkg.set(pkg, bucket); }
+      bucket.push(e);
+    }
+    const out: EmittedFile[] = [];
+    for (const pkg of [...byPkg.keys()].sort()) {
+      const r = await fn(pkg, byPkg.get(pkg)!, ctx);
+      out.push(...(Array.isArray(r) ? r : [r]));
+    }
+    return out;
+  };
+}

server/typescript/packages/codegen-ts/test/template-codegen/scope-helpers.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "bun:test";
+import { perPackage, perModel, oncePerRun } from "../../src/generator.js";
+import type { GenContext, EmittedFile } from "../../src/generator.js";
+import { MetaDataLoader } from "@metaobjectsdev/metadata";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { resolve } from "node:path";
+
+const FIXTURE = resolve(import.meta.dir, "../fixtures/single-entity.json");
+
+async function ctxFor(path: string): Promise<GenContext> {
+  const loader = new MetaDataLoader();
+  const res = await loader.load([new FileSource(path)]);
+  expect(res.errors).toEqual([]);
+  const entities = res.root.objects();
+  return {
+    entities, loadedRoot: res.root, matches: () => true,
+    config: {} as GenContext["config"], warn: () => {},
+  };
+}
+
+describe("perPackage", () => {
+  test("runs fn once per distinct package, packages sorted", async () => {
+    const ctx = await ctxFor(FIXTURE);
+    const seen: string[] = [];
+    const gen = perPackage((pkg, ents) => {
+      seen.push(pkg);
+      return { path: `${pkg || "_"}/out.txt`, content: `${ents.length}` } as EmittedFile;
+    });
+    const files = await gen(ctx);
+    const pkgs = [...new Set(ctx.entities.map((e) => e.package ?? ""))].sort();
+    expect(seen).toEqual(pkgs);
+    expect(files.length).toBe(pkgs.length);
+  });
+});
+
+describe("perModel / oncePerRun alias", () => {
+  test("perModel runs fn once with all matched entities", async () => {
+    const ctx = await ctxFor(FIXTURE);
+    let calls = 0;
+    const gen = perModel((ents) => { calls++; return { path: "all.txt", content: `${ents.length}` }; });
+    const files = await gen(ctx);
+    expect(calls).toBe(1);
+    expect(files.length).toBe(1);
+  });
+  test("oncePerRun is the same function as perModel (alias)", () => {
+    expect(oncePerRun).toBe(perModel);
+  });
+});