sigmap 6.12.0 → 6.14.0

package/CHANGELOG.md

@@ -10,6 +10,37 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [6.14.0] — 2026-06-07
+
+### Added
+
+- **`verify-ai-output` — Hallucination Guard prototype (Phase 1 MVP, #227, PR #228):**
+  - New command `sigmap verify-ai-output <answer.md> [--json]` flags fabricated claims in an AI answer against the real repository. Deterministic core — runs fully offline, no LLM.
+  - Three detectors: **fake-file** (referenced path absent on disk), **fake-import** (relative import does not resolve; bare import absent from `package.json` deps, with Node/Python builtins allow-listed and scoped packages handled), and **fake-symbol** (called function/class absent from the SigMap symbol index via `buildSigIndex`).
+  - Markdown report by default, `--json` for CI (`{ file, issues, summary }`). Exits `1` when any issue is found, `0` when clean.
+  - New modules `src/verify/parsers.js` (file/import/symbol/code-block extraction) and `src/verify/hallucination-guard.js` (`verify(answerText, cwd, opts)`); all external lookups are injectable so the core is unit-testable.
+
+---
+
+## [6.13.0] — 2026-06-05
+
+### Added
+
+- **Line anchors for JavaScript + member-level anchors (Surgical Context Phase 2.1, #223, PR #224):**
+  - The **JavaScript extractor** now emits `:start-end` line anchors on top-level functions, classes, exported arrow functions, and `module.exports` — previously only TypeScript and Python carried anchors. JS block-comment stripping switched to the newline-preserving blank so anchor line numbers stay exact below a `/* … */`.
+  - **Class methods and interface members** (TypeScript **and** JavaScript) now carry their **own** `:start-end` anchor spanning the member body, instead of inheriting nothing — unlocking method-level targeting with the `get_lines` MCP tool.
+  - Measured effect: index-mode token reduction on real repos rises from ~4.6% to **32–42%** (axios 42.1%, fastify 41.1%, svelte 36.8%, vue-core 32.4%), now 100% anchored.
+
+### Changed
+
+- The bundled standalone `gen-context.js` extractor factories are re-synced with `src/` (the bundle had been stale since v6.11.0), so anchors work in the single-file distribution too.
+
+### Fixed
+
+- **Token budget could exceed `maxTokens` with many files.** The budget was signature-only and undercounted per-file section headers plus the fixed ~150-token preamble; with anchored (collapsible) signatures keeping more files alive, output could overflow. `applyTokenBudget` now budgets *rendered* cost (signatures + section overhead) against `maxTokens` minus a `max(200, 10%)` preamble reserve.
+
+---
+
 ## [6.12.0] — 2026-06-05
 
 ### Added

package/README.md

@@ -87,7 +87,7 @@ Ask → Rank → Context → Validate → Judge → Learn
 ## Benchmark
 
 ```
-Benchmark : sigmap-v6.12-main (21 repositories, including R language)
+Benchmark : sigmap-v6.13-main (21 repositories, including R language)
 Date      : 2026-06-05
 
 Hit@5          : 81.1%   (baseline 13.6%  — 6.0× lift)

package/gen-context.js

@@ -916,61 +916,92 @@ __factories["./src/extractors/java"] = function(module, exports) {
 
 // ── ./src/extractors/javascript ──
 __factories["./src/extractors/javascript"] = function(module, exports) {
-  
+
+  const { lineAt, withAnchor } = __require('./src/extractors/line-anchor');
+
   /**
    * Extract signatures from JavaScript source code.
+   * Top-level declarations and class members carry a `:start-end` line anchor
+   * (see line-anchor.js); kept parallel to `sigs` and applied once at return.
    * @param {string} src - Raw file content
    * @returns {string[]} Array of signature strings
    */
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
+    const anchors = [];
     const returnHints = buildReturnHints(src);
-  
+
+    // Block comments are blanked newline-by-newline (non-newline chars → spaces)
+    // so character offsets AND line numbers stay exact for anchors.
     const stripped = src
       .replace(/\/\/.*$/gm, '')
-      .replace(/\/\*[\s\S]*?\*\//g, '');
-  
+      .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+
+    const blockEndIdx = (bodyStart) => bodyStart + extractBlock(stripped, bodyStart).length;
+    // End line for a function whose match ends at `matchEnd` (before its body brace).
+    const fnEndLine = (matchEnd, startLn) => {
+      const brace = stripped.indexOf('{', matchEnd);
+      return brace !== -1 ? lineAt(stripped, blockEndIdx(brace + 1)) : startLn;
+    };
+
     // Classes
     const classRegex = /^(export\s+(?:default\s+)?)?class\s+(\w+)(?:\s+extends\s+[\w.]+)?\s*\{/gm;
     for (const m of stripped.matchAll(classRegex)) {
       const prefix = m[1] ? m[1].trim() + ' ' : '';
+      const bodyStart = m.index + m[0].length;
       sigs.push(`${prefix}class ${m[2]}`);
-      const block = extractBlock(stripped, m.index + m[0].length);
-      for (const meth of extractClassMembers(block, returnHints)) sigs.push(`  ${meth}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
+      const block = extractBlock(stripped, bodyStart);
+      for (const meth of extractClassMembers(block, returnHints)) {
+        sigs.push(`  ${meth.text}`);
+        anchors.push([lineAt(stripped, bodyStart + meth.start), lineAt(stripped, bodyStart + meth.end)]);
+      }
     }
-  
+
     // Exported named functions
     for (const m of stripped.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/gm)) {
       const asyncKw = /export\s+async/.test(m[0]) ? 'async ' : '';
       const retStr = formatReturnHint(returnHints.get(m[1]));
+      const startLn = lineAt(stripped, m.index);
       sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
     }
