@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/domain/crdt/LWW.js

@@ -131,7 +131,7 @@ export function lwwMax(a, b) {
     return null;
   }
   if (a === null || a === undefined) {
-    return b;
+    return /** @type {LWWRegister<T>} */ (b);
   }
   if (b === null || b === undefined) {
     return a;

package/src/domain/crdt/ORSet.js

@@ -118,11 +118,13 @@ export function createORSet() {
 export function orsetAdd(set, element, dot) {
   const encoded = encodeDot(dot);
 
-  if (!set.entries.has(element)) {
-    set.entries.set(element, new Set());
+  let dots = set.entries.get(element);
+  if (!dots) {
+    dots = new Set();
+    set.entries.set(element, dots);
   }
 
-  set.entries.get(element).add(encoded);
+  dots.add(encoded);
 }
 
 /**
@@ -226,10 +228,11 @@ export function orsetJoin(a, b) {
 
   // Union entries from b
   for (const [element, dots] of b.entries) {
-    if (!result.entries.has(element)) {
-      result.entries.set(element, new Set());
+    let resultDots = result.entries.get(element);
+    if (!resultDots) {
+      resultDots = new Set();
+      result.entries.set(element, resultDots);
     }
-    const resultDots = result.entries.get(element);
     for (const dot of dots) {
       resultDots.add(dot);
     }
@@ -312,6 +315,7 @@ export function orsetCompact(set, includedVV) {
  */
 export function orsetSerialize(set) {
   // Serialize entries: convert Map to array of [element, sortedDots]
+  /** @type {Array<[any, string[]]>} */
   const entriesArray = [];
   for (const [element, dots] of set.entries) {
     const sortedDots = [...dots].sort((a, b) => {

package/src/domain/crdt/VersionVector.js

@@ -158,11 +158,15 @@ export function vvContains(vv, dot) {
  * @returns {Object<string, number>}
  */
 export function vvSerialize(vv) {
+  /** @type {Record<string, number>} */
   const obj = {};
   const sortedKeys = [...vv.keys()].sort();
 
   for (const key of sortedKeys) {
-    obj[key] = vv.get(key);
+    const val = vv.get(key);
+    if (val !== undefined) {
+      obj[key] = val;
+    }
   }
 
   return obj;

package/src/domain/errors/EmptyMessageError.js

@@ -12,7 +12,7 @@ import IndexError from './IndexError.js';
  * @property {string} name - The error name ('EmptyMessageError')
  * @property {string} code - Error code ('EMPTY_MESSAGE')
  * @property {string} operation - The operation that failed due to empty message
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, *>} context - Serializable context object for debugging
  *
  * @example
  * if (!message || message.trim() === '') {
@@ -27,9 +27,7 @@ export default class EmptyMessageError extends IndexError {
    * Creates a new EmptyMessageError.
    *
    * @param {string} message - Human-readable error message
-   * @param {Object} [options={}] - Error options
-   * @param {string} [options.operation] - The operation that failed
-   * @param {Object} [options.context={}] - Additional context for debugging
+   * @param {{ operation?: string, context?: Record<string, *> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ForkError.js

@@ -24,6 +24,10 @@ import WarpError from './WarpError.js';
  * @property {Object} context - Serializable context object with error details
  */
 export default class ForkError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'FORK_ERROR', options);
   }

package/src/domain/errors/IndexError.js

@@ -17,6 +17,10 @@ import WarpError from './WarpError.js';
  * });
  */
 export default class IndexError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'INDEX_ERROR', options);
   }

package/src/domain/errors/OperationAbortedError.js

@@ -13,6 +13,10 @@ import WarpError from './WarpError.js';
  * @property {Object} context - Serializable context object for debugging
  */
 export default class OperationAbortedError extends WarpError {
+  /**
+   * @param {string} operation
+   * @param {{ code?: string, context?: Object, reason?: string }} [options={}]
+   */
   constructor(operation, options = {}) {
     const reason = options.reason || 'Operation was aborted';
     super(`Operation '${operation}' aborted: ${reason}`, 'OPERATION_ABORTED', options);

package/src/domain/errors/QueryError.js

@@ -33,6 +33,10 @@ import WarpError from './WarpError.js';
  * @property {Object} context - Serializable context object with error details
  */
 export default class QueryError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'QUERY_ERROR', options);
   }

package/src/domain/errors/SchemaUnsupportedError.js

@@ -11,6 +11,10 @@ import WarpError from './WarpError.js';
  * @property {Object} context - Serializable context object for debugging
  */
 export default class SchemaUnsupportedError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'E_SCHEMA_UNSUPPORTED', options);
   }

package/src/domain/errors/ShardCorruptionError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} shardPath - Path to the corrupted shard file
  * @property {string} oid - Object ID associated with the shard
  * @property {string} reason - Reason for corruption (e.g., 'invalid_checksum', 'invalid_version', 'parse_error')
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, *>} context - Serializable context object for debugging
  *
  * @example
  * if (!validateChecksum(data)) {
@@ -30,11 +30,7 @@ export default class ShardCorruptionError extends IndexError {
    * Creates a new ShardCorruptionError.
    *
    * @param {string} message - Human-readable error message
-   * @param {Object} [options={}] - Error options
-   * @param {string} [options.shardPath] - Path to the corrupted shard file
-   * @param {string} [options.oid] - Object ID associated with the shard
-   * @param {string} [options.reason] - Reason for corruption (e.g., 'invalid_checksum', 'invalid_version', 'parse_error')
-   * @param {Object} [options.context={}] - Additional context for debugging
+   * @param {{ shardPath?: string, oid?: string, reason?: string, context?: Record<string, *> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ShardLoadError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} shardPath - Path to the shard file that failed to load
  * @property {string} oid - Object ID associated with the shard
  * @property {Error} cause - The original error that caused the load failure
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, *>} context - Serializable context object for debugging
  *
  * @example
  * try {
@@ -32,11 +32,7 @@ export default class ShardLoadError extends IndexError {
    * Creates a new ShardLoadError.
    *
    * @param {string} message - Human-readable error message
-   * @param {Object} [options={}] - Error options
-   * @param {string} [options.shardPath] - Path to the shard file
-   * @param {string} [options.oid] - Object ID associated with the shard
-   * @param {Error} [options.cause] - The original error that caused the failure
-   * @param {Object} [options.context={}] - Additional context for debugging
+   * @param {{ shardPath?: string, oid?: string, cause?: Error, context?: Record<string, *> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ShardValidationError.js

@@ -15,7 +15,7 @@ import IndexError from './IndexError.js';
  * @property {*} expected - The expected value for the field
  * @property {*} actual - The actual value found in the shard
  * @property {string} field - The field that failed validation (e.g., 'checksum', 'version')
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, *>} context - Serializable context object for debugging
  *
  * @example
  * if (shard.version !== EXPECTED_VERSION) {
@@ -32,12 +32,7 @@ export default class ShardValidationError extends IndexError {
    * Creates a new ShardValidationError.
    *
    * @param {string} message - Human-readable error message
-   * @param {Object} [options={}] - Error options
-   * @param {string} [options.shardPath] - Path to the shard file
-   * @param {*} [options.expected] - The expected value
-   * @param {*} [options.actual] - The actual value found
-   * @param {string} [options.field] - The field that failed validation (e.g., 'checksum', 'version')
-   * @param {Object} [options.context={}] - Additional context for debugging
+   * @param {{ shardPath?: string, expected?: *, actual?: *, field?: string, context?: Record<string, *> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/StorageError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} operation - The operation that failed ('read' or 'write')
  * @property {string} oid - Object ID associated with the operation
  * @property {Error} cause - The original error that caused the failure
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, *>} context - Serializable context object for debugging
  *
  * @example
  * try {
@@ -32,11 +32,7 @@ export default class StorageError extends IndexError {
    * Creates a new StorageError.
    *
    * @param {string} message - Human-readable error message
-   * @param {Object} [options={}] - Error options
-   * @param {string} [options.operation] - The operation that failed ('read' or 'write')
-   * @param {string} [options.oid] - Object ID associated with the operation
-   * @param {Error} [options.cause] - The original error that caused the failure
-   * @param {Object} [options.context={}] - Additional context for debugging
+   * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, *> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/SyncError.js

@@ -24,6 +24,10 @@ import WarpError from './WarpError.js';
  * @property {Object} context - Serializable context object with error details
  */
 export default class SyncError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'SYNC_ERROR', options);
   }

package/src/domain/errors/TraversalError.js

@@ -17,6 +17,10 @@ import WarpError from './WarpError.js';
  * });
  */
 export default class TraversalError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'TRAVERSAL_ERROR', options);
   }

package/src/domain/errors/WarpError.js

@@ -10,15 +10,13 @@
  *
  * @property {string} name - Error name (set from constructor.name)
  * @property {string} code - Machine-readable error code
- * @property {Object} context - Serializable context for debugging
+ * @property {Record<string, *>} context - Serializable context for debugging
  */
 export default class WarpError extends Error {
   /**
    * @param {string} message - Human-readable error message
    * @param {string} defaultCode - Default error code if not overridden by options
-   * @param {Object} [options={}] - Error options
-   * @param {string} [options.code] - Override error code
-   * @param {Object} [options.context={}] - Serializable context for debugging
+   * @param {{ code?: string, context?: Record<string, *> }} [options={}] - Error options
    */
   constructor(message, defaultCode, options = {}) {
     super(message);

package/src/domain/errors/WormholeError.js

@@ -22,6 +22,10 @@ import WarpError from './WarpError.js';
  * @property {Object} context - Serializable context object with error details
  */
 export default class WormholeError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Object }} [options={}]
+   */
   constructor(message, options = {}) {
     super(message, 'WORMHOLE_ERROR', options);
   }

package/src/domain/services/AnchorMessageCodec.js

@@ -56,10 +56,7 @@ export function encodeAnchorMessage({ graph, schema = 2 }) {
  * Decodes an anchor commit message.
  *
  * @param {string} message - The raw commit message
- * @returns {Object} The decoded anchor message
- * @returns {string} return.kind - Always 'anchor'
- * @returns {string} return.graph - The graph name
- * @returns {number} return.schema - The schema version
+ * @returns {{ kind: 'anchor', graph: string, schema: number }} The decoded anchor message
  * @throws {Error} If the message is not a valid anchor message
  *
  * @example

package/src/domain/services/BitmapIndexBuilder.js

@@ -1,4 +1,5 @@
 import defaultCodec from '../utils/defaultCodec.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
 import { getRoaringBitmap32, getNativeRoaringAvailable } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
 import { SHARD_VERSION } from '../utils/shardVersion.js';
@@ -13,10 +14,9 @@ export { SHARD_VERSION };
  *
  * @param {Object} data - The data object to checksum
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
- * @returns {Promise<string|null>} Hex-encoded SHA-256 hash
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
 const computeChecksum = async (data, crypto) => {
-  if (!crypto) { return null; }
   const json = canonicalStringify(data);
   return await crypto.hash('sha256', json);
 };
@@ -51,6 +51,7 @@ const wrapShard = async (data, crypto) => ({
  * @param {import('../../ports/CodecPort.js').default} codec - Codec for CBOR serialization
  */
 function serializeFrontierToTree(frontier, tree, codec) {
+  /** @type {Record<string, string|undefined>} */
   const sorted = {};
   for (const key of Array.from(frontier.keys()).sort()) {
     sorted[key] = frontier.get(key);
@@ -95,14 +96,14 @@ export default class BitmapIndexBuilder {
    */
   constructor({ crypto, codec } = {}) {
     /** @type {import('../../ports/CryptoPort.js').default} */
-    this._crypto = crypto;
-    /** @type {import('../../ports/CodecPort.js').default|undefined} */
+    this._crypto = crypto || defaultCrypto;
+    /** @type {import('../../ports/CodecPort.js').default} */
     this._codec = codec || defaultCodec;
     /** @type {Map<string, number>} */
     this.shaToId = new Map();
     /** @type {string[]} */
     this.idToSha = [];
-    /** @type {Map<string, RoaringBitmap32>} */
+    /** @type {Map<string, any>} */
     this.bitmaps = new Map();
   }
 
@@ -148,9 +149,11 @@ export default class BitmapIndexBuilder {
    * @returns {Promise<Record<string, Buffer>>} Map of path → serialized content
    */
   async serialize({ frontier } = {}) {
+    /** @type {Record<string, Buffer>} */
     const tree = {};
 
     // Serialize ID mappings (sharded by prefix)
+    /** @type {Record<string, Record<string, number>>} */
     const idShards = {};
     for (const [sha, id] of this.shaToId) {
       const prefix = sha.substring(0, 2);
@@ -165,6 +168,7 @@ export default class BitmapIndexBuilder {
 
     // Serialize bitmaps (sharded by prefix, per-node within shard)
     // Keys are constructed as '${type}_${sha}' by _addToBitmap (e.g., 'fwd_abc123', 'rev_def456')
+    /** @type {Record<string, Record<string, Record<string, string>>>} */
     const bitmapShards = { fwd: {}, rev: {} };
     for (const [key, bitmap] of this.bitmaps) {
       const [type, sha] = [key.substring(0, 3), key.substring(4)];
@@ -198,7 +202,7 @@ export default class BitmapIndexBuilder {
    */
   _getOrCreateId(sha) {
     if (this.shaToId.has(sha)) {
-      return this.shaToId.get(sha);
+      return /** @type {number} */ (this.shaToId.get(sha));
     }
     const id = this.idToSha.length;
     this.idToSha.push(sha);

package/src/domain/services/BitmapIndexReader.js

@@ -1,9 +1,14 @@
 import { ShardLoadError, ShardCorruptionError, ShardValidationError } from '../errors/index.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
 import nullLogger from '../utils/nullLogger.js';
 import LRUCache from '../utils/LRUCache.js';
 import { getRoaringBitmap32 } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
 
+/** @typedef {import('../../ports/IndexStoragePort.js').default} IndexStoragePort */
+/** @typedef {import('../../ports/LoggerPort.js').default} LoggerPort */
+/** @typedef {import('../../ports/CryptoPort.js').default} CryptoPort */
+
 /**
  * Supported shard format versions for backward compatibility.
  * Version 1: Original format using JSON.stringify for checksums
@@ -25,10 +30,9 @@ const DEFAULT_MAX_CACHED_SHARDS = 100;
  * @param {Object} data - The data object to checksum
  * @param {number} version - Shard version (1 uses JSON.stringify, 2+ uses canonicalStringify)
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
- * @returns {Promise<string|null>} Hex-encoded SHA-256 hash
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
 const computeChecksum = async (data, version, crypto) => {
-  if (!crypto) { return null; }
   const json = version === 1 ? JSON.stringify(data) : canonicalStringify(data);
   return await crypto.hash('sha256', json);
 };
@@ -77,16 +81,15 @@ export default class BitmapIndexReader {
   /**
    * Creates a BitmapIndexReader instance.
    * @param {Object} options
-   * @param {import('../../ports/IndexStoragePort.js').default} options.storage - Storage adapter for reading index data
+   * @param {IndexStoragePort} options.storage - Storage adapter for reading index data
    * @param {boolean} [options.strict=false] - If true, throw errors on validation failures; if false, log warnings and return empty shards
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
    *   Defaults to NoOpLogger (no logging).
    * @param {number} [options.maxCachedShards=100] - Maximum number of shards to keep in the LRU cache.
    *   When exceeded, least recently used shards are evicted to free memory.
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
-   *   When not provided, checksum validation is skipped.
    */
-  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = {}) {
+  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
@@ -95,9 +98,10 @@ export default class BitmapIndexReader {
     this.logger = logger;
     this.maxCachedShards = maxCachedShards;
     /** @type {import('../../ports/CryptoPort.js').default} */
-    this._crypto = crypto;
+    this._crypto = crypto || defaultCrypto;
     this.shardOids = new Map(); // path -> OID
     this.loadedShards = new LRUCache(maxCachedShards); // path -> Data
+    /** @type {string[]|null} */
     this._idToShaCache = null; // Lazy-built reverse mapping
   }
 
@@ -191,7 +195,7 @@ export default class BitmapIndexReader {
         shardPath,
         oid: this.shardOids.get(shardPath),
         reason: 'bitmap_deserialize_error',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
       this._handleShardError(corruptionError, {
         path: shardPath,
@@ -243,10 +247,10 @@ export default class BitmapIndexReader {
   /**
    * Validates a shard envelope for version and checksum integrity.
    *
-   * @param {Object} envelope - The shard envelope to validate
+   * @param {{ data?: any, version?: number, checksum?: string }} envelope - The shard envelope to validate
    * @param {string} path - Shard path (for error context)
    * @param {string} oid - Object ID (for error context)
-   * @returns {Promise<Object>} The validated data from the envelope
+   * @returns {Promise<any>} The validated data from the envelope
    * @throws {ShardCorruptionError} If envelope format is invalid
    * @throws {ShardValidationError} If version or checksum validation fails
    * @private
@@ -267,7 +271,7 @@ export default class BitmapIndexReader {
         reason: 'missing_or_invalid_data',
       });
     }
-    if (!SUPPORTED_SHARD_VERSIONS.includes(envelope.version)) {
+    if (!SUPPORTED_SHARD_VERSIONS.includes(/** @type {number} */ (envelope.version))) {
       throw new ShardValidationError('Unsupported version', {
         shardPath: path,
         expected: SUPPORTED_SHARD_VERSIONS,
@@ -276,8 +280,8 @@ export default class BitmapIndexReader {
       });
     }
     // Use version-appropriate checksum computation for backward compatibility
-    const actualChecksum = await computeChecksum(envelope.data, envelope.version, this._crypto);
-    if (actualChecksum !== null && envelope.checksum !== actualChecksum) {
+    const actualChecksum = await computeChecksum(envelope.data, /** @type {number} */ (envelope.version), this._crypto);
+    if (envelope.checksum !== actualChecksum) {
       throw new ShardValidationError('Checksum mismatch', {
         shardPath: path,
         expected: envelope.checksum,
@@ -295,7 +299,7 @@ export default class BitmapIndexReader {
    * @param {string} context.path - Shard path
    * @param {string} context.oid - Object ID
    * @param {string} context.format - 'json' or 'bitmap'
-   * @returns {Object|RoaringBitmap32} Empty shard (non-strict mode only)
+   * @returns {any} Empty shard (non-strict mode only)
    * @throws {ShardCorruptionError|ShardValidationError} In strict mode
    * @private
    */
@@ -303,15 +307,17 @@ export default class BitmapIndexReader {
     if (this.strict) {
       throw err;
     }
+    /** @type {any} */ // TODO(ts-cleanup): type lazy singleton
+    const errAny = err;
     this.logger.warn('Shard validation warning', {
       operation: 'loadShard',
       shardPath: path,
       oid,
       error: err.message,
       code: err.code,
-      field: err.field,
-      expected: err.expected,
-      actual: err.actual,
+      field: errAny.field,
+      expected: errAny.expected,
+      actual: errAny.actual,
     });
     const emptyShard = format === 'json' ? {} : new (getRoaringBitmap32())();
     this.loadedShards.set(path, emptyShard);
@@ -343,12 +349,12 @@ export default class BitmapIndexReader {
    */
   async _loadShardBuffer(path, oid) {
     try {
-      return await this.storage.readBlob(oid);
+      return await /** @type {any} */ (this.storage).readBlob(oid); // TODO(ts-cleanup): narrow port type
     } catch (cause) {
       throw new ShardLoadError('Failed to load shard from storage', {
         shardPath: path,
         oid,
-        cause,
+        cause: /** @type {Error} */ (cause),
       });
     }
   }
@@ -376,12 +382,12 @@ export default class BitmapIndexReader {
   /**
    * Attempts to handle a shard error based on its type.
    * Returns handled result for validation/corruption errors, null otherwise.
-   * @param {Error} err - The error to handle
+   * @param {any} err - The error to handle
    * @param {Object} context - Error context
    * @param {string} context.path - Shard path
    * @param {string} context.oid - Object ID
    * @param {string} context.format - 'json' or 'bitmap'
-   * @returns {Object|RoaringBitmap32|null} Handled result or null if error should be re-thrown
+   * @returns {any} Handled result or null if error should be re-thrown
    * @private
    */
   _tryHandleShardError(err, context) {
@@ -400,7 +406,7 @@ export default class BitmapIndexReader {
    *
    * @param {string} path - Shard path
    * @param {string} format - 'json' or 'bitmap'
-   * @returns {Promise<Object|RoaringBitmap32>}
+   * @returns {Promise<any>}
    * @throws {ShardLoadError} When storage.readBlob fails
    * @throws {ShardCorruptionError} When shard format is invalid (strict mode only)
    * @throws {ShardValidationError} When version or checksum validation fails (strict mode only)