@workos/oagen-emitters 0.0.1 → 0.2.1

package/src/node/models.ts

@@ -1,48 +1,121 @@
-import type { Model, Field, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
-import { walkTypeRef } from '@workos/oagen';
+import type { Model, Field, TypeRef, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { mapTypeRef, mapWireTypeRef } from './type-map.js';
+import { fieldName, wireFieldName, fileName, resolveInterfaceName, wireInterfaceName } from './naming.js';
 import {
-  fieldName,
-  wireFieldName,
-  fileName,
-  serviceDirName,
-  resolveInterfaceName,
-  buildServiceNameMap,
-  wireInterfaceName,
-} from './naming.js';
-import { assignModelsToServices, collectFieldDependencies, docComment } from './utils.js';
-
-/** Built-in TypeScript types that are always available (no import needed). */
-const BUILTINS = new Set([
-  'Record',
-  'Promise',
-  'Array',
-  'Map',
-  'Set',
-  'Date',
-  'string',
-  'number',
-  'boolean',
-  'void',
-  'null',
-  'undefined',
-  'any',
-  'never',
-  'unknown',
-  'true',
-  'false',
-]);
+  collectFieldDependencies,
+  docComment,
+  buildGenericModelDefaults,
+  pruneUnusedImports,
+  TS_BUILTINS,
+  detectStringDateConvention,
+  buildKnownTypeNames,
+  isBaselineGeneric,
+  createServiceDirResolver,
+  isListMetadataModel,
+  isListWrapperModel,
+  buildDeduplicationMap,
+} from './utils.js';
+import { assignEnumsToServices } from './enums.js';
+
+/**
+ * Detect baseline interfaces that are generic (have type parameters) even though
+ * the IR model has no typeParams (OpenAPI doesn't support generics).
+ *
+ * Heuristic: if any field type in the baseline interface contains a PascalCase
+ * name that isn't a known model, enum, or builtin, it's likely a type parameter
+ * (e.g., `CustomAttributesType`), indicating the interface is generic.
+ *
+ * When detected, adds a default generic type arg so references like `Profile`
+ * become `Profile<Record<string, unknown>>`.
+ */
+function enrichGenericDefaultsFromBaseline(
+  genericDefaults: Map<string, string>,
+  models: Model[],
+  ctx: EmitterContext,
+  resolveDir: (irService: string | undefined) => string,
+  modelToService: Map<string, string>,
+): void {
+  if (!ctx.apiSurface?.interfaces) return;
+  const knownNames = buildKnownTypeNames(models, ctx);
+
+  for (const model of models) {
+    if (genericDefaults.has(model.name)) continue; // IR already handles it
+    const domainName = resolveInterfaceName(model.name, ctx);
+    const baseline = ctx.apiSurface.interfaces[domainName];
+    if (!baseline?.fields) continue;
+
+    // Only enrich generic defaults for models whose baseline file will be
+    // preserved via skipIfExists (paths match).  If the file is generated
+    // fresh in a new directory, it won't have generics, so references
+    // to it don't need type args.
+    const generatedPath = `src/${resolveDir(modelToService.get(model.name))}/interfaces/${fileName(model.name)}.interface.ts`;
+    const baselineSourceFile = (baseline as any).sourceFile as string | undefined;
+    if (baselineSourceFile && baselineSourceFile !== generatedPath) continue;
+
+    if (isBaselineGeneric(baseline.fields, knownNames)) {
+      genericDefaults.set(model.name, '<Record<string, unknown>>');
+    }
+  }
+}
 
 export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
   if (models.length === 0) return [];
 
-  const modelToService = assignModelsToServices(models, ctx.spec.services);
-  const serviceNameMap = buildServiceNameMap(ctx.spec.services, ctx);
-  const resolveDir = (irService: string | undefined) =>
-    irService ? serviceDirName(serviceNameMap.get(irService) ?? irService) : 'common';
+  const { modelToService, resolveDir } = createServiceDirResolver(models, ctx.spec.services, ctx);
+  // Detect whether the existing SDK uses string dates (ISO 8601) rather than Date objects.
+  // When detected, newly generated models also use string to maintain consistency.
+  const useStringDates = detectStringDateConvention(models, ctx);
+  const genericDefaults = buildGenericModelDefaults(ctx.spec.models);
+  // Enrich genericDefaults from baseline interfaces that appear to be generic.
+  // The IR doesn't carry typeParams for models parsed from OpenAPI (which has no
+  // generics), but the existing SDK may have hand-written generic interfaces
+  // (e.g., Profile<CustomAttributesType>).  Detect these by checking if any
+  // field type contains a PascalCase name that isn't a known model, enum, or builtin.
+  enrichGenericDefaultsFromBaseline(genericDefaults, models, ctx, resolveDir, modelToService);
+  const typeRefOpts = useStringDates ? { stringDates: true, genericDefaults } : { genericDefaults };
+  const wireTypeRefOpts = { genericDefaults };
   const files: GeneratedFile[] = [];
 
+  // Detect structurally identical or same-name models — emit type aliases for duplicates
+  const dedup = buildDeduplicationMap(models, ctx);
+
   for (const model of models) {
+    // Fix #4: Skip per-domain ListMetadata interfaces — the shared ListMetadata type covers these
+    if (isListMetadataModel(model)) continue;
+
+    // Fix #6: Skip per-domain list wrapper interfaces — the shared List<T>/ListResponse<T> covers these
+    if (isListWrapperModel(model)) continue;
+
+    // Deduplication: if this model is structurally identical to a canonical model,
+    // emit a type alias instead of a full interface.
+    const canonicalName = dedup.get(model.name);
+    if (canonicalName) {
+      const domainName = resolveInterfaceName(model.name, ctx);
+      const responseName = wireInterfaceName(domainName);
+      const canonDomainName = resolveInterfaceName(canonicalName, ctx);
+      const canonResponseName = wireInterfaceName(canonDomainName);
+      const service = modelToService.get(model.name);
+      const dirName = resolveDir(service);
+      const canonService = modelToService.get(canonicalName);
+      const canonDir = resolveDir(canonService);
+      const canonRelPath =
+        canonDir === dirName
+          ? `./${fileName(canonicalName)}.interface`
+          : `../../${canonDir}/interfaces/${fileName(canonicalName)}.interface`;
+      const aliasLines = [
+        `import type { ${canonDomainName}, ${canonResponseName} } from '${canonRelPath}';`,
+        '',
+        `export type ${domainName} = ${canonDomainName};`,
+        `export type ${responseName} = ${canonResponseName};`,
+      ];
+      files.push({
+        path: `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`,
+        content: aliasLines.join('\n'),
+        skipIfExists: true,
+      });
+      continue;
+    }
+
     const service = modelToService.get(model.name);
     const dirName = resolveDir(service);
     const domainName = resolveInterfaceName(model.name, ctx);
@@ -50,6 +123,17 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const deps = collectFieldDependencies(model);
     const lines: string[] = [];
 
+    // Exclude the current model from generic defaults to avoid self-referencing
+    // (e.g., Profile's own fields should use TCustom, not Profile<Record<...>>)
+    let modelTypeRefOpts = typeRefOpts;
+    let modelWireTypeRefOpts = wireTypeRefOpts;
+    if (genericDefaults.has(model.name)) {
+      const filteredDefaults = new Map(genericDefaults);
+      filteredDefaults.delete(model.name);
+      modelTypeRefOpts = { ...typeRefOpts, genericDefaults: filteredDefaults };
+      modelWireTypeRefOpts = { genericDefaults: filteredDefaults };
+    }
+
     // Baseline interface data (for compat field type matching)
     const baselineDomain = ctx.apiSurface?.interfaces?.[domainName];
     const baselineResponse = ctx.apiSurface?.interfaces?.[responseName];
@@ -71,9 +155,11 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // Pre-pass: discover baseline type names that aren't directly importable.
     // For each unresolvable name we either:
     //   1. Import the real type from another service (if it exists as an enum/model there)
-    //   2. Create a local type declaration as a fallback
+    //   2. Create a local type alias from a suffix match
+    //   3. Mark as unresolvable — the field will fall back to the IR-generated type
     const typeDecls = new Map<string, string>(); // aliasName → type expression
     const crossServiceImports = new Map<string, { name: string; relPath: string }>(); // extra imports
+    const unresolvableNames = new Set<string>(); // names that can't be resolved — forces IR fallback
     const enumToService = assignEnumsToServices(ctx.spec.enums, ctx.spec.services);
     // Build a lookup: resolved enum name → IR enum name
     const resolvedEnumNames = new Map<string, string>();
@@ -92,10 +178,11 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
         if (!names) continue;
 
         for (const name of names) {
-          if (BUILTINS.has(name)) continue;
+          if (TS_BUILTINS.has(name)) continue;
           if (importableNames.has(name)) continue;
           if (typeDecls.has(name)) continue;
           if (crossServiceImports.has(name)) continue;
+          if (unresolvableNames.has(name)) continue;
 
           // Check if this name exists as an enum in another service —
           // import the actual type so the extractor sees the real name
@@ -119,11 +206,10 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
             typeDecls.set(name, candidates[0]);
             importableNames.add(name);
           } else {
-            // No suffix match — create a type alias using the IR-generated type
-            const innerType = field.type.kind === 'nullable' ? field.type.inner : field.type;
-            const typeExpr = mapTypeRef(innerType);
-            typeDecls.set(name, typeExpr);
-            importableNames.add(name);
+            // Cannot resolve this baseline type name — mark it so the field
+            // falls back to the IR-generated type instead of the baseline.
+            // This avoids creating type aliases that reference undefined types.
+            unresolvableNames.add(name);
           }
         }
       }
