@optique/discover 1.1.0 → 1.2.0-dev.2169

package/dist/index.js

@@ -1,10 +1,12 @@
-import { defineCommand, isCommand } from "./command-y_A3hG0g.js";
-import { or } from "@optique/core/constructs";
+import { defineCommand, isCommand } from "./command-DO5zgkvS.js";
+import { longestMatch, or } from "@optique/core/constructs";
+import { dispatchByMode, inheritAnnotations, mapModeValue, wrapForMode } from "@optique/core/extension";
 import { map } from "@optique/core/modifiers";
 import { command } from "@optique/core/primitives";
+import { mergeHidden } from "@optique/core/usage";
 import { runAsync } from "@optique/run";
 import { readdir, realpath, stat } from "node:fs/promises";
-import { relative, resolve, sep } from "node:path";
+import { posix, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -38,37 +40,81 @@ function getDefaultExtensions(options = {}) {
 * @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()`.
+*         command paths are duplicated, 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 entryFileName = normalizeEntryFileName(options.entryFileName);
 	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 path = commandPathFromFile(dir, filePath, extensions, entryFileName);
 		const key = commandPathKey(path);
 		const previous = seen.get(key);
 		if (previous != null) {
-			const displayPath = path.join(" ");
+			const displayPath = displayCommandPath(path);
 			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(" ")}".`);
+		const commandDefinition = commandFromModuleExport(filePath, mod.default);
+		validateDeclaredCommandPath(commandDefinition, path, filePath, "file path");
 		discovered.push({
 			path,
 			filePath,
 			command: commandDefinition
 		});
 	}
