@workos/oagen 0.1.1 → 0.2.0

package/dist/differ-BwelBJN0.mjs

@@ -0,0 +1,1100 @@
+import { A as walkTypeRef, f as toSnakeCase, o as splitWords, x as RegistryError } from "./tree-sitter-BPNfbEzY.mjs";
+//#region src/compat/extractor-registry.ts
+const extractors = /* @__PURE__ */ new Map();
+function registerExtractor(extractor) {
+	extractors.set(extractor.language, extractor);
+}
+function getExtractor(language) {
+	const extractor = extractors.get(language);
+	if (!extractor) throw new RegistryError(`No extractor registered for language: ${language}. Available: ${[...extractors.keys()].join(", ") || "(none)"}`, `Register an extractor for "${language}" via registerExtractor() or add one in your oagen.config.ts plugin.`);
+	return extractor;
+}
+//#endregion
+//#region src/compat/language-hints.ts
+/** Untyped map patterns — hoisted to avoid allocation on every isTypeEquivalent call. */
+const UNTYPED_MAP_PATTERNS = new Set([
+	"Record<string, unknown>",
+	"Record<string, any>",
+	"{ [key: string]: any; }",
+	"{ [key: string]: unknown; }",
+	"any"
+]);
+const NAMED_TYPE_RE = /^[A-Z][a-zA-Z0-9]*$/;
+/** Check whether a type name exists as an interface, class, or enum in a surface. */
+function typeExistsInSurface(name, surface) {
+	return !!(surface.interfaces[name] || surface.classes[name] || surface.enums[name]);
+}
+/** Split a PascalCase string into words, keeping only words > 2 chars. */
+function splitPascalWords(s) {
+	return splitWords(s).filter((w) => w.length > 2);
+}
+/**
+* Check whether two named types share enough PascalCase word components to
+* be considered equivalent (handles name reordering from Json merges, etc.).
+* Both names have `Response$` stripped before comparison.
+*/
+function namedTypeWordsOverlap(a, b, minOverlap = 1) {
+	const aNoResp = a.replace(/Response$/, "");
+	const bNoResp = b.replace(/Response$/, "");
+	const aWords = new Set(splitPascalWords(aNoResp).map((w) => w.toLowerCase()));
+	const bWords = new Set(splitPascalWords(bNoResp).map((w) => w.toLowerCase()));
+	const overlap = [...aWords].filter((w) => bWords.has(w));
+	return overlap.length >= minOverlap && overlap.length >= Math.min(aWords.size, bWords.size) - 1;
+}
+/** Split a pipe-delimited union string into trimmed, non-empty members. */
+function parseUnionMembers(s) {
+	return s.split("|").map((p) => p.trim()).filter(Boolean);
+}
+/**
+* Default implementation of isNullableOnlyDifference — shared across extractors.
+* Returns true when stripping nullable wrappers from both sides yields the same
+* type, but the original types differ (i.e., the only difference is nullability).
+*/
+function defaultIsNullableOnlyDifference(hints, a, b) {
+	return (hints.stripNullable(a) ?? a) === (hints.stripNullable(b) ?? b) && a !== b;
+}
+/**
+* Node/TypeScript language hints — reference implementation.
+* Extracted from the hardcoded logic previously in differ.ts and overlay.ts.
+*/
+const nodeHints = {
+	stripNullable(type) {
+		const members = parseUnionMembers(type);
+		const stripped = members.filter((p) => p !== "null");
+		if (stripped.length === members.length) return null;
+		return stripped.join(" | ");
+	},
+	isNullableOnlyDifference(a, b) {
+		return (nodeHints.stripNullable(a) ?? a) === (nodeHints.stripNullable(b) ?? b) && a !== b;
+	},
+	isUnionReorder(a, b) {
+		const membersA = parseUnionMembers(a).sort();
+		const membersB = parseUnionMembers(b).sort();
+		if (membersA.length !== membersB.length || membersA.length < 2) return false;
+		return membersA.every((m, i) => m === membersB[i]);
+	},
+	isGenericTypeParam(type) {
+		if (/^[A-Z]$/.test(type)) return true;
+		if (/^T[A-Z][a-zA-Z]*$/.test(type)) return true;
+		if (/^[A-Z]\[\]$/.test(type) || /^T[A-Z][a-zA-Z]*\[\]$/.test(type)) return true;
+		return false;
+	},
+	isExtractionArtifact(type) {
+		return type === "any" || type === "Record<string, unknown>";
+	},
+	tolerateCategoryMismatch: true,
+	extractReturnTypeName(returnType) {
+		let inner = returnType;
+		while (inner.startsWith("Promise<") && inner.endsWith(">")) inner = inner.slice(8, -1);
+		const genericMatch = inner.match(/^[A-Za-z]+<(.+)>$/);
+		if (genericMatch) inner = genericMatch[1];
+		inner = inner.replace(/\[\]$/, "");
+		if ([
+			"void",
+			"string",
+			"number",
+			"boolean",
+			"any",
+			"unknown",
+			"null",
+			"undefined"
+		].includes(inner)) return null;
+		return inner;
+	},
+	extractParamTypeName(paramType) {
+		if ([
+			"string",
+			"number",
+			"boolean",
+			"any",
+			"unknown"
+		].includes(paramType)) return null;
+		return paramType;
+	},
+	propertyMatchesClass(propertyName, className) {
+		return propertyName.replace(/[-_]/g, "").toLowerCase() === className.toLowerCase();
+	},
+	derivedModelNames(modelName) {
+		return [`${modelName}Response`, `Serialized${modelName}`];
+	},
+	isTypeEquivalent(baselineType, candidateType, candidateSurface) {
+		const candEnum = candidateSurface.enums[candidateType];
+		if (candEnum) {
+			const enumValuesSet = new Set(Object.values(candEnum.members).flatMap((v) => [`"${v}"`, `'${v}'`]));
+			const baseMembers = parseUnionMembers(baselineType);
+			if (baseMembers.length > 0 && baseMembers.every((m) => enumValuesSet.has(m))) return true;
+		}
+		if (UNTYPED_MAP_PATTERNS.has(baselineType) && UNTYPED_MAP_PATTERNS.has(candidateType)) return true;
+		if (baselineType.startsWith("{") && baselineType.endsWith("}")) {
+			if (typeExistsInSurface(candidateType, candidateSurface)) return true;
+		}
+		const baseClean = baselineType.replace(/\[\]$/, "");
+		const candClean = candidateType.replace(/\[\]$/, "");
+		const sameArrayness = baselineType.endsWith("[]") === candidateType.endsWith("[]");
+		if (sameArrayness) {
+			if (candClean === baseClean + "Response" || baseClean === candClean + "Response") return true;
+		}
+		if (sameArrayness && NAMED_TYPE_RE.test(baseClean) && NAMED_TYPE_RE.test(candClean)) {
+			if (typeExistsInSurface(candClean, candidateSurface)) {
+				if (candClean.includes(baseClean) || baseClean.includes(candClean)) return true;
+				const baseNoResp = baseClean.replace(/Response$/, "");
+				const candNoResp = candClean.replace(/Response$/, "");
+				if (candNoResp.includes(baseNoResp) || baseNoResp.includes(candNoResp)) return true;
+				if (namedTypeWordsOverlap(baseClean, candClean, 2)) return true;
+			}
+		}
+		return false;
+	}
+};
+/**
+* Merge partial language hint overrides over nodeHints defaults.
+* Any hint not provided falls back to the Node/TypeScript implementation.
+*/
+function resolveHints(overrides) {
+	return {
+		...nodeHints,
+		...overrides
+	};
+}
+//#endregion
+//#region src/compat/overlay.ts
+/**
+* Find the class name that owns a given SDK resource property.
+* E.g. if the surface has a class "Organizations" with property "organizations",
+* and sdkResourceProperty is "organizations", return "Organizations".
+*/
+function findClassForProperty(surface, sdkResourceProperty, hints) {
+	for (const [className, cls] of Object.entries(surface.classes)) {
+		if (hints.propertyMatchesClass(sdkResourceProperty, className)) return className;
+		for (const [propName, prop] of Object.entries(cls.properties)) if (propName === sdkResourceProperty) {
+			const propType = prop.type;
+			if (propType && surface.classes[propType]) return propType;
+			return;
+		}
+	}
+	const propWords = splitWords(sdkResourceProperty).map((w) => w.toLowerCase());
+	if (propWords.length > 1) for (const [className] of Object.entries(surface.classes)) {
+		const classWords = splitWords(className).map((w) => w.toLowerCase());
+		if (classWords.length > 0 && classWords.length < propWords.length) {
+			const suffix = propWords.slice(propWords.length - classWords.length);
+			if (classWords.every((w, i) => w === suffix[i])) return className;
+		}
+	}
+}
+function buildOverlayLookup(surface, manifest, spec, hints, options) {
+	const resolvedHints = hints ?? nodeHints;
+	const lookup = {
+		methodByOperation: /* @__PURE__ */ new Map(),
+		httpKeyByMethod: /* @__PURE__ */ new Map(),
+		interfaceByName: /* @__PURE__ */ new Map(),
+		typeAliasByName: /* @__PURE__ */ new Map(),
+		requiredExports: /* @__PURE__ */ new Map(),
+		modelNameByIR: /* @__PURE__ */ new Map(),
+		fileBySymbol: /* @__PURE__ */ new Map()
+	};
+	if (manifest) for (const entry of manifest) {
+		const key = `${entry.httpMethod.toUpperCase()} ${entry.path}`;
+		const className = findClassForProperty(surface, entry.sdkResourceProperty, resolvedHints);
+		if (className) {
+			let resolvedMethodName = entry.sdkMethodName;
+			let methods = surface.classes[className]?.methods[resolvedMethodName];
+			if (!methods) {
+				const classMethods = surface.classes[className]?.methods ?? {};
+				const prefix = resolvedMethodName.toLowerCase();
+				const candidates = [];
+				for (const [name, overloads] of Object.entries(classMethods)) if (name.toLowerCase().startsWith(prefix) && name !== resolvedMethodName) candidates.push([name, overloads]);
+				if (candidates.length === 1) {
+					methods = candidates[0][1];
+					resolvedMethodName = candidates[0][0];
+				} else if (candidates.length > 1) {
+					const firstSegment = entry.path.split("/").filter(Boolean)[0]?.replace(/[{}_-]/g, "") ?? "";
+					if (firstSegment) {
+						const segLower = firstSegment.toLowerCase();
+						const segSingular = segLower.endsWith("s") ? segLower.slice(0, -1) : segLower;
+						const best = candidates.find(([name]) => {
+							const lower = name.toLowerCase();
+							return lower === prefix + segLower || lower === prefix + segSingular;
+						});
+						if (best) {
+							methods = best[1];
+							resolvedMethodName = best[0];
+						}
+					}
+					if (!methods) {
+						const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
+						if (verbMatch) {
+							methods = verbMatch[1];
+							resolvedMethodName = verbMatch[0];
+						}
+					}
+				}
+			}
+			if (!methods) {
+				const classMethods = surface.classes[className]?.methods ?? {};
+				const suffix = resolvedMethodName.toLowerCase();
+				const candidates = [];
+				for (const [name, overloads] of Object.entries(classMethods)) if (name.toLowerCase().endsWith(suffix) && name !== resolvedMethodName) candidates.push([name, overloads]);
+				if (candidates.length === 1) {
+					methods = candidates[0][1];
+					resolvedMethodName = candidates[0][0];
+				}
+			}
+			if (!methods) {
+				const manifestWords = splitCamelCase(resolvedMethodName);
+				if (manifestWords.length >= 2) {
+					const classMethods = surface.classes[className]?.methods ?? {};
+					const candidates = [];
+					for (const [name, overloads] of Object.entries(classMethods)) {
+						if (name === resolvedMethodName) continue;
+						const surfaceWords = splitCamelCase(name);
+						if (surfaceWords.length > manifestWords.length && isSubsequence(manifestWords, surfaceWords)) candidates.push([name, overloads]);
+					}
+					if (candidates.length === 1) {
+						methods = candidates[0][1];
+						resolvedMethodName = candidates[0][0];
+					} else if (candidates.length > 1) {
+						const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
+						if (verbMatch) {
+							methods = verbMatch[1];
+							resolvedMethodName = verbMatch[0];
+						}
+					}
+				}
+			}
+			if (!methods) {
+				const classMethods = surface.classes[className]?.methods ?? {};
+				const manifestLower = resolvedMethodName.toLowerCase();
+				const candidates = [];
+				for (const [name, overloads] of Object.entries(classMethods)) {
+					if (name === resolvedMethodName) continue;
+					if (manifestLower.startsWith(name.toLowerCase()) && name.length >= 3) candidates.push([name, overloads]);
+				}
+				if (candidates.length === 1) {
+					methods = candidates[0][1];
+					resolvedMethodName = candidates[0][0];
+				} else if (candidates.length > 1) {
+					const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
+					if (verbMatch) {
+						methods = verbMatch[1];
+						resolvedMethodName = verbMatch[0];
+					}
+				}
+			}
+			const method = methods?.[0];
+			if (method) {
+				lookup.methodByOperation.set(key, {
+					className,
+					methodName: resolvedMethodName,
+					params: method.params,
+					returnType: method.returnType
+				});
+				lookup.httpKeyByMethod.set(`${className}.${resolvedMethodName}`, key);
+			}
+		}
+	}
+	for (const name of Object.keys(surface.interfaces)) lookup.interfaceByName.set(name, name);
+	for (const name of Object.keys(surface.typeAliases)) lookup.typeAliasByName.set(name, name);
+	for (const [path, symbols] of Object.entries(surface.exports)) lookup.requiredExports.set(path, new Set(symbols));
+	for (const record of [
+		surface.classes,
+		surface.interfaces,
+		surface.typeAliases,
+		surface.enums
+	]) for (const [name, item] of Object.entries(record)) if (item.sourceFile) lookup.fileBySymbol.set(name, item.sourceFile);
+	if (spec) {
+		buildModelNameMap(surface, spec, lookup, resolvedHints, options);
+		for (const [irName, sdkName] of lookup.modelNameByIR) {
+			const filePath = lookup.fileBySymbol.get(sdkName);
+			if (filePath) lookup.fileBySymbol.set(irName, filePath);
+		}
+	}
+	return lookup;
+}
+/** Map HTTP methods to preferred method name prefixes for disambiguation. */
+const HTTP_VERB_PREFIXES = {
+	GET: [
+		"list",
+		"get",
+		"fetch",
+		"retrieve",
+		"find"
+	],
+	POST: [
+		"create",
+		"add",
+		"insert",
+		"send"
+	],
+	PUT: [
+		"set",
+		"update",
+		"replace",
+		"put"
+	],
+	PATCH: [
+		"update",
+		"patch",
+		"modify"
+	],
+	DELETE: [
+		"delete",
+		"remove",
+		"revoke"
+	]
+};
+/**
+* Disambiguate multiple method candidates using HTTP verb semantics.
+* Returns the best match or undefined if no unique match is found.
+*/
+function disambiguateByHttpVerb(candidates, httpMethod) {
+	const prefixes = HTTP_VERB_PREFIXES[httpMethod.toUpperCase()];
+	if (!prefixes) return void 0;
+	const verbCandidates = candidates.filter(([name]) => {
+		const lower = name.toLowerCase();
+		return prefixes.some((p) => lower.startsWith(p));
+	});
+	if (verbCandidates.length === 1) return verbCandidates[0];
+}
+/** Split a camelCase identifier into its word parts (e.g., "getByExternalId" → ["get","By","External","Id"]). */
+function splitCamelCase(name) {
+	const parts = [];
+	let start = 0;
+	for (let i = 1; i < name.length; i++) if (name[i] >= "A" && name[i] <= "Z") {
+		parts.push(name.slice(start, i));
+		start = i;
+	}
+	parts.push(name.slice(start));
+	return parts;
+}
+/** Check if `needle` words form a subsequence of `haystack` words (case-insensitive). */
+function isSubsequence(needle, haystack) {
+	let ni = 0;
+	for (let hi = 0; hi < haystack.length && ni < needle.length; hi++) if (needle[ni].toLowerCase() === haystack[hi].toLowerCase()) ni++;
+	return ni === needle.length;
+}
+/**
+* Normalize a field name to a canonical form for comparison.
+* Handles camelCase → snake_case so "createdAt" and "created_at" match.
+*/
+function normalizeFieldName(name) {
+	return toSnakeCase(name);
+}
+/**
+* Compute the Jaccard similarity between two sets of normalized field names.
+* Returns score (0–1) and raw intersection count.
+*/
+function jaccardSimilarity(a, b) {
+	if (a.size === 0 && b.size === 0) return {
+		score: 0,
+		intersection: 0
+	};
+	let intersection = 0;
+	for (const item of a) if (b.has(item)) intersection++;
+	const union = a.size + b.size - intersection;
+	return {
+		score: union === 0 ? 0 : intersection / union,
+		intersection
+	};
+}
+/**
+* Build a set of normalized field names from an IR model.
+*/
+function irModelFieldSignature(model) {
+	return new Set(model.fields.map((f) => normalizeFieldName(f.name)));
+}
+/**
+* Build a set of normalized field names from an SDK interface.
+*/
+function sdkInterfaceFieldSignature(iface) {
+	return new Set(Object.keys(iface.fields).map(normalizeFieldName));
+}
+/**
+* Populate the modelNameByIR map using two strategies:
+*
+* 1. Operation-based matching (high confidence):
+*    When a manifest maps an HTTP operation to an SDK method, extract the
+*    method's return type and parameter types. Match them against the IR
+*    operation's response model and request body model.
+*
+* 2. Field-structure matching (fallback):
+*    For IR models not matched by operations, compare their field names
+*    against all SDK interfaces using Jaccard similarity. A match requires
+*    ≥60% field overlap with ≥3 fields in common.
+*/
+function buildModelNameMap(surface, spec, lookup, hints, options) {
+	const mapped = /* @__PURE__ */ new Set();
+	const usedSdkNames = /* @__PURE__ */ new Set();
+	if (lookup.methodByOperation.size > 0) for (const service of spec.services) for (const op of service.operations) {
+		const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+		const methodOverlay = lookup.methodByOperation.get(httpKey);
+		if (!methodOverlay) continue;
+		if (op.response.kind === "model" && !mapped.has(op.response.name)) {
+			const sdkTypeName = hints.extractReturnTypeName(methodOverlay.returnType);
+			if (sdkTypeName && surface.interfaces[sdkTypeName]) {
+				lookup.modelNameByIR.set(op.response.name, sdkTypeName);
+				mapped.add(op.response.name);
+				usedSdkNames.add(sdkTypeName);
+			}
+		}
+		if (op.requestBody?.kind === "model" && !mapped.has(op.requestBody.name)) for (const param of methodOverlay.params) {
+			const sdkTypeName = hints.extractParamTypeName(param.type);
+			if (sdkTypeName && surface.interfaces[sdkTypeName]) {
+				lookup.modelNameByIR.set(op.requestBody.name, sdkTypeName);
+				mapped.add(op.requestBody.name);
+				usedSdkNames.add(sdkTypeName);
+				break;
+			}
+		}
+	}
+	const sdkSignatures = [];
+	for (const [name, iface] of Object.entries(surface.interfaces)) {
+		if (usedSdkNames.has(name)) continue;
+		const fields = sdkInterfaceFieldSignature(iface);
+		if (fields.size >= 2) sdkSignatures.push({
+			name,
+			fields,
+			fieldCount: fields.size
+		});
+	}
+	const sdkSignatureNames = new Set(sdkSignatures.map((s) => s.name));
+	for (const model of spec.models) {
+		if (mapped.has(model.name)) continue;
+		if (model.fields.length < 2) continue;
+		if (sdkSignatureNames.has(model.name) && !usedSdkNames.has(model.name)) {
+			lookup.modelNameByIR.set(model.name, model.name);
+			mapped.add(model.name);
+			usedSdkNames.add(model.name);
+			continue;
+		}
+		const derivedNames = hints.derivedModelNames(model.name);
+		for (const derived of derivedNames) if (sdkSignatureNames.has(derived) && !usedSdkNames.has(derived)) {
+			lookup.modelNameByIR.set(model.name, derived);
+			mapped.add(model.name);
+			usedSdkNames.add(derived);
+			break;
+		}
+		if (mapped.has(model.name)) continue;
+		if (options?.strictModelMatch) continue;
+		const irFields = irModelFieldSignature(model);
+		let bestMatch = null;
+		let bestScore = 0;
+		for (const sdk of sdkSignatures) {
+			if (usedSdkNames.has(sdk.name)) continue;
+			const { score, intersection } = jaccardSimilarity(irFields, sdk.fields);
+			const minIntersection = Math.max(3, Math.ceil(irFields.size * .5));
+			if (score > bestScore && score >= .6 && intersection >= minIntersection) {
+				bestScore = score;
+				bestMatch = sdk.name;
+			}
+		}
+		if (bestMatch) {
+			lookup.modelNameByIR.set(model.name, bestMatch);
+			mapped.add(model.name);
+			usedSdkNames.add(bestMatch);
+		}
+	}
+}
+/**
+* Patch overlay with violations from a failed verification.
+* Adds explicit name mappings for symbols that were generated with wrong names.
+* Returns a new OverlayLookup (immutable).
+*/
+function patchOverlay(overlay, violations, baseline) {
+	const patched = {
+		methodByOperation: new Map(overlay.methodByOperation),
+		httpKeyByMethod: new Map(overlay.httpKeyByMethod),
+		interfaceByName: new Map(overlay.interfaceByName),
+		typeAliasByName: new Map(overlay.typeAliasByName),
+		requiredExports: new Map(Array.from(overlay.requiredExports.entries()).map(([k, v]) => [k, new Set(v)])),
+		modelNameByIR: new Map(overlay.modelNameByIR),
+		fileBySymbol: new Map(overlay.fileBySymbol)
+	};
+	let warnedManifest = false;
+	for (const v of violations) {
+		if (v.category === "public-api") {
+			const parts = v.symbolPath.split(".");
+			if (parts.length === 2) {
+				const [className, methodName] = parts;
+				const baseClass = baseline.classes[className];
+				if (baseClass && baseClass.methods[methodName]?.length > 0) {
+					const httpKey = overlay.httpKeyByMethod.get(`${className}.${methodName}`);
+					if (!httpKey && overlay.httpKeyByMethod.size === 0 && !warnedManifest) {
+						console.warn("Warning: No smoke-manifest.json available. Method-level violations cannot be auto-patched. Implement generateManifest in your emitter for the self-correcting loop to resolve these.");
+						warnedManifest = true;
+					}
+					if (httpKey) {
+						const method = baseClass.methods[methodName][0];
+						patched.methodByOperation.set(httpKey, {
+							className,
+							methodName,
+							params: method.params,
+							returnType: method.returnType
+						});
+					}
+				}
+				if (baseline.interfaces[className]) patched.interfaceByName.set(className, className);
+			} else if (parts.length === 1) {
+				const name = parts[0];
+				if (baseline.interfaces[name]) patched.interfaceByName.set(name, name);
+				if (baseline.typeAliases[name]) patched.typeAliasByName.set(name, name);
+			}
+		}
+		if (v.category === "export-structure") {
+			const match = v.symbolPath.match(/^exports\[(.+?)\]\.(.+)$/);
+			if (match) {
+				const [, path, symbol] = match;
+				if (!patched.requiredExports.has(path)) patched.requiredExports.set(path, /* @__PURE__ */ new Set());
+				patched.requiredExports.get(path).add(symbol);
+			}
+		}
+	}
+	return patched;
+}
+//#endregion
+//#region src/compat/spec-filter.ts
+/**
+* Compute the set of symbol names that are derivable from the OpenAPI spec.
+* Only these names should be compared during compat verification — everything
+* else in the baseline is hand-written and out of scope for generation.
+*/
+function specDerivedNames(spec, hints) {
+	const names = /* @__PURE__ */ new Set();
+	const topLevelEnumNames = new Set(spec.enums.map((e) => e.name));
+	for (const service of spec.services) {
+		names.add(service.name);
+		for (const op of service.operations) {
+			collectTypeRefNames(op.response, names, hints, topLevelEnumNames);
+			if (op.requestBody) collectTypeRefNames(op.requestBody, names, hints, topLevelEnumNames);
+			for (const p of [
+				...op.pathParams,
+				...op.queryParams,
+				...op.headerParams,
+				...op.cookieParams ?? []
+			]) collectTypeRefNames(p.type, names, hints, topLevelEnumNames);
+		}
+	}
+	for (const model of spec.models) {
+		names.add(model.name);
+		for (const derived of hints.derivedModelNames(model.name)) names.add(derived);
+		for (const field of model.fields) collectTypeRefNames(field.type, names, hints, topLevelEnumNames);
+	}
+	for (const e of spec.enums) names.add(e.name);
+	return names;
+}
+/**
+* Compute a map of enum name → set of wire values that appear in the spec.
+* Used by filterSurface to exclude hand-added enum members that aren't in the spec.
+*/
+function specDerivedEnumValues(spec) {
+	const result = /* @__PURE__ */ new Map();
+	for (const e of spec.enums) result.set(e.name, new Set(e.values.map((v) => v.value)));
+	return result;
+}
+/**
+* Compute the set of field paths (e.g., "Organization.name") that are defined
+* in the OpenAPI spec's model schemas. Used by filterSurface to exclude
+* hand-added SDK fields that reference spec-derived types.
+*/
+function specDerivedFieldPaths(spec, hints) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const model of spec.models) {
+		for (const field of model.fields) paths.add(`${model.name}.${field.name}`);
+		for (const derived of hints.derivedModelNames(model.name)) for (const field of model.fields) paths.add(`${derived}.${field.name}`);
+	}
+	return paths;
+}
+/**
+* Compute the set of method paths (e.g., "SSO.authorize") that are defined
+* as operations in the OpenAPI spec's services. Used by filterSurface to
+* exclude hand-written SDK methods that don't correspond to spec operations.
+*/
+function specDerivedMethodPaths(spec) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const service of spec.services) for (const op of service.operations) paths.add(`${service.name}.${op.name}`);
+	return paths;
+}
+/**
+* Compute the set of HTTP operation keys (e.g., "GET /sso/authorize") that
+* exist in the spec. Used for overlay-based method matching.
+*/
+function specDerivedHttpKeys(spec) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const service of spec.services) for (const op of service.operations) keys.add(`${op.httpMethod.toUpperCase()} ${op.path}`);
+	return keys;
+}
+function collectTypeRefNames(ref, out, hints, topLevelEnums) {
+	walkTypeRef(ref, {
+		model: (r) => {
+			out.add(r.name);
+			for (const derived of hints.derivedModelNames(r.name)) out.add(derived);
+		},
+		enum: (r) => {
+			if (!topLevelEnums || topLevelEnums.has(r.name)) out.add(r.name);
+		}
+	});
+}
+function filterRecord(record, allowed) {
+	const result = {};
+	for (const [name, value] of Object.entries(record)) if (allowed.has(name)) result[name] = value;
+	return result;
+}
+/**
+* Filter an ApiSurface to only include symbols whose names appear in the
+* allowed set. Symbols not in the set are dropped entirely — they won't
+* count toward the total or produce violations.
+*
+* For interfaces: when fieldPaths is provided, only keeps fields that appear
+* in the spec-derived field paths. This prevents false positives from hand-added
+* SDK fields that reference spec-derived types but aren't defined in the spec.
+*
+* For classes: when methodPaths is provided, only keeps methods whose names
+* appear in the spec-derived method paths. This prevents false positives from
+* hand-written SDK methods (e.g., SSO.authorization_url, Webhooks.construct_event)
+* that don't correspond to spec operations. Properties on service classes are
+* also filtered: only UPPER_CASE constants that are spec-derivable are kept.
+*/
+function filterSurface(surface, allowedNames, opts) {
+	const { fieldPaths, methodPaths, enumValues } = opts ?? {};
+	const filteredInterfaces = filterRecord(surface.interfaces, allowedNames);
+	if (fieldPaths) for (const [name, iface] of Object.entries(filteredInterfaces)) {
+		const filteredFields = {};
+		for (const [fieldName, field] of Object.entries(iface.fields)) if (fieldPaths.has(`${name}.${fieldName}`)) filteredFields[fieldName] = field;
+		filteredInterfaces[name] = {
+			...iface,
+			fields: filteredFields
+		};
+	}
+	let filteredClasses = filterRecord(surface.classes, allowedNames);
+	if (methodPaths) {
+		const serviceClassNames = /* @__PURE__ */ new Set();
+		for (const path of methodPaths) {
+			const dot = path.indexOf(".");
+			if (dot !== -1) serviceClassNames.add(path.slice(0, dot));
+		}
+		const newClasses = {};
+		for (const [name, cls] of Object.entries(filteredClasses)) if (serviceClassNames.has(name)) {
+			const filteredMethods = {};
+			for (const [methodName, overloads] of Object.entries(cls.methods)) if (methodPaths.has(`${name}.${methodName}`)) filteredMethods[methodName] = overloads;
+			const filteredProperties = {};
+			for (const [propName, prop] of Object.entries(cls.properties)) if (methodPaths.has(`${name}.${propName}`)) filteredProperties[propName] = prop;
+			newClasses[name] = {
+				...cls,
+				methods: filteredMethods,
+				properties: filteredProperties
+			};
+		} else if (fieldPaths) {
+			const filteredProperties = {};
+			for (const [propName, prop] of Object.entries(cls.properties)) if (fieldPaths.has(`${name}.${propName}`)) filteredProperties[propName] = prop;
+			const filteredMethods = {};
+			for (const [methodName, overloads] of Object.entries(cls.methods)) if (fieldPaths.has(`${name}.${methodName}`) || methodPaths.has(`${name}.${methodName}`)) filteredMethods[methodName] = overloads;
+			newClasses[name] = {
+				...cls,
+				methods: filteredMethods,
+				properties: filteredProperties
+			};
+		} else newClasses[name] = cls;
+		filteredClasses = newClasses;
+	}
+	let filteredEnums = filterRecord(surface.enums, allowedNames);
+	if (enumValues) {
+		const newEnums = {};
+		for (const [name, enumDef] of Object.entries(filteredEnums)) {
+			const specValues = enumValues.get(name);
+			if (!specValues) {
+				newEnums[name] = enumDef;
+				continue;
+			}
+			const specValuesLower = new Set([...specValues].map((v) => String(v).toLowerCase()));
+			const filteredMembers = {};
+			for (const [member, value] of Object.entries(enumDef.members)) if (specValues.has(value) || specValuesLower.has(String(value).toLowerCase())) filteredMembers[member] = value;
+			newEnums[name] = {
+				...enumDef,
+				members: filteredMembers
+			};
+		}
+		filteredEnums = newEnums;
+	}
+	return {
+		...surface,
+		classes: filteredClasses,
+		interfaces: filteredInterfaces,
+		typeAliases: filterRecord(surface.typeAliases, allowedNames),
+		enums: filteredEnums,
+		exports: {}
+	};
+}
+//#endregion
+//#region src/compat/differ.ts
+function diffSurfaces(baseline, candidate, hints) {
+	const violations = [];
+	const additions = [];
+	let totalBaseline = 0;
+	let preserved = 0;
+	for (const [name, baseClass] of Object.entries(baseline.classes)) {
+		totalBaseline++;
+		const candClass = candidate.classes[name];
+		if (!candClass) {
+			violations.push({
+				category: "public-api",
+				severity: "breaking",
+				symbolPath: name,
+				baseline: name,
+				candidate: "(missing)",
+				message: `Class "${name}" exists in baseline but not in generated output`
+			});
+			totalBaseline += Object.values(baseClass.methods).reduce((sum, overloads) => sum + overloads.length, 0);
+			totalBaseline += Object.keys(baseClass.properties).length;
+			continue;
+		}
+		preserved++;
+		for (const [methodName, baseOverloads] of Object.entries(baseClass.methods)) {
+			const candOverloads = candClass.methods[methodName];
+			for (const baseMethod of baseOverloads) {
+				totalBaseline++;
+				if (!candOverloads || candOverloads.length === 0) {
+					violations.push({
+						category: "public-api",
+						severity: "breaking",
+						symbolPath: `${name}.${methodName}`,
+						baseline: methodName,
+						candidate: "(missing)",
+						message: `Method "${name}.${methodName}" exists in baseline but not in generated output`
+					});
+					continue;
+				}
+				if (!candOverloads.find((c) => signaturesMatch(baseMethod, c))) {
+					if (hints.isSignatureEquivalent ? candOverloads.find((c) => hints.isSignatureEquivalent(baseMethod, c, candidate)) : void 0) {
+						preserved++;
+						continue;
+					}
+					violations.push({
+						category: "signature",
+						severity: "breaking",
+						symbolPath: `${name}.${methodName}`,
+						baseline: formatSignature(baseMethod),
+						candidate: formatSignature(candOverloads[0]),
+						message: `Signature mismatch for "${name}.${methodName}"`
+					});
+					continue;
+				}
+				preserved++;
+			}
+		}
+		for (const methodName of Object.keys(candClass.methods)) if (!baseClass.methods[methodName]) additions.push({
+			symbolPath: `${name}.${methodName}`,
+			symbolType: "method"
+		});
+		for (const [propName, baseProp] of Object.entries(baseClass.properties)) {
+			totalBaseline++;
+			const candProp = candClass.properties[propName];
+			if (!candProp) {
+				violations.push({
+					category: "public-api",
+					severity: "breaking",
+					symbolPath: `${name}.${propName}`,
+					baseline: baseProp.type,
+					candidate: "(missing)",
+					message: `Property "${name}.${propName}" exists in baseline but not in generated output`
+				});
+				continue;
+			}
+			if (baseProp.type !== candProp.type) {
+				const nullableOnly = hints.isNullableOnlyDifference(baseProp.type, candProp.type);
+				violations.push({
+					category: "signature",
+					severity: nullableOnly ? "warning" : "breaking",
+					symbolPath: `${name}.${propName}`,
+					baseline: baseProp.type,
+					candidate: candProp.type,
+					message: `Property type mismatch for "${name}.${propName}"`
+				});
+				if (nullableOnly) preserved++;
+				continue;
+			}
+			preserved++;
+		}
+		for (const propName of Object.keys(candClass.properties)) if (!baseClass.properties[propName]) additions.push({
+			symbolPath: `${name}.${propName}`,
+			symbolType: "property"
+		});
+	}
+	for (const name of Object.keys(candidate.classes)) if (!baseline.classes[name]) additions.push({
+		symbolPath: name,
+		symbolType: "class"
+	});
+	const candIfaceFieldSets = /* @__PURE__ */ new Map();
+	for (const [n, iface] of Object.entries(candidate.interfaces)) candIfaceFieldSets.set(n, new Set(Object.keys(iface.fields).map((f) => f.toLowerCase())));
+	const candClassPropSets = /* @__PURE__ */ new Map();
+	for (const [n, cls] of Object.entries(candidate.classes)) candClassPropSets.set(n, new Set(Object.keys(cls.properties).map((f) => f.toLowerCase())));
+	for (const [name, baseIface] of Object.entries(baseline.interfaces)) {
+		totalBaseline++;
+		const candIface = candidate.interfaces[name];
+		if (!candIface) {
+			let tolerated = false;
+			if (hints.tolerateCategoryMismatch && name.startsWith("Serialized")) {
+				const baseName = name.slice(10);
+				if (candidate.interfaces[baseName] || candidate.classes[baseName]) tolerated = true;
+			}
+			if (tolerated) {
+				preserved++;
+				totalBaseline += Object.keys(baseIface.fields).length;
+				preserved += Object.keys(baseIface.fields).length;
+				continue;
+			}
+			if (!tolerated) {
+				const baseFieldNamesLower = new Set(Object.keys(baseIface.fields).map((f) => f.toLowerCase()));
+				if (baseFieldNamesLower.size > 0) {
+					for (const [, candFieldNamesLower] of candIfaceFieldSets) if (candFieldNamesLower.size === baseFieldNamesLower.size && [...baseFieldNamesLower].every((f) => candFieldNamesLower.has(f))) {
+						tolerated = true;
+						break;
+					}
+					if (!tolerated) {
+						for (const [, candPropNamesLower] of candClassPropSets) if (candPropNamesLower.size === baseFieldNamesLower.size && [...baseFieldNamesLower].every((f) => candPropNamesLower.has(f))) {
+							tolerated = true;
+							break;
+						}
+					}
+				} else tolerated = true;
+			}
+			if (tolerated) {
+				preserved++;
+				totalBaseline += Object.keys(baseIface.fields).length;
+				preserved += Object.keys(baseIface.fields).length;
+				continue;
+			}
+			violations.push({
+				category: "public-api",
+				severity: "breaking",
+				symbolPath: name,
+				baseline: name,
+				candidate: "(missing)",
+				message: `Interface "${name}" exists in baseline but not in generated output`
+			});
+			totalBaseline += Object.keys(baseIface.fields).length;
+			continue;
+		}
+		preserved++;
+		for (const [fieldName, baseField] of Object.entries(baseIface.fields)) {
+			totalBaseline++;
+			const candField = candIface.fields[fieldName];
+			if (!candField) {
+				const baseTypeClean = baseField.type.replace(/\[\]$/, "").replace(/ \| null$/, "");
+				const typeIsUnresolvable = NAMED_TYPE_RE.test(baseTypeClean) && !typeExistsInSurface(baseTypeClean, candidate);
+				violations.push({
+					category: "public-api",
+					severity: typeIsUnresolvable ? "warning" : "breaking",
+					symbolPath: `${name}.${fieldName}`,
+					baseline: baseField.type,
+					candidate: "(missing)",
+					message: `Field "${name}.${fieldName}" exists in baseline but not in generated output`
+				});
+				if (typeIsUnresolvable) preserved++;
+				continue;
+			}
+			if (baseField.type !== candField.type) {
+				if (hints.isUnionReorder(baseField.type, candField.type)) {
+					preserved++;
+					continue;
+				}
+				if (hints.isTypeEquivalent?.(baseField.type, candField.type, candidate)) {
+					preserved++;
+					continue;
+				}
+				const nullableOnly = hints.isNullableOnlyDifference(baseField.type, candField.type);
+				const genericParam = hints.isGenericTypeParam(baseField.type);
+				const extractionArtifact = hints.isExtractionArtifact(candField.type);
+				const isWarning = nullableOnly || genericParam || extractionArtifact;
+				violations.push({
+					category: "signature",
+					severity: isWarning ? "warning" : "breaking",
+					symbolPath: `${name}.${fieldName}`,
+					baseline: baseField.type,
+					candidate: candField.type,
+					message: `Field type mismatch for "${name}.${fieldName}"`
+				});
+				if (isWarning) preserved++;
+				continue;
+			}
+			preserved++;
+		}
+		for (const fieldName of Object.keys(candIface.fields)) if (!baseIface.fields[fieldName]) additions.push({
+			symbolPath: `${name}.${fieldName}`,
+			symbolType: "property"
+		});
+	}
+	for (const name of Object.keys(candidate.interfaces)) if (!baseline.interfaces[name]) additions.push({
+		symbolPath: name,
+		symbolType: "interface"
+	});
+	for (const [name, baseAlias] of Object.entries(baseline.typeAliases)) {
+		totalBaseline++;
+		const candAlias = candidate.typeAliases[name];
+		if (!candAlias) {
+			if (hints.tolerateCategoryMismatch && typeExistsInSurface(name, candidate)) {
+				preserved++;
+				continue;
+			}
+			violations.push({
+				category: "public-api",
+				severity: "breaking",
+				symbolPath: name,
+				baseline: baseAlias.value,
+				candidate: "(missing)",
+				message: `Type alias "${name}" exists in baseline but not in generated output`
+			});
+			continue;
+		}
+		if (baseAlias.value !== candAlias.value) {
+			if (hints.isUnionReorder(baseAlias.value, candAlias.value)) {
+				preserved++;
+				continue;
+			}
+			const nullableOnly = hints.isNullableOnlyDifference(baseAlias.value, candAlias.value);
+			violations.push({
+				category: "signature",
+				severity: nullableOnly ? "warning" : "breaking",
+				symbolPath: name,
+				baseline: baseAlias.value,
+				candidate: candAlias.value,
+				message: `Type alias value mismatch for "${name}"`
+			});
+			if (nullableOnly) preserved++;
+			continue;
+		}
+		preserved++;
+	}
+	for (const name of Object.keys(candidate.typeAliases)) if (!baseline.typeAliases[name]) additions.push({
+		symbolPath: name,
+		symbolType: "type-alias"
+	});
+	for (const [name, baseEnum] of Object.entries(baseline.enums)) {
+		totalBaseline++;
+		const candEnum = candidate.enums[name];
+		if (!candEnum) {
+			violations.push({
+				category: "public-api",
+				severity: "breaking",
+				symbolPath: name,
+				baseline: name,
+				candidate: "(missing)",
+				message: `Enum "${name}" exists in baseline but not in generated output`
+			});
+			continue;
+		}
+		const candValueToMembers = /* @__PURE__ */ new Map();
+		for (const [candMember, candValue] of Object.entries(candEnum.members)) {
+			const existing = candValueToMembers.get(candValue);
+			if (existing) existing.push(candMember);
+			else candValueToMembers.set(candValue, [candMember]);
+		}
+		let enumMatch = true;
+		for (const [member, value] of Object.entries(baseEnum.members)) {
+			if (candEnum.members[member] === value) continue;
+			const valueMatches = candValueToMembers.get(value);
+			if (valueMatches && valueMatches.length > 0) {
+				violations.push({
+					category: "signature",
+					severity: "warning",
+					symbolPath: `${name}.${member}`,
+					baseline: `${member}=${String(value)}`,
+					candidate: `${valueMatches[0]}=${String(value)}`,
+					message: `Enum member name differs for "${name}.${member}" (value "${value}" preserved as "${valueMatches[0]}")`
+				});
+				continue;
+			}
+			const lowerValue = String(value).toLowerCase();
+			const caseInsensitiveMatch = [...candValueToMembers.entries()].find(([candVal]) => String(candVal).toLowerCase() === lowerValue);
+			if (caseInsensitiveMatch) {
+				violations.push({
+					category: "signature",
+					severity: "warning",
+					symbolPath: `${name}.${member}`,
+					baseline: `${member}=${String(value)}`,
+					candidate: `${caseInsensitiveMatch[1][0]}=${String(caseInsensitiveMatch[0])}`,
+					message: `Enum member value case differs for "${name}.${member}" (baseline "${value}" vs candidate "${caseInsensitiveMatch[0]}")`
+				});
+				continue;
+			}
+			if (String(value) === member || member === "JsonEnumDefaultValue" || member === "JsonProperty") {
+				violations.push({
+					category: "signature",
+					severity: "warning",
+					symbolPath: `${name}.${member}`,
+					baseline: String(value),
+					candidate: "(extraction artifact)",
+					message: `Enum member "${name}.${member}" appears to be an extraction artifact`
+				});
+				continue;
+			}
+			violations.push({
+				category: "signature",
+				severity: "breaking",
+				symbolPath: `${name}.${member}`,
+				baseline: String(value),
+				candidate: member in candEnum.members ? String(candEnum.members[member]) : "(missing)",
+				message: `Enum member mismatch for "${name}.${member}"`
+			});
+			enumMatch = false;
+		}
+		if (enumMatch) preserved++;
+	}
+	for (const name of Object.keys(candidate.enums)) if (!baseline.enums[name]) additions.push({
+		symbolPath: name,
+		symbolType: "enum"
+	});
+	for (const [path, baseExports] of Object.entries(baseline.exports)) {
+		const candExports = candidate.exports[path];
+		if (!candExports) {
+			for (const exp of baseExports) violations.push({
+				category: "export-structure",
+				severity: "warning",
+				symbolPath: `exports[${path}].${exp}`,
+				baseline: exp,
+				candidate: "(missing)",
+				message: `Export "${exp}" from "${path}" not found in generated output`
+			});
+			continue;
+		}
+		const candSet = new Set(candExports);
+		for (const exp of baseExports) if (!candSet.has(exp)) violations.push({
+			category: "export-structure",
+			severity: "warning",
+			symbolPath: `exports[${path}].${exp}`,
+			baseline: exp,
+			candidate: "(missing)",
+			message: `Export "${exp}" from "${path}" not found in generated output`
+		});
+	}
+	return {
+		preservationScore: totalBaseline > 0 ? Math.round(preserved / totalBaseline * 100) : 100,
+		totalBaselineSymbols: totalBaseline,
+		preservedSymbols: preserved,
+		violations,
+		additions
+	};
+}
+/**
+* Compare method signatures using raw type strings.
+* NOTE: This only produces meaningful results when both surfaces were extracted
+* by the same extractor for the same language. Cross-language or cross-extractor
+* comparisons will always fail because type representations differ.
+*/
+function signaturesMatch(baseline, candidate) {
+	if (baseline.returnType !== candidate.returnType) return false;
+	for (let i = 0; i < baseline.params.length; i++) {
+		const baseParam = baseline.params[i];
+		const candParam = candidate.params[i];
+		if (!candParam) return false;
+		if (baseParam.type !== candParam.type) return false;
+		if (baseParam.name !== candParam.name) return false;
+	}
+	for (let i = baseline.params.length; i < candidate.params.length; i++) if (!candidate.params[i].optional) return false;
+	return true;
+}
+function formatSignature(method) {
+	return `(${method.params.map((p) => `${p.name}${p.optional ? "?" : ""}: ${p.type}`).join(", ")}) => ${method.returnType}`;
+}
+//#endregion
+export { registerExtractor as _, specDerivedHttpKeys as a, buildOverlayLookup as c, defaultIsNullableOnlyDifference as d, namedTypeWordsOverlap as f, getExtractor as g, typeExistsInSurface as h, specDerivedFieldPaths as i, patchOverlay as l, resolveHints as m, filterSurface as n, specDerivedMethodPaths as o, nodeHints as p, specDerivedEnumValues as r, specDerivedNames as s, diffSurfaces as t, NAMED_TYPE_RE as u };
+
+//# sourceMappingURL=differ-BwelBJN0.mjs.map