@workos/oagen 0.9.2 → 0.10.1

package/dist/cli/index.mjs

@@ -6661,17 +6661,21 @@ async function compatExtractCommand(opts) {
 	if (opts.spec) {
 		const specContent = readFileSync(opts.spec, "utf-8");
 		snapshot.source.specSha = createHash("sha256").update(specContent).digest("hex");
-		enrichWithSpecContext(snapshot, await parseSpec(opts.spec));
+		enrichWithSpecContext(snapshot, await parseSpec(opts.spec, { schemaNameTransform: opts.schemaNameTransform }));
 	}
 	const outputPath = resolve(opts.output, SNAPSHOT_FILENAME);
 	writeFileSync(outputPath, JSON.stringify(snapshot, null, 2));
 	console.log(`Extracted ${snapshot.symbols.length} symbols → ${outputPath}`);
 }
 /**
-* Enrich snapshot symbols with operationId and route from the parsed spec.
+* Enrich snapshot symbols with spec-level identity.
 *
-* Matches callable symbols to spec operations by comparing method names
-* derived from the spec against the symbol's fqName.
+* - Callable symbols get `operationId` and `route` from spec operations.
+* - Property/field/constructor/service_accessor symbols get `schemaName`
+*   from spec models, enabling cross-language grouping in reports.
+*
+* The `schemaName` uses the spec-level identity (e.g. "GenerateLinkBody.admin_emails")
+* which is the same regardless of the language's naming conventions.
 */
 function enrichWithSpecContext(snapshot, spec) {
 	const opLookup = /* @__PURE__ */ new Map();
@@ -6683,15 +6687,38 @@ function enrichWithSpecContext(snapshot, spec) {
 			path: op.path
 		});
 	}
+	const norm = (s) => s.replace(/_/g, "").toLowerCase();
+	const modelLookup = /* @__PURE__ */ new Map();
+	for (const model of spec.models) {
+		const fieldMap = /* @__PURE__ */ new Map();
+		for (const field of model.fields) fieldMap.set(norm(field.name), field.name);
+		modelLookup.set(norm(model.name), {
+			specName: model.name,
+			fields: fieldMap
+		});
+	}
 	for (const sym of snapshot.symbols) {
-		if (sym.kind !== "callable") continue;
-		const match = opLookup.get(sym.fqName);
-		if (match) {
-			sym.operationId = match.operationId;
-			sym.route = {
-				method: match.method,
-				path: match.path
-			};
+		if (sym.kind === "callable") {
+			const match = opLookup.get(sym.fqName);
+			if (match) {
+				sym.operationId = match.operationId;
+				sym.route = {
+					method: match.method,
+					path: match.path
+				};
+			}
+		}
+		if (sym.ownerFqName) {
+			const modelMatch = modelLookup.get(norm(sym.ownerFqName));
+			if (modelMatch) {
+				const localName = sym.fqName.includes(".") ? sym.fqName.split(".").pop() : sym.fqName;
+				const fieldMatch = modelMatch.fields.get(norm(localName));
+				if (fieldMatch) sym.schemaName = `${modelMatch.specName}.${fieldMatch}`;
+				else sym.schemaName = modelMatch.specName;
+			}
+		} else {
+			const modelMatch = modelLookup.get(norm(sym.fqName));
+			if (modelMatch) sym.schemaName = modelMatch.specName;
 		}
 	}
 }
