@decaf-ts/utils 1.1.0 → 1.2.0

package/lib/types/cli/command.d.mts

@@ -0,0 +1,104 @@
+import { ParseArgsResult } from "../input/types.js";
+import { CommandOptions } from "./types.js";
+import { DefaultCommandValues } from "./constants.js";
+import { LoggedClass, Logger, LoggingConfig } from "@decaf-ts/logging";
+/**
+ * @class Command
+ * @abstract
+ * @template I - The type of input options for the command.
+ * @template R - The return type of the command execution.
+ * @memberOf module:utils
+ * @description Abstract base class for command implementation.
+ * @summary Provides a structure for creating command-line interface commands with input handling, logging, and execution flow.
+ *
+ * @param {string} name - The name of the command.
+ * @param {CommandOptions<I>} [inputs] - The input options for the command.
+ * @param {string[]} [requirements] - The list of required dependencies for the command.
+ */
+export declare abstract class Command<I, R> extends LoggedClass {
+    protected name: string;
+    protected inputs: CommandOptions<I>;
+    protected requirements: string[];
+    /**
+     * @static
+     * @description Static logger for the Command class.
+     * @type {Logger}
+     */
+    static log: Logger;
+    protected constructor(name: string, inputs?: CommandOptions<I>, requirements?: string[]);
+    /**
+     * @protected
+     * @async
+     * @description Checks if all required dependencies are present.
+     * @summary Retrieves the list of dependencies and compares it against the required dependencies for the command.
+     * @returns {Promise<void>} A promise that resolves when the check is complete.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Command
+     *   participant getDependencies
+     *   participant Set
+     *   Command->>getDependencies: Call
+     *   getDependencies-->>Command: Return {prod, dev, peer}
+     *   Command->>Set: Create Set from prod, dev, peer
+     *   Set-->>Command: Return unique dependencies
+     *   Command->>Command: Compare against requirements
+     *   alt Missing dependencies
+     *     Command->>Command: Add to missing list
+     *   end
+     *   Note over Command: If missing.length > 0, handle missing dependencies
+     */
+    protected checkRequirements(): Promise<void>;
+    /**
+     * @protected
+     * @description Provides help information for the command.
+     * @summary This method should be overridden in derived classes to provide specific help information.
+     * @param {ParseArgsResult} args - The parsed command-line arguments.
+     * @returns {void}
+     */
+    protected help(args: ParseArgsResult): void;
+    /**
+     * @protected
+     * @abstract
+     * @description Runs the command with the provided arguments.
+     * @summary This method should be implemented in derived classes to define the command's behavior.
+     * @param {ParseArgsResult} answers - The parsed command-line arguments.
+     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
+     */
+    protected abstract run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof I]: unknown;
+    }): Promise<R | string | void>;
+    /**
+     * @async
+     * @description Executes the command.
+     * @summary This method handles the overall execution flow of the command, including parsing arguments,
+     * setting up logging, checking for version or help requests, and running the command.
+     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Command
+     *   participant UserInput
+     *   participant Logging
+     *   participant getPackageVersion
+     *   participant printBanner
+     *   Command->>UserInput: parseArgs(inputs)
+     *   UserInput-->>Command: Return ParseArgsResult
+     *   Command->>Command: Process options
+     *   Command->>Logging: setConfig(options)
+     *   alt version requested
+     *     Command->>getPackageVersion: Call
+     *     getPackageVersion-->>Command: Return version
+     *   else help requested
+     *     Command->>Command: help(args)
+     *   else banner requested
+     *     Command->>printBanner: Call
+     *   end
+     *   Command->>Command: run(args)
+     *   alt error occurs
+     *     Command->>Command: Log error
+     *   end
+     *   Command-->>Command: Return result
+     */
+    execute(): Promise<R | string | void>;
+}

package/lib/types/cli/commands/build-scripts.d.cts

