@qlover/fe-release 3.0.0 → 3.1.2

package/dist/index.js

@@ -2392,6 +2392,31 @@ import {
   ScriptContext
 } from "@qlover/scripts-context";
 var ReleaseContext = class extends ScriptContext {
+  /**
+   * 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, options) {
     super(name, options);
     if (!this.options.rootPath) {
@@ -2408,27 +2433,124 @@ var ReleaseContext = class extends ScriptContext {
       });
     }
   }
+  /**
+   * Gets the root path of the project
+   *
+   * @returns Absolute path to project root
+   *
+   * @example
+   * ```typescript
+   * const root = context.rootPath;
+   * // '/path/to/project'
+   * ```
+   */
   get rootPath() {
     return this.getOptions("rootPath");
   }
+  /**
+   * 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() {
     return this.getOptions("sourceBranch");
   }
+  /**
+   * Gets the release environment
+   *
+   * @returns Environment name (e.g., 'development', 'production')
+   *
+   * @example
+   * ```typescript
+   * const env = context.releaseEnv;
+   * // 'development' or custom environment
+   * ```
+   */
   get releaseEnv() {
     return this.getOptions("releaseEnv");
   }
+  /**
+   * 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() {
     return this.getOptions("workspaces.workspaces");
   }
+  /**
+   * 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() {
     return this.getOptions("workspaces.workspace");
   }
+  /**
+   * 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) {
     this.options.workspaces = {
       ...this.options.workspaces,
       workspaces
     };
   }
+  /**
+   * 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(key, defaultValue) {
     const packageJson = this.workspace?.packageJson;
     if (!packageJson) {
@@ -2439,6 +2561,28 @@ var ReleaseContext = class extends ScriptContext {
     }
     return (0, import_get.default)(packageJson, key, defaultValue);
   }
+  /**
+   * 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() {
     return {
       ...this.getOptions(),
@@ -2449,6 +2593,28 @@ var ReleaseContext = class extends ScriptContext {
       branch: this.sourceBranch
     };
   }
+  /**
+   * 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');
+   * ```
+   */
   async runChangesetsCli(name, args) {
     let packageManager = "pnpm";
     try {
@@ -2483,6 +2649,28 @@ var DEFAULT_RELEASE_CONFIG = {
   batchTagName: "batch-${length}-packages-${timestamp}"
 };
 var ReleaseParams = class {
+  /**
+   * Creates a new ReleaseParams instance
+   *
+   * Initializes with logger for debug output and optional configuration
+   * overrides. Uses default configuration values for any unspecified options.
+   *
+   * @param logger - Logger instance for debug output
+   * @param config - Optional configuration overrides
+   *
+   * @example
+   * ```typescript
+   * // Basic initialization
+   * const params = new ReleaseParams(logger);
+   *
+   * // With custom configuration
+   * const params = new ReleaseParams(logger, {
+   *   maxWorkspace: 5,
+   *   multiWorkspaceSeparator: '-',
+   *   workspaceVersionSeparator: '#'
+   * });
+   * ```
+   */
   constructor(logger, config = {}) {
     this.logger = logger;
     this.config = {
@@ -2490,7 +2678,49 @@ var ReleaseParams = class {
       ...config
     };
   }
+  /**
+   * Current configuration
+   * @private
+   */
   config;
+  /**
+   * Generates a release branch name for a single package
+   *
+   * Uses the branch name template from shared configuration or
+   * falls back to the default template 'release-${tagName}'.
+   * Supports variable interpolation in the template.
+   *
+   * Template Variables:
+   * - ${pkgName}: Package name
+   * - ${releaseName}: Release name (same as pkgName)
+   * - ${tagName}: Release tag
+   * - All shared config properties
+   *
+   * @param releaseName - Name of the package being released
+   * @param tagName - Version tag for the release
+   * @param shared - Shared configuration with branch template
+   * @returns Formatted branch name
+   * @throws Error if branch name template is not a string
+   *
+   * @example
+   * ```typescript
+   * // With default template
+   * const branch = params.getReleaseBranchName(
+   *   'my-pkg',
+   *   'v1.0.0',
+   *   {}
+   * );
+   * // 'release-v1.0.0'
+   *
+   * // With custom template
+   * const branch = params.getReleaseBranchName(
+   *   'my-pkg',
+   *   'v1.0.0',
+   *   { branchName: '${pkgName}-release-${tagName}' }
+   * );
+   * // 'my-pkg-release-v1.0.0'
+   * ```
+   */
   getReleaseBranchName(releaseName, tagName, shared) {
     const branchNameTpl = shared.branchName || "release-${tagName}";
     if (typeof branchNameTpl !== "string") {
@@ -2505,6 +2735,49 @@ var ReleaseParams = class {
       ...shared
     });
   }
+  /**
+   * Generates a release branch name for multiple packages
+   *
+   * Uses the batch branch name template from configuration.
+   * Supports variable interpolation with additional batch-specific
+   * variables.
+   *
+   * Template Variables:
+   * - ${pkgName}: Package name
+   * - ${releaseName}: Combined release name
+   * - ${tagName}: Combined tag name
+   * - ${length}: Number of packages
+   * - ${timestamp}: Current timestamp
+   * - All shared config properties
+   *
+   * @param releaseName - Combined name of packages
+   * @param tagName - Combined version tag
+   * @param shared - Shared configuration
+   * @param length - Number of packages in batch
+   * @returns Formatted batch branch name
+   * @throws Error if branch name template is not a string
+   *
+   * @example
+   * ```typescript
+   * // With default template
+   * const branch = params.getBatchReleaseBranchName(
+   *   'pkg-a@1.0.0_pkg-b@2.0.0',
+   *   'batch-2-packages-1234567890',
+   *   {},
+   *   2
+   * );
+   * // 'batch-pkg-a@1.0.0_pkg-b@2.0.0-2-packages-1234567890'
+   *
+   * // With custom template
+   * const branch = params.getBatchReleaseBranchName(
+   *   'pkg-a@1.0.0_pkg-b@2.0.0',
+   *   'v1.0.0',
+   *   {},
+   *   2,
+   * );
+   * // Custom formatted branch name
+   * ```
+   */
   getBatchReleaseBranchName(releaseName, tagName, shared, length) {
     const branchNameTpl = this.config.batchBranchName;
     if (typeof branchNameTpl !== "string") {
@@ -2521,6 +2794,45 @@ var ReleaseParams = class {
       timestamp: Date.now()
     });
   }
+  /**
+   * Generates a release name from workspace configurations
+   *
+   * For single packages, returns the package name.
+   * For multiple packages, combines names and versions up to
+   * the configured maximum number of workspaces.
+   *
+   * Format:
+   * - Single: packageName
+   * - Multiple: pkg1@1.0.0_pkg2@2.0.0_pkg3@3.0.0
+   *
+   * @param composeWorkspaces - Array of workspace configurations
+   * @returns Formatted release name
+   *
+   * @example
+   * ```typescript
+   * // Single package
+   * const name = params.getReleaseName([
+   *   { name: 'pkg-a', version: '1.0.0' }
+   * ]);
+   * // 'pkg-a'
+   *
+   * // Multiple packages
+   * const name = params.getReleaseName([
+   *   { name: 'pkg-a', version: '1.0.0' },
+   *   { name: 'pkg-b', version: '2.0.0' }
+   * ]);
+   * // 'pkg-a@1.0.0_pkg-b@2.0.0'
+   *
+   * // With max limit
+   * const name = params.getReleaseName([
+   *   { name: 'pkg-a', version: '1.0.0' },
+   *   { name: 'pkg-b', version: '2.0.0' },
+   *   { name: 'pkg-c', version: '3.0.0' },
+   *   { name: 'pkg-d', version: '4.0.0' }
+   * ]);
+   * // Only first 3: 'pkg-a@1.0.0_pkg-b@2.0.0_pkg-c@3.0.0'
+   * ```
+   */
   getReleaseName(composeWorkspaces) {
     if (composeWorkspaces.length === 1) {
       return composeWorkspaces[0].name;
@@ -2530,6 +2842,36 @@ var ReleaseParams = class {
       ({ name, version }) => `${name}${workspaceVersionSeparator}${version}`
     ).join(multiWorkspaceSeparator);
   }
+  /**
+   * Generates a tag name for the release
+   *
+   * For single packages, uses the package version.
+   * For multiple packages, generates a batch tag name using
+   * the configured template.
+   *
+   * Format:
+   * - Single: version
+   * - Multiple: batch-${length}-packages-${timestamp}
+   *
+   * @param composeWorkspaces - Array of workspace configurations
+   * @returns Formatted tag name
+   *
+   * @example
+   * ```typescript
+   * // Single package
+   * const tag = params.getReleaseTagName([
+   *   { name: 'pkg-a', version: '1.0.0' }
+   * ]);
+   * // '1.0.0'
+   *
+   * // Multiple packages
+   * const tag = params.getReleaseTagName([
+   *   { name: 'pkg-a', version: '1.0.0' },
+   *   { name: 'pkg-b', version: '2.0.0' }
+   * ]);
+   * // 'batch-2-packages-1234567890'
+   * ```
+   */
   getReleaseTagName(composeWorkspaces) {
     if (composeWorkspaces.length === 1) {
       return composeWorkspaces[0].version;
@@ -2540,6 +2882,44 @@ var ReleaseParams = class {
       timestamp: Date.now()
     });
   }
+  /**
+   * Generates branch and tag parameters for the release
+   *
+   * Combines the generation of branch name and tag name into
+   * a single operation. Handles both single and multi-package
+   * releases appropriately.
+   *
+   * @param composeWorkspaces - Array of workspace configurations
+   * @param shared - Shared configuration
+   * @returns Object containing tag name and branch name
+   *
+   * @example Single package
+   * ```typescript
+   * const params = releaseParams.getReleaseBranchParams(
+   *   [{ name: 'pkg-a', version: '1.0.0' }],
+   *   { branchName: 'release-${tagName}' }
+   * );
+   * // {
+   * //   tagName: '1.0.0',
+   * //   releaseBranch: 'release-1.0.0'
+   * // }
+   * ```
+   *
+   * @example Multiple packages
+   * ```typescript
+   * const params = releaseParams.getReleaseBranchParams(
+   *   [
+   *     { name: 'pkg-a', version: '1.0.0' },
+   *     { name: 'pkg-b', version: '2.0.0' }
+   *   ],
+   *   {}
+   * );
+   * // {
+   * //   tagName: 'batch-2-packages-1234567890',
+   * //   releaseBranch: 'batch-pkg-a@1.0.0_pkg-b@2.0.0-2-packages-1234567890'
+   * // }
+   * ```
+   */
   getReleaseBranchParams(composeWorkspaces, shared) {
     const releaseTagName = this.getReleaseTagName(composeWorkspaces);
     const releaseName = this.getReleaseName(composeWorkspaces);
@@ -2554,6 +2934,50 @@ var ReleaseParams = class {
       releaseBranch: releaseBranchName
     };
   }
+  /**
+   * Generates a title for the release pull request
+   *
+   * Uses the configured PR title template or falls back to the default.
+   * Supports variable interpolation with release parameters and context.
+   *
+   * Template Variables:
+   * - ${tagName}: Release tag name
+   * - ${pkgName}: Package/branch name
+   * - All template context properties
+   *
+   * @param releaseBranchParams - Release branch parameters
+   * @param context - Template context for variable interpolation
+   * @returns Formatted PR title
+   *
+   * @example
+   * ```typescript
+   * // With default template
+   * const title = params.getPRTitle(
+   *   {
+   *     tagName: '1.0.0',
+   *     releaseBranch: 'release-1.0.0'
+   *   },
+   *   {
+   *     env: 'production',
+   *     pkgName: 'my-package'
+   *   }
+   * );
+   * // 'Release production my-package 1.0.0'
+   *
+   * // With custom template
+   * const title = params.getPRTitle(
+   *   {
+   *     tagName: '1.0.0',
+   *     releaseBranch: 'release-1.0.0'
+   *   },
+   *   {
+   *     env: 'staging',
+   *     pkgName: 'my-package'
+   *   }
+   * );
+   * // Custom formatted title
+   * ```
+   */
   getPRTitle(releaseBranchParams, context) {
     const prTitleTpl = this.config.PRTitle || DEFAULT_PR_TITLE;
     return Shell.format(prTitleTpl, {
@@ -2563,10 +2987,67 @@ var ReleaseParams = class {
     });
   }
   /**
-   * Gets the body for the release pull request.
+   * Generates the body content for the release pull request
+   *
+   * Handles both single and multi-package releases, combining
+   * changelogs appropriately. For batch releases, formats each
+   * package's changelog according to the batch template.
+   *
+   * Template Variables:
+   * - ${tagName}: Release tag or combined workspace versions
+   * - ${changelog}: Single changelog or combined batch changelogs
+   * - All template context properties
+   *
+   * @param composeWorkspaces - Array of workspace configurations
+   * @param releaseBranchParams - Release branch parameters
+   * @param context - Template context for variable interpolation
+   * @returns Formatted PR body content
    *
-   * @param options - The options containing tag name and changelog.
-   * @returns The formatted release pull request body.
+   * @example Single package
+   * ```typescript
+   * const body = params.getPRBody(
+   *   [{
+   *     name: 'pkg-a',
+   *     version: '1.0.0',
+   *     changelog: '- Feature: New functionality\n- Fix: Bug fix'
+   *   }],
+   *   {
+   *     tagName: '1.0.0',
+   *     releaseBranch: 'release-1.0.0'
+   *   },
+   *   context
+   * );
+   * // Custom formatted body with single changelog
+   * ```
+   *
+   * @example Multiple packages
+   * ```typescript
+   * const body = params.getPRBody(
+   *   [
+   *     {
+   *       name: 'pkg-a',
+   *       version: '1.0.0',
+   *       changelog: '- Feature: Package A changes'
+   *     },
+   *     {
+   *       name: 'pkg-b',
+   *       version: '2.0.0',
+   *       changelog: '- Feature: Package B changes'
+   *     }
+   *   ],
+   *   {
+   *     tagName: 'batch-2-packages-1234567890',
+   *     releaseBranch: 'batch-release'
+   *   },
+   *   context
+   * );
+   * // Formatted body with combined changelogs:
+   * // ## pkg-a 1.0.0
+   * // - Feature: Package A changes
+   * //
+   * // ## pkg-b 2.0.0
+   * // - Feature: Package B changes
+   * ```
    */
   getPRBody(composeWorkspaces, releaseBranchParams, context) {
     const PRBodyTpl = this.config.PRBody;
@@ -2592,10 +3073,36 @@ var ReleaseParams = class {
 import { Shell as Shell2 } from "@qlover/scripts-context";
 import { Octokit } from "@octokit/rest";
 var GithubManager = class {
+  /**
+   * Creates a new GithubManager instance
+   *
+   * @param context - Release context containing configuration
+   *
+   * @example
+   * ```typescript
+   * const manager = new GithubManager(context);
+   * ```
+   */
   constructor(context) {
     this.context = context;
   }
+  /** Lazy-loaded Octokit instance */
   _octokit = null;
+  /**
+   * Gets GitHub repository information
+   *
+   * Retrieves the owner and repository name from the context.
+   * This information is required for most GitHub API operations.
+   *
+   * @returns Repository owner and name
+   * @throws Error if owner or repo name is not set
+   *
+   * @example
+   * ```typescript
+   * const info = manager.getGitHubUserInfo();
+   * // { owner: 'org-name', repo: 'repo-name' }
+   * ```
+   */
   getGitHubUserInfo() {
     const { authorName, repoName } = this.context.getOptions();
     if (!authorName || !repoName) {
@@ -2606,6 +3113,28 @@ var GithubManager = class {
       repo: repoName
     };
   }
+  /**
+   * Gets GitHub API token
+   *
+   * Retrieves the GitHub API token from environment variables.
+   * The token name can be configured via the tokenRef option.
+   *
+   * @returns GitHub API token
+   * @throws Error if token is not set
+   *
+   * @example Default token
+   * ```typescript
+   * const token = manager.getToken();
+   * // Uses GITHUB_TOKEN env var
+   * ```
+   *
+   * @example Custom token
+   * ```typescript
+   * context.options.githubPR.tokenRef = 'CUSTOM_TOKEN';
+   * const token = manager.getToken();
+   * // Uses CUSTOM_TOKEN env var
+   * ```
+   */
   getToken() {
     const { tokenRef = "GITHUB_TOKEN" } = this.context.getOptions("githubPR");
     const token = this.context.env.get(tokenRef);
@@ -2616,6 +3145,24 @@ var GithubManager = class {
     }
     return token;
   }
+  /**
+   * Gets Octokit instance
+   *
+   * Lazily initializes and returns an Octokit instance configured
+   * with the GitHub token and timeout settings.
+   *
+   * @returns Configured Octokit instance
+   * @throws Error if token retrieval fails
+   *
+   * @example
+   * ```typescript
+   * const octokit = manager.octokit;
+   * await octokit.rest.issues.create({
+   *   ...manager.getGitHubUserInfo(),
+   *   title: 'Issue title'
+   * });
+   * ```
+   */
   get octokit() {
     if (this._octokit) {
       return this._octokit;
@@ -2630,9 +3177,37 @@ var GithubManager = class {
     this._octokit = new Octokit(options);
     return this._octokit;
   }
+  /**
+   * Gets logger instance
+   *
+   * Provides access to the context's logger for consistent
+   * logging across the manager.
+   *
+   * @returns Logger instance
+   *
+   * @example
+   * ```typescript
+   * manager.logger.info('Creating release...');
+   * manager.logger.debug('API response:', response);
+   * ```
+   */
   get logger() {
     return this.context.logger;
   }
+  /**
+   * Gets shell interface
+   *
+   * Provides access to the context's shell interface for
+   * executing Git commands and other shell operations.
+   *
+   * @returns Shell interface
+   *
+   * @example
+   * ```typescript
+   * await manager.shell.exec('git fetch origin');
+   * await manager.shell.exec(['git', 'push', 'origin', 'main']);
+   * ```
+   */
   get shell() {
     return this.context.shell;
   }
@@ -2641,6 +3216,23 @@ var GithubManager = class {
    *
    * @default `squash`
    */
+  /**
+   * Gets auto-merge type for pull requests
+   *
+   * Determines how pull requests should be merged when
+   * auto-merge is enabled. Defaults to 'squash'.
+   *
+   * @returns Auto-merge type ('merge', 'squash', or 'rebase')
+   *
+   * @example
+   * ```typescript
+   * const mergeType = manager.autoMergeType;
+   * // 'squash' (default)
+   *
+   * context.options.autoMergeType = 'rebase';
+   * manager.autoMergeType; // 'rebase'
+   * ```
+   */
   get autoMergeType() {
     return this.context.getOptions().autoMergeType || DEFAULT_AUTO_MERGE_TYPE;
   }
@@ -2649,6 +3241,25 @@ var GithubManager = class {
    *
    * @default `999999`
    */
+  /**
+   * Gets pull request number for dry runs
+   *
+   * Returns a placeholder PR number when running in dry-run mode.
+   * This allows testing PR-related functionality without creating
+   * actual pull requests.
+   *
+   * @returns Dry run PR number (default: '999999')
+   *
+   * @example
+   * ```typescript
+   * context.dryRun = true;
+   * const prNumber = manager.dryRunPRNumber;
+   * // '999999'
+   *
+   * context.options.githubPR.dryRunPRNumber = '123456';
+   * manager.dryRunPRNumber; // '123456'
+   * ```
+   */
   get dryRunPRNumber() {
     return this.context.getOptions("githubPR.dryRunPRNumber", "999999");
   }
@@ -2657,6 +3268,23 @@ var GithubManager = class {
    *
    * @default `false`
    */
+  /**
+   * Gets auto-merge setting for release PRs
+   *
+   * Determines whether release pull requests should be
+   * automatically merged after creation. Defaults to false.
+   *
+   * @returns True if auto-merge is enabled
+   *
+   * @example
+   * ```typescript
+   * const autoMerge = manager.autoMergeReleasePR;
+   * // false (default)
+   *
+   * context.options.autoMergeReleasePR = true;
+   * manager.autoMergeReleasePR; // true
+   * ```
+   */
   get autoMergeReleasePR() {
     return this.context.getOptions("autoMergeReleasePR") || DEFAULT_AUTO_MERGE_RELEASE_PR;
   }
@@ -2666,6 +3294,30 @@ var GithubManager = class {
    * @param prNumber - The pull request number to merge.
    * @param releaseBranch - The branch to merge into.
    */
+  /**
+   * Merges a pull request
+   *
+   * Merges the specified pull request using the configured
+   * merge method. In dry-run mode, logs the merge action
+   * without performing it.
+   *
+   * @param prNumber - Pull request number
+   * @param releaseBranch - Branch to merge
+   * @throws Error if merge fails
+   *
+   * @example Basic merge
+   * ```typescript
+   * await manager.mergePR('123', 'release-1.0.0');
+   * // Merges PR #123 using configured merge method
+   * ```
+   *
+   * @example Dry run
+   * ```typescript
+   * context.dryRun = true;
+   * await manager.mergePR('123', 'release-1.0.0');
+   * // Logs merge action without performing it
+   * ```
+   */
   async mergePR(prNumber, releaseBranch) {
     if (!prNumber) {
       this.logger.error("Failed to create Pull Request.", prNumber);
@@ -2685,6 +3337,24 @@ var GithubManager = class {
       merge_method: mergeMethod
     });
   }
+  /**
+   * Gets commits from a pull request
+   *
+   * Retrieves all commits associated with the specified pull request.
+   * Useful for generating changelogs or analyzing changes.
+   *
+   * @param prNumber - Pull request number
+   * @returns Promise resolving to array of commit information
+   * @throws Error if request fails
+   *
+   * @example
+   * ```typescript
+   * const commits = await manager.getPullRequestCommits(123);
+   * commits.forEach(commit => {
+   *   console.log(commit.sha, commit.commit.message);
+   * });
+   * ```
+   */
   async getPullRequestCommits(prNumber) {
     const pr = await this.octokit.rest.pulls.listCommits({
       ...this.getGitHubUserInfo(),
@@ -2692,6 +3362,23 @@ var GithubManager = class {
     });
     return pr.data;
   }
+  /**
+   * Gets detailed information about a commit
+   *
+   * Retrieves detailed information about a specific commit,
+   * including files changed, author details, and commit message.
+   *
+   * @param commitSha - Commit SHA
+   * @returns Promise resolving to commit information
+   * @throws Error if request fails
+   *
+   * @example
+   * ```typescript
+   * const info = await manager.getCommitInfo('abc123');
+   * console.log(info.commit.message);
+   * console.log(info.files.map(f => f.filename));
+   * ```
+   */
   async getCommitInfo(commitSha) {
     const pr = await this.octokit.rest.repos.getCommit({
       ...this.getGitHubUserInfo(),
@@ -2699,6 +3386,24 @@ var GithubManager = class {
     });
     return pr.data;
   }
+  /**
+   * Gets pull request information
+   *
+   * Retrieves detailed information about a pull request,
+   * including title, body, labels, and review status.
+   *
+   * @param prNumber - Pull request number
+   * @returns Promise resolving to pull request information
+   * @throws Error if request fails
+   *
+   * @example
+   * ```typescript
+   * const pr = await manager.getPullRequest(123);
+   * console.log(pr.title);
+   * console.log(pr.labels.map(l => l.name));
+   * console.log(pr.mergeable_state);
+   * ```
+   */
   async getPullRequest(prNumber) {
     const pr = await this.octokit.rest.pulls.get({
       ...this.getGitHubUserInfo(),
@@ -2712,6 +3417,27 @@ var GithubManager = class {
    * @param prNumber - The pull request number to check.
    * @param releaseBranch - The branch to check against.
    */
+  /**
+   * Checks pull request status and cleans up
+   *
+   * Verifies pull request status and deletes the release branch
+   * if the PR has been merged. Used for post-merge cleanup.
+   *
+   * Process:
+   * 1. Verify PR exists and status
+   * 2. Delete release branch if PR merged
+   * 3. Log cleanup results
+   *
+   * @param prNumber - Pull request number
+   * @param releaseBranch - Branch to clean up
+   * @throws Error if verification or cleanup fails
+   *
+   * @example
+   * ```typescript
+   * await manager.checkedPR('123', 'release-1.0.0');
+   * // Verifies PR #123 and deletes release-1.0.0 if merged
+   * ```
+   */
   async checkedPR(prNumber, releaseBranch) {
     try {
       await this.getPullRequest(Number(prNumber));
@@ -2812,10 +3538,55 @@ var GithubManager = class {
       throw error;
     }
   }
+  /**
+   * Truncates long PR/release body text
+   *
+   * GitHub has a limit on PR and release body length.
+   * This method ensures the text stays within limits by
+   * truncating if necessary.
+   *
+   * @param body - Body text to truncate
+   * @returns Truncated text (if > 124000 chars)
+   *
+   * @example
+   * ```typescript
+   * const body = manager.truncateBody(veryLongText);
+   * // Returns truncated text if > 124000 chars
+   * // Adds '...' to indicate truncation
+   * ```
+   * @private
+   */
   truncateBody(body) {
     if (body && body.length >= 124e3) return body.substring(0, 124e3) + "...";
     return body;
   }
+  /**
+   * Builds GitHub release options
+   *
+   * Combines default release options with provided overrides
+   * and context configuration. Handles formatting of release
+   * name, body, and other settings.
+   *
+   * @param options - Override options for release
+   * @returns Complete release options
+   *
+   * @example
+   * ```typescript
+   * const opts = manager.getOctokitReleaseOptions({
+   *   tag_name: 'v1.0.0',
+   *   body: 'Release notes...'
+   * });
+   * // Returns merged options with defaults:
+   * // {
+   * //   name: 'Release v1.0.0',
+   * //   body: 'Release notes...',
+   * //   draft: false,
+   * //   prerelease: false,
+   * //   ...
+   * // }
+   * ```
+   * @private
+   */
   getOctokitReleaseOptions(options) {
     const {
       releaseName,
@@ -2841,6 +3612,37 @@ var GithubManager = class {
       ...this.getGitHubUserInfo()
     };
   }
+  /**
+   * Creates a GitHub release
+   *
+   * Creates a new GitHub release for a workspace with:
+   * - Formatted release name
+   * - Changelog as release notes
+   * - Proper tag
+   * - Configurable settings (draft, prerelease, etc.)
+   *
+   * Handles dry run mode and error cases gracefully.
+   *
+   * @param workspace - Workspace to create release for
+   * @throws Error if tag name is missing or creation fails
+   *
+   * @example Basic release
+   * ```typescript
+   * await manager.createRelease({
+   *   name: 'pkg-a',
+   *   version: '1.0.0',
+   *   tagName: 'v1.0.0',
+   *   changelog: '...'
+   * });
+   * ```
+   *
+   * @example Dry run
+   * ```typescript
+   * context.dryRun = true;
+   * await manager.createRelease(workspace);
+   * // Logs release info without creating
+   * ```
+   */
   async createRelease(workspace) {
     const meragedOptions = this.getOctokitReleaseOptions({
       tag_name: workspace.tagName,
@@ -2880,6 +3682,30 @@ var GithubManager = class {
 var import_isString = __toESM(require_isString(), 1);
 import { ScriptPlugin } from "@qlover/scripts-context";
 var GitBase = class extends ScriptPlugin {
+  /**
+   * Plugin initialization hook
+   *
+   * Runs before plugin execution to set up repository context:
+   * 1. Retrieves repository information
+   * 2. Gets current branch
+   * 3. Switches to current branch if needed
+   * 4. Updates context with repository info
+   *
+   * @throws Error if repository information cannot be retrieved
+   *
+   * @example
+   * ```typescript
+   * class MyPlugin extends GitBase<GitBaseProps> {
+   *   async onExec() {
+   *     // onBefore has already:
+   *     // - Set up repository info
+   *     // - Switched to correct branch
+   *     // - Updated context
+   *     await this.doSomething();
+   *   }
+   * }
+   * ```
+   */
   async onBefore() {
     const repoInfo = await this.getUserInfo();
     if (!repoInfo) {
@@ -2900,12 +3726,44 @@ var GitBase = class extends ScriptPlugin {
       currentBranch
     });
   }
+  /**
+   * Gets the current Git branch name
+   *
+   * Retrieves the name of the currently checked out Git branch.
+   * Includes a small delay to ensure Git's internal state is updated.
+   *
+   * @returns Promise resolving to branch name
+   * @throws Error if branch name cannot be retrieved
+   *
+   * @example
+   * ```typescript
+   * const branch = await plugin.getCurrentBranch();
+   * // 'main' or 'feature/new-feature'
+   * ```
+   */
   async getCurrentBranch() {
     await new Promise((resolve2) => setTimeout(resolve2, 100));
     return this.context.shell.exec("git rev-parse --abbrev-ref HEAD", {
       dryRun: false
     });
   }
+  /**
+   * Gets the Git remote URL
+   *
+   * Retrieves the URL of the 'origin' remote from Git configuration.
+   * This URL is used to identify the GitHub repository.
+   *
+   * @returns Promise resolving to remote URL
+   * @throws Error if remote URL cannot be retrieved
+   *
+   * @example
+   * ```typescript
+   * const url = await plugin.getRemoteUrl();
+   * // 'https://github.com/org/repo.git'
+   * // or
+   * // 'git@github.com:org/repo.git'
+   * ```
+   */
   async getRemoteUrl() {
     return (await this.context.shell.exec("git config --get remote.origin.url", {
       dryRun: false
@@ -2959,9 +3817,53 @@ var GitBase = class extends ScriptPlugin {
    * @param value - The value to check.
    * @returns True if the value is a valid string, otherwise false.
    */
+  /**
+   * Type guard for valid string values
+   *
+   * Checks if a value is a non-empty string. Used for validating
+   * repository information and other string inputs.
+   *
+   * @param value - Value to check
+   * @returns True if value is a non-empty string
+   *
+   * @example
+   * ```typescript
+   * if (plugin.isValidString(value)) {
+   *   // value is definitely a non-empty string
+   *   console.log(value.toUpperCase());
+   * }
+   * ```
+   */
   isValidString(value) {
     return !!value && (0, import_isString.default)(value);
   }
+  /**
+   * Creates a Git commit
+   *
+   * Creates a new Git commit with the specified message and optional
+   * additional arguments. The message is automatically JSON-stringified
+   * to handle special characters properly.
+   *
+   * @param message - Commit message
+   * @param args - Additional Git commit arguments
+   * @returns Promise resolving to command output
+   *
+   * @example Basic commit
+   * ```typescript
+   * await plugin.commit('feat: add new feature');
+   * ```
+   *
+   * @example Commit with arguments
+   * ```typescript
+   * await plugin.commit('fix: update deps', ['--no-verify']);
+   * ```
+   *
+   * @example Commit with special characters
+   * ```typescript
+   * await plugin.commit('fix: handle "quotes" & symbols');
+   * // Message is automatically escaped
+   * ```
+   */
   commit(message, args = []) {
     return this.context.shell.exec([
       "git",
@@ -2996,14 +3898,50 @@ var CHANGELOG_ALL_FIELDS = [
   "tag"
 ];
 var GitChangelog = class {
+  /**
+   * 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) {
     this.options = options;
   }
   /**
-   * 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'
+   * });
+   * ```
    */
   async getGitLog(options = {}) {
     const { directory, noMerges = true, fields } = options;
@@ -3024,6 +3962,38 @@ var GitChangelog = class {
     this.options.logger?.debug("GitChangelog commits", commits);
     return commits;
   }
+  /**
+   * 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
+   * });
+   * ```
+   */
   async getCommits(options) {
     const gitCommits = await this.getGitLog(options);
     return gitCommits.map((commit) => {
@@ -3036,6 +4006,28 @@ var GitChangelog = class {
       };
     });
   }
+  /**
+   * 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'
+   *   }
+   * );
+   * ```
+   */
   createBaseCommit(message, target) {
     return {
       subject: message,
@@ -3045,16 +4037,66 @@ var GitChangelog = class {
     };
   }
   /**
-   * 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, size = 2) {
     return body.split("\n").map((line) => " ".repeat(size) + line.trim()).join("\n");
   }
+  /**
+   * 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, rawBody = "") {
     const [title] = subject.trim().split("\n");
     const bodyLines = rawBody.startsWith(title) ? rawBody.replace(title, "") : rawBody;
@@ -3073,6 +4115,51 @@ var GitChangelog = class {
       body: bodyLines ? this.tabify(bodyLines) : void 0
     };
   }
+  /**
+   * 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, message) {
     const [title] = message.trim().split("\n");
     const prMatch = title.match(/\(#(\d+)\)/);
@@ -3090,6 +4177,33 @@ var GitChangelog = class {
       prNumber: prMatch?.[1]
     };
   }
+  /**
+   * 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
+   * ```
+   */
   async resolveTag(tag, fallback) {
     if (tag) {
       try {
@@ -3110,9 +4224,75 @@ var import_groupBy = __toESM(require_groupBy(), 1);
 import { Shell as Shell3 } from "@qlover/scripts-context";
 var DEFAULT_TEMPLATE = "\n- ${scopeHeader} ${commitlint.message} ${commitLink} ${prLink}";
 var GitChangelogFormatter = class {
+  /**
+   * 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) {
     this.options = options;
   }
+  /**
+   * 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, options) {
     const { types = [], commitBody = false } = { ...this.options, ...options };
     const changelog = [];
@@ -3139,6 +4319,41 @@ var GitChangelogFormatter = class {
     });
     return changelog;
   }
+  /**
+   * 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, options) {
     const {
       commitlint,
@@ -3165,12 +4380,65 @@ var GitChangelogFormatter = class {
       prLink
     });
   }
+  /**
+   * 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, url) {
     return url ? `([${target}](${url}))` : `(${target})`;
   }
+  /**
+   * 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, url) {
     return url ? `([${target}](${url}))` : `(${target})`;
   }
+  /**
+   * 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) {
     return `**${scope}:**`;
   }
@@ -3224,7 +4492,30 @@ var Pather = class {
     return child[boundaryIndex] === sep;
   }
   /**
-   * Normalised `startsWith` helper.
+   * Normalized path prefix check
+   *
+   * Checks if sourcePath starts with targetPath after normalization.
+   * Handles cross-platform path separators and trailing separators.
+   *
+   * @param sourcePath - Path to check
+   * @param targetPath - Prefix path to match
+   * @returns True if sourcePath starts with targetPath
+   *
+   * @example Basic usage
+   * ```typescript
+   * const pather = new Pather();
+   *
+   * pather.startsWith('src/utils/file.ts', 'src')     // true
+   * pather.startsWith('src\\utils\\file.ts', 'src')   // true
+   * pather.startsWith('lib/utils/file.ts', 'src')     // false
+   * ```
+   *
+   * @example Trailing separators
+   * ```typescript
+   * pather.startsWith('src/utils', 'src/')    // true
+   * pather.startsWith('src/utils/', 'src')    // true
+   * pather.startsWith('src2/utils', 'src')    // false
+   * ```
    */
   startsWith(sourcePath, targetPath) {
     let src = this.toLocalPath(sourcePath);
@@ -3238,7 +4529,44 @@ var Pather = class {
     return src.startsWith(tgt);
   }
   /**
-   * Segment-aware containment check (not mere substring).
+   * Segment-aware path containment check
+   *
+   * Checks if sourcePath contains targetPath as a complete path segment.
+   * Unlike simple substring matching, this ensures proper path boundaries.
+   * For example, 'src/abc' does not contain 'src/a' even though 'src/a'
+   * is a substring.
+   *
+   * Features:
+   * - Cross-platform path handling
+   * - Proper segment boundary checking
+   * - Trailing separator normalization
+   * - Exact match support
+   *
+   * @param sourcePath - Path to search in
+   * @param targetPath - Path to search for
+   * @returns True if sourcePath contains targetPath as a segment
+   *
+   * @example Basic usage
+   * ```typescript
+   * const pather = new Pather();
+   *
+   * pather.containsPath('src/utils/file.ts', 'utils')     // true
+   * pather.containsPath('src/utils/file.ts', 'src/utils') // true
+   * pather.containsPath('src/utils/file.ts', 'til')      // false
+   * ```
+   *
+   * @example Segment boundaries
+   * ```typescript
+   * pather.containsPath('src/abc/file.ts', 'src/a')     // false
+   * pather.containsPath('src/abc/file.ts', 'src/abc')   // true
+   * ```
+   *
+   * @example Trailing separators
+   * ```typescript
+   * pather.containsPath('src/utils/', 'utils')     // true
+   * pather.containsPath('src/utils', 'utils/')     // true
+   * pather.containsPath('src/utils/', 'utils/')    // true
+   * ```
    */
   containsPath(sourcePath, targetPath) {
     let src = this.toLocalPath(sourcePath);
@@ -3264,18 +4592,49 @@ var Pather = class {
 // src/plugins/githubPR/GithubChangelog.ts
 var DOMAIN = "https://github.com";
 var GithubChangelog = class _GithubChangelog extends GitChangelog {
+  /**
+   * Creates a new GitHub changelog generator
+   *
+   * @param options - Changelog generation options
+   * @param githubManager - GitHub API manager
+   *
+   * @example
+   * ```typescript
+   * const changelog = new GithubChangelog({
+   *   shell,
+   *   logger,
+   *   mergePRcommit: true,
+   *   githubRootPath: 'https://github.com/org/repo'
+   * }, githubManager);
+   * ```
+   */
   constructor(options, githubManager) {
     super(options);
     this.options = options;
     this.githubManager = githubManager;
   }
+  /** Path manipulation utility */
   pather = new Pather();
   /**
-   * Filter commits by directory
-   * @param commits - commits
-   * @param directory - directory
-   * @returns filtered commits
+   * Filters commits by directory
+   *
+   * Filters commits based on whether they contain changes in
+   * the specified directory. Uses GitHub API to get detailed
+   * commit information.
+   *
+   * @param commits - Array of commits to filter
+   * @param directory - Directory path to filter by
+   * @returns Promise resolving to filtered commits
    * @since 2.4.0
+   *
+   * @example
+   * ```typescript
+   * const commits = await changelog.filterCommitsByDirectory(
+   *   allCommits,
+   *   'packages/pkg-a'
+   * );
+   * // Only commits that modified files in packages/pkg-a
+   * ```
    */
   async filterCommitsByDirectory(commits, directory) {
     const result = [];
@@ -3293,6 +4652,41 @@ var GithubChangelog = class _GithubChangelog extends GitChangelog {
     }
     return result;
   }
+  /**
+   * Gets complete commit information with PR details
+   *
+   * Retrieves commits and enhances them with pull request
+   * information. For commits associated with PRs, includes
+   * all PR commits and filters by directory.
+   *
+   * Process:
+   * 1. Get base commits
+   * 2. Extract PR numbers
+   * 3. Fetch PR commits
+   * 4. Filter by directory
+   * 5. Flatten results
+   *
+   * @param options - Changelog options
+   * @returns Promise resolving to enhanced commits
+   *
+   * @example Basic usage
+   * ```typescript
+   * const commits = await changelog.getFullCommit({
+   *   from: 'v1.0.0',
+   *   directory: 'packages/pkg-a'
+   * });
+   * // Returns commits with PR information
+   * ```
+   *
+   * @example With PR merging
+   * ```typescript
+   * const commits = await changelog.getFullCommit({
+   *   mergePRcommit: true,
+   *   directory: 'packages/pkg-a'
+   * });
+   * // Includes all PR commits
+   * ```
+   */
   async getFullCommit(options) {
     const _options = { ...this.options, ...options };
     const allCommits = await this.getCommits(_options);
@@ -3320,6 +4714,41 @@ var GithubChangelog = class _GithubChangelog extends GitChangelog {
     );
     return newallCommits.flat();
   }
+  /**
+   * Transforms workspaces with GitHub changelogs
+   *
+   * Processes each workspace to add GitHub-specific changelog
+   * information. Includes:
+   * - GitHub repository URL
+   * - PR-aware commit history
+   * - Formatted changelog with links
+   *
+   * Process:
+   * 1. Build GitHub root path
+   * 2. Configure changelog options
+   * 3. Get commits for each workspace
+   * 4. Format changelog with links
+   * 5. Update workspace objects
+   *
+   * @param workspaces - Array of workspaces to process
+   * @param context - Release context
+   * @returns Promise resolving to updated workspaces
+   *
+   * @example
+   * ```typescript
+   * const workspaces = await changelog.transformWorkspace(
+   *   [
+   *     {
+   *       name: 'pkg-a',
+   *       path: 'packages/a',
+   *       lastTag: 'v1.0.0'
+   *     }
+   *   ],
+   *   context
+   * );
+   * // Returns workspaces with GitHub-formatted changelogs
+   * ```
+   */
   async transformWorkspace(workspaces, context) {
     const githubRootPath = [
       DOMAIN,
@@ -3369,6 +4798,26 @@ import { Shell as Shell4 } from "@qlover/scripts-context";
 var DEFAULT_RELEASE_NAME = "Release ${name} v${version}";
 var DEFAULT_COMMIT_MESSAGE = "chore(tag): ${name} v${version}";
 var GithubPR = class extends GitBase {
+  /**
+   * Creates a new GithubPR plugin instance
+   *
+   * Initializes the plugin with GitHub-specific configuration and
+   * sets up release parameters and GitHub manager.
+   *
+   * @param context - Release context
+   * @param props - Plugin configuration
+   *
+   * @example
+   * ```typescript
+   * const plugin = new GithubPR(context, {
+   *   releasePR: true,
+   *   releaseName: 'Release v${version}',
+   *   commitMessage: 'chore: release v${version}',
+   *   draft: false,
+   *   preRelease: false
+   * });
+   * ```
+   */
   constructor(context, props) {
     super(context, "githubPR", {
       releaseName: DEFAULT_RELEASE_NAME,
@@ -3384,15 +4833,67 @@ var GithubPR = class extends GitBase {
   }
   releaseParams;
   githubManager;
+  /**
+   * Determines if the plugin should be enabled
+   *
+   * Plugin is enabled unless explicitly skipped via configuration.
+   * This allows for conditional PR creation and release publishing.
+   *
+   * @param _name - Plugin name (unused)
+   * @returns True if plugin should be enabled
+   *
+   * @example
+   * ```typescript
+   * const plugin = new GithubPR(context, { skip: true });
+   * plugin.enabled(); // false
+   *
+   * const plugin2 = new GithubPR(context, {});
+   * plugin2.enabled(); // true
+   * ```
+   */
   enabled(_name) {
     if (this.getConfig("skip")) {
       return false;
     }
     return true;
   }
+  /**
+   * Determines if the plugin is in publish mode
+   *
+   * In publish mode, the plugin publishes releases directly.
+   * In non-publish mode (releasePR=true), it creates pull requests.
+   *
+   * @returns True if in publish mode
+   *
+   * @example
+   * ```typescript
+   * const plugin = new GithubPR(context, { releasePR: true });
+   * plugin.isPublish; // false (PR mode)
+   *
+   * const plugin2 = new GithubPR(context, { releasePR: false });
+   * plugin2.isPublish; // true (publish mode)
+   * ```
+   */
   get isPublish() {
     return !this.getConfig("releasePR");
   }
+  /**
+   * Checks if the current repository is a GitHub repository
+   *
+   * Verifies that the remote URL contains 'github.com' to ensure
+   * GitHub-specific features can be used.
+   *
+   * @returns Promise resolving to true if GitHub repository
+   *
+   * @example
+   * ```typescript
+   * const isGithub = await plugin.isGithubRepository();
+   * if (isGithub) {
+   *   // Use GitHub-specific features
+   * }
+   * ```
+   * @private
+   */
   async isGithubRepository() {
     try {
       const remoteUrl = await this.getRemoteUrl();
@@ -3401,6 +4902,24 @@ var GithubPR = class extends GitBase {
       return false;
     }
   }
+  /**
+   * Plugin initialization hook
+   *
+   * Performs pre-execution setup:
+   * 1. Verifies repository is on GitHub
+   * 2. Runs parent class initialization
+   * 3. Sets up NPM token for publishing
+   *
+   * @throws Error if not a GitHub repository
+   * @throws Error if NPM_TOKEN missing in publish mode
+   *
+   * @example
+   * ```typescript
+   * const plugin = new GithubPR(context, {});
+   * await plugin.onBefore();
+   * // Throws if not GitHub repo or missing NPM token
+   * ```
+   */
   async onBefore() {
     this.logger.debug("GithubPR onBefore");
     const isGithub = await this.isGithubRepository();
@@ -3420,6 +4939,24 @@ var GithubPR = class extends GitBase {
       );
     }
   }
+  /**
+   * Main plugin execution hook
+   *
+   * Processes changelogs for all workspaces using GitHub-specific
+   * formatting and updates the context with the results.
+   *
+   * Process:
+   * 1. Initialize GitHub changelog processor
+   * 2. Transform workspace changelogs
+   * 3. Update context with new workspace info
+   *
+   * @example
+   * ```typescript
+   * const plugin = new GithubPR(context, {});
+   * await plugin.onExec();
+   * // Transforms changelogs with GitHub links
+   * ```
+   */
   async onExec() {
     const workspaces = this.context.workspaces;
     const githubChangelog = new GithubChangelog(
@@ -3432,6 +4969,27 @@ var GithubPR = class extends GitBase {
     });
     this.context.setWorkspaces(newWorkspaces);
   }
+  /**
+   * Success hook after plugin execution
+   *
+   * Handles either PR creation or release publishing based on
+   * configuration. In publish mode, publishes to NPM and creates
+   * GitHub releases. In PR mode, creates release pull requests.
+   *
+   * @example PR mode
+   * ```typescript
+   * const plugin = new GithubPR(context, { releasePR: true });
+   * await plugin.onSuccess();
+   * // Creates release PR
+   * ```
+   *
+   * @example Publish mode
+   * ```typescript
+   * const plugin = new GithubPR(context, { releasePR: false });
+   * await plugin.onSuccess();
+   * // Publishes to NPM and creates GitHub release
+   * ```
+   */
   async onSuccess() {
     if (this.isPublish) {
       await this.publishPR(this.context.workspaces);
@@ -3439,6 +4997,28 @@ var GithubPR = class extends GitBase {
     }
     await this.releasePR(this.context.workspaces);
   }
+  /**
+   * Creates a release pull request
+   *
+   * Handles the complete process of creating a release PR:
+   * 1. Creates release commit
+   * 2. Creates release branch
+   * 3. Creates and configures pull request
+   *
+   * @param workspaces - Array of workspace configurations
+   *
+   * @example
+   * ```typescript
+   * const workspaces = [{
+   *   name: 'pkg-a',
+   *   version: '1.0.0',
+   *   changelog: '...'
+   * }];
+   *
+   * await plugin.releasePR(workspaces);
+   * // Creates PR with release changes
+   * ```
+   */
   async releasePR(workspaces) {
     await this.step({
       label: "Release Commit",
@@ -3450,6 +5030,28 @@ var GithubPR = class extends GitBase {
     });
     await this.releasePullRequest(workspaces, releaseBranchParams);
   }
+  /**
+   * Publishes releases to NPM and GitHub
+   *
+   * In non-dry-run mode:
+   * 1. Publishes packages to NPM
+   * 2. Pushes tags to GitHub
+   * 3. Creates GitHub releases
+   *
+   * @param workspaces - Array of workspace configurations
+   *
+   * @example
+   * ```typescript
+   * const workspaces = [{
+   *   name: 'pkg-a',
+   *   version: '1.0.0',
+   *   changelog: '...'
+   * }];
+   *
+   * await plugin.publishPR(workspaces);
+   * // Publishes to NPM and creates GitHub releases
+   * ```
+   */
   async publishPR(workspaces) {
     if (!this.getConfig("dryRunCreatePR")) {
       await this.context.runChangesetsCli("publish");
@@ -3465,6 +5067,34 @@ var GithubPR = class extends GitBase {
       )
     });
   }
+  /**
+   * Creates release commit(s)
+   *
+   * Creates either a single commit for all workspaces or
+   * individual commits per workspace. Uses configured commit
+   * message template.
+   *
+   * @param workspaces - Array of workspace configurations
+   *
+   * @example Single workspace
+   * ```typescript
+   * await plugin.relesaeCommit([{
+   *   name: 'pkg-a',
+   *   version: '1.0.0'
+   * }]);
+   * // Creates: "chore(tag): pkg-a v1.0.0"
+   * ```
+   *
+   * @example Multiple workspaces
+   * ```typescript
+   * await plugin.relesaeCommit([
+   *   { name: 'pkg-a', version: '1.0.0' },
+   *   { name: 'pkg-b', version: '2.0.0' }
+   * ]);
+   * // Creates: "chore(tag): pkg-a v1.0.0,pkg-b v2.0.0"
+   * ```
+   * @private
+   */
   async relesaeCommit(workspaces) {
     const commitArgs = this.getConfig("commitArgs", []);
     if (workspaces.length === 1) {
@@ -3476,6 +5106,34 @@ var GithubPR = class extends GitBase {
     const commitMessage = `chore(tag): ${workspaces.map((w) => `${w.name} v${w.version}`).join(",")}`;
     await this.commit(commitMessage, commitArgs);
   }
+  /**
+   * Creates and optionally merges a release pull request
+   *
+   * Creates a PR with release changes and handles auto-merge
+   * if configured. Adds release and change labels to the PR.
+   *
+   * @param workspaces - Array of workspace configurations
+   * @param releaseBranchParams - Branch and tag information
+   *
+   * @example Manual merge
+   * ```typescript
+   * await plugin.releasePullRequest(
+   *   workspaces,
+   *   { releaseBranch: 'release-v1.0.0', tagName: 'v1.0.0' }
+   * );
+   * // Creates PR for manual merge
+   * ```
+   *
+   * @example Auto-merge
+   * ```typescript
+   * const plugin = new GithubPR(context, {
+   *   autoMergeReleasePR: true
+   * });
+   *
+   * await plugin.releasePullRequest(workspaces, params);
+   * // Creates and auto-merges PR
+   * ```
+   */
   async releasePullRequest(workspaces, releaseBranchParams) {
     const prNumber = await this.step({
       label: "Create Release PR",
@@ -3497,6 +5155,34 @@ var GithubPR = class extends GitBase {
       `Please manually merge PR(#${prNumber}) and complete the publishing process afterwards`
     );
   }
+  /**
+   * Creates a commit for a single workspace
+   *
+   * Uses the configured commit message template to create a
+   * commit for the workspace's changes.
+   *
+   * @param workspace - Workspace configuration
+   * @param commitArgs - Additional Git commit arguments
+   * @returns Promise resolving to commit output
+   *
+   * @example Basic commit
+   * ```typescript
+   * await plugin.commitWorkspace({
+   *   name: 'pkg-a',
+   *   version: '1.0.0'
+   * });
+   * // Creates: "chore(tag): pkg-a v1.0.0"
+   * ```
+   *
+   * @example With arguments
+   * ```typescript
+   * await plugin.commitWorkspace(
+   *   { name: 'pkg-a', version: '1.0.0' },
+   *   ['--no-verify']
+   * );
+   * ```
+   * @private
+   */
   async commitWorkspace(workspace, commitArgs = []) {
     const commitMessage = Shell4.format(
       this.getConfig("commitMessage", DEFAULT_COMMIT_MESSAGE),
@@ -3514,6 +5200,37 @@ var GithubPR = class extends GitBase {
    *
    * @returns The release branch.
    */
+  /**
+   * Creates a release branch for changes
+   *
+   * Creates a new branch from the current branch for release
+   * changes. The branch name is generated from the configured
+   * template and workspace information.
+   *
+   * Process:
+   * 1. Generate branch parameters
+   * 2. Fetch required branches
+   * 3. Create and push release branch
+   *
+   * @param workspaces - Array of workspace configurations
+   * @returns Promise resolving to branch parameters
+   *
+   * @example
+   * ```typescript
+   * const params = await plugin.createReleaseBranch([{
+   *   name: 'pkg-a',
+   *   version: '1.0.0'
+   * }]);
+   * // {
+   * //   tagName: 'pkg-a@1.0.0',
+   * //   releaseBranch: 'release-pkg-a-1.0.0'
+   * // }
+   * ```
+   *
+   * @throws Error if tag name is invalid
+   * @throws Error if branch creation fails
+   * @private
+   */
   async createReleaseBranch(workspaces) {
     const params = this.releaseParams.getReleaseBranchParams(
       workspaces,
@@ -3556,6 +5273,42 @@ var GithubPR = class extends GitBase {
    * @param releaseBranchParams - The release branch params.
    * @returns The created pull request number.
    */
+  /**
+   * Creates a release pull request
+   *
+   * Creates a pull request with:
+   * 1. Release label
+   * 2. Change labels (if configured)
+   * 3. Generated title and body
+   * 4. Proper branch configuration
+   *
+   * @param workspaces - Array of workspace configurations
+   * @param releaseBranchParams - Branch and tag information
+   * @returns Promise resolving to PR number
+   *
+   * @example Basic PR
+   * ```typescript
+   * const prNumber = await plugin.createReleasePR(
+   *   workspaces,
+   *   { releaseBranch: 'release-v1.0.0', tagName: 'v1.0.0' }
+   * );
+   * // Creates PR with default labels
+   * ```
+   *
+   * @example With change labels
+   * ```typescript
+   * const plugin = new GithubPR(context, {
+   *   pushChangeLabels: true
+   * });
+   *
+   * const prNumber = await plugin.createReleasePR(
+   *   workspaces,
+   *   params
+   * );
+   * // Creates PR with release and change labels
+   * ```
+   * @private
+   */
   async createReleasePR(workspaces, releaseBranchParams) {
     const label = await this.githubManager.createReleasePRLabel();
     let labels = [label.name];
@@ -3589,21 +5342,137 @@ import { join as join2, resolve, relative } from "path";
 
 // src/implments/ReleaseLabel.ts
 var ReleaseLabel = class {
+  /**
+   * 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) {
     this.options = options;
   }
+  /**
+   * 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, packagePath) {
     if (typeof this.options.compare === "function") {
       return this.options.compare(changedFilePath, packagePath);
     }
     return changedFilePath.startsWith(packagePath);
   }
+  /**
+   * 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, label = this.options.changePackagesLabel) {
     return label.replace("${name}", packagePath);
   }
+  /**
+   * 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, label = this.options.changePackagesLabel) {
     return packages.map((pkg) => this.toChangeLabel(pkg, label));
   }
+  /**
+   * 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, packages = this.options.packagesDirectories) {
     const result = [];
     for (const pkgPath of packages) {
@@ -3972,6 +5841,31 @@ import {
 } from "@qlover/scripts-context";
 var contentTmplate = "---\n'${name}': '${increment}'\n---\n\n${changelog}";
 var Changelog = class extends ScriptPlugin3 {
+  /**
+   * Creates a new Changelog plugin instance
+   *
+   * Initializes the plugin with default configuration values and
+   * merges them with provided options.
+   *
+   * Default values:
+   * - increment: 'patch'
+   * - changesetRoot: '.changeset'
+   * - tagTemplate: '${name}@${version}'
+   * - tagPrefix: '${name}'
+   * - tagMatch: '${name}@*'
+   *
+   * @param context - Release context
+   * @param props - Plugin configuration
+   *
+   * @example
+   * ```typescript
+   * const plugin = new Changelog(context, {
+   *   increment: 'minor',
+   *   changesetRoot: 'custom/changeset',
+   *   tagTemplate: 'v${version}'
+   * });
+   * ```
+   */
   constructor(context, props) {
     super(context, "changelog", {
       increment: "patch",
@@ -3982,15 +5876,78 @@ var Changelog = class extends ScriptPlugin3 {
       ...props
     });
   }
+  /**
+   * Gets the absolute path to the changeset root directory
+   *
+   * Combines the project root path with the configured changeset
+   * directory path.
+   *
+   * @returns Absolute path to changeset directory
+   *
+   * @example
+   * ```typescript
+   * const root = plugin.changesetRoot;
+   * // '/path/to/project/.changeset'
+   * ```
+   */
   get changesetRoot() {
     return join4(this.context.rootPath, this.getConfig("changesetRoot"));
   }
+  /**
+   * Gets the path to the changeset configuration file
+   *
+   * Returns the absolute path to the config.json file in the
+   * changeset directory.
+   *
+   * @returns Path to changeset config file
+   *
+   * @example
+   * ```typescript
+   * const configPath = plugin.changesetConfigPath;
+   * // '/path/to/project/.changeset/config.json'
+   * ```
+   */
   get changesetConfigPath() {
     return join4(this.changesetRoot, "config.json");
   }
+  /**
+   * Determines if the plugin should be enabled
+   *
+   * Plugin is enabled unless explicitly skipped via configuration.
+   * This allows for conditional changelog generation.
+   *
+   * @returns True if plugin should be enabled
+   *
+   * @example
+   * ```typescript
+   * const plugin = new Changelog(context, { skip: true });
+   * plugin.enabled(); // false
+   *
+   * const plugin2 = new Changelog(context, {});
+   * plugin2.enabled(); // true
+   * ```
+   */
   enabled() {
     return !this.getConfig("skip");
   }
+  /**
+   * Plugin initialization hook
+   *
+   * Verifies that the changeset directory exists before proceeding
+   * with changelog generation.
+   *
+   * @throws Error if changeset directory does not exist
+   *
+   * @example
+   * ```typescript
+   * const plugin = new Changelog(context, {
+   *   changesetRoot: '.changeset'
+   * });
+   *
+   * await plugin.onBefore();
+   * // Throws if .changeset directory doesn't exist
+   * ```
+   */
   async onBefore() {
     if (!existsSync(this.changesetRoot)) {
       throw new Error(
@@ -3999,6 +5956,33 @@ var Changelog = class extends ScriptPlugin3 {
     }
     this.logger.debug(`${this.changesetRoot} exists`);
   }
+  /**
+   * Updates workspace information with latest versions
+   *
+   * Reads the latest version information from each workspace's
+   * package.json and updates the workspace objects with new
+   * versions and tag names.
+   *
+   * @param workspaces - Array of workspace configurations
+   * @returns Updated workspace configurations
+   *
+   * @example
+   * ```typescript
+   * const workspaces = [
+   *   { name: 'pkg-a', path: 'packages/a', version: '1.0.0' }
+   * ];
+   *
+   * const updated = plugin.mergeWorkspaces(workspaces);
+   * // [
+   * //   {
+   * //     name: 'pkg-a',
+   * //     path: 'packages/a',
+   * //     version: '1.1.0',  // Updated version
+   * //     tagName: 'pkg-a@1.1.0'
+   * //   }
+   * // ]
+   * ```
+   */
   mergeWorkspaces(workspaces) {
     return workspaces.map((workspace) => {
       const newPackgeJson = WorkspaceCreator.toWorkspace(
@@ -4015,6 +5999,25 @@ var Changelog = class extends ScriptPlugin3 {
       return newWorkspace;
     });
   }
+  /**
+   * Main plugin execution hook
+   *
+   * Generates changelogs for all workspaces in parallel and updates
+   * the context with the results.
+   *
+   * Process:
+   * 1. Generate changelogs for each workspace
+   * 2. Update context with new workspace information
+   *
+   * @param _context - Execution context
+   *
+   * @example
+   * ```typescript
+   * const plugin = new Changelog(context, {});
+   * await plugin.onExec(execContext);
+   * // Generates changelogs for all workspaces
+   * ```
+   */
   async onExec(_context) {
     const workspaces = await this.step({
       label: "Generate Changelogs",
@@ -4026,6 +6029,28 @@ var Changelog = class extends ScriptPlugin3 {
     });
     this.context.setWorkspaces(workspaces);
   }
+  /**
+   * Success hook after plugin execution
+   *
+   * Handles post-changelog generation tasks:
+   * 1. Creates changeset files (if not skipped)
+   * 2. Updates package versions
+   * 3. Restores unchanged packages (if configured)
+   * 4. Updates workspace information
+   *
+   * @example
+   * ```typescript
+   * const plugin = new Changelog(context, {
+   *   skipChangeset: false,
+   *   ignoreNonUpdatedPackages: true
+   * });
+   *
+   * await plugin.onSuccess();
+   * // - Creates changeset files
+   * // - Updates versions
+   * // - Restores unchanged packages
+   * ```
+   */
   async onSuccess() {
     const workspaces = this.context.workspaces;
     if (!this.getConfig("skipChangeset")) {
@@ -4049,6 +6074,25 @@ var Changelog = class extends ScriptPlugin3 {
     this.logger.debug("new workspaces", newWorkspaces);
     this.context.setWorkspaces(newWorkspaces);
   }
+  /**
+   * Restores unchanged packages to their original state
+   *
+   * When ignoreNonUpdatedPackages is enabled, this method:
+   * 1. Identifies packages without changes
+   * 2. Uses git restore to revert them to original state
+   *
+   * @example
+   * ```typescript
+   * // With changed and unchanged packages
+   * context.options.workspaces = {
+   *   packages: ['pkg-a', 'pkg-b', 'pkg-c'],
+   *   changedPaths: ['pkg-a', 'pkg-b']
+   * };
+   *
+   * await plugin.restoreIgnorePackages();
+   * // Restores 'pkg-c' to original state
+   * ```
+   */
   async restoreIgnorePackages() {
     const { changedPaths = [], packages = [] } = this.context.getOptions(
       "workspaces"
@@ -4061,12 +6105,60 @@ var Changelog = class extends ScriptPlugin3 {
       await this.shell.exec(["git", "restore", ...noChangedPackages]);
     }
   }
+  /**
+   * Gets the tag prefix for a workspace
+   *
+   * Formats the configured tag prefix template with workspace
+   * information. Used for generating Git tag names.
+   *
+   * @param workspace - Workspace configuration
+   * @returns Formatted tag prefix
+   *
+   * @example
+   * ```typescript
+   * const workspace = {
+   *   name: 'pkg-a',
+   *   version: '1.0.0'
+   * };
+   *
+   * const prefix = plugin.getTagPrefix(workspace);
+   * // With default template: 'pkg-a'
+   * // With custom template: 'v1.0.0'
+   * ```
+   */
   getTagPrefix(workspace) {
     return Shell5.format(
       this.getConfig("tagPrefix"),
       workspace
     );
   }
+  /**
+   * Generates a changelog for a workspace
+   *
+   * Creates a changelog by:
+   * 1. Getting the appropriate tag name
+   * 2. Retrieving commits since last tag
+   * 3. Formatting commits into changelog entries
+   *
+   * @param workspace - Workspace configuration
+   * @returns Updated workspace with changelog
+   *
+   * @example
+   * ```typescript
+   * const workspace = {
+   *   name: 'pkg-a',
+   *   path: 'packages/a',
+   *   version: '1.0.0'
+   * };
+   *
+   * const updated = await plugin.generateChangelog(workspace);
+   * // {
+   * //   ...workspace,
+   * //   lastTag: 'pkg-a@1.0.0',
+   * //   changelog: '- feat: new feature\n- fix: bug fix'
+   * // }
+   * ```
+   */
   async generateChangelog(workspace) {
     let tagName = await this.getTagName(workspace);
     if (workspace.lastTag) {
@@ -4092,6 +6184,32 @@ var Changelog = class extends ScriptPlugin3 {
       changelog: changelog.join("\n")
     };
   }
+  /**
+   * Generates a tag name for a workspace
+   *
+   * Uses the configured tag template to generate a tag name
+   * for the workspace. Handles errors by providing a fallback.
+   *
+   * @param workspace - Workspace configuration
+   * @returns Generated tag name
+   *
+   * @example
+   * ```typescript
+   * // With default template
+   * const tag = plugin.generateTagName({
+   *   name: 'pkg-a',
+   *   version: '1.0.0'
+   * });
+   * // 'pkg-a@1.0.0'
+   *
+   * // With error (fallback)
+   * const tag = plugin.generateTagName({
+   *   name: 'pkg-a'
+   * });
+   * // 'pkg-a-v0.0.0'
+   * ```
+   * @private
+   */
   generateTagName(workspace) {
     try {
       const tagTemplate = this.getConfig("tagTemplate");
@@ -4104,6 +6222,38 @@ var Changelog = class extends ScriptPlugin3 {
       return `${workspace.name}-v0.0.0`;
     }
   }
+  /**
+   * Gets the appropriate tag name for a workspace
+   *
+   * Attempts to find the latest tag for the workspace, falling back
+   * to generating a new tag if none exists. Uses git commands to
+   * find and sort tags by creation date.
+   *
+   * Process:
+   * 1. Generate current tag pattern
+   * 2. Search for existing tags matching pattern
+   * 3. Return latest tag or generate new one
+   *
+   * @param workspace - Workspace configuration
+   * @returns Promise resolving to tag name
+   *
+   * @example
+   * ```typescript
+   * // With existing tags
+   * const tag = await plugin.getTagName({
+   *   name: 'pkg-a',
+   *   version: '1.0.0'
+   * });
+   * // Returns latest matching tag: 'pkg-a@0.9.0'
+   *
+   * // Without existing tags
+   * const tag = await plugin.getTagName({
+   *   name: 'pkg-b',
+   *   version: '1.0.0'
+   * });
+   * // Returns new tag: 'pkg-b@1.0.0'
+   * ```
+   */
   async getTagName(workspace) {
     try {
       const currentTagPattern = this.generateTagName(workspace);
@@ -4130,6 +6280,31 @@ var Changelog = class extends ScriptPlugin3 {
       return fallbackTag;
     }
   }
+  /**
+   * Determines the version increment type
+   *
+   * Checks for increment labels in the following order:
+   * 1. 'increment:major' label
+   * 2. 'increment:minor' label
+   * 3. Configured increment value
+   * 4. Default to 'patch'
+   *
+   * @returns Version increment type
+   *
+   * @example
+   * ```typescript
+   * // With labels
+   * context.options.workspaces.changeLabels = ['increment:major'];
+   * plugin.getIncrement(); // 'major'
+   *
+   * // With configuration
+   * const plugin = new Changelog(context, { increment: 'minor' });
+   * plugin.getIncrement(); // 'minor'
+   *
+   * // Default
+   * plugin.getIncrement(); // 'patch'
+   * ```
+   */
   getIncrement() {
     const lables = this.context.getOptions("workspaces.changeLabels");
     if (Array.isArray(lables) && lables.length > 0) {
@@ -4143,6 +6318,43 @@ var Changelog = class extends ScriptPlugin3 {
     const increment = this.getConfig("increment", "patch");
     return increment;
   }
+  /**
+   * Generates a changeset file for a workspace
+   *
+   * Creates a changeset file containing version increment
+   * information and changelog content. Handles dry run mode
+   * and existing files.
+   *
+   * File format:
+   * ```yaml
+   * ---
+   * 'package-name': 'increment-type'
+   * ---
+   *
+   * changelog content
+   * ```
+   *
+   * @param workspace - Workspace configuration
+   *
+   * @example
+   * ```typescript
+   * const workspace = {
+   *   name: 'pkg-a',
+   *   version: '1.0.0',
+   *   changelog: '- feat: new feature'
+   * };
+   *
+   * await plugin.generateChangesetFile(workspace);
+   * // Creates .changeset/pkg-a-1.0.0.md
+   * ```
+   *
+   * @example Dry run
+   * ```typescript
+   * context.dryRun = true;
+   * await plugin.generateChangesetFile(workspace);
+   * // Logs file content without creating file
+   * ```
+   */
   async generateChangesetFile(workspace) {
     const { name, version } = workspace;
     const changesetName = `${name}-${version}`.replace(/[\/\\]/g, "_");
@@ -4176,15 +6388,89 @@ var innerTuples = [
 ];
 var defaultName = "release";
 var ReleaseTask = class {
+  /**
+   * 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 = {}, executor = new AsyncExecutor(), defaultTuples = innerTuples) {
     this.executor = executor;
     this.defaultTuples = defaultTuples;
     this.context = new ReleaseContext(defaultName, options);
   }
+  /**
+   * Release context instance
+   * @protected
+   */
   context;
+  /**
+   * 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() {
     return this.context;
   }
+  /**
+   * 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' })
+   * ]);
+   * ```
+   */
   async usePlugins(externalTuples) {
     externalTuples = externalTuples || this.context.options.plugins || [];
     const plugins = await loaderPluginsFromPluginTuples(this.context, [
@@ -4199,12 +6485,65 @@ var ReleaseTask = class {
     });
     return plugins;
   }
+  /**
+   * Executes the release task
+   *
+   * Internal method that runs the task through the executor.
+   * Preserves the context through the execution chain.
+   *
+   * @returns Execution result
+   * @internal
+   */
   async run() {
     return this.executor.exec(
       this.context,
       (context) => Promise.resolve(context)
     );
   }
+  /**
+   * 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');
+   *   }
+   * }
+   * ```
+   */
   async exec(externalTuples) {
     if (this.context.env.get("FE_RELEASE") === "false") {
       throw new Error("Skip Release");