@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/domain/services/QueryBuilder.js

@@ -12,8 +12,8 @@ const DEFAULT_PATTERN = '*';
  * @typedef {Object} QueryNodeSnapshot
  * @property {string} id - The unique identifier of the node
  * @property {Record<string, unknown>} props - Frozen snapshot of node properties
- * @property {Array<{label: string, to: string}>} edgesOut - Outgoing edges sorted by label then target
- * @property {Array<{label: string, from: string}>} edgesIn - Incoming edges sorted by label then source
+ * @property {ReadonlyArray<{label: string, to?: string, from?: string}>} edgesOut - Outgoing edges sorted by label then target
+ * @property {ReadonlyArray<{label: string, to?: string, from?: string}>} edgesIn - Incoming edges sorted by label then source
  */
 
 /**
@@ -271,6 +271,7 @@ function cloneValue(value) {
  * @private
  */
 function buildPropsSnapshot(propsMap) {
+  /** @type {Record<string, unknown>} */
   const props = {};
   const keys = [...propsMap.keys()].sort();
   for (const key of keys) {
@@ -299,8 +300,8 @@ function buildEdgesSnapshot(edges, directionKey) {
     if (a.label !== b.label) {
       return a.label < b.label ? -1 : 1;
     }
-    const aPeer = a[directionKey];
-    const bPeer = b[directionKey];
+    const aPeer = /** @type {string} */ (a[directionKey]);
+    const bPeer = /** @type {string} */ (b[directionKey]);
     return aPeer < bPeer ? -1 : aPeer > bPeer ? 1 : 0;
   });
   return deepFreeze(list);
@@ -493,9 +494,13 @@ export default class QueryBuilder {
    */
   constructor(graph) {
     this._graph = graph;
+    /** @type {string|null} */
     this._pattern = null;
+    /** @type {Array<{type: string, fn?: (node: QueryNodeSnapshot) => boolean, label?: string, depth?: [number, number]}>} */
     this._operations = [];
+    /** @type {string[]|null} */
     this._select = null;
+    /** @type {AggregateSpec|null} */
     this._aggregate = null;
   }
 
@@ -531,7 +536,7 @@ export default class QueryBuilder {
    */
   where(fn) {
     assertPredicate(fn);
-    const predicate = isPlainObject(fn) ? objectToPredicate(fn) : fn;
+    const predicate = isPlainObject(fn) ? objectToPredicate(/** @type {Record<string, unknown>} */ (fn)) : /** @type {(node: QueryNodeSnapshot) => boolean} */ (fn);
     this._operations.push({ type: 'where', fn: predicate });
     return this;
   }
@@ -628,11 +633,6 @@ export default class QueryBuilder {
    * The "props." prefix is optional and will be stripped automatically.
    *
    * @param {AggregateSpec} spec - Aggregation specification
-   * @param {boolean} [spec.count] - If true, include count of matched nodes
-   * @param {string} [spec.sum] - Property path to sum
-   * @param {string} [spec.avg] - Property path to average
-   * @param {string} [spec.min] - Property path to find minimum
-   * @param {string} [spec.max] - Property path to find maximum
    * @returns {QueryBuilder} This builder for chaining
    * @throws {QueryError} If spec is not a plain object (code: E_QUERY_AGGREGATE_TYPE)
    * @throws {QueryError} If numeric aggregation keys are not strings (code: E_QUERY_AGGREGATE_TYPE)
@@ -646,11 +646,12 @@ export default class QueryBuilder {
       });
     }
     const numericKeys = ['sum', 'avg', 'min', 'max'];
+    const specAny = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (spec));
     for (const key of numericKeys) {
-      if (spec[key] !== undefined && typeof spec[key] !== 'string') {
+      if (specAny[key] !== undefined && typeof specAny[key] !== 'string') {
         throw new QueryError(`aggregate() expects ${key} to be a string path`, {
           code: 'E_QUERY_AGGREGATE_TYPE',
-          context: { key, receivedType: typeof spec[key] },
+          context: { key, receivedType: typeof specAny[key] },
         });
       }
     }
@@ -674,7 +675,7 @@ export default class QueryBuilder {
    * @throws {QueryError} If an unknown select field is specified (code: E_QUERY_SELECT_FIELD)
    */
   async run() {
-    const materialized = await this._graph._materializeGraph();
+    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
     const { adjacency, stateHash } = materialized;
     const allNodes = sortIds(await this._graph.getNodes());
 
@@ -696,15 +697,16 @@ export default class QueryBuilder {
             };
           })
         );
+        const predicate = /** @type {(node: QueryNodeSnapshot) => boolean} */ (op.fn);
         const filtered = snapshots
-          .filter(({ snapshot }) => op.fn(snapshot))
+          .filter(({ snapshot }) => predicate(snapshot))
           .map(({ nodeId }) => nodeId);
         workingSet = sortIds(filtered);
         continue;
       }
 
       if (op.type === 'outgoing' || op.type === 'incoming') {
-        const [minD, maxD] = op.depth;
+        const [minD, maxD] = /** @type {[number, number]} */ (op.depth);
         if (minD === 1 && maxD === 1) {
           workingSet = applyHop({
             direction: op.type,
@@ -718,7 +720,7 @@ export default class QueryBuilder {
             label: op.label,
             workingSet,
             adjacency,
-            depth: op.depth,
+            depth: /** @type {[number, number]} */ (op.depth),
           });
         }
       }
@@ -778,21 +780,24 @@ export default class QueryBuilder {
    * @private
    */
   async _runAggregate(workingSet, stateHash) {
-    const spec = this._aggregate;
+    const spec = /** @type {AggregateSpec} */ (this._aggregate);
+    /** @type {AggregateResult} */
     const result = { stateHash };
+    const specRec = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (spec));
 
     if (spec.count) {
       result.count = workingSet.length;
     }
 
     const numericAggs = ['sum', 'avg', 'min', 'max'];
-    const activeAggs = numericAggs.filter((key) => spec[key]);
+    const activeAggs = numericAggs.filter((key) => specRec[key]);
 
     if (activeAggs.length > 0) {
+      /** @type {Map<string, {segments: string[], values: number[]}>} */
       const propsByAgg = new Map();
       for (const key of activeAggs) {
         propsByAgg.set(key, {
-          segments: spec[key].replace(/^props\./, '').split('.'),
+          segments: /** @type {string} */ (specRec[key]).replace(/^props\./, '').split('.'),
           values: [],
         });
       }
@@ -800,6 +805,7 @@ export default class QueryBuilder {
       for (const nodeId of workingSet) {
         const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
         for (const { segments, values } of propsByAgg.values()) {
+          /** @type {*} */ // TODO(ts-cleanup): type deep property traversal
           let value = propsMap.get(segments[0]);
           for (let i = 1; i < segments.length; i++) {
             if (value && typeof value === 'object') {
@@ -817,15 +823,15 @@ export default class QueryBuilder {
 
       for (const [key, { values }] of propsByAgg) {
         if (key === 'sum') {
-          result.sum = values.length > 0 ? values.reduce((a, b) => a + b, 0) : 0;
+          result.sum = values.length > 0 ? values.reduce((/** @type {number} */ a, /** @type {number} */ b) => a + b, 0) : 0;
         } else if (key === 'avg') {
-          result.avg = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+          result.avg = values.length > 0 ? values.reduce((/** @type {number} */ a, /** @type {number} */ b) => a + b, 0) / values.length : 0;
         } else if (key === 'min') {
           result.min =
-            values.length > 0 ? values.reduce((m, v) => (v < m ? v : m), Infinity) : 0;
+            values.length > 0 ? values.reduce((/** @type {number} */ m, /** @type {number} */ v) => (v < m ? v : m), Infinity) : 0;
         } else if (key === 'max') {
           result.max =
-            values.length > 0 ? values.reduce((m, v) => (v > m ? v : m), -Infinity) : 0;
+            values.length > 0 ? values.reduce((/** @type {number} */ m, /** @type {number} */ v) => (v > m ? v : m), -Infinity) : 0;
         }
       }
     }

package/src/domain/services/StateDiff.js

@@ -86,8 +86,8 @@ function compareProps(a, b) {
 
 /**
  * Checks if two arrays are deeply equal.
- * @param {Array} a
- * @param {Array} b
+ * @param {Array<*>} a
+ * @param {Array<*>} b
  * @returns {boolean}
  */
 function arraysEqual(a, b) {
@@ -104,8 +104,8 @@ function arraysEqual(a, b) {
 
 /**
  * Checks if two objects are deeply equal.
- * @param {Object} a
- * @param {Object} b
+ * @param {Record<string, *>} a
+ * @param {Record<string, *>} b
  * @returns {boolean}
  */
 function objectsEqual(a, b) {
@@ -155,9 +155,9 @@ function deepEqual(a, b) {
 
 /**
  * Computes set difference: elements in `after` not in `before`.
- * @param {Set} before
- * @param {Set} after
- * @returns {Array}
+ * @param {Set<string>} before
+ * @param {Set<string>} after
+ * @returns {Array<string>}
  */
 function setAdded(before, after) {
   const result = [];

package/src/domain/services/StateSerializerV5.js

@@ -1,4 +1,5 @@
 import defaultCodec from '../utils/defaultCodec.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
 import { orsetContains, orsetElements } from '../crdt/ORSet.js';
 import { decodeEdgeKey, decodePropKey } from './KeyCodec.js';
 
@@ -75,7 +76,7 @@ export function propVisibleV5(state, propKey) {
  * @param {import('./JoinReducer.js').WarpStateV5} state
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Buffer}
+ * @returns {Buffer|Uint8Array}
  */
 export function serializeStateV5(state, { codec } = {}) {
   const c = codec || defaultCodec;
@@ -122,13 +123,14 @@ export function serializeStateV5(state, { codec } = {}) {
  * Computes SHA-256 hash of canonical state bytes.
  * @param {import('./JoinReducer.js').WarpStateV5} state
  * @param {Object} [options] - Options
- * @param {import('../../ports/CryptoPort.js').default} options.crypto - CryptoPort instance
+ * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Promise<string|null>} Hex-encoded SHA-256 hash, or null if no crypto
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
-export async function computeStateHashV5(state, { crypto, codec } = {}) {
+export async function computeStateHashV5(state, { crypto, codec } = /** @type {{crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default}} */ ({})) {
+  const c = crypto || defaultCrypto;
   const serialized = serializeStateV5(state, { codec });
-  return crypto ? await crypto.hash('sha256', serialized) : null;
+  return await c.hash('sha256', serialized);
 }
 
 /**
@@ -141,7 +143,7 @@ export async function computeStateHashV5(state, { crypto, codec } = {}) {
  */
 export function deserializeStateV5(buffer, { codec } = {}) {
   const c = codec || defaultCodec;
-  return c.decode(buffer);
+  return /** @type {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: *}>}} */ (c.decode(buffer));
 }
 
 // ============================================================================

package/src/domain/services/StreamingBitmapIndexBuilder.js

@@ -1,4 +1,5 @@
 import defaultCodec from '../utils/defaultCodec.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
 import ShardCorruptionError from '../errors/ShardCorruptionError.js';
 import ShardValidationError from '../errors/ShardValidationError.js';
 import nullLogger from '../utils/nullLogger.js';
@@ -36,10 +37,9 @@ const BITMAP_BASE_OVERHEAD = 64;
  *
  * @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);
 };
@@ -89,6 +89,8 @@ export default class StreamingBitmapIndexBuilder {
    *   Receives { flushedBytes, totalFlushedBytes, flushCount }.
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
    *   Defaults to NoOpLogger (no logging).
+   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for hashing
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
    */
   constructor({ storage, maxMemoryBytes = DEFAULT_MAX_MEMORY_BYTES, onFlush, logger = nullLogger, crypto, codec }) {
     if (!storage) {
@@ -99,9 +101,9 @@ export default class StreamingBitmapIndexBuilder {
     }
 
     /** @type {import('../../ports/CryptoPort.js').default} */
-    this._crypto = crypto;
+    this._crypto = crypto || defaultCrypto;
 
-    /** @type {import('../../ports/CodecPort.js').default|undefined} */
+    /** @type {import('../../ports/CodecPort.js').default} */
     this._codec = codec || defaultCodec;
 
     /** @type {Object} */
@@ -122,7 +124,7 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {string[]} ID → SHA reverse mapping (kept in memory) */
     this.idToSha = [];
 
-    /** @type {Map<string, RoaringBitmap32>} Current in-memory bitmaps */
+    /** @type {Map<string, any>} Current in-memory bitmaps */
     this.bitmaps = new Map();
 
     /** @type {number} Estimated bytes used by current bitmaps */
@@ -137,8 +139,8 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {number} Number of flush operations performed */
     this.flushCount = 0;
 
-    /** @type {typeof import('roaring').RoaringBitmap32} Cached constructor */
-    this._RoaringBitmap32 = getRoaringBitmap32();
+    /** @type {any} Cached Roaring bitmap constructor */ // TODO(ts-cleanup): type lazy singleton
+    this._RoaringBitmap32 = getRoaringBitmap32(); // TODO(ts-cleanup): type lazy singleton
   }
 
   /**
@@ -189,11 +191,12 @@ export default class StreamingBitmapIndexBuilder {
    * Groups bitmaps by type ('fwd' or 'rev') and SHA prefix (first 2 hex chars).
    * Each bitmap is serialized to a portable format and base64-encoded.
    *
-   * @returns {{fwd: Object<string, Object<string, string>>, rev: Object<string, Object<string, string>>}}
+   * @returns {Record<string, Record<string, Record<string, string>>>}
    *   Object with 'fwd' and 'rev' keys, each mapping prefix to SHA→base64Bitmap entries
    * @private
    */
   _serializeBitmapsToShards() {
+    /** @type {Record<string, Record<string, Record<string, string>>>} */
     const bitmapShards = { fwd: {}, rev: {} };
     for (const [key, bitmap] of this.bitmaps) {
       const type = key.substring(0, 3);
@@ -215,7 +218,7 @@ export default class StreamingBitmapIndexBuilder {
    * The resulting blob OIDs are tracked in `flushedChunks` for later merging.
    * Writes are performed in parallel for efficiency.
    *
-   * @param {{fwd: Object<string, Object<string, string>>, rev: Object<string, Object<string, string>>}} bitmapShards
+   * @param {Record<string, Record<string, Record<string, string>>>} bitmapShards
    *   Object with 'fwd' and 'rev' keys containing prefix-grouped bitmap data
    * @returns {Promise<void>} Resolves when all shards have been written
    * @async
@@ -235,11 +238,11 @@ export default class StreamingBitmapIndexBuilder {
               data: shardData,
             };
             const buffer = Buffer.from(JSON.stringify(envelope));
-            const oid = await this.storage.writeBlob(buffer);
+            const oid = await /** @type {any} */ (this.storage).writeBlob(buffer); // TODO(ts-cleanup): narrow port type
             if (!this.flushedChunks.has(path)) {
               this.flushedChunks.set(path, []);
             }
-            this.flushedChunks.get(path).push(oid);
+            /** @type {string[]} */ (this.flushedChunks.get(path)).push(oid);
           })
         );
       }
@@ -310,6 +313,7 @@ export default class StreamingBitmapIndexBuilder {
    * @private
    */
   _buildMetaShards() {
+    /** @type {Record<string, Record<string, number>>} */
     const idShards = {};
     for (const [sha, id] of this.shaToId) {
       const prefix = sha.substring(0, 2);
@@ -344,7 +348,7 @@ export default class StreamingBitmapIndexBuilder {
           data: map,
         };
         const buffer = Buffer.from(JSON.stringify(envelope));
-        const oid = await this.storage.writeBlob(buffer);
+        const oid = await /** @type {any} */ (this.storage).writeBlob(buffer); // TODO(ts-cleanup): narrow port type
         return `100644 blob ${oid}\t${path}`;
       })
     );
@@ -436,18 +440,19 @@ export default class StreamingBitmapIndexBuilder {
 
     // Store frontier metadata for staleness detection
     if (frontier) {
+      /** @type {Record<string, number|undefined>} */
       const sorted = {};
       for (const key of Array.from(frontier.keys()).sort()) {
         sorted[key] = frontier.get(key);
       }
       const envelope = { version: 1, writerCount: frontier.size, frontier: sorted };
-      const cborOid = await this.storage.writeBlob(Buffer.from(this._codec.encode(envelope)));
+      const cborOid = await /** @type {any} */ (this.storage).writeBlob(Buffer.from(/** @type {any} */ (this._codec).encode(envelope))); // TODO(ts-cleanup): narrow port type
       flatEntries.push(`100644 blob ${cborOid}\tfrontier.cbor`);
-      const jsonOid = await this.storage.writeBlob(Buffer.from(canonicalStringify(envelope)));
+      const jsonOid = await /** @type {any} */ (this.storage).writeBlob(Buffer.from(canonicalStringify(envelope))); // TODO(ts-cleanup): narrow port type
       flatEntries.push(`100644 blob ${jsonOid}\tfrontier.json`);
     }
 
-    const treeOid = await this.storage.writeTree(flatEntries);
+    const treeOid = await /** @type {any} */ (this.storage).writeTree(flatEntries); // TODO(ts-cleanup): narrow port type
 
     this.logger.debug('Index finalized', {
       operation: 'finalize',
@@ -501,7 +506,7 @@ export default class StreamingBitmapIndexBuilder {
    */
   _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);
@@ -564,7 +569,7 @@ export default class StreamingBitmapIndexBuilder {
    * @private
    */
   async _loadAndValidateChunk(oid) {
-    const buffer = await this.storage.readBlob(oid);
+    const buffer = await /** @type {any} */ (this.storage).readBlob(oid); // TODO(ts-cleanup): narrow port type
     let envelope;
     try {
       envelope = JSON.parse(buffer.toString('utf-8'));
@@ -572,14 +577,13 @@ export default class StreamingBitmapIndexBuilder {
       throw new ShardCorruptionError('Failed to parse shard JSON', {
         oid,
         reason: 'invalid_format',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
     }
 
     // Validate version
     if (envelope.version !== SHARD_VERSION) {
       throw new ShardValidationError('Shard version mismatch', {
-        oid,
         expected: SHARD_VERSION,
         actual: envelope.version,
         field: 'version',
@@ -610,7 +614,7 @@ export default class StreamingBitmapIndexBuilder {
    * it using `orInPlace` to combine edge sets.
    *
    * @param {Object} opts - Options object
-   * @param {Object<string, RoaringBitmap32>} opts.merged - Object mapping SHA to
+   * @param {Record<string, any>} opts.merged - Object mapping SHA to
    *   RoaringBitmap32 instances (mutated in place)
    * @param {string} opts.sha - The SHA key for this bitmap (40-character hex string)
    * @param {string} opts.base64Bitmap - Base64-encoded serialized RoaringBitmap32 data
@@ -627,7 +631,7 @@ export default class StreamingBitmapIndexBuilder {
       throw new ShardCorruptionError('Failed to deserialize bitmap', {
         oid,
         reason: 'invalid_bitmap',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
     }
 
@@ -671,6 +675,7 @@ export default class StreamingBitmapIndexBuilder {
    */
   async _mergeChunks(oids, { signal } = {}) {
     // Load all chunks and merge bitmaps by SHA
+    /** @type {Record<string, any>} */
     const merged = {};
 
     for (const oid of oids) {
@@ -683,6 +688,7 @@ export default class StreamingBitmapIndexBuilder {
     }
 
     // Serialize merged result
+    /** @type {Record<string, string>} */
     const result = {};
     for (const [sha, bitmap] of Object.entries(merged)) {
       result[sha] = bitmap.serialize(true).toString('base64');
@@ -701,9 +707,9 @@ export default class StreamingBitmapIndexBuilder {
     } catch (err) {
       throw new ShardCorruptionError('Failed to serialize merged shard', {
         reason: 'serialization_error',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
     }
-    return this.storage.writeBlob(serialized);
+    return /** @type {any} */ (this.storage).writeBlob(serialized); // TODO(ts-cleanup): narrow port type
   }
 }