@workos/oagen-emitters 0.2.1 → 0.3.0

package/src/python/enums.ts

@@ -0,0 +1,313 @@
+import type { Enum, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { toUpperSnakeCase, walkTypeRef } from '@workos/oagen';
+import { className, fileName, buildMountDirMap, dirToModule } from './naming.js';
+
+/**
+ * Convert a PascalCase class name to a human-readable lowercase string,
+ * preserving known acronyms instead of splitting them character-by-character.
+ */
+function humanizeClassName(name: string): string {
+  // Insert spaces before uppercase runs, but keep acronyms together
+  let result = name.replace(/([a-z])([A-Z])/g, '$1 $2');
+  // Split consecutive uppercase letters from following lowercase: "SSOProvider" -> "SSO Provider"
+  result = result.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+  return result.toLowerCase();
+}
+
+/**
+ * Generate Python enum class files from IR Enum definitions.
+ * Uses `(str, Enum)` for type-safe enum values (Python 3.10+).
+ */
+export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+  if (enums.length === 0) return [];
+
+  const enumToService = assignEnumsToServices(enums, ctx.spec.services);
+  const mountDirMap = buildMountDirMap(ctx);
+  const resolveDir = (irService: string | undefined) =>
+    irService ? (mountDirMap.get(irService) ?? 'common') : 'common';
+  const files: GeneratedFile[] = [];
+  const compatAliases = collectCompatEnumAliases(enums, ctx);
+
+  const aliasOf = collectEnumAliasOf(enums);
+
+  for (const enumDef of enums) {
+    const service = enumToService.get(enumDef.name);
+    const dirName = resolveDir(service);
+
+    // If this enum is an alias for a canonical enum, generate a type alias file
+    const canonicalName = aliasOf.get(enumDef.name);
+    if (canonicalName) {
+      const canonicalService = enumToService.get(canonicalName);
+      const canonicalDir = resolveDir(canonicalService);
+      const canonicalCls = className(canonicalName);
+      const aliasCls = className(enumDef.name);
+      const lines: string[] = [];
+      lines.push('from typing_extensions import TypeAlias');
+      // Use explicit __all__ to prevent ruff F401 from stripping the re-export
+      // Always use direct file import to avoid barrel dependency on the canonical
+      if (canonicalDir === dirName) {
+        lines.push(`from .${fileName(canonicalName)} import ${canonicalCls}`);
+      } else {
+        lines.push(
+          `from ${ctx.namespace}.${dirToModule(canonicalDir)}.models.${fileName(canonicalName)} import ${canonicalCls}`,
+        );
+      }
+      lines.push('');
+      lines.push(`${aliasCls}: TypeAlias = ${canonicalCls}`);
+      lines.push(`__all__ = ["${aliasCls}"]`);
+      files.push({
+        path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+
+      // Also generate compat alias files for dedup aliases (they may have compat aliases too)
+      for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
+        const importLine =
+          canonicalDir === dirName
+            ? `from .${fileName(canonicalName)} import ${canonicalCls}`
+            : `from ${ctx.namespace}.${dirToModule(canonicalDir)}.models.${fileName(canonicalName)} import ${canonicalCls}`;
+        files.push({
+          path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
+          content: [
+            'from typing_extensions import TypeAlias',
+            importLine,
+            '',
+            `${aliasName}: TypeAlias = ${canonicalCls}`,
+            `__all__ = ["${aliasName}"]`,
+          ].join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
+
+      continue;
+    }
+
+    const cls = className(enumDef.name);
+    const lines: string[] = [];
+
+    const readable = humanizeClassName(enumDef.name);
+    lines.push(`"""Enumeration of ${readable} values."""`);
+    lines.push('');
+    lines.push('from __future__ import annotations');
+    lines.push('');
+
+    if (enumDef.values.length === 0) {
+      lines.push('from typing import Union');
+      lines.push('from typing_extensions import TypeAlias');
+      lines.push('');
+      lines.push(`${cls}: TypeAlias = str`);
+    } else {
+      // Deduplicate values that produce the same string
+      const seenValues = new Set<string>();
+      const uniqueValues: typeof enumDef.values = [];
+      for (const value of enumDef.values) {
+        const valueStr = String(value.value);
+        if (!seenValues.has(valueStr)) {
+          seenValues.add(valueStr);
+          uniqueValues.push({ ...value, value: valueStr });
+        }
+      }
+
+      // Determine if all values are strings or all integers
+      const allStrings = uniqueValues.every((v) => typeof v.value === 'string');
+      const allIntegers = uniqueValues.every((v) => typeof v.value === 'number' && Number.isInteger(v.value));
+
+      if (allStrings) {
+        lines.push('from enum import Enum');
+        lines.push('from typing import Optional');
+        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('');
+        lines.push('');
+        lines.push(`class ${cls}(str, Enum):`);
+        lines.push(`    """Known values for ${cls}."""`);
+        lines.push('');
+      } else if (allIntegers) {
+        lines.push('from enum import IntEnum');
+        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('');
+        lines.push('');
+        lines.push(`class ${cls}(IntEnum):`);
+        lines.push(`    """Known values for ${cls}."""`);
+        lines.push('');
+      } else {
+        // Mixed types — fall back to Union[Literal[...], str]
+        lines.push('from typing import Union');
+        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('');
+        const literals = uniqueValues.map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)));
+        lines.push(`${cls}: TypeAlias = Union[Literal[${literals.join(', ')}], str]`);
+        files.push({
+          path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+        continue;
+      }
+
+      const usedNames = new Set<string>();
+      for (const v of uniqueValues) {
+        let memberName = toUpperSnakeCase(String(v.value));
+        if (usedNames.has(memberName)) {
+          let suffix = 2;
+          while (usedNames.has(`${memberName}_${suffix}`)) suffix++;
+          memberName = `${memberName}_${suffix}`;
+        }
+        usedNames.add(memberName);
+        const valueStr = typeof v.value === 'string' ? `"${v.value}"` : String(v.value);
+        lines.push(`    ${memberName} = ${valueStr}`);
+        if (v.description || v.deprecated) {
+          const parts: string[] = [];
+          if (v.description) parts.push(v.description);
+          if (v.deprecated) parts.push('.. deprecated::');
+          lines.push(`    """${parts.join('\n\n    ')}"""`);
+        }
+      }
+      if (allStrings) {
+        lines.push('');
+        lines.push('    @classmethod');
+        lines.push(`    def _missing_(cls, value: object) -> Optional["${cls}"]:`);
+        lines.push('        if not isinstance(value, str):');
+        lines.push('            return None');
+        lines.push('        unknown = str.__new__(cls, value)');
+        lines.push('        unknown._name_ = value.upper()');
+        lines.push('        unknown._value_ = value');
+        lines.push('        return unknown');
+      }
+      lines.push('');
+      lines.push(
+        `${cls}Literal: TypeAlias = Literal[${uniqueValues
+          .map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)))
+          .join(', ')}]`,
+      );
+    }
+
+    files.push({
+      path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
+      content: lines.join('\n'),
+      integrateTarget: true,
+      overwriteExisting: true,
+    });
+
+    for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
+      files.push({
+        path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
+        content: [
+          'from typing_extensions import TypeAlias',
+          `from .${fileName(enumDef.name)} import ${cls}`,
+          '',
+          `${aliasName}: TypeAlias = ${cls}`,
+          `__all__ = ["${aliasName}"]`,
+        ].join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
+  }
+
+  return files;
+}
+
+export function collectCompatEnumAliases(enums: Enum[], ctx: EmitterContext): Map<string, string[]> {
+  const aliases = new Map<string, string[]>();
+  const irEnumNames = new Set(enums.map((enumDef) => enumDef.name));
+  const normalizedHashToEnum = new Map<string, string>();
+
+  for (const enumDef of enums) {
+    normalizedHashToEnum.set(enumValueHash(enumDef), enumDef.name);
+  }
+
+  for (const baselineEnum of Object.values(ctx.apiSurface?.enums ?? {})) {
+    if (irEnumNames.has(baselineEnum.name)) continue;
+    const hash = Object.values(baselineEnum.members)
+      .map((value) => String(value))
+      .sort()
+      .join('|');
+    const target = normalizedHashToEnum.get(hash);
+    if (!target) continue;
+    if (!aliases.has(target)) aliases.set(target, []);
+    aliases.get(target)!.push(baselineEnum.name);
+  }
+
+  return aliases;
+}
+
+function collectEnumAliasOf(enums: Enum[]): Map<string, string> {
+  const hashGroups = new Map<string, string[]>();
+  for (const enumDef of enums) {
+    const hash = [...enumDef.values]
+      .map((v) => String(v.value))
+      .sort()
+      .join('|');
+    if (!hashGroups.has(hash)) hashGroups.set(hash, []);
+    hashGroups.get(hash)!.push(enumDef.name);
+  }
+
+  const aliasOf = new Map<string, string>();
+  for (const [, names] of hashGroups) {
+    if (names.length <= 1) continue;
+    const sorted = [...names].sort();
+    const canonical = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+      aliasOf.set(sorted[i], canonical);
+    }
+  }
+  return aliasOf;
+}
+
+export function collectGeneratedEnumSymbolsByDir(enums: Enum[], ctx: EmitterContext): Map<string, string[]> {
+  const enumToService = assignEnumsToServices(enums, ctx.spec.services);
+  const mountDirMap = buildMountDirMap(ctx);
+  const resolveDir = (irService: string | undefined) =>
+    irService ? (mountDirMap.get(irService) ?? 'common') : 'common';
+  const compatAliases = collectCompatEnumAliases(enums, ctx);
+  const symbolsByDir = new Map<string, string[]>();
+
+  for (const enumDef of enums) {
+    const service = enumToService.get(enumDef.name);
+    const dirName = resolveDir(service);
+    if (!symbolsByDir.has(dirName)) symbolsByDir.set(dirName, []);
+    symbolsByDir.get(dirName)!.push(enumDef.name);
+    for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
+      symbolsByDir.get(dirName)!.push(aliasName);
+    }
+  }
+
+  return symbolsByDir;
+}
+
+function enumValueHash(enumDef: Enum): string {
+  return [...enumDef.values]
+    .map((value) => String(value.value))
+    .sort()
+    .join('|');
+}
+
+export function assignEnumsToServices(enums: Enum[], 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, ...(op.cookieParams ?? [])]) {
+        collect(p.type);
+      }
+      for (const name of refs) {
+        if (enumNames.has(name) && !enumToService.has(name)) {
+          enumToService.set(name, service.name);
+        }
+      }
+    }
+  }
+
+  return enumToService;
+}

