@aroman22/codegraph-vba 1.3.3

package/dist/utils.d.ts

@@ -0,0 +1,224 @@
+/**
+ * CodeGraph Utilities
+ *
+ * Common utility functions for memory management, concurrency, batching,
+ * and security validation.
+ *
+ * @module utils
+ *
+ * @example
+ * ```typescript
+ * import { Mutex, processInBatches, MemoryMonitor, validatePathWithinRoot } from 'codegraph';
+ *
+ * // Use mutex for concurrent safety
+ * const mutex = new Mutex();
+ * await mutex.withLock(async () => {
+ *   await performCriticalOperation();
+ * });
+ *
+ * // Process items in batches to manage memory
+ * const results = await processInBatches(items, 100, async (item) => {
+ *   return await processItem(item);
+ * });
+ *
+ * // Monitor memory usage
+ * const monitor = new MemoryMonitor(512, (usage) => {
+ *   console.warn(`Memory usage exceeded 512MB: ${usage / 1024 / 1024}MB`);
+ * });
+ * monitor.start();
+ * ```
+ */
+/**
+ * Config "languages" whose nodes are pure key/value DATA lifted from a config
+ * file (e.g. Spring `application.{yml,properties}`), not source code.
+ */
+export declare const CONFIG_LEAF_LANGUAGES: ReadonlySet<string>;
+/**
+ * A config-leaf node is a single key lifted out of a pure config/data file —
+ * `kind: 'constant'` in a {@link CONFIG_LEAF_LANGUAGES} language. Its on-disk
+ * line is `key = <value>`, and that value is routinely a secret (DB password,
+ * API key, JDBC URL with embedded creds). CodeGraph must surface the KEY only
+ * and never read/return the value, or it pushes secrets into agent context
+ * unbidden — the value isn't needed for resolution, and an agent that genuinely
+ * needs it can read the file directly. (#383)
+ */
+export declare function isConfigLeafNode(node: {
+    kind: string;
+    language?: string;
+}): boolean;
+/**
+ * Validate that a file path stays within the project root, resolving symlinks.
+ *
+ * Two layers: a cheap lexical check that catches `../` traversal, then a
+ * realpath check that catches symlink escapes — an in-repo symlink whose
+ * logical path is inside the root but whose real target points outside it
+ * (issue #527). A symlink that stays within the root is still allowed, so
+ * legitimate in-tree symlinks keep working. Both content-serving read sinks
+ * (codegraph_node `includeCode`, codegraph_explore source) go through here, so
+ * this is the chokepoint that keeps out-of-root file contents from leaking.
+ *
+ * `allowSymlinkEscape` waives **only** the realpath-escape rejection (the
+ * lexical `../` guard still applies) for the INDEXING read path. The directory
+ * walk deliberately descends into in-root symlinks whose targets live outside
+ * the root (e.g. a `game/` symlink in a Dota custom-game tree, #935); discovery
+ * and the reader must agree, or every file the walk enumerated fails to index.
+ * Indexing only reads paths it just discovered, into a local index — it never
+ * serves them to an agent, so this does not widen the #527 leak surface. The
+ * content-serving sinks must never pass this flag.
+ *
+ * @param projectRoot - The project root directory
+ * @param filePath - The (relative or absolute) file path to validate
+ * @param options.allowSymlinkEscape - Follow in-root symlinks out of the root
+ *   (indexing read path only); defaults to the strict, leak-safe behavior.
+ * @returns The resolved absolute path (realpath when it exists), or null if it
+ *   escapes the root
+ */
+export declare function validatePathWithinRoot(projectRoot: string, filePath: string, options?: {
+    allowSymlinkEscape?: boolean;
+}): string | null;
+/**
+ * Validate that a path is a safe project root directory.
+ *
+ * Rejects sensitive system directories and ensures the path is
+ * a real, existing directory. Used at MCP and API entry points
+ * to prevent arbitrary directory access.
+ *
+ * @param dirPath - The path to validate
+ * @returns An error message if invalid, or null if valid
+ */
+export declare function validateProjectPath(dirPath: string): string | null;
+/**
+ * Safely parse JSON with a fallback value.
+ * Prevents crashes from corrupted database metadata.
+ */
+export declare function safeJsonParse<T>(value: string, fallback: T): T;
+/**
+ * Clamp a numeric value to a range.
+ * Used to enforce sane limits on MCP tool inputs.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Normalize a file path to use forward slashes.
+ * Fixes Windows backslash paths so glob matching works consistently.
+ */
+export declare function normalizePath(filePath: string): string;
+/**
+ * Cross-process file lock using a lock file with PID tracking.
+ *
+ * Prevents multiple processes (e.g., git hooks, CLI, MCP server) from
+ * writing to the same database simultaneously.
+ */
+export declare class FileLock {
+    private lockPath;
+    private held;
+    /** Locks older than this are considered stale regardless of PID status */
+    private static readonly STALE_TIMEOUT_MS;
+    constructor(lockPath: string);
+    /**
+     * Acquire the lock. Throws if the lock is held by another live process.
+     */
+    acquire(): void;
+    /**
+     * Release the lock
+     */
+    release(): void;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => T): T;
+    /**
+     * Execute an async function while holding the lock
+     */
+    withLockAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if a process is still running
+     */
+    private isProcessAlive;
+}
+/**
+ * Process items in batches to manage memory
+ *
+ * @param items - Array of items to process
+ * @param batchSize - Number of items per batch
+ * @param processor - Function to process each item
+ * @param onBatchComplete - Optional callback after each batch
+ * @returns Array of results
+ */
+export declare function processInBatches<T, R>(items: T[], batchSize: number, processor: (item: T, index: number) => Promise<R>, onBatchComplete?: (completed: number, total: number) => void): Promise<R[]>;
+/**
+ * Simple mutex lock for preventing concurrent operations
+ */
+export declare class Mutex {
+    private locked;
+    private waitQueue;
+    /**
+     * Acquire the lock
+     *
+     * @returns A release function to call when done
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Check if the lock is currently held
+     */
+    isLocked(): boolean;
+}
+/**
+ * Chunked file reader for large files
+ *
+ * Reads a file in chunks to avoid loading entire file into memory.
+ */
+export declare function readFileInChunks(filePath: string, chunkSize?: number): AsyncGenerator<string, void, undefined>;
+/**
+ * Debounce a function
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle a function
+ *
+ * @param fn - Function to throttle
+ * @param limit - Minimum time between calls in milliseconds
+ * @returns Throttled function
+ */
+export declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Estimate memory usage of an object (rough approximation)
+ *
+ * @param obj - Object to measure
+ * @returns Approximate size in bytes
+ */
+export declare function estimateSize(obj: unknown): number;
+/**
+ * Memory monitor for tracking usage during operations
+ */
+export declare class MemoryMonitor {
+    private checkInterval;
+    private peakUsage;
+    private threshold;
+    private onThresholdExceeded?;
+    constructor(thresholdMB?: number, onThresholdExceeded?: (usage: number) => void);
+    /**
+     * Start monitoring memory usage
+     */
+    start(intervalMs?: number): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Get peak memory usage in bytes
+     */
+    getPeakUsage(): number;
+    /**
+     * Get current memory usage in bytes
+     */
+    getCurrentUsage(): number;
+}
+//# sourceMappingURL=utils.d.ts.map

