feat(codegen-ts): emitAbstractShapes config knob (cross-port parity)

Adds the emitAbstractShapes option (default true) to MetaobjectsGenConfig +
NormalizedMetaobjectsGenConfig, threaded through normalizeConfig and
makeRenderContext into RenderContext. When false, the entity-file generator
emits no file for abstract entities (their shape is the only thing they emit;
instance/write generators already skip abstract unconditionally via
instance-artifacts). Default true preserves existing behavior. Completes the
optional TS parity (Unit 5) for the cross-port abstract-codegen knob.

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

Author: dmealing

server/typescript/packages/codegen-ts/src/generators/entity-file.ts

@@ -3,6 +3,7 @@ import { perEntity, type Generator, type GeneratorFactory } from "../generator.j
 import { renderEntityFile } from "../templates/entity-file.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
+import { isAbstract } from "../instance-artifacts.js";
 
 export interface EntityFileOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -33,6 +34,12 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator
       if (!ctx.renderContext) {
         throw new Error("entity-file: renderContext is required (provided by runGen)");
       }
+      // Abstract entities contribute shape only. When emitAbstractShapes is off
+      // (cross-port knob; default on) the entity-file generator emits nothing for
+      // them. Instance/write generators skip abstract unconditionally elsewhere.
+      if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
+        return [];
+      }
       return {
         path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
         content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),

server/typescript/packages/codegen-ts/src/metaobjects-config.ts

@@ -37,6 +37,15 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
   columnNamingStrategy?: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix?: string;
+  /**
+   * Whether abstract entities (`@isAbstract: true`) emit their shape artifact
+   * (the type-only interface / value-object file from the entity-file
+   * generator). Defaults to `true`. Instance/write artifacts (forms, CRUD/read
+   * hooks, grids) are NEVER emitted for abstract entities regardless of this
+   * flag — that invariant lives in `instance-artifacts.ts`. This knob only
+   * governs the shape, mirroring the cross-port `emitAbstractShapes` option.
+   */
+  emitAbstractShapes?: boolean;
   /** Named output destinations. Generators reference one via `target`. */
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
@@ -57,6 +66,7 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
 export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfig, "targets"> {
   columnNamingStrategy: ColumnNamingStrategy;
   apiPrefix: string;
+  emitAbstractShapes: boolean;
   outputLayout: OutputLayout;
   targets: Record<string, ResolvedTarget>;
 }
@@ -98,6 +108,7 @@ export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobj
     ...config,
     columnNamingStrategy: config.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY,
     apiPrefix: config.apiPrefix ?? "",
+    emitAbstractShapes: config.emitAbstractShapes ?? true,
     outputLayout: config.outputLayout ?? "flat",
     targets: resolveTargets(config),
   };

server/typescript/packages/codegen-ts/src/render-context.ts

@@ -39,6 +39,8 @@ export interface RenderContext {
   columnNamingStrategy: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix: string;
+  /** Whether abstract entities emit their shape artifact (type-only interface / value-object file). Defaults to true. Instance/write artifacts are never emitted for abstract entities regardless. */
+  emitAbstractShapes: boolean;
   /** Output layout mode: "flat" (default) — all files in outDir; "package" — sub-paths from entity metadata package. */
   outputLayout: OutputLayout;
   /** The target THIS generator emits to (drives path layout + same-target imports). */
@@ -53,11 +55,12 @@ export interface RenderContext {
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
   apiPrefix?: string;
+  emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
   packageOf?: Map<string, string | undefined>;
   selfTarget?: ResolvedTarget;
@@ -85,6 +88,7 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     omImport: opts.omImport ?? "../index",
     columnNamingStrategy: opts.columnNamingStrategy ?? "snake_case",
     apiPrefix: opts.apiPrefix ?? "",
+    emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
     packageOf: opts.packageOf ?? new Map(),
     selfTarget: defaultTarget,

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

@@ -155,6 +155,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       extStyle: config.extStyle,
       columnNamingStrategy: config.columnNamingStrategy,
       apiPrefix: config.apiPrefix,
+      emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,
       pkMap,
       relationMap,

server/typescript/packages/codegen-ts/test/generators/entity-file.test.ts

@@ -6,7 +6,7 @@ import { buildPkMap } from "../../src/pk-resolver.js";
 import { buildRelationMap } from "../../src/relation-resolver.js";
 import { makeRenderContext } from "../../src/render-context.js";
 import type { GenContext } from "../../src/generator.js";
-import { MetaDataLoader } from "@metaobjectsdev/metadata";
+import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
 import { FileSource } from "@metaobjectsdev/metadata/core";
 
 const FIXTURE = resolve(import.meta.dir, "..", "fixtures", "single-entity.json");
@@ -101,3 +101,66 @@ describe("entityFile() factory", () => {
     expect(files).toEqual([]);
   });
 });
+
+describe("entityFile() — emitAbstractShapes knob", () => {
+  // Abstract base (sourceless → shape is a value-object interface) + concrete subclass.
+  const MODEL = JSON.stringify({
+    "metadata.root": {
+      package: "acme",
+      children: [
+        {
+          "object.entity": {
+            name: "Base",
+            abstract: true,
+            children: [
+              { "field.int": { name: "id" } },
+              { "field.string": { name: "name" } },
+              { "identity.primary": { "@fields": "id" } },
+            ],
+          },
+        },
+        {
+          "object.entity": {
+            name: "Widget",
+            extends: "Base",
+            children: [
+              { "source.rdb": { "@table": "widgets" } },
+              { "field.string": { name: "sku" } },
+            ],
+          },
+        },
+      ],
+    },
+  });
+
+  async function runWith(emitAbstractShapes: boolean) {
+    const { root, errors } = await new MetaDataLoader().load([new InMemoryStringSource(MODEL)]);
+    if (errors.length > 0) throw new Error(errors.map((e: { message: string }) => e.message).join("\n"));
+    const entities = root.objects();
+    const renderContext = makeRenderContext({
+      dialect: "sqlite", loadedRoot: root, outDir: "/tmp",
+      dbImport: "../db", extStyle: "none", emitAbstractShapes,
+      pkMap: buildPkMap(root), relationMap: buildRelationMap(root),
+    });
+    const ctx: GenContext = {
+      entities, loadedRoot: root,
+      matches: () => true,
+      config: { outDir: "/tmp", extStyle: "none", dbImport: "../db", dialect: "sqlite" },
+      renderContext,
+      warn: () => {},
+    };
+    return (await entityFile().generate(ctx)).map((f) => f.path);
+  }
+
+  test("default (on): abstract entity emits its shape file", async () => {
+    const paths = await runWith(true);
+    expect(paths).toContain("Base.ts");
+    expect(paths).toContain("Widget.ts");
+  });
+
+  test("off: abstract entity emits no file; concrete still emits", async () => {
+    const paths = await runWith(false);
+    expect(paths).not.toContain("Base.ts");
+    expect(paths).toContain("Widget.ts");
+  });
+});