-	rejectPathConflicts(discovered);
+	return sortCommands(discovered);
+}
+/**
+* Converts a static module map into command entries.
+*
+* This is useful for bundlers and single-file packagers that can statically
+* see module maps, such as `import.meta.glob(..., { eager: true })`, while
+* still deriving command paths from file-like module keys.
+*
+* @param modules Static module map keyed by module path.
+* @param options Module path derivation options.
+* @returns Command entries sorted by command path.
+* @throws {TypeError} If options are invalid, no command modules are found,
+*         command paths are duplicated, a module does not default-export a
+*         command created with `defineCommand()`, or an explicit command
+*         `path` does not match the module-derived path.
+* @since 1.2.0
+*/
+function commandsFromModules(modules, options = {}) {
+	if (modules == null || typeof modules !== "object") throw new TypeError("commandsFromModules() requires a module map object.");
+	const base = normalizeModuleBase(options.base);
+	const extensions = normalizeExtensions(options.extensions ?? getDefaultExtensions());
+	const entryFileName = normalizeEntryFileName(options.entryFileName);
+	const modulePaths = Object.keys(modules).toSorted((a, b) => a.localeCompare(b));
+	const seen = /* @__PURE__ */ new Map();
+	const discovered = [];
+	for (const modulePath of modulePaths) {
+		if (isDeclarationFile(posix.basename(modulePath)) || !extensions.some((ext) => modulePath.endsWith(ext))) continue;
+		const path = commandPathFromModulePath(base, modulePath, extensions, entryFileName);
+		const key = commandPathKey(path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = displayCommandPath(path);
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${modulePath}.`);
+		}
+		seen.set(key, modulePath);
+		const commandDefinition = commandFromModuleExport(modulePath, modules[modulePath]);
+		validateDeclaredCommandPath(commandDefinition, path, modulePath, "module path");
+		discovered.push({
+			path,
+			modulePath,
+			command: commandDefinition
+		});
+	}
+	if (discovered.length < 1) throw new TypeError("No command modules found in module map.");
 	return sortCommands(discovered);
 }
 /**
@@ -77,7 +123,8 @@ async function discoverCommands(options) {
 * @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.
+* @throws {TypeError} If no commands are provided or command paths are
+*         duplicated.
 * @since 1.1.0
 */
 function createProgramParser(commands, metadata = {}) {
@@ -85,11 +132,7 @@ function createProgramParser(commands, metadata = {}) {
 	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("/")
+		filePath: displayCommandPath(entry.path)
 	})));
 	const rootNode = buildCommandTree(sortedCommands);
 	const parser = buildNodeParser(rootNode);
@@ -109,7 +152,8 @@ async function runProgram(options) {
 	if (isStaticRunProgramOptions(options)) commands = staticCommandsToEntries(options.commands);
 	else commands = await discoverCommands({
 		dir: options.dir,
-		extensions: options.extensions
+		extensions: options.extensions,
+		entryFileName: options.entryFileName
 	});
 	const parser = createProgramParser(commands, options.metadata);
 	const invocation = await runAsync(parser, buildRunOptions(options));
@@ -140,6 +184,19 @@ function normalizeExtensions(extensions) {
 	}
 	return normalized.toSorted((a, b) => b.length - a.length || a.localeCompare(b));
 }
+function normalizeEntryFileName(entryFileName) {
+	if (entryFileName === void 0) return "index";
+	if (entryFileName === false) return false;
+	if (typeof entryFileName !== "string") throw new TypeError(`Command entry file name must be a non-empty file name: ${entryFileName}`);
+	const normalized = entryFileName;
+	if (normalized.length < 1 || normalized.includes("/") || normalized.includes("\\")) throw new TypeError(`Command entry file name must be a non-empty file name: ${normalized}`);
+	return normalized;
+}
+function normalizeModuleBase(base) {
+	if (base === void 0) return ".";
+	if (typeof base !== "string" || base.length < 1) throw new TypeError(`Module base path must be a non-empty string: ${base}`);
+	return normalizeModulePath(base);
+}
 async function collectCommandFiles(dir, extensions, activeDirs = /* @__PURE__ */ new Set()) {
 	const canonicalDir = await realpath(dir);
 	if (activeDirs.has(canonicalDir)) return [];
@@ -171,29 +228,45 @@ async function getCommandFileEntryType(path, entry) {
 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);
+function commandPathFromFile(rootDir, filePath, extensions, entryFileName) {
+	const withoutExtension = stripCommandExtension(filePath, extensions);
 	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];
+	return commandPathFromSegments(path, filePath, entryFileName);
+}
+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 normalizedPath = normalizeModulePath(modulePath);
+	const relativePath = posix.relative(base, normalizedPath);
+	if (relativePath.length < 1 || relativePath === ".." || relativePath.startsWith("../") || posix.isAbsolute(relativePath)) throw new TypeError(`Module path ${originalModulePath} is not under base path ${base}.`);
+	return relativePath;
+}
+function normalizeModulePath(path) {
+	return posix.normalize(path.replaceAll("\\", "/"));
+}
+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 commandPathKey(path) {
 	return path.join("\0");
 }
+function displayCommandPath(path) {
+	return path.length < 1 ? "<root>" : path.join(" ");
+}
 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(" ")}".`);
-	}
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
 }
 function rejectDuplicatePaths(commands) {
 	const seen = /* @__PURE__ */ new Map();
@@ -201,7 +274,7 @@ function rejectDuplicatePaths(commands) {
 		const key = commandPathKey(entry.path);
 		const previous = seen.get(key);
 		if (previous != null) {
-			const displayPath = entry.path.join(" ");
+			const displayPath = displayCommandPath(entry.path);
 			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${entry.filePath}.`);
 		}
 		seen.set(key, entry.filePath);
@@ -217,23 +290,38 @@ function isStaticRunProgramOptions(options) {
 	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 commands.map((entry) => {
+		if (isCommandEntry(entry)) return entry;
+		if (!isCommand(entry)) throw new TypeError("Static command entries must be created with defineCommand().");
+		if (!isCommandPath(entry.path)) throw new TypeError("Static command entries must declare a path.");
 		return {
-			path: command$1.path,
-			command: command$1
+			path: entry.path,
+			command: entry
 		};
 	});
 }
+function isCommandEntry(value) {
+	return value != null && typeof value === "object" && isCommandPath(value.path) && isCommand(value.command);
+}
 function unwrapCommandExport(value) {
-	if (isCommand(value)) return value;
-	if (value != null && typeof value === "object") {
-		const nestedDefault = value.default;
-		if (isCommand(nestedDefault)) return nestedDefault;
+	let current = value;
+	for (let depth = 0; depth < 3; depth++) {
+		if (isCommand(current)) return current;
+		if (current == null || typeof current !== "object") return void 0;
+		const nestedDefault = current.default;
+		if (Object.is(nestedDefault, current)) return void 0;
+		current = nestedDefault;
 	}
 	return void 0;
 }
+function commandFromModuleExport(source, value) {
+	const commandDefinition = unwrapCommandExport(value);
+	if (commandDefinition == null) throw new TypeError(`Module ${source} default export must be created with defineCommand().`);
+	return commandDefinition;
+}
+function validateDeclaredCommandPath(commandDefinition, path, source, sourcePathLabel) {
+	if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${source} declares command path "${displayCommandPath(commandDefinition.path)}" but ${sourcePathLabel} defines "${displayCommandPath(path)}".`);
+}
 function buildCommandTree(commands) {
 	const root = { children: /* @__PURE__ */ new Map() };
 	for (const entry of commands) {
@@ -250,41 +338,354 @@ function buildCommandTree(commands) {
 	}
 	return root;
 }
-function buildNodeParser(node) {
+function buildNodeParser(node, inheritedHidden) {
+	const childParser = buildChildrenParser(node, inheritedHidden);
+	if (childParser != null && node.command != null) return createExecutableNodeParser(childParser, node.command);
+	if (childParser != null) return childParser;
+	if (node.command != null) return createLeafParser(node.command);
+	throw new TypeError("Command tree node must contain a command.");
+}
+function createExecutableNodeParser(childParser, commandDefinition) {
+	const leafParser = createLeafParser(commandDefinition, true);
+	const branchParsers = [childParser, leafParser];
+	const parser = longestMatch(childParser, leafParser);
+	const phase2SeedHook = findPhase2SeedHook(parser);
+	const executableParser = {
+		...parser,
+		$valueType: [],
+		$stateType: [],
+		initialState: void 0,
+		parse(context) {
+			const activeState = normalizeExecutableNodeState(context.state);
+			if (activeState?.committed === true && activeState.result.success) {
+				const branchParser = branchParsers[activeState.branch];
+				const result$1 = branchParser.parse(withExecutableNodeChildContext(context, activeState.branch, inheritAnnotations(context.state, activeState.result.next.state), branchParser));
+				return mapModeValue(parser.mode, wrapForMode(parser.mode, result$1), (resolved) => wrapBranchParseResult(context, activeState, resolved));
+			}
+			const result = parser.parse({
+				...context,
+				state: toExclusiveState(activeState, context.state)
+			});
+			return mapModeValue(parser.mode, wrapForMode(parser.mode, result), (resolved) => wrapInitialParseResult(context, resolved));
+		},
+		complete(state, exec) {
+			const activeState = normalizeExecutableNodeState(state);
+			if (activeState?.result.success === true) return wrapForMode(parser.mode, branchParsers[activeState.branch].complete(inheritAnnotations(state, activeState.result.next.state), withExecutableNodeChildExecPath(exec, activeState.branch)));
+			if (activeState == null) return wrapForMode(parser.mode, completeExecutableNodeLeaf(state, exec, leafParser));
+			return wrapForMode(parser.mode, parser.complete(toExclusiveState(activeState, state), exec));
+		},
+		suggest(context, prefix) {
+			const activeState = normalizeExecutableNodeState(context.state);
+			if (activeState?.committed === true && activeState.result.success) {
+				const branchParser = branchParsers[activeState.branch];
+				return branchParser.suggest(withExecutableNodeChildContext(context, activeState.branch, inheritAnnotations(context.state, activeState.result.next.state), branchParser), prefix);
+			}
+			return parser.suggest({
+				...context,
+				state: toExclusiveState(activeState, context.state)
+			}, prefix);
+		},
+		getSuggestRuntimeNodes(state, path) {
+			const activeState = normalizeExecutableNodeState(state);
+			if (activeState == null) {
+				const branchPath$1 = [...path, 1];
+				const branchState$1 = inheritAnnotations(state, leafParser.initialState);
+				return getExecutableNodeBranchSuggestRuntimeNodes(leafParser, branchState$1, branchPath$1);
+			}
+			if (activeState?.result.success !== true) return parser.getSuggestRuntimeNodes?.(toExclusiveState(activeState, state), path) ?? [];
+			const branchParser = branchParsers[activeState.branch];
+			const branchPath = [...path, activeState.branch];
+			const branchState = inheritAnnotations(state, activeState.result.next.state);
+			return getExecutableNodeBranchSuggestRuntimeNodes(branchParser, branchState, branchPath);
+		},
+		getDocFragments(state, defaultValue) {
+			const activeState = state.kind === "available" ? normalizeExecutableNodeState(state.state) : void 0;
+			const fragments = parser.getDocFragments(state.kind === "available" ? {
+				kind: "available",
+				state: toExclusiveState(activeState, state.state)
+			} : state, defaultValue);
+			if (activeState == null) return withCommandDocMetadata(fragments, commandDefinition.metadata);
+			return fragments;
+		}
+	};
+	if (phase2SeedHook != null) Object.defineProperty(executableParser, phase2SeedHook.key, {
+		value(state, exec) {
+			return extractExecutableNodePhase2Seed(state, exec, leafParser, phase2SeedHook);
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return executableParser;
+}
+function getExecutableNodeBranchSuggestRuntimeNodes(parser, state, path) {
+	return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
+		path,
+		parser,
+		state
+	}] : []);
+}
+const phase2SeedSymbolDescription = "@optique/core/extractPhase2Seed";
+function findPhase2SeedHook(parser) {
+	for (const key of Object.getOwnPropertySymbols(parser)) {
+		if (key.description !== phase2SeedSymbolDescription) continue;
+		const value = Reflect.get(parser, key);
+		if (typeof value !== "function") continue;
+		return {
+			key,
+			extract(state, exec) {
+				const seed = Reflect.apply(value, parser, [state, exec]);
+				return seed;
+			}
+		};
+	}
+	return void 0;
+}
+function completeExecutableNodeLeaf(state, exec, leafParser) {
+	const result = parseExecutableNodeLeaf(state, exec, leafParser);
+	return dispatchByMode(leafParser.mode, () => wrapForMode("sync", completeParsedExecutableNodeLeaf(state, exec, leafParser, wrapForMode("sync", result))), () => Promise.resolve(wrapForMode("async", result)).then((resolved) => wrapForMode("async", completeParsedExecutableNodeLeaf(state, exec, leafParser, resolved))));
+}
+function completeParsedExecutableNodeLeaf(state, exec, leafParser, result) {
+	const childExec = withExecutableNodeChildExecPath(exec, 1);
+	const nextExec = result.success ? mergeExecutableNodeChildExec(childExec, result.next.exec) : childExec;
+	const nextState = result.success ? inheritAnnotations(state, result.next.state) : inheritAnnotations(state, leafParser.initialState);
+	return leafParser.complete(nextState, nextExec);
+}
+function extractExecutableNodePhase2Seed(state, exec, leafParser, phase2SeedHook) {
+	const activeState = normalizeExecutableNodeState(state);
+	if (activeState != null) return phase2SeedHook.extract(toExclusiveState(activeState, state), exec);
+	const result = parseExecutableNodeLeaf(state, exec, leafParser);
+	return dispatchByMode(leafParser.mode, () => extractParsedExecutableNodePhase2Seed(state, exec, wrapForMode("sync", result), phase2SeedHook), () => Promise.resolve(wrapForMode("async", result)).then((resolved) => extractParsedExecutableNodePhase2Seed(state, exec, resolved, phase2SeedHook)));
+}
+function extractParsedExecutableNodePhase2Seed(state, exec, result, phase2SeedHook) {
+	if (!result.success) return phase2SeedHook.extract(toExclusiveState(void 0, state), exec);
+	const executableState = inheritAnnotations(state, {
+		branch: 1,
+		result,
+		committed: false
+	});
+	return phase2SeedHook.extract(toExclusiveState(executableState, state), exec);
+}
+function parseExecutableNodeLeaf(state, exec, leafParser) {
+	const childExec = withExecutableNodeChildExecPath(exec, 1);
+	const childContext = {
+		buffer: [],
+		optionsTerminated: false,
+		usage: leafParser.usage,
+		state: inheritAnnotations(state, leafParser.initialState),
+		...childExec != null ? {
+			exec: childExec,
+			dependencyRegistry: childExec.dependencyRegistry
+		} : {}
+	};
+	return leafParser.parse(childContext);
+}
+function normalizeExecutableNodeState(state) {
+	if (state == null || typeof state !== "object" || !("branch" in state) || !("result" in state)) return void 0;
+	const branch = state.branch;
+	if (branch !== 0 && branch !== 1) return void 0;
+	const result = state.result;
+	if (result == null || typeof result !== "object" || typeof result.success !== "boolean") return void 0;
+	return inheritAnnotations(state, {
+		branch,
+		result,
+		committed: state.committed === true
+	});
+}
+function toExclusiveState(state, sourceState = state) {
+	const exclusiveState = state == null ? void 0 : [state.branch, state.result];
+	return inheritAnnotations(sourceState, exclusiveState);
+}
+function fromExclusiveState(state) {
+	if (!Array.isArray(state) || state.length !== 2 || state[0] !== 0 && state[0] !== 1) return void 0;
+	return inheritAnnotations(state, {
+		branch: state[0],
+		result: state[1],
+		committed: isCommittedResult(state[1])
+	});
+}
+function isCommittedResult(result) {
+	return result != null && typeof result === "object" && result.success === true && Array.isArray(result.consumed) && result.consumed.length > 0;
+}
+function wrapInitialParseResult(_context, result) {
+	if (!result.success) return result;
+	return {
+		success: true,
+		consumed: result.consumed,
+		provisional: result.provisional,
+		next: {
+			...result.next,
+			state: fromExclusiveState(result.next.state)
+		}
+	};
+}
+function wrapBranchParseResult(context, activeState, result) {
+	if (!result.success) return result;
+	const mergedExec = mergeExecutableNodeChildExec(context.exec, result.next.exec);
+	const dependencyRegistry = mergedExec?.dependencyRegistry ?? result.next.dependencyRegistry ?? context.dependencyRegistry;
+	const nextState = inheritAnnotations(result.next.state, {
+		branch: activeState.branch,
+		result,
+		committed: activeState.committed || result.consumed.length > 0
+	});
+	return {
+		success: true,
+		consumed: result.consumed,
+		provisional: result.provisional,
+		next: {
+			...context,
+			buffer: result.next.buffer,
+			optionsTerminated: result.next.optionsTerminated,
+			state: inheritAnnotations(context.state, nextState),
+			...mergedExec != null ? {
+				exec: mergedExec,
+				trace: mergedExec.trace
+			} : {},
+			...dependencyRegistry != null ? { dependencyRegistry } : {}
+		}
+	};
+}
+function withExecutableNodeChildContext(context, branch, state, parser) {
+	const exec = withExecutableNodeChildExecPath(context.exec, branch);
+	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	return {
+		...context,
+		state,
+		usage: parser.usage,
+		...exec != null ? {
+			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
+				...exec,
+				dependencyRegistry
+			},
+			dependencyRegistry
+		} : {}
+	};
+}
+function withExecutableNodeChildExecPath(exec, branch) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		path: [...exec.path ?? [], branch]
+	};
+}
+function mergeExecutableNodeChildExec(parent, child) {
+	if (parent == null) return child;
+	if (child == null) return parent;
+	return {
+		...parent,
+		trace: child.trace ?? parent.trace,
+		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
+		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		commandPath: child.commandPath ?? parent.commandPath,
+		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
+		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
+	};
+}
+function withCommandDocMetadata(fragments, metadata) {
+	if (metadata == null) return fragments;
+	return {
+		...fragments,
+		brief: fragments.brief ?? metadata.brief,
+		description: fragments.description ?? metadata.description,
+		footer: fragments.footer ?? metadata.footer
+	};
+}
+function buildChildrenParser(node, inheritedHidden) {
 	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));
