@workos/oagen 0.29.2 → 0.29.4

package/dist/cli/index.mjs

@@ -2013,6 +2013,30 @@ function extractInlineModel(name, schema) {
 }
 //#endregion
 //#region src/parser/operations.ts
+/**
+* Resolve a raw parameter entry to a concrete Parameter Object, following
+* `$ref`s into `components/parameters` when present. Follows chains of refs
+* (a component that itself is a `$ref` to another component), with a cycle
+* guard for a spec that refs itself.
+*
+* Throws when a `$ref` can't be resolved so a malformed spec fails loudly at
+* parse time instead of silently losing the parameter (see `extractParams`,
+* which used to drop any entry with no `in` field — every `$ref` object has
+* none).
+*/
+function resolveParameterRef(raw, componentParameters, operationContext) {
+	const seenRefs = /* @__PURE__ */ new Set();
+	let current = raw;
+	while ("$ref" in current) {
+		if (seenRefs.has(current.$ref)) throw new Error(`Circular parameter $ref chain starting at "${current.$ref}" in ${operationContext}.`);
+		seenRefs.add(current.$ref);
+		const refName = /^#\/components\/parameters\/(.+)$/.exec(current.$ref)?.[1].replace(/~1/g, "/").replace(/~0/g, "~");
+		const resolved = refName ? componentParameters?.[refName] : void 0;
+		if (!resolved) throw new Error(`Unresolved parameter $ref "${current.$ref}" in ${operationContext}: no matching entry under components/parameters.`);
+		current = resolved;
+	}
+	return current;
+}
 const HTTP_METHODS = [
 	"get",
 	"post",
@@ -2023,7 +2047,7 @@ const HTTP_METHODS = [
 	"options",
 	"trace"
 ];
-function extractOperations(paths, operationIdTransform, componentSchemas) {
+function extractOperations(paths, operationIdTransform, componentSchemas, componentParameters) {
 	if (!paths) return {
 		services: [],
 		inlineModels: []
@@ -2036,7 +2060,7 @@ function extractOperations(paths, operationIdTransform, componentSchemas) {
 			const op = pathItem[method];
 			if (!op) continue;
 			const serviceName = inferServiceName(path, op.tags?.[0]);
-			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas);
+			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas, componentParameters);
 			inlineModels.push(...opModels);
 			const ops = serviceMap.get(serviceName) ?? [];
 			ops.push(operation);
@@ -2234,19 +2258,11 @@ function extractParameterGroups(op, allIRParams, operationContext) {
 * the request body. Emitters use the group's presence to generate sum-type
 * interfaces and custom JSON marshalling instead of flat optional fields.
 */
-function extractBodyParameterGroups(op, operationContext) {
+function extractBodyParameterGroups(op, operationContext, componentSchemas) {
 	const raw = op["x-mutually-exclusive-body-groups"];
 	if (!raw || typeof raw !== "object") return void 0;
 	const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
-	const variantFieldSchemas = /* @__PURE__ */ new Map();
-	if (bodySchema) {
-		for (const sub of bodySchema.allOf ?? []) for (const variant of sub.oneOf ?? []) if (variant.properties) {
-			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
-		}
-		for (const variant of bodySchema.oneOf ?? []) if (variant.properties) {
-			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
-		}
-	}
+	const variantFieldSchemas = collectVariantFieldSchemas(bodySchema, componentSchemas);
 	const groups = [];
 	for (const [groupName, groupDef] of Object.entries(raw)) {
 		if (!groupDef || typeof groupDef !== "object") continue;
@@ -2256,10 +2272,12 @@ function extractBodyParameterGroups(op, operationContext) {
 		const variants = Object.entries(groupDef.variants).map(([variantName, paramNames]) => {
 			if (!Array.isArray(paramNames) || paramNames.length === 0) throw new Error(`Malformed x-mutually-exclusive-body-groups.${groupName}.variants.${variantName} in ${operationContext}: expected a non-empty array of parameter names.`);
 			const parameters = paramNames.map((pName) => {
-				const fieldSchema = variantFieldSchemas.get(pName);
+				const entry = variantFieldSchemas.get(pName);
+				const fieldSchema = entry?.schema;
+				if (!fieldSchema) console.warn(`[oagen] Warning: x-mutually-exclusive-body-groups.${groupName}.variants.${variantName} references "${pName}" in ${operationContext}, but no oneOf branch of the request body declares that property. Falling back to type: string.`);
 				return {
 					name: pName,
-					type: fieldSchema ? schemaToTypeRef(fieldSchema, toPascalCase(pName)) : {
+					type: fieldSchema ? schemaToTypeRef(fieldSchema, toPascalCase(pName), entry?.owner) : {
 						kind: "primitive",
 						type: "string"
 					},
@@ -2283,8 +2301,14 @@ function extractBodyParameterGroups(op, operationContext) {
 	}
 	return groups.length > 0 ? groups : void 0;
 }
-function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas) {
-	const allParams = [...pathLevelParams, ...op.parameters ?? []];
+function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas, componentParameters) {
+	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
+	const paramsByIdentity = /* @__PURE__ */ new Map();
+	for (const raw of [...pathLevelParams, ...op.parameters ?? []]) {
+		const param = resolveParameterRef(raw, componentParameters, opLabel);
+		paramsByIdentity.set(`${param.in}:${param.name}`, param);
+	}
+	const allParams = [...paramsByIdentity.values()];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
 	const opContext = serviceName;
 	const pathParams = extractParams(allParams, "path", opContext, componentSchemas);
@@ -2308,15 +2332,13 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
 	const security = extractOperationSecurity(op.security);
-	const allIRParams = [
+	const queryParamGroups = extractParameterGroups(op, [
 		...pathParams,
 		...queryParams,
 		...headerParams,
 		...cookieParams
-	];
-	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
-	const queryParamGroups = extractParameterGroups(op, allIRParams, opLabel);
-	const bodyParamGroups = extractBodyParameterGroups(op, opLabel);
+	], opLabel);
+	const bodyParamGroups = extractBodyParameterGroups(op, opLabel, componentSchemas);
 	const parameterGroups = queryParamGroups || bodyParamGroups ? [...queryParamGroups ?? [], ...bodyParamGroups ?? []] : void 0;
 	return {
 		operation: {
@@ -2399,6 +2421,55 @@ function resolveParamSchemaRef(schema, componentSchemas) {
 	if (!match) return void 0;
 	return componentSchemas[match[1]];
 }
+/**
+* Collect the property schemas of every `oneOf` branch reachable from a request
+* body schema, keyed by property name. These are the candidate members of a
+* mutually-exclusive body group.
+*
+* The bundler runs with `dereference: false`, so the body schema is very often
+* a bare `{ $ref: '#/components/schemas/XDto' }` and the `allOf`/`oneOf`
+* composition that actually declares the variant properties lives on the
+* component. Walking without resolving refs finds nothing, and every group
+* member then falls back to `string` — an SDK that compiles but types
+* object-valued members (e.g. a connection's `saml_options`) as plain strings.
+*
+* Composition keywords nest and may themselves be refs, so resolve and recurse
+* at each level. `seen` guards against a schema that (directly or transitively)
+* refs itself.
+*/
+function collectVariantFieldSchemas(schema, componentSchemas, owner = void 0, out = /* @__PURE__ */ new Map(), seen = /* @__PURE__ */ new Set()) {
+	if (!schema) return out;
+	const ref = schema.$ref;
+	if (ref) {
+		if (seen.has(ref)) return out;
+		seen.add(ref);
+		const match = /^#\/components\/schemas\/(.+)$/.exec(ref);
+		return collectVariantFieldSchemas(match && componentSchemas ? componentSchemas[match[1]] : void 0, componentSchemas, match ? resolveSchemaName(match[1]) : owner, out, seen);
+	}
+	for (const variant of schema.oneOf ?? []) {
+		const variantRef = variant.$ref;
+		const refMatch = variantRef ? /^#\/components\/schemas\/(.+)$/.exec(variantRef) : null;
+		const resolved = resolveSchemaRefObject(variant, componentSchemas) ?? variant;
+		const variantOwner = refMatch ? resolveSchemaName(refMatch[1]) : owner;
+		for (const [name, fieldSchema] of Object.entries(resolved.properties ?? {})) if (fieldSchema) out.set(name, {
+			schema: fieldSchema,
+			owner: variantOwner
+		});
+		collectVariantFieldSchemas(variant, componentSchemas, owner, out, seen);
+	}
+	for (const sub of schema.allOf ?? []) collectVariantFieldSchemas(sub, componentSchemas, owner, out, seen);
+	for (const sub of schema.anyOf ?? []) collectVariantFieldSchemas(sub, componentSchemas, owner, out, seen);
+	return out;
+}
+/** Resolve `{ $ref: '#/components/schemas/X' }` to its component, else undefined. */
+function resolveSchemaRefObject(schema, componentSchemas) {
+	if (!schema || !componentSchemas) return void 0;
+	const ref = schema.$ref;
+	if (!ref) return void 0;
+	const match = /^#\/components\/schemas\/(.+)$/.exec(ref);
+	if (!match) return void 0;
+	return componentSchemas[match[1]];
+}
 function extractRequestBody(body, op, inlineModels) {
 	if (!body?.content) return {};
 	let encoding = "json";
@@ -2811,6 +2882,262 @@ function collectInlineEnumsFromOperations(services, enums) {
 	]) collectInlineEnumFromRef(param.type, enums, enumNames);
 }
 //#endregion
+//#region src/parser/parameter-group-names.ts
+/**
+* Assign `ParameterGroup.wrapperName` across the whole spec.
+*
+* Emitters derive a group's generated wrapper type name from the group name
+* alone, so two operations sharing a group name (create and update both
+* declare `protocol_options`) collapse onto a single type. That is only sound
+* while the two declarations carry the same members. Where they differ, one
+* operation ends up typed with the other's member — e.g. a connection update
+* forced to pass `CreateConnectionSAMLOptions`, which accepts three fields the
+* PATCH endpoint rejects.
+*
+* This pass fingerprints every group's members structurally and qualifies the
+* wrapper name with the operation name only for groups that genuinely diverge.
+* Groups whose declarations agree keep the bare group name, so wrapper types
+* already published in the SDKs are never renamed.
+*/
+function assignParameterGroupWrapperNames(spec) {
+	const modelMap = new Map(spec.models.map((m) => [m.name, m]));
+	const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
+	const fingerprints = /* @__PURE__ */ new Map();
+	const occurrences = [];
+	for (const service of spec.services) for (const op of service.operations) for (const group of op.parameterGroups ?? []) {
+		const fp = fingerprintGroup(group, modelMap, enumMap);
+		let seen = fingerprints.get(group.name);
+		if (!seen) {
+			seen = /* @__PURE__ */ new Set();
+			fingerprints.set(group.name, seen);
+		}
+		seen.add(fp);
+		occurrences.push({
+			service,
+			op,
+			group,
+			fingerprint: fp
+		});
+	}
+	for (const { op, group } of occurrences) group.wrapperName = (fingerprints.get(group.name)?.size ?? 0) > 1 ? `${op.name}_${group.name}` : group.name;
+	qualifyResidualCollisions(occurrences);
+	reconcileSharedGroups(occurrences.map((o) => o.group));
+}
+/**
+* Break the collisions the operation-qualified name can still leave behind.
+*
+* `${op.name}_${group.name}` is not a unique key, for two separate reasons:
+*
+*  - `disambiguateOperationNames` makes operation names unique only *within* a
+*    service, so two services that each own an operation named `create`, both
+*    declaring a `password` group with different members, both land on
+*    `create_password`.
+*  - Within one service it deliberately leaves same-name operations alone when
+*    they share a path (see the `uniquePaths.size <= 1` guard — "same path,
+*    different methods"), so `PUT` and `PATCH` on one path both stay `update`
+*    and a service prefix alone still produces one name for both.
+*
+* Either way `reconcileSharedGroups` would then fuse two incompatible
+* declarations into a single type — the exact failure this pass exists to
+* prevent — and it does not drop the surplus member, so the wrapper would
+* expose a field one of the operations rejects.
+*
+* So escalate in rounds, adding a qualifier at a time and re-testing what still
+* collides. `(service, path, method)` identifies an operation uniquely, and a
+* same-name collision within a service implies a shared path, so service then
+* method is sufficient to separate every case.
+*
+* Each round only touches names that *still* group differing fingerprints, so a
+* name whose sharers agree is never renamed: sharing one wrapper is exactly what
+* should happen there, and renaming it would move a type the SDKs already
+* publish. On a spec where no qualified name collides — the WorkOS spec today —
+* the whole pass is a no-op.
+*/
+function qualifyResidualCollisions(occurrences) {
+	const qualifiers = [(o) => o.service.name, (o) => o.op.httpMethod];
+	for (const qualify of qualifiers) for (const sharers of collidingCandidates(occurrences)) {
+		const movable = sharers.filter((o) => o.group.wrapperName !== o.group.name);
+		for (const o of movable) o.group.wrapperName = `${qualify(o)}_${o.group.wrapperName ?? o.group.name}`;
+	}
+	separateRemainingByStructure(occurrences);
+}
+/**
+* Terminal round: separate whatever the operation attributes could not.
+*
+* No combination of operation attributes is unique by construction. Two
+* operations in one service can share a name, a method *and* differ only by
+* path — `normalizeOperationIdForNaming` strips the `[N]` suffix, so a NestJS
+* controller method bound to several routes derives one name for all of them.
+* The WorkOS spec already contains such a pair (`Authorization`'s
+* `listRoleAssignments` on two paths); it declares no parameter groups today,
+* so nothing is wrong in the SDKs, but the shape is present rather than
+* hypothetical. Adding `path` as a fourth qualifier would only move the
+* boundary again.
+*
+* So stop enumerating attributes and separate by the thing that actually
+* matters: a name still fusing distinct structures gets one wrapper per
+* distinct fingerprint. That makes "same `wrapperName` implies same structure"
+* hold unconditionally, which is the invariant every emitter relies on.
+*
+* Suffixes are keyed on the fingerprint, not on a per-occurrence counter, so
+* declarations that agree keep sharing a wrapper.
+*
+* Ordering is by first appearance, not by sorted fingerprint: the structure
+* declared first keeps the unsuffixed name. Sorting by fingerprint would be
+* equally deterministic but less stable in the way that matters — adding a
+* member to one operation changes its fingerprint and could swap which of two
+* published wrappers holds the bare name. Under first-appearance order only
+* reordering the operations themselves can shift a name, which is both rarer
+* and visible in the spec diff.
+*
+* Either way this is a no-op wherever an earlier round already sufficed —
+* including the WorkOS spec, which never reaches this round at all.
+*/
+function separateRemainingByStructure(occurrences) {
+	const taken = new Set(occurrences.map((o) => o.group.wrapperName ?? o.group.name));
+	for (const sharers of collidingCandidates(occurrences)) {
+		const base = sharers[0].group.wrapperName ?? sharers[0].group.name;
+		const nameFor = /* @__PURE__ */ new Map();
+		let n = 2;
+		for (const o of sharers) {
+			if (nameFor.has(o.fingerprint)) continue;
+			if (nameFor.size === 0) {
+				nameFor.set(o.fingerprint, base);
+				continue;
+			}
+			while (taken.has(`${base}_${n}`)) n++;
+			const name = `${base}_${n}`;
+			taken.add(name);
+			nameFor.set(o.fingerprint, name);
+			n++;
+		}
+		for (const o of sharers) o.group.wrapperName = nameFor.get(o.fingerprint);
+	}
+}
+/**
+* Candidate wrapper names shared by declarations that do not agree — the only
+* ones an escalation round may rename.
+*/
+function collidingCandidates(occurrences) {
+	const byCandidate = /* @__PURE__ */ new Map();
+	for (const o of occurrences) {
+		const key = o.group.wrapperName ?? o.group.name;
+		const list = byCandidate.get(key);
+		if (list) list.push(o);
+		else byCandidate.set(key, [o]);
+	}
+	return [...byCandidate.values()].filter((sharers) => sharers.length > 1 && new Set(sharers.map((o) => o.fingerprint)).size > 1);
+}
+/**
+* Make every group that shares a `wrapperName` describe literally the same
+* type.
+*
+* Deciding two declarations may share one wrapper is only half the job. The
+* fingerprint deliberately ignores nullability and member order, so sharers can
+* still disagree on both — and each emitter renders the wrapper from whichever
+* operation it happens to reach first while rendering call sites from their own
+* operation. Kotlin showed the consequence: `ParentResource.ById.id` emitted as
+* `String` from one operation, while the Java-friendly overload built from
+* another passed a `String?` into it, and the SDK stopped compiling.
+*
+* So normalize the two axes the fingerprint waived:
+*   - a member the sharers disagree on settles as non-nullable. Widening to
+*     nullable instead reads as the friendlier choice, but the nullable form
+*     doesn't survive every emitter's group paths (Kotlin's query dispatch
+*     builds a `Pair<String, String>` from the member, which a `String?` can't
+*     satisfy), and non-nullable is what all sharers carried before group
+*     member types were resolved at all — so it changes no published surface.
+*     A member every sharer agrees is nullable stays nullable.
+*
+*     The cost: an operation whose spec really does accept null for a member
+*     (`PATCH` on a resource may clear `parent_resource_id`) can't express that
+*     through the shared wrapper. It never could — the member used to be a flat
+*     `string` everywhere — so nothing regresses, but the limitation is real and
+*     removing it means letting that group's wrapper split per operation.
+*   - member order follows the first sharer, so positional constructors and
+*     their call sites agree.
+*/
+function reconcileSharedGroups(groups) {
+	const byWrapper = /* @__PURE__ */ new Map();
+	for (const group of groups) {
+		const key = group.wrapperName ?? group.name;
+		const list = byWrapper.get(key);
+		if (list) list.push(group);
+		else byWrapper.set(key, [group]);
+	}
+	for (const sharers of byWrapper.values()) {
+		if (sharers.length < 2) continue;
+		for (const variant of sharers[0].variants) {
+			const peers = sharers.slice(1).map((g) => g.variants.find((v) => v.name === variant.name)).filter((v) => v !== void 0);
+			if (peers.length === 0) continue;
+			for (const member of variant.parameters) {
+				const all = [member, ...peers.map((p) => p.parameters.find((q) => q.name === member.name)).filter(isParameter)];
+				if (all.every((p) => p.type.kind === "nullable")) continue;
+				for (const p of all) if (p.type.kind === "nullable") p.type = p.type.inner;
+			}
+			const canonical = variant.parameters.map((p) => p.name);
+			for (const peer of peers) peer.parameters.sort((a, b) => {
+				const ia = canonical.indexOf(a.name);
+				const ib = canonical.indexOf(b.name);
+				if (ia === -1 && ib === -1) return 0;
+				if (ia === -1) return 1;
+				if (ib === -1) return -1;
+				return ia - ib;
+			});
+		}
+	}
+}
+function isParameter(p) {
+	return p !== void 0;
+}
+/**
+* Structural fingerprint of a group: its variants, their members, and each
+* member's resolved shape. Two declarations with the same fingerprint can
+* safely share one generated wrapper type.
+*/
+function fingerprintGroup(group, modelMap, enumMap) {
+	return group.variants.map((v) => {
+		const members = [...v.parameters].sort((a, b) => a.name.localeCompare(b.name)).map((p) => `${p.name}:${fingerprintType(p.type, modelMap, enumMap, /* @__PURE__ */ new Set())}`);
+		const optional = [...v.optionalParameters ?? []].sort();
+		return `${v.name}(${members.join(",")})[${optional.join(",")}]`;
+	}).join("|");
+}
+/**
+* Fingerprint a type by shape rather than by name.
+*
+* Names cannot be compared directly because the parser synthesizes a separate
+* name per declaration site for inline schemas: `create_user` and `update_user`
+* each get their own `PasswordHashType` enum, spelled `CreateUserPasswordHashType`
+* and `UpdateUserPasswordHashType`, though their values are identical. Comparing
+* names would report divergence and rename a wrapper for no reason.
+*
+* Nullability is also stripped: an update declaring a member nullable while
+* create declares it plain is not a reason to split the wrapper type.
+*/
+function fingerprintType(ref, modelMap, enumMap, visiting) {
+	switch (ref.kind) {
+		case "nullable": return fingerprintType(ref.inner, modelMap, enumMap, visiting);
+		case "primitive": return `p:${ref.type}`;
+		case "literal": return `l:${typeof ref.value}:${String(ref.value)}`;
+		case "array": return `a<${fingerprintType(ref.items, modelMap, enumMap, visiting)}>`;
+		case "map": return `m<${fingerprintType(ref.valueType, modelMap, enumMap, visiting)}>`;
+		case "union": return `u<${ref.variants.map((v) => fingerprintType(v, modelMap, enumMap, visiting)).sort().join(",")}>`;
+		case "enum": {
+			const e = enumMap.get(ref.name);
+			if (!e) return `e:${ref.name}`;
+			return `e<${e.values.map((v) => `${typeof v.value}:${String(v.value)}`).sort().join(",")}>`;
+		}
+		case "model": {
+			const m = modelMap.get(ref.name);
+			if (!m) return `M:${ref.name}`;
+			if (visiting.has(ref.name)) return `M:${ref.name}`;
+			const next = new Set(visiting).add(ref.name);
+			return `M<${[...m.fields].sort((a, b) => a.name.localeCompare(b.name)).map((f) => `${f.name}${f.required ? "!" : "?"}:${fingerprintType(f.type, modelMap, enumMap, next)}`).join(",")}>`;
+		}
+		default: return "unknown";
+	}
+}
+//#endregion
 //#region src/parser/normalize-model-refs.ts
 function validateModelRefs(spec) {
 	const knownNames = /* @__PURE__ */ new Set();
@@ -2840,7 +3167,7 @@ async function parseSpec(specPath, options) {
 	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, { schemaNameTransform: options?.schemaNameTransform });
-	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform, spec.components?.schemas);
+	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform, spec.components?.schemas, spec.components?.parameters);
 	const responseNormalizedModels = mergeInlineResponseModels(models, inlineModels);
 	const fieldInlineModels = extractInlineModelsFromSchemas(spec.components?.schemas);
 	clearSchemaNameTransform();
@@ -2865,6 +3192,7 @@ async function parseSpec(specPath, options) {
 		auth,
 		sdk: defaultSdkBehavior()
 	};
+	assignParameterGroupWrapperNames(result);
 	validateModelRefs(result);
 	return result;
 }
@@ -3447,6 +3775,7 @@ function extractKotlinClassMembers(classBody, source) {
 	const children = classBody.namedChildren;
 	for (let i = 0; i < children.length; i++) {
 		const child = children[i];
+		const declIndex = i;
 		let memberName = null;
 		if (child.type === "property_declaration") memberName = child.children.find((c) => c.type === "variable_declaration")?.children.find((c) => c.type === "simple_identifier")?.text ?? null;
 		else if (child.type === "function_declaration") memberName = child.children.find((c) => c.type === "simple_identifier")?.text ?? null;
@@ -3461,7 +3790,7 @@ function extractKotlinClassMembers(classBody, source) {
 			} else break;
 		}
 		let startIdx = child.startIndex;
-		for (let k = i - 1; k >= 0; k--) {
+		for (let k = declIndex - 1; k >= 0; k--) {
 			const prev = children[k];
 			if (prev.type === "multiline_comment") {
 				if (source.slice(prev.startIndex, prev.endIndex).startsWith("/**")) startIdx = prev.startIndex;
@@ -3530,6 +3859,13 @@ const kotlinMergeAdapter = {
 	isManagedMember(member) {
 		return KOTLIN_MANAGED_ACCESSOR_DOC.test(member.text);
 	},
+	importedNames(imp) {
+		const path = imp.text.replace(/^import\s+/, "").trim();
+		const alias = path.match(/\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/);
+		if (alias) return [alias[1]];
+		const last = path.split(".").pop();
+		return last && last !== "*" ? [last] : [];
+	},
 	shouldSkipDeepMerge(_symbolName, existingMemberKeys, newMembers) {
 		const newText = newMembers.map((m) => m.text).join("\n");
 		for (const match of newText.matchAll(/this\.(\w+)/g)) {
@@ -4412,6 +4748,116 @@ function declarationLineStart(content, declStartIndex) {
 	return prevNewline === -1 ? 0 : prevNewline + 1;
 }
 /**
+* Widen a member's byte range so deleting it removes whole lines.
+*
+* The raw range starts at the declaration (or its docstring), which sits after
+* the member's indentation — splicing it out verbatim leaves that indentation
+* glued to the following line. Extends backwards over the indentation and
+* forwards over the trailing newline, then absorbs the blank line the removal
+* would otherwise duplicate (or strand in front of the block's closing brace).
+*/
+function expandPruneRange(source, rawStart, rawEnd) {
+	let start = rawStart;
+	while (start > 0 && (source[start - 1] === " " || source[start - 1] === "	")) start--;
+	let end = rawEnd;
+	while (end < source.length && (source[end] === " " || source[end] === "	")) end++;
+	end = skipLineBreak(source, end);
+	if (precededByBlankLine(source, start)) {
+		if (startsWithLineBreak(source, end)) end = skipLineBreak(source, end);
+		else if (/^[ \t]*\}/.test(source.slice(end, end + 40))) start = backOverLineBreak(source, start);
+	}
+	return {
+		start,
+		end
+	};
+}
+function startsWithLineBreak(source, idx) {
+	return source[idx] === "\n" || source[idx] === "\r" && source[idx + 1] === "\n";
+}
+function skipLineBreak(source, idx) {
+	let i = idx;
+	if (source[i] === "\r") i++;
+	return source[i] === "\n" ? i + 1 : i;
+}
+function backOverLineBreak(source, idx) {
+	let i = idx;
+	if (source[i - 1] === "\n") i--;
+	if (source[i - 1] === "\r") i--;
+	return i;
+}
+/** Whether the line ending immediately before `idx` (a line start) is empty. */
+function precededByBlankLine(source, idx) {
+	if (idx === 0 || source[idx - 1] !== "\n") return false;
+	const priorLineEnd = backOverLineBreak(source, idx);
+	return priorLineEnd > 0 && source[priorLineEnd - 1] === "\n";
+}
+function referencesIdentifier(source, name) {
+	return new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(source);
+}
+/**
+* Blank out comments and string text, preserving offsets and line structure.
+*
+* An identifier lookup over raw source can't tell a live reference from a name
+* that merely survives in prose. That distinction decides whether an import
+* stays: keeping one whose only remaining mention is a KDoc leaves an import of
+* a class the generator no longer emits, which doesn't compile — the very
+* failure the prune exists to prevent.
+*
+* Interpolated expressions are the exception: `"${Agents.NAME}"` is code that
+* sits inside a string literal, and masking it would drop an import the file
+* genuinely uses. String extents are masked around those holes, not over them.
+*
+* Grammar node names come from the adapter's `urlFingerprintConfig`, which
+* already inventories exactly these three categories per language. Comments are
+* matched structurally instead — every grammar we support names them `*comment`.
+*/
+function maskNonCode(tree, source, config) {
+	const stringNodeTypes = new Set(config?.stringNodeTypes ?? []);
+	const interpolationNodeTypes = new Set(config?.interpolationNodeTypes ?? []);
+	const spans = [];
+	const collectStringSpans = (node) => {
+		const holes = [];
+		const findHoles = (n) => {
+			if (interpolationNodeTypes.has(n.type)) {
+				holes.push([n.startIndex, n.endIndex]);
+				return;
+			}
+			for (const child of n.children) findHoles(child);
+		};
+		findHoles(node);
+		let cursor = node.startIndex;
+		for (const [holeStart, holeEnd] of holes) {
+			if (holeStart > cursor) spans.push([cursor, holeStart]);
+			cursor = holeEnd;
+		}
+		if (cursor < node.endIndex) spans.push([cursor, node.endIndex]);
+	};
+	const walk = (node) => {
+		if (node.type.includes("comment")) {
+			spans.push([node.startIndex, node.endIndex]);
+			return;
+		}
+		if (stringNodeTypes.has(node.type)) {
+			collectStringSpans(node);
+			return;
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(tree.rootNode);
+	if (spans.length === 0) return source;
+	let masked = "";
+	let cursor = 0;
+	for (const [spanStart, spanEnd] of spans) {
+		if (spanStart < cursor) continue;
+		masked += source.slice(cursor, spanStart) + source.slice(spanStart, spanEnd).replace(/[^\r\n]/g, " ");
+		cursor = spanEnd;
+	}
+	return masked + source.slice(cursor);
+}
+function removeLines(source, lines) {
+	return source.split("\n").filter((line) => !lines.has(line.trim())).join("\n");
+}
+/**
 * Resolve a docstring range by searching for the nearest matching text before
 * the declaration start. Falls back to parser-provided offsets when search fails.
 */
@@ -4626,6 +5072,7 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 	let deepAdded = 0;
 	let deepPruned = 0;
 	const insertions = [];
+	const prunedTexts = [];
 	if (adapter.extractMembers) {
 		const parser = await getParser(language);
 		const resultTree = safeParse(parser, result);
@@ -4654,10 +5101,9 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			if (pruneEdits.length > 0) {
 				pruneEdits.sort((a, b) => b.start - a.start);
 				for (const edit of pruneEdits) {
-					let end = edit.end;
-					while (end < result.length && (result[end] === " " || result[end] === "	")) end++;
-					if (result[end] === "\n") end++;
-					result = result.slice(0, edit.start) + result.slice(end);
+					const { start, end } = expandPruneRange(result, edit.start, edit.end);
+					prunedTexts.push(result.slice(start, end));
+					result = result.slice(0, start) + result.slice(end);
 				}
 				deepPruned = pruneEdits.length;
 				const reTree = safeParse(parser, result);
@@ -4722,6 +5168,21 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			result = lines.join("\n");
 		}
 	}
+	if (prunedTexts.length > 0 && adapter.importedNames) {
+		const prunedText = prunedTexts.join("\n");
+		const codeOnly = maskNonCode(safeParse(await getParser(language), result), result, adapter.urlFingerprintConfig);
+		const orphaned = /* @__PURE__ */ new Set();
+		for (const imp of existingStatements.imports) {
+			const names = adapter.importedNames(imp);
+			if (names.length === 0) continue;
+			if (!names.some((n) => referencesIdentifier(prunedText, n))) continue;
+			const line = imp.text.trim();
+			const withoutImport = removeLines(codeOnly, new Set([line]));
+			if (names.some((n) => referencesIdentifier(withoutImport, n))) continue;
+			orphaned.add(line);
+		}
+		if (orphaned.size > 0) result = removeLines(result, orphaned);
+	}
 	let docstringUpdates = 0;
 	{
 		const parser = await getParser(language);