@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/dotnet/enums.ts

@@ -0,0 +1,323 @@
+import type { Enum, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { walkTypeRef } from '@workos/oagen';
+import { className, deprecationMessage, escapeCsAttributeString, humanize } from './naming.js';
+import { setEnumAliases, setSingleValueEnumNames } from './type-map.js';
+import { enrichModelsFromSpec } from '../shared/model-utils.js';
+
+/**
+ * Generate C# enum definitions from IR Enum definitions.
+ * Each enum becomes a separate .cs file. Structurally-identical enums are
+ * deduplicated: only the canonical (alphabetically-first) name is emitted,
+ * and every reference to a duplicate enum is rewritten to the canonical one
+ * by `mapTypeRef` via `setEnumAliases`.
+ */
+export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+  if (enums.length === 0) return [];
+
+  // Publish the alias map + single-value enum set so model/options/wrapper
+  // emitters all resolve duplicate enum references to the canonical name and
+  // rewrite 1-value enum refs to `string`.
+  const aliasOf = collectEnumAliasOf(enums);
+  setEnumAliases(aliasOf);
+  setSingleValueEnumNames(enums.filter((e) => e.values.length === 1).map((e) => e.name));
+  diagnoseDivergentEnums(enums);
+
+  // Collect all enum names actually referenced by models and operations so we
+  // can suppress orphan enums that would otherwise be emitted but never used.
+  const referencedEnums = collectReferencedEnumNames(ctx);
+
+  const files: GeneratedFile[] = [];
+
+  for (const enumDef of enums) {
+    const typeName = className(enumDef.name);
+
+    // Skip duplicate enums — their references are retargeted to the canonical.
+    if (aliasOf.has(enumDef.name)) continue;
+
+    // Skip empty and single-value enums — the single-value case is a discriminator
+    // masquerading as an enum, and mapTypeRef rewrites such refs to `string` with
+    // a const initializer on the owning property.
+    if (enumDef.values.length <= 1) continue;
+
+    // Skip orphan enums that are not referenced by any model field or operation
+    // parameter. Resolve aliases so that a canonical enum is kept if any of its
+    // aliases are referenced.
+    const isReferenced =
+      referencedEnums.has(enumDef.name) ||
+      [...aliasOf.entries()].some(([alias, canon]) => canon === enumDef.name && referencedEnums.has(alias));
+    if (!isReferenced) continue;
+
+    // Deduplicate values
+    const seenValues = new Set<string>();
+    const uniqueValues: typeof enumDef.values = [];
+    for (const v of enumDef.values) {
+      const vs = String(v.value);
+      if (!seenValues.has(vs)) {
+        seenValues.add(vs);
+        uniqueValues.push(v);
+      }
+    }
+
+    const lines: string[] = [];
+    lines.push(`namespace ${ctx.namespacePascal}`);
+    lines.push('{');
+    lines.push('    using System.Runtime.Serialization;');
+    lines.push('    using Newtonsoft.Json;');
+    lines.push('    using STJS = System.Text.Json.Serialization;');
+    lines.push('');
+    lines.push(`    /// <summary>Represents ${humanize(enumDef.name)} values.</summary>`);
+    lines.push('    [JsonConverter(typeof(WorkOSNewtonsoftStringEnumConverter))]');
+    lines.push('    [STJS.JsonConverter(typeof(WorkOSStringEnumConverterFactory))]');
+    lines.push(`    public enum ${typeName}`);
+    lines.push('    {');
+    // Unknown sentinel as first member (value 0) for forward-compatibility
+    lines.push(`        [EnumMember(Value = "unknown")]`);
+    lines.push(`        Unknown,`);
+    lines.push('');
+
+    const usedNames = new Set<string>();
+    usedNames.add('Unknown');
+    // Track used EnumMember wire values to avoid duplicates (sentinel uses "unknown")
+    const usedWireValues = new Set<string>();
+    usedWireValues.add('unknown');
+    for (let i = 0; i < uniqueValues.length; i++) {
+      const v = uniqueValues[i];
+      // Skip values whose wire representation collides with the sentinel
+      if (usedWireValues.has(String(v.value))) continue;
+      usedWireValues.add(String(v.value));
+      let memberName = className(String(v.value));
+      // Avoid collision with the type itself or previously used names
+      if (memberName === typeName || usedNames.has(memberName)) {
+        let suffix = 2;
+        while (usedNames.has(`${memberName}${suffix}`)) suffix++;
+        memberName = `${memberName}${suffix}`;
+      }
+      usedNames.add(memberName);
+
+      if (v.description) {
+        lines.push(`        /// <summary>${escapeXml(v.description)}</summary>`);
+      }
+      if (v.deprecated) {
+        const msg = escapeCsAttributeString(deprecationMessage(v.description, 'value'));
+        lines.push(`        [System.Obsolete("${msg}")]`);
+      }
+      lines.push(`        [EnumMember(Value = "${v.value}")]`);
+      const comma = i < uniqueValues.length - 1 ? ',' : ',';
+      lines.push(`        ${memberName}${comma}`);
+    }
+
+    lines.push('    }');
+    lines.push('}');
+
+    files.push({
+      path: `Enums/${typeName}.cs`,
+      content: lines.join('\n'),
+      overwriteExisting: true,
+    });
+  }
+
+  return files;
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * Populate the module-level enum alias resolver from the given spec's enums.
+ * Call from every emitter entrypoint that uses `mapTypeRef` so enum
+ * references resolve to their canonical names regardless of which emitter
+ * phase runs first.
+ */
+export function primeEnumAliases(enums: Enum[]): void {
+  setEnumAliases(collectEnumAliasOf(enums));
+  setSingleValueEnumNames(enums.filter((e) => e.values.length === 1).map((e) => e.name));
+}
+
+/**
+ * Warn when two enums share a trailing stem (e.g., `ConnectionType`) but
+ * carry *contradictory* wire values — each side has values the other lacks.
+ * Pure subset relationships (event-specific payloads that narrow a shared
+ * base set — the usual shape of WorkOS event enums) are legitimate and not
+ * flagged. Only true divergences, which typically indicate spec drift, are
+ * reported.
+ */
+export function diagnoseDivergentEnums(enums: Enum[]): void {
+  const byStem = new Map<string, Enum[]>();
+  for (const e of enums) {
+    if (e.values.length < 2) continue;
+    const stem = trailingPascalStem(e.name);
+    if (!stem) continue;
+    if (!byStem.has(stem)) byStem.set(stem, []);
+    byStem.get(stem)!.push(e);
+  }
+
+  for (const [stem, group] of byStem) {
+    if (group.length < 2) continue;
+    // Skip generic event-payload stems (`DataState`, `DataStatus`,
+    // `DataActorSource`, …). Many unrelated event subtypes expose a
+    // `data.{state,status}` field whose allowed values are scoped per
+    // event; grouping them by the generic `Data*` suffix surfaces
+    // false-positive divergences, not real drift.
+    if (stem.startsWith('Data')) continue;
+    // Identical value sets are handled by the alias/dedupe pass.
+    const distinctSigs = new Set(group.map(valueSignature));
+    if (distinctSigs.size === 1) continue;
+    // Only warn when some pair is *mutually exclusive*: each enum has a
+    // value the other doesn't. Subsets are not drift.
+    if (!hasMutuallyExclusivePair(group)) continue;
+    const summary = group.map((e) => `${e.name}[${e.values.length}]`).join(', ');
+    console.warn(`[oagen:dotnet] Divergent enums sharing stem "${stem}": ${summary}`);
+  }
+}
+
+/**
+ * True if some pair in the group both:
+ *   (a) shares enough values to plausibly be the same concept, AND
+ *   (b) has values exclusive to each side (i.e., is not a subset/equal).
+ * Sharing the trailing stem alone is insufficient — `DataStatus` shows up on
+ * unrelated domains (connection link state vs. membership state) that only
+ * coincidentally overlap on a sentinel like `unknown`. Require a non-trivial
+ * intersection before treating two enums as the same logical enum.
+ */
+function hasMutuallyExclusivePair(group: Enum[]): boolean {
+  // Compare case-insensitively so cosmetic drift like `GitHubOAuth` vs
+  // `GithubOAuth` — an intentional historical spelling carried forward by
+  // the spec — doesn't register as divergence.
+  const valueSets = group.map((e) => new Set(e.values.map((v) => String(v.value).toLowerCase())));
+  for (let i = 0; i < valueSets.length; i++) {
+    for (let j = i + 1; j < valueSets.length; j++) {
+      const a = valueSets[i];
+      const b = valueSets[j];
+      // Concept-similarity gate: two enums are treated as the same logical
+      // enum only when they share >= 3 values AND those shared values
+      // dominate both sides (>= 50% of the larger set). A handful of
+      // shared sentinels (`unknown`, `pending`) recurs across unrelated
+      // domains (`AuthMethod` on Radar assessments vs. sessions: only
+      // `password`/`passkey`/`sso`/`unknown` overlap out of ~15 total), and
+      // that sparse overlap shouldn't count as drift.
+      let shared = 0;
+      for (const v of a) {
+        if (b.has(v)) shared++;
+      }
+      if (shared < 3) continue;
+      const larger = Math.max(a.size, b.size);
+      if (larger === 0 || shared / larger < 0.5) continue;
+      // Both sides must have values the other lacks — a subset is legitimate
+      // narrowing, not drift.
+      let aHasExtra = false;
+      for (const v of a) {
+        if (!b.has(v)) {
+          aHasExtra = true;
+          break;
+        }
+      }
+      if (!aHasExtra) continue;
+      for (const v of b) {
+        if (!a.has(v)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function trailingPascalStem(name: string): string | null {
+  // Extract the last two PascalCase segments so that `SSOConnectionType`
+  // and `ConnectionFindResponseConnectionType` both map to `ConnectionType`.
+  const segments = name.match(/[A-Z]+[a-z0-9]*/g);
+  if (!segments || segments.length < 2) return null;
+  return segments.slice(-2).join('');
+}
+
+function valueSignature(e: Enum): string {
+  return [...e.values]
+    .map((v) => String(v.value))
+    .sort()
+    .join('|');
+}
+
+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;
+}
+
+/**
+ * Collect all enum names referenced anywhere in the spec — model fields,
+ * operation params, request bodies, and responses. Used to prune orphan
+ * enums that the IR extracted from the spec but that no generated code
+ * actually references.
+ */
+function collectReferencedEnumNames(ctx: EmitterContext): Set<string> {
+  const refs = new Set<string>();
+  const collect = (ref: any) => {
+    walkTypeRef(ref, { enum: (r: any) => refs.add(r.name) });
+  };
+  // Walk the enriched models (which include synthetic fields from oneOf
+  // flattening) so synthetic enums are also counted as referenced.
+  const enrichedModels = enrichModelsFromSpec(ctx.spec.models);
+  for (const model of enrichedModels) {
+    for (const field of model.fields) {
+      collect(field.type);
+    }
+  }
+  for (const service of ctx.spec.services) {
+    for (const op of service.operations) {
+      if (op.requestBody) collect(op.requestBody);
+      if (op.response) collect(op.response);
+      for (const p of [...op.pathParams, ...op.queryParams, ...op.headerParams, ...(op.cookieParams ?? [])]) {
+        collect(p.type);
+      }
+    }
+  }
+  return refs;
+}
+
+/** Get the canonical enum name if the given enum is an alias. */
+export function resolveEnumName(name: string, enums: Enum[]): string {
+  const aliasOf = collectEnumAliasOf(enums);
+  return aliasOf.get(name) ? className(aliasOf.get(name)!) : className(name);
+}
+
+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/dotnet/fixtures.ts

@@ -0,0 +1,236 @@
+import type { Model, TypeRef, Enum } from '@workos/oagen';
+import { fixtureFileName, 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;
+
+    const fixture = model.fields.length === 0 ? {} : generateModelFixture(model, modelMap, enumMap);
+
+    files.push({
+      path: `testdata/${fixtureFileName(model.name)}.json`,
+      content: JSON.stringify(fixture, null, 2),
+    });
+
+    // Generate null-field variant for models with nullable/optional fields
+    const hasNullableFields = model.fields.some((f) => !f.required || f.type.kind === 'nullable');
+    if (hasNullableFields && model.fields.length > 0) {
+      const nullFixture: Record<string, any> = {};
+      for (const field of model.fields) {
+        if (!field.required || field.type.kind === 'nullable') {
+          nullFixture[field.name] = null;
+        } else {
+          nullFixture[field.name] = fixture[field.name] ?? null;
+        }
+      }
+      files.push({
+        path: `testdata/${fixtureFileName(model.name)}_nulls.json`,
+        content: JSON.stringify(nullFixture, 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: `testdata/list_${fixtureFileName(itemModel.name)}.json`,
+            content: JSON.stringify(listFixture, null, 2),
+          });
+        }
+      }
+    }
+  }
+
+  // Generate empty 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;
+          const emptyFixture = {
+            data: [],
+            list_metadata: {
+              before: null,
+              after: null,
+            },
+          };
+          files.push({
+            path: `testdata/list_empty_${fixtureFileName(itemModel.name)}.json`,
+            content: JSON.stringify(emptyFixture, null, 2),
+          });
+        }
+      }
+    }
+  }
+
+  // Deduplicate fixtures by path (keep last-written for each path)
+  const byPath = new Map<string, { path: string; content: string }>();
+  for (const f of files) {
+    byPath.set(f.path, f);
+  }
+
+  return [...byPath.values()];
+}
+
+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> = {};
+
+  const seenFieldNames = new Set<string>();
+  const deduplicatedFields = model.fields.filter((f) => {
+    const csName = fieldName(f.name);
+    if (seenFieldNames.has(csName)) return false;
+    seenFieldNames.add(csName);
+    return true;
+  });
+
+  for (const field of deduplicatedFields) {
+    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,
+  fName: string,
+  modelName: string,
+  modelMap: Map<string, Model>,
+  enumMap: Map<string, Enum>,
+): any {
+  switch (ref.kind) {
+    case 'primitive':
+      return generatePrimitiveValue(ref.type, ref.format, fName, 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, fName, modelName, modelMap, enumMap);
+      return [item];
+    }
+    case 'nullable':
+      return generateFieldValue(ref.inner, fName, modelName, modelMap, enumMap);
+    case 'union':
+      if (ref.variants.length > 0) {
+        return generateFieldValue(ref.variants[0], fName, 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;
+  }
+}