@workos/oagen 0.2.0 → 0.4.0

package/dist/cli/index.mjs

@@ -3,13 +3,128 @@ import "dotenv/config";
 import { Command } from "commander";
 import * as fs from "node:fs/promises";
 import { readFile } from "node:fs/promises";
-import * as path from "node:path";
-import { relative, resolve } from "node:path";
+import * as path$1 from "node:path";
+import path, { relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { BaseResolver, bundleDocument, createConfig, makeDocumentFromString } from "@redocly/openapi-core";
+import { BaseResolver, Oas3_1Types, bundleDocument, createConfig, makeDocumentFromString } from "@redocly/openapi-core";
 import Parser from "tree-sitter";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
+//#region src/ir/sdk-behavior.ts
+/**
+* Canonical SDK behavior defaults. These match the PHP emitter's current
+* implementation (the most complete). Per-language overrides can be applied
+* via `mergeSdkBehavior()` in each SDK's `oagen.config.ts`.
+*
+* - Retry: exponential backoff with jitter, retries on 429/5xx
+* - Errors: standard HTTP status → exception kind mapping
+* - Telemetry: enabled by default, tracks request ID + latency
+* - Pagination: no inter-page delay (Node overrides to 350ms)
+* - Idempotency: auto-generate UUID v4 for retryable POSTs
+* - Logging: all lifecycle events enabled
+* - User-Agent: SDK identifier + runtime version + app info + AI agent detection
+* - Request guards: detect misplaced RequestOptions keys in params
+* - Timeout: 60s default (Python overrides to 30s)
+*/
+function defaultSdkBehavior() {
+	return {
+		retry: {
+			retryableStatusCodes: [
+				429,
+				500,
+				502,
+				503,
+				504
+			],
+			maxRetries: 3,
+			retryOnConnectionError: true,
+			retryOnTimeout: true,
+			backoff: {
+				initialDelay: 1,
+				multiplier: 2,
+				maxDelay: 30,
+				jitterFactor: .5
+			}
+		},
+		errors: {
+			statusCodeMap: {
+				400: "BadRequest",
+				401: "Authentication",
+				403: "Authorization",
+				404: "NotFound",
+				409: "Conflict",
+				422: "UnprocessableEntity",
+				429: "RateLimitExceeded"
+			},
+			serverErrorKind: "Server",
+			clientErrorKind: "Api",
+			errorDocUrlTemplate: "https://workos.com/docs/errors/{code}"
+		},
+		telemetry: {
+			enabledByDefault: true,
+			headerName: "X-WorkOS-Client-Telemetry",
+			requestIdHeader: "X-Request-ID"
+		},
+		pagination: { autoPageDelayMs: 0 },
+		idempotency: {
+			headerName: "Idempotency-Key",
+			autoGenerateForPost: true
+		},
+		logging: {
+			enabled: true,
+			events: [
+				"request.start",
+				"request.success",
+				"request.retry",
+				"request.rate_limited",
+				"request.error",
+				"request.connection_error"
+			]
+		},
+		userAgent: {
+			sdkIdentifierTemplate: "{name} {lang}/{version}",
+			includeRuntimeVersion: true,
+			allowAppInfo: true,
+			aiAgentEnvVars: [
+				{
+					envVar: "CLAUDE_CODE",
+					agentName: "ClaudeCode"
+				},
+				{
+					envVar: "CURSOR_AGENT",
+					agentName: "Cursor"
+				},
+				{
+					envVar: "CLINE_ACTIVE",
+					agentName: "Cline"
+				},
+				{
+					envVar: "WINDSURF_ACTIVE",
+					agentName: "Windsurf"
+				},
+				{
+					envVar: "COPILOT_AGENT",
+					agentName: "Copilot"
+				}
+			]
+		},
+		requestGuard: { optionKeys: [
+			"api_key",
+			"apiKey",
+			"idempotency_key",
+			"idempotencyKey",
+			"extra_headers",
+			"extraHeaders",
+			"max_retries",
+			"maxRetries",
+			"base_url",
+			"baseUrl"
+		] },
+		timeout: { defaultTimeoutSeconds: 60 }
+	};
+}
+//#endregion
 //#region src/errors.ts
 /**
 * Structured error hierarchy for oagen.
@@ -68,13 +183,11 @@ var RegistryError = class extends OagenError {
 //#region src/parser/refs.ts
 async function loadAndBundleSpec(specPath) {
 	const absolutePath = resolve(specPath);
-	const document = makeDocumentFromString(await readFile(absolutePath, "utf-8"), pathToFileURL(absolutePath).href);
-	const config = await createConfig({});
-	const resolver = new BaseResolver();
 	const result = await bundleDocument({
-		document,
-		config: config.styleguide,
-		externalRefResolver: resolver,
+		document: makeDocumentFromString(await readFile(absolutePath, "utf-8"), pathToFileURL(absolutePath).href),
+		config: await createConfig({}),
+		types: Oas3_1Types,
+		externalRefResolver: new BaseResolver(),
 		dereference: false
 	});
 	if (result.problems.some((p) => p.severity === "error")) throw new SpecParseError(`Failed to parse spec: ${result.problems.filter((p) => p.severity === "error").map((p) => p.message).join("\n")}`, `Check the OpenAPI spec at "${absolutePath}" for syntax errors. Run a linter such as \`npx @redocly/cli lint ${specPath}\` to identify issues.`);
@@ -143,15 +256,49 @@ function walkTypeRef(ref, visitor) {
 //#endregion
 //#region src/utils/naming.ts
 /**
+* Known compound tokens that the regex-based splitter over-splits.
+* Each entry is [lowercase-word-sequence, canonical-form].
+* Sorted longest-first so greedy matching works correctly.
+*/
+const COMPOUND_WORDS = [[[
+	"m",
+	"2",
+	"m"
+], "M2M"], [["o", "auth"], "OAuth"]];
+/**
+* Recombine adjacent words that form a known compound token.
+*/
+function recombineCompounds(words) {
+	const result = [];
+	let i = 0;
+	while (i < words.length) {
+		let matched = false;
+		for (const [pattern, canonical] of COMPOUND_WORDS) if (i + pattern.length <= words.length) {
+			if (pattern.every((p, j) => words[i + j].toLowerCase() === p)) {
+				result.push(canonical);
+				i += pattern.length;
+				matched = true;
+				break;
+			}
+		}
+		if (!matched) {
+			result.push(words[i]);
+			i++;
+		}
+	}
+	return result;
+}
+/**
 * Split a string into words, handling:
 * - camelCase / PascalCase boundaries
 * - snake_case / kebab-case separators
 * - Consecutive capitals (e.g., "HTTPClient" → ["HTTP", "Client"])
 * - Numbers as word boundaries (e.g., "OAuth2Token" → ["OAuth", "2", "Token"])
+* - Known compounds are recombined (e.g., "M2M" stays as one word)
 */
 function splitWords(s) {
 	if (!s) return [];
-	return s.replace(/[^a-zA-Z0-9_\-\s.]/g, "_").replace(/([a-z])([A-Z])/g, "$1\0$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1\0$2").replace(/([a-zA-Z])(\d)/g, "$1\0$2").replace(/(\d)([a-zA-Z])/g, "$1\0$2").split(/[\0_\-\s.]+/).filter((w) => w.length > 0);
+	return recombineCompounds(s.replace(/[^a-zA-Z0-9_\-\s.]/g, "_").replace(/([a-z])([A-Z])/g, "$1\0$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1\0$2").replace(/([a-zA-Z])(\d)/g, "$1\0$2").replace(/(\d)([a-zA-Z])/g, "$1\0$2").split(/[\0_\-\s.]+/).filter((w) => w.length > 0));
 }
 const ACRONYM_SET = new Set([
 	"SSO",
@@ -159,7 +306,8 @@ const ACRONYM_SET = new Set([
 	"SAML",
 	"SCIM",
 	"JWT",
-	"HMAC"
+	"HMAC",
+	"M2M"
 ]);
 function toPascalCase(s, acronyms) {
 	const merged = acronyms ? new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
@@ -188,11 +336,7 @@ function toSnakeCase(s) {
 function toUpperSnakeCase(s) {
 	return splitWords(s).map((w) => w.toUpperCase()).join("_");
 }
-const BACKEND_SUFFIXES = [
-	"Dto",
-	"DTO",
-	"Controller"
-];
+const BACKEND_SUFFIXES = ["Controller"];
 function stripBackendSuffixes(name) {
 	for (const suffix of BACKEND_SUFFIXES) if (name.endsWith(suffix) && name.length > suffix.length) return name.slice(0, -suffix.length);
 	return name;
@@ -219,7 +363,9 @@ const SINGULAR_SAFE_LIST = new Set([
 	"Canvas",
 	"Alias",
 	"Basis",
-	"Bus"
+	"Bus",
+	"Species",
+	"Series"
 ]);
 /**
 * Conservative singularize for the leading PascalCase word.
@@ -228,7 +374,7 @@ const SINGULAR_SAFE_LIST = new Set([
 * - trailing `s` for words >4 chars (e.g. Organizations → Organization)
 * Safe-listed words are never singularized.
 */
-function singularize(word) {
+function singularize$1(word) {
 	if (SINGULAR_SAFE_LIST.has(word)) return word;
 	if (word.endsWith("ies") && word.length > 4) return word.slice(0, -3) + "y";
 	if (word.endsWith("ses") && word.length > 4) return word.slice(0, -2);
@@ -254,7 +400,7 @@ function cleanSchemaName(name) {
 	const match = result.match(/^([A-Z][a-z]*)/);
 	if (match) {
 		const leadWord = match[1];
-		const singular = singularize(leadWord);
+		const singular = singularize$1(leadWord);
 		if (singular !== leadWord) result = singular + result.slice(leadWord.length);
 	}
 	return result;
@@ -274,7 +420,7 @@ function qualifyInlineModelName(baseName, parentName) {
 	const trailingMatch = baseName.match(/^(.*?)([A-Z][a-z]*)$/);
 	if (trailingMatch) {
 		const [, prefix, trailingWord] = trailingMatch;
-		return `${cleanParent}${prefix}${singularize(trailingWord)}`;
+		return `${cleanParent}${prefix}${singularize$1(trailingWord)}`;
 	}
 	return `${cleanParent}${baseName}`;
 }
@@ -335,15 +481,39 @@ function buildInlineModel(name, schema) {
 }
 //#endregion
 //#region src/parser/schemas.ts
-function extractSchemas(schemas) {
+/**
+* Module-level transform set during extractSchemas(). Used by schemaToTypeRef()
+* to apply the same name transform to $ref model/enum references.
+*/
+let activeSchemaNameTransform = null;
+/** Apply cleanSchemaName + the active transform (if any) to a raw schema name. */
+function resolveSchemaName(rawName) {
+	let name = cleanSchemaName(toPascalCase(rawName));
+	if (activeSchemaNameTransform) name = activeSchemaNameTransform(name);
+	return name;
+}
+function extractSchemas(schemas, options) {
 	const enums = [];
 	if (!schemas) return {
 		models: [],
 		enums
 	};
+	if (options?.schemaNameTransform) {
+		const transform = options.schemaNameTransform;
+		const cleanedNames = Object.keys(schemas).map((n) => cleanSchemaName(toPascalCase(n)));
+		const transformedToOriginals = /* @__PURE__ */ new Map();
+		for (const cleaned of cleanedNames) {
+			const transformed = transform(cleaned);
+			if (!transformedToOriginals.has(transformed)) transformedToOriginals.set(transformed, []);
+			transformedToOriginals.get(transformed).push(cleaned);
+		}
+		const unsafeToTransform = /* @__PURE__ */ new Set();
+		for (const [, originals] of transformedToOriginals) if (originals.length > 1) for (const n of originals) unsafeToTransform.add(n);
+		activeSchemaNameTransform = (name) => unsafeToTransform.has(name) ? name : transform(name);
+	} else activeSchemaNameTransform = null;
 	const modelsByCleanName = /* @__PURE__ */ new Map();
 	for (const [name, schema] of Object.entries(schemas)) {
-		const pascalName = cleanSchemaName(toPascalCase(name));
+		const pascalName = resolveSchemaName(name);
 		if (schema.enum) enums.push(extractEnum(pascalName, schema));
 		else {
 			const model = extractModel(pascalName, schema, schemas);
@@ -351,6 +521,12 @@ function extractSchemas(schemas) {
 			if (existing) {
 				if (model.fields.length > existing.fields.length) modelsByCleanName.set(pascalName, model);
 			} else modelsByCleanName.set(pascalName, model);
+			for (const inlineModel of extractDiscriminatedAllOfVariantModels(schema, pascalName)) {
+				const existingInline = modelsByCleanName.get(inlineModel.name);
+				if (existingInline) {
+					if (inlineModel.fields.length > existingInline.fields.length) modelsByCleanName.set(inlineModel.name, inlineModel);
+				} else modelsByCleanName.set(inlineModel.name, inlineModel);
+			}
 		}
 	}
 	const models = [...modelsByCleanName.values()];
@@ -366,6 +542,10 @@ function extractSchemas(schemas) {
 		enums
 	};
 }
+/** Clear the module-level schemaNameTransform. Called by parseSpec() after all extraction phases. */
+function clearSchemaNameTransform() {
+	activeSchemaNameTransform = null;
+}
 /**
 * Walk a single TypeRef and extract inline enum refs as top-level enum definitions.
 * Shared by both schemas.ts (field-level) and parse.ts (model-level) collection passes.
@@ -402,7 +582,7 @@ function collectInlineEnums(fields, enums) {
 function collectNestedInlineModels(ref, fieldName, parentModelName, schemas, models, modelNames, queue) {
 	walkTypeRef(ref, { model: (modelRef) => {
 		if (modelNames.has(modelRef.name)) return;
-		if (Object.keys(schemas).some((k) => cleanSchemaName(toPascalCase(k)) === modelRef.name)) return;
+		if (Object.keys(schemas).some((k) => resolveSchemaName(k) === modelRef.name)) return;
 		const parentSchema = findSchemaByName(parentModelName, schemas);
 		if (!parentSchema) return;
 		const fieldSchema = findNestedFieldSchema(fieldName, parentSchema, schemas);
@@ -417,7 +597,7 @@ function collectNestedInlineModels(ref, fieldName, parentModelName, schemas, mod
 }
 /** Find a component schema by PascalCase name. */
 function findSchemaByName(pascalName, schemas) {
-	for (const [k, v] of Object.entries(schemas)) if (cleanSchemaName(toPascalCase(k)) === pascalName) return v;
+	for (const [k, v] of Object.entries(schemas)) if (resolveSchemaName(k) === pascalName) return v;
 	return null;
 }
 /** Walk into a schema to find a field's sub-schema, resolving allOf. */
@@ -575,13 +755,88 @@ function extractAllOfModel(name, schema, schemas) {
 		fields
 	};
 }
+function extractDiscriminatedAllOfVariantModels(schema, fallbackName) {
+	const models = [];
+	const seenNames = /* @__PURE__ */ new Set();
+	for (const subSchema of schema.allOf ?? []) for (const variant of subSchema.oneOf ?? []) {
+		if (!variant.properties || variant.type !== void 0 && variant.type !== "object") continue;
+		const variantName = deriveDiscriminatedVariantName(variant, fallbackName);
+		for (const model of extractInlineModelDeep(variantName, variant)) {
+			if (seenNames.has(model.name)) continue;
+			seenNames.add(model.name);
+			models.push(model);
+		}
+	}
+	return models;
+}
+function deriveDiscriminatedVariantName(schema, fallbackName) {
+	if (!schema.properties) return fallbackName;
+	for (const name of [
+		"event",
+		"type",
+		"object"
+	]) {
+		const field = schema.properties[name];
+		if (!field) continue;
+		if (typeof field.const === "string") return toPascalCase(field.const);
+		if (field.enum && field.enum.length === 1 && typeof field.enum[0] === "string") return toPascalCase(field.enum[0]);
+	}
+	for (const field of Object.values(schema.properties)) {
+		if (!field) continue;
+		if (typeof field.const === "string") return toPascalCase(field.const);
+		if (field.enum && field.enum.length === 1 && typeof field.enum[0] === "string") return toPascalCase(field.enum[0]);
+	}
+	return fallbackName;
+}
+function extractInlineModelDeep(name, schema) {
+	const requiredSet = new Set(schema.required ?? []);
+	const fields = [];
+	const properties = schema.properties ?? {};
+	const nestedModels = [];
+	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+		if (!fieldSchema) continue;
+		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
+		if (fieldSchema.type === "object" && fieldSchema.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema));
+		if (fieldSchema.type === "array" && fieldSchema.items?.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema.items));
+		if (fieldSchema.allOf) {
+			const mergedProperties = {};
+			const mergedRequired = [];
+			for (const sub of fieldSchema.allOf) {
+				if (sub.properties) Object.assign(mergedProperties, sub.properties);
+				if (sub.required) mergedRequired.push(...sub.required);
+			}
+			if (Object.keys(mergedProperties).length > 0) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), {
+				type: "object",
+				properties: mergedProperties,
+				required: mergedRequired
+			}));
+		}
+		if (fieldSchema.oneOf) {
+			const objectVariant = fieldSchema.oneOf.find((v) => v.properties && (v.type === "object" || !v.type));
+			if (objectVariant) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), objectVariant));
+		}
+	}
+	return [{
+		name,
+		description: schema.description,
+		fields
+	}, ...nestedModels];
+}
+function qualifyNestedInlineName(parentName, fieldName) {
+	const pascalField = toPascalCase(fieldName);
+	if (pascalField.startsWith(parentName)) return pascalField;
+	const qualified = `${stripListItemMarkers(parentName)}${pascalField}`;
+	const match = qualified.match(/^(.+?)([A-Z][a-z]+s?)$/);
+	if (match && match[2]) return match[1] + singularize$1(match[2]);
+	return qualified;
+}
 function schemaToTypeRef(schema, contextName, parentModelName) {
 	if (schema.$ref) {
 		const segments = schema.$ref.split("/");
 		const rawName = segments[segments.length - 1];
 		return {
 			kind: "model",
-			name: cleanSchemaName(toPascalCase(rawName))
+			name: resolveSchemaName(rawName)
 		};
 	}
 	if (Array.isArray(schema.type)) {
@@ -845,6 +1100,7 @@ const KNOWN_DATA_PATHS = new Set([
 	"edges"
 ]);
 const PAGINATION_METADATA_PATTERNS = [
+	"meta",
 	"metadata",
 	"pagination",
 	"cursor",
@@ -876,11 +1132,12 @@ function detectListEnvelope(schema) {
 	}
 	if (arrayProps.length === 1 && nonArrayKeys.length >= 1) {
 		const arrayPropName = arrayProps[0];
-		if (KNOWN_DATA_PATHS.has(arrayPropName)) return {
+		const hasPaginationCompanion = nonArrayKeys.some((key) => PAGINATION_METADATA_PATTERNS.some((pattern) => key.toLowerCase().includes(pattern)));
+		if (KNOWN_DATA_PATHS.has(arrayPropName) && hasPaginationCompanion) return {
 			isEnvelope: true,
 			dataPath: arrayPropName
 		};
-		if (nonArrayKeys.some((key) => PAGINATION_METADATA_PATTERNS.some((pattern) => key.toLowerCase().includes(pattern)))) return {
+		if (hasPaginationCompanion) return {
 			isEnvelope: true,
 			dataPath: arrayPropName
 		};
@@ -1104,7 +1361,7 @@ function qualifyNestedName(parentName, fieldName) {
 	const qualified = `${stripListItemMarkers(parentName)}${pascalField}`;
 	const match = qualified.match(/^(.+?)([A-Z][a-z]+s?)$/);
 	if (match && match[2]) {
-		const trailing = singularize(match[2]);
+		const trailing = singularize$1(match[2]);
 		return match[1] + trailing;
 	}
 	return qualified;
@@ -1184,13 +1441,33 @@ function extractOperations(paths, operationIdTransform) {
 			const op = pathItem[method];
 			if (!op) continue;
 			const serviceName = inferServiceName(path, op.tags?.[0]);
-			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform);
+			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName);
 			inlineModels.push(...opModels);
 			const ops = serviceMap.get(serviceName) ?? [];
 			ops.push(operation);
 			serviceMap.set(serviceName, ops);
 		}
 	}
+	for (const [serviceName, operations] of serviceMap) {
+		const pathGroups = /* @__PURE__ */ new Map();
+		for (const op of operations) {
+			const firstSeg = op.path.split("/").filter(Boolean)[0] ?? "";
+			const groupKey = firstSeg.startsWith("{") ? serviceName : toPascalCase(firstSeg);
+			const group = pathGroups.get(groupKey) ?? [];
+			group.push(op);
+			pathGroups.set(groupKey, group);
+		}
+		if (pathGroups.size > 1) {
+			if ([...pathGroups.keys()].some((k) => k !== serviceName)) {
+				serviceMap.delete(serviceName);
+				for (const [groupName, groupOps] of pathGroups) {
+					const existing = serviceMap.get(groupName) ?? [];
+					existing.push(...groupOps);
+					serviceMap.set(groupName, existing);
+				}
+			}
+		}
+	}
 	for (const [, operations] of serviceMap) disambiguateOperationNames(operations);
 	return {
 		services: Array.from(serviceMap.entries()).map(([name, operations]) => ({
@@ -1306,13 +1583,14 @@ function inferDeeperContext(path) {
 	if (nonParams.length >= 3) return toPascalCase(nonParams.slice(1, -1).join("_"));
 	return null;
 }
-function buildOperation(method, path, op, pathLevelParams, operationIdTransform) {
+function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName) {
 	const allParams = [...pathLevelParams, ...op.parameters ?? []];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
-	const pathParams = extractParams(allParams, "path");
-	const queryParams = extractParams(allParams, "query");
-	const headerParams = extractParams(allParams, "header").filter((p) => p.name.toLowerCase() !== "idempotency-key");
-	const cookieParams = extractParams(allParams, "cookie");
+	const opContext = serviceName;
+	const pathParams = extractParams(allParams, "path", opContext);
+	const queryParams = extractParams(allParams, "query", opContext);
+	const headerParams = extractParams(allParams, "header", opContext).filter((p) => p.name.toLowerCase() !== "idempotency-key");
+	const cookieParams = extractParams(allParams, "cookie", opContext);
 	const reqBodyModels = [];
 	const { body: requestBody, encoding: requestBodyEncoding } = extractRequestBody(op.requestBody, op, reqBodyModels);
 	const { response, successResponses, errors, inlineModels, isPaginated, dataPath: responseDataPath, itemType: responseItemType } = extractResponses(op.responses, op, path, method);
@@ -1329,6 +1607,7 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform)
 			itemType
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
+	const security = extractOperationSecurity(op.security);
 	return {
 		operation: {
 			name: inferOperationName(method, path, op.operationId, operationIdTransform),
@@ -1347,19 +1626,35 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform)
 			pagination,
 			injectIdempotencyKey: hasIdempotencyHeader,
 			deprecated: op.deprecated || void 0,
-			async: op["x-oagen-async"]
+			async: op["x-oagen-async"],
+			security
 		},
 		inlineModels
 	};
 }
+/**
+* Extract per-operation security requirements from an OpenAPI security directive.
+* Returns undefined when the operation uses the spec-level default security.
+*
+* OpenAPI security format: `security: [{ schemeName: [scope1, scope2] }]`
+*/
+function extractOperationSecurity(security) {
+	if (!security || security.length === 0) return void 0;
+	const requirements = [];
+	for (const entry of security) for (const [schemeName, scopes] of Object.entries(entry)) requirements.push({
+		schemeName,
+		scopes: scopes ?? []
+	});
+	return requirements.length > 0 ? requirements : void 0;
+}
 function buildDescription(summary, description) {
 	if (summary && description && summary !== description) return `${summary}\n\n${description}`;
 	return description ?? summary;
 }
-function extractParams(params, location) {
+function extractParams(params, location, operationContext) {
 	return params.filter((p) => p.in === location).map((p) => ({
 		name: p.name,
-		type: p.schema ? schemaToTypeRef(p.schema, p.name) : {
+		type: p.schema ? schemaToTypeRef(p.schema, p.name, operationContext ? toPascalCase(operationContext) : void 0) : {
 			kind: "primitive",
 			type: "string"
 		},
@@ -1545,7 +1840,14 @@ function extractResponses(responses, op, path, method) {
 				statusCode: code,
 				type: extractedType
 			});
-		} else if (code >= 400) {
+		} else if (code >= 300 && code < 400) allSuccessResponses.push({
+			statusCode: code,
+			type: {
+				kind: "primitive",
+				type: "unknown"
+			}
+		});
+		else if (code >= 400) {
 			const jsonContent = resp.content?.["application/json"];
 			const type = jsonContent?.schema ? schemaToTypeRef(jsonContent.schema, `Error${code}`) : void 0;
 			errors.push({
@@ -1672,6 +1974,19 @@ function collectInlineEnumsFromModels(models, enums) {
 	const enumNames = new Set(enums.map((e) => e.name));
 	for (const model of models) for (const field of model.fields) collectInlineEnumFromRef(field.type, enums, enumNames);
 }
+/**
+* Collect inline enum definitions from operation parameters (query, path, header)
+* and promote them to top-level enums so emitters can generate typed enum files.
+*/
+function collectInlineEnumsFromOperations(services, enums) {
+	const enumNames = new Set(enums.map((e) => e.name));
+	for (const service of services) for (const op of service.operations) for (const param of [
+		...op.pathParams,
+		...op.queryParams,
+		...op.headerParams,
+		...op.cookieParams ?? []
+	]) collectInlineEnumFromRef(param.type, enums, enumNames);
+}
 //#endregion
 //#region src/parser/normalize-model-refs.ts
 function validateModelRefs(spec) {
@@ -1701,10 +2016,12 @@ async function parseSpec(specPath, options) {
 	const spec = parsed;
 	const version = spec.openapi ?? "";
 	if (!version.startsWith("3.")) throw new SpecParseError(`Unsupported OpenAPI version: ${version}. oagen requires OpenAPI 3.x`, `Update the spec to OpenAPI 3.0 or 3.1. If you are using Swagger 2.x, convert it first with \`npx swagger2openapi ${specPath}\`.`);
-	const { models, enums } = extractSchemas(spec.components?.schemas);
+	const { models, enums } = extractSchemas(spec.components?.schemas, { schemaNameTransform: options?.schemaNameTransform });
 	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform);
+	clearSchemaNameTransform();
 	const finalModels = collapseJsonSuffixModels(mergeFieldInlineModels(mergeInlineResponseModels(models, inlineModels), extractInlineModelsFromSchemas(spec.components?.schemas)), services);
 	collectInlineEnumsFromModels(finalModels, enums);
+	collectInlineEnumsFromOperations(services, enums);
 	const auth = extractAuthSchemes(spec.components?.securitySchemes);
 	const serverEntries = (spec.servers ?? []).map((s) => ({
 		url: s.url ?? "",
@@ -1719,7 +2036,8 @@ async function parseSpec(specPath, options) {
 		services,
 		models: finalModels,
 		enums,
-		auth
+		auth,
+		sdk: defaultSdkBehavior()
 	};
 	validateModelRefs(result);
 	return result;
@@ -2655,8 +2973,9 @@ const phpMergeAdapter = {
 	testFilePatterns: [/Test\.php$/],
 	urlFingerprintConfig: PHP_URL_FINGERPRINT_CONFIG,
 	resolveGrammar: (mod) => {
-		if (typeof mod === "object" && mod !== null && "php" in mod) return mod.php;
-		return mod;
+		const m = mod?.default ?? mod;
+		if (typeof m === "object" && m !== null && "php" in m) return m.php;
+		return m;
 	},
 	parseStatements(tree, source) {
 		const imports = [];
@@ -3162,6 +3481,35 @@ async function extractStatements(source, language) {
 	return adapter.parseStatements(tree, source);
 }
 /**
+* Return a map of top-level class name → { bodyEndLine, bodyEndCol } using
+* tree-sitter.  `bodyEndLine` is 0-based.  For brace-delimited classes the
+* end points at the closing brace line; for indentation-delimited classes
+* it points one past the last line of the class body.
+*/
+async function extractClassEndLines(source, language) {
+	const tree = safeParse(await getParser(language), source);
+	const map = /* @__PURE__ */ new Map();
+	function processClassNode(node) {
+		const nameNode = node.childForFieldName("name");
+		if (!nameNode) return;
+		const name = nameNode.text;
+		const body = node.childForFieldName("body");
+		const endRow = body ? body.endPosition.row : node.endPosition.row;
+		if (source[body ? body.endIndex - 1 : node.endIndex - 1] === "}") map.set(name, { bodyEndLine: endRow });
+		else map.set(name, { bodyEndLine: endRow + 1 });
+	}
+	for (const child of tree.rootNode.children) {
+		if (child.type === "class_definition" || child.type === "class_declaration") processClassNode(child);
+		if (child.type === "decorated_definition") {
+			for (const inner of child.namedChildren) if (inner.type === "class_definition") processClassNode(inner);
+		}
+		if (child.type === "export_statement") {
+			for (const inner of child.namedChildren) if (inner.type === "class_declaration") processClassNode(inner);
+		}
+	}
+	return map;
+}
+/**
 * Merge generated content into an existing file.
 *
 * - Parses both files with tree-sitter
@@ -3310,11 +3658,27 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 		const addedParts = [...toAppend];
 		if (insertions) for (const ins of insertions) addedParts.push(ins.text);
 		const addedCodeText = addedParts.join("\n");
-		const filteredImports = newImports.filter((imp) => {
+		const filteredImports = [];
+		for (const imp of newImports) {
 			const braceMatch = imp.text.match(/\{([^}]+)\}/);
-			if (!braceMatch) return true;
-			return braceMatch[1].split(",").map((n) => n.replace(/\btype\b/, "").trim()).filter(Boolean).some((name) => addedCodeText.includes(name));
-		});
+			if (!braceMatch) {
+				filteredImports.push(imp);
+				continue;
+			}
+			const names = braceMatch[1].split(",").map((n) => n.replace(/\btype\b/, "").trim()).filter(Boolean);
+			const usedNames = names.filter((name) => addedCodeText.includes(name));
+			if (usedNames.length === 0) continue;
+			if (usedNames.length === names.length) filteredImports.push(imp);
+			else {
+				const prefix = imp.text.trimStart().startsWith("import type") ? "import type" : "import";
+				const sourceMatch = imp.text.match(/from\s+(['"][^'"]+['"]);?/);
+				if (sourceMatch) filteredImports.push({
+					key: imp.key,
+					text: `${prefix} { ${usedNames.join(", ")} } from ${sourceMatch[1]};`
+				});
+				else filteredImports.push(imp);
+			}
+		}
 		if (filteredImports.length > 0) {
 			const renderedImports = adapter.renderImports ? adapter.renderImports(filteredImports) : filteredImports.map((entry) => entry.text);
 			const lines = result.split("\n");
@@ -3472,13 +3836,13 @@ async function writeFiles(files, outputDir, options) {
 	const language = options?.language;
 	const header = options?.header ?? "";
 	for (const file of sorted) {
-		const fullPath = path.join(outputDir, file.path);
+		const fullPath = path$1.join(outputDir, file.path);
 		let existingContent = null;
 		try {
 			existingContent = await fs.readFile(fullPath, "utf-8");
 		} catch {}
 		if (existingContent === null) {
-			await fs.mkdir(path.dirname(fullPath), { recursive: true });
+			await fs.mkdir(path$1.dirname(fullPath), { recursive: true });
 			await fs.writeFile(fullPath, file.content, "utf-8");
 			result.written.push(file.path);
 			continue;
@@ -3494,15 +3858,18 @@ async function writeFiles(files, outputDir, options) {
 		}
 		const adapter = language ? getMergeAdapter(language) : void 0;
 		if (adapter?.testFilePatterns ? adapter.testFilePatterns.some((p) => p.test(file.path)) : isDefaultTestFile(file.path)) {
-			result.skipped.push(file.path);
-			continue;
+			if (!(header && existingContent.startsWith(header))) {
+				result.skipped.push(file.path);
+				continue;
+			}
 		}
 		if (existingContent === file.content) {
 			result.identical.push(file.path);
 			continue;
 		}
 		if (file.overwriteExisting) {
-			await fs.writeFile(fullPath, file.content, "utf-8");
+			const content = existingContent.includes("@oagen-ignore-start") && language && hasGrammar(language) ? await overwriteWithPreservedRegions(existingContent, file.content, language) : file.content;
+			await fs.writeFile(fullPath, content, "utf-8");
 			result.written.push(file.path);
 			continue;
 		}
@@ -3546,6 +3913,311 @@ async function writeFiles(files, outputDir, options) {
 function isDefaultTestFile(filePath) {
 	return /\.(spec|test)\.[jt]sx?$/.test(filePath) || filePath.endsWith("_test.go") || filePath.endsWith("_test.rb") || filePath.endsWith("_spec.rb") || /(?:^|\/)test_.*\.py$/.test(filePath) || filePath.endsWith("_test.py") || filePath.endsWith("Test.php") || filePath.endsWith("_test.rs") || /(?:^|\/)tests\/.*\.rs$/.test(filePath);
 }
+/**
+* Overwrite a file with generated content while preserving
+* `@oagen-ignore-start` / `@oagen-ignore-end` regions (and their
+* required imports) from the existing file.
+*
+* Uses tree-sitter via `extractClassEndLines` to find accurate class
+* boundaries so ignore blocks are inserted at the correct position even
+* when docstrings contain unindented text.
+*/
+async function overwriteWithPreservedRegions(existingContent, generatedContent, language) {
+	const existingLines = existingContent.split("\n");
+	const generatedLines = generatedContent.split("\n");
+	const blocks = [];
+	for (let i = 0; i < existingLines.length; i++) {
+		if (!existingLines[i].includes("@oagen-ignore-start")) continue;
+		const startIdx = i;
+		while (i < existingLines.length && !existingLines[i].includes("@oagen-ignore-end")) i++;
+		blocks.push({
+			containingClass: findContainingClass(existingLines, startIdx),
+			lines: existingLines.slice(startIdx, i + 1)
+		});
+	}
+	if (blocks.length === 0) return generatedContent;
+	const result = [...generatedLines];
+	spliceExtraImports(existingLines, result);
+	const classEndLines = await extractClassEndLines(result.join("\n"), language);
+	const blocksByClass = /* @__PURE__ */ new Map();
+	for (const b of blocks) {
+		if (!blocksByClass.has(b.containingClass)) blocksByClass.set(b.containingClass, []);
+		blocksByClass.get(b.containingClass).push(b.lines);
+	}
+	const replacedClasses = /* @__PURE__ */ new Set();
+	const handledBlockKeys = /* @__PURE__ */ new Set();
+	const replacements = [];
+	for (const [className, classBlocks] of blocksByClass) {
+		let targetClass = className;
+		if (!targetClass) for (const blockLines of classBlocks) {
+			for (const l of blockLines) {
+				const m = l.match(/^(?:export\s+)?class\s+(\w+)/);
+				if (m && classEndLines.has(m[1])) {
+					targetClass = m[1];
+					break;
+				}
+			}
+			if (targetClass) break;
+		}
+		if (!targetClass) continue;
+		if (!classBlocks.some((blockLines) => blockLines.some((l) => {
+			return l.match(/^(?:export\s+)?class\s+(\w+)/)?.[1] === targetClass;
+		}))) continue;
+		const info = classEndLines.get(targetClass);
+		if (!info) continue;
+		const startLine = findClassDeclarationStart(result, targetClass, info.bodyEndLine);
+		if (startLine < 0) continue;
+		const content = [];
+		for (const block of classBlocks) {
+			content.push("");
+			content.push(...block);
+		}
+		replacements.push({
+			startLine,
+			endLine: info.bodyEndLine,
+			content
+		});
+		replacedClasses.add(targetClass);
+		handledBlockKeys.add(className);
+	}
+	replacements.sort((a, b) => b.startLine - a.startLine);
+	for (const rep of replacements) result.splice(rep.startLine, rep.endLine - rep.startLine, ...rep.content);
+	let effectiveClassEndLines = classEndLines;
+	if (replacedClasses.size > 0) effectiveClassEndLines = await extractClassEndLines(result.join("\n"), language);
+	const insertions = [];
+	for (const [className, classBlocks] of blocksByClass) {
+		if (handledBlockKeys.has(className) || replacedClasses.has(className)) continue;
+		const info = className ? effectiveClassEndLines.get(className) : void 0;
+		const insertLine = info ? info.bodyEndLine : result.length;
+		const content = [];
+		for (const block of classBlocks) {
+			content.push("");
+			content.push(...block);
+		}
+		insertions.push({
+			line: insertLine,
+			content
+		});
+	}
+	insertions.sort((a, b) => b.line - a.line);
+	for (const ins of insertions) result.splice(ins.line, 0, ...ins.content);
+	return result.join("\n");
+}
+/** Scan backwards from `lineIdx` to find the nearest class declaration name. */
+function findContainingClass(lines, lineIdx) {
+	for (let j = lineIdx - 1; j >= 0; j--) {
+		const m = lines[j].match(/^(?:export\s+)?class\s+(\w+)/);
+		if (m) return m[1];
+	}
+	return "";
+}
+/**
+* Find the start line of a class declaration (including decorators above it)
+* by scanning backwards from `beforeLine`.
+*/
+function findClassDeclarationStart(lines, className, beforeLine) {
+	const classPattern = new RegExp(`^(?:export\\s+)?class\\s+${className}\\b`);
+	for (let i = beforeLine - 1; i >= 0; i--) {
+		if (!classPattern.test(lines[i])) continue;
+		let start = i;
+		while (start > 0 && /^\s*@\w+/.test(lines[start - 1])) start--;
+		return start;
+	}
+	return -1;
+}
+/**
+* Collect `from X import Y, Z` identifiers grouped by module, handling
+* both single-line and multiline (parenthesized) forms.
+*/
+function collectFromImports(lines) {
+	const byModule = /* @__PURE__ */ new Map();
+	for (let i = 0; i < lines.length; i++) {
+		if (!/^from\s+/.test(lines[i])) continue;
+		let fullText = lines[i];
+		if (fullText.includes("(") && !fullText.includes(")")) while (i + 1 < lines.length) {
+			i++;
+			fullText += " " + lines[i].trim();
+			if (lines[i].includes(")")) break;
+		}
+		const match = fullText.replace(/[()]/g, "").replace(/\s+/g, " ").trim().match(/^from\s+(\S+)\s+import\s+(.+)$/);
+		if (!match) continue;
+		const mod = match[1];
+		if (!byModule.has(mod)) byModule.set(mod, /* @__PURE__ */ new Set());
+		for (const id of match[2].split(",").map((s) => s.trim()).filter(Boolean)) byModule.get(mod).add(id);
+	}
+	return byModule;
+}
+/**
+* Add imports from the existing file that are absent from the generated
+* result. Handles both `import X` and `from X import Y` forms.
+* Mutates `resultLines` in place.
+*/
+function spliceExtraImports(existingLines, resultLines) {
+	const isSimpleImport = (l) => /^import\s+\w/.test(l);
+	const existingSimple = new Set(existingLines.filter(isSimpleImport).map((l) => l.trim()));
+	const generatedSimple = new Set(resultLines.filter(isSimpleImport).map((l) => l.trim()));
+	const extraSimple = [...existingSimple].filter((l) => !generatedSimple.has(l));
+	const existingFrom = collectFromImports(existingLines);
+	const generatedFrom = collectFromImports(resultLines);
+	const extraFromLines = [];
+	for (const [mod, existIds] of existingFrom) {
+		const genIds = generatedFrom.get(mod);
+		if (!genIds) extraFromLines.push(`from ${mod} import ${[...existIds].join(", ")}`);
+		else {
+			const extra = [...existIds].filter((id) => !genIds.has(id));
+			if (extra.length > 0) extraFromLines.push(`from ${mod} import ${extra.join(", ")}`);
+		}
+	}
+	const allExtra = [...extraSimple, ...extraFromLines];
+	if (allExtra.length === 0) return;
+	let lastImportIdx = -1;
+	for (let i = 0; i < resultLines.length; i++) if (isSimpleImport(resultLines[i]) || /^from\s+/.test(resultLines[i])) {
+		lastImportIdx = i;
+		if (resultLines[i].includes("(") && !resultLines[i].includes(")")) while (i + 1 < resultLines.length) {
+			i++;
+			lastImportIdx = i;
+			if (resultLines[i].includes(")")) break;
+		}
+	}
+	if (lastImportIdx >= 0) resultLines.splice(lastImportIdx + 1, 0, ...allExtra);
+}
+//#endregion
+//#region src/ir/operation-hints.ts
+/** Minimal snake_case converter for path segments (avoids cross-layer import). */
+function toSnake(s) {
+	return s.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[-\s.]+/g, "_").toLowerCase();
+}
+/**
+* Action verbs recognised at the terminal path segment.
+* When a path ends with one of these, we use it as the verb instead of
+* deriving a CRUD verb from the HTTP method.
+*/
+const ACTION_VERBS = new Set([
+	"accept",
+	"activate",
+	"authorize",
+	"challenge",
+	"check",
+	"complete",
+	"confirm",
+	"deactivate",
+	"disable",
+	"enable",
+	"enroll",
+	"generate",
+	"reactivate",
+	"resend",
+	"revoke",
+	"send",
+	"verify"
+]);
+/** Map HTTP method → default CRUD verb. */
+const CRUD_VERB = {
+	get: "list",
+	post: "create",
+	put: "update",
+	patch: "update",
+	delete: "delete",
+	head: "get",
+	options: "list",
+	trace: "list"
+};
+/**
+* Naive singularization: strips trailing "s" with common-sense exceptions.
+* Good enough for API resource nouns; not a general-purpose English stemmer.
+*/
+function singularize(word) {
+	if (word.length <= 2) return word;
+	if (word.endsWith("ies")) return word.slice(0, -3) + "y";
+	if (word.endsWith("ses") || word.endsWith("zes") || word.endsWith("xes") || word.endsWith("ches") || word.endsWith("shes")) return word.slice(0, -2);
+	if (word.endsWith("ss") || word.endsWith("us") || word.endsWith("is")) return word;
+	if (word.endsWith("s")) return word.slice(0, -1);
+	return word;
+}
+/**
+* Derive a snake_case method name from an operation's HTTP method and path.
+*
+* Rules:
+* 1. Strip path-param segments (`{id}`, `{slug}`, etc.)
+* 2. If the terminal segment is an action verb, use it as the verb
+* 3. Otherwise, use the CRUD verb for the HTTP method
+* 4. For GET on a collection (no trailing {id}), use "list"; with {id}, use "get"
+* 5. For POST on a resource path, if only one path param, use "create" singular
+* 6. Singularize the resource noun for single-resource operations
+*/
+function deriveMethodName(op, _service) {
+	const segments = op.path.split("/").filter(Boolean);
+	const staticSegments = [];
+	let trailingParam = false;
+	for (const seg of segments) if (seg.startsWith("{") && seg.endsWith("}")) trailingParam = true;
+	else {
+		staticSegments.push(seg);
+		trailingParam = false;
+	}
+	if (staticSegments.length === 0) return `${CRUD_VERB[op.httpMethod] ?? "get"}_root`;
+	const terminal = toSnake(staticSegments[staticSegments.length - 1]);
+	if (ACTION_VERBS.has(terminal)) {
+		const context = staticSegments.slice(0, -1).filter((s) => !s.startsWith("{"));
+		const resource = context.length > 0 ? toSnake(singularize(context[context.length - 1])) : "";
+		if (resource) return `${terminal}_${resource}`;
+		return terminal;
+	}
+	let verb = CRUD_VERB[op.httpMethod] ?? "get";
+	if (op.httpMethod === "get" && trailingParam) verb = "get";
+	let resource = toSnake(terminal);
+	if (staticSegments.length >= 2) {
+		const penultimate = staticSegments[staticSegments.length - 2];
+		const penIdx = segments.lastIndexOf(penultimate);
+		const termIdx = segments.lastIndexOf(staticSegments[staticSegments.length - 1]);
+		if (segments.slice(penIdx + 1, termIdx).some((s) => s.startsWith("{"))) resource = `${toSnake(singularize(penultimate))}_${resource}`;
+	}
+	const noun = trailingParam ? singularize(resource) : resource;
+	return `${verb}_${verb === "list" ? resource : noun}`;
+}
+/**
+* Resolve all operations in the spec, applying hints and mount rules.
+*
+* @param spec - The parsed API spec
+* @param hints - Per-operation overrides keyed by "METHOD /path"
+* @param mountRules - Service name → target service mappings
+* @returns Resolved operations ready for emitter consumption
+*/
+function resolveOperations(spec, hints, mountRules) {
+	const resolved = [];
+	const hintMap = hints ?? {};
+	const mounts = mountRules ?? {};
+	for (const service of spec.services) for (const op of service.operations) {
+		const hint = hintMap[`${op.httpMethod.toUpperCase()} ${op.path}`];
+		const methodName = hint?.name ?? deriveMethodName(op, service);
+		const mountOn = hint?.mountOn ?? mounts[service.name] ?? service.name;
+		let wrappers;
+		if (hint?.split) wrappers = hint.split.map((sh) => ({
+			name: sh.name,
+			targetVariant: sh.targetVariant,
+			defaults: sh.defaults ?? {},
+			inferFromClient: sh.inferFromClient ?? [],
+			exposedParams: sh.exposedParams ?? [],
+			optionalParams: [],
+			responseModelName: resolveResponseModelName(op)
+		}));
+		resolved.push({
+			operation: op,
+			service,
+			methodName,
+			mountOn,
+			wrappers
+		});
+	}
+	return resolved;
+}
+/** Extract the response model name from an operation (for wrapper metadata). */
+function resolveResponseModelName(op) {
+	if (op.httpMethod === "delete") return null;
+	const ref = op.response;
+	if (ref.kind === "model") return ref.name;
+	if (ref.kind === "nullable" && ref.inner.kind === "model") return ref.inner.name;
+	return null;
+}
 //#endregion
 //#region src/engine/generate-files.ts
 function buildEmitterContext(spec, options) {
@@ -3555,20 +4227,79 @@ function buildEmitterContext(spec, options) {
 		spec,
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
-		overlayLookup: options.overlayLookup
+		overlayLookup: options.overlayLookup,
+		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules)
 	};
 }
+/**
+* Collect model and enum names transitively referenced by service operations.
+* Walks operation parameters, request bodies, responses, and pagination item
+* types, then chases model field references until the set stabilizes.
+*/
+function collectReferencedNames(services, models) {
+	const referencedModels = /* @__PURE__ */ new Set();
+	const referencedEnums = /* @__PURE__ */ new Set();
+	const collectFromTypeRef = (ref) => {
+		walkTypeRef(ref, {
+			model: (r) => referencedModels.add(r.name),
+			enum: (r) => referencedEnums.add(r.name)
+		});
+	};
+	for (const service of services) for (const op of service.operations) {
+		for (const p of [
+			...op.pathParams,
+			...op.queryParams,
+			...op.headerParams,
+			...op.cookieParams ?? []
+		]) collectFromTypeRef(p.type);
+		if (op.requestBody) collectFromTypeRef(op.requestBody);
+		collectFromTypeRef(op.response);
+		if (op.pagination) collectFromTypeRef(op.pagination.itemType);
+		for (const err of op.errors) if (err.type) collectFromTypeRef(err.type);
+		if (op.successResponses) for (const sr of op.successResponses) collectFromTypeRef(sr.type);
+	}
+	for (const model of models) if (isDiscriminatedModel(model)) referencedModels.add(model.name);
+	const modelsByName = new Map(models.map((m) => [m.name, m]));
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [...referencedModels];
+	while (queue.length > 0) {
+		const name = queue.pop();
+		if (visited.has(name)) continue;
+		visited.add(name);
+		const model = modelsByName.get(name);
+		if (!model) continue;
+		for (const field of model.fields) {
+			collectFromTypeRef(field.type);
+			for (const m of referencedModels) if (!visited.has(m)) queue.push(m);
+		}
+	}
+	return {
+		models: referencedModels,
+		enums: referencedEnums
+	};
+}
+function isDiscriminatedModel(model) {
+	return model.fields.some((field) => (field.name === "event" || field.name === "type" || field.name === "object") && field.type.kind === "literal");
+}
 /** Collect all generated files from an emitter (no headers, no path prefixes). */
 function generateAllFiles(spec, emitter, ctx) {
+	const referenced = collectReferencedNames(spec.services, spec.models);
+	const reachableModels = spec.models.filter((m) => referenced.models.has(m.name));
+	const reachableEnums = spec.enums.filter((e) => referenced.enums.has(e.name));
+	const reachableSpec = {
+		...spec,
+		models: reachableModels,
+		enums: reachableEnums
+	};
 	return [
-		...emitter.generateModels(spec.models, ctx),
-		...emitter.generateEnums(spec.enums, ctx),
+		...emitter.generateModels(reachableModels, ctx),
+		...emitter.generateEnums(reachableEnums, ctx),
 		...emitter.generateResources(spec.services, ctx),
 		...emitter.generateClient(spec, ctx),
 		...emitter.generateErrors(ctx),
 		...emitter.generateConfig(ctx),
-		...emitter.generateTypeSignatures?.(spec, ctx) ?? [],
-		...emitter.generateTests(spec, ctx),
+		...emitter.generateTypeSignatures?.(reachableSpec, ctx) ?? [],
+		...emitter.generateTests(reachableSpec, ctx),
 		...emitter.generateManifest?.(spec, ctx) ?? []
 	];
 }
@@ -3592,6 +4323,103 @@ function generateFiles(spec, emitter, options) {
 }
 //#endregion
 //#region src/engine/integrate.ts
+/**
+* Resolve a relative import path against a source file path to get the
+* target file path.  Handles implicit .ts extensions and /index.ts.
+*/
+function resolveImportPath(fromFilePath, importModulePath, knownPaths) {
+	const cleaned = importModulePath.replace(/^['"]|['"]$/g, "");
+	if (!cleaned.startsWith(".")) return void 0;
+	const dir = path.dirname(fromFilePath);
+	const resolved = path.normalize(path.join(dir, cleaned));
+	for (const candidate of [
+		resolved,
+		`${resolved}.ts`,
+		`${resolved}/index.ts`
+	]) if (knownPaths.has(candidate)) return candidate;
+}
+/**
+* Determine whether a generated file is a "root" — a file that should always
+* be integrated into the target.  Roots are entry points from which we trace
+* the import graph.  Everything else must be reachable from a root.
+*
+* Roots: resource classes, client, config, errors, enums, barrel index files.
+* Non-roots: serializers, fixtures, standalone interfaces, test files.
+*/
+function isRootFile(filePath) {
+	if (filePath.includes("/fixtures/")) return false;
+	if (filePath.endsWith(".spec.ts") || filePath.endsWith(".test.ts")) return false;
+	if (filePath.includes("/serializers/")) return false;
+	if (filePath.includes("/interfaces/") && !filePath.endsWith("/index.ts")) return false;
+	return true;
+}
+/**
+* Build a file-level dependency graph from generated files and return only
+* files reachable from root entry points.  Uses tree-sitter to parse imports.
+*/
+async function treeShakeFiles(files, language) {
+	if (!hasGrammar(language)) return files;
+	const knownPaths = new Set(files.map((f) => f.path));
+	const deps = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		if (!file.path.endsWith(".ts") && !file.path.endsWith(".js")) {
+			deps.set(file.path, /* @__PURE__ */ new Set());
+			continue;
+		}
+		const parsed = await extractStatements(file.content, language);
+		const fileDeps = /* @__PURE__ */ new Set();
+		for (const imp of parsed.imports) {
+			const resolved = resolveImportPath(file.path, imp.key, knownPaths);
+			if (resolved) fileDeps.add(resolved);
+		}
+		for (const stmt of parsed.statements) if (stmt.kind === "reexport") {
+			const match = stmt.text.match(/from\s+['"]([^'"]+)['"]/);
+			if (match) {
+				const resolved = resolveImportPath(file.path, match[1], knownPaths);
+				if (resolved) fileDeps.add(resolved);
+			}
+		}
+		deps.set(file.path, fileDeps);
+	}
+	const codeExtensions = new Set([
+		".ts",
+		".js",
+		".tsx",
+		".jsx",
+		".py",
+		".rb",
+		".go",
+		".rs",
+		".kt",
+		".cs",
+		".ex",
+		".exs",
+		".php"
+	]);
+	const reachable = /* @__PURE__ */ new Set();
+	const queue = [];
+	for (const file of files) {
+		const ext = file.path.slice(file.path.lastIndexOf("."));
+		if (!codeExtensions.has(ext)) {
+			reachable.add(file.path);
+			continue;
+		}
+		if (isRootFile(file.path)) {
+			reachable.add(file.path);
+			queue.push(file.path);
+		}
+	}
+	while (queue.length > 0) {
+		const current = queue.pop();
+		const fileDeps = deps.get(current);
+		if (!fileDeps) continue;
+		for (const dep of fileDeps) if (!reachable.has(dep)) {
+			reachable.add(dep);
+			queue.push(dep);
+		}
+	}
+	return files.filter((f) => reachable.has(f.path));
+}
 function mapFilesForTargetIntegration(files, language) {
 	const langPrefix = `${language}/`;
 	return files.filter((f) => f.integrateTarget !== false).map((f) => {
@@ -3603,11 +4431,93 @@ function mapFilesForTargetIntegration(files, language) {
 		};
 	});
 }
+/**
+* Resolve file-to-directory conflicts in the target.
+*
+* When a generated file creates a package directory (e.g., `api_keys/__init__.py`)
+* that would shadow an existing module file (e.g., `api_keys.py`), move the
+* module file's content into `_compat.py` inside the package and add a
+* re-export from `__init__.py`.  This preserves backward-compatible imports
+* (e.g., `from workos.api_keys import ApiKeysModule`) while the package directory
+* provides the generated models and resource classes.
+*/
+async function resolveFileToDirectoryConflicts(files, targetDir) {
+	const result = [...files];
+	const removals = [];
+	for (let i = 0; i < result.length; i++) {
+		const file = result[i];
+		const match = file.path.match(/^(.+)\/__init__\.py$/);
+		if (!match) continue;
+		const dirPath = match[1];
+		const moduleFilePath = `${dirPath}.py`;
+		const fullModulePath = path.join(targetDir, moduleFilePath);
+		let moduleContent;
+		try {
+			moduleContent = await fs.readFile(fullModulePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const compatPath = `${dirPath}/_compat.py`;
+		result.push({
+			path: compatPath,
+			content: moduleContent,
+			overwriteExisting: true
+		});
+		const compatImport = "from ._compat import *  # noqa: F401,F403  # pyright: ignore[reportUnusedImport]";
+		const existingContent = file.content.endsWith("\n") ? file.content : file.content + "\n";
+		result[i] = {
+			...file,
+			content: existingContent + compatImport + "\n"
+		};
+		removals.push(fullModulePath);
+	}
+	return {
+		files: result,
+		removals
+	};
+}
 async function integrateGeneratedFiles(opts) {
-	return writeFiles(mapFilesForTargetIntegration(opts.files, opts.language), opts.targetDir, {
+	const { files: resolved, removals } = await resolveFileToDirectoryConflicts(await treeShakeFiles(mapFilesForTargetIntegration(opts.files, opts.language), opts.language), opts.targetDir);
+	const result = await writeFiles(resolved, opts.targetDir, {
 		language: opts.language,
 		header: opts.header
 	});
+	for (const filePath of removals) try {
+		await fs.unlink(filePath);
+	} catch {}
+	return result;
+}
+//#endregion
+//#region src/engine/formatter.ts
+/**
+* Post-integration formatter.
+*
+* After generating and merging files into a target directory, runs the
+* emitter-provided format command on all written/merged files so that
+* generated code matches the target project's style conventions.
+*/
+const execFileAsync = promisify(execFile);
+/**
+* Run the emitter's format command on the given target files.
+* Silently skips if the emitter has no formatCommand or returns null.
+*/
+async function formatTargetFiles(emitter, targetDir, filePaths) {
+	if (filePaths.length === 0) return;
+	if (!emitter.formatCommand) return;
+	const formatCmd = emitter.formatCommand(targetDir);
+	if (!formatCmd) return;
+	const absolutePaths = filePaths.map((f) => path$1.resolve(targetDir, f));
+	const batchSize = formatCmd.batchSize ?? 100;
+	for (let i = 0; i < absolutePaths.length; i += batchSize) {
+		const batch = absolutePaths.slice(i, i + batchSize);
+		try {
+			await execFileAsync(formatCmd.cmd, [...formatCmd.args, ...batch], {
+				cwd: targetDir,
+				maxBuffer: 10 * 1024 * 1024,
+				timeout: 12e4
+			});
+		} catch {}
+	}
 }
 //#endregion
 //#region src/engine/orchestrator.ts
@@ -3636,6 +4546,12 @@ async function generate(spec, emitter, options) {
 		if (targetResult.written.length > 0) console.log(`Target: created ${targetResult.written.length} new files`);
 		if (targetResult.merged.length > 0) console.log(`Target: merged into ${targetResult.merged.length} existing files (additive only)`);
 		if (targetResult.skipped.length > 0) console.log(`Target: skipped ${targetResult.skipped.length} files (excluded or no grammar)`);
+		const allTargetFiles = [
+			...targetResult.written,
+			...targetResult.merged,
+			...targetResult.identical
+		];
+		if (allTargetFiles.length > 0) await formatTargetFiles(emitter, options.target, allTargetFiles);
 	}
 	return withHeaders;
 }
@@ -4204,7 +5120,7 @@ function loadOverlayContext(opts) {
 		throw new ConfigError(`Failed to parse API surface JSON: ${err instanceof Error ? err.message : String(err)}`, `Ensure "${opts.apiSurfacePath}" contains valid JSON. Re-run \`oagen extract\` to regenerate it.`);
 	}
 	let manifest;
-	const resolvedManifestPath = opts.manifestPath ?? path.join(opts.outputDir, "smoke-manifest.json");
+	const resolvedManifestPath = opts.manifestPath ?? path$1.join(opts.outputDir, "smoke-manifest.json");
 	if (opts.manifestPath || existsSync(resolvedManifestPath)) try {
 		const parsed = JSON.parse(readFileSync(resolvedManifestPath, "utf-8"));
 		if (Array.isArray(parsed)) manifest = parsed;
@@ -4295,7 +5211,10 @@ function expandDocUrls(spec, docUrl) {
 //#endregion
 //#region src/cli/generate.ts
 async function generateCommand(opts) {
-	let ir = await parseSpec(opts.spec, { operationIdTransform: opts.operationIdTransform });
+	let ir = await parseSpec(opts.spec, {
+		operationIdTransform: opts.operationIdTransform,
+		schemaNameTransform: opts.schemaNameTransform
+	});
 	if (opts.docUrl) ir = expandDocUrls(ir, opts.docUrl);
 	const emitter = getEmitter(opts.lang);
 	const namespace = opts.namespace ?? ir.name;
@@ -4318,7 +5237,9 @@ async function generateCommand(opts) {
 		outputDir: opts.output,
 		target: opts.target,
 		apiSurface,
-		overlayLookup
+		overlayLookup,
+		operationHints: opts.operationHints,
+		mountRules: opts.mountRules
 	});
 	if (opts.dryRun) for (const f of files) console.log(f.path);
 	else {
@@ -4675,7 +5596,10 @@ function summarize(changes) {
 //#endregion
 //#region src/cli/diff.ts
 async function diffCommand(opts) {
-	const parseOptions = { operationIdTransform: opts.operationIdTransform };
+	const parseOptions = {
+		operationIdTransform: opts.operationIdTransform,
+		schemaNameTransform: opts.schemaNameTransform
+	};
 	let [oldSpec, newSpec] = await Promise.all([parseSpec(opts.old, parseOptions), parseSpec(opts.new, parseOptions)]);
 	if (opts.docUrl) {
 		oldSpec = expandDocUrls(oldSpec, opts.docUrl);
@@ -5277,7 +6201,7 @@ function cleanGeneratedFiles(dir) {
 		return;
 	}
 	for (const entry of entries) {
-		const full = path.join(dir, entry);
+		const full = path$1.join(dir, entry);
 		let stat;
 		try {
 			stat = statSync(full);
@@ -5307,7 +6231,7 @@ function cleanGeneratedFiles(dir) {
 * it to ManifestEntry[] for the overlay builder.
 */
 function loadManifestFromDir(outputDir) {
-	const manifestPath = path.join(outputDir, "smoke-manifest.json");
+	const manifestPath = path$1.join(outputDir, "smoke-manifest.json");
 	if (!existsSync(manifestPath)) return void 0;
 	try {
 		const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -5468,16 +6392,16 @@ function runStalenessCheck(baseline, oldSpec, newSpec, lang) {
 //#endregion
 //#region src/verify/run-smoke-check.ts
 const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __dirname = path$1.dirname(__filename);
 function resolveScript(scriptRelPath) {
-	const distScript = path.resolve(__dirname, "..", "..", "dist", "scripts", scriptRelPath.replace(/\.ts$/, ".js"));
+	const distScript = path$1.resolve(__dirname, "..", "..", "dist", "scripts", scriptRelPath.replace(/\.ts$/, ".mjs"));
 	if (existsSync(distScript)) return {
 		bin: "node",
 		script: distScript
 	};
 	return {
 		bin: "npx",
-		script: path.resolve(__dirname, "..", "..", "scripts", scriptRelPath)
+		script: path$1.resolve(__dirname, "..", "..", "scripts", scriptRelPath)
 	};
 }
 function runPackagedScript(scriptRelPath, args) {
@@ -5589,7 +6513,7 @@ function printCompatResult(result, baseline) {
 	console.log(`compat: ${result.preservationScore}% (${result.preservedSymbols}/${result.totalBaselineSymbols} symbols preserved)`);
 }
 async function verifyCommand(opts) {
-	const { spec, oldSpec, lang, output, apiSurface, rawResults, smokeConfig, smokeRunner, scope, diagnostics, operationIdTransform } = opts;
+	const { spec, oldSpec, lang, output, apiSurface, rawResults, smokeConfig, smokeRunner, scope, diagnostics, operationIdTransform, schemaNameTransform } = opts;
 	const maxRetries = opts.maxRetries ?? 3;
 	const diagData = {};
 	let stepNum = 1;
@@ -5600,7 +6524,10 @@ async function verifyCommand(opts) {
 		console.log(separator);
 		const effectiveScope = scope ?? (spec ? "spec-only" : "full");
 		let parsedSpec;
-		if (effectiveScope === "spec-only" && spec) parsedSpec = await parseSpec(spec, { operationIdTransform });
+		if (effectiveScope === "spec-only" && spec) parsedSpec = await parseSpec(spec, {
+			operationIdTransform,
+			schemaNameTransform
+		});
 		else if (effectiveScope === "spec-only") throw new CommandError("error: --scope spec-only requires --spec <path>", "", 1);
 		const compatFlow = parsedSpec && maxRetries > 0 ? await runOverlayRetryLoop({
 			baseline,
@@ -5643,7 +6570,13 @@ async function verifyCommand(opts) {
 		console.log(`\n${separator}`);
 		console.log(`Step ${stepNum}: Staleness detection`);
 		console.log(separator);
-		const stalenessResult = runStalenessCheck(baseline, await parseSpec(oldSpec, { operationIdTransform }), await parseSpec(spec, { operationIdTransform }), lang);
+		const stalenessResult = runStalenessCheck(baseline, await parseSpec(oldSpec, {
+			operationIdTransform,
+			schemaNameTransform
+		}), await parseSpec(spec, {
+			operationIdTransform,
+			schemaNameTransform
+		}), lang);
 		if (stalenessResult.violations.length > 0) {
 			console.log(`Found ${stalenessResult.violations.length} stale symbol(s):`);
 			for (const v of stalenessResult.violations) console.log(`  [${v.category}] ${v.severity}: ${v.symbolPath} — ${v.message}`);
@@ -5920,6 +6853,50 @@ async function initCommand(opts) {
 	console.log("  - npm run sdk:verify -- --spec <path-to-spec>");
 }
 //#endregion
+//#region src/cli/resolve.ts
+async function resolveCommand(opts) {
+	let ir = await parseSpec(opts.spec, {
+		operationIdTransform: opts.operationIdTransform,
+		schemaNameTransform: opts.schemaNameTransform
+	});
+	if (opts.docUrl) ir = expandDocUrls(ir, opts.docUrl);
+	const resolved = resolveOperations(ir, opts.operationHints, opts.mountRules);
+	if ((opts.format ?? "table") === "json") {
+		const output = resolved.map(toJsonRow);
+		console.log(JSON.stringify(output, null, 2));
+		return;
+	}
+	printTable(resolved, opts.operationHints);
+}
+function toJsonRow(r) {
+	return {
+		service: r.service.name,
+		method: r.operation.httpMethod.toUpperCase(),
+		path: r.operation.path,
+		derivedName: r.methodName,
+		hintApplied: r.methodName !== r.operation.name,
+		mountOn: r.mountOn,
+		wrappers: r.wrappers?.map((w) => w.name)
+	};
+}
+function printTable(resolved, hints) {
+	const hintMap = hints ?? {};
+	console.log("| Service | Method | Path | Resolved Name | Hint | Mount On |");
+	console.log("|---|---|---|---|---|---|");
+	const unhinted = [];
+	for (const r of resolved) {
+		const hasHint = `${r.operation.httpMethod.toUpperCase()} ${r.operation.path}` in hintMap;
+		const hintMarker = hasHint ? "yes" : "";
+		const mountChanged = r.mountOn !== r.service.name;
+		const mountCol = mountChanged ? r.mountOn : "";
+		console.log(`| ${r.service.name} | ${r.operation.httpMethod.toUpperCase()} | ${r.operation.path} | \`${r.methodName}\` | ${hintMarker} | ${mountCol} |`);
+		if (r.wrappers) for (const w of r.wrappers) console.log(`|  | | | \`${w.name}\` (wrapper) | yes | ${mountCol} |`);
+		if (!hasHint && !mountChanged) unhinted.push(r);
+	}
+	console.log("");
+	console.log(`Total: ${resolved.length} operations, ${resolved.length - unhinted.length} with hints/mounts, ${unhinted.length} algorithm-only`);
+}
+//#endregion
 //#region src/cli/config-loader.ts
 const CONFIG_NAMES = [
 	"oagen.config.ts",
@@ -5928,7 +6905,7 @@ const CONFIG_NAMES = [
 ];
 async function loadConfig(cwd = process.cwd()) {
 	for (const name of CONFIG_NAMES) {
-		const configPath = path.resolve(cwd, name);
+		const configPath = path$1.resolve(cwd, name);
 		if (!existsSync(configPath)) continue;
 		try {
 			const mod = await import(pathToFileURL(configPath).href);
@@ -5955,14 +6932,20 @@ function handleError(err) {
 }
 let configSmokeRunners;
 let configOperationIdTransform;
+let configSchemaNameTransform;
 let configDocUrl;
+let configOperationHints;
+let configMountRules;
 try {
 	const config = await loadConfig();
 	if (config) {
 		applyConfig(config);
 		configSmokeRunners = config.smokeRunners;
 		configOperationIdTransform = config.operationIdTransform;
+		configSchemaNameTransform = config.schemaNameTransform;
 		configDocUrl = config.docUrl;
+		configOperationHints = config.operationHints;
+		configMountRules = config.mountRules;
 	}
 } catch (err) {
 	handleError(err);
@@ -5985,13 +6968,17 @@ program.command("generate").description("Run a registered emitter against an Ope
 	generateCommand({
 		...opts,
 		operationIdTransform: configOperationIdTransform,
-		docUrl: configDocUrl
+		schemaNameTransform: configSchemaNameTransform,
+		docUrl: configDocUrl,
+		operationHints: configOperationHints,
+		mountRules: configMountRules
 	}).catch(handleError);
 });
 program.command("diff").description("Compare two OpenAPI specs and output a diff report").requiredOption("--old <path>", "Path to old spec").requiredOption("--new <path>", "Path to new spec").action((opts) => {
 	diffCommand({
 		...opts,
 		operationIdTransform: configOperationIdTransform,
+		schemaNameTransform: configSchemaNameTransform,
 		docUrl: configDocUrl
 	}).catch(handleError);
 });
@@ -6005,7 +6992,23 @@ program.command("verify").description("Run smoke tests (and optional compat chec
 	verifyCommand({
 		...opts,
 		maxRetries: parseInt(opts.maxRetries, 10),
-		operationIdTransform: configOperationIdTransform
+		operationIdTransform: configOperationIdTransform,
+		schemaNameTransform: configSchemaNameTransform
+	}).catch(handleError);
+});
+program.command("resolve").description("Resolve operation names from spec and output a review table").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").option("--format <format>", "Output format: table or json", "table").action((opts) => {
+	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
+	if (!opts.spec) {
+		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");
+		process.exit(1);
+	}
+	resolveCommand({
+		...opts,
+		operationIdTransform: configOperationIdTransform,
+		schemaNameTransform: configSchemaNameTransform,
+		docUrl: configDocUrl,
+		operationHints: configOperationHints,
+		mountRules: configMountRules
 	}).catch(handleError);
 });
 program.command("init").description("Scaffold a new emitter project").requiredOption("--lang <language>", "Target language").option("--project <dir>", "Project directory", ".").action((opts) => {