@@ -6741,6 +6768,7 @@ function severityMeetsThreshold(severity, threshold) {
 */
 function classifySymbolChanges(baseline, candidate, policy) {
 	const changes = [];
+	const specRef = baseline.schemaName ?? candidate?.schemaName;
 	if (!candidate) {
 		changes.push(makeChange({
 			category: "symbol_removed",
@@ -6748,7 +6776,8 @@ function classifySymbolChanges(baseline, candidate, policy) {
 			old: { symbol: baseline.fqName },
 			new: { symbol: "(removed)" },
 			message: `Symbol "${baseline.displayName}" was removed`,
-			policy
+			policy,
+			specRef
 		}));
 		return changes;
 	}
@@ -6758,16 +6787,18 @@ function classifySymbolChanges(baseline, candidate, policy) {
 		old: { name: baseline.fqName },
 		new: { name: candidate.fqName },
 		message: `Symbol renamed from "${baseline.displayName}" to "${candidate.displayName}"`,
-		policy
+		policy,
+		specRef
 	}));
-	if (baseline.parameters && candidate.parameters) changes.push(...classifyParameterChanges(baseline, candidate, policy));
+	if (baseline.parameters && candidate.parameters) changes.push(...classifyParameterChanges(baseline, candidate, policy, specRef));
 	if (baseline.returns && candidate.returns && baseline.returns.name !== candidate.returns.name) changes.push(makeChange({
 		category: "return_type_changed",
 		symbol: baseline.fqName,
 		old: { returnType: baseline.returns.name },
 		new: { returnType: candidate.returns.name },
 		message: `Return type changed for "${baseline.displayName}" from "${baseline.returns.name}" to "${candidate.returns.name}"`,
-		policy
+		policy,
+		specRef
 	}));
 	if (baseline.typeRef && candidate.typeRef && baseline.typeRef.name !== candidate.typeRef.name) changes.push(makeChange({
 		category: "field_type_changed",
@@ -6775,7 +6806,8 @@ function classifySymbolChanges(baseline, candidate, policy) {
 		old: { type: baseline.typeRef.name },
 		new: { type: candidate.typeRef.name },
 		message: `Type changed for "${baseline.displayName}" from "${baseline.typeRef.name}" to "${candidate.typeRef.name}"`,
-		policy
+		policy,
+		specRef
 	}));
 	if (baseline.kind === "enum_member" && candidate.kind === "enum_member" && baseline.value !== void 0 && candidate.value !== void 0 && baseline.value !== candidate.value) changes.push(makeChange({
 		category: "enum_member_value_changed",
@@ -6790,7 +6822,7 @@ function classifySymbolChanges(baseline, candidate, policy) {
 /**
 * Classify parameter-level changes between two symbol versions.
 */
-function classifyParameterChanges(baseline, candidate, policy) {
+function classifyParameterChanges(baseline, candidate, policy, specRef) {
 	const changes = [];
 	const baseParams = baseline.parameters ?? [];
 	const candParams = candidate.parameters ?? [];
@@ -6810,6 +6842,7 @@ function classifyParameterChanges(baseline, candidate, policy) {
 					new: { parameter: positionalMatch.publicName },
 					message: `Parameter "${baseParam.publicName}" renamed to "${positionalMatch.publicName}" on "${baseline.displayName}"`,
 					policy,
+					specRef,
 					severityOverride: isBreakingRename ? void 0 : "soft-risk"
 				}));
 			} else changes.push(makeChange({
@@ -6818,7 +6851,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 				old: { parameter: baseParam.publicName },
 				new: { parameter: "(removed)" },
 				message: `Parameter "${baseParam.publicName}" removed from "${baseline.displayName}"`,
-				policy
+				policy,
+				specRef
 			}));
 			continue;
 		}
@@ -6834,7 +6868,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 				required: "true"
 			},
 			message: `Parameter "${baseParam.publicName}" became required on "${baseline.displayName}"`,
-			policy
+			policy,
+			specRef
 		}));
 		if (baseParam.type.name !== candParam.type.name) changes.push(makeChange({
 			category: "parameter_type_narrowed",
@@ -6848,7 +6883,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 				type: candParam.type.name
 			},
 			message: `Parameter type changed for "${baseParam.publicName}" on "${baseline.displayName}"`,
-			policy
+			policy,
+			specRef
 		}));
 		if (baseParam.position !== candParam.position) if (isConstructor ? policy.constructorOrderMatters : baseParam.sensitivity.order) {
 			const category = isConstructor ? "constructor_position_changed_order_sensitive" : "parameter_position_changed_order_sensitive";
@@ -6864,7 +6900,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 					position: String(candParam.position)
 				},
 				message: `Parameter "${baseParam.publicName}" moved from position ${baseParam.position} to ${candParam.position} on "${baseline.displayName}"`,
-				policy
+				policy,
+				specRef
 			}));
 		} else changes.push(makeChange({
 			category: "constructor_reordered_named_friendly",
@@ -6878,7 +6915,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 				position: String(candParam.position)
 			},
 			message: `Parameter "${baseParam.publicName}" reordered on "${baseline.displayName}" (named-friendly language)`,
-			policy
+			policy,
+			specRef
 		}));
 	}
 	for (const candParam of candParams) if (!baseByName.has(candParam.publicName)) {
@@ -6894,7 +6932,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 				required: "true"
 			},
 			message: `Required parameter "${candParam.publicName}" added to "${baseline.displayName}"`,
-			policy
+			policy,
+			specRef
 		}));
 		else changes.push(makeChange({
 			category,
@@ -6902,7 +6941,8 @@ function classifyParameterChanges(baseline, candidate, policy) {
 			old: { parameter: "(absent)" },
 			new: { parameter: candParam.publicName },
 			message: `Optional parameter "${candParam.publicName}" added to "${baseline.displayName}"`,
-			policy
+			policy,
+			specRef
 		}));
 	}
 	return changes;
@@ -6912,12 +6952,19 @@ function parameterNameIsPublicApi(param, policy, isConstructor) {
 	if (isConstructor) return policy.constructorParameterNamesArePublicApi;
 	return policy.methodParameterNamesArePublicApi;
 }
-/** Build a deterministic conceptual change ID. */
-function buildConceptualChangeId(category, symbol, match) {
+/**
+* Build a deterministic conceptual change ID.
+*
+* When `specRef` is provided (e.g. "GenerateLinkBody.admin_emails"), it is
+* used instead of the language-specific symbol name.  This ensures the same
+* spec entity produces the same ID across all languages, enabling cross-
+* language rollup in reports.
+*/
+function buildConceptualChangeId(category, symbol, match, specRef) {
 	const parts = [
 		"chg",
 		category,
-		symbol.replace(/[^a-zA-Z0-9_.]/g, "_")
+		(specRef ?? symbol).replace(/[^a-zA-Z0-9_.]/g, "_")
 	];
 	if (match.parameter) parts.push(match.parameter);
 	if (match.member) parts.push(match.member);
@@ -6928,7 +6975,7 @@ function makeChange(opts) {
 		category: opts.category,
 		severity: opts.severityOverride ?? defaultSeverityForCategory(opts.category),
 		symbol: opts.symbol,
-		conceptualChangeId: buildConceptualChangeId(opts.category, opts.symbol, opts.old),
+		conceptualChangeId: buildConceptualChangeId(opts.category, opts.symbol, opts.old, opts.specRef),
 		provenance: opts.provenance ?? "unknown",
 		old: opts.old,
 		new: opts.new,
@@ -6943,7 +6990,7 @@ function classifyAddedSymbol(symbol) {
 		category: "symbol_added",
 		severity: "additive",
 		symbol: symbol.fqName,
-		conceptualChangeId: buildConceptualChangeId("symbol_added", symbol.fqName, {}),
+		conceptualChangeId: buildConceptualChangeId("symbol_added", symbol.fqName, {}, symbol.schemaName),
 		provenance: "unknown",
 		old: { symbol: "(absent)" },
 		new: { symbol: symbol.fqName },
@@ -8355,7 +8402,10 @@ program.command("extract").description("Extract public API surface from a live S
 });
 program.command("compat-extract").description("Extract a compat snapshot from a live SDK and write .oagen-compat-snapshot.json").requiredOption("--sdk-path <path>", "Path to the live SDK").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Directory to write .oagen-compat-snapshot.json into").option("--spec <path>", "Path to OpenAPI spec — enriches symbols with operationId, route, and specSha").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
-	compatExtractCommand(opts).catch(handleError);
+	compatExtractCommand({
+		...opts,
+		schemaNameTransform: configSchemaNameTransform
+	}).catch(handleError);
 });
 program.command("compat-diff").description("Diff two compat snapshot files and produce a classified change report").requiredOption("--baseline <path>", "Path to the baseline compat snapshot JSON").requiredOption("--candidate <path>", "Path to the candidate compat snapshot JSON").option("--output <path>", "Write machine-readable report to this path").option("--fail-on <level>", "Fail threshold: none, breaking, or soft-risk", "breaking").option("--explain", "Include provenance explanations in output").action((opts) => {
 	compatDiffCommand(opts).catch(handleError);