@saluzi/codegraph 0.1.0 → 0.2.1

package/dist/utils.js

@@ -63,11 +63,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryMonitor = exports.Mutex = exports.FileLock = void 0;
+exports.MemoryMonitor = exports.Mutex = exports.FileLock = exports.CONFIG_LEAF_LANGUAGES = void 0;
+exports.isConfigLeafNode = isConfigLeafNode;
 exports.validatePathWithinRoot = validatePathWithinRoot;
 exports.validateProjectPath = validateProjectPath;
-exports.isPathWithinRoot = isPathWithinRoot;
-exports.isPathWithinRootReal = isPathWithinRootReal;
 exports.safeJsonParse = safeJsonParse;
 exports.clamp = clamp;
 exports.normalizePath = normalizePath;
@@ -91,20 +90,94 @@ const SENSITIVE_PATHS = new Set([
     'c:\\', 'c:\\windows', 'c:\\windows\\system32',
 ]);
 /**
- * Validate that a resolved file path stays within the project root.
- * Prevents path traversal attacks (e.g. node.filePath = "../../etc/passwd").
+ * Config "languages" whose nodes are pure key/value DATA lifted from a config
+ * file (e.g. Spring `application.{yml,properties}`), not source code.
+ */
+exports.CONFIG_LEAF_LANGUAGES = new Set(['yaml', 'properties']);
+/**
+ * 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)
+ */
+function isConfigLeafNode(node) {
+    return node.kind === 'constant' && !!node.language && exports.CONFIG_LEAF_LANGUAGES.has(node.language);
+}
+/**
+ * Whether `child` is `parent` itself or sits underneath it. Case-insensitive on
+ * Windows — NTFS is case-insensitive, and realpathSync can hand back a different
+ * case than the lexical root, which would otherwise false-reject a valid file.
+ */
+function isWithinDir(child, parent) {
+    let c = child;
+    let p = parent;
+    if (process.platform === 'win32') {
+        c = c.toLowerCase();
+        p = p.toLowerCase();
+    }
+    return c === p || c.startsWith(p + path.sep);
+}
+/**
+ * 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 file path to validate
- * @returns The resolved absolute path, or null if it escapes the root
+ * @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
  */
