@workos/oagen-emitters 0.0.1 → 0.2.1

package/test/node/enums.test.ts

@@ -15,7 +15,6 @@ const ctx: EmitterContext = {
   namespace: 'workos',
   namespacePascal: 'WorkOS',
   spec: emptySpec,
-  irVersion: 6,
 };
 
 describe('generateEnums', () => {
@@ -31,7 +30,13 @@ describe('generateEnums', () => {
           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: {
@@ -77,7 +82,13 @@ describe('generateEnums', () => {
           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: 'enum', name: 'OrgStatus' },
@@ -104,13 +115,71 @@ describe('generateEnums', () => {
     expect(files[0].path).toBe('src/organizations/interfaces/org-status.interface.ts');
   });
 
+  it('derives PascalCase member names when merging new enum values into baseline', () => {
+    const enums: Enum[] = [
+      {
+        name: 'OrganizationDomainState',
+        values: [
+          { name: 'FAILED', value: 'failed' },
+          { name: 'PENDING', value: 'pending' },
+          { name: 'VERIFIED', value: 'verified' },
+          { name: 'LEGACY_VERIFIED', value: 'legacy_verified' },
+          { name: 'UNVERIFIED', value: 'unverified' },
+        ],
+      },
+    ];
+
+    const testCtx: EmitterContext = {
+      ...ctx,
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2024-01-01',
+        classes: {},
+        interfaces: {},
+        typeAliases: {},
+        enums: {
+          OrganizationDomainState: {
+            name: 'OrganizationDomainState',
+            members: {
+              Failed: 'failed',
+              Pending: 'pending',
+              Verified: 'verified',
+            },
+          },
+        },
+        exports: {},
+      },
+    };
+
+    const files = generateEnums(enums, testCtx);
+    const content = files[0].content;
+
+    // Existing members should be preserved as-is
+    expect(content).toContain("Failed = 'failed',");
+    expect(content).toContain("Pending = 'pending',");
+    expect(content).toContain("Verified = 'verified',");
+
+    // New members should be PascalCase, not lowercased
+    expect(content).toContain("LegacyVerified = 'legacy_verified',");
+    expect(content).toContain("Unverified = 'unverified',");
+
+    // Should NOT produce lowercased member names
+    expect(content).not.toContain('legacyverified');
+  });
+
   it('renders @deprecated on enum values', () => {
     const enums: Enum[] = [
       {
         name: 'Status',
         values: [
           { name: 'ACTIVE', value: 'active' },
-          { name: 'LEGACY', value: 'legacy', description: 'No longer supported.', deprecated: true },
+          {
+            name: 'LEGACY',
+            value: 'legacy',
+            description: 'No longer supported.',
+            deprecated: true,
+          },
           { name: 'OLD', value: 'old', deprecated: true },
         ],
       },

package/test/node/errors.test.ts

@@ -1,26 +1,9 @@
 import { describe, it, expect } from 'vitest';
 import { generateErrors } from '../../src/node/errors.js';
-import type { EmitterContext, ApiSpec } from '@workos/oagen';
-
-const emptySpec: ApiSpec = {
-  name: 'Test',
-  version: '1.0.0',
-  baseUrl: '',
-  services: [],
-  models: [],
-  enums: [],
-};
-
-const ctx: EmitterContext = {
-  namespace: 'workos',
-  namespacePascal: 'WorkOS',
-  spec: emptySpec,
-  irVersion: 6,
-};
 
 describe('generateErrors', () => {
   it('generates all exception classes', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
 
     const names = files.map((f) => f.path);
     expect(names).toContain('src/common/exceptions/bad-request.exception.ts');
@@ -35,7 +18,7 @@ describe('generateErrors', () => {
   });
 
   it('generates NotFoundException with correct status', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
     const notFoundFile = files.find((f) => f.path.includes('not-found.exception.ts'))!;
 
     expect(notFoundFile.content).toContain('export class NotFoundException extends Error');
@@ -44,7 +27,7 @@ describe('generateErrors', () => {
   });
 
   it('generates RateLimitExceededException with retryAfter', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
     const rateLimitFile = files.find((f) => f.path.includes('rate-limit-exceeded.exception.ts'))!;
 
     expect(rateLimitFile.content).toContain('export class RateLimitExceededException extends Error');
@@ -53,7 +36,7 @@ describe('generateErrors', () => {
   });
 
   it('generates exception barrel with all exports', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
     const barrel = files.find((f) => f.path === 'src/common/exceptions/index.ts')!;
 
     expect(barrel.content).toContain('export { BadRequestException }');

package/test/node/models.test.ts

@@ -15,7 +15,6 @@ const ctx: EmitterContext = {
   namespace: 'workos',
   namespacePascal: 'WorkOS',
   spec: emptySpec,
-  irVersion: 6,
 };
 
 describe('generateModels', () => {
@@ -31,7 +30,13 @@ describe('generateModels', () => {
           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' },
@@ -85,7 +90,7 @@ describe('generateModels', () => {
     expect(files[0].content).toContain('export interface Organization {');
     expect(files[0].content).toContain('  id: string;');
     expect(files[0].content).toContain('  name: string;');
-    expect(files[0].content).toContain('  createdAt: string;');
+    expect(files[0].content).toContain('  createdAt: Date;');
     expect(files[0].content).toContain('  externalId?: string | null;');
 
     // Response interface has snake_case fields
@@ -102,7 +107,13 @@ describe('generateModels', () => {
           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' },
@@ -248,7 +259,13 @@ describe('generateModels', () => {
           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' },
@@ -298,4 +315,481 @@ describe('generateModels', () => {
     // Field with only deprecated gets single-line JSDoc
     expect(content).toContain('  /** @deprecated */');
   });
+
+  it('renders field-level JSDoc from OpenAPI descriptions', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [
+            {
+              name: 'id',
+              type: { kind: 'primitive', type: 'string' },
+              required: true,
+            },
+          ],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        description: 'An organization in the WorkOS system.',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            description: 'Unique identifier for the organization.',
+          },
+          {
+            name: 'name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            description: 'The display name of the organization.',
+          },
+          {
+            name: 'created_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+            // No description — should not get JSDoc
+          },
+          {
+            name: 'allow_profiles_outside_organization',
+            type: { kind: 'primitive', type: 'boolean' },
+            required: false,
+            description:
+              'Whether connections within the organization allow profiles\nthat do not have a domain that is verified by the organization.',
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    const content = files[0].content;
+
+    // Model-level JSDoc is emitted
+    expect(content).toContain('/** An organization in the WorkOS system. */');
+
+    // Fields with description get per-field JSDoc
+    expect(content).toContain('/** Unique identifier for the organization. */');
+    expect(content).toContain('/** The display name of the organization. */');
+
+    // Multiline description renders correctly
+    expect(content).toContain(
+      '  /**\n   * Whether connections within the organization allow profiles\n   * that do not have a domain that is verified by the organization.\n   */',
+    );
+
+    // Field without description does NOT get JSDoc
+    const lines = content.split('\n');
+    const createdAtIdx = lines.findIndex((l) => l.includes('createdAt'));
+    expect(createdAtIdx).toBeGreaterThan(0);
+    // The line before createdAt should not be a JSDoc closing tag
+    expect(lines[createdAtIdx - 1].trim()).not.toBe('*/');
+  });
+
+  it('renders readOnly/writeOnly/default annotations', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [
+            {
+              name: 'id',
+              type: { kind: 'primitive', type: 'string' },
+              required: true,
+            },
+          ],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            readOnly: true,
+          },
+          {
+            name: 'secret_key',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            writeOnly: true,
+          },
+          {
+            name: 'status',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+            default: 'active',
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    const content = files[0].content;
+
+    // readOnly field gets @readonly JSDoc and readonly TS modifier
+    expect(content).toContain('/** @readonly */');
+    expect(content).toContain('  readonly id: string;');
+
+    // writeOnly field gets @writeonly JSDoc
+    expect(content).toContain('/** @writeonly */');
+
+    // default field gets @default JSDoc
+    expect(content).toContain('@default "active"');
+  });
+
+  it('skips per-domain ListMetadata models (Fix #4)', () => {
+    const service: Service = {
+      name: 'Connections',
+      operations: [
+        {
+          name: 'listConnections',
+          httpMethod: 'get',
+          path: '/connections',
+          pathParams: [],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'ConnectionList' },
+          errors: [],
+          injectIdempotencyKey: false,
+          pagination: {
+            strategy: 'cursor',
+            param: 'after',
+            itemType: { kind: 'model', name: 'Connection' },
+          },
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'ConnectionListListMetadata',
+        fields: [
+          {
+            name: 'before',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+          {
+            name: 'after',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'Connection',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+
+    // The ListMetadata model should be skipped entirely
+    const listMetadataFile = files.find((f) => f.path.includes('list-metadata'));
+    expect(listMetadataFile).toBeUndefined();
+
+    // The Connection model should still be generated
+    const connectionFile = files.find((f) => f.path.includes('connection.interface.ts'));
+    expect(connectionFile).toBeDefined();
+  });
+
+  it('skips per-domain list wrapper models (Fix #6)', () => {
+    const service: Service = {
+      name: 'Connections',
+      operations: [
+        {
+          name: 'listConnections',
+          httpMethod: 'get',
+          path: '/connections',
+          pathParams: [],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'ConnectionList' },
+          errors: [],
+          injectIdempotencyKey: false,
+          pagination: {
+            strategy: 'cursor',
+            param: 'after',
+            itemType: { kind: 'model', name: 'Connection' },
+          },
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'ConnectionList',
+        fields: [
+          {
+            name: 'object',
+            type: { kind: 'literal', value: 'list' },
+            required: true,
+          },
+          {
+            name: 'data',
+            type: {
+              kind: 'array',
+              items: { kind: 'model', name: 'Connection' },
+            },
+            required: true,
+          },
+          {
+            name: 'list_metadata',
+            type: { kind: 'model', name: 'ConnectionListListMetadata' },
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'ConnectionListListMetadata',
+        fields: [
+          {
+            name: 'before',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+          {
+            name: 'after',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'Connection',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+
+    // The list wrapper model should be skipped
+    const listFile = files.find((f) => f.path.includes('connection-list.interface.ts'));
+    expect(listFile).toBeUndefined();
+
+    // The ListMetadata model should also be skipped
+    const listMetadataFile = files.find((f) => f.path.includes('list-metadata'));
+    expect(listMetadataFile).toBeUndefined();
+
+    // The Connection model should still be generated
+    const connectionFile = files.find((f) => f.path.includes('connection.interface.ts'));
+    expect(connectionFile).toBeDefined();
+  });
+
+  it('does not skip models that only partially match list-metadata shape', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [
+            {
+              name: 'id',
+              type: { kind: 'primitive', type: 'string' },
+              required: true,
+            },
+          ],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Pagination' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Pagination',
+        fields: [
+          {
+            name: 'before',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+          {
+            name: 'after',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+          {
+            name: 'total',
+            type: { kind: 'primitive', type: 'integer' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    // Model with 3 fields should NOT be skipped even if it has before/after
+    expect(files.length).toBe(1);
+    expect(files[0].path).toContain('pagination.interface.ts');
+  });
+});
+
+describe('model deduplication', () => {
+  it('emits type alias for structurally identical models', () => {
+    const service: Service = {
+      name: 'Roles',
+      operations: [
+        {
+          name: 'getRole',
+          httpMethod: 'get',
+          path: '/roles/{id}',
+          pathParams: [
+            {
+              name: 'id',
+              type: { kind: 'primitive', type: 'string' },
+              required: true,
+            },
+          ],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'EnvironmentRole' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'EnvironmentRole',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'type',
+            type: { kind: 'literal', value: 'environment_role' },
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'OrganizationRole',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'type',
+            type: { kind: 'literal', value: 'environment_role' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    expect(files.length).toBe(2);
+
+    // First model: full interface
+    expect(files[0].content).toContain('export interface EnvironmentRole');
+
+    // Second model: type alias referencing canonical
+    expect(files[1].content).toContain('export type OrganizationRole = EnvironmentRole');
+    expect(files[1].content).toContain('export type OrganizationRoleResponse = EnvironmentRoleResponse');
+  });
 });