@vohongtho.infotech/code-intel 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
-import path26 from 'path';
+import path27 from 'path';
 import fs19, { existsSync } from 'fs';
 import { Parser, Language, Query } from 'web-tree-sitter';
 import { NodeSDK } from '@opentelemetry/sdk-node';
@@ -26,6 +26,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSche
 import { Database, Connection } from '@ladybugdb/core';
 import { execSync } from 'child_process';
 import express from 'express';
+import compression from 'compression';
 import cors from 'cors';
 import helmet from 'helmet';
 import cookieParser from 'cookie-parser';
@@ -125,11 +126,11 @@ var init_shared = __esm({
   }
 });
 function findBundledWasmDir() {
-  const fileDir = path26.dirname(fileURLToPath(import.meta.url));
+  const fileDir = path27.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path26.join(fileDir, "wasm"),
+    path27.join(fileDir, "wasm"),
     // dist/index.js → dist/wasm/
-    path26.join(fileDir, "../wasm")
+    path27.join(fileDir, "../wasm")
     // dist/cli/main.js → dist/wasm/
   ];
   for (const candidate of candidates) {
@@ -170,7 +171,7 @@ function wasmPath(lang) {
   }
   const bundled = BUNDLED_WASM_MAP[lang];
   if (bundled) {
-    const bundledPath = path26.join(_bundledWasmDir, bundled);
+    const bundledPath = path27.join(_bundledWasmDir, bundled);
     if (existsSync(bundledPath)) return bundledPath;
   }
   return null;
@@ -1161,7 +1162,7 @@ var init_logger = __esm({
         };
       }
       /** Global log directory: ~/.code-intel/logs */
-      static LOG_DIR = path26.join(os12.homedir(), ".code-intel", "logs");
+      static LOG_DIR = path27.join(os12.homedir(), ".code-intel", "logs");
       static getLogger() {
         if (!_Logger.instance) {
           const isProduction = process.env.NODE_ENV === "production";
@@ -1175,7 +1176,7 @@ var init_logger = __esm({
               }
               transports.push(
                 new DailyRotateFile({
-                  filename: path26.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
+                  filename: path27.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
                   datePattern: "YYYY-MM-DD",
                   maxSize: "20m",
                   maxFiles: "14d"
@@ -1973,14 +1974,14 @@ var init_parse_phase = __esm({
           const lang = detectLanguage(filePath);
           if (!lang) {
             if (context2.verbose) {
-              const relativePath2 = path26.relative(context2.workspaceRoot, filePath);
+              const relativePath2 = path27.relative(context2.workspaceRoot, filePath);
               logger_default.info(`  [parse] skipped (no parser): ${relativePath2}`);
             }
             continue;
           }
           const source = context2.fileCache.get(filePath);
           if (!source) continue;
-          const relativePath = path26.relative(context2.workspaceRoot, filePath);
+          const relativePath = path27.relative(context2.workspaceRoot, filePath);
           const fileNodeId = generateNodeId("file", relativePath, relativePath);
           const fileNode = context2.graph.getNode(fileNodeId);
           if (fileNode) {
@@ -2220,11 +2221,11 @@ var init_resolve_phase = __esm({
         let heritageEdges = 0;
         const fileIndex = /* @__PURE__ */ new Map();
         for (const fp of filePaths) {
-          const rel = path26.relative(workspaceRoot, fp);
+          const rel = path27.relative(workspaceRoot, fp);
           fileIndex.set(rel, fp);
           const noExt = rel.replace(/\.\w+$/, "");
           if (!fileIndex.has(noExt)) fileIndex.set(noExt, fp);
-          const base = path26.basename(rel, path26.extname(rel));
+          const base = path27.basename(rel, path27.extname(rel));
           if (!fileIndex.has(base)) fileIndex.set(base, fp);
         }
         const symbolIndex = /* @__PURE__ */ new Map();
@@ -2255,7 +2256,7 @@ var init_resolve_phase = __esm({
         for (const filePath of filePaths) {
           const lang = detectLanguage(filePath);
           if (!lang) continue;
-          const relativePath = path26.relative(workspaceRoot, filePath);
+          const relativePath = path27.relative(workspaceRoot, filePath);
           const fileNodeId = generateNodeId("file", relativePath, relativePath);
           const source = fileCache.get(filePath);
           if (!source) continue;
@@ -2268,13 +2269,13 @@ var init_resolve_phase = __esm({
             let resolvedRelPath = null;
             if (cleaned.startsWith(".")) {
               const cleanedNoJs = cleaned.replace(/\.(js|jsx)$/, "");
-              const fromDir = path26.dirname(relativePath);
+              const fromDir = path27.dirname(relativePath);
               for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", "/index.ts", "/index.js"]) {
-                const candidate = path26.join(fromDir, cleanedNoJs + ext);
-                const normalized = path26.normalize(candidate);
+                const candidate = path27.join(fromDir, cleanedNoJs + ext);
+                const normalized = path27.normalize(candidate);
                 if (fileIndex.has(normalized)) {
                   const absPath = fileIndex.get(normalized);
-                  resolvedRelPath = path26.relative(workspaceRoot, absPath);
+                  resolvedRelPath = path27.relative(workspaceRoot, absPath);
                   break;
                 }
               }
@@ -2588,7 +2589,7 @@ __export(group_registry_exports, {
   saveSyncResult: () => saveSyncResult
 });
 function groupFile(name) {
-  return path26.join(GROUPS_DIR, `${name}.json`);
+  return path27.join(GROUPS_DIR, `${name}.json`);
 }
 function loadGroup(name) {
   try {
@@ -2608,7 +2609,7 @@ function listGroups() {
       if (!file.endsWith(".json") || file.endsWith(".sync.json")) continue;
       try {
         const g = JSON.parse(
-          fs19.readFileSync(path26.join(GROUPS_DIR, file), "utf-8")
+          fs19.readFileSync(path27.join(GROUPS_DIR, file), "utf-8")
         );
         groups.push(g);
       } catch {
@@ -2624,7 +2625,7 @@ function deleteGroup(name) {
   } catch {
   }
   try {
-    fs19.unlinkSync(path26.join(GROUPS_DIR, `${name}.sync.json`));
+    fs19.unlinkSync(path27.join(GROUPS_DIR, `${name}.sync.json`));
   } catch {
   }
 }
@@ -2657,14 +2658,14 @@ function removeMember(groupName, groupPath) {
 function saveSyncResult(result) {
   fs19.mkdirSync(GROUPS_DIR, { recursive: true });
   fs19.writeFileSync(
-    path26.join(GROUPS_DIR, `${result.groupName}.sync.json`),
+    path27.join(GROUPS_DIR, `${result.groupName}.sync.json`),
     JSON.stringify(result, null, 2) + "\n"
   );
 }
 function loadSyncResult(groupName) {
   try {
     return JSON.parse(
-      fs19.readFileSync(path26.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
+      fs19.readFileSync(path27.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
     );
   } catch {
     return null;
@@ -2673,7 +2674,7 @@ function loadSyncResult(groupName) {
 var GROUPS_DIR;
 var init_group_registry = __esm({
   "src/multi-repo/group-registry.ts"() {
-    GROUPS_DIR = path26.join(os12.homedir(), ".code-intel", "groups");
+    GROUPS_DIR = path27.join(os12.homedir(), ".code-intel", "groups");
   }
 });
 
@@ -2954,6 +2955,753 @@ var init_health_score = __esm({
   }
 });
 
+// src/query/gql-parser.ts
+var gql_parser_exports = {};
+__export(gql_parser_exports, {
+  isGQLParseError: () => isGQLParseError,
+  parseGQL: () => parseGQL
+});
+function isGQLParseError(v) {
+  return v.type === "GQLParseError";
+}
+function tokenize(input) {
+  const tokens = [];
+  let i = 0;
+  const len = input.length;
+  while (i < len) {
+    if (/\s/.test(input[i])) {
+      i++;
+      continue;
+    }
+    if (input[i] === "#") {
+      while (i < len && input[i] !== "\n") i++;
+      continue;
+    }
+    const pos = i;
+    if (input[i] === '"' || input[i] === "'") {
+      const quote = input[i];
+      i++;
+      let str = "";
+      while (i < len && input[i] !== quote) {
+        if (input[i] === "\\") {
+          i++;
+          if (i < len) {
+            const esc = input[i];
+            str += esc === "n" ? "\n" : esc === "t" ? "	" : esc;
+            i++;
+          }
+        } else {
+          str += input[i++];
+        }
+      }
+      if (i >= len) {
+        return { type: "GQLParseError", message: `Unterminated string at position ${pos}`, pos };
+      }
+      i++;
+      tokens.push({ kind: "STRING", value: str, pos });
+      continue;
+    }
+    if (/[0-9]/.test(input[i])) {
+      let num = "";
+      while (i < len && /[0-9]/.test(input[i])) num += input[i++];
+      tokens.push({ kind: "NUMBER", value: num, pos });
+      continue;
+    }
+    if (input[i] === "[") {
+      tokens.push({ kind: "LBRACKET", value: "[", pos });
+      i++;
+      continue;
+    }
+    if (input[i] === "]") {
+      tokens.push({ kind: "RBRACKET", value: "]", pos });
+      i++;
+      continue;
+    }
+    if (input[i] === "*") {
+      tokens.push({ kind: "STAR", value: "*", pos });
+      i++;
+      continue;
+    }
+    if (input[i] === "!" && input[i + 1] === "=") {
+      tokens.push({ kind: "OPERATOR", value: "!=", pos });
+      i += 2;
+      continue;
+    }
+    if (input[i] === "=") {
+      tokens.push({ kind: "OPERATOR", value: "=", pos });
+      i++;
+      continue;
+    }
+    if (/[a-zA-Z_]/.test(input[i])) {
+      let ident = "";
+      while (i < len && /[a-zA-Z0-9_]/.test(input[i])) ident += input[i++];
+      const upper = ident.toUpperCase();
+      if (upper === "CONTAINS" || upper === "STARTS_WITH" || upper === "IN") {
+        tokens.push({ kind: "OPERATOR", value: upper, pos });
+      } else if (KEYWORDS.has(upper)) {
+        tokens.push({ kind: "KEYWORD", value: upper, pos });
+      } else {
+        tokens.push({ kind: "IDENT", value: ident, pos });
+      }
+      continue;
+    }
+    if (input[i] === ",") {
+      i++;
+      continue;
+    }
+    return {
+      type: "GQLParseError",
+      message: `Unexpected character '${input[i]}' at position ${i}`,
+      pos: i
+    };
+  }
+  tokens.push({ kind: "EOF", value: "", pos: len });
+  return tokens;
+}
+function parseGQL(input) {
+  const tokens = tokenize(input.trim());
+  if (!Array.isArray(tokens)) return tokens;
+  const parser = new Parser2(tokens);
+  return parser.parse();
+}
+var KEYWORDS, Parser2;
+var init_gql_parser = __esm({
+  "src/query/gql-parser.ts"() {
+    KEYWORDS = /* @__PURE__ */ new Set([
+      "FIND",
+      "TRAVERSE",
+      "PATH",
+      "COUNT",
+      "WHERE",
+      "FROM",
+      "TO",
+      "IN",
+      "BY",
+      "AND",
+      "NOT",
+      "LIMIT",
+      "OFFSET",
+      "DEPTH",
+      "GROUP",
+      "CONTAINS",
+      "STARTS_WITH",
+      "CALLS",
+      "IMPORTS",
+      "EXTENDS",
+      "IMPLEMENTS",
+      "HAS_MEMBER",
+      "ACCESSES",
+      "OVERRIDES",
+      "BELONGS_TO",
+      "STEP_OF",
+      "HANDLES",
+      "CONTAINS_EDGE",
+      "OUTGOING",
+      "INCOMING",
+      "BOTH"
+    ]);
+    Parser2 = class {
+      tokens;
+      pos = 0;
+      constructor(tokens) {
+        this.tokens = tokens;
+      }
+      peek() {
+        return this.tokens[this.pos];
+      }
+      consume() {
+        return this.tokens[this.pos++];
+      }
+      expect(kind, value) {
+        const tok = this.peek();
+        if (tok.kind !== kind) {
+          return {
+            type: "GQLParseError",
+            message: `Expected ${value ?? kind} but got '${tok.value}' at position ${tok.pos}`,
+            pos: tok.pos,
+            expected: value ?? kind,
+            got: tok.value
+          };
+        }
+        if (value !== void 0 && tok.value !== value) {
+          return {
+            type: "GQLParseError",
+            message: `Expected '${value}' but got '${tok.value}' at position ${tok.pos}`,
+            pos: tok.pos,
+            expected: value,
+            got: tok.value
+          };
+        }
+        return this.consume();
+      }
+      matchKeyword(...values) {
+        const tok = this.peek();
+        return tok.kind === "KEYWORD" && values.includes(tok.value);
+      }
+      optionalKeyword(...values) {
+        if (this.matchKeyword(...values)) {
+          return this.consume();
+        }
+        return null;
+      }
+      /** Parse the node kind filter (IDENT, KEYWORD that's a kind, or STAR) */
+      parseNodeKind() {
+        const tok = this.peek();
+        if (tok.kind === "STAR") {
+          this.consume();
+          return "*";
+        }
+        if (tok.kind === "IDENT" || tok.kind === "KEYWORD") {
+          this.consume();
+          return tok.value.toLowerCase();
+        }
+        return {
+          type: "GQLParseError",
+          message: `Expected node kind or '*' at position ${tok.pos}`,
+          pos: tok.pos
+        };
+      }
+      /** Parse a string value (STRING or IDENT) */
+      parseStringValue() {
+        const tok = this.peek();
+        if (tok.kind === "STRING") {
+          this.consume();
+          return tok.value;
+        }
+        if (tok.kind === "IDENT" || tok.kind === "KEYWORD") {
+          this.consume();
+          return tok.value;
+        }
+        return {
+          type: "GQLParseError",
+          message: `Expected string value at position ${tok.pos}`,
+          pos: tok.pos
+        };
+      }
+      /** Parse an IN list: [ value, value, ... ] */
+      parseInList() {
+        const lb = this.expect("LBRACKET");
+        if (isGQLParseError(lb)) return lb;
+        const values = [];
+        while (!this.matchKeyword() && this.peek().kind !== "RBRACKET" && this.peek().kind !== "EOF") {
+          const v = this.parseStringValue();
+          if (typeof v !== "string") return v;
+          values.push(v);
+        }
+        const rb = this.expect("RBRACKET");
+        if (isGQLParseError(rb)) return rb;
+        return values;
+      }
+      /** Parse a single WHERE expression */
+      parseWhereExpr() {
+        const propTok = this.peek();
+        if (propTok.kind !== "IDENT" && propTok.kind !== "KEYWORD") {
+          return {
+            type: "GQLParseError",
+            message: `Expected property name at position ${propTok.pos}`,
+            pos: propTok.pos
+          };
+        }
+        this.consume();
+        const property = propTok.value.toLowerCase();
+        const opTok = this.peek();
+        if (opTok.kind !== "OPERATOR") {
+          return {
+            type: "GQLParseError",
+            message: `Expected operator (=, !=, CONTAINS, STARTS_WITH, IN) at position ${opTok.pos}`,
+            pos: opTok.pos,
+            expected: "operator",
+            got: opTok.value
+          };
+        }
+        this.consume();
+        const operator = opTok.value;
+        if (operator === "IN") {
+          const list = this.parseInList();
+          if (!Array.isArray(list)) return list;
+          return { property, operator, value: list };
+        }
+        const val = this.parseStringValue();
+        if (typeof val !== "string") return val;
+        return { property, operator, value: val };
+      }
+      /** Parse WHERE clause: WHERE expr (AND expr)* */
+      parseWhereClause() {
+        const kw = this.expect("KEYWORD", "WHERE");
+        if (isGQLParseError(kw)) return kw;
+        const exprs = [];
+        const first = this.parseWhereExpr();
+        if ("type" in first && first.type === "GQLParseError") return first;
+        exprs.push(first);
+        while (this.matchKeyword("AND")) {
+          this.consume();
+          const expr = this.parseWhereExpr();
+          if ("type" in expr && expr.type === "GQLParseError") return expr;
+          exprs.push(expr);
+        }
+        return { exprs };
+      }
+      /** Parse FIND statement */
+      parseFindStatement() {
+        this.consume();
+        const kind = this.parseNodeKind();
+        if (typeof kind !== "string") return kind;
+        let where;
+        if (this.matchKeyword("WHERE")) {
+          const w = this.parseWhereClause();
+          if ("type" in w && w.type === "GQLParseError") return w;
+          where = w;
+        }
+        let limit;
+        let offset;
+        while (this.matchKeyword("LIMIT", "OFFSET")) {
+          const kw = this.consume();
+          const numTok = this.peek();
+          if (numTok.kind !== "NUMBER") {
+            return {
+              type: "GQLParseError",
+              message: `Expected number after ${kw.value} at position ${numTok.pos}`,
+              pos: numTok.pos
+            };
+          }
+          this.consume();
+          const n = parseInt(numTok.value, 10);
+          if (kw.value === "LIMIT") limit = n;
+          else offset = n;
+        }
+        return { type: "FIND", target: kind, where, limit, offset };
+      }
+      /** Parse TRAVERSE statement */
+      parseTraverseStatement() {
+        this.consume();
+        const edgeTok = this.peek();
+        if (edgeTok.kind !== "KEYWORD" && edgeTok.kind !== "IDENT") {
+          return {
+            type: "GQLParseError",
+            message: `Expected edge kind after TRAVERSE at position ${edgeTok.pos}`,
+            pos: edgeTok.pos
+          };
+        }
+        this.consume();
+        const edgeKind = edgeTok.value.toLowerCase();
+        const fromKw = this.expect("KEYWORD", "FROM");
+        if (isGQLParseError(fromKw)) return fromKw;
+        const fromVal = this.parseStringValue();
+        if (typeof fromVal !== "string") return fromVal;
+        let depth;
+        let direction;
+        if (this.matchKeyword("DEPTH")) {
+          this.consume();
+          const numTok = this.peek();
+          if (numTok.kind !== "NUMBER") {
+            return {
+              type: "GQLParseError",
+              message: `Expected number after DEPTH at position ${numTok.pos}`,
+              pos: numTok.pos
+            };
+          }
+          this.consume();
+          depth = parseInt(numTok.value, 10);
+        }
+        if (this.matchKeyword("OUTGOING", "INCOMING", "BOTH")) {
+          direction = this.consume().value;
+        }
+        return { type: "TRAVERSE", edgeKind, from: fromVal, depth, direction };
+      }
+      /** Parse PATH statement */
+      parsePathStatement() {
+        this.consume();
+        const fromKw = this.expect("KEYWORD", "FROM");
+        if (isGQLParseError(fromKw)) return fromKw;
+        const fromVal = this.parseStringValue();
+        if (typeof fromVal !== "string") return fromVal;
+        const toKw = this.expect("KEYWORD", "TO");
+        if (isGQLParseError(toKw)) return toKw;
+        const toVal = this.parseStringValue();
+        if (typeof toVal !== "string") return toVal;
+        return { type: "PATH", from: fromVal, to: toVal };
+      }
+      /** Parse COUNT statement */
+      parseCountStatement() {
+        this.consume();
+        const kind = this.parseNodeKind();
+        if (typeof kind !== "string") return kind;
+        let where;
+        if (this.matchKeyword("WHERE")) {
+          const w = this.parseWhereClause();
+          if ("type" in w && w.type === "GQLParseError") return w;
+          where = w;
+        }
+        let groupBy;
+        if (this.matchKeyword("GROUP")) {
+          this.consume();
+          const byKw = this.expect("KEYWORD", "BY");
+          if (isGQLParseError(byKw)) return byKw;
+          const propTok = this.peek();
+          if (propTok.kind !== "IDENT" && propTok.kind !== "KEYWORD") {
+            return {
+              type: "GQLParseError",
+              message: `Expected property name after GROUP BY at position ${propTok.pos}`,
+              pos: propTok.pos
+            };
+          }
+          this.consume();
+          groupBy = propTok.value.toLowerCase();
+        }
+        return { type: "COUNT", target: kind, where, groupBy };
+      }
+      parse() {
+        const tok = this.peek();
+        if (tok.kind !== "KEYWORD") {
+          return {
+            type: "GQLParseError",
+            message: `Expected FIND, TRAVERSE, PATH, or COUNT at position ${tok.pos}`,
+            pos: tok.pos,
+            expected: "FIND | TRAVERSE | PATH | COUNT",
+            got: tok.value
+          };
+        }
+        let result;
+        switch (tok.value) {
+          case "FIND":
+            result = this.parseFindStatement();
+            break;
+          case "TRAVERSE":
+            result = this.parseTraverseStatement();
+            break;
+          case "PATH":
+            result = this.parsePathStatement();
+            break;
+          case "COUNT":
+            result = this.parseCountStatement();
+            break;
+          default:
+            return {
+              type: "GQLParseError",
+              message: `Unknown statement type '${tok.value}' at position ${tok.pos}`,
+              pos: tok.pos,
+              expected: "FIND | TRAVERSE | PATH | COUNT",
+              got: tok.value
+            };
+        }
+        if (isGQLParseError(result)) return result;
+        const remaining = this.peek();
+        if (remaining.kind !== "EOF") {
+          return {
+            type: "GQLParseError",
+            message: `Unexpected token '${remaining.value}' at position ${remaining.pos}`,
+            pos: remaining.pos,
+            got: remaining.value
+          };
+        }
+        return result;
+      }
+    };
+  }
+});
+
+// src/query/gql-executor.ts
+var gql_executor_exports = {};
+__export(gql_executor_exports, {
+  executeGQL: () => executeGQL
+});
+function getNodeProperty(node, property) {
+  switch (property) {
+    case "name":
+      return node.name;
+    case "kind":
+      return node.kind;
+    case "filepath":
+    case "filePath":
+      return node.filePath;
+    case "exported":
+      return node.exported;
+    case "language":
+      return node.metadata?.language ?? void 0;
+    case "cluster":
+      return node.metadata?.cluster ?? void 0;
+    default:
+      return node.metadata?.[property] ?? void 0;
+  }
+}
+function evaluateExpr(node, expr) {
+  const val = getNodeProperty(node, expr.property);
+  if (val === void 0) return false;
+  const strVal = String(val).toLowerCase();
+  switch (expr.operator) {
+    case "=":
+      if (typeof expr.value === "string") {
+        return strVal === expr.value.toLowerCase();
+      }
+      return false;
+    case "!=":
+      if (typeof expr.value === "string") {
+        return strVal !== expr.value.toLowerCase();
+      }
+      return true;
+    case "CONTAINS":
+      if (typeof expr.value === "string") {
+        return strVal.includes(expr.value.toLowerCase());
+      }
+      return false;
+    case "STARTS_WITH":
+      if (typeof expr.value === "string") {
+        return strVal.startsWith(expr.value.toLowerCase());
+      }
+      return false;
+    case "IN":
+      if (Array.isArray(expr.value)) {
+        return expr.value.some((v) => strVal === v.toLowerCase());
+      }
+      return false;
+    default:
+      return false;
+  }
+}
+function evaluateWhere(node, where) {
+  return where.exprs.every((expr) => evaluateExpr(node, expr));
+}
+function executeFIND(stmt, graph) {
+  const start = Date.now();
+  const limit = stmt.limit ?? 1e3;
+  const offset = stmt.offset ?? 0;
+  let totalCount = 0;
+  let truncated = false;
+  const allMatching = [];
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  for (const node of graph.allNodes()) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    if (stmt.target !== "*" && node.kind !== stmt.target) continue;
+    if (stmt.where && !evaluateWhere(node, stmt.where)) continue;
+    allMatching.push(node);
+  }
+  totalCount = allMatching.length;
+  const paginated = allMatching.slice(offset, offset + limit);
+  return {
+    nodes: paginated,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount
+  };
+}
+function executeTRAVERSE(stmt, graph) {
+  const start = Date.now();
+  const maxDepth = stmt.depth ?? 5;
+  const edgeKind = stmt.edgeKind;
+  const direction = stmt.direction ?? "OUTGOING";
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  let startNode;
+  for (const node of graph.allNodes()) {
+    if (node.name === stmt.from) {
+      startNode = node;
+      break;
+    }
+  }
+  if (!startNode) {
+    return {
+      nodes: [],
+      edges: [],
+      executionTimeMs: Date.now() - start,
+      truncated: false,
+      totalCount: 0
+    };
+  }
+  const visitedNodes = /* @__PURE__ */ new Set();
+  const visitedEdges = /* @__PURE__ */ new Set();
+  const resultNodes = [];
+  const resultEdges = [];
+  const queue = [{ id: startNode.id, depth: 0 }];
+  visitedNodes.add(startNode.id);
+  resultNodes.push(startNode);
+  let truncated = false;
+  while (queue.length > 0) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    const { id, depth } = queue.shift();
+    if (depth >= maxDepth) continue;
+    const nextEdges = [];
+    if (direction === "OUTGOING" || direction === "BOTH") {
+      for (const edge of graph.findEdgesFrom(id)) {
+        if (!edgeKind || edge.kind === edgeKind) nextEdges.push(edge);
+      }
+    }
+    if (direction === "INCOMING" || direction === "BOTH") {
+      for (const edge of graph.findEdgesTo(id)) {
+        if (!edgeKind || edge.kind === edgeKind) nextEdges.push(edge);
+      }
+    }
+    for (const edge of nextEdges) {
+      if (!visitedEdges.has(edge.id)) {
+        visitedEdges.add(edge.id);
+        resultEdges.push(edge);
+      }
+      const neighborId = direction === "INCOMING" ? edge.source : edge.target;
+      const effectiveNeighborId = direction === "BOTH" ? edge.source === id ? edge.target : edge.source : neighborId;
+      if (!visitedNodes.has(effectiveNeighborId)) {
+        visitedNodes.add(effectiveNeighborId);
+        const neighborNode = graph.getNode(effectiveNeighborId);
+        if (neighborNode) {
+          resultNodes.push(neighborNode);
+          queue.push({ id: effectiveNeighborId, depth: depth + 1 });
+        }
+      }
+    }
+  }
+  return {
+    nodes: resultNodes,
+    edges: resultEdges,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount: resultNodes.length
+  };
+}
+function executePATH(stmt, graph) {
+  const start = Date.now();
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  let startNode;
+  let endNode;
+  for (const node of graph.allNodes()) {
+    if (node.name === stmt.from) startNode = node;
+    if (node.name === stmt.to) endNode = node;
+    if (startNode && endNode) break;
+  }
+  if (!startNode || !endNode) {
+    return {
+      path: null,
+      nodes: [],
+      executionTimeMs: Date.now() - start,
+      truncated: false,
+      totalCount: 0
+    };
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const parent = /* @__PURE__ */ new Map();
+  const queue = [startNode.id];
+  visited.add(startNode.id);
+  let found = false;
+  let truncated = false;
+  outer: while (queue.length > 0) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    const current2 = queue.shift();
+    for (const edge of graph.findEdgesFrom(current2)) {
+      const next = edge.target;
+      if (!visited.has(next)) {
+        visited.add(next);
+        parent.set(next, { nodeId: current2, edgeId: edge.id });
+        if (next === endNode.id) {
+          found = true;
+          break outer;
+        }
+        queue.push(next);
+      }
+    }
+    for (const edge of graph.findEdgesTo(current2)) {
+      const next = edge.source;
+      if (!visited.has(next)) {
+        visited.add(next);
+        parent.set(next, { nodeId: current2, edgeId: edge.id });
+        if (next === endNode.id) {
+          found = true;
+          break outer;
+        }
+        queue.push(next);
+      }
+    }
+  }
+  if (!found) {
+    return {
+      path: null,
+      nodes: [],
+      executionTimeMs: Date.now() - start,
+      truncated,
+      totalCount: 0
+    };
+  }
+  const pathNodeIds = [];
+  const pathEdgeIds = [];
+  let current = endNode.id;
+  while (current !== startNode.id) {
+    pathNodeIds.unshift(current);
+    const p = parent.get(current);
+    pathEdgeIds.unshift(p.edgeId);
+    current = p.nodeId;
+  }
+  pathNodeIds.unshift(startNode.id);
+  const pathNodes = pathNodeIds.map((id) => graph.getNode(id)).filter(Boolean);
+  const pathEdges = pathEdgeIds.map((id) => graph.getEdge(id)).filter(Boolean);
+  return {
+    path: pathNodes,
+    nodes: pathNodes,
+    edges: pathEdges,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount: pathNodes.length
+  };
+}
+function executeCOUNT(stmt, graph) {
+  const start = Date.now();
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  let truncated = false;
+  const groups = /* @__PURE__ */ new Map();
+  let total = 0;
+  for (const node of graph.allNodes()) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    if (stmt.target !== "*" && node.kind !== stmt.target) continue;
+    if (stmt.where && !evaluateWhere(node, stmt.where)) continue;
+    total++;
+    if (stmt.groupBy) {
+      const key = String(getNodeProperty(node, stmt.groupBy) ?? "(none)");
+      groups.set(key, (groups.get(key) ?? 0) + 1);
+    } else {
+      groups.set("total", (groups.get("total") ?? 0) + 1);
+    }
+  }
+  const groupList = [...groups.entries()].map(([key, count]) => ({ key, count }));
+  groupList.sort((a, b) => b.count - a.count);
+  return {
+    groups: groupList,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount: total
+  };
+}
+function executeGQL(ast, graph) {
+  switch (ast.type) {
+    case "FIND":
+      return executeFIND(ast, graph);
+    case "TRAVERSE":
+      return executeTRAVERSE(ast, graph);
+    case "PATH":
+      return executePATH(ast, graph);
+    case "COUNT":
+      return executeCOUNT(ast, graph);
+    default:
+      return {
+        nodes: [],
+        executionTimeMs: 0,
+        truncated: false,
+        totalCount: 0
+      };
+  }
+}
+var EXECUTION_TIMEOUT_MS;
+var init_gql_executor = __esm({
+  "src/query/gql-executor.ts"() {
+    EXECUTION_TIMEOUT_MS = 1e4;
+  }
+});
+
 // src/errors/codes.ts
 var ErrorCodes, AppError;
 var init_codes = __esm({
@@ -3008,7 +3756,7 @@ function tightenDbFiles(dir) {
   for (const name of fs19.readdirSync(dir)) {
     if (name.endsWith(".db") || name.endsWith(".db-wal") || name.endsWith(".db-shm")) {
       try {
-        fs19.chmodSync(path26.join(dir, name), SECURE_FILE_MODE);
+        fs19.chmodSync(path27.join(dir, name), SECURE_FILE_MODE);
       } catch {
       }
     }
@@ -3022,7 +3770,7 @@ var init_fs_secure = __esm({
   }
 });
 function getUsersDBPath() {
-  return process.env["CODE_INTEL_USERS_DB_PATH"] ?? path26.join(os12.homedir(), ".code-intel", "users.db");
+  return process.env["CODE_INTEL_USERS_DB_PATH"] ?? path27.join(os12.homedir(), ".code-intel", "users.db");
 }
 function getOrCreateUsersDB() {
   if (!_usersDB) {
@@ -3038,7 +3786,7 @@ var init_users_db = __esm({
     UsersDB = class {
       db;
       constructor(dbPath) {
-        const dir = path26.dirname(dbPath);
+        const dir = path27.dirname(dbPath);
         secureMkdir(dir);
         this.db = new Database3(dbPath);
         this.db.pragma("journal_mode = WAL");
@@ -3315,7 +4063,7 @@ function getScryptN() {
   return Number.isInteger(v) && v >= 1024 ? v : 1 << 14;
 }
 function getSecretsPath() {
-  return process.env["CODE_INTEL_SECRETS_PATH"] ?? path26.join(os12.homedir(), ".code-intel", ".secrets");
+  return process.env["CODE_INTEL_SECRETS_PATH"] ?? path27.join(os12.homedir(), ".code-intel", ".secrets");
 }
 function getMasterPassword() {
   const fromEnv = process.env["CODE_INTEL_SECRET_KEY"];
@@ -3904,7 +4652,7 @@ init_shared();
 init_shared();
 init_typescript();
 function resolveRelative(rawPath, fromFile, workspace) {
-  const fromDir = path26.dirname(fromFile);
+  const fromDir = path27.dirname(fromFile);
   const cleaned = rawPath.replace(/['"]/g, "");
   const extensions = [".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.js"];
   const resolved = workspace.resolve(fromDir, cleaned);
@@ -3956,7 +4704,7 @@ var pythonModule = {
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/['"]/g, "");
     const parts = cleaned.split(".");
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     const relPath = parts.join("/");
     for (const suffix of ["/__init__.py", ".py"]) {
       const r = workspace.resolve(fromDir, relPath + suffix);
@@ -4035,7 +4783,7 @@ var cModule = {
   inheritanceStrategy: "none",
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/[<>"']/g, "");
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(_node) {
@@ -4058,7 +4806,7 @@ var cppModule = {
   inheritanceStrategy: "depth-first",
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/[<>"']/g, "");
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(_node) {
@@ -4220,7 +4968,7 @@ var dartModule = {
       const pkg = cleaned.replace("package:", "");
       return workspace.findByPackage(pkg);
     }
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(node) {
@@ -4806,7 +5554,7 @@ var IGNORED_DIRS = /* @__PURE__ */ new Set([
 ]);
 function loadIgnorePatterns(workspaceRoot) {
   try {
-    const raw = fs19.readFileSync(path26.join(workspaceRoot, ".codeintelignore"), "utf-8");
+    const raw = fs19.readFileSync(path27.join(workspaceRoot, ".codeintelignore"), "utf-8");
     const extras = /* @__PURE__ */ new Set();
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();
@@ -4839,13 +5587,13 @@ var scanPhase = {
           if (entry.name.startsWith(".")) continue;
           if (IGNORED_DIRS.has(entry.name)) continue;
           if (extraIgnore.has(entry.name)) continue;
-          walk(path26.join(dir, entry.name));
+          walk(path27.join(dir, entry.name));
         } else if (entry.isFile()) {
           const name = entry.name;
           if (IGNORED_FILE_SUFFIXES.some((s) => name.endsWith(s))) continue;
-          const ext = path26.extname(name);
+          const ext = path27.extname(name);
           if (!extensions.has(ext)) continue;
-          const fullPath = path26.join(dir, name);
+          const fullPath = path27.join(dir, name);
           try {
             const stat = fs19.statSync(fullPath);
             if (stat.size > MAX_FILE_SIZE_BYTES) continue;
@@ -4874,20 +5622,20 @@ var structurePhase = {
     const dirs = /* @__PURE__ */ new Set();
     let structDone = 0;
     for (const filePath of context2.filePaths) {
-      const relativePath = path26.relative(context2.workspaceRoot, filePath);
+      const relativePath = path27.relative(context2.workspaceRoot, filePath);
       const lang = detectLanguage(filePath);
       context2.graph.addNode({
         id: generateNodeId("file", relativePath, relativePath),
         kind: "file",
-        name: path26.basename(filePath),
+        name: path27.basename(filePath),
         filePath: relativePath,
         metadata: lang ? { language: lang } : void 0
       });
-      let dir = path26.dirname(relativePath);
+      let dir = path27.dirname(relativePath);
       while (dir && dir !== "." && dir !== "") {
         if (dirs.has(dir)) break;
         dirs.add(dir);
-        dir = path26.dirname(dir);
+        dir = path27.dirname(dir);
       }
       structDone++;
       context2.onPhaseProgress?.("structure", structDone, context2.filePaths.length);
@@ -4896,7 +5644,7 @@ var structurePhase = {
       context2.graph.addNode({
         id: generateNodeId("directory", dir, dir),
         kind: "directory",
-        name: path26.basename(dir),
+        name: path27.basename(dir),
         filePath: dir
       });
     }
@@ -5053,7 +5801,7 @@ var LLMGovernanceLogger = class {
   }
   /** Path to the JSONL log file. */
   getLogPath() {
-    return process.env["CODE_INTEL_GOVERNANCE_LOG_PATH"] ?? path26.join(os12.homedir(), ".code-intel", "llm-governance.jsonl");
+    return process.env["CODE_INTEL_GOVERNANCE_LOG_PATH"] ?? path27.join(os12.homedir(), ".code-intel", "llm-governance.jsonl");
   }
   /**
    * Append an entry to the governance log.
@@ -5069,7 +5817,7 @@ var LLMGovernanceLogger = class {
         ...entry
       };
       const logPath = this.getLogPath();
-      fs19.mkdirSync(path26.dirname(logPath), { recursive: true });
+      fs19.mkdirSync(path27.dirname(logPath), { recursive: true });
       fs19.appendFileSync(logPath, JSON.stringify(full) + "\n", "utf-8");
     } catch {
     }
@@ -5525,7 +6273,7 @@ var DbManager = class {
     this.dbPath = dbPath;
   }
   async init() {
-    fs19.mkdirSync(path26.dirname(this.dbPath), { recursive: true });
+    fs19.mkdirSync(path27.dirname(this.dbPath), { recursive: true });
     this.db = new Database(this.dbPath);
     await this.db.init();
     this.conn = new Connection(this.db);
@@ -5622,7 +6370,7 @@ function writeNodeCSVs(graph, outputDir) {
     const table = NODE_TABLE_MAP[node.kind];
     if (!tableBuffers.has(table)) {
       tableBuffers.set(table, [header]);
-      tableFilePaths.set(table, path26.join(outputDir, `${table}.csv`));
+      tableFilePaths.set(table, path27.join(outputDir, `${table}.csv`));
     }
     tableBuffers.get(table).push(
       csvRow([
@@ -5658,7 +6406,7 @@ function writeEdgeCSV(graph, outputDir) {
     const toTable = NODE_TABLE_MAP[targetNode.kind];
     const key = `${fromTable}->${toTable}`;
     if (!groups.has(key)) {
-      const filePath = path26.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
+      const filePath = path27.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
       groups.set(key, { lines: [header], from: fromTable, to: toTable, filePath });
     }
     groups.get(key).lines.push(
@@ -5701,7 +6449,7 @@ async function loadGraphToDB(graph, dbManager) {
     } catch {
     }
   }
-  const tmpDir = fs19.mkdtempSync(path26.join(os12.tmpdir(), "code-intel-csv-"));
+  const tmpDir = fs19.mkdtempSync(path27.join(os12.tmpdir(), "code-intel-csv-"));
   try {
     const nodeTableFiles = writeNodeCSVs(graph, tmpDir);
     const edgeGroups = writeEdgeCSV(graph, tmpDir);
@@ -5801,8 +6549,8 @@ function buildNodeProps(node) {
 function escCypher(s) {
   return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "");
 }
-var GLOBAL_DIR = path26.join(os12.homedir(), ".code-intel");
-var REPOS_FILE = path26.join(GLOBAL_DIR, "repos.json");
+var GLOBAL_DIR = path27.join(os12.homedir(), ".code-intel");
+var REPOS_FILE = path27.join(GLOBAL_DIR, "repos.json");
 function loadRegistry() {
   try {
     const data = fs19.readFileSync(REPOS_FILE, "utf-8");
@@ -5830,23 +6578,23 @@ function removeRepo(repoPath) {
   saveRegistry(entries);
 }
 function saveMetadata(repoDir, metadata) {
-  const metaDir = path26.join(repoDir, ".code-intel");
+  const metaDir = path27.join(repoDir, ".code-intel");
   fs19.mkdirSync(metaDir, { recursive: true });
-  fs19.writeFileSync(path26.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
+  fs19.writeFileSync(path27.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
 }
 function loadMetadata(repoDir) {
   try {
-    const data = fs19.readFileSync(path26.join(repoDir, ".code-intel", "meta.json"), "utf-8");
+    const data = fs19.readFileSync(path27.join(repoDir, ".code-intel", "meta.json"), "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 function getDbPath(repoDir) {
-  return path26.join(repoDir, ".code-intel", "graph.db");
+  return path27.join(repoDir, ".code-intel", "graph.db");
 }
 function getVectorDbPath(repoDir) {
-  return path26.join(repoDir, ".code-intel", "vector.db");
+  return path27.join(repoDir, ".code-intel", "vector.db");
 }
 
 // src/mcp-server/server.ts
@@ -6045,7 +6793,7 @@ async function syncGroup(group) {
       logger_default.warn(`  \u26A0 Registry entry "${member.registryName}" not found \u2014 skipping ${member.groupPath}`);
       continue;
     }
-    const dbPath = path26.join(regEntry.path, ".code-intel", "graph.db");
+    const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
     if (!fs19.existsSync(dbPath)) {
       logger_default.warn(`  \u26A0 No index at ${dbPath} \u2014 run \`code-intel analyze ${regEntry.path}\` first`);
       continue;
@@ -6081,7 +6829,7 @@ async function queryGroup(group, query, limit = 20) {
   for (const member of group.members) {
     const regEntry = registry.find((r) => r.name === member.registryName);
     if (!regEntry) continue;
-    const dbPath = path26.join(regEntry.path, ".code-intel", "graph.db");
+    const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
     if (!fs19.existsSync(dbPath)) continue;
     const graph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
@@ -6265,6 +7013,23 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           }
         }
       },
+      // ── query (GQL) ────────────────────────────────────────────────────────
+      {
+        name: "query",
+        description: "Execute a GQL (Graph Query Language) query. Supports FIND, TRAVERSE, PATH, and COUNT. More expressive than raw_query.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            gql: {
+              type: "string",
+              description: 'GQL query string. Examples: "FIND function WHERE name CONTAINS \\"auth\\"", "TRAVERSE CALLS FROM \\"handleLogin\\" DEPTH 3", "PATH FROM \\"createUser\\" TO \\"sendEmail\\"", "COUNT function GROUP BY cluster"'
+            },
+            limit: { type: "number", description: "Override LIMIT in the query (optional)" },
+            ..._tokenProp
+          },
+          required: ["gql"]
+        }
+      },
       // ── Raw query ─────────────────────────────────────────────────────────
       {
         name: "raw_query",
@@ -6445,7 +7210,7 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       const limit = a.limit ?? 20;
       const vdbPath = workspaceRoot ? getVectorDbPath(workspaceRoot) : void 0;
       const { results, searchMode } = await hybridSearch(graph, query, limit, { vectorDbPath: vdbPath });
-      return { content: [{ type: "text", text: JSON.stringify({ results, searchMode }, null, 2) }] };
+      return { content: [{ type: "text", text: JSON.stringify({ results, searchMode, suggested_next_tools: ["inspect", "query", "blast_radius"] }, null, 2) }] };
     }
     // ── inspect ────────────────────────────────────────────────────────────
     case "inspect": {
@@ -6684,7 +7449,7 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       for (const { filePath: changedFile, changedLines } of changedFiles) {
         for (const node of graph.allNodes()) {
           if (!node.filePath) continue;
-          const normNode = node.filePath.replace(repoRoot + "/", "").replace(repoRoot + path26.sep, "");
+          const normNode = node.filePath.replace(repoRoot + "/", "").replace(repoRoot + path27.sep, "");
           const normChanged = changedFile.replace(/^a\/|^b\//, "");
           if (!normNode.endsWith(normChanged) && !normChanged.endsWith(normNode)) continue;
           if (node.startLine !== void 0 && node.endLine !== void 0) {
@@ -6733,16 +7498,51 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
         }]
       };
     }
+    // ── query (GQL) ───────────────────────────────────────────────────────────
+    case "query": {
+      const gqlInput = a.gql;
+      if (!gqlInput) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Missing required parameter: gql" }) }], isError: true };
+      }
+      const { parseGQL: parseGQL2, isGQLParseError: isGQLParseError2 } = await Promise.resolve().then(() => (init_gql_parser(), gql_parser_exports));
+      const { executeGQL: executeGQL2 } = await Promise.resolve().then(() => (init_gql_executor(), gql_executor_exports));
+      const ast = parseGQL2(gqlInput);
+      if (isGQLParseError2(ast)) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: `GQL parse error: ${ast.message}`, pos: ast.pos, expected: ast.expected, got: ast.got }) }],
+          isError: true
+        };
+      }
+      if (a.limit !== void 0 && ast.type === "FIND") {
+        ast.limit = a.limit;
+      }
+      const result = executeGQL2(ast, graph);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            nodes: result.nodes,
+            edges: result.edges,
+            groups: result.groups,
+            path: result.path,
+            executionTimeMs: result.executionTimeMs,
+            truncated: result.truncated,
+            totalCount: result.totalCount
+          }, null, 2)
+        }]
+      };
+    }
     // ── raw_query ──────────────────────────────────────────────────────────
     case "raw_query": {
       const q = a.cypher;
+      const deprecationWarning = "raw_query is deprecated, use query instead";
       const nameMatch = q?.match(/name\s*=\s*['"]([^'"]+)['"]/i);
       if (nameMatch) {
         const results = [];
         for (const node of graph.allNodes()) {
           if (node.name === nameMatch[1]) results.push(node);
         }
-        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        return { content: [{ type: "text", text: JSON.stringify({ deprecation: deprecationWarning, results }, null, 2) }] };
       }
       const kindMatch = q?.match(/:\s*(\w+)/);
       if (kindMatch) {
@@ -6751,9 +7551,9 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
           if (node.kind === kindMatch[1]) results.push(node);
           if (results.length >= 50) break;
         }
-        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        return { content: [{ type: "text", text: JSON.stringify({ deprecation: deprecationWarning, results }, null, 2) }] };
       }
-      return { content: [{ type: "text", text: "Query not recognized. Use name='X' or :kind syntax." }] };
+      return { content: [{ type: "text", text: JSON.stringify({ deprecation: deprecationWarning, error: "Query not recognized. Use name='X' or :kind syntax. Or use the query tool with GQL instead." }) }] };
     }
     // ── group_list ─────────────────────────────────────────────────────────
     case "group_list": {
@@ -6964,7 +7764,7 @@ var STUCK_THRESHOLD_MINUTES = 30;
 var JobsDB = class {
   db;
   constructor(dbPath) {
-    fs19.mkdirSync(path26.dirname(dbPath), { recursive: true });
+    fs19.mkdirSync(path27.dirname(dbPath), { recursive: true });
     this.db = new Database3(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.pragma("foreign_keys = ON");
@@ -7106,7 +7906,7 @@ var JobsDB = class {
   }
 };
 function getJobsDBPath() {
-  return path26.join(os12.homedir(), ".code-intel", "jobs.db");
+  return path27.join(os12.homedir(), ".code-intel", "jobs.db");
 }
 var _jobsDB = null;
 function getOrCreateJobsDB() {
@@ -7198,7 +7998,7 @@ var BACKUP_VERSION = "1.0";
 var ALGORITHM = "aes-256-gcm";
 var IV_LENGTH = 16;
 function getBackupDir() {
-  return path26.join(os12.homedir(), ".code-intel", "backups");
+  return path27.join(os12.homedir(), ".code-intel", "backups");
 }
 function getBackupKey() {
   const keyHex = process.env["CODE_INTEL_BACKUP_KEY"];
@@ -7236,22 +8036,22 @@ var BackupService = class {
    * Returns the backup entry.
    */
   createBackup(repoPath) {
-    const codeIntelDir = path26.join(repoPath, ".code-intel");
+    const codeIntelDir = path27.join(repoPath, ".code-intel");
     const id = v4();
     const createdAt = (/* @__PURE__ */ new Date()).toISOString();
     const filesToBackup = [];
     const candidates = ["graph.db", "vector.db", "meta.json"];
     for (const f of candidates) {
-      const fp = path26.join(codeIntelDir, f);
+      const fp = path27.join(codeIntelDir, f);
       if (fs19.existsSync(fp)) {
         filesToBackup.push({ name: f, localPath: fp });
       }
     }
-    const registryPath = path26.join(os12.homedir(), ".code-intel", "registry.json");
+    const registryPath = path27.join(os12.homedir(), ".code-intel", "registry.json");
     if (fs19.existsSync(registryPath)) {
       filesToBackup.push({ name: "registry.json", localPath: registryPath });
     }
-    const usersDbPath = path26.join(os12.homedir(), ".code-intel", "users.db");
+    const usersDbPath = path27.join(os12.homedir(), ".code-intel", "users.db");
     if (fs19.existsSync(usersDbPath)) {
       filesToBackup.push({ name: "users.db", localPath: usersDbPath });
     }
@@ -7288,7 +8088,7 @@ var BackupService = class {
     const plaintext = Buffer.concat(parts);
     const encrypted = encryptBuffer(plaintext, this.key);
     const backupFileName = `backup-${id}.cib`;
-    const backupPath = path26.join(this.backupDir, backupFileName);
+    const backupPath = path27.join(this.backupDir, backupFileName);
     fs19.writeFileSync(backupPath, encrypted);
     const entry = {
       id,
@@ -7316,7 +8116,7 @@ var BackupService = class {
   async uploadToS3(entry) {
     const cfg = getS3Config();
     if (!cfg) throw new Error("S3 not configured. Set CODE_INTEL_BACKUP_S3_BUCKET, CODE_INTEL_BACKUP_S3_ACCESS_KEY_ID, CODE_INTEL_BACKUP_S3_SECRET_ACCESS_KEY.");
-    const fileName = path26.basename(entry.path);
+    const fileName = path27.basename(entry.path);
     const s3Key = `${cfg.prefix}${fileName}`;
     const body = fs19.readFileSync(entry.path);
     const result = await s3Request({ method: "PUT", cfg, key: s3Key, body });
@@ -7335,7 +8135,7 @@ var BackupService = class {
     if (result.statusCode < 200 || result.statusCode >= 300) {
       throw new Error(`S3 download failed (HTTP ${result.statusCode}): ${result.body.slice(0, 200)}`);
     }
-    fs19.mkdirSync(path26.dirname(destPath), { recursive: true });
+    fs19.mkdirSync(path27.dirname(destPath), { recursive: true });
     fs19.writeFileSync(destPath, Buffer.from(result.body, "binary"));
   }
   /**
@@ -7399,7 +8199,7 @@ var BackupService = class {
     offset += manifestLen;
     const manifest = JSON.parse(manifestStr);
     const restoreBase = targetRepoPath ?? entry.repoPath;
-    const codeIntelDir = path26.join(restoreBase, ".code-intel");
+    const codeIntelDir = path27.join(restoreBase, ".code-intel");
     fs19.mkdirSync(codeIntelDir, { recursive: true });
     for (const fileEntry of manifest.files) {
       const nameLen = plaintext.readUInt16BE(offset);
@@ -7417,9 +8217,9 @@ var BackupService = class {
       }
       let destPath;
       if (name === "registry.json" || name === "users.db") {
-        destPath = path26.join(os12.homedir(), ".code-intel", name);
+        destPath = path27.join(os12.homedir(), ".code-intel", name);
       } else {
-        destPath = path26.join(codeIntelDir, name);
+        destPath = path27.join(codeIntelDir, name);
       }
       fs19.writeFileSync(destPath, data);
     }
@@ -7470,7 +8270,7 @@ var BackupService = class {
   }
   // ── Index helpers ──────────────────────────────────────────────────────────
   _indexPath() {
-    return path26.join(this.backupDir, "index.json");
+    return path27.join(this.backupDir, "index.json");
   }
   _loadIndex() {
     try {
@@ -7971,6 +8771,60 @@ var openApiSpec = {
         }
       }
     },
+    "/source": {
+      get: {
+        tags: ["Files"],
+        summary: "Get source code preview with context around specified lines",
+        description: "Returns the file content around the specified line range (\xB120 lines context), with language detection. Requires viewer role.",
+        security: [{ BearerAuth: [] }, { SessionCookie: [] }],
+        parameters: [
+          {
+            name: "file",
+            in: "query",
+            required: true,
+            description: "Absolute path to the file",
+            schema: { type: "string" }
+          },
+          {
+            name: "startLine",
+            in: "query",
+            required: false,
+            description: "Start line number (1-indexed)",
+            schema: { type: "integer", minimum: 1 }
+          },
+          {
+            name: "endLine",
+            in: "query",
+            required: false,
+            description: "End line number (1-indexed)",
+            schema: { type: "integer", minimum: 1 }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "Source code preview",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    content: { type: "string", description: "File content (with context lines)" },
+                    language: { type: "string", description: "Detected programming language", example: "typescript" },
+                    startLine: { type: "integer", description: "Actual start line returned (with context)" },
+                    endLine: { type: "integer", description: "Actual end line returned (with context)" }
+                  },
+                  required: ["content", "language", "startLine", "endLine"]
+                }
+              }
+            }
+          },
+          "400": { description: "Bad request (missing file param or path traversal detected)", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "401": { description: "Unauthorized", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "403": { description: "Forbidden (file outside indexed repos)", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "404": { description: "File not found", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
     "/grep": {
       post: {
         tags: ["Files"],
@@ -8084,16 +8938,122 @@ var openApiSpec = {
           "404": { description: "Group not found", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
         }
       }
+    },
+    "/query": {
+      post: {
+        tags: ["GQL"],
+        summary: "Execute a GQL (Graph Query Language) query against the knowledge graph",
+        description: "Supports FIND, TRAVERSE, PATH, and COUNT statements. Requires viewer role minimum.",
+        security: [{ BearerAuth: [] }, { SessionCookie: [] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  gql: {
+                    type: "string",
+                    description: "GQL query string",
+                    example: 'FIND function WHERE name CONTAINS "auth"'
+                  },
+                  format: {
+                    type: "string",
+                    enum: ["json", "table", "csv"],
+                    default: "json",
+                    description: "Output format"
+                  }
+                },
+                required: ["gql"]
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "GQL execution result",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    nodes: { type: "array", items: { "$ref": "#/components/schemas/CodeNode" } },
+                    edges: { type: "array", items: { type: "object" } },
+                    groups: { type: "array", items: { type: "object", properties: { key: { type: "string" }, count: { type: "integer" } } } },
+                    path: { type: "array", items: { "$ref": "#/components/schemas/CodeNode" }, nullable: true },
+                    executionTimeMs: { type: "number" },
+                    truncated: { type: "boolean" },
+                    totalCount: { type: "integer" }
+                  }
+                }
+              }
+            }
+          },
+          "400": { description: "Missing gql field", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "401": { description: "Unauthorized", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "403": { description: "Forbidden (insufficient role)", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "422": { description: "GQL parse error", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
+    "/query/explain": {
+      post: {
+        tags: ["GQL"],
+        summary: "Explain a GQL query \u2014 returns the execution plan without running it",
+        description: "Returns a query plan object describing the steps that would be executed. Requires viewer role minimum.",
+        security: [{ BearerAuth: [] }, { SessionCookie: [] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  gql: { type: "string", description: "GQL query string", example: 'FIND function WHERE name CONTAINS "auth"' }
+                },
+                required: ["gql"]
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Query plan",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    plan: {
+                      type: "object",
+                      properties: {
+                        type: { type: "string", enum: ["FIND", "TRAVERSE", "PATH", "COUNT"] },
+                        gql: { type: "string" },
+                        steps: { type: "array", items: { type: "object" } },
+                        estimatedCost: { type: "number" }
+                      }
+                    },
+                    graphSize: { type: "object", properties: { nodes: { type: "integer" }, edges: { type: "integer" } } }
+                  }
+                }
+              }
+            }
+          },
+          "400": { description: "Missing gql field", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "401": { description: "Unauthorized", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "422": { description: "GQL parse error", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
     }
   }
 };
 
 // src/http/app.ts
-var __dirname$1 = path26.dirname(fileURLToPath(import.meta.url));
+var __dirname$1 = path27.dirname(fileURLToPath(import.meta.url));
 var WEB_DIST = (() => {
-  const bundled = path26.resolve(__dirname$1, "..", "web");
+  const bundled = path27.resolve(__dirname$1, "..", "web");
   if (fs19.existsSync(bundled)) return bundled;
-  return path26.resolve(__dirname$1, "..", "..", "..", "web", "dist");
+  return path27.resolve(__dirname$1, "..", "..", "..", "web", "dist");
 })();
 function getAllowedOrigins() {
   const env = process.env["CODE_INTEL_CORS_ORIGINS"];
@@ -8121,6 +9081,7 @@ function createDefaultLimiter() {
 function createApp(graph, repoName, workspaceRoot, watcherState) {
   const app = express();
   app.set("trust proxy", 1);
+  app.use(compression());
   app.use(
     helmet({
       contentSecurityPolicy: false
@@ -8623,7 +9584,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     const registry = loadRegistry();
     const entry = registry.find((r) => r.name === requestedRepo || r.path === requestedRepo);
     if (!entry) return null;
-    const dbPath = path26.join(entry.path, ".code-intel", "graph.db");
+    const dbPath = path27.join(entry.path, ".code-intel", "graph.db");
     if (!fs19.existsSync(dbPath)) return null;
     const repoGraph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
@@ -8969,7 +9930,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     for (const member of group.members) {
       const regEntry = registry.find((r) => r.name === member.registryName);
       if (!regEntry) continue;
-      const dbPath = path26.join(regEntry.path, ".code-intel", "graph.db");
+      const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
       if (!fs19.existsSync(dbPath)) continue;
       const db = new DbManager(dbPath);
       try {
@@ -8982,10 +9943,245 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     }
     res.json({ nodes: [...mergedGraph.allNodes()], edges: [...mergedGraph.allEdges()] });
   });
+  app.get("/api/v1/source", requireAuth, requireRole("viewer"), (req, res) => {
+    const { file, startLine: startLineStr, endLine: endLineStr } = req.query;
+    if (!file) {
+      res.status(400).json({
+        error: {
+          code: ErrorCodes.INVALID_REQUEST,
+          message: "Missing required query parameter: file",
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    if (file.includes("../")) {
+      res.status(400).json({
+        error: {
+          code: ErrorCodes.INVALID_REQUEST,
+          message: "Path traversal detected",
+          hint: 'File paths must not contain "../"',
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    let rawResolved = path27.normalize(file);
+    if (!path27.isAbsolute(rawResolved) && workspaceRoot) {
+      rawResolved = path27.join(workspaceRoot, rawResolved);
+    }
+    const resolvedFile = path27.resolve(rawResolved);
+    function isInsideDir(fileAbs, dir) {
+      const rel = path27.relative(path27.resolve(dir), fileAbs);
+      return !rel.startsWith("..") && !path27.isAbsolute(rel);
+    }
+    if (workspaceRoot) {
+      if (!isInsideDir(resolvedFile, workspaceRoot)) {
+        const registry = loadRegistry();
+        const inKnownRepo = registry.some((r) => isInsideDir(resolvedFile, r.path));
+        if (!inKnownRepo) {
+          res.status(403).json({
+            error: {
+              code: ErrorCodes.FORBIDDEN,
+              message: "Access denied",
+              hint: "File path must be within an indexed repository",
+              requestId: req.requestId,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            }
+          });
+          return;
+        }
+      }
+    } else {
+      const registry = loadRegistry();
+      const inKnownRepo = registry.some((r) => isInsideDir(resolvedFile, r.path));
+      if (!inKnownRepo) {
+        res.status(403).json({
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: "Access denied",
+            hint: "File path must be within an indexed repository",
+            requestId: req.requestId,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        return;
+      }
+    }
+    let fileContent;
+    try {
+      fileContent = fs19.readFileSync(resolvedFile, "utf-8");
+    } catch {
+      res.status(404).json({
+        error: {
+          code: ErrorCodes.NOT_FOUND,
+          message: "File not found",
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    const lines = fileContent.split("\n");
+    const parsedStart = startLineStr ? Number.parseInt(startLineStr, 10) : 1;
+    const parsedEnd = endLineStr ? Number.parseInt(endLineStr, 10) : parsedStart;
+    if (!Number.isFinite(parsedStart) || parsedStart < 1 || !Number.isFinite(parsedEnd) || parsedEnd < 1) {
+      res.status(400).json({
+        error: {
+          code: ErrorCodes.INVALID_REQUEST,
+          message: "Invalid startLine or endLine: must be positive integers",
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    const startLine = Math.max(1, parsedStart);
+    const endLine = Math.min(lines.length, parsedEnd);
+    const contextStart = Math.max(1, startLine - 20);
+    const contextEnd = Math.min(lines.length, endLine + 20);
+    const content = lines.slice(contextStart - 1, contextEnd).join("\n");
+    const ext = path27.extname(resolvedFile).toLowerCase();
+    const languageMap = {
+      ".ts": "typescript",
+      ".tsx": "typescript",
+      ".js": "javascript",
+      ".jsx": "javascript",
+      ".mjs": "javascript",
+      ".cjs": "javascript",
+      ".py": "python",
+      ".go": "go",
+      ".rs": "rust",
+      ".java": "java",
+      ".cs": "csharp",
+      ".cpp": "cpp",
+      ".cc": "cpp",
+      ".cxx": "cpp",
+      ".c": "c",
+      ".h": "c",
+      ".hpp": "cpp",
+      ".rb": "ruby",
+      ".php": "php",
+      ".swift": "swift",
+      ".kt": "kotlin",
+      ".kts": "kotlin",
+      ".json": "json",
+      ".yaml": "yaml",
+      ".yml": "yaml",
+      ".md": "markdown",
+      ".sh": "bash",
+      ".bash": "bash",
+      ".zsh": "bash",
+      ".sql": "sql",
+      ".html": "html",
+      ".htm": "html",
+      ".css": "css",
+      ".scss": "scss",
+      ".less": "less",
+      ".xml": "xml",
+      ".toml": "toml"
+    };
+    const language = languageMap[ext] ?? "plaintext";
+    res.json({
+      content,
+      language,
+      startLine: contextStart,
+      endLine: contextEnd
+    });
+  });
+  app.post("/api/v1/query", requireRole("viewer"), async (req, res) => {
+    const { gql, format } = req.body;
+    if (!gql || typeof gql !== "string") {
+      res.status(400).json({
+        error: { code: ErrorCodes.INVALID_REQUEST, message: "Missing required field: gql", requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      });
+      return;
+    }
+    try {
+      const { parseGQL: parseGQL2, isGQLParseError: isGQLParseError2 } = await Promise.resolve().then(() => (init_gql_parser(), gql_parser_exports));
+      const { executeGQL: executeGQL2 } = await Promise.resolve().then(() => (init_gql_executor(), gql_executor_exports));
+      const ast = parseGQL2(gql);
+      if (isGQLParseError2(ast)) {
+        res.status(422).json({
+          error: {
+            code: ErrorCodes.INVALID_REQUEST,
+            message: `GQL parse error: ${ast.message}`,
+            hint: `Position: ${ast.pos}${ast.expected ? `, expected: ${ast.expected}` : ""}${ast.got ? `, got: ${ast.got}` : ""}`,
+            requestId: req.requestId,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        return;
+      }
+      const result = executeGQL2(ast, graph);
+      const statusCode = result.truncated ? 408 : 200;
+      res.status(statusCode).json({ ...result, format: format ?? "json" });
+    } catch (err) {
+      res.status(500).json({ error: { code: ErrorCodes.INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err), requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() } });
+    }
+  });
+  app.post("/api/v1/query/explain", requireRole("viewer"), async (req, res) => {
+    const { gql } = req.body;
+    if (!gql || typeof gql !== "string") {
+      res.status(400).json({
+        error: { code: ErrorCodes.INVALID_REQUEST, message: "Missing required field: gql", requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      });
+      return;
+    }
+    try {
+      const { parseGQL: parseGQL2, isGQLParseError: isGQLParseError2 } = await Promise.resolve().then(() => (init_gql_parser(), gql_parser_exports));
+      const ast = parseGQL2(gql);
+      if (isGQLParseError2(ast)) {
+        res.status(422).json({
+          error: {
+            code: ErrorCodes.INVALID_REQUEST,
+            message: `GQL parse error: ${ast.message}`,
+            hint: `Position: ${ast.pos}`,
+            requestId: req.requestId,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        return;
+      }
+      const plan = { type: ast.type, gql };
+      if (ast.type === "FIND") {
+        plan.steps = [
+          { step: 1, op: "SCAN_NODES", filter: ast.target === "*" ? "all" : `kind=${ast.target}` },
+          ...ast.where ? [{ step: 2, op: "WHERE", conditions: ast.where.exprs.length }] : [],
+          ...ast.limit !== void 0 ? [{ step: 3, op: "LIMIT", value: ast.limit }] : []
+        ];
+        plan.estimatedCost = graph.size.nodes;
+      } else if (ast.type === "TRAVERSE") {
+        plan.steps = [
+          { step: 1, op: "FIND_START_NODE", name: ast.from },
+          { step: 2, op: "BFS", edgeKind: ast.edgeKind, maxDepth: ast.depth ?? 5 }
+        ];
+        plan.estimatedCost = Math.min(graph.size.nodes, Math.pow(4, ast.depth ?? 5));
+      } else if (ast.type === "PATH") {
+        plan.steps = [
+          { step: 1, op: "FIND_NODES", from: ast.from, to: ast.to },
+          { step: 2, op: "BFS_SHORTEST_PATH" }
+        ];
+        plan.estimatedCost = graph.size.nodes + graph.size.edges;
+      } else if (ast.type === "COUNT") {
+        plan.steps = [
+          { step: 1, op: "SCAN_NODES", filter: ast.target === "*" ? "all" : `kind=${ast.target}` },
+          ...ast.where ? [{ step: 2, op: "WHERE", conditions: ast.where.exprs.length }] : [],
+          ...ast.groupBy ? [{ step: 3, op: "GROUP_BY", property: ast.groupBy }] : [{ step: 3, op: "COUNT" }]
+        ];
+        plan.estimatedCost = graph.size.nodes;
+      }
+      res.json({ plan, graphSize: graph.size });
+    } catch (err) {
+      res.status(500).json({ error: { code: ErrorCodes.INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err), requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() } });
+    }
+  });
   if (fs19.existsSync(WEB_DIST)) {
     app.use(express.static(WEB_DIST));
     app.get("/{*path}", (_req, res) => {
-      res.sendFile(path26.join(WEB_DIST, "index.html"));
+      res.sendFile(path27.join(WEB_DIST, "index.html"));
     });
   }
   app.use("/admin", requireRole("admin"));