@workos/oagen-emitters 0.11.0 → 0.12.1

package/src/rust/enums.ts

@@ -0,0 +1,201 @@
+import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { typeName, moduleName, variantName } from './naming.js';
+
+/**
+ * Generate one Rust source file per enum under `src/enums/`, plus a
+ * `src/enums/mod.rs` barrel.
+ *
+ * Each enum is emitted as a string-backed, forward-compatible Rust enum:
+ *   - `#[non_exhaustive]` so callers can't write exhaustive matches that
+ *     break when WorkOS adds a new value server-side.
+ *   - A fallback variant (`Unknown(String)` by default, or `Unrecognized` /
+ *     `Other` / `OagenUnknown` if the spec already defines a variant by that
+ *     name) captures any wire value the SDK doesn't yet recognize, preserving
+ *     the original string instead of failing deserialization.
+ *   - Manual `Serialize`/`Deserialize` map between the canonical wire string
+ *     and the Rust variant; alias wire values deserialize into the canonical
+ *     variant and re-serialize as the canonical wire string.
+ *   - `Display`, `FromStr`, and `AsRef<str>` are implemented for ergonomics.
+ */
+export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const seen = new Set<string>();
+  const moduleNames: string[] = [];
+
+  for (const e of enums) {
+    if (!e.values || e.values.length === 0) continue;
+    const mod = moduleName(e.name);
+    if (seen.has(mod)) continue;
+    seen.add(mod);
+    moduleNames.push(mod);
+
+    files.push({
+      path: `src/enums/${mod}.rs`,
+      content: renderEnum(e),
+      overwriteExisting: true,
+    });
+  }
+
+  files.push({
+    path: 'src/enums/mod.rs',
+    content: renderEnumsBarrel(moduleNames),
+    overwriteExisting: true,
+  });
+
+  return files;
+}
+
+function renderEnum(e: Enum): string {
+  const lines: string[] = [];
+  const tname = typeName(e.name);
+
+  // Collapse wire values that map to the same Rust variant. The first wire
+  // value for a variant is the canonical one (used for serialization); the
+  // remaining ones are aliases (accepted on deserialization).
+  const order: string[] = [];
+  const wireByVariant = new Map<string, string[]>();
+  const descByVariant = new Map<string, string | undefined>();
+  const deprecatedByVariant = new Map<string, boolean>();
+  for (const v of e.values) {
+    const variant = variantName(v.value);
+    if (!wireByVariant.has(variant)) {
+      wireByVariant.set(variant, []);
+      order.push(variant);
+      descByVariant.set(variant, v.description);
+      deprecatedByVariant.set(variant, !!v.deprecated);
+    }
+    wireByVariant.get(variant)!.push(String(v.value));
+  }
+
+  // Pick a fallback-variant name that doesn't collide with an existing one.
+  // Prefer `Unknown` for ergonomics; fall back to less-likely names for the
+  // (rare) enums whose spec already defines `Unknown`/`Unrecognized`/`Other`.
+  const taken = new Set(order);
+  const FB = ['Unknown', 'Unrecognized', 'Other', 'OagenUnknown'].find((c) => !taken.has(c)) ?? 'OagenUnknown';
+
+  lines.push('use serde::{Deserialize, Serialize};');
+  lines.push('use std::fmt;');
+  lines.push('use std::str::FromStr;');
+  lines.push('');
+
+  lines.push('#[derive(Debug, Clone, PartialEq, Eq, Hash)]');
+  lines.push('#[non_exhaustive]');
+  lines.push(`pub enum ${tname} {`);
+  for (const variant of order) {
+    const desc = descByVariant.get(variant);
+    if (desc) {
+      for (const c of docComment(desc)) lines.push(`    ${c}`);
+    }
+    if (deprecatedByVariant.get(variant)) lines.push('    #[allow(deprecated)]');
+    lines.push(`    ${variant},`);
+  }
+  lines.push('    /// Wire value not recognized by this SDK version. The original');
+  lines.push('    /// string is preserved verbatim. WorkOS may add new enum values');
+  lines.push('    /// server-side; matching on this variant lets callers handle');
+  lines.push('    /// forward-compatible values without panicking.');
+  lines.push(`    ${FB}(String),`);
+  lines.push('}');
+  lines.push('');
+
+  // as_str(): canonical wire value for known variants, inner string for fallback.
+  lines.push(`impl ${tname} {`);
+  lines.push(`    /// Canonical wire string for this value. For [\`Self::${FB}\`] returns the`);
+  lines.push('    /// original wire value as received from the API.');
+  lines.push('    #[allow(deprecated)]');
+  lines.push('    pub fn as_str(&self) -> &str {');
+  lines.push('        match self {');
+  for (const variant of order) {
+    const canonical = wireByVariant.get(variant)![0]!;
+    lines.push(`            Self::${variant} => ${JSON.stringify(canonical)},`);
+  }
+  lines.push(`            Self::${FB}(s) => s.as_str(),`);
+  lines.push('        }');
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+
+  // Display via as_str().
+  lines.push(`impl fmt::Display for ${tname} {`);
+  lines.push("    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {");
+  lines.push('        f.write_str(self.as_str())');
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+
+  // AsRef<str>.
+  lines.push(`impl AsRef<str> for ${tname} {`);
+  lines.push('    fn as_ref(&self) -> &str {');
+  lines.push('        self.as_str()');
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+
+  // FromStr — infallible (fallback variant captures anything else).
+  lines.push(`impl FromStr for ${tname} {`);
+  lines.push('    type Err = std::convert::Infallible;');
+  lines.push('    #[allow(deprecated)]');
+  lines.push('    fn from_str(s: &str) -> Result<Self, Self::Err> {');
+  lines.push('        Ok(match s {');
+  for (const variant of order) {
+    const wires = wireByVariant.get(variant)!;
+    for (const w of wires) {
+      lines.push(`            ${JSON.stringify(w)} => Self::${variant},`);
+    }
+  }
+  lines.push(`            other => Self::${FB}(other.to_string()),`);
+  lines.push('        })');
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+
+  // From<String>/From<&str>.
+  lines.push(`impl From<String> for ${tname} {`);
+  lines.push('    fn from(s: String) -> Self {');
+  lines.push('        // Reuse the original `String` allocation in the fallback branch.');
+  lines.push('        match Self::from_str(&s) {');
+  lines.push(`            Ok(Self::${FB}(_)) => Self::${FB}(s),`);
+  lines.push('            Ok(other) => other,');
+  lines.push('        }');
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+  lines.push(`impl From<&str> for ${tname} {`);
+  lines.push('    fn from(s: &str) -> Self {');
+  lines.push(`        Self::from_str(s).unwrap_or_else(|_| Self::${FB}(s.to_string()))`);
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+
+  // Manual Serialize / Deserialize.
+  lines.push(`impl Serialize for ${tname} {`);
+  lines.push('    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {');
+  lines.push('        serializer.serialize_str(self.as_str())');
+  lines.push('    }');
+  lines.push('}');
+  lines.push('');
+  lines.push(`impl<'de> Deserialize<'de> for ${tname} {`);
+  lines.push("    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {");
+  lines.push('        let s = String::deserialize(deserializer)?;');
+  lines.push('        Ok(Self::from(s))');
+  lines.push('    }');
+  lines.push('}');
+
+  return lines.join('\n') + '\n';
+}
+
+function renderEnumsBarrel(modules: string[]): string {
+  const sorted = [...new Set(modules)].sort();
+  const lines: string[] = [];
+  for (const m of sorted) lines.push(`pub mod ${m};`);
+  lines.push('');
+  for (const m of sorted) lines.push(`pub use ${m}::*;`);
+  return lines.join('\n') + '\n';
+}
+
+function docComment(text: string): string[] {
+  return text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .map((l) => `/// ${l}`);
+}

