@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/infrastructure/adapters/InMemoryGraphAdapter.js

@@ -0,0 +1,488 @@
+/* eslint-disable @typescript-eslint/require-await -- all async methods match the port contract */
+/**
+ * @fileoverview In-memory persistence adapter for WARP graph storage.
+ *
+ * Implements the same {@link GraphPersistencePort} contract as GitGraphAdapter
+ * but stores all data in Maps. Designed for fast unit/integration tests that
+ * don't need real Git I/O.
+ *
+ * SHA computation follows Git's object format so debugging is straightforward,
+ * but cross-adapter SHA matching is NOT guaranteed.
+ *
+ * @module infrastructure/adapters/InMemoryGraphAdapter
+ */
+
+import { createHash } from 'node:crypto';
+import { Readable } from 'node:stream';
+import GraphPersistencePort from '../../ports/GraphPersistencePort.js';
+import { validateOid, validateRef, validateLimit, validateConfigKey } from './adapterValidation.js';
+
+/** Well-known SHA for Git's empty tree. */
+const EMPTY_TREE_OID = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+// ── SHA helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Computes a Git blob SHA-1: `SHA1("blob " + len + "\0" + content)`.
+ * @param {Buffer} content
+ * @returns {string} 40-hex SHA
+ */
+function hashBlob(content) {
+  const header = Buffer.from(`blob ${content.length}\0`);
+  return createHash('sha1').update(header).update(content).digest('hex');
+}
+
+/**
+ * Builds the binary tree buffer in Git's internal format and hashes it.
+ *
+ * Each entry is: `<mode> <path>\0<20-byte binary OID>`
+ * Entries are sorted by path (byte order), matching Git's canonical sort.
+ *
+ * @param {Array<{mode: string, path: string, oid: string}>} entries
+ * @returns {string} 40-hex SHA
+ */
+function hashTree(entries) {
+  const sorted = [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const parts = sorted.map(e => {
+    const prefix = Buffer.from(`${e.mode} ${e.path}\0`);
+    const oidBin = Buffer.from(e.oid, 'hex');
+    return Buffer.concat([prefix, oidBin]);
+  });
+  const body = Buffer.concat(parts);
+  const header = Buffer.from(`tree ${body.length}\0`);
+  return createHash('sha1').update(header).update(body).digest('hex');
+}
+
+/**
+ * Builds a Git-style commit string and hashes it.
+ * @param {{treeOid: string, parents: string[], message: string, author: string, date: string}} opts
+ * @returns {string} 40-hex SHA
+ */
+function hashCommit({ treeOid, parents, message, author, date }) {
+  const lines = [`tree ${treeOid}`];
+  for (const p of parents) {
+    lines.push(`parent ${p}`);
+  }
+  lines.push(`author ${author} ${date}`);
+  lines.push(`committer ${author} ${date}`);
+  lines.push('');
+  lines.push(message);
+  const body = lines.join('\n');
+  const header = `commit ${Buffer.byteLength(body)}\0`;
+  return createHash('sha1').update(header).update(body).digest('hex');
+}
+
+// ── Adapter ─────────────────────────────────────────────────────────────
+
+/**
+ * In-memory implementation of {@link GraphPersistencePort}.
+ *
+ * Data structures:
+ * - `_commits` — Map<sha, {treeOid, parents[], message, author, date}>
+ * - `_blobs`   — Map<oid, Buffer>
+ * - `_trees`   — Map<oid, Array<{mode, path, oid}>>
+ * - `_refs`    — Map<refName, sha>
+ * - `_config`  — Map<key, value>
+ *
+ * @extends GraphPersistencePort
+ */
+export default class InMemoryGraphAdapter extends GraphPersistencePort {
+  /**
+   * @param {{ author?: string, clock?: { now: () => number } }} [options]
+   */
+  constructor({ author, clock } = {}) {
+    super();
+    this._author = author || 'InMemory <inmemory@test>';
+    this._clock = clock || { now: () => Date.now() };
+
+    /** @type {Map<string, {treeOid: string, parents: string[], message: string, author: string, date: string}>} */
+    this._commits = new Map();
+    /** @type {Map<string, Buffer>} */
+    this._blobs = new Map();
+    /** @type {Map<string, Array<{mode: string, path: string, oid: string}>>} */
+    this._trees = new Map();
+    /** @type {Map<string, string>} */
+    this._refs = new Map();
+    /** @type {Map<string, string>} */
+    this._config = new Map();
+  }
+
+  // ── TreePort ────────────────────────────────────────────────────────
+
+  /** @type {string} */
+  get emptyTree() {
+    return EMPTY_TREE_OID;
+  }
+
+  /**
+   * Creates a tree from mktree-formatted entries.
+   * @param {string[]} entries - Lines in `"<mode> <type> <oid>\t<path>"` format
+   * @returns {Promise<string>}
+   */
+  async writeTree(entries) {
+    const parsed = entries.map(line => {
+      const tabIdx = line.indexOf('\t');
+      if (tabIdx === -1) {
+        throw new Error(`Invalid mktree entry (missing tab): ${line}`);
+      }
+      const meta = line.slice(0, tabIdx);
+      const path = line.slice(tabIdx + 1);
+      const [mode, , oid] = meta.split(' ');
+      return { mode, path, oid };
+    });
+    const oid = hashTree(parsed);
+    this._trees.set(oid, parsed);
+    return oid;
+  }
+
+  /**
+   * @param {string} treeOid
+   * @returns {Promise<Record<string, string>>}
+   */
+  async readTreeOids(treeOid) {
+    validateOid(treeOid);
+    if (treeOid === EMPTY_TREE_OID) {
+      return {};
+    }
+    const entries = this._trees.get(treeOid);
+    if (!entries) {
+      throw new Error(`Tree not found: ${treeOid}`);
+    }
+    /** @type {Record<string, string>} */
+    const result = {};
+    for (const e of entries) {
+      result[e.path] = e.oid;
+    }
+    return result;
+  }
+
+  /**
+   * @param {string} treeOid
+   * @returns {Promise<Record<string, Buffer>>}
+   */
+  async readTree(treeOid) {
+    const oids = await this.readTreeOids(treeOid);
+    /** @type {Record<string, Buffer>} */
+    const files = {};
+    for (const [path, oid] of Object.entries(oids)) {
+      files[path] = await this.readBlob(oid);
+    }
+    return files;
+  }
+
+  // ── BlobPort ────────────────────────────────────────────────────────
+
+  /**
+   * @param {Buffer|string} content
+   * @returns {Promise<string>}
+   */
+  async writeBlob(content) {
+    const buf = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    const oid = hashBlob(buf);
+    this._blobs.set(oid, buf);
+    return oid;
+  }
+
+  /**
+   * @param {string} oid
+   * @returns {Promise<Buffer>}
+   */
+  async readBlob(oid) {
+    validateOid(oid);
+    const buf = this._blobs.get(oid);
+    if (!buf) {
+      throw new Error(`Blob not found: ${oid}`);
+    }
+    return buf;
+  }
+
+  // ── CommitPort ──────────────────────────────────────────────────────
+
+  /**
+   * @param {{ message: string, parents?: string[], sign?: boolean }} options
+   * @returns {Promise<string>}
+   */
+  async commitNode({ message, parents = [] }) {
+    for (const p of parents) {
+      validateOid(p);
+    }
+    return this._createCommit(EMPTY_TREE_OID, parents, message);
+  }
+
+  /**
+   * @param {{ treeOid: string, parents?: string[], message: string, sign?: boolean }} options
+   * @returns {Promise<string>}
+   */
+  async commitNodeWithTree({ treeOid, parents = [], message }) {
+    validateOid(treeOid);
+    for (const p of parents) {
+      validateOid(p);
+    }
+    return this._createCommit(treeOid, parents, message);
+  }
+
+  /**
+   * @param {string} sha
+   * @returns {Promise<string>}
+   */
+  async showNode(sha) {
+    validateOid(sha);
+    const commit = this._commits.get(sha);
+    if (!commit) {
+      throw new Error(`Commit not found: ${sha}`);
+    }
+    return commit.message;
+  }
+
+  /**
+   * @param {string} sha
+   * @returns {Promise<{sha: string, message: string, author: string, date: string, parents: string[]}>}
+   */
+  async getNodeInfo(sha) {
+    validateOid(sha);
+    const commit = this._commits.get(sha);
+    if (!commit) {
+      throw new Error(`Commit not found: ${sha}`);
+    }
+    return {
+      sha,
+      message: commit.message,
+      author: commit.author,
+      date: commit.date,
+      parents: [...commit.parents],
+    };
+  }
+
+  /**
+   * @param {string} sha
+   * @returns {Promise<boolean>}
+   */
+  async nodeExists(sha) {
+    validateOid(sha);
+    return this._commits.has(sha);
+  }
+
+  /**
+   * @param {string} ref
+   * @returns {Promise<number>}
+   */
+  async countNodes(ref) {
+    validateRef(ref);
+    const tip = this._resolveRef(ref);
+    if (!tip) {
+      throw new Error(`Ref not found: ${ref}`);
+    }
+    const visited = new Set();
+    const stack = [tip];
+    while (stack.length > 0) {
+      const sha = /** @type {string} */ (stack.pop());
+      if (visited.has(sha)) {
+        continue;
+      }
+      visited.add(sha);
+      const commit = this._commits.get(sha);
+      if (commit) {
+        for (const p of commit.parents) {
+          stack.push(p);
+        }
+      }
+    }
+    return visited.size;
+  }
+
+  /**
+   * @param {{ ref: string, limit?: number, format?: string }} options
+   * @returns {Promise<string>}
+   */
+  async logNodes({ ref, limit = 50, format: _format }) {
+    validateRef(ref);
+    validateLimit(limit);
+    const records = this._walkLog(ref, limit);
+    // Format param is accepted for port compatibility but always uses
+    // the GitLogParser-compatible layout (SHA\nauthor\ndate\nparents\nmessage).
+    if (!_format) {
+      return records.map(c => `commit ${c.sha}\nAuthor: ${c.author}\nDate:   ${c.date}\n\n    ${c.message}\n`).join('\n');
+    }
+    return records.map(c => this._formatCommitRecord(c)).join('\0') + (records.length > 0 ? '\0' : '');
+  }
+
+  /**
+   * @param {{ ref: string, limit?: number, format?: string }} options
+   * @returns {Promise<Readable>}
+   */
+  async logNodesStream({ ref, limit = 1000000, format: _format }) {
+    validateRef(ref);
+    validateLimit(limit);
+    const records = this._walkLog(ref, limit);
+    const formatted = records.map(c => this._formatCommitRecord(c)).join('\0') + (records.length > 0 ? '\0' : '');
+    return Readable.from([formatted]);
+  }
+
+  /**
+   * @returns {Promise<{ok: boolean, latencyMs: number}>}
+   */
+  async ping() {
+    return { ok: true, latencyMs: 0 };
+  }
+
+  // ── RefPort ─────────────────────────────────────────────────────────
+
+  /**
+   * @param {string} ref
+   * @param {string} oid
+   * @returns {Promise<void>}
+   */
+  async updateRef(ref, oid) {
+    validateRef(ref);
+    validateOid(oid);
+    this._refs.set(ref, oid);
+  }
+
+  /**
+   * @param {string} ref
+   * @returns {Promise<string|null>}
+   */
+  async readRef(ref) {
+    validateRef(ref);
+    return this._refs.get(ref) || null;
+  }
+
+  /**
+   * @param {string} ref
+   * @returns {Promise<void>}
+   */
+  async deleteRef(ref) {
+    validateRef(ref);
+    this._refs.delete(ref);
+  }
+
+  /**
+   * @param {string} prefix
+   * @returns {Promise<string[]>}
+   */
+  async listRefs(prefix) {
+    validateRef(prefix);
+    const result = [];
+    for (const key of this._refs.keys()) {
+      if (key.startsWith(prefix)) {
+        result.push(key);
+      }
+    }
+    return result.sort();
+  }
+
+  // ── ConfigPort ──────────────────────────────────────────────────────
+
+  /**
+   * @param {string} key
+   * @returns {Promise<string|null>}
+   */
+  async configGet(key) {
+    validateConfigKey(key);
+    return this._config.get(key) ?? null;
+  }
+
+  /**
+   * @param {string} key
+   * @param {string} value
+   * @returns {Promise<void>}
+   */
+  async configSet(key, value) {
+    validateConfigKey(key);
+    if (typeof value !== 'string') {
+      throw new Error('Config value must be a string');
+    }
+    this._config.set(key, value);
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────────
+
+  /**
+   * @param {string} treeOid
+   * @param {string[]} parents
+   * @param {string} message
+   * @returns {string}
+   */
+  _createCommit(treeOid, parents, message) {
+    const date = new Date(this._clock.now()).toISOString();
+    const sha = hashCommit({
+      treeOid,
+      parents,
+      message,
+      author: this._author,
+      date,
+    });
+    this._commits.set(sha, {
+      treeOid,
+      parents: [...parents],
+      message,
+      author: this._author,
+      date,
+    });
+    return sha;
+  }
+
+  /**
+   * Resolves a ref name to a SHA. If the ref looks like a raw SHA, returns it.
+   * @param {string} ref
+   * @returns {string|null}
+   */
+  _resolveRef(ref) {
+    if (this._refs.has(ref)) {
+      return /** @type {string} */ (this._refs.get(ref));
+    }
+    if (this._commits.has(ref)) {
+      return ref;
+    }
+    return null;
+  }
+
+  /**
+   * Walks commit history from a ref, reverse chronological (newest first),
+   * up to limit. Matches `git log` default ordering for merge DAGs.
+   * @param {string} ref
+   * @param {number} limit
+   * @returns {Array<{sha: string, message: string, author: string, date: string, parents: string[]}>}
+   */
+  _walkLog(ref, limit) {
+    const tip = this._resolveRef(ref);
+    if (!tip) {
+      return [];
+    }
+    /** @type {Array<{sha: string, message: string, author: string, date: string, parents: string[]}>} */
+    const all = [];
+    const visited = new Set();
+    const queue = [tip];
+    let head = 0;
+    while (head < queue.length) {
+      const sha = /** @type {string} */ (queue[head++]);
+      if (visited.has(sha)) {
+        continue;
+      }
+      visited.add(sha);
+      const commit = this._commits.get(sha);
+      if (!commit) {
+        continue;
+      }
+      all.push({ sha, ...commit });
+      for (const p of commit.parents) {
+        if (!visited.has(p)) {
+          queue.push(p);
+        }
+      }
+    }
+    // Sort by date descending (reverse chronological), matching git log
+    all.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+    return all.slice(0, limit);
+  }
+
+  /**
+   * Formats a commit record in GitLogParser's expected format:
+   * `<SHA>\n<author>\n<date>\n<parents>\n<message>`
+   * @param {{sha: string, message: string, author: string, date: string, parents: string[]}} c
+   * @returns {string}
+   */
+  _formatCommitRecord(c) {
+    return `${c.sha}\n${c.author}\n${c.date}\n${c.parents.join(' ')}\n${c.message}`;
+  }
+}

package/src/infrastructure/adapters/NodeCryptoAdapter.js

@@ -13,19 +13,32 @@ import {
  * @extends CryptoPort
  */
 export default class NodeCryptoAdapter extends CryptoPort {
-  /** @inheritdoc */
+  /**
+   * @param {string} algorithm
+   * @param {string|Buffer|Uint8Array} data
+   * @returns {Promise<string>}
+   */
   // eslint-disable-next-line @typescript-eslint/require-await -- async ensures sync throws become rejected promises
   async hash(algorithm, data) {
     return createHash(algorithm).update(data).digest('hex');
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {string} algorithm
+   * @param {string|Buffer|Uint8Array} key
+   * @param {string|Buffer|Uint8Array} data
+   * @returns {Promise<Buffer>}
+   */
   // eslint-disable-next-line @typescript-eslint/require-await -- async ensures sync throws become rejected promises
   async hmac(algorithm, key, data) {
     return createHmac(algorithm, key).update(data).digest();
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Buffer|Uint8Array} a
+   * @param {Buffer|Uint8Array} b
+   * @returns {boolean}
+   */
   timingSafeEqual(a, b) {
     return nodeTimingSafeEqual(a, b);
   }

package/src/infrastructure/adapters/NodeHttpAdapter.js

@@ -7,6 +7,9 @@ const MAX_BODY_BYTES = 10 * 1024 * 1024;
 /**
  * Collects the request body and dispatches to the handler, returning
  * a 500 response if the handler throws.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ handler: Function, logger: { error: Function } }} options
  */
 async function dispatch(req, res, { handler, logger }) {
   try {
@@ -60,33 +63,52 @@ export default class NodeHttpAdapter extends HttpServerPort {
     this._logger = logger || noopLogger;
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Function} requestHandler
+   * @returns {{ listen: Function, close: Function, address: Function }}
+   */
   createServer(requestHandler) {
     const logger = this._logger;
     const server = createServer((req, res) => {
-      dispatch(req, res, { handler: requestHandler, logger }).catch((err) => {
-        logger.error('[NodeHttpAdapter] unhandled dispatch error:', err);
-      });
+      dispatch(req, res, { handler: requestHandler, logger }).catch(
+        /** @param {*} err */ (err) => {
+          logger.error('[NodeHttpAdapter] unhandled dispatch error:', err);
+        });
     });
 
     return {
+      /**
+       * @param {number} port
+       * @param {string|Function} [host]
+       * @param {Function} [callback]
+       */
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
         const bindHost = typeof host === 'string' ? host : undefined;
+        /** @param {*} err */
         const onError = (err) => {
           if (cb) {
             cb(err);
           }
         };
         server.once('error', onError);
-        const args = bindHost !== undefined ? [port, bindHost] : [port];
-        server.listen(...args, () => {
-          server.removeListener('error', onError);
-          if (cb) {
-            cb(null);
-          }
-        });
+        if (bindHost !== undefined) {
+          server.listen(port, bindHost, () => {
+            server.removeListener('error', onError);
+            if (cb) {
+              cb(null);
+            }
+          });
+        } else {
+          server.listen(port, () => {
+            server.removeListener('error', onError);
+            if (cb) {
+              cb(null);
+            }
+          });
+        }
       },
+      /** @param {((err?: Error) => void)} [callback] */
       close(callback) {
         server.close(callback);
       },

package/src/infrastructure/adapters/WebCryptoAdapter.js

@@ -2,9 +2,9 @@ import CryptoPort from '../../ports/CryptoPort.js';
 
 /**
  * Map of common algorithm names to Web Crypto API algorithm identifiers.
- * @const {Object<string, string>}
+ * @const {Record<string, string>}
  */
-const ALGO_MAP = {
+const ALGO_MAP = /** @type {Record<string, string>} */ ({
   'sha-1': 'SHA-1',
   'sha1': 'SHA-1',
   'sha-256': 'SHA-256',
@@ -13,7 +13,7 @@ const ALGO_MAP = {
   'sha384': 'SHA-384',
   'sha-512': 'SHA-512',
   'sha512': 'SHA-512',
-};
+});
 
 /**
  * Converts a common algorithm name to the Web Crypto API identifier.
@@ -38,8 +38,9 @@ function toWebCryptoAlgo(algorithm) {
 function toUint8Array(data) {
   if (data instanceof Uint8Array) { return data; }
   if (typeof data === 'string') { return new TextEncoder().encode(data); }
-  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(data)) {
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(/** @type {*} */ (data))) { // TODO(ts-cleanup): narrow port type
+    const buf = /** @type {Buffer} */ (/** @type {*} */ (data)); // TODO(ts-cleanup): narrow port type
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
   }
   throw new Error('WebCryptoAdapter: data must be string, Buffer, or Uint8Array');
 }
@@ -59,7 +60,7 @@ function bufToHex(buf) {
  * Web Crypto API adapter implementing CryptoPort.
  *
  * Uses the standard Web Crypto API (globalThis.crypto.subtle) which is
- * available in browsers, Deno, Bun, and Node.js 20+.
+ * available in browsers, Deno, Bun, and Node.js 22+.
  *
  * All hash and HMAC operations are async because the Web Crypto API
  * is inherently promise-based.
@@ -77,26 +78,35 @@ export default class WebCryptoAdapter extends CryptoPort {
     this._subtle = subtle || globalThis.crypto.subtle;
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {string} algorithm
+   * @param {string|Buffer|Uint8Array} data
+   * @returns {Promise<string>}
+   */
   async hash(algorithm, data) {
     const digest = await this._subtle.digest(
       toWebCryptoAlgo(algorithm),
-      toUint8Array(data),
+      /** @type {BufferSource} */ (toUint8Array(data)),
     );
     return bufToHex(digest);
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {string} algorithm
+   * @param {string|Buffer|Uint8Array} key
+   * @param {string|Buffer|Uint8Array} data
+   * @returns {Promise<Uint8Array>}
+   */
   async hmac(algorithm, key, data) {
     const keyBytes = toUint8Array(key);
     const cryptoKey = await this._subtle.importKey(
       'raw',
-      keyBytes,
+      /** @type {BufferSource} */ (keyBytes),
       { name: 'HMAC', hash: toWebCryptoAlgo(algorithm) },
       false,
       ['sign'],
     );
-    const signature = await this._subtle.sign('HMAC', cryptoKey, toUint8Array(data));
+    const signature = await this._subtle.sign('HMAC', cryptoKey, /** @type {BufferSource} */ (toUint8Array(data)));
     return new Uint8Array(signature);
   }