@workos/oagen-emitters 0.2.1 → 0.4.0

package/src/go/models.ts

@@ -0,0 +1,254 @@
+import type { Model, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { mapTypeRef } from './type-map.js';
+import { className, fieldName } from './naming.js';
+import { lowerFirstForDoc, fieldDocComment, articleFor } from '../shared/naming-utils.js';
+
+// Import and re-export shared model detection utilities
+import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+export { isListWrapperModel, isListMetadataModel };
+
+/**
+ * Generate Go struct definitions from IR Models.
+ * All models go into a single models.go file for the flat package.
+ */
+export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  const files: GeneratedFile[] = [];
+  const lines: string[] = [];
+
+  lines.push(`package ${ctx.namespace}`);
+  lines.push('');
+
+  // Build structural hash for deduplication
+  const modelHashMap = new Map<string, string>();
+  const hashGroups = new Map<string, string[]>();
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(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.
+  // Empty structs (hash '') are now properly populated by oneOf flattening,
+  // so we still skip aliasing them to avoid aliasing truly empty structs.
+  const aliasOf = new Map<string, string>();
+  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++) {
+      aliasOf.set(sorted[i], canonical);
+    }
+  }
+
+  const batchedAliases = new Set<string>();
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+
+    const structName = className(model.name);
+
+    // If this model is a dedup alias, emit a type alias.
+    // For large alias groups (5+), use a compact batch declaration.
+    const canonicalName = aliasOf.get(model.name);
+    if (canonicalName) {
+      // Check if this alias is part of a batch that was already emitted
+      if (batchedAliases.has(model.name)) continue;
+
+      const canonicalStruct = className(canonicalName);
+      const hash = modelHashMap.get(model.name)!;
+      const groupNames = hashGroups.get(hash) ?? [];
+      const aliases = groupNames.filter((n) => aliasOf.has(n));
+
+      if (aliases.length >= 5) {
+        // Batch emit all aliases for this group at once
+        for (const aliasName of aliases) {
+          batchedAliases.add(aliasName);
+        }
+        lines.push(`// The following types are structurally identical to ${canonicalStruct}.`);
+        lines.push('type (');
+        for (const aliasName of aliases) {
+          lines.push(`\t${className(aliasName)} = ${canonicalStruct}`);
+        }
+        lines.push(')');
+        lines.push('');
+      } else {
+        lines.push(`// ${structName} is an alias for ${canonicalStruct}.`);
+        lines.push(`type ${structName} = ${canonicalStruct}`);
+        lines.push('');
+      }
+      continue;
+    }
+
+    // Emit struct
+    if (model.description) {
+      const descLines = model.description.split('\n').filter((l) => l.trim());
+      lines.push(`// ${structName} ${lowerFirst(descLines[0])}`);
+      for (let i = 1; i < descLines.length; i++) {
+        lines.push(`// ${descLines[i].trim()}`);
+      }
+    } else {
+      const humanized = humanize(model.name);
+      lines.push(`// ${structName} represents ${articleFor(humanized)} ${humanized}.`);
+    }
+    lines.push(`type ${structName} struct {`);
+
+    // Deduplicate fields by Go field name
+    const seenFieldNames = new Set<string>();
+    for (const field of model.fields) {
+      const goFieldName = fieldName(field.name);
+      if (seenFieldNames.has(goFieldName)) continue;
+      seenFieldNames.add(goFieldName);
+
+      const isOptional = !field.required;
+      const goType = isOptional ? makeOptional(mapTypeRef(field.type)) : mapTypeRef(field.type);
+
+      const jsonTag = field.required ? `json:"${field.name}"` : `json:"${field.name},omitempty"`;
+
+      if (field.description) {
+        const fdLines = field.description.split('\n').filter((l) => l.trim());
+        lines.push(`\t// ${fieldDocComment(goFieldName, fdLines[0])}`);
+        for (let i = 1; i < fdLines.length; i++) {
+          lines.push(`\t// ${fdLines[i].trim()}`);
+        }
+      }
+      if (field.deprecated) {
+        if (field.description) lines.push(`\t//`);
+        const deprecationReason = extractDeprecationReason(field.description);
+        lines.push(`\t// Deprecated: ${deprecationReason}`);
+      }
+      lines.push(`\t${goFieldName} ${goType} \`${jsonTag}\``);
+    }
+
+    lines.push('}');
+    lines.push('');
+  }
+
+  // Emit shared PaginationParams struct for list operations to embed
+  lines.push('// PaginationParams contains common pagination parameters for list operations.');
+  lines.push('type PaginationParams struct {');
+  lines.push('\t// Before is a cursor for reverse pagination.');
+  lines.push('\tBefore *string `url:"before,omitempty" json:"-"`');
+  lines.push('\t// After is a cursor for forward pagination.');
+  lines.push('\tAfter *string `url:"after,omitempty" json:"-"`');
+  lines.push('\t// Limit is the maximum number of items to return per page.');
+  lines.push('\tLimit *int `url:"limit,omitempty" json:"-"`');
+  lines.push('\t// Order is the sort order for results (asc or desc).');
+  lines.push('\tOrder *string `url:"order,omitempty" json:"-"`');
+  lines.push('}');
+  lines.push('');
+
+  files.push({
+    path: 'models.go',
+    content: lines.join('\n'),
+    overwriteExisting: true,
+  });
+
+  return files;
+}
+
+/**
+ * Make a Go type optional (pointer) if it isn't already.
+ */
+function makeOptional(goType: string): string {
+  if (goType.startsWith('*') || goType.startsWith('[]') || goType.startsWith('map[')) {
+    return goType;
+  }
+  return `*${goType}`;
+}
+
+function structuralHash(model: Model): string {
+  return model.fields
+    .map((f) => `${f.name}:${JSON.stringify(f.type)}:${f.required}`)
+    .sort()
+    .join('|');
+}
+
+/** Known acronyms to preserve as single tokens during humanization. */
+const HUMANIZE_ACRONYMS: [RegExp, string][] = [
+  [/OAuth/g, 'OAUTH_ACRN'],
+  [/URN/g, 'URN_ACRN'],
+  [/IETF/g, 'IETF_ACRN'],
+  [/API/g, 'API_ACRN'],
+  [/SSO/g, 'SSO_ACRN'],
+  [/PKCE/g, 'PKCE_ACRN'],
+  [/JWT/g, 'JWT_ACRN'],
+  [/MFA/g, 'MFA_ACRN'],
+  [/TOTP/g, 'TOTP_ACRN'],
+  [/SAML/g, 'SAML_ACRN'],
+  [/SCIM/g, 'SCIM_ACRN'],
+  [/OIDC/g, 'OIDC_ACRN'],
+  [/CORS/g, 'CORS_ACRN'],
+  [/RBAC/g, 'RBAC_ACRN'],
+];
+
+const HUMANIZE_RESTORE: [RegExp, string][] = [
+  [/oauth_acrn/g, 'OAuth'],
+  [/urn_acrn/g, 'URN'],
+  [/ietf_acrn/g, 'IETF'],
+  [/api_acrn/g, 'API'],
+  [/sso_acrn/g, 'SSO'],
+  [/pkce_acrn/g, 'PKCE'],
+  [/jwt_acrn/g, 'JWT'],
+  [/mfa_acrn/g, 'MFA'],
+  [/totp_acrn/g, 'TOTP'],
+  [/saml_acrn/g, 'SAML'],
+  [/scim_acrn/g, 'SCIM'],
+  [/oidc_acrn/g, 'OIDC'],
+  [/cors_acrn/g, 'CORS'],
+  [/rbac_acrn/g, 'RBAC'],
+];
+
+function humanize(name: string): string {
+  // Replace known acronyms with placeholders before splitting
+  let s = name;
+  for (const [pattern, replacement] of HUMANIZE_ACRONYMS) {
+    s = s.replace(pattern, replacement);
+  }
+  // Split camelCase/PascalCase into words
+  let result = s.replace(/([a-z])([A-Z])/g, '$1 $2');
+  result = result.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+  result = result.toLowerCase();
+  // Restore acronyms
+  for (const [pattern, replacement] of HUMANIZE_RESTORE) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+function lowerFirst(s: string): string {
+  return lowerFirstForDoc(s);
+}
+
+/**
+ * Extract a deprecation reason from a field description.
+ * Looks for patterns like "Use X instead", "Replaced by Y", etc.
+ * Falls back to a generic message if no migration guidance is found.
+ */
+function extractDeprecationReason(description?: string): string {
+  if (!description) return 'this field is deprecated.';
+
+  // Common patterns: "Use X instead", "Replaced by X", "Deprecated in favor of X"
+  const patterns = [
+    /\b(use\s+\S+(?:\s+\S+){0,3}\s+instead)\b/i,
+    /\b(replaced\s+by\s+\S+(?:\s+\S+){0,3})\b/i,
+    /\b(deprecated\s+in\s+favor\s+of\s+\S+(?:\s+\S+){0,3})\b/i,
+    /\b(prefer\s+\S+(?:\s+\S+){0,3})\b/i,
+    /\b(migrate\s+to\s+\S+(?:\s+\S+){0,3})\b/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = description.match(pattern);
+    if (match) {
+      let reason = match[1].trim();
+      // Ensure it ends with a period
+      if (!reason.endsWith('.')) reason += '.';
+      return reason;
+    }
+  }
+
+  return 'this field is deprecated.';
+}

package/src/go/naming.ts

@@ -0,0 +1,179 @@
+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';
+
+/**
+ * Go-specific acronym extensions beyond the shared base set.
+ * Go convention requires ALL_CAPS for well-known initialisms.
+ */
+const GO_EXTRA_ACRONYM_FIXES: [RegExp, string][] = [
+  [/Jwks(?=[A-Z]|$)/g, 'JWKS'],
+  [/Totp(?=[A-Z]|$)/g, 'TOTP'],
+  [/Api(?=[A-Z]|$)/g, 'API'],
+  [/Urls(?=[A-Z]|$)/g, 'URLs'],
+  [/Url(?=[A-Z]|$)/g, 'URL'],
+  [/Uris(?=[A-Z]|$)/g, 'URIs'],
+  [/Uri(?=[A-Z]|$)/g, 'URI'],
+  [/Http(?=[A-Z]|$)/g, 'HTTP'],
+  [/Uuid(?=[A-Z]|$)/g, 'UUID'],
+  [/Json(?=[A-Z]|$)/g, 'JSON'],
+  [/Html(?=[A-Z]|$)/g, 'HTML'],
+  [/Ip(?=[A-Z]|$)/g, 'IP'],
+  [/Pkce/g, 'PKCE'],
+];
+
+/**
+ * Fix trailing "Id" to "ID" in Go convention.
+ * Must be applied after PascalCase and other acronym fixes.
+ */
+function fixTrailingId(s: string): string {
+  // Fix "Ids" → "IDs" first (plural), then "Id" → "ID" (singular)
+  let result = s.replace(/Ids(?=[A-Z]|$)/g, 'IDs');
+  result = result.replace(/Id(?=[A-Z]|$)/g, 'ID');
+  return result;
+}
+
+/** Apply all Go acronym conventions to a PascalCase string. */
+function applyAcronyms(s: string): string {
+  let result = applyAcronymFixes(s, GO_EXTRA_ACRONYM_FIXES);
+  result = fixTrailingId(result);
+  return result;
+}
+
+/** PascalCase type/struct name with Go acronym conventions. */
+export function className(name: string): string {
+  return applyAcronyms(toPascalCase(stripUrnPrefix(name)));
+}
+
+/** snake_case file name (without extension). */
+export function fileName(name: string): string {
+  return toSnakeCase(stripUrnPrefix(name));
+}
+
+/** PascalCase exported method name with Go acronym conventions. */
+export function methodName(name: string): string {
+  return applyAcronyms(toPascalCase(name));
+}
+
+/** PascalCase exported field name with Go acronym conventions. */
+export function fieldName(name: string): string {
+  return applyAcronyms(toPascalCase(name));
+}
+
+/** 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 unexportedName(className(name));
+}
+
+/** Lower-camel identifier with Go acronym conventions preserved. */
+export function unexportedName(name: string): string {
+  const exported = className(name);
+  if (!exported) return exported;
+
+  const initialism = exported.match(/^[A-Z]+(?=[A-Z][a-z]|[0-9]|$)/)?.[0];
+  if (initialism) {
+    return initialism.toLowerCase() + exported.slice(initialism.length);
+  }
+
+  return exported.charAt(0).toLowerCase() + exported.slice(1);
+}
+
+/** Resolve the effective service name using resolved operations. */
+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 output directory for a service. */
+export function resolveServiceDir(resolvedServiceName: string): string {
+  return moduleName(resolvedServiceName);
+}
+
+/** 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 trimMountedResourceFromMethod(methodName(resolved), resolveClassName(_service, ctx));
+  const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
+  if (existing) return trimMountedResourceFromMethod(methodName(existing.methodName), resolveClassName(_service, ctx));
+  return trimMountedResourceFromMethod(methodName(op.name), resolveClassName(_service, ctx));
+}
+
+/** 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 className(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 className(existing.className);
+    }
+  }
+  return className(service.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;
+}
+
+function splitPascalWords(name: string): string[] {
+  return name.match(/[A-Z]+(?:[a-z]+|(?=[A-Z]|$))|[A-Z]?[a-z]+|[0-9]+/g) ?? [name];
+}
+
+function singularize(word: string): string {
+  if (word.endsWith('ies') && word.length > 3) {
+    return `${word.slice(0, -3)}y`;
+  }
+  if (word.endsWith('s') && !word.endsWith('ss')) {
+    return word.slice(0, -1);
+  }
+  return word;
+}
+
+function wordsMatch(left: string, right: string): boolean {
+  return singularize(left.toLowerCase()) === singularize(right.toLowerCase());
+}
+
+function trimMountedResourceFromMethod(method: string, mountName: string): string {
+  const methodWords = splitPascalWords(method);
+  if (methodWords.length < 2) return method;
+
+  const mountWords = splitPascalWords(className(mountName));
+  if (mountWords.length === 0) return method;
+
+  let matched = 0;
+  while (
+    matched < mountWords.length &&
+    matched + 1 < methodWords.length &&
+    wordsMatch(methodWords[matched + 1], mountWords[matched])
+  ) {
+    matched++;
+  }
+
+  if (matched === 0) return method;
+
+  return [methodWords[0], ...methodWords.slice(matched + 1)].join('');
+}