@optique/discover 1.1.0 → 1.2.0-dev.2169

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-2HtR3-TV.cjs";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DSHBTa5c.cjs";
 import { Mode, Parser } from "@optique/core/parser";
 import { Message } from "@optique/core/message";
 import { ProgramMetadata } from "@optique/core/program";
@@ -28,12 +28,31 @@ interface ProgramInvocation {
    */
   readonly handler: (value: unknown) => void | Promise<void>;
 }
+/**
+ * A command paired with its command path.
+ *
+ * `createProgramParser()` accepts command entries directly, and
+ * `runProgram({ commands })` accepts them alongside commands that declare
+ * their own `path` field.
+ *
+ * @since 1.2.0
+ */
+interface CommandEntry {
+  /**
+   * Command path used to place the command in the program tree.
+   */
+  readonly path: CommandPath;
+  /**
+   * The command definition.
+   */
+  readonly command: AnyCommand;
+}
 /**
  * A command found on disk.
  *
  * @since 1.1.0
  */
-interface DiscoveredCommand {
+interface DiscoveredCommand extends CommandEntry {
   /**
    * Command path derived from the module's relative path.
    */
@@ -47,6 +66,26 @@ interface DiscoveredCommand {
    */
   readonly command: AnyCommand;
 }
+/**
+ * A command loaded from a static module map.
+ *
+ * @since 1.2.0
+ */
+interface ModuleCommand extends CommandEntry {
+  /**
+   * Module map key used to derive the command path.
+   */
+  readonly modulePath: string;
+}
+/**
+ * Static module map accepted by {@link commandsFromModules}.
+ *
+ * This matches eager glob import APIs such as Vite's
+ * `import.meta.glob(..., { eager: true })`.
+ *
+ * @since 1.2.0
+ */
+type ModuleMap = Readonly<Record<string, unknown>>;
 /**
  * Options for {@link discoverCommands}.
  *
@@ -64,6 +103,45 @@ interface DiscoverCommandsOptions {
    * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
+}
+/**
+ * Options for {@link commandsFromModules}.
+ *
+ * @since 1.2.0
+ */
+interface CommandsFromModulesOptions {
+  /**
+   * Base module path to strip before deriving command paths.
+   *
+   * @default `"."`
+   */
+  readonly base?: string;
+  /**
+   * Module suffixes to include.  Compound suffixes such as `.cmd.ts` are
+   * supported.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   */
+  readonly entryFileName?: string | false;
 }
 /**
  * Runtime hint for {@link getDefaultExtensions}.
@@ -134,6 +212,14 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
    * File suffixes to include during discovery.
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
   /**
    * Static commands cannot be used together with `dir`.
    */
@@ -147,8 +233,11 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
 interface RunProgramStaticOptions extends RunProgramBaseOptions {
   /**
    * Commands to compose without file-system discovery.
+   *
+   * Pass commands that declare their own `path`, or command entries returned
+   * by {@link commandsFromModules}.
    */
-  readonly commands: readonly AnyStaticCommand[];
+  readonly commands: readonly (AnyStaticCommand | CommandEntry)[];
   /**
    * File-system discovery cannot be used together with `commands`.
    */
@@ -157,6 +246,10 @@ interface RunProgramStaticOptions extends RunProgramBaseOptions {
    * File suffixes are only used with file-system discovery.
    */
   readonly extensions?: never;
+  /**
+   * Entry file names are only used with file-system discovery.
+   */
+  readonly entryFileName?: never;
 }
 /**
  * Options for {@link runProgram}.
@@ -178,21 +271,39 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @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
  */
 declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
+/**
+ * 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
+ */
+declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand[];
 /**
  * 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.
+ * @throws {TypeError} If no commands are provided or command paths are
+ *         duplicated.
  * @since 1.1.0
  */
-declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
+declare function createProgramParser(commands: readonly CommandEntry[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
 /**
  * Discovers and runs a command program.
  *
@@ -223,4 +334,4 @@ interface ProgramHelpMetadata {
   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 };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-BAVhIzfI.js";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DyiVIMUh.js";
 import { RunOptions } from "@optique/run";
 import { Mode, Parser } from "@optique/core/parser";
 import { Message } from "@optique/core/message";
@@ -28,12 +28,31 @@ interface ProgramInvocation {
    */
   readonly handler: (value: unknown) => void | Promise<void>;
 }
+/**
+ * A command paired with its command path.
+ *
+ * `createProgramParser()` accepts command entries directly, and
+ * `runProgram({ commands })` accepts them alongside commands that declare
+ * their own `path` field.
+ *
+ * @since 1.2.0
+ */
+interface CommandEntry {
+  /**
+   * Command path used to place the command in the program tree.
+   */
+  readonly path: CommandPath;
+  /**
+   * The command definition.
+   */
+  readonly command: AnyCommand;
+}
 /**
  * A command found on disk.
  *
  * @since 1.1.0
  */
-interface DiscoveredCommand {
+interface DiscoveredCommand extends CommandEntry {
   /**
    * Command path derived from the module's relative path.
    */
@@ -47,6 +66,26 @@ interface DiscoveredCommand {
    */
   readonly command: AnyCommand;
 }
+/**
+ * A command loaded from a static module map.
+ *
+ * @since 1.2.0
+ */
+interface ModuleCommand extends CommandEntry {
+  /**
+   * Module map key used to derive the command path.
+   */
+  readonly modulePath: string;
+}
+/**
+ * Static module map accepted by {@link commandsFromModules}.
+ *
+ * This matches eager glob import APIs such as Vite's
+ * `import.meta.glob(..., { eager: true })`.
+ *
+ * @since 1.2.0
+ */
+type ModuleMap = Readonly<Record<string, unknown>>;
 /**
  * Options for {@link discoverCommands}.
  *
@@ -64,6 +103,45 @@ interface DiscoverCommandsOptions {
    * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
+}
+/**
+ * Options for {@link commandsFromModules}.
+ *
+ * @since 1.2.0
+ */
+interface CommandsFromModulesOptions {
+  /**
+   * Base module path to strip before deriving command paths.
+   *
+   * @default `"."`
+   */
+  readonly base?: string;
+  /**
+   * Module suffixes to include.  Compound suffixes such as `.cmd.ts` are
+   * supported.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   */
+  readonly entryFileName?: string | false;
 }
 /**
  * Runtime hint for {@link getDefaultExtensions}.
@@ -134,6 +212,14 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
    * File suffixes to include during discovery.
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
   /**
    * Static commands cannot be used together with `dir`.
    */
@@ -147,8 +233,11 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
 interface RunProgramStaticOptions extends RunProgramBaseOptions {
   /**
    * Commands to compose without file-system discovery.
+   *
+   * Pass commands that declare their own `path`, or command entries returned
+   * by {@link commandsFromModules}.
    */
-  readonly commands: readonly AnyStaticCommand[];
+  readonly commands: readonly (AnyStaticCommand | CommandEntry)[];
   /**
    * File-system discovery cannot be used together with `commands`.
    */
@@ -157,6 +246,10 @@ interface RunProgramStaticOptions extends RunProgramBaseOptions {
    * File suffixes are only used with file-system discovery.
    */
   readonly extensions?: never;
+  /**
+   * Entry file names are only used with file-system discovery.
+   */
+  readonly entryFileName?: never;
 }
 /**
  * Options for {@link runProgram}.
@@ -178,21 +271,39 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @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
  */
 declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
+/**
+ * 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
+ */
+declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand[];
 /**
  * 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.
+ * @throws {TypeError} If no commands are provided or command paths are
+ *         duplicated.
  * @since 1.1.0
  */
-declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
+declare function createProgramParser(commands: readonly CommandEntry[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
 /**
  * Discovers and runs a command program.
  *
@@ -223,4 +334,4 @@ interface ProgramHelpMetadata {
   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 };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };