@workos/oagen-emitters 0.12.1 → 0.12.3

package/src/node/field-plan.ts

@@ -1,10 +1,17 @@
 import type { Model, Field, EmitterContext, TypeRef, UnionType, PrimitiveType } from '@workos/oagen';
 import { mapTypeRef as tsMapTypeRef } from './type-map.js';
 import { fieldName, wireFieldName, fileName, resolveInterfaceName, wireInterfaceName } from './naming.js';
-import { relativeImport, buildKnownTypeNames, isBaselineGeneric, createServiceDirResolver } from './utils.js';
+import {
+  relativeImport,
+  buildKnownTypeNames,
+  isBaselineGeneric,
+  createServiceDirResolver,
+  modelHasNewFields,
+} from './utils.js';
+import { liveSurfaceHasFunction, liveSurfaceHasFile, liveSurfaceFunctionPath } from './live-surface.js';
 
 // ---------------------------------------------------------------------------
-// Guard strategy — determines how a field assignment is wrapped
+// Guard strategy
 // ---------------------------------------------------------------------------
 
 type GuardStrategy =
@@ -13,10 +20,6 @@ type GuardStrategy =
   | { kind: 'coalesce'; fallback: string }
   | { kind: 'non-null-assert' };
 
-// ---------------------------------------------------------------------------
-// Baseline types used by planning functions
-// ---------------------------------------------------------------------------
-
 interface BaselineFieldInfo {
   type: string;
   optional: boolean;
@@ -32,9 +35,25 @@ interface BaselineInterface {
 // ---------------------------------------------------------------------------
 
 /**
- * Build a deserialization expression for a type reference.
- * @param nullFallback - fallback value for nullable inner expressions (default 'null')
+ * Decide whether a `deserialize${X}` / `serialize${X}` helper will be
+ * resolvable at compile time. A helper is callable when:
+ *   - the live SDK already exports it (live-surface knows), OR
+ *   - the emitter is producing the dep model's serializer this run, which
+ *     happens when `modelHasNewFields(dep, ctx)` says the dep needs
+ *     regeneration.
+ *
+ * When neither condition holds, expression builders fall back to passing
+ * the value through unchanged — `deserializeX(wire)` and `serializeX(model)`
+ * become `wire` / `model` respectively. Safe because elided cases imply
+ * the wire and domain shapes are identical (no IR additions).
  */
+function helperExists(helperName: string, depModelName: string, ctx: EmitterContext): boolean {
+  if (liveSurfaceHasFunction(helperName)) return true;
+  const depModel = ctx.spec.models.find((m) => m.name === depModelName);
+  if (!depModel) return false;
+  return modelHasNewFields(depModel, ctx);
+}
+
 export function deserializeExpression(
   ref: TypeRef,
   wireExpr: string,
@@ -49,11 +68,17 @@ export function deserializeExpression(
       return wireExpr;
     case 'model': {
       const name = resolveInterfaceName(ref.name, ctx);
+      // The deserialize helper may not exist if its serializer file was
+      // elided (no baseline serializer + no new fields ⇒ no generation).
+      // Fall back to passing the wire value through — the runtime shape
+      // is identical to the domain shape in those cases.
+      if (!helperExists(`deserialize${name}`, ref.name, ctx)) return wireExpr;
       return `deserialize${name}(${wireExpr})`;
     }
     case 'array':
       if (ref.items.kind === 'model') {
         const name = resolveInterfaceName(ref.items.name, ctx);
+        if (!helperExists(`deserialize${name}`, ref.items.name, ctx)) return wireExpr;
         return `${wireExpr}.map(deserialize${name})`;
       }
       return wireExpr;
@@ -83,10 +108,6 @@ export function deserializeExpression(
   }
 }
 
-/**
- * Build a serialization expression for a type reference.
- * @param nullFallback - fallback value for nullable inner expressions (default 'null')
- */
 export function serializeExpression(
   ref: TypeRef,
   domainExpr: string,
@@ -101,11 +122,13 @@ export function serializeExpression(
       return domainExpr;
     case 'model': {
       const name = resolveInterfaceName(ref.name, ctx);
+      if (!helperExists(`serialize${name}`, ref.name, ctx)) return domainExpr;
       return `serialize${name}(${domainExpr})`;
     }
     case 'array':
       if (ref.items.kind === 'model') {
         const name = resolveInterfaceName(ref.items.name, ctx);
+        if (!helperExists(`serialize${name}`, ref.items.name, ctx)) return domainExpr;
         return `${domainExpr}.map(serialize${name})`;
       }
       return domainExpr;
@@ -155,7 +178,6 @@ function serializePrimitive(ref: PrimitiveType, domainExpr: string): string {
 // Union helpers
 // ---------------------------------------------------------------------------
 
-/** Extract unique model names from a union's variants. */
 export function uniqueModelVariants(ref: UnionType): string[] {
   const modelNames = new Set<string>();
   for (const v of ref.variants) {
@@ -177,6 +199,10 @@ function renderDiscriminatorSwitch(
     const fn = `${direction}${resolved}`;
     cases.push(`case '${value}': return ${fn}(${expr} as any)`);
   }
+  // No mapping → passthrough. Without this guard, an empty `disc.mapping`
+  // emits `switch { ; default: ... }` which is invalid TypeScript syntax
+  // (the leading `;` looks like a stray statement before the first case).
+  if (cases.length === 0) return expr;
   return `(() => { switch ((${expr} as any).${disc.property}) { ${cases.join('; ')}; default: return ${expr} } })()`;
 }
 
@@ -199,7 +225,6 @@ function renderAllOfMerge(
 // Type inspection helpers
 // ---------------------------------------------------------------------------
 
-/** Check whether a TypeRef involves a function call in serialization. */
 export function needsNullGuard(ref: TypeRef): boolean {
   switch (ref.kind) {
     case 'model':
@@ -241,11 +266,6 @@ export function hasDateTimeConversion(ref: TypeRef): boolean {
   }
 }
 
-/**
- * Collect model names that will actually be called in serialize/deserialize expressions.
- * Unlike collectModelRefs (which walks all union variants), this only includes models
- * that the expression functions will actually invoke a serializer/deserializer for.
- */
 export function collectSerializedModelRefs(ref: TypeRef): string[] {
   switch (ref.kind) {
     case 'model':
@@ -270,7 +290,6 @@ export function collectSerializedModelRefs(ref: TypeRef): string[] {
   }
 }
 
-/** Return a TypeScript default value expression for a type. */
 export function defaultForType(ref: TypeRef): string | null {
   switch (ref.kind) {
     case 'literal':
@@ -414,10 +433,9 @@ export function serializerHasBaselineIncompatibility(
 }
 
 // ---------------------------------------------------------------------------
-// Field assignment planning — replaces inline if/else chains
+// Field assignment planning
 // ---------------------------------------------------------------------------
 
-/** Plan a single deserializer field assignment. */
 export function planDeserializeField(
   field: Field,
   baselineDomain: BaselineInterface | undefined,
@@ -429,8 +447,40 @@ export function planDeserializeField(
   const wire = wireFieldName(field.name);
   const wireAccess = `response.${wire}`;
   const skip = skipFormatFields.has(field.name);
-  const fallbackForNullable = field.type.kind === 'nullable' ? 'null' : 'undefined';
-  const expr = skip ? wireAccess : deserializeExpression(field.type, wireAccess, ctx, fallbackForNullable);
+
+  // Fallback selection considers both the IR field type and the baseline
+  // domain field. When baseline declares the field as `optional`
+  // (undefined-permitting) but the IR is nullable (null-only), prefer
+  // `undefined` so the deserialize output matches the baseline interface
+  // signature. Otherwise the assignment becomes
+  // `Record<...> | null → Record<...> | undefined` (TS2322).
+  const baselineDomainField = baselineDomain?.fields?.[domain];
+  const baselineDomainAcceptsNull = baselineDomainField?.type?.includes('null') ?? false;
+  let fallbackForNullable: string;
+  if (field.type.kind === 'nullable') {
+    fallbackForNullable =
+      baselineDomainField && baselineDomainField.optional && !baselineDomainAcceptsNull ? 'undefined' : 'null';
+  } else {
+    fallbackForNullable = 'undefined';
+  }
+  let expr = skip ? wireAccess : deserializeExpression(field.type, wireAccess, ctx, fallbackForNullable);
+
+  // Baseline-declared Date for an IR `string` field: the interface body
+  // uses the baseline's `Date` (line 392 in models.ts), so the serializer
+  // must convert with `new Date(...)`. The IR type doesn't carry the
+  // `format: date-time` here (the spec just said `type: string`), so
+  // `deserializeExpression` would otherwise return the raw wire access.
+  const baselineField = baselineDomain?.fields?.[domain];
+  if (
+    !skip &&
+    expr === wireAccess &&
+    baselineField?.type === 'Date' &&
+    field.type.kind === 'primitive' &&
+    field.type.type === 'string'
+  ) {
+    expr = `new Date(${wireAccess})`;
+  }
+
   const isNewField = baselineDomain && !baselineDomain.fields?.[domain];
   const effectivelyOptional = !field.required || isNewField;
 
@@ -446,13 +496,11 @@ function planDeserializeGuard(
   isNewField: boolean | null | undefined,
   baselineResponse: BaselineInterface | undefined,
 ): GuardStrategy {
-  // Optional field with function-call expression → null check
   if (effectivelyOptional && expr !== wireAccess && needsNullGuard(field.type)) {
     const fallback = field.type.kind === 'nullable' ? 'null' : 'undefined';
     return { kind: 'null-check', fallback };
   }
 
-  // Required field with direct assignment — may need coalesce fallback
   if (field.required && expr === wireAccess) {
     const wire = wireFieldName(field.name);
     const responseFieldInfo = baselineResponse?.fields?.[wire];
@@ -467,7 +515,6 @@ function planDeserializeGuard(
   return { kind: 'direct' };
 }
 
-/** Plan a single serializer field assignment. */
 export function planSerializeField(
   field: Field,
   baselineDomain: BaselineInterface | undefined,
@@ -479,8 +526,37 @@ export function planSerializeField(
   const domain = fieldName(field.name);
   const domainAccess = `model.${domain}`;
   const skip = skipFormatFields.has(field.name);
-  const fallbackForNullable = field.type.kind === 'nullable' ? 'null' : 'undefined';
-  const expr = skip ? domainAccess : serializeExpression(field.type, domainAccess, ctx, fallbackForNullable);
+
+  // Symmetric to `planDeserializeField`: when the baseline wire is
+  // `optional` (undefined) but the IR is nullable, fall back to
+  // `undefined` so the serialized output matches the baseline wire shape.
+  const baselineWireField = baselineResponse?.fields?.[wire];
+  const baselineWireAcceptsNull = baselineWireField?.type?.includes('null') ?? false;
+  let fallbackForNullable: string;
+  if (field.type.kind === 'nullable') {
+    fallbackForNullable =
+      baselineWireField && baselineWireField.optional && !baselineWireAcceptsNull ? 'undefined' : 'null';
+  } else {
+    fallbackForNullable = 'undefined';
+  }
+  let expr = skip ? domainAccess : serializeExpression(field.type, domainAccess, ctx, fallbackForNullable);
+
+  // Symmetric to `planDeserializeField`: when the baseline declares the
+  // domain field as `Date` but the IR carries a plain `string`, the
+  // serializer must call `.toISOString()` so the wire form gets a string
+  // back. Without this, the serializer assigns a `Date` model field into
+  // a `string` wire field — TS2322.
+  const baselineField = baselineDomain?.fields?.[domain];
+  if (
+    !skip &&
+    expr === domainAccess &&
+    baselineField?.type === 'Date' &&
+    field.type.kind === 'primitive' &&
+    field.type.type === 'string'
+  ) {
+    expr = field.required ? `${domainAccess}.toISOString()` : `${domainAccess}?.toISOString()`;
+  }
+
   const isNewSerField = baselineDomain && !baselineDomain.fields?.[domain];
   const effectivelyOptionalSer = !field.required || isNewSerField;
 
@@ -508,14 +584,24 @@ function planSerializeGuard(
   const wire = wireFieldName(field.name);
   const domain = fieldName(field.name);
 
-  // Function-call expression for optional/nullable fields → null check
   const shouldGuardSer = effectivelyOptionalSer || field.type.kind === 'nullable';
   if (expr !== domainAccess && needsNullGuard(field.type) && shouldGuardSer) {
-    const fallback = field.type.kind === 'nullable' ? 'null' : 'undefined';
+    let fallback: string = field.type.kind === 'nullable' ? 'null' : 'undefined';
+    // If the wire side is required but the field guard would otherwise emit
+    // `undefined`, the assignment becomes `string | undefined → string`.
+    // Pick a non-undefined fallback that satisfies the wire type:
+    //   - `null` when the wire type accepts null
+    //   - the string-defaulting `defaultForType(field.type)` (e.g. `''`)
+    //     for required-string wires
+    const baselineWireField = baselineResponse?.fields?.[wire];
+    const wireRequired = baselineWireField ? !baselineWireField.optional : field.required;
+    if (fallback === 'undefined' && wireRequired) {
+      const wireAcceptsNull = baselineWireField?.type?.includes('null');
+      fallback = wireAcceptsNull ? 'null' : (defaultForType(field.type) ?? 'undefined');
+    }
     return { kind: 'null-check', fallback };
   }
 
-  // Optional domain → required wire: needs coalesce or assert
   const baselineWireField = baselineResponse?.fields?.[wire];
   const baselineDomainField = baselineDomain?.fields?.[domain];
   const isNewFieldOnExistingDomain = baselineDomain && !baselineDomainField;
@@ -532,7 +618,6 @@ function planSerializeGuard(
     return { kind: 'non-null-assert' };
   }
 
-  // Nullable with direct assignment → may need coalesce for domain-response mismatch
   if (field.type.kind === 'nullable' && expr === domainAccess) {
     const domainWireField2 = wireFieldName(field.name);
     const responseBaselineField2 = baselineResponse?.fields?.[domainWireField2];
@@ -544,26 +629,23 @@ function planSerializeGuard(
       responseBaselineField2.optional;
     const fieldEffectivelyOptional = !field.required || !!isNewSerField || !!domainResponseMismatch;
     if (fieldEffectivelyOptional) {
-      return { kind: 'coalesce', fallback: 'null' };
+      // The wire side may not accept `null` (e.g. `metadata?: Record<...>`).
+      // Fall back to `undefined` in that case so the assignment matches the
+      // baseline wire field's actual type.
+      const wireAcceptsNull = responseBaselineField2?.type?.includes('null') ?? true;
+      const fallback = wireAcceptsNull ? 'null' : 'undefined';
+      return { kind: 'coalesce', fallback };
     }
   }
 
   return { kind: 'direct' };
 }
 
-// ---------------------------------------------------------------------------
-// Field assignment emission — single function for all guard strategies
-// ---------------------------------------------------------------------------
-
 function emitAssignment(lhs: string, expr: string, accessExpr: string, guard: GuardStrategy): string {
   switch (guard.kind) {
     case 'direct':
       return `  ${lhs}: ${expr},`;
     case 'null-check':
-      // If the expression already contains a null guard from nullable type handling
-      // (e.g., `response.x != null ? deserializeFoo(response.x) : null`),
-      // emit it directly — the fallback was baked into the expression.
-      // Otherwise, wrap with an outer null check using the accessor.
       if (expr.includes(`${accessExpr} != null ?`)) {
         return `  ${lhs}: ${expr},`;
       }
@@ -587,7 +669,6 @@ interface SerializerContext {
   ctx: EmitterContext;
 }
 
-/** Build the import block for a serializer file. */
 export function buildSerializerImports(
   model: Model,
   serializerPath: string,
@@ -598,7 +679,10 @@ export function buildSerializerImports(
 ): string[] {
   const lines: string[] = [];
   const interfacePath = `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`;
-  lines.push(`import type { ${domainName}, ${responseName} } from '${relativeImport(serializerPath, interfacePath)}';`);
+  // Single-form baselines (`wireInterfaceName` returns the same name as
+  // `domainName`) only export one symbol — don't duplicate the import.
+  const symbols = domainName === responseName ? domainName : `${domainName}, ${responseName}`;
+  lines.push(`import type { ${symbols} } from '${relativeImport(serializerPath, interfacePath)}';`);
 
   const nestedModelRefs = new Set<string>();
   for (const field of model.fields) {
@@ -610,13 +694,71 @@ export function buildSerializerImports(
   for (const dep of nestedModelRefs) {
     const depService = sctx.modelToService.get(dep);
     const depDir = sctx.resolveDir(depService);
-    const depSerializerPath = `src/${depDir}/serializers/${fileName(dep)}.serializer.ts`;
     const depName = resolveInterfaceName(dep, sctx.ctx);
+
+    // Locate the serializer file, in priority order:
+    //   1. The actual file containing `deserialize${depName}` per
+    //      live-surface (e.g. `deserializeAuditLogSchema` lives in
+    //      `create-audit-log-schema.serializer.ts`, not in the predictable
+    //      `audit-log-schema.serializer.ts`).
+    //   2. The baseline interface's adjacent serializer file path.
+    //   3. The IR-name path — this is where the emitter writes the
+    //      serializer it's producing this run.
+    const baselineSrc = (sctx.ctx.apiSurface?.interfaces?.[depName] as { sourceFile?: string } | undefined)?.sourceFile;
+    const baselineSerializerPath = baselineSrc
+      ? baselineSrc.replace('/interfaces/', '/serializers/').replace('.interface.ts', '.serializer.ts')
+      : null;
+    const irNameSerializerPath = `src/${depDir}/serializers/${fileName(dep)}.serializer.ts`;
+
+    const liveDeserPath = liveSurfaceFunctionPath(`deserialize${depName}`);
+    const liveSerPath = liveSurfaceFunctionPath(`serialize${depName}`);
+    const depSerializerPath =
+      liveDeserPath ??
+      liveSerPath ??
+      (baselineSerializerPath && liveSurfaceHasFile(baselineSerializerPath)
+        ? baselineSerializerPath
+        : irNameSerializerPath);
+
     const rel = relativeImport(serializerPath, depSerializerPath);
-    // Check the canonical name for dedup'd models
     const canon = sctx.dedup.get(dep);
     const depSkipSerialize =
       sctx.skippedSerializeModels.has(dep) || (canon != null && sctx.skippedSerializeModels.has(canon));
+
+    // Decide whether this serializer is reachable at runtime:
+    //   - file on disk → honor what it exports (hasDeser/hasSer)
+    //   - file NOT on disk → only safe to import if the emitter is
+    //     producing the dep's serializer this run, which only happens
+    //     when `modelHasNewFields` says the dep needs regeneration.
+    //
+    // Skip the import otherwise. The serializer body falls back to a
+    // pass-through expression when it can't call the helper.
+    const hasDeser = liveSurfaceHasFunction(`deserialize${depName}`);
+    const hasSer = liveSurfaceHasFunction(`serialize${depName}`);
+    const fileExists = liveSurfaceHasFile(depSerializerPath);
+    if (fileExists && !hasDeser && !hasSer) continue;
+    if (!fileExists) {
+      const depModel = sctx.ctx.spec.models.find((m) => m.name === dep);
+      const willGenerateSerializer = depModel ? modelHasNewFields(depModel, sctx.ctx) : true;
+      if (!willGenerateSerializer) continue;
+    }
+
+    // Mixed: file exists, only one of the pair is exported. Import only
+    // what's present so we don't synthesize a missing symbol. The body
+    // emitter's `bodyArgExpr` already falls through when it sees a missing
+    // serialize function.
+    if (fileExists && depSkipSerialize) {
+      if (hasDeser) lines.push(`import { deserialize${depName} } from '${rel}';`);
+      continue;
+    }
+    if (fileExists && !hasSer) {
+      lines.push(`import { deserialize${depName} } from '${rel}';`);
+      continue;
+    }
+    if (fileExists && !hasDeser) {
+      lines.push(`import { serialize${depName} } from '${rel}';`);
+      continue;
+    }
+
     if (depSkipSerialize) {
       lines.push(`import { deserialize${depName} } from '${rel}';`);
     } else {
@@ -627,7 +769,6 @@ export function buildSerializerImports(
   return lines;
 }
 
-/** Build the set of field names where format conversion should be skipped. */
 export function buildSkipFormatFields(model: Model, baselineDomain: BaselineInterface | undefined): Set<string> {
   const skipFormatFields = new Set<string>();
   if (baselineDomain) {
@@ -635,7 +776,6 @@ export function buildSkipFormatFields(model: Model, baselineDomain: BaselineInte
       if (skipFormatFields.has(field.name)) continue;
       const baselineField = baselineDomain.fields?.[fieldName(field.name)];
       if (baselineField && !baselineField.type.includes('Date') && hasFormatConversion(field.type)) {
-        // Always convert date-time fields to Date regardless of baseline
         if (hasDateTimeConversion(field.type)) continue;
         skipFormatFields.add(field.name);
       }
@@ -644,7 +784,6 @@ export function buildSkipFormatFields(model: Model, baselineDomain: BaselineInte
   return skipFormatFields;
 }
 
-/** Check if serialize should be skipped (baseline incompat or cascading dependency). */
 export function shouldSkipSerializeForModel(
   model: Model,
   baselineResponse: BaselineInterface | undefined,
@@ -673,7 +812,6 @@ export function shouldSkipSerializeForModel(
   return shouldSkip;
 }
 
-/** Emit deserializer + serializer body lines for a model. */
 export function emitSerializerBody(
   model: Model,
   domainName: string,
@@ -687,7 +825,6 @@ export function emitSerializerBody(
 ): string[] {
   const lines: string[] = [];
 
-  // Deserialize function (wire → domain)
   const seenDeserFields = new Set<string>();
   const deserParamPrefix = model.fields.length === 0 ? '_' : '';
   lines.push(`export const deserialize${domainName} = ${typeParams.decl}(`);
@@ -702,7 +839,6 @@ export function emitSerializerBody(
   }
   lines.push('});');
 
-  // Serialize function (domain → wire)
   if (!shouldSkipSerialize) {
     const serParamPrefix = model.fields.length === 0 ? '_' : '';
     lines.push('');

package/src/node/fixtures.ts

@@ -1,13 +1,8 @@
 import type { Model, TypeRef, Enum, EmitterContext } from '@workos/oagen';
 import { wireFieldName, fileName, resolveServiceDir } from './naming.js';
-import { resolveResourceClassName } from './resources.js';
+import { resolveResourceClassName, resolveResourceDir } from './resources.js';
 import { createServiceDirResolver, assignModelsToServices, isListMetadataModel, isListWrapperModel } from './utils.js';
 
-/**
- * Prefix mapping for generating realistic ID fixture values.
- * When a field named "id" belongs to a model whose name matches a key here,
- * the generated ID will be prefixed accordingly (e.g. "conn_01234").
- */
 export const ID_PREFIXES: Record<string, string> = {
   Connection: 'conn_',
   Organization: 'org_',
@@ -24,10 +19,6 @@ export const ID_PREFIXES: Record<string, string> = {
   PasswordReset: 'password_reset_',
 };
 
-/**
- * Generate JSON fixture files for test data.
- * Each model that appears as a response gets a fixture in wire format (snake_case).
- */
 export function generateFixtures(
   spec: {
     models: Model[];
@@ -48,12 +39,11 @@ export function generateFixtures(
   const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
   const files: { path: string; content: string }[] = [];
 
-  // Only generate fixtures for models reachable from non-event operations
   const fixtureSeeds = new Set<string>();
   for (const svc of spec.services) {
     if (svc.name.toLowerCase() === 'events') continue;
     for (const op of svc.operations) {
-      const collectFromRef = (t: import('@workos/oagen').TypeRef | undefined): void => {
+      const collectFromRef = (t: TypeRef | undefined): void => {
         if (!t) return;
         if (t.kind === 'model') fixtureSeeds.add(t.name);
         if (t.kind === 'array') collectFromRef(t.items);
@@ -75,7 +65,7 @@ export function generateFixtures(
     const m = fixtureModelMap.get(name);
     if (!m) continue;
     for (const field of m.fields) {
-      const walk = (t: import('@workos/oagen').TypeRef): void => {
+      const walk = (t: TypeRef): void => {
         if (t.kind === 'model' && !fixtureReachable.has(t.name)) fixtureQueue.push(t.name);
         if (t.kind === 'array') walk(t.items);
         if (t.kind === 'nullable') walk(t.inner);
@@ -84,6 +74,7 @@ export function generateFixtures(
       walk(field.type);
     }
   }
+
   const seenFixturePaths = new Set<string>();
   for (const model of spec.models) {
     if (!fixtureReachable.has(model.name)) continue;
@@ -94,8 +85,6 @@ export function generateFixtures(
     const dirName = resolveDir(service);
     const fixturePath = `src/${dirName}/fixtures/${fileName(model.name)}.json`;
 
-    // After noise suffix stripping, multiple models may resolve to the same
-    // fixture path (e.g., OrganizationDto and Organization).  Skip duplicates.
     if (seenFixturePaths.has(fixturePath)) continue;
     seenFixturePaths.add(fixturePath);
 
@@ -107,16 +96,13 @@ export function generateFixtures(
     });
   }
 
-  // Generate list fixtures for models that appear in paginated responses
   for (const service of spec.services) {
     const resolvedName = ctx ? resolveResourceClassName(service, ctx) : service.name;
-    const serviceDir = resolveServiceDir(resolvedName);
+    const serviceDir = ctx ? resolveResourceDir(service, ctx) : resolveServiceDir(resolvedName);
     for (const op of service.operations) {
       if (op.pagination) {
         let itemModel = op.pagination.itemType.kind === 'model' ? modelMap.get(op.pagination.itemType.name) : null;
         if (itemModel) {
-          // Detect if the "item" model is actually a list wrapper (has `data` array + `list_metadata`).
-          // If so, unwrap to the actual item type to avoid double-nesting in fixtures.
           const unwrapped = unwrapListModel(itemModel, modelMap);
           if (unwrapped) {
             itemModel = unwrapped;
@@ -141,12 +127,6 @@ export function generateFixtures(
   return files;
 }
 
-/**
- * Detect if a model is a list wrapper (has a `data` array field and a `list_metadata` field).
- * If so, return the inner item model from the `data` array. Otherwise return null.
- * This prevents double-nesting when the pagination itemType points to a list wrapper
- * instead of the actual item model.
- */
 export function unwrapListModel(model: Model, modelMap: Map<string, Model>): Model | null {
   const dataField = model.fields.find((f) => f.name === 'data');
   const hasListMetadata = model.fields.some((f) => f.name === 'list_metadata' || f.name === 'listMetadata');
@@ -159,7 +139,7 @@ export function unwrapListModel(model: Model, modelMap: Map<string, Model>): Mod
   return null;
 }
 
-function generateModelFixture(
+export function generateModelFixture(
   model: Model,
   modelMap: Map<string, Model>,
   enumMap: Map<string, Enum>,
@@ -168,7 +148,6 @@ function generateModelFixture(
 
   for (const field of model.fields) {
     const wireName = wireFieldName(field.name);
-    // Prefer the OpenAPI example value when available on the field
     if (field.example !== undefined) {
       fixture[wireName] = field.example;
     } else {
@@ -181,14 +160,14 @@ function generateModelFixture(
 
 function generateFieldValue(
   ref: TypeRef,
-  fieldName: string,
+  fName: string,
   modelName: string,
   modelMap: Map<string, Model>,
   enumMap: Map<string, Enum>,
 ): any {
   switch (ref.kind) {
     case 'primitive':
-      return generatePrimitiveValue(ref.type, ref.format, fieldName, modelName);
+      return generatePrimitiveValue(ref.type, ref.format, fName, modelName);
     case 'literal':
       return ref.value;
     case 'enum': {
@@ -201,21 +180,20 @@ function generateFieldValue(
       return {};
     }
     case 'array': {
-      // For array<enum>, use actual enum values instead of a single generated item
       if (ref.items.kind === 'enum') {
         const e = enumMap.get(ref.items.name);
         if (e && e.values.length > 0) {
           return e.values.map((v) => v.value);
         }
       }
-      const item = generateFieldValue(ref.items, fieldName, modelName, modelMap, enumMap);
+      const item = generateFieldValue(ref.items, fName, modelName, modelMap, enumMap);
       return [item];
     }
     case 'nullable':
-      return generateFieldValue(ref.inner, fieldName, modelName, modelMap, enumMap);
+      return generateFieldValue(ref.inner, fName, modelName, modelMap, enumMap);
     case 'union':
       if (ref.variants.length > 0) {
-        return generateFieldValue(ref.variants[0], fieldName, modelName, modelMap, enumMap);
+        return generateFieldValue(ref.variants[0], fName, modelName, modelMap, enumMap);
       }
       return null;
     case 'map':