@workos/oagen 0.3.0 → 0.5.0

package/dist/cli/index.mjs

@@ -6,11 +6,125 @@ import { readFile } from "node:fs/promises";
 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";
+//#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.
@@ -69,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.`);
@@ -224,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;
@@ -255,7 +363,9 @@ const SINGULAR_SAFE_LIST = new Set([
 	"Canvas",
 	"Alias",
 	"Basis",
-	"Bus"
+	"Bus",
+	"Species",
+	"Series"
 ]);
 /**
 * Conservative singularize for the leading PascalCase word.
@@ -264,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);
@@ -290,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;
@@ -310,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}`;
 }
@@ -371,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);
@@ -387,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()];
@@ -402,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.
@@ -438,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);
@@ -453,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. */
@@ -611,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)) {
@@ -881,6 +1100,7 @@ const KNOWN_DATA_PATHS = new Set([
 	"edges"
 ]);
 const PAGINATION_METADATA_PATTERNS = [
+	"meta",
 	"metadata",
 	"pagination",
 	"cursor",
@@ -912,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
 		};
@@ -1140,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;
@@ -1220,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]) => ({
@@ -1342,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);
@@ -1365,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),
@@ -1383,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"
 		},
@@ -1403,7 +1662,9 @@ function extractParams(params, location) {
 		description: p.description,
 		deprecated: p.deprecated || p.schema?.deprecated || void 0,
 		default: p.schema?.default,
-		example: p.example ?? p.schema?.example
+		example: p.example ?? p.schema?.example,
+		style: p.style,
+		explode: p.explode
 	}));
 }
 function extractRequestBody(body, op, inlineModels) {
@@ -1581,7 +1842,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({
@@ -1708,6 +1976,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) {
@@ -1737,10 +2018,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 ?? "",
@@ -1755,7 +2038,8 @@ async function parseSpec(specPath, options) {
 		services,
 		models: finalModels,
 		enums,
-		auth
+		auth,
+		sdk: defaultSdkBehavior()
 	};
 	validateModelRefs(result);
 	return result;
@@ -2691,8 +2975,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 = [];
@@ -3143,6 +3428,30 @@ function safeParse(parser, source) {
 * Supports any language with a tree-sitter grammar package.
 */
 const parserCache = /* @__PURE__ */ new Map();
+/**
+* When replacing an existing docstring with a generated one, carry over any
+* `@deprecated` lines from the existing doc that aren't present in the
+* generated doc.  This prevents hand-written deprecation notices from being
+* silently dropped during docstring refresh.
+*/
+function preserveDeprecatedTags(existingDoc, generatedDoc) {
+	if (!existingDoc.includes("@deprecated")) return generatedDoc;
+	if (generatedDoc.includes("@deprecated")) return generatedDoc;
+	const deprecatedParts = [];
+	for (const line of existingDoc.split("\n")) if (/@deprecated\b/.test(line)) {
+		const match = line.match(/@deprecated\b.*/);
+		if (match) {
+			const cleaned = match[0].replace(/\s*\*\/\s*$/, "");
+			deprecatedParts.push(`   * ${cleaned}`);
+		}
+	}
+	if (deprecatedParts.length === 0) return generatedDoc;
+	const closingIdx = generatedDoc.lastIndexOf("*/");
+	if (closingIdx === -1) return generatedDoc;
+	const before = generatedDoc.slice(0, closingIdx);
+	const after = generatedDoc.slice(closingIdx);
+	return before + deprecatedParts.join("\n") + "\n " + after;
+}
 function findIgnoredRegions(source) {
 	const regions = [];
 	const startTag = "@oagen-ignore-start";
@@ -3198,6 +3507,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
@@ -3227,10 +3565,21 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 	}
 	for (const anchor of existingStatements.importAnchors) lastImportEndIndex = existingContent.slice(0, existingContent.indexOf(anchor)).split("\n").length - 1 + anchor.split("\n").length - 1;
 	if (lastImportEndIndex === -1 && existingStatements.importInsertionAnchor) lastImportEndIndex = existingContent.slice(0, existingContent.indexOf(existingStatements.importInsertionAnchor)).split("\n").length - 1 + existingStatements.importInsertionAnchor.split("\n").length - 1;
+	const existingExportedNames = /* @__PURE__ */ new Set();
 	for (const stmt of existingStatements.statements) {
-		if (stmt.kind === "reexport") existingReexports.add(adapter.normalizeReexport ? adapter.normalizeReexport(stmt.text.trim()) : stmt.text.trim());
-		if (stmt.key) existingKeys.add(stmt.key);
-		else existingUnnamedTexts.add(stmt.text.trim());
+		if (stmt.kind === "reexport") {
+			existingReexports.add(adapter.normalizeReexport ? adapter.normalizeReexport(stmt.text.trim()) : stmt.text.trim());
+			const braceMatch = stmt.text.match(/\{([^}]+)\}/);
+			if (braceMatch) for (const part of braceMatch[1].split(",")) {
+				const segments = part.trim().split(/\s+as\s+/);
+				const exportedName = (segments[1] ?? segments[0]).trim();
+				if (exportedName) existingExportedNames.add(exportedName);
+			}
+		}
+		if (stmt.key) {
+			existingKeys.add(stmt.key);
+			existingExportedNames.add(stmt.key);
+		} else existingUnnamedTexts.add(stmt.text.trim());
 	}
 	const headerLine = header.trim();
 	const newImports = [];
@@ -3290,6 +3639,17 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 				preserved++;
 				continue;
 			}
+			const braceMatch = stmt.text.match(/\{([^}]+)\}/);
+			if (braceMatch) {
+				const exportedNames = braceMatch[1].split(",").map((n) => {
+					const parts = n.trim().split(/\s+as\s+/);
+					return (parts[1] ?? parts[0]).trim();
+				}).filter(Boolean);
+				if (exportedNames.length > 0 && exportedNames.every((n) => existingExportedNames.has(n))) {
+					preserved++;
+					continue;
+				}
+			}
 		}
 		if (stmt.key && (existingKeys.has(stmt.key) || existingImportedNames.has(stmt.key))) {
 			preserved++;
@@ -3391,10 +3751,11 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			const genDoc = genInfo.docstring && genInfo.docstring.text.trim() !== headerLine ? genInfo.docstring : null;
 			if (genDoc) if (existInfo.docstring) {
 				if (!existInfo.docstring.text.includes("@oagen-ignore") && existInfo.docstring.text !== genDoc.text) {
+					const newText = preserveDeprecatedTags(existInfo.docstring.text, genDoc.text);
 					edits.push({
 						start: existInfo.docstring.startIndex,
 						end: existInfo.docstring.endIndex,
-						newText: genDoc.text
+						newText
 					});
 					docstringUpdates++;
 				}
@@ -3411,14 +3772,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			const matchedExistMembers = /* @__PURE__ */ new Set();
 			for (const [memberName, genMember] of genInfo.members) {
 				const existMember = existInfo.members.get(memberName);
-				if (!existMember || !genMember.docstring) continue;
+				if (!existMember) continue;
 				matchedExistMembers.add(memberName);
+				if (!genMember.docstring) continue;
 				if (existMember.docstring) {
 					if (!existMember.docstring.text.includes("@oagen-ignore") && existMember.docstring.text !== genMember.docstring.text) {
+						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
 						edits.push({
 							start: existMember.docstring.startIndex,
 							end: existMember.docstring.endIndex,
-							newText: genMember.docstring.text
+							newText
 						});
 						docstringUpdates++;
 					}
@@ -3433,34 +3796,59 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 					docstringUpdates++;
 				}
 			}
-			for (const [_genName, genMember] of genInfo.members) {
+			const unmatchedGenByFp = /* @__PURE__ */ new Map();
+			for (const [genName, genMember] of genInfo.members) {
+				if (matchedExistMembers.has(genName)) continue;
 				if (!genMember.docstring || !genMember.urlFingerprint) continue;
-				for (const [existName, existMember] of existInfo.members) {
-					if (matchedExistMembers.has(existName)) continue;
-					if (!existMember.urlFingerprint || existMember.urlFingerprint !== genMember.urlFingerprint) continue;
-					if (existMember.docstring) {
-						if (existMember.docstring.text.includes("@oagen-ignore")) continue;
-						if (existMember.docstring.text !== genMember.docstring.text) {
-							edits.push({
-								start: existMember.docstring.startIndex,
-								end: existMember.docstring.endIndex,
-								newText: genMember.docstring.text
-							});
-							docstringUpdates++;
-						}
-					} else {
-						const lineStart = existMember.declStartIndex - existMember.declColumn;
-						const indent = " ".repeat(existMember.declColumn);
+				if (existInfo.members.has(genName)) continue;
+				const bucket = unmatchedGenByFp.get(genMember.urlFingerprint) ?? [];
+				bucket.push({
+					name: genName,
+					member: genMember
+				});
+				unmatchedGenByFp.set(genMember.urlFingerprint, bucket);
+			}
+			const unmatchedExistByFp = /* @__PURE__ */ new Map();
+			for (const [existName, existMember] of existInfo.members) {
+				if (matchedExistMembers.has(existName)) continue;
+				if (!existMember.urlFingerprint) continue;
+				const bucket = unmatchedExistByFp.get(existMember.urlFingerprint) ?? [];
+				bucket.push({
+					name: existName,
+					member: existMember
+				});
+				unmatchedExistByFp.set(existMember.urlFingerprint, bucket);
+			}
+			for (const [fp, genBucket] of unmatchedGenByFp) {
+				if (genBucket.length !== 1) continue;
+				const existBucket = unmatchedExistByFp.get(fp);
+				if (!existBucket || existBucket.length !== 1) continue;
+				const genMember = genBucket[0].member;
+				const existEntry = existBucket[0];
+				const existMember = existEntry.member;
+				if (!genMember.docstring) continue;
+				if (existMember.docstring) {
+					if (existMember.docstring.text.includes("@oagen-ignore")) continue;
+					if (existMember.docstring.text !== genMember.docstring.text) {
+						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
 						edits.push({
-							start: lineStart,
-							end: lineStart,
-							newText: indent + genMember.docstring.text + "\n"
+							start: existMember.docstring.startIndex,
+							end: existMember.docstring.endIndex,
+							newText
 						});
 						docstringUpdates++;
 					}
-					matchedExistMembers.add(existName);
-					break;
+				} else {
+					const lineStart = existMember.declStartIndex - existMember.declColumn;
+					const indent = " ".repeat(existMember.declColumn);
+					edits.push({
+						start: lineStart,
+						end: lineStart,
+						newText: indent + genMember.docstring.text + "\n"
+					});
+					docstringUpdates++;
 				}
+				matchedExistMembers.add(existEntry.name);
 			}
 		}
 		if (edits.length > 0) {
@@ -3546,15 +3934,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;
 		}
@@ -3598,6 +3989,317 @@ 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 allGeneratedIds = /* @__PURE__ */ new Set();
+	for (const ids of generatedFrom.values()) for (const id of ids) allGeneratedIds.add(id);
+	const extraFromLines = [];
+	for (const [mod, existIds] of existingFrom) {
+		const genIds = generatedFrom.get(mod);
+		if (!genIds) {
+			const extra = [...existIds].filter((id) => !allGeneratedIds.has(id));
+			if (extra.length > 0) extraFromLines.push(`from ${mod} import ${extra.join(", ")}`);
+		} else {
+			const extra = [...existIds].filter((id) => !genIds.has(id) && !allGeneratedIds.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,
+			defaults: hint?.defaults ?? {},
+			inferFromClient: hint?.inferFromClient ?? []
+		});
+	}
+	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) {
@@ -3607,7 +4309,8 @@ function buildEmitterContext(spec, options) {
 		spec,
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
-		overlayLookup: options.overlayLookup
+		overlayLookup: options.overlayLookup,
+		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules)
 	};
 }
 /**
@@ -3637,6 +4340,7 @@ function collectReferencedNames(services, models) {
 		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];
@@ -3656,6 +4360,9 @@ function collectReferencedNames(services, models) {
 		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);
@@ -3672,7 +4379,6 @@ function generateAllFiles(spec, emitter, ctx) {
 		...emitter.generateResources(spec.services, ctx),
 		...emitter.generateClient(spec, ctx),
 		...emitter.generateErrors(ctx),
-		...emitter.generateConfig(ctx),
 		...emitter.generateTypeSignatures?.(reachableSpec, ctx) ?? [],
 		...emitter.generateTests(reachableSpec, ctx),
 		...emitter.generateManifest?.(spec, ctx) ?? []
@@ -3756,11 +4462,33 @@ async function treeShakeFiles(files, language) {
 		}
 		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) if (isRootFile(file.path)) {
-		reachable.add(file.path);
-		queue.push(file.path);
+	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();
@@ -3784,11 +4512,61 @@ 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(await treeShakeFiles(mapFilesForTargetIntegration(opts.files, opts.language), 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
@@ -3849,7 +4627,11 @@ 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];
+		const allTargetFiles = [
+			...targetResult.written,
+			...targetResult.merged,
+			...targetResult.identical
+		];
 		if (allTargetFiles.length > 0) await formatTargetFiles(emitter, options.target, allTargetFiles);
 	}
 	return withHeaders;
@@ -4510,7 +5292,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;
@@ -4533,7 +5318,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 {
@@ -4890,7 +5677,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);
@@ -5685,7 +6475,7 @@ function runStalenessCheck(baseline, oldSpec, newSpec, lang) {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path$1.dirname(__filename);
 function resolveScript(scriptRelPath) {
-	const distScript = path$1.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
@@ -5804,7 +6594,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;
@@ -5815,7 +6605,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,
@@ -5858,7 +6651,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}`);
@@ -6037,10 +6836,6 @@ export const ${`${toCamelCase(lang)}Emitter`}: Emitter = {
     return [];
   },
 
-  generateConfig(_ctx: EmitterContext): GeneratedFile[] {
-    return [];
-  },
-
   generateTypeSignatures(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
     return [];
   },
@@ -6135,6 +6930,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",
@@ -6170,14 +7009,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);
@@ -6200,13 +7045,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);
 });
@@ -6220,7 +7069,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) => {