@workos/oagen-emitters 0.16.0 → 0.17.0

package/src/shared/union-flatten.ts

@@ -0,0 +1,201 @@
+import type { Model, Field, TypeRef, UnionType } from '@workos/oagen';
+
+/**
+ * Flatten field-level discriminated unions into a single superset model for
+ * the flat-emit languages (Go, Kotlin, Node) that have no native sum type.
+ *
+ * Background: a property like `ApiKey.owner` is a discriminated `oneOf` whose
+ * variants are inline objects — `{ type: 'organization', id }` and
+ * `{ type: 'user', id, organization_id }`. The IR represents this as a `union`
+ * TypeRef referencing two variant models (`ApiKeyOwner`, `UserApiKeyOwner`).
+ * Languages that render such a union as "the first variant" — Go's
+ * `unionResolverName`, Kotlin's `baseName` — silently drop every field that
+ * only exists on a later variant, so `organization_id` disappears for
+ * user-scoped keys. (See the SDK compat report's owner-field note.)
+ *
+ * This transform, applied only by the flat-emit emitters, merges every
+ * variant's fields into the first variant (the union's canonical model),
+ * marks any field not shared by all variants optional, widens the
+ * discriminator property to the union of its per-variant literal values, and
+ * rewrites the field to a plain model ref to that canonical model. The result
+ * is one flat struct/data class/interface that carries every variant field,
+ * with the discriminator property telling callers which variant they hold —
+ * exactly how these emitters already flatten `allOf [base, oneOf]`
+ * discriminated bases (see `enrichModelsFromSpec`).
+ *
+ * Returns a new models array; the input models are not mutated. Union-emitting
+ * languages (Python, PHP, Rust, Ruby, .NET) must NOT call this — they emit a
+ * real discriminated union and lose nothing.
+ */
+export function flattenDiscriminatedUnionFields(models: Model[]): Model[] {
+  const byName = new Map(models.map((m) => [m.name, m]));
+  // Canonical (first-variant) model name → its merged superset field list.
+  const mergedFieldsByCanonical = new Map<string, Field[]>();
+
+  /**
+   * Decide whether a union is a flat-flattenable discriminated union of inline
+   * object variants. When it is, record the merged field set for its canonical
+   * model and return that model's name; otherwise return null.
+   */
+  function planUnion(union: UnionType): string | null {
+    if (!union.discriminator) return null;
+
+    const variantNames = union.variants.map((v) => (v.kind === 'model' ? v.name : null));
+    // Require that *every* variant is a model ref (the inline-object oneOf
+    // shape). Untagged unions of primitives (e.g. AuditLogEvent actor
+    // metadata: string | number | boolean) carry no discriminator and never
+    // reach here, but guard anyway.
+    if (variantNames.length < 2 || variantNames.some((n) => n === null)) return null;
+
+    const variantModels = (variantNames as string[]).map((n) => byName.get(n));
+    // Every variant must resolve to a concrete data model — not a discriminator
+    // dispatcher (empty-field base with its own `discriminator`) and not a
+    // fieldless placeholder. This keeps event-style unions out of scope.
+    if (variantModels.some((m) => !m || (m as { discriminator?: unknown }).discriminator || m.fields.length === 0)) {
+      return null;
+    }
+
+    const canonical = (variantNames as string[])[0];
+    const merged = mergeVariantFields(variantModels as Model[], union.discriminator.property);
+
+    // The merge map is keyed by the first-variant model name. The same union
+    // referenced by several container fields re-plans to an identical merge
+    // (harmless). But two *distinct* unions that share a first variant would
+    // each want a different superset on that one model — pass 2 can apply only
+    // one, silently dropping the other's fields. Fail loudly instead; the spec
+    // must disambiguate (rename one union's leading variant).
+    const existing = mergedFieldsByCanonical.get(canonical);
+    if (existing && fieldListSignature(existing) !== fieldListSignature(merged)) {
+      throw new Error(
+        `flattenDiscriminatedUnionFields: model "${canonical}" is the first variant of two distinct ` +
+          'discriminated unions that merge to different field sets. Flattening both onto one model would ' +
+          'silently drop fields; disambiguate the variants in the spec (rename the leading variant of one union).',
+      );
+    }
+    mergedFieldsByCanonical.set(canonical, merged);
+    return canonical;
+  }
+
+  /** Rewrite a TypeRef, collapsing flattenable unions to a canonical model ref. */
+  function rewriteRef(ref: TypeRef): TypeRef {
+    switch (ref.kind) {
+      case 'union': {
+        const canonical = planUnion(ref);
+        return canonical ? { kind: 'model', name: canonical } : ref;
+      }
+      case 'nullable': {
+        // Preserve reference identity when nothing inside changed, so pass 1's
+        // `type === field.type` check doesn't flag (and rebuild) union-free fields.
+        const inner = rewriteRef(ref.inner);
+        return inner === ref.inner ? ref : { kind: 'nullable', inner };
+      }
+      case 'array': {
+        const items = rewriteRef(ref.items);
+        return items === ref.items ? ref : { kind: 'array', items };
+      }
+      default:
+        return ref;
+    }
+  }
+
+  // Pass 1: rewrite container fields, recording the merges to apply in pass 2.
+  const rewritten = models.map((model) => {
+    let changed = false;
+    const fields = model.fields.map((field) => {
+      const type = rewriteRef(field.type);
+      if (type === field.type) return field;
+      changed = true;
+      return { ...field, type };
+    });
+    return changed ? { ...model, fields } : model;
+  });
+
+  if (mergedFieldsByCanonical.size === 0) return models;
+
+  // Pass 2: replace each canonical variant model with its merged superset.
+  return rewritten.map((model) => {
+    const merged = mergedFieldsByCanonical.get(model.name);
+    return merged ? { ...model, fields: merged } : model;
+  });
+}
+
+/**
+ * Build the merged field list for a discriminated union's variant models.
+ *
+ * - A field is required only when present-and-required in *every* variant; a
+ *   field missing from some variant (e.g. the user variant's `organization_id`)
+ *   becomes optional.
+ * - The discriminator property is widened to the union of its per-variant
+ *   literal values (`'organization' | 'user'`) so it isn't pinned to the first
+ *   variant's constant. (Flat-emit type maps collapse a single-typed literal
+ *   union to a plain string, so this is a no-op for Go/Kotlin and a precise
+ *   `'organization' | 'user'` for Node.)
+ * - Field order follows the first variant, then newly-seen fields from later
+ *   variants.
+ */
+function mergeVariantFields(variants: Model[], discriminatorProp: string): Field[] {
+  const total = variants.length;
+  const order: string[] = [];
+  const defByName = new Map<string, Field>();
+  const presence = new Map<string, number>();
+  const requiredCount = new Map<string, number>();
+
+  for (const variant of variants) {
+    for (const field of variant.fields) {
+      const seen = defByName.get(field.name);
+      if (!seen) {
+        defByName.set(field.name, field);
+        order.push(field.name);
+      } else if (field.name !== discriminatorProp && !sameTypeRef(seen.type, field.type)) {
+        // Only the first-seen definition is kept, so a shared field whose type
+        // differs across variants would be merged with the wrong type for the
+        // other variants. The discriminator is exempt (it is widened below).
+        throw new Error(
+          `flattenDiscriminatedUnionFields: field "${field.name}" has conflicting types across variants ` +
+            'of a discriminated union; a flat superset model cannot represent both. Align the field type ' +
+            'across variants in the spec.',
+        );
+      }
+      presence.set(field.name, (presence.get(field.name) ?? 0) + 1);
+      if (field.required) requiredCount.set(field.name, (requiredCount.get(field.name) ?? 0) + 1);
+    }
+  }
+
+  return order.map((name) => {
+    const def = defByName.get(name)!;
+
+    if (name === discriminatorProp) {
+      const literals = dedupeLiteralTypes(
+        variants.map((v) => v.fields.find((f) => f.name === name)?.type).filter((t): t is TypeRef => t != null),
+      );
+      const type: TypeRef = literals.length > 1 ? { kind: 'union', variants: literals } : (literals[0] ?? def.type);
+      return { ...def, type, required: presence.get(name) === total };
+    }
+
+    const required = presence.get(name) === total && requiredCount.get(name) === total;
+    return required === def.required ? def : { ...def, required };
+  });
+}
+
+/** Structural equality of two TypeRefs (IR refs have a stable, deterministic shape). */
+function sameTypeRef(a: TypeRef, b: TypeRef): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Stable signature of a merged field list, used to detect canonical collisions. */
+function fieldListSignature(fields: Field[]): string {
+  return JSON.stringify(fields.map((f) => [f.name, f.required, f.type]));
+}
+
+/** Deduplicate literal TypeRefs by value, preserving first-seen order. */
+function dedupeLiteralTypes(types: TypeRef[]): TypeRef[] {
+  const seen = new Set<string>();
+  const out: TypeRef[] = [];
+  for (const t of types) {
+    const key = t.kind === 'literal' ? `lit:${String(t.value)}` : JSON.stringify(t);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+  }
+  return out;
+}

