@optique/discover 1.2.0-dev.2169 → 1.2.0-dev.2180

package/dist/generator-e4RwnDKG.cjs

@@ -0,0 +1,288 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const require_src = require('./src-BYGxdHGJ.cjs');
+const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
+const node_path = require_chunk.__toESM(require("node:path"));
+const node_url = require_chunk.__toESM(require("node:url"));
+
+//#region src/generator.ts
+/**
+* Generates a TypeScript module that exports command entries.
+*
+* @param options Generation options.
+* @returns The generated source code and command module metadata.
+* @throws {TypeError} If options are invalid or no command modules are found.
+* @since 1.2.0
+*/
+async function generateCommandsModule(options) {
+	const normalized = normalizeGenerateOptions(options);
+	const files = await collectGeneratedCommandFiles(normalized);
+	return generateCommandsModuleFromFiles(normalized, files);
+}
+/**
+* Writes a generated command module to disk.
+*
+* @param options Generation options.
+* @returns The generated source code and command module metadata.
+* @throws {TypeError} If options are invalid or no command modules are found.
+* @throws {Error} If the generated module cannot be written.
+* @since 1.2.0
+*/
+async function writeCommandsModule(options) {
+	const result = await generateCommandsModule(options);
+	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(pathFromFile(options.outputFile)), { recursive: true });
+	await (0, node_fs_promises.writeFile)(pathFromFile(options.outputFile), result.code, "utf-8");
+	return result;
+}
+/**
+* Watches the command file set and rewrites the generated module when it
+* changes.
+*
+* Content-only edits do not trigger regeneration because they do not change
+* the static module map.
+*
+* @param options Watch options.
+* @returns A promise that resolves when the watch signal is aborted.
+* @throws {TypeError} If options are invalid.
+* @since 1.2.0
+*/
+async function watchCommandsModule(options) {
+	const normalized = normalizeGenerateOptions(options);
+	const intervalMs = options.intervalMs ?? 250;
+	if (!Number.isInteger(intervalMs) || intervalMs < 1) throw new TypeError(`Watch interval must be a positive integer: ${intervalMs}`);
+	let previousSignature;
+	while (options.signal?.aborted !== true) {
+		try {
+			const files = await collectGeneratedCommandFiles(normalized, { allowEmpty: true });
+			const signature = files.map((file) => file.filePath).join("\0");
+			if (signature !== previousSignature) {
+				const result = generateCommandsModuleFromFiles(normalized, files);
+				await (0, node_fs_promises.mkdir)((0, node_path.dirname)(normalized.outputFile), { recursive: true });
+				await (0, node_fs_promises.writeFile)(normalized.outputFile, result.code, "utf-8");
+				options.onGenerate?.(result);
+				previousSignature = signature;
+			}
+		} catch (error) {
+			options.onError?.(error);
+		}
+		await delay(intervalMs, options.signal);
+	}
+}
+async function collectGeneratedCommandFiles(options, collectOptions = {}) {
+	const filePaths = await collectCommandFiles(options.dir, options.extensions, options.outputFile);
+	if (filePaths.length < 1) {
+		if (collectOptions.allowEmpty === true) return [];
+		throw new TypeError(`No command modules found in ${options.dir}.`);
+	}
+	const files = filePaths.map((filePath, index) => {
+		const importSpecifier = relativeImportSpecifier(options.outputDir, filePath);
+		const defaultModulePath = relativeModuleSpecifier(options.outputDir, filePath);
+		const modulePath = options.baseWasProvided ? joinModulePath(options.base, normalizeRelativePath((0, node_path.relative)(options.dir, filePath))) : defaultModulePath;
+		return {
+			filePath,
+			importSpecifier,
+			modulePath,
+			identifier: `cmd${index}`
+		};
+	});
+	rejectDuplicateCommandPaths(files, options);
+	return files;
+}
+function generateCommandsModuleFromFiles(options, files) {
+	if (files.length < 1) return {
+		code: "import type { ModuleCommand } from \"@optique/discover\";\n\nexport default [] satisfies readonly ModuleCommand[];\n",
+		files
+	};
+	const imports = files.map(formatCommandModuleImport).join("\n");
+	const entries = files.map((file) => `    ${JSON.stringify(file.modulePath)}: ${file.identifier},`).join("\n");
+	const optionEntries = [
+		`    base: ${JSON.stringify(options.base)},`,
+		`    extensions: ${formatStringArray(options.extensions)},`,
+		...options.entryFileName === void 0 ? [] : [`    entryFileName: ${JSON.stringify(options.entryFileName)},`]
+	].join("\n");
+	return {
+		code: `import { commandsFromModules } from "@optique/discover";\n${imports}\n\nexport default commandsFromModules(\n  {\n${entries}\n  },\n  {\n${optionEntries}\n  },\n);\n`,
+		files
+	};
+}
+function formatCommandModuleImport(file) {
+	const importSpecifier = JSON.stringify(file.importSpecifier);
+	const importDeclaration = `import * as ${file.identifier} from ${importSpecifier};`;
+	if (requiresTypeScriptResolutionIgnore(file.importSpecifier)) return `// @ts-ignore: Percent-encoded import preserves URL-significant command paths.\n${importDeclaration}`;
+	return importDeclaration;
+}
+function requiresTypeScriptResolutionIgnore(specifier) {
+	return specifier.includes("%");
+}
+function normalizeGenerateOptions(options) {
+	const dir = (0, node_path.resolve)(pathFromFile(options.dir));
+	const outputFile = (0, node_path.resolve)(pathFromFile(options.outputFile));
+	const outputDir = (0, node_path.dirname)(outputFile);
+	const baseWasProvided = options.base !== void 0;
+	const base = normalizeBase(options.base ?? relativeModuleSpecifier(outputDir, dir));
+	return {
+		dir,
+		outputFile,
+		outputDir,
+		base,
+		baseWasProvided,
+		extensions: normalizeExtensions(options.extensions ?? require_src.getDefaultExtensions()),
+		entryFileName: normalizeEntryFileName(options.entryFileName)
+	};
+}
+function pathFromFile(path) {
+	return typeof path === "string" ? path : (0, node_url.fileURLToPath)(path);
+}
+function normalizeBase(base) {
+	if (typeof base !== "string" || base.length < 1) throw new TypeError(`Module base path must be a non-empty string: ${base}`);
+	return normalizeModulePath(base);
+}
+function normalizeExtensions(extensions) {
+	if (extensions.length < 1) throw new TypeError("At least one command file extension is required.");
+	const normalized = [];
+	for (const extension of extensions) {
+		if (!extension.startsWith(".") || extension.length < 2) throw new TypeError(`Command file extension must start with a dot: ${extension}`);
+		if (!normalized.includes(extension)) normalized.push(extension);
+	}
+	return normalized.toSorted((a, b) => b.length - a.length || a.localeCompare(b));
+}
+function normalizeEntryFileName(entryFileName) {
+	if (entryFileName === void 0) return void 0;
+	if (entryFileName === false) return false;
+	if (typeof entryFileName !== "string" || entryFileName.length < 1 || entryFileName.includes("/") || entryFileName.includes("\\")) throw new TypeError(`Command entry file name must be a non-empty file name: ${entryFileName}`);
+	return entryFileName;
+}
+async function collectCommandFiles(dir, extensions, excludedFile, activeDirs = /* @__PURE__ */ new Set()) {
+	const canonicalDir = await (0, node_fs_promises.realpath)(dir);
+	if (activeDirs.has(canonicalDir)) return [];
+	const nextActiveDirs = new Set(activeDirs);
+	nextActiveDirs.add(canonicalDir);
+	const entries = await (0, node_fs_promises.readdir)(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+		const path = (0, node_path.resolve)(dir, entry.name);
+		const entryType = await getCommandFileEntryType(path, entry);
+		if (entryType === "directory") files.push(...await collectCommandFiles(path, extensions, excludedFile, nextActiveDirs));
+		else if (entryType === "file" && path !== excludedFile && !isDeclarationFile(entry.name) && extensions.some((ext) => entry.name.endsWith(ext))) files.push(path);
+	}
+	return files;
+}
+async function getCommandFileEntryType(path, entry) {
+	if (entry.isDirectory()) return "directory";
+	if (entry.isFile()) return "file";
+	if (!entry.isSymbolicLink()) return void 0;
+	try {
+		const target = await (0, node_fs_promises.stat)(path);
+		if (target.isDirectory()) return "directory";
+		if (target.isFile()) return "file";
+		return void 0;
+	} catch {
+		return void 0;
+	}
+}
+function isDeclarationFile(fileName) {
+	return /\.d\.[cm]?ts$/.test(fileName);
+}
+function rejectDuplicateCommandPaths(files, options) {
+	const entryFileName = options.entryFileName ?? "index";
+	const seen = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const commandPath = commandPathFromModulePath(options.base, file.modulePath, options.extensions, entryFileName);
+		const key = commandPath.join("\0");
+		const previous = seen.get(key);
+		if (previous != null) throw new TypeError(`Duplicate command path "${displayCommandPath(commandPath)}" from ${previous} and ${file.modulePath}.`);
+		seen.set(key, file.modulePath);
+	}
+}
+function commandPathFromModulePath(base, modulePath, extensions, entryFileName) {
+	const withoutExtension = stripCommandExtension(modulePath, extensions);
+	const relativePath = relativeModulePath(base, withoutExtension, modulePath);
+	const path = relativePath.split("/").filter((segment) => segment.length > 0);
+	return commandPathFromSegments(path, modulePath, entryFileName);
+}
+function stripCommandExtension(path, extensions) {
+	const matchedExtension = extensions.find((ext) => path.endsWith(ext));
+	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${path}.`);
+	return path.slice(0, -matchedExtension.length);
+}
+function relativeModulePath(base, modulePath, originalModulePath) {
+	const normalizedBase = normalizeDerivedModulePath(base);
+	const normalizedPath = normalizeDerivedModulePath(modulePath);
+	const relativePath = node_path.posix.relative(normalizedBase, normalizedPath);
+	if (relativePath.length < 1 || relativePath === ".." || relativePath.startsWith("../") || node_path.posix.isAbsolute(relativePath)) throw new TypeError(`Module path ${originalModulePath} is not under base path ${base}.`);
+	return relativePath;
+}
+function commandPathFromSegments(path, source, entryFileName) {
+	if (path.length < 1) throw new TypeError(`Command module ${source} does not define a path.`);
+	if (entryFileName !== false && path[path.length - 1] === entryFileName) return path.slice(0, -1);
+	return path;
+}
+function displayCommandPath(path) {
+	return path.length < 1 ? "<root>" : path.join(" ");
+}
+function relativeModuleSpecifier(fromDir, target) {
+	const relativePath = normalizeRelativePath((0, node_path.relative)(fromDir, target));
+	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+function relativeImportSpecifier(fromDir, target) {
+	const specifier = relativeModuleSpecifier(fromDir, target);
+	if (requiresEncodedImportSpecifier(specifier)) return encodeImportSpecifier(specifier);
+	return specifier;
+}
+function requiresEncodedImportSpecifier(specifier) {
+	return specifier.includes("#") || specifier.includes("?") || specifier.includes("%");
+}
+function encodeImportSpecifier(specifier) {
+	return specifier.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
+function normalizeRelativePath(path) {
+	return path.replaceAll("\\", "/");
+}
+function normalizeModulePath(path) {
+	return path.replaceAll("\\", "/");
+}
+function normalizeDerivedModulePath(path) {
+	return node_path.posix.normalize(normalizeModulePath(path));
+}
+function joinModulePath(base, relativePath) {
+	if (base === "." || base === "./") return `./${relativePath}`;
+	const prefix = base.endsWith("/") ? base.slice(0, -1) : base;
+	return `${prefix}/${relativePath}`;
+}
+function formatStringArray(values) {
+	return `[${values.map((value) => JSON.stringify(value)).join(", ")}]`;
+}
+function delay(ms, signal) {
+	if (signal?.aborted === true) return Promise.resolve();
+	return new Promise((resolve$1) => {
+		const onTimeout = () => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve$1();
+		};
+		const onAbort = () => {
+			clearTimeout(timeout);
+			resolve$1();
+		};
+		const timeout = setTimeout(onTimeout, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+//#endregion
+Object.defineProperty(exports, 'generateCommandsModule', {
+  enumerable: true,
+  get: function () {
+    return generateCommandsModule;
+  }
+});
+Object.defineProperty(exports, 'watchCommandsModule', {
+  enumerable: true,
+  get: function () {
+    return watchCommandsModule;
+  }
+});
+Object.defineProperty(exports, 'writeCommandsModule', {
+  enumerable: true,
+  get: function () {
+    return writeCommandsModule;
+  }
+});

package/dist/generator.cjs

@@ -0,0 +1,7 @@
+require('./command-CUn2_NIA.cjs');
+require('./src-BYGxdHGJ.cjs');
+const require_generator = require('./generator-e4RwnDKG.cjs');
+
+exports.generateCommandsModule = require_generator.generateCommandsModule;
+exports.watchCommandsModule = require_generator.watchCommandsModule;
+exports.writeCommandsModule = require_generator.writeCommandsModule;

package/dist/generator.d.cts

@@ -0,0 +1,136 @@
+//#region src/generator.d.ts
+/**
+ * A command module file included in generated discovery output.
+ *
+ * @since 1.2.0
+ */
+interface GeneratedCommandModuleFile {
+  /**
+   * Absolute path to the command module file.
+   */
+  readonly filePath: string;
+  /**
+   * Module specifier used by the generated import declaration.
+   *
+   * Paths containing URL-significant characters use percent-encoded
+   * relative specifiers so generated modules stay relocatable.
+   */
+  readonly importSpecifier: string;
+  /**
+   * Module map key passed to `commandsFromModules()`.
+   */
+  readonly modulePath: string;
+  /**
+   * Namespace import identifier used in the generated module.
+   */
+  readonly identifier: string;
+}
+/**
+ * Options for generating a static command module.
+ *
+ * @since 1.2.0
+ */
+interface GenerateCommandsModuleOptions {
+  /**
+   * Directory containing command modules.
+   */
+  readonly dir: string | URL;
+  /**
+   * Path to the module that will be generated.
+   */
+  readonly outputFile: string | URL;
+  /**
+   * Module map base path passed to `commandsFromModules()`.
+   *
+   * By default, this is the command directory path relative to the generated
+   * module's containing directory.
+   */
+  readonly base?: string;
+  /**
+   * Module suffixes to include.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * Entry file name passed to `commandsFromModules()`.  Pass `false` to
+   * disable entry-file mapping.
+   */
+  readonly entryFileName?: string | false;
+}
+/**
+ * Result of generating a static command module.
+ *
+ * @since 1.2.0
+ */
+interface GeneratedCommandsModule {
+  /**
+   * Generated TypeScript source code.
+   */
+  readonly code: string;
+  /**
+   * Command module files included in the generated module.
+   */
+  readonly files: readonly GeneratedCommandModuleFile[];
+}
+/**
+ * Options for watching and regenerating a static command module.
+ *
+ * @since 1.2.0
+ */
+interface WatchCommandsModuleOptions extends GenerateCommandsModuleOptions {
+  /**
+   * Polling interval in milliseconds.
+   *
+   * @default `250`
+   */
+  readonly intervalMs?: number;
+  /**
+   * Abort signal used to stop watching.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Callback invoked after each regeneration.
+   */
+  readonly onGenerate?: (result: GeneratedCommandsModule) => void;
+  /**
+   * Callback invoked when generation fails during watching.
+   *
+   * @since 1.2.0
+   */
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * Generates a TypeScript module that exports command entries.
+ *
+ * @param options Generation options.
+ * @returns The generated source code and command module metadata.
+ * @throws {TypeError} If options are invalid or no command modules are found.
+ * @since 1.2.0
+ */
+declare function generateCommandsModule(options: GenerateCommandsModuleOptions): Promise<GeneratedCommandsModule>;
+/**
+ * Writes a generated command module to disk.
+ *
+ * @param options Generation options.
+ * @returns The generated source code and command module metadata.
+ * @throws {TypeError} If options are invalid or no command modules are found.
+ * @throws {Error} If the generated module cannot be written.
+ * @since 1.2.0
+ */
+declare function writeCommandsModule(options: GenerateCommandsModuleOptions): Promise<GeneratedCommandsModule>;
+/**
+ * Watches the command file set and rewrites the generated module when it
+ * changes.
+ *
+ * Content-only edits do not trigger regeneration because they do not change
+ * the static module map.
+ *
+ * @param options Watch options.
+ * @returns A promise that resolves when the watch signal is aborted.
+ * @throws {TypeError} If options are invalid.
+ * @since 1.2.0
+ */
+declare function watchCommandsModule(options: WatchCommandsModuleOptions): Promise<void>;
+//#endregion
+export { GenerateCommandsModuleOptions, GeneratedCommandModuleFile, GeneratedCommandsModule, WatchCommandsModuleOptions, generateCommandsModule, watchCommandsModule, writeCommandsModule };

package/dist/generator.d.ts

@@ -0,0 +1,136 @@
+//#region src/generator.d.ts
+/**
+ * A command module file included in generated discovery output.
+ *
+ * @since 1.2.0
+ */
+interface GeneratedCommandModuleFile {
+  /**
+   * Absolute path to the command module file.
+   */
+  readonly filePath: string;
+  /**
+   * Module specifier used by the generated import declaration.
+   *
+   * Paths containing URL-significant characters use percent-encoded
+   * relative specifiers so generated modules stay relocatable.
+   */
+  readonly importSpecifier: string;
+  /**
+   * Module map key passed to `commandsFromModules()`.
+   */
+  readonly modulePath: string;
+  /**
+   * Namespace import identifier used in the generated module.
+   */
+  readonly identifier: string;
+}
+/**
+ * Options for generating a static command module.
+ *
+ * @since 1.2.0
+ */
+interface GenerateCommandsModuleOptions {
+  /**
+   * Directory containing command modules.
+   */
+  readonly dir: string | URL;
+  /**
+   * Path to the module that will be generated.
+   */
+  readonly outputFile: string | URL;
+  /**
+   * Module map base path passed to `commandsFromModules()`.
+   *
+   * By default, this is the command directory path relative to the generated
+   * module's containing directory.
+   */
+  readonly base?: string;
+  /**
+   * Module suffixes to include.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * Entry file name passed to `commandsFromModules()`.  Pass `false` to
+   * disable entry-file mapping.
+   */
+  readonly entryFileName?: string | false;
+}
+/**
+ * Result of generating a static command module.
+ *
+ * @since 1.2.0
+ */
+interface GeneratedCommandsModule {
+  /**
+   * Generated TypeScript source code.
+   */
+  readonly code: string;
+  /**
+   * Command module files included in the generated module.
+   */
+  readonly files: readonly GeneratedCommandModuleFile[];
+}
+/**
+ * Options for watching and regenerating a static command module.
+ *
+ * @since 1.2.0
+ */
+interface WatchCommandsModuleOptions extends GenerateCommandsModuleOptions {
+  /**
+   * Polling interval in milliseconds.
+   *
+   * @default `250`
+   */
+  readonly intervalMs?: number;
+  /**
+   * Abort signal used to stop watching.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Callback invoked after each regeneration.
+   */
+  readonly onGenerate?: (result: GeneratedCommandsModule) => void;
+  /**
+   * Callback invoked when generation fails during watching.
+   *
+   * @since 1.2.0
+   */
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * Generates a TypeScript module that exports command entries.
+ *
+ * @param options Generation options.
+ * @returns The generated source code and command module metadata.
+ * @throws {TypeError} If options are invalid or no command modules are found.
+ * @since 1.2.0
+ */
+declare function generateCommandsModule(options: GenerateCommandsModuleOptions): Promise<GeneratedCommandsModule>;
+/**
+ * Writes a generated command module to disk.
+ *
+ * @param options Generation options.
+ * @returns The generated source code and command module metadata.
+ * @throws {TypeError} If options are invalid or no command modules are found.
+ * @throws {Error} If the generated module cannot be written.
+ * @since 1.2.0
+ */
+declare function writeCommandsModule(options: GenerateCommandsModuleOptions): Promise<GeneratedCommandsModule>;
+/**
+ * Watches the command file set and rewrites the generated module when it
+ * changes.
+ *
+ * Content-only edits do not trigger regeneration because they do not change
+ * the static module map.
+ *
+ * @param options Watch options.
+ * @returns A promise that resolves when the watch signal is aborted.
+ * @throws {TypeError} If options are invalid.
+ * @since 1.2.0
+ */
+declare function watchCommandsModule(options: WatchCommandsModuleOptions): Promise<void>;
+//#endregion
+export { GenerateCommandsModuleOptions, GeneratedCommandModuleFile, GeneratedCommandsModule, WatchCommandsModuleOptions, generateCommandsModule, watchCommandsModule, writeCommandsModule };

package/dist/generator.js

@@ -0,0 +1,5 @@
+import "./command-DO5zgkvS.js";
+import "./src-Ci75oZo-.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-C12pIuFe.js";
+
+export { generateCommandsModule, watchCommandsModule, writeCommandsModule };