@@ -157,75 +243,111 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     }
     if (typeDecls.size > 0) lines.push('');
 
-    // Type params (generics)
-    const typeParams = renderTypeParams(model);
+    // Type params (generics) — pass genericDefaults so baseline-detected generics
+    // also get type parameter declarations on the interface itself.
+    const typeParams = renderTypeParams(model, genericDefaults);
 
     // Domain interface (camelCase fields) — deduplicate by camelCase name
     const seenDomainFields = new Set<string>();
     if (model.description) {
       lines.push(...docComment(model.description));
     }
-    lines.push(`export interface ${domainName}${typeParams} {`);
-    for (const field of model.fields) {
-      const domainFieldName = fieldName(field.name);
-      if (seenDomainFields.has(domainFieldName)) continue;
-      seenDomainFields.add(domainFieldName);
-      if (field.description || field.deprecated) {
-        const parts: string[] = [];
-        if (field.description) parts.push(field.description);
-        if (field.deprecated) parts.push('@deprecated');
-        lines.push(...docComment(parts.join('\n'), 2));
-      }
-      const baselineField = baselineDomain?.fields?.[domainFieldName];
-      // For the domain interface, also check that the response baseline's optionality
-      // is compatible — the serializer reads from the response type and assigns to the domain type.
-      // If the domain baseline says required but the response baseline says optional,
-      // the serializer would produce T | undefined for a field expecting T.
-      const domainWireField = wireFieldName(field.name);
-      const responseBaselineField = baselineResponse?.fields?.[domainWireField];
-      const domainResponseOptionalMismatch =
-        baselineField && !baselineField.optional && responseBaselineField && responseBaselineField.optional;
-      if (
-        baselineField &&
-        !domainResponseOptionalMismatch &&
-        baselineTypeResolvable(baselineField.type, importableNames) &&
-        baselineFieldCompatible(baselineField, field)
-      ) {
-        const opt = baselineField.optional ? '?' : '';
-        lines.push(`  ${domainFieldName}${opt}: ${baselineField.type};`);
-      } else {
-        const opt = !field.required ? '?' : '';
-        lines.push(`  ${domainFieldName}${opt}: ${mapTypeRef(field.type)};`);
+    if (model.fields.length === 0) {
+      lines.push(`export type ${domainName}${typeParams} = object;`);
+    } else {
+      lines.push(`export interface ${domainName}${typeParams} {`);
+      for (const field of model.fields) {
+        const domainFieldName = fieldName(field.name);
+        if (seenDomainFields.has(domainFieldName)) continue;
+        seenDomainFields.add(domainFieldName);
+        if (field.description || field.deprecated || field.readOnly || field.writeOnly || field.default !== undefined) {
+          const parts: string[] = [];
+          if (field.description) parts.push(field.description);
+          if (field.readOnly) parts.push('@readonly');
+          if (field.writeOnly) parts.push('@writeonly');
+          if (field.default !== undefined) parts.push(`@default ${JSON.stringify(field.default)}`);
+          if (field.deprecated) parts.push('@deprecated');
+          lines.push(...docComment(parts.join('\n'), 2));
+        }
+        const baselineField = baselineDomain?.fields?.[domainFieldName];
+        // For the domain interface, also check that the response baseline's optionality
+        // is compatible — the serializer reads from the response type and assigns to the domain type.
+        // If the domain baseline says required but the response baseline says optional,
+        // the serializer would produce T | undefined for a field expecting T.
+        const domainWireField = wireFieldName(field.name);
+        const responseBaselineField = baselineResponse?.fields?.[domainWireField];
+        const domainResponseOptionalMismatch =
+          baselineField && !baselineField.optional && responseBaselineField && responseBaselineField.optional;
+        const readonlyPrefix = field.readOnly ? 'readonly ' : '';
+        if (
+          baselineField &&
+          !domainResponseOptionalMismatch &&
+          baselineTypeResolvable(baselineField.type, importableNames) &&
+          baselineFieldCompatible(baselineField, field)
+        ) {
+          const opt = baselineField.optional ? '?' : '';
+          lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${baselineField.type};`);
+        } else {
+          // When a baseline exists for this model, new fields (not present in the
+          // baseline) are generated as optional.  The merger can deep-merge new
+          // fields into existing interfaces, but it cannot update existing
+          // deserializer function bodies.  Making the field optional prevents a
+          // type error where the interface requires a field that the preserved
+          // deserializer never populates.
+          const isNewFieldOnExistingModel = baselineDomain && !baselineField;
+          // Also make the field optional when the response baseline has it as optional
+          // but the domain baseline has it as required — the deserializer reads from
+          // the response type, so if the response field is optional, the domain value
+          // may be undefined.
+          // Additionally, when a baseline exists for the RESPONSE interface but NOT the
+          // domain interface, fields that are new on the response baseline become optional
+          // in the wire type. The domain type must also be optional to match, otherwise
+          // the deserializer produces T | undefined for a field typed as T.
+          const isNewFieldOnExistingResponse = !baselineDomain && baselineResponse && !responseBaselineField;
+          const opt =
+            !field.required ||
+            isNewFieldOnExistingModel ||
+            domainResponseOptionalMismatch ||
+            isNewFieldOnExistingResponse
+              ? '?'
+              : '';
+          lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${mapTypeRef(field.type, modelTypeRefOpts)};`);
+        }
       }
-    }
-    lines.push('}');
+      lines.push('}');
+    } // close else for non-empty domain interface
     lines.push('');
 
     // Wire/response interface (snake_case fields) — deduplicate by snake_case name
     const seenWireFields = new Set<string>();