package/test/node/enums.test.ts

@@ -1,7 +1,13 @@
-import { describe, it, expect } from 'vitest';
-import type { EmitterContext, ApiSpec, Enum } from '@workos/oagen';
+import { describe, it, expect, vi } from 'vitest';
+import type { EmitterContext, ApiSpec, Enum, Model } from '@workos/oagen';
 import { defaultSdkBehavior } from '@workos/oagen';
 import { generateEnums } from '../../src/node/enums.js';
+import { nodeEmitter } from '../../src/node/index.js';
+import { emptyLiveSurface, setActiveLiveSurface } from '../../src/node/live-surface.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 const emptySpec: ApiSpec = {
   name: 'Test',
@@ -126,3 +132,234 @@ describe('generateEnums', () => {
     expect(result[0].content).toContain('/** @deprecated */');
   });
 });
+
+describe('assignEnumsToServices owned-service dependency reassignment', () => {
+  it('follows a reassigned dependency model into the owned service', () => {
+    // The enum is referenced only through `AuditLogsRetention`, whose
+    // first-reference assignment is Organizations (unemittable this run).
+    // When the owned AuditLogs service pulls the model into `audit-logs/`,
+    // the enum must follow — otherwise the model file imports an enum file
+    // that is emitted nowhere.
+    const surface = emptyLiveSurface();
+    surface.files.add('src/workos.ts'); // existing SDK
+    setActiveLiveSurface(surface);
+    try {
+      const enums: Enum[] = [
+        {
+          name: 'RetentionPeriod',
+          values: [
+            { name: 'THIRTY_DAYS', value: '30d' },
+            { name: 'NINETY_DAYS', value: '90d' },
+          ],
+        },
+      ];
+      const models = [
+        {
+          name: 'AuditLogsRetention',
+          fields: [
+            {
+              name: 'period',
+              type: { kind: 'enum' as const, name: 'RetentionPeriod', values: ['30d', '90d'] },
+              required: true,
+            },
+          ],
+        },
+      ];
+      const retentionOp = (name: string, path: string) => ({
+        name,
+        httpMethod: 'get' as const,
+        path,
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model' as const, name: 'AuditLogsRetention' },
+        errors: [],
+        injectIdempotencyKey: false,
+      });
+      const services = [
+        { name: 'Organizations', operations: [retentionOp('getRetention', '/organizations/{id}/retention')] },
+        { name: 'AuditLogs', operations: [retentionOp('getAuditLogsRetention', '/audit_logs/retention')] },
+      ];
+      const ctxOwned: EmitterContext = {
+        ...ctx,
+        spec: { ...emptySpec, enums, models, services },
+        emitterOptions: { ownedServices: ['AuditLogs'] },
+      } as EmitterContext;
+
+      const result = generateEnums(enums, ctxOwned);
+      expect(result).toHaveLength(1);
+      expect(result[0].path).toBe('src/audit-logs/interfaces/retention-period.interface.ts');
+    } finally {
+      setActiveLiveSurface(emptyLiveSurface());
+    }
+  });
+});
+
+describe('owned-service enum emission under the live-surface skip', () => {
+  function ownedDomainSpec(enums: Enum[], models: Model[]): ApiSpec {
+    return {
+      ...emptySpec,
+      enums,
+      models,
+      services: [
+        {
+          name: 'OrganizationDomains',
+          operations: [
+            {
+              name: 'getOrganizationDomain',
+              httpMethod: 'get',
+              path: '/organization_domains/{id}',
+              pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+              queryParams: [],
+              headerParams: [],
+              response: { kind: 'model', name: 'OrganizationDomain' },
+              errors: [],
+              injectIdempotencyKey: false,
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  const stateEnum: Enum = {
+    name: 'OrganizationDomainState',
+    values: [
+      { name: 'VERIFIED', value: 'verified' },
+      { name: 'PENDING', value: 'pending' },
+    ],
+  };
+  const domainModel: Model = {
+    name: 'OrganizationDomain',
+    fields: [
+      { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+      {
+        name: 'state',
+        type: { kind: 'enum', name: 'OrganizationDomainState', values: ['verified', 'pending'] },
+        required: true,
+      },
+    ],
+  };
+
+  it('still emits the union module when the name is declared in a file the owned regeneration overwrites', () => {
+    // Real instance (OrganizationDomains rebuild, service OWNED): the
+    // on-disk organization-domain.interface.ts declared the enum names, so
+    // the live-surface skip suppressed emitting the canonical modules — but
+    // that very file was simultaneously being OVERWRITTEN by the owned
+    // regeneration, leaving the names declared nowhere.
+    const surface = emptyLiveSurface();
+    surface.files.add('src/workos.ts'); // existing SDK
+    surface.files.add('src/organization-domains/interfaces/organization-domain.interface.ts');
+    surface.interfaces.set('OrganizationDomainState', {
+      filePath: 'src/organization-domains/interfaces/organization-domain.interface.ts',
+      fields: new Set(),
+    });
+    setActiveLiveSurface(surface);
+    try {
+      const ctxOwned: EmitterContext = {
+        ...ctx,
+        spec: ownedDomainSpec([stateEnum], [domainModel]),
+        emitterOptions: { ownedServices: ['OrganizationDomains'] },
+      } as EmitterContext;
+
+      const result = generateEnums([stateEnum], ctxOwned);
+      const enumFile = result.find(
+        (f) => f.path === 'src/organization-domains/interfaces/organization-domain-state.interface.ts',
+      );
+      expect(enumFile).toBeDefined();
+      expect(enumFile!.content).toContain('export const OrganizationDomainState = {');
+      expect(enumFile!.content).toContain('export type OrganizationDomainState =');
+    } finally {
+      setActiveLiveSurface(emptyLiveSurface());
+    }
+  });
+
+  it('keeps the skip for non-owned services whose enum genuinely lives elsewhere', () => {
+    const surface = emptyLiveSurface();
+    surface.files.add('src/workos.ts');
+    surface.interfaces.set('OrganizationDomainState', {
+      filePath: 'src/common/interfaces/organization-domain-state.interface.ts',
+      fields: new Set(),
+    });
+    setActiveLiveSurface(surface);
+    try {
+      const ctxNotOwned: EmitterContext = {
+        ...ctx,
+        spec: ownedDomainSpec([stateEnum], [domainModel]),
+      } as EmitterContext;
+
+      const result = generateEnums([stateEnum], ctxNotOwned);
+      expect(result).toHaveLength(0);
+    } finally {
+      setActiveLiveSurface(emptyLiveSurface());
+    }
+  });
+
+  it('emits the module, resolves the barrel export, and imports the name in the model file', () => {
+    // End-to-end shape of the OrganizationDomains failure: generated
+    // organization-domain.interface.ts used `OrganizationDomainState` with
+    // NO import, and interfaces/index.ts exported
+    // ./organization-domain-state.interface — a module no hook ever emitted.
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'node-owned-enum-'));
+    try {
+      const ifaceDir = path.join(tmpRoot, 'src', 'organization-domains', 'interfaces');
+      fs.mkdirSync(ifaceDir, { recursive: true });
+      fs.writeFileSync(path.join(tmpRoot, 'src', 'workos.ts'), 'export class WorkOS {}\n');
+      fs.writeFileSync(
+        path.join(ifaceDir, 'organization-domain.interface.ts'),
+        [
+          "export type OrganizationDomainState = 'verified' | 'pending';",
+          '',
+          'export interface OrganizationDomain {',
+          '  id: string;',
+          '  state: OrganizationDomainState;',
+          '}',
+        ].join('\n'),
+      );
+      execFileSync('git', ['init'], { cwd: tmpRoot, stdio: 'ignore' });
+      execFileSync('git', ['add', 'src'], { cwd: tmpRoot, stdio: 'ignore' });
+
+      const spec = ownedDomainSpec([stateEnum], [domainModel]);
+      const runCtx = {
+        ...ctx,
+        spec,
+        outputDir: tmpRoot,
+        emitterOptions: { ownedServices: ['OrganizationDomains'] },
+      } as EmitterContext;
+
+      const modelFiles = nodeEmitter.generateModels([domainModel], runCtx);
+      const enumFiles = nodeEmitter.generateEnums([stateEnum], runCtx);
+      const clientFiles = nodeEmitter.generateClient(spec, runCtx);
+
+      // The canonical union module IS emitted…
+      const enumPath = 'src/organization-domains/interfaces/organization-domain-state.interface.ts';
+      expect(enumFiles.some((f) => f.path === enumPath)).toBe(true);
+
+      // …the model file imports the name from it…
+      const modelFile = modelFiles.find(
+        (f) => f.path === 'src/organization-domains/interfaces/organization-domain.interface.ts',
+      );
+      expect(modelFile).toBeDefined();
+      expect(modelFile!.content).toContain(
+        "import type { OrganizationDomainState } from './organization-domain-state.interface';",
+      );
+
+      // …and the barrel export resolves to an emitted module instead of a
+      // phantom the import-invariant pass has to drop.
+      const barrel = clientFiles.find((f) => f.path === 'src/organization-domains/interfaces/index.ts');
+      expect(barrel).toBeDefined();
+      expect(barrel!.content).toContain("export * from './organization-domain-state.interface';");
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        nodeEmitter.generateTests(spec, runCtx);
+        const dropped = warnSpy.mock.calls.filter((call) => String(call[0]).includes('dropped unresolvable'));
+        expect(dropped).toEqual([]);
+      } finally {
+        warnSpy.mockRestore();
+      }
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+});