graph-indexer 2.1.1 → 3.0.1

package/integrations/opencode/graph-indexer.js

@@ -0,0 +1,129 @@
+/**
+ * graph-indexer plugin for OpenCode and Kilo Code (installed by `graph-indexer init --hooks`).
+ *
+ * After a read, a search or an edit it appends to the tool's output what the Claude Code hooks add
+ * as context: where the names used in the lines just read are defined (once the agent is
+ * crawling), where a definition that a search missed is, and what an edit broke. It asks the
+ * repository's graph-indexer resident process over its local socket (the MCP server `init`
+ * configures keeps one running) and adds nothing when none answers; the first miss starts
+ * `graph-indexer daemon` in the background for the next calls.
+ *
+ * Only the plugin function is exported: OpenCode calls every export of a plugin module.
+ */
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+const PROTOCOL = 1;
+const WIN = process.platform === 'win32';
+// how to start a resident when none answers (rewritten by `init --local` and installed binaries);
+// --prefix keeps npx from running a graph-indexer that the repository ships in its own node_modules
+const DAEMON = ['npx', '-y', '--prefix', os.homedir(), 'graph-indexer@3', 'daemon'];
+// OpenCode tool ids → the tool names graph-indexer's hook understands
+const TOOLS = { read: 'Read', grep: 'Grep', bash: 'Bash', edit: 'Edit', write: 'Write' };
+
+function findRepoRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, '.git'))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.resolve(start);
+        dir = parent;
+    }
+}
+
+// must match socketPath() in graph-indexer's src/cli/resident.mjs
+function socketPath(root) {
+    const abs = path.resolve(root);
+    const hash = crypto.createHash('sha256').update(abs).digest('hex').slice(0, 16);
+    if (WIN) return `\\\\.\\pipe\\graph-indexer-${hash}`;
+    const inRepo = path.join(abs, '.graph-indexer', 'resident.sock');
+    if (Buffer.byteLength(inRepo) <= 100) return inRepo;
+    return path.join(os.tmpdir(), `graph-indexer-${process.getuid?.() ?? 'user'}`, `${hash}.sock`);
+}
+
+function trusted(file, root) {
+    if (WIN) return true;
+    const mine = (st) => !process.getuid || st.uid === process.getuid();
+    try {
+        const sock = fs.lstatSync(file), dir = fs.lstatSync(path.dirname(file));
+        const inRepo = path.dirname(file) === path.join(path.resolve(root), '.graph-indexer');
+        // the socket and its directory are ours, not links or listeners planted by the repository or another user
+        return sock.isSocket() && mine(sock) && dir.isDirectory() && mine(dir) && (inRepo || (dir.mode & 0o077) === 0);
+    } catch { return false; }
+}
+
+function ask(root, request, totalMs) {
+    const file = socketPath(root);
+    if (!trusted(file, root)) return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let done = false, buf = '';
+        const sock = net.createConnection(file);
+        const finish = (v) => { if (!done) { done = true; clearTimeout(timer); sock.destroy(); resolve(v); } };
+        const timer = setTimeout(() => finish(null), totalMs);
+        sock.setEncoding('utf8');
+        sock.on('connect', () => sock.write(JSON.stringify({ v: PROTOCOL, any: true, ...request }) + '\n'));
+        sock.on('data', (d) => {
+            buf += d;
+            const i = buf.indexOf('\n');
+            if (i < 0) return;
+            let r = null;
+            try { r = JSON.parse(buf.slice(0, i)); } catch { /* garbled */ }
+            finish(r?.ok ? r : null);
+        });
+        sock.on('error', () => finish(null));
+        sock.on('close', () => finish(null));
+    });
+}
+
+/** The Claude Code-style PostToolUse payload for an OpenCode tool call, or null. */
+function hookPayload(input, output, root) {
+    const name = TOOLS[input?.tool];
+    if (!name) return null;
+    const a = input.args ?? {};
+    let text = typeof output?.output === 'string' ? output.output : '';
+    if (name === 'Grep' && /^No files found/.test(text.trim())) text = ''; // a search that found nothing
+    const toolInput = name === 'Read' ? { file_path: a.filePath, offset: a.offset, limit: a.limit }
+        : name === 'Grep' ? { pattern: a.pattern, path: a.path }
+            : name === 'Bash' ? { command: a.command }
+                : { file_path: a.filePath };
+    return { session_id: `opencode-${input.sessionID ?? 'default'}`, cwd: root, hook_event_name: 'PostToolUse', tool_name: name, tool_input: toolInput, tool_response: text };
+}
+
+export const GraphIndexer = async ({ directory, worktree } = {}) => {
+    // Kilo Code may load the plugin from both .kilo/ and .opencode/: register once
+    if (globalThis.__graphIndexerPlugin) return {};
+    globalThis.__graphIndexerPlugin = true;
+    const root = findRepoRoot(worktree || directory || process.cwd());
+    let started = false;
+    return {
+        'tool.execute.after': async (input, output) => {
+            try {
+                const payload = hookPayload(input, output, root);
+                if (!payload) return;
+                const reply = await ask(root, { op: 'hook', event: 'post-tool', input: payload }, 2000);
+                if (!reply) {
+                    if (!started) {
+                        started = true;
+                        // cmd.exe (npx.cmd needs a shell on Windows) would run `&`, `|`… in a path: quote
+                        // every argument, and give up on one that a quote cannot hold
+                        const args = [...DAEMON.slice(1), '--repo', root];
+                        if (WIN && args.some(a => /["%\r\n]/.test(a))) return;
+                        const child = spawn(DAEMON[0], WIN ? args.map(a => `"${a}"`) : args, { detached: true, stdio: 'ignore', windowsHide: true, shell: WIN });
+                        child.on('error', () => { /* optional */ });
+                        child.unref();
+                    }
+                    return;
+                }
+                const text = reply.out ? JSON.parse(reply.out)?.hookSpecificOutput?.additionalContext : null;
+                if (text) output.output = `${output.output ?? ''}\n\n${text}`;
+            } catch { /* fail open: the tool's own output is untouched */ }
+        },
+    };
+};
+
+// for tests only; a property, not an export, so OpenCode does not call it as a plugin
+GraphIndexer.hookPayload = hookPayload;

package/package.json

@@ -1,126 +1,56 @@
 {
     "name": "graph-indexer",
-    "version": "2.1.1",
-    "description": "Air-gapped code-retrieval MCP server: AST chunking, hybrid RRF search and cross-language call graph, with an optional zero-dependency SQLite backend for monorepo scale and optional local-LLM semantic enrichment.",
+    "version": "3.0.1",
+    "description": "Live code graph and search for AI coding agents over MCP: tree-sitter (WASM) symbols, scope/import/type-aware references, call graphs, change impact and hybrid search — local, zero-dependency, no native builds.",
     "type": "module",
-    "main": "engine/memory.mjs",
+    "main": "src/query/intel.mjs",
     "exports": {
-        ".": "./engine/memory.mjs"
+        ".": "./src/query/intel.mjs",
+        "./mcp": "./src/mcp/server.mjs"
     },
     "bin": {
-        "graph-indexer": "init.mjs",
-        "idx-index": "indexer.mjs",
-        "idx-watch": "watch-daemon.mjs",
-        "idx-daemon": "daemon-ctl.mjs",
-        "idx-mcp": "mcp-server.mjs"
+        "graph-indexer": "bin/graph-indexer.mjs",
+        "idx-mcp": "bin/graph-indexer.mjs",
+        "idx-index": "bin/graph-indexer.mjs"
     },
     "files": [
-        "*.mjs",
-        "engine/",
-        "mcp/",
-        "parse/",
-        "embedders/setup-mlx.mjs",
-        "embedders/python/mlx_embed_server.py",
-        "embedders/python/requirements-mlx.txt",
-        "!embedders/python/test_servers.mjs",
-        "prompts/",
+        "bin/",
+        "src/",
+        "integrations/",
+        "vendor/",
         "README.md",
         "CHANGELOG.md",
         "SECURITY.md",
         "TRADEMARK.md",
         "LICENSE"
     ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/MaquinaTech/graph-indexer.git"
-    },
     "scripts": {
-        "start": "node ./mcp-server.mjs",
-        "test": "node test/run.mjs",
-        "test:unit": "node test/unit.mjs",
-        "test:sqlite": "node test/sqlite.mjs",
-        "test:enrich": "node test/enrichment.mjs",
-        "test:mcp": "node test/mcp.mjs",
-        "test:scale": "node test/scale.mjs",
-        "test:callgraph": "node test/callgraph.mjs",
-        "test:edges": "node test/edges.mjs",
-        "test:references": "node test/references.mjs",
-        "test:routes": "node test/routes.mjs",
-        "test:jsonout": "node test/json-output.mjs",
-        "test:gitsignals": "node test/git-signals.mjs",
-        "test:security": "node test/security.mjs",
-        "test:seal": "node test/seal.mjs",
-        "test:taint": "node test/taint.mjs",
-        "test:scip": "node test/scip.mjs",
-        "test:ranker": "node test/ranker.mjs",
-        "test:sparse": "node test/sparse.mjs",
-        "test:colbert": "node test/colbert.mjs",
-        "test:embed": "node test/embeddings.mjs",
-        "test:languages": "node test/languages.mjs",
-        "test:all": "node test/unit.mjs && node test/sqlite.mjs && node test/enrichment.mjs && node test/mcp.mjs && node test/scale.mjs && node test/callgraph.mjs && node test/edges.mjs && node test/references.mjs && node test/routes.mjs && node test/json-output.mjs && node test/git-signals.mjs && node test/security.mjs && node test/seal.mjs && node test/taint.mjs && node test/scip.mjs && node test/ranker.mjs && node test/sparse.mjs && node test/colbert.mjs && node test/embeddings.mjs && node test/languages.mjs",
-        "test:eval": "node test/evaluate.mjs",
-        "test:eval:embeddings": "OLLAMA_HOST=http://localhost:11434 node test/evaluate.mjs --embeddings",
-        "test:setup": "node test/setup.mjs",
-        "test:run": "node test/run.mjs",
-        "test:embeddings": "OLLAMA_HOST=http://localhost:11434 node test/run-embeddings.mjs",
-        "test:embeddings:skip": "OLLAMA_HOST=http://localhost:11434 node test/run-embeddings.mjs --skip-indexing",
-        "test:suite": "node test/run.mjs --suite",
-        "test:json": "node test/run.mjs --json",
-        "test:reset": "rm -rf test/fixtures && node test/setup.mjs",
-        "embed:setup:mlx": "node embedders/setup-mlx.mjs",
-        "embed:setup:local": "npm install @huggingface/transformers",
-        "mcp:index": "idx-index --repo .",
-        "mcp:index:sqlite": "node indexer.mjs --repo . --use-sqlite",
-        "mcp:index:enriched": "node indexer.mjs --repo . --enrichment",
-        "mcp:watch": "node watch-daemon.mjs",
-        "mcp:start": "idx-mcp",
-        "mcp:daemon": "node daemon-ctl.mjs status",
-        "mcp:daemon:start": "node daemon-ctl.mjs start",
-        "mcp:daemon:stop": "node daemon-ctl.mjs stop",
-        "mcp:daemon:restart": "node daemon-ctl.mjs restart",
-        "mcp:daemon:status": "node daemon-ctl.mjs status",
-        "mcp:daemon:logs": "node daemon-ctl.mjs logs"
+        "test": "node --test test/*.test.mjs",
+        "bench": "node bench/eval-search.mjs",
+        "bench:graph": "node bench/eval-graph.mjs",
+        "bench:localize": "node bench/eval-localize.mjs",
+        "fixtures": "node bench/fixtures.mjs",
+        "start": "node bin/graph-indexer.mjs serve",
+        "index": "node bin/graph-indexer.mjs index"
     },
-    "dependencies": {
-        "@modelcontextprotocol/sdk": "1.29.0",
-        "chokidar": "5.0.0",
-        "ignore": "5.3.2",
-        "tree-sitter": "0.21.1",
-        "zod": "^3.25.76"
-    },
-    "devDependencies": {
-        "@huggingface/transformers": "3.8.1",
-        "hnswlib-node": "3.0.0",
-        "tree-sitter-bash": "0.23.3",
-        "tree-sitter-c": "0.21.4",
-        "tree-sitter-c-sharp": "0.21.3",
-        "tree-sitter-css": "0.21.1",
-        "tree-sitter-go": "0.21.0",
-        "tree-sitter-java": "0.21.0",
-        "tree-sitter-javascript": "0.21.4",
-        "tree-sitter-kotlin": "0.3.8",
-        "tree-sitter-php": "0.23.1",
-        "tree-sitter-python": "0.21.0",
-        "tree-sitter-ruby": "0.23.1",
-        "tree-sitter-rust": "0.21.0",
-        "tree-sitter-scss": "1.0.0",
-        "tree-sitter-swift": "0.5.0",
-        "tree-sitter-typescript": "0.21.2"
+    "engines": {
+        "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
     },
-    "overrides": {
-        "sharp": "^0.35.4"
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/MaquinaTech/graph-indexer.git"
     },
     "keywords": [
         "mcp",
         "model-context-protocol",
-        "indexer",
-        "ast",
-        "tree-sitter",
-        "rag",
-        "hybrid-search",
-        "rrf",
+        "code-search",
         "call-graph",
-        "ollama"
+        "tree-sitter",
+        "code-intelligence",
+        "ai-agents",
+        "claude-code",
+        "find-references",
+        "impact-analysis"
     ],
     "author": {
         "name": "MaquinaTech",
@@ -128,18 +58,11 @@
         "email": "nicolopezdelerma@gmail.com"
     },
     "license": "MIT",
-    "engines": {
-        "node": ">=18.0.0"
-    },
     "bugs": {
         "url": "https://github.com/MaquinaTech/graph-indexer/issues"
     },
     "homepage": "https://github.com/MaquinaTech/graph-indexer",
-    "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/MaquinaTech"
-    },
     "publishConfig": {
         "access": "public"
     }
-}
+}

package/src/cli/helper.mjs

@@ -0,0 +1,67 @@
+/**
+ * The structural helper: a sub-agent on a small model that answers structural questions — call
+ * sites, callers of callers, subclasses and implementations, what a change affects — from the
+ * index, and replies with the answer alone. The main agent delegates the question and gets back a
+ * path:line list instead of the searches and reads behind it, and the lookup runs on a model that
+ * costs a fraction per token. `init` writes it for Claude Code (.claude/agents/) and the Claude Code
+ * plugin ships the same file (integrations/claude-code/agents/).
+ */
+
+export const HELPER_NAME = 'code-structure';
+
+// what the main agent sees when it decides whether to delegate
+const DESCRIPTION = 'Exact answers to structural questions about this repository\'s code, from graph-indexer\'s index, on a small fast model: every call site of a function or method (told apart from same-name methods of other classes), callers of callers, classes that extend or implement a type, and what a change would affect with the tests that cover it. Give it the symbol (Class.method, with its file when you know it) and the scope (directories, whether tests count, how many levels); it replies with path:line lists and says whether they are complete. Delegate these instead of grepping for names and reading files yourself.';
+
+/** How to answer each kind of question, with the MCP tools or, given its path, the CLI. */
+function howTo(cli) {
+    if (!cli) return [
+        '- Call sites or other uses of a function, method or class: `find_references` on it (`Class.method`, or `path:Name` when the name is ambiguous), with kind `call` for calls only, `include_tests: false` when tests are excluded and `path` for one directory. It says when the list is complete.',
+        '- Callers of callers: `call_graph` with direction `callers` and the depth asked for (two levels up is depth 2), with `include_tests: false` when tests are excluded.',
+        '- Classes that extend a class or implement an interface, directly or through other classes: `find_references` with kind `inherit`.',
+        '- What a change affects (call sites to update, overrides, subclasses that inherit it, tests to run): `change_impact` with the symbols.',
+        '- A definition or a signature: `read_code` with its name.',
+    ];
+    return [
+        `- Call sites or other uses of a function, method or class: \`${cli} refs <Class.method>\` (or \`path:Name\` when the name is ambiguous), with \`--kind call\` for calls only, \`--no-tests\` when tests are excluded and \`--path DIR\` for one directory. It says when the list is complete.`,
+        `- Callers of callers: \`${cli} callgraph <Class.method> --direction callers --depth N\` with the depth asked for (two levels up is 2), and \`--no-tests\` when tests are excluded.`,
+        `- Classes that extend a class or implement an interface, directly or through other classes: \`${cli} refs <Name> --kind inherit\`.`,
+        `- What a change affects (call sites to update, overrides, subclasses that inherit it, tests to run): \`${cli} impact --symbols A,B\`.`,
+        `- A definition or a signature: \`${cli} read <name>\`.`,
+    ];
+}
+
+/**
+ * The helper's instructions (its system prompt). `cli` is the path of the graph-indexer executable
+ * when the helper reaches the index through a shell instead of the MCP server.
+ */
+export function helperInstructions({ cli = null } = {}) {
+    return [
+        `You answer structural questions about the code in this repository — where something is used, who calls it, what extends or implements it, what a change would affect — exactly and briefly, from graph-indexer's index${cli ? ` (run it through the shell with the executable \`${cli}\`)` : ' (the graph-indexer tools)'}. The index binds every reference through scopes, imports and receiver types, so methods that only share a name are kept apart, and it re-syncs with the files before every answer.`,
+        '',
+        'How to answer',
+        ...howTo(cli),
+        '- Answer from these results. Read code or search text only to settle what they report as unresolved or incomplete (a call through a name built at run time, a receiver of unknown type), not to redo a list they give as complete.',
+        '- Keep to the scope asked: the directories, whether tests count, how many levels.',
+        '',
+        'Reply',
+        '- When the request gives an answer format, follow it exactly.',
+        '- Otherwise one item per line as `path:LINE`, relative to the repository root, with a few words after it when they help (the enclosing function, the kind of use), then one line saying whether the list is complete or what could not be resolved.',
+        '- Nothing else: no account of how you found it. You do not change files.',
+    ].join('\n');
+}
+
+/**
+ * The Claude Code sub-agent file. It inherits the session's tools (so the graph-indexer MCP tools
+ * whatever the server is called: project .mcp.json or plugin) minus the editing ones.
+ */
+export function claudeAgentFile() {
+    return `---
+name: ${HELPER_NAME}
+description: ${JSON.stringify(DESCRIPTION)}
+model: haiku
+disallowedTools: Edit, Write, MultiEdit, NotebookEdit
+omitClaudeMd: true
+---
+${helperInstructions()}
+`;
+}