package/src/python/fixtures.ts

@@ -0,0 +1,196 @@
+import type { Model, TypeRef, Enum } from '@workos/oagen';
+
+import { fileName, fieldName } from './naming.js';
+import { isListMetadataModel, isListWrapperModel } from './models.js';
+
+/**
+ * Prefix mapping for generating realistic ID fixture values.
+ */
+export const ID_PREFIXES: Record<string, string> = {
+  Connection: 'conn_',
+  Organization: 'org_',
+  OrganizationMembership: 'om_',
+  User: 'user_',
+  Directory: 'directory_',
+  DirectoryGroup: 'dir_grp_',
+  DirectoryUser: 'dir_usr_',
+  Invitation: 'inv_',
+  Session: 'session_',
+  AuthenticationFactor: 'auth_factor_',
+  EmailVerification: 'email_verification_',
+  MagicAuth: 'magic_auth_',
+  PasswordReset: 'password_reset_',
+};
+
+/**
+ * Generate JSON fixture files for test data.
+ */
+export function generateFixtures(spec: {
+  models: Model[];
+  enums: Enum[];
+  services: any[];
+}): { path: string; content: string }[] {
+  if (spec.models.length === 0) return [];
+
+  const modelMap = new Map(spec.models.map((m) => [m.name, m]));
+  const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
+  const files: { path: string; content: string }[] = [];
+
+  for (const model of spec.models) {
+    if (isListMetadataModel(model)) continue;
+    if (isListWrapperModel(model)) continue;
+    // Skip models with no fields — these are typically discriminated unions
+    // with hand-maintained @oagen-ignore overrides; generated empty fixtures
+    // would not match the override's required fields.
+    if (model.fields.length === 0) continue;
+
+    const fixture = generateModelFixture(model, modelMap, enumMap);
+
+    files.push({
+      path: `tests/fixtures/${fileName(model.name)}.json`,
+      content: JSON.stringify(fixture, null, 2),
+    });
+  }
+
+  // Generate list fixtures for paginated responses
+  for (const service of spec.services) {
+    for (const op of service.operations) {
+      if (op.pagination) {
+        let itemModel = op.pagination.itemType.kind === 'model' ? modelMap.get(op.pagination.itemType.name) : null;
+        if (itemModel) {
+          const unwrapped = unwrapListModel(itemModel, modelMap);
+          if (unwrapped) itemModel = unwrapped;
+          if (itemModel.fields.length === 0) continue;
+          const fixture = generateModelFixture(itemModel, modelMap, enumMap);
+          const listFixture = {
+            data: [fixture],
+            list_metadata: {
+              before: null,
+              after: null,
+            },
+          };
+          files.push({
+            path: `tests/fixtures/list_${fileName(itemModel.name)}.json`,
+            content: JSON.stringify(listFixture, null, 2),
+          });
+        }
+      }
+    }
+  }
+
+  return files;
+}
+
+export function unwrapListModel(model: Model, modelMap: Map<string, Model>): Model | null {
+  const dataField = model.fields.find((f) => f.name === 'data');
+  const hasListMetadata = model.fields.some((f) => f.name === 'list_metadata' || f.name === 'listMetadata');
+  if (dataField && hasListMetadata && dataField.type.kind === 'array') {
+    const itemType = dataField.type.items;
+    if (itemType.kind === 'model') {
+      return modelMap.get(itemType.name) ?? null;
+    }
+  }
+  return null;
+}
+
+export function generateModelFixture(
+  model: Model,
+  modelMap: Map<string, Model>,
+  enumMap: Map<string, Enum>,
+): Record<string, any> {
+  const fixture: Record<string, any> = {};
+
+  // Deduplicate fields by snake_case name (matching model generation in models.ts)
+  const seenFieldNames = new Set<string>();
+  const deduplicatedFields = model.fields.filter((f) => {
+    const pyName = fieldName(f.name);
+    if (seenFieldNames.has(pyName)) return false;
+    seenFieldNames.add(pyName);
+    return true;
+  });
+
+  for (const field of deduplicatedFields) {
+    // Use the original field name as the wire key (matches from_dict access patterns)
+    const wireName = field.name;
+    if (field.example !== undefined) {
+      fixture[wireName] = field.example;
+    } else {
+      fixture[wireName] = generateFieldValue(field.type, field.name, model.name, modelMap, enumMap);
+    }
+  }
+
+  return fixture;
+}
+
+function generateFieldValue(
+  ref: TypeRef,
+  fieldName: string,
+  modelName: string,
+  modelMap: Map<string, Model>,
+  enumMap: Map<string, Enum>,
+): any {
+  switch (ref.kind) {
+    case 'primitive':
+      return generatePrimitiveValue(ref.type, ref.format, fieldName, modelName);
+    case 'literal':
+      return ref.value;
+    case 'enum': {
+      const e = enumMap.get(ref.name);
+      return e?.values[0]?.value ?? 'unknown';
+    }
+    case 'model': {
+      const nested = modelMap.get(ref.name);
+      if (nested) return generateModelFixture(nested, modelMap, enumMap);
+      return {};
+    }
+    case 'array': {
+      if (ref.items.kind === 'enum') {
+        const e = enumMap.get(ref.items.name);
+        if (e && e.values.length > 0) {
+          return e.values.map((v) => v.value);
+        }
+      }
+      const item = generateFieldValue(ref.items, fieldName, modelName, modelMap, enumMap);
+      return [item];
+    }
+    case 'nullable':
+      return generateFieldValue(ref.inner, fieldName, modelName, modelMap, enumMap);
+    case 'union':
+      if (ref.variants.length > 0) {
+        return generateFieldValue(ref.variants[0], fieldName, modelName, modelMap, enumMap);
+      }
+      return null;
+    case 'map':
+      return {
+        key: generateFieldValue(ref.valueType, 'value', modelName, modelMap, enumMap),
+      };
+  }
+}
+
+function generatePrimitiveValue(type: string, format: string | undefined, name: string, modelName: string): any {
+  switch (type) {
+    case 'string':
+      if (format === 'date-time') return '2023-01-01T00:00:00.000Z';
+      if (format === 'date') return '2023-01-01';
+      if (format === 'uuid') return '00000000-0000-0000-0000-000000000000';
+      if (name === 'id') {
+        const prefix = ID_PREFIXES[modelName] ?? '';
+        return `${prefix}01234`;
+      }
+      if (name.includes('id')) return `${name}_01234`;
+      if (name.includes('email')) return 'test@example.com';
+      if (name.includes('url') || name.includes('uri')) return 'https://example.com';
+      if (name.includes('name')) return 'Test';
+      return `test_${name}`;
+    case 'integer':
+      return 1;
+    case 'number':
+      return 1.0;
+    case 'boolean':
+      return true;
+    case 'unknown':
+      return {};
+    default:
+      return null;
+  }
+}

package/src/python/index.ts

@@ -0,0 +1,95 @@
+import type {
+  Emitter,
+  EmitterContext,
+  FormatCommand,
+  GeneratedFile,
+  ApiSpec,
+  Model,
+  Enum,
+  Service,
+} from '@workos/oagen';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { generateModels } from './models.js';
+import { generateEnums } from './enums.js';
+import { generateResources } from './resources.js';
+import { generateClient } from './client.js';
+import { generateTests } from './tests.js';
+import { generateManifest } from './manifest.js';
+/** Ensure every generated file's content ends with a trailing newline. */
+function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
+  for (const f of files) {
+    if (f.content && !f.content.endsWith('\n')) {
+      f.content += '\n';
+    }
+  }
+  return files;
+}
+
+export const pythonEmitter: Emitter = {
+  language: 'python',
+
+  generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateModels(models, ctx));
+  },
+
+  generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateEnums(enums, ctx));
+  },
+
+  generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateResources(services, ctx));
+  },
+
+  generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateClient(spec, ctx));
+  },
+
+  generateErrors(): GeneratedFile[] {
+    // _errors.py is now hand-maintained in the target SDK (@oagen-ignore-file)
+    return [];
+  },
+
+  generateTypeSignatures(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    void spec;
+    void ctx;
+    // Python uses inline type annotations — no separate type signature files needed
+    return [];
+  },
+
+  generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateTests(spec, ctx));
+  },
+
+  generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateManifest(spec, ctx));
+  },
+
+  fileHeader(): string {
+    return '# This file is auto-generated by oagen. Do not edit.';
+  },
+
+  formatCommand(targetDir: string): FormatCommand | null {
+    const hasRuff =
+      fs.existsSync(path.join(targetDir, 'ruff.toml')) || fs.existsSync(path.join(targetDir, '.ruff.toml'));
+    // Also check pyproject.toml for [tool.ruff] section
+    const pyproject = path.join(targetDir, 'pyproject.toml');
+    const hasRuffInPyproject = fs.existsSync(pyproject) && fs.readFileSync(pyproject, 'utf8').includes('[tool.ruff]');
+    // Check for noxfile that uses ruff
+    const noxfile = path.join(targetDir, 'noxfile.py');
+    const hasRuffInNox = fs.existsSync(noxfile) && fs.readFileSync(noxfile, 'utf8').includes('ruff');
+
+    if (hasRuff || hasRuffInPyproject || hasRuffInNox) {
+      return {
+        cmd: 'bash',
+        args: [
+          '-c',
+          'PY_FILES=$(printf "%s\\n" "$@" | grep "\\.py$"); [ -n "$PY_FILES" ] && echo "$PY_FILES" | xargs ruff check --fix --quiet 2>/dev/null; [ -n "$PY_FILES" ] && echo "$PY_FILES" | xargs ruff format --quiet',
+          '--',
+        ],
+      };
+    }
+    return null;
+  },
+};

package/src/python/manifest.ts

@@ -0,0 +1,38 @@
+import type { ApiSpec, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { resolveMethodName } from './naming.js';
+import { buildServiceAccessPaths } from './client.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
+
+/**
+ * Generate smoke test manifest mapping HTTP operations to SDK methods.
+ */
+export function generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const manifest: Record<string, { sdkMethod: string; service: string }> = {};
+  const accessPaths = buildServiceAccessPaths(spec.services, ctx);
+
+  for (const service of spec.services) {
+    // For mounted services, look up the mount target's access path
+    let propName = accessPaths.get(service.name);
+    if (!propName) {
+      const mountTarget = getMountTarget(service, ctx);
+      propName = accessPaths.get(mountTarget);
+    }
+    if (!propName) {
+      throw new Error(`Missing public client access path for service ${service.name}`);
+    }
+    for (const op of service.operations) {
+      const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+      const method = resolveMethodName(op, service, ctx);
+      manifest[httpKey] = { sdkMethod: method, service: propName };
+    }
+  }
+
+  return [
+    {
+      path: 'smoke-manifest.json',
+      content: JSON.stringify(manifest, null, 2),
+      integrateTarget: false,
+      overwriteExisting: true,
+    },
+  ];
+}