@workos/oagen-emitters 0.4.0 → 0.6.0

package/src/ruby/client.ts

@@ -0,0 +1,238 @@
+import type { ApiSpec, EmitterContext, GeneratedFile, Service, Model, Enum } from '@workos/oagen';
+import { assignModelsToServices } from '@workos/oagen';
+import { servicePropertyName, resolveClassName, className, fileName, buildMountDirMap } from './naming.js';
+import { classifyUnassignedModel } from './models.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
+import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+import { NON_SPEC_SERVICES } from '../shared/non-spec-services.js';
+
+/**
+ * Ruby `Client#accessor` wiring for each non-spec service id.
+ *
+ * Entries omitted from this map (e.g. `webhook_verification`) extend an
+ * already-generated service class via `@oagen-ignore` blocks and need no
+ * dedicated accessor.
+ *
+ * `ctorArg = 'self'` means the helper takes the client (`Foo.new(self)`).
+ * `ctorArg = ''` means the accessor returns the constant directly (modules
+ * with module-level functions, e.g. `WorkOS::PKCE`).
+ */
+const NON_SPEC_ACCESSORS: Record<string, { prop: string; className: string; ctorArg: 'self' | '' }> = {
+  passwordless: { prop: 'passwordless', className: 'Passwordless', ctorArg: 'self' },
+  vault: { prop: 'vault', className: 'Vault', ctorArg: 'self' },
+  actions: { prop: 'actions', className: 'Actions', ctorArg: 'self' },
+  session_manager: { prop: 'session_manager', className: 'SessionManager', ctorArg: 'self' },
+  pkce: { prop: 'pkce', className: 'PKCE', ctorArg: '' },
+};
+
+/**
+ * Hand-maintained class names whose file basename does NOT camelCase to the
+ * expected Ruby class name under Zeitwerk's default inflector. Each entry
+ * adds an `inflect("file" => "Class")` override so the autoloader can
+ * resolve `WorkOS::PKCE` (rather than the default `WorkOS::Pkce`).
+ */
+const NON_SPEC_INFLECTIONS: ReadonlyArray<readonly [string, string]> = [['pkce', 'PKCE']];
+
+/**
+ * Generate:
+ *  - lib/workos.rb         — sets up a Zeitwerk loader for the gem
+ *  - lib/workos/client.rb  — client class with service accessors
+ *
+ * The HTTP runtime (request execution, retries, error mapping, pagination)
+ * lives in hand-maintained files flagged with `@oagen-ignore-file`:
+ *  - lib/workos/base_client.rb
+ *  - lib/workos/errors.rb
+ *  - lib/workos/configuration.rb
+ *  - lib/workos/hash_provider.rb
+ *  - lib/workos/types/list_struct.rb
+ */
+export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  files.push(generateInflectionsFile(spec, ctx));
+  files.push(generateMainEntryFile(spec, ctx));
+  files.push(generateClientClass(spec, ctx));
+  return files;
+}
+
+/** Build map: top-level service -> resolved class name (deduplicated by mount target). */
+export function buildTopLevelServices(spec: ApiSpec, ctx: EmitterContext): Service[] {
+  const seen = new Set<string>();
+  const out: Service[] = [];
+  for (const service of spec.services) {
+    const target = getMountTarget(service, ctx) || resolveClassName(service, ctx);
+    if (seen.has(target)) continue;
+    seen.add(target);
+    const canonical =
+      spec.services.find((s) => (getMountTarget(s, ctx) || resolveClassName(s, ctx)) === target && s.name === target) ??
+      service;
+    out.push(canonical);
+  }
+  return out;
+}
+
+/**
+ * Simulate Zeitwerk::Inflector's default inflection so we can emit the minimal
+ * set of overrides. Zeitwerk camelizes `foo_bar` -> `FooBar`; we only add
+ * inflector entries when the emitter's canonical className disagrees.
+ */
+function rubyCamelize(basename: string): string {
+  return basename
+    .split('_')
+    .filter((p) => p.length > 0)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('');
+}
+
+/** Build the inflection map: file basename -> class name for all generated constants. */
+function buildInflectionMap(spec: ApiSpec, ctx: EmitterContext): Map<string, string> {
+  const inflections = new Map<string, string>();
+
+  inflections.set('workos', 'WorkOS');
+
+  for (const service of buildTopLevelServices(spec, ctx)) {
+    const target = getMountTarget(service, ctx) || resolveClassName(service, ctx);
+    const cls = className(target);
+    const file = fileName(target);
+    if (rubyCamelize(file) !== cls) inflections.set(file, cls);
+  }
+
+  const seenClasses = new Set<string>();
+  for (const model of spec.models as Model[]) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+    const cls = className(model.name);
+    if (seenClasses.has(cls)) continue;
+    seenClasses.add(cls);
+    const file = fileName(model.name);
+    if (rubyCamelize(file) !== cls) inflections.set(file, cls);
+  }
+
+  const seenEnums = new Set<string>();
+  for (const enumDef of spec.enums as Enum[]) {
+    const cls = className(enumDef.name);
+    if (seenEnums.has(cls)) continue;
+    seenEnums.add(cls);
+    const file = fileName(enumDef.name);
+    if (rubyCamelize(file) !== cls) inflections.set(file, cls);
+  }
+
+  for (const [file, cls] of NON_SPEC_INFLECTIONS) inflections.set(file, cls);
+
+  return inflections;
+}
+
+/** Generate lib/workos/inflections.rb — Zeitwerk inflection overrides (T40/C5). */
+function generateInflectionsFile(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
+  const inflections = buildInflectionMap(spec, ctx);
+  const inflectEntries = [...inflections.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([fileBase, cls]) => `  "${fileBase}" => "${cls}"`)
+    .join(',\n');
+
+  const lines: string[] = [];
+  lines.push('# Zeitwerk inflection overrides for the WorkOS gem.');
+  lines.push('# Maps file basenames to class/module names where the default');
+  lines.push('# CamelCase inference disagrees with the canonical class name.');
+  lines.push('WORKOS_INFLECTIONS = {');
+  lines.push(inflectEntries);
+  lines.push('}.freeze');
+
+  return {
+    path: 'lib/workos/inflections.rb',
+    content: lines.join('\n'),
+    integrateTarget: true,
+    overwriteExisting: true,
+  };
+}
+
+/** Generate lib/workos.rb — Zeitwerk bootstrap for the gem. */
+function generateMainEntryFile(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
+  const modelSubdirs = collectModelSubdirs(spec, ctx);
+
+  const lines: string[] = [];
+  lines.push(`require 'zeitwerk'`);
+  lines.push('');
+  lines.push('module WorkOS');
+  lines.push('end');
+  lines.push('');
+  lines.push('loader = Zeitwerk::Loader.for_gem');
+  lines.push(`require_relative 'workos/inflections'`);
+  lines.push('loader.inflector.inflect(WORKOS_INFLECTIONS)');
+  for (const dir of modelSubdirs) {
+    lines.push(`loader.collapse("#{__dir__}/workos/${dir}")`);
+  }
+  lines.push(`loader.ignore("#{__dir__}/workos/errors.rb")`);
+  lines.push(`loader.ignore("#{__dir__}/workos/inflections.rb")`);
+  lines.push('loader.setup');
+  lines.push('');
+  lines.push(`require 'workos/errors'`);
+
+  return {
+    path: 'lib/workos.rb',
+    content: lines.join('\n'),
+    integrateTarget: true,
+    overwriteExisting: true,
+  };
+}
+
+/**
+ * Collect the set of mount-target subfolders that models.ts will populate.
+ * Used by the Zeitwerk bootstrap to emit `loader.collapse` directives, which
+ * keep the generated namespace flat while the filesystem is grouped.
+ */
+function collectModelSubdirs(spec: ApiSpec, ctx: EmitterContext): string[] {
+  const modelToService = assignModelsToServices(spec.models as Model[], spec.services);
+  const mountDirMap = buildMountDirMap(ctx);
+  const subdirs = new Set<string>();
+  for (const model of spec.models as Model[]) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+    const service = modelToService.get(model.name);
+    const dir = service
+      ? (mountDirMap.get(service) ?? classifyUnassignedModel(model.name))
+      : classifyUnassignedModel(model.name);
+    subdirs.add(dir);
+  }
+  return [...subdirs].sort();
+}
+
+/** Generate lib/workos/client.rb — thin service-wiring client. */
+function generateClientClass(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
+  const lines: string[] = [];
+  lines.push('module WorkOS');
+  lines.push('  class Client < BaseClient');
+
+  const topLevelServices = buildTopLevelServices(spec, ctx);
+  for (const service of topLevelServices) {
+    const target = getMountTarget(service, ctx) || resolveClassName(service, ctx);
+    const cls = className(target);
+    const prop = servicePropertyName(target);
+    lines.push('');
+    lines.push(`    def ${prop}`);
+    lines.push(`      @${prop} ||= WorkOS::${cls}.new(self)`);
+    lines.push('    end');
+  }
+
+  // Non-spec service accessors. Emitted inside @oagen-ignore so user edits
+  // (added/removed accessors, renames) survive subsequent regenerations.
+  lines.push('');
+  lines.push('    # @oagen-ignore-start — non-spec service accessors (hand-maintained)');
+  for (const { id } of NON_SPEC_SERVICES) {
+    const wiring = NON_SPEC_ACCESSORS[id];
+    if (!wiring) continue;
+    const init = wiring.ctorArg ? `.new(${wiring.ctorArg})` : '';
+    lines.push('');
+    lines.push(`    def ${wiring.prop}`);
+    lines.push(`      @${wiring.prop} ||= WorkOS::${wiring.className}${init}`);
+    lines.push('    end');
+  }
+  lines.push('    # @oagen-ignore-end');
+
+  lines.push('  end');
+  lines.push('end');
+
+  return {
+    path: 'lib/workos/client.rb',
+    content: lines.join('\n'),
+    integrateTarget: true,
+    overwriteExisting: true,
+  };
+}