@@ -0,0 +1,148 @@
+import { Command } from "../command.cjs";
+import { CommandOptions } from "../types.cjs";
+import { DefaultCommandValues } from "../constants.cjs";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare module "@rollup/plugin-terser";
+export declare function parseList(input?: string | string[]): string[];
+export declare function packageToGlobal(name: string): string;
+export declare function getPackageDependencies(): string[];
+declare enum Modes {
+    CJS = "commonjs",
+    ESM = "es2022"
+}
+declare enum BuildMode {
+    BUILD = "build",
+    BUNDLE = "bundle",
+    ALL = "all"
+}
+declare const options: {
+    prod: {
+        type: string;
+        default: boolean;
+    };
+    dev: {
+        type: string;
+        default: boolean;
+    };
+    buildMode: {
+        type: string;
+        default: BuildMode;
+    };
+    includes: {
+        type: string;
+        default: string;
+    };
+    externals: {
+        type: string;
+        default: string;
+    };
+    docs: {
+        type: string;
+        default: boolean;
+    };
+    commands: {
+        type: string;
+        default: boolean;
+    };
+    entry: {
+        type: string;
+        default: string;
+    };
+    banner: {
+        type: string;
+        default: boolean;
+    };
+    validateNodeNext: {
+        type: string;
+        default: boolean;
+    };
+};
+/**
+ * @description A command-line script for building and bundling TypeScript projects.
+ * @summary This class provides a comprehensive build script that handles TypeScript compilation,
+ * bundling with Rollup, and documentation generation. It supports different build modes
+ * (development, production), module formats (CJS, ESM), and can be extended with custom
+ * configurations.
+ * @class BuildScripts
+ */
+export declare class BuildScripts extends Command<CommandOptions<typeof options>, void> {
+    private replacements;
+    private readonly pkgVersion;
+    private readonly pkgName;
+    constructor();
+    /**
+     * @description Patches files with version and package name.
+     * @summary This method reads all files in a directory, finds placeholders for version
+     * and package name, and replaces them with the actual values from package.json.
+     * @param {string} p - The path to the directory containing the files to patch.
+     */
+    patchFiles(p: string): void;
+    private reportDiagnostics;
+    private formatDiagnostics;
+    private readConfigFile;
+    private evalDiagnostics;
+    private preCheckDiagnostics;
+    private checkTsDiagnostics;
+    private buildTs;
+    private build;
+    private rewriteRelativeJsSpecifiersToCjs;
+    private buildCjsFromEsm;
+    private applyTsConfigProfile;
+    private checkNodeNextCompatibility;
+    private buildTypes;
+    private rewriteRelativeDeclarationSpecifiers;
+    private emitDualDeclarationFiles;
+    private updatePackageJsonDualTypeExports;
+    /**
+     * @description Copies assets to the build output directory.
+     * @summary This method checks for the existence of an 'assets' directory in the source
+     * and copies it to the appropriate build output directory (lib or dist).
+     * @param {Modes} mode - The build mode (CJS or ESM).
+     */
+    copyAssets(mode: Modes): void;
+    /**
+     * @description Bundles the project using Rollup.
+     * @summary This method configures and runs Rollup to bundle the project. It handles
+     * different module formats, development and production builds, and external dependencies.
+     * @param {Modes} mode - The module format (CJS or ESM).
+     * @param {boolean} isDev - Whether it's a development build.
+     * @param {boolean} isLib - Whether it's a library build.
+     * @param {string} [entryFile="src/index.ts"] - The entry file for the bundle.
+     * @param {string} [nameOverride=this.pkgName] - The name of the output bundle.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @param {string|string[]} [includeArg] - A list of dependencies to include.
+     * @returns {Promise<void>}
+     */
+    bundle(mode: Modes, isDev: boolean, isLib: boolean, entryFile?: string, nameOverride?: string, externalsArg?: string | string[], includeArg?: string | string[]): Promise<void>;
+    private buildByEnv;
+    /**
+     * @description Builds the project for development.
+     * @summary This method runs the build process with development-specific configurations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildDev(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Builds the project for production.
+     * @summary This method runs the build process with production-specific configurations,
+     * including minification and other optimizations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildProd(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Generates the project documentation.
+     * @summary This method uses JSDoc and other tools to generate HTML documentation for the project.
+     * It also patches the README.md file with version and package size information.
+     * @returns {Promise<void>}
+     */
+    buildDocs(): Promise<void>;
+    protected run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof typeof options]: unknown;
+    }): Promise<string | void | R>;
+}
+export {};

