@workos/oagen 0.3.0 → 0.4.0

package/dist/{diff-Cn6S74vV.mjs → diff-DcY93sii.mjs}

@@ -1,10 +1,147 @@
-import { A as walkTypeRef, C as assertNever, f as toSnakeCase, i as normalizeJsExtension, t as safeParse, x as RegistryError } from "./tree-sitter-DFRXfWg9.mjs";
+import { A as walkTypeRef, C as assertNever, f as toSnakeCase, i as normalizeJsExtension, t as safeParse, x as RegistryError } from "./tree-sitter-C53w_0WE.mjs";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
 import path from "node:path";
 import Parser from "tree-sitter";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+//#region src/ir/operation-hints.ts
+/** Minimal snake_case converter for path segments (avoids cross-layer import). */
+function toSnake(s) {
+	return s.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[-\s.]+/g, "_").toLowerCase();
+}
+/**
+* Action verbs recognised at the terminal path segment.
+* When a path ends with one of these, we use it as the verb instead of
+* deriving a CRUD verb from the HTTP method.
+*/
+const ACTION_VERBS = new Set([
+	"accept",
+	"activate",
+	"authorize",
+	"challenge",
+	"check",
+	"complete",
+	"confirm",
+	"deactivate",
+	"disable",
+	"enable",
+	"enroll",
+	"generate",
+	"reactivate",
+	"resend",
+	"revoke",
+	"send",
+	"verify"
+]);
+/** Map HTTP method → default CRUD verb. */
+const CRUD_VERB = {
+	get: "list",
+	post: "create",
+	put: "update",
+	patch: "update",
+	delete: "delete",
+	head: "get",
+	options: "list",
+	trace: "list"
+};
+/**
+* Naive singularization: strips trailing "s" with common-sense exceptions.
+* Good enough for API resource nouns; not a general-purpose English stemmer.
+*/
+function singularize(word) {
+	if (word.length <= 2) return word;
+	if (word.endsWith("ies")) return word.slice(0, -3) + "y";
+	if (word.endsWith("ses") || word.endsWith("zes") || word.endsWith("xes") || word.endsWith("ches") || word.endsWith("shes")) return word.slice(0, -2);
+	if (word.endsWith("ss") || word.endsWith("us") || word.endsWith("is")) return word;
+	if (word.endsWith("s")) return word.slice(0, -1);
+	return word;
+}
+/**
+* Derive a snake_case method name from an operation's HTTP method and path.
+*
+* Rules:
+* 1. Strip path-param segments (`{id}`, `{slug}`, etc.)
+* 2. If the terminal segment is an action verb, use it as the verb
+* 3. Otherwise, use the CRUD verb for the HTTP method
+* 4. For GET on a collection (no trailing {id}), use "list"; with {id}, use "get"
+* 5. For POST on a resource path, if only one path param, use "create" singular
+* 6. Singularize the resource noun for single-resource operations
+*/
+function deriveMethodName(op, _service) {
+	const segments = op.path.split("/").filter(Boolean);
+	const staticSegments = [];
+	let trailingParam = false;
+	for (const seg of segments) if (seg.startsWith("{") && seg.endsWith("}")) trailingParam = true;
+	else {
+		staticSegments.push(seg);
+		trailingParam = false;
+	}
+	if (staticSegments.length === 0) return `${CRUD_VERB[op.httpMethod] ?? "get"}_root`;
+	const terminal = toSnake(staticSegments[staticSegments.length - 1]);
+	if (ACTION_VERBS.has(terminal)) {
+		const context = staticSegments.slice(0, -1).filter((s) => !s.startsWith("{"));
+		const resource = context.length > 0 ? toSnake(singularize(context[context.length - 1])) : "";
+		if (resource) return `${terminal}_${resource}`;
+		return terminal;
+	}
+	let verb = CRUD_VERB[op.httpMethod] ?? "get";
+	if (op.httpMethod === "get" && trailingParam) verb = "get";
+	let resource = toSnake(terminal);
+	if (staticSegments.length >= 2) {
+		const penultimate = staticSegments[staticSegments.length - 2];
+		const penIdx = segments.lastIndexOf(penultimate);
+		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;
+	return `${verb}_${verb === "list" ? resource : noun}`;
+}
+/**
+* Resolve all operations in the spec, applying hints and mount rules.
+*
+* @param spec - The parsed API spec
+* @param hints - Per-operation overrides keyed by "METHOD /path"
+* @param mountRules - Service name → target service mappings
+* @returns Resolved operations ready for emitter consumption
+*/
+function resolveOperations(spec, hints, mountRules) {
+	const resolved = [];
+	const hintMap = hints ?? {};
+	const mounts = mountRules ?? {};
+	for (const service of spec.services) for (const op of service.operations) {
+		const hint = hintMap[`${op.httpMethod.toUpperCase()} ${op.path}`];
+		const methodName = hint?.name ?? deriveMethodName(op, service);
+		const mountOn = hint?.mountOn ?? mounts[service.name] ?? service.name;
+		let wrappers;
+		if (hint?.split) wrappers = hint.split.map((sh) => ({
+			name: sh.name,
+			targetVariant: sh.targetVariant,
+			defaults: sh.defaults ?? {},
+			inferFromClient: sh.inferFromClient ?? [],
+			exposedParams: sh.exposedParams ?? [],
+			optionalParams: [],
+			responseModelName: resolveResponseModelName(op)
+		}));
+		resolved.push({
+			operation: op,
+			service,
+			methodName,
+			mountOn,
+			wrappers
+		});
+	}
+	return resolved;
+}
+/** Extract the response model name from an operation (for wrapper metadata). */
+function resolveResponseModelName(op) {
+	if (op.httpMethod === "delete") return null;
+	const ref = op.response;
+	if (ref.kind === "model") return ref.name;
+	if (ref.kind === "nullable" && ref.inner.kind === "model") return ref.inner.name;
+	return null;
+}
+//#endregion
 //#region src/engine/merge-adapters/url-fingerprint.ts
 /**
 * Extract a URL path fingerprint from a method body using tree-sitter AST traversal.
@@ -913,8 +1050,9 @@ const phpMergeAdapter = {
 	testFilePatterns: [/Test\.php$/],
 	urlFingerprintConfig: PHP_URL_FINGERPRINT_CONFIG,
 	resolveGrammar: (mod) => {
-		if (typeof mod === "object" && mod !== null && "php" in mod) return mod.php;
-		return mod;
+		const m = mod?.default ?? mod;
+		if (typeof m === "object" && m !== null && "php" in m) return m.php;
+		return m;
 	},
 	parseStatements(tree, source) {
 		const imports = [];
@@ -1413,6 +1551,35 @@ async function extractStatements(source, language) {
 	return adapter.parseStatements(tree, source);
 }
 /**
+* Return a map of top-level class name → { bodyEndLine, bodyEndCol } using
+* tree-sitter.  `bodyEndLine` is 0-based.  For brace-delimited classes the
+* end points at the closing brace line; for indentation-delimited classes
+* it points one past the last line of the class body.
+*/
+async function extractClassEndLines(source, language) {
+	const tree = safeParse(await getParser(language), source);
+	const map = /* @__PURE__ */ new Map();
+	function processClassNode(node) {
+		const nameNode = node.childForFieldName("name");
+		if (!nameNode) return;
+		const name = nameNode.text;
+		const body = node.childForFieldName("body");
+		const endRow = body ? body.endPosition.row : node.endPosition.row;
+		if (source[body ? body.endIndex - 1 : node.endIndex - 1] === "}") map.set(name, { bodyEndLine: endRow });
+		else map.set(name, { bodyEndLine: endRow + 1 });
+	}
+	for (const child of tree.rootNode.children) {
+		if (child.type === "class_definition" || child.type === "class_declaration") processClassNode(child);
+		if (child.type === "decorated_definition") {
+			for (const inner of child.namedChildren) if (inner.type === "class_definition") processClassNode(inner);
+		}
+		if (child.type === "export_statement") {
+			for (const inner of child.namedChildren) if (inner.type === "class_declaration") processClassNode(inner);
+		}
+	}
+	return map;
+}
+/**
 * Merge generated content into an existing file.
 *
 * - Parses both files with tree-sitter
@@ -1761,15 +1928,18 @@ async function writeFiles(files, outputDir, options) {
 		}
 		const adapter = language ? getMergeAdapter(language) : void 0;
 		if (adapter?.testFilePatterns ? adapter.testFilePatterns.some((p) => p.test(file.path)) : isDefaultTestFile(file.path)) {
-			result.skipped.push(file.path);
-			continue;
+			if (!(header && existingContent.startsWith(header))) {
+				result.skipped.push(file.path);
+				continue;
+			}
 		}
 		if (existingContent === file.content) {
 			result.identical.push(file.path);
 			continue;
 		}
 		if (file.overwriteExisting) {
-			await fs.writeFile(fullPath, file.content, "utf-8");
+			const content = existingContent.includes("@oagen-ignore-start") && language && hasGrammar(language) ? await overwriteWithPreservedRegions(existingContent, file.content, language) : file.content;
+			await fs.writeFile(fullPath, content, "utf-8");
 			result.written.push(file.path);
 			continue;
 		}
@@ -1813,6 +1983,174 @@ async function writeFiles(files, outputDir, options) {
 function isDefaultTestFile(filePath) {
 	return /\.(spec|test)\.[jt]sx?$/.test(filePath) || filePath.endsWith("_test.go") || filePath.endsWith("_test.rb") || filePath.endsWith("_spec.rb") || /(?:^|\/)test_.*\.py$/.test(filePath) || filePath.endsWith("_test.py") || filePath.endsWith("Test.php") || filePath.endsWith("_test.rs") || /(?:^|\/)tests\/.*\.rs$/.test(filePath);
 }
+/**
+* Overwrite a file with generated content while preserving
+* `@oagen-ignore-start` / `@oagen-ignore-end` regions (and their
+* required imports) from the existing file.
+*
+* Uses tree-sitter via `extractClassEndLines` to find accurate class
+* boundaries so ignore blocks are inserted at the correct position even
+* when docstrings contain unindented text.
+*/
+async function overwriteWithPreservedRegions(existingContent, generatedContent, language) {
+	const existingLines = existingContent.split("\n");
+	const generatedLines = generatedContent.split("\n");
+	const blocks = [];
+	for (let i = 0; i < existingLines.length; i++) {
+		if (!existingLines[i].includes("@oagen-ignore-start")) continue;
+		const startIdx = i;
+		while (i < existingLines.length && !existingLines[i].includes("@oagen-ignore-end")) i++;
+		blocks.push({
+			containingClass: findContainingClass(existingLines, startIdx),
+			lines: existingLines.slice(startIdx, i + 1)
+		});
+	}
+	if (blocks.length === 0) return generatedContent;
+	const result = [...generatedLines];
+	spliceExtraImports(existingLines, result);
+	const classEndLines = await extractClassEndLines(result.join("\n"), language);
+	const blocksByClass = /* @__PURE__ */ new Map();
+	for (const b of blocks) {
+		if (!blocksByClass.has(b.containingClass)) blocksByClass.set(b.containingClass, []);
+		blocksByClass.get(b.containingClass).push(b.lines);
+	}
+	const replacedClasses = /* @__PURE__ */ new Set();
+	const handledBlockKeys = /* @__PURE__ */ new Set();
+	const replacements = [];
+	for (const [className, classBlocks] of blocksByClass) {
+		let targetClass = className;
+		if (!targetClass) for (const blockLines of classBlocks) {
+			for (const l of blockLines) {
+				const m = l.match(/^(?:export\s+)?class\s+(\w+)/);
+				if (m && classEndLines.has(m[1])) {
+					targetClass = m[1];
+					break;
+				}
+			}
+			if (targetClass) break;
+		}
+		if (!targetClass) continue;
+		if (!classBlocks.some((blockLines) => blockLines.some((l) => {
+			return l.match(/^(?:export\s+)?class\s+(\w+)/)?.[1] === targetClass;
+		}))) continue;
+		const info = classEndLines.get(targetClass);
+		if (!info) continue;
+		const startLine = findClassDeclarationStart(result, targetClass, info.bodyEndLine);
+		if (startLine < 0) continue;
+		const content = [];
+		for (const block of classBlocks) {
+			content.push("");
+			content.push(...block);
+		}
+		replacements.push({
+			startLine,
+			endLine: info.bodyEndLine,
+			content
+		});
+		replacedClasses.add(targetClass);
+		handledBlockKeys.add(className);
+	}
+	replacements.sort((a, b) => b.startLine - a.startLine);
+	for (const rep of replacements) result.splice(rep.startLine, rep.endLine - rep.startLine, ...rep.content);
+	let effectiveClassEndLines = classEndLines;
+	if (replacedClasses.size > 0) effectiveClassEndLines = await extractClassEndLines(result.join("\n"), language);
+	const insertions = [];
+	for (const [className, classBlocks] of blocksByClass) {
+		if (handledBlockKeys.has(className) || replacedClasses.has(className)) continue;
+		const info = className ? effectiveClassEndLines.get(className) : void 0;
+		const insertLine = info ? info.bodyEndLine : result.length;
+		const content = [];
+		for (const block of classBlocks) {
+			content.push("");
+			content.push(...block);
+		}
+		insertions.push({
+			line: insertLine,
+			content
+		});
+	}
+	insertions.sort((a, b) => b.line - a.line);
+	for (const ins of insertions) result.splice(ins.line, 0, ...ins.content);
+	return result.join("\n");
+}
+/** Scan backwards from `lineIdx` to find the nearest class declaration name. */
+function findContainingClass(lines, lineIdx) {
+	for (let j = lineIdx - 1; j >= 0; j--) {
+		const m = lines[j].match(/^(?:export\s+)?class\s+(\w+)/);
+		if (m) return m[1];
+	}
+	return "";
+}
+/**
+* Find the start line of a class declaration (including decorators above it)
+* by scanning backwards from `beforeLine`.
+*/
+function findClassDeclarationStart(lines, className, beforeLine) {
+	const classPattern = new RegExp(`^(?:export\\s+)?class\\s+${className}\\b`);
+	for (let i = beforeLine - 1; i >= 0; i--) {
+		if (!classPattern.test(lines[i])) continue;
+		let start = i;
+		while (start > 0 && /^\s*@\w+/.test(lines[start - 1])) start--;
+		return start;
+	}
+	return -1;
+}
+/**
+* Collect `from X import Y, Z` identifiers grouped by module, handling
+* both single-line and multiline (parenthesized) forms.
+*/
+function collectFromImports(lines) {
+	const byModule = /* @__PURE__ */ new Map();
+	for (let i = 0; i < lines.length; i++) {
+		if (!/^from\s+/.test(lines[i])) continue;
+		let fullText = lines[i];
+		if (fullText.includes("(") && !fullText.includes(")")) while (i + 1 < lines.length) {
+			i++;
+			fullText += " " + lines[i].trim();
+			if (lines[i].includes(")")) break;
+		}
+		const match = fullText.replace(/[()]/g, "").replace(/\s+/g, " ").trim().match(/^from\s+(\S+)\s+import\s+(.+)$/);
+		if (!match) continue;
+		const mod = match[1];
+		if (!byModule.has(mod)) byModule.set(mod, /* @__PURE__ */ new Set());
+		for (const id of match[2].split(",").map((s) => s.trim()).filter(Boolean)) byModule.get(mod).add(id);
+	}
+	return byModule;
+}
+/**
+* Add imports from the existing file that are absent from the generated
+* result. Handles both `import X` and `from X import Y` forms.
+* Mutates `resultLines` in place.
+*/
+function spliceExtraImports(existingLines, resultLines) {
+	const isSimpleImport = (l) => /^import\s+\w/.test(l);
+	const existingSimple = new Set(existingLines.filter(isSimpleImport).map((l) => l.trim()));
+	const generatedSimple = new Set(resultLines.filter(isSimpleImport).map((l) => l.trim()));
+	const extraSimple = [...existingSimple].filter((l) => !generatedSimple.has(l));
+	const existingFrom = collectFromImports(existingLines);
+	const generatedFrom = collectFromImports(resultLines);
+	const extraFromLines = [];
+	for (const [mod, existIds] of existingFrom) {
+		const genIds = generatedFrom.get(mod);
+		if (!genIds) extraFromLines.push(`from ${mod} import ${[...existIds].join(", ")}`);
+		else {
+			const extra = [...existIds].filter((id) => !genIds.has(id));
+			if (extra.length > 0) extraFromLines.push(`from ${mod} import ${extra.join(", ")}`);
+		}
+	}
+	const allExtra = [...extraSimple, ...extraFromLines];
+	if (allExtra.length === 0) return;
+	let lastImportIdx = -1;
+	for (let i = 0; i < resultLines.length; i++) if (isSimpleImport(resultLines[i]) || /^from\s+/.test(resultLines[i])) {
+		lastImportIdx = i;
+		if (resultLines[i].includes("(") && !resultLines[i].includes(")")) while (i + 1 < resultLines.length) {
+			i++;
+			lastImportIdx = i;
+			if (resultLines[i].includes(")")) break;
+		}
+	}
+	if (lastImportIdx >= 0) resultLines.splice(lastImportIdx + 1, 0, ...allExtra);
+}
 //#endregion
 //#region src/engine/generate-files.ts
 function buildEmitterContext(spec, options) {
@@ -1822,7 +2160,8 @@ function buildEmitterContext(spec, options) {
 		spec,
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
-		overlayLookup: options.overlayLookup
+		overlayLookup: options.overlayLookup,
+		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules)
 	};
 }
 /**
@@ -1852,6 +2191,7 @@ function collectReferencedNames(services, models) {
 		for (const err of op.errors) if (err.type) collectFromTypeRef(err.type);
 		if (op.successResponses) for (const sr of op.successResponses) collectFromTypeRef(sr.type);
 	}
+	for (const model of models) if (isDiscriminatedModel(model)) referencedModels.add(model.name);
 	const modelsByName = new Map(models.map((m) => [m.name, m]));
 	const visited = /* @__PURE__ */ new Set();
 	const queue = [...referencedModels];
