@workos/oagen 0.11.0 → 0.13.0

package/README.md

@@ -196,6 +196,11 @@ export default {
     Connections: 'SSO',           // All Connections ops mount on SSO
     DirectoryGroups: 'DirectorySync',
   },
+  modelHints: {
+    // Pin a model's placement when "first service to reference it wins"
+    // would otherwise drift as the spec evolves.
+    User: 'UserManagementUsers',
+  },
 };
 ```
 

package/dist/cli/index.mjs

@@ -2278,7 +2278,7 @@ function validateModelRefs(spec) {
 //#region src/parser/parse.ts
 async function parseSpec(specPath, options) {
 	const { parsed } = await loadAndBundleSpec(specPath);
-	const spec = parsed;
+	const spec = options?.transformSpec ? options.transformSpec(parsed) : parsed;
 	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 });
@@ -2326,7 +2326,11 @@ function extractAuthSchemes(securitySchemes) {
 //#endregion
 //#region src/cli/parse.ts
 async function parseCommand(opts) {
-	const ir = await parseSpec(opts.spec);
+	const ir = await parseSpec(opts.spec, {
+		operationIdTransform: opts.operationIdTransform,
+		schemaNameTransform: opts.schemaNameTransform,
+		transformSpec: opts.transformSpec
+	});
 	console.log(JSON.stringify(ir, null, 2));
 }
 //#endregion
@@ -4289,7 +4293,7 @@ async function writeFiles(files, outputDir, options) {
 			continue;
 		}
 		if (file.skipIfExists) {
-			if (header && !existingContent.startsWith(header)) await fs.writeFile(fullPath, header + "\n\n" + existingContent, "utf-8");
+			if (header && !existingContent.startsWith(header) && !file.path.endsWith(".json")) await fs.writeFile(fullPath, header + "\n\n" + existingContent, "utf-8");
 			result.skipped.push(file.path);
 			continue;
 		}
@@ -4700,6 +4704,7 @@ function buildEmitterContext(spec, options) {
 		apiSurface: options.apiSurface,
 		overlayLookup: options.overlayLookup,
 		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules),
+		modelHints: options.modelHints,
 		targetDir: options.target,
 		priorTargetManifestPaths: options.priorTargetManifestPaths
 	};
@@ -5906,7 +5911,8 @@ function expandDocUrls(spec, docUrl) {
 async function generateCommand(opts) {
 	let ir = await parseSpec(opts.spec, {
 		operationIdTransform: opts.operationIdTransform,
-		schemaNameTransform: opts.schemaNameTransform
+		schemaNameTransform: opts.schemaNameTransform,
+		transformSpec: opts.transformSpec
 	});
 	if (opts.docUrl) ir = expandDocUrls(ir, opts.docUrl);
 	const emitter = getEmitter(opts.lang);
@@ -5932,6 +5938,7 @@ async function generateCommand(opts) {
 		overlayLookup,
 		operationHints: opts.operationHints,
 		mountRules: opts.mountRules,
+		modelHints: opts.modelHints,
 		noPrune: opts.prune === false
 	});
 	if (opts.dryRun) for (const f of files) console.log(f.path);
@@ -6291,7 +6298,8 @@ function summarize(changes) {
 async function diffCommand(opts) {
 	const parseOptions = {
 		operationIdTransform: opts.operationIdTransform,
-		schemaNameTransform: opts.schemaNameTransform
+		schemaNameTransform: opts.schemaNameTransform,
+		transformSpec: opts.transformSpec
 	};
 	let [oldSpec, newSpec] = await Promise.all([parseSpec(opts.old, parseOptions), parseSpec(opts.new, parseOptions)]);
 	if (opts.docUrl) {
@@ -6666,7 +6674,10 @@ 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, { schemaNameTransform: opts.schemaNameTransform }));
+		enrichWithSpecContext(snapshot, await parseSpec(opts.spec, {
+			schemaNameTransform: opts.schemaNameTransform,
+			transformSpec: opts.transformSpec
+		}));
 	}
 	const outputPath = resolve(opts.output, SNAPSHOT_FILENAME);
 	writeFileSync(outputPath, JSON.stringify(snapshot, null, 2));
@@ -7209,12 +7220,95 @@ function diffSnapshots(baseline, candidate, policy) {
 		if (isServiceWrapperConstructor(candSym, serviceAccessors)) continue;
 		changes.push(classifyAddedSymbol(candSym));
 	}
+	detectForkedSchemas(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;
+}
+/**
+* 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
@@ -7298,7 +7392,8 @@ function generateReport(diff, language) {
 			provenance: c.provenance,
 			old: c.old,
 			new: c.new,
-			...c.message ? { message: c.message } : {}
+			...c.message ? { message: c.message } : {},
+			...c.remediation ? { remediation: c.remediation } : {}
 		}))
 	};
 }
@@ -7319,6 +7414,7 @@ function formatHumanSummary(diff, opts) {
 		lines.push("  Breaking:");
 		for (const c of breaking) {
 			lines.push(`    [${c.category}] ${c.symbol} — ${c.message}`);
+			if (c.remediation) lines.push(`      hint: ${c.remediation}`);
 			if (opts?.explain && c.provenance !== "unknown") lines.push(`      provenance: ${c.provenance}`);
 		}
 	}
@@ -7327,6 +7423,7 @@ function formatHumanSummary(diff, opts) {
 		lines.push("  Soft-risk:");
 		for (const c of softRisk) {
 			lines.push(`    [${c.category}] ${c.symbol} — ${c.message}`);
+			if (c.remediation) lines.push(`      hint: ${c.remediation}`);
 			if (opts?.explain && c.provenance !== "unknown") lines.push(`      provenance: ${c.provenance}`);
 		}
 	}
@@ -7893,7 +7990,7 @@ function printCompatResult(result, baseline) {
 	console.log(`compat: ${result.preservationScore}% (${result.preservedSymbols}/${result.totalBaselineSymbols} symbols preserved)`);
 }
 async function verifyCommand(opts) {
-	const { spec, oldSpec, lang, output, apiSurface, rawResults, smokeConfig, smokeRunner, scope, diagnostics, operationIdTransform, schemaNameTransform, compatConfig, compatReport, compatExplain } = opts;
+	const { spec, oldSpec, lang, output, apiSurface, rawResults, smokeConfig, smokeRunner, scope, diagnostics, operationIdTransform, schemaNameTransform, transformSpec, compatConfig, compatReport, compatExplain } = opts;
 	const maxRetries = opts.maxRetries ?? 3;
 	const diagData = {};
 	const effectiveFailOn = opts.compatFailOn ?? compatConfig?.failOn ?? "breaking";
@@ -7909,7 +8006,8 @@ async function verifyCommand(opts) {
 		let parsedSpec;
 		if (effectiveScope === "spec-only" && spec) parsedSpec = await parseSpec(spec, {
 			operationIdTransform,
-			schemaNameTransform
+			schemaNameTransform,
+			transformSpec
 		});
 		else if (effectiveScope === "spec-only") throw new CommandError("error: --scope spec-only requires --spec <path>", "", 1);
 		const compatFlow = parsedSpec && maxRetries > 0 ? await runOverlayRetryLoop({
@@ -7976,10 +8074,12 @@ async function verifyCommand(opts) {
 		console.log(separator);
 		const stalenessResult = runStalenessCheck(baseline, await parseSpec(oldSpec, {
 			operationIdTransform,
-			schemaNameTransform
+			schemaNameTransform,
+			transformSpec
 		}), await parseSpec(spec, {
 			operationIdTransform,
-			schemaNameTransform
+			schemaNameTransform,
+			transformSpec
 		}), lang);
 		if (stalenessResult.violations.length > 0) {
 			console.log(`Found ${stalenessResult.violations.length} stale symbol(s):`);
@@ -8279,7 +8379,8 @@ async function initCommand(opts) {
 async function resolveCommand(opts) {
 	let ir = await parseSpec(opts.spec, {
 		operationIdTransform: opts.operationIdTransform,
-		schemaNameTransform: opts.schemaNameTransform
+		schemaNameTransform: opts.schemaNameTransform,
+		transformSpec: opts.transformSpec
 	});
 	if (opts.docUrl) ir = expandDocUrls(ir, opts.docUrl);
 	const resolved = resolveOperations(ir, opts.operationHints, opts.mountRules);
@@ -8375,9 +8476,11 @@ const explicitConfigPath = configArgIdx !== -1 ? process.argv[configArgIdx + 1]
 let configSmokeRunners;
 let configOperationIdTransform;
 let configSchemaNameTransform;
+let configTransformSpec;
 let configDocUrl;
 let configOperationHints;
 let configMountRules;
+let configModelHints;
 let configCompat;
 try {
 	const config = await loadConfig(explicitConfigPath);
@@ -8386,9 +8489,11 @@ try {
 		configSmokeRunners = config.smokeRunners;
 		configOperationIdTransform = config.operationIdTransform;
 		configSchemaNameTransform = config.schemaNameTransform;
+		configTransformSpec = config.transformSpec;
 		configDocUrl = config.docUrl;
 		configOperationHints = config.operationHints;
 		configMountRules = config.mountRules;
+		configModelHints = config.modelHints;
 		configCompat = config.compat;
 	}
 } catch (err) {
@@ -8401,7 +8506,12 @@ program.command("parse").description("Parse an OpenAPI spec and output IR as JSO
 		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");
 		process.exit(1);
 	}
-	return parseCommand(opts);
+	return parseCommand({
+		...opts,
+		operationIdTransform: configOperationIdTransform,
+		schemaNameTransform: configSchemaNameTransform,
+		transformSpec: configTransformSpec
+	});
 });
 program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
@@ -8413,9 +8523,11 @@ program.command("generate").description("Run a registered emitter against an Ope
 		...opts,
 		operationIdTransform: configOperationIdTransform,
 		schemaNameTransform: configSchemaNameTransform,
+		transformSpec: configTransformSpec,
 		docUrl: configDocUrl,
 		operationHints: configOperationHints,
-		mountRules: configMountRules
+		mountRules: configMountRules,
+		modelHints: configModelHints
 	}).catch(handleError);
 });
 program.command("diff").description("Compare two OpenAPI specs and output a diff report").requiredOption("--old <path>", "Path to old spec").requiredOption("--new <path>", "Path to new spec").action((opts) => {
@@ -8423,6 +8535,7 @@ program.command("diff").description("Compare two OpenAPI specs and output a diff
 		...opts,
 		operationIdTransform: configOperationIdTransform,
 		schemaNameTransform: configSchemaNameTransform,
+		transformSpec: configTransformSpec,
 		docUrl: configDocUrl
 	}).catch(handleError);
 });
@@ -8434,7 +8547,8 @@ program.command("compat-extract").description("Extract a compat snapshot from a
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	compatExtractCommand({
 		...opts,
-		schemaNameTransform: configSchemaNameTransform
+		schemaNameTransform: configSchemaNameTransform,
+		transformSpec: configTransformSpec
 	}).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) => {
@@ -8451,6 +8565,7 @@ program.command("verify").description("Run smoke tests (and optional compat chec
 		maxRetries: parseInt(opts.maxRetries, 10),
 		operationIdTransform: configOperationIdTransform,
 		schemaNameTransform: configSchemaNameTransform,
+		transformSpec: configTransformSpec,
 		compatConfig: configCompat,
 		compatReport: opts.compatReport,
 		compatFailOn: opts.compatFailOn,
@@ -8468,6 +8583,7 @@ program.command("resolve").description("Resolve operation names from spec and ou
 		...opts,
 		operationIdTransform: configOperationIdTransform,
 		schemaNameTransform: configSchemaNameTransform,
+		transformSpec: configTransformSpec,
 		docUrl: configDocUrl,
 		operationHints: configOperationHints,
 		mountRules: configMountRules