sigmap 7.3.0 → 7.5.0

package/gen-context.js

@@ -20,6 +20,248 @@ 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) {
+  
+  /**
+   * Bundle-safe extractor dispatch.
+   *
+   * `packages/core`'s extract() resolves extractors via dynamic `require(path.join(…))`,
+   * which cannot run inside the standalone bundle (no filesystem `src/`). This module
+   * uses STATIC requires so the bundler rewrites them to `__require` and the extractors
+   * resolve from the bundled factories. Used by the live-index MCP write hooks.
+   */
+
+  const path = require('path');
+
+  // Static language → extractor map (every entry is a bundled factory).
+  const EXTRACTORS = {
+    typescript: __require('./src/extractors/typescript'),
+    typescript_react: __require('./src/extractors/typescript_react'),
+    javascript: __require('./src/extractors/javascript'),
+    python: __require('./src/extractors/python'),
+    java: __require('./src/extractors/java'),
+    kotlin: __require('./src/extractors/kotlin'),
+    go: __require('./src/extractors/go'),
+    rust: __require('./src/extractors/rust'),
+    csharp: __require('./src/extractors/csharp'),
+    cpp: __require('./src/extractors/cpp'),
+    ruby: __require('./src/extractors/ruby'),
+    php: __require('./src/extractors/php'),
+    swift: __require('./src/extractors/swift'),
+    dart: __require('./src/extractors/dart'),
+    scala: __require('./src/extractors/scala'),
+    gdscript: __require('./src/extractors/gdscript'),
+    r: __require('./src/extractors/r'),
+    vue: __require('./src/extractors/vue'),
+    vue_sfc: __require('./src/extractors/vue_sfc'),
+    svelte: __require('./src/extractors/svelte'),
+    html: __require('./src/extractors/html'),
+    css: __require('./src/extractors/css'),
+    yaml: __require('./src/extractors/yaml'),
+    shell: __require('./src/extractors/shell'),
+    sql: __require('./src/extractors/sql'),
+    graphql: __require('./src/extractors/graphql'),
+    terraform: __require('./src/extractors/terraform'),
+    protobuf: __require('./src/extractors/protobuf'),
+    toml: __require('./src/extractors/toml'),
+    properties: __require('./src/extractors/properties'),
+    xml: __require('./src/extractors/xml'),
+    markdown: __require('./src/extractors/markdown'),
+    dockerfile: __require('./src/extractors/dockerfile'),
+    generic: __require('./src/extractors/generic'),
+  };
+
+  const EXT_MAP = {
+    '.ts': 'typescript', '.tsx': 'typescript_react',
+    '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.py': 'python', '.pyw': 'python',
+    '.java': 'java',
+    '.kt': 'kotlin', '.kts': 'kotlin',
+    '.go': 'go',
+    '.rs': 'rust',
+    '.cs': 'csharp',
+    '.cpp': 'cpp', '.c': 'cpp', '.h': 'cpp', '.hpp': 'cpp', '.cc': 'cpp',
+    '.rb': 'ruby', '.rake': 'ruby',
+    '.php': 'php',
+    '.swift': 'swift',
+    '.dart': 'dart',
+    '.scala': 'scala', '.sc': 'scala',
+    '.gd': 'gdscript',
+    '.r': 'r', '.R': 'r',
+    '.vue': 'vue_sfc',
+    '.svelte': 'svelte',
+    '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'css', '.sass': 'css', '.less': 'css',
+    '.yml': 'yaml', '.yaml': 'yaml',
+    '.sh': 'shell', '.bash': 'shell', '.zsh': 'shell', '.fish': 'shell',
+    '.sql': 'sql',
+    '.graphql': 'graphql', '.gql': 'graphql',
+    '.tf': 'terraform', '.tfvars': 'terraform',
+    '.proto': 'protobuf',
+    '.toml': 'toml',
+    '.properties': 'properties',
+    '.xml': 'xml',
+    '.md': 'markdown',
+  };
+
+  /** Resolve a language key from a file path/name. */
+  function langFor(filePathOrName) {
+    const base = path.basename(String(filePathOrName || ''));
+    if (base === 'Dockerfile' || base.startsWith('Dockerfile.')) return 'dockerfile';
+    const ext = path.extname(base).toLowerCase();
+    return EXT_MAP[ext] || null;
+  }
+
+  /**
+   * Extract signatures from a file's content using the right extractor.
+   * @param {string} filePathOrName - path or name (extension drives the extractor)
+   * @param {string} src - file content
+   * @returns {string[]}
+   */
+  function extractFile(filePathOrName, src) {
+    if (!src || typeof src !== 'string') return [];
+    const lang = langFor(filePathOrName);
+    const mod = lang ? EXTRACTORS[lang] : null;
+    if (!mod || typeof mod.extract !== 'function') return [];
+    try {
+      const out = mod.extract(src);
+      return Array.isArray(out) ? out : [];
+    } catch (_) {
+      return [];
+    }
+  }
+
+  module.exports = { extractFile, langFor };
+  
+};
+
 // ── ./src/config/defaults ──
 __factories["./src/config/defaults"] = function(module, exports) {
   
@@ -5601,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) {
@@ -6088,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);
@@ -6125,7 +6369,83 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     }
   }
 
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures };
+  // ── Layer 1: live-index write hooks ────────────────────────────────────────
+  // Keep the sig-cache fresh while an agent creates/modifies/deletes files, so
+  // new code is discoverable in the same session. buildSigIndex already merges
+  // the cache (_buildSigIndexFromCache), so updates are live on the next read.
+
+  function _pkgVersion(cwd) {
+    try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
+    catch (_) { return '0.0.0'; }
+  }
+
+
+  /** notify_file_created — extract a file's signatures and index it live. */
+  function notifyFileCreated(args, cwd) {
+    const rel = args && args.path;
+    if (!rel) return 'Missing required argument: path';
+    try {
+      const { extractFile } = __require('./src/extractors/dispatch');
+      const { loadCache, saveCache } = __require('./src/cache/sig-cache');
+      const abs = path.resolve(cwd, rel);
+      let content = args.content;
+      if (typeof content !== 'string') {
+        try { content = fs.readFileSync(abs, 'utf8'); } catch (_) { content = ''; }
+      }
+      const sigs = extractFile(abs, content);
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      if (sigs.length > 0) {
+        cache.set(abs, { mtime: Date.now(), sigs });
+      }
+      saveCache(cwd, version, cache);
+      return `Indexed ${rel}: ${sigs.length} signature(s) now live.`;
+    } catch (err) {
+      return `_notify_file_created failed: ${err.message}_`;
+    }
+  }
+
+  /** notify_symbol_added — append one signature to a file's live cache entry. */
+  function notifySymbolAdded(args, cwd) {
+    if (!args || !args.signature || !args.file) {
+      return 'Missing required arguments: signature, file';
+    }
+    try {
+      const { loadCache, saveCache } = __require('./src/cache/sig-cache');
+      const abs = path.resolve(cwd, args.file);
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      const entry = cache.get(abs) || { mtime: Date.now(), sigs: [] };
+      const line = Number.isFinite(Number(args.line)) ? `  :${args.line}` : '';
+      const sig = String(args.signature) + line;
+      if (!entry.sigs.includes(sig)) entry.sigs.push(sig);
+      entry.mtime = Date.now();
+      cache.set(abs, entry);
+      saveCache(cwd, version, cache);
+      return `Added signature to ${args.file} (${entry.sigs.length} total).`;
+    } catch (err) {
+      return `_notify_symbol_added failed: ${err.message}_`;
+    }
+  }
+
+  /** notify_file_deleted — drop a file's cache-overlay entry. */
+  function notifyFileDeleted(args, cwd) {
+    const rel = args && args.path;
+    if (!rel) return 'Missing required argument: path';
+    try {
+      const { loadCache, saveCache } = __require('./src/cache/sig-cache');
+      const abs = path.resolve(cwd, rel);
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      const had = cache.delete(abs);
+      saveCache(cwd, version, cache);
+      return had ? `Removed ${rel} from the live index.` : `${rel} was not in the live cache.`;
+    } catch (err) {
+      return `_notify_file_deleted failed: ${err.message}_`;
+    }
+  }
+
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted };
   
 };
 // ── ./src/learning/weights ──
