sigmap 6.14.0 → 6.15.0

package/src/verify/hallucination-guard.js

@@ -1,21 +1,31 @@
 'use strict';
 
 /**
- * Hallucination Guard — deterministic core (Phase 1 MVP).
+ * Hallucination Guard — deterministic core (Reliable MVP, v6.15.0).
  *
  * 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
+ *   - fake-file      : a referenced path is not on disk
+ *   - fake-test-file : a referenced *test* path is not on disk (sub-type)
+ *   - 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
+ *   - fake-npm-script: `npm run X` where X is not a package.json script
  *
- * No network, no LLM. Reuses SigMap primitives (buildSigIndex) but every
- * external dependency is injectable via `opts` so the core stays unit-testable.
+ * Each issue carries a `confidence` (detection certainty) and, where a near
+ * match exists, a heuristic `suggestion` ("Did you mean …?"). 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 { closestMatch, buildSymbolCandidates, formatSuggestion } = require('./closest-match');
+
+// A path that looks like a test file (JS/TS spec/test, Python test_/_test, or
+// a tests/__tests__ directory). Used to flag fake-test-file separately.
+const TEST_PATH_RE = /(?:\.(?:test|spec)\.[mc]?[jt]sx?$)|(?:(?:^|\/)__tests__\/)|(?:(?:^|\/)test_[^/]+\.py$)|(?:_test\.py$)|(?:(?:^|\/)tests?\/)/i;
+function isTestPath(p) { return TEST_PATH_RE.test(p); }
 
 const NODE_BUILTINS = new Set([
   'fs', 'path', 'os', 'util', 'events', 'stream', 'http', 'https', 'crypto',
@@ -49,10 +59,14 @@ const LANG_GLOBALS = new Set([
 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. */
+/**
+ * Build the set of known symbol identifiers from the SigMap signature index,
+ * plus `{ name, file, line }` candidates (for closest-match suggestions).
+ */
 function buildSymbolSet(cwd) {
   const set = new Set();
   let fileKeys = [];
+  let symbolCandidates = [];
   try {
     const { buildSigIndex } = require('../retrieval/ranker');
     const idx = buildSigIndex(cwd);
@@ -64,8 +78,9 @@ function buildSymbolSet(cwd) {
         for (const id of ids) set.add(id);
       }
     }
+    symbolCandidates = buildSymbolCandidates(idx);
   } catch (_) {}
-  return { set, fileKeys };
+  return { set, fileKeys, symbolCandidates };
 }
 
 /** Load declared dependency names from package.json. */
@@ -84,6 +99,18 @@ function loadDeps(cwd) {
   return { deps, hasPkg };
 }
 
