@workos/oagen-emitters 0.16.0 → 0.17.0

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-DuB1UozS.mjs";
+import { t as workosEmittersPlugin } from "./plugin-BLnR-FMi.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",
@@ -40,12 +40,12 @@
   "devDependencies": {
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.3",
     "husky": "^9.1.7",
-    "oxfmt": "^0.53.0",
-    "oxlint": "^1.68.0",
-    "prettier": "^3.8.3",
-    "tsdown": "^0.22.1",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "prettier": "^3.8.4",
+    "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
@@ -54,6 +54,6 @@
     "node": ">=24.10.0"
   },
   "dependencies": {
-    "@workos/oagen": "^0.22.0"
+    "@workos/oagen": "^0.22.5"
   }
 }

package/src/go/index.ts

@@ -11,6 +11,7 @@ import type {
 
 import { generateModels } from './models.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { flattenDiscriminatedUnionFields } from '../shared/union-flatten.js';
 import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
@@ -47,7 +48,11 @@ export const goEmitter: Emitter = {
       }
       return m;
     });
-    return ensureTrailingNewlines(generateModels(goModels, ctx));
+    // Go has no sum types: a discriminated-union field (e.g. ApiKey.owner)
+    // renders as its first variant, dropping fields that only exist on later
+    // variants (organization_id on the user owner). Flatten such unions into a
+    // single superset struct so every variant field survives.
+    return ensureTrailingNewlines(generateModels(flattenDiscriminatedUnionFields(goModels), ctx));
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {

package/src/kotlin/index.ts

@@ -18,6 +18,7 @@ import { generateClient } from './client.js';
 import { generateTests } from './tests.js';
 import { buildOperationsMap } from './manifest.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { flattenDiscriminatedUnionFields } from '../shared/union-flatten.js';
 
 /** Ensure every generated file ends with a trailing newline. */
 function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
@@ -49,7 +50,11 @@ export const kotlinEmitter: Emitter = {
       }
       return m;
     });
-    return ensureTrailingNewlines(generateModels(kotlinModels, ctx));
+    // Kotlin renders a discriminated-union field as its first variant's data
+    // class, so fields unique to later variants (organization_id on the user
+    // owner) are lost. Flatten such unions into one superset data class so
+    // every variant field is reachable.
+    return ensureTrailingNewlines(generateModels(flattenDiscriminatedUnionFields(kotlinModels), ctx));
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
@@ -78,8 +83,9 @@ export const kotlinEmitter: Emitter = {
 
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
     // Pass enriched models so round-trip tests see the full field set
-    // (including optional oneOf-enriched fields) and can filter accurately.
-    const enrichedModels = enrichModelsFromSpec(spec.models);
+    // (including optional oneOf-enriched fields and flattened discriminated-
+    // union owner fields) and can filter accurately.
+    const enrichedModels = flattenDiscriminatedUnionFields(enrichModelsFromSpec(spec.models));
     const enrichedSpec: ApiSpec = { ...spec, models: enrichedModels };
     return ensureTrailingNewlines(generateTests(enrichedSpec, { ...ctx, spec: enrichedSpec }));
   },

package/src/node/enums.ts

@@ -1,8 +1,9 @@
 import type { Enum, EmitterContext, GeneratedFile, Model, Service } from '@workos/oagen';
-import { assignModelsToServices, collectFieldDependencies, toPascalCase, walkTypeRef } from '@workos/oagen';
+import { collectFieldDependencies, toPascalCase, walkTypeRef } from '@workos/oagen';
 import { fileName, resolveServiceDir, buildServiceNameMap } from './naming.js';
-import { docComment } from './utils.js';
+import { docComment, assignModelsToEmittableServices } from './utils.js';
 import { isInlineEnum } from './type-map.js';
+import { isNodeOwnedService } from './options.js';
 import { liveSurfaceConstEnumMembers, liveSurfaceInterfacePath } from './live-surface.js';
 
 export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
@@ -30,7 +31,15 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     if (dirName === 'common' && !baselineSourceFile && (ctx.outputDir || ctx.targetDir || ctx.apiSurface)) {
       continue;
     }
-    if (baselineSourceFile && baselineSourceFile !== generatedPath) {
+    // The declared-elsewhere skip must not fire for OWNED services: the
+    // "elsewhere" is typically the very interface file the owned-service
+    // regeneration is simultaneously overwriting (e.g. legacy enums declared
+    // inline in organization-domain.interface.ts), so skipping here leaves
+    // the names referenced by generated code but declared nowhere. Under
+    // ownership the canonical per-service module is the source of truth —
+    // emit it; the model emitter plans its import from the same path.
+    const isOwnedEnumService = isNodeOwnedService(ctx, service, service ? serviceNameMap.get(service) : undefined);
+    if (baselineSourceFile && baselineSourceFile !== generatedPath && !isOwnedEnumService) {
       continue;
     }
 
@@ -160,7 +169,11 @@ export function assignEnumsToServices(
   }
 
   if (models.length > 0) {
-    const modelToService = assignModelsToServices(models, services, ctx?.modelHints);
+    // Use the emittable-services assignment (not the raw engine one) so an
+    // enum referenced through a model that was re-homed into an owned
+    // service directory follows the model — `generateEnums` emission and the
+    // model's enum imports must agree on the directory.
+    const modelToService = assignModelsToEmittableServices(models, services, ctx);
     for (const model of models) {
       const service = modelToService.get(model.name);
       if (!service) continue;

package/src/node/index.ts

@@ -8,6 +8,7 @@ import type {
   Enum,
   Service,
 } from '@workos/oagen';
+import { toPascalCase } from '@workos/oagen';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
@@ -17,11 +18,19 @@ import { generateResources, resolveResourceClassName, resolveResourceDir } from
 import { generateClient } from './client.js';
 import { generateTests as generateTestFiles } from './tests.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { flattenDiscriminatedUnionFields } from '../shared/union-flatten.js';
 import { planDiscriminatedModels, generateDiscriminatedFiles } from './discriminated-models.js';
-import { buildLiveSurface, emptyLiveSurface, setActiveLiveSurface, type LiveSurface } from './live-surface.js';
+import {
+  buildLiveSurface,
+  emptyLiveSurface,
+  mergeGeneratedClassMethodsIntoExisting,
+  setActiveLiveSurface,
+  type LiveSurface,
+} from './live-surface.js';
 import {
   setBaselineSerializedNames,
   setBaselineInterfaceNames,
+  setBaselineDeclaredNames,
   setAdoptedModelNames,
   setDiscriminatedModelNames,
   setStructurallyRenamedDomainNames,
@@ -31,7 +40,7 @@ import { withNodeOperationOverrides } from './node-overrides.js';
 import { isNodeOwnedService, nodeOptions } from './options.js';
 import { setInlineEnumUnions, setDomainNameResolver } from './type-map.js';
 import { groupByMount } from '../shared/resolved-ops.js';
-import { assignModelsToServices, createServiceDirResolver } from './utils.js';
+import { assignModelsToServices, createServiceDirResolver, relativeImport } from './utils.js';
 import { fileName } from './naming.js';
 
 /**
@@ -58,6 +67,24 @@ function getEmittedPaths(ctx: EmitterContext): Set<string> {
   return set;
 }
 
+/**
+ * Every `GeneratedFile` the node emitter has produced so far in this ctx,
+ * keyed by path. All emitter hooks share one ctx (and the engine only reads
+ * file contents after the last hook returns), so the final hook can run a
+ * whole-run pass over files emitted by earlier hooks — see
+ * `enforceEmittedImportInvariant`.
+ */
+const emittedFilesCache = new WeakMap<EmitterContext, Map<string, GeneratedFile>>();
+
+function getEmittedFiles(ctx: EmitterContext): Map<string, GeneratedFile> {
+  let map = emittedFilesCache.get(ctx);
+  if (!map) {
+    map = new Map();
+    emittedFilesCache.set(ctx, map);
+  }
+  return map;
+}
+
 function getSurface(ctx: EmitterContext): LiveSurface {
   let surface = surfaceCache.get(ctx);
   if (surface) return surface;
@@ -102,6 +129,18 @@ function getSurface(ctx: EmitterContext): LiveSurface {
   for (const name of surface.interfaces.keys()) allInterfaces.add(name);
   setBaselineInterfaceNames(allInterfaces);
 
+  // Every DECLARED baseline name — interfaces and type aliases, from both
+  // the api-surface JSON and the disk walk (whose `interfaces` map already
+  // includes `export type` aliases). `resolveInterfaceName` uses this to
+  // let exact-name declarations preempt structural renames: an alias-form
+  // file (`export type X = Y;`) carries no fields, so the engine's
+  // structural matcher would otherwise re-point IR model X at a similarly
+  // shaped interface and emit renamed duplicates that flip the file's form
+  // on every regeneration.
+  const declaredNames = new Set<string>(allInterfaces);
+  for (const name of Object.keys(ctx.apiSurface?.typeAliases ?? {})) declaredNames.add(name);
+  setBaselineDeclaredNames(declaredNames);
+
   // Inline-enum optimization is intentionally disabled. workos-node emits the
   // dual `const X = {...} as const; type X = ...` pattern so callers can use
   // members at runtime (e.g. `GenerateLinkIntent.SSO`). Inlining the type
@@ -342,6 +381,16 @@ function isOwnedPath(relPath: string, policy: LiveSurfacePolicy): boolean {
   return dir !== undefined && policy.ownedServiceDirs.has(dir);
 }
 
+/** Read the current on-disk content of a live-surface file, if present. */
+function readExistingSurfaceFile(surface: LiveSurface, relPath: string): string | null {
+  if (!surface.rootDir) return null;
+  try {
+    return fs.readFileSync(path.join(surface.rootDir, relPath), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
 function extractRelativeImportPaths(content: string, fromPath: string): string[] {
   const dir = path.dirname(fromPath);
   const paths: string[] = [];
@@ -438,7 +487,26 @@ function applyLiveSurface(files: GeneratedFile[], ctx: EmitterContext, surface:
     // `@oagen-ignore-start`/`@oagen-ignore-end` regions inside the file
     // are still preserved by `overwriteWithPreservedRegions` in the
     // engine.
+    //
+    // Exception: a NOT-owned, NOT-adopted service can receive a PARTIAL
+    // resource emission — resources.ts filters out operations already
+    // covered by the baseline class, leaving only the new methods (see
+    // generateResourceClass). Forcing a full overwrite with that partial
+    // class deletes the existing public methods (workos-node's
+    // api-keys.ts lost four methods when the spec gained one operation).
+    // When the generated class would drop methods that the on-disk class
+    // declares, merge instead: keep the existing file text verbatim and
+    // append only the new methods plus the imports they need.
     if (surface.autogenFiles.has(f.path) || ownedPath) {
+      const dir = topLevelDir(f.path);
+      const isAdoptedDirPath = dir !== undefined && policy.adoptedServiceDirs.has(dir);
+      if (!ownedPath && !isAdoptedDirPath && surface.autogenFiles.has(f.path)) {
+        const existingText = readExistingSurfaceFile(surface, f.path);
+        if (existingText !== null) {
+          const merged = mergeGeneratedClassMethodsIntoExisting(existingText, f.content);
+          if (merged !== null) f.content = merged;
+        }
+      }
       f.overwriteExisting = true;
       f.skipIfExists = false;
     }
@@ -449,10 +517,192 @@ function applyLiveSurface(files: GeneratedFile[], ctx: EmitterContext, surface:
     out.push(f);
   }
   const emitted = getEmittedPaths(ctx);
-  for (const f of out) emitted.add(f.path);
+  const emittedFiles = getEmittedFiles(ctx);
+  for (const f of out) {
+    emitted.add(f.path);
+    emittedFiles.set(f.path, f);
+  }
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Import-resolution invariant
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches single-line `import`/`export … from './relative'` statements — the
+ * only form the node emitter produces. Captures: keyword, optional ` type`
+ * modifier, the binding clause (`* [as ns]` or `{ … }`), and the module path.
+ */
+const RELATIVE_FROM_STMT_RE =
+  /^(import|export)(\s+type)?\s+(\*(?:\s+as\s+[\w$]+)?|\{[^}]*\})\s+from\s+['"](\.[^'"]+)['"];?\s*$/;
+
+const EXPORTED_DECL_RE =
+  /^export\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:interface|class|enum|function|const|let|var|type)\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORTED_CLAUSE_RE = /^export\s+(?:type\s+)?\{([^}]*)\}/gm;
+
+/** Repo-relative paths a relative import specifier may resolve to. */
+function importTargetCandidates(fromPath: string, spec: string): string[] {
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromPath), spec));
+  return [base, `${base}.ts`, `${base}/index.ts`];
+}
+
+/** Index exported symbol → file path across this run's emitted contents. */
+function indexEmittedExports(files: GeneratedFile[]): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const f of files) {
+    if (!f.path.endsWith('.ts') || !f.content) continue;
+    for (const m of f.content.matchAll(EXPORTED_DECL_RE)) {
+      if (!index.has(m[1])) index.set(m[1], f.path);
+    }
+    for (const m of f.content.matchAll(EXPORTED_CLAUSE_RE)) {
+      for (const raw of m[1].split(',')) {
+        const entry = raw.trim();
+        if (!entry) continue;
+        const parts = entry.split(/\s+as\s+/);
+        const exported = (parts[1] ?? parts[0]).replace(/^type\s+/, '').trim();
+        if (exported && !index.has(exported)) index.set(exported, f.path);
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * Enforce: every relative import/re-export path in emitted code resolves to
+ * either (i) a file emitted in the same run, or (ii) a file that already
+ * exists on disk in the target SDK.
+ *
+ * Violations observed in real generations (all TS2307 in otherwise-valid
+ * output): serializer imports pointing at canonical paths while the function
+ * lives in a legacy hand serializer under a different filename; barrels
+ * re-exporting a module-local enum file whose declaration lives under
+ * `src/common/interfaces`; barrels exporting interface files that no run
+ * emits at all.
+ *
+ * Repair strategy, per statement whose target is neither emitted nor on
+ * disk:
+ *  1. Locate each imported symbol (this run's emissions first, then the
+ *     live-surface declaration maps) and rewrite the path to where the
+ *     symbol actually lives — splitting into one statement per location
+ *     when symbols are spread across files.
+ *  2. `export * from` / namespace imports carry no symbol list, so derive
+ *     the expected symbol from the file stem (`foo-bar.interface` →
+ *     `FooBar`, `foo.serializer` → `deserializeFoo`/`serializeFoo`).
+ *  3. When a symbol exists nowhere, drop the statement and warn — a missing
+ *     named export fails loudly at the usage site instead of as a phantom
+ *     module, and a barrel line for a never-emitted file is pure noise.
+ *
+ * Mutates `f.content` in place and returns the warnings issued.
+ */
+export function enforceEmittedImportInvariant(
+  files: Iterable<GeneratedFile>,
+  emittedPaths: Set<string>,
+  surface: LiveSurface,
+): string[] {
+  const fileList = [...files];
+  const emittedSymbols = indexEmittedExports(fileList);
+  const warnings: string[] = [];
+
+  const targetExists = (fromPath: string, spec: string): boolean =>
+    importTargetCandidates(fromPath, spec).some((p) => emittedPaths.has(p) || surface.files.has(p));
+
+  const locateSymbol = (name: string): string | undefined =>
+    emittedSymbols.get(name) ??
+    surface.functions.get(name) ??
+    surface.interfaces.get(name)?.filePath ??
+    surface.classes.get(name)?.filePath;
+
+  for (const f of fileList) {
+    if (!f.path.endsWith('.ts') || !f.content) continue;
+    let changed = false;
+    const outLines: string[] = [];
+    for (const line of f.content.split('\n')) {
+      const m = line.match(RELATIVE_FROM_STMT_RE);
+      if (!m || targetExists(f.path, m[4])) {
+        outLines.push(line);
+        continue;
+      }
+      const [, keyword, typeMod, clause, spec] = m;
+      const repaired = repairUnresolvableStatement(f.path, keyword, typeMod ?? '', clause, spec, locateSymbol);
+      changed = true;
+      outLines.push(...repaired.lines);
+      if (repaired.warning) warnings.push(repaired.warning);
+    }
+    if (changed) f.content = outLines.join('\n');
+  }
+
+  for (const w of warnings) console.warn(w);
+  return warnings;
+}
+
+function repairUnresolvableStatement(
+  fromPath: string,
+  keyword: string,
+  typeMod: string,
+  clause: string,
+  spec: string,
+  locateSymbol: (name: string) => string | undefined,
+): { lines: string[]; warning?: string } {
+  if (clause.startsWith('{')) {
+    const entries = clause
+      .slice(1, -1)
+      .split(',')
+      .map((e) => e.trim())
+      .filter(Boolean);
+    const byLocation = new Map<string, string[]>();
+    const missing: string[] = [];
+    for (const entry of entries) {
+      const source = entry
+        .split(/\s+as\s+/)[0]
+        .replace(/^type\s+/, '')
+        .trim();
+      const location = locateSymbol(source);
+      if (!location) {
+        missing.push(source);
+        continue;
+      }
+      if (location === fromPath) continue; // declared locally — no import needed
+      const group = byLocation.get(location);
+      if (group) {
+        group.push(entry);
+      } else {
+        byLocation.set(location, [entry]);
+      }
+    }
+    // Emit the symbols we *can* relocate; only the genuinely-missing ones are
+    // dropped (and warned about). Returning [] for the whole clause when any
+    // one symbol is missing would also discard the resolvable symbols, failing
+    // them with TS2305 at their usage sites — the breakage this pass prevents.
+    const lines = [...byLocation].map(
+      ([location, group]) =>
+        `${keyword}${typeMod} { ${group.join(', ')} } from '${relativeImport(fromPath, location)}';`,
+    );
+    const warning =
+      missing.length > 0
+        ? `oagen(node): dropped unresolvable symbol(s) from ${keyword} in ${fromPath}: '${spec}' — found neither in this run's output nor in the target SDK: ${missing.join(', ')}`
+        : undefined;
+    return { lines, warning };
+  }
+
+  // `* [as ns]` — no symbol list; derive the expected symbol from the stem.
+  const stem = spec.split('/').pop() ?? '';
+  let location: string | undefined;
+  if (stem.endsWith('.interface')) {
+    location = locateSymbol(toPascalCase(stem.slice(0, -'.interface'.length)));
+  } else if (stem.endsWith('.serializer')) {
+    const base = toPascalCase(stem.slice(0, -'.serializer'.length));
+    location = locateSymbol(`deserialize${base}`) ?? locateSymbol(`serialize${base}`);
+  }
+  if (location && location !== fromPath) {
+    return { lines: [`${keyword}${typeMod} ${clause} from '${relativeImport(fromPath, location)}';`] };
+  }
+  return {
+    lines: [],
+    warning: `oagen(node): dropped unresolvable ${keyword} in ${fromPath}: '${spec}' — module is neither emitted this run nor present in the target SDK`,
+  };
+}
+
 /**
  * Re-declare prior-manifest paths that we did not emit this run so manifest
  * pruning can tell "intentionally removed" from "untouched but still managed."
@@ -517,7 +767,7 @@ function carryForwardManagedFiles(ctx: EmitterContext, surface: LiveSurface): Ge
 function enrichModelsForNode(models: Model[]): Model[] {
   const enriched = enrichModelsFromSpec(models);
   const originalByName = new Map(models.map((m) => [m.name, m]));
-  return enriched.map((m) => {
+  const restored = enriched.map((m) => {
     if ((m as { discriminator?: unknown }).discriminator && m.fields.length === 0) {
       const original = originalByName.get(m.name);
       if (original && original.fields.length > 0) {
@@ -526,6 +776,11 @@ function enrichModelsForNode(models: Model[]): Model[] {
     }
     return m;
   });
+  // Field-level discriminated unions (e.g. ApiKey.owner) otherwise render as
+  // `FirstVariant | SecondVariant`; collapse them to one flat superset
+  // interface so callers see every variant field (organization_id on the user
+  // owner) on a single type — parity with the other flat-emit languages.
+  return flattenDiscriminatedUnionFields(restored);
 }
 
 export const nodeEmitter: Emitter = {
@@ -593,7 +848,18 @@ export const nodeEmitter: Emitter = {
     const testFiles = nodeOptions(nodeCtx).regenerateOwnedTests
       ? applyLiveSurface(generateTestFiles(spec, nodeCtx), nodeCtx, surface)
       : [];
-    return [...testFiles, ...carryForwardManagedFiles(nodeCtx, surface)];
+    const result = [...testFiles, ...carryForwardManagedFiles(nodeCtx, surface)];
+
+    // Final whole-run pass: this is the last generate hook, every hook shares
+    // `nodeCtx`, and the engine reads contents only after all hooks return —
+    // so the emitted-files cache now covers the complete run and repairs here
+    // reach files produced by earlier hooks. Greenfield runs are exempt: with
+    // no SDK on disk, "resolves to an existing file" has no meaning and the
+    // SDK core (workos.ts, common/) is intentionally not emitted.
+    if (managedPathsFor(nodeCtx, surface).size > 0) {
+      enforceEmittedImportInvariant(getEmittedFiles(nodeCtx).values(), getEmittedPaths(nodeCtx), surface);
+    }
+    return result;
   },
 
   // No operations map needed — the manifest belongs to the staging+target flow,