@workos/oagen 0.7.0 → 0.8.0

package/dist/compat/index.mjs

@@ -1,5 +1,5 @@
 import { t as safeParse$1, v as ExtractorError } from "../tree-sitter-C53w_0WE.mjs";
-import { _ as registerExtractor, a as specDerivedHttpKeys, c as buildOverlayLookup, d as defaultIsNullableOnlyDifference, f as namedTypeWordsOverlap, g as getExtractor, h as typeExistsInSurface, i as specDerivedFieldPaths, l as patchOverlay, m as resolveHints, n as filterSurface, o as specDerivedMethodPaths, p as nodeHints, r as specDerivedEnumValues, s as specDerivedNames, t as diffSurfaces, u as NAMED_TYPE_RE } from "../differ-CG5ZErKl.mjs";
+import { A as getDefaultPolicy, C as defaultSeverityForCategory, D as isCompatibleSchemaVersion, E as COMPAT_SCHEMA_VERSION, O as validateSnapshot, S as summarizeChanges, T as apiSurfaceToSnapshot, _ as nodeHints, a as registerExtractor, b as classifyAddedSymbol, c as filterSurface, d as specDerivedHttpKeys, f as specDerivedMethodPaths, g as namedTypeWordsOverlap, h as defaultIsNullableOnlyDifference, i as getExtractor, j as mergePolicy, k as ALL_LANGUAGE_IDS, l as specDerivedEnumValues, m as NAMED_TYPE_RE, n as isPatchableChange, o as diffSnapshots, p as specDerivedNames, r as patchOverlay, s as diffSurfaces, t as buildOverlayLookup, u as specDerivedFieldPaths, v as resolveHints, w as severityMeetsThreshold, x as classifySymbolChanges, y as typeExistsInSurface } from "../overlay-TYxHOCow.mjs";
 import path, { basename, dirname, join, relative, resolve } from "node:path";
 import Parser from "tree-sitter";
 import ts from "typescript";
@@ -9,6 +9,225 @@ import Python from "tree-sitter-python";
 import Ruby from "tree-sitter-ruby";
 import Go from "tree-sitter-go";
 import RustLang from "tree-sitter-rust";
+//#region src/compat/concepts.ts
+/**
+* Group classified changes from multiple languages into conceptual changes.
+*
+* Changes are grouped by their `conceptualChangeId` — a deterministic ID
+* derived from the symbol, category, and match details. Changes with the
+* same ID across different languages represent the same conceptual change.
+*/
+function buildConceptualRollup(perLanguageResults) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const { diff: result, language } of perLanguageResults) for (const change of result.changes) {
+		const existing = grouped.get(change.conceptualChangeId);
+		if (existing) existing.impact[language] = change.severity;
+		else grouped.set(change.conceptualChangeId, {
+			id: change.conceptualChangeId,
+			symbol: change.symbol,
+			category: change.category,
+			impact: { [language]: change.severity },
+			message: change.message,
+			old: change.old,
+			new: change.new
+		});
+	}
+	return { conceptualChanges: [...grouped.values()] };
+}
+/** Get the highest severity across all languages for a conceptual change. */
+function highestSeverity(change) {
+	const severities = Object.values(change.impact);
+	if (severities.includes("breaking")) return "breaking";
+	if (severities.includes("soft-risk")) return "soft-risk";
+	return "additive";
+}
+/** Count conceptual changes by highest severity. */
+function summarizeConceptualChanges(rollup) {
+	let breaking = 0;
+	let softRisk = 0;
+	let additive = 0;
+	for (const change of rollup.conceptualChanges) {
+		const sev = highestSeverity(change);
+		if (sev === "breaking") breaking++;
+		else if (sev === "soft-risk") softRisk++;
+		else additive++;
+	}
+	return {
+		breaking,
+		softRisk,
+		additive
+	};
+}
+//#endregion
+//#region src/compat/report.ts
+/** Generate a machine-readable compat report from a diff result. */
+function generateReport(diff, language) {
+	return {
+		schemaVersion: "1",
+		language: language ?? "unknown",
+		summary: diff.summary,
+		changes: diff.changes.map((c) => ({
+			severity: c.severity,
+			category: c.category,
+			symbol: c.symbol,
+			conceptualChangeId: c.conceptualChangeId,
+			provenance: c.provenance,
+			old: c.old,
+			new: c.new,
+			...c.message ? { message: c.message } : {}
+		}))
+	};
+}
+/** Generate a human-readable summary string for terminal output. */
+function formatHumanSummary(diff, opts) {
+	const lines = [];
+	lines.push(`Compat report${opts?.language ? ` for ${opts.language}` : ""}:`);
+	lines.push(`  ${diff.summary.breaking} breaking, ${diff.summary.softRisk} soft-risk, ${diff.summary.additive} additive`);
+	if (diff.changes.length === 0) {
+		lines.push("  No compatibility changes detected.");
+		return lines.join("\n");
+	}
+	const breaking = diff.changes.filter((c) => c.severity === "breaking");
+	const softRisk = diff.changes.filter((c) => c.severity === "soft-risk");
+	const additive = diff.changes.filter((c) => c.severity === "additive");
+	if (breaking.length > 0) {
+		lines.push("");
+		lines.push("  Breaking:");
+		for (const c of breaking) {
+			lines.push(`    [${c.category}] ${c.symbol} — ${c.message}`);
+			if (opts?.explain && c.provenance !== "unknown") lines.push(`      provenance: ${c.provenance}`);
+		}
+	}
+	if (softRisk.length > 0) {
+		lines.push("");
+		lines.push("  Soft-risk:");
+		for (const c of softRisk) {
+			lines.push(`    [${c.category}] ${c.symbol} — ${c.message}`);
+			if (opts?.explain && c.provenance !== "unknown") lines.push(`      provenance: ${c.provenance}`);
+		}
+	}
+	if (additive.length > 0) {
+		lines.push("");
+		lines.push(`  Additive: ${additive.length} new symbol(s)`);
+	}
+	return lines.join("\n");
+}
+/** Generate a conceptual cross-language report from multiple per-language results. */
+function generateConceptualReport(perLanguageResults) {
+	return { conceptualChanges: buildConceptualRollup(perLanguageResults).conceptualChanges.map((c) => ({
+		id: c.id,
+		symbol: c.symbol,
+		category: c.category,
+		impact: c.impact
+	})) };
+}
+/** Format a conceptual cross-language summary for terminal output. */
+function formatConceptualSummary(perLanguageResults) {
+	const rollup = buildConceptualRollup(perLanguageResults);
+	const summary = summarizeConceptualChanges(rollup);
+	const lines = [];
+	lines.push("Cross-language conceptual summary:");
+	lines.push(`  ${summary.breaking} breaking, ${summary.softRisk} soft-risk, ${summary.additive} additive`);
+	if (rollup.conceptualChanges.length === 0) {
+		lines.push("  No cross-language changes.");
+		return lines.join("\n");
+	}
+	for (const change of rollup.conceptualChanges) {
+		const sev = highestSeverity(change);
+		const impactStr = Object.entries(change.impact).map(([lang, s]) => `${lang}: ${s}`).join(", ");
+		lines.push(`  [${sev}] ${change.category}: ${change.symbol}`);
+		lines.push(`    impact: ${impactStr}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/compat/approvals.ts
+/** Validate that an approval is narrow enough to be accepted. */
+function validateApproval(approval) {
+	const errors = [];
+	if (!approval.symbol || approval.symbol.trim() === "") errors.push("Approval must target a specific symbol");
+	if (!approval.category) errors.push("Approval must specify a change category");
+	if (!approval.reason || approval.reason.trim() === "") errors.push("Approval must include a reason");
+	if (approval.symbol === "*" || approval.symbol.endsWith(".*") || approval.symbol.endsWith("::*")) errors.push(`Approval symbol "${approval.symbol}" is too broad — must target a specific symbol`);
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/** Validate all approvals in a config. Returns errors keyed by index. */
+function validateApprovals(approvals) {
+	const result = /* @__PURE__ */ new Map();
+	for (let i = 0; i < approvals.length; i++) {
+		const validation = validateApproval(approvals[i]);
+		if (!validation.valid) result.set(i, validation.errors);
+	}
+	return result;
+}
+/**
+* Match a classified change against a list of approvals.
+* Returns the first matching approval, or null if none match.
+*/
+function matchApproval(change, approvals, language) {
+	for (const approval of approvals) if (approvalMatchesChange(approval, change, language)) return approval;
+	return null;
+}
+/**
+* Apply approvals to a list of changes.
+* Returns matches for every change (approved or not).
+*/
+function applyApprovals(changes, approvals, language) {
+	return changes.map((change) => {
+		const approval = matchApproval(change, approvals, language);
+		return {
+			change,
+			approval,
+			approved: approval !== null
+		};
+	});
+}
+/**
+* Filter changes to only those NOT covered by approvals.
+* These are the remaining unapproved changes that may cause failure.
+*/
+function unapprovedChanges(changes, approvals, language) {
+	return changes.filter((change) => !matchApproval(change, approvals, language));
+}
+function approvalMatchesChange(approval, change, language) {
+	if (approval.approved === false) return false;
+	if (approval.category !== change.category) return false;
+	if (!symbolMatches(approval.symbol, change.symbol)) return false;
+	if (!languageMatches(approval.appliesTo, language)) return false;
+	if (approval.match && !narrowingMatches(approval.match, change)) return false;
+	return true;
+}
+function symbolMatches(approvalSymbol, changeSymbol) {
+	if (approvalSymbol === changeSymbol) return true;
+	return approvalSymbol.replace(/::/g, ".").replace(/\\/g, ".") === changeSymbol.replace(/::/g, ".").replace(/\\/g, ".");
+}
+function languageMatches(appliesTo, language) {
+	if (!appliesTo || appliesTo === "all-impacted-languages") return true;
+	return appliesTo.includes(language);
+}
+function narrowingMatches(match, change) {
+	if (match.parameter) {
+		const paramInOld = change.old.parameter === match.parameter;
+		const paramInNew = change.new.parameter === match.parameter;
+		if (!paramInOld && !paramInNew) return false;
+	}
+	if (match.member) {
+		const memberInOld = change.old.member === match.member;
+		const memberInNew = change.new.member === match.member;
+		if (!memberInOld && !memberInNew) return false;
+	}
+	if (match.oldName) {
+		if (!Object.values(change.old).some((v) => v === match.oldName)) return false;
+	}
+	if (match.newName) {
+		if (!Object.values(change.new).some((v) => v === match.newName)) return false;
+	}
+	return true;
+}
+//#endregion
 //#region src/compat/extractors/shared.ts
 /** Sort an object's keys alphabetically. Shared across all extractors for deterministic output. */
 function sortRecord(record) {
@@ -38,6 +257,9 @@ var ExportCollector = class {
 const nodeExtractor = {
 	language: "node",
 	hints: nodeHints,
+	async extractSnapshot(sdkPath) {
+		return apiSurfaceToSnapshot(await this.extract(sdkPath));
+	},
 	async extract(sdkPath) {
 		sdkPath = resolve(sdkPath);
 		const configPath = ts.findConfigFile(sdkPath, ts.sys.fileExists, "tsconfig.json");
@@ -176,12 +398,13 @@ function extractClass(sym, checker) {
 				else deprecationMessage = "";
 			}
 			for (const member of decl.members) if (ts.isConstructorDeclaration(member)) for (const param of member.parameters) {
-				const paramName = extractParameterName(param, param.name.getText());
+				const { name: paramName, isDestructured } = extractParameterInfo(param, param.name.getText());
 				const paramType = param.type ? checker.typeToString(checker.getTypeFromTypeNode(param.type)) : "any";
 				constructorParams.push({
 					name: paramName,
 					type: paramType,
-					optional: !!param.questionToken || !!param.initializer
+					optional: !!param.questionToken || !!param.initializer,
+					passingStyle: isDestructured ? "options_object" : "positional"
 				});
 			}
 		}
@@ -226,20 +449,57 @@ function extractParam(sym, checker) {
 	const decl = sym.getDeclarations()?.[0];
 	const isOptional = decl && ts.isParameter(decl) ? !!decl.questionToken || !!decl.initializer : false;
 	const type = checker.getTypeOfSymbolAtLocation(sym, decl);
+	const { name, isDestructured } = extractParameterInfo(decl, sym.name);
+	const typeStr = checker.typeToString(type);
+	let passingStyle;
+	if (isDestructured) passingStyle = "options_object";
+	else {
+		const resolvedType = checker.getTypeOfSymbolAtLocation(sym, decl);
+		const isObjectLike = resolvedType.isClassOrInterface() || (resolvedType.getFlags() & ts.TypeFlags.Object) !== 0;
+		const isPrimitive = [
+			"string",
+			"number",
+			"boolean",
+			"undefined",
+			"null",
+			"void",
+			"never",
+			"any",
+			"unknown"
+		].includes(typeStr);
+		if (isObjectLike && !isPrimitive && !typeStr.startsWith("Promise<")) passingStyle = "options_object";
+		else passingStyle = "positional";
+	}
 	return {
-		name: extractParameterName(decl, sym.name),
-		type: checker.typeToString(type),
-		optional: isOptional
+		name,
+		type: typeStr,
+		optional: isOptional,
+		passingStyle
 	};
 }
-function extractParameterName(decl, fallback) {
-	if (!decl || !ts.isParameter(decl)) return fallback;
-	if (ts.isIdentifier(decl.name)) return decl.name.text;
+function extractParameterInfo(decl, fallback) {
+	if (!decl || !ts.isParameter(decl)) return {
+		name: fallback,
+		isDestructured: false
+	};
+	if (ts.isIdentifier(decl.name)) return {
+		name: decl.name.text,
+		isDestructured: false
+	};
 	const index = decl.parent.parameters?.indexOf(decl) ?? -1;
 	const suffix = index > 0 ? String(index) : "";
-	if (ts.isObjectBindingPattern(decl.name)) return `options${suffix}`;
-	if (ts.isArrayBindingPattern(decl.name)) return `args${suffix}`;
-	return fallback;
+	if (ts.isObjectBindingPattern(decl.name)) return {
+		name: `options${suffix}`,
+		isDestructured: true
+	};
+	if (ts.isArrayBindingPattern(decl.name)) return {
+		name: `args${suffix}`,
+		isDestructured: false
+	};
+	return {
+		name: fallback,
+		isDestructured: false
+	};
 }
 function extractInterface(sym, checker) {
 	const type = checker.getDeclaredTypeOfSymbol(sym);
@@ -726,7 +986,8 @@ function buildSurface$6(allClasses, hints) {
 			const params = method.params.map((p) => ({
 				name: p.name,
 				type: p.type,
-				optional: p.optional
+				optional: p.optional,
+				passingStyle: "named"
 			}));
 			if (!apiMethods[method.name]) apiMethods[method.name] = [];
 			apiMethods[method.name].push({
@@ -868,6 +1129,9 @@ function createPhpExtractor(hintOverrides) {
 	return {
 		language: "php",
 		hints: mergedHints,
+		async extractSnapshot(sdkPath) {
+			return apiSurfaceToSnapshot(await this.extract(sdkPath));
+		},
 		async extract(sdkPath) {
 			let sourceDir;
 			const libPath = resolve(sdkPath, "lib");
@@ -1059,6 +1323,7 @@ function extractFunctionParams(paramsNode, skipFirst) {
 	if (!paramsNode) return [];
 	const params = [];
 	let skippedFirst = false;
+	let seenStarMarker = false;
 	for (const child of paramsNode.namedChildren) {
 		if (!skippedFirst && !skipFirst && child.type === "identifier" && (child.text === "self" || child.text === "cls")) {
 			skippedFirst = true;
@@ -1068,13 +1333,18 @@ function extractFunctionParams(paramsNode, skipFirst) {
 			skippedFirst = true;
 			continue;
 		}
-		if (child.text === "*") continue;
+		if (child.text === "*") {
+			seenStarMarker = true;
+			continue;
+		}
 		if (child.type === "list_splat_pattern") {
+			seenStarMarker = true;
 			const nameNode = child.namedChildren.find((c) => c.type === "identifier");
 			params.push({
 				name: nameNode ? `*${nameNode.text}` : "*args",
 				type: "",
-				optional: true
+				optional: true,
+				passingStyle: "positional"
 			});
 			continue;
 		}
@@ -1083,17 +1353,20 @@ function extractFunctionParams(paramsNode, skipFirst) {
 			params.push({
 				name: nameNode ? `**${nameNode.text}` : "**kwargs",
 				type: "",
-				optional: true
+				optional: true,
+				passingStyle: "keyword"
 			});
 			continue;
 		}
+		const passingStyle = seenStarMarker ? "keyword" : "keyword_or_positional";
 		if (child.type === "typed_parameter") {
 			const nameNode = child.namedChildren.find((c) => c.type === "identifier");
 			const typeNode = child.childForFieldName("type");
 			if (nameNode) params.push({
 				name: nameNode.text,
 				type: typeNode ? typeNode.text : "",
-				optional: false
+				optional: false,
+				passingStyle
 			});
 		} else if (child.type === "typed_default_parameter") {
 			const nameNode = child.childForFieldName("name");
@@ -1101,19 +1374,22 @@ function extractFunctionParams(paramsNode, skipFirst) {
 			if (nameNode) params.push({
 				name: nameNode.text,
 				type: typeNode ? typeNode.text : "",
-				optional: true
+				optional: true,
+				passingStyle
 			});
 		} else if (child.type === "default_parameter") {
 			const nameNode = child.childForFieldName("name");
 			if (nameNode) params.push({
 				name: nameNode.text,
 				type: "",
-				optional: true
+				optional: true,
+				passingStyle
 			});
 		} else if (child.type === "identifier") params.push({
 			name: child.text,
 			type: "",
-			optional: false
+			optional: false,
+			passingStyle
 		});
 	}
 	return params;
@@ -1333,7 +1609,8 @@ function buildSurface$5(parsedFiles, hints) {
 					const params = method.params.map((p) => ({
 						name: p.name,
 						type: p.type,
-						optional: p.optional
+						optional: p.optional,
+						...p.passingStyle ? { passingStyle: p.passingStyle } : {}
 					}));
 					const returnType = unwrapReturnType(method.returnType);
 					if (!apiMethods[method.name]) apiMethods[method.name] = [];
@@ -1394,7 +1671,8 @@ function buildSurface$5(parsedFiles, hints) {
 					const params = method.params.map((p) => ({
 						name: p.name,
 						type: p.type,
-						optional: p.optional
+						optional: p.optional,
+						...p.passingStyle ? { passingStyle: p.passingStyle } : {}
 					}));
 					if (!apiMethods[method.name]) apiMethods[method.name] = [];
 					apiMethods[method.name].push({
@@ -1428,14 +1706,16 @@ function buildSurface$5(parsedFiles, hints) {
 						constructorParams.push(...method.params.map((p) => ({
 							name: p.name,
 							type: p.type,
-							optional: p.optional
+							optional: p.optional,
+							...p.passingStyle ? { passingStyle: p.passingStyle } : {}
 						})));
 						continue;
 					}
 					const params = method.params.map((p) => ({
 						name: p.name,
 						type: p.type,
-						optional: p.optional
+						optional: p.optional,
+						...p.passingStyle ? { passingStyle: p.passingStyle } : {}
 					}));
 					if (!apiMethods[method.name]) apiMethods[method.name] = [];
 					apiMethods[method.name].push({
@@ -1712,6 +1992,9 @@ function createPythonExtractor(hintOverrides) {
 	return {
 		language: "python",
 		hints: mergedHints,
+		async extractSnapshot(sdkPath) {
+			return apiSurfaceToSnapshot(await this.extract(sdkPath));
+		},
 		async extract(sdkPath) {
 			const sourceRoot = findPythonSourceRoot(sdkPath);
 			if (!sourceRoot) throw new ExtractorError(`No Python package found in ${sdkPath}`, `Ensure the --sdk-path argument points to a Python project root containing a package directory with __init__.py.`);
@@ -1908,7 +2191,8 @@ function extractMethodParams(methodNode) {
 			params.push({
 				name: paramNode.text,
 				type: "Object",
-				optional: false
+				optional: false,
+				passingStyle: "positional"
 			});
 			break;
 		case "optional_parameter": {
@@ -1916,7 +2200,8 @@ function extractMethodParams(methodNode) {
 			if (nameNode) params.push({
 				name: nameNode.text,
 				type: "Object",
-				optional: true
+				optional: true,
+				passingStyle: "positional"
 			});
 			break;
 		}
@@ -1927,7 +2212,8 @@ function extractMethodParams(methodNode) {
 				params.push({
 					name: nameNode.text,
 					type: "Object",
-					optional: valueNode !== null
+					optional: valueNode !== null,
+					passingStyle: "keyword"
 				});
 			}
 			break;
@@ -1937,7 +2223,8 @@ function extractMethodParams(methodNode) {
 			params.push({
 				name: nameNode ? `*${nameNode.text}` : "*args",
 				type: "Object",
-				optional: true
+				optional: true,
+				passingStyle: "positional"
 			});
 			break;
 		}
@@ -1946,7 +2233,8 @@ function extractMethodParams(methodNode) {
 			params.push({
 				name: nameNode ? `**${nameNode.text}` : "**kwargs",
 				type: "Object",
-				optional: true
+				optional: true,
+				passingStyle: "keyword"
 			});
 			break;
 		}
@@ -1955,7 +2243,8 @@ function extractMethodParams(methodNode) {
 			params.push({
 				name: nameNode ? `&${nameNode.text}` : "&block",
 				type: "Object",
-				optional: true
+				optional: true,
+				passingStyle: "positional"
 			});
 			break;
 		}
@@ -2095,6 +2384,9 @@ function collectRbFiles(dir) {
 const rubyExtractor = {
 	language: "ruby",
 	hints: rubyHints,
+	async extractSnapshot(sdkPath) {
+		return apiSurfaceToSnapshot(await this.extract(sdkPath));
+	},
 	async extract(sdkPath) {
 		const libPath = resolve(sdkPath, "lib");
 		try {
@@ -2526,7 +2818,8 @@ function buildSurface$4(allStructs, allTypes, allFuncs, allConsts) {
 				const params = fn.params.filter((p) => p.type !== "context.Context").map((p) => ({
 					name: p.name,
 					type: goTypeToString(p.type),
-					optional: false
+					optional: false,
+					passingStyle: "positional"
 				}));
 				if (!apiMethods[fn.name]) apiMethods[fn.name] = [];
 				apiMethods[fn.name].push({
@@ -2683,6 +2976,9 @@ const goExtractor = {
 			return false;
 		}
 	},
+	async extractSnapshot(sdkPath) {
+		return apiSurfaceToSnapshot(await this.extract(sdkPath));
+	},
 	async extract(sdkPath) {
 		const goFiles = walkGoFiles(sdkPath);
 		if (goFiles.length === 0) throw new ExtractorError(`No .go files found in ${sdkPath}`, `Ensure the --sdk-path argument points to a Go project root containing .go source files.`);
@@ -3014,7 +3310,8 @@ function buildSurface$3(allStructs, allEnums, allFuncs, allTraits, allTypeAliase
 				const params = fn.params.map((p) => ({
 					name: p.name,
 					type: rustTypeToString(p.type),
-					optional: p.type.startsWith("Option<")
+					optional: p.type.startsWith("Option<"),
+					passingStyle: "positional"
 				}));
 				const returnType = unwrapResultType(fn.returnType);
 				if (!apiMethods[fn.name]) apiMethods[fn.name] = [];
@@ -3171,6 +3468,9 @@ const rustExtractor = {
 			return [`${modelName}Response`];
 		}
 	},
+	async extractSnapshot(sdkPath) {
+		return apiSurfaceToSnapshot(await this.extract(sdkPath));
+	},
 	async extract(sdkPath) {
 		const rsFiles = walkRustFiles(sdkPath);
 		if (rsFiles.length === 0) throw new ExtractorError(`No .rs files found in ${sdkPath}`, `Ensure the --sdk-path argument points to a Rust project root containing .rs source files.`);
@@ -3496,7 +3796,8 @@ function buildSurface$2(allDataClasses, allClasses, allEnums, allTypeAliases) {
 			const params = method.params.map((p) => ({
 				name: p.name,
 				type: p.type,
-				optional: p.optional
+				optional: p.optional,
+				passingStyle: "named"
 			}));
 			if (!methods[method.name]) methods[method.name] = [];
 			methods[method.name].push({
@@ -3509,7 +3810,8 @@ function buildSurface$2(allDataClasses, allClasses, allEnums, allTypeAliases) {
 		const constructorParams = cls.constructorParams.map((p) => ({
 			name: p.name,
 			type: p.type,
-			optional: false
+			optional: false,
+			passingStyle: "named"
 		}));
 		classes[cls.name] = {
 			name: cls.name,
@@ -3604,6 +3906,9 @@ const kotlinExtractor = {
 			return [`${modelName}Response`];
 		}
 	},
+	async extractSnapshot(sdkPath) {
+		return apiSurfaceToSnapshot(await this.extract(sdkPath));
+	},
 	async extract(sdkPath) {
 		const ktFiles = walkKotlinFiles(sdkPath);
 		if (ktFiles.length === 0) throw new ExtractorError(`No .kt files found in ${sdkPath}`, `Ensure the --sdk-path argument points to a Kotlin project root containing .kt source files.`);
@@ -3859,7 +4164,8 @@ function buildSurface$1(allClasses, allEnums, _hints) {
 				const params = method.params.map((p) => ({
 					name: p.name,
 					type: p.type,
-					optional: p.optional
+					optional: p.optional,
+					passingStyle: "named"
 				}));
 				if (!methods[method.name]) methods[method.name] = [];
 				methods[method.name].push({
@@ -3880,7 +4186,8 @@ function buildSurface$1(allClasses, allEnums, _hints) {
 			const constructorParams = cls.constructorParams.map((p) => ({
 				name: p.name,
 				type: p.type,
-				optional: false
+				optional: false,
+				passingStyle: "named"
 			}));
 			classes[cls.name] = {
 				name: cls.name,
@@ -4095,6 +4402,9 @@ function createDotnetExtractor(hintOverrides) {
 	return {
 		language: "dotnet",
 		hints: mergedHints,
+		async extractSnapshot(sdkPath) {
+			return apiSurfaceToSnapshot(await this.extract(sdkPath));
+		},
 		async extract(sdkPath) {
 			let sourceDir;
 			const srcPath = resolve(sdkPath, "src");
@@ -4273,11 +4583,17 @@ function extractFunctions(modules, sourceFile) {
 			const paramsStr = funcMatch[3] || "";
 			if (name === "defstruct" || name === "defmodule") continue;
 			const params = [];
+			const paramStyles = [];
 			if (paramsStr.trim()) {
 				const paramParts = paramsStr.split(",");
 				for (const part of paramParts) {
-					const paramNameMatch = part.trim().match(/^(\w+)/);
-					if (paramNameMatch) params.push(paramNameMatch[1]);
+					const trimmed = part.trim();
+					const paramNameMatch = trimmed.match(/^(\w+)/);
+					if (paramNameMatch) {
+						params.push(paramNameMatch[1]);
+						const isKeywordList = /\\\\\s*\[/.test(trimmed);
+						paramStyles.push(isKeywordList ? "keyword" : "positional");
+					}
 				}
 			}
 			functions.push({
@@ -4285,6 +4601,7 @@ function extractFunctions(modules, sourceFile) {
 				name,
 				arity: params.length,
 				params,
+				paramStyles,
 				isPrivate,
 				sourceFile
 			});
@@ -4445,10 +4762,11 @@ function buildSurface(allStructs, allFunctions, allEnumModules, allTypeSpecs) {
 		for (const func of funcs) {
 			if (seenFuncs.has(func.name)) continue;
 			seenFuncs.add(func.name);
-			const params = func.params.map((p) => ({
+			const params = func.params.map((p, i) => ({
 				name: p,
 				type: "any",
-				optional: false
+				optional: false,
+				passingStyle: func.paramStyles[i] ?? "positional"
 			}));
 			if (!methods[func.name]) methods[func.name] = [];
 			methods[func.name].push({
@@ -4544,6 +4862,9 @@ const elixirExtractor = {
 			return [`${modelName}Response`];
 		}
 	},
+	async extractSnapshot(sdkPath) {
+		return apiSurfaceToSnapshot(await this.extract(sdkPath));
+	},
 	async extract(sdkPath) {
 		let sourceDir;
 		const libPath = resolve(sdkPath, "lib");
@@ -4580,6 +4901,6 @@ const elixirExtractor = {
 	}
 };
 //#endregion
-export { buildOverlayLookup, diffSurfaces, dotnetExtractor, elixirExtractor, filterSurface, getExtractor, goExtractor, kotlinExtractor, nodeExtractor, nodeHints, patchOverlay, phpExtractor, pythonExtractor, registerExtractor, resolveHints, rubyExtractor, rustExtractor, specDerivedEnumValues, specDerivedFieldPaths, specDerivedHttpKeys, specDerivedMethodPaths, specDerivedNames };
+export { ALL_LANGUAGE_IDS, COMPAT_SCHEMA_VERSION, apiSurfaceToSnapshot, applyApprovals, buildConceptualRollup, buildOverlayLookup, classifyAddedSymbol, classifySymbolChanges, defaultSeverityForCategory, diffSnapshots, diffSurfaces, dotnetExtractor, elixirExtractor, filterSurface, formatConceptualSummary, formatHumanSummary, generateConceptualReport, generateReport, getDefaultPolicy, getExtractor, goExtractor, highestSeverity, isCompatibleSchemaVersion, isPatchableChange, kotlinExtractor, matchApproval, mergePolicy, nodeExtractor, nodeHints, patchOverlay, phpExtractor, pythonExtractor, registerExtractor, resolveHints, rubyExtractor, rustExtractor, severityMeetsThreshold, specDerivedEnumValues, specDerivedFieldPaths, specDerivedHttpKeys, specDerivedMethodPaths, specDerivedNames, summarizeChanges, summarizeConceptualChanges, unapprovedChanges, validateApproval, validateApprovals, validateSnapshot };
 
 //# sourceMappingURL=index.mjs.map