@workos/oagen-emitters 0.18.3 → 0.19.0

package/src/ruby/models.ts

@@ -1,11 +1,12 @@
 import type { Model, EmitterContext, GeneratedFile, TypeRef, Field } from '@workos/oagen';
 import { walkTypeRef, assignModelsToServices } from '@workos/oagen';
-import { className, fieldName, fileName, buildMountDirMap } from './naming.js';
+import { className, domainFieldName, fileName, buildMountDirMap } from './naming.js';
 import {
   isListWrapperModel,
   isListMetadataModel,
   collectNonPaginatedResponseModelNames,
 } from '../shared/model-utils.js';
+import { isModelInScope } from '../shared/resolved-ops.js';
 
 /** Folder under lib/workos/ for models not owned by any service. */
 export const SHARED_MODEL_DIR = 'shared';
@@ -119,19 +120,25 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       lines.push('module WorkOS');
       lines.push(`  ${cls} = ${canonCls}`);
       lines.push('end');
-      files.push({
-        path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
-        content: lines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
+      // FR-1.4: write the per-model file only when in scope. Zeitwerk autoloads
+      // by path, so there is no barrel to keep in sync; out-of-scope alias files
+      // are left untouched on disk.
+      if (isModelInScope(model.name, ctx)) {
+        files.push({
+          path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
     // Deduplicate field names that collide after snake_case.
     const seenFieldNames = new Set<string>();
     const fields = model.fields.filter((f) => {
-      const n = fieldName(f.name);
+      // Dedup on the DOMAIN accessor name (honors fieldHints override).
+      const n = domainFieldName(f);
       if (seenFieldNames.has(n)) return false;
       seenFieldNames.add(n);
       return true;
@@ -151,7 +158,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('    HASH_ATTRS = {');
     for (let i = 0; i < fields.length; i++) {
       const field = fields[i];
-      const fname = fieldName(field.name);
+      // DOMAIN attr symbol (honors fieldHints); the key below is the WIRE name.
+      const fname = domainFieldName(field);
       const sep = i === fields.length - 1 ? '' : ',';
       lines.push(`      ${rubyHashLiteralKey(field.name)} :${fname}${sep}`);
     }
@@ -162,14 +170,14 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     if (deprecatedFields.length > 0) {
       for (const f of deprecatedFields) {
         const desc = f.description ? ` ${f.description.split('\n')[0].trim()}` : '';
-        lines.push(`    # @!attribute ${fieldName(f.name)}`);
+        lines.push(`    # @!attribute ${domainFieldName(f)}`);
         lines.push(`    #   @deprecated${desc}`);
       }
       lines.push('');
     }
 
     if (accessorFields.length > 0) {
-      const attrs = accessorFields.map((f) => `:${fieldName(f.name)}`);
+      const attrs = accessorFields.map((f) => `:${domainFieldName(f)}`);
       if (attrs.length === 1) {
         lines.push(`    attr_accessor ${attrs[0]}`);
       } else {
@@ -184,7 +192,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     // Emit deprecated field accessors with runtime warnings.
     for (const f of deprecatedFields) {
-      const fname = fieldName(f.name);
+      const fname = domainFieldName(f);
       lines.push(`    def ${fname}`);
       lines.push(
         `      warn "[DEPRECATION] \\\`${fname}\\\` is deprecated and will be removed in a future version.", uplevel: 1`,
@@ -202,7 +210,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('    def initialize(json)');
     lines.push('      hash = self.class.normalize(json)');
     for (const field of fields) {
-      const fname = fieldName(field.name);
+      // DOMAIN ivar name (honors fieldHints); rawKey is the WIRE key read from the hash.
+      const fname = domainFieldName(field);
       const rawKey = field.name;
       lines.push(`      ${deserializeAssignment(fname, rawKey, field.type, field.required, enumNames, modelNames)}`);
     }
@@ -211,12 +220,17 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('  end');
     lines.push('end');
 
-    files.push({
-      path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
+    // FR-1.4: write the per-model file only when in scope. Zeitwerk autoloads by
+    // path, so there is no barrel to keep in sync; out-of-scope model files are
+    // left untouched on disk.
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;

package/src/ruby/naming.ts

@@ -57,6 +57,16 @@ export function fieldName(name: string): string {
   return toSnakeCase(name);
 }
 
+/**
+ * snake_case domain field name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier name. The wire key (still derived from `field.name`) is what
+ * gets sent/received over the wire — only the domain attr/accessor name changes.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return toSnakeCase(field.domainName ?? field.name);
+}
+
 /**
  * Ruby reserved words that cannot be used as parameter names.
  * When a path/query param name collides, suffix with underscore.

package/src/ruby/rbi.ts

@@ -3,6 +3,7 @@ import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
 import {
   className,
   fieldName,
+  domainFieldName,
   fileName,
   safeParamName,
   scopedGroupVariantClassName,
@@ -14,6 +15,8 @@ import {
 import {
   buildResolvedLookup,
   groupByMount,
+  isMountInScope,
+  isModelInScope,
   lookupResolved,
   buildHiddenParams,
   collectGroupedParamNames,
@@ -92,7 +95,8 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     // Field accessors
     const seenFieldNames = new Set<string>();
     for (const f of model.fields) {
-      const fname = fieldName(f.name);
+      // DOMAIN accessor name in the .rbi (honors fieldHints override).
+      const fname = domainFieldName(f);
       if (seenFieldNames.has(fname)) continue;
       seenFieldNames.add(fname);
       const sorbetType = f.required ? mapSorbetType(f.type) : wrapNilable(mapSorbetType(f.type));
@@ -114,12 +118,17 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     lines.push('  end');
     lines.push('end');
 
-    files.push({
-      path: `rbi/workos/${fileName(model.name)}.rbi`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
+    // FR-1.4: write the per-model .rbi only when in scope. The client.rbi
+    // aggregate (section 3) stays on the full set so sigs for out-of-scope
+    // services whose .rb/.rbi still exist keep resolving.
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: `rbi/workos/${fileName(model.name)}.rbi`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
   }
 
   // 2. Generate service RBI files
@@ -135,6 +144,10 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
   const exportedClasses = buildExportedClassNameSet(ctx);
 
   for (const [mountTarget, group] of groups) {
+    // Scoped run: emit per-service .rbi only for selected mount targets. The
+    // client.rbi aggregate loop below intentionally stays on the FULL `groups`
+    // set so it keeps emitting sigs for every service whose .rb still exists.
+    if (!isMountInScope(mountTarget, ctx)) continue;
     const resolvedTarget = resolveServiceTarget(mountTarget, exportedClasses);
     const cls = className(resolvedTarget);
     const lines: string[] = [];

package/src/ruby/resources.ts

@@ -15,7 +15,7 @@ import { mapTypeRefForYard } from './type-map.js';
 import {
   buildResolvedLookup,
   lookupResolved,
-  groupByMount,
+  scopedMountGroups,
   getOpDefaults,
   getOpInferFromClient,
   buildHiddenParams,
@@ -33,7 +33,7 @@ import { buildGroupOwnerMap, collectVariantsForMountTarget, emitInlineVariantCla
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
-  const groups = groupByMount(ctx);
+  const groups = scopedMountGroups(ctx);
   const lookup = buildResolvedLookup(ctx);
   const modelNames = new Set(ctx.spec.models.map((m) => m.name));
   const enumNames = new Set(ctx.spec.enums.map((e) => e.name));

package/src/ruby/tests.ts

@@ -3,6 +3,7 @@ import {
   className,
   fileName,
   fieldName,
+  domainFieldName,
   safeParamName,
   scopedGroupVariantClassName,
   servicePropertyName,
@@ -12,7 +13,7 @@ import {
 } from './naming.js';
 import {
   buildResolvedLookup,
-  groupByMount,
+  scopedMountGroups,
   lookupResolved,
   buildHiddenParams,
   collectBodyFieldTypes,
@@ -33,7 +34,7 @@ import { buildGroupOwnerMap, pickVariantParamType } from './parameter-groups.js'
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
-  const groups = groupByMount(ctx);
+  const groups = scopedMountGroups(ctx);
   const models = spec.models as Model[];
   const modelByName = new Map<string, Model>();
   for (const m of models) modelByName.set(m.name, m);
@@ -235,7 +236,9 @@ function generateModelRoundTripTest(spec: ApiSpec): GeneratedFile {
     const dedupFields = new Set<string>();
     for (const f of model.fields) {
       const wireName = f.name;
-      const rubyFieldName = fieldName(f.name);
+      // Dedup on the DOMAIN accessor name to mirror the model's field dedup
+      // (models.ts). The fixture/assertion keys below still use the WIRE name.
+      const rubyFieldName = domainFieldName(f);
       if (dedupFields.has(rubyFieldName)) continue;
       dedupFields.add(rubyFieldName);
       const stub = roundTripStub(f.type, enumNames);

package/src/rust/enums.ts

@@ -1,5 +1,6 @@
 import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { typeName, moduleName, variantName } from './naming.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 /**
  * Generate one Rust source file per enum under `src/enums/`, plus a
@@ -17,7 +18,7 @@ import { typeName, moduleName, variantName } from './naming.js';
  *     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[] {
+export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
   const seen = new Set<string>();
   const moduleNames: string[] = [];
@@ -27,8 +28,15 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
     const mod = moduleName(e.name);
     if (seen.has(mod)) continue;
     seen.add(mod);
+    // The barrel (`src/enums/mod.rs`) must declare every enum's module so Rust
+    // compiles even in a scoped run — `moduleNames` is collected from the FULL
+    // enum set regardless of scope.
     moduleNames.push(mod);
 
+    // Only the per-enum `.rs` FILE write is scoped (FR-1.4). In a scoped run we
+    // skip emitting files for out-of-scope enums, but the barrel above still
+    // declares their modules (their existing `.rs` files stay untouched on disk).
+    if (!isEnumInScope(e.name, ctx)) continue;
     files.push({
       path: `src/enums/${mod}.rs`,
       content: renderEnum(e),

package/src/rust/index.ts

@@ -17,6 +17,7 @@ import { generateTests } from './tests.js';
 import { buildOperationsMap } from './manifest.js';
 import { UnionRegistry } from './type-map.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 
 /**
  * Shared per-emit registry that collects synthesised oneOf-style unions
@@ -98,7 +99,7 @@ export const rustEmitter: Emitter = {
   },
 
   fileHeader(): string {
-    return '// Code generated by oagen. DO NOT EDIT.';
+    return `// ${AUTOGEN_NOTICE}`;
   },
 
   formatCommand(_targetDir: string): FormatCommand | null {

package/src/rust/models.ts

@@ -1,7 +1,8 @@
-import type { Model, EmitterContext, GeneratedFile, Field } from '@workos/oagen';
-import { typeName, fieldName, moduleName } from './naming.js';
+import type { Model, EmitterContext, GeneratedFile, Field, TypeRef } from '@workos/oagen';
+import { typeName, domainFieldName, moduleName } from './naming.js';
 import { mapTypeRef, makeOptional, UnionRegistry } from './type-map.js';
 import { applySecretRedaction } from './secret.js';
+import { isModelInScope } from '../shared/resolved-ops.js';
 
 const HEADER_PLACEHOLDER = ''; // engine prepends fileHeader()
 
@@ -18,6 +19,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, registry: U
   const moduleNames: string[] = [];
   const seen = new Set<string>();
 
+  // Map of variant-model name -> discriminator wire-property for every model
+  // that appears as an arm of an internally-tagged (`#[serde(tag = ...)]`)
+  // union. serde consumes that property as the enum tag and strips it from the
+  // variant body during deserialization, so a *required* field of the same
+  // name can never be satisfied ("missing field `type`"). See renderField.
+  const taggedVariantFields = collectTaggedVariantFields(models);
+
   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
@@ -25,11 +33,27 @@ export function generateModels(models: Model[], ctx: EmitterContext, registry: U
     const mod = moduleName(model.name);
     if (seen.has(mod)) continue;
     seen.add(mod);
+    // The barrel (`src/models/mod.rs`) must declare every model's module so
+    // Rust compiles even in a scoped run — `moduleNames` is collected from the
+    // FULL model set regardless of scope.
     moduleNames.push(mod);
 
+    // renderModel registers inline unions into `registry` as a side effect, and
+    // `_unions.rs` is rendered later (in generateClient) from that registry — so
+    // it MUST run for every model, even out-of-scope ones, or scoped runs drop
+    // unions. Compute content unconditionally; only the per-model `.rs` FILE write
+    // is scoped (FR-1.4). The barrel above still declares every module, and an
+    // out-of-scope model's existing `.rs` file stays untouched on disk.
     const hintPath = ctx.overlayLookup?.fileBySymbol?.get(model.name);
     const path = hintPath ?? `src/models/${mod}.rs`;
-    files.push({ path, content: renderModel(model, registry), overwriteExisting: true });
+    const content = renderModel(model, registry, taggedVariantFields.get(model.name));
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path,
+        content,
+        overwriteExisting: true,
+      });
+    }
   }
 
   // Always include the unions module in the barrel so downstream stages
@@ -47,7 +71,48 @@ export function generateModels(models: Model[], ctx: EmitterContext, registry: U
   return files;
 }
 
-function renderModel(model: Model, registry: UnionRegistry): string {
+/**
+ * Walk every model field and record which models are arms of an
+ * internally-tagged union, mapped to that union's discriminator property.
+ */
+function collectTaggedVariantFields(models: Model[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const visit = (ref: TypeRef): void => {
+    switch (ref.kind) {
+      case 'union':
+        if (ref.discriminator?.property) {
+          for (const variant of ref.variants) {
+            const name = variantModelName(variant);
+            if (name) out.set(name, ref.discriminator.property);
+          }
+        }
+        ref.variants.forEach(visit);
+        break;
+      case 'array':
+        visit(ref.items);
+        break;
+      case 'nullable':
+        visit(ref.inner);
+        break;
+      case 'map':
+        visit(ref.valueType);
+        break;
+      default:
+        break;
+    }
+  };
+  for (const model of models) for (const field of model.fields) visit(field.type);
+  return out;
+}
+
+/** Resolve the underlying model name of a union arm, unwrapping a nullable. */
+function variantModelName(ref: TypeRef): string | null {
+  if (ref.kind === 'model') return ref.name;
+  if (ref.kind === 'nullable') return variantModelName(ref.inner);
+  return null;
+}
+
+function renderModel(model: Model, registry: UnionRegistry, tagField?: string): string {
   const lines: string[] = [];
   lines.push(HEADER_PLACEHOLDER);
   // Match rustfmt's canonical grouping: keyword-rooted paths (`super`,
@@ -65,7 +130,7 @@ function renderModel(model: Model, registry: UnionRegistry): string {
   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));
+  const fieldLines = model.fields.map((f, i) => renderField(f, resolvedNames[i]!, model.name, registry, tagField));
 
   // rustfmt collapses zero-field structs to `pub struct Foo {}` on a single
   // line. Match that shape so `cargo fmt --check` passes.
@@ -80,17 +145,20 @@ function renderModel(model: Model, registry: UnionRegistry): string {
 }
 
 /**
- * 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.
+ * Resolve unique Rust identifiers for struct fields. The domain identifier
+ * honors a `fieldHints` override (`domainName`, e.g. wire `connection_type` →
+ * domain `type`); the wire name (and the `#[serde(rename = ...)]` key emitted
+ * in `renderField`) still derives from `f.name`. Multiple names can collide
+ * after snake-casing (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);
+    const base = domainFieldName(f);
     let candidate = base;
     let suffix = 2;
     while (used.has(candidate)) {
@@ -103,7 +171,13 @@ function resolveFieldNames(fields: Field[]): string[] {
   return out;
 }
 
-function renderField(field: Field, rustField: string, modelName: string, registry: UnionRegistry): string {
+function renderField(
+  field: Field,
+  rustField: string,
+  modelName: string,
+  registry: UnionRegistry,
+  tagField?: string,
+): string {
   const lines: string[] = [];
   const hasDescription = !!field.description;
   if (hasDescription) {
@@ -128,9 +202,20 @@ function renderField(field: Field, rustField: string, modelName: string, registr
   // 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 (tagField === field.name) {
+    // This field is the discriminator of an internally-tagged union it belongs
+    // to. serde reads it as the enum tag and strips it from the variant body,
+    // so `default` lets the struct deserialize without it; `skip_serializing`
+    // stops the struct from re-emitting it (serde injects the tag itself,
+    // which would otherwise produce a duplicate key). Standalone uses of the
+    // struct still deserialize the value normally because the key is present.
+    const args = rename ? `rename = "${rename}", default, skip_serializing` : 'default, skip_serializing';
+    lines.push(`    #[serde(${args})]`);
+  } else {
+    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},`);

package/src/rust/naming.ts

@@ -77,6 +77,16 @@ export function fieldName(name: string): string {
   return escapeKeyword(toSnakeCase(name));
 }
 
+/**
+ * snake_case domain field name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier identifier. The wire name (and thus the `#[serde(rename = ...)]`
+ * key) still derives from `field.name`.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return escapeKeyword(toSnakeCase(field.domainName ?? field.name));
+}
+
 /** PascalCase enum variant. */
 export function variantName(value: string | number): string {
   const s = String(value);

package/src/rust/resources.ts

@@ -10,11 +10,11 @@ import type {
   TypeRef,
 } from '@workos/oagen';
 import { planOperation } from '@workos/oagen';
-import { fieldName, methodName, typeName, moduleName, variantName } from './naming.js';
+import { fieldName, domainFieldName, methodName, typeName, moduleName, variantName } from './naming.js';
 import { mapTypeRef, makeOptional, UnionRegistry } from './type-map.js';
 import { applySecretRedaction } from './secret.js';
 import { parsePathTemplate } from '../shared/path-template.js';
-import { groupByMount, buildResolvedLookup } from '../shared/resolved-ops.js';
+import { groupByMount, buildResolvedLookup, isMountInScope } from '../shared/resolved-ops.js';
 import { resolveWrapperParams, type ResolvedWrapperParam } from '../shared/wrapper-utils.js';
 
 /**
@@ -32,7 +32,14 @@ export function generateResources(_services: Service[], ctx: EmitterContext, reg
     if (group.operations.length === 0) continue;
     const basename = moduleName(mountName);
     const struct = mountStructName(mountName);
+    // The barrel (`src/resources/mod.rs`) must list every mount's module so
+    // Rust compiles even in a scoped run — `exports` is collected from the
+    // FULL groupByMount set regardless of scope.
     exports.push({ module: basename, struct });
+    // Only the per-service resource `.rs` FILE write is scoped. In a scoped
+    // run we skip emitting files for out-of-scope mounts, but the barrel above
+    // still references their modules (their existing `.rs` files stay on disk).
+    if (!isMountInScope(mountName, ctx)) continue;
     files.push({
       path: `src/resources/${basename}.rs`,
       content: renderMountGroup(mountName, group.resolvedOps, ctx, registry, lookup),
@@ -617,7 +624,11 @@ function registerSyntheticBody(
       if (!f.required && !rust.startsWith('Option<')) rust = makeOptional(rust);
       rust = applySecretRedaction(rust, f.name);
       return {
-        rustName: fieldName(f.name),
+        // Domain identifier honors a `fieldHints` override (e.g. wire
+        // `connection_type` → domain `type`); `wireName` keeps `f.name`, and
+        // the `#[serde(rename = wireName)]` emitted in GroupEmitter.render
+        // fires whenever the two differ.
+        rustName: domainFieldName(f),
         wireName: f.name,
         rustType: rust,
         required: !!f.required && !rust.startsWith('Option<'),

package/src/rust/tests.ts

@@ -11,7 +11,7 @@ import type {
   TypeRef,
 } from '@workos/oagen';
 import { methodName, moduleName, typeName } from './naming.js';
-import { groupByMount } from '../shared/resolved-ops.js';
+import { scopedMountGroups } from '../shared/resolved-ops.js';
 import { exampleFor, generateFixtures } from './fixtures.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { isInlineEnvelopeList } from './resources.js';
@@ -43,7 +43,7 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     overwriteExisting: true,
   });
 
-  const groups = groupByMount(ctx);
+  const groups = scopedMountGroups(ctx);
   const modelMap = new Map(spec.models.map((m) => [m.name, m]));
   const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
 

package/src/shared/file-header.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical "do not edit" banner text shared by every emitter's
+ * `fileHeader()`. The text is comment-syntax agnostic — each emitter prefixes
+ * it with the appropriate comment marker for its language (`//`, `#`, etc.).
+ *
+ * Keeping this in one place prevents the wording from drifting between
+ * languages (Rust previously emitted a different banner).
+ *
+ * Go intentionally does NOT use this constant: its header must match the
+ * standard `^// Code generated .* DO NOT EDIT\.$` marker that Go tooling
+ * relies on to recognize generated files. See `src/go/index.ts`.
+ */
+export const AUTOGEN_NOTICE = 'This file is auto-generated by oagen. Do not edit.';

package/src/shared/resolved-ops.ts

@@ -94,6 +94,53 @@ export function groupByMount(ctx: EmitterContext): Map<string, MountGroup> {
   return groups;
 }
 
+/**
+ * Like {@link groupByMount}, but for a scoped (`--services`) run returns ONLY the
+ * mount groups the run selected (`ctx.scopedServices`, POST-MOUNT names). When
+ * scoping is inactive the full set is returned unchanged.
+ *
+ * Use this for PER-SERVICE resource/test emission. Do NOT use it for
+ * aggregate/barrel files (Rust `mod.rs`, Ruby `client.rbi`, the root client) —
+ * those must continue to list every service, so they keep calling
+ * {@link groupByMount} over the full set; otherwise a scoped run would drop
+ * sibling modules and break the build/type-check.
+ */
+export function scopedMountGroups(ctx: EmitterContext): Map<string, MountGroup> {
+  const groups = groupByMount(ctx);
+  const scope = ctx.scopedServices;
+  if (!scope || scope.size === 0) return groups;
+  return new Map([...groups].filter(([mountName]) => scope.has(mountName)));
+}
+
+/**
+ * True when a POST-MOUNT service name should be emitted in the current run.
+ * Inactive scoping (no `ctx.scopedServices`) ⇒ everything is in scope. Use this
+ * for inline per-service gates (e.g. manifest loops keyed by `getMountTarget`).
+ */
+export function isMountInScope(mountName: string, ctx: EmitterContext): boolean {
+  const scope = ctx.scopedServices;
+  return !scope || scope.size === 0 || scope.has(mountName);
+}
+
+/**
+ * True when a MODEL's per-model FILE should be written in the current run (FR-1.4).
+ * A scoped run sets `ctx.scopedModelNames` to the models reachable from the
+ * selected services; out-of-scope models are left untouched on disk. Inactive
+ * scoping ⇒ everything is in scope. NOTE: gate only the per-model FILE write —
+ * the model must still appear in barrels/indexes (built from the full set) so the
+ * untouched on-disk file stays importable.
+ */
+export function isModelInScope(modelName: string, ctx: EmitterContext): boolean {
+  const scope = ctx.scopedModelNames;
+  return !scope || scope.has(modelName);
+}
+
+/** Like {@link isModelInScope} but for an ENUM's per-enum file (`ctx.scopedEnumNames`). */
+export function isEnumInScope(enumName: string, ctx: EmitterContext): boolean {
+  const scope = ctx.scopedEnumNames;
+  return !scope || scope.has(enumName);
+}
+
 /**
  * Get the mount target for an IR service.
  * Checks the first resolved operation that belongs to this service.