@rexeus/typeweaver-gen 0.7.0 → 0.9.0

package/dist/index.mjs

@@ -1,7 +1,237 @@
+import { HttpMethod, HttpStatusCodeNameMap, isNamedResponseDefinition, validateUniqueResponseNames } from "@rexeus/typeweaver-core";
+import { z } from "zod";
 import fs from "node:fs";
 import path from "node:path";
-import { render } from "ejs";
-
+import ejs from "ejs";
+//#region src/errors/DerivedResponseCycleError.ts
+var DerivedResponseCycleError = class extends Error {
+	constructor(responseName) {
+		super(`Derived response '${responseName}' contains a cyclic lineage.`);
+		this.name = "DerivedResponseCycleError";
+	}
+};
+//#endregion
+//#region src/errors/DuplicateOperationIdError.ts
+var DuplicateOperationIdError = class extends Error {
+	constructor(operationId) {
+		super(`Operation ID '${operationId}' must be globally unique within a spec.`);
+		this.name = "DuplicateOperationIdError";
+	}
+};
+//#endregion
+//#region src/errors/DuplicateRouteError.ts
+var DuplicateRouteError = class extends Error {
+	constructor(method, path, normalizedPath) {
+		super(`Route '${method} ${path}' conflicts with an existing route using normalized path '${normalizedPath}'.`);
+		this.name = "DuplicateRouteError";
+	}
+};
+//#endregion
+//#region src/errors/EmptyOperationResponsesError.ts
+var EmptyOperationResponsesError = class extends Error {
+	constructor(operationId) {
+		super(`Operation '${operationId}' must declare at least one response.`);
+		this.name = "EmptyOperationResponsesError";
+	}
+};
+//#endregion
+//#region src/errors/EmptyResourceOperationsError.ts
+var EmptyResourceOperationsError = class extends Error {
+	constructor(resourceName) {
+		super(`Resource '${resourceName}' must contain at least one operation.`);
+		this.name = "EmptyResourceOperationsError";
+	}
+};
+//#endregion
+//#region src/errors/EmptySpecResourcesError.ts
+var EmptySpecResourcesError = class extends Error {
+	constructor() {
+		super("Spec definition must contain at least one resource.");
+		this.name = "EmptySpecResourcesError";
+	}
+};
+//#endregion
+//#region src/errors/InvalidDerivedResponseError.ts
+var InvalidDerivedResponseError = class extends Error {
+	constructor(responseName) {
+		super(`Derived response '${responseName}' contains invalid lineage metadata.`);
+		this.name = "InvalidDerivedResponseError";
+	}
+};
+//#endregion
+//#region src/errors/InvalidRequestSchemaError.ts
+var InvalidRequestSchemaError = class extends Error {
+	constructor(operationId, requestPart) {
+		super(`Operation '${operationId}' has an invalid request.${requestPart} schema definition.`);
+		this.name = "InvalidRequestSchemaError";
+	}
+};
+//#endregion
+//#region src/errors/MissingDerivedResponseParentError.ts
+var MissingDerivedResponseParentError = class extends Error {
+	constructor(responseName, parentName) {
+		super(`Derived response '${responseName}' references missing canonical parent '${parentName}'.`);
+		this.name = "MissingDerivedResponseParentError";
+	}
+};
+//#endregion
+//#region src/errors/PathParameterMismatchError.ts
+var PathParameterMismatchError = class extends Error {
+	constructor(operationId, path, pathParams, requestParams) {
+		super(`Operation '${operationId}' has mismatched path parameters for '${path}'. Path params: [${pathParams.join(", ")}], request.param keys: [${requestParams.join(", ")}].`);
+		this.name = "PathParameterMismatchError";
+	}
+};
+//#endregion
+//#region src/helpers/routePath.ts
+const PATH_PARAMETER_PATTERN = /:([A-Za-z0-9_]+)/g;
+const normalizeRoutePath = (path) => {
+	const segments = path.split("/").filter(Boolean);
+	if (segments.length === 0) return "/";
+	return `/${segments.map((segment) => segment.startsWith(":") ? ":" : segment).join("/")}`;
+};
+const getPathParameterNames = (path) => {
+	return Array.from(path.matchAll(PATH_PARAMETER_PATTERN), (match) => match[1]);
+};
+//#endregion
+//#region src/validation/derivedResponseValidation.ts
+const validateDerivedResponseMetadata = (response) => {
+	const derived = response.derived;
+	if (derived === void 0) return;
+	if (derived.parentName === response.name) throw new DerivedResponseCycleError(response.name);
+	if (derived.lineage.length === 0) throw new InvalidDerivedResponseError(response.name);
+	if (derived.lineage.at(-1) !== response.name) throw new InvalidDerivedResponseError(response.name);
+	if (derived.lineage.length !== derived.depth) throw new InvalidDerivedResponseError(response.name);
+	if (new Set(derived.lineage).size !== derived.lineage.length) throw new DerivedResponseCycleError(response.name);
+	if (derived.depth > 1 && derived.lineage.at(-2) !== derived.parentName) throw new InvalidDerivedResponseError(response.name);
+};
+const collectCanonicalResponseDefinitions = (definition) => {
+	const canonicalResponses = /* @__PURE__ */ new Map();
+	for (const resource of Object.values(definition.resources)) for (const operation of resource.operations) for (const response of operation.responses) {
+		if (!isNamedResponseDefinition(response)) continue;
+		validateDerivedResponseMetadata(response);
+		canonicalResponses.set(response.name, response);
+	}
+	return canonicalResponses;
+};
+const getDerivedResponseChain = (response, canonicalResponses) => {
+	const chain = [response.name];
+	const visitedResponseNames = new Set(chain);
+	let parentName = response.derived?.parentName;
+	while (parentName !== void 0) {
+		if (visitedResponseNames.has(parentName)) throw new DerivedResponseCycleError(response.name);
+		const parentResponse = canonicalResponses.get(parentName);
+		if (parentResponse === void 0) throw new MissingDerivedResponseParentError(response.name, parentName);
+		chain.unshift(parentResponse.name);
+		visitedResponseNames.add(parentResponse.name);
+		parentName = parentResponse.derived?.parentName;
+	}
+	return chain;
+};
+const validateDerivedResponseGraph = (canonicalResponses) => {
+	for (const response of canonicalResponses.values()) {
+		if (response.derived === void 0) continue;
+		const materializedLineage = getDerivedResponseChain(response, canonicalResponses).slice(1);
+		if (response.derived.depth !== materializedLineage.length) throw new InvalidDerivedResponseError(response.name);
+		if (materializedLineage.length !== response.derived.lineage.length || materializedLineage.some((lineageEntry, index) => lineageEntry !== response.derived?.lineage[index])) throw new InvalidDerivedResponseError(response.name);
+	}
+};
+const normalizeResponseDefinition = (response) => {
+	return {
+		name: response.name,
+		statusCode: response.statusCode,
+		statusCodeName: HttpStatusCodeNameMap[response.statusCode],
+		description: response.description,
+		header: response.header,
+		body: response.body,
+		kind: response.derived === void 0 ? "response" : "derived-response",
+		derivedFrom: response.derived?.parentName,
+		lineage: response.derived?.lineage,
+		depth: response.derived?.depth
+	};
+};
+const collectCanonicalResponses = (definition) => {
+	const canonicalResponseDefinitions = collectCanonicalResponseDefinitions(definition);
+	validateDerivedResponseGraph(canonicalResponseDefinitions);
+	return new Map(Array.from(canonicalResponseDefinitions.entries(), ([responseName, response]) => [responseName, normalizeResponseDefinition(response)]));
+};
+//#endregion
+//#region src/normalizeSpec.ts
+const isZodType = (schema) => {
+	return schema instanceof z.ZodType;
+};
+const isZodObject = (schema) => {
+	return schema instanceof z.ZodObject;
+};
+const validateRequestSchema = (operationId, requestPart, schema) => {
+	if (!isZodType(schema)) throw new InvalidRequestSchemaError(operationId, requestPart);
+	if (requestPart === "param" && !isZodObject(schema)) throw new InvalidRequestSchemaError(operationId, requestPart);
+};
+const validateRequest = (operationId, path, request) => {
+	if (request.header !== void 0) validateRequestSchema(operationId, "header", request.header);
+	if (request.param !== void 0) validateRequestSchema(operationId, "param", request.param);
+	if (request.query !== void 0) validateRequestSchema(operationId, "query", request.query);
+	if (request.body !== void 0) validateRequestSchema(operationId, "body", request.body);
+	const pathParams = getPathParameterNames(path);
+	const requestParams = request.param === void 0 ? [] : Object.keys(request.param.shape);
+	if (pathParams.length !== requestParams.length || pathParams.some((pathParam) => !requestParams.includes(pathParam))) throw new PathParameterMismatchError(operationId, path, pathParams, requestParams);
+	if (request.header === void 0 && request.param === void 0 && request.query === void 0 && request.body === void 0) return;
+	return {
+		header: request.header,
+		param: request.param,
+		query: request.query,
+		body: request.body
+	};
+};
+const normalizeOperationResponses = (responses) => {
+	return responses.map((response) => {
+		if (isNamedResponseDefinition(response)) return {
+			responseName: response.name,
+			source: "canonical"
+		};
+		return {
+			responseName: response.name,
+			source: "inline",
+			response: normalizeResponseDefinition(response)
+		};
+	});
+};
+const normalizeOperation = (operationIds, routeKeys, operation) => {
+	if (operationIds.has(operation.operationId)) throw new DuplicateOperationIdError(operation.operationId);
+	operationIds.add(operation.operationId);
+	const normalizedPath = normalizeRoutePath(operation.path);
+	const routeKey = `${operation.method}:${normalizedPath}`;
+	if (routeKeys.has(routeKey)) throw new DuplicateRouteError(operation.method, operation.path, normalizedPath);
+	routeKeys.add(routeKey);
+	if (operation.responses.length === 0) throw new EmptyOperationResponsesError(operation.operationId);
+	return {
+		operationId: operation.operationId,
+		method: operation.method,
+		path: operation.path,
+		summary: operation.summary,
+		request: validateRequest(operation.operationId, operation.path, operation.request),
+		responses: normalizeOperationResponses(operation.responses)
+	};
+};
+const normalizeSpec = (definition) => {
+	const resourceEntries = Object.entries(definition.resources);
+	if (resourceEntries.length === 0) throw new EmptySpecResourcesError();
+	validateUniqueResponseNames(definition.resources);
+	const canonicalResponses = collectCanonicalResponses(definition);
+	const operationIds = /* @__PURE__ */ new Set();
+	const routeKeys = /* @__PURE__ */ new Set();
+	return {
+		resources: resourceEntries.map(([resourceName, resource]) => {
+			if (resource.operations.length === 0) throw new EmptyResourceOperationsError(resourceName);
+			return {
+				name: resourceName,
+				operations: resource.operations.map((operation) => normalizeOperation(operationIds, routeKeys, operation))
+			};
+		}),
+		responses: Array.from(canonicalResponses.values())
+	};
+};
+//#endregion
 //#region src/plugins/types.ts
 /**
 * Plugin loading error
@@ -24,7 +254,6 @@ var PluginDependencyError = class extends Error {
 		this.name = "PluginDependencyError";
 	}
 };
-
 //#endregion
 //#region src/plugins/BasePlugin.ts
 /**
@@ -46,8 +275,8 @@ var BasePlugin = class {
 	/**
 	* Default implementation - override in subclasses if needed
 	*/
