@workos/oagen 0.18.0 → 0.18.2

package/README.md

@@ -1,6 +1,6 @@
 # oagen
 
-oagen is a framework for building custom SDK generators from OpenAPI 3.x specifications.
+oagen ([**oʊweɪdd͡ʒɛn**](https://ipa-reader.com/?text=o%CA%8Awe%C9%AAdd%CD%A1%CA%92%C9%9Bn)) is a framework for building custom SDK generators from OpenAPI 3.x specifications.
 
 Its core job is narrow:
 

package/dist/cli/index.mjs

@@ -1435,7 +1435,7 @@ const LIMIT_PARAMS = [
 * Returns null if no pagination pattern is detected.
 */
 function detectPagination(response, queryParams, dataPath) {
-	const cursorParam = queryParams.find((p) => CURSOR_PARAMS.includes(p.name));
+	const cursorParam = CURSOR_PARAMS.map((name) => queryParams.find((p) => p.name === name)).find((p) => p !== void 0);
 	if (cursorParam) {
 		const itemType = response.kind === "array" ? response.items : response;
 		return {
@@ -1811,7 +1811,7 @@ const HTTP_METHODS = [
 	"options",
 	"trace"
 ];
-function extractOperations(paths, operationIdTransform) {
+function extractOperations(paths, operationIdTransform, componentSchemas) {
 	if (!paths) return {
 		services: [],
 		inlineModels: []
@@ -1824,7 +1824,7 @@ function extractOperations(paths, operationIdTransform) {
 			const op = pathItem[method];
 			if (!op) continue;
 			const serviceName = inferServiceName(path, op.tags?.[0]);
-			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName);
+			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas);
 			inlineModels.push(...opModels);
 			const ops = serviceMap.get(serviceName) ?? [];
 			ops.push(operation);
@@ -2067,14 +2067,14 @@ function extractBodyParameterGroups(op, operationContext) {
 	}
 	return groups.length > 0 ? groups : void 0;
 }
-function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName) {
+function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas) {
 	const allParams = [...pathLevelParams, ...op.parameters ?? []];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
 	const opContext = serviceName;
-	const pathParams = extractParams(allParams, "path", opContext);
-	const queryParams = extractParams(allParams, "query", opContext);
-	const headerParams = extractParams(allParams, "header", opContext).filter((p) => p.name.toLowerCase() !== "idempotency-key");
-	const cookieParams = extractParams(allParams, "cookie", opContext);
+	const pathParams = extractParams(allParams, "path", opContext, componentSchemas);
+	const queryParams = extractParams(allParams, "query", opContext, componentSchemas);
+	const headerParams = extractParams(allParams, "header", opContext, componentSchemas).filter((p) => p.name.toLowerCase() !== "idempotency-key");
+	const cookieParams = extractParams(allParams, "cookie", opContext, componentSchemas);
 	const reqBodyModels = [];
 	const { body: requestBody, encoding: requestBodyEncoding } = extractRequestBody(op.requestBody, op, reqBodyModels);
 	const { response, successResponses, errors, inlineModels, isPaginated, dataPath: responseDataPath, itemType: responseItemType } = extractResponses(op.responses, op, path, method);
@@ -2146,21 +2146,42 @@ function buildDescription(summary, description) {
 	if (summary && description && summary !== description) return `${summary}\n\n${description}`;
 	return description ?? summary;
 }
-function extractParams(params, location, operationContext) {
-	return params.filter((p) => p.in === location).map((p) => ({
-		name: p.name,
-		type: p.schema ? schemaToTypeRef(p.schema, p.name, operationContext ? toPascalCase(operationContext) : void 0) : {
-			kind: "primitive",
-			type: "string"
-		},
-		required: p.required ?? false,
-		description: p.description,
-		deprecated: p.deprecated || p.schema?.deprecated || void 0,
-		default: p.schema?.default,
-		example: p.example ?? p.schema?.example,
-		style: p.style,
-		explode: p.explode
-	}));
+function extractParams(params, location, operationContext, componentSchemas) {
+	return params.filter((p) => p.in === location).map((p) => {
+		const refTarget = resolveParamSchemaRef(p.schema, componentSchemas);
+		return {
+			name: p.name,
+			type: p.schema ? schemaToTypeRef(p.schema, p.name, operationContext ? toPascalCase(operationContext) : void 0) : {
+				kind: "primitive",
+				type: "string"
+			},
+			required: p.required ?? false,
+			description: p.description,
+			deprecated: p.deprecated || p.schema?.deprecated || refTarget?.deprecated || void 0,
+			default: p.schema?.default ?? refTarget?.default,
+			example: p.example ?? p.schema?.example ?? refTarget?.example,
+			style: p.style,
+			explode: p.explode
+		};
+	});
+}
+/**
+* If a parameter's schema is a `$ref` to `#/components/schemas/X`, return the
+* referenced component schema. Used to surface schema-level metadata (default,
+* example, deprecated) that wouldn't otherwise be visible at the param level.
+*
+* Refs are not pre-resolved by the bundler (`dereference: false` in refs.ts),
+* so without this, a param like `schema: { $ref: '.../PaginationOrder' }`
+* silently loses the target's `default: desc` and the SDK stops emitting the
+* spec-mandated default value in generated method signatures.
+*/
+function resolveParamSchemaRef(schema, componentSchemas) {
+	if (!schema || !componentSchemas) return void 0;
+	const ref = schema.$ref;
+	if (!ref) return void 0;
+	const match = /^#\/components\/schemas\/(.+)$/.exec(ref);
+	if (!match) return void 0;
+	return componentSchemas[match[1]];
 }
 function extractRequestBody(body, op, inlineModels) {
 	if (!body?.content) return {};
@@ -2514,7 +2535,7 @@ async function parseSpec(specPath, options) {
 	const version = spec.openapi ?? "";
 	if (!version.startsWith("3.")) throw new SpecParseError(`Unsupported OpenAPI version: ${version}. oagen requires OpenAPI 3.x`, `Update the spec to OpenAPI 3.0 or 3.1. If you are using Swagger 2.x, convert it first with \`npx swagger2openapi ${specPath}\`.`);
 	const { models, enums } = extractSchemas(spec.components?.schemas, { schemaNameTransform: options?.schemaNameTransform });
-	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform);
+	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform, spec.components?.schemas);
 	clearSchemaNameTransform();
 	const finalModels = collapseJsonSuffixModels(mergeFieldInlineModels(mergeInlineResponseModels(models, inlineModels), extractInlineModelsFromSchemas(spec.components?.schemas)), services);
 	collectInlineEnumsFromModels(finalModels, enums);
@@ -6223,6 +6244,11 @@ function classifyFieldChange(kind, fieldName, isRequired) {
 			fieldName,
 			classification: "breaking"
 		};
+		case "field-format-changed": return {
+			kind,
+			fieldName,
+			classification: "additive"
+		};
 		case "field-required-changed": return {
 			kind,
 			fieldName,
@@ -6253,11 +6279,21 @@ function classifyParamChange(kind, paramName, isRequired) {
 			paramName,
 			classification: "breaking"
 		};
+		case "param-format-changed": return {
+			kind,
+			paramName,
+			classification: "additive"
+		};
 		case "param-required-changed": return {
 			kind,
 			paramName,
 			classification: isRequired ? "breaking" : "additive"
 		};
+		case "param-default-changed": return {
+			kind,
+			paramName,
+			classification: "breaking"
+		};
 	}
 }
 //#endregion
@@ -6301,7 +6337,11 @@ function diffFields(oldModel, newModel) {
 	for (const [name, newField] of newByName) {
 		const oldField = oldByName.get(name);
 		if (!oldField) continue;
-		if (!typeRefsEqual(oldField.type, newField.type)) changes.push({
+		if (!typeRefsEqual(oldField.type, newField.type)) if (primitivesDifferOnlyByFormat(oldField.type, newField.type)) changes.push({
+			...classifyFieldChange("field-format-changed", name),
+			details: formatChangeDetails(oldField.type, newField.type)
+		});
+		else changes.push({
 			kind: "field-type-changed",
 			fieldName: name,
 			classification: "breaking",
@@ -6312,6 +6352,23 @@ function diffFields(oldModel, newModel) {
 	}
 	return changes;
 }
+/**
+* True when both refs are primitives with the same base `type` but different
+* `format`. Used to downgrade format-only diffs from breaking type changes to
+* additive `field-format-changed` / `param-format-changed` events: the wire
+* base type is unchanged, so the diff is a hint to language emitters rather
+* than a source-level break.
+*/
+function primitivesDifferOnlyByFormat(a, b) {
+	if (a.kind !== "primitive" || b.kind !== "primitive") return false;
+	if (a.type !== b.type) return false;
+	return (a.format ?? "") !== (b.format ?? "");
+}
+function formatChangeDetails(a, b) {
+	const oldFmt = a.kind === "primitive" ? a.format : void 0;
+	const newFmt = b.kind === "primitive" ? b.format : void 0;
+	return `format ${oldFmt ?? "<unset>"} → ${newFmt ?? "<unset>"}`;
+}
 function typeRefsEqual(a, b) {
 	if (a.kind !== b.kind) return false;
 	switch (a.kind) {
@@ -6413,28 +6470,57 @@ function classifyErrorsChange(oldErrors, newErrors) {
 }
 function diffParams(oldOp, newOp) {
 	const changes = [];
+	const tagged = (loc, params) => params.map((p) => ({
+		p,
+		loc
+	}));
 	const allOldParams = [
-		...oldOp.pathParams,
-		...oldOp.queryParams,
-		...oldOp.headerParams
+		...tagged("path", oldOp.pathParams),
+		...tagged("query", oldOp.queryParams),
+		...tagged("header", oldOp.headerParams)
 	];
 	const allNewParams = [
-		...newOp.pathParams,
-		...newOp.queryParams,
-		...newOp.headerParams
+		...tagged("path", newOp.pathParams),
+		...tagged("query", newOp.queryParams),
+		...tagged("header", newOp.headerParams)
 	];
-	const oldByName = new Map(allOldParams.map((p) => [p.name, p]));
-	const newByName = new Map(allNewParams.map((p) => [p.name, p]));
-	for (const [name, param] of newByName) if (!oldByName.has(name)) changes.push(classifyParamChange("param-added", name, param.required));
+	const oldByName = new Map(allOldParams.map((e) => [e.p.name, e]));
+	const newByName = new Map(allNewParams.map((e) => [e.p.name, e]));
+	for (const [name, entry] of newByName) if (!oldByName.has(name)) changes.push(classifyParamChange("param-added", name, entry.p.required));
 	for (const [name] of oldByName) if (!newByName.has(name)) changes.push(classifyParamChange("param-removed", name));
-	for (const [name, newParam] of newByName) {
-		const oldParam = oldByName.get(name);
-		if (!oldParam) continue;
-		if (!typeRefsEqual(oldParam.type, newParam.type)) changes.push(classifyParamChange("param-type-changed", name));
-		if (oldParam.required !== newParam.required) changes.push(classifyParamChange("param-required-changed", name, newParam.required));
+	for (const [name, newEntry] of newByName) {
+		const oldEntry = oldByName.get(name);
+		if (!oldEntry) continue;
+		if (!typeRefsEqual(oldEntry.p.type, newEntry.p.type)) if (primitivesDifferOnlyByFormat(oldEntry.p.type, newEntry.p.type)) {
+			const change = classifyParamChange("param-format-changed", name);
+			change.details = formatChangeDetails(oldEntry.p.type, newEntry.p.type);
+			changes.push(change);
+		} else changes.push(classifyParamChange("param-type-changed", name));
+		if (oldEntry.p.required !== newEntry.p.required) changes.push(classifyParamChange("param-required-changed", name, newEntry.p.required));
+		const oldDefault = serializeDefault(oldEntry.p.default);
+		const newDefault = serializeDefault(newEntry.p.default);
+		if (oldDefault !== newDefault) {
+			const change = classifyParamChange("param-default-changed", name);
+			change.oldDefault = oldDefault;
+			change.newDefault = newDefault;
+			change.paramLocation = newEntry.loc;
+			change.details = `default ${oldDefault ?? "<unset>"} → ${newDefault ?? "<unset>"}`;
+			changes.push(change);
+		}
 	}
 	return changes;
 }
+function serializeDefault(value) {
+	if (value === void 0) return null;
+	if (value === null) return "null";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
 //#endregion
 //#region src/differ/services.ts
 function diffServices(oldServices, newServices) {
@@ -6466,13 +6552,38 @@ function diffSpecs(oldSpec, newSpec) {
 		...diffEnums(oldSpec.enums, newSpec.enums),
 		...diffServices(oldSpec.services, newSpec.services)
 	];
+	const behaviorChanges = collectBehaviorChanges(changes);
 	return {
 		oldVersion: oldSpec.version,
 		newVersion: newSpec.version,
 		changes,
-		summary: summarize(changes)
+		behaviorChanges,
+		summary: {
+			...summarize(changes),
+			behaviorChanges: behaviorChanges.length
+		}
 	};
 }
+function collectBehaviorChanges(changes) {
+	const out = [];
+	for (const c of changes) {
+		if (c.kind !== "operation-modified") continue;
+		for (const pc of c.paramChanges) {
+			if (pc.kind !== "param-default-changed") continue;
+			out.push({
+				kind: "param-default-changed",
+				serviceName: c.serviceName,
+				operationName: c.operationName,
+				paramName: pc.paramName,
+				paramLocation: pc.paramLocation ?? "query",
+				oldDefault: pc.oldDefault ?? null,
+				newDefault: pc.newDefault ?? null,
+				classification: "breaking"
+			});
+		}
+	}
+	return out;
+}
 function diffEnums(oldEnums, newEnums) {
 	const changes = [];
 	const oldByName = new Map(oldEnums.map((e) => [e.name, e]));