@@ -6302,11 +6622,11 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const readline = require('readline');
   const { TOOLS } = __require('./src/mcp/tools');
-  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures } = __require('./src/mcp/handlers');
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted } = __require('./src/mcp/handlers');
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.3.0',
+    version: '7.5.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -6366,6 +6686,9 @@ __factories["./src/mcp/server"] = function(module, exports) {
         else if (name === 'get_lines') text = getLines(args, cwd);
         else if (name === 'read_memory') text = readMemory(args, cwd);
         else if (name === 'get_callee_signatures') text = getCalleeSignatures(args, cwd);
+        else if (name === 'sigmap_notify_file_created') text = notifyFileCreated(args, cwd);
+        else if (name === 'sigmap_notify_symbol_added') text = notifySymbolAdded(args, cwd);
+        else if (name === 'sigmap_notify_file_deleted') text = notifyFileDeleted(args, cwd);
         else {
           respondError(id, -32601, `Unknown tool: ${name}`);
           return;
@@ -6425,10 +6748,11 @@ __factories["./src/mcp/server"] = function(module, exports) {
 __factories["./src/mcp/tools"] = function(module, exports) {
   
   /**
-   * MCP tool definitions for SigMap (12 tools).
+   * MCP tool definitions for SigMap (15 tools).
    * read_context, search_signatures, get_map, create_checkpoint, get_routing,
    * explain_file, list_modules, query_context, get_impact, get_lines, read_memory,
-   * get_callee_signatures.
+   * get_callee_signatures, sigmap_notify_file_created, sigmap_notify_symbol_added,
+   * sigmap_notify_file_deleted.
    */
 
   const TOOLS = [
@@ -6659,6 +6983,48 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         required: ['symbols'],
       },
     },
+    {
+      name: 'sigmap_notify_file_created',
+      description:
+        'Tell SigMap a file was created or modified so its signatures are indexed ' +
+        'live for the rest of the session. Call this after writing a file — the new ' +
+        'symbols become resolvable by search_signatures / get_callee_signatures.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File path relative to the project root.' },
+          content: { type: 'string', description: 'Optional file content; read from disk if omitted.' },
+        },
+        required: ['path'],
+      },
+    },
+    {
+      name: 'sigmap_notify_symbol_added',
+      description:
+        'Fast path: register a single new symbol signature directly in the live ' +
+        'index without re-reading the whole file.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          signature: { type: 'string', description: 'The signature line (e.g. "function check(key)").' },
+          file: { type: 'string', description: 'File path the symbol belongs to (relative to root).' },
+          line: { type: 'number', description: 'Optional 1-based line number.' },
+        },
+        required: ['signature', 'file'],
+      },
+    },
+    {
+      name: 'sigmap_notify_file_deleted',
+      description:
+        'Tell SigMap a file was deleted so its symbols are dropped from the live index.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Deleted file path relative to the project root.' },
+        },
+        required: ['path'],
+      },
+    },
   ];
 
   module.exports = { TOOLS };