+		const childHidden = mergeHidden(inheritedHidden, child.command?.metadata?.hidden);
+		const childParser = buildNodeParser(child, childHidden);
+		if (child.children.size > 0) parsers.push(createNamespaceCommandParser(name, childParser, child.command, inheritedHidden));
+		else parsers.push(command(name, childParser, commandMetadataWithInheritedHidden(child.command?.metadata, inheritedHidden)));
 	}
+	if (parsers.length < 1) return void 0;
 	if (parsers.length === 1) return parsers[0];
 	return or(...parsers);
 }
-function createLeafParser(commandDefinition) {
-	return map(commandDefinition.parser, (value) => ({
+function createNamespaceCommandParser(name, childParser, commandDefinition, inheritedHidden) {
+	const metadata = commandDefinition?.metadata;
+	const parser = command(name, childParser, namespaceCommandMetadata(metadata, inheritedHidden));
+	const description = metadata?.brief ?? metadata?.description;
+	if (description == null) return parser;
+	return {
+		...parser,
+		getDocFragments(state, defaultValue) {
+			const fragments = parser.getDocFragments(state, defaultValue);
+			if (state.kind !== "unavailable" && (state.kind !== "available" || !Object.is(state.state, parser.initialState))) return fragments;
+			return withNamespaceListDocDescription(fragments, name, description);
+		}
+	};
+}
+function withNamespaceListDocDescription(fragments, name, description) {
+	return {
+		...fragments,
+		fragments: fragments.fragments.map((fragment) => {
+			if (fragment.type !== "entry" || fragment.term.type !== "command" || fragment.term.name !== name) return fragment;
+			return {
+				...fragment,
+				description: fragment.description ?? description
+			};
+		})
+	};
+}
+function namespaceCommandMetadata(metadata, inheritedHidden) {
+	const hidden = mergeHidden(inheritedHidden, metadata?.hidden);
+	if (metadata?.aliases == null && metadata?.errors == null && hidden == null && metadata?.usageLine == null) return void 0;
+	return {
+		...metadata?.aliases != null && { aliases: metadata.aliases },
+		...metadata?.errors != null && { errors: metadata.errors },
+		...hidden != null && { hidden },
+		...metadata?.usageLine != null && { usageLine: metadata.usageLine }
+	};
+}
+function commandMetadataWithInheritedHidden(metadata, inheritedHidden) {
+	const hidden = mergeHidden(inheritedHidden, metadata?.hidden);
+	if (metadata == null) return hidden == null ? void 0 : { hidden };
+	if (hidden === metadata.hidden) return metadata;
+	return {
+		...metadata,
+		...hidden != null && { hidden }
+	};
+}
+function createLeafParser(commandDefinition, includeMetadata = false) {
+	const parser = map(commandDefinition.parser, (value) => ({
 		command: commandDefinition,
 		value,
 		handler: commandDefinition.handler
 	}));
+	if (!includeMetadata) return parser;
+	return {
+		...parser,
+		getDocFragments(state, defaultValue) {
+			const fragments = parser.getDocFragments(state, defaultValue);
+			return withCommandDocMetadata(fragments, commandDefinition.metadata);
+		}
+	};
 }
 function withRootDocs(parser, commands, metadata) {
 	const rootState = parser.initialState;
-	const rootDocs = () => ({
-		brief: metadata.brief,
-		description: metadata.description,
-		footer: metadata.footer,
-		fragments: [{
+	const rootCommand = commands.find((entry) => entry.path.length < 1);
+	const listedCommands = commands.filter((entry) => entry.path.length > 0);
+	const commandsByPath = new Map(commands.map((entry) => [commandPathKey(entry.path), entry.command]));
+	const rootDocs = () => {
+		const fragments = [...rootCommand?.command.parser.getDocFragments({ kind: "unavailable" }).fragments ?? []];
+		if (listedCommands.length > 0) fragments.push({
 			type: "section",
-			entries: commands.map((entry) => ({
+			entries: listedCommands.map((entry) => ({
 				term: {
 					type: "command",
 					name: entry.path.join(" "),
-					hidden: entry.command.metadata?.hidden
+					hidden: commandPathHidden(entry.path, commandsByPath)
 				},
 				description: entry.command.metadata?.brief ?? entry.command.metadata?.description
 			}))
-		}]
-	});
+		});
+		return {
+			brief: metadata.brief,
+			description: metadata.description,
+			footer: metadata.footer,
+			fragments
+		};
+	};
 	return {
 		...parser,
 		getDocFragments(state, defaultValue) {
@@ -293,9 +694,14 @@ function withRootDocs(parser, commands, metadata) {
 		}
 	};
 }
+function commandPathHidden(path, commandsByPath) {
+	let hidden;
+	for (let length = 1; length <= path.length; length++) hidden = mergeHidden(hidden, commandsByPath.get(commandPathKey(path.slice(0, length)))?.metadata?.hidden);
+	return hidden;
+}
 function buildRunOptions(options) {
 	const metadata = options.metadata;
-	const { dir: _dir, commands: _commands, extensions: _extensions, metadata: _metadata, help, version, completion,...rest } = options;
+	const { dir: _dir, commands: _commands, extensions: _extensions, entryFileName: _entryFileName, metadata: _metadata, help, version, completion,...rest } = options;
 	const runOptions = {
 		...rest,
 		contexts: unwrapProgramContexts(rest.contexts),
@@ -345,4 +751,4 @@ function isProgramInvocation(value) {
 }
 
 //#endregion
-export { createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };