@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/dotnet/index.ts

@@ -0,0 +1,248 @@
+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, primeModelAliases } from './models.js';
+import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { generateEnums, primeEnumAliases } from './enums.js';
+import { generateResources } from './resources.js';
+import { generateClient } from './client.js';
+import { generateTests } from './tests.js';
+import { generateManifest } from './manifest.js';
+import { generateWrapperOptionsClasses } from './wrappers.js';
+import { groupByMount } from '../shared/resolved-ops.js';
+import { discriminatedUnions } from './type-map.js';
+
+/**
+ * Fix the namespace for C#. The CLI passes `--namespace workos` which gives
+ * namespacePascal = "Workos", but C# needs "WorkOS" (preserving the brand casing).
+ */
+function fixNamespace(ctx: EmitterContext): EmitterContext {
+  if (ctx.namespace === 'workos' || ctx.namespacePascal === 'Workos') {
+    return { ...ctx, namespacePascal: 'WorkOS' };
+  }
+  return ctx;
+}
+
+/** 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;
+}
+
+/** Prefix for source files so they land under the .csproj directory. */
+const SRC_PREFIX = 'src/WorkOS.net/';
+/** Prefix for test files so they land under the test project directory. */
+const TEST_PREFIX = 'test/WorkOSTests/';
+
+/** Prefix generated source file paths to match the .NET project layout. */
+function prefixSourcePaths(files: GeneratedFile[]): GeneratedFile[] {
+  for (const f of files) {
+    f.path = `${SRC_PREFIX}${f.path}`;
+  }
+  return files;
+}
+
+/** Prefix generated test/fixture paths to match the .NET test project layout. */
+function prefixTestPaths(files: GeneratedFile[]): GeneratedFile[] {
+  for (const f of files) {
+    f.path = `${TEST_PREFIX}${f.path}`;
+  }
+  return files;
+}
+
+export const dotnetEmitter: Emitter = {
+  language: 'dotnet',
+
+  generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+    const c = fixNamespace(ctx);
+    primeEnumAliases(c.spec.enums);
+    const enriched = enrichModelsFromSpec(models);
+    // Re-prime after enrichment so synthetic enums from oneOf branches are
+    // included in the alias map used by mapTypeRef during model emission.
+    const synEnumsForModels = getSyntheticEnums();
+    if (synEnumsForModels.length > 0) {
+      primeEnumAliases([...c.spec.enums, ...synEnumsForModels]);
+    }
+    const files = generateModels(enriched, c);
+
+    // Generate discriminator converters for oneOf unions with discriminator
+    if (discriminatedUnions.size > 0) {
+      for (const [baseName, disc] of discriminatedUnions) {
+        const converterName = `${baseName}DiscriminatorConverter`;
+        const lines: string[] = [];
+        lines.push(`namespace ${c.namespacePascal}`);
+        lines.push('{');
+        lines.push('    using System;');
+        lines.push('    using System.Text.Json;');
+        lines.push('    using System.Text.Json.Serialization;');
+        lines.push('    using Newtonsoft.Json;');
+        lines.push('    using Newtonsoft.Json.Linq;');
+        lines.push('');
+        lines.push(`    /// <summary>`);
+        lines.push(`    /// JSON converter that deserializes discriminated union variants`);
+        lines.push(`    /// based on the "${disc.property}" property.`);
+        lines.push(`    /// </summary>`);
+        lines.push(`    public class ${converterName} : Newtonsoft.Json.JsonConverter`);
+        lines.push('    {');
+        lines.push('        public override bool CanConvert(Type objectType) => objectType == typeof(object);');
+        lines.push('');
+        lines.push(
+          '        public override object ReadJson(Newtonsoft.Json.JsonReader reader, Type objectType, object existingValue, Newtonsoft.Json.JsonSerializer serializer)',
+        );
+        lines.push('        {');
+        lines.push('            var jObject = JObject.Load(reader);');
+        lines.push(`            var discriminatorValue = jObject["${disc.property}"]?.ToString();`);
+        lines.push('            switch (discriminatorValue)');
+        lines.push('            {');
+        for (const [value, modelName] of Object.entries(disc.mapping)) {
+          const csName = modelName.replace(/([a-z])([A-Z])/g, '$1$2');
+          lines.push(`                case "${value}": return jObject.ToObject<${csName}>(serializer);`);
+        }
+        lines.push('                default: return jObject.ToObject<object>(serializer);');
+        lines.push('            }');
+        lines.push('        }');
+        lines.push('');
+        lines.push(
+          '        public override void WriteJson(Newtonsoft.Json.JsonWriter writer, object value, Newtonsoft.Json.JsonSerializer serializer)',
+        );
+        lines.push('        {');
+        lines.push('            serializer.Serialize(writer, value);');
+        lines.push('        }');
+        lines.push('    }');
+        lines.push('}');
+
+        files.push({
+          path: `Client/Utilities/${converterName}.cs`,
+          content: lines.join('\n'),
+          overwriteExisting: true,
+        });
+      }
+    }
+
+    return prefixSourcePaths(ensureTrailingNewlines(files));
+  },
+
+  generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+    const c = fixNamespace(ctx);
+    // Ensure synthetic enums are populated regardless of method execution order.
+    // enrichModelsFromSpec is idempotent (cached raw spec) and populates the
+    // module-level synthetic-enum store consumed by getSyntheticEnums().
+    enrichModelsFromSpec(c.spec.models);
+    const syntheticEnums = getSyntheticEnums();
+    const allEnums = syntheticEnums.length > 0 ? [...enums, ...syntheticEnums] : enums;
+    return prefixSourcePaths(ensureTrailingNewlines(generateEnums(allEnums, c)));
+  },
+
+  generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
+    const c = fixNamespace(ctx);
+    const synEnums = getSyntheticEnums();
+    primeEnumAliases(synEnums.length > 0 ? [...c.spec.enums, ...synEnums] : c.spec.enums);
+    primeModelAliases(enrichModelsFromSpec(c.spec.models));
+    const files = generateResources(services, c);
+
+    // Also generate wrapper options classes
+    const mountGroups = groupByMount(c);
+    for (const [, group] of mountGroups) {
+      for (const resolvedOp of group.resolvedOps) {
+        if (resolvedOp.wrappers && resolvedOp.wrappers.length > 0) {
+          const wrapperOptionsLines = generateWrapperOptionsClasses(resolvedOp, c);
+          if (wrapperOptionsLines.length > 0) {
+            const mountName = resolvedOp.mountOn;
+            const optionsPath = `Services/${mountName}/_interfaces/${mountName}WrapperOptions.cs`;
+            const content = [
+              `namespace ${c.namespacePascal}`,
+              '{',
+              '    using System.Collections.Generic;',
+              '    using Newtonsoft.Json;',
+              '    using STJS = System.Text.Json.Serialization;',
+              ...wrapperOptionsLines,
+              '}',
+            ].join('\n');
+            files.push({
+              path: optionsPath,
+              content,
+              overwriteExisting: true,
+            });
+          }
+        }
+      }
+    }
+
+    return prefixSourcePaths(ensureTrailingNewlines(files));
+  },
+
+  generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    const c = fixNamespace(ctx);
+    return prefixSourcePaths(ensureTrailingNewlines(generateClient(spec, c)));
+  },
+
+  generateErrors(): GeneratedFile[] {
+    return [];
+  },
+
+  generateTypeSignatures(): GeneratedFile[] {
+    return [];
+  },
+
+  generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    const c = fixNamespace(ctx);
+    const synEnumsForTests = getSyntheticEnums();
+    primeEnumAliases(synEnumsForTests.length > 0 ? [...spec.enums, ...synEnumsForTests] : spec.enums);
+    primeModelAliases(enrichModelsFromSpec(c.spec.models));
+    return prefixTestPaths(ensureTrailingNewlines(generateTests(spec, c)));
+  },
+
+  generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateManifest(spec, fixNamespace(ctx)));
+  },
+
+  fileHeader(): string {
+    return '// This file is auto-generated by oagen. Do not edit.';
+  },
+
+  formatCommand(targetDir: string): FormatCommand | null {
+    // `dotnet format` applies both whitespace rules and analyzer code fixes
+    // (StyleCop, etc.) to the generated files, matching the target project's
+    // conventions. We prefer a .sln/.slnx/.csproj workspace so MSBuild loads
+    // the analyzer ruleset correctly.
+    const workspace = findDotnetWorkspace(targetDir);
+    if (!workspace) return null;
+
+    // `dotnet format` expects `--include` paths relative to the workspace
+    // (or absolute). Our harness appends absolute paths, which is fine.
+    // Run `--no-restore` so formatting doesn't trigger a package restore on
+    // every codegen run.
+    return {
+      cmd: 'dotnet',
+      args: ['format', workspace, '--no-restore', '--include'],
+      // Keep batches small enough to stay under argv length limits while
+      // still amortizing MSBuild startup across many files.
+      batchSize: 500,
+    };
+  },
+};
+
+/** Locate a .sln/.slnx/.csproj file in the target directory for `dotnet format`. */
+function findDotnetWorkspace(targetDir: string): string | null {
+  if (!fs.existsSync(targetDir)) return null;
+  const entries = fs.readdirSync(targetDir);
+  const sln = entries.find((e) => e.endsWith('.sln') || e.endsWith('.slnx'));
+  if (sln) return path.resolve(targetDir, sln);
+  const csproj = entries.find((e) => e.endsWith('.csproj'));
+  if (csproj) return path.resolve(targetDir, csproj);
+  return null;
+}