package/src/ruby/enums.ts

@@ -0,0 +1,149 @@
+import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { toUpperSnakeCase } from '@workos/oagen';
+import { className, fileName } from './naming.js';
+
+/**
+ * Generate Ruby enum class files.
+ *
+ * Each enum becomes a class under `WorkOS::Types::` with uppercase constants
+ * and a frozen `ALL` array of all values.
+ */
+export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+  void ctx;
+  if (enums.length === 0) return [];
+
+  const files: GeneratedFile[] = [];
+  const aliasOf = collectEnumAliasOf(enums);
+
+  for (const enumDef of enums) {
+    const cls = className(enumDef.name);
+
+    // If this enum duplicates another (by value set), emit a Ruby constant
+    // alias. Zeitwerk autoloads the canonical when the alias is first
+    // referenced.
+    const canonicalName = aliasOf.get(enumDef.name);
+    if (canonicalName) {
+      const canonicalCls = className(canonicalName);
+      const lines: string[] = [];
+      lines.push('module WorkOS');
+      lines.push('  module Types');
+      lines.push(`    ${cls} = ${canonicalCls}`);
+      lines.push('  end');
+      lines.push('end');
+      files.push({
+        path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+      continue;
+    }
+
+    // Deduplicate repeated string values.
+    const seen = new Set<string>();
+    const uniqueValues: typeof enumDef.values = [];
+    for (const v of enumDef.values) {
+      const str = String(v.value);
+      if (!seen.has(str)) {
+        seen.add(str);
+        uniqueValues.push({ ...v, value: str });
+      }
+    }
+
+    if (uniqueValues.length === 0) {
+      // No values — emit a placeholder string-alias class.
+      const lines: string[] = [];
+      lines.push('module WorkOS');
+      lines.push('  module Types');
+      lines.push(`    class ${cls}`);
+      lines.push('      ALL = [].freeze');
+      lines.push('    end');
+      lines.push('  end');
+      lines.push('end');
+      files.push({
+        path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+      continue;
+    }
+
+    // Determine string vs integer enum.
+    const allIntegers = uniqueValues.every((v) => typeof v.value === 'number' && Number.isInteger(v.value));
+
+    // Reserve ALL for the frozen list constant at the bottom; any enum value
+    // whose upper-snake form collides gets a VALUE_ prefix.
+    const RESERVED_MEMBER_NAMES = new Set(['ALL']);
+    const usedNames = new Set<string>();
+    const memberLines: string[] = [];
+    const allEntries: string[] = [];
+
+    for (const v of uniqueValues) {
+      let member = toUpperSnakeCase(String(v.value));
+      // Ruby constants must start with an uppercase letter.
+      if (!/^[A-Z]/.test(member)) member = `VALUE_${member}`;
+      if (RESERVED_MEMBER_NAMES.has(member)) member = `VALUE_${member}`;
+      if (usedNames.has(member)) {
+        let suffix = 2;
+        while (usedNames.has(`${member}_${suffix}`)) suffix++;
+        member = `${member}_${suffix}`;
+      }
+      usedNames.add(member);
+      const valueLit = allIntegers ? String(v.value) : `'${String(v.value).replace(/'/g, "\\'")}'`;
+      if (v.deprecated) {
+        memberLines.push(`      # @deprecated`);
+      }
+      memberLines.push(`      ${member} = ${valueLit}`);
+      allEntries.push(member);
+    }
+
+    const lines: string[] = [];
+    lines.push('module WorkOS');
+    lines.push('  module Types');
+    lines.push(`    class ${cls}`);
+    lines.push(...memberLines);
+    lines.push(`      ALL = [${allEntries.join(', ')}].freeze`);
+    lines.push('    end');
+    lines.push('  end');
+    lines.push('end');
+
+    files.push({
+      path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
+      content: lines.join('\n'),
+      integrateTarget: true,
+      overwriteExisting: true,
+    });
+  }
+
+  return files;
+}
+
+/**
+ * Detect when two or more enums have the same value set — pick the lexicographically
+ * first as canonical and return a map of aliasName -> canonicalName for the rest.
+ */
+function collectEnumAliasOf(enums: Enum[]): Map<string, string> {
+  const hashGroups = new Map<string, string[]>();
+  for (const e of enums) {
+    const hash = [...e.values]
+      .map((v) => String(v.value))
+      .sort()
+      .join('|');
+    if (!hashGroups.has(hash)) hashGroups.set(hash, []);
+    hashGroups.get(hash)!.push(e.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);
+  }
+  return aliasOf;
+}
+
+/** Collect the set of enum names that were emitted. */
+export function collectEnumSymbols(enums: Enum[]): string[] {
+  return enums.map((e) => e.name);
+}

package/src/ruby/index.ts

@@ -0,0 +1,93 @@
+import type {
+  Emitter,
+  EmitterContext,
+  FormatCommand,
+  GeneratedFile,
+  ApiSpec,
+  Model,
+  Enum,
+  Service,
+} from '@workos/oagen';
+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 { buildOperationsMap } from './manifest.js';
+import { generateRbiFiles } from './rbi.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 rubyEmitter: Emitter = {
+  language: 'ruby',
+
+  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[] {
+    // Hand-maintained in the target SDK — base_client.rb, errors.rb,
+    // configuration.rb, hash_provider.rb, types/list_struct.rb,
+    // test/test_helper.rb, and version.rb all carry `@oagen-ignore-file`
+    // and are not regenerated.
+    return [];
+  },
+
+  generateTypeSignatures(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateRbiFiles(spec, ctx));
+  },
+
+  generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateTests(spec, ctx));
+  },
+
+  buildOperationsMap(spec: ApiSpec, ctx: EmitterContext) {
+    return buildOperationsMap(spec, ctx);
+  },
+
+  fileHeader(): string {
+    return `# frozen_string_literal: true\n\n# This file is auto-generated by oagen. Do not edit.`;
+  },
+
+  formatCommand(targetDir: string): FormatCommand | null {
+    void targetDir;
+    // The WorkOS Ruby SDK uses standardrb. oagen appends the list of written
+    // files as positional args after `args`; we filter to .rb files and pipe
+    // them to `bundle exec standardrb --fix`. cwd is set to targetDir by the
+    // harness so bundler picks up the SDK's Gemfile.
+    //
+    // Note: errors are NOT swallowed here — if standardrb fails (missing
+    // bundle, syntax error, etc.) the engine surfaces it. Silence only hides
+    // the fact that formatting never happened.
+    return {
+      cmd: 'bash',
+      args: [
+        '-c',
+        'RB_FILES=$(for f in "$@"; do case "$f" in *.rb) echo "$f";; esac; done); ' +
+          'if [ -n "$RB_FILES" ]; then printf "%s\\n" "$RB_FILES" | xargs bundle exec standardrb --fix --format quiet; fi',
+        '--',
+      ],
+      batchSize: 1000,
+    };
+  },
+};

package/src/ruby/manifest.ts

@@ -0,0 +1,28 @@
+import type { ApiSpec, EmitterContext, OperationsMap } from '@workos/oagen';
+import { servicePropertyName } from './naming.js';
+
+/**
+ * Build operation-to-SDK-method mapping for the manifest.
+ *
+ * Uses each resolved operation's actual mountOn (not the service default) so
+ * operations remounted via operationHints land on the correct service prop.
+ * Split operations emit one entry per wrapper (keyed by wrapper name + variant).
+ */
+export function buildOperationsMap(spec: ApiSpec, ctx: EmitterContext): OperationsMap {
+  void spec;
+  const manifest: OperationsMap = {};
+
+  for (const r of ctx.resolvedOperations ?? []) {
+    const op = r.operation;
+    const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+    const propName = servicePropertyName(r.mountOn);
+    manifest[httpKey] = { sdkMethod: r.methodName, service: propName };
+    if (r.wrappers && r.wrappers.length > 0) {
+      for (const w of r.wrappers) {
+        manifest[`${httpKey}#${w.targetVariant}`] = { sdkMethod: w.name, service: propName };
+      }
+    }
+  }
+
+  return manifest;
+}