-function validatePathWithinRoot(projectRoot, filePath) {
+function validatePathWithinRoot(projectRoot, filePath, options) {
     const resolved = path.resolve(projectRoot, filePath);
     const normalizedRoot = path.resolve(projectRoot);
-    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
+    // 1. Lexical containment — cheap, catches `../` traversal. Applies even on
+    //    the indexing read path: a crafted `../` escape is still rejected.
+    if (!isWithinDir(resolved, normalizedRoot)) {
+        return null;
+    }
+    // 2. Symlink-aware containment — resolve symlinks on both sides and re-check,
+    //    so an in-repo symlink whose real target escapes the root is rejected.
+    //    The indexing read path (allowSymlinkEscape) skips only this rejection so
+    //    it stays consistent with the directory walk, which already followed the
+    //    in-root symlink to enumerate these files (#935).
+    try {
+        const realRoot = fs.realpathSync(normalizedRoot);
+        const realResolved = fs.realpathSync(resolved);
+        if (options?.allowSymlinkEscape) {
+            return realResolved;
+        }
+        return isWithinDir(realResolved, realRoot) ? realResolved : null;
+    }
+    catch (err) {
+        // ENOENT: the path doesn't exist yet (a file about to be written, or an
+        // index entry for a since-deleted file) — no symlink to follow, and the
+        // lexical check already passed, so allow the lexical path. Any other
+        // resolution failure (ELOOP, EACCES, …) is treated as unsafe → reject.
+        if (err.code === 'ENOENT') {
+            return resolved;
+        }
         return null;
     }
-    return resolved;
 }
 /**
  * Validate that a path is a safe project root directory.
@@ -143,45 +216,6 @@ function validateProjectPath(dirPath) {
     }
     return null;
 }
-/**
- * Check if a file path resolves to a location within the given root directory.
- *
- * Prevents path traversal attacks by ensuring the resolved absolute path
- * starts with the resolved root path. Handles '..' sequences, symlink-like
- * relative paths, and platform-specific separators.
- *
- * @param filePath - The path to check (can be relative or absolute)
- * @param rootDir - The root directory that filePath must stay within
- * @returns true if filePath resolves to a location within rootDir
- */
-function isPathWithinRoot(filePath, rootDir) {
-    const resolvedPath = path.resolve(rootDir, filePath);
-    const resolvedRoot = path.resolve(rootDir);
-    return resolvedPath.startsWith(resolvedRoot + path.sep) || resolvedPath === resolvedRoot;
-}
-/**
- * Like isPathWithinRoot but also resolves symlinks via fs.realpathSync.
- *
- * This catches symlink escapes where the logical path appears to be within
- * root but the real path on disk points elsewhere. Falls back to logical
- * path checking if realpath resolution fails (e.g. broken symlink).
- */
-function isPathWithinRootReal(filePath, rootDir) {
-    // First do the cheap logical check
-    if (!isPathWithinRoot(filePath, rootDir)) {
-        return false;
-    }
-    // Then verify with realpath to catch symlink escapes
-    try {
-        const realPath = fs.realpathSync(path.resolve(rootDir, filePath));
-        const realRoot = fs.realpathSync(rootDir);
-        return realPath.startsWith(realRoot + path.sep) || realPath === realRoot;
-    }
-    catch {
-        // If realpath fails (broken symlink, permissions), fall back to logical check
-        return true;
-    }
-}
 /**
  * Safely parse JSON with a fallback value.
  * Prevents crashes from corrupted database metadata.

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCH,4CAEC;AA4CD,wDAoCC;AAYD,kDA6BC;AAMD,sCAMC;AAMD,sBAEC;AAMD,sCAEC;AAiID,4CA0BC;AAyDD,4CAiBC;AASD,4BAeC;AASD,4BA0BC;AAQD,oCAmCC;AAlgBD,uCAAyB;AACzB,2CAA6B;AAE7B,+DAA+D;AAC/D,qBAAqB;AACrB,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAC1C,MAAM,EAAE,aAAa,EAAE,uBAAuB;CAC/C,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,qBAAqB,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;AAE1F;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAAC,IAAyC;IACxE,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,6BAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACjG,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,KAAa,EAAE,MAAc;IAChD,IAAI,CAAC,GAAG,KAAK,CAAC;IACd,IAAI,CAAC,GAAG,MAAM,CAAC;IACf,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QACpB,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,sBAAsB,CACpC,WAAmB,EACnB,QAAgB,EAChB,OAA0C;IAE1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrD,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAEjD,2EAA2E;IAC3E,uEAAuE;IACvE,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,sDAAsD;IACtD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,OAAO,EAAE,kBAAkB,EAAE,CAAC;YAChC,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,OAAO,WAAW,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wEAAwE;QACxE,wEAAwE;QACxE,qEAAqE;QACrE,uEAAuE;QACvE,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,mBAAmB,CAAC,OAAe;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC,qCAAqC;IACrC,IAAI,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACjF,OAAO,sDAAsD,QAAQ,EAAE,CAAC;IAC1E,CAAC;IAED,kDAAkD;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;IACxC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAChE,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACpC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC9C,IAAI,QAAQ,KAAK,aAAa,IAAI,QAAQ,CAAC,UAAU,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAChF,OAAO,+CAA+C,QAAQ,EAAE,CAAC;QACnE,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,OAAO,4BAA4B,QAAQ,EAAE,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,6CAA6C,QAAQ,EAAE,CAAC;IACjE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAI,KAAa,EAAE,QAAW;IACzD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IAC3D,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,QAAgB;IAC5C,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAa,QAAQ;IACX,QAAQ,CAAS;IACjB,IAAI,GAAG,KAAK,CAAC;IAErB,0EAA0E;IAClE,MAAM,CAAU,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;IAEtE,YAAY,QAAgB;QAC1B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,OAAO;QACL,0BAA0B;QAC1B,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC/D,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBAClC,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACxC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;gBAE1C,iEAAiE;gBACjE,IAAI,OAAO,GAAG,QAAQ,CAAC,gBAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;oBACnF,MAAM,IAAI,KAAK,CACb,wDAAwD,GAAG,KAAK;wBAChE,sDAAsD,IAAI,CAAC,QAAQ,EAAE,CACtE,CAAC;gBACJ,CAAC;gBAED,qDAAqD;gBACrD,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;oBACtE,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,oDAAoD;gBACpD,IAAI,CAAC;oBAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,6DAA6D;QAC7D,IAAI,CAAC;YACH,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1B,+EAA+E;gBAC/E,MAAM,IAAI,KAAK,CACb,mDAAmD;oBACnD,sDAAsD,IAAI,CAAC,QAAQ,EAAE,CACtE,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO;QACvB,IAAI,CAAC;YACH,6CAA6C;YAC7C,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YAC/D,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC;gBAC1C,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;QACzC,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,QAAQ,CAAI,EAAW;QACrB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa,CAAI,EAAoB;QACzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,GAAW;QAChC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;;AA7GH,4BA8GC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,gBAAgB,CACpC,KAAU,EACV,SAAiB,EACjB,SAAiD,EACjD,eAA4D;IAE5D,MAAM,OAAO,GAAQ,EAAE,CAAC;IAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACpE,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CACpC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CACnD,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;QAE9B,IAAI,eAAe,EAAE,CAAC;YACpB,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACvE,CAAC;QAED,2BAA2B;QAC3B,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAa,KAAK;IACR,MAAM,GAAG,KAAK,CAAC;IACf,SAAS,GAAsB,EAAE,CAAC;IAE1C;;;;OAIG;IACH,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAEnB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACpB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YACpC,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,EAAE,CAAC;YACT,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAI,EAAwB;QACxC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AA7CD,sBA6CC;AAED;;;;GAIG;AACI,KAAK,SAAS,CAAC,CAAC,gBAAgB,CACrC,QAAgB,EAChB,YAAoB,EAAE,GAAG,IAAI;IAE7B,MAAM,EAAE,GAAG,wDAAa,IAAI,GAAC,CAAC;IAE9B,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAEvC,IAAI,CAAC;QACH,IAAI,SAAiB,CAAC;QACtB,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YACrE,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CACtB,EAAK,EACL,KAAa;IAEb,IAAI,SAAS,GAAyC,IAAI,CAAC;IAE3D,OAAO,CAAC,GAAG,IAAmB,EAAE,EAAE;QAChC,IAAI,SAAS,EAAE,CAAC;YACd,YAAY,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;QACD,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACZ,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CACtB,EAAK,EACL,KAAa;IAEb,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAyC,IAAI,CAAC;IAE3D,OAAO,CAAC,GAAG,IAAmB,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,KAAK,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC;QAE3C,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACnB,IAAI,SAAS,EAAE,CAAC;gBACd,YAAY,CAAC,SAAS,CAAC,CAAC;gBACxB,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;YACD,QAAQ,GAAG,GAAG,CAAC;YACf,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,CAAC;aAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YACtB,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC1B,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACtB,SAAS,GAAG,IAAI,CAAC;gBACjB,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACd,CAAC,EAAE,SAAS,CAAC,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,GAAY;IACvC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IAE3B,SAAS,MAAM,CAAC,KAAc;QAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,CAAC,CAAC;QACX,CAAC;QAED,QAAQ,OAAO,KAAK,EAAE,CAAC;YACrB,KAAK,SAAS;gBACZ,OAAO,CAAC,CAAC;YACX,KAAK,QAAQ;gBACX,OAAO,CAAC,CAAC;YACX,KAAK,QAAQ;gBACX,OAAO,CAAC,GAAI,KAAgB,CAAC,MAAM,CAAC;YACtC,KAAK,QAAQ;gBACX,IAAI,IAAI,CAAC,GAAG,CAAC,KAAe,CAAC,EAAE,CAAC;oBAC9B,OAAO,CAAC,CAAC;gBACX,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,KAAe,CAAC,CAAC;gBAE1B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAW,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBACpE,CAAC;gBAED,OAAO,MAAM,CAAC,OAAO,CAAC,KAAe,CAAC,CAAC,MAAM,CAC3C,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,EACpD,CAAC,CACF,CAAC;YACJ;gBACE,OAAO,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAa,aAAa;IAChB,aAAa,GAA0C,IAAI,CAAC;IAC5D,SAAS,GAAG,CAAC,CAAC;IACd,SAAS,CAAS;IAClB,mBAAmB,CAA2B;IAEtD,YACE,cAAsB,GAAG,EACzB,mBAA6C;QAE7C,IAAI,CAAC,SAAS,GAAG,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;QAC3C,IAAI,CAAC,mBAAmB,GAAG,mBAAmB,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAqB,IAAI;QAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QAEnB,IAAI,CAAC,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE;YACpC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC;YAC7C,IAAI,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;YACzB,CAAC;YACD,IAAI,KAAK,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;gBACvD,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAClC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC;IACxC,CAAC;CACF;AAvDD,sCAuDC"}

package/package.json

@@ -1,24 +1,56 @@
 {
   "name": "@saluzi/codegraph",
-  "version": "0.1.0",
-  "description": "Local-first code intelligence — builds a semantic knowledge graph from any codebase using tree-sitter + SQLite",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "version": "0.2.1",
+  "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "codegraph": "./dist/bin/codegraph.js"
+  },
   "files": [
-    "dist/"
+    "dist",
+    "scripts",
+    "README.md"
   ],
+  "scripts": {
+    "build": "tsc && npm run copy-assets && node -e \"require('fs').chmodSync('dist/bin/codegraph.js', 0o755)\"",
+    "preuninstall": "node dist/bin/uninstall.js",
+    "copy-assets": "node -e \"const fs=require('fs');fs.mkdirSync('dist/db',{recursive:true});fs.copyFileSync('src/db/schema.sql','dist/db/schema.sql');fs.mkdirSync('dist/extraction/wasm',{recursive:true});fs.readdirSync('src/extraction/wasm').filter(f=>f.endsWith('.wasm')).forEach(f=>fs.copyFileSync('src/extraction/wasm/'+f,'dist/extraction/wasm/'+f))\"",
+    "dev": "tsc --watch",
+    "cli": "npm run build && node dist/bin/codegraph.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:eval": "vitest run __tests__/evaluation/",
+    "eval": "npm run build && npx tsx __tests__/evaluation/runner.ts",
+    "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\""
+  },
   "keywords": [
     "code-intelligence",
-    "tree-sitter",
-    "sqlite",
     "knowledge-graph",
-    "code-analysis"
+    "static-analysis"
   ],
+  "author": "",
   "license": "MIT",
   "dependencies": {
-    "web-tree-sitter": "^0.25.3",
+    "@clack/prompts": "^1.3.0",
+    "commander": "^14.0.2",
+    "fast-string-width": "^3.0.2",
+    "fast-wrap-ansi": "^0.2.0",
     "ignore": "^7.0.5",
+    "jsonc-parser": "^3.3.1",
     "picomatch": "^4.0.3",
-    "jsonc-parser": "^3.3.1"
+    "sisteransi": "^1.0.5",
+    "tree-sitter-wasms": "^0.1.11",
+    "web-tree-sitter": "^0.25.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.19.30",
+    "@types/picomatch": "^4.0.2",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20.0.0 <25.0.0"
   }
 }

package/scripts/add-lang/bench.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Add-lang benchmark for ONE repo:
+#   clone -> wipe+index (with the codegraph on PATH) -> verify extraction ->
+#   with/without retrieval A/B (reuses scripts/agent-eval/run-all.sh).
+#
+# Assumes the codegraph dev build is already built + linked on PATH — the skill
+# runs `npm run build && ./scripts/local-install.sh` ONCE before looping repos.
+# The A/B is skipped if extraction fails its critical checks (don't burn $ on a
+# broken extractor); set FORCE_AB=1 to run it anyway.
+#
+# Usage: bench.sh <lang> <repo-name> <repo-url> "<question>" [headless|tmux|all]
+# Env:   CORPUS   corpus dir (default /tmp/codegraph-corpus, shared with agent-eval)
+set -uo pipefail
+
+LANG_TOKEN="${1:?usage: bench.sh <lang> <repo-name> <repo-url> \"<question>\" [mode]}"
+NAME="${2:?repo-name required}"
+URL="${3:?repo-url required}"
+Q="${4:?question required}"
+MODE="${5:-headless}"
+
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+AGENT_EVAL="$(cd "$HARNESS/../agent-eval" && pwd)"
+CORPUS="${CORPUS:-/tmp/codegraph-corpus}"
+REPO="$CORPUS/$NAME"
+
+command -v codegraph >/dev/null || { echo "no codegraph on PATH (build + ./scripts/local-install.sh first)"; exit 1; }
+
+echo "==================== add-lang bench: $NAME ($LANG_TOKEN) ===================="
+echo "codegraph: $(command -v codegraph) -> $(codegraph --version 2>/dev/null || echo '?')"
+
+# 1. Ensure the repo (shallow clone, reuse if present).
+mkdir -p "$CORPUS"
+if [ -d "$REPO/.git" ]; then
+  echo "→ reusing checkout: $REPO"
+else
+  echo "→ cloning $URL"
+  git clone --depth 1 "$URL" "$REPO" || { echo "git clone failed"; exit 1; }
+fi
+
+# 2. Wipe + index with the binary under test.
+echo "→ wiping .codegraph and indexing"
+rm -rf "$REPO/.codegraph"
+( cd "$REPO" && codegraph init -i ) || { echo "indexing failed"; exit 1; }
+
+# 3. Verify extraction (cheap guard before the paid A/B).
+echo "→ verifying extraction"
+node "$HARNESS/verify-extraction.mjs" "$REPO" "$LANG_TOKEN"
+VERIFY=$?
+
+# 4. Retrieval A/B (skipped if extraction is broken, unless FORCE_AB=1).
+if [ "$VERIFY" -ne 0 ] && [ "${FORCE_AB:-0}" != "1" ]; then
+  echo "→ SKIPPING A/B — extraction failed critical checks (set FORCE_AB=1 to override)"
+else
+  echo "→ retrieval A/B (mode=$MODE)"
+  bash "$AGENT_EVAL/run-all.sh" "$REPO" "$Q" "$MODE"
+fi
+
+echo "==================== bench complete: $NAME (verify exit=$VERIFY) ===================="
+# Exit reflects extraction: 0 = pass/warn, 1 = critical fail, 2 = couldn't read status.
+exit "$VERIFY"

package/scripts/add-lang/check-grammar.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Verify a tree-sitter grammar wasm is HEALTHY under the project's web-tree-sitter
+// runtime BEFORE writing an extractor. Prints the ABI version and parses a valid
+// sample many times in a multi-grammar context, to catch heap-corruption bugs
+// that silently drop nodes on every parse after the first.
+//
+// Why this exists: the tree-sitter-wasms Lua grammar is ABI 13 and corrupts the
+// shared WASM heap under web-tree-sitter 0.25 — Lua extraction degraded on every
+// file after the first (nested calls/imports vanished). The fix was to vendor the
+// upstream ABI-15 wasm. Run this on any new grammar first; if it FAILs, vendor a
+// newer build instead of using the tree-sitter-wasms one.
+//
+// Usage: node scripts/add-lang/check-grammar.mjs <lang|wasm-path> <valid-sample> [iterations]
+// Exit: 0 healthy, 1 corruption / parse errors, 2 could not run.
+// NOTE: the sample must be SYNTACTICALLY VALID — a broken sample fails for the
+//       wrong reason.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { Parser, Language } from 'web-tree-sitter';
+
+const require = createRequire(import.meta.url);
+const fail = (code, msg) => { console.error(`[check-grammar] ${msg}`); process.exit(code); };
+
+const [token, sample, iterArg] = process.argv.slice(2);
+if (!token || !sample) fail(2, 'usage: check-grammar.mjs <lang|wasm-path> <valid-sample> [iterations]');
+if (!existsSync(sample)) fail(2, `sample not found: ${sample}`);
+const iters = iterArg ? parseInt(iterArg, 10) : 20;
+
+const SPECIAL = { csharp: 'c_sharp', 'c#': 'c_sharp' };
+function resolveWasm(t) {
+  if (t.endsWith('.wasm')) return existsSync(t) ? t : fail(2, `wasm not found: ${t}`);
+  const base = SPECIAL[t.toLowerCase()] ?? t.toLowerCase();
+  try { return require.resolve(`tree-sitter-wasms/out/tree-sitter-${base}.wasm`); } catch { /* try vendored */ }
+  const vendored = `src/extraction/wasm/tree-sitter-${base}.wasm`;
+  if (existsSync(vendored)) return vendored;
+  return fail(2, `no grammar for "${t}" — not in tree-sitter-wasms and not vendored`);
+}
+
+const wasmPath = resolveWasm(token);
+const source = readFileSync(sample, 'utf8');
+
+try { await Parser.init(); }
+catch { await Parser.init({ locateFile: () => require.resolve('web-tree-sitter/tree-sitter.wasm') }); }
+
+// Load a second, known-good grammar — the corruption surfaces under the
+// multi-grammar runtime that real indexing uses, not a single grammar in isolation.
+try { await Language.load(require.resolve('tree-sitter-wasms/out/tree-sitter-python.wasm')); } catch { /* ok */ }
+
+let language;
+try { language = await Language.load(wasmPath); }
+catch (e) { fail(2, `failed to load ${wasmPath}: ${e.message}`); }
+
+const parser = new Parser();
+parser.setLanguage(language);
+
+let ok = 0, err = 0;
+for (let i = 0; i < iters; i++) {
+  const tree = parser.parse(source);
+  if (tree.rootNode.hasError) err++; else ok++;
+}
+
+console.log(`grammar: ${wasmPath.split('/').pop()}`);
+console.log(`  ABI version: ${language.abiVersion}`);
+console.log(`  parses: ${ok} clean / ${err} with errors (of ${iters})`);
+if (err > 0) {
+  console.log(
+    `RESULT: FAIL — ${err}/${iters} parses produced ERROR trees on a valid sample. ` +
+    `This grammar corrupts under web-tree-sitter; vendor a newer (ABI 14/15) wasm ` +
+    `(see SKILL.md "Find a grammar"). Confirm your sample is syntactically valid first.`
+  );
+  process.exit(1);
+}
+console.log('RESULT: PASS — grammar parses cleanly and reuses safely.');
+process.exit(0);

