@workos/oagen-emitters 0.2.1 → 0.3.0

package/src/php/fixtures.ts

@@ -0,0 +1,181 @@
+import type { Model, TypeRef, Enum } from '@workos/oagen';
+import { isListMetadataModel, isListWrapperModel } from './models.js';
+import { snakeName } from './naming.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;
+
+    const fixture = generateModelFixture(model, modelMap, enumMap);
+
+    files.push({
+      path: `tests/Fixtures/${snakeName(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_${snakeName(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> = {};
+
+  for (const field of model.fields) {
+    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/php/index.ts

@@ -0,0 +1,96 @@
+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';
+import { initializeEnumDedup } from './naming.js';
+
+/** Initialize enum deduplication from spec data. */
+function ensureNamingInitialized(ctx: EmitterContext): void {
+  initializeEnumDedup(ctx.spec.enums);
+}
+
+/** 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 phpEmitter: Emitter = {
+  language: 'php',
+
+  generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+    ensureNamingInitialized(ctx);
+    return ensureTrailingNewlines(generateModels(models, ctx));
+  },
+
+  generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+    ensureNamingInitialized(ctx);
+    return ensureTrailingNewlines(generateEnums(enums, ctx));
+  },
+
+  generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
+    ensureNamingInitialized(ctx);
+    return ensureTrailingNewlines(generateResources(services, ctx));
+  },
+
+  generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    ensureNamingInitialized(ctx);
+    return ensureTrailingNewlines(generateClient(spec, ctx));
+  },
+
+  generateErrors(): GeneratedFile[] {
+    return [];
+  },
+
+  generateTypeSignatures(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
+    // PHP uses inline type hints — no separate type signature files needed
+    return [];
+  },
+
+  generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    ensureNamingInitialized(ctx);
+    return ensureTrailingNewlines(generateTests(spec, ctx));
+  },
+
+  generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    ensureNamingInitialized(ctx);
+    return ensureTrailingNewlines(generateManifest(spec, ctx));
+  },
+
+  fileHeader(): string {
+    return '<?php\n\ndeclare(strict_types=1);\n\n// This file is auto-generated by oagen. Do not edit.';
+  },
+
+  formatCommand(targetDir: string): FormatCommand | null {
+    const hasPhpCsFixer =
+      fs.existsSync(path.join(targetDir, '.php-cs-fixer.dist.php')) ||
+      fs.existsSync(path.join(targetDir, '.php-cs-fixer.php'));
+    if (hasPhpCsFixer) {
+      return {
+        cmd: 'bash',
+        args: ['-c', 'php vendor/bin/php-cs-fixer fix --using-cache=no --quiet . || true'],
+        batchSize: 999999,
+      };
+    }
+    return null;
+  },
+};

package/src/php/manifest.ts

@@ -0,0 +1,36 @@
+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) {
+    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,
+    },
+  ];
+}

package/src/php/models.ts

@@ -0,0 +1,310 @@
+import type { Model, TypeRef, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
+import { className, enumClassName, fieldName } from './naming.js';
+import { phpDocComment } from './utils.js';
+
+// Import and re-export shared model detection utilities
+import { isListMetadataModel, isListWrapperModel } from '../shared/model-utils.js';
+export { isListMetadataModel, isListWrapperModel };
+
+/**
+ * Generate PHP model files from IR models.
+ */
+export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  // Build structural hash for deduplication
+  const modelHashMap = new Map<string, string>();
+  const hashGroups = new Map<string, string[]>();
+  for (const model of models) {
+    if (isListMetadataModel(model)) continue;
+    if (isListWrapperModel(model)) continue;
+    const hash = structuralHash(model);
+    modelHashMap.set(model.name, hash);
+    if (!hashGroups.has(hash)) hashGroups.set(hash, []);
+    hashGroups.get(hash)!.push(model.name);
+  }
+
+  // Pick canonical for each duplicate group (shortest class name wins)
+  const aliasOf = new Map<string, string>();
+  for (const [hash, names] of hashGroups) {
+    if (names.length <= 1) continue;
+    if (hash === '') continue;
+    const sorted = [...names].sort((a, b) => className(a).length - className(b).length);
+    const canonical = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+      aliasOf.set(sorted[i], canonical);
+    }
+  }
+
+  const files: GeneratedFile[] = [];
+
+  // Emit shared JsonSerializableTrait once
+  files.push({
+    path: 'lib/Resource/JsonSerializableTrait.php',
+    content: [
+      `namespace ${ctx.namespacePascal}\\Resource;`,
+      '',
+      'trait JsonSerializableTrait',
+      '{',
+      '    public function jsonSerialize(): array',
+      '    {',
+      '        return $this->toArray();',
+      '    }',
+      '}',
+    ].join('\n'),
+    overwriteExisting: true,
+  });
+
+  for (const model of models) {
+    if (isListMetadataModel(model)) continue;
+    if (isListWrapperModel(model)) continue;
+    if (aliasOf.has(model.name)) continue; // skip structural duplicates
+
+    const name = className(model.name);
+    const lines: string[] = [];
+
+    // No <?php here — the file header from fileHeader() provides it
+    lines.push(`namespace ${ctx.namespacePascal}\\Resource;`);
+    lines.push('');
+    if (model.description) {
+      lines.push(...phpDocComment(model.description, 0));
+    }
+    lines.push(`readonly class ${name} implements \\JsonSerializable`);
+    lines.push('{');
+    lines.push('    use JsonSerializableTrait;');
+    lines.push('');
+
+    // Constructor with promoted properties
+    lines.push('    public function __construct(');
+    const requiredFields = model.fields.filter((f) => f.required);
+    const optionalFields = model.fields.filter((f) => !f.required);
+    // Deduplicate fields that map to the same PHP name
+    const seenNames = new Set<string>();
+    const allFields = [...requiredFields, ...optionalFields].filter((f) => {
+      const phpName = fieldName(f.name);
+      if (seenNames.has(phpName)) return false;
+      seenNames.add(phpName);
+      return true;
+    });
+
+    for (let i = 0; i < allFields.length; i++) {
+      const field = allFields[i];
+      const phpName = fieldName(field.name);
+      const phpType = mapTypeRef(field.type);
+      const isOptional = !field.required;
+      const comma = i < allFields.length - 1 ? ',' : ',';
+
+      const varDocType = mapTypeRefForPHPDoc(field.type);
+      const varNullSuffix = isOptional && !varDocType.endsWith('|null') ? '|null' : '';
+      const varAnnotation = needsVarAnnotation(field.type) ? `@var ${varDocType}${varNullSuffix}` : null;
+      if (field.description || field.deprecated || varAnnotation) {
+        const parts: string[] = [];
+        if (field.description) parts.push(field.description);
+        if (varAnnotation) parts.push(varAnnotation);
+        if (field.deprecated) parts.push('@deprecated');
+        lines.push(...phpDocComment(parts.join('\n'), 8));
+      }
+
+      if (isOptional) {
+        const nullableType = phpType.startsWith('?') ? phpType : `?${phpType}`;
+        lines.push(`        public ${nullableType} $${phpName} = null${comma}`);
+      } else {
+        lines.push(`        public ${phpType} $${phpName}${comma}`);
+      }
+    }
+    lines.push('    ) {');
+    lines.push('    }');
+
+    // fromArray factory method
+    lines.push('');
+    lines.push(`    public static function fromArray(array $data): self`);
+    lines.push('    {');
+    lines.push(`        return new self(`);
+    for (let i = 0; i < allFields.length; i++) {
+      const field = allFields[i];
+      const phpName = fieldName(field.name);
+      const wireName = field.name;
+      const comma = i < allFields.length - 1 ? ',' : ',';
+      const accessor = generateFromArrayAccessor(field.type, wireName, field.required);
+
+      lines.push(`            ${phpName}: ${accessor}${comma}`);
+    }
+    lines.push('        );');
+    lines.push('    }');
+
+    // toArray method
+    lines.push('');
+    lines.push('    public function toArray(): array');
+    lines.push('    {');
+    lines.push('        return [');
+    for (const field of allFields) {
+      const phpName = fieldName(field.name);
+      const wireName = field.name;
+      const serialized = generateToArrayValue(field.type, `$this->${phpName}`, !field.required);
+      lines.push(`            '${wireName}' => ${serialized},`);
+    }
+    lines.push('        ];');
+    lines.push('    }');
+
+    lines.push('}');
+
+    files.push({
+      path: `lib/Resource/${name}.php`,
+      content: lines.join('\n'),
+      overwriteExisting: true,
+    });
+  }
+
+  return files;
+}
+
+/**
+ * Generate the fromArray accessor expression for a field.
+ */
+function generateFromArrayAccessor(ref: TypeRef, wireName: string, required: boolean): string {
+  // For nullable types, always guard with isset() regardless of required flag
+  const isNullable = ref.kind === 'nullable';
+  if (!required || isNullable) {
+    const innerRef = isNullable ? ref.inner : ref;
+    const inner = generateFromArrayValue(innerRef, `$data['${wireName}']`);
+    if (isComplexType(innerRef)) {
+      return `isset($data['${wireName}']) ? ${inner} : null`;
+    }
+    if (isNullable) {
+      return `$data['${wireName}'] ?? null`;
+    }
+    return `$data['${wireName}'] ?? null`;
+  }
+  // Required field: access directly
+  return generateFromArrayValue(ref, `$data['${wireName}']`);
+}
+
+/**
+ * Generate the fromArray value expression for a type.
+ */
+function generateFromArrayValue(ref: TypeRef, accessor: string): string {
+  switch (ref.kind) {
+    case 'primitive':
+      if (ref.format === 'date-time') {
+        // Always access directly — nullable fields are already guarded by isset() in
+        // generateFromArrayAccessor(). Required fields should error if missing.
+        return `new \\DateTimeImmutable(${accessor})`;
+      }
+      return accessor;
+    case 'model': {
+      const name = className(ref.name);
+      return `${name}::fromArray(${accessor})`;
+    }
+    case 'enum': {
+      const name = enumClassName(ref.name);
+      return `${name}::from(${accessor})`;
+    }
+    case 'array':
+      if (ref.items.kind === 'model') {
+        const itemName = className(ref.items.name);
+        return `array_map(fn ($item) => ${itemName}::fromArray($item), ${accessor})`;
+      }
+      if (ref.items.kind === 'enum') {
+        const itemName = enumClassName(ref.items.name);
+        return `array_map(fn ($item) => ${itemName}::from($item), ${accessor})`;
+      }
+      if (ref.items.kind === 'primitive' && ref.items.format === 'date-time') {
+        return `array_map(fn ($item) => new \\DateTimeImmutable($item), ${accessor})`;
+      }
+      return accessor;
+    case 'nullable':
+      return generateFromArrayValue(ref.inner, accessor);
+    case 'union':
+      return accessor;
+    case 'map':
+      return accessor;
+    case 'literal':
+      return accessor;
+  }
+}
+
+/**
+ * Check if a TypeRef needs special handling (not a simple key access).
+ */
+function isComplexType(ref: TypeRef): boolean {
+  switch (ref.kind) {
+    case 'primitive':
+      return ref.format === 'date-time';
+    case 'model':
+    case 'enum':
+      return true;
+    case 'array':
+      return isComplexType(ref.items);
+    case 'nullable':
+      return isComplexType(ref.inner);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Generate the toArray serialization expression for a field value.
+ */
+function generateToArrayValue(ref: TypeRef, accessor: string, nullable = false): string {
+  const ns = nullable ? '?' : '';
+  switch (ref.kind) {
+    case 'primitive':
+      if (ref.format === 'date-time') {
+        return `${accessor}${ns}->format(\\DateTimeInterface::RFC3339_EXTENDED)`;
+      }
+      return accessor;
+    case 'model':
+      return `${accessor}${ns}->toArray()`;
+    case 'enum':
+      return nullable ? `${accessor}?->value` : `${accessor}->value`;
+    case 'array':
+      if (ref.items.kind === 'model') {
+        return nullable
+          ? `${accessor} !== null ? array_map(fn ($item) => $item->toArray(), ${accessor}) : null`
+          : `array_map(fn ($item) => $item->toArray(), ${accessor})`;
+      }
+      if (ref.items.kind === 'enum') {
+        return nullable
+          ? `${accessor} !== null ? array_map(fn ($item) => $item->value, ${accessor}) : null`
+          : `array_map(fn ($item) => $item->value, ${accessor})`;
+      }
+      if (ref.items.kind === 'primitive' && ref.items.format === 'date-time') {
+        return nullable
+          ? `${accessor} !== null ? array_map(fn ($item) => $item->format(\\DateTimeInterface::RFC3339_EXTENDED), ${accessor}) : null`
+          : `array_map(fn ($item) => $item->format(\\DateTimeInterface::RFC3339_EXTENDED), ${accessor})`;
+      }
+      return accessor;
+    case 'nullable':
+      return generateToArrayValue(ref.inner, accessor, true);
+    case 'map':
+      return accessor;
+    case 'union':
+      return accessor;
+    case 'literal':
+      return accessor;
+  }
+}
+
+/**
+ * Check if a TypeRef needs a @var PHPDoc annotation because the PHP type hint
+ * loses information (e.g., `array` vs `array<ConnectionDomain>`).
+ */
+function needsVarAnnotation(ref: TypeRef): boolean {
+  switch (ref.kind) {
+    case 'array':
+    case 'map':
+      return true;
+    case 'nullable':
+      return needsVarAnnotation(ref.inner);
+    default:
+      return false;
+  }
+}
+
+function structuralHash(model: Model): string {
+  return model.fields
+    .map((f) => `${f.name}:${JSON.stringify(f.type)}:${f.required}`)
+    .sort()
+    .join('|');
+}