gitx.do 0.0.1 → 0.0.3

package/dist/refs/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/refs/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,GAAG,EAAE,GAAG,CAAA;IACR,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAA;IACX,+CAA+C;IAC/C,KAAK,EAAE,GAAG,EAAE,CAAA;CACb;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,YAAY;aAClB,OAAO,CAAC,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC;AAED,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,gBAAgB,GAChB,cAAc,GACd,QAAQ,GACR,UAAU,GACV,cAAc,GACd,oBAAoB,GACpB,aAAa,CAAA;AAEjB;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,uBAAuB;IACvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,kCAAkC;IAClC,MAAM,IAAI,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAA;IAC1C,kBAAkB;IAClB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,mBAAmB;IACnB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAC1C,8BAA8B;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7D,uBAAuB;IACvB,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC9C,wBAAwB;IACxB,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA4DpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWlF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAKpD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqCpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAWrE;AAED;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAE9C;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAO/C;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAwCjF;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC;IAoDvF;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B3E;;OAEG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IA0BzD;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAIpC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAIhC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ7B;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAWlE;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAKxC;;OAEG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAqBnE;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAInE;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,GAAG,CAAC,CAEd;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,GAAG,EAAE,CAAC,CAEhB"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/refs/storage.ts"],"names":[],"mappings":"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"}

package/dist/refs/storage.js