@@ -7979,61 +8345,293 @@ __factories["./src/retrieval/tokenizer"] = function(module, exports) {
 
 // ── ./src/retrieval/ranker ──
 __factories["./src/retrieval/ranker"] = function(module, exports) {
-  'use strict';
+  
+  /**
+   * SigMap zero-dependency relevance ranker.
+   *
+   * Ranks all files in a signature index against a natural-language query.
+   * Scoring weights:
+   *   - keyword overlap (exact token match against sigs)
+   *   - symbol match (token appears in a top-level identifier / function name)
+   *   - partial prefix match (token is prefix of a sig token, length ≥ 4)
+   *   - path relevance (query token appears in the file path)
+   *   - recency boost (applied externally via recency map)
+   *
+   * Usage:
+   *   const { rank } = __require('./src/retrieval/src/retrieval/ranker');
+   *   const results = rank(query, sigIndex, { topK: 10 });
+   *   // results: [{ file, score, sigs, tokens }]
+   */
+
   const { loadWeights } = __require('./src/learning/weights');
   const { tokenize, STOP_WORDS } = __require('./src/retrieval/tokenizer');
+
+  // ---------------------------------------------------------------------------
+  // Default weights
+  // ---------------------------------------------------------------------------
   const DEFAULT_WEIGHTS = {
-    exactToken: 1.0, symbolMatch: 0.5, prefixMatch: 0.3, pathMatch: 0.8, recencyBoost: 1.5,
+    exactToken: 1.0,       // query token exactly in sig tokens
+    symbolMatch: 0.5,      // bonus if token appears in a function/class name line
+    prefixMatch: 0.3,      // partial prefix hit (query token ≥ 4 chars)
+    pathMatch: 0.8,        // query token appears in the file path
+    recencyBoost: 1.5,     // multiplier applied when file is in recencySet
+    graphBoost: 0.4,       // additive bonus for 1-hop import neighbors of matching files
   };
+
+  // Graph boost amounts for 2-hop traversal with decay (v6.7)
+  const GRAPH_BOOST_AMOUNTS = {
+    hop1: 0.40,   // direct import neighbor of a file with score > 0
+    hop2: 0.15,   // 2 hops away (transitive), with decay
+  };
+
+  // Intent-specific weight adjustments
+  const INTENT_WEIGHTS = {
+    search:     DEFAULT_WEIGHTS,
+    debug:      { ...DEFAULT_WEIGHTS, exactToken: 1.2, pathMatch: 0.6 },
+    explain:    { ...DEFAULT_WEIGHTS, symbolMatch: 0.8, pathMatch: 0.9 },
+    refactor:   { ...DEFAULT_WEIGHTS, symbolMatch: 0.9, exactToken: 0.8 },
+    review:     { ...DEFAULT_WEIGHTS, pathMatch: 1.0, exactToken: 0.9 },
+    test:       { ...DEFAULT_WEIGHTS, exactToken: 0.7, symbolMatch: 0.4 },
+    integrate:  { ...DEFAULT_WEIGHTS, graphBoost: 0.7, pathMatch: 1.1 },
+    navigate:   { ...DEFAULT_WEIGHTS, pathMatch: 1.2, exactToken: 0.9 },
+  };
+
+  // Penalty multipliers for negative signals
+  const PENALTY_SIGNALS = {
+    testFile:      0.4,    // test/spec/__tests__ in path
+    generatedCode: 0.3,    // dist/build/.next in path
+    docsFile:      0.2,    // docs/doc/README in path
+    nodeModules:   0.0,    // node_modules (zero score)
+  };
+
+  function _computePenalty(filePath) {
+    const pathLower = filePath.toLowerCase();
+    if (pathLower.includes('node_modules')) return PENALTY_SIGNALS.nodeModules;
+    if (/(^|\/)(test|tests|spec|__tests__|e2e)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.testFile;
+    if (/(^|\/)(dist|build|\.next|\.nuxt|out|\.venv|venv)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.generatedCode;
+    if (/(^|\/)(docs|doc|readme|changelog)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.docsFile;
+    return 1.0;
+  }
+
+  // Detect hub files: those with fanout > 20% of all files in the graph
+  function _computeHubs(graph) {
+    if (!graph || !graph.reverse) return new Set();
+    const fileCount = Math.max(1, graph.reverse.size);
+    const threshold = Math.ceil(fileCount * 0.2);
+    const hubs = new Set();
+    for (const [file, deps] of graph.reverse) {
+      if ((deps && deps.size >= threshold) || (Array.isArray(deps) && deps.length >= threshold)) {
+        hubs.add(file);
+      }
+    }
+    return hubs;
+  }
+
+  // Common utility paths that should be treated as hubs regardless of fanout
+  function _isHub(filePath) {
+    return /\/(utils|helpers|shared|common|constants|types|interfaces|index|zzz|globals)\.(ts|tsx|js|jsx|r|R)$/.test(filePath)
+        || filePath.endsWith('/index.ts') || filePath.endsWith('/index.js')
+        || filePath.endsWith('/R/utils.R') || filePath.endsWith('/R/zzz.R') || filePath.endsWith('/R/globals.R');
+  }
+
+  /**
+   * Score a single file against a query, returning detailed signal breakdown.
+   *
+   * @param {string}   filePath   - relative file path (e.g. 'src/extractors/python.js')
+   * @param {string[]} sigs       - signature strings for this file
+   * @param {string[]} queryTokens - pre-tokenized query
+   * @param {object}   weights
+   * @returns {{ score: number, signals: { exactToken: number, symbolMatch: number, prefixMatch: number, pathMatch: number, penalty: number } }}
+   */
   function scoreFile(filePath, sigs, queryTokens, weights) {
-    if (!sigs || sigs.length === 0) return 0;
+    if (!sigs || sigs.length === 0) return { score: 0, signals: { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: 1.0 } };
+
     const w = weights || DEFAULT_WEIGHTS;
-    const sigTokenSet = new Set(tokenize(sigs.join(' ')));
+    const signals = { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: _computePenalty(filePath) };
+
+    // Build token set from all signatures
+    const sigText = sigs.join(' ');
+    const sigTokenSet = new Set(tokenize(sigText));
+
+    // Build token set from the file path
     const pathTokenSet = new Set(tokenize(filePath));
+
     let score = 0;
+
     for (const qt of queryTokens) {
       if (STOP_WORDS.has(qt)) continue;
+
+      // Exact token match in sigs
       if (sigTokenSet.has(qt)) {
-        score += w.exactToken;
-        if (sigs.some((sig) => tokenize(sig.replace(/[^a-zA-Z0-9_\s]/g, ' ')).includes(qt))) score += w.symbolMatch;
+        const bonus = w.exactToken;
+        score += bonus;
+        signals.exactToken += bonus;
+
+        // Bonus: appears directly in a function/class/method name line
+        const nameLineMatch = sigs.some((sig) => {
+          const nt = tokenize(sig.replace(/[^a-zA-Z0-9_\s]/g, ' '));
+          return nt.includes(qt);
+        });
+        if (nameLineMatch) {
+          score += w.symbolMatch;
+          signals.symbolMatch += w.symbolMatch;
+        }
       }
+
+      // Prefix match (e.g. query "python" matches "pythonDeps")
       if (qt.length >= 4) {
         for (const st of sigTokenSet) {
-          if (st !== qt && st.startsWith(qt)) { score += w.prefixMatch; break; }
+          if (st !== qt && st.startsWith(qt)) {
+            score += w.prefixMatch;
+            signals.prefixMatch += w.prefixMatch;
+            break; // one bonus per query token
+          }
         }
       }
-      if (pathTokenSet.has(qt)) score += w.pathMatch;
+
+      // Path token match
+      if (pathTokenSet.has(qt)) {
+        score += w.pathMatch;
+        signals.pathMatch += w.pathMatch;
+      }
     }
-    return score;
+
+    // Apply penalty multiplier
+    score *= signals.penalty;
+
+    return { score, signals };
   }
+
+  /**
+   * Rank all files in a signature index against a query.
+   *
+   * @param {string}              query     - natural language query
+   * @param {Map<string,string[]>} sigIndex - Map<file, sigs[]>
+   * @param {object}  [opts]
+   * @param {number}  [opts.topK=10]               - max results to return
+   * @param {number}  [opts.recencyBoost=1.5]       - multiplier for recent files
+   * @param {Set<string>} [opts.recencySet]         - set of recently-changed file paths
+   * @param {object}  [opts.weights]               - override scoring weights
+   * @param {string}  [opts.cwd]                   - project root for learned ranking weights
+   * @param {{ forward: Map<string,string[]> }} [opts.graph] - dependency graph for neighbor boost
+   * @returns {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]}
+   */
   function rank(query, sigIndex, opts) {
     if (!query || typeof query !== 'string') return [];
     if (!sigIndex || !(sigIndex instanceof Map) || sigIndex.size === 0) return [];
+
     const topK = (opts && opts.topK) || 10;
     const recencyMultiplier = (opts && opts.recencyBoost) || DEFAULT_WEIGHTS.recencyBoost;
     const recencySet = (opts && opts.recencySet) || null;
-    const weights = (opts && opts.weights) ? Object.assign({}, DEFAULT_WEIGHTS, opts.weights) : DEFAULT_WEIGHTS;
+    const graph = (opts && opts.graph && opts.graph.forward instanceof Map) ? opts.graph : null;
+    const cwd = (opts && opts.cwd) || null;
+
+    // Detect query intent and get appropriate weights
+    const intent = detectIntent(query);
+    const intentWeights = INTENT_WEIGHTS[intent] || DEFAULT_WEIGHTS;
+    const weights = (opts && opts.weights) ? Object.assign({}, intentWeights, opts.weights) : intentWeights;
     const learnedWeights = opts && opts.cwd ? loadWeights(opts.cwd) : null;
+
     const queryTokens = tokenize(query);
     if (queryTokens.length === 0) {
+      // Empty query: return top-K by file count (most signatures = most useful)
       const all = [];
-      for (const [file, sigs] of sigIndex.entries()) all.push({ file, score: sigs.length, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
+      for (const [file, sigs] of sigIndex.entries()) {
+        all.push({ file, score: sigs.length, sigs, tokens: Math.ceil(sigs.join('\n').length / 4), intent, signals: {} });
+      }
       all.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
       return all.slice(0, topK);
     }
+
     const scored = [];
     for (const [file, sigs] of sigIndex.entries()) {
-      let score = scoreFile(file, sigs, queryTokens, weights);
-      if (recencySet && recencySet.has(file) && score > 0) score *= recencyMultiplier;
-      if (learnedWeights && score > 0) score *= learnedWeights[file] || 1.0;
-      scored.push({ file, score, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
+      const result = scoreFile(file, sigs, queryTokens, weights);
+      let score = result.score;
+      const signals = result.signals;
+
+      // Recency boost
+      if (recencySet && recencySet.has(file) && score > 0) {
+        score *= recencyMultiplier;
+        signals.recencyBoost = recencyMultiplier;
+      }
+
+      if (learnedWeights && score > 0) {
+        const multiplier = learnedWeights[file] || 1.0;
+        score *= multiplier;
+        signals.learnedWeights = multiplier;
+      }
+
+      scored.push({
+        file,
+        score,
+        sigs,
+        tokens: Math.ceil(sigs.join('\n').length / 4),
+        intent,
+        signals,
+      });
+    }
+
+    // Graph neighbor boost: 2-hop traversal with decay (v6.7)
+    // Hop 1: add hop1 amount to direct import neighbors (score > 0)
+    // Hop 2: add hop2 amount to neighbors of hop1 files (with decay)
+    // Hub suppression: files with high fanout (>20%) are not boosted
+    if (graph && cwd) {
+      const path = require('path');
+      // Build maps for relative ↔ absolute path conversion and index lookup
+      const relToIdx = new Map();
+      const absToRel = new Map();
+      for (let i = 0; i < scored.length; i++) {
+        relToIdx.set(scored[i].file, i);
+        const abs = path.resolve(cwd, scored[i].file);
+        absToRel.set(abs, scored[i].file);
+      }
+
+      const hubs = _computeHubs(graph);
+      const hop1Files = new Set(); // track which files received hop1 boost
+
+      // Hop 1: direct neighbors of scored files
+      for (const entry of scored) {
+        if (entry.score <= 0) continue;
+        const abs = path.resolve(cwd, entry.file);
+        const neighbors = graph.forward.get(abs) || [];
+        for (const neighborAbs of neighbors) {
+          if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
+          const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
+          const idx = relToIdx.get(neighborRel);
+          if (idx !== undefined) {
+            scored[idx].score += GRAPH_BOOST_AMOUNTS.hop1;
+            scored[idx].signals.graphBoost = (scored[idx].signals.graphBoost || 0) + GRAPH_BOOST_AMOUNTS.hop1;
+            hop1Files.add(neighborAbs);
+          }
+        }
+      }
+
+      // Hop 2: neighbors of hop1 files (only if they didn't get a direct score)
+      for (const hop1File of hop1Files) {
+        if (!absToRel.has(hop1File)) continue; // skip files not in index
+        const neighbors = graph.forward.get(hop1File) || [];
+        for (const neighborAbs of neighbors) {
+          if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
+          if (hop1Files.has(neighborAbs)) continue; // skip already hop1-boosted
+          const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
+          const idx = relToIdx.get(neighborRel);
+          if (idx !== undefined && scored[idx].score > 0) {
+            // Only boost files that have some baseline score (not noise)
+            scored[idx].score += GRAPH_BOOST_AMOUNTS.hop2;
+            scored[idx].signals.graphBoost = (scored[idx].signals.graphBoost || 0) + GRAPH_BOOST_AMOUNTS.hop2;
+          }
+        }
+      }
     }
+
     // Compute confidence levels based on score distribution
     if (scored.length > 0) {
       const scores = scored.map(s => s.score);
       const maxScore = Math.max(...scores);
       const minScore = Math.min(...scores);
       const scoreRange = maxScore - minScore || 1;
+
+      // Confidence tiers: top 33% = high, next 33% = medium, rest = low
       for (const entry of scored) {
         if (entry.score <= 0) {
           entry.confidence = 'low';
@@ -8043,39 +8641,73 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
         }
       }
     }
+
     scored.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
     return scored.slice(0, topK);
   }
+
+  /**
+   * All paths where sigmap adapters write their context files, in probe order.
+   * The first existing file with a non-empty index wins when no explicit path
+   * is supplied.
+   */
   const ADAPTER_OUTPUT_PATHS = [
-    ['.github', 'copilot-instructions.md'],
-    ['CLAUDE.md'],
-    ['AGENTS.md'],
-    ['.cursorrules'],
-    ['.windsurfrules'],
-    ['.github', 'openai-context.md'],
-    ['.github', 'gemini-context.md'],
-    ['llm-full.txt'],
-    ['llm.txt'],
+    ['.github', 'copilot-instructions.md'], // copilot (default)
+    ['CLAUDE.md'],                           // claude
+    ['AGENTS.md'],                           // codex
+    ['.cursorrules'],                        // cursor
+    ['.windsurfrules'],                      // windsurf
+    ['.github', 'openai-context.md'],        // openai
+    ['.github', 'gemini-context.md'],        // gemini
+    ['llm-full.txt'],                        // llm-full
+    ['llm.txt'],                             // llm
   ];
+
+  /**
+   * Parse a single context file into a Map<filePath, string[]>.
+   *
+   * Files that contain human-written content before an
+   * "## Auto-generated signatures" marker (e.g. CLAUDE.md) are handled
+   * by skipping everything above the marker before scanning for ### headers.
+   *
+   * @param {string} contextPath  - absolute path to the context file
+   * @returns {Map<string, string[]>}
+   */
   function _parseContextFile(contextPath) {
     const fs = require('fs');
     const index = new Map();
+
     if (!fs.existsSync(contextPath)) return index;
+
     let content = fs.readFileSync(contextPath, 'utf8');
+
+    // Skip any human-written preamble that sits above the auto-generated block.
     const markerIdx = content.indexOf('## Auto-generated signatures');
     if (markerIdx !== -1) content = content.slice(markerIdx);
+
     const lines = content.split('\n');
-    let currentFile = null; let inBlock = false; let sigs = [];
+    let currentFile = null;
+    let inBlock = false;
+    let sigs = [];
+
     for (const line of lines) {
-      const hm = line.match(/^###\s+(\S+)\s*$/);
-      if (hm) { if (currentFile !== null) index.set(currentFile, sigs); currentFile = hm[1]; sigs = []; inBlock = false; continue; }
+      const headerMatch = line.match(/^###\s+(\S+)\s*$/);
+      if (headerMatch) {
+        if (currentFile !== null) index.set(currentFile, sigs);
+        currentFile = headerMatch[1];
+        sigs = [];
+        inBlock = false;
+        continue;
+      }
       if (line.startsWith('```')) { inBlock = !inBlock; continue; }
       if (inBlock && currentFile && line.trim()) sigs.push(line.trim());
     }
     if (currentFile !== null) index.set(currentFile, sigs);
+
     return index;
   }
 
+  /** Merge source index into target; prefer non-empty sig lists. */
   function _mergeSigIndex(target, source) {
     for (const [file, sigs] of source.entries()) {
       if (!sigs || sigs.length === 0) continue;
@@ -8086,12 +8718,17 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return target;
   }
 
+  /**
+   * Load signatures from .sigmap-cache.json (absolute paths → repo-relative keys).
+   * @param {string} cwd
+   * @returns {Map<string, string[]>}
+   */
   function _buildSigIndexFromCache(cwd) {
     const fs = require('fs');
     const path = require('path');
     const index = new Map();
     try {
-      const { loadCache } = require('../cache/sig-cache');
+      const { loadCache } = __require('./src/cache/sig-cache');
       const pkgPath = path.join(cwd, 'package.json');
       let version = '0.0.0';
       if (fs.existsSync(pkgPath)) {
@@ -8108,6 +8745,12 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return index;
   }
 
+  /**
+   * Hot-cold and per-module strategies store most signatures outside the primary
+   * copilot-instructions.md file. MCP tools must merge all sources.
+   * @param {string} cwd
+   * @returns {Map<string, string[]>}
+   */
   function _enrichSigIndexFromStrategy(cwd, index) {
     const path = require('path');
     const coldPath = path.join(cwd, '.github', 'context-cold.md');
@@ -8116,49 +8759,138 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return index;
   }
 
+  /**
+   * Build a signature index from the generated context file.
+   * Returns Map<filePath, string[]> where filePath is the relative path
+   * as it appears in the ### headers of the context file.
+   *
+   * Resolution priority:
+   *  1. `opts.contextPath` — explicit path from --output or --adapter flag
+   *  2. `customOutput` key in gen-context.config.json — persisted from a
+   *     previous `--output <file>` generation run
+   *  3. All known adapter output paths probed in order (first non-empty wins)
+   *
+   * @param {string} cwd
+   * @param {{ contextPath?: string }} [opts]
+   * @returns {Map<string, string[]>}
+   */
   function buildSigIndex(cwd, opts) {
-    const fs = require('fs'); const path = require('path');
-    if (opts && opts.contextPath) return _enrichSigIndexFromStrategy(cwd, _parseContextFile(opts.contextPath));
-    // Check gen-context.config.json for a persisted customOutput path.
+    const fs   = require('fs');
+    const path = require('path');
+
+    // 1. Caller supplied an explicit path — use it directly.
+    if (opts && opts.contextPath) {
+      const index = _parseContextFile(opts.contextPath);
+      return _enrichSigIndexFromStrategy(cwd, index);
+    }
+
+    // 2. Check gen-context.config.json for a persisted customOutput path.
     try {
       const cfgPath = path.join(cwd, 'gen-context.config.json');
       if (fs.existsSync(cfgPath)) {
         const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
         if (cfg.customOutput) {
-          const idx = _parseContextFile(path.resolve(cwd, cfg.customOutput));
-          if (idx.size > 0) return _enrichSigIndexFromStrategy(cwd, idx);
+          const customPath = path.resolve(cwd, cfg.customOutput);
+          const index = _parseContextFile(customPath);
+          if (index.size > 0) return _enrichSigIndexFromStrategy(cwd, index);
         }
       }
     } catch (_) {}
+
+    // 3. Probe all known adapter output paths; return first non-empty index.
     for (const parts of ADAPTER_OUTPUT_PATHS) {
       const contextPath = path.join(cwd, ...parts);
       const index = _parseContextFile(contextPath);
       if (index.size > 0) return _enrichSigIndexFromStrategy(cwd, index);
     }
-    return _enrichSigIndexFromStrategy(cwd, new Map());
+
+    // 4. Primary file empty/missing (hot-cold) — still serve cold + cache.
+    const fallback = new Map();
+    return _enrichSigIndexFromStrategy(cwd, fallback);
   }
+
+  /**
+   * Format ranked results as a markdown table string.
+   *
+   * @param {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]} results
+   * @param {string} query
+   * @returns {string}
+   */
   function formatRankTable(results, query) {
-    if (!results || results.length === 0) return `No matching files found for query: "${query}"\n`;
-    const lines = [`## Query: ${query}`, '', '| Rank | File | Score | Sigs | Tokens |', '|------|------|-------|------|--------|',
-      ...results.map((r, i) => `| ${i + 1} | ${r.file} | ${r.score.toFixed(2)} | ${r.sigs.length} | ${r.tokens} |`), ''];
+    if (!results || results.length === 0) {
+      return `No matching files found for query: "${query}"\n`;
+    }
+
+    const intent = (results[0] && results[0].intent) || 'search';
+    const lines = [
+      `## Query: ${query}`,
+      `Intent: ${intent}`,
+      '',
+      '| Rank | File | Score | Sigs | Penalty |',
+      '|------|------|-------|------|---------|',
+      ...results.map((r, i) => {
+        const penalty = r.signals && r.signals.penalty ? r.signals.penalty.toFixed(2) : '1.00';
+        return `| ${i + 1} | ${r.file} | ${r.score.toFixed(2)} | ${r.sigs.length} | ${penalty} |`;
+      }),
+      '',
+    ];
+
+    // Add signature details for top results
     for (const r of results.slice(0, 3)) {
       if (r.sigs.length > 0) {
-        lines.push(`### ${r.file}`, '```', ...r.sigs.slice(0, 10));
+        lines.push(`### ${r.file}`);
+        if (r.signals) {
+          const sig = r.signals;
+          lines.push(`Signals: exactToken=${(sig.exactToken || 0).toFixed(2)} symbolMatch=${(sig.symbolMatch || 0).toFixed(2)} prefixMatch=${(sig.prefixMatch || 0).toFixed(2)} pathMatch=${(sig.pathMatch || 0).toFixed(2)} penalty=${(sig.penalty || 1).toFixed(2)}`);
+        }
+        lines.push('```');
+        lines.push(...r.sigs.slice(0, 10));
         if (r.sigs.length > 10) lines.push(`... (${r.sigs.length - 10} more)`);
-        lines.push('```', '');
+        lines.push('```');
+        lines.push('');
       }
     }
+
     return lines.join('\n');
   }
+
+  /**
+   * Format ranked results as a structured JSON-serialisable object.
+   *
+   * @param {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]} results
+   * @param {string} query
+   * @returns {object}
+   */
   function formatRankJSON(results, query) {
-    return { query, results: (results || []).map((r, i) => ({ rank: i + 1, file: r.file, score: r.score, sigs: r.sigs, tokens: r.tokens })), totalResults: (results || []).length };
+    const intent = (results && results[0] && results[0].intent) || 'search';
+    return {
+      query,
+      intent,
+      results: (results || []).map((r, i) => ({
+        rank: i + 1,
+        file: r.file,
+        score: r.score,
+        sigs: r.sigs,
+        tokens: r.tokens,
+        signals: r.signals || {},
+      })),
+      totalResults: (results || []).length,
+    };
   }
+
+  // ---------------------------------------------------------------------------
+  // Intent detection — 7 intents
+  // ---------------------------------------------------------------------------
   const INTENT_PATTERNS = {
     debug:    /\b(bug|fix|error|crash|exception|broken|failing|issue|problem|regression)\b/i,
-    explain:  /\b(explain|how does|what is|understand|overview|architecture|describe|walk me)\b/i,
-    refactor: /\b(refactor|restructure|redesign|clean up|extract|move|rename|simplify)\b/i,
-    review:   /\b(review|check|audit|security|pr|pull request|assess)\b/i,
+    explain:  /\b(explain|how does|what is|understand|overview|architecture|describe|walk me|teach)\b/i,
+    refactor: /\b(refactor|restructure|redesign|clean up|extract|move|rename|simplify|optimize)\b/i,
+    review:   /\b(review|check|audit|security|pr|pull request|assess|validate)\b/i,
+    test:     /\b(test|unit test|integration test|testing|spec|assert|mock)\b/i,
+    integrate:/\b(import|integrate|connect|wire|bind|require|export|depend|graph)\b|require[ds]\b/i,
+    navigate: /\b(find|locate|where|search|look for|show me|navigate|browse|list)\b/i,
   };
+
   function detectIntent(query) {
     if (!query || typeof query !== 'string') return 'search';
     for (const [intent, re] of Object.entries(INTENT_PATTERNS)) {
@@ -8166,9 +8898,10 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     }
     return 'search';
   }
-  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent };
-};
 
+  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, detectIntent };
+  
+};
 // ── ./src/eval/scorer ──
 __factories["./src/eval/scorer"] = function(module, exports) {
   'use strict';
@@ -11571,7 +12304,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.3.0';
+const VERSION = '7.5.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {