sigmap 8.9.1 → 8.11.0

package/llms-full.txt

@@ -11,13 +11,13 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.9.1 | Benchmark: sigmap-v8.9-main (2026-07-06)
+# Version: 8.11.0 | Benchmark: sigmap-v8.11-main (2026-07-11)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.9-main, 2026-07-06)
+## Core metrics (benchmark: sigmap-v8.11-main, 2026-07-11)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -55,6 +55,7 @@ sigmap                                   Generate context once and exit
 sigmap --monorepo                        Generate per-package context (monorepo)
 sigmap --each                            Run for every repo in the current directory
 sigmap --routing                         Include model routing hints in output
+sigmap --terse                           Compact signature encoding (deterministic; line anchors preserved)
 sigmap --format cache                    Also write Anthropic prompt-cache JSON
 sigmap --track                           Append run metrics to .context/usage.ndjson
 sigmap --watch                           Generate + watch for file changes
@@ -325,6 +326,7 @@ tracking = false
 mcp = {"autoRegister":true}
 depMap = true
 versionPins = true
+terse = false
 todos = true
 changes = true
 changesCommits = 10

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.9.1 | Benchmark: sigmap-v8.9-main (2026-07-06)
+# Version: 8.11.0 | Benchmark: sigmap-v8.11-main (2026-07-11)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,7 +23,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.9-main, 2026-07-06)
+## Core metrics (benchmark: sigmap-v8.11-main, 2026-07-11)
 
 - hit@5 retrieval: 87.8% vs 13.6% random baseline (6.5× lift)
 - Token reduction: 97.0% average across benchmark repos

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sigmap",
-  "version": "8.9.1",
-  "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
+  "version": "8.11.0",
+  "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {
     ".": "./packages/core/index.js",
@@ -29,6 +29,7 @@
     "benchmark:verify": "node scripts/run-verify-benchmark.mjs",
     "benchmark:squeeze": "node scripts/run-squeeze-benchmark.mjs --save",
     "benchmark:test-discovery": "node scripts/run-test-discovery-benchmark.mjs --save",
+    "benchmark:terse": "node scripts/run-terse-benchmark.mjs --save",
     "validate:squeeze": "node scripts/run-squeeze-benchmark.mjs --gate",
     "health": "node gen-context.js --health",
     "map": "node gen-project-map.js",
@@ -80,7 +81,13 @@
     "mcp",
     "function-signatures",
     "code-intelligence",
-    "context-compression",
+    "ai-grounding",
+    "hallucination-detection",
+    "deterministic",
+    "verifiable-ai",
+    "code-signatures",
+    "ai-code-review",
+    "evidence-pack",
     "local-llm",
     "ollama",
     "ai-coding"

package/packages/cli/package.json

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

package/src/config/defaults.js

