@workos/oagen-emitters 0.12.0 → 0.12.2

package/src/node/index.ts

@@ -12,58 +12,385 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { generateModelsAndSerializers } from './models.js';
-import { generateEnums } from './enums.js';
-import { generateResources } from './resources.js';
+import { generateEnums as generateEnumFiles } from './enums.js';
+import { generateResources, resolveResourceClassName, resolveResourceDir } from './resources.js';
 import { generateClient } from './client.js';
-import { generateErrors } from './errors.js';
+import { generateTests as generateTestFiles } from './tests.js';
+import { buildLiveSurface, emptyLiveSurface, setActiveLiveSurface, type LiveSurface } from './live-surface.js';
+import {
+  setBaselineSerializedNames,
+  setBaselineInterfaceNames,
+  setAdoptedModelNames,
+  resolveInterfaceName,
+} from './naming.js';
+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 { fileName } from './naming.js';
 
-import { generateTests } from './tests.js';
-import { buildOperationsMap } from './manifest.js';
+/**
+ * Cache live-surface per ctx — every emitter method receives the same ctx in
+ * one oagen run, so we walk the target SDK once and reuse it.
+ */
+const surfaceCache = new WeakMap<EmitterContext, LiveSurface>();
 
-/** Ensure every generated file's content ends with a trailing newline. */
-function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
+function getSurface(ctx: EmitterContext): LiveSurface {
+  let surface = surfaceCache.get(ctx);
+  if (surface) return surface;
+  // Prefer --output (where we are writing) over --target (rare for node).
+  // The literal command `--output <SDK>` makes outputDir the SDK root.
+  const root = ctx.outputDir ?? ctx.targetDir;
+  surface = root ? buildLiveSurface(root) : emptyLiveSurface();
+  if (root) markPriorManifestAutogen(surface, root, ctx.priorTargetManifestPaths);
+  surfaceCache.set(ctx, surface);
+  setActiveLiveSurface(surface);
+
+  // Wire the type-map's resolver so field-type references (`schema: X`) and
+  // import statements (`import type { X }`) agree on the same name. The
+  // structural baseline match in `resolveInterfaceName` can map an IR name
+  // to a different live-SDK name (e.g. `AuditLogSchemaJson` → baseline
+  // `AuditLogSchemaResponse` via `overlayLookup.modelNameByIR`).
+  setDomainNameResolver((irName: string) => resolveInterfaceName(irName, ctx));
+
+  // Tell `naming.wireInterfaceName` which `Serialized*` interfaces exist in
+  // the live SDK so generated imports use the legacy name where applicable.
+  // Source from the api-surface JSON (richer) when present, else fall back
+  // to the disk walk.
+  const serialized = new Set<string>();
+  const ifaces = ctx.apiSurface?.interfaces;
+  if (ifaces) {
+    for (const name of Object.keys(ifaces)) {
+      if (name.startsWith('Serialized')) serialized.add(name);
+    }
+  }
+  for (const name of surface.interfaces.keys()) {
+    if (name.startsWith('Serialized')) serialized.add(name);
+  }
+  setBaselineSerializedNames(serialized);
+
+  // Full set of baseline interface names — used by `wireInterfaceName` to
+  // detect when a `Response`-suffixed name has no `*Wire` companion in
+  // the live SDK and is therefore the single-form wire interface.
+  const allInterfaces = new Set<string>();
+  if (ifaces) {
+    for (const name of Object.keys(ifaces)) allInterfaces.add(name);
+  }
+  for (const name of surface.interfaces.keys()) allInterfaces.add(name);
+  setBaselineInterfaceNames(allInterfaces);
+
+  // 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
+  // would drop the enum's file but leave value references in hand-written
+  // test files dangling — see admin-portal.spec.ts referencing `.SSO`.
+  // Pass an empty map; type-map will fall back to emitting the symbol name.
+  setInlineEnumUnions(new Map());
+  setAdoptedModelNames(computeAdoptedModelNames(ctx, surface));
+  return surface;
+}
+
+/**
+ * Apply the live-surface filter to a batch of generated files.
+ *
+ * Three signals decide what happens to each `GeneratedFile`:
+ *
+ *   1. `@oagen-ignore-file` marker (`surface.protectedFiles`) — the user has
+ *      taken ownership of the file, never write on top of it.
+ *   2. `auto-generated by oagen` header (`surface.autogenFiles`) — the file
+ *      was produced by a prior generation. Spec changes (e.g. parameter
+ *      renames) must propagate, so we leave the file in the output and let
+ *      the engine's AST merger update it. No skip flags.
+ *   3. File on disk without either marker — treat as hand-written; drop from
+ *      the output to avoid the engine prepending a header on `skipIfExists`
+ *      files (see writeFiles:~4360 in @workos/oagen) or merging unrequested
+ *      changes into it.
+ *   4. Brand-new path in an existing SDK — drop it. For a live SDK we treat
+ *      the git-tracked baseline as the managed surface; generating new files
+ *      is what caused the workos-node file explosion.
+ *
+ * `integrateTarget: false` files (smoke-manifest.json etc.) are also dropped:
+ * with no `--target` step they would otherwise land as untracked cruft.
+ *
+ * Note: pairing this with `--no-prune` is required for stable behavior — see
+ * `scripts/sdk-generate.sh` in the spec repo, which enables it for `--lang node`.
+ */
+/**
+ * `*.spec.ts`, `*.test.ts`, and JSON fixtures under `fixtures/` are owned by
+ * the test author after first emission. The emitter scaffolds them on a
+ * brand-new resource, but subsequent regenerations must leave them alone —
+ * assertions get hand-tuned, fixture data gets stabilized, and re-emission
+ * would point them at sibling serializers/interfaces that may have shape-
+ * shifted under the user's feet.
+ */
+function isUserOwnedAfterFirstEmit(relPath: string): boolean {
+  if (relPath.endsWith('.spec.ts') || relPath.endsWith('.test.ts')) return true;
+  if (/\/fixtures\/[^/]+\.json$/.test(relPath)) return true;
+  return false;
+}
+
+interface LiveSurfacePolicy {
+  managedPaths: Set<string>;
+  hasExistingSdk: boolean;
+  adoptedServiceDirs: Set<string>;
+  ownedServiceDirs: Set<string>;
+  oagenOwnedDirs: Set<string>;
+  regenerateOwnedTests: boolean;
+}
+
+function managedPathsFor(ctx: EmitterContext, surface: LiveSurface): Set<string> {
+  const managedPaths = new Set(surface.trackedFiles.size > 0 ? surface.trackedFiles : surface.files);
+  for (const relPath of ctx.priorTargetManifestPaths ?? []) {
+    if (relPath.startsWith('src/')) managedPaths.add(relPath);
+  }
+  return managedPaths;
+}
+
+function markPriorManifestAutogen(
+  surface: LiveSurface,
+  root: string,
+  priorManifestPaths: Set<string> | undefined,
+): void {
+  if (!priorManifestPaths) return;
+
+  for (const relPath of priorManifestPaths) {
+    if (!relPath.startsWith('src/')) continue;
+    if (!surface.files.has(relPath)) continue;
+    if (surface.protectedFiles.has(relPath)) continue;
+
+    try {
+      const text = fs.readFileSync(path.join(root, relPath), 'utf8');
+      if (/auto-generated by oagen/i.test(text.slice(0, 400))) {
+        surface.autogenFiles.add(relPath);
+        extractManifestFunctions(text, relPath, surface);
+      }
+    } catch {
+      // File disappeared between surface walk and read; ignore it.
+    }
+  }
+}
+
+const MANIFEST_FUNCTION_RE = /^\s*export\s+(?:async\s+)?function\s+([a-zA-Z_$][\w$]*)/gm;
+const MANIFEST_CONST_FN_RE =
+  /^\s*export\s+const\s+([a-zA-Z_$][\w$]*)\s*(?::\s*[^=]+)?=\s*(?:async\s+)?(?:<[^>]*>\s*)?\(/gm;
+
+function extractManifestFunctions(text: string, relPath: string, surface: LiveSurface): void {
+  for (const match of text.matchAll(MANIFEST_FUNCTION_RE)) {
+    surface.functions.set(match[1], relPath);
+  }
+  for (const match of text.matchAll(MANIFEST_CONST_FN_RE)) {
+    surface.functions.set(match[1], relPath);
+  }
+}
+
+function buildLiveSurfacePolicy(ctx: EmitterContext, surface: LiveSurface): LiveSurfacePolicy {
+  const managedPaths = managedPathsFor(ctx, surface);
+  const hasExistingSdk = managedPaths.size > 0;
+  const adoptedServiceDirs = nodeOptions(ctx).adoptMissingServices
+    ? computeAdoptedServiceDirs(ctx, surface)
+    : new Set<string>();
+  const ownedServiceDirs = computeOwnedServiceDirs(ctx);
+  for (const dir of ownedServiceDirs) {
+    for (const relPath of surface.files) {
+      if (topLevelDir(relPath) === dir) managedPaths.add(relPath);
+    }
+  }
+
+  return {
+    managedPaths,
+    hasExistingSdk,
+    adoptedServiceDirs,
+    ownedServiceDirs,
+    oagenOwnedDirs: topLevelDirs(surface.autogenFiles),
+    regenerateOwnedTests: nodeOptions(ctx).regenerateOwnedTests === true,
+  };
+}
+
+function computeOwnedServiceDirs(ctx: EmitterContext): Set<string> {
+  const dirs = new Set<string>();
+  if ((nodeOptions(ctx).ownedServices ?? []).length === 0) return dirs;
+
+  const mountGroups = groupByMount(ctx);
+  const services =
+    mountGroups.size > 0
+      ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
+      : ctx.spec.services;
+  const { resolveDir } = createServiceDirResolver(ctx.spec.models, ctx.spec.services, ctx);
+
+  for (const service of services) {
+    const resourceName = resolveResourceClassName(service, ctx);
+    if (!isNodeOwnedService(ctx, service.name, resourceName)) continue;
+    dirs.add(resolveResourceDir(service, ctx));
+    dirs.add(resolveDir(service.name));
+  }
+
+  return dirs;
+}
+
+function computeAdoptedServiceDirs(ctx: EmitterContext, surface: LiveSurface): Set<string> {
+  const dirs = new Set<string>();
+  const mountGroups = groupByMount(ctx);
+  const services =
+    mountGroups.size > 0
+      ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
+      : ctx.spec.services;
+  const { resolveDir } = createServiceDirResolver(ctx.spec.models, ctx.spec.services, ctx);
+
+  for (const service of services) {
+    if (service.operations.length === 0) continue;
+
+    const resourceName = resolveResourceClassName(service, ctx);
+    if (surface.classes.has(resourceName) || ctx.apiSurface?.classes?.[resourceName]) continue;
+
+    const resourceDir = resolveResourceDir(service, ctx);
+    const resourcePath = `src/${resourceDir}/${fileName(resourceName)}.ts`;
+    if (surface.protectedFiles.has(resourcePath)) continue;
+
+    dirs.add(resourceDir);
+    dirs.add(resolveDir(service.name));
+  }
+
+  return dirs;
+}
+
+function computeAdoptedModelNames(ctx: EmitterContext, surface: LiveSurface): Set<string> {
+  if (!nodeOptions(ctx).adoptMissingServices) return new Set();
+
+  const adoptedServiceDirs = computeAdoptedServiceDirs(ctx, surface);
+  if (adoptedServiceDirs.size === 0) return new Set();
+
+  const modelToService = assignModelsToServices(ctx.spec.models, ctx.spec.services, ctx.modelHints);
+  const { resolveDir } = createServiceDirResolver(ctx.spec.models, ctx.spec.services, ctx);
+  const names = new Set<string>();
+  for (const model of ctx.spec.models) {
+    const dirName = resolveDir(modelToService.get(model.name));
+    if (adoptedServiceDirs.has(dirName)) names.add(model.name);
+  }
+  return names;
+}
+
+function topLevelDirs(paths: Set<string>): Set<string> {
+  const dirs = new Set<string>();
+  for (const relPath of paths) {
+    const dir = topLevelDir(relPath);
+    if (dir) dirs.add(dir);
+  }
+  return dirs;
+}
+
+function topLevelDir(relPath: string): string | undefined {
+  return relPath.match(/^src\/([^/]+)\//)?.[1];
+}
+
+function canCreateNewPath(relPath: string, policy: LiveSurfacePolicy): boolean {
+  const dir = topLevelDir(relPath);
+  if (!dir) return false;
+  return policy.adoptedServiceDirs.has(dir) || policy.ownedServiceDirs.has(dir) || policy.oagenOwnedDirs.has(dir);
+}
+
+function isOwnedPath(relPath: string, policy: LiveSurfacePolicy): boolean {
+  const dir = topLevelDir(relPath);
+  return dir !== undefined && policy.ownedServiceDirs.has(dir);
+}
+
+function applyLiveSurface(files: GeneratedFile[], ctx: EmitterContext, surface: LiveSurface): GeneratedFile[] {
+  const out: GeneratedFile[] = [];
+  const policy = buildLiveSurfacePolicy(ctx, surface);
   for (const f of files) {
+    const ownedPath = isOwnedPath(f.path, policy);
+    if (f.integrateTarget === false) continue;
+    if (surface.protectedFiles.has(f.path)) continue;
+    if (policy.hasExistingSdk && !policy.managedPaths.has(f.path) && !canCreateNewPath(f.path, policy)) continue;
+
+    // Hand-written files (on disk, no `auto-generated by oagen` header) →
+    // drop. The engine would otherwise prepend the header on
+    // `skipIfExists: true` files (writeFiles:~4360), and the merger may
+    // try to splice generated symbols into hand-written ones.
+    if (surface.files.has(f.path) && !surface.autogenFiles.has(f.path) && !ownedPath) continue;
+
+    // Test specs and fixtures: author-owned after first emission. Once a
+    // test file or fixture exists on disk, the user owns it — the emitter
+    // re-emitting against new IR would either replace assertions/data the
+    // user has hand-tuned, or leave it pointing at sibling files that no
+    // longer have the same shape. Treat existing test/fixture files as
+    // frozen even when they carry the auto-gen header.
+    if (isUserOwnedAfterFirstEmit(f.path)) {
+      if (surface.files.has(f.path) && !surface.autogenFiles.has(f.path)) continue;
+      if (!ownedPath && !surface.autogenFiles.has(f.path)) continue;
+      if (ownedPath && !policy.regenerateOwnedTests) continue;
+    }
+
+    // Previously auto-generated files → fully overwrite so spec changes
+    // (e.g. parameter renames like `admin_emails` → `it_contact_emails`)
+    // propagate. The engine's default AST merger is additive and would
+    // leave the old name on existing methods. Files marked
+    // `@oagen-ignore-start`/`@oagen-ignore-end` regions inside the file
+    // are still preserved by `overwriteWithPreservedRegions` in the
+    // engine.
+    if (surface.autogenFiles.has(f.path) || ownedPath) {
+      f.overwriteExisting = true;
+      f.skipIfExists = false;
+    }
+
     if (f.content && !f.content.endsWith('\n')) {
       f.content += '\n';
     }
+    out.push(f);
   }
-  return files;
+  return out;
 }
 
 export const nodeEmitter: Emitter = {
   language: 'node',
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateModelsAndSerializers(models, ctx));
+    const nodeCtx = withNodeOperationOverrides(ctx);
+    const surface = getSurface(nodeCtx);
+    return applyLiveSurface(generateModelsAndSerializers(models, nodeCtx), nodeCtx, surface);
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateEnums(enums, ctx));
+    const nodeCtx = withNodeOperationOverrides(ctx);
+    const surface = getSurface(nodeCtx);
+    return applyLiveSurface(generateEnumFiles(enums, nodeCtx), nodeCtx, surface);
   },
 
   generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateResources(services, ctx));
