carto-md 2.0.6 → 2.0.8

package/src/acp/providers/index.js

@@ -30,20 +30,12 @@ class ProviderRegistry {
     this._config = null;
   }
 
-  /**
-   * list() — Returns supported providers for ACP providers/list.
-   */
-  list() {
-    return SUPPORTED_PROVIDERS.map(p => ({
-      id: p.id,
-      name: p.name,
-      defaultModel: p.defaultModel,
-      models: p.models,
-    }));
-  }
+  // list() was removed — it was only called by a dropped custom
+  // provider-list ACP method that the SDK never actually dispatched.
+  // SUPPORTED_PROVIDERS is still exported for external callers / tests.
 
   /**
-   * set(params) — Configures the active provider from ACP providers/set.
+   * set(params) — Configures the active provider.
    * params: { providerId, apiKey, baseUrl?, model? }
    */
   set(params) {

package/src/agents/leiden.js

@@ -300,24 +300,18 @@ function clusterByGraph(importGraph, gamma = 0.03, keywordSeeds = {}) {
 
   // Name each community
   const commNames = new Map();
-  const usedNames = new Map(); // name → count (for deduplication)
 
   for (const [commId, members] of communities) {
-    let name = nameCommunity(members, keywordSeeds);
-
-    // Deduplicate: if name already used, append a number
-    if (usedNames.has(name)) {
-      const count = usedNames.get(name) + 1;
-      usedNames.set(name, count);
-      name = `${name}_${count}`;
-    } else {
-      usedNames.set(name, 1);
-    }
-
+    const name = nameCommunity(members, keywordSeeds);
     commNames.set(commId, name);
   }
 
-  // Build final file → domain map
+  // Build final file → domain map.
+  // When multiple communities resolve to the same base name (e.g. with a
+  // dense import graph, several disjoint sub-systems can each rank highest
+  // for AUTH), merge them into a single domain. The keyword that names the
+  // domain is the user-visible truth; preserving "AUTH_2", "AUTH_3", ...
+  // suffixes leaks Leiden's internal community count into the UI.
   const result = new Map();
   for (const [node, commId] of communityMap) {
     result.set(node, commNames.get(commId) || 'CORE');

package/src/bitmap/bitset.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * Bitset — Uint32Array-backed dense bitmap.
+ *
+ * 60-line implementation,
+ * zero deps. Used by Carto's bitmap engine (`src/bitmap/`) for sub-millisecond
+ * forward/reverse adjacency queries on the import graph.
+ *
+ * Operations are word-level (32-bit lanes) — `or`, `and`, `andNot`, `popcount`,
+ * `iterate` all run at one cycle per 32 bits on modern CPUs. For Carto's typical
+ * 10K-file repos this is 312 words per bitmap → tens of nanoseconds for a
+ * popcount, microseconds for a 1-hop frontier expansion.
+ *
+ * Layout: bit `i` lives in `words[i >>> 5]` at lane `i & 31`. Out-of-range reads
+ * return false; out-of-range writes are caller's responsibility (the bitset
+ * does not auto-grow — it's sized at construction to the max file id + 1).
+ */
+class Bitset {
+  /**
+   * @param {number} size — Number of bits (i.e. max file id + 1).
+   */
+  constructor(size) {
+    this.size = size;
+    this.words = new Uint32Array(Math.ceil(size / 32));
+  }
+
+  /** Set bit `i` to 1. */
+  set(i) { this.words[i >>> 5] |= (1 << (i & 31)); }
+
+  /** Clear bit `i` (set to 0). */
+  clear(i) { this.words[i >>> 5] &= ~(1 << (i & 31)); }
+
+  /** Return true if bit `i` is set. */
+  has(i) { return (this.words[i >>> 5] & (1 << (i & 31))) !== 0; }
+
+  /** Bitwise OR. Returns a new Bitset sized to the larger of the two. */
+  or(other) {
+    const r = new Bitset(Math.max(this.size, other.size));
+    for (let i = 0; i < this.words.length; i++) r.words[i] = this.words[i];
+    for (let i = 0; i < other.words.length; i++) r.words[i] |= other.words[i];
+    return r;
+  }
+
+  /** Bitwise AND. Returns a new Bitset sized to `this`. */
+  and(other) {
+    const r = new Bitset(this.size);
+    const len = Math.min(this.words.length, other.words.length);
+    for (let i = 0; i < len; i++) r.words[i] = this.words[i] & other.words[i];
+    return r;
+  }
+
+  /** Bitwise AND-NOT (this & ~other). Returns a new Bitset sized to `this`. */
+  andNot(other) {
+    const r = new Bitset(this.size);
+    for (let i = 0; i < this.words.length; i++) {
+      r.words[i] = this.words[i] & ~(other.words[i] || 0);
+    }
+    return r;
+  }
+
+  /**
+   * In-place bitwise OR. Mutates `this` to `this | other` and returns `this`.
+   *
+   * Used by hot BFS loops (`blastRadius`, `simulateChangeImpact`)
+   * to avoid the per-hop Uint32Array allocation that `.or()` performs.
+   * If `other` is wider than `this`, words beyond `this.size` are dropped —
+   * callers that care about size growth should resize before calling.
+   */
+  orInPlace(other) {
+    const n = Math.min(this.words.length, other.words.length);
+    for (let i = 0; i < n; i++) this.words[i] |= other.words[i];
+    return this;
+  }
+
+  /**
+   * In-place bitwise AND-NOT. Mutates `this` to `this & ~other` and
+   * returns `this`.
+   */
+  andNotInPlace(other) {
+    const n = Math.min(this.words.length, other.words.length);
+    for (let i = 0; i < n; i++) this.words[i] &= ~other.words[i];
+    // If `other` is shorter than `this`, the trailing words stay as-is —
+    // andNot with implicit-zero is a no-op.
+    return this;
+  }
+
+  /**
+   * Copy bits from `other` into `this` (mutates and returns `this`).
+   *
+   * The receiver's word array is reused — no new allocation.
+   * If sizes differ, the overlapping prefix is copied and the suffix of
+   * `this` (if any) is zeroed so stale bits don't leak.
+   */
+  copyFrom(other) {
+    if (this.words.length === other.words.length) {
+      this.words.set(other.words);
+    } else {
+      const n = Math.min(this.words.length, other.words.length);
+      for (let i = 0; i < n; i++) this.words[i] = other.words[i];
+      for (let i = n; i < this.words.length; i++) this.words[i] = 0;
+    }
+    return this;
+  }
+
+  /**
+   * Set every word to `value` (defaults to 0). Mutates and returns `this`.
+   *
+   * The hot use case is `setAll(0)` to clear the transient
+   * frontier bitset between BFS hops without reallocating its 32-bit lanes.
+   */
+  setAll(value = 0) {
+    this.words.fill(value >>> 0);
+    return this;
+  }
+
+  /**
+   * Population count (number of set bits).
+   * Hamming weight via parallel bit-fold — same kernel as POPCNT but portable
+   * across Node runtimes that don't expose hardware popcount.
+   */
+  popcount() {
+    let c = 0;
+    for (let i = 0; i < this.words.length; i++) {
+      let v = this.words[i];
+      v = v - ((v >>> 1) & 0x55555555);
+      v = (v & 0x33333333) + ((v >>> 2) & 0x33333333);
+      c += (((v + (v >>> 4)) & 0x0F0F0F0F) * 0x01010101) >>> 24;
+    }
+    return c;
+  }
+
+  /**
+   * Returns an array of every set bit's index (file id), in ascending order.
+   * Uses the `v & -v` LSB trick to skip zero lanes early.
+   */
+  iterate() {
+    const result = [];
+    for (let w = 0; w < this.words.length; w++) {
+      let v = this.words[w];
+      while (v) {
+        const bit = v & (-v);
+        result.push((w << 5) + (31 - Math.clz32(bit)));
+        v ^= bit;
+      }
+    }
+    return result;
+  }
+
+  /** Deep copy. */
+  clone() {
+    const r = new Bitset(this.size);
+    r.words.set(this.words);
+    return r;
+  }
+
+  /**
+   * Serialize to a Buffer. Layout: just the raw word bytes (LE on x86/ARM
+   * Node hosts; Carto runs Node so endianness matches the running machine —
+   * the on-disk file is per-machine just like SQLite's `carto.db`).
+   *
+   * Size in bytes: `Math.ceil(size / 32) * 4`. Caller persists the `size`
+   * separately so deserialize knows how many bits to expect.
+   */
+  serialize() {
+    return Buffer.from(this.words.buffer, this.words.byteOffset, this.words.byteLength);
+  }
+
+  /**
+   * Reconstruct a Bitset from a Buffer + the original size.
+   *
+   * @param {Buffer} buf — Bytes produced by `serialize()`.
+   * @param {number} size — Bit count (must match the serialized bitset).
+   * @returns {Bitset}
+   */
+  static deserialize(buf, size) {
+    const r = new Bitset(size);
+    // Copy through a Uint8Array view so we don't alias buf's underlying
+    // ArrayBuffer (which may be shared with Node's internal pool).
+    const expected = r.words.byteLength;
+    if (buf.length < expected) {
+      throw new Error(`Bitset.deserialize: buffer too small (got ${buf.length}, need ${expected})`);
+    }
+    const u8 = new Uint8Array(r.words.buffer, r.words.byteOffset, expected);
+    for (let i = 0; i < expected; i++) u8[i] = buf[i];
+    return r;
+  }
+}
+
+module.exports = { Bitset };

package/src/bitmap/index.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * Bitmap engine orchestrator — freshness, persistence, and process-lifetime cache.
+ *
+ * Wraps `sidecar.js` with a simple lifecycle: SQLite is the durable
+ * source of truth, the bitmap layer is derived + disposable, and a
+ * stale or corrupt bitmap.bin must never be a correctness problem —
+ * we just rebuild.
+ *
+ * Public surface:
+ *   ensureBitmapFresh(cartoDir, store) → sidecar object
+ *     Returns a fresh sidecar suitable for the bitmap query tools. If
+ *     `.carto/bitmap.bin` is missing, older than `.carto/carto.db`, or
+ *     fails to load (corrupt / version mismatch), rebuilds from `store`
+ *     and re-persists.
+ *
+ *   invalidate(cartoDir?) → void
+ *     Clears the in-memory cache. If `cartoDir` is given, also deletes
+ *     the on-disk bitmap.bin so a follow-up `ensureBitmapFresh` from a
+ *     different process triggers a rebuild even if the carto.db mtime
+ *     didn't bump (e.g. write within the same mtime granularity).
+ *
+ *   _resetForTests() → void
+ *     Test-only escape hatch — drops the cache without filesystem side
+ *     effects. The leading underscore signals "do not use in production."
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  buildFromStore,
+  saveToDisk,
+  loadFromDisk,
+  BITMAP_FILENAME,
+} = require('./sidecar');
+
+// Process-lifetime cache. The MCP server is one Node process per repo,
+// so a singleton matches the lifecycle correctly. `cartoDir` is part of
+// the key so the (rare) case where one process serves multiple repos
+// — e.g. tests that spin up several MCP servers in sequence — doesn't
+// hand a stale sidecar to the wrong project.
+let cached = null;
+
+/**
+ * Returns true if `bitmapPath` exists and is at least as fresh as `dbPath`.
+ * Files with identical mtimes are treated as fresh — the bitmap was almost
+ * certainly written immediately after the DB row that triggered the rebuild.
+ */
+function bitmapIsFresh(cartoDir) {
+  const dbPath = path.join(cartoDir, 'carto.db');
+  const bitmapPath = path.join(cartoDir, BITMAP_FILENAME);
+  let bitmapStat, dbStat;
+  try { bitmapStat = fs.statSync(bitmapPath); } catch { return false; }
+  try { dbStat = fs.statSync(dbPath); } catch { return false; }
+  return bitmapStat.mtimeMs >= dbStat.mtimeMs;
+}
+
+/**
+ * ensureBitmapFresh(cartoDir, store) → sidecar
+ *
+ * Best-effort cache lookup → disk load → rebuild. Throws only if the
+ * SQLite store itself is unusable (no `.db`). Callers that can fall back
+ * to SQLite query paths should wrap this in try/catch.
+ */
+function ensureBitmapFresh(cartoDir, store) {
+  // 1. In-memory cache hit (and still fresh).
+  if (cached && cached.cartoDir === cartoDir) {
+    if (bitmapIsFresh(cartoDir)) return cached.sidecar;
+    // Cache is stale w.r.t. on-disk DB — fall through and rebuild.
+    cached = null;
+  }
+
+  // 2. Try loading from disk if the file is fresh.
+  if (bitmapIsFresh(cartoDir)) {
+    const loaded = loadFromDisk(cartoDir);
+    if (loaded) {
+      cached = { cartoDir, sidecar: loaded };
+      return loaded;
+    }
+    // loadFromDisk returned null → corrupt or version mismatch. Rebuild.
+  }
+
+  // 3. Rebuild from the SQLite source of truth and re-persist.
+  const sidecar = buildFromStore(store);
+  try {
+    saveToDisk(cartoDir, sidecar);
+  } catch (err) {
+    // Persistence failure (read-only FS, disk full, race with another
+    // writer) is non-fatal — the in-memory sidecar still answers
+    // queries correctly. Surface to stderr so it shows up in MCP host
+    // logs without killing the request.
+    process.stderr.write(
+      `[CARTO bitmap] failed to persist sidecar to ${cartoDir}: ` +
+      `${err && err.message ? err.message : err}\n`
+    );
+  }
+  cached = { cartoDir, sidecar };
+  return sidecar;
+}
+
+/**
+ * invalidate(cartoDir?) — drop in-memory cache and (optionally) the
+ * on-disk file. Called by `runSyncV2` (full sync rebuilds, then we
+ * re-prime the cache on next ensureBitmapFresh) and `syncFiles`
+ * (partial sync — disk file is now stale).
+ */
+function invalidate(cartoDir) {
+  cached = null;
+  if (cartoDir) {
+    const target = path.join(cartoDir, BITMAP_FILENAME);
+    try { fs.unlinkSync(target); } catch {}
+  }
+}
+
+/** Test-only: drop the in-memory cache without touching the filesystem. */
+function _resetForTests() {
+  cached = null;
+}
+
+module.exports = { ensureBitmapFresh, invalidate, _resetForTests };