@workos/oagen-emitters 0.2.0 → 0.3.0

package/test/node/resources.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { generateResources, resolveResourceClassName, hasCompatibleConstructor } from '../../src/node/resources.js';
 import type { EmitterContext, ApiSpec, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
 
 const emptySpec: ApiSpec = {
   name: 'Test',
@@ -9,6 +10,7 @@ const emptySpec: ApiSpec = {
   services: [],
   models: [],
   enums: [],
+  sdk: defaultSdkBehavior(),
 };
 
 const ctx: EmitterContext = {
@@ -72,7 +74,10 @@ describe('generateResources', () => {
             queryParams: [
               {
                 name: 'domains',
-                type: { kind: 'array', items: { kind: 'primitive', type: 'string' } },
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
                 required: false,
               },
             ],
@@ -243,7 +248,12 @@ describe('generateResources', () => {
         methodByOperation: new Map([
           [
             'POST /auth/factors/enroll',
-            { className: 'Mfa', methodName: 'enrollFactor', params: [], returnType: 'void' },
+            {
+              className: 'Mfa',
+              methodName: 'enrollFactor',
+              params: [],
+              returnType: 'void',
+            },
           ],
         ]),
         httpKeyByMethod: new Map(),
@@ -301,7 +311,7 @@ describe('generateResources', () => {
     expect(content).toContain('   *');
     expect(content).toContain('   * You may optionally inform Radar that an attempt was successful.');
     expect(content).toContain('   * @param id - The unique identifier of the attempt.');
-    expect(content).toContain('   * @returns {RadarAttempt}');
+    expect(content).toContain('   * @returns {Promise<RadarAttempt>}');
     expect(content).toContain('   * @deprecated');
     expect(content).toContain('   */');
   });
@@ -315,7 +325,13 @@ describe('generateResources', () => {
             name: 'getOrganization',
             httpMethod: 'get',
             path: '/organizations/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [],
             headerParams: [],
             response: { kind: 'model', name: 'Organization' },
@@ -328,7 +344,61 @@ describe('generateResources', () => {
 
     const files = generateResources(services, ctx);
     const content = files[0].content;
-    expect(content).toContain('@returns {Organization}');
+    expect(content).toContain('@returns {Promise<Organization>}');
+  });
+
+  it('renders @returns from overlay return type when available', () => {
+    const services: Service[] = [
+      {
+        name: 'Authorization',
+        operations: [
+          {
+            name: 'createEnvironmentRole',
+            httpMethod: 'post',
+            path: '/authorization/roles',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateRoleInput' },
+            response: { kind: 'model', name: 'Role' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'POST /authorization/roles',
+            {
+              className: 'Authorization',
+              methodName: 'createEnvironmentRole',
+              params: [{ name: 'payload', type: 'CreateRoleInput', optional: false }],
+              returnType: 'Promise<EnvironmentRole>',
+            },
+          ],
+        ]),
+        httpKeyByMethod: new Map(),
+        interfaceByName: new Map(),
+        typeAliasByName: new Map(),
+        requiredExports: new Map(),
+        modelNameByIR: new Map(),
+        fileBySymbol: new Map(),
+      },
+    };
+
+    const files = generateResources(services, overlayCtx);
+    const content = files[0].content;
+    // JSDoc should use the overlay return type, not the spec schema name
+    expect(content).toContain('@returns {Promise<EnvironmentRole>}');
+    expect(content).not.toContain('@returns {Role}');
+    expect(content).not.toContain('@returns {Promise<Role>}');
   });
 
   it('renders query param docs for non-paginated operations', () => {
@@ -340,7 +410,13 @@ describe('generateResources', () => {
             name: 'getOrganization',
             httpMethod: 'get',
             path: '/organizations/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [
               {
                 name: 'include_fields',
@@ -372,7 +448,13 @@ describe('generateResources', () => {
             name: 'getSession',
             httpMethod: 'get',
             path: '/sessions/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [],
             headerParams: [
               {
@@ -421,8 +503,14 @@ describe('generateResources', () => {
             requestBody: { kind: 'model', name: 'CreateOrganizationInput' },
             response: { kind: 'model', name: 'Organization' },
             successResponses: [
-              { statusCode: 200, type: { kind: 'model', name: 'Organization' } },
-              { statusCode: 201, type: { kind: 'model', name: 'Organization' } },
+              {
+                statusCode: 200,
+                type: { kind: 'model', name: 'Organization' },
+              },
+              {
+                statusCode: 201,
+                type: { kind: 'model', name: 'Organization' },
+              },
             ],
             errors: [],
             injectIdempotencyKey: false,
@@ -434,9 +522,9 @@ describe('generateResources', () => {
     const files = generateResources(services, ctx);
     const content = files[0].content;
     // Only emit a single @returns for the primary response model (no status-code variants)
-    expect(content).toContain('@returns {Organization}');
-    expect(content).not.toContain('@returns {Organization} 200');
-    expect(content).not.toContain('@returns {Organization} 201');
+    expect(content).toContain('@returns {Promise<Organization>}');
+    expect(content).not.toContain('@returns {Promise<Organization>} 200');
+    expect(content).not.toContain('@returns {Promise<Organization>} 201');
   });
 
   it('generates DELETE-with-body method using deleteWithBody', () => {
@@ -517,7 +605,13 @@ describe('generateResources', () => {
             name: 'getOrganization',
             httpMethod: 'get',
             path: '/organizations/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [
               {
                 name: 'include_fields',
@@ -603,7 +697,7 @@ describe('generateResources', () => {
     expect(content).toContain('query: options');
   });
 
-  it('generates union type for non-discriminated request body (pass-through)', () => {
+  it('falls back to pass-through for non-discriminated union when models not in spec', () => {
     const services: Service[] = [
       {
         name: 'Auth',
@@ -640,7 +734,7 @@ describe('generateResources', () => {
     // Should NOT use Record<string, unknown>
     expect(content).not.toContain('Record<string, unknown>');
 
-    // Should pass payload directly (no serializer for unions)
+    // Models not in spec → falls back to pass-through
     expect(content).toContain("'/user_management/authenticate',");
     expect(content).toContain('payload,');
 
@@ -650,6 +744,111 @@ describe('generateResources', () => {
     expect(content).toContain('AuthByMagicAuth');
   });
 
+  it('generates field-guard serializer dispatch for non-discriminated union with models', () => {
+    const services: Service[] = [
+      {
+        name: 'Applications',
+        operations: [
+          {
+            name: 'createApplication',
+            httpMethod: 'post',
+            path: '/connect/applications',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: {
+              kind: 'union',
+              variants: [
+                { kind: 'model', name: 'CreateOAuthApplication' },
+                { kind: 'model', name: 'CreateM2MApplication' },
+              ],
+            },
+            response: { kind: 'model', name: 'ConnectApplication' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const testCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: {
+        ...emptySpec,
+        services,
+        models: [
+          {
+            name: 'CreateOAuthApplication',
+            fields: [
+              {
+                name: 'name',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+              {
+                name: 'redirect_uris',
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
+                required: true,
+              },
+              {
+                name: 'uses_pkce',
+                type: { kind: 'primitive', type: 'boolean' },
+                required: false,
+              },
+            ],
+          },
+          {
+            name: 'CreateM2MApplication',
+            fields: [
+              {
+                name: 'name',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+              {
+                name: 'scopes',
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
+                required: true,
+              },
+            ],
+          },
+          {
+            name: 'ConnectApplication',
+            fields: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const files = generateResources(services, testCtx);
+    const content = files[0].content;
+
+    // Should use the union type for the payload parameter
+    expect(content).toContain('payload: CreateOAuthApplication | CreateM2MApplication');
+
+    // Should dispatch via unique required field guards
+    expect(content).toContain("'redirectUris' in payload");
+    expect(content).toContain('serializeCreateOAuthApplication(payload as any)');
+    expect(content).toContain('serializeCreateM2MApplication(payload as any)');
+
+    // Should import serializers for all union variants
+    expect(content).toContain('serializeCreateOAuthApplication');
+    expect(content).toContain('serializeCreateM2MApplication');
+  });
+
   it('generates discriminated union serializer dispatch for request body', () => {
     const services: Service[] = [
       {
@@ -790,12 +989,12 @@ describe('generateResources', () => {
   it('prefixes ListOptions with service name when method is "list"', () => {
     const services: Service[] = [
       {
-        name: 'Connections',
+        name: 'Payments',
         operations: [
           {
             name: 'list',
             httpMethod: 'get',
-            path: '/connections',
+            path: '/payments',
             pathParams: [],
             queryParams: [
               {
@@ -826,7 +1025,15 @@ describe('generateResources', () => {
       spec: { ...emptySpec, services, models: [] },
       overlayLookup: {
         methodByOperation: new Map([
-          ['GET /connections', { className: 'Connections', methodName: 'list', params: [], returnType: 'void' }],
+          [
+            'GET /payments',
+            {
+              className: 'Payments',
+              methodName: 'list',
+              params: [],
+              returnType: 'void',
+            },
+          ],
         ]),
         httpKeyByMethod: new Map(),
         interfaceByName: new Map(),
@@ -841,8 +1048,8 @@ describe('generateResources', () => {
     const content = files[0].content;
 
     // Should use service-prefixed options name instead of generic "ListOptions"
-    expect(content).toContain('export interface ConnectionsListOptions extends PaginationOptions {');
-    expect(content).toContain('Promise<AutoPaginatable<Connection, ConnectionsListOptions>>');
+    expect(content).toContain('export interface PaymentsListOptions extends PaginationOptions {');
+    expect(content).toContain('Promise<AutoPaginatable<Connection, PaymentsListOptions>>');
     // Should NOT use the generic "ListOptions"
     expect(content).not.toContain('export interface ListOptions ');
   });
@@ -860,7 +1067,10 @@ describe('generateResources', () => {
             queryParams: [
               {
                 name: 'domains',
-                type: { kind: 'array', items: { kind: 'primitive', type: 'string' } },
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
                 required: false,
               },
             ],
@@ -885,6 +1095,185 @@ describe('generateResources', () => {
     // Method is "listOrganizations", not "list", so options name should be normal
     expect(content).toContain('export interface ListOrganizationsOptions extends PaginationOptions {');
   });
+
+  it('removes skipIfExists when fully-covered service has methods absent from baseline', () => {
+    const services: Service[] = [
+      {
+        name: 'SSOService',
+        operations: [
+          {
+            name: 'getAuthorizationUrl',
+            httpMethod: 'get',
+            path: '/sso/authorize',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'AuthorizationUrl' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+          {
+            name: 'logout',
+            httpMethod: 'get',
+            path: '/sso/logout',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'LogoutResult' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    // Overlay maps both operations to SSO class
+    // Baseline SSO class exists but only has getAuthorizationUrl (logout is missing)
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'GET /sso/authorize',
+            {
+              className: 'SSO',
+              methodName: 'getAuthorizationUrl',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+          [
+            'GET /sso/logout',
+            {
+              className: 'SSO',
+              methodName: 'logout',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+        ]),
+        httpKeyByMethod: new Map(),
+        interfaceByName: new Map(),
+        typeAliasByName: new Map(),
+        requiredExports: new Map(),
+        modelNameByIR: new Map(),
+        fileBySymbol: new Map(),
+      },
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2024-01-01',
+        classes: {
+          SSO: {
+            name: 'SSO',
+            methods: {
+              getAuthorizationUrl: [
+                {
+                  name: 'getAuthorizationUrl',
+                  params: [],
+                  returnType: 'void',
+                  async: true,
+                },
+              ],
+              // logout method is intentionally ABSENT
+            },
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateResources(services, overlayCtx);
+    expect(files.length).toBe(1);
+
+    // skipIfExists should be removed because 'logout' is absent from baseline
+    expect(files[0].skipIfExists).toBeUndefined();
+  });
+
+  it('keeps skipIfExists when fully-covered service has all methods in baseline', () => {
+    const services: Service[] = [
+      {
+        name: 'SSOService',
+        operations: [
+          {
+            name: 'getAuthorizationUrl',
+            httpMethod: 'get',
+            path: '/sso/authorize',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'AuthorizationUrl' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'GET /sso/authorize',
+            {
+              className: 'SSO',
+              methodName: 'getAuthorizationUrl',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+        ]),
+        httpKeyByMethod: new Map(),
+        interfaceByName: new Map(),
+        typeAliasByName: new Map(),
+        requiredExports: new Map(),
+        modelNameByIR: new Map(),
+        fileBySymbol: new Map(),
+      },
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2024-01-01',
+        classes: {
+          SSO: {
+            name: 'SSO',
+            methods: {
+              getAuthorizationUrl: [
+                {
+                  name: 'getAuthorizationUrl',
+                  params: [],
+                  returnType: 'void',
+                  async: true,
+                },
+              ],
+            },
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateResources(services, overlayCtx);
+    expect(files.length).toBe(1);
+
+    // skipIfExists should stay true because all methods exist in baseline
+    expect(files[0].skipIfExists).toBe(true);
+  });
 });
 
 describe('resolveResourceClassName', () => {
@@ -914,7 +1303,12 @@ describe('resolveResourceClassName', () => {
         methodByOperation: new Map([
           [
             'GET /webhook_events',
-            { className: 'Webhooks', methodName: 'listWebhookEvents', params: [], returnType: 'void' },
+            {
+              className: 'Webhooks',
+              methodName: 'listWebhookEvents',
+              params: [],
+              returnType: 'void',
+            },
           ],
         ]),
         httpKeyByMethod: new Map(),
@@ -933,7 +1327,13 @@ describe('resolveResourceClassName', () => {
             name: 'Webhooks',
             methods: {},
             properties: {},
-            constructorParams: [{ name: 'cryptoProvider', type: 'CryptoProvider', optional: false }],
+            constructorParams: [
+              {
+                name: 'cryptoProvider',
+                type: 'CryptoProvider',
+                optional: false,
+              },
+            ],
           },
         },
         interfaces: {},
@@ -957,7 +1357,12 @@ describe('resolveResourceClassName', () => {
         methodByOperation: new Map([
           [
             'GET /webhook_events',
-            { className: 'Webhooks', methodName: 'listWebhookEvents', params: [], returnType: 'void' },
+            {
+              className: 'Webhooks',
+              methodName: 'listWebhookEvents',
+              params: [],
+              returnType: 'void',
+            },
           ],
         ]),
         httpKeyByMethod: new Map(),
@@ -1014,7 +1419,15 @@ describe('resolveResourceClassName', () => {
       spec: { ...emptySpec, services: [collisionService] },
       overlayLookup: {
         methodByOperation: new Map([
-          ['GET /webhooks', { className: 'Webhooks', methodName: 'listWebhooks', params: [], returnType: 'void' }],
+          [
+            'GET /webhooks',
+            {
+              className: 'Webhooks',
+              methodName: 'listWebhooks',
+              params: [],
+              returnType: 'void',
+            },
+          ],
         ]),
         httpKeyByMethod: new Map(),
         interfaceByName: new Map(),
@@ -1032,7 +1445,13 @@ describe('resolveResourceClassName', () => {
             name: 'Webhooks',
             methods: {},
             properties: {},
-            constructorParams: [{ name: 'cryptoProvider', type: 'CryptoProvider', optional: false }],
+            constructorParams: [
+              {
+                name: 'cryptoProvider',
+                type: 'CryptoProvider',
+                optional: false,
+              },
+            ],
           },
         },
         interfaces: {},
@@ -1090,7 +1509,13 @@ describe('hasCompatibleConstructor', () => {
             name: 'Webhooks',
             methods: {},
             properties: {},
-            constructorParams: [{ name: 'cryptoProvider', type: 'CryptoProvider', optional: false }],
+            constructorParams: [
+              {
+                name: 'cryptoProvider',
+                type: 'CryptoProvider',
+                optional: false,
+              },
+            ],
           },
         },
         interfaces: {},
@@ -1192,7 +1617,14 @@ describe('partial service coverage', () => {
           AuditLogs: {
             name: 'AuditLogs',
             methods: {
-              createEvent: [{ name: 'createEvent', params: [], returnType: 'AuditLogEvent', async: true }],
+              createEvent: [
+                {
+                  name: 'createEvent',
+                  params: [],
+                  returnType: 'AuditLogEvent',
+                  async: true,
+                },
+              ],
             },
             properties: {},
             constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
@@ -1211,7 +1643,207 @@ describe('partial service coverage', () => {
 
     // Should generate method for uncovered operation
     expect(content).toContain('async getRetention');
-    // Should NOT generate method for covered operation
-    expect(content).not.toContain('async createEvent');
+    // Should also generate covered operation so the merger can apply JSDoc
+    expect(content).toContain('async createEvent');
+  });
+
+  it('generates resource class for fully covered services to provide JSDoc', () => {
+    const services: Service[] = [
+      {
+        name: 'Permissions',
+        operations: [
+          {
+            name: 'listPermissions',
+            description: 'List all permissions.',
+            httpMethod: 'get',
+            path: '/authorization/permissions',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'PermissionList' },
+            errors: [{ statusCode: 404 }],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxCovered: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'GET /authorization/permissions',
+            {
+              className: 'Permissions',
+              methodName: 'listPermissions',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+        ]),
+        httpKeyByMethod: new Map(),
+        interfaceByName: new Map(),
+        typeAliasByName: new Map(),
+        requiredExports: new Map(),
+        modelNameByIR: new Map(),
+        fileBySymbol: new Map(),
+      },
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2024-01-01',
+        classes: {
+          Permissions: {
+            name: 'Permissions',
+            methods: {
+              listPermissions: [
+                {
+                  name: 'listPermissions',
+                  params: [],
+                  returnType: 'void',
+                  async: true,
+                },
+              ],
+            },
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateResources(services, ctxCovered);
+    expect(files.length).toBe(1);
+    const content = files[0].content;
+    // All methods should have generated JSDoc — the merger matches by name
+    // and handles @deprecated preservation, so the emitter always provides
+    // docstrings for the merger to work with.
+    expect(content).toContain('List all permissions.');
+    // skipIfExists should remain true for covered services
+    expect(files[0].skipIfExists).toBe(true);
+  });
+
+  it('uses resolved operation method names when provided', () => {
+    const op = {
+      name: 'listRolesOrganizations',
+      httpMethod: 'get' as const,
+      path: '/authorization/organizations/{organizationId}/roles',
+      pathParams: [
+        {
+          name: 'organizationId',
+          type: { kind: 'primitive' as const, type: 'string' as const },
+          required: true,
+        },
+      ],
+      queryParams: [],
+      headerParams: [],
+      response: { kind: 'model' as const, name: 'RoleList' },
+      errors: [],
+      pagination: {
+        strategy: 'cursor' as const,
+        param: 'after',
+        itemType: { kind: 'model' as const, name: 'RoleList' },
+      },
+      injectIdempotencyKey: false,
+    };
+    const services: Service[] = [
+      {
+        name: 'Authorization',
+        operations: [op],
+      },
+    ];
+
+    const ctxResolved: EmitterContext = {
+      ...ctx,
+      spec: {
+        ...emptySpec,
+        services,
+        models: [{ name: 'RoleList', fields: [] }],
+      },
+      resolvedOperations: [
+        {
+          operation: op,
+          service: services[0],
+          methodName: 'list_organization_roles',
+          mountOn: 'Authorization',
+        } as any,
+      ],
+    };
+
+    const files = generateResources(services, ctxResolved);
+    expect(files.length).toBe(1);
+    const content = files[0].content;
+    // Should use the resolved operation name (converted to camelCase)
+    expect(content).toContain('async listOrganizationRoles');
+    expect(content).not.toContain('async listRolesOrganizations');
+  });
+
+  it('deduplicates method names for operations on different paths', () => {
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'create',
+            httpMethod: 'post',
+            path: '/organization_domains',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateOrgDomain' },
+            response: { kind: 'model', name: 'OrgDomain' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+          {
+            name: 'create',
+            httpMethod: 'post',
+            path: '/organizations',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateOrg' },
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxDedup: EmitterContext = {
+      ...ctx,
+      spec: {
+        ...emptySpec,
+        services,
+        models: [
+          { name: 'CreateOrgDomain', fields: [] },
+          { name: 'OrgDomain', fields: [] },
+          { name: 'CreateOrg', fields: [] },
+          { name: 'Organization', fields: [] },
+        ],
+      },
+    };
+
+    const files = generateResources(services, ctxDedup);
+    expect(files.length).toBe(1);
+    const content = files[0].content;
+    // The best-scoring plan keeps the name; the other gets disambiguated.
+    // "create" matches "organizations" path better (the word "create" doesn't
+    // appear in either path, but scoring is equal — first wins).
+    // The other gets a path suffix.
+    const createMatches = content.match(/async create\b/g);
+    // At most one un-suffixed "create"
+    expect(createMatches?.length ?? 0).toBeLessThanOrEqual(1);
+    // The two methods should have different names
+    const methodNames = [...content.matchAll(/async (\w+)\(/g)].map((m) => m[1]);
+    const createMethods = methodNames.filter((n) => n.toLowerCase().startsWith('create'));
+    expect(new Set(createMethods).size).toBe(createMethods.length); // all unique
   });
 });