@workos/oagen 0.29.0 → 0.29.2

package/dist/cli/index.mjs

@@ -8165,7 +8165,10 @@ function apiSurfaceToSnapshot(surface) {
 	}
 	return {
 		schemaVersion: "1",
-		source: { extractedAt: surface.extractedAt },
+		source: {
+			extractedAt: surface.extractedAt,
+			language
+		},
 		policies: getDefaultPolicy(language),
 		symbols
 	};
@@ -8395,10 +8398,138 @@ function severityMeetsThreshold(severity, threshold) {
 //#endregion
 //#region src/compat/classify.ts
 /**
+* Normalize a type annotation string to a canonical form before equality
+* comparison. Emitters evolve their annotation style across releases (e.g.
+* Python's PEP 604 `X | None` replacing `Optional[X]`, PEP 585 lowercase
+* generics, or dropping quotes from forward refs); such changes are cosmetic
+* and must not register as breaking type changes. Only Python needs this
+* today — other languages encode optionality with a single stable spelling
+* (`*Foo`, `Option<T>`, `T?`, `T.nilable(Foo)`) so they use exact comparison.
+* String-literal *values* inside `Literal[...]` are preserved verbatim so a
+* genuine change to a wire value stays visible. When `language` is absent
+* (older snapshots) no normalization is applied, preserving prior behaviour.
+*/
+function normalizeType(type, language) {
+	if (!type) return type;
+	if (language !== "python") return type;
+	return canonicalizePythonType(type);
+}
+/** PEP 585 capitalized builtins that map to their lowercase spellings, so
+*  `List[str]` and `list[str]` compare equal. */
+const PEP585_BUILTINS = {
+	List: "list",
+	Dict: "dict",
+	Tuple: "tuple",
+	Set: "set",
+	FrozenSet: "frozenset",
+	Type: "type"
+};
+/** Recursively canonicalize a Python annotation. Structural forms are
+*  normalized (`Optional[X]`→`X | None`, `Union[...]`→` | ` joins, PEP 585
+*  builtins, quoted forward refs, parenthesized unions), but `Literal[...]`
+*  arguments are preserved verbatim — their quotes and inner whitespace are
+*  part of the wire value, not cosmetic. */
+function canonicalizePythonType(s) {
+	const t = s.trim();
+	if (t.length === 0) return t;
+	if (t.startsWith("(") && t.endsWith(")")) return canonicalizePythonType(t.slice(1, -1));
+	if (t.startsWith("Literal[") && t.endsWith("]")) return `Literal[${splitTopLevel(t.slice(8, -1), ",").map((p) => p.trim()).filter((p) => p.length > 0).map(canonicalizeLiteralArg).join(", ")}]`;
+	if (t.startsWith("Optional[") && t.endsWith("]")) return `${canonicalizePythonType(t.slice(9, -1))} | None`;
+	if (t.startsWith("Union[") && t.endsWith("]")) return splitTopLevel(t.slice(6, -1), ",").map((p) => p.trim()).filter((p) => p.length > 0).map(canonicalizePythonType).join(" | ");
+	if (t.includes("|")) {
+		const arms = splitTopLevel(t, "|").map((p) => p.trim()).filter((p) => p.length > 0);
+		if (arms.length > 1) return arms.map(canonicalizePythonType).join(" | ");
+	}
+	const open = t.indexOf("[");
+	if (open !== -1 && t.endsWith("]")) {
+		const outer = t.slice(0, open).trim();
+		const inner = t.slice(open + 1, -1);
+		return `${PEP585_BUILTINS[outer] ?? outer}[${splitTopLevel(inner, ",").map((p) => p.trim()).filter((p) => p.length > 0).map(canonicalizePythonType).join(", ")}]`;
+	}
+	if (t.startsWith("\"") && t.endsWith("\"") && t.length >= 2 || t.startsWith("'") && t.endsWith("'") && t.length >= 2) return t.slice(1, -1);
+	return PEP585_BUILTINS[t] ?? t;
+}
+/** Canonicalize one `Literal[...]` argument so semantically identical string
+*  values compare equal regardless of quote style or escape form. The value
+*  is decoded (backslash escapes processed) then re-encoded in a canonical
+*  double-quoted form, so `Literal['say "hi"']` and `Literal["say \\"hi\\""]`
+*  both canonicalize to `"say \"hi\""`. Bare (unquoted) arguments — e.g. an
+*  enum name or a number — are returned unchanged. */
+function canonicalizeLiteralArg(arg) {
+	const a = arg.trim();
+	if (a.length < 2) return a;
+	let quote = null;
+	if (a.startsWith("\"") && a.endsWith("\"")) quote = "\"";
+	else if (a.startsWith("'") && a.endsWith("'")) quote = "'";
+	if (!quote) return a;
+	return `"${encodeDoubleQuoted(decodeStringLiteral(a.slice(1, -1)))}"`;
+}
+/** Decode the backslash escapes inside a Python string literal's content.
+*  Only the delimiter-relevant escapes (`\\`, `\'`, `\"`) are processed;
+*  other sequences (`\n`, `\t`, `\u…`) are kept verbatim since they're
+*  written identically regardless of quote style and so compare equal already. */
+function decodeStringLiteral(content) {
+	let out = "";
+	for (let i = 0; i < content.length; i++) {
+		const c = content[i];
+		if (c === "\\" && i + 1 < content.length) {
+			const next = content[i + 1];
+			if (next === "\\" || next === "\"" || next === "'") {
+				out += next;
+				i++;
+				continue;
+			}
+			out += c + next;
+			i++;
+			continue;
+		}
+		out += c;
+	}
+	return out;
+}
+/** Re-encode a decoded value as a canonical double-quoted Python string. */
+function encodeDoubleQuoted(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+/** Split on a separator that sits at bracket-depth 0 and outside string
+*  literals, so commas/pipes inside `Literal["a,b"]` or `"x|y"` are not split.
+*  An escaped matching quote (`\"` inside a double-quoted string) does not
+*  close the string: only a quote preceded by an even number of backslashes
+*  (zero counts) is a real closing delimiter. */
+function splitTopLevel(s, sep) {
+	const parts = [];
+	let depth = 0;
+	let inStr = null;
+	let start = 0;
+	for (let i = 0; i < s.length; i++) {
+		const c = s[i];
+		if (inStr) {
+			if (c === inStr) {
+				let precedingBackslashes = 0;
+				for (let j = i - 1; j >= 0 && s[j] === "\\"; j--) precedingBackslashes++;
+				if (precedingBackslashes % 2 === 0) inStr = null;
+			}
+			continue;
+		}
+		if (c === "\"" || c === "'") {
+			inStr = c;
+			continue;
+		}
+		if (c === "[") depth++;
+		else if (c === "]") depth--;
+		else if (c === sep && depth === 0) {
+			parts.push(s.slice(start, i));
+			start = i + 1;
+		}
+	}
+	parts.push(s.slice(start));
+	return parts;
+}
+/**
 * Classify changes between a baseline and candidate symbol.
 * Returns one or more classified changes for the diff.
 */
-function classifySymbolChanges(baseline, candidate, policy) {
+function classifySymbolChanges(baseline, candidate, policy, language) {
 	const changes = [];
 	const specRef = baseline.schemaName ?? candidate?.schemaName;
 	if (!candidate) {
@@ -8422,8 +8553,8 @@ function classifySymbolChanges(baseline, candidate, policy) {
 		policy,
 		specRef
 	}));
-	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({
+	if (baseline.parameters && candidate.parameters) changes.push(...classifyParameterChanges(baseline, candidate, policy, specRef, language));
+	if (baseline.returns && candidate.returns && normalizeType(baseline.returns.name, language) !== normalizeType(candidate.returns.name, language)) changes.push(makeChange({
 		category: "return_type_changed",
 		symbol: baseline.fqName,
 		old: { returnType: baseline.returns.name },
@@ -8441,7 +8572,7 @@ function classifySymbolChanges(baseline, candidate, policy) {
 		policy,
 		specRef
 	}));
-	if (baseline.typeRef && candidate.typeRef && baseline.typeRef.name !== candidate.typeRef.name) changes.push(makeChange({
+	if (baseline.typeRef && candidate.typeRef && normalizeType(baseline.typeRef.name, language) !== normalizeType(candidate.typeRef.name, language)) changes.push(makeChange({
 		category: "field_type_changed",
 		symbol: baseline.fqName,
 		old: { type: baseline.typeRef.name },
@@ -8463,7 +8594,7 @@ function classifySymbolChanges(baseline, candidate, policy) {
 /**
 * Classify parameter-level changes between two symbol versions.
 */
-function classifyParameterChanges(baseline, candidate, policy, specRef) {
+function classifyParameterChanges(baseline, candidate, policy, specRef, language) {
 	const changes = [];
 	const baseParams = baseline.parameters ?? [];
 	const candParams = candidate.parameters ?? [];
@@ -8512,7 +8643,7 @@ function classifyParameterChanges(baseline, candidate, policy, specRef) {
 			policy,
 			specRef
 		}));
-		if (baseParam.type.name !== candParam.type.name) changes.push(makeChange({
+		if (normalizeType(baseParam.type.name, language) !== normalizeType(candParam.type.name, language)) changes.push(makeChange({
 			category: "parameter_type_narrowed",
 			symbol: baseline.fqName,
 			old: {
@@ -8869,7 +9000,7 @@ function diffSnapshots(baseline, candidate, policy) {
 	for (const baseSym of baseline.symbols) {
 		if (isServiceWrapperConstructor(baseSym, serviceAccessors)) continue;
 		const candSym = candById.get(baseSym.id) ?? candByFqName.get(baseSym.fqName);
-		changes.push(...classifySymbolChanges(baseSym, candSym, effectivePolicy));
+		changes.push(...classifySymbolChanges(baseSym, candSym, effectivePolicy, baseline.source.language));
 	}
 	for (const candSym of candidate.symbols) if (!baseByFqName.has(candSym.fqName)) {
 		if (isServiceWrapperConstructor(candSym, serviceAccessors)) continue;