package/lib/types/cli/commands/build-scripts.d.mts

@@ -0,0 +1,148 @@
+import { Command } from "../command.js";
+import { CommandOptions } from "../types.js";
+import { DefaultCommandValues } from "../constants.js";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare module "@rollup/plugin-terser";
+export declare function parseList(input?: string | string[]): string[];
+export declare function packageToGlobal(name: string): string;
+export declare function getPackageDependencies(): string[];
+declare enum Modes {
+    CJS = "commonjs",
+    ESM = "es2022"
+}
+declare enum BuildMode {
+    BUILD = "build",
+    BUNDLE = "bundle",
+    ALL = "all"
+}
+declare const options: {
+    prod: {
+        type: string;
+        default: boolean;
+    };
+    dev: {
+        type: string;
+        default: boolean;
+    };
+    buildMode: {
+        type: string;
+        default: BuildMode;
+    };
+    includes: {
+        type: string;
+        default: string;
+    };
+    externals: {
+        type: string;
+        default: string;
+    };
+    docs: {
+        type: string;
+        default: boolean;
+    };
+    commands: {
+        type: string;
+        default: boolean;
+    };
+    entry: {
+        type: string;
+        default: string;
+    };
+    banner: {
+        type: string;
+        default: boolean;
+    };
+    validateNodeNext: {
+        type: string;
+        default: boolean;
+    };
+};
+/**
+ * @description A command-line script for building and bundling TypeScript projects.
+ * @summary This class provides a comprehensive build script that handles TypeScript compilation,
+ * bundling with Rollup, and documentation generation. It supports different build modes
+ * (development, production), module formats (CJS, ESM), and can be extended with custom
+ * configurations.
+ * @class BuildScripts
+ */
+export declare class BuildScripts extends Command<CommandOptions<typeof options>, void> {
+    private replacements;
+    private readonly pkgVersion;
+    private readonly pkgName;
+    constructor();
+    /**
+     * @description Patches files with version and package name.
+     * @summary This method reads all files in a directory, finds placeholders for version
+     * and package name, and replaces them with the actual values from package.json.
+     * @param {string} p - The path to the directory containing the files to patch.
+     */
+    patchFiles(p: string): void;
+    private reportDiagnostics;
+    private formatDiagnostics;
+    private readConfigFile;
+    private evalDiagnostics;
+    private preCheckDiagnostics;
+    private checkTsDiagnostics;
+    private buildTs;
+    private build;
+    private rewriteRelativeJsSpecifiersToCjs;
+    private buildCjsFromEsm;
+    private applyTsConfigProfile;
+    private checkNodeNextCompatibility;
+    private buildTypes;
+    private rewriteRelativeDeclarationSpecifiers;
+    private emitDualDeclarationFiles;
+    private updatePackageJsonDualTypeExports;
+    /**
+     * @description Copies assets to the build output directory.
+     * @summary This method checks for the existence of an 'assets' directory in the source
+     * and copies it to the appropriate build output directory (lib or dist).
+     * @param {Modes} mode - The build mode (CJS or ESM).
+     */
+    copyAssets(mode: Modes): void;
+    /**
+     * @description Bundles the project using Rollup.
+     * @summary This method configures and runs Rollup to bundle the project. It handles
+     * different module formats, development and production builds, and external dependencies.
+     * @param {Modes} mode - The module format (CJS or ESM).
+     * @param {boolean} isDev - Whether it's a development build.
+     * @param {boolean} isLib - Whether it's a library build.
+     * @param {string} [entryFile="src/index.ts"] - The entry file for the bundle.
+     * @param {string} [nameOverride=this.pkgName] - The name of the output bundle.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @param {string|string[]} [includeArg] - A list of dependencies to include.
+     * @returns {Promise<void>}
+     */
+    bundle(mode: Modes, isDev: boolean, isLib: boolean, entryFile?: string, nameOverride?: string, externalsArg?: string | string[], includeArg?: string | string[]): Promise<void>;
+    private buildByEnv;
+    /**
+     * @description Builds the project for development.
+     * @summary This method runs the build process with development-specific configurations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildDev(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Builds the project for production.
+     * @summary This method runs the build process with production-specific configurations,
+     * including minification and other optimizations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildProd(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Generates the project documentation.
+     * @summary This method uses JSDoc and other tools to generate HTML documentation for the project.
+     * It also patches the README.md file with version and package size information.
+     * @returns {Promise<void>}
+     */
+    buildDocs(): Promise<void>;
+    protected run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof typeof options]: unknown;
+    }): Promise<string | void | R>;
+}
+export {};

