@workos/oagen-emitters 0.4.0 → 0.5.0

package/src/ruby/models.ts

@@ -0,0 +1,360 @@
+import type { Model, EmitterContext, GeneratedFile, TypeRef, Field } from '@workos/oagen';
+import { walkTypeRef, assignModelsToServices } from '@workos/oagen';
+import { className, fieldName, fileName, buildMountDirMap } from './naming.js';
+import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+
+/** Folder under lib/workos/ for models not owned by any service. */
+export const SHARED_MODEL_DIR = 'shared';
+
+/**
+ * Prefix → mount-target-dir map for models that `assignModelsToServices` can't
+ * place (mostly webhook event payloads whose types aren't directly returned by
+ * any API operation). The prefix is the PascalCase model-name prefix.
+ *
+ * Order matters: longest prefix wins (checked first). Prefixes not in this map
+ * land in `shared/`.
+ */
+export const EVENT_MODEL_DIR_BY_PREFIX: ReadonlyArray<readonly [string, string]> = [
+  // Longer prefixes first — prefix matching is first-hit wins.
+  ['ApiKey', 'api_keys'],
+  ['OrganizationDomain', 'organization_domains'],
+  ['Organization', 'organizations'],
+  ['Authentication', 'user_management'],
+  ['Invitation', 'user_management'],
+  ['MagicAuth', 'user_management'],
+  ['Magic', 'user_management'],
+  ['Password', 'user_management'],
+  ['Email', 'user_management'],
+  ['Session', 'user_management'],
+  ['Action', 'user_management'],
+  ['User', 'user_management'],
+  ['Connection', 'sso'],
+  ['Dsync', 'directory_sync'],
+  ['Directory', 'directory_sync'],
+  ['Flag', 'feature_flags'],
+  ['Role', 'authorization'],
+  ['Permission', 'authorization'],
+  // Vault has no generated resource class (service is hand-maintained in the
+  // Ruby SDK), but the webhook payload models ship from the spec — group them
+  // under vault/ so the folder tree matches the hand-written client.
+  ['Vault', 'vault'],
+];
+
+/** Pick a subfolder for a model not assigned to any service. */
+export function classifyUnassignedModel(modelName: string): string {
+  for (const [prefix, dir] of EVENT_MODEL_DIR_BY_PREFIX) {
+    if (modelName.startsWith(prefix)) return dir;
+  }
+  return SHARED_MODEL_DIR;
+}
+
+/**
+ * Generate Ruby model classes from IR Model definitions.
+ *
+ * Each model becomes a file at `lib/workos/{snake_name}.rb` containing
+ * a class under `WorkOS::` with:
+ *   - attr_accessor for all fields
+ *   - initialize(json) that parses JSON
+ *   - to_json(*) that returns a hash
+ */
+export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  // Enum name set — used to detect enum-typed fields (treated as plain strings in Ruby).
+  const enumNames = new Set(ctx.spec.enums.map((e) => e.name));
+  const modelNames = new Set(models.map((m) => m.name));
+
+  // Model → mount target directory. Each model is assigned to the first service
+  // that references it (transitively). Orphans land in `shared/`. Zeitwerk is
+  // told to collapse each subfolder (in client.ts) so the namespace stays flat.
+  const modelToService = assignModelsToServices(models, ctx.spec.services);
+  const mountDirMap = buildMountDirMap(ctx);
+  const dirFor = (modelName: string): string => {
+    const service = modelToService.get(modelName);
+    if (!service) return classifyUnassignedModel(modelName);
+    return mountDirMap.get(service) ?? classifyUnassignedModel(modelName);
+  };
+
+  const files: GeneratedFile[] = [];
+
+  // Dedup identical models (by recursive structural hash).
+  const recursiveHashes = buildRecursiveHashMap(models, enumNames);
+  const hashGroups = new Map<string, string[]>();
+  for (const m of models) {
+    if (isListWrapperModel(m) || isListMetadataModel(m)) continue;
+    const h = recursiveHashes.get(m.name) ?? '';
+    if (!hashGroups.has(h)) hashGroups.set(h, []);
+    hashGroups.get(h)!.push(m.name);
+  }
+  const aliasOf = new Map<string, string>();
+  for (const names of hashGroups.values()) {
+    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);
+  }
+
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+
+    const cls = className(model.name);
+    const file = fileName(model.name);
+
+    // Ruby constant alias for duplicate models. Zeitwerk resolves the
+    // canonical on reference; the alias file just assigns the constant.
+    const canonical = aliasOf.get(model.name);
+    if (canonical) {
+      const canonCls = className(canonical);
+      const lines: string[] = [];
+      lines.push('module WorkOS');
+      lines.push(`  ${cls} = ${canonCls}`);
+      lines.push('end');
+      files.push({
+        path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+      continue;
+    }
+
+    // Deduplicate field names that collide after snake_case.
+    const seenFieldNames = new Set<string>();
+    const fields = model.fields.filter((f) => {
+      const n = fieldName(f.name);
+      if (seenFieldNames.has(n)) return false;
+      seenFieldNames.add(n);
+      return true;
+    });
+
+    const lines: string[] = [];
+    lines.push('module WorkOS');
+    lines.push(`  class ${cls} < WorkOS::Types::BaseModel`);
+    lines.push('');
+
+    // Split fields into non-deprecated (attr_accessor) and deprecated (explicit accessors with warn).
+    const accessorFields = fields.filter((f) => !f.deprecated);
+    const deprecatedFields = fields.filter((f) => f.deprecated);
+
+    // HASH_ATTRS maps wire names (symbols) to Ruby attribute names (symbols).
+    // HashProvider uses this for to_h, to_json, and inspect.
+    lines.push('    HASH_ATTRS = {');
+    for (let i = 0; i < fields.length; i++) {
+      const field = fields[i];
+      const fname = fieldName(field.name);
+      const sep = i === fields.length - 1 ? '' : ',';
+      lines.push(`      ${rubyHashLiteralKey(field.name)} :${fname}${sep}`);
+    }
+    lines.push('    }.freeze');
+    lines.push('');
+
+    // Emit @deprecated YARD tags for any deprecated fields before the accessor block.
+    if (deprecatedFields.length > 0) {
+      for (const f of deprecatedFields) {
+        const desc = f.description ? ` ${f.description.split('\n')[0].trim()}` : '';
+        lines.push(`    # @!attribute ${fieldName(f.name)}`);
+        lines.push(`    #   @deprecated${desc}`);
+      }
+      lines.push('');
+    }
+
+    if (accessorFields.length > 0) {
+      const attrs = accessorFields.map((f) => `:${fieldName(f.name)}`);
+      if (attrs.length === 1) {
+        lines.push(`    attr_accessor ${attrs[0]}`);
+      } else {
+        lines.push(`    attr_accessor \\`);
+        for (let i = 0; i < attrs.length; i++) {
+          const sep = i === attrs.length - 1 ? '' : ',';
+          lines.push(`      ${attrs[i]}${sep}`);
+        }
+      }
+      lines.push('');
+    }
+
+    // Emit deprecated field accessors with runtime warnings.
+    for (const f of deprecatedFields) {
+      const fname = fieldName(f.name);
+      lines.push(`    def ${fname}`);
+      lines.push(
+        `      warn "[DEPRECATION] \\\`${fname}\\\` is deprecated and will be removed in a future version.", uplevel: 1`,
+      );
+      lines.push(`      @${fname}`);
+      lines.push('    end');
+      lines.push('');
+      lines.push(`    def ${fname}=(value)`);
+      lines.push(`      @${fname} = value`);
+      lines.push('    end');
+      lines.push('');
+    }
+
+    // initialize(json)
+    lines.push('    def initialize(json)');
+    lines.push('      hash = self.class.normalize(json)');
+    for (const field of fields) {
+      const fname = fieldName(field.name);
+      const rawKey = field.name;
+      lines.push(`      ${deserializeAssignment(fname, rawKey, field.type, field.required, enumNames, modelNames)}`);
+    }
+    lines.push('    end');
+
+    lines.push('  end');
+    lines.push('end');
+
+    files.push({
+      path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
+      content: lines.join('\n'),
+      integrateTarget: true,
+      overwriteExisting: true,
+    });
+  }
+
+  return files;
+}
+
+/**
+ * Produce a Ruby assignment line like `@foo = hash[:foo]` or the appropriate
+ * nested-model construction for the field's type.
+ */
+function deserializeAssignment(
+  rubyFieldName: string,
+  rawKey: string,
+  ref: TypeRef,
+  required: boolean,
+  enumNames: Set<string>,
+  modelNames: Set<string>,
+): string {
+  const accessor = rubyHashAccessor('hash', rawKey);
+  const expr = deserializeExpression(accessor, ref, required, enumNames, modelNames);
+  return `@${rubyFieldName} = ${expr}`;
+}
+
+/** Build an expression that deserializes a TypeRef from the given accessor. */
+function deserializeExpression(
+  accessor: string,
+  ref: TypeRef,
+  required: boolean,
+  enumNames: Set<string>,
+  modelNames: Set<string>,
+): string {
+  void enumNames;
+  // Unwrap nullable — nullable behaves like optional at the value level.
+  if (ref.kind === 'nullable') {
+    return deserializeExpression(accessor, ref.inner, false, enumNames, modelNames);
+  }
+
+  if (ref.kind === 'array') {
+    const inner = ref.items;
+    const itemDeser = deserializeExpression('item', inner, true, enumNames, modelNames);
+    if (itemDeser === 'item') {
+      return `(${accessor} || [])`;
+    }
+    return `(${accessor} || []).map { |item| ${itemDeser} }`;
+  }
+
+  if (ref.kind === 'map') {
+    return `${accessor} || {}`;
+  }
+
+  if (ref.kind === 'model' && modelNames.has(ref.name)) {
+    const cls = `WorkOS::${className(ref.name)}`;
+    if (required) {
+      return `${accessor} ? ${cls}.new(${accessor}) : nil`;
+    }
+    return `${accessor} ? ${cls}.new(${accessor}) : nil`;
+  }
+
+  if (ref.kind === 'enum' && enumNames.has(ref.name)) {
+    return accessor; // enums are plain strings in Ruby (values match server)
+  }
+
+  if (ref.kind === 'union') {
+    // Unions: if all variants are models, try each; otherwise return raw value.
+    const modelVariants = ref.variants.filter((v) => v.kind === 'model' && modelNames.has(v.name));
+    if (modelVariants.length > 0 && modelVariants.length === ref.variants.length) {
+      // Multiple model variants — default to first successful parse or raw value.
+      return accessor; // simplification: return raw, let user inspect
+    }
+    return accessor;
+  }
+
+  if (ref.kind === 'literal') {
+    return accessor;
+  }
+
+  // primitive
+  return accessor;
+}
+
+/** Produce a Ruby accessor expression `hash[:foo]` or `hash[:"weird#name"]` for a raw field name. */
+function rubyHashAccessor(accessor: string, name: string): string {
+  if (/^[a-z_][a-zA-Z0-9_]*$/.test(name)) {
+    return `${accessor}[:${name}]`;
+  }
+  // Non-simple identifier: quoted symbol literal.
+  return `${accessor}[:"${name.replace(/"/g, '\\"')}"]`;
+}
+
+/** Produce a Ruby hash key literal (e.g., `foo:` shorthand or `"foo#bar" =>`).
+ *  Simple identifiers (including camelCase) use symbol shorthand; names with
+ *  special characters fall back to string-key `=>` syntax. */
+function rubyHashLiteralKey(name: string): string {
+  if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    return `${name}:`;
+  }
+  return `"${name.replace(/"/g, '\\"')}" =>`;
+}
+
+/** Build a recursive structural hash map for model deduplication. */
+function buildRecursiveHashMap(models: Model[], enumNames: Set<string>): Map<string, string> {
+  const modelByName = new Map(models.map((m) => [m.name, m]));
+  const memo = new Map<string, string>();
+
+  const hashTypeRef = (ref: TypeRef, visiting: Set<string>): string => {
+    switch (ref.kind) {
+      case 'primitive':
+        return `P:${ref.type}${ref.format ?? ''}`;
+      case 'array':
+        return `A[${hashTypeRef(ref.items, visiting)}]`;
+      case 'nullable':
+        return `N[${hashTypeRef(ref.inner, visiting)}]`;
+      case 'map':
+        return `M[${hashTypeRef(ref.valueType, visiting)}]`;
+      case 'literal':
+        return `L:${String(ref.value)}`;
+      case 'enum':
+        return `E:${ref.name}`;
+      case 'model': {
+        if (visiting.has(ref.name)) return `R:${ref.name}`; // cycle
+        return `Ref[${hashModel(ref.name, visiting)}]`;
+      }
+      case 'union':
+        return `U[${ref.variants.map((v) => hashTypeRef(v, visiting)).join(',')}]`;
+    }
+    return 'unknown';
+  };
+
+  const hashField = (f: Field, visiting: Set<string>): string => {
+    return `${f.name}:${f.required ? 'R' : 'O'}:${hashTypeRef(f.type, visiting)}`;
+  };
+
+  const hashModel = (name: string, visiting: Set<string>): string => {
+    if (memo.has(name)) return memo.get(name)!;
+    const m = modelByName.get(name);
+    if (!m) return `?:${name}`;
+    visiting.add(name);
+    const fieldsSorted = [...m.fields].sort((a, b) => a.name.localeCompare(b.name));
+    const h = fieldsSorted.map((f) => hashField(f, visiting)).join('|');
+    visiting.delete(name);
+    memo.set(name, h);
+    return h;
+  };
+
+  void enumNames;
+  void walkTypeRef;
+  const out = new Map<string, string>();
+  for (const m of models) {
+    out.set(m.name, hashModel(m.name, new Set()));
+  }
+  return out;
+}