-    lines.push(`export interface ${responseName}${typeParams} {`);
-    for (const field of model.fields) {
-      const wireField = wireFieldName(field.name);
-      if (seenWireFields.has(wireField)) continue;
-      seenWireFields.add(wireField);
-      const baselineField = baselineResponse?.fields?.[wireField];
-      if (
-        baselineField &&
-        baselineTypeResolvable(baselineField.type, importableNames) &&
-        baselineFieldCompatible(baselineField, field)
-      ) {
-        const opt = baselineField.optional ? '?' : '';
-        lines.push(`  ${wireField}${opt}: ${baselineField.type};`);
-      } else {
-        const opt = !field.required ? '?' : '';
-        lines.push(`  ${wireField}${opt}: ${mapWireTypeRef(field.type)};`);
+    if (model.fields.length === 0) {
+      lines.push(`export type ${responseName}${typeParams} = object;`);
+    } else {
+      lines.push(`export interface ${responseName}${typeParams} {`);
+      for (const field of model.fields) {
+        const wireField = wireFieldName(field.name);
+        if (seenWireFields.has(wireField)) continue;
+        seenWireFields.add(wireField);
+        const baselineField = baselineResponse?.fields?.[wireField];
+        if (
+          baselineField &&
+          baselineTypeResolvable(baselineField.type, importableNames) &&
+          baselineFieldCompatible(baselineField, field)
+        ) {
+          const opt = baselineField.optional ? '?' : '';
+          lines.push(`  ${wireField}${opt}: ${baselineField.type};`);
+        } else {
+          const isNewFieldOnExistingModel = baselineResponse && !baselineField;
+          const opt = !field.required || isNewFieldOnExistingModel ? '?' : '';
+          lines.push(`  ${wireField}${opt}: ${mapWireTypeRef(field.type, modelWireTypeRefOpts)};`);
+        }
       }
-    }
-    lines.push('}');
+      lines.push('}');
+    } // close else for non-empty wire interface
 
     files.push({
       path: `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`,
-      content: lines.join('\n'),
+      content: pruneUnusedImports(lines).join('\n'),
       skipIfExists: true,
     });
   }