@@ -117,6 +117,9 @@ const DEFAULTS = {
   // Include a compact `name@version` list of installed direct deps (D8)
   versionPins: true,
 
+  // Terse signature encoding — deterministic compaction of sig lines (D7, opt-in)
+  terse: false,
+
   // Include TODO/FIXME/HACK/XXX comments as compact section
   todos: true,
 

package/src/conventions/extract.js

@@ -26,8 +26,16 @@ const TIER_MOSTLY = 0.7;
 
 /**
  * Classify a file's base name (without extension) into a naming style.
+ *
+ * A single lowercase word (`user`, `index`, `loader`) is classified
+ * `single-word`, NOT `camelCase`: it has no case boundary or separator, so it is
+ * compatible with camelCase, kebab-case AND snake_case at once and expresses no
+ * distinguishable convention. `scoreConvention` treats it as style-neutral
+ * (excluded), so a repo of single-word files reports "unknown" rather than a
+ * spurious "100% camelCase".
+ *
  * @param {string} basename a file basename, e.g. "user-service.ts"
- * @returns {'PascalCase'|'camelCase'|'kebab-case'|'snake_case'|'other'}
+ * @returns {'PascalCase'|'camelCase'|'kebab-case'|'snake_case'|'single-word'|'other'}
  */
 function classifyNaming(basename) {
   let stem = String(basename || '');
@@ -38,7 +46,7 @@ function classifyNaming(basename) {
   if (/[_]/.test(stem) && /^[a-z0-9]+(?:_[a-z0-9]+)+$/.test(stem)) return 'snake_case';
   if (/^[A-Z][A-Za-z0-9]*$/.test(stem) && /[a-z]/.test(stem)) return 'PascalCase';
   if (/^[a-z][A-Za-z0-9]*$/.test(stem) && /[A-Z]/.test(stem)) return 'camelCase';
-  if (/^[a-z][a-z0-9]*$/.test(stem)) return 'camelCase'; // single lowercase word
+  if (/^[a-z][a-z0-9]*$/.test(stem)) return 'single-word'; // style-neutral (no case boundary)
   return 'other';
 }
 
@@ -61,7 +69,9 @@ function scoreConvention(labels, refs) {
   let total = 0;
   for (let i = 0; i < all.length; i++) {
     const l = all[i];
-    if (l == null || l === 'other') continue;
+    // 'other' = unclassifiable; 'single-word' = style-neutral. Both express no
+    // distinguishable convention and are excluded from the score.
+    if (l == null || l === 'other' || l === 'single-word') continue;
     total++;
     counts.set(l, (counts.get(l) || 0) + 1);
     if (refs && refs[i] != null) {

package/src/conventions/fix.js

@@ -47,7 +47,10 @@ function buildFixList(cwd, files, conventions) {
     if (TEST_RE.test(f)) continue;
     const base = path.basename(f);
     const style = classifyNaming(base);
-    if (style === 'other' || style === dominant) continue;
+    // Skip unclassifiable ('other') and style-neutral single-word names — a
+    // single lowercase word already satisfies any convention, so renaming it
+    // (e.g. user.js → user.js) is a no-op at best and noise at worst.
+    if (style === 'other' || style === 'single-word' || style === dominant) continue;
     const rel = path.relative(cwd, f).replace(/\\/g, '/');
     renames.push({ from: rel, to: _renamePath(rel, dominant), fromStyle: style });
   }

package/src/extractors/javascript.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { lineAt, withAnchor } = require('./line-anchor');
+const { capWithNotice, capMembersWithNotice } = require('../util/truncate');
 
 /**
  * Extract signatures from JavaScript source code.
@@ -80,9 +81,8 @@ function extract(src) {
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
-  return sigs
-    .map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s))
-    .slice(0, 25);
+  const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+  return capWithNotice(withAnchors, 25, 'signatures');
 }
 
 function extractBlock(src, startIndex) {
@@ -113,7 +113,7 @@ function extractClassMembers(block, returnHints) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
   }
-  return members.slice(0, 8);
+  return capMembersWithNotice(members, 8, 'methods');
 }
 
 function buildReturnHints(src) {

package/src/extractors/typescript.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { lineAt, withAnchor } = require('./line-anchor');
+const { capWithNotice, capMembersWithNotice } = require('../util/truncate');
 
 /**
  * Extract signatures from TypeScript source code.
@@ -152,9 +153,8 @@ function extract(src) {
     }
   }
 
-  return sigs
-    .map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s))
-    .slice(0, 35);
+  const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+  return capWithNotice(withAnchors, 35, 'signatures');
 }
 
 function extractBlock(src, startIndex) {
@@ -184,7 +184,7 @@ function extractInterfaceMembers(block) {
     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);
+  return capMembersWithNotice(members, 8, 'members');
 }
 
 const _CTRL_KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'do', 'try', 'catch', 'finally', 'else', 'return']);
@@ -210,7 +210,7 @@ function extractClassMembers(block) {
     const retStr = retType ? ` → ${retType}` : '';
     members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
   }
-  return members.slice(0, 8);
+  return capMembersWithNotice(members, 8, 'methods');
 }
 
 function normalizeParams(params) {

package/src/format/terse.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Terse signature encoder (D7).
+ *
+ * Deterministic compaction of signature lines for the generated context —
+ * opt-in via `--terse` / `terse: true`. Every transform is a fixed string
+ * rewrite (no heuristics, no LLM), so terse output stays byte-stable.
+ *
+ * The line anchor (`  :start-end`) and everything after it (Python/R doc
+ * hints) are preserved byte-exactly: `parseAnchor`, `get_lines`, and the
+ * evidence pack keep working on terse output. Symbol extraction is safe too —
+ * `extractName` in src/extractors/prdiff.js already recognizes `fn <name>`.
+ */
+
+/** First `  :start[-end]` anchor token (two-space prefix, as emitted by line-anchor.js). */
+const ANCHOR_RE = /\s{2}:\d+(?:-\d+)?(?=\s|$)/;
+
+/**
+ * Split a signature into the compactable text and the byte-preserved suffix
+ * (anchor + any trailing doc hint).
+ * @param {string} sig
+ * @returns {{ text: string, suffix: string }}
+ */
+function splitAnchor(sig) {
+  const s = String(sig);
+  const m = ANCHOR_RE.exec(s);
+  if (!m) return { text: s, suffix: '' };
+  return { text: s.slice(0, m.index), suffix: s.slice(m.index) };
+}
+
+/**
+ * Compact one signature line. Leading whitespace (member indentation) is kept.
+ * @param {string} sig
+ * @returns {string}
+ */
+function encodeTerseSig(sig) {
+  const { text, suffix } = splitAnchor(sig);
+  let t = text
+    .replace(/\basync function\b/g, 'async fn')
+    .replace(/\bfunction\b/g, 'fn')
+    .replace(/\s+→\s+/g, '→')
+    .replace(/,\s+/g, ',')
+    .replace(/\s+=\s+/g, '=')
+    .replace(/\{\s+/g, '{')
+    .replace(/\s+\}/g, '}')
+    .replace(/(\S)\s{2,}(?=\S)/g, '$1 ')
+    .replace(/^module\.exports=/, 'exports=');
+  return t + suffix;
+}
+
+/**
+ * Compact an array of signature lines.
+ * @param {string[]} sigs
+ * @returns {string[]}
+ */
+function encodeTerseSigs(sigs) {
+  return (sigs || []).map(encodeTerseSig);
+}
+
+/** Estimated tokens of joined signature lines (same chars/4 rule as elsewhere). */
+function _tokens(sigs) {
+  return Math.ceil(sigs.join('\n').length / 4);
+}
+
+/**
+ * Measure the real reduction terse encoding buys over a set of signature
+ * lists — the D7 "measure first" gate. Never quote a number this didn't produce.
+ * @param {string[][]} sigsList one string[] per file
+ * @returns {{ beforeTokens: number, afterTokens: number, reductionPct: number }}
+ */
+function measureTerse(sigsList) {
+  let beforeTokens = 0;
+  let afterTokens = 0;
+  for (const sigs of sigsList || []) {
+    if (!sigs || !sigs.length) continue;
+    beforeTokens += _tokens(sigs);
+    afterTokens += _tokens(encodeTerseSigs(sigs));
+  }
+  const reductionPct = beforeTokens > 0
+    ? Math.round(((beforeTokens - afterTokens) / beforeTokens) * 1000) / 10
+    : 0;
+  return { beforeTokens, afterTokens, reductionPct };
+}
+
+module.exports = { encodeTerseSig, encodeTerseSigs, measureTerse, splitAnchor };

package/src/graph/builder.js

@@ -31,20 +31,19 @@ const RB_EXTS  = new Set(['.rb', '.rake']);
 const R_EXTS   = new Set(['.r', '.R']);
 
 /**
- * Resolve a JS/TS relative import string to an absolute path in fileSet.
- * @param {string} dir - directory of the importing file
- * @param {string} importStr - raw import string (e.g. './utils', '../store')
+ * Probe an absolute base path for a JS/TS module file in fileSet, trying the
+ * usual extension and index-file candidates.
+ * @param {string} base - absolute path (no extension) to probe
  * @param {Set<string>} fileSet
  * @returns {string|null}
  */
-function resolveJsPath(dir, importStr, fileSet) {
-  const base = path.resolve(dir, importStr);
+function probeJs(base, fileSet) {
   const candidates = [
     base,
     base + '.ts', base + '.tsx',
     base + '.js', base + '.jsx', base + '.mjs', base + '.cjs',
-    path.join(base, 'index.ts'),
-    path.join(base, 'index.js'),
+    path.join(base, 'index.ts'), path.join(base, 'index.tsx'),
+    path.join(base, 'index.js'), path.join(base, 'index.jsx'),
   ];
   for (const c of candidates) {
     const normC = normalizePath(c);
@@ -53,6 +52,103 @@ function resolveJsPath(dir, importStr, fileSet) {
   return null;
 }
 
+/**
+ * Resolve a JS/TS relative import string to an absolute path in fileSet.
+ * @param {string} dir - directory of the importing file
+ * @param {string} importStr - raw import string (e.g. './utils', '../store')
+ * @param {Set<string>} fileSet
+ * @returns {string|null}
+ */
+function resolveJsPath(dir, importStr, fileSet) {
+  return probeJs(path.resolve(dir, importStr), fileSet);
+}
+
+/**
+ * Strip comments and trailing commas so a tsconfig/jsconfig (JSONC) parses.
+ * Deliberately conservative — leaves string contents alone.
+ */
+function stripJsonc(src) {
+  let out = '';
+  let inStr = false, quote = '', inLine = false, inBlock = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i], n = src[i + 1];
+    if (inLine) { if (c === '\n') { inLine = false; out += c; } continue; }
+    if (inBlock) { if (c === '*' && n === '/') { inBlock = false; i++; } continue; }
+    if (inStr) { out += c; if (c === '\\') { out += (n || ''); i++; } else if (c === quote) inStr = false; continue; }
+    if (c === '"' || c === "'") { inStr = true; quote = c; out += c; continue; }
+    if (c === '/' && n === '/') { inLine = true; i++; continue; }
+    if (c === '/' && n === '*') { inBlock = true; i++; continue; }
+    out += c;
+  }
+  // remove trailing commas before } or ]
+  return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
+/**
+ * Load the JS/TS path-alias map from tsconfig.json / jsconfig.json.
+ * Resolves `compilerOptions.paths` and `baseUrl` into absolute target bases so
+ * bare/aliased imports (e.g. `@/utils`, `components/Button`) can be resolved to
+ * on-disk files. Returns null when no config or no aliasing is configured.
+ *
+ * @param {string} cwd
+ * @returns {{ baseUrl: string|null, entries: Array<{prefix:string,wildcard:boolean,targets:string[]}> }|null}
+ */
+function loadAliasMap(cwd) {
+  if (!cwd) return null;
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    let json;
+    try { json = JSON.parse(stripJsonc(fs.readFileSync(path.join(cwd, name), 'utf8'))); }
+    catch (_) { continue; }
+    const co = (json && json.compilerOptions) || {};
+    const baseUrl = co.baseUrl ? path.resolve(cwd, co.baseUrl) : null;
+    const base = baseUrl || cwd;
+    const entries = [];
+    for (const [pattern, targets] of Object.entries(co.paths || {})) {
+      const wildcard = pattern.includes('*');
+      const prefix = pattern.replace(/\*.*$/, '');
+      const tgs = (Array.isArray(targets) ? targets : [])
+        .map((t) => path.resolve(base, String(t).replace(/\*.*$/, '')));
+      if (tgs.length) entries.push({ prefix, wildcard, targets: tgs });
+    }
+    if (baseUrl || entries.length) return { baseUrl, entries };
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Resolve a non-relative JS/TS import specifier through the alias map.
+ * @param {string} spec - e.g. '@/utils', '@app/Button', 'components/Nav'
+ * @param {object|null} aliasMap - from loadAliasMap
+ * @param {Set<string>} fileSet
+ * @returns {string|null}
+ */
+function resolveAlias(spec, aliasMap, fileSet) {
+  if (!aliasMap) return null;
+  for (const e of aliasMap.entries) {
+    if (e.wildcard) {
+      if (spec.startsWith(e.prefix)) {
+        const rest = spec.slice(e.prefix.length);
+        for (const t of e.targets) {
+          const r = probeJs(rest ? path.join(t, rest) : t, fileSet);
+          if (r) return r;
+        }
+      }
+    } else if (spec === e.prefix) {
+      for (const t of e.targets) {
+        const r = probeJs(t, fileSet);
+        if (r) return r;
+      }
+    }
+  }
+  // Bare import resolved from baseUrl (tsconfig baseUrl without an explicit alias).
+  if (aliasMap.baseUrl) {
+    const r = probeJs(path.join(aliasMap.baseUrl, spec), fileSet);
+    if (r) return r;
+  }
+  return null;
+}
+
 /**
  * Resolve an R `source(...)` argument to an absolute path in fileSet.
  * Tries the dir-relative path first, then a cwd-relative path so that
@@ -98,21 +194,29 @@ function extractFileDeps(filePath, content, fileSet, cwd, ctx) {
 
   // ── JS / TS ───────────────────────────────────────────────────────────────
   if (JS_EXTS.has(ext)) {
+    const aliasMap = ctx && ctx.aliasMap;
+    // Resolve any specifier: relative → dir-relative; otherwise via tsconfig/
+    // jsconfig path aliases + baseUrl. Bare npm packages (react, lodash) fall
+    // through to null because they are not in fileSet, so no false edges.
+    const resolveSpec = (spec) => spec.startsWith('.')
+      ? resolveJsPath(dir, spec, fileSet)
+      : resolveAlias(spec, aliasMap, fileSet);
+
     const stripped = content
       .replace(/\/\/.*$/gm, '')
       .replace(/\/\*[\s\S]*?\*\//g, '');
 
-    // ES imports:   import ... from './foo'  or  import './side-effect'
-    const reEs = /(?:^|[\r\n])\s*import\s+(?:[^'";\r\n]*?\s+from\s+)?['"](\.[^'"]+)['"]/g;
     let m;
+    // ES imports:  import ... from 'x'  |  import 'x'  |  export ... from 'x'
+    const reEs = /(?:^|[\r\n])\s*(?:import|export)\s+(?:[^'";\r\n]*?\s+from\s+)?['"]([^'"]+)['"]/g;
     while ((m = reEs.exec(stripped)) !== null) {
-      const r = resolveJsPath(dir, m[1], fileSet);
+      const r = resolveSpec(m[1]);
       if (r) found.push(r);
     }
-    // CommonJS: require('./foo')
-    const reCjs = /\brequire\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
-    while ((m = reCjs.exec(stripped)) !== null) {
-      const r = resolveJsPath(dir, m[1], fileSet);
+    // CommonJS require('x') and dynamic import('x').
+    const reCall = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((m = reCall.exec(stripped)) !== null) {
+      const r = resolveSpec(m[1]);
       if (r) found.push(r);
     }
   }
@@ -284,6 +388,10 @@ function build(files, cwd, ctx) {
   const fileSet = new Set(files.map((f) => path.resolve(f)));
   // Create a normalized version for cross-platform case-insensitive lookups
   const fileSetNormalized = new Set([...fileSet].map(normalizePath));
+  // Resolve the JS/TS path-alias map once (tsconfig/jsconfig paths + baseUrl),
+  // unless a caller supplied one explicitly via ctx.
+  const aliasMap = (ctx && 'aliasMap' in ctx) ? ctx.aliasMap : loadAliasMap(cwd);
+  const effectiveCtx = Object.assign({}, ctx, { aliasMap });
   const forward = new Map();
   const reverse = new Map();
 
@@ -304,7 +412,7 @@ function build(files, cwd, ctx) {
     }
 
     const normFilePath = normalizePath(filePath);
-    const deps = extractFileDeps(filePath, content, fileSetNormalized, cwd, ctx);
+    const deps = extractFileDeps(filePath, content, fileSetNormalized, cwd, effectiveCtx);
     if (deps.length > 0) {
       forward.set(normFilePath, deps);
       for (const dep of deps) {
@@ -383,4 +491,4 @@ function buildFromCwd(cwd, opts) {
   return build(files, cwd, ctx);
 }
 
-module.exports = { build, buildFromCwd, extractFileDeps, normalizePath };
+module.exports = { build, buildFromCwd, extractFileDeps, normalizePath, loadAliasMap, resolveAlias };

package/src/graph/impact.js

@@ -186,11 +186,11 @@ function formatImpact(result) {
   lines.push('');
 
   if (result.direct.length === 0 && result.transitive.length === 0) {
-    lines.push('_No files import this file — zero blast radius._');
+    lines.push('_No importers found via relative + aliased imports (lower bound — dynamic/computed imports are not tracked)._');
     return lines.join('\n');
   }
 
-  lines.push(`**Total impacted files:** ${result.totalImpact}`);
+  lines.push(`**Total impacted files:** ${result.totalImpact} _(lower bound — resolves relative + tsconfig/jsconfig-aliased imports)_`);
   lines.push('');
 
   if (result.direct.length > 0) {