-  
+
     // Exported arrow functions
     for (const m of stripped.matchAll(/^export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/gm)) {
       const asyncKw = m[0].includes('async') ? 'async ' : '';
       const retStr = formatReturnHint(returnHints.get(m[1]));
+      const startLn = lineAt(stripped, m.index);
       sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>${retStr}`);
+      anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
     }
-  
+
     // module.exports = { ... }
     const moduleExports = stripped.match(/^module\.exports\s*=\s*\{([^}]+)\}/m);
     if (moduleExports) {
       const names = moduleExports[1].split(',').map((s) => s.trim()).filter(Boolean);
-      if (names.length > 0) sigs.push(`module.exports = { ${names.join(', ')} }`);
+      if (names.length > 0) {
+        const startLn = lineAt(stripped, moduleExports.index);
+        sigs.push(`module.exports = { ${names.join(', ')} }`);
+        anchors.push([startLn, lineAt(stripped, moduleExports.index + moduleExports[0].length)]);
+      }
     }
-  
+
     // Top-level named functions (non-exported)
     for (const m of stripped.matchAll(/^(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/gm)) {
       const asyncKw = m[0].startsWith('async') ? 'async ' : '';
       const retStr = formatReturnHint(returnHints.get(m[1]));
+      const startLn = lineAt(stripped, m.index);
       sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
     }
-  
-    return sigs.slice(0, 25);
+
+    return sigs
+      .map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s))
+      .slice(0, 25);
   }
-  
+
   function extractBlock(src, startIndex) {
     let depth = 1;
     let i = startIndex;
@@ -982,16 +1013,22 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
     }
     return src.slice(startIndex, i - 1);
   }
-  
+
+  // Returns members as { text, start, end } where start/end are char offsets
+  // WITHIN `block` (end = the method's closing brace), so the caller can resolve
+  // per-method line anchors that span the method body.
   function extractClassMembers(block, returnHints) {
     const members = [];
     for (const m of block.matchAll(/^\s+(?:static\s+|async\s+|get\s+|set\s+)*(\w+)\s*\(([^)]*)\)\s*\{/gm)) {
       if (/^_/.test(m[1])) continue;
-      if (m[1] === 'constructor') { members.push(`constructor(${normalizeParams(m[2])})`); continue; }
+      const bodyStart = m.index + m[0].length; // just past the opening brace
+      const end = bodyStart + extractBlock(block, bodyStart).length;
+      const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+      if (m[1] === 'constructor') { members.push({ text: `constructor(${normalizeParams(m[2])})`, start, end }); continue; }
       const isAsync = m[0].includes('async ') ? 'async ' : '';
       const isStatic = m[0].includes('static ') ? 'static ' : '';
       const retStr = formatReturnHint(returnHints.get(m[1]));
-      members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
     }
     return members.slice(0, 8);
   }
@@ -1016,18 +1053,17 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
   }
 
   function formatReturnHint(type) {
-    return type ? ` \u2192 ${type}` : '';
+    return type ? ` → ${type}` : '';
   }
-  
+
   function normalizeParams(params) {
     if (!params) return '';
     return params.trim().replace(/\s+/g, ' ');
   }
-  
+
   module.exports = { extract };
-  
-};
 
+};
 // ── ./src/extractors/kotlin ──
 __factories["./src/extractors/kotlin"] = function(module, exports) {
   
@@ -1799,101 +1835,164 @@ __factories["./src/extractors/swift"] = function(module, exports) {
 
 // ── ./src/extractors/typescript ──
 __factories["./src/extractors/typescript"] = function(module, exports) {
-  
+
+  const { lineAt, withAnchor } = __require('./src/extractors/line-anchor');
+
   /**
    * Extract signatures from TypeScript source code.
+   * Top-level declarations carry a `:start-end` line anchor (see line-anchor.js);
+   * indented members do not.
    * @param {string} src - Raw file content
    * @returns {string[]} Array of signature strings
    */
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
-  
-    // Strip single-line comments
+    // anchors[i] is [start, end] for a top-level sig, or null for an indented member.
+    // Kept parallel to `sigs` so existing push/mutation logic stays untouched;
+    // anchors are applied once at return.
+    const anchors = [];
+
+    // Strip comments to simplify matching. Block comments are blanked
+    // newline-by-newline (non-newline chars → spaces) so character offsets AND
+    // line numbers stay exact. Line comments preserve their trailing newline.
     const stripped = src
       .replace(/\/\/.*$/gm, '')
-      .replace(/\/\*[\s\S]*?\*\//g, '');
-  
+      .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+
+    // Index of the closing brace for a block whose body starts at bodyStart.
+    const blockEndIdx = (bodyStart) => bodyStart + extractBlock(stripped, bodyStart).length;
+
     // Exported interfaces
     for (const m of stripped.matchAll(/^export\s+interface\s+(\w+)(?:<[^{]*>)?\s*(?:extends\s+[^{]+)?\{/gm)) {
+      const bodyStart = m.index + m[0].length;
       sigs.push(`export interface ${m[1]}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
       // Collect members
-      const start = m.index + m[0].length;
-      const block = extractBlock(stripped, start);
+      const block = extractBlock(stripped, bodyStart);
       const members = extractInterfaceMembers(block);
-      for (const mem of members) sigs.push(`  ${mem}`);
+      for (const mem of members) {
+        sigs.push(`  ${mem.text}`);
+        anchors.push([lineAt(stripped, bodyStart + mem.start), lineAt(stripped, bodyStart + mem.end)]);
+      }
     }