package/src/rust/fixtures.ts

@@ -0,0 +1,196 @@
+import type { ApiSpec, GeneratedFile, Model, Enum, TypeRef } from '@workos/oagen';
+import { walkTypeRef } from '@workos/oagen';
+import { moduleName } from './naming.js';
+
+/**
+ * Generate JSON test fixture files under `tests/fixtures/`. The Rust tests
+ * pull these in via `include_str!` so no I/O is required at test time.
+ */
+export function generateFixtures(spec: ApiSpec): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const modelMap = new Map(spec.models.map((m) => [m.name, m]));
+  const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
+  const seen = new Set<string>();
+
+  for (const model of spec.models) {
+    if (seen.has(model.name)) continue;
+    if (model.fields.length === 0) continue;
+    seen.add(model.name);
+
+    const fixture = generateModelFixture(model, modelMap, enumMap, new Set());
+    const path = `tests/fixtures/${moduleName(model.name)}.json`;
+    files.push({
+      path,
+      content: JSON.stringify(fixture, null, 2) + '\n',
+      headerPlacement: 'skip',
+    });
+  }
+
+  return files;
+}
+
+export function generateModelFixture(
+  model: Model,
+  modelMap: Map<string, Model>,
+  enumMap: Map<string, Enum>,
+  visiting: Set<string>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  if (visiting.has(model.name)) return result; // Break recursion.
+  visiting.add(model.name);
+
+  for (const field of model.fields) {
+    if (!field.required) continue;
+    // Prefer the spec `example` value when it is shape-compatible with the
+    // declared type. Falls back to the placeholder generator when no example
+    // is provided or when the example would not deserialize cleanly.
+    const fromExample = exampleFromSpec(field.example, field.type, enumMap);
+    result[field.name] =
+      fromExample !== undefined ? fromExample : exampleFor(field.type, modelMap, enumMap, visiting, field.name);
+  }
+
+  visiting.delete(model.name);
+  return result;
+}
+
+export function exampleFor(
+  type: TypeRef,
+  modelMap: Map<string, Model>,
+  enumMap: Map<string, Enum>,
+  visiting: Set<string>,
+  fieldName: string,
+): unknown {
+  switch (type.kind) {
+    case 'primitive':
+      switch (type.type) {
+        case 'string':
+          if (type.format === 'date-time') return '2023-01-01T00:00:00.000Z';
+          if (type.format === 'date') return '2023-01-01';
+          if (type.format === 'uuid') return '00000000-0000-0000-0000-000000000000';
+          if (fieldName === 'id') return 'test_id';
+          if (fieldName === 'email') return 'test@example.com';
+          return `test_${fieldName}`;
+        case 'integer':
+          return 0;
+        case 'number':
+          return 0;
+        case 'boolean':
+          return false;
+        case 'unknown':
+          return {};
+      }
+      return null;
+    case 'array':
+      return [exampleFor(type.items, modelMap, enumMap, visiting, fieldName)];
+    case 'map':
+      return {};
+    case 'nullable':
+      return exampleFor(type.inner, modelMap, enumMap, visiting, fieldName);
+    case 'literal':
+      return type.value;
+    case 'enum': {
+      const e = enumMap.get(type.name);
+      const v = e?.values?.[0]?.value;
+      return v ?? '';
+    }
+    case 'model': {
+      const m = modelMap.get(type.name);
+      if (!m) return {};
+      return generateModelFixture(m, modelMap, enumMap, visiting);
+    }
+    case 'union': {
+      // Find first model variant; fall back to empty object.
+      let result: unknown = null;
+      walkTypeRef(type.variants[0]!, {
+        primitive: () => {
+          result = exampleFor(type.variants[0]!, modelMap, enumMap, visiting, fieldName);
+        },
+      });
+      if (result === null) {
+        result = exampleFor(type.variants[0]!, modelMap, enumMap, visiting, fieldName);
+      }
+      return result;
+    }
+  }
+}
+
+/**
+ * Resolve a spec-provided `example` against a TypeRef and return the value to
+ * embed in the fixture, or `undefined` when the example cannot be used safely.
+ *
+ * "Safely" means the value would round-trip through serde to the generated
+ * Rust type. We deliberately only accept primitives, enum string/number
+ * values, and homogenous arrays of those; nested object examples (which the
+ * spec sometimes supplies as illustrative metadata blobs) are skipped because
+ * they rarely match the strict struct shape Rust expects.
+ */
+export function exampleFromSpec(example: unknown, type: TypeRef, enumMap: Map<string, Enum>): unknown {
+  if (example === undefined) return undefined;
+  // Spec authors sometimes use `null` as a sentinel; let placeholder gen
+  // handle nullable types so we don't emit `null` for required fields.
+  if (example === null) return undefined;
+  return matchExampleToType(example, type, enumMap);
+}
+
+function matchExampleToType(value: unknown, type: TypeRef, enumMap: Map<string, Enum>): unknown {
+  switch (type.kind) {
+    case 'primitive':
+      return matchPrimitive(value, type.type);
+    case 'literal':
+      return value === type.value ? value : undefined;
+    case 'enum': {
+      const e = enumMap.get(type.name);
+      if (!e) return undefined;
+      const ok = e.values.some((v) => v.value === value);
+      return ok ? value : undefined;
+    }
+    case 'array': {
+      if (!Array.isArray(value)) return undefined;
+      const out: unknown[] = [];
+      for (const item of value) {
+        const matched = matchExampleToType(item, type.items, enumMap);
+        if (matched === undefined) return undefined;
+        out.push(matched);
+      }
+      // Empty arrays are valid but unhelpful in fixtures — fall back so the
+      // placeholder generator can produce a one-element example.
+      if (out.length === 0) return undefined;
+      return out;
+    }
+    case 'nullable':
+      return matchExampleToType(value, type.inner, enumMap);
+    case 'map':
+      // Map examples are usually free-form metadata blobs that match
+      // `HashMap<String, _>`; only accept plain objects with string-keyed values.
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+      return value;
+    case 'union': {
+      for (const variant of type.variants) {
+        const matched = matchExampleToType(value, variant, enumMap);
+        if (matched !== undefined) return matched;
+      }
+      return undefined;
+    }
+    case 'model':
+      // Model-shaped examples are too risky to copy verbatim: they rarely
+      // supply every required field and may use wire names that don't align
+      // with the generated struct. Let the recursive generator handle them.
+      return undefined;
+  }
+}
+
+function matchPrimitive(value: unknown, primitive: 'string' | 'integer' | 'number' | 'boolean' | 'unknown'): unknown {
+  switch (primitive) {
+    case 'string':
+      return typeof value === 'string' ? value : undefined;
+    case 'integer':
+      return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+    case 'number':
+      return typeof value === 'number' ? value : undefined;
+    case 'boolean':
+      return typeof value === 'boolean' ? value : undefined;
+    case 'unknown':
+      // `unknown` deserialises to `serde_json::Value`, so any JSON value works.
+      return value;
+  }
+}

package/src/rust/index.ts

@@ -0,0 +1,95 @@
+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 { UnionRegistry } from './type-map.js';
+
+/**
+ * Shared per-emit registry that collects synthesised oneOf-style unions
+ * encountered in *any* call (model fields, request bodies, etc.). Rendered
+ * once into `src/models/_unions.rs` during the final structural pass so
+ * downstream files can reference the synthesised type names uniformly.
+ */
+const unionRegistry = new UnionRegistry();
+
+function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
+  for (const f of files) {
+    if (f.content && !f.content.endsWith('\n')) {
+      f.content += '\n';
+    }
+  }
+  return files;
+}
+
+export const rustEmitter: Emitter = {
+  language: 'rust',
+
+  generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+    unionRegistry.reset();
+    return ensureTrailingNewlines(generateModels(models, ctx, unionRegistry));
+  },
+
+  generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateEnums(enums, ctx));
+  },
+
+  generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateResources(services, ctx, unionRegistry));
+  },
+
+  generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateClient(spec, ctx, unionRegistry));
+  },
+
+  generateErrors(): GeneratedFile[] {
+    // Hand-maintained in the target SDK — `src/error.rs`, `src/client.rs`,
+    // `src/lib.rs`, `src/pagination.rs`, and `Cargo.toml` all carry
+    // `@oagen-ignore-file` and are not regenerated.
+    return [];
+  },
+
+  generateTypeSignatures(): GeneratedFile[] {
+    return [];
+  },
+
+  generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return ensureTrailingNewlines(generateTests(spec, ctx));
+  },
+
+  buildOperationsMap(spec: ApiSpec, ctx: EmitterContext) {
+    return buildOperationsMap(spec, ctx);
+  },
+
+  fileHeader(): string {
+    return '// Code generated by oagen. DO NOT EDIT.';
+  },
+
+  formatCommand(_targetDir: string): FormatCommand | null {
+    // oagen appends every generated file path (mixing .rs, Cargo.toml, .json
+    // fixtures) to the format command. `rustfmt` errors on non-`.rs` paths,
+    // so wrap it in a bash filter that only forwards `.rs` files. Same
+    // shape as the Go emitter's gofmt wrapper.
+    return {
+      cmd: 'bash',
+      args: [
+        '-c',
+        'RS_FILES=$(printf "%s\\n" "$@" | grep "\\.rs$"); [ -n "$RS_FILES" ] && echo "$RS_FILES" | xargs rustfmt --edition 2024 --quiet',
+        '--',
+      ],
+      batchSize: 999999,
+    };
+  },
+};

package/src/rust/manifest.ts

@@ -0,0 +1,31 @@
+import type { ApiSpec, EmitterContext, OperationsMap } from '@workos/oagen';
+import { methodName, moduleName } from './naming.js';
+import { groupByMount } from '../shared/resolved-ops.js';
+
+/**
+ * Build the operation→SDK-method map written into `.oagen-manifest.json`,
+ * which the smoke runner consults to dispatch HTTP operations to SDK calls.
+ *
+ * Keys are `METHOD /path`; values point at the mount-target accessor on
+ * `Client` and the resolved snake_case method name. Split operations register
+ * one entry per wrapper (the wrapper name takes precedence over the raw op
+ * name since the raw method does not exist in the generated SDK).
+ */
+export function buildOperationsMap(_spec: ApiSpec, ctx: EmitterContext): OperationsMap {
+  const map: OperationsMap = {};
+
+  for (const [mountName, group] of groupByMount(ctx)) {
+    const accessor = moduleName(mountName);
+    for (const r of group.resolvedOps) {
+      const httpKey = `${r.operation.httpMethod.toUpperCase()} ${r.operation.path}`;
+      if ((r.wrappers?.length ?? 0) > 0) {
+        const first = r.wrappers![0]!;
+        map[httpKey] = { sdkMethod: methodName(first.name), service: accessor };
+      } else {
+        map[httpKey] = { sdkMethod: methodName(r.methodName), service: accessor };
+      }
+    }
+  }
+
+  return map;
+}

