@qlover/fe-release 3.0.0 → 3.1.2

package/dist/index.d.ts

@@ -5,26 +5,384 @@ import { CommitField } from 'gitlog';
 import { LoggerInterface } from '@qlover/logger';
 import { OptionValues } from 'commander';
 
+/**
+ * @module PluginTuple
+ * @description Type-safe plugin tuple creation and handling
+ *
+ * This module provides utilities for creating and handling tuples that
+ * represent plugin configurations. It ensures type safety when working
+ * with plugin constructors and their parameters.
+ *
+ * Core Features:
+ * - Type-safe plugin class handling
+ * - Constructor parameter inference
+ * - Plugin tuple creation
+ *
+ * @example Basic usage
+ * ```typescript
+ * class MyPlugin extends ScriptPlugin {
+ *   constructor(context: ScriptContext, config: { option: string }) {
+ *     super(context);
+ *   }
+ * }
+ *
+ * const pluginTuple = tuple(MyPlugin, { option: 'value' });
+ * // [MyPlugin, { option: 'value' }]
+ * ```
+ *
+ * @example Plugin name string
+ * ```typescript
+ * const pluginTuple = tuple('MyPlugin', { option: 'value' });
+ * // ['MyPlugin', { option: 'value' }]
+ * ```
+ */
+
+/**
+ * Plugin class constructor type
+ *
+ * Represents a constructor for a class that extends ScriptPlugin.
+ * Supports generic constructor arguments.
+ *
+ * @template T - Array type for constructor arguments
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends ScriptPlugin {
+ *   constructor(context: ScriptContext, config: { option: string }) {
+ *     super(context);
+ *   }
+ * }
+ *
+ * const PluginCtor: PluginClass = MyPlugin;
+ * ```
+ */
 type PluginClass<T extends unknown[] = any[]> = new (...args: T) => ScriptPlugin<ScriptContext<any>, ScriptPluginProps>;
 /**
- * Represents the constructor parameters for a specific Plugin class, excluding the first parameter.
- * This assumes that the constructor parameters are known and can be inferred.
+ * Plugin constructor parameters type
+ *
+ * Extracts the constructor parameter types for a plugin class,
+ * excluding the first parameter (context). Uses TypeScript's
+ * conditional types and inference to extract parameter types.
+ *
+ * @template T - Plugin class type
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends ScriptPlugin {
+ *   constructor(
+ *     context: ScriptContext,
+ *     config: { option: string },
+ *     extra: number
+ *   ) {
+ *     super(context);
+ *   }
+ * }
+ *
+ * // Type: [{ option: string }, number]
+ * type Params = PluginConstructorParams<typeof MyPlugin>;
+ * ```
  */
 type PluginConstructorParams<T extends PluginClass> = T extends new (first: any, ...args: infer P) => unknown ? P : never;
+/**
+ * Plugin configuration tuple type
+ *
+ * Represents a tuple containing a plugin class (or name) and its
+ * constructor arguments. Used for plugin registration and loading.
+ *
+ * @template T - Plugin class type
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends ScriptPlugin {
+ *   constructor(context: ScriptContext, config: { option: string }) {
+ *     super(context);
+ *   }
+ * }
+ *
+ * // Type: [typeof MyPlugin, { option: string }]
+ * type Tuple = PluginTuple<typeof MyPlugin>;
+ *
+ * // Type: [string, { option: string }]
+ * type StringTuple = PluginTuple<'MyPlugin'>;
+ * ```
+ */
 type PluginTuple<T extends PluginClass> = [
     T | string,
     ...PluginConstructorParams<T>
 ];
+/**
+ * Creates a type-safe plugin configuration tuple
+ *
+ * Helper function for creating tuples that represent plugin
+ * configurations with proper type inference for constructor
+ * arguments.
+ *
+ * @template T - Plugin class type
+ * @param plugin - Plugin class or name
+ * @param args - Plugin constructor arguments
+ * @returns Plugin configuration tuple
+ *
+ * @example Class-based plugin
+ * ```typescript
+ * class MyPlugin extends ScriptPlugin {
+ *   constructor(
+ *     context: ScriptContext,
+ *     config: { option: string },
+ *     extra: number
+ *   ) {
+ *     super(context);
+ *   }
+ * }
+ *
+ * const config = tuple(MyPlugin, { option: 'value' }, 42);
+ * // [MyPlugin, { option: 'value' }, 42]
+ * ```
+ *
+ * @example String-based plugin
+ * ```typescript
+ * const config = tuple('MyPlugin', { option: 'value' });
+ * // ['MyPlugin', { option: 'value' }]
+ * ```
+ */
 declare function tuple<T extends PluginClass>(plugin: T | string, ...args: PluginConstructorParams<T>): PluginTuple<T>;
 
+/**
+ * @module ReleaseTask
+ * @description Task orchestration for release process
+ *
+ * This module provides the core task orchestration for the release process,
+ * managing plugin loading, execution order, and context handling. It serves
+ * as the main entry point for executing release operations.
+ *
+ * Core Features:
+ * - Plugin management and execution
+ * - Release context initialization
+ * - Task execution control
+ * - Environment-based control
+ *
+ * Default Plugins:
+ * - Workspaces: Monorepo workspace management
+ * - Changelog: Version and changelog management
+ * - GithubPR: Pull request creation and management
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Initialize and execute
+ * const task = new ReleaseTask({
+ *   rootPath: '/path/to/project',
+ *   sourceBranch: 'main'
+ * });
+ *
+ * await task.exec();
+ * ```
+ *
+ * @example Custom plugins
+ * ```typescript
+ * import { tuple } from '@qlover/fe-release';
+ *
+ * // Add custom plugin
+ * class CustomPlugin extends ScriptPlugin {
+ *   async onExec() {
+ *     // Custom release logic
+ *   }
+ * }
+ *
+ * const task = new ReleaseTask({}, new AsyncExecutor(), [
+ *   tuple(CustomPlugin, { option: 'value' })
+ * ]);
+ *
+ * await task.exec();
+ * ```
+ *
+ * @example Environment control
+ * ```typescript
+ * // Skip release
+ * process.env.FE_RELEASE = 'false';
+ *
+ * const task = new ReleaseTask();
+ * try {
+ *   await task.exec();
+ * } catch (e) {
+ *   // Handle "Skip Release" error
+ * }
+ * ```
+ */
+
+/**
+ * Core task class for managing release operations
+ *
+ * Handles plugin orchestration, task execution, and context management
+ * for the release process. Supports both built-in and custom plugins.
+ *
+ * Features:
+ * - Plugin lifecycle management
+ * - Task execution control
+ * - Context initialization and access
+ * - Environment-based control
+ *
+ * @example Basic initialization
+ * ```typescript
+ * const task = new ReleaseTask({
+ *   rootPath: '/path/to/project'
+ * });
+ * ```
+ *
+ * @example Custom executor
+ * ```typescript
+ * const executor = new AsyncExecutor({
+ *   onError: (err) => console.error('Release failed:', err)
+ * });
+ *
+ * const task = new ReleaseTask({}, executor);
+ * ```
+ *
+ * @example Custom plugins
+ * ```typescript
+ * const task = new ReleaseTask(
+ *   {}, // options
+ *   new AsyncExecutor(),
+ *   [
+ *     tuple(CustomPlugin, { config: 'value' }),
+ *     ...innerTuples // include default plugins
+ *   ]
+ * );
+ * ```
+ */
 declare class ReleaseTask {
     private executor;
     private defaultTuples;
+    /**
+     * Release context instance
+     * @protected
+     */
     protected context: ReleaseContext;
+    /**
+     * Creates a new ReleaseTask instance
+     *
+     * Initializes the release context and sets up plugin configuration.
+     * Supports custom executors and plugin configurations.
+     *
+     * @param options - Release context configuration
+     * @param executor - Custom async executor (optional)
+     * @param defaultTuples - Plugin configuration tuples (optional)
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const task = new ReleaseTask({
+     *   rootPath: '/path/to/project',
+     *   sourceBranch: 'main'
+     * });
+     *
+     * // With custom executor and plugins
+     * const task = new ReleaseTask(
+     *   { rootPath: '/path/to/project' },
+     *   new AsyncExecutor(),
+     *   [tuple(CustomPlugin, { option: 'value' })]
+     * );
+     * ```
+     */
     constructor(options?: Partial<ReleaseContextOptions>, executor?: AsyncExecutor, defaultTuples?: PluginTuple<PluginClass>[]);
+    /**
+     * Gets the current release context
+     *
+     * @returns Release context instance
+     *
+     * @example
+     * ```typescript
+     * const task = new ReleaseTask();
+     * const context = task.getContext();
+     *
+     * console.log(context.releaseEnv);
+     * console.log(context.sourceBranch);
+     * ```
+     */
     getContext(): ReleaseContext;
+    /**
+     * Loads and configures plugins for the release task
+     *
+     * Combines default and external plugins, initializes them with
+     * the current context, and configures special cases like the
+     * Workspaces plugin.
+     *
+     * Plugin Loading Process:
+     * 1. Merge default and external plugins
+     * 2. Initialize plugins with context
+     * 3. Configure special plugins
+     * 4. Add plugins to executor
+     *
+     * @param externalTuples - Additional plugin configurations
+     * @returns Array of initialized plugins
+     *
+     * @example Basic usage
+     * ```typescript
+     * const task = new ReleaseTask();
+     * const plugins = await task.usePlugins();
+     * ```
+     *
+     * @example Custom plugins
+     * ```typescript
+     * const task = new ReleaseTask();
+     * const plugins = await task.usePlugins([
+     *   tuple(CustomPlugin, { option: 'value' })
+     * ]);
+     * ```
+     */
     usePlugins(externalTuples?: PluginTuple<PluginClass>[]): Promise<ScriptPlugin<ScriptContext<any>, ScriptPluginProps>[]>;
+    /**
+     * Executes the release task
+     *
+     * Internal method that runs the task through the executor.
+     * Preserves the context through the execution chain.
+     *
+     * @returns Execution result
+     * @internal
+     */
     run(): Promise<unknown>;
+    /**
+     * Main entry point for executing the release task
+     *
+     * Checks environment conditions, loads plugins, and executes
+     * the release process. Supports additional plugin configuration
+     * at execution time.
+     *
+     * Environment Control:
+     * - Checks FE_RELEASE environment variable
+     * - Skips release if FE_RELEASE=false
+     *
+     * @param externalTuples - Additional plugin configurations
+     * @returns Execution result
+     * @throws Error if release is skipped via environment variable
+     *
+     * @example Basic execution
+     * ```typescript
+     * const task = new ReleaseTask();
+     * await task.exec();
+     * ```
+     *
+     * @example With additional plugins
+     * ```typescript
+     * const task = new ReleaseTask();
+     * await task.exec([
+     *   tuple(CustomPlugin, { option: 'value' })
+     * ]);
+     * ```
+     *
+     * @example Environment control
+     * ```typescript
+     * // Skip release
+     * process.env.FE_RELEASE = 'false';
+     *
+     * const task = new ReleaseTask();
+     * try {
+     *   await task.exec();
+     * } catch (e) {
+     *   if (e.message === 'Skip Release') {
+     *     console.log('Release skipped via environment variable');
+     *   }
+     * }
+     * ```
+     */
     exec(externalTuples?: PluginTuple<PluginClass>[]): Promise<unknown>;
 }
 
