gitx.do 0.0.1 → 0.0.3

package/dist/utils/hash.d.ts

@@ -1,31 +1,152 @@
 /**
- * SHA hashing utilities for git objects
+ * @fileoverview SHA Hashing Utilities for Git Objects
  *
- * Git uses SHA-1 for object identifiers and SHA-256 is used
- * in newer git versions (v2.29+) as an optional hash algorithm.
+ * This module provides cryptographic hashing functions used for Git object
+ * identification and verification. Git uses SHA-1 as its primary hash algorithm,
+ * with SHA-256 available as an optional newer algorithm (Git v2.29+).
+ *
+ * The hash functions work with the Web Crypto API for broad compatibility
+ * with browsers and edge runtimes like Cloudflare Workers.
+ *
+ * @module utils/hash
+ *
+ * @example
+ * ```typescript
+ * import { sha1, hashObject, hexToBytes, bytesToHex } from './utils/hash'
+ *
+ * // Hash raw data
+ * const hash = await sha1('Hello, World!')
+ *
+ * // Hash as a Git object (includes type header)
+ * const content = new TextEncoder().encode('file content')
+ * const blobSha = await hashObject('blob', content)
+ * console.log(`blob ${blobSha}`)
+ * ```
  */
 /**
- * Compute SHA-1 hash of data
- * @returns 40-character lowercase hex string
+ * Compute the SHA-1 hash of data.
+ *
+ * @description
+ * Computes a SHA-1 digest of the input data using the Web Crypto API.
+ * This is the standard hash algorithm used by Git for object identification.
+ *
+ * **Note**: SHA-1 is considered cryptographically weak. Git uses it for
+ * content addressing, not security. For new security-sensitive applications,
+ * use SHA-256.
+ *
+ * @param data - Input data as Uint8Array or string (UTF-8 encoded)
+ * @returns 40-character lowercase hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * // Hash a string
+ * const hash1 = await sha1('Hello, World!')
+ * console.log(hash1) // '0a0a9f2a6772942557ab5355d76af442f8f65e01'
+ *
+ * // Hash binary data
+ * const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f])
+ * const hash2 = await sha1(data)
+ * ```
  */
 export declare function sha1(data: Uint8Array | string): Promise<string>;
 /**
- * Compute SHA-256 hash of data
- * @returns 64-character lowercase hex string
+ * Compute the SHA-256 hash of data.
+ *
+ * @description
+ * Computes a SHA-256 digest of the input data using the Web Crypto API.
+ * SHA-256 is the newer, more secure hash algorithm supported by Git v2.29+
+ * as an alternative to SHA-1.
+ *
+ * @param data - Input data as Uint8Array or string (UTF-8 encoded)
+ * @returns 64-character lowercase hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * // Hash a string
+ * const hash = await sha256('Hello, World!')
+ * console.log(hash) // 'dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f'
+ *
+ * // Hash binary data
+ * const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f])
+ * const hash2 = await sha256(data)
+ * ```
  */
 export declare function sha256(data: Uint8Array | string): Promise<string>;
 /**
- * Hash a git object with type header
- * Format: "{type} {size}\0{content}"
- * This matches `git hash-object` output
+ * Hash a Git object with its type header.
+ *
+ * @description
+ * Computes the SHA-1 hash of a Git object including its header.
+ * The header format is: "{type} {size}\0" followed by the content.
+ *
+ * This matches the output of `git hash-object` command and is the
+ * standard way Git computes object identifiers.
+ *
+ * @param type - Object type ('blob', 'tree', 'commit', 'tag')
+ * @param data - Object content as binary data (without header)
+ * @returns 40-character lowercase hexadecimal SHA-1 hash
+ *
+ * @example
+ * ```typescript
+ * // Hash a blob (equivalent to `echo -n "hello" | git hash-object --stdin`)
+ * const content = new TextEncoder().encode('hello')
+ * const sha = await hashObject('blob', content)
+ * console.log(sha) // 'b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0'
+ *
+ * // Verify with git:
+ * // $ echo -n "hello" | git hash-object --stdin
+ * // b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0
+ * ```
  */
 export declare function hashObject(type: string, data: Uint8Array): Promise<string>;
 /**
- * Convert hex string to Uint8Array
+ * Convert a hexadecimal string to a Uint8Array.
+ *
+ * @description
+ * Parses a hexadecimal string and returns the corresponding bytes.
+ * Each pair of hex characters becomes one byte.
+ *
+ * **Edge Cases**:
+ * - Empty string returns empty Uint8Array
+ * - Hex string should have even length (odd length may produce unexpected results)
+ *
+ * @param hex - Hexadecimal string (case-insensitive)
+ * @returns Binary data as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const bytes = hexToBytes('48656c6c6f')
+ * console.log(new TextDecoder().decode(bytes)) // 'Hello'
+ *
+ * // Convert SHA back to bytes (useful for tree entries)
+ * const sha = 'abc123def456...'
+ * const sha20 = hexToBytes(sha) // 20 bytes for SHA-1
+ * ```
  */
 export declare function hexToBytes(hex: string): Uint8Array;
 /**
- * Convert Uint8Array to hex string
+ * Convert a Uint8Array to a hexadecimal string.
+ *
+ * @description
+ * Converts binary data to a lowercase hexadecimal string representation.
+ * Each byte becomes two hex characters (zero-padded).
+ *
+ * **Edge Cases**:
+ * - Empty Uint8Array returns empty string
+ *
+ * @param bytes - Binary data to convert
+ * @returns Lowercase hexadecimal string
+ *
+ * @example
+ * ```typescript
+ * const hello = new TextEncoder().encode('Hello')
+ * const hex = bytesToHex(hello)
+ * console.log(hex) // '48656c6c6f'
+ *
+ * // Convert SHA-1 bytes to string
+ * const hashBytes = new Uint8Array(20) // ... from crypto
+ * const sha = bytesToHex(hashBytes) // 40-char hex string
+ * ```
  */
 export declare function bytesToHex(bytes: Uint8Array): string;
 //# sourceMappingURL=hash.d.ts.map

