sigmap 7.4.0 → 7.6.0

package/CHANGELOG.md

@@ -10,6 +10,24 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.6.0] — 2026-06-17
+
+Minor release — the grounding benchmark (the offline GATE for grounded codegen).
+
+### Added
+- **Grounding benchmark — `npm run benchmark:grounding` (#294):** a deterministic, offline callee-grounding ablation that measures how much ground truth SigMap actually gives an agent. For each corpus repo: `coverage = grounded / universe`, where universe is every symbol defined in the source and grounded is the subset SigMap surfaces in its index (resolvable by `get_callee_signatures`); baseline is 0 (no SigMap → guess every reference). `scripts/run-hallucination-benchmark.mjs` prints per-repo + aggregate coverage; `--save` writes `benchmarks/reports/hallucination.json`; `--gate <pct>` exits non-zero below a threshold. It's an honest *ground-truth-availability proxy*, not a measured LLM hallucination rate (the LLM A/B ablation is a documented follow-up needing an API key). No LLM, no network — runs in CI.
+
+---
+
+## [7.5.0] — 2026-06-17
+
+Minor release — read-time self-heal completes Layer 1 freshness.
+
+### Added
+- **Read-time self-heal — live index without agent hooks (#290):** the v7.4.0 write hooks kept the index fresh only if the agent called them; now `search_signatures` / `get_callee_signatures` reconcile the index with the source tree *on read*, so on-disk edits show up even when no hook fired — closing that single point of failure. New `src/cache/freshen.js` re-extracts files modified since the last `generate` (bounded to actual session edits, not the whole tree), persists to the sig-cache (which `buildSigIndex` merges), and is throttled per repo. Deletions stay the job of `sigmap_notify_file_deleted` (a cache entry may be a notify overlay for a not-yet-on-disk file). Verified end-to-end in the standalone bundle.
+
+---
+
 ## [7.4.0] — 2026-06-17
 
 Minor release — live-index write hooks (grounded codegen, Layer 1).

package/gen-context.js

@@ -20,6 +20,132 @@ function __require(key) {
 }
 
 
+// ── ./src/cache/freshen ──
+__factories["./src/cache/freshen"] = function(module, exports) {
+  
+  /**
+   * Read-time self-heal (IMPL.md Layer 1, "safety net" tier).
+   *
+   * Keeps the sig-cache in line with the current source tree so the index reflects
+   * on-disk reality even when no write hook was called. Re-extracts files modified
+   * since the context file was generated (bounded to actual session edits, not the
+   * whole tree), drops cache entries for deleted files, and persists. buildSigIndex
+   * already merges the cache, so the next read is fresh.
+   *
+   * Throttled per cwd. Skips entirely when there is no generated index to heal
+   * (a cold repo should run `generate` or use the notify hooks).
+   *
+   * Zero-dependency, bundle-safe (fs + dispatch + sig-cache).
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+  const { loadCache, saveCache, getChangedFiles } = __require('./src/cache/sig-cache');
+  const { extractFile, langFor } = __require('./src/extractors/dispatch');
+
+  const DEFAULT_SRC_DIRS = ['src', 'app', 'lib', 'packages', 'services', 'api'];
+  const DEFAULT_EXCLUDE = [
+    'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+    '.next', 'coverage', 'target', 'vendor', '.context',
+  ];
+  const CONTEXT_PATHS = [
+    ['.github', 'copilot-instructions.md'],
+    ['CLAUDE.md'], ['AGENTS.md'], ['.github', 'context-cold.md'],
+  ];
+  const THROTTLE_MS = 1500;
+  const _lastRun = new Map();
+
+  function _readConfig(cwd) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(cwd, 'gen-context.config.json'), 'utf8'));
+      return cfg && typeof cfg === 'object' ? cfg : {};
+    } catch (_) { return {}; }
+  }
+
+  function _pkgVersion(cwd) {
+    try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
+    catch (_) { return '0.0.0'; }
+  }
+
+  /** Newest mtime among existing generated context files, or 0 if none. */
+  function _contextMtime(cwd) {
+    let newest = 0;
+    for (const parts of CONTEXT_PATHS) {
+      try { newest = Math.max(newest, fs.statSync(path.join(cwd, ...parts)).mtimeMs); } catch (_) {}
+    }
+    return newest;
+  }
+
+  function _walk(dir, exclude, out, depth, maxDepth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of entries) {
+      if (exclude.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) _walk(full, exclude, out, depth + 1, maxDepth);
+      else if (e.isFile() && langFor(e.name)) out.push(full);
+    }
+  }
+
+  /**
+   * Re-extract source files changed since the last generate; drop deleted files.
+   * @param {string} cwd
+   * @param {{force?:boolean, now?:number}} [opts]
+   * @returns {number} cache entries touched
+   */
+  function freshen(cwd, opts = {}) {
+    const now = opts.now != null ? opts.now : Date.now();
+    if (!opts.force) {
+      if (now - (_lastRun.get(cwd) || 0) < THROTTLE_MS) return 0;
+    }
+    _lastRun.set(cwd, now);
+
+    try {
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      const ctxMtime = _contextMtime(cwd);
+      // Nothing to heal: no generated context AND no live cache overlay.
+      if (ctxMtime === 0 && cache.size === 0) return 0;
+
+      const cfg = _readConfig(cwd);
+      const srcDirs = Array.isArray(cfg.srcDirs) && cfg.srcDirs.length ? cfg.srcDirs : DEFAULT_SRC_DIRS;
+      const exclude = new Set([...DEFAULT_EXCLUDE, ...(Array.isArray(cfg.exclude) ? cfg.exclude : [])]);
+      const maxDepth = Number.isFinite(cfg.maxDepth) ? cfg.maxDepth : 8;
+
+      const files = [];
+      for (const d of srcDirs) {
+        const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+        if (fs.existsSync(abs)) _walk(abs, exclude, files, 0, maxDepth);
+      }
+
+      // Candidates = files modified since the context was generated, or not yet cached.
+      const candidates = files.filter((f) => {
+        try { return fs.statSync(f).mtimeMs > ctxMtime || !cache.has(f); } catch (_) { return false; }
+      });
+      const { changed } = getChangedFiles(candidates, cache);
+
+      let touched = 0;
+      for (const f of changed) {
+        try {
+          const sigs = extractFile(f, fs.readFileSync(f, 'utf8'));
+          cache.set(f, { mtime: fs.statSync(f).mtimeMs, sigs });
+          touched++;
+        } catch (_) {}
+      }
+      // Note: deletions are NOT swept here — a cache entry may be a `notify`
+      // overlay for a file not yet on disk. Explicit removal is `notify_file_deleted`.
+
+      if (touched > 0) saveCache(cwd, version, cache);
+      return touched;
+    } catch (_) {
+      return 0;
+    }
+  }
+
+  module.exports = { freshen };
+  
+};
 // ── ./src/extractors/dispatch ──
 __factories["./src/extractors/dispatch"] = function(module, exports) {
   
@@ -5717,6 +5843,7 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
 
     const query = args.query.toLowerCase();
     try {
+      try { __require('./src/cache/freshen').freshen(cwd); } catch (_) {}
       const { buildSigIndex } = __require('./src/retrieval/ranker');
       const index = buildSigIndex(cwd);
       if (index.size === 0) {
@@ -6204,6 +6331,7 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     }
 
     try {
+      try { __require('./src/cache/freshen').freshen(cwd); } catch (_) {}
       const { buildSigIndex } = __require('./src/retrieval/ranker');
       const { buildSymbolCandidates, closestMatch, formatSuggestion } = __require('./src/verify/closest-match');
       const index = buildSigIndex(cwd);
@@ -6498,7 +6626,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.4.0',
+    version: '7.6.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -12176,7 +12304,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.4.0';
+const VERSION = '7.6.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {

package/llms-full.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.4.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.6.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 

package/llms.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.4.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.6.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "7.4.0",
+  "version": "7.6.0",
   "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
   "main": "packages/core/index.js",
   "exports": {
@@ -38,7 +38,8 @@
     "version:sync": "node scripts/sync-versions.mjs",
     "generate:llms": "node scripts/generate-llms.mjs",
     "validate:llms": "node scripts/validate-llms.mjs",
-    "prepublishOnly": "node scripts/check-bundle.mjs && node scripts/check-version-meta.mjs && node scripts/generate-llms.mjs"
+    "prepublishOnly": "node scripts/check-bundle.mjs && node scripts/check-version-meta.mjs && node scripts/generate-llms.mjs",
+    "benchmark:grounding": "node scripts/run-hallucination-benchmark.mjs"
   },
   "files": [
     "gen-context.js",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "7.4.0",
+  "version": "7.6.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "7.4.0",
+  "version": "7.6.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/cache/freshen.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Read-time self-heal (IMPL.md Layer 1, "safety net" tier).
+ *
+ * Keeps the sig-cache in line with the current source tree so the index reflects
+ * on-disk reality even when no write hook was called. Re-extracts files modified
+ * since the context file was generated (bounded to actual session edits, not the
+ * whole tree), drops cache entries for deleted files, and persists. buildSigIndex
+ * already merges the cache, so the next read is fresh.
+ *
+ * Throttled per cwd. Skips entirely when there is no generated index to heal
+ * (a cold repo should run `generate` or use the notify hooks).
+ *
+ * Zero-dependency, bundle-safe (fs + dispatch + sig-cache).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { loadCache, saveCache, getChangedFiles } = require('./sig-cache');
+const { extractFile, langFor } = require('../extractors/dispatch');
+
+const DEFAULT_SRC_DIRS = ['src', 'app', 'lib', 'packages', 'services', 'api'];
+const DEFAULT_EXCLUDE = [
+  'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+  '.next', 'coverage', 'target', 'vendor', '.context',
+];
+const CONTEXT_PATHS = [
+  ['.github', 'copilot-instructions.md'],
+  ['CLAUDE.md'], ['AGENTS.md'], ['.github', 'context-cold.md'],
+];
+const THROTTLE_MS = 1500;
+const _lastRun = new Map();
+
+function _readConfig(cwd) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(cwd, 'gen-context.config.json'), 'utf8'));
+    return cfg && typeof cfg === 'object' ? cfg : {};
+  } catch (_) { return {}; }
+}
+
+function _pkgVersion(cwd) {
+  try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
+  catch (_) { return '0.0.0'; }
+}
+
+/** Newest mtime among existing generated context files, or 0 if none. */
+function _contextMtime(cwd) {
+  let newest = 0;
+  for (const parts of CONTEXT_PATHS) {
+    try { newest = Math.max(newest, fs.statSync(path.join(cwd, ...parts)).mtimeMs); } catch (_) {}
+  }
+  return newest;
+}
+
+function _walk(dir, exclude, out, depth, maxDepth) {
+  if (depth > maxDepth) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+  for (const e of entries) {
+    if (exclude.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) _walk(full, exclude, out, depth + 1, maxDepth);
+    else if (e.isFile() && langFor(e.name)) out.push(full);
+  }
+}
+
+/**
+ * Re-extract source files changed since the last generate; drop deleted files.
+ * @param {string} cwd
+ * @param {{force?:boolean, now?:number}} [opts]
+ * @returns {number} cache entries touched
+ */
+function freshen(cwd, opts = {}) {
+  const now = opts.now != null ? opts.now : Date.now();
+  if (!opts.force) {
+    if (now - (_lastRun.get(cwd) || 0) < THROTTLE_MS) return 0;
+  }
+  _lastRun.set(cwd, now);
+
+  try {
+    const version = _pkgVersion(cwd);
+    const cache = loadCache(cwd, version);
+    const ctxMtime = _contextMtime(cwd);
+    // Nothing to heal: no generated context AND no live cache overlay.
+    if (ctxMtime === 0 && cache.size === 0) return 0;
+
+    const cfg = _readConfig(cwd);
+    const srcDirs = Array.isArray(cfg.srcDirs) && cfg.srcDirs.length ? cfg.srcDirs : DEFAULT_SRC_DIRS;
+    const exclude = new Set([...DEFAULT_EXCLUDE, ...(Array.isArray(cfg.exclude) ? cfg.exclude : [])]);
+    const maxDepth = Number.isFinite(cfg.maxDepth) ? cfg.maxDepth : 8;
+
+    const files = [];
+    for (const d of srcDirs) {
+      const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+      if (fs.existsSync(abs)) _walk(abs, exclude, files, 0, maxDepth);
+    }
+
+    // Candidates = files modified since the context was generated, or not yet cached.
+    const candidates = files.filter((f) => {
+      try { return fs.statSync(f).mtimeMs > ctxMtime || !cache.has(f); } catch (_) { return false; }
+    });
+    const { changed } = getChangedFiles(candidates, cache);
+
+    let touched = 0;
+    for (const f of changed) {
+      try {
+        const sigs = extractFile(f, fs.readFileSync(f, 'utf8'));
+        cache.set(f, { mtime: fs.statSync(f).mtimeMs, sigs });
+        touched++;
+      } catch (_) {}
+    }
+    // Note: deletions are NOT swept here — a cache entry may be a `notify`
+    // overlay for a file not yet on disk. Explicit removal is `notify_file_deleted`.
+
+    if (touched > 0) saveCache(cwd, version, cache);
+    return touched;
+  } catch (_) {
+    return 0;
+  }
+}
+
+module.exports = { freshen };

package/src/mcp/handlers.js

@@ -72,6 +72,7 @@ function searchSignatures(args, cwd) {
 
   const query = args.query.toLowerCase();
   try {
+    try { require('../cache/freshen').freshen(cwd); } catch (_) {}
     const { buildSigIndex } = require('../retrieval/ranker');
     const index = buildSigIndex(cwd);
     if (index.size === 0) {
@@ -559,6 +560,7 @@ function getCalleeSignatures(args, cwd) {
   }
 
   try {
+    try { require('../cache/freshen').freshen(cwd); } catch (_) {}
     const { buildSigIndex } = require('../retrieval/ranker');
     const { buildSymbolCandidates, closestMatch, formatSuggestion } = require('../verify/closest-match');
     const index = buildSigIndex(cwd);

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '7.4.0',
+  version: '7.6.0',
   description: 'SigMap MCP server — code signatures on demand',
 };