-	collectResources(resources) {
-		return resources;
+	collectResources(normalizedSpec) {
+		return normalizedSpec;
 	}
 	/**
 	* Default implementation - override in subclasses if needed
@@ -61,169 +290,187 @@ var BasePlugin = class {
 		if (fs.existsSync(path.join(libDir, "index.ts"))) context.addGeneratedFile(libIndexPath);
 	}
 };
-
 //#endregion
-//#region src/plugins/BaseTemplatePlugin.ts
-/**
-* Base class for template-based generator plugins
-* Provides utilities for working with EJS templates
-*/
-var BaseTemplatePlugin = class extends BasePlugin {
-	/**
-	* Render an EJS template with the given data
-	*/
-	renderTemplate(templatePath, data) {
-		return render(fs.readFileSync(templatePath, "utf8"), data);
-	}
-	/**
-	* Write a file relative to the output directory
-	*/
-	writeFile(context, relativePath, content) {
-		context.writeFile(relativePath, content);
-	}
-	/**
-	* Ensure a directory exists
-	*/
-	ensureDir(context, relativePath) {
-		const fullPath = path.join(context.outputDir, relativePath);
-		fs.mkdirSync(fullPath, { recursive: true });
-	}
-	/**
-	* Get the template path for this plugin
-	*/
-	getTemplatePath(context, templateName) {
-		return path.join(context.templateDir, templateName);
-	}
-};
-
+//#region src/plugins/pluginRegistry.ts
+function createPluginRegistry() {
+	const plugins = /* @__PURE__ */ new Map();
+	return {
+		register: (plugin, config) => {
+			if (plugins.has(plugin.name)) {
+				console.info(`Skipping duplicate registration of required plugin: ${plugin.name}`);
+				return;
+			}
+			const registration = {
+				name: plugin.name,
+				plugin,
+				config
+			};
+			plugins.set(plugin.name, registration);
+			console.info(`Registered plugin: ${plugin.name}`);
+		},
+		get: (name) => plugins.get(name),
+		getAll: () => Array.from(plugins.values()),
+		has: (name) => plugins.has(name),
+		clear: () => plugins.clear()
+	};
+}
 //#endregion
-//#region src/plugins/PluginRegistry.ts
-/**
-* Registry for managing typeweaver plugins
-*/
-var PluginRegistry = class {
-	plugins;
-	constructor() {
-		this.plugins = /* @__PURE__ */ new Map();
-	}
-	/**
-	* Register a plugin
-	*/
-	register(plugin, config) {
-		if (this.plugins.has(plugin.name)) {
-			console.info(`Skipping duplicate registration of required plugin: ${plugin.name}`);
-			return;
-		}
-		const registration = {
-			name: plugin.name,
-			plugin,
-			config
-		};
-		this.plugins.set(plugin.name, registration);
-		console.info(`Registered plugin: ${plugin.name}`);
+//#region src/helpers/path.ts
+function relative(from, to) {
+	const relativePath = path.relative(from, to);
+	if (relativePath.includes("node_modules")) {
+		const parts = relativePath.split(path.sep);
+		const index = parts.indexOf("node_modules");
+		return parts.slice(index + 1).join("/");
 	}
-	/**
-	* Get a registered plugin
-	*/
-	get(name) {
-		return this.plugins.get(name);
-	}
-	/**
-	* Get all registered plugins
-	*/
-	getAll() {
-		return Array.from(this.plugins.values());
-	}
-	/**
-	* Check if a plugin is registered
-	*/
-	has(name) {
-		return this.plugins.has(name);
-	}
-	/**
-	* Clear all registered plugins (except required ones)
-	*/
-	clear() {
-		this.plugins.clear();
-	}
-};
-
+	const posixPath = relativePath.split(path.sep).join("/");
+	if (!posixPath.startsWith("./") && !posixPath.startsWith("../")) return `./${posixPath}`;
+	return posixPath;
+}
 //#endregion
-//#region src/plugins/PluginContext.ts
-/**
-* Builder for plugin contexts
-*/
-var PluginContextBuilder = class {
-	generatedFiles = /* @__PURE__ */ new Set();
-	/**
-	* Create a basic plugin context
-	*/
-	createPluginContext(params) {
+//#region src/plugins/pluginContext.ts
+function createPluginContextBuilder() {
+	const generatedFiles = /* @__PURE__ */ new Set();
+	const createPluginContext = (params) => {
 		return {
 			outputDir: params.outputDir,
 			inputDir: params.inputDir,
 			config: params.config
 		};
-	}
-	/**
-	* Create a generator context with utilities
-	*/
-	createGeneratorContext(params) {
+	};
+	const createGeneratorContext = (params) => {
+		const pluginContext = createPluginContext(params);
+		const canonicalResponsesByName = new Map(params.normalizedSpec.responses.map((response) => [response.name, response]));
+		const getResourceOutputDir = (resourceName) => {
+			return path.join(params.outputDir, resourceName);
+		};
+		const getOperationOutputPaths = (config) => {
+			const outputDir = getResourceOutputDir(config.resourceName);
+			const requestFileName = `${config.operationId}Request.ts`;
+			const responseFileName = `${config.operationId}Response.ts`;
+			const requestValidationFileName = `${config.operationId}RequestValidator.ts`;
+			const responseValidationFileName = `${config.operationId}ResponseValidator.ts`;
+			const clientFileName = `${config.operationId}Client.ts`;
+			return {
+				outputDir,
+				requestFile: path.join(outputDir, requestFileName),
+				requestFileName,
+				responseFile: path.join(outputDir, responseFileName),
+				responseFileName,
+				requestValidationFile: path.join(outputDir, requestValidationFileName),
+				requestValidationFileName,
+				responseValidationFile: path.join(outputDir, responseValidationFileName),
+				responseValidationFileName,
+				clientFile: path.join(outputDir, clientFileName),
+				clientFileName
+			};
+		};
+		const getCanonicalResponse = (responseName) => {
+			const response = canonicalResponsesByName.get(responseName);
+			if (response === void 0) throw new Error(`Missing canonical response '${responseName}'.`);
+			return response;
+		};
+		const getCanonicalResponseOutputFile = (responseName) => {
+			return path.join(params.responsesOutputDir, `${responseName}Response.ts`);
+		};
 		return {
-			...this.createPluginContext(params),
-			resources: params.resources,
+			...pluginContext,
+			normalizedSpec: params.normalizedSpec,
 			templateDir: params.templateDir,
 			coreDir: params.coreDir,
+			responsesOutputDir: params.responsesOutputDir,
+			specOutputDir: params.specOutputDir,
+			getCanonicalResponse,
+			getCanonicalResponseOutputFile,
+			getCanonicalResponseImportPath: (config) => {
+				return relative(config.importerDir, getCanonicalResponseOutputFile(config.responseName).replace(/\.ts$/, ""));
+			},
+			getSpecImportPath: (config) => {
+				return relative(config.importerDir, path.join(params.specOutputDir, "spec").replace(/\.ts$/, ""));
+			},
+			getOperationDefinitionAccessor: (config) => {
+				return `getOperationDefinition(spec, ${JSON.stringify(config.resourceName)}, ${JSON.stringify(config.operationId)})`;
+			},
+			getOperationOutputPaths,
+			getResourceOutputDir,
 			writeFile: (relativePath, content) => {
 				const fullPath = path.join(params.outputDir, relativePath);
 				const dir = path.dirname(fullPath);
 				fs.mkdirSync(dir, { recursive: true });
 				fs.writeFileSync(fullPath, content);
-				this.generatedFiles.add(relativePath);
+				generatedFiles.add(relativePath);
 				console.info(`Generated: ${relativePath}`);
 			},
 			renderTemplate: (templatePath, data) => {
 				const fullTemplatePath = path.isAbsolute(templatePath) ? templatePath : path.join(params.templateDir, templatePath);
-				return render(fs.readFileSync(fullTemplatePath, "utf8"), data);
+				const template = fs.readFileSync(fullTemplatePath, "utf8");
+				return ejs.render(template, data);
 			},
 			addGeneratedFile: (relativePath) => {
-				this.generatedFiles.add(relativePath);
+				generatedFiles.add(relativePath);
 			},
 			getGeneratedFiles: () => {
-				return Array.from(this.generatedFiles);
+				return Array.from(generatedFiles);
 			}
 		};
-	}
-	/**
-	* Get all generated files
-	*/
-	getGeneratedFiles() {
-		return Array.from(this.generatedFiles);
-	}
-	/**
-	* Clear generated files tracking
-	*/
-	clearGeneratedFiles() {
-		this.generatedFiles.clear();
-	}
-};
-
+	};
+	return {
+		createPluginContext,
+		createGeneratorContext,
+		getGeneratedFiles: () => Array.from(generatedFiles),
+		clearGeneratedFiles: () => generatedFiles.clear()
+	};
+}
 //#endregion
-//#region src/helpers/Path.ts
-var Path = class {
-	static relative(from, to) {
-		const relativePath = path.relative(from, to);
-		if (relativePath.includes("node_modules")) {
-			const parts = relativePath.split(path.sep);
-			const index = parts.indexOf("node_modules");
-			return parts.slice(index + 1).join("/");
-		}
-		const posixPath = relativePath.split(path.sep).join("/");
-		if (!posixPath.startsWith("./") && !posixPath.startsWith("../")) return `./${posixPath}`;
-		return posixPath;
+//#region src/helpers/routeSort.ts
+/**
+* HTTP method priority for route ordering.
+* Lower numbers = higher priority (sorted first).
+*/
+const METHOD_PRIORITY = {
+	[HttpMethod.GET]: 1,
+	[HttpMethod.POST]: 2,
+	[HttpMethod.PUT]: 3,
+	[HttpMethod.PATCH]: 4,
+	[HttpMethod.DELETE]: 5,
+	[HttpMethod.OPTIONS]: 6,
+	[HttpMethod.HEAD]: 7
+};
+/**
+* Returns the sort priority for an HTTP method.
+* Unrecognized methods default to priority 999.
+*/
+const getMethodPriority = (method) => METHOD_PRIORITY[method] ?? 999;
+/**
+* Compares two path segments for route ordering.
+* Returns negative if a should come before b, positive if after.
+*
+* Order: static segments before parameters, then alphabetically.
+*/
+const comparePathSegments = (a, b) => {
+	const aIsParam = a.startsWith(":");
+	if (aIsParam !== b.startsWith(":")) return aIsParam ? 1 : -1;
+	return a.localeCompare(b);
+};
+/**
+* Compares two routes for ordering.
+* Routes are sorted by:
+* 1. Path depth (shallow to deep)
+* 2. Static segments before parameters
+* 3. Alphabetical within same segment type
+* 4. HTTP method priority
+*/
+const compareRoutes = (a, b) => {
+	const aSegments = a.path.split("/").filter(Boolean);
+	const bSegments = b.path.split("/").filter(Boolean);
+	if (aSegments.length !== bSegments.length) return aSegments.length - bSegments.length;
+	for (let i = 0; i < aSegments.length; i++) {
+		const cmp = comparePathSegments(aSegments[i], bSegments[i]);
+		if (cmp !== 0) return cmp;
 	}
+	return getMethodPriority(a.method) - getMethodPriority(b.method);
 };
-
 //#endregion
-export { BasePlugin, BaseTemplatePlugin, Path, PluginContextBuilder, PluginDependencyError, PluginLoadError, PluginRegistry };
+export { BasePlugin, DerivedResponseCycleError, DuplicateOperationIdError, DuplicateRouteError, EmptyOperationResponsesError, EmptyResourceOperationsError, EmptySpecResourcesError, InvalidDerivedResponseError, InvalidRequestSchemaError, MissingDerivedResponseParentError, PathParameterMismatchError, PluginDependencyError, PluginLoadError, compareRoutes, createPluginContextBuilder, createPluginRegistry, getMethodPriority, getPathParameterNames, normalizeRoutePath, normalizeSpec, relative };
+
 //# sourceMappingURL=index.mjs.map