gitx.do 0.0.1 → 0.0.3

package/dist/refs/branch.d.ts

@@ -1,224 +1,670 @@
 /**
- * Git Branch Operations
+ * @fileoverview Git Branch Operations
  *
- * Handles branch creation, deletion, renaming, listing, and tracking.
- * Works with the RefStorage system for underlying ref management.
+ * This module provides comprehensive branch management functionality including
+ * creation, deletion, renaming, listing, and upstream tracking configuration.
+ *
+ * Branches in Git are simply refs under `refs/heads/` that point to commits.
+ * This module provides a higher-level API that handles the ref manipulation
+ * and adds branch-specific features like tracking information.
+ *
+ * **Key Features**:
+ * - Branch CRUD operations (create, read, update, delete)
+ * - Upstream tracking configuration
+ * - Merge status checking
+ * - Branch name validation and normalization
+ *
+ * @module refs/branch
+ *
+ * @example
+ * ```typescript
+ * import { BranchManager, createBranch, listBranches } from './refs/branch'
+ *
+ * // Using the manager
+ * const manager = new BranchManager(refStorage)
+ * const branch = await manager.createBranch('feature/new-thing', { startPoint: 'main' })
+ *
+ * // Or using convenience functions
+ * const branches = await listBranches(refStorage)
+ * ```
  */
 import { RefStorage } from './storage';
 /**
- * Branch tracking information
+ * Upstream tracking information for a branch.
+ *
+ * @description
+ * Contains information about the remote branch that a local branch tracks,
+ * including ahead/behind counts for synchronization status.
+ *
+ * @example
+ * ```typescript
+ * const tracking: BranchTrackingInfo = {
+ *   remote: 'origin',
+ *   remoteBranch: 'refs/remotes/origin/main',
+ *   ahead: 2,   // Local has 2 commits not on remote
+ *   behind: 0,  // Remote has 0 commits not on local
+ *   gone: false // Remote branch still exists
+ * }
+ * ```
  */
 export interface BranchTrackingInfo {
-    /** Remote name (e.g., 'origin') */
+    /** Remote name (e.g., 'origin', 'upstream') */
     remote: string;
-    /** Remote branch name (e.g., 'refs/remotes/origin/main') */
+    /** Full remote branch ref (e.g., 'refs/remotes/origin/main') */
     remoteBranch: string;
-    /** Number of commits ahead of upstream */
+    /** Number of local commits not pushed to upstream */
     ahead: number;
-    /** Number of commits behind upstream */
+    /** Number of upstream commits not pulled locally */
     behind: number;
-    /** Whether the branch is gone from remote */
+    /** True if the remote branch has been deleted */
     gone: boolean;
 }
 /**
- * Branch information
+ * Complete branch information.
+ *
+ * @description
+ * Represents a Git branch with all associated metadata including
+ * current status, tracking info, and optional commit details.
+ *
+ * @example
+ * ```typescript
+ * const branch: Branch = {
+ *   name: 'feature/auth',
+ *   ref: 'refs/heads/feature/auth',
+ *   sha: 'abc123...',
+ *   isCurrent: true,
+ *   isRemote: false,
+ *   tracking: {
+ *     remote: 'origin',
+ *     remoteBranch: 'refs/remotes/origin/feature/auth',
+ *     ahead: 1,
+ *     behind: 0,
+ *     gone: false
+ *   }
+ * }
+ * ```
  */
 export interface Branch {
-    /** Short branch name (e.g., 'main', 'feature/foo') */
+    /** Short branch name without refs/heads/ prefix (e.g., 'main', 'feature/foo') */
     name: string;
     /** Full ref name (e.g., 'refs/heads/main') */
     ref: string;
     /** SHA-1 of the commit this branch points to */
     sha: string;
-    /** Whether this is the current branch (HEAD points to it) */
+    /** True if this is the current branch (HEAD points to it) */
     isCurrent: boolean;
-    /** Whether this is a remote tracking branch */
+    /** True if this is a remote tracking branch (refs/remotes/) */
     isRemote: boolean;
-    /** Tracking information if the branch tracks an upstream */
+    /** Upstream tracking information (if configured) */
     tracking?: BranchTrackingInfo;
-    /** Last commit message (optional) */
+    /** Subject line of the last commit (optional, for display) */
     lastCommitMessage?: string;
-    /** Last commit author (optional) */
+    /** Author name of the last commit (optional, for display) */
     lastCommitAuthor?: string;
-    /** Last commit date (optional) */
+    /** Date of the last commit (optional, for sorting/display) */
     lastCommitDate?: Date;
 }
 /**
- * Options for creating a branch
+ * Options for creating a new branch.
+ *
+ * @description
+ * Controls branch creation behavior including start point,
+ * force overwrite, and tracking configuration.
  */
 export interface CreateBranchOptions {
-    /** Start point (SHA, branch name, or ref) - defaults to HEAD */
+    /**
+     * Starting point for the new branch.
+     * Can be a SHA, branch name, or ref. Defaults to HEAD.
+     */
     startPoint?: string;
-    /** Force creation even if branch exists (overwrite) */
+    /** If true, overwrite existing branch with same name */
     force?: boolean;
-    /** Set up tracking for the new branch */
+    /**
+     * Configure upstream tracking.
+     * - `true`: Track the startPoint if it's a remote branch
+     * - `string`: Explicit upstream ref to track
+     * - `false`/undefined: No tracking
+     */
     track?: boolean | string;
-    /** Don't actually create the branch, just validate */
+    /** If true, validate but don't actually create */
     dryRun?: boolean;
 }
 /**
- * Options for deleting a branch
+ * Options for deleting a branch.
  */
 export interface DeleteBranchOptions {
-    /** Force delete even if not fully merged */
+    /** If true, delete even if not fully merged */
     force?: boolean;
-    /** Remote branch to delete (for remote tracking branches) */
+    /** Remote name for deleting remote tracking branches */
     remote?: string;
-    /** Don't actually delete, just validate */
+    /** If true, validate but don't actually delete */
     dryRun?: boolean;
 }
 /**
- * Options for renaming a branch
+ * Options for renaming a branch.
  */
 export interface RenameBranchOptions {
-    /** Force rename even if target exists (overwrite) */
+    /** If true, overwrite target if it exists */
     force?: boolean;
-    /** Don't actually rename, just validate */
+    /** If true, validate but don't actually rename */
     dryRun?: boolean;
 }
 /**
- * Options for listing branches
+ * Options for listing branches.
+ *
+ * @description
+ * Provides extensive filtering, sorting, and inclusion options
+ * for branch listing operations.
  */
 export interface ListBranchesOptions {
-    /** Include remote tracking branches */
+    /** Include remote tracking branches (refs/remotes/) */
     includeRemotes?: boolean;
     /** Only list remote tracking branches */
     remotesOnly?: boolean;
-    /** Pattern to filter branches (glob-style) */
+    /** Filter pattern (glob-style, e.g., 'feature/*') */
     pattern?: string;
-    /** Sort by (name, committerdate, authordate, etc.) */
+    /** Sort by field */
     sortBy?: 'name' | 'committerdate' | 'authordate';
-    /** Sort order */
+    /** Sort direction */
     sortOrder?: 'asc' | 'desc';
-    /** Include tracking info (slower) */
+    /** Include tracking info (slower - requires extra lookups) */
     includeTracking?: boolean;
-    /** Include commit info (slower) */
+    /** Include last commit info (slower - requires object access) */
     includeCommitInfo?: boolean;
-    /** Merged into this ref (filter only merged branches) */
+    /** Only show branches merged into this ref */
     mergedInto?: string;
-    /** Not merged into this ref (filter only unmerged branches) */
+    /** Only show branches NOT merged into this ref */
     notMergedInto?: string;
-    /** Only show branches that contain this commit */
+    /** Only show branches containing this commit */
     contains?: string;
-    /** Only show branches that don't contain this commit */
+    /** Only show branches NOT containing this commit */
     noContains?: string;
 }
 /**
- * Options for setting upstream
+ * Options for setting upstream tracking.
  */
 export interface SetUpstreamOptions {
-    /** Remote name */
+    /** Remote name (e.g., 'origin') */
     remote?: string;
-    /** Remote branch name */
+    /** Remote branch name (without refs/remotes/ prefix) */
     remoteBranch?: string;
-    /** Unset the upstream (remove tracking) */
+    /** If true, remove upstream tracking */
     unset?: boolean;
 }
 /**
- * Result of branch validation
+ * Result of branch name validation.
+ *
+ * @description
+ * Provides detailed validation result including the normalized
+ * form of the branch name if valid.
  */
 export interface BranchValidationResult {
-    /** Whether the name is valid */
+    /** Whether the name passes validation */
     valid: boolean;
-    /** Error message if invalid */
+    /** Error message explaining why validation failed */
     error?: string;
-    /** Normalized branch name */
+    /** Normalized branch name (cleaned up form) */
     normalized?: string;
 }
 /**
- * Error thrown when a branch operation fails
+ * Error thrown when a branch operation fails.
+ *
+ * @description
+ * Provides structured error information with error code
+ * for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await manager.deleteBranch('main')
+ * } catch (e) {
+ *   if (e instanceof BranchError) {
+ *     if (e.code === 'CANNOT_DELETE_CURRENT') {
+ *       console.log('Cannot delete the branch you are on')
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare class BranchError extends Error {
     readonly code: BranchErrorCode;
     readonly branchName?: string | undefined;
+    /**
+     * Create a new BranchError.
+     *
+     * @param message - Human-readable error description
+     * @param code - Error code for programmatic handling
+     * @param branchName - The branch that caused the error
+     */
     constructor(message: string, code: BranchErrorCode, branchName?: string | undefined);
 }
