@rexeus/typeweaver 0.10.3 → 0.10.5

package/dist/cli.mjs

@@ -6,42 +6,83 @@ import { createPluginContextBuilder, createPluginRegistry, normalizeSpec, render
 import { TypesPlugin } from "@rexeus/typeweaver-types";
 import os from "node:os";
 import { build } from "rolldown";
+import { createHash } from "node:crypto";
 import { HttpMethod, HttpStatusCode } from "@rexeus/typeweaver-core";
+//#region src/errors/InvalidConfigExportError.ts
+var InvalidConfigExportError = class extends Error {
+	name = "InvalidConfigExportError";
+	constructor(configPath, reason) {
+		super(getInvalidConfigExportMessage(configPath, reason));
+		this.configPath = configPath;
+		this.reason = reason;
+	}
+};
+const getInvalidConfigExportMessage = (configPath, reason) => {
+	switch (reason) {
+		case "both-default-and-named-config": return `Configuration file '${configPath}' must choose one export style: use either 'export default' or 'export const config = ...', but not both.`;
+		case "default-namespace-wrapper": return `Configuration file '${configPath}' default export must be the config object itself, not a module namespace-like wrapper. Export the config directly with 'export default { ... }' or use 'export const config = ...'.`;
+		case "missing-config-export": return `Configuration file '${configPath}' must export its config via 'export default' or 'export const config = ...'.`;
+		case "non-object-config": return `Configuration file '${configPath}' must export a config object via 'export default' or 'export const config = ...'.`;
+	}
+};
+//#endregion
+//#region src/errors/UnsupportedConfigExtensionError.ts
+var UnsupportedConfigExtensionError = class extends Error {
+	name = "UnsupportedConfigExtensionError";
+	constructor(configPath, extension, supportedExtensions) {
+		super(`Unsupported config file extension '${extension}' for '${configPath}'. TypeWeaver accepts only these config extensions: ${supportedExtensions.join(", ")}.`);
+		this.configPath = configPath;
+		this.extension = extension;
+		this.supportedExtensions = supportedExtensions;
+	}
+};
+//#endregion
+//#region src/errors/UnsupportedTypeScriptConfigError.ts
+var UnsupportedTypeScriptConfigError = class extends Error {
+	name = "UnsupportedTypeScriptConfigError";
+	constructor(configPath, extension) {
+		super(`TypeScript config files are not supported: '${configPath}' uses '${extension}'. Use a JavaScript config file with one of these extensions: .js, .mjs, or .cjs.`);
+		this.configPath = configPath;
+		this.extension = extension;
+	}
+};
+//#endregion
 //#region src/configLoader.ts
-const SUPPORTED_CONFIG_EXTENSIONS = new Set([
+const SUPPORTED_CONFIG_EXTENSIONS = [
 	".js",
 	".mjs",
 	".cjs"
-]);
+];
+const SUPPORTED_CONFIG_EXTENSION_SET = new Set(SUPPORTED_CONFIG_EXTENSIONS);
 const UNSUPPORTED_TYPESCRIPT_CONFIG_EXTENSIONS = new Set([
 	".ts",
 	".mts",
 	".cts"
 ]);
 const getResolvedConfigPath = (configPath, currentWorkingDirectory = process.cwd()) => {
-	return path.isAbsolute(configPath) ? configPath : path.join(currentWorkingDirectory, configPath);
+	return path.isAbsolute(configPath) ? configPath : path.resolve(currentWorkingDirectory, configPath);
 };
 const assertSupportedConfigPath = (configPath) => {
 	const extension = path.extname(configPath).toLowerCase();
-	if (UNSUPPORTED_TYPESCRIPT_CONFIG_EXTENSIONS.has(extension)) throw new Error(`TypeScript config files are no longer supported: '${configPath}'. Convert the config to .js, .mjs, or .cjs, or compile it before passing --config.`);
-	if (!SUPPORTED_CONFIG_EXTENSIONS.has(extension)) throw new Error(`Unsupported config file extension for '${configPath}'. TypeWeaver only accepts .js, .mjs, or .cjs config files.`);
+	if (UNSUPPORTED_TYPESCRIPT_CONFIG_EXTENSIONS.has(extension)) throw new UnsupportedTypeScriptConfigError(configPath, extension);
+	if (!SUPPORTED_CONFIG_EXTENSION_SET.has(extension)) throw new UnsupportedConfigExtensionError(configPath, extension, SUPPORTED_CONFIG_EXTENSIONS);
 };
 const loadConfig = async (configPath) => {
 	assertSupportedConfigPath(configPath);
 	const loadedConfig = getConfigExport(await import(pathToFileURL(path.resolve(configPath)).toString()), configPath);
-	if (!isConfigObject(loadedConfig)) throw new Error(`Configuration file '${configPath}' must export a config object via 'export default' or 'export const config = ...'.`);
+	if (!isConfigObject(loadedConfig)) throw new InvalidConfigExportError(configPath, "non-object-config");
 	return loadedConfig;
 };
 const getConfigExport = (configModule, configPath) => {
 	const hasDefaultExport = Object.hasOwn(configModule, "default");
 	const hasNamedConfigExport = Object.hasOwn(configModule, "config");
-	if (hasDefaultExport && hasNamedConfigExport) throw new Error(`Configuration file '${configPath}' must choose a single export style: either 'export default' or 'export const config = ...', but not both.`);
+	if (hasDefaultExport && hasNamedConfigExport) throw new InvalidConfigExportError(configPath, "both-default-and-named-config");
 	if (hasDefaultExport) {
-		if (isNamespaceLikeConfigExport(configModule.default)) throw new Error(`Configuration file '${configPath}' default export must be the config object itself, not a module namespace-like wrapper. Export the config directly with 'export default { ... }' or use 'export const config = ...'.`);
+		if (isNamespaceLikeConfigExport(configModule.default)) throw new InvalidConfigExportError(configPath, "default-namespace-wrapper");
 		return configModule.default;
 	}
 	if (hasNamedConfigExport) return configModule.config;
-	throw new Error(`Configuration file '${configPath}' must export its config via 'export default' or 'export const config = ...'.`);
+	throw new InvalidConfigExportError(configPath, "missing-config-export");
 };
 const isConfigObject = (value) => {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -51,6 +92,35 @@ const isNamespaceLikeConfigExport = (value) => {
 	return Object.hasOwn(value, "default") || Object.hasOwn(value, "config");
 };
 //#endregion
+//#region src/generators/errors/UnsafeCleanTargetError.ts
+var UnsafeCleanTargetError = class extends Error {
+	name = "UnsafeCleanTargetError";
+	resolvedOutputDir;
+	currentWorkingDirectory;
+	protectedWorkspaceRoot;
+	filesystemRoot;
+	constructor(outputDir, reason, diagnostics = {}) {
+		super(getUnsafeCleanTargetMessage(outputDir, reason, diagnostics));
+		this.outputDir = outputDir;
+		this.reason = reason;
+		this.resolvedOutputDir = diagnostics.resolvedOutputDir;
+		this.currentWorkingDirectory = diagnostics.currentWorkingDirectory;
+		this.protectedWorkspaceRoot = diagnostics.protectedWorkspaceRoot;
+		this.filesystemRoot = diagnostics.filesystemRoot;
+	}
+};
+const getUnsafeCleanTargetMessage = (outputDir, reason, diagnostics) => {
+	const targetDescription = `Refusing to clean '${outputDir}'`;
+	const suffix = "Use a dedicated generated output directory instead.";
+	switch (reason) {
+		case "empty-path": return `Refusing to clean an empty output directory path. ${suffix}`;
+		case "filesystem-root": return `${targetDescription} because it resolves to the filesystem root '${diagnostics.filesystemRoot ?? diagnostics.resolvedOutputDir ?? outputDir}'. ${suffix}`;
+		case "current-working-directory": return `${targetDescription} because it resolves to the current working directory '${diagnostics.currentWorkingDirectory ?? diagnostics.resolvedOutputDir ?? outputDir}'. ${suffix}`;
+		case "workspace-root": return `${targetDescription} because it resolves to the protected workspace root '${diagnostics.protectedWorkspaceRoot ?? diagnostics.resolvedOutputDir ?? outputDir}'. ${suffix}`;
+		case "ancestor-of-current-working-directory": return `${targetDescription} because it resolves to an ancestor directory of the current working directory '${diagnostics.currentWorkingDirectory ?? ""}'. ${suffix}`;
+	}
+};
+//#endregion
 //#region src/generators/formatter.ts
 async function formatCode(outputDir, startDir) {
 	const format = await loadFormatter();
@@ -87,11 +157,16 @@ function generateIndexFiles(templateDir, context) {
 		const withJsExt = normalizedFile.replace(/\.ts$/, ".js");
 		const stripped = normalizedFile.replace(/\.ts$/, "");
 		const firstSlash = stripped.indexOf("/");
+		if (stripped === "index") continue;
 		if (firstSlash === -1) {
 			rootFiles.add(`./${withJsExt}`);
 			continue;
 		}
 		const firstSegment = stripped.slice(0, firstSlash);
+		if (stripped === "lib/index") {
+			existingBarrels.add("lib");
+			continue;
+		}
 		if (firstSegment === "lib") {
 			const secondSlash = stripped.indexOf("/", firstSlash + 1);
 			const groupKey = secondSlash === -1 ? stripped : stripped.slice(0, secondSlash);
@@ -140,30 +215,29 @@ async function loadPlugins(registry, requiredPlugins, strategies, config) {
 	if (!config?.plugins) return;
 	const successful = [];
 	for (const plugin of config.plugins) {
-		let result;
-		if (typeof plugin === "string") result = await loadPlugin(plugin, strategies);
-		else result = await loadPlugin(plugin[0], strategies);
+		const result = await loadPlugin(typeof plugin === "string" ? plugin : plugin[0], strategies, typeof plugin === "string" ? void 0 : plugin[1]);
 		if (result.success === false) throw new PluginLoadingFailure(result.error.pluginName, result.error.attempts);
 		successful.push(result.value);
-		registry.register(result.value.plugin);
+		registry.register(result.value.plugin, result.value.config);
 	}
 	reportSuccessfulLoads(successful);
 }
-async function loadPlugin(pluginName, strategies) {
+async function loadPlugin(pluginName, strategies, pluginConfig) {
 	const possiblePaths = generatePluginPaths(pluginName, strategies);
 	const attempts = [];
 	for (const possiblePath of possiblePaths) try {
-		const PluginClass = findPluginConstructor(await import(possiblePath));
-		if (PluginClass) return {
+		const plugin = createPluginInstance(await import(possiblePath), pluginConfig);
+		if (plugin.success) return {
 			success: true,
 			value: {
-				plugin: new PluginClass(),
-				source: possiblePath
+				plugin: plugin.value,
+				source: possiblePath,
+				config: pluginConfig
 			}
 		};
 		attempts.push({
 			path: possiblePath,
-			error: "No plugin class export found"
+			error: plugin.error
 		});
 	} catch (error) {
 		attempts.push({
@@ -179,10 +253,46 @@ async function loadPlugin(pluginName, strategies) {
 		}
 	};
 }
-function findPluginConstructor(pluginModule) {
-	for (const [key, value] of Object.entries(pluginModule)) if (key !== "default" && typeof value === "function") return value;
+function createPluginInstance(pluginModule, pluginConfig) {
+	const candidates = findPluginConstructorCandidates(pluginModule);
+	if (candidates.length === 0) return {
+		success: false,
+		error: "No plugin constructor export found"
+	};
+	const errors = [];
+	for (const candidate of candidates) try {
+		const plugin = new candidate.constructor(pluginConfig);
+		if (isTypeweaverPlugin(plugin)) return {
+			success: true,
+			value: plugin
+		};
+		errors.push(`Export '${candidate.exportName}' did not produce a valid plugin with a string name`);
+	} catch (error) {
+		errors.push(`Export '${candidate.exportName}' could not be instantiated: ${formatError(error)}`);
+	}
+	return {
+		success: false,
+		error: errors.join("; ")
+	};
+}
+function findPluginConstructorCandidates(pluginModule) {
+	const candidates = [];
+	for (const [key, value] of Object.entries(pluginModule)) if (key !== "default" && typeof value === "function") candidates.push({
+		exportName: key,
+		constructor: value
+	});
 	const defaultExport = pluginModule.default;
-	if (typeof defaultExport === "function") return defaultExport;
+	if (typeof defaultExport === "function") candidates.push({
+		exportName: "default",
+		constructor: defaultExport
+	});
+	return candidates;
+}
+function isTypeweaverPlugin(value) {
+	return typeof value === "object" && value !== null && typeof value.name === "string" && value.name.length > 0;
+}
+function formatError(error) {
+	return error instanceof Error ? error.message : String(error);
 }
 function generatePluginPaths(pluginName, strategies) {
 	const paths = [];
@@ -192,11 +302,19 @@ function generatePluginPaths(pluginName, strategies) {
 			paths.push(`@rexeus/${pluginName}`);
 			break;
 		case "local":
+			paths.push(toLocalImportSpecifier(pluginName));
+			break;
+		case "scoped":
 			paths.push(pluginName);
 			break;
 	}
 	return paths;
 }
+function toLocalImportSpecifier(pluginName) {
+	if (pluginName.startsWith("file:")) return pluginName;
+	if (path.isAbsolute(pluginName)) return pathToFileURL(pluginName).href;
+	return pluginName;
+}
 function reportSuccessfulLoads(successful) {
 	if (successful.length > 0) {
 		console.info(`Successfully loaded ${successful.length} plugin(s):`);
@@ -204,6 +322,17 @@ function reportSuccessfulLoads(successful) {
 	}
 }
 //#endregion
+//#region src/generators/spec/errors/SpecBundleOutputMissingError.ts
+var SpecBundleOutputMissingError = class extends Error {
+	name = "SpecBundleOutputMissingError";
+	constructor(inputFile, bundledSpecFile, specOutputDir) {
+		super(`Spec bundling completed but did not create the expected output '${bundledSpecFile}' for entrypoint '${inputFile}'. Expected the bundle inside '${specOutputDir}'.`);
+		this.inputFile = inputFile;
+		this.bundledSpecFile = bundledSpecFile;
+		this.specOutputDir = specOutputDir;
+	}
+};
+//#endregion
 //#region src/generators/spec/specBundler.ts
 const WINDOWS_ABSOLUTE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
 const WINDOWS_UNC_PATH_PATTERN = /^\\\\/;
@@ -217,7 +346,7 @@ function createWrapperImportSpecifier(wrapperFile, inputFile) {
 	if (relativeInputFile.startsWith(".") || relativeInputFile.startsWith("..")) return relativeInputFile;
 	return `./${relativeInputFile}`;
 }
-async function bundle(config) {
+async function bundle(config, deps = {}) {
 	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "typeweaver-spec-loader-"));
 	const wrapperFile = path.join(tempDir, "spec-entrypoint.ts");
 	const bundledSpecFile = path.join(config.specOutputDir, "spec.js");
@@ -233,7 +362,7 @@ async function bundle(config) {
 		""
 	].join("\n"));
 	try {
-		await build({
+		await (deps.build ?? build)({
 			cwd: tempDir,
 			input: wrapperFile,
 			treeshake: true,
@@ -253,7 +382,7 @@ async function bundle(config) {
 			force: true
 		});
 	}
-	if (!fs.existsSync(bundledSpecFile)) throw new Error(`Failed to bundle spec entrypoint '${config.inputFile}' to '${bundledSpecFile}'.`);
+	if (!(deps.existsSync ?? fs.existsSync)(bundledSpecFile)) throw new SpecBundleOutputMissingError(config.inputFile, bundledSpecFile, config.specOutputDir);
 	return bundledSpecFile;
 }
 function resolveBundledInputFile(inputFile) {
@@ -303,7 +432,10 @@ const isSpecDefinition = (value) => {
 //#endregion
 //#region src/generators/spec/specImporter.ts
 async function importDefinition(bundledSpecFile) {
-	const specModule = await import(pathToFileURL(bundledSpecFile).toString());
+	const contentHash = createHash("sha256").update(fs.readFileSync(bundledSpecFile)).digest("hex");
+	const moduleUrl = pathToFileURL(bundledSpecFile);
+	moduleUrl.searchParams.set("content", contentHash);
+	const specModule = await import(moduleUrl.toString());
 	const definition = specModule.spec ?? specModule.default ?? specModule;
 	if (!isSpecDefinition(definition)) throw new InvalidSpecEntrypointError(bundledSpecFile);
 	return definition;
@@ -332,13 +464,32 @@ function writeSpecDeclarationFile(specOutputDir) {
 const moduleDir$1 = path.dirname(fileURLToPath(import.meta.url));
 const assertSafeCleanTarget = (outputDir, currentWorkingDirectory) => {
 	const trimmedOutputDir = outputDir.trim();
-	if (trimmedOutputDir.length === 0) throw new Error("Refusing to clean an empty output directory path. Pass a dedicated generated output directory instead.");
+	if (trimmedOutputDir.length === 0) throw new UnsafeCleanTargetError(outputDir, "empty-path");
 	const resolvedWorkingDirectory = path.resolve(currentWorkingDirectory);
+	const canonicalWorkingDirectory = fs.realpathSync.native(resolvedWorkingDirectory);
 	const resolvedOutputDir = path.resolve(resolvedWorkingDirectory, trimmedOutputDir);
-	if (resolvedOutputDir === path.parse(resolvedOutputDir).root) throw new Error(`Refusing to clean '${outputDir}' because it resolves to the filesystem root.`);
-	if (resolvedOutputDir === resolvedWorkingDirectory) throw new Error(`Refusing to clean '${outputDir}' because it resolves to the current working directory.`);
-	const protectedWorkspaceRoot = findProtectedWorkspaceRoot(resolvedWorkingDirectory);
-	if (protectedWorkspaceRoot !== void 0 && resolvedOutputDir === protectedWorkspaceRoot) throw new Error(`Refusing to clean '${outputDir}' because it resolves to the inferred workspace root '${protectedWorkspaceRoot}'. Choose a dedicated output subdirectory instead.`);
+	const canonicalOutputDir = canonicalizePathForContainment(resolvedOutputDir);
+	const filesystemRoot = path.parse(canonicalOutputDir).root;
+	if (canonicalOutputDir === filesystemRoot) throw new UnsafeCleanTargetError(outputDir, "filesystem-root", {
+		resolvedOutputDir,
+		currentWorkingDirectory: resolvedWorkingDirectory,
+		filesystemRoot
+	});
+	if (resolvedOutputDir === resolvedWorkingDirectory || canonicalOutputDir === canonicalWorkingDirectory) throw new UnsafeCleanTargetError(outputDir, "current-working-directory", {
+		resolvedOutputDir,
+		currentWorkingDirectory: resolvedWorkingDirectory
+	});
+	const protectedWorkspaceRoots = [findProtectedWorkspaceRoot(resolvedWorkingDirectory), findProtectedWorkspaceRoot(canonicalWorkingDirectory)].filter((root) => root !== void 0);
+	const protectedWorkspaceRootTarget = protectedWorkspaceRoots.find((protectedWorkspaceRoot) => resolvedOutputDir === protectedWorkspaceRoot || canonicalOutputDir === fs.realpathSync.native(protectedWorkspaceRoot));
+	if (protectedWorkspaceRootTarget !== void 0) throw new UnsafeCleanTargetError(outputDir, "workspace-root", {
+		resolvedOutputDir,
+		currentWorkingDirectory: resolvedWorkingDirectory,
+		protectedWorkspaceRoot: protectedWorkspaceRootTarget
+	});
+	if (protectedWorkspaceRoots.length > 0 && (isSameOrDescendantOf(resolvedWorkingDirectory, resolvedOutputDir) || isSameOrDescendantOf(canonicalWorkingDirectory, canonicalOutputDir))) throw new UnsafeCleanTargetError(outputDir, "ancestor-of-current-working-directory", {
+		resolvedOutputDir,
+		currentWorkingDirectory: resolvedWorkingDirectory
+	});
 };
 /**
 * Main generator for typeweaver
@@ -432,6 +583,58 @@ const findProtectedWorkspaceRoot = (startDirectory) => {
 const hasWorkspaceMarker = (directory) => {
 	return ["pnpm-workspace.yaml", ".git"].some((marker) => fs.existsSync(path.join(directory, marker)));
 };
+const canonicalizePathForContainment = (targetPath) => {
+	const remainingSegments = [];
+	let nearestExistingPath = path.resolve(targetPath);
+	while (!fs.existsSync(nearestExistingPath)) {
+		const parentPath = path.dirname(nearestExistingPath);
+		if (parentPath === nearestExistingPath) break;
+		remainingSegments.unshift(path.basename(nearestExistingPath));
+		nearestExistingPath = parentPath;
+	}
+	const canonicalExistingPath = fs.realpathSync.native(nearestExistingPath);
+	return path.join(canonicalExistingPath, ...remainingSegments);
+};
+const isSameOrDescendantOf = (directory, ancestor) => {
+	const relativePath = path.relative(ancestor, directory);
+	const parentTraversalPrefix = `..${path.sep}`;
+	const escapesAncestor = relativePath === ".." || relativePath.startsWith(parentTraversalPrefix);
+	return relativePath === "" || !escapesAncestor && !path.isAbsolute(relativePath);
+};
+//#endregion
+//#region src/errors/MissingGenerateOptionError.ts
+var MissingGenerateOptionError = class extends Error {
+	name = "MissingGenerateOptionError";
+	constructor(optionName, flag, configKey) {
+		super(`Missing required generate option '${optionName}'. Pass ${flag} or set '${configKey}' in the TypeWeaver config file.`);
+		this.optionName = optionName;
+		this.flag = flag;
+		this.configKey = configKey;
+	}
+};
+//#endregion
+//#region src/resolveGenerateOptions.ts
+const resolveGenerateOptions = (options, config, currentWorkingDirectory) => {
+	const inputPath = options.input ?? config.input;
+	const outputDir = options.output ?? config.output;
+	if (!inputPath) throw new MissingGenerateOptionError("input", "--input", "input");
+	if (!outputDir) throw new MissingGenerateOptionError("output", "--output", "output");
+	const resolvedInputPath = path.isAbsolute(inputPath) ? inputPath : path.join(currentWorkingDirectory, inputPath);
+	const resolvedOutputDir = path.isAbsolute(outputDir) ? outputDir : path.join(currentWorkingDirectory, outputDir);
+	const finalConfig = {
+		input: resolvedInputPath,
+		output: resolvedOutputDir,
+		format: options.format ?? config.format ?? true,
+		clean: options.clean ?? config.clean ?? true
+	};
+	if (options.plugins) finalConfig.plugins = options.plugins.split(",").map((plugin) => plugin.trim());
+	else if (config.plugins) finalConfig.plugins = config.plugins;
+	return {
+		inputPath: resolvedInputPath,
+		outputDir: resolvedOutputDir,
+		config: finalConfig
+	};
+};
 //#endregion
 //#region src/cli.ts
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -452,21 +655,8 @@ program.command("generate").description("Generate types, validators, and clients
 			process.exit(1);
 		}
 	}
-	const inputPath = options.input ?? config.input;
-	const outputDir = options.output ?? config.output;
-	if (!inputPath) throw new Error("No input spec entrypoint provided. Use --input or specify in config file.");
-	if (!outputDir) throw new Error("No output directory provided. Use --output or specify in config file.");
-	const resolvedInputPath = path.isAbsolute(inputPath) ? inputPath : path.join(execDir, inputPath);
-	const resolvedOutputDir = path.isAbsolute(outputDir) ? outputDir : path.join(execDir, outputDir);
-	const finalConfig = {
-		input: resolvedInputPath,
-		output: resolvedOutputDir,
-		format: options.format ?? config.format ?? true,
-		clean: options.clean ?? config.clean ?? true
-	};
-	if (options.plugins) finalConfig.plugins = options.plugins.split(",").map((p) => p.trim());
-	else if (config.plugins) finalConfig.plugins = config.plugins;
-	return new Generator().generate(resolvedInputPath, resolvedOutputDir, finalConfig, execDir);
+	const resolvedGenerateOptions = resolveGenerateOptions(options, config, execDir);
+	return new Generator().generate(resolvedGenerateOptions.inputPath, resolvedGenerateOptions.outputDir, resolvedGenerateOptions.config, execDir);
 });
 program.command("init").description("Initialize a new typeweaver project (coming soon)").action(() => {
 	console.log("The init command is coming soon!");