package/src/rust/models.ts

@@ -0,0 +1,165 @@
+import type { Model, EmitterContext, GeneratedFile, Field } from '@workos/oagen';
+import { typeName, fieldName, moduleName } from './naming.js';
+import { mapTypeRef, makeOptional, UnionRegistry } from './type-map.js';
+import { applySecretRedaction } from './secret.js';
+
+const HEADER_PLACEHOLDER = ''; // engine prepends fileHeader()
+
+const UNIONS_MODULE = '_unions';
+
+/**
+ * Generate one Rust source file per model under `src/models/`, plus a
+ * `src/models/mod.rs` barrel that re-exports each module. Inline IR unions
+ * encountered in field positions are synthesised into a single
+ * `src/models/_unions.rs` module so the resulting Rust types are concrete.
+ */
+export function generateModels(models: Model[], ctx: EmitterContext, registry: UnionRegistry): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const moduleNames: string[] = [];
+  const seen = new Set<string>();
+
+  for (const model of models) {
+    // Empty-field, non-discriminator models still need to be emitted as an
+    // empty struct so request bodies that reference them (e.g. an empty
+    // `CreateApplicationSecretDto`) compile.
+    const mod = moduleName(model.name);
+    if (seen.has(mod)) continue;
+    seen.add(mod);
+    moduleNames.push(mod);
+
+    const hintPath = ctx.overlayLookup?.fileBySymbol?.get(model.name);
+    const path = hintPath ?? `src/models/${mod}.rs`;
+    files.push({ path, content: renderModel(model, registry), overwriteExisting: true });
+  }
+
+  // Always include the unions module in the barrel so downstream stages
+  // (resources, etc.) that register additional unions don't need to mutate
+  // the barrel after the fact. The actual `_unions.rs` file is rendered in
+  // generateClient once every stage has finished registering.
+  moduleNames.push(UNIONS_MODULE);
+
+  files.push({
+    path: 'src/models/mod.rs',
+    content: renderModelsBarrel(moduleNames),
+    overwriteExisting: true,
+  });
+
+  return files;
+}
+
+function renderModel(model: Model, registry: UnionRegistry): string {
+  const lines: string[] = [];
+  lines.push(HEADER_PLACEHOLDER);
+  // Match rustfmt's canonical grouping: keyword-rooted paths (`super`,
+  // `crate`) sort before external-crate paths (`serde`). Pre-emit in that
+  // order so `cargo fmt --check` does not reshuffle the file.
+  lines.push('#[allow(unused_imports)]');
+  lines.push('use super::*;');
+  lines.push('#[allow(unused_imports)]');
+  lines.push('use crate::enums::*;');
+  lines.push('use serde::{Deserialize, Serialize};');
+  lines.push('');
+
+  if (model.description) lines.push(...docComment(model.description));
+
+  lines.push('#[derive(Debug, Clone, Serialize, Deserialize)]');
+
+  const resolvedNames = resolveFieldNames(model.fields);
+  const fieldLines = model.fields.map((f, i) => renderField(f, resolvedNames[i]!, model.name, registry));
+
+  // rustfmt collapses zero-field structs to `pub struct Foo {}` on a single
+  // line. Match that shape so `cargo fmt --check` passes.
+  if (fieldLines.length === 0) {
+    lines.push(`pub struct ${typeName(model.name)} {}`);
+  } else {
+    lines.push(`pub struct ${typeName(model.name)} {`);
+    lines.push(...fieldLines);
+    lines.push('}');
+  }
+  return lines.filter((l) => l !== HEADER_PLACEHOLDER).join('\n') + '\n';
+}
+
+/**
+ * Resolve unique Rust identifiers for struct fields. Multiple wire names can
+ * collide after `fieldName()` snake-cases them (e.g. `integration_type` and
+ * `integrationType` both become `integration_type`). Subsequent collisions get
+ * a numeric suffix so the struct compiles; serde `rename` preserves the
+ * original wire name in every case.
+ */
+function resolveFieldNames(fields: Field[]): string[] {
+  const used = new Set<string>();
+  const out: string[] = [];
+  for (const f of fields) {
+    const base = fieldName(f.name);
+    let candidate = base;
+    let suffix = 2;
+    while (used.has(candidate)) {
+      candidate = `${base}_${suffix}`;
+      suffix++;
+    }
+    used.add(candidate);
+    out.push(candidate);
+  }
+  return out;
+}
+
+function renderField(field: Field, rustField: string, modelName: string, registry: UnionRegistry): string {
+  const lines: string[] = [];
+  const hasDescription = !!field.description;
+  if (hasDescription) {
+    for (const c of docComment(field.description!)) lines.push(`    ${c}`);
+  }
+  if (field.default != null) {
+    if (hasDescription) lines.push('    ///');
+    lines.push(`    /// Defaults to \`${formatDefault(field.default)}\`.`);
+  }
+
+  const rename = rustField !== field.name ? field.name : null;
+
+  let baseType = mapTypeRef(field.type, {
+    hint: `${typeName(modelName)}${typeName(field.name)}`,
+    registry,
+  });
+  const isOptional = !field.required || field.type.kind === 'nullable';
+  if (isOptional && !baseType.startsWith('Option<')) {
+    baseType = makeOptional(baseType);
+  }
+  // Wrap String / Option<String> in SecretString when the field name implies
+  // the value is a credential or token. Wire format is unchanged.
+  baseType = applySecretRedaction(baseType, field.name);
+
+  if (rename) lines.push(`    #[serde(rename = "${rename}")]`);
+  if (baseType.startsWith('Option<')) {
+    lines.push('    #[serde(skip_serializing_if = "Option::is_none", default)]');
+  }
+  if (field.deprecated) lines.push('    #[deprecated]');
+  lines.push(`    pub ${rustField}: ${baseType},`);
+  return lines.join('\n');
+}
+
+function renderModelsBarrel(modules: string[]): string {
+  const sorted = [...new Set(modules)].sort();
+  const lines: string[] = [];
+  for (const m of sorted) lines.push(`pub mod ${m};`);
+  lines.push('');
+  for (const m of sorted) lines.push(`pub use ${m}::*;`);
+  return lines.join('\n') + '\n';
+}
+
+function docComment(text: string): string[] {
+  return text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .map((l) => `/// ${l}`);
+}
+
+/**
+ * Render a spec-level default value for inclusion in a doc comment. Strings
+ * render bare (e.g. `desc`) so they nest naturally inside the surrounding
+ * backticks; numbers/booleans use JSON encoding.
+ */
+function formatDefault(value: unknown): string {
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value);
+}