+/**
+ * Error codes for branch operations.
+ *
+ * @description
+ * - `NOT_FOUND`: Branch doesn't exist
+ * - `ALREADY_EXISTS`: Branch already exists (when creating)
+ * - `INVALID_NAME`: Branch name fails validation
+ * - `NOT_FULLY_MERGED`: Branch has unmerged commits (when deleting)
+ * - `CANNOT_DELETE_CURRENT`: Attempting to delete checked-out branch
+ * - `CHECKOUT_CONFLICT`: Working tree has uncommitted changes
+ * - `INVALID_START_POINT`: Start point doesn't resolve to valid commit
+ * - `NO_UPSTREAM`: Branch has no upstream configured
+ * - `DETACHED_HEAD`: HEAD is detached (no current branch)
+ */
 export type BranchErrorCode = 'NOT_FOUND' | 'ALREADY_EXISTS' | 'INVALID_NAME' | 'NOT_FULLY_MERGED' | 'CANNOT_DELETE_CURRENT' | 'CHECKOUT_CONFLICT' | 'INVALID_START_POINT' | 'NO_UPSTREAM' | 'DETACHED_HEAD';
 /**
- * Branch manager for performing branch operations
+ * Branch manager for performing Git branch operations.
+ *
+ * @description
+ * Provides a comprehensive API for branch management. Uses RefStorage
+ * internally for ref manipulation.
+ *
+ * Note: Many methods are currently stubs (TODO) and will throw 'Not implemented'.
+ * These will be implemented in the GREEN phase of TDD development.
+ *
+ * @example
+ * ```typescript
+ * const manager = new BranchManager(refStorage)
+ *
+ * // Create a feature branch
+ * const branch = await manager.createBranch('feature/auth', {
+ *   startPoint: 'main',
+ *   track: true
+ * })
+ *
+ * // List all branches
+ * const branches = await manager.listBranches({ includeRemotes: true })
+ *
+ * // Delete a merged branch
+ * await manager.deleteBranch('feature/auth')
+ * ```
  */
 export declare class BranchManager {
+    /**
+     * Create a new BranchManager.
+     *
+     * @param storage - RefStorage instance for ref operations
+     */
     constructor(storage: RefStorage);
     /**
-     * Create a new branch
+     * Create a new branch.
+     *
+     * @description
+     * Creates a new branch pointing to the specified start point.
+     * By default, the branch starts at HEAD.
+     *
+     * @param name - Branch name (without refs/heads/ prefix)
+     * @param options - Creation options
+     * @returns The created branch
+     * @throws BranchError with code 'INVALID_NAME' if name is invalid
+     * @throws BranchError with code 'ALREADY_EXISTS' if branch exists and not forcing
+     * @throws BranchError with code 'INVALID_START_POINT' if start point is invalid
+     *
+     * @example
+     * ```typescript
+     * // Create from HEAD
+     * const branch = await manager.createBranch('feature')
+     *
+     * // Create from specific commit
+     * const branch = await manager.createBranch('hotfix', { startPoint: 'abc123' })
+     *
+     * // Force overwrite existing
+     * const branch = await manager.createBranch('main', { force: true, startPoint: 'HEAD' })
+     * ```
      */
     createBranch(_name: string, _options?: CreateBranchOptions): Promise<Branch>;
     /**
-     * Delete a branch
+     * Delete a branch.
+     *
+     * @description
+     * Removes a branch ref. By default, refuses to delete unmerged branches.
+     *
+     * @param name - Branch name to delete
+     * @param options - Deletion options
+     * @throws BranchError with code 'NOT_FOUND' if branch doesn't exist
+     * @throws BranchError with code 'CANNOT_DELETE_CURRENT' if branch is checked out
+     * @throws BranchError with code 'NOT_FULLY_MERGED' if branch has unmerged commits
+     *
+     * @example
+     * ```typescript
+     * // Safe delete (only if merged)
+     * await manager.deleteBranch('feature')
+     *
+     * // Force delete
+     * await manager.deleteBranch('experiment', { force: true })
+     * ```
      */
     deleteBranch(_name: string, _options?: DeleteBranchOptions): Promise<void>;
     /**
-     * Rename a branch
+     * Rename a branch.
+     *
+     * @description
+     * Renames a branch, updating the ref name. If the branch is the current
+     * branch, HEAD is updated accordingly.
+     *
+     * @param oldName - Current branch name
+     * @param newName - New branch name
+     * @param options - Rename options
+     * @returns The renamed branch
+     * @throws BranchError with code 'NOT_FOUND' if old branch doesn't exist
+     * @throws BranchError with code 'ALREADY_EXISTS' if new name exists and not forcing
+     * @throws BranchError with code 'INVALID_NAME' if new name is invalid
+     *
+     * @example
+     * ```typescript
+     * const branch = await manager.renameBranch('old-name', 'new-name')
+     * ```
      */
     renameBranch(_oldName: string, _newName: string, _options?: RenameBranchOptions): Promise<Branch>;
     /**
-     * List all branches
+     * List all branches.
+     *
+     * @description
+     * Returns branches matching the specified criteria.
+     * By default, returns only local branches.
+     *
+     * @param options - Listing options
+     * @returns Array of branches matching criteria
+     *
+     * @example
+     * ```typescript
+     * // List local branches
+     * const local = await manager.listBranches()
+     *
+     * // List all branches including remotes
+     * const all = await manager.listBranches({ includeRemotes: true })
+     *
+     * // List merged branches
+     * const merged = await manager.listBranches({ mergedInto: 'main' })
+     * ```
      */
     listBranches(_options?: ListBranchesOptions): Promise<Branch[]>;
     /**
-     * Get the current branch
+     * Get the current branch.
+     *
+     * @description
+     * Returns the branch that HEAD points to, or null if HEAD is detached.
+     *
+     * @returns Current branch or null if detached
+     *
+     * @example
+     * ```typescript
+     * const current = await manager.getCurrentBranch()
+     * if (current) {
+     *   console.log(`On branch: ${current.name}`)
+     * } else {
+     *   console.log('HEAD is detached')
+     * }
+     * ```
      */
     getCurrentBranch(): Promise<Branch | null>;
     /**
-     * Get a specific branch by name
+     * Get a specific branch by name.
+     *
+     * @description
+     * Retrieves branch information for a specific branch.
+     *
+     * @param name - Branch name
+     * @returns Branch info or null if not found
+     *
+     * @example
+     * ```typescript
+     * const branch = await manager.getBranch('main')
+     * if (branch) {
+     *   console.log(`main is at ${branch.sha}`)
+     * }
+     * ```
      */
     getBranch(_name: string): Promise<Branch | null>;
     /**
-     * Check if a branch exists
+     * Check if a branch exists.
+     *
+     * @description
+     * Quick check for branch existence without fetching full info.
+     *
+     * @param name - Branch name
+     * @returns True if branch exists
+     *
+     * @example
+     * ```typescript
+     * if (await manager.branchExists('feature')) {
+     *   console.log('Branch already exists')
+     * }
+     * ```
      */
     branchExists(_name: string): Promise<boolean>;
     /**
-     * Set upstream branch for tracking
+     * Set upstream branch for tracking.
+     *
+     * @description
+     * Configures or removes upstream tracking for a branch.
+     *
+     * @param branchName - Local branch to configure
+     * @param options - Tracking options
+     * @throws BranchError with code 'NOT_FOUND' if branch doesn't exist
+     *
+     * @example
+     * ```typescript
+     * // Set upstream
+     * await manager.setUpstream('feature', {
+     *   remote: 'origin',
+     *   remoteBranch: 'feature'
+     * })
+     *
+     * // Remove upstream
+     * await manager.setUpstream('feature', { unset: true })
+     * ```
      */
     setUpstream(_branchName: string, _options: SetUpstreamOptions): Promise<void>;
     /**
-     * Get tracking info for a branch
+     * Get tracking info for a branch.
+     *
+     * @description
+     * Returns upstream tracking information including ahead/behind counts.
+     *
+     * @param branchName - Branch to check
+     * @returns Tracking info or null if not tracking
+     *
+     * @example
+     * ```typescript
+     * const tracking = await manager.getTrackingInfo('main')
+     * if (tracking) {
+     *   console.log(`${tracking.ahead} ahead, ${tracking.behind} behind ${tracking.remoteBranch}`)
+     * }
+     * ```
      */
     getTrackingInfo(_branchName: string): Promise<BranchTrackingInfo | null>;
     /**
-     * Check if a branch is fully merged into another branch
+     * Check if a branch is fully merged into another branch.
+     *
+     * @description
+     * Determines if all commits on the branch are reachable from the target.
+     *
+     * @param branchName - Branch to check
+     * @param into - Target branch (defaults to current branch)
+     * @returns True if fully merged
+     *
+     * @example
+     * ```typescript
+     * if (await manager.isMerged('feature', 'main')) {
+     *   console.log('Safe to delete feature branch')
+     * }
+     * ```
      */
     isMerged(_branchName: string, _into?: string): Promise<boolean>;
     /**
-     * Force delete an unmerged branch
+     * Force delete an unmerged branch.
+     *
+     * @description
+     * Deletes a branch even if it has unmerged commits. Use with caution
+     * as this can result in lost commits.
+     *
+     * @param name - Branch name to delete
+     * @throws BranchError with code 'NOT_FOUND' if branch doesn't exist
+     * @throws BranchError with code 'CANNOT_DELETE_CURRENT' if branch is checked out
+     *
+     * @example
+     * ```typescript
+     * await manager.forceDeleteBranch('abandoned-feature')
+     * ```
      */
     forceDeleteBranch(_name: string): Promise<void>;
 }
 /**
- * Validate a branch name according to Git rules
- * See: https://git-scm.com/docs/git-check-ref-format
+ * Validate a branch name according to Git rules.
+ *
+ * @description
+ * Checks if a branch name is valid and returns detailed validation results
+ * including the normalized form of the name.
+ *
+ * Note: This is a stub implementation. Full validation will be added in GREEN phase.
+ *
+ * @param name - Branch name to validate
+ * @returns Validation result with valid flag, error message, and normalized name
+ *
+ * @see https://git-scm.com/docs/git-check-ref-format
+ *
+ * @example
+ * ```typescript
+ * const result = validateBranchName('feature/auth')
+ * if (result.valid) {
+ *   console.log(`Valid: ${result.normalized}`)
+ * } else {
+ *   console.log(`Invalid: ${result.error}`)
+ * }
+ * ```
  */
 export declare function validateBranchName(_name: string): BranchValidationResult;
 /**
- * Check if a string is a valid branch name
+ * Check if a string is a valid branch name.
+ *
+ * @description
+ * Simple boolean check for branch name validity.
+ *
+ * @param name - Branch name to check
+ * @returns True if valid
+ *
+ * @example
+ * ```typescript
+ * if (isValidBranchName('feature/new')) {
+ *   // Create the branch
+ * }
+ * ```
  */
 export declare function isValidBranchName(_name: string): boolean;
 /**
- * Normalize a branch name (remove refs/heads/ prefix, etc.)
+ * Normalize a branch name.
+ *
+ * @description
+ * Removes refs/heads/ prefix if present, cleans up the name.
+ *
+ * @param name - Branch name or ref
+ * @returns Normalized short branch name
+ *
+ * @example
+ * ```typescript
+ * normalizeBranchName('refs/heads/main')  // 'main'
+ * normalizeBranchName('main')              // 'main'
+ * ```
  */
 export declare function normalizeBranchName(_name: string): string;
 /**
- * Get the full ref name for a branch
+ * Get the full ref name for a branch.
+ *
+ * @description
+ * Adds refs/heads/ prefix if not present.
+ *
+ * @param name - Short branch name
+ * @returns Full ref name
+ *
+ * @example
+ * ```typescript
+ * getBranchRefName('main')            // 'refs/heads/main'
+ * getBranchRefName('refs/heads/main') // 'refs/heads/main'
+ * ```
  */
 export declare function getBranchRefName(_name: string): string;
 /**
- * Create a new branch (convenience function)
+ * Create a new branch.
+ *
+ * @description
+ * Convenience function that creates a BranchManager and calls createBranch.
+ *
+ * @param storage - RefStorage instance
+ * @param name - Branch name
+ * @param options - Creation options
+ * @returns Created branch
+ *
+ * @example
+ * ```typescript
+ * const branch = await createBranch(storage, 'feature', { startPoint: 'main' })
+ * ```
  */
 export declare function createBranch(_storage: RefStorage, _name: string, _options?: CreateBranchOptions): Promise<Branch>;
 /**
- * Delete a branch (convenience function)
+ * Delete a branch.
+ *
+ * @description
+ * Convenience function that creates a BranchManager and calls deleteBranch.
+ *
+ * @param storage - RefStorage instance
+ * @param name - Branch name to delete
+ * @param options - Deletion options
+ *
+ * @example
+ * ```typescript
+ * await deleteBranch(storage, 'feature', { force: true })
+ * ```
  */
 export declare function deleteBranch(_storage: RefStorage, _name: string, _options?: DeleteBranchOptions): Promise<void>;
 /**
- * Rename a branch (convenience function)
+ * Rename a branch.
+ *
+ * @description
+ * Convenience function that creates a BranchManager and calls renameBranch.
+ *
+ * @param storage - RefStorage instance
+ * @param oldName - Current branch name
+ * @param newName - New branch name
+ * @param options - Rename options
+ * @returns Renamed branch
+ *
+ * @example
+ * ```typescript
+ * const branch = await renameBranch(storage, 'old', 'new')
+ * ```
  */
 export declare function renameBranch(_storage: RefStorage, _oldName: string, _newName: string, _options?: RenameBranchOptions): Promise<Branch>;
 /**
- * List all branches (convenience function)
+ * List all branches.
+ *
+ * @description
+ * Convenience function that creates a BranchManager and calls listBranches.
+ *
+ * @param storage - RefStorage instance
+ * @param options - Listing options
+ * @returns Array of branches
+ *
+ * @example
+ * ```typescript
+ * const branches = await listBranches(storage, { includeRemotes: true })
+ * ```
  */
 export declare function listBranches(_storage: RefStorage, _options?: ListBranchesOptions): Promise<Branch[]>;
 /**
- * Get the current branch (convenience function)
+ * Get the current branch.
+ *
+ * @description
+ * Convenience function that creates a BranchManager and calls getCurrentBranch.
+ *
+ * @param storage - RefStorage instance
+ * @returns Current branch or null if detached
+ *
+ * @example
+ * ```typescript
+ * const current = await getCurrentBranch(storage)
+ * ```
  */
 export declare function getCurrentBranch(_storage: RefStorage): Promise<Branch | null>;
 //# sourceMappingURL=branch.d.ts.map