package/src/dotnet/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/dotnet/models.ts

@@ -0,0 +1,320 @@
+import type { Model, EmitterContext, GeneratedFile, TypeRef } from '@workos/oagen';
+import {
+  mapTypeRef,
+  isValueTypeRef,
+  isEnumRef,
+  emitJsonPropertyAttributes,
+  setModelAliases,
+  isModelAlias,
+} from './type-map.js';
+import {
+  articleFor,
+  fieldName,
+  humanize,
+  emitXmlDoc,
+  deprecationMessage,
+  escapeCsAttributeString,
+  modelClassName,
+} from './naming.js';
+
+// Import and re-export shared model detection utilities
+import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+export { isListWrapperModel, isListMetadataModel };
+
+/**
+ * Generate C# model classes from IR Models.
+ * Each model becomes a separate .cs file under Services/{mount}/Entities/.
+ * For initial generation, all models go into a flat Entities/ directory.
+ */
+export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  // Build a lookup from enum name → single wire value for 1-value enums so
+  // we can emit a const initializer on the owning property without needing
+  // the full EnumRef.values payload (which the IR sometimes omits on refs).
+  const enumConstByName = new Map<string, string>();
+  for (const e of ctx.spec.enums) {
+    if (e.values.length === 1) {
+      enumConstByName.set(e.name, String(e.values[0].value));
+    }
+  }
+
+  const files: GeneratedFile[] = [];
+
+  // Compute and publish model aliases so mapTypeRef rewrites references.
+  primeModelAliases(models);
+
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+
+    const csClassName = modelClassName(model.name);
+
+    // Skip alias models — all references are already rewritten to the
+    // canonical type by mapTypeRef, so the alias class would be dead code.
+    if (isModelAlias(model.name)) continue;
+
+    const lines: string[] = [];
+    const fieldTypes = model.fields.map((f) => mapTypeRef(f.type));
+    const needsCollections = fieldTypes.some((t) => t.startsWith('List<') || t.startsWith('Dictionary<'));
+    const needsSystem = fieldTypes.some((t) => t.includes('DateTimeOffset'));
+    const needsJsonAttrs = model.fields.some((f) => f.required && isEnumRef(f.type));
+
+    lines.push(`namespace ${ctx.namespacePascal}`);
+    lines.push('{');
+    if (needsSystem) {
+      lines.push('    using System;');
+    }
+    if (needsCollections) {
+      lines.push('    using System.Collections.Generic;');
+    }
+    if (needsJsonAttrs) {
+      lines.push('    using Newtonsoft.Json;');
+      lines.push('    using STJS = System.Text.Json.Serialization;');
+    }
+    lines.push('');
+
+    // XML doc comment
+    if (model.description) {
+      lines.push(...emitXmlDoc(model.description, '    '));
+    } else {
+      const human = humanize(model.name);
+      lines.push(`    /// <summary>Represents ${articleFor(human)} ${human}.</summary>`);
+    }
+
+    lines.push(`    public class ${csClassName}`);
+    lines.push('    {');
+
+    // Track Dictionary<string, object> fields so we can emit a typed
+    // accessor helper per field at the end of the class body.
+    const dictObjectFields: Array<{ csName: string; typeText: string }> = [];
+
+    // Deduplicate fields by C# property name
+    const seenFieldNames = new Set<string>();
+    for (const field of model.fields) {
+      const csFieldName = fieldName(field.name);
+      if (seenFieldNames.has(csFieldName)) continue;
+      seenFieldNames.add(csFieldName);
+
+      const isOptional = !field.required;
+      const baseType = mapTypeRef(field.type);
+      const isAlreadyNullable = baseType.endsWith('?');
+      const constInit = singleValueConstInitializer(field.type, enumConstByName);
+      let csType: string;
+      let initializer = '';
+      let setterModifier = '';
+
+      if (constInit !== null) {
+        // Discriminator-style single-value enum/literal: emit with a const
+        // initializer and a non-public setter so callers can't drift the
+        // wire value. The converter still reads whatever the server sends.
+        csType = baseType;
+        initializer = ` = ${constInit};`;
+        setterModifier = 'internal ';
+      } else if (isOptional) {
+        if (isAlreadyNullable) {
+          csType = baseType;
+        } else if (isValueTypeRef(field.type)) {
+          csType = `${baseType}?`;
+        } else {
+          // With nullable enabled, optional reference types need `?`
+          csType = `${baseType}?`;
+        }
+      } else {
+        csType = baseType;
+        // Required non-nullable reference types need = default! to suppress CS8618
+        if (!isAlreadyNullable && !isValueTypeRef(field.type)) {
+          initializer = ' = default!;';
+        }
+      }
+
+      // Field description (full multi-line, with continuations as <remarks>)
+      const fieldDocs = emitXmlDoc(field.description, '        ');
+      if (fieldDocs.length > 0) {
+        lines.push('');
+        lines.push(...fieldDocs);
+      }
+
+      if (field.deprecated) {
+        const msg = escapeCsAttributeString(deprecationMessage(field.description, 'field'));
+        lines.push(`        [System.Obsolete("${msg}")]`);
+      }
+
+      const isRequiredEnum = field.required && isEnumRef(field.type) && constInit === null;
+      lines.push(...emitJsonPropertyAttributes(field.name, { isRequiredEnum }));
+      lines.push(`        public ${csType} ${csFieldName} { get; ${setterModifier}set; }${initializer}`);
+
+      // Track additional-properties / metadata dictionaries for typed accessors.
+      // Skip deprecated fields so the generated accessor doesn't reference
+      // a field marked `[System.Obsolete]` (which would fail the build).
+      if (isDictionaryOfObject(csType) && !field.deprecated) {
+        dictObjectFields.push({ csName: csFieldName, typeText: csType });
+      }
+    }
+
+    for (const dict of dictObjectFields) {
+      lines.push('');
+      lines.push(`        /// <summary>`);
+      lines.push(`        /// Typed accessor for <see cref="${dict.csName}"/>. Returns the value stored under`);
+      lines.push(`        /// <paramref name="key"/> coerced to <typeparamref name="T"/>, or the default`);
+      lines.push(`        /// value when the key is missing or the value is not convertible.`);
+      lines.push(`        /// </summary>`);
+      lines.push(`        /// <typeparam name="T">Expected value type.</typeparam>`);
+      lines.push(`        /// <param name="key">The key to look up.</param>`);
+      lines.push(`        public T? Get${dict.csName}Attribute<T>(string key)`);
+      lines.push('        {');
+      lines.push(`            if (this.${dict.csName} == null)`);
+      lines.push('            {');
+      lines.push('                return default;');
+      lines.push('            }');
+      lines.push('');
+      lines.push(`            if (!this.${dict.csName}.TryGetValue(key, out var value))`);
+      lines.push('            {');
+      lines.push('                return default;');
+      lines.push('            }');
+      lines.push('');
+      lines.push('            if (value is T typed)');
+      lines.push('            {');
+      lines.push('                return typed;');
+      lines.push('            }');
+      lines.push('');
+      lines.push('            if (value is Newtonsoft.Json.Linq.JToken token)');
+      lines.push('            {');
+      lines.push('                return token.ToObject<T>();');
+      lines.push('            }');
+      lines.push('');
+      lines.push('            if (value is System.Text.Json.JsonElement element)');
+      lines.push('            {');
+      lines.push('                return System.Text.Json.JsonSerializer.Deserialize<T>(element.GetRawText());');
+      lines.push('            }');
+      lines.push('');
+      lines.push('            return default;');
+      lines.push('        }');
+    }
+
+    lines.push('    }');
+    lines.push('}');
+
+    files.push({
+      path: `Entities/${csClassName}.cs`,
+      content: lines.join('\n'),
+      overwriteExisting: true,
+    });
+  }
+
+  return files;
+}
+
+/**
+ * Whether the emitted C# type is `Dictionary<string, object>` or its
+ * nullable variant — the usual shape of metadata / additional-properties
+ * fields that get typed accessors.
+ */
+function isDictionaryOfObject(csType: string): boolean {
+  const bare = csType.endsWith('?') ? csType.slice(0, -1) : csType;
+  return bare === 'Dictionary<string, object>';
+}
+
+/**
+ * If the given TypeRef is a single-value enum / literal (a discriminator
+ * const masquerading as an enum), return the C# literal expression (already
+ * quoted for strings, bare for bool/number) so the emitter can lock the
+ * field down with a const initializer and non-public setter. Returns null
+ * for any other type.
+ */
+function singleValueConstInitializer(ref: TypeRef, enumConstByName: Map<string, string>): string | null {
+  // OpenAPI `enum: [value]` (single-value) is normalized by the IR to a
+  // LiteralType on the field, not an EnumRef. Emit per-type: booleans and
+  // numbers are bare literals; strings get JSON-quoted.
+  if (ref.kind === 'literal') {
+    if (ref.value === null) return null;
+    if (typeof ref.value === 'boolean') return ref.value ? 'true' : 'false';
+    if (typeof ref.value === 'number') return String(ref.value);
+    if (typeof ref.value === 'string') return JSON.stringify(ref.value);
+    return null;
+  }
+  if (ref.kind !== 'enum') return null;
+  let wire: string | null = null;
+  if (ref.values && ref.values.length === 1) {
+    const v = ref.values[0] as string | number | { value: string | number };
+    wire = typeof v === 'string' || typeof v === 'number' ? String(v) : String(v.value);
+  } else {
+    wire = enumConstByName.get(ref.name) ?? null;
+  }
+  if (wire === null) return null;
+  // Enum wire values serialize as strings in JSON, and mapTypeRef returns
+  // `string` for single-value enums — so always quote.
+  return JSON.stringify(wire);
+}
+
+/**
+ * Compute and publish the model alias map. Safe to call multiple times
+ * (idempotent for a given set of models). Must be invoked before any emitter
+ * phase that calls `mapTypeRef` with model references.
+ */
+export function primeModelAliases(models: Model[]): void {
+  const eligibleModels = models.filter((m) => !isListWrapperModel(m) && !isListMetadataModel(m));
+  const aliasOf = new Map<string, string>();
+  while (true) {
+    const hashGroups = new Map<string, string[]>();
+    for (const model of eligibleModels) {
+      const hash = structuralHash(model, aliasOf);
+      if (!hashGroups.has(hash)) hashGroups.set(hash, []);
+      hashGroups.get(hash)!.push(model.name);
+    }
+
+    let added = false;
+    for (const [hash, names] of hashGroups) {
+      if (names.length <= 1) continue;
+      if (hash === '') continue;
+      const sorted = [...names].sort();
+      const canonical = sorted[0];
+      for (let i = 1; i < sorted.length; i++) {
+        const name = sorted[i];
+        if (aliasOf.get(name) !== canonical) {
+          aliasOf.set(name, canonical);
+          added = true;
+        }
+      }
+    }
+    if (!added) break;
+  }
+  setModelAliases(aliasOf);
+}
+
+/**
+ * Normalize a TypeRef for structural comparison.
+ * Enum references are normalized to their values (not names) so that
+ * structurally identical enums with different names still match.
+ * Model references are rewritten to their canonical alias (if any) so that
+ * parents whose only difference is an already-aliased child collapse too.
+ */
+function normalizeTypeForHash(ref: TypeRef, aliasOf: Map<string, string>): any {
+  if (ref.kind === 'enum') {
+    // Normalize enum refs by their sorted values, not their name
+    const vals = ref.values ? [...ref.values].sort() : [];
+    return { kind: 'enum', values: vals };
+  }
+  if (ref.kind === 'model') {
+    return { kind: 'model', name: aliasOf.get(ref.name) ?? ref.name };
+  }
+  if (ref.kind === 'nullable') {
+    return { kind: 'nullable', inner: normalizeTypeForHash(ref.inner, aliasOf) };
+  }
+  if (ref.kind === 'array') {
+    return { kind: 'array', items: normalizeTypeForHash(ref.items, aliasOf) };
+  }
+  if (ref.kind === 'union') {
+    return { kind: 'union', variants: ref.variants.map((v) => normalizeTypeForHash(v, aliasOf)) };
+  }
+  if (ref.kind === 'map') {
+    return { kind: 'map', valueType: normalizeTypeForHash(ref.valueType, aliasOf) };
+  }
+  return ref;
+}
+
+function structuralHash(model: Model, aliasOf: Map<string, string> = new Map()): string {
+  return model.fields
+    .map((f) => `${f.name}:${JSON.stringify(normalizeTypeForHash(f.type, aliasOf))}:${f.required}`)
+    .sort()
+    .join('|');
+}