@workos/oagen-emitters 0.12.0 → 0.12.2

package/test/node/enums.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import { generateEnums } from '../../src/node/enums.js';
-import type { EmitterContext, ApiSpec, Enum, Service } from '@workos/oagen';
+import type { EmitterContext, ApiSpec, Enum } from '@workos/oagen';
 import { defaultSdkBehavior } from '@workos/oagen';
+import { generateEnums } from '../../src/node/enums.js';
 
 const emptySpec: ApiSpec = {
   name: 'Test',
@@ -24,33 +24,7 @@ describe('generateEnums', () => {
     expect(generateEnums([], ctx)).toEqual([]);
   });
 
-  it('generates string literal union type', () => {
-    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,
-        },
-      ],
-    };
-
+  it('generates const-object enum with derived type alias', () => {
     const enums: Enum[] = [
       {
         name: 'Status',
@@ -62,138 +36,93 @@ describe('generateEnums', () => {
       },
     ];
 
-    // Enum not referenced by any service → placed in common/
-    const files = generateEnums(enums, {
-      ...ctx,
-      spec: { ...emptySpec, services: [service] },
-    });
-    expect(files.length).toBe(1);
-    expect(files[0].content).toMatchInlineSnapshot(`
-      "export type Status =
-        | 'active'
-        | 'inactive'
-        | 'pending';"
-    `);
-  });
+    const result = generateEnums(enums, ctx);
 
-  it('places enum in service directory when referenced', () => {
-    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: 'enum', name: 'OrgStatus' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toContain('export const Status = {');
+    expect(result[0].content).toContain("Active: 'active'");
+    expect(result[0].content).toContain("Inactive: 'inactive'");
+    expect(result[0].content).toContain("Pending: 'pending'");
+    expect(result[0].content).toContain('} as const;');
+    expect(result[0].content).toContain('export type Status =');
+    expect(result[0].content).toContain('(typeof Status)[keyof typeof Status]');
+  });
 
+  it('places enum in common when not referenced by service', () => {
     const enums: Enum[] = [
       {
-        name: 'OrgStatus',
-        values: [
-          { name: 'ACTIVE', value: 'active' },
-          { name: 'INACTIVE', value: 'inactive' },
-        ],
+        name: 'Status',
+        values: [{ name: 'ACTIVE', value: 'active' }],
       },
     ];
 
-    const files = generateEnums(enums, {
-      ...ctx,
-      spec: { ...emptySpec, services: [service] },
-    });
-    expect(files[0].path).toBe('src/organizations/interfaces/org-status.interface.ts');
+    const result = generateEnums(enums, ctx);
+
+    expect(result[0].path).toBe('src/common/interfaces/status.interface.ts');
   });
 
-  it('derives PascalCase member names when merging new enum values into baseline', () => {
+  it('places enum in service directory when referenced', () => {
     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' },
-        ],
+        name: 'OrgStatus',
+        values: [{ name: 'ACTIVE', value: 'active' }],
       },
     ];
 
-    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',
+    const specWithServices: ApiSpec = {
+      ...emptySpec,
+      enums,
+      services: [
+        {
+          name: 'Organizations',
+          operations: [
+            {
+              name: 'listOrganizations',
+              httpMethod: 'get',
+              path: '/organizations',
+              pathParams: [],
+              queryParams: [
+                {
+                  name: 'status',
+                  type: { kind: 'enum', name: 'OrgStatus', values: ['active'] },
+                  required: false,
+                },
+              ],
+              headerParams: [],
+              response: { kind: 'primitive', type: 'unknown' },
+              errors: [],
+              injectIdempotencyKey: false,
             },
-          },
+          ],
         },
-        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',");
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: specWithServices,
+    };
 
-    // New members should be PascalCase, not lowercased
-    expect(content).toContain("LegacyVerified = 'legacy_verified',");
-    expect(content).toContain("Unverified = 'unverified',");
+    const result = generateEnums(enums, ctxWithServices);
 
-    // Should NOT produce lowercased member names
-    expect(content).not.toContain('legacyverified');
+    expect(result[0].path).toBe('src/organizations/interfaces/org-status.interface.ts');
   });
 
   it('renders @deprecated on enum values', () => {
     const enums: Enum[] = [
       {
-        name: 'Status',
+        name: 'Method',
         values: [
           { name: 'ACTIVE', value: 'active' },
-          {
-            name: 'LEGACY',
-            value: 'legacy',
-            description: 'No longer supported.',
-            deprecated: true,
-          },
-          { name: 'OLD', value: 'old', deprecated: true },
+          { name: 'OLD', value: 'old', deprecated: true, description: 'No longer supported.' },
+          { name: 'BARE', value: 'bare', deprecated: true },
         ],
       },
     ];
 
-    const files = generateEnums(enums, ctx);
-    const content = files[0].content;
-
-    // Value with description + deprecated gets multiline JSDoc
-    expect(content).toContain('  /**\n   * No longer supported.\n   * @deprecated\n   */');
+    const result = generateEnums(enums, ctx);
 
-    // Value with only deprecated gets single-line JSDoc
-    expect(content).toContain('  /** @deprecated */');
+    expect(result[0].content).toContain('No longer supported.\n   * @deprecated');
+    expect(result[0].content).toContain('/** @deprecated */');
   });
 });