package/scripts/add-lang/dump-ast.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Dump the tree-sitter AST for a sample file so you can write a LanguageExtractor
+// mapping. Loads a grammar .wasm directly via web-tree-sitter (the same runtime
+// codegraph uses) — you do NOT need to register the language first.
+//
+// Usage:
+//   node scripts/add-lang/dump-ast.mjs <lang|wasm-path> <sample-file> [--depth=N] [--full]
+// Examples:
+//   node scripts/add-lang/dump-ast.mjs lua sample.lua
+//   node scripts/add-lang/dump-ast.mjs src/extraction/wasm/tree-sitter-zig.wasm a.zig --depth=4
+//
+// Output: an indented AST (named nodes, with field names) followed by a
+// node-type FREQUENCY table. The frequency table is the payoff — it tells you
+// which node types to map to functionTypes / classTypes / importTypes / etc.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { Parser, Language } from 'web-tree-sitter';
+
+const require = createRequire(import.meta.url);
+const fail = (msg) => { console.error(`[dump-ast] ${msg}`); process.exit(1); };
+
+const argv = process.argv.slice(2);
+const positional = argv.filter((a) => !a.startsWith('--'));
+const [langOrWasm, sampleFile] = positional;
+const depthFlag = argv.find((a) => a.startsWith('--depth='));
+const showAll = argv.includes('--full'); // also print anonymous (token) nodes
+const maxDepth = depthFlag ? parseInt(depthFlag.split('=')[1], 10) : (showAll ? Infinity : 8);
+
+if (!langOrWasm || !sampleFile) {
+  fail('usage: dump-ast.mjs <lang|wasm-path> <sample-file> [--depth=N] [--full]');
+}
+if (!existsSync(sampleFile)) fail(`sample file not found: ${sampleFile}`);
+
+// Language tokens whose tree-sitter-wasms filename differs from the token.
+const WASM_SPECIAL = { csharp: 'c_sharp', 'c#': 'c_sharp' };
+
+function resolveWasm(token) {
+  if (token.endsWith('.wasm')) {
+    if (!existsSync(token)) fail(`wasm not found: ${token}`);
+    return token;
+  }
+  const base = WASM_SPECIAL[token.toLowerCase()] ?? token.toLowerCase();
+  try {
+    return require.resolve(`tree-sitter-wasms/out/tree-sitter-${base}.wasm`);
+  } catch {
+    /* not in tree-sitter-wasms — try a vendored copy */
+  }
+  const vendored = `src/extraction/wasm/tree-sitter-${base}.wasm`;
+  if (existsSync(vendored)) return vendored;
+  fail(
+    `no grammar for "${token}" — not in tree-sitter-wasms and not vendored at ` +
+      `${vendored}. Pass an explicit .wasm path, or vendor one (see SKILL.md "Find a grammar").`
+  );
+}
+
+const wasmPath = resolveWasm(langOrWasm);
+const source = readFileSync(sampleFile, 'utf8');
+
+try {
+  await Parser.init();
+} catch {
+  await Parser.init({ locateFile: () => require.resolve('web-tree-sitter/tree-sitter.wasm') });
+}
+
+let language;
+try {
+  language = await Language.load(wasmPath);
+} catch (e) {
+  fail(`failed to load grammar ${wasmPath}: ${e.message}`);
+}
+
+const parser = new Parser();
+parser.setLanguage(language);
+const tree = parser.parse(source);
+
+const freq = new Map();
+const snippet = (node) => {
+  const t = node.text.replace(/\s+/g, ' ').trim();
+  return t.length > 48 ? `${t.slice(0, 48)}…` : t;
+};
+
+function walk(node, depth, fieldName) {
+  if (node.isNamed) freq.set(node.type, (freq.get(node.type) || 0) + 1);
+  if ((node.isNamed || showAll) && depth <= maxDepth) {
+    const field = fieldName ? `${fieldName}: ` : '';
+    const leaf = node.childCount === 0 ? `  "${snippet(node)}"` : '';
+    console.log(`${'  '.repeat(depth)}${field}${node.type}  @${node.startPosition.row + 1}:${node.startPosition.column}${leaf}`);
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) walk(child, depth + 1, node.fieldNameForChild(i));
+  }
+}
+
+console.log(`\n# AST for ${sampleFile}  (grammar: ${wasmPath.split('/').pop()})\n`);
+walk(tree.rootNode, 0, null);
+
+console.log('\n# Node-type frequency (named nodes) — map the relevant ones in your extractor:\n');
+[...freq.entries()]
+  .sort((a, b) => b[1] - a[1])
+  .forEach(([type, n]) => console.log(`  ${String(n).padStart(5)}  ${type}`));
+console.log();

