@sdsrs/code-graph 0.37.0 → 0.39.0

package/README.md

@@ -281,6 +281,8 @@ All tools are also available as CLI subcommands for shell scripts, hooks, and te
 
 Common options: `--json` (JSON output), `--compact` (compact output), `--limit N`, `--depth N`, `--file <path>`.
 
+As of **v0.37.0** the CLI is [clap](https://docs.rs/clap)-based: **every subcommand has `--help`** for its full flag list (`code-graph-mcp <command> --help`), value flags accept both `--flag value` and `--flag=value`, and unknown flags or malformed arguments fail fast with a clear error and a non-zero exit code (`2`) instead of being silently ignored. For example, `trace` hides downstream middleware with `--no-middleware` (shown by default), and `snapshot` is a `create`/`inspect` subcommand pair.
+
 ## Plugin Slash Commands
 
 Available when installed as a Claude Code plugin:

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.37.0",
+  "version": "0.39.0",
   "keywords": [
     "code-graph",
     "ast",

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

@@ -29,6 +29,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { cgTmpDir } = require('./tmp-dir');
+const { recordRecommendation } = require('./recommendation-log');
 
 // --- Pure logic (testable) ---
 
@@ -194,6 +195,7 @@ function runMain() {
     // ignored by Claude Code — the grep ran anyway. The hookSpecificOutput form
     // is the documented modern path. Exit 0 — this is a routing decision, not
     // a hook failure (exit 2 would mark the tool call as "hook errored").
+    recordRecommendation(cwd, { hook: 'grep', action: 'deny' });
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
@@ -204,6 +206,7 @@ function runMain() {
     return;
   }
 
+  recordRecommendation(cwd, { hook: 'grep', action: 'hint' });
   process.stdout.write(buildHint() + '\n');
 }
 

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

@@ -26,6 +26,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { cgTmpDir } = require('./tmp-dir');
+const { recordRecommendation } = require('./recommendation-log');
 
 // --- Configuration ---
 
@@ -158,7 +159,10 @@ function runMain() {
     fired = true;
   }
   saveState(cwd, state);
-  if (fired) process.stdout.write(buildHint(dir) + '\n');
+  if (fired) {
+    recordRecommendation(cwd, { hook: 'read', action: 'hint' });
+    process.stdout.write(buildHint(dir) + '\n');
+  }
 }
 
 if (require.main === module) {

package/claude-plugin/scripts/recommendation-log.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+// Real-session conversion metric (JS counterpart to the Rust MCP usage.jsonl).
+//
+// The PreToolUse hooks (pre-grep-guide / pre-read-guide) RECOMMEND a code-graph
+// tool when Claude reaches for raw grep / fans out Reads. This module records
+// each emitted recommendation so `code-graph-mcp stats` can compute the *field*
+// conversion rate (recommend → actual cg tool call) — the metric the synthetic
+// routing_bench oracle can't see (memory: self-dogfood-blindspot / feedback_routing_bench).
+//
+// Bounded + best-effort by construction:
+//   - appends to <cwd>/.code-graph/recommendations.jsonl and NEVER creates the
+//     `.code-graph` dir — so a non-project / tmp cwd (no index) leaves zero
+//     footprint, mirroring each hook's existing `.code-graph/index.db` guard.
+//   - swallows every error: telemetry must never break or delay a tool call.
+const fs = require('fs');
+const path = require('path');
+
+const REC_FILE = 'recommendations.jsonl';
+
+/**
+ * Append one recommendation event to <cwd>/.code-graph/recommendations.jsonl.
+ * @param {string} cwd        project root (the hook's process.cwd())
+ * @param {object} event      e.g. { hook: 'grep', action: 'deny' }
+ * @returns {boolean} true if a line was written
+ */
+function recordRecommendation(cwd, event = {}) {
+  try {
+    const dir = path.join(cwd, '.code-graph');
+    // Append-only: do NOT create .code-graph. Its absence means "not an indexed
+    // project" — recording there would pollute non-project cwds.
+    if (!fs.existsSync(dir)) return false;
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) + '\n';
+    fs.appendFileSync(path.join(dir, REC_FILE), line);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { recordRecommendation, REC_FILE };

package/claude-plugin/scripts/recommendation-log.test.js

@@ -0,0 +1,44 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { recordRecommendation, REC_FILE } = require('./recommendation-log');
+
+function tmpProject(t, withCodeGraph) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-rec-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  if (withCodeGraph) fs.mkdirSync(path.join(dir, '.code-graph'));
+  return dir;
+}
+
+test('recordRecommendation appends a JSON line with ts + fields', (t) => {
+  const cwd = tmpProject(t, true);
+  assert.equal(recordRecommendation(cwd, { hook: 'grep', action: 'deny' }), true);
+  const content = fs.readFileSync(path.join(cwd, '.code-graph', REC_FILE), 'utf8');
+  const lines = content.trim().split('\n');
+  assert.equal(lines.length, 1);
+  const rec = JSON.parse(lines[0]);
+  assert.equal(rec.hook, 'grep');
+  assert.equal(rec.action, 'deny');
+  assert.ok(typeof rec.ts === 'string' && rec.ts.length > 0, 'ts should be a timestamp');
+});
+
+test('recordRecommendation is a no-op (no dir created) when .code-graph absent', (t) => {
+  const cwd = tmpProject(t, false);
+  assert.equal(recordRecommendation(cwd, { hook: 'grep', action: 'hint' }), false);
+  // Must NOT create the dir or file — zero footprint in non-project cwd.
+  assert.equal(fs.existsSync(path.join(cwd, '.code-graph')), false);
+});
+
+test('recordRecommendation appends across calls (one line each)', (t) => {
+  const cwd = tmpProject(t, true);
+  recordRecommendation(cwd, { hook: 'grep', action: 'hint' });
+  recordRecommendation(cwd, { hook: 'read', action: 'hint' });
+  recordRecommendation(cwd, { hook: 'grep', action: 'deny' });
+  const lines = fs.readFileSync(path.join(cwd, '.code-graph', REC_FILE), 'utf8').trim().split('\n');
+  assert.equal(lines.length, 3);
+  const hooks = lines.map((l) => JSON.parse(l).hook);
+  assert.deepEqual(hooks, ['grep', 'read', 'grep']);
+});

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

@@ -30,6 +30,16 @@ function computeQuietHooks({ env = {} } = {}) {
   return true;
 }
 
+// SessionStart project-map injection gate. Beyond the (already default-quiet)
+// verbose opt-in, the map is now also ADOPTED-ONLY: cross-project measurement
+// (memory cross-project-interference) found the ≈2 KB dump is zero-referenced
+// in projects the user hasn't adopted into their MEMORY.md workflow, so it only
+// earns its standing-context cost for adopted projects. Unadopted projects get
+// no map even under CODE_GRAPH_VERBOSE_HOOKS / legacy QUIET_HOOKS=0.
+function shouldInjectMap({ available, quietHooks, adopted } = {}) {
+  return !!(available && !quietHooks && adopted);
+}
+
 function launchBackgroundAutoUpdate(spawnFn = spawn, env = process.env) {
   try {
     const child = spawnFn(process.execPath, [path.join(__dirname, 'auto-update.js'), 'check', '--silent'], {
@@ -316,11 +326,14 @@ function runSessionInit() {
 
   // quietHooks: default quiet (project_map injection duplicates MEMORY.md +
   // on-demand tool). CODE_GRAPH_VERBOSE_HOOKS=1 to opt in to the dump;
-  // legacy CODE_GRAPH_QUIET_HOOKS=0/1 still force the old behavior.
+  // legacy CODE_GRAPH_QUIET_HOOKS=0/1 still force the old behavior. The opt-in
+  // dump is further gated to adopted projects (shouldInjectMap).
   const adopted = isAdopted();
   const quietHooks = computeQuietHooks({ env: process.env });
 
-  const mapInjected = binaryCheck.available && !quietHooks ? injectProjectMap() : false;
+  const mapInjected = shouldInjectMap({ available: binaryCheck.available, quietHooks, adopted })
+    ? injectProjectMap()
+    : false;
   const consistencyIssues = binaryCheck.available
     ? consistencyCheck(binaryCheck.binary)
     : [];
@@ -369,6 +382,7 @@ module.exports = {
   consistencyCheck,
   runSessionInit,
   computeQuietHooks,
+  shouldInjectMap,
 };
 
 if (require.main === module) {

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

@@ -4,7 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const path = require('path');
 
-const { launchBackgroundAutoUpdate, syncLifecycleConfig, ensureIndexFresh, verifyBinary, computeQuietHooks } = require('./session-init');
+const { launchBackgroundAutoUpdate, syncLifecycleConfig, ensureIndexFresh, verifyBinary, computeQuietHooks, shouldInjectMap } = require('./session-init');
 
 test('syncLifecycleConfig is exported as a callable helper', () => {
   assert.equal(typeof syncLifecycleConfig, 'function');
@@ -147,6 +147,20 @@ test('computeQuietHooks: legacy `adopted` param is ignored under new default', (
   assert.equal(computeQuietHooks({ adopted: false, env: {} }), true);
 });
 
+test('shouldInjectMap: only injects when available + not-quiet + adopted', () => {
+  // The single positive case: opted into verbose AND adopted.
+  assert.equal(shouldInjectMap({ available: true, quietHooks: false, adopted: true }), true);
+  // Adopted-only gate: verbose but unadopted → no injection (the zero-referenced
+  // case cross-project-interference flagged).
+  assert.equal(shouldInjectMap({ available: true, quietHooks: false, adopted: false }), false);
+  // Quiet default suppresses regardless of adoption.
+  assert.equal(shouldInjectMap({ available: true, quietHooks: true, adopted: true }), false);
+  // No binary → nothing to inject.
+  assert.equal(shouldInjectMap({ available: false, quietHooks: false, adopted: true }), false);
+  // Missing args default to falsey → no injection.
+  assert.equal(shouldInjectMap(), false);
+});
+
 test('consistencyCheck returns version-mismatch when versions differ', (t) => {
   const os = require('os');
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-'));

package/package.json

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