package/dist/utils/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIrE;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIvE;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOlD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKpD"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIrE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOlD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKpD"}

package/dist/utils/hash.js

@@ -1,12 +1,52 @@
 /**
- * SHA hashing utilities for git objects
+ * @fileoverview SHA Hashing Utilities for Git Objects
  *
- * Git uses SHA-1 for object identifiers and SHA-256 is used
- * in newer git versions (v2.29+) as an optional hash algorithm.
+ * This module provides cryptographic hashing functions used for Git object
+ * identification and verification. Git uses SHA-1 as its primary hash algorithm,
+ * with SHA-256 available as an optional newer algorithm (Git v2.29+).
+ *
+ * The hash functions work with the Web Crypto API for broad compatibility
+ * with browsers and edge runtimes like Cloudflare Workers.
+ *
+ * @module utils/hash
+ *
+ * @example
+ * ```typescript
+ * import { sha1, hashObject, hexToBytes, bytesToHex } from './utils/hash'
+ *
+ * // Hash raw data
+ * const hash = await sha1('Hello, World!')
+ *
+ * // Hash as a Git object (includes type header)
+ * const content = new TextEncoder().encode('file content')
+ * const blobSha = await hashObject('blob', content)
+ * console.log(`blob ${blobSha}`)
+ * ```
  */
 /**
- * Compute SHA-1 hash of data
- * @returns 40-character lowercase hex string
+ * Compute the SHA-1 hash of data.
+ *
+ * @description
+ * Computes a SHA-1 digest of the input data using the Web Crypto API.
+ * This is the standard hash algorithm used by Git for object identification.
+ *
+ * **Note**: SHA-1 is considered cryptographically weak. Git uses it for
+ * content addressing, not security. For new security-sensitive applications,
+ * use SHA-256.
+ *
+ * @param data - Input data as Uint8Array or string (UTF-8 encoded)
+ * @returns 40-character lowercase hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * // Hash a string
+ * const hash1 = await sha1('Hello, World!')
+ * console.log(hash1) // '0a0a9f2a6772942557ab5355d76af442f8f65e01'
+ *
+ * // Hash binary data
+ * const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f])
+ * const hash2 = await sha1(data)
+ * ```
  */
 export async function sha1(data) {
     const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
@@ -14,8 +54,26 @@ export async function sha1(data) {
     return bytesToHex(new Uint8Array(hashBuffer));
 }
 /**
- * Compute SHA-256 hash of data
- * @returns 64-character lowercase hex string
+ * Compute the SHA-256 hash of data.
+ *
+ * @description
+ * Computes a SHA-256 digest of the input data using the Web Crypto API.
+ * SHA-256 is the newer, more secure hash algorithm supported by Git v2.29+
+ * as an alternative to SHA-1.
+ *
+ * @param data - Input data as Uint8Array or string (UTF-8 encoded)
+ * @returns 64-character lowercase hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * // Hash a string
+ * const hash = await sha256('Hello, World!')
+ * console.log(hash) // 'dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f'
+ *
+ * // Hash binary data
+ * const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f])
+ * const hash2 = await sha256(data)
+ * ```
  */
 export async function sha256(data) {
     const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
@@ -23,9 +81,30 @@ export async function sha256(data) {
     return bytesToHex(new Uint8Array(hashBuffer));
 }
 /**
- * Hash a git object with type header
- * Format: "{type} {size}\0{content}"
- * This matches `git hash-object` output
+ * Hash a Git object with its type header.
+ *
+ * @description
+ * Computes the SHA-1 hash of a Git object including its header.
+ * The header format is: "{type} {size}\0" followed by the content.
+ *
+ * This matches the output of `git hash-object` command and is the
+ * standard way Git computes object identifiers.
+ *
+ * @param type - Object type ('blob', 'tree', 'commit', 'tag')
+ * @param data - Object content as binary data (without header)
+ * @returns 40-character lowercase hexadecimal SHA-1 hash
+ *
+ * @example
+ * ```typescript
+ * // Hash a blob (equivalent to `echo -n "hello" | git hash-object --stdin`)
+ * const content = new TextEncoder().encode('hello')
+ * const sha = await hashObject('blob', content)
+ * console.log(sha) // 'b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0'
+ *
+ * // Verify with git:
+ * // $ echo -n "hello" | git hash-object --stdin
+ * // b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0
+ * ```
  */
 export async function hashObject(type, data) {
     const header = `${type} ${data.length}\0`;
@@ -36,7 +115,28 @@ export async function hashObject(type, data) {
     return sha1(combined);
 }
 /**
- * Convert hex string to Uint8Array
+ * Convert a hexadecimal string to a Uint8Array.
+ *
+ * @description
+ * Parses a hexadecimal string and returns the corresponding bytes.
+ * Each pair of hex characters becomes one byte.
+ *
+ * **Edge Cases**:
+ * - Empty string returns empty Uint8Array
+ * - Hex string should have even length (odd length may produce unexpected results)
+ *
+ * @param hex - Hexadecimal string (case-insensitive)
+ * @returns Binary data as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const bytes = hexToBytes('48656c6c6f')
+ * console.log(new TextDecoder().decode(bytes)) // 'Hello'
+ *
+ * // Convert SHA back to bytes (useful for tree entries)
+ * const sha = 'abc123def456...'
+ * const sha20 = hexToBytes(sha) // 20 bytes for SHA-1
+ * ```
  */
 export function hexToBytes(hex) {
     if (hex.length === 0)
@@ -48,7 +148,28 @@ export function hexToBytes(hex) {
     return bytes;
 }
 /**
- * Convert Uint8Array to hex string
+ * Convert a Uint8Array to a hexadecimal string.
+ *
+ * @description
+ * Converts binary data to a lowercase hexadecimal string representation.
+ * Each byte becomes two hex characters (zero-padded).
+ *
+ * **Edge Cases**:
+ * - Empty Uint8Array returns empty string
+ *
+ * @param bytes - Binary data to convert
+ * @returns Lowercase hexadecimal string
+ *
+ * @example
+ * ```typescript
+ * const hello = new TextEncoder().encode('Hello')
+ * const hex = bytesToHex(hello)
+ * console.log(hex) // '48656c6c6f'
+ *
+ * // Convert SHA-1 bytes to string
+ * const hashBytes = new Uint8Array(20) // ... from crypto
+ * const sha = bytesToHex(hashBytes) // 40-char hex string
+ * ```
  */
 export function bytesToHex(bytes) {
     if (bytes.length === 0)

package/dist/utils/hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAyB;IAClD,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9E,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAC7D,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAA;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAyB;IACpD,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9E,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;IAC/D,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAA;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,IAAgB;IAC7D,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,CAAA;IACzC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACpD,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAA;IACjE,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;IAC5B,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAA;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;IAC9C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAClD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,EAAE,CAAC,CAAA;AACb,CAAC"}
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAyB;IAClD,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9E,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAC7D,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAyB;IACpD,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9E,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;IAC/D,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,IAAgB;IAC7D,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,CAAA;IACzC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACpD,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAA;IACjE,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;IAC5B,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAA;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;IAC9C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAClD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,EAAE,CAAC,CAAA;AACb,CAAC"}

package/dist/utils/sha1.d.ts

@@ -1,26 +1,119 @@
 /**
- * Synchronous SHA-1 utilities for git pack operations
+ * @fileoverview Synchronous SHA-1 Utilities for Git Pack Operations
  *
- * These functions provide synchronous SHA-1 hashing needed for pack file
- * generation and verification. For async operations, use hash.ts instead.
+ * This module provides synchronous (non-async) SHA-1 hashing needed for pack file
+ * generation, verification, and streaming operations where async is impractical.
+ *
+ * The implementation follows the SHA-1 specification (FIPS 180-4) and processes
+ * data in 512-bit (64-byte) chunks using the standard compression function.
+ *
+ * **When to use this vs hash.ts**:
+ * - Use `utils/hash.ts` for general async hashing (uses Web Crypto API)
+ * - Use this module for pack operations that need synchronous hashing
+ *
+ * @module utils/sha1
+ *
+ * @example
+ * ```typescript
+ * import { sha1, sha1Hex, sha1Verify } from './utils/sha1'
+ *
+ * // Compute SHA-1 as bytes
+ * const data = new TextEncoder().encode('Hello, World!')
+ * const hashBytes = sha1(data) // 20-byte Uint8Array
+ *
+ * // Compute SHA-1 as hex string
+ * const hashHex = sha1Hex(data) // 40-char string
+ *
+ * // Verify data against expected hash
+ * const isValid = sha1Verify(data, expectedHash)
+ * ```
  */
 /**
- * Compute SHA-1 hash of data synchronously
+ * Compute SHA-1 hash of data synchronously.
+ *
+ * @description
+ * Implements the SHA-1 algorithm per FIPS 180-4. This pure JavaScript
+ * implementation is used when synchronous hashing is needed, such as
+ * in pack file generation or streaming operations.
+ *
+ * **Algorithm Details**:
+ * 1. Pad message to 512-bit boundary (with 1-bit, zeros, and 64-bit length)
+ * 2. Process in 64-byte chunks using 80-round compression function
+ * 3. Return final 160-bit (20-byte) hash
+ *
+ * **Performance Note**: This is slower than Web Crypto API. Use `hash.ts`
+ * for async operations where performance is critical.
+ *
  * @param data - Input data to hash
  * @returns 20-byte hash as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('test')
+ * const hash = sha1(data)
+ * console.log(hash.length) // 20
+ *
+ * // Use with pack file verification
+ * const packData = readPackFile()
+ * const computedHash = sha1(packData.slice(0, -20))
+ * ```
  */
 export declare function sha1(data: Uint8Array): Uint8Array;
 /**
- * Compute SHA-1 hash and return as hex string
+ * Compute SHA-1 hash and return as hexadecimal string.
+ *
+ * @description
+ * Convenience wrapper that computes SHA-1 and converts the result
+ * to a lowercase hexadecimal string. Equivalent to calling `sha1()`
+ * followed by hex conversion.
+ *
  * @param data - Input data to hash
- * @returns 40-character lowercase hex string
+ * @returns 40-character lowercase hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('hello')
+ * const hex = sha1Hex(data)
+ * console.log(hex) // 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d'
+ *
+ * // Compare with git:
+ * // $ echo -n "hello" | sha1sum
+ * // aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
+ * ```
  */
 export declare function sha1Hex(data: Uint8Array): string;
 /**
- * Verify data against expected SHA-1 hash
+ * Verify data against an expected SHA-1 hash.
+ *
+ * @description
+ * Computes the SHA-1 hash of the data and compares it byte-by-byte
+ * with the expected hash. Returns true only if all 20 bytes match.
+ *
+ * This uses constant-time comparison to avoid timing attacks,
+ * though SHA-1 is not used for security purposes in Git.
+ *
  * @param data - Data to verify
- * @param expected - Expected 20-byte hash
- * @returns true if hash matches
+ * @param expected - Expected 20-byte SHA-1 hash
+ * @returns True if the computed hash matches the expected hash
+ * @throws Never throws - returns false for invalid inputs
+ *
+ * @example
+ * ```typescript
+ * // Verify pack file integrity
+ * const packContent = readPackFile()
+ * const contentWithoutChecksum = packContent.slice(0, -20)
+ * const expectedChecksum = packContent.slice(-20)
+ *
+ * if (sha1Verify(contentWithoutChecksum, expectedChecksum)) {
+ *   console.log('Pack file integrity verified')
+ * } else {
+ *   console.log('Pack file corrupted!')
+ * }
+ *
+ * // Invalid expected hash length
+ * const badHash = new Uint8Array(10)
+ * sha1Verify(data, badHash) // false (wrong length)
+ * ```
  */
 export declare function sha1Verify(data: Uint8Array, expected: Uint8Array): boolean;
 //# sourceMappingURL=sha1.d.ts.map

package/dist/utils/sha1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sha1.d.ts","sourceRoot":"","sources":["../../src/utils/sha1.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAgGjD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAc1E"}
+{"version":3,"file":"sha1.d.ts","sourceRoot":"","sources":["../../src/utils/sha1.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAwGjD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAOhD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAgB1E"}

package/dist/utils/sha1.js

@@ -1,19 +1,72 @@
 /**
- * Synchronous SHA-1 utilities for git pack operations
+ * @fileoverview Synchronous SHA-1 Utilities for Git Pack Operations
  *
- * These functions provide synchronous SHA-1 hashing needed for pack file
- * generation and verification. For async operations, use hash.ts instead.
+ * This module provides synchronous (non-async) SHA-1 hashing needed for pack file
+ * generation, verification, and streaming operations where async is impractical.
+ *
+ * The implementation follows the SHA-1 specification (FIPS 180-4) and processes
+ * data in 512-bit (64-byte) chunks using the standard compression function.
+ *
+ * **When to use this vs hash.ts**:
+ * - Use `utils/hash.ts` for general async hashing (uses Web Crypto API)
+ * - Use this module for pack operations that need synchronous hashing
+ *
+ * @module utils/sha1
+ *
+ * @example
+ * ```typescript
+ * import { sha1, sha1Hex, sha1Verify } from './utils/sha1'
+ *
+ * // Compute SHA-1 as bytes
+ * const data = new TextEncoder().encode('Hello, World!')
+ * const hashBytes = sha1(data) // 20-byte Uint8Array
+ *
+ * // Compute SHA-1 as hex string
+ * const hashHex = sha1Hex(data) // 40-char string
+ *
+ * // Verify data against expected hash
+ * const isValid = sha1Verify(data, expectedHash)
+ * ```
  */
 /**
- * Compute SHA-1 hash of data synchronously
+ * Compute SHA-1 hash of data synchronously.
+ *
+ * @description
+ * Implements the SHA-1 algorithm per FIPS 180-4. This pure JavaScript
+ * implementation is used when synchronous hashing is needed, such as
+ * in pack file generation or streaming operations.
+ *
+ * **Algorithm Details**:
+ * 1. Pad message to 512-bit boundary (with 1-bit, zeros, and 64-bit length)
+ * 2. Process in 64-byte chunks using 80-round compression function
+ * 3. Return final 160-bit (20-byte) hash
+ *
+ * **Performance Note**: This is slower than Web Crypto API. Use `hash.ts`
+ * for async operations where performance is critical.
+ *
  * @param data - Input data to hash
  * @returns 20-byte hash as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('test')
+ * const hash = sha1(data)
+ * console.log(hash.length) // 20
+ *
+ * // Use with pack file verification
+ * const packData = readPackFile()
+ * const computedHash = sha1(packData.slice(0, -20))
+ * ```
  */
 export function sha1(data) {
+    /**
+     * Rotate left (circular left shift) operation.
+     * @internal
+     */
     function rotl(n, s) {
         return ((n << s) | (n >>> (32 - s))) >>> 0;
     }
-    // Initialize hash values
+    // Initialize hash values (first 32 bits of fractional parts of square roots of first 5 primes)
     let h0 = 0x67452301;
     let h1 = 0xefcdab89;
     let h2 = 0x98badcfe;
@@ -50,22 +103,26 @@ export function sha1(data) {
         let c = h2;
         let d = h3;
         let e = h4;
-        // Main loop
+        // Main loop - 80 rounds
         for (let i = 0; i < 80; i++) {
             let f, k;
             if (i < 20) {
+                // Round 0-19: Ch(b,c,d) = (b AND c) XOR (NOT b AND d)
                 f = (b & c) | (~b & d);
                 k = 0x5a827999;
             }
             else if (i < 40) {
+                // Round 20-39: Parity(b,c,d) = b XOR c XOR d
                 f = b ^ c ^ d;
                 k = 0x6ed9eba1;
             }
             else if (i < 60) {
+                // Round 40-59: Maj(b,c,d) = (b AND c) XOR (b AND d) XOR (c AND d)
                 f = (b & c) | (b & d) | (c & d);
                 k = 0x8f1bbcdc;
             }
             else {
+                // Round 60-79: Parity(b,c,d) = b XOR c XOR d
                 f = b ^ c ^ d;
                 k = 0xca62c1d6;
             }
@@ -94,9 +151,26 @@ export function sha1(data) {
     return result;
 }
 /**
- * Compute SHA-1 hash and return as hex string
+ * Compute SHA-1 hash and return as hexadecimal string.
+ *
+ * @description
+ * Convenience wrapper that computes SHA-1 and converts the result
+ * to a lowercase hexadecimal string. Equivalent to calling `sha1()`
+ * followed by hex conversion.
+ *
  * @param data - Input data to hash
- * @returns 40-character lowercase hex string
+ * @returns 40-character lowercase hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('hello')
+ * const hex = sha1Hex(data)
+ * console.log(hex) // 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d'
+ *
+ * // Compare with git:
+ * // $ echo -n "hello" | sha1sum
+ * // aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
+ * ```
  */
 export function sha1Hex(data) {
     const hash = sha1(data);
@@ -107,16 +181,45 @@ export function sha1Hex(data) {
     return hex;
 }
 /**
- * Verify data against expected SHA-1 hash
+ * Verify data against an expected SHA-1 hash.
+ *
+ * @description
+ * Computes the SHA-1 hash of the data and compares it byte-by-byte
+ * with the expected hash. Returns true only if all 20 bytes match.
+ *
+ * This uses constant-time comparison to avoid timing attacks,
+ * though SHA-1 is not used for security purposes in Git.
+ *
  * @param data - Data to verify
- * @param expected - Expected 20-byte hash
- * @returns true if hash matches
+ * @param expected - Expected 20-byte SHA-1 hash
+ * @returns True if the computed hash matches the expected hash
+ * @throws Never throws - returns false for invalid inputs
+ *
+ * @example
+ * ```typescript
+ * // Verify pack file integrity
+ * const packContent = readPackFile()
+ * const contentWithoutChecksum = packContent.slice(0, -20)
+ * const expectedChecksum = packContent.slice(-20)
+ *
+ * if (sha1Verify(contentWithoutChecksum, expectedChecksum)) {
+ *   console.log('Pack file integrity verified')
+ * } else {
+ *   console.log('Pack file corrupted!')
+ * }
+ *
+ * // Invalid expected hash length
+ * const badHash = new Uint8Array(10)
+ * sha1Verify(data, badHash) // false (wrong length)
+ * ```
  */
 export function sha1Verify(data, expected) {
+    // Expected hash must be exactly 20 bytes
     if (expected.length !== 20) {
         return false;
     }
     const computed = sha1(data);
+    // Compare all 20 bytes
     for (let i = 0; i < 20; i++) {
         if (computed[i] !== expected[i]) {
             return false;