@optique/discover 1.1.0-dev.0

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-BAVhIzfI.js";
+import { RunOptions } from "@optique/run";
+import { Mode, Parser } from "@optique/core/parser";
+import { Message } from "@optique/core/message";
+import { ProgramMetadata } from "@optique/core/program";
+
+//#region src/index.d.ts
+
+/**
+ * The parsed command selected by a discovered command parser.
+ *
+ * Most applications receive this only indirectly through {@link runProgram},
+ * which calls the handler automatically.
+ *
+ * @since 1.1.0
+ */
+interface ProgramInvocation {
+  /**
+   * The command definition that matched the input.
+   */
+  readonly command: AnyCommand;
+  /**
+   * Parsed value produced by the command parser.
+   */
+  readonly value: unknown;
+  /**
+   * Handler to call with {@link ProgramInvocation.value}.
+   */
+  readonly handler: (value: unknown) => void | Promise<void>;
+}
+/**
+ * A command found on disk.
+ *
+ * @since 1.1.0
+ */
+interface DiscoveredCommand {
+  /**
+   * Command path derived from the module's relative path.
+   */
+  readonly path: CommandPath;
+  /**
+   * Absolute path to the command module.
+   */
+  readonly filePath: string;
+  /**
+   * The command exported by the module.
+   */
+  readonly command: AnyCommand;
+}
+/**
+ * Options for {@link discoverCommands}.
+ *
+ * @since 1.1.0
+ */
+interface DiscoverCommandsOptions {
+  /**
+   * Directory to scan recursively.
+   */
+  readonly dir: string | URL;
+  /**
+   * File suffixes to include.  Compound suffixes such as `.cmd.ts` are
+   * supported.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+}
+/**
+ * Runtime hint for {@link getDefaultExtensions}.
+ *
+ * @since 1.1.0
+ */
+interface RuntimeExtensionOptions {
+  /**
+   * Runtime to model.
+   */
+  readonly runtime?: "node" | "deno" | "bun";
+  /**
+   * Node.js execution arguments used for TypeScript loader detection.
+   */
+  readonly execArgv?: readonly string[];
+  /**
+   * The `NODE_OPTIONS` value used for TypeScript loader detection.
+   */
+  readonly nodeOptions?: string;
+  /**
+   * Whether the Node.js runtime supports TypeScript files without a custom
+   * loader or flag.
+   */
+  readonly nodeTypeScriptSupport?: boolean;
+}
+interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "completion" | "programName"> {
+  /**
+   * Root program metadata.
+   */
+  readonly metadata: ProgramMetadata;
+  /**
+   * Program name override for help, errors, and completion scripts.
+   *
+   * @default `metadata.name`
+   */
+  readonly programName?: string;
+  /**
+   * Help configuration.  Pass `false` to disable built-in help.
+   *
+   * @default `"both"`
+   */
+  readonly help?: RunOptions["help"] | false;
+  /**
+   * Version configuration.  Pass `false` to disable built-in version output.
+   *
+   * @default `metadata.version` as `--version`, when present
+   */
+  readonly version?: RunOptions["version"] | false;
+  /**
+   * Shell completion configuration.  Pass `false` to disable built-in
+   * completion.
+   *
+   * @default `"both"`
+   */
+  readonly completion?: RunOptions["completion"] | false;
+}
+/**
+ * Options for {@link runProgram} when discovering commands from files.
+ *
+ * @since 1.1.0
+ */
+interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
+  /**
+   * Directory containing command modules.
+   */
+  readonly dir: string | URL;
+  /**
+   * File suffixes to include during discovery.
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * Static commands cannot be used together with `dir`.
+   */
+  readonly commands?: never;
+}
+/**
+ * Options for {@link runProgram} when commands are imported manually.
+ *
+ * @since 1.1.0
+ */
+interface RunProgramStaticOptions extends RunProgramBaseOptions {
+  /**
+   * Commands to compose without file-system discovery.
+   */
+  readonly commands: readonly AnyStaticCommand[];
+  /**
+   * File-system discovery cannot be used together with `commands`.
+   */
+  readonly dir?: never;
+  /**
+   * File suffixes are only used with file-system discovery.
+   */
+  readonly extensions?: never;
+}
+/**
+ * Options for {@link runProgram}.
+ *
+ * @since 1.1.0
+ */
+type RunProgramOptions = RunProgramDiscoveryOptions | RunProgramStaticOptions;
+/**
+ * Returns runtime-aware command module suffixes.
+ *
+ * @param options Runtime detection overrides for testing or custom launchers.
+ * @returns File suffixes to scan.
+ * @since 1.1.0
+ */
+declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readonly string[];
+/**
+ * Discovers command modules under a directory.
+ *
+ * @param options Discovery options.
+ * @returns Discovered commands sorted by command path.
+ * @throws {TypeError} If options are invalid, discovery finds no commands,
+ *         command paths conflict, or a module does not default-export a
+ *         command created with `defineCommand()`.
+ * @since 1.1.0
+ */
+declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
+/**
+ * Builds a parser that dispatches to discovered command handlers.
+ *
+ * @param commands Commands to compose.
+ * @param metadata Optional root documentation metadata.
+ * @returns A parser that resolves to an internal command invocation.
+ * @throws {TypeError} If no commands are provided or command paths conflict.
+ * @since 1.1.0
+ */
+declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
+/**
+ * Discovers and runs a command program.
+ *
+ * @param options Program options.
+ * @returns A promise that resolves after the selected command handler
+ *          completes.
+ * @throws {TypeError} If discovery or command loading fails.
+ * @since 1.1.0
+ */
+declare function runProgram(options: RunProgramOptions): Promise<void>;
+/**
+ * Root help metadata for {@link createProgramParser}.
+ *
+ * @since 1.1.0
+ */
+interface ProgramHelpMetadata {
+  /**
+   * Brief text shown before the command list.
+   */
+  readonly brief?: Message;
+  /**
+   * Detailed text shown before the command list.
+   */
+  readonly description?: Message;
+  /**
+   * Footer text shown after the command list.
+   */
+  readonly footer?: Message;
+}
+//#endregion
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, type CommandMetadata, type CommandPath, DiscoverCommandsOptions, DiscoveredCommand, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.js

