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

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 };