@sdsrs/code-graph 0.5.1 → 0.5.3

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,6 +4,6 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.5.1",
+  "version": "0.5.3",
   "keywords": ["code-graph", "ast", "navigation", "mcp", "knowledge-graph"]
 }

package/claude-plugin/commands/rebuild.md

@@ -0,0 +1,6 @@
+---
+description: Force a full code-graph index rebuild
+---
+
+Call the `rebuild_index` tool with `{"confirm": true}` to rebuild the index from scratch.
+Report the number of files indexed and nodes created.

package/claude-plugin/commands/status.md

@@ -0,0 +1,8 @@
+---
+description: Show code-graph index status and embedding progress
+---
+
+Call the `get_index_status` tool and present the results:
+- files_count, nodes_count, edges_count
+- embedding_status and embedding_progress
+- model_available, is_watching

package/claude-plugin/hooks/hooks.json

@@ -1,5 +1,29 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "tool == \"Grep\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-search-guide.js\"",
+            "timeout": 2
+          }
+        ],
+        "description": "Suggest code-graph alternatives on first Grep call"
+      },
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-edit-guide.js\"",
+            "timeout": 2
+          }
+        ],
+        "description": "Remind about impact_analysis before first code modification"
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "tool == \"Write\" || tool == \"Edit\"",

package/claude-plugin/scripts/pre-edit-guide.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+// PreToolUse hook: On FIRST Edit/Write call per session window, remind Claude
+// to check impact_analysis before modifying functions. Fast and non-blocking.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const flag = path.join(os.tmpdir(), '.code-graph-edit-guided');
+const WINDOW_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+try {
+  const stat = fs.statSync(flag);
+  if (Date.now() - stat.mtimeMs < WINDOW_MS) process.exit(0);
+} catch { /* first time */ }
+
+fs.writeFileSync(flag, '');
+process.stdout.write(
+  '[code-graph] Before modifying functions, consider running impact_analysis(symbol_name) ' +
+  'to check blast radius (callers, affected routes, risk level).\n'
+);

package/claude-plugin/scripts/pre-search-guide.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+'use strict';
+// PreToolUse hook: On FIRST Grep call per session window, remind Claude
+// about code-graph alternatives. Runs fast (<10ms) and only outputs once.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const flag = path.join(os.tmpdir(), '.code-graph-search-guided');
+const WINDOW_MS = 2 * 60 * 60 * 1000; // 2 hours (approximate session window)
+
+try {
+  const stat = fs.statSync(flag);
+  if (Date.now() - stat.mtimeMs < WINDOW_MS) process.exit(0);
+} catch { /* flag doesn't exist — first time */ }
+
+fs.writeFileSync(flag, '');
+process.stdout.write(
+  '[code-graph] For code understanding, prefer code-graph tools over Grep:\n' +
+  '  project_map → full project architecture overview (call FIRST)\n' +
+  '  semantic_code_search → find code by concept (10x fewer tokens)\n' +
+  '  get_call_graph → who calls X / what X calls (13x fewer tokens)\n' +
+  '  module_overview → understand a module (20x fewer tokens)\n' +
+  'Use Grep only for exact strings, constants, or regex patterns.\n'
+);

package/claude-plugin/scripts/session-init.js

@@ -18,6 +18,14 @@ if (BIN) {
   } catch { /* timeout — silent */ }
 }
 
+// --- 1b. Suggest project_map as first action ---
+if (BIN) {
+  process.stdout.write(
+    '\n[code-graph] TIP: Call project_map first to get a full architecture overview ' +
+    '(modules, dependencies, hot functions, entry points) in one call.\n'
+  );
+}
+
 // --- 2. Scope conflict warning ---
 const conflict = checkScopeConflict();
 if (conflict) {

package/claude-plugin/skills/code-navigation.md

@@ -1,29 +1,30 @@
 ---
 name: code-navigation
-description: Code-graph tool selection guide. Use BEFORE any code exploration, bug fixing, feature implementation, or refactoring task to choose the most token-efficient tool (code-graph vs Grep/Read). Especially important before modifying functions — check impact_analysis first.
+description: PROACTIVE code-graph tool selection. Triggers automatically when you need to explore, understand, trace, or modify code. Use BEFORE choosing Grep/Read for code understanding tasks — code-graph tools save 10-40x tokens. Especially critical before modifying functions (impact_analysis first).
 ---
 
-# Code Navigation with Code Graph
+# Code Navigation Rules
 
-This project has a code-graph MCP server providing AST-level code intelligence.
-These tools return structured, token-efficient results. Use them as your
-PRIMARY navigation method for code understanding tasks.
+This project has a code-graph MCP server. These tools return structured, token-efficient results.
+**Use them as your PRIMARY navigation method. Fall back to Grep/Read only for exact-match or file editing.**
 
-| You want to... | Use this | NOT this |
-|---|---|---|
-| Find code by concept/meaning | `semantic_code_search` | Grep multiple patterns |
-| Understand who calls what | `get_call_graph` | Grep function name + Read files |
-| Trace HTTP request flow | `trace_http_chain` | Read router -> handler -> service |
-| Find route handler | `find_http_route` | Grep route string |
-| Get symbol signature + relations | `get_ast_node` | Read entire file |
-| Read specific code after search | `read_snippet` (by node_id) | Read entire file |
-| Analyze change impact | `impact_analysis` | Manual call graph tracing |
-| Understand a module | `module_overview` | Read all files in directory |
-| Map dependencies | `dependency_graph` | Grep import statements |
-| Find similar code | `find_similar_code` | Grep partial function names |
+## Decision Rules
 
-## Still use native tools for
-- Exact string match → Grep
-- File path lookup → Glob
-- Reading a specific known file → Read
-- Creating/editing files → Write/Edit
+| Task | MUST use | NOT this | Token savings |
+|---|---|---|---|
+| Who calls X / what X calls | `get_call_graph` | Grep + Read ×5 | 13x |
+| Understand module/directory | `module_overview` | Read multiple files | 20x |
+| **Before modifying a function** | `impact_analysis` FIRST | Just Edit | prevents breakage |
+| Find code by concept/meaning | `semantic_code_search` | Grep multiple patterns | 10x |
+| Trace HTTP request flow | `trace_http_chain` | Read router→handler→service | 10x |
+| One symbol's signature+relations | `get_ast_node` | Read entire file | 10x |
+| File import/export dependencies | `dependency_graph` | Grep import statements | 5x |
+| Find similar/duplicate code | `find_similar_code` | Grep partial names | 5x |
+| Read code of a search result | `get_ast_node` (by node_id) | Read entire file | 3x |
+
+## When to use native tools instead
+
+- **Grep**: exact string match, constants, regex patterns, literal text search
+- **Glob**: find files by name/path pattern
+- **Read**: specific file you already know and need to edit
+- **Write/Edit**: creating or modifying files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.5.1",
-    "@sdsrs/code-graph-linux-arm64": "0.5.1",
-    "@sdsrs/code-graph-darwin-x64": "0.5.1",
-    "@sdsrs/code-graph-darwin-arm64": "0.5.1",
-    "@sdsrs/code-graph-win32-x64": "0.5.1"
+    "@sdsrs/code-graph-linux-x64": "0.5.3",
+    "@sdsrs/code-graph-linux-arm64": "0.5.3",
+    "@sdsrs/code-graph-darwin-x64": "0.5.3",
+    "@sdsrs/code-graph-darwin-arm64": "0.5.3",
+    "@sdsrs/code-graph-win32-x64": "0.5.3"
   }
 }