package/npm-sdk.js

@@ -0,0 +1,75 @@
+'use strict';
+//
+// Programmatic / embedded SDK entry for codegraph-vba (issue #354).
+//
+// The CLI/MCP `bin` (npm-shim.js) execs the per-platform bundle's OWN Node 24 so
+// the tool never depends on the user's runtime. Embedded library consumers are
+// the opposite case: they already run their own Node and just want the compiled
+// API — `require("codegraph-vba")` returning the CodeGraph class et al.
+//
+// The compiled library + its production dependencies (web-tree-sitter,
+// tree-sitter-wasms, …) ship INSIDE the per-platform bundle, at
+//   codegraph-vba-<platform>-<arch>/lib/dist/index.js
+// (with the deps in the sibling lib/node_modules). Re-exporting that bundle keeps
+// the main package thin — no second 50 MB copy of the grammars — while making the
+// SDK work in the consumer's process. Types are a separate concern: the main
+// package ships its own dist/**/*.d.ts tree (pointed at by `types`), built from
+// the same release so it can never skew from the runtime it re-exports.
+//
+// node:sqlite (Node >= 22.5) is required to OPEN a graph, but only lazily inside
+// the SQLite adapter — so loading this module is safe on older Node, and the
+// node:sqlite requirement surfaces with an actionable error only when a DB is
+// actually opened. Heavy extraction additionally wants the bundled launcher's
+// --liftoff-only flag (the WASM Zone-OOM guard, issues #293/#298); an embedded
+// host that drives large indexing should pass that flag to its own Node.
+
+var path = require('path');
+var os = require('os');
+var fs = require('fs');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@aroman22/codegraph-vba-' + target;
+
+module.exports = require(resolveLibrary());
+
+// Locate the compiled library entry inside the installed per-platform bundle.
+// Throws an actionable error (rather than a bare MODULE_NOT_FOUND) when no bundle
+// is present, so an embedded consumer knows exactly what to install.
+function resolveLibrary() {
+  // 1) The npm-installed optional dependency — the normal case.
+  try {
+    return require.resolve(pkg + '/lib/dist/index.js');
+  } catch (e) {
+    /* fall through to the self-healed cache */
+  }
+
+  // 2) A bundle the CLI shim self-healed from GitHub Releases into the cache
+  //    (issue #303). Same node/lib/bin layout as the npm package. We only REUSE a
+  //    cached bundle here — unlike the CLI shim we never trigger a network
+  //    download from inside require(), which must stay synchronous and cheap.
+  var cached = cachedLibrary();
+  if (cached) return cached;
+
+  throw new Error(
+    'codegraph: the programmatic API is unavailable because the platform bundle\n' +
+    '(' + pkg + ') is not installed.\n' +
+    'The compiled library ships inside that per-platform optional dependency.\n' +
+    'Fixes:\n' +
+    '  - install from the official npm registry so the matching bundle is fetched:\n' +
+    '      npm i codegraph-vba --registry=https://registry.npmjs.org\n' +
+    '  - or run the CLI once (e.g. `npx codegraph-vba status`) to\n' +
+    '    self-heal the bundle into ~/.codegraph, then require() will find it.'
+  );
+}
+
+function cachedLibrary() {
+  try {
+    var version = require(path.join(__dirname, 'package.json')).version;
+    var base = process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph');
+    var lib = path.join(base, 'bundles', target + '-' + version, 'lib', 'dist', 'index.js');
+    if (fs.existsSync(lib)) return lib;
+  } catch (e) {
+    /* no readable cache → caller reports the install guidance */
+  }
+  return null;
+}