@@ -246,7 +368,7 @@ function baselineTypeResolvable(typeStr: string, importableNames: Set<string>):
   if (!matches) return true;
 
   for (const name of matches) {
-    if (BUILTINS.has(name)) continue;
+    if (TS_BUILTINS.has(name)) continue;
     if (importableNames.has(name)) continue;
     return false;
   }
@@ -286,38 +408,43 @@ function baselineFieldCompatible(baselineField: { type: string; optional: boolea
   // the serializer produces a definite value but the interface is looser — that's OK
   // (the domain type is wider than the serializer output)
 
+  // If the baseline type is Record<string, unknown> but the IR field has a more specific
+  // type (model, enum, or union with named variants), prefer the IR type for better type safety
+  if (baselineField.type === 'Record<string, unknown>' && hasSpecificIRType(irField.type)) {
+    return false;
+  }
+
   return true;
 }
 
-function renderTypeParams(model: Model): string {
-  if (!model.typeParams?.length) return '';
+/** Check if an IR type is more specific than Record<string, unknown>. */
+function hasSpecificIRType(ref: TypeRef): boolean {
+  switch (ref.kind) {
+    case 'model':
+    case 'enum':
+      return true;
+    case 'union':
+      // A union with named model/enum variants is more specific
+      return ref.variants.some((v) => v.kind === 'model' || v.kind === 'enum');
+    case 'nullable':
+      return hasSpecificIRType(ref.inner);
+    default:
+      return false;
+  }
+}
+
+function renderTypeParams(model: Model, genericDefaults?: Map<string, string>): string {
+  if (!model.typeParams?.length) {
+    // Fallback: if genericDefaults indicates this model is generic (detected
+    // from the baseline), generate a default generic type parameter declaration.
+    if (genericDefaults?.has(model.name)) {
+      return '<GenericType extends Record<string, unknown> = Record<string, unknown>>';
+    }
+    return '';
+  }
   const params = model.typeParams.map((tp) => {
     const def = tp.default ? ` = ${mapTypeRef(tp.default)}` : '';
     return `${tp.name}${def}`;
   });
   return `<${params.join(', ')}>`;
 }
-
-function assignEnumsToServices(enums: { name: string }[], services: Service[]): Map<string, string> {
-  const enumToService = new Map<string, string>();
-  const enumNames = new Set(enums.map((e) => e.name));
-  for (const service of services) {
-    for (const op of service.operations) {
-      const refs = new Set<string>();
-      const collect = (ref: any) => {
-        walkTypeRef(ref, { enum: (r: any) => refs.add(r.name) });
-      };
-      if (op.requestBody) collect(op.requestBody);
-      collect(op.response);
-      for (const p of [...op.pathParams, ...op.queryParams, ...op.headerParams]) {
-        collect(p.type);
-      }
-      for (const name of refs) {
-        if (enumNames.has(name) && !enumToService.has(name)) {
-          enumToService.set(name, service.name);
-        }
-      }
-    }
-  }
-  return enumToService;
-}

package/src/node/naming.ts

@@ -66,26 +66,130 @@ export function buildServiceNameMap(services: Service[], ctx: EmitterContext): M
   return map;
 }
 
+/**
+ * Explicit method name overrides for operations where the spec's operationId
+ * does not match the desired SDK method name and the spec cannot be changed.
+ * Key: "HTTP_METHOD /path", Value: camelCase method name.
+ */
+const METHOD_NAME_OVERRIDES: Record<string, string> = {
+  'POST /portal/generate_link': 'generatePortalLink',
+};
+
+/**
+ * Explicit service directory overrides. Maps a resolved PascalCase service name
+ * to a target directory (kebab-case). Use this when the spec's tag grouping
+ * does not match the desired SDK directory layout and the spec cannot be changed.
+ */
+const SERVICE_DIR_OVERRIDES: Record<string, string> = {
+  ApplicationClientSecrets: 'workos-connect',
+  Applications: 'workos-connect',
+  Connections: 'sso',
+  Directories: 'directory-sync',
+  DirectoryGroups: 'directory-sync',
+  DirectoryUsers: 'directory-sync',
+  FeatureFlagsTargets: 'feature-flags',
+  MultiFactorAuth: 'mfa',
+  MultiFactorAuthChallenges: 'mfa',
+  OrganizationsApiKeys: 'organizations',
+  WebhooksEndpoints: 'webhooks',
+  UserManagementAuthentication: 'user-management',
+  UserManagementCorsOrigins: 'user-management',
+  UserManagementDataProviders: 'user-management',
+  UserManagementInvitations: 'user-management',
+  UserManagementJWTTemplate: 'user-management',
+  UserManagementMagicAuth: 'user-management',
+  UserManagementMultiFactorAuthentication: 'user-management',
+  UserManagementOrganizationMembership: 'user-management',
+  UserManagementRedirectUris: 'user-management',
+  UserManagementSessionTokens: 'user-management',
+  UserManagementUsers: 'user-management',
+  UserManagementUsersAuthorizedApplications: 'user-management',
+  WorkOSConnect: 'workos-connect',
+};
+
+/**
+ * Maps a service (by PascalCase name) to the existing hand-written class that
+ * already covers its endpoints. When a service appears here:
+ *   - `resolveClassName` returns the target class (so generated code merges in)
+ *   - `isServiceCoveredByExisting` returns true
+ *   - `hasMethodsAbsentFromBaseline` checks the target class for missing methods,
+ *     so new endpoints are added to the existing class rather than silently dropped
+ */
+export const SERVICE_COVERED_BY: Record<string, string> = {
+  Connections: 'SSO',
+  Directories: 'DirectorySync',
+  DirectoryGroups: 'DirectorySync',
+  DirectoryUsers: 'DirectorySync',
+  FeatureFlagsTargets: 'FeatureFlags',
+  MultiFactorAuth: 'Mfa',
+  MultiFactorAuthChallenges: 'Mfa',
+  OrganizationsApiKeys: 'Organizations',
+  UserManagementAuthentication: 'UserManagement',
+  UserManagementInvitations: 'UserManagement',
+  UserManagementMagicAuth: 'UserManagement',
+  UserManagementMultiFactorAuthentication: 'UserManagement',
+  UserManagementOrganizationMembership: 'UserManagement',
+  UserManagementUsers: 'UserManagement',
+};
+
+/**
+ * Explicit class name overrides. Maps the default PascalCase service name
+ * to the desired SDK class name when toPascalCase produces the wrong casing.
+ */
+const CLASS_NAME_OVERRIDES: Record<string, string> = {
+  WorkosConnect: 'WorkOSConnect',
+};
+
+/**
+ * Resolve the output directory for a service, checking overrides first.
+ * Falls back to the standard kebab-case conversion.
+ */
+export function resolveServiceDir(resolvedServiceName: string): string {
+  return SERVICE_DIR_OVERRIDES[resolvedServiceName] ?? serviceDirName(resolvedServiceName);
+}
+
 /** Resolve the SDK method name for an operation, checking overlay first. */
 export function resolveMethodName(op: Operation, _service: Service, ctx: EmitterContext): string {
   const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  const override = METHOD_NAME_OVERRIDES[httpKey];
+  if (override) return override;
   const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
-  if (existing) return existing.methodName;
+  if (existing) {
+    // Fix: when the path ends with a path parameter (single-resource operation)
+    // and the overlay method name is plural, prefer the singular form.
+    // E.g., getUsers → getUser when path is /user_management/users/{id}
+    const isSingleResource = /\/\{[^}]+\}$/.test(op.path);
+    if (isSingleResource && existing.methodName.endsWith('s') && !existing.methodName.endsWith('ss')) {
+      const singular = existing.methodName.slice(0, -1);
+      // Only singularize if it looks like a typical pluralization (ends in 's')
+      // and the spec-derived name agrees it should be singular
+      const specDerived = toCamelCase(op.name);
+      if (specDerived === singular || specDerived.endsWith(singular.slice(singular.length - 4))) {
+        return singular;
+      }
+    }
+    return existing.methodName;
+  }
   return toCamelCase(op.name);
 }
 
 /** Resolve the SDK class name for a service, checking overlay for existing names. */
 export function resolveClassName(service: Service, ctx: EmitterContext): string {
+  // Explicit coverage: this service's endpoints belong to an existing class
+  const coveredBy = SERVICE_COVERED_BY[toPascalCase(service.name)];
+  if (coveredBy) return coveredBy;
+
   // Check overlay's methodByOperation for any operation in this service
   // to find the existing class name
   if (ctx.overlayLookup?.methodByOperation) {
     for (const op of service.operations) {
       const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
       const existing = ctx.overlayLookup.methodByOperation.get(httpKey);
-      if (existing) return existing.className;
+      if (existing) return CLASS_NAME_OVERRIDES[existing.className] ?? existing.className;
     }
   }
-  return toPascalCase(service.name);
+  const defaultName = toPascalCase(service.name);
+  return CLASS_NAME_OVERRIDES[defaultName] ?? defaultName;
 }
 
 /** Resolve the interface name for a model, checking overlay first. */