+/** Load the set of npm script names declared in package.json. */
+function loadScripts(cwd) {
+  const scripts = new Set();
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    if (pkg.scripts && typeof pkg.scripts === 'object') {
+      for (const name of Object.keys(pkg.scripts)) scripts.add(name);
+    }
+  } catch (_) {}
+  return scripts;
+}
+
 /** Default file-existence check: resolve a referenced path against cwd. */
 function defaultFileExists(cwd, ref) {
   const clean = ref.replace(/^\.\//, '');
@@ -118,11 +145,20 @@ function defaultRelativeResolvable(cwd, mod, fileBasenames) {
 /**
  * Verify an AI answer against the repository.
  *
+ * Each issue has the shape:
+ *   { type, value, line, location, message, confidence, suggestion }
+ * where `confidence` is the *detection* certainty ('high' for path/dep/script
+ * checks, 'medium' for symbol checks) and `suggestion` is a heuristic
+ * closest-match hint (or null).
+ *
  * @param {string} answerText
  * @param {string} cwd
  * @param {object} [opts]
  * @param {Set<string>} [opts.symbolSet]      override known symbols
+ * @param {Array}       [opts.symbolCandidates] override { name, file, line } list
+ * @param {Array<string>} [opts.fileCandidates]  override repo file paths (suggestions)
  * @param {Set<string>} [opts.deps]           override package deps
+ * @param {Set<string>} [opts.scripts]        override package.json script names
  * @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
@@ -131,12 +167,16 @@ function defaultRelativeResolvable(cwd, mod, fileBasenames) {
 function verify(answerText, cwd, opts = {}) {
   let symbolSet = opts.symbolSet;
   let fileBasenames = opts.fileBasenames;
+  let symbolCandidates = opts.symbolCandidates || [];
+  let fileCandidates = opts.fileCandidates || [];
   if (!symbolSet) {
     const built = buildSymbolSet(cwd);
     symbolSet = built.set;
     fileBasenames = new Set(built.fileKeys.map(
       (k) => path.basename(k).replace(/\.[^.]+$/, '').toLowerCase()
     ));
+    symbolCandidates = built.symbolCandidates;
+    fileCandidates = built.fileKeys;
   }
   if (!fileBasenames) fileBasenames = new Set();
 
@@ -147,32 +187,47 @@ function verify(answerText, cwd, opts = {}) {
     deps = loaded.deps;
     if (hasPkg === undefined) hasPkg = loaded.hasPkg;
   }
+  const scripts = opts.scripts || (hasPkg ? loadScripts(cwd) : new Set());
 
   const fileExists = opts.fileExists || ((ref) => defaultFileExists(cwd, ref));
   const relativeResolvable = opts.relativeResolvable
     || ((mod) => defaultRelativeResolvable(cwd, mod, fileBasenames));
 
+  // Pre-derive basename candidates for file suggestions (compare on basename so
+  // a wrong directory still surfaces the right file).
+  const fileBasenameCandidates = fileCandidates.map((f) => ({ name: path.basename(f), file: f }));
+
   const issues = [];
   const dedupe = new Set();
   const add = (issue) => {
     const key = `${issue.type}::${issue.value}`;
     if (dedupe.has(key)) return;
     dedupe.add(key);
+    if (!('suggestion' in issue)) issue.suggestion = null;
+    issue.location = `L${issue.line}`;
     issues.push(issue);
   };
 
-  // 1. fake-file
+  // 1. fake-file / fake-test-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}` });
-    }
+    if (fileExists(p)) continue;
+    const isTest = isTestPath(p);
+    const match = closestMatch(path.basename(p), fileBasenameCandidates, { minLen: 4 });
+    add({
+      type: isTest ? 'fake-test-file' : 'fake-file',
+      value: p,
+      line,
+      message: `${isTest ? 'Test file' : 'File'} not found on disk: ${p}`,
+      confidence: 'high',
+      suggestion: match ? formatSuggestion(match, false) : null,
+    });
   }
 
   // 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}` });
+        add({ type: 'fake-import', value: imp.module, line: imp.line, message: `Import does not resolve: ${imp.module}`, confidence: 'high' });
       }
       continue;
     }
@@ -187,7 +242,15 @@ function verify(answerText, cwd, opts = {}) {
       } 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}` });
+      const match = closestMatch(top, [...deps], { minLen: 3 });
+      add({
+        type: 'fake-import',
+        value: imp.module,
+        line: imp.line,
+        message: `Package not in dependencies: ${imp.module}`,
+        confidence: 'high',
+        suggestion: match ? formatSuggestion({ name: match.name }, false) : null,
+      });
     }
     // Python bare imports: stdlib is unbounded offline — skip to keep precision.
   }
@@ -197,13 +260,40 @@ function verify(answerText, cwd, opts = {}) {
     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}()` });
+      const match = closestMatch(name, symbolCandidates, { minLen: 4 });
+      add({
+        type: 'fake-symbol',
+        value: name,
+        line,
+        message: `Symbol not found in repo index: ${name}()`,
+        confidence: 'medium',
+        suggestion: match ? formatSuggestion(match, true) : null,
+      });
+    }
+  }
+
+  // 4. fake-npm-script
+  if (hasPkg && scripts.size > 0) {
+    for (const { name, line } of parsers.extractNpmScripts(answerText)) {
+      if (scripts.has(name)) continue;
+      const match = closestMatch(name, [...scripts], { minLen: 2 });
+      add({
+        type: 'fake-npm-script',
+        value: name,
+        line,
+        message: `npm script not in package.json: ${name}`,
+        confidence: 'high',
+        suggestion: match ? formatSuggestion({ name: match.name }, false) : null,
+      });
     }
   }
 
   issues.sort((a, b) => a.line - b.line);
 
-  const byType = { 'fake-file': 0, 'fake-import': 0, 'fake-symbol': 0 };
+  const byType = {
+    'fake-file': 0, 'fake-test-file': 0, 'fake-import': 0,
+    'fake-symbol': 0, 'fake-npm-script': 0,
+  };
   for (const i of issues) byType[i.type] = (byType[i.type] || 0) + 1;
 
   const summary = {
@@ -211,9 +301,10 @@ function verify(answerText, cwd, opts = {}) {
     byType,
     clean: issues.length === 0,
     symbolsIndexed: symbolSet.size,
+    withSuggestion: issues.filter((i) => i.suggestion).length,
   };
 
   return { issues, summary };
 }
 
-module.exports = { verify, buildSymbolSet, loadDeps };
+module.exports = { verify, buildSymbolSet, loadDeps, loadScripts, isTestPath };

package/src/verify/parsers.js

@@ -106,6 +106,11 @@ function extractImports(text) {
     let r;
     while ((r = reqRe.exec(line)) !== null) push(r[1], 'js', i + 1, line);
 
+    // TS: import X = require('mod')
+    if ((m = line.match(/\bimport\s+[A-Za-z_$][\w$]*\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/))) {
+      push(m[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);
@@ -113,6 +118,51 @@ function extractImports(text) {
       push(m[1], 'py', i + 1, line);
     }
   }
+
+  // Multi-line JS/TS imports, e.g.
+  //   import {
+  //     A as B,
+  //   } from './mod';
+  // The per-line pass above misses these because `from '…'` sits on a later
+  // line. Trigger only when the opening line has no quote and no `from` yet,
+  // then gather forward until the source string appears.
+  for (let i = 0; i < lines.length; i++) {
+    const start = lines[i];
+    if (!/^\s*(?:import|export)\b/.test(start)) continue;
+    if (/['"]/.test(start) || /\bfrom\b/.test(start)) continue; // single-line, already handled
+    let joined = start;
+    for (let j = i + 1; j < Math.min(lines.length, i + 12); j++) {
+      joined += ' ' + lines[j];
+      const fm = joined.match(/\bfrom\s*['"]([^'"]+)['"]/);
+      if (fm) { push(fm[1], 'js', i + 1, start.trim()); break; }
+      if (/['"]/.test(lines[j]) && !/\bfrom\b/.test(joined)) break; // a string that isn't a source — bail
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract npm/pnpm/yarn script invocations (`npm run <name>`).
+ * Only the explicit `run` form is matched, to avoid confusing package-manager
+ * subcommands (`yarn add`, `pnpm install`) with script names.
+ * @param {string} text
+ * @returns {{ name: string, line: number }[]}
+ */
+function extractNpmScripts(text) {
+  const lines = text.split('\n');
+  const out = [];
+  const seen = new Set();
+  const re = /\b(?:npm|pnpm|yarn)\s+run(?:-script)?\s+([A-Za-z0-9:_-]+)/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];
+      if (seen.has(name)) continue;
+      seen.add(name);
+      out.push({ name, line: i + 1 });
+    }
+  }
   return out;
 }
 
@@ -146,4 +196,5 @@ module.exports = {
   extractFilePaths,
   extractImports,
   extractSymbols,
+  extractNpmScripts,
 };