-  
+
     // Exported type aliases
     for (const m of stripped.matchAll(/^export\s+type\s+(\w+)(?:<[^=]*>)?\s*=/gm)) {
       sigs.push(`export type ${m[1]}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, m.index + m[0].length)]);
     }
-  
+
     // Exported enums
     for (const m of stripped.matchAll(/^export\s+(?:const\s+)?enum\s+(\w+)\s*\{/gm)) {
+      const bodyStart = m.index + m[0].length;
       sigs.push(`export enum ${m[1]}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
     }
-  
+
     // Classes (exported and internal)
     const classRegex = /^(export\s+)?(abstract\s+)?class\s+(\w+)(?:<[^{]*>)?(?:\s+extends\s+[\w<>, .]+)?(?:\s+implements\s+[\w<> ,]+)?\s*\{/gm;
     for (const m of stripped.matchAll(classRegex)) {
       const prefix = m[1] ? 'export ' : '';
       const abs = m[2] ? 'abstract ' : '';
+      const bodyStart = m.index + m[0].length;
       sigs.push(`${prefix}${abs}class ${m[3]}`);
-      const start = m.index + m[0].length;
-      const block = extractBlock(stripped, start);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
+      const block = extractBlock(stripped, bodyStart);
       const methods = extractClassMembers(block);
-      for (const meth of methods) sigs.push(`  ${meth}`);
+      for (const meth of methods) {
+        sigs.push(`  ${meth.text}`);
+        anchors.push([lineAt(stripped, bodyStart + meth.start), lineAt(stripped, bodyStart + meth.end)]);
+      }
     }
-  
+
     // Exported top-level functions (not methods)
     for (const m of stripped.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)(?:\s*:\s*[^{]+)?\s*\{/gm)) {
       const asyncKw = /export\s+async/.test(m[0]) ? 'async ' : '';
       const params = normalizeParams(m[2]);
       const retMatch = m[0].match(/\)\s*:\s*([^{]+)\s*\{/);
       const retType = retMatch ? retMatch[1].trim().replace(/\s+/g, ' ').slice(0, 30) : '';
-      const retStr = retType ? ` \u2192 ${retType}` : '';
+      const retStr = retType ? ` → ${retType}` : '';
+      const bodyStart = m.index + m[0].length;
       sigs.push(`export ${asyncKw}function ${m[1]}(${params})${retStr}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
+
+      // Hooks: capture compact return object shape for use* functions.
+      if (m[1].startsWith('use')) {
+        const body = stripped.slice(bodyStart, bodyStart + 800);
+        const ret = body.match(/return\s*\{([^}]{1,260})\}/);
+        if (ret) {
+          const keys = ret[1]
+            .split(',')
+            .map((s) => s.trim().split(':')[0].split('(')[0].trim())
+            .filter(Boolean)
+            .slice(0, 8);
+          if (keys.length) {
+            sigs[sigs.length - 1] += ` → { ${keys.join(', ')} }`;
+          }
+        }
+      }
     }
-  
+
     // Exported arrow functions / const functions
     for (const m of stripped.matchAll(/^export\s+const\s+(\w+)\s*(?::\s*[^=]+)?\s*=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*[^=>{]+)?\s*=>/gm)) {
       const asyncKw = /=\s*async\s+/.test(m[0]) ? 'async ' : '';
       const params = normalizeParams(m[2]);
       sigs.push(`export const ${m[1]} = ${asyncKw}(${params}) =>`);
+      const bodyStart = stripped.indexOf('{', m.index + m[0].length);
+      const endLn = bodyStart !== -1
+        ? lineAt(stripped, blockEndIdx(bodyStart + 1))
+        : lineAt(stripped, m.index + m[0].length);
+      anchors.push([lineAt(stripped, m.index), endLn]);
+
+      // Hooks: capture compact return object shape for use* functions.
+      if (m[1].startsWith('use')) {
+        if (bodyStart !== -1) {
+          const body = stripped.slice(bodyStart, bodyStart + 800);
+          const ret = body.match(/return\s*\{([^}]{1,260})\}/);
+          if (ret) {
+            const keys = ret[1]
+              .split(',')
+              .map((s) => s.trim().split(':')[0].split('(')[0].trim())
+              .filter(Boolean)
+              .slice(0, 8);
+            if (keys.length) {
+              sigs[sigs.length - 1] += ` → { ${keys.join(', ')} }`;
+            }
+          }
+        }
+      }
     }
 
     // Zustand stores: export const useXxxStore = create<State>()(...)
     for (const m of stripped.matchAll(/^export\s+const\s+(use\w+Store)\s*=\s*create(?:<[^>]*>)?\s*\(/gm)) {
-      // Extract the State interface name from create<StateName>
       const stateType = m[0].match(/create<([\w]+)>/)?.[1] || '';
+      const startLn = lineAt(stripped, m.index);
       sigs.push(`export const ${m[1]} = create<${stateType}>(...)`);
-      // Extract action/state keys from the embedded interface in same file
+      anchors.push([startLn, startLn]);
       const ifaceRe = new RegExp(`interface\\s+${stateType}\\s*\\{([\\s\\S]*?)\\}`);
       const ifm = stripped.match(ifaceRe);
       if (ifm) {
-        for (const fm of ifm[1].matchAll(/^\s+(\w+)\s*(?:\([^)]*\))?\s*:/gm)) {
-          sigs.push(`  ${fm[1]}`);
-        }
+        for (const fm of ifm[1].matchAll(/^\s+(\w+)\s*(?:\([^)]*\))?\s*:/gm)) { sigs.push(`  ${fm[1]}`); anchors.push(null); }
       }
     }
 
-    // API client objects: export default { method: async (...) => ... }
-    // Pattern: const xxxApi = { methodName: async ... }
+    // API client objects: const xxxApi = { method: async () => {} }
     for (const m of stripped.matchAll(/^(?:export\s+default\s+|const\s+)(\w*[Aa]pi\w*)\s*=\s*\{/gm)) {
-      const apiName = m[1];
-      const start = m.index + m[0].length;
-      const block = extractBlock(stripped, start);
-      const methods = [];
-      for (const mm of block.matchAll(/^\s+(\w+)\s*:\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/gm)) {
-        methods.push(mm[1]);
+      const bodyStart = m.index + m[0].length;
+      const block = extractBlock(stripped, bodyStart);
+      const methods = [...block.matchAll(/^\s+(\w+)\s*:\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/gm)].map(mm => mm[1]);
+      if (methods.length) {
+        sigs.push(`${m[1]}: { ${methods.join(', ')} }`);
+        anchors.push([lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)]);
       }
-      if (methods.length) sigs.push(`${apiName}: { ${methods.join(', ')} }`);
     }
-  
-    return sigs.slice(0, 35);
+
+    return sigs
+      .map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s))
+      .slice(0, 35);
   }
-  
+
   function extractBlock(src, startIndex) {
     let depth = 1;
     let i = startIndex;
@@ -1905,47 +2004,59 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
     }
     return src.slice(startIndex, i - 1);
   }
-  
+
+  // Returns members as { text, start, end } where start/end are char offsets
+  // WITHIN `block`, so the caller can resolve member line anchors.
   function extractInterfaceMembers(block) {
     const members = [];
     for (const m of block.matchAll(/^\s+(readonly\s+)?(\w+)(\??):\s*([^;]+);/gm)) {
       const readonly = m[1] ? 'readonly ' : '';
       const optional = m[3] ? '?' : '';
       const typeStr = m[4].trim().replace(/\s+/g, ' ').slice(0, 35);
-      members.push(`${readonly}${m[2]}${optional}: ${typeStr}`);
+      const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+      members.push({ text: `${readonly}${m[2]}${optional}: ${typeStr}`, start, end: m.index + m[0].length });
     }
     for (const m of block.matchAll(/^\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)\s*:/gm)) {
-      members.push(`${m[1]}(${normalizeParams(m[2])})`);
+      const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+      members.push({ text: `${m[1]}(${normalizeParams(m[2])})`, start, end: m.index + m[0].length });
     }
     return members.slice(0, 8);
   }
-  
+
+  const _CTRL_KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'do', 'try', 'catch', 'finally', 'else', 'return']);
+
+  // Returns members as { text, start, end } where start/end are char offsets
+  // WITHIN `block` (end = the method's closing brace), so the caller can resolve
+  // per-method line anchors that span the method body.
   function extractClassMembers(block) {
     const members = [];
-    // Public methods (skip private/protected/_ prefixed)
+    // Public methods (skip private/protected/_ prefixed and control-flow keywords)
     const methodRe = /^\s+(?:public\s+|static\s+|async\s+|override\s+)*(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)(?:\s*:\s*[^{;]+)?\s*\{/gm;
     for (const m of block.matchAll(methodRe)) {
+      if (_CTRL_KEYWORDS.has(m[1])) continue;
       if (/^(private|protected|_)/.test(m[1])) continue;
-      if (m[1] === 'constructor') { members.push(`constructor(${normalizeParams(m[2])})`); continue; }
+      const bodyStart = m.index + m[0].length; // just past the opening brace
+      const end = bodyStart + extractBlock(block, bodyStart).length;
+      const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+      if (m[1] === 'constructor') { members.push({ text: `constructor(${normalizeParams(m[2])})`, start, end }); continue; }
       const isAsync = m[0].includes('async ') ? 'async ' : '';
       const isStatic = m[0].includes('static ') ? 'static ' : '';
       const retMatch = m[0].match(/\)\s*:\s*([^{;]+)\s*\{/);
       const retType = retMatch ? retMatch[1].trim().replace(/\s+/g, ' ').slice(0, 20) : '';
-      const retStr = retType ? ` \u2192 ${retType}` : '';
-      members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      const retStr = retType ? ` → ${retType}` : '';
+      members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
     }
     return members.slice(0, 8);
   }
-  
+
   function normalizeParams(params) {
     if (!params) return '';
     return params.trim().replace(/\s+/g, ' ').replace(/:[^,)]+/g, '').trim();
   }
-  
+
   module.exports = { extract };
-  
-};
 
+};
 // ── ./src/extractors/graphql ──
 __factories["./src/extractors/graphql"] = function(module, exports) {
   
@@ -6043,7 +6154,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '6.12.0',
+  version: '6.14.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -8867,7 +8978,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '6.12.0';
+const VERSION = '6.14.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -9154,10 +9265,18 @@ function computeEffectiveMaxTokens(fileEntries, config) {
 
 function applyTokenBudget(fileEntries, maxTokens) {
   // fileEntries: [{ filePath, sigs, mtime }]
-  // Reserve ~10% for formatting overhead (section headers, code fences, top-level header)
-  const effectiveBudget = Math.floor(maxTokens * 0.90);
-  let total = fileEntries.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')), 0);
-  if (total <= effectiveBudget) return fileEntries;
+  // Per-file rendered overhead: "### <path>", code fences, trailing blank line.
+  // A signature-only budget undercounts this, so when many files survive the
+  // section headers alone can blow maxTokens.
+  const sectionOverhead = (e) => estimateTokens(String(e.filePath || '')) + 6;
+  const renderedTotal = (entries) =>
+    entries.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')) + sectionOverhead(e), 0);
+  // The generated file also carries a ~150-token fixed preamble (SigMap command
+  // table + headers). Reserve at least that much so small budgets don't overflow;
+  // for large budgets this matches the historical 10% reserve.
+  const budgetForEntries = Math.max(1, maxTokens - Math.max(200, Math.ceil(maxTokens * 0.10)));
+  let total = renderedTotal(fileEntries);
+  if (total <= budgetForEntries) return fileEntries;
 
   // v6.12 Surgical Context — progressive disclosure: before dropping whole files,
   // collapse signature BODIES to their line-anchor pointers (keep `symbol :start-end`).
@@ -9171,12 +9290,13 @@ function applyTokenBudget(fileEntries, maxTokens) {
     });
     return { ...e, sigs: slim };
   });
-  const collapsedTotal = collapsed.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')), 0);
-  if (collapsedTotal < total) {
-    console.warn(`[sigmap] budget: collapsed bodies to anchors, reclaimed ~${total - collapsedTotal} tokens`);
+  const collapsedRendered = renderedTotal(collapsed);
+  if (collapsedRendered < total) {
+    console.warn(`[sigmap] budget: collapsed bodies to anchors, reclaimed ~${total - collapsedRendered} tokens`);
     working = collapsed;
-    total = collapsedTotal;
-    if (total <= effectiveBudget) return working; // anchor collapse alone fit the budget
+    total = collapsedRendered;
+    // Collapsing keeps every file, so the section overhead must fit too — not just sigs.
+    if (total <= budgetForEntries) return working;
   }
 
   // Sort by drop priority (drop first = index 0)
@@ -9203,12 +9323,13 @@ function applyTokenBudget(fileEntries, maxTokens) {
 
   const kept = [];
   const verboseDropped = [];
-  // Iterate forward: highest drop-priority files (generated=10, mock=9, test=8) are at index 0
-  // Drop those first until we're under budget, then keep everything else
+  // Iterate forward: highest drop-priority files (generated=10, mock=9, test=8) are at index 0.
+  // Drop those first until the RENDERED total (sigs + section overhead) fits maxTokens,
+  // then keep everything else.
+  let rendered = renderedTotal(withPriority);
   for (const entry of withPriority) {
-    const entryTokens = estimateTokens(entry.sigs.join('\n'));
-    if (total > effectiveBudget) {
-      total -= entryTokens;
+    if (rendered > budgetForEntries) {
+      rendered -= estimateTokens(entry.sigs.join('\n')) + sectionOverhead(entry);
       verboseDropped.push({ filePath: entry.filePath, reason: entry.dropReason });
     } else {
       kept.push(entry);
@@ -10616,6 +10737,8 @@ Usage:
   ${cmd} --impact <file>                   Show every file impacted by changing <file>
   ${cmd} --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
   ${cmd} --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
+  ${cmd} verify-ai-output <answer.md>      Flag fake files/imports/symbols in an AI answer
+  ${cmd} verify-ai-output <answer.md> --json  Hallucination report as JSON (exits 1 if issues)
   ${cmd} --init                            Write example config + .contextignore scaffold
   ${cmd} --help                            Show this message
   ${cmd} --version                         Show version
@@ -11737,6 +11860,45 @@ function main() {
     process.exit(0);
   }
 
+  // `sigmap verify-ai-output <answer.md>` — Hallucination Guard (deterministic core)
+  if (args[0] === 'verify-ai-output') {
+    const target = args[1];
+    const jsonOut = args.includes('--json');
+    if (!target || target.startsWith('--')) {
+      console.error('[sigmap] Usage: sigmap verify-ai-output <answer.md> [--json]');
+      process.exit(1);
+    }
+    const absTarget = path.resolve(cwd, target);
+    if (!fs.existsSync(absTarget)) {
+      console.error(`[sigmap] file not found: ${target}`);
+      process.exit(1);
+    }
+
+    const answerText = fs.readFileSync(absTarget, 'utf8');
+    const { verify } = requireSourceOrBundled('./src/verify/hallucination-guard');
+    const { issues, summary } = verify(answerText, cwd);
+
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify({ file: path.relative(cwd, absTarget) || target, issues, summary }) + '\n');
+      process.exit(summary.total > 0 ? 1 : 0);
+    }
+
+    const rel = path.relative(cwd, absTarget) || target;
+    if (summary.total === 0) {
+      console.log(`[sigmap] ✓ ${rel} — no hallucinations detected (${summary.symbolsIndexed} symbols indexed)`);
+      process.exit(0);
+    }
+
+    const labels = { 'fake-file': 'Fake file', 'fake-import': 'Fake import', 'fake-symbol': 'Fake symbol' };
+    console.log(`[sigmap] ✗ ${rel} — ${summary.total} issue${summary.total === 1 ? '' : 's'} found`);
+    console.log(`  fake-file: ${summary.byType['fake-file']}  fake-import: ${summary.byType['fake-import']}  fake-symbol: ${summary.byType['fake-symbol']}`);
+    console.log('');
+    for (const issue of issues) {
+      console.log(`  L${issue.line}  [${labels[issue.type] || issue.type}]  ${issue.message}`);
+    }
+    process.exit(1);
+  }
+
   // Feature 1: `sigmap explain <file>` — why a file is included or excluded
   if (args[0] === 'explain' || args.includes('--explain')) {
     const target = args[0] === 'explain'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "6.12.0",
+  "version": "6.14.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "6.12.0",
+  "version": "6.14.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": "6.12.0",
+  "version": "6.14.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/extractors/javascript.js

@@ -1,57 +1,88 @@
 'use strict';
 
+const { lineAt, withAnchor } = require('./line-anchor');
+
 /**
  * Extract signatures from JavaScript source code.
+ * Top-level declarations and class members carry a `:start-end` line anchor
+ * (see line-anchor.js); kept parallel to `sigs` and applied once at return.
  * @param {string} src - Raw file content
  * @returns {string[]} Array of signature strings
  */
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  const anchors = [];
   const returnHints = buildReturnHints(src);
 
+  // Block comments are blanked newline-by-newline (non-newline chars → spaces)
+  // so character offsets AND line numbers stay exact for anchors.
   const stripped = src
     .replace(/\/\/.*$/gm, '')
-    .replace(/\/\*[\s\S]*?\*\//g, '');
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+
+  const blockEndIdx = (bodyStart) => bodyStart + extractBlock(stripped, bodyStart).length;
+  // End line for a function whose match ends at `matchEnd` (before its body brace).
+  const fnEndLine = (matchEnd, startLn) => {
+    const brace = stripped.indexOf('{', matchEnd);
+    return brace !== -1 ? lineAt(stripped, blockEndIdx(brace + 1)) : startLn;
+  };
 
   // Classes
   const classRegex = /^(export\s+(?:default\s+)?)?class\s+(\w+)(?:\s+extends\s+[\w.]+)?\s*\{/gm;
   for (const m of stripped.matchAll(classRegex)) {
     const prefix = m[1] ? m[1].trim() + ' ' : '';
+    const bodyStart = m.index + m[0].length;
     sigs.push(`${prefix}class ${m[2]}`);
-    const block = extractBlock(stripped, m.index + m[0].length);
-    for (const meth of extractClassMembers(block, returnHints)) sigs.push(`  ${meth}`);
+    anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
+    const block = extractBlock(stripped, bodyStart);
+    for (const meth of extractClassMembers(block, returnHints)) {
+      sigs.push(`  ${meth.text}`);
+      anchors.push([lineAt(stripped, bodyStart + meth.start), lineAt(stripped, bodyStart + meth.end)]);
+    }
   }
 
   // Exported named functions
   for (const m of stripped.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/gm)) {
     const asyncKw = /export\s+async/.test(m[0]) ? 'async ' : '';
     const retStr = formatReturnHint(returnHints.get(m[1]));
+    const startLn = lineAt(stripped, m.index);
     sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
   // Exported arrow functions
   for (const m of stripped.matchAll(/^export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/gm)) {
     const asyncKw = m[0].includes('async') ? 'async ' : '';
     const retStr = formatReturnHint(returnHints.get(m[1]));
+    const startLn = lineAt(stripped, m.index);
     sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>${retStr}`);
+    anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
   // module.exports = { ... }
   const moduleExports = stripped.match(/^module\.exports\s*=\s*\{([^}]+)\}/m);
   if (moduleExports) {
     const names = moduleExports[1].split(',').map((s) => s.trim()).filter(Boolean);
-    if (names.length > 0) sigs.push(`module.exports = { ${names.join(', ')} }`);
+    if (names.length > 0) {
+      const startLn = lineAt(stripped, moduleExports.index);
+      sigs.push(`module.exports = { ${names.join(', ')} }`);
+      anchors.push([startLn, lineAt(stripped, moduleExports.index + moduleExports[0].length)]);
+    }
   }
 
   // Top-level named functions (non-exported)
   for (const m of stripped.matchAll(/^(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/gm)) {
     const asyncKw = m[0].startsWith('async') ? 'async ' : '';
     const retStr = formatReturnHint(returnHints.get(m[1]));
+    const startLn = lineAt(stripped, m.index);
     sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
-  return sigs.slice(0, 25);
+  return sigs
+    .map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s))
+    .slice(0, 25);
 }
 
 function extractBlock(src, startIndex) {
@@ -66,15 +97,21 @@ function extractBlock(src, startIndex) {
   return src.slice(startIndex, i - 1);
 }
 
+// Returns members as { text, start, end } where start/end are char offsets
+// WITHIN `block` (end = the method's closing brace), so the caller can resolve
+// per-method line anchors that span the method body.
 function extractClassMembers(block, returnHints) {
   const members = [];
   for (const m of block.matchAll(/^\s+(?:static\s+|async\s+|get\s+|set\s+)*(\w+)\s*\(([^)]*)\)\s*\{/gm)) {
     if (/^_/.test(m[1])) continue;
-    if (m[1] === 'constructor') { members.push(`constructor(${normalizeParams(m[2])})`); continue; }
+    const bodyStart = m.index + m[0].length; // just past the opening brace
+    const end = bodyStart + extractBlock(block, bodyStart).length;
+    const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+    if (m[1] === 'constructor') { members.push({ text: `constructor(${normalizeParams(m[2])})`, start, end }); continue; }
     const isAsync = m[0].includes('async ') ? 'async ' : '';
     const isStatic = m[0].includes('static ') ? 'static ' : '';
     const retStr = formatReturnHint(returnHints.get(m[1]));
-    members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
   }
   return members.slice(0, 8);
 }

package/src/extractors/typescript.js

@@ -35,7 +35,10 @@ function extract(src) {
     // Collect members
     const block = extractBlock(stripped, bodyStart);
     const members = extractInterfaceMembers(block);
-    for (const mem of members) { sigs.push(`  ${mem}`); anchors.push(null); }
+    for (const mem of members) {
+      sigs.push(`  ${mem.text}`);
+      anchors.push([lineAt(stripped, bodyStart + mem.start), lineAt(stripped, bodyStart + mem.end)]);
+    }
   }
 
   // Exported type aliases
@@ -61,7 +64,10 @@ function extract(src) {
     anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
     const block = extractBlock(stripped, bodyStart);
     const methods = extractClassMembers(block);
-    for (const meth of methods) { sigs.push(`  ${meth}`); anchors.push(null); }
+    for (const meth of methods) {
+      sigs.push(`  ${meth.text}`);
+      anchors.push([lineAt(stripped, bodyStart + meth.start), lineAt(stripped, bodyStart + meth.end)]);
+    }
   }
 
   // Exported top-level functions (not methods)
@@ -163,22 +169,29 @@ function extractBlock(src, startIndex) {
   return src.slice(startIndex, i - 1);
 }
 
+// Returns members as { text, start, end } where start/end are char offsets
+// WITHIN `block`, so the caller can resolve member line anchors.
 function extractInterfaceMembers(block) {
   const members = [];
   for (const m of block.matchAll(/^\s+(readonly\s+)?(\w+)(\??):\s*([^;]+);/gm)) {
     const readonly = m[1] ? 'readonly ' : '';
     const optional = m[3] ? '?' : '';
     const typeStr = m[4].trim().replace(/\s+/g, ' ').slice(0, 35);
-    members.push(`${readonly}${m[2]}${optional}: ${typeStr}`);
+    const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+    members.push({ text: `${readonly}${m[2]}${optional}: ${typeStr}`, start, end: m.index + m[0].length });
   }
   for (const m of block.matchAll(/^\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)\s*:/gm)) {
-    members.push(`${m[1]}(${normalizeParams(m[2])})`);
+    const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+    members.push({ text: `${m[1]}(${normalizeParams(m[2])})`, start, end: m.index + m[0].length });
   }
   return members.slice(0, 8);
 }
 
 const _CTRL_KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'do', 'try', 'catch', 'finally', 'else', 'return']);
 
+// Returns members as { text, start, end } where start/end are char offsets
+// WITHIN `block` (end = the method's closing brace), so the caller can resolve
+// per-method line anchors that span the method body.
 function extractClassMembers(block) {
   const members = [];
   // Public methods (skip private/protected/_ prefixed and control-flow keywords)
@@ -186,13 +199,16 @@ function extractClassMembers(block) {
   for (const m of block.matchAll(methodRe)) {
     if (_CTRL_KEYWORDS.has(m[1])) continue;
     if (/^(private|protected|_)/.test(m[1])) continue;
-    if (m[1] === 'constructor') { members.push(`constructor(${normalizeParams(m[2])})`); continue; }
+    const bodyStart = m.index + m[0].length; // just past the opening brace
+    const end = bodyStart + extractBlock(block, bodyStart).length;
+    const start = m.index + (m[0].length - m[0].replace(/^\s+/, '').length);
+    if (m[1] === 'constructor') { members.push({ text: `constructor(${normalizeParams(m[2])})`, start, end }); continue; }
     const isAsync = m[0].includes('async ') ? 'async ' : '';
     const isStatic = m[0].includes('static ') ? 'static ' : '';
     const retMatch = m[0].match(/\)\s*:\s*([^{;]+)\s*\{/);
     const retType = retMatch ? retMatch[1].trim().replace(/\s+/g, ' ').slice(0, 20) : '';
     const retStr = retType ? ` → ${retType}` : '';
-    members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
   }
   return members.slice(0, 8);
 }

package/src/mcp/server.js

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

package/src/verify/hallucination-guard.js

@@ -0,0 +1,219 @@
+'use strict';
+
+/**
+ * Hallucination Guard — deterministic core (Phase 1 MVP).
+ *
+ * Given the text of an AI answer, flag claims that do not match the repo:
+ *   - fake-file   : a referenced path is not on disk
+ *   - fake-import : a relative import does not resolve; a bare import is
+ *                   absent from package.json deps (builtins allow-listed)
+ *   - fake-symbol : a called function/class is absent from the symbol index
+ *
+ * No network, no LLM. Reuses SigMap primitives (buildSigIndex) but every
+ * external dependency is injectable via `opts` so the core stays unit-testable.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const parsers = require('./parsers');
+
+const NODE_BUILTINS = new Set([
+  'fs', 'path', 'os', 'util', 'events', 'stream', 'http', 'https', 'crypto',
+  'child_process', 'url', 'querystring', 'assert', 'zlib', 'readline', 'net',
+  'tls', 'dns', 'buffer', 'process', 'vm', 'module', 'console', 'timers',
+  'string_decoder', 'perf_hooks', 'worker_threads', 'cluster', 'dgram', 'v8',
+  'tty', 'repl', 'async_hooks', 'inspector', 'fs/promises', 'path/posix',
+]);
+
+const PY_BUILTINS = new Set([
+  'os', 'sys', 're', 'json', 'math', 'typing', 'collections', 'itertools',
+  'functools', 'datetime', 'pathlib', 'subprocess', 'abc', 'dataclasses',
+  'enum', 'io', 'time', 'random', 'logging', 'argparse', 'unittest', 'asyncio',
+  'copy', 'hashlib', 'threading', 'string', 'csv', 'glob', 'shutil', 'tempfile',
+]);
+
+const LANG_GLOBALS = new Set([
+  // JS
+  'console', 'require', 'module', 'exports', 'process', 'Object', 'Array',
+  'String', 'Number', 'Boolean', 'Math', 'JSON', 'Date', 'Promise', 'Map',
+  'Set', 'WeakMap', 'WeakSet', 'RegExp', 'Error', 'Symbol', 'parseInt',
+  'parseFloat', 'isNaN', 'setTimeout', 'setInterval', 'clearTimeout', 'fetch',
+  'Buffer', 'Function', 'eval', 'encodeURIComponent', 'decodeURIComponent',
+  // Python
+  'print', 'len', 'range', 'str', 'int', 'float', 'dict', 'list', 'tuple',
+  'set', 'bool', 'open', 'enumerate', 'zip', 'map', 'filter', 'sorted',
+  'sum', 'min', 'max', 'abs', 'isinstance', 'super', 'type', 'getattr',
+  'setattr', 'hasattr',
+]);
+
+const REL_EXTS = ['', '.js', '.ts', '.tsx', '.jsx', '.mjs', '.cjs', '.json', '.py', '.r', '.R', '.vue'];
+const REL_INDEX = ['index.js', 'index.ts', 'index.tsx', 'index.jsx', '__init__.py'];
+
+/** Build the set of known symbol identifiers from the SigMap signature index. */
+function buildSymbolSet(cwd) {
+  const set = new Set();
+  let fileKeys = [];
+  try {
+    const { buildSigIndex } = require('../retrieval/ranker');
+    const idx = buildSigIndex(cwd);
+    fileKeys = [...idx.keys()];
+    for (const sigs of idx.values()) {
+      for (const sig of sigs) {
+        const cleaned = String(sig).replace(/\s*:\d+(?:-\d+)?\s*$/, '');
+        const ids = cleaned.match(/[A-Za-z_$][\w$]*/g) || [];
+        for (const id of ids) set.add(id);
+      }
+    }
+  } catch (_) {}
+  return { set, fileKeys };
+}
+
+/** Load declared dependency names from package.json. */
+function loadDeps(cwd) {
+  const deps = new Set();
+  let hasPkg = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    hasPkg = true;
+    for (const k of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+      if (pkg[k] && typeof pkg[k] === 'object') {
+        for (const name of Object.keys(pkg[k])) deps.add(name);
+      }
+    }
+  } catch (_) {}
+  return { deps, hasPkg };
+}
+
+/** Default file-existence check: resolve a referenced path against cwd. */
+function defaultFileExists(cwd, ref) {
+  const clean = ref.replace(/^\.\//, '');
+  for (const c of [path.resolve(cwd, clean), path.resolve(cwd, ref)]) {
+    try {
+      if (fs.existsSync(c)) return true;
+    } catch (_) {}
+  }
+  return false;
+}
+
+/** Default relative-import resolver: fs candidates + basename match in index. */
+function defaultRelativeResolvable(cwd, mod, fileBasenames) {
+  const base = path.resolve(cwd, mod);
+  for (const e of REL_EXTS) {
+    try {
+      if (fs.existsSync(base + e)) return true;
+    } catch (_) {}
+  }
+  for (const idx of REL_INDEX) {
+    try {
+      if (fs.existsSync(path.join(base, idx))) return true;
+    } catch (_) {}
+  }
+  // Fall back to basename match against the indexed file set (the answer's
+  // import is relative to a file we cannot know, so a name match is enough
+  // to avoid false positives).
+  const wantBase = path.basename(mod).replace(/\.[^.]+$/, '').toLowerCase();
+  return fileBasenames.has(wantBase);
+}
+
+/**
+ * Verify an AI answer against the repository.
+ *
+ * @param {string} answerText
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {Set<string>} [opts.symbolSet]      override known symbols
+ * @param {Set<string>} [opts.deps]           override package deps
+ * @param {boolean}     [opts.hasPkg]         whether a package.json exists
+ * @param {(ref: string) => boolean} [opts.fileExists]          override file check
+ * @param {(mod: string) => boolean} [opts.relativeResolvable]  override rel-import check
+ * @returns {{ issues: object[], summary: object }}
+ */
+function verify(answerText, cwd, opts = {}) {
+  let symbolSet = opts.symbolSet;
+  let fileBasenames = opts.fileBasenames;
+  if (!symbolSet) {
+    const built = buildSymbolSet(cwd);
+    symbolSet = built.set;
+    fileBasenames = new Set(built.fileKeys.map(
+      (k) => path.basename(k).replace(/\.[^.]+$/, '').toLowerCase()
+    ));
+  }
+  if (!fileBasenames) fileBasenames = new Set();
+
+  let deps = opts.deps;
+  let hasPkg = opts.hasPkg;
+  if (!deps) {
+    const loaded = loadDeps(cwd);
+    deps = loaded.deps;
+    if (hasPkg === undefined) hasPkg = loaded.hasPkg;
+  }
+
+  const fileExists = opts.fileExists || ((ref) => defaultFileExists(cwd, ref));
+  const relativeResolvable = opts.relativeResolvable
+    || ((mod) => defaultRelativeResolvable(cwd, mod, fileBasenames));
+
+  const issues = [];
+  const dedupe = new Set();
+  const add = (issue) => {
+    const key = `${issue.type}::${issue.value}`;
+    if (dedupe.has(key)) return;
+    dedupe.add(key);
+    issues.push(issue);
+  };
+
+  // 1. fake-file
+  for (const { path: p, line } of parsers.extractFilePaths(answerText)) {
+    if (!fileExists(p)) {
+      add({ type: 'fake-file', value: p, line, message: `File not found on disk: ${p}` });
+    }
+  }
+
+  // 2. fake-import
+  for (const imp of parsers.extractImports(answerText)) {
+    if (imp.relative) {
+      if (!relativeResolvable(imp.module)) {
+        add({ type: 'fake-import', value: imp.module, line: imp.line, message: `Import does not resolve: ${imp.module}` });
+      }
+      continue;
+    }
+    // Bare module — only verifiable for JS when a package.json exists.
+    const top = imp.module.split('/')[0];
+    if (imp.kind === 'js') {
+      if (!hasPkg) continue;
+      if (NODE_BUILTINS.has(imp.module) || NODE_BUILTINS.has(top)) continue;
+      if (top.startsWith('@')) {
+        const scoped = imp.module.split('/').slice(0, 2).join('/');
+        if (deps.has(scoped) || deps.has(imp.module)) continue;
+      } else if (deps.has(top) || deps.has(imp.module)) {
+        continue;
+      }
+      add({ type: 'fake-import', value: imp.module, line: imp.line, message: `Package not in dependencies: ${imp.module}` });
+    }
+    // Python bare imports: stdlib is unbounded offline — skip to keep precision.
+  }
+
+  // 3. fake-symbol
+  if (symbolSet.size > 0) {
+    for (const { name, line } of parsers.extractSymbols(answerText)) {
+      if (symbolSet.has(name)) continue;
+      if (LANG_GLOBALS.has(name) || NODE_BUILTINS.has(name) || PY_BUILTINS.has(name)) continue;
+      add({ type: 'fake-symbol', value: name, line, message: `Symbol not found in repo index: ${name}()` });
+    }
+  }
+
+  issues.sort((a, b) => a.line - b.line);
+
+  const byType = { 'fake-file': 0, 'fake-import': 0, 'fake-symbol': 0 };
+  for (const i of issues) byType[i.type] = (byType[i.type] || 0) + 1;
+
+  const summary = {
+    total: issues.length,
+    byType,
+    clean: issues.length === 0,
+    symbolsIndexed: symbolSet.size,
+  };
+
+  return { issues, summary };
+}
+
+module.exports = { verify, buildSymbolSet, loadDeps };

package/src/verify/parsers.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * Parsers for the Hallucination Guard (verify-ai-output).
+ *
+ * Extract the verifiable claims an AI answer makes about a codebase:
+ *   - file paths it references
+ *   - import / require statements it shows
+ *   - function / class symbols it calls
+ *   - fenced code blocks (so callers can scope checks to code vs prose)
+ *
+ * Everything here is deterministic and offline — pure string analysis.
+ */
+
+// Extensions we are confident name a source/code/config file (no slash required).
+const KNOWN_CODE_EXT = new Set([
+  'js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'py', 'pyw', 'rb', 'go', 'rs',
+  'java', 'kt', 'swift', 'c', 'h', 'cpp', 'hpp', 'cs', 'php', 'r',
+  'vue', 'svelte', 'css', 'scss', 'less', 'html', 'json', 'yml', 'yaml',
+  'toml', 'xml', 'sql', 'graphql', 'gql', 'proto', 'tf', 'md', 'sh',
+  'gd', 'gdscript',
+]);
+
+/**
+ * Extract fenced code blocks.
+ * @param {string} text
+ * @returns {{ lang: string, content: string, line: number }[]}
+ */
+function extractCodeBlocks(text) {
+  const blocks = [];
+  const lines = text.split('\n');
+  let inBlock = false;
+  let lang = '';
+  let buf = [];
+  let startLine = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^```(\w*)/);
+    if (m) {
+      if (!inBlock) {
+        inBlock = true;
+        lang = m[1] || '';
+        buf = [];
+        startLine = i + 2; // first content line (1-based)
+      } else {
+        blocks.push({ lang, content: buf.join('\n'), line: startLine });
+        inBlock = false;
+      }
+      continue;
+    }
+    if (inBlock) buf.push(lines[i]);
+  }
+  return blocks;
+}
+
+/**
+ * Extract file-path references (deduped, first-seen line kept).
+ * A token counts as a path when it has a `.<letter…>` extension AND
+ * either contains a `/` or carries a known code/config extension.
+ * @param {string} text
+ * @returns {{ path: string, line: number }[]}
+ */
+function extractFilePaths(text) {
+  const lines = text.split('\n');
+  const seen = new Map();
+  const re = /(?:^|[\s`"'(\[<])([A-Za-z0-9_][\w./-]*\.[A-Za-z][A-Za-z0-9]*)/g;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let m;
+    re.lastIndex = 0;
+    while ((m = re.exec(line)) !== null) {
+      const p = m[1];
+      if (/^https?:/i.test(p)) continue;
+      const ext = (p.split('.').pop() || '').toLowerCase();
+      const hasSlash = p.includes('/');
+      if (!hasSlash && !KNOWN_CODE_EXT.has(ext)) continue;
+      if (!seen.has(p)) seen.set(p, i + 1);
+    }
+  }
+  return [...seen.entries()].map(([p, line]) => ({ path: p, line }));
+}
+
+/**
+ * Extract import / require statements.
+ * @param {string} text
+ * @returns {{ module: string, kind: 'js'|'py', relative: boolean, line: number, raw: string }[]}
+ */
+function extractImports(text) {
+  const lines = text.split('\n');
+  const out = [];
+  const push = (module, kind, line, raw) => {
+    if (!module) return;
+    out.push({ module, kind, relative: /^[./]/.test(module), line, raw: raw.trim() });
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let m;
+    // JS/TS: import ... from 'x'  |  export ... from 'x'
+    if ((m = line.match(/\b(?:import|export)\b[^'"]*\bfrom\s*['"]([^'"]+)['"]/))) {
+      push(m[1], 'js', i + 1, line);
+    } else if ((m = line.match(/\bimport\s*['"]([^'"]+)['"]/))) {
+      // side-effect import 'x'
+      push(m[1], 'js', i + 1, line);
+    }
+    // require('x') / dynamic import('x') — may co-occur, scan separately
+    const reqRe = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    let r;
+    while ((r = reqRe.exec(line)) !== null) push(r[1], 'js', i + 1, line);
+
+    // Python: from x import y  |  import x
+    if ((m = line.match(/^\s*from\s+([.\w]+)\s+import\b/))) {
+      push(m[1], 'py', i + 1, line);
+    } else if ((m = line.match(/^\s*import\s+([A-Za-z_][\w.]*)/))) {
+      push(m[1], 'py', i + 1, line);
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract function/class symbol references that look like calls.
+ * Restricted to backtick-wrapped calls (`foo(...)`) for high precision.
+ * @param {string} text
+ * @returns {{ name: string, line: number }[]}
+ */
+function extractSymbols(text) {
+  const lines = text.split('\n');
+  const out = [];
+  const seen = new Set();
+  const re = /`([A-Za-z_$][\w$]*)\s*\([^`]*\)`/g;
+  for (let i = 0; i < lines.length; i++) {
+    let m;
+    re.lastIndex = 0;
+    while ((m = re.exec(lines[i])) !== null) {
+      const name = m[1];
+      const key = name + '@' + (i + 1);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ name, line: i + 1 });
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  extractCodeBlocks,
+  extractFilePaths,
+  extractImports,
+  extractSymbols,
+};