@workos/oagen 0.12.0 → 0.14.0

package/dist/{overlay-DTaApIqN.mjs → overlay-DGcHh1KN.mjs}

@@ -912,12 +912,269 @@ function diffSnapshots(baseline, candidate, policy) {
 		if (isServiceWrapperConstructor(candSym, serviceAccessors)) continue;
 		changes.push(classifyAddedSymbol(candSym));
 	}
+	detectForkedSchemas(changes, baseline, candidate);
+	cascadeRenameDowngrades(changes, detectTypeRenames(changes, baseline, candidate), detectEnumRenames(changes, baseline, candidate));
 	return {
 		changes,
 		summary: summarizeChanges(changes)
 	};
 }
 /**
+* Detect "schema fork" antipattern and attach a remediation hint.
+*
+* Fires when:
+*  1. A return type or field type changed from `OldType` → `NewType`.
+*  2. `NewType` is newly added in the candidate snapshot.
+*  3. `NewType.fields ⊇ OldType.fields` (every field on the old type still
+*     exists on the new one — the new schema is a strict superset, so the
+*     same fields could have been added to the existing schema additively).
+*
+* Mutates `changes` in place: sets `remediation` on the matching change.
+* Leaves the original category and severity alone — this is just a hint.
+*
+* Identity match is by `displayName` of the type symbol, which corresponds
+* to the type name as it appears in `change.old.returnType` / `.type` and
+* `change.new.returnType` / `.type`.
+*/
+function detectForkedSchemas(changes, baseline, candidate) {
+	const baselineTypeFields = collectTypeFieldSets(baseline);
+	const candidateTypeFields = collectTypeFieldSets(candidate);
+	const baselineTypeNames = new Set(baselineTypeFields.keys());
+	for (const change of changes) {
+		if (change.remediation) continue;
+		let oldType;
+		let newType;
+		if (change.category === "return_type_changed") {
+			oldType = change.old.returnType;
+			newType = change.new.returnType;
+		} else if (change.category === "field_type_changed") {
+			oldType = change.old.type;
+			newType = change.new.type;
+		} else continue;
+		if (!oldType || !newType || oldType === newType) continue;
+		const oldTypeBare = bareTypeName(oldType);
+		const newTypeBare = bareTypeName(newType);
+		if (baselineTypeNames.has(newTypeBare)) continue;
+		const oldFields = baselineTypeFields.get(oldTypeBare);
+		const newFields = candidateTypeFields.get(newTypeBare);
+		if (!oldFields || !newFields) continue;
+		if (oldFields.size === 0) continue;
+		let isSuperset = true;
+		for (const f of oldFields) if (!newFields.has(f)) {
+			isSuperset = false;
+			break;
+		}
+		if (!isSuperset) continue;
+		change.remediation = `Schema "${newTypeBare}" looks like "${oldTypeBare}" with additional fields. Consider adding the new fields to "${oldTypeBare}" instead of forking a new schema — forking forces a breaking type-name change in typed SDKs, while extending the existing schema is additive.`;
+	}
+}
+/**
+* Build a map from type fqName → set of (lowercased) child field names.
+* Used by `detectForkedSchemas` for superset comparison.
+*/
+function collectTypeFieldSets(snapshot) {
+	const result = /* @__PURE__ */ new Map();
+	for (const sym of snapshot.symbols) {
+		if (sym.kind !== "field" && sym.kind !== "property") continue;
+		if (!sym.ownerFqName) continue;
+		const localName = sym.fqName.includes(".") ? sym.fqName.slice(sym.fqName.lastIndexOf(".") + 1) : sym.fqName;
+		let set = result.get(sym.ownerFqName);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			result.set(sym.ownerFqName, set);
+		}
+		set.add(localName.toLowerCase());
+	}
+	return result;
+}
+/**
+* Detect type renames: a baseline type symbol disappears and a candidate
+* type symbol with the same (or superset) field set takes its place.
+*
+* Common when an upstream spec promotes a single schema into multiple
+* (e.g. `ApiKey` → `OrganizationApiKey` + `UserApiKey`). The wire shape
+* returned by individual endpoints is unchanged — `OrganizationApiKey`
+* has the same fields `ApiKey` had — so consumer code accessing those
+* fields keeps working. The compat report flags `ApiKey` as removed
+* because its symbol is gone; this pass downgrades the removal to
+* soft-risk and records the rename so its child fields/methods cascade.
+*
+* Identity criteria (must all hold):
+*   1. The removed symbol owns ≥ 1 field/property in the baseline (i.e.
+*      it's a type-shaped symbol — model/interface/class — not a plain
+*      function or constant).
+*   2. Some candidate type that did *not* exist in the baseline has a
+*      field set that is a non-strict superset of the removed type's
+*      fields. (Strict-subset would mean fields were lost — a real break.)
+*   3. The candidate type is the alphabetically-first such match, so
+*      pairing is deterministic when multiple candidates fit (e.g. both
+*      `OrganizationApiKey` and `UserApiKey` share the original fields).
+*
+* Returns a `removedName -> newName` map so a downstream cascade pass
+* can downgrade owned-field removals and `*_type_changed` pointing at
+* the same pair.
+*
+* Mutates matching `symbol_removed` entries in `changes`: severity →
+* `soft-risk`, attaches a `remediation` describing the rename.
+*/
+function detectTypeRenames(changes, baseline, candidate) {
+	const renameMap = /* @__PURE__ */ new Map();
+	const baselineTypeFields = collectTypeFieldSets(baseline);
+	const candidateTypeFields = collectTypeFieldSets(candidate);
+	const baselineTypeNames = new Set(baselineTypeFields.keys());
+	const candidateTypesSorted = [...candidateTypeFields.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+	for (const change of changes) {
+		if (change.category !== "symbol_removed") continue;
+		if (change.severity !== "breaking") continue;
+		const removedName = bareTypeName(change.old.symbol ?? "");
+		if (!removedName) continue;
+		const removedFields = baselineTypeFields.get(removedName);
+		if (!removedFields || removedFields.size === 0) continue;
+		const match = candidateTypesSorted.find(([candName, candFields]) => {
+			if (baselineTypeNames.has(candName)) return false;
+			for (const f of removedFields) if (!candFields.has(f)) return false;
+			return true;
+		});
+		if (!match) continue;
+		const [newName] = match;
+		renameMap.set(removedName, newName);
+		change.severity = "soft-risk";
+		change.remediation = `Type "${removedName}" appears to have been renamed to "${newName}" — the new type has every field of the old (a non-strict superset). Field accesses and method calls on values of type "${newName}" continue to work; only explicit "${removedName}" type annotations need to migrate. Consider emitting a deprecated alias \`type ${removedName} = ${newName}\` in languages that support it.`;
+	}
+	return renameMap;
+}
+/**
+* Detect enum canonical-flips: a baseline enum disappears and a candidate
+* enum with the **same wire-value set** takes its place.
+*
+* Caused by the emitter's enum-dedup heuristic picking a different
+* canonical name when a new same-shape enum joins the spec. Languages
+* that emit type aliases (Go, Ruby, Python, PHP, Kotlin) handle this
+* transparently via `type Old = New`; languages without first-class
+* aliases (dotnet) report the old enum as removed. The wire values are
+* unchanged — every legal value still serializes to the same JSON — so
+* consumer code constructing or matching on these enum values keeps
+* working. Only references to the typed enum class need migration.
+*
+* Identity criterion: a removed enum's value set is *exactly* equal to
+* a newly-added enum's value set (not superset — narrowing the value
+* set would be a real break for consumers expecting the dropped values).
+*/
+function detectEnumRenames(changes, baseline, candidate) {
+	const renameMap = /* @__PURE__ */ new Map();
+	const baselineEnumValues = collectEnumValueSets(baseline);
+	const candidateEnumValues = collectEnumValueSets(candidate);
+	const baselineEnumNames = new Set(baselineEnumValues.keys());
+	const candidateEnumsSorted = [...candidateEnumValues.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+	for (const change of changes) {
+		if (change.category !== "symbol_removed") continue;
+		if (change.severity !== "breaking") continue;
+		const removedName = bareTypeName(change.old.symbol ?? "");
+		if (!removedName) continue;
+		const removedValues = baselineEnumValues.get(removedName);
+		if (!removedValues || removedValues.size === 0) continue;
+		const match = candidateEnumsSorted.find(([candName, candValues]) => {
+			if (baselineEnumNames.has(candName)) return false;
+			if (candValues.size !== removedValues.size) return false;
+			for (const v of removedValues) if (!candValues.has(v)) return false;
+			return true;
+		});
+		if (!match) continue;
+		const [newName] = match;
+		renameMap.set(removedName, newName);
+		change.severity = "soft-risk";
+		change.remediation = `Enum "${removedName}" appears to have been renamed to "${newName}" — both enums have identical wire values, so on-the-wire serialization is unchanged. This is typically the emitter's dedup canonical-flip after a new same-shape enum joined the spec. Consider emitting a deprecated alias in languages that support it, or pinning the canonical via emitter config.`;
+	}
+	return renameMap;
+}
+/**
+* Cascade rename downgrades to changes whose meaning depends on a renamed
+* symbol. Walks every change and:
+*
+*   - Downgrades child removals (`Owner.field` removed where `Owner` was
+*     renamed) — the field still exists, just under a new owner fqName.
+*     Same logic for enum members under a renamed enum.
+*   - Downgrades `return_type_changed` / `field_type_changed` whose
+*     old → new pair matches a recorded rename — the type swap is the
+*     rename itself, not a meaningful signature break.
+*
+* Each cascaded change gets a remediation pointing at the parent rename
+* so the reviewer can find the explanation in the report.
+*/
+function cascadeRenameDowngrades(changes, typeRenames, enumRenames) {
+	if (typeRenames.size === 0 && enumRenames.size === 0) return;
+	for (const change of changes) {
+		if (change.severity !== "breaking") continue;
+		if (change.category === "symbol_removed") {
+			const removed = change.old.symbol ?? "";
+			const dotIdx = removed.indexOf(".");
+			if (dotIdx <= 0) continue;
+			const ownerName = removed.slice(0, dotIdx);
+			const renamedTo = typeRenames.get(ownerName) ?? enumRenames.get(ownerName);
+			if (!renamedTo) continue;
+			change.severity = "soft-risk";
+			change.remediation = `Owned by renamed symbol "${ownerName}" (now "${renamedTo}"). The same member exists on the new symbol under "${renamedTo}.${removed.slice(dotIdx + 1)}".`;
+			continue;
+		}
+		if (change.category === "return_type_changed") {
+			const oldT = bareTypeName(change.old.returnType ?? "");
+			const newT = bareTypeName(change.new.returnType ?? "");
+			if (typeRenames.get(oldT) === newT) {
+				change.severity = "soft-risk";
+				change.remediation = `Return type swap matches recorded rename "${oldT}" → "${newT}". The underlying field set is preserved (see the rename advisory on "${oldT}").`;
+			}
+			continue;
+		}
+		if (change.category === "field_type_changed") {
+			const oldT = bareTypeName(change.old.type ?? "");
+			const newT = bareTypeName(change.new.type ?? "");
+			if ((typeRenames.get(oldT) ?? enumRenames.get(oldT)) === newT) {
+				change.severity = "soft-risk";
+				change.remediation = `Field type swap matches recorded rename "${oldT}" → "${newT}". On-the-wire shape is unchanged (see the rename advisory on "${oldT}").`;
+			}
+		}
+	}
+}
+/**
+* Build a map from enum fqName → set of wire values. Used by
+* `detectEnumRenames` to find structurally-identical enums across
+* baseline and candidate. Wire values come from `enum_member.value`
+* (the JSON-level value) — not the member names, which are
+* language-specific PascalCase forms.
+*
+* Members whose `value` is undefined are skipped — they contribute no
+* identity information.
+*/
+function collectEnumValueSets(snapshot) {
+	const result = /* @__PURE__ */ new Map();
+	for (const sym of snapshot.symbols) {
+		if (sym.kind !== "enum_member") continue;
+		if (!sym.ownerFqName) continue;
+		if (sym.value === void 0) continue;
+		let set = result.get(sym.ownerFqName);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			result.set(sym.ownerFqName, set);
+		}
+		set.add(String(sym.value));
+	}
+	return result;
+}
+/**
+* Strip array/nullable suffixes so we compare bare type names. Languages
+* encode these differently (`Foo[]`, `Foo | null`, `Foo?`, `List<Foo>`,
+* `Optional[Foo]`); this is a best-effort common-case stripper, not an
+* exhaustive parser.
+*/
+function bareTypeName(t) {
+	let s = t.trim();
+	s = s.replace(/\s*\|\s*null$/, "").replace(/\?$/, "");
+	s = s.replace(/\[\]$/, "");
+	const generic = s.match(/^[A-Za-z_][A-Za-z0-9_.]*<\s*([A-Za-z_][A-Za-z0-9_.]*)\s*>$/);
+	if (generic) s = generic[1];
+	return s;
+}
+/**
 * Check if a symbol is a constructor belonging to a service wrapper class.
 *
 * Service wrapper constructors are internal plumbing (taking a client/config
@@ -1711,4 +1968,4 @@ function patchOverlay(overlay, changes, baseline) {
 //#endregion
 export { getDefaultPolicy as A, defaultSeverityForCategory as C, isCompatibleSchemaVersion as D, COMPAT_SCHEMA_VERSION as E, validateSnapshot as O, summarizeChanges as S, apiSurfaceToSnapshot as T, nodeHints as _, registerExtractor as a, classifyAddedSymbol as b, filterSurface as c, specDerivedHttpKeys as d, specDerivedMethodPaths as f, namedTypeWordsOverlap as g, defaultIsNullableOnlyDifference as h, getExtractor as i, mergePolicy as j, ALL_LANGUAGE_IDS as k, specDerivedEnumValues as l, NAMED_TYPE_RE as m, isPatchableChange as n, diffSnapshots as o, specDerivedNames as p, patchOverlay as r, diffSurfaces as s, buildOverlayLookup as t, specDerivedFieldPaths as u, resolveHints as v, severityMeetsThreshold as w, classifySymbolChanges as x, typeExistsInSurface as y };
 
-//# sourceMappingURL=overlay-DTaApIqN.mjs.map
+//# sourceMappingURL=overlay-DGcHh1KN.mjs.map