@@ -152,19 +510,88 @@ type ReleaseParamsConfig = {
     PRBody?: string;
 };
 
+/**
+ * Base configuration for Git-related plugins
+ *
+ * Extends ScriptPluginProps with GitHub-specific configuration
+ * options for API access and timeouts.
+ *
+ * @example
+ * ```typescript
+ * const config: GitBaseProps = {
+ *   tokenRef: 'CUSTOM_TOKEN',
+ *   timeout: 5000
+ * };
+ * ```
+ */
 interface GitBaseProps extends ScriptPluginProps {
     /**
-     * The token for the GitHub API
+     * Environment variable name for GitHub API token
+     *
+     * The value of this environment variable will be used
+     * for GitHub API authentication.
      *
-     * @default `GITHUB_TOKEN`
+     * @default 'GITHUB_TOKEN'
+     *
+     * @example
+     * ```typescript
+     * process.env.CUSTOM_TOKEN = 'ghp_123...';
+     * const config = { tokenRef: 'CUSTOM_TOKEN' };
+     * ```
      */
     tokenRef?: string;
     /**
-     * The timeout for the GitHub API
+     * Timeout for GitHub API requests in milliseconds
+     *
+     * Controls how long to wait for GitHub API responses
+     * before timing out.
+     *
+     * @example
+     * ```typescript
+     * const config = { timeout: 5000 }; // 5 seconds
+     * ```
      */
     timeout?: number;
 }
 