@@ -1,15 +1,68 @@
 /**
- * Git Reference Storage
+ * @fileoverview Git Reference Storage System
  *
- * Handles storage and resolution of Git refs (branches, tags, HEAD).
- * Supports both loose refs and packed refs formats.
+ * This module provides a complete implementation of Git reference management,
+ * including branches, tags, HEAD, and symbolic refs. It supports both loose refs
+ * (individual files) and packed refs (consolidated file).
+ *
+ * **Key Concepts**:
+ * - **Direct refs**: Point directly to a SHA-1 hash (e.g., branch pointing to commit)
+ * - **Symbolic refs**: Point to another ref (e.g., HEAD -> refs/heads/main)
+ * - **Loose refs**: Individual ref files in .git/refs/
+ * - **Packed refs**: Consolidated refs in .git/packed-refs for efficiency
+ *
+ * @module refs/storage
+ *
+ * @example
+ * ```typescript
+ * import { RefStorage, isValidRefName, isValidSha } from './refs/storage'
+ *
+ * // Create storage with backend
+ * const storage = new RefStorage(backend)
+ *
+ * // Resolve HEAD to get current commit
+ * const resolved = await storage.resolveRef('HEAD')
+ * console.log(`Current commit: ${resolved.sha}`)
+ *
+ * // Update a branch
+ * await storage.updateRef('refs/heads/feature', newCommitSha, { create: true })
+ *
+ * // List all branches
+ * const branches = await storage.listBranches()
+ * ```
  */
 /**
- * Error thrown when a ref operation fails
+ * Error thrown when a ref operation fails.
+ *
+ * @description
+ * Provides structured error information including error code
+ * and the ref name that caused the error.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await storage.updateRef('refs/heads/main', sha)
+ * } catch (e) {
+ *   if (e instanceof RefError) {
+ *     switch (e.code) {
+ *       case 'NOT_FOUND': // Ref doesn't exist
+ *       case 'CONFLICT':  // CAS failed
+ *       case 'LOCKED':    // Ref is locked
+ *     }
+ *   }
+ * }
+ * ```
  */
 export class RefError extends Error {
     code;
     refName;
+    /**
+     * Create a new RefError.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param refName - The ref that caused the error (optional)
+     */
     constructor(message, code, refName) {
         super(message);
         this.code = code;
@@ -17,9 +70,37 @@ export class RefError extends Error {
         this.name = 'RefError';
     }
 }
+// ============================================================================
+// Validation Functions
+// ============================================================================
 /**
- * Validate a ref name according to Git rules
- * See: https://git-scm.com/docs/git-check-ref-format
+ * Validate a ref name according to Git rules.
+ *
+ * @description
+ * Git has specific rules for valid ref names. This function implements
+ * the validation from `git check-ref-format`.
+ *
+ * **Rules**:
+ * - Cannot be empty or just '@'
+ * - Cannot end with '/' or '.lock'
+ * - Cannot contain '..', '@{', control chars, space, ~, ^, :, ?, *, [, \
+ * - Components cannot start or end with '.'
+ * - HEAD is always valid
+ *
+ * @param name - Ref name to validate
+ * @returns True if the name is valid
+ *
+ * @see https://git-scm.com/docs/git-check-ref-format
+ *
+ * @example
+ * ```typescript
+ * isValidRefName('refs/heads/main')       // true
+ * isValidRefName('refs/heads/feature/x')  // true
+ * isValidRefName('HEAD')                   // true
+ * isValidRefName('refs/heads/../main')    // false (contains ..)
+ * isValidRefName('refs/heads/.hidden')    // false (component starts with .)
+ * isValidRefName('refs/heads/foo.lock')   // false (ends with .lock)
+ * ```
  */
 export function isValidRefName(name) {
     // HEAD is always valid
@@ -74,7 +155,22 @@ export function isValidRefName(name) {
     return true;
 }
 /**
- * Validate a SHA-1 hash
+ * Validate a SHA-1 hash string.
+ *
+ * @description
+ * SHA-1 hashes must be exactly 40 hexadecimal characters.
+ * This validates the format, not whether the object exists.
+ *
+ * @param sha - SHA string to validate
+ * @returns True if the string is a valid SHA-1 format
+ *
+ * @example
+ * ```typescript
+ * isValidSha('abc123def456789...')  // true (if 40 hex chars)
+ * isValidSha('abc123')              // false (too short)
+ * isValidSha('xyz...')              // false (invalid hex)
+ * isValidSha(null)                  // false
+ * ```
  */
 export function isValidSha(sha) {
     // Must be exactly 40 characters
@@ -84,8 +180,28 @@ export function isValidSha(sha) {
     // Must be valid hex
     return /^[0-9a-fA-F]{40}$/.test(sha);
 }
+// ============================================================================
+// Parsing and Serialization Functions
+// ============================================================================
 /**
- * Parse a ref file content
+ * Parse ref file content into type and target.
+ *
+ * @description
+ * Ref files either contain a SHA directly or "ref: <target>" for symbolic refs.
+ *
+ * @param content - Raw ref file content
+ * @returns Parsed type and target
+ *
+ * @example
+ * ```typescript
+ * // Direct ref
+ * parseRefContent('abc123def456...\n')
+ * // => { type: 'direct', target: 'abc123def456...' }
+ *
+ * // Symbolic ref
+ * parseRefContent('ref: refs/heads/main\n')
+ * // => { type: 'symbolic', target: 'refs/heads/main' }
+ * ```
  */
 export function parseRefContent(content) {
     const trimmed = content.trim();
@@ -98,7 +214,22 @@ export function parseRefContent(content) {
     return { type: 'direct', target: trimmed };
 }
 /**
- * Serialize a ref to file content
+ * Serialize a ref to file content format.
+ *
+ * @description
+ * Converts a Ref object to the string format stored in ref files.
+ *
+ * @param ref - Ref to serialize
+ * @returns File content string (with trailing newline)
+ *
+ * @example
+ * ```typescript
+ * serializeRefContent({ name: 'HEAD', target: 'refs/heads/main', type: 'symbolic' })
+ * // => 'ref: refs/heads/main\n'
+ *
+ * serializeRefContent({ name: 'refs/heads/main', target: 'abc123...', type: 'direct' })
+ * // => 'abc123...\n'
+ * ```
  */
 export function serializeRefContent(ref) {
     if (ref.type === 'symbolic') {
@@ -107,7 +238,26 @@ export function serializeRefContent(ref) {
     return `${ref.target}\n`;
 }
 /**
- * Parse packed-refs file content
+ * Parse packed-refs file content.
+ *
+ * @description
+ * The packed-refs file contains multiple refs in a space-efficient format.
+ * Format: "<sha> <refname>" on each line, with optional comments (#) and
+ * peeled entries (^sha for annotated tags).
+ *
+ * @param content - Raw packed-refs file content
+ * @returns Map of ref names to SHA values
+ *
+ * @example
+ * ```typescript
+ * const content = `# pack-refs with: peeled fully-peeled sorted
+ * abc123 refs/heads/main
+ * def456 refs/tags/v1.0.0
+ * ^aaa111
+ * `
+ * const refs = parsePackedRefs(content)
+ * // Map { 'refs/heads/main' => 'abc123', 'refs/tags/v1.0.0' => 'def456' }
+ * ```
  */
 export function parsePackedRefs(content) {
     const refs = new Map();
@@ -140,7 +290,24 @@ export function parsePackedRefs(content) {
     return refs;
 }
 /**
- * Serialize refs to packed-refs format
+ * Serialize refs to packed-refs file format.
+ *
+ * @description
+ * Creates the content for a packed-refs file from a map of refs.
+ * Refs are sorted alphabetically for consistency.
+ *
+ * @param refs - Map of ref names to SHA values
+ * @returns Packed-refs file content
+ *
+ * @example
+ * ```typescript
+ * const refs = new Map([
+ *   ['refs/heads/main', 'abc123...'],
+ *   ['refs/tags/v1.0.0', 'def456...']
+ * ])
+ * const content = serializePackedRefs(refs)
+ * // '# pack-refs with: peeled fully-peeled sorted\nabc123... refs/heads/main\n...'
+ * ```
  */
 export function serializePackedRefs(refs) {
     const lines = ['# pack-refs with: peeled fully-peeled sorted'];
@@ -151,16 +318,62 @@ export function serializePackedRefs(refs) {
     }
     return lines.join('\n') + '\n';
 }
+// ============================================================================
+// RefStorage Class
+// ============================================================================
 /**
- * Ref storage implementation
+ * Reference storage manager.
+ *
+ * @description
+ * Provides a high-level API for managing Git references. Handles ref
+ * resolution, updates with locking, symbolic refs, and packed refs.
+ *
+ * @example
+ * ```typescript
+ * const storage = new RefStorage(myBackend)
+ *
+ * // Get current branch
+ * const head = await storage.getHead()
+ * if (head.type === 'symbolic') {
+ *   console.log(`On branch: ${head.target}`)
+ * }
+ *
+ * // Resolve to SHA
+ * const resolved = await storage.resolveRef('HEAD')
+ * console.log(`Current commit: ${resolved.sha}`)
+ *
+ * // Create a branch
+ * await storage.updateRef('refs/heads/feature', commitSha, { create: true })
+ * ```
  */
 export class RefStorage {
     backend;
+    /**
+     * Create a new RefStorage instance.
+     *
+     * @param backend - Storage backend for persistence
+     */
     constructor(backend) {
         this.backend = backend;
     }
     /**
-     * Get a ref by name
+     * Get a ref by name.
+     *
+     * @description
+     * Retrieves a ref without resolving symbolic refs.
+     * Use `resolveRef` to follow symbolic refs to their final target.
+     *
+     * @param name - Full ref name
+     * @returns The ref or null if not found
+     * @throws Error if backend doesn't support readRef
+     *
+     * @example
+     * ```typescript
+     * const head = await storage.getRef('HEAD')
+     * if (head && head.type === 'symbolic') {
+     *   console.log(`HEAD points to ${head.target}`)
+     * }
+     * ```
      */
     async getRef(name) {
         if (!this.backend.readRef) {
@@ -169,7 +382,26 @@ export class RefStorage {
         return this.backend.readRef(name);
     }
     /**
-     * Resolve a ref to its final SHA target
+     * Resolve a ref to its final SHA target.
+     *
+     * @description
+     * Follows symbolic refs until reaching a direct ref, then returns
+     * the SHA and the chain of refs followed.
+     *
+     * @param name - Ref name to resolve
+     * @param options - Resolution options (maxDepth)
+     * @returns Resolved ref with SHA and chain
+     * @throws RefError with code 'NOT_FOUND' if ref doesn't exist
+     * @throws RefError with code 'CIRCULAR_REF' if circular reference detected
+     * @throws RefError with code 'MAX_DEPTH_EXCEEDED' if too many redirects
+     *
+     * @example
+     * ```typescript
+     * const resolved = await storage.resolveRef('HEAD')
+     * console.log(`SHA: ${resolved.sha}`)
+     * console.log(`Chain: ${resolved.chain.map(r => r.name).join(' -> ')}`)
+     * // Chain: HEAD -> refs/heads/main
+     * ```
      */
     async resolveRef(name, options) {
         const maxDepth = options?.maxDepth ?? 10;
@@ -203,10 +435,36 @@ export class RefStorage {
         throw new RefError(`Max ref resolution depth exceeded: ${maxDepth}`, 'MAX_DEPTH_EXCEEDED', name);
     }
     /**
-     * Update or create a ref
+     * Update or create a ref.
+     *
+     * @description
+     * Creates a new ref or updates an existing one. Supports atomic
+     * compare-and-swap operations via oldValue option.
      *
      * Note: For atomic operations, callers can acquire a lock via acquireLock()
      * and pass it via options.lock to avoid double-locking.
+     *
+     * @param name - Full ref name
+     * @param target - SHA-1 hash to point to
+     * @param options - Update options (create, oldValue, force, lock)
+     * @returns The updated/created ref
+     * @throws RefError with code 'INVALID_NAME' if ref name is invalid
+     * @throws RefError with code 'INVALID_SHA' if SHA format is invalid
+     * @throws RefError with code 'ALREADY_EXISTS' if creating and ref exists
+     * @throws RefError with code 'CONFLICT' if oldValue doesn't match
+     * @throws RefError with code 'NOT_FOUND' if ref doesn't exist and not creating
+     *
+     * @example
+     * ```typescript
+     * // Create a new branch
+     * await storage.updateRef('refs/heads/feature', sha, { create: true })
+     *
+     * // Atomic update (fails if someone else modified)
+     * await storage.updateRef('refs/heads/main', newSha, { oldValue: currentSha })
+     *
+     * // Force update (skips fast-forward check)
+     * await storage.updateRef('refs/heads/main', sha, { force: true })
+     * ```
      */
     async updateRef(name, target, options) {
         // Validate ref name
@@ -257,7 +515,25 @@ export class RefStorage {
         }
     }
     /**
-     * Delete a ref
+     * Delete a ref.
+     *
+     * @description
+     * Removes a ref from storage. HEAD cannot be deleted.
+     *
+     * @param name - Full ref name to delete
+     * @param options - Delete options (oldValue for CAS)
+     * @returns True if deleted, false if ref didn't exist
+     * @throws RefError with code 'INVALID_NAME' for HEAD or invalid names
+     * @throws RefError with code 'CONFLICT' if oldValue doesn't match
+     *
+     * @example
+     * ```typescript
+     * // Simple delete
+     * const deleted = await storage.deleteRef('refs/heads/old-branch')
+     *
+     * // Atomic delete (only if value matches)
+     * await storage.deleteRef('refs/heads/feature', { oldValue: expectedSha })
+     * ```
      */
     async deleteRef(name, options) {
         // Cannot delete HEAD
@@ -281,7 +557,26 @@ export class RefStorage {
         return this.backend.deleteRef(name);
     }
     /**
-     * List refs matching a pattern
+     * List refs matching a pattern.
+     *
+     * @description
+     * Returns refs filtered by pattern and options.
+     * By default, excludes HEAD and symbolic refs.
+     *
+     * @param options - Listing options (pattern, includeHead, includeSymbolic)
+     * @returns Array of matching refs
+     *
+     * @example
+     * ```typescript
+     * // List all refs
+     * const all = await storage.listRefs()
+     *
+     * // List branches only
+     * const branches = await storage.listRefs({ pattern: 'refs/heads/*' })
+     *
+     * // Include HEAD
+     * const withHead = await storage.listRefs({ includeHead: true })
+     * ```
      */
     async listRefs(options) {
         let refs = await this.backend.listRefs(options?.pattern);
@@ -307,19 +602,61 @@ export class RefStorage {
         return refs;
     }
     /**
-     * List all branches
+     * List all branches.
+     *
+     * @description
+     * Convenience method to list refs under refs/heads/.
+     *
+     * @returns Array of branch refs
+     *
+     * @example
+     * ```typescript
+     * const branches = await storage.listBranches()
+     * for (const branch of branches) {
+     *   console.log(branch.name.replace('refs/heads/', ''))
+     * }
+     * ```
      */
     async listBranches() {
         return this.listRefs({ pattern: 'refs/heads/*' });
     }
     /**
-     * List all tags
+     * List all tags.
+     *
+     * @description
+     * Convenience method to list refs under refs/tags/.
+     *
+     * @returns Array of tag refs
+     *
+     * @example
+     * ```typescript
+     * const tags = await storage.listTags()
+     * for (const tag of tags) {
+     *   console.log(tag.name.replace('refs/tags/', ''))
+     * }
+     * ```
      */
     async listTags() {
         return this.listRefs({ pattern: 'refs/tags/*' });
     }
     /**
-     * Get HEAD ref
+     * Get HEAD ref.
+     *
+     * @description
+     * Returns the HEAD ref. Every repository should have HEAD.
+     *
+     * @returns The HEAD ref
+     * @throws RefError with code 'NOT_FOUND' if HEAD doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const head = await storage.getHead()
+     * if (head.type === 'symbolic') {
+     *   console.log(`On branch: ${head.target}`)
+     * } else {
+     *   console.log(`Detached at: ${head.target}`)
+     * }
+     * ```
      */
     async getHead() {
         const head = await this.getRef('HEAD');
@@ -329,7 +666,23 @@ export class RefStorage {
         return head;
     }
     /**
-     * Update HEAD (can be symbolic or detached)
+     * Update HEAD (can be symbolic or detached).
+     *
+     * @description
+     * Sets HEAD to point to a branch (symbolic) or commit (detached).
+     *
+     * @param target - Branch ref name (symbolic) or SHA (detached)
+     * @param symbolic - If true, create symbolic ref; if false, direct ref
+     * @returns The updated HEAD ref
+     *
+     * @example
+     * ```typescript
+     * // Switch to branch
+     * await storage.updateHead('refs/heads/main', true)
+     *
+     * // Detach HEAD at commit
+     * await storage.updateHead(commitSha, false)
+     * ```
      */
     async updateHead(target, symbolic) {
         const ref = {
@@ -341,14 +694,43 @@ export class RefStorage {
         return ref;
     }
     /**
-     * Check if HEAD is detached
+     * Check if HEAD is detached.
+     *
+     * @description
+     * HEAD is detached when it points directly to a commit SHA
+     * rather than symbolically to a branch.
+     *
+     * @returns True if HEAD is detached (points to SHA directly)
+     *
+     * @example
+     * ```typescript
+     * if (await storage.isHeadDetached()) {
+     *   console.log('You are in detached HEAD state')
+     * }
+     * ```
      */
     async isHeadDetached() {
         const head = await this.getHead();
         return head.type === 'direct';
     }
     /**
-     * Create a symbolic ref
+     * Create a symbolic ref.
+     *
+     * @description
+     * Creates a ref that points to another ref name (not a SHA).
+     * Used primarily for HEAD pointing to a branch.
+     *
+     * @param name - Name for the new symbolic ref
+     * @param target - Target ref name (not SHA)
+     * @returns The created symbolic ref
+     * @throws RefError with code 'INVALID_NAME' if name is invalid
+     * @throws RefError with code 'CIRCULAR_REF' if name equals target
+     *
+     * @example
+     * ```typescript
+     * // Make HEAD point to main branch
+     * await storage.createSymbolicRef('HEAD', 'refs/heads/main')
+     * ```
      */
     async createSymbolicRef(name, target) {
         // Validate ref name
@@ -368,13 +750,43 @@ export class RefStorage {
         return ref;
     }
     /**
-     * Acquire a lock for updating a ref
+     * Acquire a lock for updating a ref.
+     *
+     * @description
+     * Acquires an exclusive lock on a ref. Use this for complex operations
+     * that need to read-modify-write atomically.
+     *
+     * @param name - Full ref name to lock
+     * @param timeout - Lock acquisition timeout in milliseconds
+     * @returns Lock handle - must be released when done
+     *
+     * @example
+     * ```typescript
+     * const lock = await storage.acquireLock('refs/heads/main', 5000)
+     * try {
+     *   // Perform atomic operations
+     *   await storage.updateRef('refs/heads/main', sha, { lock })
+     * } finally {
+     *   await lock.release()
+     * }
+     * ```
      */
     async acquireLock(name, timeout) {
         return this.backend.acquireLock(name, timeout);
     }
     /**
-     * Pack loose refs into packed-refs file
+     * Pack loose refs into packed-refs file.
+     *
+     * @description
+     * Consolidates loose ref files into a single packed-refs file.
+     * This improves performance for repositories with many refs.
+     * HEAD and symbolic refs are not packed.
+     *
+     * @example
+     * ```typescript
+     * // After creating many branches/tags
+     * await storage.packRefs()
+     * ```
      */
     async packRefs() {
         const allRefs = await this.backend.listRefs();
@@ -393,27 +805,67 @@ export class RefStorage {
         await this.backend.writePackedRefs(packed);
     }
 }
+// ============================================================================
+// Convenience Functions
+// ============================================================================
 /**
- * Resolve a ref to its final SHA target (convenience function)
+ * Resolve a ref to its final SHA target.
+ *
+ * @description
+ * Convenience function that wraps RefStorage.resolveRef.
+ *
+ * @param storage - RefStorage instance
+ * @param name - Ref name to resolve
+ * @param options - Resolution options
+ * @returns The final SHA target
+ *
+ * @example
+ * ```typescript
+ * const sha = await resolveRef(storage, 'HEAD')
+ * ```
  */
 export async function resolveRef(storage, name, options) {
     const resolved = await storage.resolveRef(name, options);
     return resolved.sha;
 }
 /**
- * Update a ref (convenience function)
+ * Update a ref.
+ *
+ * @description
+ * Convenience function that wraps RefStorage.updateRef.
+ *
+ * @param storage - RefStorage instance
+ * @param name - Full ref name
+ * @param target - SHA target
+ * @param options - Update options
+ * @returns The updated ref
  */
 export async function updateRef(storage, name, target, options) {
     return storage.updateRef(name, target, options);
 }
 /**
- * Delete a ref (convenience function)
+ * Delete a ref.
+ *
+ * @description
+ * Convenience function that wraps RefStorage.deleteRef.
+ *
+ * @param storage - RefStorage instance
+ * @param name - Full ref name to delete
+ * @param options - Delete options
+ * @returns True if deleted
  */
 export async function deleteRef(storage, name, options) {
     return storage.deleteRef(name, options);
 }
 /**
- * List refs (convenience function)
+ * List refs.
+ *
+ * @description
+ * Convenience function that wraps RefStorage.listRefs.
+ *
+ * @param storage - RefStorage instance
+ * @param options - Listing options
+ * @returns Array of refs
  */
 export async function listRefs(storage, options) {
     return storage.listRefs(options);