@@ -0,0 +1,348 @@
+import { defineCommand, isCommand } from "./command-y_A3hG0g.js";
+import { or } from "@optique/core/constructs";
+import { map } from "@optique/core/modifiers";
+import { command } from "@optique/core/primitives";
+import { runAsync } from "@optique/run";
+import { readdir, realpath, stat } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+//#region src/index.ts
+/**
+* Returns runtime-aware command module suffixes.
+*
+* @param options Runtime detection overrides for testing or custom launchers.
+* @returns File suffixes to scan.
+* @since 1.1.0
+*/
+function getDefaultExtensions(options = {}) {
+	const runtime = options.runtime ?? getRuntime();
+	if (runtime === "deno" || runtime === "bun") return [
+		".ts",
+		".mts",
+		".js",
+		".mjs"
+	];
+	const extensions = [
+		".js",
+		".mjs",
+		".cjs"
+	];
+	if (hasNodeTypeScriptLoader(options.execArgv ?? process.execArgv, options.nodeOptions ?? process.env.NODE_OPTIONS ?? "", options.nodeTypeScriptSupport ?? hasNativeNodeTypeScriptSupport())) extensions.push(".ts", ".mts", ".cts");
+	return extensions;
+}
+/**
+* Discovers command modules under a directory.
+*
+* @param options Discovery options.
+* @returns Discovered commands sorted by command path.
+* @throws {TypeError} If options are invalid, discovery finds no commands,
+*         command paths conflict, or a module does not default-export a
+*         command created with `defineCommand()`.
+* @since 1.1.0
+*/
+async function discoverCommands(options) {
+	const dir = pathFromDir(options.dir);
+	const extensions = normalizeExtensions(options.extensions ?? getDefaultExtensions());
+	const files = await collectCommandFiles(dir, extensions);
+	if (files.length < 1) throw new TypeError(`No command modules found in ${dir}.`);
+	const seen = /* @__PURE__ */ new Map();
+	const discovered = [];
+	for (const filePath of files) {
+		const path = commandPathFromFile(dir, filePath, extensions);
+		const key = commandPathKey(path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = path.join(" ");
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${filePath}.`);
+		}
+		seen.set(key, filePath);
+		const mod = await import(pathToFileURL(filePath).href);
+		const commandDefinition = unwrapCommandExport(mod.default);
+		if (commandDefinition == null) throw new TypeError(`Module ${filePath} default export must be created with defineCommand().`);
+		if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${filePath} declares command path "${commandDefinition.path.join(" ")}" but file path defines "${path.join(" ")}".`);
+		discovered.push({
+			path,
+			filePath,
+			command: commandDefinition
+		});
+	}
+	rejectPathConflicts(discovered);
+	return sortCommands(discovered);
+}
+/**
+* Builds a parser that dispatches to discovered command handlers.
+*
+* @param commands Commands to compose.
+* @param metadata Optional root documentation metadata.
+* @returns A parser that resolves to an internal command invocation.
+* @throws {TypeError} If no commands are provided or command paths conflict.
+* @since 1.1.0
+*/
+function createProgramParser(commands, metadata = {}) {
+	if (commands.length < 1) throw new TypeError("createProgramParser() requires at least one command.");
+	const sortedCommands = sortCommands(commands);
+	rejectDuplicatePaths(sortedCommands.map((entry) => ({
+		path: entry.path,
+		filePath: entry.path.join("/")
+	})));
+	rejectPathConflicts(sortedCommands.map((entry) => ({
+		path: entry.path,
+		filePath: entry.path.join("/")
+	})));
+	const rootNode = buildCommandTree(sortedCommands);
+	const parser = buildNodeParser(rootNode);
+	return withRootDocs(parser, sortedCommands, metadata);
+}
+/**
+* Discovers and runs a command program.
+*
+* @param options Program options.
+* @returns A promise that resolves after the selected command handler
+*          completes.
+* @throws {TypeError} If discovery or command loading fails.
+* @since 1.1.0
+*/
+async function runProgram(options) {
+	let commands;
+	if (isStaticRunProgramOptions(options)) commands = staticCommandsToEntries(options.commands);
+	else commands = await discoverCommands({
+		dir: options.dir,
+		extensions: options.extensions
+	});
+	const parser = createProgramParser(commands, options.metadata);
+	const invocation = await runAsync(parser, buildRunOptions(options));
+	await invocation.handler(invocation.value);
+}
+function getRuntime() {
+	if ("Deno" in globalThis) return "deno";
+	if ("Bun" in globalThis) return "bun";
+	return "node";
+}
+function hasNodeTypeScriptLoader(execArgv, nodeOptions, nativeSupport) {
+	const haystack = [...execArgv, nodeOptions].join(" ");
+	return nativeSupport || /\b(?:tsx|ts-node|tsimp|jiti)\b/.test(haystack) || /--(?:experimental-)?transform-types\b/.test(haystack) || /--experimental-strip-types\b/.test(haystack);
+}
+function hasNativeNodeTypeScriptSupport() {
+	const features = process.features;
+	return features?.typescript === "strip" || features?.typescript === "transform";
+}
+function pathFromDir(dir) {
+	return typeof dir === "string" ? resolve(dir) : fileURLToPath(dir);
+}
+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));
+}
+async function collectCommandFiles(dir, extensions, activeDirs = /* @__PURE__ */ new Set()) {
+	const canonicalDir = await realpath(dir);
+	if (activeDirs.has(canonicalDir)) return [];
+	const nextActiveDirs = new Set(activeDirs);
+	nextActiveDirs.add(canonicalDir);
+	const entries = await readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+		const path = resolve(dir, entry.name);
+		const entryType = await getCommandFileEntryType(path, entry);
+		if (entryType === "directory") files.push(...await collectCommandFiles(path, extensions, nextActiveDirs));
+		else if (entryType === "file" && !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 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 commandPathFromFile(rootDir, filePath, extensions) {
+	const matchedExtension = extensions.find((ext) => filePath.endsWith(ext));
+	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${filePath}.`);
+	const withoutExtension = filePath.slice(0, -matchedExtension.length);
+	const relativePath = relative(rootDir, withoutExtension);
+	const path = relativePath.split(sep).filter((segment) => segment.length > 0);
+	const [first, ...rest] = path;
+	if (first == null) throw new TypeError(`Command file ${filePath} does not define a path.`);
+	return [first, ...rest];
+}
+function commandPathKey(path) {
+	return path.join("\0");
+}
+function isCommandPath(path) {
+	return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0);
+}
+function rejectPathConflicts(commands) {
+	const paths = new Map(commands.map((entry) => [commandPathKey(entry.path), entry]));
+	for (const entry of commands) for (let i = 1; i < entry.path.length; i++) {
+		const parent = entry.path.slice(0, i);
+		const parentEntry = paths.get(commandPathKey(parent));
+		if (parentEntry != null) throw new TypeError(`Command path "${parent.join(" ")}" conflicts with nested command "${entry.path.join(" ")}".`);
+	}
+}
+function rejectDuplicatePaths(commands) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const entry of commands) {
+		const key = commandPathKey(entry.path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = entry.path.join(" ");
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${entry.filePath}.`);
+		}
+		seen.set(key, entry.filePath);
+	}
+}
+function sortCommands(commands) {
+	return commands.toSorted((a, b) => commandPathKey(a.path).localeCompare(commandPathKey(b.path)));
+}
+function isStaticRunProgramOptions(options) {
+	const hasCommands = "commands" in options && options.commands != null;
+	const hasDir = "dir" in options && options.dir != null;
+	if (hasCommands === hasDir) throw new TypeError("runProgram() requires exactly one of dir or commands.");
+	return hasCommands;
+}
+function staticCommandsToEntries(commands) {
+	return commands.map((command$1) => {
+		if (!isCommand(command$1)) throw new TypeError("Static command entries must be created with defineCommand().");
+		if (!isCommandPath(command$1.path)) throw new TypeError("Static command entries must declare a non-empty path.");
+		return {
+			path: command$1.path,
+			command: command$1
+		};
+	});
+}
+function unwrapCommandExport(value) {
+	if (isCommand(value)) return value;
+	if (value != null && typeof value === "object") {
+		const nestedDefault = value.default;
+		if (isCommand(nestedDefault)) return nestedDefault;
+	}
+	return void 0;
+}
+function buildCommandTree(commands) {
+	const root = { children: /* @__PURE__ */ new Map() };
+	for (const entry of commands) {
+		let current = root;
+		for (const segment of entry.path) {
+			let child = current.children.get(segment);
+			if (child == null) {
+				child = { children: /* @__PURE__ */ new Map() };
+				current.children.set(segment, child);
+			}
+			current = child;
+		}
+		current.command = entry.command;
+	}
+	return root;
+}
+function buildNodeParser(node) {
+	const parsers = [];
+	for (const [name, child] of node.children) {
+		const childParser = child.command != null ? createLeafParser(child.command) : buildNodeParser(child);
+		const metadata = child.command?.metadata;
+		parsers.push(command(name, childParser, metadata));
+	}
+	if (parsers.length === 1) return parsers[0];
+	return or(...parsers);
+}
+function createLeafParser(commandDefinition) {
+	return map(commandDefinition.parser, (value) => ({
+		command: commandDefinition,
+		value,
+		handler: commandDefinition.handler
+	}));
+}
+function withRootDocs(parser, commands, metadata) {
+	const rootState = parser.initialState;
+	const rootDocs = () => ({
+		brief: metadata.brief,
+		description: metadata.description,
+		footer: metadata.footer,
+		fragments: [{
+			type: "section",
+			entries: commands.map((entry) => ({
+				term: {
+					type: "command",
+					name: entry.path.join(" "),
+					hidden: entry.command.metadata?.hidden
+				},
+				description: entry.command.metadata?.brief ?? entry.command.metadata?.description
+			}))
+		}]
+	});
+	return {
+		...parser,
+		getDocFragments(state, defaultValue) {
+			if (state.kind === "unavailable" || state.kind === "available" && Object.is(state.state, rootState)) return rootDocs();
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+function buildRunOptions(options) {
+	const metadata = options.metadata;
+	const { dir: _dir, commands: _commands, extensions: _extensions, metadata: _metadata, help, version, completion,...rest } = options;
+	const runOptions = {
+		...rest,
+		contexts: unwrapProgramContexts(rest.contexts),
+		programName: options.programName ?? metadata.name,
+		brief: options.brief ?? metadata.brief,
+		description: options.description ?? metadata.description,
+		examples: options.examples ?? metadata.examples,
+		author: options.author ?? metadata.author,
+		bugs: options.bugs ?? metadata.bugs,
+		footer: options.footer ?? metadata.footer,
+		help: help === false ? void 0 : help ?? "both",
+		version: version === false ? void 0 : version ?? (metadata.version == null ? void 0 : metadata.version),
+		completion: completion === false ? void 0 : completion ?? "both"
+	};
+	return runOptions;
+}
+function unwrapProgramContexts(contexts) {
+	if (contexts == null) return void 0;
+	return contexts.map(wrapProgramContext);
+}
+function wrapProgramContext(context) {
+	const wrapped = {
+		id: context.id,
+		phase: context.phase,
+		getAnnotations(request, options) {
+			return context.getAnnotations(unwrapProgramContextRequest(request), options);
+		}
+	};
+	if (context.getInternalAnnotations != null) wrapped.getInternalAnnotations = (request, annotations) => {
+		return context.getInternalAnnotations(unwrapProgramContextRequest(request) ?? request, annotations);
+	};
+	if (context[Symbol.dispose] != null) wrapped[Symbol.dispose] = () => context[Symbol.dispose]();
+	if (context[Symbol.asyncDispose] != null) wrapped[Symbol.asyncDispose] = () => context[Symbol.asyncDispose]();
+	return wrapped;
+}
+function unwrapProgramContextRequest(request) {
+	if (request?.phase === "phase2" && isProgramInvocation(request.parsed)) return {
+		phase: "phase2",
+		parsed: request.parsed.value
+	};
+	return request;
+}
+function isProgramInvocation(value) {
+	if (value == null || typeof value !== "object") return false;
+	const candidate = value;
+	return "value" in value && isCommand(candidate.command) && typeof candidate.handler === "function";
+}
+
+//#endregion
+export { createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@optique/discover",
+  "version": "1.1.0-dev.0",
+  "description": "Runtime-aware command discovery for Optique CLI programs",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "commands",
+    "discovery"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/discover/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./command": {
+      "types": {
+        "import": "./dist/command.d.ts",
+        "require": "./dist/command.d.cts"
+      },
+      "import": "./dist/command.js",
+      "require": "./dist/command.cjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@optique/core": "1.1.0",
+    "@optique/run": "1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --experimental-transform-types --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test --allow-read --allow-write --allow-env",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test --allow-read --allow-write --allow-env"
+  }
+}