package/scripts/add-lang/verify-extraction.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Sanity-check that codegraph extracted REAL symbols (not just file/import nodes)
+// from a repo for a given language. Exits non-zero on a critical failure so it
+// can drive a write-extractor -> build -> re-check loop.
+//
+// Usage: node scripts/add-lang/verify-extraction.mjs <repo-path> <lang>
+// Reads `codegraph status <repo> --json` using whatever codegraph is on PATH,
+// so it reflects the binary that built the index.
+//
+// Exit codes: 0 = pass or soft-warn, 1 = critical fail, 2 = could not run.
+
+import { execFileSync } from 'node:child_process';
+
+const [repo, lang] = process.argv.slice(2);
+if (!repo || !lang) {
+  console.error('usage: verify-extraction.mjs <repo-path> <lang>');
+  process.exit(2);
+}
+
+let status;
+try {
+  const out = execFileSync('codegraph', ['status', repo, '--json'], { encoding: 'utf8' });
+  status = JSON.parse(out);
+} catch (e) {
+  console.error(`[verify] could not read codegraph status for ${repo}: ${e.message}`);
+  process.exit(2);
+}
+
+// Kinds that prove the extractor mapped AST node types (everything except
+// 'file' and 'import', which codegraph creates structurally for any language).
+const SYMBOL_KINDS = new Set([
+  'module', 'class', 'struct', 'interface', 'trait', 'protocol', 'function',
+  'method', 'property', 'field', 'variable', 'constant', 'enum', 'enum_member',
+  'type_alias', 'namespace', 'route', 'component',
+]);
+
+const byKind = status.nodesByKind || {};
+const langs = status.languages || [];
+const files = status.fileCount || 0;
+const edges = status.edgeCount || 0;
+const symbolKinds = Object.keys(byKind).filter((k) => SYMBOL_KINDS.has(k));
+const symbolCount = symbolKinds.reduce((s, k) => s + byKind[k], 0);
+
+const checks = [];
+const add = (severity, ok, label, detail) => checks.push({ severity, ok, label, detail });
+
+add('critical', status.initialized === true, 'index initialized', `initialized=${status.initialized}`);
+add('critical', langs.includes(lang), `language "${lang}" detected`, `languages=[${langs.join(', ')}]`);
+add('critical', symbolCount > 0, 'structural symbols extracted', `${symbolCount} symbols (${symbolKinds.join(', ') || 'NONE — only file/import nodes!'})`);
+add('soft', symbolCount >= files, 'symbol density >= 1/file', `${symbolCount} symbols across ${files} files`);
+add('soft', edges > files, 'edges resolved', `${edges} edges across ${files} files`);
+
+console.log(`\n# Extraction check — ${repo}  (lang=${lang}, backend=${status.backend})`);
+console.log(`  files=${files} nodes=${status.nodeCount} edges=${edges}`);
+console.log(`  nodesByKind: ${JSON.stringify(byKind)}\n`);
+for (const c of checks) console.log(`  ${c.ok ? '✓' : '✗'} ${c.label} — ${c.detail}`);
+
+const critical = checks.filter((c) => !c.ok && c.severity === 'critical');
+const soft = checks.filter((c) => !c.ok && c.severity === 'soft');
+console.log();
+if (critical.length) {
+  console.log(`RESULT: FAIL (${critical.length} critical) — extractor or grammar wiring is broken. Re-run dump-ast.mjs and fix the node-type mappings.`);
+  process.exit(1);
+}
+if (soft.length) {
+  console.log(`RESULT: WARN (${soft.length} soft) — extraction works but looks thin; inspect the counts above.`);
+  process.exit(0);
+}
+console.log('RESULT: PASS — extraction looks healthy.');
+process.exit(0);