+/**
+ * @module GithubPR
+ * @description GitHub Pull Request and Release Management
+ *
+ * This module provides functionality for managing GitHub pull requests
+ * and releases as part of the release process. It handles PR creation,
+ * release publishing, and changelog management.
+ *
+ * Core Features:
+ * - Pull request creation and management
+ * - Release publishing
+ * - Changelog integration
+ * - Tag management
+ * - Label management
+ * - Auto-merge support
+ *
+ * @example Basic usage
+ * ```typescript
+ * const plugin = new GithubPR(context, {
+ *   releasePR: true,
+ *   autoGenerate: true
+ * });
+ *
+ * await plugin.exec();
+ * ```
+ *
+ * @example Release publishing
+ * ```typescript
+ * const plugin = new GithubPR(context, {
+ *   releasePR: false,
+ *   makeLatest: true,
+ *   preRelease: false
+ * });
+ *
+ * await plugin.exec();
+ * ```
+ */
+
 interface GithubPRProps extends ReleaseParamsConfig, GitBaseProps {
     /**
      * Whether to dry run the creation of the pull request
@@ -251,28 +678,196 @@ interface GithubPRProps extends ReleaseParamsConfig, GitBaseProps {
     pushChangeLabels?: boolean;
 }
 
+/**
+ * @module FeReleaseTypes
+ * @description Type definitions for the fe-release framework
+ *
+ * This module provides TypeScript type definitions for the fe-release framework,
+ * including interfaces for release context, configuration, execution context,
+ * and various utility types.
+ *
+ * Type Categories:
+ * - Execution Context: Types for task execution and return values
+ * - Configuration: Types for release and workspace configuration
+ * - Plugin Types: Interfaces for GitHub PR and workspace plugins
+ * - Utility Types: Helper types like DeepPartial and PackageJson
+ *
+ * Design Considerations:
+ * - Type safety for plugin configuration
+ * - Extensible context interfaces
+ * - Backward compatibility support
+ * - Clear deprecation markers
+ * - Generic type constraints
+ */
+
+/**
+ * Extended execution context for release tasks
+ *
+ * Adds release-specific return value handling to the base executor context.
+ * Used to track and manage release task execution results.
+ *
+ * @example
+ * ```typescript
+ * const context: ExecutorReleaseContext = {
+ *   returnValue: { githubToken: 'token123' },
+ *   // ... other executor context properties
+ * };
+ * ```
+ */
 interface ExecutorReleaseContext extends ExecutorContext<ReleaseContext> {
     returnValue: ReleaseReturnValue;
 }
+/**
+ * Return value type for release tasks
+ *
+ * Defines the structure of data returned from release task execution.
+ * Includes GitHub token and allows for additional custom properties.
+ *
+ * @example
+ * ```typescript
+ * const returnValue: ReleaseReturnValue = {
+ *   githubToken: 'github_pat_123',
+ *   customData: { version: '1.0.0' }
+ * };
+ * ```
+ */
 type ReleaseReturnValue = {
     githubToken?: string;
     [key: string]: unknown;
 };
+/**
+ * Utility type for creating deep partial types
+ *
+ * Makes all properties in T optional recursively, useful for
+ * partial configuration objects and type-safe updates.
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   deep: {
+ *     nested: {
+ *       value: string;
+ *     }
+ *   }
+ * }
+ *
+ * const partial: DeepPartial<Config> = {
+ *   deep: {
+ *     nested: {
+ *       // All properties optional
+ *     }
+ *   }
+ * };
+ * ```
+ */
 type DeepPartial<T> = {
     [P in keyof T]?: DeepPartial<T[P]>;
 };
+/**
+ * Configuration interface for release process
+ *
+ * Extends shared script configuration with release-specific
+ * settings for GitHub PR and workspace management.
+ *
+ * @example
+ * ```typescript
+ * const config: ReleaseConfig = {
+ *   githubPR: {
+ *     owner: 'org',
+ *     repo: 'repo',
+ *     base: 'main'
+ *   },
+ *   workspaces: {
+ *     packages: ['packages/*']
+ *   }
+ * };
+ * ```
+ */
 interface ReleaseConfig extends ScriptSharedInterface {
     githubPR?: GithubPRProps;
     workspaces?: WorkspacesProps;
 }
+/**
+ * Options interface for release context
+ *
+ * Extends script context interface with release-specific configuration.
+ * Uses generic type parameter for custom configuration extensions.
+ *
+ * @example
+ * ```typescript
+ * interface CustomConfig extends ReleaseConfig {
+ *   custom: {
+ *     feature: boolean;
+ *   }
+ * }
+ *
+ * const options: ReleaseContextOptions<CustomConfig> = {
+ *   custom: {
+ *     feature: true
+ *   }
+ * };
+ * ```
+ */
 interface ReleaseContextOptions$1<T extends ReleaseConfig = ReleaseConfig> extends ScriptContextInterface<T> {
 }
+/**
+ * Configuration for a single execution step
+ *
+ * Defines a labeled, optionally enabled task with async execution.
+ * Used for creating structured, trackable release steps.
+ *
+ * @example
+ * ```typescript
+ * const step: StepOption<string> = {
+ *   label: 'Update version',
+ *   enabled: true,
+ *   task: async () => {
+ *     // Version update logic
+ *     return 'Version updated to 1.0.0';
+ *   }
+ * };
+ * ```
+ */
 type StepOption<T> = {
     label: string;
     enabled?: boolean;
     task: () => Promise<T>;
 };
+/**
+ * Type alias for package.json structure
+ *
+ * Represents the structure of a package.json file with flexible
+ * key-value pairs. Used for package metadata handling.
+ *
+ * @example
+ * ```typescript
+ * const pkg: PackageJson = {
+ *   name: 'my-package',
+ *   version: '1.0.0',
+ *   dependencies: {
+ *     // ...
+ *   }
+ * };
+ * ```
+ */
 type PackageJson = Record<string, unknown>;
+/**
+ * Context interface for template processing
+ *
+ * Combines release context options with workspace values and
+ * adds template-specific properties. Includes deprecated fields
+ * with migration guidance.
+ *
+ * @example
+ * ```typescript
+ * const context: TemplateContext = {
+ *   publishPath: './dist',
+ *   env: 'production',      // Deprecated
+ *   branch: 'main',         // Deprecated
+ *   // ... other properties from ReleaseContextOptions
+ * };
+ * ```
+ */
 interface TemplateContext extends ReleaseContextOptions$1, WorkspaceValue {
     publishPath: string;
     /**
@@ -285,6 +880,57 @@ interface TemplateContext extends ReleaseContextOptions$1, WorkspaceValue {
     branch: string;
 }
 
+/**
+ * @module ReleaseContext
+ * @description Core context management for release operations
+ *
+ * This module provides the central context management for release operations,
+ * handling configuration, environment variables, workspace management, and
+ * package information. It extends the base ScriptContext with release-specific
+ * functionality.
+ *
+ * Core Features:
+ * - Environment variable management
+ * - Workspace configuration
+ * - Package.json access
+ * - Template context generation
+ * - Changeset CLI integration
+ *
+ * @example Basic usage
+ * ```typescript
+ * const context = new ReleaseContext('my-package', {
+ *   rootPath: '/path/to/project',
+ *   sourceBranch: 'main',
+ *   releaseEnv: 'production'
+ * });
+ *
+ * // Access package info
+ * const version = context.getPkg('version');
+ *
+ * // Generate template context
+ * const templateData = context.getTemplateContext();
+ * ```
+ *
+ * @example Workspace management
+ * ```typescript
+ * // Set workspace configuration
+ * context.setWorkspaces([{
+ *   name: 'package-a',
+ *   version: '1.0.0',
+ *   path: 'packages/a'
+ * }]);
+ *
+ * // Access workspace info
+ * const currentWorkspace = context.workspace;
+ * ```
+ *
+ * @example Changeset integration
+ * ```typescript
+ * // Run changeset commands
+ * await context.runChangesetsCli('version', ['--snapshot', 'alpha']);
+ * ```
+ */
+
 interface ReleaseContextOptions extends ScriptContextInterface<ReleaseContextConfig> {
 }
 interface ReleaseContextConfig extends FeReleaseConfig, ScriptSharedInterface {
@@ -324,19 +970,271 @@ interface ReleaseContextConfig extends FeReleaseConfig, ScriptSharedInterface {
      */
     currentBranch?: string;
 }
+/**
+ * Core context class for release operations
+ *
+ * Manages release-specific configuration, environment variables,
+ * workspace settings, and provides utilities for release operations.
+ *
+ * Features:
+ * - Automatic environment detection
+ * - Source branch management
+ * - Workspace configuration
+ * - Package.json access
+ * - Template context generation
+ * - Changeset CLI integration
+ *
+ * @example Basic initialization
+ * ```typescript
+ * const context = new ReleaseContext('my-package', {
+ *   rootPath: '/path/to/project',
+ *   sourceBranch: 'main'
+ * });
+ * ```
+ *
+ * @example Environment configuration
+ * ```typescript
+ * // With environment variables
+ * process.env.FE_RELEASE_ENV = 'staging';
+ * process.env.FE_RELEASE_BRANCH = 'develop';
+ *
+ * const context = new ReleaseContext('my-package', {});
+ * // context.releaseEnv === 'staging'
+ * // context.sourceBranch === 'develop'
+ * ```
+ */
 declare class ReleaseContext extends ScriptContext<ReleaseContextConfig> {
+    /**
+     * Creates a new ReleaseContext instance
+     *
+     * Initializes the context with provided options and sets up
+     * default values for required configuration:
+     * - rootPath: Defaults to current working directory
+     * - sourceBranch: Uses environment variables or default
+     * - releaseEnv: Uses environment variables or 'development'
+     *
+     * Environment Variable Priority:
+     * - sourceBranch: FE_RELEASE_BRANCH > FE_RELEASE_SOURCE_BRANCH > DEFAULT_SOURCE_BRANCH
+     * - releaseEnv: FE_RELEASE_ENV > NODE_ENV > 'development'
+     *
+     * @param name - Unique identifier for this release context
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * const context = new ReleaseContext('web-app', {
+     *   rootPath: '/projects/web-app',
+     *   sourceBranch: 'main',
+     *   releaseEnv: 'production'
+     * });
+     * ```
+     */
     constructor(name: string, options: Partial<ReleaseContextOptions>);
+    /**
+     * Gets the root path of the project
+     *
+     * @returns Absolute path to project root
+     *
+     * @example
+     * ```typescript
+     * const root = context.rootPath;
+     * // '/path/to/project'
+     * ```
+     */
     get rootPath(): string;
+    /**
+     * Gets the source branch for the release
+     *
+     * @returns Branch name to use as source
+     *
+     * @example
+     * ```typescript
+     * const branch = context.sourceBranch;
+     * // 'main' or custom branch name
+     * ```
+     */
     get sourceBranch(): string;
+    /**
+     * Gets the release environment
+     *
+     * @returns Environment name (e.g., 'development', 'production')
+     *
+     * @example
+     * ```typescript
+     * const env = context.releaseEnv;
+     * // 'development' or custom environment
+     * ```
+     */
     get releaseEnv(): string;
+    /**
+     * Gets all configured workspaces
+     *
+     * @returns Array of workspace configurations or undefined
+     *
+     * @example
+     * ```typescript
+     * const allWorkspaces = context.workspaces;
+     * // [{ name: 'pkg-a', version: '1.0.0', ... }]
+     * ```
+     */
     get workspaces(): WorkspaceValue[] | undefined;
+    /**
+     * Gets the current active workspace
+     *
+     * @returns Current workspace configuration or undefined
+     *
+     * @example
+     * ```typescript
+     * const current = context.workspace;
+     * // { name: 'pkg-a', version: '1.0.0', ... }
+     * ```
+     */
     get workspace(): WorkspaceValue | undefined;
+    /**
+     * Sets the workspace configurations
+     *
+     * Updates the workspace list while preserving other workspace settings
+     *
+     * @param workspaces - Array of workspace configurations
+     *
+     * @example
+     * ```typescript
+     * context.setWorkspaces([{
+     *   name: 'pkg-a',
+     *   version: '1.0.0',
+     *   path: 'packages/a'
+     * }]);
+     * ```
+     */
     setWorkspaces(workspaces: WorkspaceValue[]): void;
+    /**
+     * Gets package.json data for the current workspace
+     *
+     * Provides type-safe access to package.json fields with optional
+     * path and default value support.
+     *
+     * @param key - Optional dot-notation path to specific field
+     * @param defaultValue - Default value if field not found
+     * @returns Package data of type T
+     * @throws Error if package.json not found
+     *
+     * @example Basic usage
+     * ```typescript
+     * // Get entire package.json
+     * const pkg = context.getPkg();
+     *
+     * // Get specific field
+     * const version = context.getPkg<string>('version');
+     *
+     * // Get nested field with default
+     * const script = context.getPkg<string>(
+     *   'scripts.build',
+     *   'echo "No build script"'
+     * );
+     * ```
+     */
     getPkg<T>(key?: string, defaultValue?: T): T;
+    /**
+     * Generates template context for string interpolation
+     *
+     * Combines context options, workspace data, and specific paths
+     * for use in template processing. Includes deprecated fields
+     * for backward compatibility.
+     *
+     * @returns Combined template context
+     *
+     * @example
+     * ```typescript
+     * const context = releaseContext.getTemplateContext();
+     * // {
+     * //   publishPath: 'packages/my-pkg',
+     * //   env: 'production',        // deprecated
+     * //   branch: 'main',          // deprecated
+     * //   releaseEnv: 'production', // use this instead
+     * //   sourceBranch: 'main',    // use this instead
+     * //   ...other options
+     * // }
+     * ```
+     */
     getTemplateContext(): TemplateContext;
+    /**
+     * Executes changeset CLI commands
+     *
+     * Automatically detects and uses appropriate package manager
+     * (pnpm or npx) to run changeset commands.
+     *
+     * @param name - Changeset command name
+     * @param args - Optional command arguments
+     * @returns Command output
+     *
+     * @example Version bump
+     * ```typescript
+     * // Bump version with snapshot
+     * await context.runChangesetsCli('version', ['--snapshot', 'alpha']);
+     *
+     * // Create new changeset
+     * await context.runChangesetsCli('add');
+     *
+     * // Status check
+     * await context.runChangesetsCli('status');
+     * ```
+     */
     runChangesetsCli(name: string, args?: string[]): Promise<string>;
 }
 
+/**
+ * @module ReleaseLabel
+ * @description Release label management and file change detection
+ *
+ * This module provides utilities for managing release labels and detecting
+ * which packages have changed based on file paths. It supports custom
+ * comparison logic and label formatting.
+ *
+ * Core Features:
+ * - File change detection
+ * - Package path matching
+ * - Label generation
+ * - Custom comparison logic
+ *
+ * @example Basic usage
+ * ```typescript
+ * const label = new ReleaseLabel({
+ *   changePackagesLabel: 'changed:${name}',
+ *   packagesDirectories: ['packages/a', 'packages/b']
+ * });
+ *
+ * // Find changed packages
+ * const changed = label.pick(['packages/a/src/index.ts']);
+ * // ['packages/a']
+ *
+ * // Generate labels
+ * const labels = label.toChangeLabels(changed);
+ * // ['changed:packages/a']
+ * ```
+ *
+ * @example Custom comparison
+ * ```typescript
+ * const label = new ReleaseLabel({
+ *   changePackagesLabel: 'changed:${name}',
+ *   packagesDirectories: ['packages/a'],
+ *   compare: (file, pkg) => file.includes(pkg)
+ * });
+ *
+ * const changed = label.pick(['src/packages/a/index.ts']);
+ * // ['packages/a']
+ * ```
+ */
+/**
+ * Function type for custom file path comparison
+ *
+ * Used to determine if a changed file belongs to a package.
+ * Default implementation checks if the file path starts with
+ * the package path.
+ *
+ * @param changedFilePath - Path of the changed file
+ * @param packagePath - Path of the package to check against
+ * @returns True if the file belongs to the package
+ */
 type ReleaseLabelCompare = (changedFilePath: string, packagePath: string) => boolean;
 interface ReleaseLabelOptions {
     /**
@@ -349,43 +1247,334 @@ interface ReleaseLabelOptions {
     packagesDirectories: string[];
     compare?: ReleaseLabelCompare;
 }
+/**
+ * Core class for managing release labels and change detection
+ *
+ * Provides utilities for detecting changed packages and generating
+ * appropriate labels. Supports custom comparison logic and label
+ * formatting.
+ *
+ * Features:
+ * - File change detection
+ * - Package path matching
+ * - Label generation
+ * - Custom comparison logic
+ *
+ * @example Basic usage
+ * ```typescript
+ * const label = new ReleaseLabel({
+ *   changePackagesLabel: 'changed:${name}',
+ *   packagesDirectories: ['packages/a', 'packages/b']
+ * });
+ *
+ * // Find changed packages
+ * const changed = label.pick(['packages/a/src/index.ts']);
+ *
+ * // Generate labels
+ * const labels = label.toChangeLabels(changed);
+ * ```
+ *
+ * @example Custom comparison
+ * ```typescript
+ * const label = new ReleaseLabel({
+ *   changePackagesLabel: 'changed:${name}',
+ *   packagesDirectories: ['packages/a'],
+ *   compare: (file, pkg) => file.includes(pkg)
+ * });
+ *
+ * const changed = label.pick(['src/packages/a/index.ts']);
+ * ```
+ */
 declare class ReleaseLabel {
     private readonly options;
+    /**
+     * Creates a new ReleaseLabel instance
+     *
+     * @param options - Configuration options for label management
+     *
+     * @example
+     * ```typescript
+     * const label = new ReleaseLabel({
+     *   // Label template with ${name} placeholder
+     *   changePackagesLabel: 'changed:${name}',
+     *
+     *   // Package directories to monitor
+     *   packagesDirectories: ['packages/a', 'packages/b'],
+     *
+     *   // Optional custom comparison logic
+     *   compare: (file, pkg) => file.includes(pkg)
+     * });
+     * ```
+     */
     constructor(options: ReleaseLabelOptions);
+    /**
+     * Compares a changed file path against a package path
+     *
+     * Uses custom comparison function if provided, otherwise
+     * checks if the file path starts with the package path.
+     *
+     * @param changedFilePath - Path of the changed file
+     * @param packagePath - Path of the package to check against
+     * @returns True if the file belongs to the package
+     *
+     * @example
+     * ```typescript
+     * // Default comparison
+     * label.compare('packages/a/src/index.ts', 'packages/a');
+     * // true
+     *
+     * // Custom comparison
+     * const label = new ReleaseLabel({
+     *   ...options,
+     *   compare: (file, pkg) => file.includes(pkg)
+     * });
+     * label.compare('src/packages/a/index.ts', 'packages/a');
+     * // true
+     * ```
+     */
     compare(changedFilePath: string, packagePath: string): boolean;
+    /**
+     * Generates a change label for a single package
+     *
+     * Replaces ${name} placeholder in the label template with
+     * the package path.
+     *
+     * @param packagePath - Path of the package
+     * @param label - Optional custom label template
+     * @returns Formatted change label
+     *
+     * @example
+     * ```typescript
+     * // Default label template
+     * label.toChangeLabel('packages/a');
+     * // 'changed:packages/a'
+     *
+     * // Custom label template
+     * label.toChangeLabel('packages/a', 'modified:${name}');
+     * // 'modified:packages/a'
+     * ```
+     */
     toChangeLabel(packagePath: string, label?: string): string;
+    /**
+     * Generates change labels for multiple packages
+     *
+     * Maps each package path to a formatted change label.
+     *
+     * @param packages - Array of package paths
+     * @param label - Optional custom label template
+     * @returns Array of formatted change labels
+     *
+     * @example
+     * ```typescript
+     * // Default label template
+     * label.toChangeLabels(['packages/a', 'packages/b']);
+     * // ['changed:packages/a', 'changed:packages/b']
+     *
+     * // Custom label template
+     * label.toChangeLabels(
+     *   ['packages/a', 'packages/b'],
+     *   'modified:${name}'
+     * );
+     * // ['modified:packages/a', 'modified:packages/b']
+     * ```
+     */
     toChangeLabels(packages: string[], label?: string): string[];
+    /**
+     * Identifies packages affected by changed files
+     *
+     * Checks each changed file against package paths to determine
+     * which packages have been modified.
+     *
+     * @param changedFiles - Array or Set of changed file paths
+     * @param packages - Optional array of package paths to check
+     * @returns Array of affected package paths
+     *
+     * @example
+     * ```typescript
+     * // Check against default packages
+     * label.pick(['packages/a/src/index.ts']);
+     * // ['packages/a']
+     *
+     * // Check specific packages
+     * label.pick(
+     *   ['packages/a/index.ts', 'packages/b/test.ts'],
+     *   ['packages/a', 'packages/c']
+     * );
+     * // ['packages/a']
+     *
+     * // Using Set of files
+     * label.pick(new Set(['packages/a/index.ts']));
+     * // ['packages/a']
+     * ```
+     */
     pick(changedFiles: Array<string> | Set<string>, packages?: string[]): string[];
 }
 
+/**
+ * @module ChangeLog
+ * @description Core interfaces for changelog generation
+ *
+ * This module provides the core interfaces and types for generating
+ * changelogs from Git commit history. It includes types for commit
+ * parsing, formatting, and changelog generation.
+ *
+ * Core Components:
+ * - Commit data structures
+ * - Changelog formatting
+ * - Git log options
+ * - Changelog generation
+ *
+ * @example Basic usage
+ * ```typescript
+ * class MyChangeLog implements ChangeLogInterface {
+ *   async getCommits(options?: GitChangelogOptions): Promise<CommitValue[]> {
+ *     // Implementation
+ *   }
+ * }
+ *
+ * class MyFormatter implements ChangelogFormatter {
+ *   format(commits: CommitValue[]): string[] {
+ *     // Implementation
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Base commit type mapping Git commit fields
+ *
+ * Maps all available Git commit fields to optional string values.
+ * Uses the CommitField type from gitlog package to ensure type safety.
+ *
+ * Available fields include:
+ * - hash: Full commit hash
+ * - abbrevHash: Abbreviated commit hash
+ * - subject: Commit message subject
+ * - authorName: Author's name
+ * - authorDate: Author date
+ * - And many more from gitlog.CommitField
+ *
+ * @example
+ * ```typescript
+ * const commit: BaseCommit = {
+ *   hash: 'abc123def456',
+ *   abbrevHash: 'abc123',
+ *   subject: 'feat: new feature',
+ *   authorName: 'John Doe',
+ *   authorDate: '2023-01-01'
+ * };
+ * ```
+ */
 type BaseCommit = {
     [key in CommitField]: string | undefined;
 };
+/**
+ * Configuration options for changelog generation
+ *
+ * Provides comprehensive options for controlling how changelogs
+ * are generated from Git history, including commit range selection,
+ * formatting, and filtering.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const options: GitChangelogOptions = {
+ *   from: 'v1.0.0',
+ *   to: 'v2.0.0',
+ *   directory: 'packages/my-pkg',
+ *   noMerges: true
+ * };
+ * ```
+ *
+ * @example Custom formatting
+ * ```typescript
+ * const options: GitChangelogOptions = {
+ *   types: [
+ *     { type: 'feat', section: '### Features' },
+ *     { type: 'fix', section: '### Bug Fixes' }
+ *   ],
+ *   formatTemplate: '* ${commitlint.message} ${prLink}',
+ *   commitBody: true
+ * };
+ * ```
+ */
 interface GitChangelogOptions {
     /**
-     * start tag
+     * Starting tag or commit reference
+     *
+     * Defines the start point for collecting commits.
+     * Can be a tag name, commit hash, or branch name.
+     *
+     * @example
+     * ```typescript
+     * from: 'v1.0.0'  // Start from v1.0.0 tag
+     * from: 'abc123'  // Start from specific commit
+     * ```
      */
     from?: string;
     /**
-     * end tag
+     * Ending tag or commit reference
+     *
+     * Defines the end point for collecting commits.
+     * Can be a tag name, commit hash, or branch name.
+     *
+     * @example
+     * ```typescript
+     * to: 'v2.0.0'    // End at v2.0.0 tag
+     * to: 'main'      // End at main branch
+     * ```
      */
     to?: string;
     /**
-     * log directory
+     * Directory to collect commits from
+     *
+     * Limits commit collection to changes in specified directory.
+     * Useful for monorepo package-specific changelogs.
+     *
+     * @example
+     * ```typescript
+     * directory: 'packages/my-pkg'  // Only changes in this directory
+     * ```
      */
     directory?: string;
     /**
-     * gitlog default fields
+     * Git commit fields to include
+     *
+     * Specifies which Git commit fields to retrieve.
      * @default ["abbrevHash", "hash", "subject", "authorName", "authorDate"]
+     *
+     * @example
+     * ```typescript
+     * fields: ['hash', 'subject', 'authorName']
+     * ```
      */
     fields?: CommitField[];
     /**
-     * not include merge commit
+     * Whether to exclude merge commits
+     *
+     * When true, merge commits are filtered out from the changelog.
      * @default true
+     *
+     * @example
+     * ```typescript
+     * noMerges: true  // Exclude merge commits
+     * noMerges: false // Include merge commits
+     * ```
      */
     noMerges?: boolean;
     /**
-     * custom commit type
+     * Commit type configurations
+     *
+     * Defines how different commit types should be handled and
+     * formatted in the changelog.
+     *
+     * @example
+     * ```typescript
+     * types: [
+     *   { type: 'feat', section: '### Features' },
+     *   { type: 'fix', section: '### Bug Fixes' },
+     *   { type: 'chore', hidden: true }  // Skip chore commits
+     * ]
+     * ```
      */
     types?: {
         type: string;
@@ -393,115 +1582,1172 @@ interface GitChangelogOptions {
         hidden?: boolean;
     }[];
     /**
-     * custom commit format
+     * Template for formatting commit entries
      *
-     * - support `CommitValue` properties
-     * - add scopeHeader, commitLink, prLink
+     * Supports variables from CommitValue properties and adds:
+     * - ${scopeHeader}: Formatted scope
+     * - ${commitLink}: Commit hash link
+     * - ${prLink}: PR number link
      *
      * @default '\n- ${scopeHeader} ${commitlint.message} ${commitLink} ${prLink}'
+     *
+     * @example
+     * ```typescript
+     * formatTemplate: '* ${commitlint.message} (${commitLink})'
+     * ```
      */
     formatTemplate?: string;
     /**
-     * whether to include commit body
+     * Whether to include commit message body
+     *
+     * When true, includes the full commit message body
+     * in the changelog entry.
+     *
      * @since 2.3.0
      * @default false
+     *
+     * @example
+     * ```typescript
+     * commitBody: true  // Include full commit message
+     * ```
      */
     commitBody?: boolean;
 }
+/**
+ * Parsed conventional commit data
+ *
+ * Represents a commit message parsed according to the
+ * conventional commit specification.
+ *
+ * Format: type(scope): message
+ *
+ * @example
+ * ```typescript
+ * const commit: Commitlint = {
+ *   type: 'feat',
+ *   scope: 'api',
+ *   message: 'add new endpoint',
+ *   body: 'Adds support for new API endpoint\n\nBREAKING CHANGE: API format changed'
+ * };
+ * ```
+ */
 interface Commitlint {
+    /** Commit type (e.g., 'feat', 'fix') */
     type?: string;
+    /** Commit scope (e.g., 'api', 'core') */
     scope?: string;
+    /** Main commit message */
     message: string;
     /**
-     * commit body, remove repeat title
+     * Commit message body with title removed
      * @since 2.3.0
      */
     body?: string;
 }
+/**
+ * Complete commit information
+ *
+ * Combines Git commit data, parsed conventional commit info,
+ * and PR metadata into a single value object.
+ *
+ * @example
+ * ```typescript
+ * const commit: CommitValue = {
+ *   base: {
+ *     hash: 'abc123',
+ *     subject: 'feat(api): new endpoint (#123)'
+ *   },
+ *   commitlint: {
+ *     type: 'feat',
+ *     scope: 'api',
+ *     message: 'new endpoint'
+ *   },
+ *   commits: [],
+ *   prNumber: '123'
+ * };
+ * ```
+ */
 interface CommitValue {
-    /**
-     * git log base info
-     */
+    /** Raw Git commit information */
     base: BaseCommit;
-    /**
-     * parsed commitlint info
-     */
+    /** Parsed conventional commit data */
     commitlint: Commitlint;
-    /**
-     * parsed commitlint info
-     */
+    /** Sub-commits (for merge commits) */
     commits: CommitValue[];
-    /**
-     * pr number
-     */
+    /** Associated pull request number */
     prNumber?: string;
 }
+/**
+ * Interface for changelog formatting
+ *
+ * Defines the contract for classes that format commit data
+ * into changelog entries.
+ *
+ * @example
+ * ```typescript
+ * class MarkdownFormatter implements ChangelogFormatter {
+ *   format(commits: CommitValue[]): string[] {
+ *     return commits.map(commit =>
+ *       `- ${commit.commitlint.message} (#${commit.prNumber})`
+ *     );
+ *   }
+ * }
+ * ```
+ */
 interface ChangelogFormatter {
+    /**
+     * Formats commits into changelog entries
+     *
+     * @param commits - Array of commits to format
+     * @param options - Optional formatting options
+     * @returns Array of formatted changelog lines
+     */
     format<Opt extends GitChangelogOptions>(commits: unknown[], options?: Opt): string[];
 }
+/**
+ * Interface for changelog generation
+ *
+ * Defines the contract for classes that generate changelogs
+ * from Git history.
+ *
+ * @example
+ * ```typescript
+ * class GitChangelog implements ChangeLogInterface {
+ *   async getCommits(options?: GitChangelogOptions): Promise<CommitValue[]> {
+ *     // Get commits from Git and parse them
+ *     const commits = await gitlog(options);
+ *     return commits.map(commit => ({
+ *       base: commit,
+ *       commitlint: parseCommit(commit.subject),
+ *       commits: []
+ *     }));
+ *   }
+ * }
+ * ```
+ */
 interface ChangeLogInterface {
+    /**
+     * Retrieves and parses Git commits
+     *
+     * @param options - Optional Git log options
+     * @returns Promise resolving to array of parsed commits
+     */
     getCommits(options?: GitChangelogOptions): Promise<CommitValue[]>;
 }
 
+/**
+ * @module GitChangelog
+ * @description Git-based changelog generation and commit parsing
+ *
+ * This module provides functionality for generating changelogs from Git
+ * history, parsing commit messages according to conventional commit format,
+ * and managing commit metadata.
+ *
+ * Core Features:
+ * - Git log retrieval
+ * - Conventional commit parsing
+ * - Changelog generation
+ * - Tag resolution
+ * - PR number extraction
+ *
+ * @example Basic usage
+ * ```typescript
+ * const changelog = new GitChangelog({
+ *   shell,
+ *   logger,
+ *   directory: 'packages/my-pkg'
+ * });
+ *
+ * // Get commits between tags
+ * const commits = await changelog.getCommits({
+ *   from: 'v1.0.0',
+ *   to: 'v2.0.0'
+ * });
+ * ```
+ *
+ * @example Commit parsing
+ * ```typescript
+ * const changelog = new GitChangelog({ shell, logger });
+ *
+ * // Parse conventional commit
+ * const commit = changelog.parseCommitlint(
+ *   'feat(api): add new endpoint',
+ *   'Detailed description\n\nBREAKING CHANGE: API format changed'
+ * );
+ * // {
+ * //   type: 'feat',
+ * //   scope: 'api',
+ * //   message: 'add new endpoint',
+ * //   body: '  Detailed description\n\n  BREAKING CHANGE: API format changed'
+ * // }
+ * ```
+ */
+
+/**
+ * Complete list of available Git commit fields
+ *
+ * These fields can be used when retrieving commit information
+ * to specify which data should be included in the output.
+ *
+ * @example
+ * ```typescript
+ * const commits = await changelog.getGitLog({
+ *   fields: CHANGELOG_ALL_FIELDS
+ * });
+ * ```
+ */
 declare const CHANGELOG_ALL_FIELDS: CommitField[];
 interface GitChangelogProps extends GitChangelogOptions {
     shell: ShellInterface;
     logger: LoggerInterface;
 }
+/**
+ * Core class for Git-based changelog generation
+ *
+ * Provides functionality for retrieving and parsing Git commit history,
+ * generating changelogs, and managing commit metadata. Implements the
+ * ChangeLogInterface for standardized changelog generation.
+ *
+ * Features:
+ * - Git log retrieval with flexible options
+ * - Conventional commit parsing
+ * - Tag resolution and validation
+ * - PR number extraction
+ * - Commit body formatting
+ *
+ * @example Basic usage
+ * ```typescript
+ * const changelog = new GitChangelog({
+ *   shell,
+ *   logger,
+ *   directory: 'packages/my-pkg'
+ * });
+ *
+ * // Get commits with parsed metadata
+ * const commits = await changelog.getCommits({
+ *   from: 'v1.0.0',
+ *   to: 'v2.0.0',
+ *   noMerges: true
+ * });
+ * ```
+ *
+ * @example Custom commit parsing
+ * ```typescript
+ * const changelog = new GitChangelog({ shell, logger });
+ *
+ * // Create commit value from hash and message
+ * const commit = changelog.toCommitValue(
+ *   'abc1234',
+ *   'feat(api): new endpoint (#123)'
+ * );
+ * // {
+ * //   base: { hash: 'abc1234', ... },
+ * //   commitlint: { type: 'feat', scope: 'api', ... },
+ * //   prNumber: '123'
+ * // }
+ * ```
+ */
 declare class GitChangelog implements ChangeLogInterface {
     protected options: GitChangelogProps;
+    /**
+     * Creates a new GitChangelog instance
+     *
+     * @param options - Configuration options including shell and logger
+     *
+     * @example
+     * ```typescript
+     * const changelog = new GitChangelog({
+     *   shell: new Shell(),
+     *   logger: new Logger(),
+     *   directory: 'packages/my-pkg',
+     *   noMerges: true
+     * });
+     * ```
+     */
     constructor(options: GitChangelogProps);
     /**
-     * Get the git log
+     * Retrieves Git commit history with specified options
+     *
+     * Fetches commit information between specified tags or commits,
+     * with support for filtering and field selection.
+     *
+     * @param options - Configuration options for Git log retrieval
+     * @returns Array of commit objects with requested fields
      *
-     * @param options
-     * @returns
+     * @example Basic usage
+     * ```typescript
+     * const commits = await changelog.getGitLog({
+     *   from: 'v1.0.0',
+     *   to: 'v2.0.0',
+     *   directory: 'packages/my-pkg',
+     *   noMerges: true
+     * });
+     * ```
+     *
+     * @example Custom fields
+     * ```typescript
+     * const commits = await changelog.getGitLog({
+     *   fields: ['hash', 'subject', 'authorName'],
+     *   directory: 'src'
+     * });
+     * ```
      */
     getGitLog(options?: GitChangelogOptions): Promise<BaseCommit[]>;
+    /**
+     * Retrieves and parses Git commits with metadata
+     *
+     * Gets commit history and enhances it with parsed conventional
+     * commit information and PR metadata.
+     *
+     * @param options - Configuration options for Git log retrieval
+     * @returns Array of enhanced commit objects with parsed metadata
+     *
+     * @example Basic usage
+     * ```typescript
+     * const commits = await changelog.getCommits({
+     *   from: 'v1.0.0',
+     *   to: 'v2.0.0'
+     * });
+     * // [
+     * //   {
+     * //     base: { hash: '...', subject: '...' },
+     * //     commitlint: { type: 'feat', scope: 'api', ... },
+     * //     commits: []
+     * //   }
+     * // ]
+     * ```
+     *
+     * @example Filtered commits
+     * ```typescript
+     * const commits = await changelog.getCommits({
+     *   directory: 'packages/my-pkg',
+     *   noMerges: true
+     * });
+     * ```
+     */
     getCommits(options?: GitChangelogOptions): Promise<CommitValue[]>;
+    /**
+     * Creates a base commit object from message and optional data
+     *
+     * Utility method to create a standardized commit object with
+     * basic metadata. Used internally for commit value creation.
+     *
+     * @param message - Commit message
+     * @param target - Optional additional commit data
+     * @returns Base commit object
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * const commit = changelog.createBaseCommit(
+     *   'feat: new feature',
+     *   {
+     *     hash: 'abc123',
+     *     authorName: 'John Doe'
+     *   }
+     * );
+     * ```
+     */
     protected createBaseCommit(message: string, target?: Partial<BaseCommit>): BaseCommit;
     /**
-     * Tabify the body
+     * Indents each line of a text block
+     *
+     * Adds specified number of spaces to the start of each line
+     * in a multi-line string. Used for formatting commit body text.
      *
      * @since 2.3.2
-     * @param body
-     * @param size
-     * @returns
+     * @param body - Text to indent
+     * @param size - Number of spaces to add (default: 2)
+     * @returns Indented text
+     *
+     * @example
+     * ```typescript
+     * const text = changelog.tabify(
+     *   'Line 1\nLine 2\nLine 3',
+     *   4
+     * );
+     * // '    Line 1\n    Line 2\n    Line 3'
+     * ```
      */
     tabify(body: string, size?: number): string;
+    /**
+     * Parses a commit message into conventional commit format
+     *
+     * Extracts type, scope, message, and body from a commit message
+     * following the conventional commit specification.
+     *
+     * Format: type(scope): message
+     *
+     * @param subject - Commit subject line
+     * @param rawBody - Full commit message body
+     * @returns Parsed conventional commit data
+     *
+     * @example Basic commit
+     * ```typescript
+     * const commit = changelog.parseCommitlint(
+     *   'feat(api): add new endpoint'
+     * );
+     * // {
+     * //   type: 'feat',
+     * //   scope: 'api',
+     * //   message: 'add new endpoint'
+     * // }
+     * ```
+     *
+     * @example With body
+     * ```typescript
+     * const commit = changelog.parseCommitlint(
+     *   'fix(core): memory leak',
+     *   'Fixed memory leak in core module\n\nBREAKING CHANGE: API changed'
+     * );
+     * // {
+     * //   type: 'fix',
+     * //   scope: 'core',
+     * //   message: 'memory leak',
+     * //   body: '  Fixed memory leak in core module\n\n  BREAKING CHANGE: API changed'
+     * // }
+     * ```
+     */
     parseCommitlint(subject: string, rawBody?: string): Commitlint;
+    /**
+     * Creates a complete commit value object from hash and message
+     *
+     * Combines commit hash, parsed conventional commit data, and
+     * PR information into a single commit value object.
+     *
+     * @param hash - Commit hash
+     * @param message - Full commit message
+     * @returns Complete commit value object
+     *
+     * @example Basic commit
+     * ```typescript
+     * const commit = changelog.toCommitValue(
+     *   'abc123',
+     *   'feat(api): new endpoint'
+     * );
+     * // {
+     * //   base: {
+     * //     hash: 'abc123',
+     * //     abbrevHash: 'abc123',
+     * //     subject: 'feat(api): new endpoint'
+     * //   },
+     * //   commitlint: {
+     * //     type: 'feat',
+     * //     scope: 'api',
+     * //     message: 'new endpoint'
+     * //   },
+     * //   commits: []
+     * // }
+     * ```
+     *
+     * @example PR commit
+     * ```typescript
+     * const commit = changelog.toCommitValue(
+     *   'def456',
+     *   'fix(core): memory leak (#123)'
+     * );
+     * // {
+     * //   base: { hash: 'def456', ... },
+     * //   commitlint: { type: 'fix', ... },
+     * //   commits: [],
+     * //   prNumber: '123'
+     * // }
+     * ```
+     */
     toCommitValue(hash: string, message: string): CommitValue;
+    /**
+     * Resolves a Git tag or reference to a valid commit reference
+     *
+     * Attempts to resolve a tag name to a valid Git reference.
+     * Falls back to root commit or HEAD if tag doesn't exist.
+     *
+     * @param tag - Tag name to resolve
+     * @param fallback - Fallback value ('root' or 'HEAD')
+     * @returns Resolved Git reference
+     * @protected
+     *
+     * @example Basic tag resolution
+     * ```typescript
+     * const ref = await changelog.resolveTag('v1.0.0');
+     * // 'v1.0.0' if tag exists
+     * // 'HEAD' if tag doesn't exist
+     * ```
+     *
+     * @example Root commit fallback
+     * ```typescript
+     * const ref = await changelog.resolveTag(
+     *   'non-existent-tag',
+     *   'root'
+     * );
+     * // First commit hash if tag doesn't exist
+     * ```
+     */
     protected resolveTag(tag?: string, fallback?: string): Promise<string>;
 }
 
+/**
+ * @module GitChangelogFormatter
+ * @description Formats Git commits into readable changelog entries
+ *
+ * This module provides functionality for formatting Git commits into
+ * a structured changelog format, with support for conventional commits,
+ * PR links, and custom templates.
+ *
+ * Core Features:
+ * - Conventional commit formatting
+ * - PR and commit linking
+ * - Type-based grouping
+ * - Custom templates
+ * - Markdown formatting
+ *
+ * @example Basic usage
+ * ```typescript
+ * const formatter = new GitChangelogFormatter({
+ *   shell,
+ *   repoUrl: 'https://github.com/org/repo',
+ *   types: [
+ *     { type: 'feat', section: '### Features' },
+ *     { type: 'fix', section: '### Bug Fixes' }
+ *   ]
+ * });
+ *
+ * const changelog = formatter.format(commits);
+ * // ### Features
+ * // - **api:** new endpoint ([abc123](https://github.com/org/repo/commit/abc123)) (#123)
+ * //
+ * // ### Bug Fixes
+ * // - **core:** fix memory leak ([def456](https://github.com/org/repo/commit/def456))
+ * ```
+ *
+ * @example Custom template
+ * ```typescript
+ * const formatter = new GitChangelogFormatter({
+ *   shell,
+ *   formatTemplate: '* ${commitlint.message} ${prLink}',
+ *   types: [{ type: 'feat', section: '## New' }]
+ * });
+ *
+ * const changelog = formatter.format(commits);
+ * // ## New
+ * // * add user authentication (#124)
+ * ```
+ */
+
+/**
+ * Configuration options for changelog formatting
+ *
+ * Extends GitChangelogOptions with repository URL support
+ * for generating links to commits and pull requests.
+ */
 interface Options extends GitChangelogOptions {
+    /**
+     * Repository URL for generating links
+     *
+     * @example 'https://github.com/org/repo'
+     */
     repoUrl?: string;
 }
+/**
+ * Core class for formatting Git commits into changelog entries
+ *
+ * Implements ChangelogFormatter interface to provide standardized
+ * changelog generation with support for:
+ * - Conventional commit formatting
+ * - Type-based grouping
+ * - PR and commit linking
+ * - Custom templates
+ * - Markdown formatting
+ *
+ * @example Basic usage
+ * ```typescript
+ * const formatter = new GitChangelogFormatter({
+ *   shell,
+ *   repoUrl: 'https://github.com/org/repo',
+ *   types: [
+ *     { type: 'feat', section: '### Features' },
+ *     { type: 'fix', section: '### Bug Fixes' }
+ *   ]
+ * });
+ *
+ * const changelog = formatter.format(commits);
+ * ```
+ *
+ * @example Custom formatting
+ * ```typescript
+ * const formatter = new GitChangelogFormatter({
+ *   shell,
+ *   formatTemplate: '* ${commitlint.message}',
+ *   types: [{ type: 'feat', section: '## New' }],
+ *   commitBody: true // Include commit body
+ * });
+ * ```
+ */
 declare class GitChangelogFormatter implements ChangelogFormatter {
     protected options: Options & {
         shell: ShellInterface;
     };
+    /**
+     * Creates a new GitChangelogFormatter instance
+     *
+     * @param options - Configuration options including shell interface
+     *
+     * @example
+     * ```typescript
+     * const formatter = new GitChangelogFormatter({
+     *   shell: new Shell(),
+     *   repoUrl: 'https://github.com/org/repo',
+     *   types: [
+     *     { type: 'feat', section: '### Features' }
+     *   ],
+     *   formatTemplate: '- ${commitlint.message}'
+     * });
+     * ```
+     */
     constructor(options: Options & {
         shell: ShellInterface;
     });
+    /**
+     * Formats an array of commits into changelog entries
+     *
+     * Groups commits by type and formats them according to the
+     * configured template and options. Supports commit body
+     * inclusion and type-based sections.
+     *
+     * @param commits - Array of commit values to format
+     * @param options - Optional formatting options
+     * @returns Array of formatted changelog lines
+     *
+     * @example Basic formatting
+     * ```typescript
+     * const changelog = formatter.format([
+     *   {
+     *     base: { hash: 'abc123' },
+     *     commitlint: {
+     *       type: 'feat',
+     *       scope: 'api',
+     *       message: 'new endpoint'
+     *     }
+     *   }
+     * ]);
+     * // [
+     * //   '### Features',
+     * //   '- **api:** new endpoint ([abc123](...))'
+     * // ]
+     * ```
+     *
+     * @example With commit body
+     * ```typescript
+     * const changelog = formatter.format(
+     *   [{
+     *     commitlint: {
+     *       type: 'fix',
+     *       message: 'memory leak',
+     *       body: 'Fixed memory allocation\nAdded cleanup'
+     *     }
+     *   }],
+     *   { commitBody: true }
+     * );
+     * // [
+     * //   '### Bug Fixes',
+     * //   '- memory leak',
+     * //   '  Fixed memory allocation',
+     * //   '  Added cleanup'
+     * // ]
+     * ```
+     */
     format(commits: CommitValue[], options?: Options): string[];
+    /**
+     * Formats a single commit into a changelog entry
+     *
+     * Applies the configured template to a commit, including
+     * scope formatting, PR links, and commit hash links.
+     *
+     * @param commit - Commit value to format
+     * @param options - Optional formatting options
+     * @returns Formatted changelog entry
+     *
+     * @example Basic formatting
+     * ```typescript
+     * const entry = formatter.formatCommit({
+     *   base: { hash: 'abc123' },
+     *   commitlint: {
+     *     type: 'feat',
+     *     scope: 'api',
+     *     message: 'new endpoint'
+     *   }
+     * });
+     * // '- **api:** new endpoint ([abc123](...))'
+     * ```
+     *
+     * @example With PR number
+     * ```typescript
+     * const entry = formatter.formatCommit({
+     *   base: { hash: 'def456' },
+     *   commitlint: {
+     *     message: 'fix bug'
+     *   },
+     *   prNumber: '123'
+     * });
+     * // '- fix bug ([def456](...)) (#123)'
+     * ```
+     */
     formatCommit(commit: CommitValue, options?: Options): string;
+    /**
+     * Formats a target string as a Markdown link
+     *
+     * Creates a Markdown-formatted link with optional URL.
+     * If no URL is provided, formats as a plain reference.
+     *
+     * @param target - Text to display
+     * @param url - Optional URL for the link
+     * @returns Formatted Markdown link
+     *
+     * @example With URL
+     * ```typescript
+     * const link = formatter.foramtLink('abc123', 'https://github.com/org/repo/commit/abc123');
+     * // '([abc123](https://github.com/org/repo/commit/abc123))'
+     * ```
+     *
+     * @example Without URL
+     * ```typescript
+     * const link = formatter.foramtLink('abc123');
+     * // '(abc123)'
+     * ```
+     */
     foramtLink(target: string, url?: string): string;
+    /**
+     * Formats a commit hash as a Markdown link
+     *
+     * @deprecated Use foramtLink instead
+     * @param target - Commit hash to display
+     * @param url - Optional URL to the commit
+     * @returns Formatted Markdown link
+     *
+     * @example
+     * ```typescript
+     * const link = formatter.formatCommitLink(
+     *   'abc123',
+     *   'https://github.com/org/repo/commit/abc123'
+     * );
+     * // '([abc123](https://github.com/org/repo/commit/abc123))'
+     * ```
+     */
     formatCommitLink(target: string, url?: string): string;
+    /**
+     * Formats a commit scope in Markdown
+     *
+     * Wraps the scope in bold syntax and adds a colon.
+     *
+     * @param scope - Scope to format
+     * @returns Formatted scope in Markdown
+     *
+     * @example
+     * ```typescript
+     * const scope = formatter.formatScope('api');
+     * // '**api:**'
+     * ```
+     */
     formatScope(scope: string): string;
 }
 
+/**
+ * @module GithubChangelog
+ * @description GitHub-specific changelog generation
+ *
+ * This module extends the base changelog functionality with
+ * GitHub-specific features like PR linking, commit filtering
+ * by directory, and workspace-aware changelog generation.
+ *
+ * Core Features:
+ * - PR-aware commit gathering
+ * - Directory-based filtering
+ * - GitHub link generation
+ * - Workspace changelog transformation
+ * - Markdown formatting
+ *
+ * @example Basic usage
+ * ```typescript
+ * const changelog = new GithubChangelog({
+ *   shell,
+ *   logger,
+ *   githubRootPath: 'https://github.com/org/repo'
+ * }, githubManager);
+ *
+ * const commits = await changelog.getFullCommit({
+ *   from: 'v1.0.0',
+ *   directory: 'packages/pkg-a'
+ * });
+ * ```
+ *
+ * @example Workspace transformation
+ * ```typescript
+ * const workspaces = await changelog.transformWorkspace(
+ *   [{ name: 'pkg-a', path: 'packages/a' }],
+ *   context
+ * );
+ * // Adds formatted changelog to each workspace
+ * ```
+ */
+
 interface GithubChangelogProps extends GitChangelogProps {
     mergePRcommit?: boolean;
     githubRootPath?: string;
 }
 
+/**
+ * @module PluginLoader
+ * @description Dynamic plugin loading and instantiation
+ *
+ * This module provides utilities for dynamically loading and instantiating
+ * plugins from various sources (ESM imports, file paths, package names).
+ * It supports concurrent loading with limits and fallback mechanisms.
+ *
+ * Core Features:
+ * - Dynamic ESM imports
+ * - Fallback to CommonJS require
+ * - Concurrent loading with limits
+ * - Plugin instantiation with context
+ *
+ * @example Basic plugin loading
+ * ```typescript
+ * // Load plugin by name
+ * const [name, Plugin] = await load('@scope/my-plugin');
+ *
+ * // Load and instantiate multiple plugins
+ * const plugins = await loaderPluginsFromPluginTuples(
+ *   context,
+ *   [
+ *     tuple(MyPlugin, { option: 'value' }),
+ *     tuple('@scope/my-plugin', { option: 'value' })
+ *   ]
+ * );
+ * ```
+ *
+ * @example Custom concurrency
+ * ```typescript
+ * // Load plugins with custom concurrency limit
+ * const plugins = await loaderPluginsFromPluginTuples(
+ *   context,
+ *   pluginTuples,
+ *   3 // Max 3 concurrent loads
+ * );
+ * ```
+ */
+
+/**
+ * Dynamically loads a plugin module
+ *
+ * Attempts to load a plugin using multiple strategies:
+ * 1. Direct ESM import
+ * 2. Import from current working directory
+ * 3. Fallback to CommonJS require.resolve
+ *
+ * @template T - Plugin module type
+ * @param pluginName - Plugin name or path to load
+ * @returns Promise resolving to [plugin name, plugin module]
+ * @throws If plugin cannot be loaded by any method
+ *
+ * @example Package import
+ * ```typescript
+ * const [name, Plugin] = await load('@scope/my-plugin');
+ * const instance = new Plugin(context);
+ * ```
+ *
+ * @example Local file import
+ * ```typescript
+ * const [name, Plugin] = await load('./plugins/MyPlugin');
+ * const instance = new Plugin(context);
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * try {
+ *   const [name, Plugin] = await load('non-existent');
+ * } catch (error) {
+ *   console.error('Failed to load plugin:', error);
+ * }
+ * ```
+ */
 declare function load<T>(pluginName: string): Promise<[string, T]>;
+/**
+ * Loads and instantiates multiple plugins concurrently
+ *
+ * Takes an array of plugin tuples and creates plugin instances
+ * with the provided context. Supports both class-based and
+ * string-based plugin specifications.
+ *
+ * Features:
+ * - Concurrent loading with configurable limit
+ * - Mixed plugin types (class/string)
+ * - Automatic context injection
+ * - Type-safe instantiation
+ *
+ * @template T - Plugin instance type
+ * @param context - Release context for plugin initialization
+ * @param pluginsTuples - Array of plugin configuration tuples
+ * @param maxLimit - Maximum concurrent plugin loads (default: 5)
+ * @returns Promise resolving to array of plugin instances
+ *
+ * @example Basic usage
+ * ```typescript
+ * const plugins = await loaderPluginsFromPluginTuples(
+ *   context,
+ *   [
+ *     tuple(MyPlugin, { option: 'value' }),
+ *     tuple('@scope/plugin', { option: 'value' })
+ *   ]
+ * );
+ * ```
+ *
+ * @example Custom concurrency
+ * ```typescript
+ * const plugins = await loaderPluginsFromPluginTuples(
+ *   context,
+ *   pluginTuples,
+ *   3  // Load max 3 plugins at once
+ * );
+ * ```
+ *
+ * @example Type-safe loading
+ * ```typescript
+ * interface MyPlugin extends ScriptPlugin {
+ *   customMethod(): void;
+ * }
+ *
+ * const plugins = await loaderPluginsFromPluginTuples<MyPlugin>(
+ *   context,
+ *   pluginTuples
+ * );
+ *
+ * plugins.forEach(plugin => plugin.customMethod());
+ * ```
+ */
 declare function loaderPluginsFromPluginTuples<T extends ScriptPlugin<ScriptContext<any>, ScriptPluginProps>>(context: ReleaseContext, pluginsTuples: PluginTuple<PluginClass>[], maxLimit?: number): Promise<T[]>;
 
+/**
+ * @module Factory
+ * @description Type-safe factory function for class and function instantiation
+ *
+ * This module provides a flexible factory function that can handle both
+ * class constructors and factory functions with proper type inference.
+ *
+ * Core Features:
+ * - Type-safe instantiation
+ * - Support for both classes and functions
+ * - Argument type inference
+ * - Runtime constructor detection
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Class-based
+ * class MyClass {
+ *   constructor(name: string, value: number) {}
+ * }
+ *
+ * const instance = factory(MyClass, 'test', 42);
+ *
+ * // Function-based
+ * function createObject(config: { option: string }) {
+ *   return { ...config };
+ * }
+ *
+ * const object = factory(createObject, { option: 'value' });
+ * ```
+ */
+/**
+ * Combined type for class constructors and factory functions
+ *
+ * Represents either a class constructor or a factory function
+ * with proper typing for arguments and return value.
+ *
+ * @template T - Return type
+ * @template Args - Tuple type for arguments
+ *
+ * @example Class constructor
+ * ```typescript
+ * class MyClass {
+ *   constructor(name: string) {}
+ * }
+ *
+ * const ctor: ConstructorType<MyClass, [string]> = MyClass;
+ * ```
+ *
+ * @example Factory function
+ * ```typescript
+ * interface Config {
+ *   option: string;
+ * }
+ *
+ * const factory: ConstructorType<Config, [string]> =
+ *   (option: string) => ({ option });
+ * ```
+ */
 type ConstructorType<T, Args extends unknown[]> = (new (...args: Args) => T) | ((...args: Args) => T);
+/**
+ * Creates instances from constructors or factory functions
+ *
+ * A flexible factory function that can handle both class constructors
+ * and factory functions. It automatically detects the type at runtime
+ * and uses the appropriate instantiation method.
+ *
+ * Features:
+ * - Automatic constructor detection
+ * - Type-safe argument passing
+ * - Support for both classes and functions
+ * - Generic type inference
+ *
+ * @template T - Return type
+ * @template Args - Tuple type for arguments
+ * @param Constructor - Class constructor or factory function
+ * @param args - Arguments to pass to constructor/function
+ * @returns Instance of type T
+ *
+ * @example Class instantiation
+ * ```typescript
+ * class Logger {
+ *   constructor(name: string, level: string) {
+ *     // Implementation
+ *   }
+ * }
+ *
+ * const logger = factory(Logger, 'main', 'debug');
+ * ```
+ *
+ * @example Factory function
+ * ```typescript
+ * interface Config {
+ *   name: string;
+ *   options: Record<string, unknown>;
+ * }
+ *
+ * function createConfig(name: string, options = {}): Config {
+ *   return { name, options };
+ * }
+ *
+ * const config = factory(createConfig, 'myConfig', { debug: true });
+ * ```
+ *
+ * @example Generic types
+ * ```typescript
+ * class Container<T> {
+ *   constructor(value: T) {
+ *     // Implementation
+ *   }
+ * }
+ *
+ * const container = factory<Container<string>, [string]>(
+ *   Container,
+ *   'value'
+ * );
+ * ```
+ */
 declare function factory<T, Args extends unknown[]>(Constructor: ConstructorType<T, Args>, ...args: Args): T;
 
+/**
+ * @module CommanderArgs
+ * @description Command-line argument processing utilities
+ *
+ * This module provides utilities for processing and transforming
+ * command-line arguments from Commander.js into structured objects.
+ * It supports dot notation for nested properties and common prefix
+ * grouping.
+ *
+ * Core Features:
+ * - Dot notation support
+ * - Common prefix grouping
+ * - Deep object creation
+ * - Type-safe processing
+ *
+ * @example Basic usage
+ * ```typescript
+ * const args = {
+ *   verbose: true,
+ *   'config.port': 3000,
+ *   'config.host': 'localhost'
+ * };
+ *
+ * const processed = reduceOptions(args);
+ * // {
+ * //   verbose: true,
+ * //   config: {
+ * //     port: 3000,
+ * //     host: 'localhost'
+ * //   }
+ * // }
+ * ```
+ *
+ * @example With common prefix
+ * ```typescript
+ * const args = {
+ *   verbose: true,
+ *   port: 3000
+ * };
+ *
+ * const processed = reduceOptions(args, 'options');
+ * // {
+ * //   options: {
+ * //     verbose: true,
+ * //     port: 3000
+ * //   }
+ * // }
+ * ```
+ */
+
+/**
+ * Processes Commander.js options into a structured object
+ *
+ * Takes raw options from Commander.js and transforms them into a
+ * structured object, handling dot notation for nested properties
+ * and optional common prefix grouping.
+ *
+ * Features:
+ * - Dot notation parsing (e.g., 'config.port' → { config: { port: value } })
+ * - Common prefix grouping (e.g., { port: 3000 } → { common: { port: 3000 } })
+ * - Deep object creation with lodash/set
+ * - Preserves value types
+ *
+ * @param opts - Raw options from Commander.js
+ * @param commonKey - Optional prefix for non-nested properties
+ * @returns Processed options object
+ *
+ * @example Basic dot notation
+ * ```typescript
+ * const args = {
+ *   'server.port': 3000,
+ *   'server.host': 'localhost',
+ *   verbose: true
+ * };
+ *
+ * const result = reduceOptions(args);
+ * // {
+ * //   server: {
+ * //     port: 3000,
+ * //     host: 'localhost'
+ * //   },
+ * //   verbose: true
+ * // }
+ * ```
+ *
+ * @example With common prefix
+ * ```typescript
+ * const args = {
+ *   'config.debug': true,
+ *   port: 3000,
+ *   host: 'localhost'
+ * };
+ *
+ * const result = reduceOptions(args, 'server');
+ * // {
+ * //   config: {
+ * //     debug: true
+ * //   },
+ * //   server: {
+ * //     port: 3000,
+ * //     host: 'localhost'
+ * //   }
+ * // }
+ * ```
+ */
 declare function reduceOptions(opts: OptionValues, commonKey?: string): OptionValues;
 
 export { CHANGELOG_ALL_FIELDS, type ConstructorType, type DeepPartial, type ExecutorReleaseContext, GitChangelog, GitChangelogFormatter, type GitChangelogProps, type GithubChangelogProps, type Options, type PackageJson, type PluginClass, type PluginConstructorParams, type PluginTuple, type ReleaseConfig, ReleaseContext, type ReleaseContextOptions$1 as ReleaseContextOptions, ReleaseLabel, type ReleaseLabelCompare, type ReleaseLabelOptions, type ReleaseReturnValue, ReleaseTask, type StepOption, type TemplateContext, factory, load, loaderPluginsFromPluginTuples, reduceOptions, tuple };