@workos/oagen 0.9.0 → 0.9.1

package/dist/cli/index.mjs

@@ -6313,12 +6313,351 @@ async function extractCommand(opts) {
 	console.log(`Extracted ${symbolCount} symbols → ${opts.output}`);
 }
 //#endregion
+//#region src/compat/policy.ts
+/** Built-in language defaults. */
+const LANGUAGE_DEFAULTS = {
+	php: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	},
+	python: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	},
+	ruby: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	},
+	go: {
+		callerUsesParamNames: false,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: false,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: true
+	},
+	kotlin: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: true,
+		arityIsPublicApi: false
+	},
+	dotnet: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: true,
+		arityIsPublicApi: false
+	},
+	elixir: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: true
+	},
+	rust: {
+		callerUsesParamNames: false,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: false,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: true
+	},
+	node: {
+		callerUsesParamNames: false,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: false,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	}
+};
+/** Get the built-in default policy for a language. */
+function getDefaultPolicy(language) {
+	return { ...LANGUAGE_DEFAULTS[language] };
+}
+/** Merge user overrides onto language defaults. Only provided keys are overridden. */
+function mergePolicy(defaults, overrides) {
+	return {
+		...defaults,
+		...overrides
+	};
+}
+//#endregion
+//#region src/compat/schema.ts
+/** Validate the basic structure of a parsed compat snapshot. */
+function validateSnapshot(data) {
+	if (typeof data !== "object" || data === null) return false;
+	const obj = data;
+	return typeof obj.schemaVersion === "string" && typeof obj.source === "object" && obj.source !== null && typeof obj.policies === "object" && obj.policies !== null && Array.isArray(obj.symbols);
+}
+//#endregion
+//#region src/compat/ir.ts
+/**
+* Convert a legacy ApiSurface to a CompatSnapshot.
+*
+* This bridge allows existing extractors (which produce ApiSurface) to feed
+* into the new classified diff engine without requiring immediate migration.
+*/
+function apiSurfaceToSnapshot(surface) {
+	const language = surface.language || "node";
+	const symbols = [];
+	for (const [className, cls] of Object.entries(surface.classes)) {
+		symbols.push({
+			id: `class:${className}`,
+			kind: "service_accessor",
+			fqName: className,
+			displayName: className,
+			visibility: "public",
+			stability: cls.deprecationMessage ? "deprecated" : "stable",
+			sourceKind: "generated_service_wrapper"
+		});
+		if (cls.constructorParams.length > 0) symbols.push({
+			id: `ctor:${className}`,
+			kind: "constructor",
+			fqName: `${className}.constructor`,
+			ownerFqName: className,
+			displayName: `new ${className}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor",
+			parameters: cls.constructorParams.map((p, i) => apiParamToCompatParam(p, i, language))
+		});
+		for (const [methodName, overloads] of Object.entries(cls.methods)) for (let oi = 0; oi < overloads.length; oi++) {
+			const method = overloads[oi];
+			const suffix = overloads.length > 1 ? `#${oi}` : "";
+			symbols.push({
+				id: `method:${className}.${methodName}${suffix}`,
+				kind: "callable",
+				fqName: `${className}.${methodName}`,
+				ownerFqName: className,
+				displayName: `${className}.${methodName}`,
+				visibility: "public",
+				stability: "stable",
+				sourceKind: "generated_service_wrapper",
+				parameters: method.params.map((p, i) => apiParamToCompatParam(p, i, language)),
+				returns: { name: method.returnType }
+			});
+		}
+		for (const [propName, prop] of Object.entries(cls.properties)) symbols.push({
+			id: `prop:${className}.${propName}`,
+			kind: "property",
+			fqName: `${className}.${propName}`,
+			ownerFqName: className,
+			displayName: `${className}.${propName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_service_wrapper",
+			typeRef: { name: prop.type }
+		});
+	}
+	for (const [ifaceName, iface] of Object.entries(surface.interfaces)) {
+		symbols.push({
+			id: `iface:${ifaceName}`,
+			kind: "alias",
+			fqName: ifaceName,
+			displayName: ifaceName,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor"
+		});
+		for (const [fieldName, field] of Object.entries(iface.fields)) symbols.push({
+			id: `field:${ifaceName}.${fieldName}`,
+			kind: "field",
+			fqName: `${ifaceName}.${fieldName}`,
+			ownerFqName: ifaceName,
+			displayName: `${ifaceName}.${fieldName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor",
+			typeRef: { name: field.type }
+		});
+		if (iface.hasCustomConstructor) symbols.push({
+			id: `ctor:${ifaceName}`,
+			kind: "constructor",
+			fqName: `${ifaceName}.constructor`,
+			ownerFqName: ifaceName,
+			displayName: `new ${ifaceName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor"
+		});
+	}
+	for (const [aliasName] of Object.entries(surface.typeAliases)) symbols.push({
+		id: `alias:${aliasName}`,
+		kind: "alias",
+		fqName: aliasName,
+		displayName: aliasName,
+		visibility: "public",
+		stability: "stable",
+		sourceKind: "generated_resource_constructor"
+	});
+	for (const [enumName, enumDef] of Object.entries(surface.enums)) {
+		symbols.push({
+			id: `enum:${enumName}`,
+			kind: "enum",
+			fqName: enumName,
+			displayName: enumName,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_enum"
+		});
+		for (const [memberName, memberValue] of Object.entries(enumDef.members)) symbols.push({
+			id: `enum_member:${enumName}.${memberName}`,
+			kind: "enum_member",
+			fqName: `${enumName}.${memberName}`,
+			ownerFqName: enumName,
+			displayName: `${enumName}.${memberName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_enum",
+			value: memberValue
+		});
+	}
+	return {
+		schemaVersion: "1",
+		source: { extractedAt: surface.extractedAt },
+		policies: getDefaultPolicy(language),
+		symbols
+	};
+}
+/** Convert a legacy ApiParam to a CompatParameter. */
+function apiParamToCompatParam(param, position, language) {
+	const policy = getDefaultPolicy(language);
+	return {
+		publicName: param.name,
+		position,
+		required: !param.optional,
+		nullable: false,
+		hasDefault: param.optional,
+		passing: param.passingStyle ?? inferPassingStyle(language),
+		type: { name: param.type },
+		sensitivity: {
+			order: policy.constructorOrderMatters,
+			publicName: policy.methodParameterNamesArePublicApi,
+			requiredness: true,
+			type: true
+		}
+	};
+}
+/** Infer the default parameter passing style for a language. */
+function inferPassingStyle(language) {
+	switch (language) {
+		case "python":
+		case "ruby":
+		case "elixir": return "keyword";
+		case "php":
+		case "kotlin":
+		case "dotnet": return "named";
+		case "node": return "options_object";
+		default: return "positional";
+	}
+}
+//#endregion
 //#region src/cli/compat-extract.ts
 const SNAPSHOT_FILENAME = ".oagen-compat-snapshot.json";
+/** Normalize a name for case-insensitive matching: strip underscores and lowercase. */
+function normalize(name) {
+	return name.replace(/_/g, "").toLowerCase();
+}
+/**
+* Build a map of normalized service name → Set of generated method names
+* from the manifest's operations record.
+*/
+function buildServiceMethodMap(operations) {
+	const result = /* @__PURE__ */ new Map();
+	for (const value of Object.values(operations)) {
+		if (typeof value !== "object" || value === null) continue;
+		const { sdkMethod, service } = value;
+		if (typeof sdkMethod !== "string" || typeof service !== "string") continue;
+		const key = normalize(service);
+		if (!result.has(key)) result.set(key, /* @__PURE__ */ new Set());
+		result.get(key).add(sdkMethod);
+	}
+	return result;
+}
+/**
+* Filter an ApiSurface to only include generated symbols based on the manifest.
+*
+* Two levels of filtering:
+*  1. File-level: classes/interfaces/enums from files not in the manifest are
+*     dropped entirely (they are wholly hand-written).
+*  2. Method-level: for service classes (those whose name matches a manifest
+*     service), only methods listed in the manifest operations are kept.
+*     Constructors and properties are always preserved since they are structural.
+*     Non-service classes (models, enums, etc.) keep all their symbols.
+*/
+function filterSurfaceByManifest(surface, manifest) {
+	const manifestFiles = new Set(manifest.files);
+	const serviceMethodMap = manifest.operations ? buildServiceMethodMap(manifest.operations) : /* @__PURE__ */ new Map();
+	let filesExcluded = 0;
+	let methodsExcluded = 0;
+	const filterByFile = (record) => {
+		const result = {};
+		for (const [name, entry] of Object.entries(record)) if (entry.sourceFile && manifestFiles.has(entry.sourceFile)) result[name] = entry;
+		else filesExcluded++;
+		return result;
+	};
+	const filteredClasses = {};
+	for (const [name, cls] of Object.entries(surface.classes)) {
+		if (cls.sourceFile && !manifestFiles.has(cls.sourceFile)) {
+			filesExcluded++;
+			continue;
+		}
+		const generatedMethods = serviceMethodMap.get(normalize(name));
+		if (generatedMethods) {
+			const methods = {};
+			for (const [methodName, overloads] of Object.entries(cls.methods)) if (generatedMethods.has(methodName)) methods[methodName] = overloads;
+			else methodsExcluded++;
+			filteredClasses[name] = {
+				...cls,
+				methods
+			};
+		} else filteredClasses[name] = cls;
+	}
+	const filteredExports = {};
+	for (const [filePath, symbols] of Object.entries(surface.exports)) if (manifestFiles.has(filePath)) filteredExports[filePath] = symbols;
+	return {
+		filtered: {
+			...surface,
+			classes: filteredClasses,
+			interfaces: filterByFile(surface.interfaces),
+			typeAliases: filterByFile(surface.typeAliases),
+			enums: filterByFile(surface.enums),
+			exports: filteredExports
+		},
+		filesExcluded,
+		methodsExcluded
+	};
+}
 async function compatExtractCommand(opts) {
 	const extractor = getExtractor(opts.lang);
 	console.log(`Extracting ${opts.lang} compat snapshot from ${opts.sdkPath}...`);
-	const snapshot = await extractor.extractSnapshot(opts.sdkPath);
+	let surface = await extractor.extract(opts.sdkPath);
+	const manifest = await readManifest(opts.sdkPath);
+	if (manifest) {
+		const { filtered, filesExcluded, methodsExcluded } = filterSurfaceByManifest(surface, manifest);
+		surface = filtered;
+		if (filesExcluded > 0 || methodsExcluded > 0) console.log(`Manifest filter: excluded ${filesExcluded} hand-written file(s), ${methodsExcluded} hand-written method(s)`);
+	}
+	const snapshot = apiSurfaceToSnapshot(surface);
 	if (opts.spec) {
 		const specContent = readFileSync(opts.spec, "utf-8");
 		snapshot.source.specSha = createHash("sha256").update(specContent).digest("hex");
@@ -6349,20 +6688,12 @@ function enrichWithSpecContext(snapshot, spec) {
 		const match = opLookup.get(sym.fqName);
 		if (match) {
 			sym.operationId = match.operationId;
-			sym.route = {
-				method: match.method,
-				path: match.path
-			};
-		}
-	}
-}
-//#endregion
-//#region src/compat/schema.ts
-/** Validate the basic structure of a parsed compat snapshot. */
-function validateSnapshot(data) {
-	if (typeof data !== "object" || data === null) return false;
-	const obj = data;
-	return typeof obj.schemaVersion === "string" && typeof obj.source === "object" && obj.source !== null && typeof obj.policies === "object" && obj.policies !== null && Array.isArray(obj.symbols);
+			sym.route = {
+				method: match.method,
+				path: match.path
+			};
+		}
+	}
 }
 //#endregion
 //#region src/compat/config.ts
@@ -7150,256 +7481,6 @@ function narrowingMatches(match, change) {
 	return true;
 }
 //#endregion
-//#region src/compat/policy.ts
-/** Built-in language defaults. */
-const LANGUAGE_DEFAULTS = {
-	php: {
-		callerUsesParamNames: true,
-		constructorOrderMatters: true,
-		methodParameterNamesArePublicApi: true,
-		constructorParameterNamesArePublicApi: true,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: false
-	},
-	python: {
-		callerUsesParamNames: true,
-		constructorOrderMatters: true,
-		methodParameterNamesArePublicApi: true,
-		constructorParameterNamesArePublicApi: true,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: false
-	},
-	ruby: {
-		callerUsesParamNames: true,
-		constructorOrderMatters: true,
-		methodParameterNamesArePublicApi: true,
-		constructorParameterNamesArePublicApi: true,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: false
-	},
-	go: {
-		callerUsesParamNames: false,
-		constructorOrderMatters: true,
-		methodParameterNamesArePublicApi: false,
-		constructorParameterNamesArePublicApi: false,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: true
-	},
-	kotlin: {
-		callerUsesParamNames: true,
-		constructorOrderMatters: false,
-		methodParameterNamesArePublicApi: true,
-		constructorParameterNamesArePublicApi: true,
-		overloadsArePublicApi: true,
-		arityIsPublicApi: false
-	},
-	dotnet: {
-		callerUsesParamNames: true,
-		constructorOrderMatters: false,
-		methodParameterNamesArePublicApi: true,
-		constructorParameterNamesArePublicApi: true,
-		overloadsArePublicApi: true,
-		arityIsPublicApi: false
-	},
-	elixir: {
-		callerUsesParamNames: true,
-		constructorOrderMatters: false,
-		methodParameterNamesArePublicApi: true,
-		constructorParameterNamesArePublicApi: false,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: true
-	},
-	rust: {
-		callerUsesParamNames: false,
-		constructorOrderMatters: true,
-		methodParameterNamesArePublicApi: false,
-		constructorParameterNamesArePublicApi: false,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: true
-	},
-	node: {
-		callerUsesParamNames: false,
-		constructorOrderMatters: false,
-		methodParameterNamesArePublicApi: false,
-		constructorParameterNamesArePublicApi: false,
-		overloadsArePublicApi: false,
-		arityIsPublicApi: false
-	}
-};
-/** Get the built-in default policy for a language. */
-function getDefaultPolicy(language) {
-	return { ...LANGUAGE_DEFAULTS[language] };
-}
-/** Merge user overrides onto language defaults. Only provided keys are overridden. */
-function mergePolicy(defaults, overrides) {
-	return {
-		...defaults,
-		...overrides
-	};
-}
-//#endregion
-//#region src/compat/ir.ts
-/**
-* Convert a legacy ApiSurface to a CompatSnapshot.
-*
-* This bridge allows existing extractors (which produce ApiSurface) to feed
-* into the new classified diff engine without requiring immediate migration.
-*/
-function apiSurfaceToSnapshot(surface) {
-	const language = surface.language || "node";
-	const symbols = [];
-	for (const [className, cls] of Object.entries(surface.classes)) {
-		symbols.push({
-			id: `class:${className}`,
-			kind: "service_accessor",
-			fqName: className,
-			displayName: className,
-			visibility: "public",
-			stability: cls.deprecationMessage ? "deprecated" : "stable",
-			sourceKind: "generated_service_wrapper"
-		});
-		if (cls.constructorParams.length > 0) symbols.push({
-			id: `ctor:${className}`,
-			kind: "constructor",
-			fqName: `${className}.constructor`,
-			ownerFqName: className,
-			displayName: `new ${className}`,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_resource_constructor",
-			parameters: cls.constructorParams.map((p, i) => apiParamToCompatParam(p, i, language))
-		});
-		for (const [methodName, overloads] of Object.entries(cls.methods)) for (let oi = 0; oi < overloads.length; oi++) {
-			const method = overloads[oi];
-			const suffix = overloads.length > 1 ? `#${oi}` : "";
-			symbols.push({
-				id: `method:${className}.${methodName}${suffix}`,
-				kind: "callable",
-				fqName: `${className}.${methodName}`,
-				ownerFqName: className,
-				displayName: `${className}.${methodName}`,
-				visibility: "public",
-				stability: "stable",
-				sourceKind: "generated_service_wrapper",
-				parameters: method.params.map((p, i) => apiParamToCompatParam(p, i, language)),
-				returns: { name: method.returnType }
-			});
-		}
-		for (const [propName, prop] of Object.entries(cls.properties)) symbols.push({
-			id: `prop:${className}.${propName}`,
-			kind: "property",
-			fqName: `${className}.${propName}`,
-			ownerFqName: className,
-			displayName: `${className}.${propName}`,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_service_wrapper",
-			typeRef: { name: prop.type }
-		});
-	}
-	for (const [ifaceName, iface] of Object.entries(surface.interfaces)) {
-		symbols.push({
-			id: `iface:${ifaceName}`,
-			kind: "alias",
-			fqName: ifaceName,
-			displayName: ifaceName,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_resource_constructor"
-		});
-		for (const [fieldName, field] of Object.entries(iface.fields)) symbols.push({
-			id: `field:${ifaceName}.${fieldName}`,
-			kind: "field",
-			fqName: `${ifaceName}.${fieldName}`,
-			ownerFqName: ifaceName,
-			displayName: `${ifaceName}.${fieldName}`,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_resource_constructor",
-			typeRef: { name: field.type }
-		});
-		if (iface.hasCustomConstructor) symbols.push({
-			id: `ctor:${ifaceName}`,
-			kind: "constructor",
-			fqName: `${ifaceName}.constructor`,
-			ownerFqName: ifaceName,
-			displayName: `new ${ifaceName}`,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_resource_constructor"
-		});
-	}
-	for (const [aliasName] of Object.entries(surface.typeAliases)) symbols.push({
-		id: `alias:${aliasName}`,
-		kind: "alias",
-		fqName: aliasName,
-		displayName: aliasName,
-		visibility: "public",
-		stability: "stable",
-		sourceKind: "generated_resource_constructor"
-	});
-	for (const [enumName, enumDef] of Object.entries(surface.enums)) {
-		symbols.push({
-			id: `enum:${enumName}`,
-			kind: "enum",
-			fqName: enumName,
-			displayName: enumName,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_enum"
-		});
-		for (const [memberName, memberValue] of Object.entries(enumDef.members)) symbols.push({
-			id: `enum_member:${enumName}.${memberName}`,
-			kind: "enum_member",
-			fqName: `${enumName}.${memberName}`,
-			ownerFqName: enumName,
-			displayName: `${enumName}.${memberName}`,
-			visibility: "public",
-			stability: "stable",
-			sourceKind: "generated_enum",
-			value: memberValue
-		});
-	}
-	return {
-		schemaVersion: "1",
-		source: { extractedAt: surface.extractedAt },
-		policies: getDefaultPolicy(language),
-		symbols
-	};
-}
-/** Convert a legacy ApiParam to a CompatParameter. */
-function apiParamToCompatParam(param, position, language) {
-	const policy = getDefaultPolicy(language);
-	return {
-		publicName: param.name,
-		position,
-		required: !param.optional,
-		nullable: false,
-		hasDefault: param.optional,
-		passing: param.passingStyle ?? inferPassingStyle(language),
-		type: { name: param.type },
-		sensitivity: {
-			order: policy.constructorOrderMatters,
-			publicName: policy.methodParameterNamesArePublicApi,
-			requiredness: true,
-			type: true
-		}
-	};
-}
-/** Infer the default parameter passing style for a language. */
-function inferPassingStyle(language) {
-	switch (language) {
-		case "python":
-		case "ruby":
-		case "elixir": return "keyword";
-		case "php":
-		case "kotlin":
-		case "dotnet": return "named";
-		case "node": return "options_object";
-		default: return "positional";
-	}
-}
-//#endregion
 //#region src/verify/run-compat-check.ts
 async function runCompatCheck(baseline, outputDir, lang, spec, policyOverrides) {
 	const extractor = getExtractor(lang);