@workos/oagen 0.5.0 → 0.6.0

package/dist/cli/index.mjs

@@ -679,6 +679,86 @@ function buildFieldFromSchema(fieldName, fieldSchema, contextName, requiredSet)
 		example: fieldSchema.example
 	};
 }
+/**
+* If every non-null oneOf/anyOf variant is a string-valued const, return the
+* list of those const values so the union can collapse into a single enum.
+* Returns null when any variant isn't a pure string-const (model ref,
+* number const, nullable, etc.).
+*/
+function collectLiteralStringConsts(variants) {
+	if (variants.length === 0) return null;
+	const values = [];
+	for (const v of variants) {
+		if (typeof v.const === "string") {
+			values.push(v.const);
+			continue;
+		}
+		if (Array.isArray(v.enum) && v.enum.length === 1 && typeof v.enum[0] === "string") {
+			values.push(v.enum[0]);
+			continue;
+		}
+		return null;
+	}
+	return values;
+}
+/** Build an EnumRef the same way the regular enum path does for naming. */
+function buildSyntheticEnumRef(values, contextName, parentModelName) {
+	const baseName = toPascalCase(contextName ?? "UnknownEnum");
+	const cleanParent = parentModelName ? stripListItemMarkers(parentModelName) : void 0;
+	return {
+		kind: "enum",
+		name: cleanParent && !baseName.startsWith(cleanParent) ? `${cleanParent}${baseName}` : baseName,
+		values
+	};
+}
+/**
+* Detect an implicit discriminator on an oneOf where every variant is an
+* object schema that pins the same property to a const value. Returns
+* { property, mapping } so the IR can represent the union as discriminated
+* without needing an explicit `discriminator:` key in the spec.
+*
+* Both shapes are supported:
+*   { properties: { event: { const: "x" } }, required: ["event"] }
+*   { properties: { event: { type: "string", enum: ["x"] } } }
+*
+* Returns null when any variant doesn't fit the pattern or when variants
+* disagree on which property carries the discriminator.
+*/
+function detectConstPropertyDiscriminator(variants) {
+	if (variants.length < 2) return null;
+	let candidateProperty = null;
+	const candidates = Object.keys(variants[0]?.properties ?? {});
+	for (const propName of candidates) if (variants.every((v) => getConstPropertyValue(v, propName) !== null)) {
+		candidateProperty = propName;
+		break;
+	}
+	if (!candidateProperty) return null;
+	const mapping = {};
+	for (const v of variants) {
+		const value = getConstPropertyValue(v, candidateProperty);
+		if (value === null) return null;
+		const variantName = resolveVariantModelName(v);
+		if (!variantName) return null;
+		mapping[value] = variantName;
+	}
+	return {
+		property: candidateProperty,
+		mapping
+	};
+}
+function getConstPropertyValue(schema, property) {
+	const prop = schema.properties?.[property];
+	if (!prop) return null;
+	if (typeof prop.const === "string") return prop.const;
+	if (Array.isArray(prop.enum) && prop.enum.length === 1 && typeof prop.enum[0] === "string") return prop.enum[0];
+	return null;
+}
+function resolveVariantModelName(schema) {
+	if (schema.$ref) return resolveSchemaName(schema.$ref.replace(/^#\/components\/schemas\//, ""));
+	const title = typeof schema["title"] === "string" ? schema["title"] : null;
+	if (title) return resolveSchemaName(title);
+	return null;
+}
 function extractEnum(name, schema) {
 	return {
 		name,
@@ -902,6 +982,15 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			kind: "nullable",
 			inner: schemaToTypeRef(nonNullVariants[0], contextName, parentModelName)
 		};
+		const literalStrings = collectLiteralStringConsts(nonNullVariants);
+		if (literalStrings !== null && literalStrings.length >= 2) {
+			const enumRef = buildSyntheticEnumRef(literalStrings, contextName, parentModelName);
+			return nullVariant ? {
+				kind: "nullable",
+				inner: enumRef
+			} : enumRef;
+		}
+		const syntheticDiscriminator = !schema.discriminator && compositionKind === "oneOf" ? detectConstPropertyDiscriminator(nonNullVariants) : null;
 		const variants = rawVariants.filter((v) => v.type !== "null").map((v) => schemaToTypeRef(v, contextName, parentModelName));
 		const hasNull = !!nullVariant;
 		const union = {
@@ -911,7 +1000,7 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			...schema.discriminator ? { discriminator: {
 				property: schema.discriminator.propertyName,
 				mapping: Object.fromEntries(Object.entries(schema.discriminator.mapping ?? {}).map(([k, v]) => [k, v.replace(/^#\/components\/schemas\//, "")]))
-			} } : {}
+			} } : syntheticDiscriminator ? { discriminator: syntheticDiscriminator } : {}
 		};
 		return hasNull ? {
 			kind: "nullable",
@@ -2598,6 +2687,41 @@ function findPrecedingKdoc(children, index, source) {
 	}
 	return null;
 }
+function extractKotlinClassMembers(classBody, source) {
+	const members = [];
+	const children = classBody.namedChildren;
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		let memberName = null;
+		if (child.type === "property_declaration") memberName = child.children.find((c) => c.type === "variable_declaration")?.children.find((c) => c.type === "simple_identifier")?.text ?? null;
+		else if (child.type === "function_declaration") memberName = child.children.find((c) => c.type === "simple_identifier")?.text ?? null;
+		else if (child.type === "companion_object") memberName = "companion";
+		if (!memberName) continue;
+		let endIdx = child.endIndex;
+		if (child.type === "property_declaration") while (i + 1 < children.length) {
+			const next = children[i + 1];
+			if (next.type === "getter" || next.type === "setter") {
+				endIdx = next.endIndex;
+				i++;
+			} else break;
+		}
+		let startIdx = child.startIndex;
+		for (let k = i - 1; k >= 0; k--) {
+			const prev = children[k];
+			if (prev.type === "multiline_comment") {
+				if (source.slice(prev.startIndex, prev.endIndex).startsWith("/**")) startIdx = prev.startIndex;
+				break;
+			}
+			if (prev.type === "line_comment") continue;
+			break;
+		}
+		members.push({
+			key: memberName,
+			text: source.slice(startIdx, endIdx)
+		});
+	}
+	return members;
+}
 const kotlinMergeAdapter = {
 	language: "kotlin",
 	grammarModule: "tree-sitter-kotlin",
@@ -2638,6 +2762,33 @@ const kotlinMergeAdapter = {
 	renderImports(imports) {
 		return imports.map((entry) => entry.text);
 	},
+	shouldSkipDeepMerge(_symbolName, existingMemberKeys, newMembers) {
+		const newText = newMembers.map((m) => m.text).join("\n");
+		for (const match of newText.matchAll(/this\.(\w+)/g)) {
+			const propName = match[1];
+			if (propName && !existingMemberKeys.has(propName)) return true;
+		}
+		return false;
+	},
+	extractMembers(tree, source) {
+		const result = /* @__PURE__ */ new Map();
+		for (const child of tree.rootNode.children) {
+			if (child.type !== "class_declaration") continue;
+			const nameNode = child.children.find((c) => c.type === "type_identifier");
+			if (!nameNode) continue;
+			const body = child.children.find((c) => c.type === "class_body");
+			if (!body) continue;
+			const members = extractKotlinClassMembers(body, source);
+			const firstMember = body.firstNamedChild;
+			const memberIndent = firstMember ? " ".repeat(firstMember.startPosition.column) : void 0;
+			result.set(nameNode.text, {
+				members,
+				bodyEndLine: body.endPosition.row,
+				memberIndent
+			});
+		}
+		return result;
+	},
 	extractDocstrings(tree, source) {
 		const result = /* @__PURE__ */ new Map();
 		const rootChildren = tree.rootNode.children;
@@ -3687,10 +3838,10 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			if (newMembers.length > 0) {
 				if (adapter.shouldSkipDeepMerge?.(symbolName, existingMemberKeys, newMembers)) continue;
 				const indent = existSymbol.memberIndent ?? "  ";
-				const insertText = newMembers.map((m) => indent + m.text).join("\n");
+				const insertText = newMembers.map((m) => indent + m.text).join("\n\n");
 				insertions.push({
 					line: existSymbol.bodyEndLine,
-					text: insertText
+					text: "\n" + insertText
 				});
 				deepAdded += newMembers.length;
 			}
@@ -4251,7 +4402,7 @@ function deriveMethodName(op, _service) {
 		const termIdx = segments.lastIndexOf(staticSegments[staticSegments.length - 1]);
 		if (segments.slice(penIdx + 1, termIdx).some((s) => s.startsWith("{"))) resource = `${toSnake(singularize(penultimate))}_${resource}`;
 	}
-	const noun = trailingParam ? singularize(resource) : resource;
+	const noun = trailingParam || verb === "create" ? singularize(resource) : resource;
 	return `${verb}_${verb === "list" ? resource : noun}`;
 }
 /**
@@ -4277,7 +4428,7 @@ function resolveOperations(spec, hints, mountRules) {
 			defaults: sh.defaults ?? {},
 			inferFromClient: sh.inferFromClient ?? [],
 			exposedParams: sh.exposedParams ?? [],
-			optionalParams: [],
+			optionalParams: sh.optionalParams ?? [],
 			responseModelName: resolveResponseModelName(op)
 		}));
 		resolved.push({
@@ -4287,7 +4438,8 @@ function resolveOperations(spec, hints, mountRules) {
 			mountOn,
 			wrappers,
 			defaults: hint?.defaults ?? {},
-			inferFromClient: hint?.inferFromClient ?? []
+			inferFromClient: hint?.inferFromClient ?? [],
+			urlBuilder: hint?.urlBuilder ?? false
 		});
 	}
 	return resolved;
@@ -4310,7 +4462,9 @@ function buildEmitterContext(spec, options) {
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
 		overlayLookup: options.overlayLookup,
-		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules)
+		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules),
+		targetDir: options.target,
+		priorTargetManifestPaths: options.priorTargetManifestPaths
 	};
 }
 /**
@@ -4429,7 +4583,7 @@ function resolveImportPath(fromFilePath, importModulePath, knownPaths) {
 */
 function isRootFile(filePath) {
 	if (filePath.includes("/fixtures/")) return false;
-	if (filePath.endsWith(".spec.ts") || filePath.endsWith(".test.ts")) return false;
+	if (filePath.endsWith(".spec.ts") || filePath.endsWith(".test.ts")) return true;
 	if (filePath.includes("/serializers/")) return false;
 	if (filePath.includes("/interfaces/") && !filePath.endsWith("/index.ts")) return false;
 	return true;
@@ -4566,7 +4720,10 @@ async function integrateGeneratedFiles(opts) {
 	for (const filePath of removals) try {
 		await fs.unlink(filePath);
 	} catch {}
-	return result;
+	return {
+		...result,
+		emittedPaths: resolved.map((f) => f.path)
+	};
 }
 //#endregion
 //#region src/engine/formatter.ts
@@ -4601,9 +4758,141 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 	}
 }
 //#endregion
+//#region src/engine/manifest.ts
+/**
+* Prune-manifest support for `oagen generate`.
+*
+* The manifest records every auto-generated file emitted on the previous run,
+* relative to the directory it lives in (either the `--output` standalone dir
+* or the `--target` integration dir).  On the next run we diff the previous
+* list against the current emission set and delete anything that's no longer
+* produced — preventing stale-file accumulation across regens.
+*
+* Design notes:
+*  - The manifest is versioned so future format changes can be handled safely.
+*  - Paths are stored sorted for deterministic diffs in git.
+*  - Deletion is gated on a header guard when one is available: we only remove
+*    files whose contents start with the auto-generated header.  This protects
+*    a hand-maintained file that happens to share a name with a previously
+*    generated one (extremely rare, but worth catching).
+*  - On first adoption (no previous manifest), pruning is skipped and a
+*    one-line notice is printed — no surprise deletions.
+*/
+const MANIFEST_FILENAME = ".oagen-manifest.json";
+const MANIFEST_VERSION = 1;
+/** Read `.oagen-manifest.json` from a directory.  Returns null if absent or malformed. */
+async function readManifest(dir) {
+	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
+	let raw;
+	try {
+		raw = await fs.readFile(manifestPath, "utf-8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.version !== "number" || typeof parsed.language !== "string" || typeof parsed.generatedAt !== "string" || !Array.isArray(parsed.files) || !parsed.files.every((p) => typeof p === "string")) return null;
+		if (parsed.version > MANIFEST_VERSION) {
+			console.warn(`[oagen] ${MANIFEST_FILENAME} schema version ${parsed.version} is newer than supported (${MANIFEST_VERSION}); ignoring for pruning.`);
+			return null;
+		}
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/** Write `.oagen-manifest.json` to a directory with sorted paths. */
+async function writeManifest(dir, opts) {
+	const manifest = {
+		version: MANIFEST_VERSION,
+		language: opts.language,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		files: [...new Set(opts.files)].sort()
+	};
+	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
+	await fs.mkdir(dir, { recursive: true });
+	await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+/** Return the set of previous paths no longer present in the current emission. */
+function computeStalePaths(prev, currentPaths) {
+	const current = new Set(currentPaths);
+	return prev.files.filter((p) => !current.has(p)).sort();
+}
+/**
+* Delete stale files from `dir`.
+*
+* When `header` is provided, a file is only deleted if its contents start with
+* that header — so hand-maintained files that somehow collide with a previously
+* generated path can't be clobbered.  When `header` is omitted, the guard is
+* skipped (useful for non-source artifacts like fixture JSON).
+*
+* Returns lists for reporting.  Empty parent directories are removed after
+* deletion, up to (but not including) `dir` itself.
+*/
+async function pruneStaleFiles(dir, paths, opts = {}) {
+	const pruned = [];
+	const preserved = [];
+	const missing = [];
+	for (const relPath of paths) {
+		const fullPath = path$1.join(dir, relPath);
+		let content;
+		try {
+			content = await fs.readFile(fullPath, "utf-8");
+		} catch {
+			missing.push(relPath);
+			continue;
+		}
+		if (opts.header && !content.startsWith(opts.header)) {
+			preserved.push(relPath);
+			continue;
+		}
+		try {
+			await fs.unlink(fullPath);
+			pruned.push(relPath);
+		} catch {
+			missing.push(relPath);
+			continue;
+		}
+		await removeEmptyParents(path$1.dirname(fullPath), dir);
+	}
+	return {
+		pruned,
+		preserved,
+		missing
+	};
+}
+/**
+* Walk up from `startDir` removing empty directories until we hit `stopDir`
+* (exclusive) or a non-empty directory.  Silently ignores errors.
+*/
+async function removeEmptyParents(startDir, stopDir) {
+	let current = path$1.resolve(startDir);
+	const stop = path$1.resolve(stopDir);
+	while (current.startsWith(stop + path$1.sep) && current !== stop) {
+		let entries;
+		try {
+			entries = await fs.readdir(current);
+		} catch {
+			return;
+		}
+		if (entries.length > 0) return;
+		try {
+			await fs.rmdir(current);
+		} catch {
+			return;
+		}
+		current = path$1.dirname(current);
+	}
+}
+//#endregion
 //#region src/engine/orchestrator.ts
 async function generate(spec, emitter, options) {
-	const { files: withHeaders, header } = generateFiles(spec, emitter, options);
+	const targetManifestForCtx = options.target && !options.noPrune ? await readManifest(options.target) : null;
+	const priorTargetManifestPaths = targetManifestForCtx ? new Set(targetManifestForCtx.files) : void 0;
+	const { files: withHeaders, header } = generateFiles(spec, emitter, {
+		...options,
+		priorTargetManifestPaths
+	});
 	if (options.dryRun) {
 		if (options.target) {
 			console.log(`\nTarget integration (${options.target}):`);
@@ -4611,13 +4900,25 @@ async function generate(spec, emitter, options) {
 		}
 		return withHeaders;
 	}
+	const outputPrevManifest = options.noPrune ? null : await readManifest(options.outputDir);
 	const writeResult = await writeFiles(withHeaders, options.outputDir, {
 		language: emitter.language,
 		header
 	});
 	if (writeResult.merged.length > 0) console.log(`Merged into ${writeResult.merged.length} existing files (additive only)`);
 	if (writeResult.ignored.length > 0) console.log(`Ignored ${writeResult.ignored.length} files (@oagen-ignore-file)`);
+	const outputEmittedPaths = withHeaders.map((f) => f.path);
+	await applyManifestPrune({
+		dir: options.outputDir,
+		label: "Output",
+		prevManifest: outputPrevManifest,
+		currentPaths: outputEmittedPaths,
+		language: emitter.language,
+		header,
+		noPrune: options.noPrune
+	});
 	if (options.target) {
+		const targetPrevManifest = targetManifestForCtx;
 		const targetResult = await integrateGeneratedFiles({
 			files: withHeaders,
 			language: emitter.language,
@@ -4627,6 +4928,15 @@ async function generate(spec, emitter, options) {
 		if (targetResult.written.length > 0) console.log(`Target: created ${targetResult.written.length} new files`);
 		if (targetResult.merged.length > 0) console.log(`Target: merged into ${targetResult.merged.length} existing files (additive only)`);
 		if (targetResult.skipped.length > 0) console.log(`Target: skipped ${targetResult.skipped.length} files (excluded or no grammar)`);
+		await applyManifestPrune({
+			dir: options.target,
+			label: "Target",
+			prevManifest: targetPrevManifest,
+			currentPaths: targetResult.emittedPaths,
+			language: emitter.language,
+			header,
+			noPrune: options.noPrune
+		});
 		const allTargetFiles = [
 			...targetResult.written,
 			...targetResult.merged,
@@ -4636,6 +4946,40 @@ async function generate(spec, emitter, options) {
 	}
 	return withHeaders;
 }
+/**
+* Prune files recorded in the previous manifest but absent from the current emission,
+* then write the fresh manifest.  Safe on first adoption (no previous manifest).
+*/
+async function applyManifestPrune(opts) {
+	if (opts.noPrune) {
+		await writeManifest(opts.dir, {
+			language: opts.language,
+			files: opts.currentPaths
+		});
+		return;
+	}
+	if (!opts.prevManifest) {
+		console.log(`${opts.label}: no ${MANIFEST_FILENAME} found — skipping prune (this baseline manifest will be written now).`);
+		await writeManifest(opts.dir, {
+			language: opts.language,
+			files: opts.currentPaths
+		});
+		return;
+	}
+	const stale = computeStalePaths(opts.prevManifest, opts.currentPaths);
+	if (stale.length > 0) {
+		const { pruned, preserved } = await pruneStaleFiles(opts.dir, stale, { header: opts.header });
+		if (pruned.length > 0) console.log(`${opts.label}: pruned ${pruned.length} stale file${pruned.length === 1 ? "" : "s"}`);
+		if (preserved.length > 0) {
+			console.log(`${opts.label}: preserved ${preserved.length} file${preserved.length === 1 ? "" : "s"} in previous manifest but lacking the auto-generated header (possibly hand-edited).`);
+			for (const p of preserved) console.log(`  ${p}`);
+		}
+	}
+	await writeManifest(opts.dir, {
+		language: opts.language,
+		files: opts.currentPaths
+	});
+}
 //#endregion
 //#region src/engine/registry.ts
 const emitters = /* @__PURE__ */ new Map();
@@ -5320,7 +5664,8 @@ async function generateCommand(opts) {
 		apiSurface,
 		overlayLookup,
 		operationHints: opts.operationHints,
-		mountRules: opts.mountRules
+		mountRules: opts.mountRules,
+		noPrune: opts.prune === false
 	});
 	if (opts.dryRun) for (const f of files) console.log(f.path);
 	else {
@@ -7036,7 +7381,7 @@ program.command("parse").description("Parse an OpenAPI spec and output IR as JSO
 	}
 	return parseCommand(opts);
 });
-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("--manifest <path>", "Path to smoke-manifest.json for method overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").action((opts) => {
+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("--manifest <path>", "Path to smoke-manifest.json for method 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;
 	if (!opts.spec) {
 		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");