package/lib/types/cli/commands/build-scripts.d.ts

@@ -90,6 +90,9 @@ export declare class BuildScripts extends Command<CommandOptions<typeof options>
     private applyTsConfigProfile;
     private checkNodeNextCompatibility;
     private buildTypes;
+    private rewriteRelativeDeclarationSpecifiers;
+    private emitDualDeclarationFiles;
+    private updatePackageJsonDualTypeExports;
     /**
      * @description Copies assets to the build output directory.
      * @summary This method checks for the existence of an 'assets' directory in the source

package/lib/types/cli/commands/index.d.cts

@@ -0,0 +1,3 @@
+export * from "./build-scripts.cjs";
+export * from "./tag-release.cjs";
+export * from "./release-chain.cjs";

package/lib/types/cli/commands/index.d.mts

@@ -0,0 +1,3 @@
+export * from "./build-scripts.js";
+export * from "./tag-release.js";
+export * from "./release-chain.js";

package/lib/types/cli/commands/release-chain.d.cts

@@ -0,0 +1,62 @@
+import { Command } from "../command.cjs";
+import { CommandOptions } from "../types.cjs";
+import { DefaultCommandValues } from "../constants.cjs";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare const releaseChainArgs: {
+    meta: {
+        type: string;
+        default: string;
+    };
+    branch: {
+        type: string;
+        default: string;
+    };
+    current: {
+        type: string;
+        default: string;
+    };
+    package: {
+        type: string;
+        default: string;
+    };
+    token: {
+        type: string;
+        default: string;
+    };
+    submoduleFile: {
+        type: string;
+        default: string;
+    };
+    submodulePath: {
+        type: string;
+        default: string;
+    };
+    workflow: {
+        type: string;
+        default: string;
+    };
+    repo: {
+        type: string;
+        default: string;
+    };
+    ref: {
+        type: string;
+        default: string;
+    };
+    targetBase: {
+        type: string;
+        default: string;
+    };
+};
+type ReleaseChainAnswerMap = {
+    [K in keyof typeof releaseChainArgs]: unknown;
+};
+export declare class ReleaseChainCommand extends Command<CommandOptions<typeof releaseChainArgs>, void> {
+    constructor();
+    protected run(options: LoggingConfig & typeof DefaultCommandValues & ReleaseChainAnswerMap): Promise<void>;
+}
+export declare class ReleaseChainDispatchCommand extends Command<CommandOptions<typeof releaseChainArgs>, void> {
+    constructor();
+    protected run(options: LoggingConfig & typeof DefaultCommandValues & ReleaseChainAnswerMap): Promise<void>;
+}
+export {};

package/lib/types/cli/commands/release-chain.d.mts

@@ -0,0 +1,62 @@
+import { Command } from "../command.js";
+import { CommandOptions } from "../types.js";
+import { DefaultCommandValues } from "../constants.js";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare const releaseChainArgs: {
+    meta: {
+        type: string;
+        default: string;
+    };
+    branch: {
+        type: string;
+        default: string;
+    };
+    current: {
+        type: string;
+        default: string;
+    };
+    package: {
+        type: string;
+        default: string;
+    };
+    token: {
+        type: string;
+        default: string;
+    };
+    submoduleFile: {
+        type: string;
+        default: string;
+    };
+    submodulePath: {
+        type: string;
+        default: string;
+    };
+    workflow: {
+        type: string;
+        default: string;
+    };
+    repo: {
+        type: string;
+        default: string;
+    };
+    ref: {
+        type: string;
+        default: string;
+    };
+    targetBase: {
+        type: string;
+        default: string;
+    };
+};
+type ReleaseChainAnswerMap = {
+    [K in keyof typeof releaseChainArgs]: unknown;
+};
+export declare class ReleaseChainCommand extends Command<CommandOptions<typeof releaseChainArgs>, void> {
+    constructor();
+    protected run(options: LoggingConfig & typeof DefaultCommandValues & ReleaseChainAnswerMap): Promise<void>;
+}
+export declare class ReleaseChainDispatchCommand extends Command<CommandOptions<typeof releaseChainArgs>, void> {
+    constructor();
+    protected run(options: LoggingConfig & typeof DefaultCommandValues & ReleaseChainAnswerMap): Promise<void>;
+}
+export {};

package/lib/types/cli/commands/tag-release.d.cts

@@ -0,0 +1,105 @@
+import { Command } from "../command.cjs";
+import { DefaultCommandValues } from "../index.cjs";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare const options: {
+    ci: {
+        type: string;
+        default: boolean;
+    };
+    message: {
+        type: string;
+        short: string;
+    };
+    tag: {
+        type: string;
+        short: string;
+        default: undefined;
+    };
+};
+/**
+ * @class ReleaseScript
+ * @extends {Command}
+ * @cavegory scripts
+ * @description A command-line script for managing releases and version updates.
+ * @summary This script automates the process of creating and pushing new releases. It handles version updates,
+ * commit messages, and optionally publishes to NPM. The script supports semantic versioning and can work in both CI and non-CI environments.
+ *
+ * @param {Object} options - Configuration options for the script
+ * @param {boolean} options.ci - Whether the script is running in a CI environment (default: true)
+ * @param {string} options.message - The release message (short: 'm')
+ * @param {string} options.tag - The version tag to use (short: 't', default: undefined)
+ */
+export declare class ReleaseScript extends Command<typeof options, void> {
+    constructor();
+    /**
+     * @description Prepares the version for the release.
+     * @summary This method validates the provided tag or prompts the user for a new one if not provided or invalid.
+     * It also displays the latest git tags for reference.
+     * @param {string} tag - The version tag to prepare
+     * @returns {Promise<string>} The prepared version tag
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant R as ReleaseScript
+     *   participant T as TestVersion
+     *   participant U as UserInput
+     *   participant G as Git
+     *   R->>T: testVersion(tag)
+     *   alt tag is valid
+     *     T-->>R: return tag
+     *   else tag is invalid or not provided
+     *     R->>G: List latest git tags
+     *     R->>U: Prompt for new tag
+     *     U-->>R: return new tag
+     *   end
+     */
+    prepareVersion(tag?: string): Promise<string>;
+    /**
+     * @description Tests if the provided version is valid.
+     * @summary This method checks if the version is a valid semantic version or a predefined update type (PATCH, MINOR, MAJOR).
+     * @param {string} version - The version to test
+     * @returns {string | undefined} The validated version or undefined if invalid
+     */
+    testVersion(version: string): string | undefined;
+    /**
+     * @description Prepares the release message.
+     * @summary This method either returns the provided message or prompts the user for a new one if not provided.
+     * @param {string} [message] - The release message
+     * @returns {Promise<string>} The prepared release message
+     */
+    prepareMessage(message?: string): Promise<string>;
+    /**
+     * @description Runs the release script.
+     * @summary This method orchestrates the entire release process, including version preparation, message creation,
+     * git operations, and npm publishing (if not in CI environment).
+     * @param {ParseArgsResult} args - The parsed command-line arguments
+     * @returns {Promise<void>}
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant R as ReleaseScript
+     *   participant V as PrepareVersion
+     *   participant M as PrepareMessage
+     *   participant N as NPM
+     *   participant G as Git
+     *   participant U as UserInput
+     *   R->>V: prepareVersion(tag)
+     *   R->>M: prepareMessage(message)
+     *   R->>N: Run prepare-release script
+     *   R->>G: Check git status
+     *   alt changes exist
+     *     R->>U: Ask for confirmation
+     *     U-->>R: Confirm
+     *     R->>G: Add and commit changes
+     *   end
+     *   R->>N: Update npm version
+     *   R->>G: Push changes and tags
+     *   alt not CI environment
+     *     R->>N: Publish to npm
+     *   end
+     */
+    run(args: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof typeof options]: unknown;
+    }): Promise<void>;
+}
+export {};