package/test/node/errors.test.ts

@@ -2,8 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { generateErrors } from '../../src/node/errors.js';
 
 describe('generateErrors', () => {
-  it('returns empty array without context (static exceptions now hand-maintained)', () => {
-    const files = generateErrors();
-    expect(files).toEqual([]);
+  it('returns empty array without context', () => {
+    expect(generateErrors()).toEqual([]);
   });
 });

package/test/node/live-surface.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import { buildLiveSurface, emptyLiveSurface, pathExists, shouldSkipPath } from '../../src/node/live-surface.js';
+
+let tmpRoot: string;
+
+beforeAll(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'live-surface-'));
+  const src = path.join(tmpRoot, 'src');
+  fs.mkdirSync(path.join(src, 'organizations', 'interfaces'), { recursive: true });
+  fs.mkdirSync(path.join(src, 'common', 'utils'), { recursive: true });
+  fs.mkdirSync(path.join(src, 'webhooks'), { recursive: true });
+
+  // Plain hand-written class file (no header, no marker)
+  fs.writeFileSync(
+    path.join(src, 'organizations', 'organizations.ts'),
+    [
+      "import { WorkOS } from '../workos.js';",
+      'export class Organizations {',
+      '  constructor(private workos: WorkOS) {}',
+      '  async listOrganizations(options?: { limit?: number }) {',
+      '    return this.workos.get("/organizations", options);',
+      '  }',
+      '  async getOrganization(id: string) {',
+      '    return this.workos.get(`/organizations/${id}`);',
+      '  }',
+      '}',
+    ].join('\n'),
+  );
+
+  fs.writeFileSync(
+    path.join(src, 'organizations', 'interfaces', 'organization.interface.ts'),
+    [
+      'export interface Organization {',
+      '  id: string;',
+      '  name: string;',
+      '  createdAt: string;',
+      '}',
+      '',
+      'export interface OrganizationResponse {',
+      '  id: string;',
+      '  name: string;',
+      "  'created_at': string;",
+      '}',
+      '',
+      'export type Status = "active" | "suspended";',
+    ].join('\n'),
+  );
+
+  // Auto-generated file (header present, no ignore marker)
+  fs.mkdirSync(path.join(src, 'admin-portal'), { recursive: true });
+  fs.writeFileSync(
+    path.join(src, 'admin-portal', 'admin-portal.ts'),
+    [
+      '// This file is auto-generated by oagen. Do not edit.',
+      "import { WorkOS } from '../workos.js';",
+      'export class AdminPortal {',
+      '  constructor(private workos: WorkOS) {}',
+      '  async generateLink(opts: { adminEmails?: string[] }) { return opts; }',
+      '}',
+    ].join('\n'),
+  );
+
+  // Const-object enum (workos-node house style) with acronym casing.
+  fs.mkdirSync(path.join(src, 'common', 'interfaces'), { recursive: true });
+  fs.writeFileSync(
+    path.join(src, 'common', 'interfaces', 'generate-link-intent.interface.ts'),
+    [
+      '// This file is auto-generated by oagen. Do not edit.',
+      '',
+      'export const GenerateLinkIntent = {',
+      "  SSO: 'sso',",
+      "  DSync: 'dsync',",
+      "  AuditLogs: 'audit_logs',",
+      '} as const;',
+      'export type GenerateLinkIntent = (typeof GenerateLinkIntent)[keyof typeof GenerateLinkIntent];',
+    ].join('\n'),
+  );
+
+  // Protected file
+  fs.writeFileSync(
+    path.join(src, 'webhooks', 'webhooks.ts'),
+    [
+      '// @oagen-ignore-file',
+      'export class Webhooks {',
+      '  verifySignature(payload: string) { return true; }',
+      '}',
+    ].join('\n'),
+  );
+
+  fs.writeFileSync(
+    path.join(src, 'common', 'utils', 'pagination.ts'),
+    [
+      '// @oagen-ignore-file',
+      'export function autoPaginate<T>(input: T[]): T[] { return input; }',
+      'export async function fetchPage(url: string) { return { data: [], after: null }; }',
+    ].join('\n'),
+  );
+
+  // A spec file that should be ignored
+  fs.writeFileSync(
+    path.join(src, 'organizations', 'organizations.spec.ts'),
+    ["import { Organizations } from './organizations.js';", "describe('x', () => { it('y', () => {}) })"].join('\n'),
+  );
+
+  execFileSync('git', ['init'], { cwd: tmpRoot, stdio: 'ignore' });
+  execFileSync('git', ['add', 'src'], { cwd: tmpRoot, stdio: 'ignore' });
+  fs.mkdirSync(path.join(src, 'connect'), { recursive: true });
+  fs.writeFileSync(path.join(src, 'connect', 'connect.ts'), 'export class Connect {}');
+});
+
+afterAll(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe('buildLiveSurface', () => {
+  it('returns an empty surface when src/ is missing', () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'no-src-'));
+    try {
+      const surface = buildLiveSurface(empty);
+      expect(surface.files.size).toBe(0);
+      expect(surface.classes.size).toBe(0);
+      expect(surface.interfaces.size).toBe(0);
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+
+  it('records files relative to root with POSIX separators', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.files.has('src/organizations/organizations.ts')).toBe(true);
+    expect(surface.files.has('src/organizations/interfaces/organization.interface.ts')).toBe(true);
+    expect(surface.files.has('src/webhooks/webhooks.ts')).toBe(true);
+  });
+
+  it('distinguishes git-tracked baseline files from untracked junk', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.trackedFiles.has('src/organizations/organizations.ts')).toBe(true);
+    expect(surface.trackedFiles.has('src/connect/connect.ts')).toBe(false);
+  });
+
+  it('does not parse declarations from untracked files when git baseline exists', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.classes.has('Connect')).toBe(false);
+  });
+
+  it('detects @oagen-ignore-file markers', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.protectedFiles.has('src/webhooks/webhooks.ts')).toBe(true);
+    expect(surface.protectedFiles.has('src/common/utils/pagination.ts')).toBe(true);
+    expect(surface.protectedFiles.has('src/organizations/organizations.ts')).toBe(false);
+  });
+
+  it('detects auto-generated header', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.autogenFiles.has('src/admin-portal/admin-portal.ts')).toBe(true);
+    expect(surface.autogenFiles.has('src/organizations/organizations.ts')).toBe(false);
+    // Protected files are NOT also recorded as autogen even if their content
+    // happens to mention the phrase — the marker takes precedence.
+    expect(surface.autogenFiles.has('src/webhooks/webhooks.ts')).toBe(false);
+  });
+
+  it('extracts exported class names with their methods', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    const orgs = surface.classes.get('Organizations');
+    expect(orgs).toBeDefined();
+    expect(orgs?.filePath).toBe('src/organizations/organizations.ts');
+    expect(orgs?.methods.has('listOrganizations')).toBe(true);
+    expect(orgs?.methods.has('getOrganization')).toBe(true);
+  });
+
+  it('extracts protected class declarations as well', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.classes.get('Webhooks')?.filePath).toBe('src/webhooks/webhooks.ts');
+  });
+
+  it('extracts exported interface names with their fields', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    const org = surface.interfaces.get('Organization');
+    expect(org?.filePath).toBe('src/organizations/interfaces/organization.interface.ts');
+    expect(org?.fields.has('id')).toBe(true);
+    expect(org?.fields.has('name')).toBe(true);
+    expect(org?.fields.has('createdAt')).toBe(true);
+
+    const wire = surface.interfaces.get('OrganizationResponse');
+    expect(wire?.fields.has('created_at')).toBe(true);
+  });
+
+  it('records exported type aliases', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.interfaces.has('Status')).toBe(true);
+  });
+
+  it('records exported functions', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(surface.functions.get('autoPaginate')).toBe('src/common/utils/pagination.ts');
+    expect(surface.functions.get('fetchPage')).toBe('src/common/utils/pagination.ts');
+  });
+
+  it('extracts const-object enum members with acronym casing preserved', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    const members = surface.constObjectEnums.get('GenerateLinkIntent');
+    expect(members).toBeDefined();
+    expect(members?.get('sso')).toBe('SSO');
+    expect(members?.get('dsync')).toBe('DSync');
+    expect(members?.get('audit_logs')).toBe('AuditLogs');
+  });
+
+  it('skips .spec.ts files when extracting symbols', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    // The spec file is recorded in files but its symbols are not parsed (no class extraction).
+    expect(surface.files.has('src/organizations/organizations.spec.ts')).toBe(true);
+    // No class declarations exist in the spec file anyway, so no false-positive check needed.
+  });
+});
+
+describe('helpers', () => {
+  it('shouldSkipPath returns true for protected files', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(shouldSkipPath(surface, 'src/webhooks/webhooks.ts')).toBe(true);
+    expect(shouldSkipPath(surface, 'src/organizations/organizations.ts')).toBe(false);
+  });
+
+  it('pathExists reflects walked file set', () => {
+    const surface = buildLiveSurface(tmpRoot);
+    expect(pathExists(surface, 'src/organizations/organizations.ts')).toBe(true);
+    expect(pathExists(surface, 'src/missing/file.ts')).toBe(false);
+  });
+
+  it('emptyLiveSurface produces a usable zero state', () => {
+    const surface = emptyLiveSurface();
+    expect(surface.files.size).toBe(0);
+    expect(shouldSkipPath(surface, 'anything')).toBe(false);
+    expect(pathExists(surface, 'anything')).toBe(false);
+  });
+});