@optique/discover 1.2.0-dev.2167 → 1.2.0-dev.2179

package/dist/index.d.cts

@@ -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}.
  *
@@ -75,6 +114,35 @@ interface DiscoverCommandsOptions {
    */
   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}.
  *
@@ -165,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`.
    */
@@ -205,6 +276,23 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @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.
  *
@@ -215,7 +303,7 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  *         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.
  *
@@ -246,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,8 +1,8 @@
-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 { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DrmNW0HO.js";
 import { Message } from "@optique/core/message";
 import { ProgramMetadata } from "@optique/core/program";
+import { RunOptions } from "@optique/run";
+import { Mode, Parser } from "@optique/core/parser";
 
 //#region src/index.d.ts
 
@@ -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}.
  *
@@ -75,6 +114,35 @@ interface DiscoverCommandsOptions {
    */
   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}.
  *
@@ -165,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`.
    */
@@ -205,6 +276,23 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @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.
  *
@@ -215,7 +303,7 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  *         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.
  *
@@ -246,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 };