@@ -1871,6 +2211,9 @@ function collectReferencedNames(services, models) {
 		enums: referencedEnums
 	};
 }
+function isDiscriminatedModel(model) {
+	return model.fields.some((field) => (field.name === "event" || field.name === "type" || field.name === "object") && field.type.kind === "literal");
+}
 /** Collect all generated files from an emitter (no headers, no path prefixes). */
 function generateAllFiles(spec, emitter, ctx) {
 	const referenced = collectReferencedNames(spec.services, spec.models);
@@ -1971,11 +2314,33 @@ async function treeShakeFiles(files, language) {
 		}
 		deps.set(file.path, fileDeps);
 	}
+	const codeExtensions = new Set([
+		".ts",
+		".js",
+		".tsx",
+		".jsx",
+		".py",
+		".rb",
+		".go",
+		".rs",
+		".kt",
+		".cs",
+		".ex",
+		".exs",
+		".php"
+	]);
 	const reachable = /* @__PURE__ */ new Set();
 	const queue = [];
-	for (const file of files) if (isRootFile(file.path)) {
-		reachable.add(file.path);
-		queue.push(file.path);
+	for (const file of files) {
+		const ext = file.path.slice(file.path.lastIndexOf("."));
+		if (!codeExtensions.has(ext)) {
+			reachable.add(file.path);
+			continue;
+		}
+		if (isRootFile(file.path)) {
+			reachable.add(file.path);
+			queue.push(file.path);
+		}
 	}
 	while (queue.length > 0) {
 		const current = queue.pop();
@@ -1999,11 +2364,61 @@ function mapFilesForTargetIntegration(files, language) {
 		};
 	});
 }
+/**
+* Resolve file-to-directory conflicts in the target.
+*
+* When a generated file creates a package directory (e.g., `api_keys/__init__.py`)
+* that would shadow an existing module file (e.g., `api_keys.py`), move the
+* module file's content into `_compat.py` inside the package and add a
+* re-export from `__init__.py`.  This preserves backward-compatible imports
+* (e.g., `from workos.api_keys import ApiKeysModule`) while the package directory
+* provides the generated models and resource classes.
+*/
+async function resolveFileToDirectoryConflicts(files, targetDir) {
+	const result = [...files];
+	const removals = [];
+	for (let i = 0; i < result.length; i++) {
+		const file = result[i];
+		const match = file.path.match(/^(.+)\/__init__\.py$/);
+		if (!match) continue;
+		const dirPath = match[1];
+		const moduleFilePath = `${dirPath}.py`;
+		const fullModulePath = path.join(targetDir, moduleFilePath);
+		let moduleContent;
+		try {
+			moduleContent = await fs.readFile(fullModulePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const compatPath = `${dirPath}/_compat.py`;
+		result.push({
+			path: compatPath,
+			content: moduleContent,
+			overwriteExisting: true
+		});
+		const compatImport = "from ._compat import *  # noqa: F401,F403  # pyright: ignore[reportUnusedImport]";
+		const existingContent = file.content.endsWith("\n") ? file.content : file.content + "\n";
+		result[i] = {
+			...file,
+			content: existingContent + compatImport + "\n"
+		};
+		removals.push(fullModulePath);
+	}
+	return {
+		files: result,
+		removals
+	};
+}
 async function integrateGeneratedFiles(opts) {
-	return writeFiles(await treeShakeFiles(mapFilesForTargetIntegration(opts.files, opts.language), opts.language), opts.targetDir, {
+	const { files: resolved, removals } = await resolveFileToDirectoryConflicts(await treeShakeFiles(mapFilesForTargetIntegration(opts.files, opts.language), opts.language), opts.targetDir);
+	const result = await writeFiles(resolved, opts.targetDir, {
 		language: opts.language,
 		header: opts.header
 	});
+	for (const filePath of removals) try {
+		await fs.unlink(filePath);
+	} catch {}
+	return result;
 }
 //#endregion
 //#region src/engine/formatter.ts
@@ -2064,7 +2479,11 @@ 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)`);
-		const allTargetFiles = [...targetResult.written, ...targetResult.merged];
+		const allTargetFiles = [
+			...targetResult.written,
+			...targetResult.merged,
+			...targetResult.identical
+		];
 		if (allTargetFiles.length > 0) await formatTargetFiles(emitter, options.target, allTargetFiles);
 	}
 	return withHeaders;
@@ -2427,6 +2846,6 @@ function summarize(changes) {
 	};
 }
 //#endregion
-export { integrateGeneratedFiles as a, applyFileHeaders as c, generateAllFiles as d, generateFiles as f, generate as i, buildEmitterContext as l, getEmitter as n, mapFilesForTargetIntegration as o, registerEmitter as r, treeShakeFiles as s, diffSpecs as t, collectReferencedNames as u };
+export { integrateGeneratedFiles as a, applyFileHeaders as c, generateAllFiles as d, generateFiles as f, generate as i, buildEmitterContext as l, resolveOperations as m, getEmitter as n, mapFilesForTargetIntegration as o, deriveMethodName as p, registerEmitter as r, treeShakeFiles as s, diffSpecs as t, collectReferencedNames as u };
 
-//# sourceMappingURL=diff-Cn6S74vV.mjs.map
+//# sourceMappingURL=diff-DcY93sii.mjs.map