+    const nodeCtx = withNodeOperationOverrides(ctx);
+    const surface = getSurface(nodeCtx);
+    return applyLiveSurface(generateResources(services, nodeCtx), nodeCtx, surface);
   },
 
   generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateClient(spec, ctx));
+    const nodeCtx = withNodeOperationOverrides(ctx);
+    const surface = getSurface(nodeCtx);
+    return applyLiveSurface(generateClient(spec, nodeCtx), nodeCtx, surface);
   },
 
-  generateErrors(ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateErrors(ctx));
+  // workos-node ships its own exception hierarchy under src/common/exceptions/.
+  // Re-emitting them would either skip (if files exist) or overwrite hand-edits.
+  generateErrors(_ctx: EmitterContext): GeneratedFile[] {
+    return [];
   },
 
   generateTypeSignatures(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
-    // TypeScript uses inline types — no separate type signature files needed
     return [];
   },
 
+  // Test specs and fixtures are hand-maintained except for explicitly-owned
+  // service directories.
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateTests(spec, ctx));
+    const nodeCtx = withNodeOperationOverrides(ctx);
+    if (!nodeOptions(nodeCtx).regenerateOwnedTests) return [];
+    const surface = getSurface(nodeCtx);
+    return applyLiveSurface(generateTestFiles(spec, nodeCtx), nodeCtx, surface);
   },
 
-  buildOperationsMap(spec: ApiSpec, ctx: EmitterContext) {
-    return buildOperationsMap(spec, ctx);
+  // No operations map needed — the manifest belongs to the staging+target flow,
+  // which the literal `--output <SDK>` command does not use.
+  buildOperationsMap(): Record<string, never> {
+    return {};
   },
 
   fileHeader(): string {
@@ -79,8 +406,6 @@ export const nodeEmitter: Emitter = {
       fs.existsSync(path.join(targetDir, '.eslintrc.js'));
 
     if (hasPrettier && hasEslint) {
-      // Chain ESLint autofix (e.g. unused-import removal) then prettier.
-      // ESLint errors are suppressed so formatting still runs on lint failure.
       return {
         cmd: 'bash',
         args: [