package/scripts/agent-eval/ab-adoption.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Does the agent PICK codegraph_node to read a file, vs the built-in Read tool?
+# Build A/B: NEW build (HEAD, codegraph_node has Read parity) vs BASELINE build
+# (a ref where it doesn't), BOTH codegraph-attached + pre-warmed, same task. The
+# metric is tool CHOICE: Read calls vs codegraph_node[file] calls per run.
+#
+# Usage: ab-adoption.sh <indexed-repo> "<task>" [runs-per-arm] [baseline-ref]
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-adoption)
+set -uo pipefail
+TARGET="${1:?usage: ab-adoption.sh <indexed-repo> \"<task>\" [runs] [baseline-ref]}"
+TASK="${2:?task required}"
+RUNS="${3:-2}"
+BASE_REF="${4:-HEAD~1}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-adoption}"
+
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$TARGET/.codegraph" ] || { echo "target not indexed: run 'codegraph init $TARGET' first"; exit 1; }
+git -C "$ENGINE" diff --quiet && git -C "$ENGINE" diff --cached --quiet || { echo "engine has uncommitted changes — commit/stash first"; exit 1; }
+CHANGED=$(git -C "$ENGINE" diff --name-only "$BASE_REF" HEAD -- src 2>/dev/null)
+[ -n "$CHANGED" ] || { echo "no src/ changes between $BASE_REF and HEAD"; exit 1; }
+
+cleanup() {
+  pkill -9 -f "serve --mcp --path $OUT/" 2>/dev/null
+  git -C "$ENGINE" checkout HEAD -- $CHANGED 2>/dev/null
+  ( cd "$ENGINE" && npm run build >/dev/null 2>&1 )
+}
+trap cleanup EXIT
+mkdir -p "$OUT"
+echo "###### target=$TARGET  runs/arm=$RUNS  baseline=$BASE_REF"
+echo "###### changed: $(echo "$CHANGED" | tr '\n' ' ')"
+echo "###### task=$TASK"; echo
+
+prewarm() {
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" >/dev/null 2>&1
+}
+
+# Per-run tool-choice counts: Read vs codegraph_node[file] vs [symbol].
+count() {
+  node -e '
+    const fs=require("fs");
+    const lines=fs.readFileSync(process.argv[1],"utf8").split("\n").filter(Boolean);
+    let read=0,cgFile=0,cgSym=0,cgOther=0,exposed="?";
+    for(const l of lines){try{const o=JSON.parse(l);
+      if(o.type==="system"&&o.subtype==="init"){exposed=(o.tools||[]).filter(t=>/codegraph/.test(t)).length;}
+      const blocks=o.message?.content||[];
+      for(const b of (Array.isArray(blocks)?blocks:[])){
+        if(b.type!=="tool_use")continue;
+        if(b.name==="Read")read++;
+        else if(b.name==="mcp__codegraph__codegraph_node"){ if(b.input&&b.input.symbol)cgSym++; else cgFile++; }
+        else if(/mcp__codegraph__/.test(b.name))cgOther++;
+      }
+    }catch{}}
+    console.log(`    Read=${read}  codegraph_node[file]=${cgFile}  codegraph_node[symbol]=${cgSym}  other_cg=${cgOther}  (cg exposed=${exposed})`);
+  ' "$1"
+}
+
+run_arm() { # label, N
+  local label="$1" n="$2"
+  local c="$OUT/mcp-$label.json"
+  for i in $(seq 1 "$n"); do
+    local tgt="$OUT/t-$label-$i"
+    rm -rf "$tgt"
+    rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$TARGET/" "$tgt/"
+    node "$BIN" init "$tgt" >/dev/null 2>&1
+    printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$c"
+    prewarm "$tgt"
+    echo "----- [$label] run $i -----"
+    ( cd "$tgt" && claude -p "$TASK" \
+        --output-format stream-json --verbose --permission-mode bypassPermissions \
+        --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 --strict-mcp-config --mcp-config "$c" \
+        </dev/null > "$OUT/run-$label-$i.jsonl" 2>"$OUT/run-$label-$i.err" )
+    count "$OUT/run-$label-$i.jsonl"
+    pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  done
+  echo
+}
+
+echo "== NEW build (HEAD: codegraph_node has Read parity) =="
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+run_arm new "$RUNS"
+
+echo "== BASELINE build ($BASE_REF) =="
+git -C "$ENGINE" checkout "$BASE_REF" -- $CHANGED
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+run_arm baseline "$RUNS"
+
+echo "###### DONE — compare [new] vs [baseline]: does codegraph_node[file] rise / Read fall? Logs: $OUT"