package/npm-shim.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+'use strict';
+//
+// npm thin-installer launcher for CodeGraph.
+//
+// The heavy artifact (a vendored Node runtime + the app) ships as a per-platform
+// optionalDependency: codegraph-vba-<platform>-<arch>. npm installs
+// only the one matching the host, via each package's `os`/`cpu` fields (the
+// esbuild pattern). This shim — run by the user's OWN Node — locates that bundle
+// and execs its launcher, so the real work always runs on the bundled Node 24
+// (with node:sqlite), regardless of the user's Node version. The user's Node is
+// only ever a launcher; even an ancient version can run this file.
+//
+// Self-heal (issue #303): some registries — notably the npmmirror/cnpm mirrors,
+// and some corporate proxies — don't reliably mirror the per-platform
+// optionalDependencies. npm treats an unfetchable optional dep as success and
+// silently skips it, so the bundle goes missing and every command fails. When
+// the installed bundle can't be resolved, this shim falls back to downloading
+// the matching bundle straight from GitHub Releases — the very archive
+// install.sh uses — into a cache dir, then runs that. Knobs:
+//   CODEGRAPH_NO_DOWNLOAD=1     disable the network fallback (print guidance)
+//   CODEGRAPH_INSTALL_DIR=DIR   cache location (default: ~/.codegraph)
+//   CODEGRAPH_DOWNLOAD_BASE=URL release-download base (for mirrors/air-gapped)
+//
+// Wired up at release time as the main package's `bin`:
+//   "bin": { "codegraph": "npm-shim.js" }
+// with the platform packages listed in `optionalDependencies`.
+
+var childProcess = require('child_process');
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@aroman22/codegraph-vba-' + target;
+var isWindows = process.platform === 'win32';
+var REPO = 'ardelperal/codegraph';
+
+main().catch(function (e) {
+  process.stderr.write('codegraph: ' + (e && e.message ? e.message : String(e)) + '\n');
+  process.exit(1);
+});
+
+async function main() {
+  // Happy path: the npm-installed optional dependency. Fall back to a download
+  // when the registry didn't deliver it.
+  var resolved = resolveInstalledBundle() || (await selfHealBundle());
+  var res = childProcess.spawnSync(resolved.command, resolved.args, { stdio: 'inherit' });
+  if (res.error) {
+    process.stderr.write('codegraph: ' + res.error.message + '\n');
+    process.exit(1);
+  }
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+// Resolve the launcher from the installed per-platform optionalDependency.
+// Returns {command, args} or null if the package isn't installed.
+function resolveInstalledBundle() {
+  try {
+    if (isWindows) {
+      // Modern Node refuses to spawn the bundle's .cmd directly (EINVAL, the
+      // CVE-2024-27980 hardening on Node 24), so invoke the bundled node.exe
+      // against the app entry point and pass --liftoff-only here.
+      var nodeExe = require.resolve(pkg + '/node.exe');
+      var entry = require.resolve(pkg + '/lib/dist/bin/codegraph.js');
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+    return { command: require.resolve(pkg + '/bin/codegraph'), args: process.argv.slice(2) };
+  } catch (e) {
+    return null;
+  }
+}
+
+// Locate the launcher inside an extracted GitHub bundle directory (same
+// node/lib/bin layout as the npm platform package). Returns {command, args} or
+// null when the directory doesn't hold a usable bundle yet.
+function launcherIn(dir) {
+  if (isWindows) {
+    var nodeExe = path.join(dir, 'node.exe');
+    var entry = path.join(dir, 'lib', 'dist', 'bin', 'codegraph.js');
+    if (fs.existsSync(nodeExe) && fs.existsSync(entry)) {
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+  } else {
+    var launcher = path.join(dir, 'bin', 'codegraph');
+    if (fs.existsSync(launcher)) return { command: launcher, args: process.argv.slice(2) };
+  }
+  return null;
+}
+
+// --liftoff-only keeps tree-sitter's WASM grammars off V8's turboshaft tier to
+// avoid the Zone OOM on Node >= 22 (issues #293/#298). The unix bin/codegraph
+// launcher already passes it; on Windows we invoke node.exe directly so add it.
+function liftoff(entry) {
+  return ['--liftoff-only', entry].concat(process.argv.slice(2));
+}
+
+// Download + cache the platform bundle from GitHub Releases. Returns
+// {command, args}; exits the process with guidance if it can't.
+async function selfHealBundle() {
+  var version = readVersion();
+  var bundlesDir = path.join(process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph'), 'bundles');
+  var dest = path.join(bundlesDir, target + '-' + version);
+
+  // Already downloaded by a previous run? Use it even when downloads are
+  // disabled — CODEGRAPH_NO_DOWNLOAD blocks fetching, not a cached bundle.
+  var cached = launcherIn(dest);
+  if (cached) return cached;
+
+  if (process.env.CODEGRAPH_NO_DOWNLOAD) {
+    fail('the network fallback is disabled (CODEGRAPH_NO_DOWNLOAD is set).');
+  }
+
+  var asset = 'codegraph-vba-' + target + (isWindows ? '.zip' : '.tar.gz');
+  var base = process.env.CODEGRAPH_DOWNLOAD_BASE || ('https://github.com/' + REPO + '/releases/download');
+  var url = base + '/v' + version + '/' + asset;
+
+  process.stderr.write(
+    'codegraph: platform bundle missing (registry did not provide ' + pkg + ').\n' +
+    'codegraph: downloading ' + asset + ' from GitHub Releases (' + version + ')...\n'
+  );
+
+  // Stage inside bundlesDir so the final rename is on the same filesystem (atomic,
+  // no EXDEV across tmpfs). Strip the archive's top-level codegraph-<target>/ dir.
+  fs.mkdirSync(bundlesDir, { recursive: true });
+  var stage = fs.mkdtempSync(path.join(bundlesDir, '.dl-'));
+  try {
+    var archivePath = path.join(stage, asset);
+    await download(url, archivePath, 6);
+    await verifyChecksum(archivePath, asset, base, version);
+    var extracted = path.join(stage, 'bundle');
+    fs.mkdirSync(extracted);
+    extract(archivePath, extracted);
+
+    var raced = launcherIn(dest); // another process may have finished meanwhile
+    if (raced) { rmrf(stage); return raced; }
+    try {
+      fs.renameSync(extracted, dest);
+    } catch (e) {
+      var other = launcherIn(dest); // lost the race but theirs is valid
+      if (other) { rmrf(stage); return other; }
+      throw e;
+    }
+  } catch (e) {
+    rmrf(stage);
+    fail('download failed (' + e.message + ').\n  URL: ' + url);
+  }
+  rmrf(stage);
+
+  var ready = launcherIn(dest);
+  if (!ready) fail('downloaded bundle is missing its launcher under ' + dest + '.');
+  process.stderr.write('codegraph: bundle ready.\n');
+  return ready;
+}
+
+function readVersion() {
+  try {
+    return require(path.join(__dirname, 'package.json')).version;
+  } catch (e) {
+    fail('could not read this package\'s version to locate a matching release.');
+  }
+}
+
+// GET with manual redirect following (GitHub release URLs redirect to a CDN).
+function download(url, dest, redirectsLeft) {
+  return new Promise(function (resolve, reject) {
+    var https = require('https');
+    // timeout is an idle/inactivity timeout — it won't kill a slow-but-progressing
+    // download, only a stalled connection (so a blocked mirror fails fast with
+    // guidance instead of hanging the user's command forever).
+    var req = https.get(url, { headers: { 'User-Agent': 'codegraph-npm-shim' }, timeout: 30000 }, function (res) {
+      var status = res.statusCode;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) { reject(new Error('too many redirects')); return; }
+        download(new URL(res.headers.location, url).toString(), dest, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) { res.resume(); reject(new Error('HTTP ' + status)); return; }
+      var file = fs.createWriteStream(dest);
+      res.on('error', reject);
+      res.pipe(file);
+      file.on('error', reject);
+      file.on('finish', function () { file.close(function () { resolve(); }); });
+    });
+    req.on('timeout', function () { req.destroy(new Error('connection timed out')); });
+    req.on('error', reject);
+  });
+}
+
+// Best-effort integrity check. When the release publishes a SHA256SUMS file, the
+// downloaded archive MUST match its listed hash or we abort. When that file is
+// absent (older releases) or simply unreachable, we proceed — the archive still
+// arrived from GitHub over TLS. So tampering/corruption is caught, while a
+// missing checksum never breaks an install.
+async function verifyChecksum(archivePath, asset, base, version) {
+  var sumsPath = archivePath + '.SHA256SUMS';
+  try {
+    await download(base + '/v' + version + '/SHA256SUMS', sumsPath, 6);
+  } catch (e) {
+    return; // not published / unreachable → skip
+  }
+  var expected = null;
+  var lines = fs.readFileSync(sumsPath, 'utf8').split('\n');
+  for (var i = 0; i < lines.length; i++) {
+    var m = lines[i].trim().match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+    if (m && path.basename(m[2].trim()) === asset) { expected = m[1].toLowerCase(); break; }
+  }
+  if (!expected) return; // asset not listed → nothing to check
+  var actual = require('crypto').createHash('sha256').update(fs.readFileSync(archivePath)).digest('hex');
+  if (actual !== expected) {
+    throw new Error('checksum mismatch for ' + asset +
+      ' (expected ' + expected.slice(0, 12) + '…, got ' + actual.slice(0, 12) + '…)');
+  }
+  process.stderr.write('codegraph: checksum verified.\n');
+}
+
+// Extract via the system tar — present on macOS, Linux, and Windows 10+
+// (bsdtar reads .zip too). No third-party dependency in the shim.
+function extract(archive, destDir) {
+  var args = isWindows
+    ? ['-xf', archive, '-C', destDir, '--strip-components=1']
+    : ['-xzf', archive, '-C', destDir, '--strip-components=1'];
+  var res = childProcess.spawnSync('tar', args, { stdio: 'ignore' });
+  if (res.error) throw new Error('tar unavailable: ' + res.error.message);
+  if (res.status !== 0) throw new Error('tar exited ' + res.status);
+}
+
+function rmrf(p) {
+  try { fs.rmSync(p, { recursive: true, force: true }); } catch (e) { /* best effort */ }
+}
+
+function fail(reason) {
+  process.stderr.write(
+    'codegraph: no prebuilt bundle for ' + target + '.\n' +
+    (reason ? 'codegraph: ' + reason + '\n' : '') +
+    'Expected the optional package ' + pkg + ' to be installed.\n' +
+    'A registry mirror (e.g. npmmirror/cnpm) that did not mirror the per-platform\n' +
+    'package is the usual cause. Fixes:\n' +
+    '  - install from the official registry:\n' +
+    '      npm i -g codegraph-vba --registry=https://registry.npmjs.org\n' +
+    '  - or use the standalone installer (no Node required):\n' +
+    '      curl -fsSL https://raw.githubusercontent.com/' + REPO + '/main/install.sh | sh\n'
+  );
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aroman22/codegraph-vba",
+  "version": "1.3.3",
+  "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
+  "bin": {
+    "codegraph-vba": "npm-shim.js"
+  },
+  "main": "npm-sdk.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./npm-sdk.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "optionalDependencies": {
+    "@aroman22/codegraph-vba-darwin-arm64": "1.3.3",
+    "@aroman22/codegraph-vba-darwin-x64": "1.3.3",
+    "@aroman22/codegraph-vba-linux-arm64": "1.3.3",
+    "@aroman22/codegraph-vba-linux-x64": "1.3.3",
+    "@aroman22/codegraph-vba-win32-arm64": "1.3.3",
+    "@aroman22/codegraph-vba-win32-x64": "1.3.3"
+  },
+  "files": [
+    "npm-shim.js",
+    "npm-sdk.js",
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT"
+}