package/src/ruby/naming.ts

@@ -0,0 +1,187 @@
+import type { Operation, Service, EmitterContext } from '@workos/oagen';
+import { toPascalCase, toSnakeCase } from '@workos/oagen';
+import { buildResolvedLookup, lookupMethodName, getMountTarget } from '../shared/resolved-ops.js';
+import { stripUrnPrefix, applyAcronymFixes } from '../shared/naming-utils.js';
+
+/**
+ * Ruby class names that collide with core classes. When a model name resolves
+ * to one of these, suffix with "Model".
+ */
+const RUBY_RESERVED_CLASS_NAMES = new Set([
+  'Array',
+  'Hash',
+  'String',
+  'Integer',
+  'Float',
+  'Object',
+  'Module',
+  'Class',
+  'Comparable',
+  'Enumerable',
+  'Range',
+  'Proc',
+  'Method',
+  'Regexp',
+  'Symbol',
+  'File',
+  'Dir',
+  'IO',
+  'Data',
+]);
+
+/** PascalCase class name with acronym preservation. */
+export function className(name: string): string {
+  let result = applyAcronymFixes(toPascalCase(stripUrnPrefix(name)));
+  if (RUBY_RESERVED_CLASS_NAMES.has(result)) {
+    result += 'Model';
+  }
+  return result;
+}
+
+/** snake_case file name (without extension). */
+export function fileName(name: string): string {
+  return toSnakeCase(stripUrnPrefix(name));
+}
+
+/** snake_case method name. */
+export function methodName(name: string): string {
+  return toSnakeCase(name);
+}
+
+/** snake_case field name. */
+export function fieldName(name: string): string {
+  return toSnakeCase(name);
+}
+
+/**
+ * Ruby reserved words that cannot be used as parameter names.
+ * When a path/query param name collides, suffix with underscore.
+ */
+const RUBY_RESERVED_WORDS = new Set([
+  'BEGIN',
+  'END',
+  'alias',
+  'and',
+  'begin',
+  'break',
+  'case',
+  'class',
+  'def',
+  'defined?',
+  'do',
+  'else',
+  'elsif',
+  'end',
+  'ensure',
+  'false',
+  'for',
+  'if',
+  'in',
+  'module',
+  'next',
+  'nil',
+  'not',
+  'or',
+  'redo',
+  'rescue',
+  'retry',
+  'return',
+  'self',
+  'super',
+  'then',
+  'true',
+  'undef',
+  'unless',
+  'until',
+  'when',
+  'while',
+  'yield',
+  // Common methods on Object/Kernel that shouldn't be shadowed
+  'hash',
+  'send',
+  'class',
+  'method',
+  'tap',
+]);
+
+/**
+ * Safe parameter name for path/query params that avoids shadowing Ruby reserved words.
+ */
+export function safeParamName(name: string): string {
+  const snake = toSnakeCase(name);
+  return RUBY_RESERVED_WORDS.has(snake) ? `${snake}_` : snake;
+}
+
+/** snake_case module/directory name. */
+export function moduleName(name: string): string {
+  return toSnakeCase(name);
+}
+
+/** snake_case property name for service accessors on the client. */
+export function servicePropertyName(name: string): string {
+  return toSnakeCase(name);
+}
+
+/**
+ * Resolve the effective service name, using the overlay-resolved class name
+ * when available.
+ */
+export function resolveServiceName(service: Service, ctx: EmitterContext): string {
+  return resolveClassName(service, ctx);
+}
+
+/**
+ * Build a map from IR service name to resolved service name.
+ */
+export function buildServiceNameMap(services: Service[], ctx: EmitterContext): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const service of services) {
+    map.set(service.name, resolveServiceName(service, ctx));
+  }
+  return map;
+}
+
+/** Resolve the SDK method name for an operation, using resolved operations first. */
+export function resolveMethodName(op: Operation, _service: Service, ctx: EmitterContext): string {
+  const lookup = buildResolvedLookup(ctx);
+  const resolved = lookupMethodName(op, lookup);
+  if (resolved) return resolved;
+  const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
+  if (existing) return toSnakeCase(existing.methodName);
+  return toSnakeCase(op.name);
+}
+
+/** Resolve the SDK class name for a service, using resolved operations' mountOn. */
+export function resolveClassName(service: Service, ctx: EmitterContext): string {
+  for (const r of ctx.resolvedOperations ?? []) {
+    if (r.service.name === service.name) return r.mountOn;
+  }
+  if (ctx.overlayLookup?.methodByOperation) {
+    for (const op of service.operations) {
+      const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+      const existing = ctx.overlayLookup.methodByOperation.get(httpKey);
+      if (existing) return existing.className;
+    }
+  }
+  return toPascalCase(service.name);
+}
+
+/** Resolve the type name for a model, checking overlay first. */
+export function resolveTypeName(name: string, ctx: EmitterContext): string {
+  const existing = ctx.overlayLookup?.interfaceByName?.get(name);
+  if (existing) return existing;
+  return toPascalCase(stripUrnPrefix(name));
+}
+
+/**
+ * Build a map from IR service name to mount-target directory name.
+ */
+export function buildMountDirMap(ctx: EmitterContext): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const service of ctx.spec.services) {
+    const target = getMountTarget(service, ctx);
+    map.set(service.name, moduleName(target));
+  }
+  return map;
+}