sigmap 3.6.0 → 4.0.0

package/AGENTS.md

@@ -12,35 +12,40 @@ Use this marker block for all appendable context files:
 ## Auto-generated signatures
 <!-- Updated by gen-context.js -->
 You are a coding assistant with full knowledge of this codebase.
-Below are the code signatures extracted by SigMap v3.5.1 on 2026-04-14T23:05:11.451Z.
+Below are the code signatures extracted by SigMap v4.0.0 on 2026-04-15T05:40:32.012Z.
 
 Use these signatures to answer questions about the code accurately.
 
 ## Code Signatures
 
-<!-- Generated by SigMap gen-context.js v3.5.1 -->
+<!-- Generated by SigMap gen-context.js v4.0.0 -->
 <!-- DO NOT EDIT below the marker line — run gen-context.js to regenerate -->
 
 # Code signatures
 
+## changes (last 5 commits — 6 hours ago)
+```
+src/extractors/generic.js                     +extract
+src/format/llm-txt.js                         +outputPath  +format
+src/format/llms-txt.js                        +outputPath  +getShortCommit  +detectVersion  +format
+packages/adapters/llm-full.js                 +outputPath  +format  +write
+```
+
 ## packages
 
-### packages/core/index.js
+### packages/adapters/llm-full.js
 ```
-module.exports = { extract, rank, buildSigIndex, scan, score, adapt }
-function _resolveExtractor(language)
-function extract(src, language) → string[]
-function rank(query, sigIndex, opts) → { file: string, score: nu
-function buildSigIndex(cwd) → Map<string, string[]>
-function scan(sigs, filePath) → { safe: string[], redacte
-function score(cwd) → { * score: number, * grad
-function adapt(context, adapterName, opts = {}) → string
+module.exports = { name: 'llm-full', format, outputPath, write }
+function outputPath(cwd)
+function format(context, opts)
+function write(context, cwd, opts)
 ```
 
 ### packages/adapters/claude.js
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
@@ -57,6 +62,7 @@ function write(context, cwd, opts = {})
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
@@ -65,6 +71,7 @@ function write(context, cwd, opts = {})
 ```
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 ```
 
@@ -74,6 +81,7 @@ module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
+function _confidenceMeta(opts)
 ```
 
 ### packages/adapters/index.js
@@ -85,25 +93,19 @@ function adapt(context, adapterName, opts = {}) → string
 function outputsToAdapters(outputs) → string[]
 ```
 
-### packages/adapters/llm-full.js
-```
-module.exports = { name: 'llm-full', format, outputPath, write }
-function outputPath(cwd)
-function format(context, opts)
-function write(context, cwd, opts)
-```
-
 ### packages/adapters/openai.js
 ```
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
 function outputPath(cwd) → string
+function _confidenceMeta(opts)
 ```
 
 ### packages/adapters/windsurf.js
 ```
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 ```
 
@@ -133,8 +135,49 @@ code-fence js
 code-fence ---
 ```
 
+### packages/core/index.js
+```
+module.exports = { extract, rank, buildSigIndex, scan, score, adapt }
+function _resolveExtractor(language)
+function extract(src, language) → string[]
+function rank(query, sigIndex, opts) → { file: string, score: nu
+function buildSigIndex(cwd) → Map<string, string[]>
+function scan(sigs, filePath) → { safe: string[], redacte
+function score(cwd) → { * score: number, * grad
+function adapt(context, adapterName, opts = {}) → string
+```
+
 ## src
 
+### src/extractors/generic.js
+```
+module.exports = { extract }
+function extract(src)
+```
+
+### src/format/llm-txt.js
+```
+module.exports = { format, outputPath }
+function outputPath(cwd)
+function format(context, cwd, version)
+```
+
+### src/format/llms-txt.js
+```
+module.exports = { format, outputPath }
+function outputPath(cwd)
+function getShortCommit(cwd)
+function detectVersion(cwd)
+function format(context, cwd, writtenFiles, sigmapVersion)
+```
+
+### src/analysis/coverage-score.js
+```
+module.exports = { coverageScore }
+function coverageScore(cwd, fileEntries, config) → { * score: number, * grad
+function _walk(dir, excludeSet, out)
+```
+
 ### src/config/defaults.js
 ```
 module.exports = { DEFAULTS }
@@ -161,63 +204,6 @@ function formatAnalysisTable(stats, showSlow) → string
 function formatAnalysisJSON(stats) → object
 ```
 
-### src/extractors/markdown.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/patterns.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/properties.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/python_dataclass.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/toml.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/typescript_react.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/vue_sfc.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/xml.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/mcp/server.js
-```
-module.exports = { start }
-function respond(id, result)
-function respondError(id, code, message)
-function dispatch(msg, cwd)
-function start(cwd)
-```
-
 ### src/eval/runner.js
 ```
 module.exports = { run, rank, loadTasks, buildSigIndex, formatTable, formatMetrics, tokenize }
@@ -301,12 +287,6 @@ module.exports = { extract }
 function extract(src) → string[]
 ```
 
-### src/extractors/generic.js
-```
-module.exports = { extract }
-function extract(src)
-```
-
 ### src/extractors/go.js
 ```
 module.exports = { extract }
@@ -359,6 +339,18 @@ function extractMembers(block)
 function normalizeParams(params)
 ```
 
+### src/extractors/markdown.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
+### src/extractors/patterns.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/php.js
 ```
 module.exports = { extract }
@@ -376,6 +368,12 @@ function diffSignatures(baseSigs, currentSigs) → {added:string[], removed:
 function extractName(sig)
 ```
 
+### src/extractors/properties.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/protobuf.js
 ```
 module.exports = { extract }
@@ -395,6 +393,12 @@ function normalizeParams(params)
 function extractDocHint(src, fnName, fnSigLine)
 ```
 
+### src/extractors/python_dataclass.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/ruby.js
 ```
 module.exports = { extract }
@@ -467,6 +471,12 @@ module.exports = { extractTodos }
 function extractTodos(src) → {line:number, tag:string,
 ```
 
+### src/extractors/toml.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/typescript.js
 ```
 module.exports = { extract }
@@ -477,6 +487,12 @@ function extractClassMembers(block)
 function normalizeParams(params)
 ```
 
+### src/extractors/typescript_react.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/vue.js
 ```
 module.exports = { extract }
@@ -485,6 +501,18 @@ function normalizeParams(params)
 function normalizeType(type)
 ```
 
+### src/extractors/vue_sfc.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
+### src/extractors/xml.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/yaml.js
 ```
 module.exports = { extract }
@@ -518,22 +546,6 @@ function generateDashboardHtml(cwd, health)
 function renderHistoryCharts(cwd, health)
 ```
 
-### src/format/llm-txt.js
-```
-module.exports = { format, outputPath }
-function outputPath(cwd)
-function format(context, cwd, version)
-```
-
-### src/format/llms-txt.js
-```
-module.exports = { format, outputPath }
-function outputPath(cwd)
-function getShortCommit(cwd)
-function detectVersion(cwd)
-function format(context, cwd, writtenFiles, sigmapVersion)
-```
-
 ### src/graph/builder.js
 ```
 module.exports = { build, buildFromCwd, extractFileDeps }
@@ -597,6 +609,15 @@ function queryContext(args, cwd)
 function getImpact(args, cwd)
 ```
 
+### src/mcp/server.js
+```
+module.exports = { start }
+function respond(id, result)
+function respondError(id, code, message)
+function dispatch(msg, cwd)
+function start(cwd)
+```
+
 ### src/mcp/tools.js
 ```
 module.exports = { TOOLS }

package/gen-context.js

@@ -4478,7 +4478,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '3.5.0',
+    version: '4.0.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -6040,7 +6040,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '3.6.0';
+const VERSION = '4.0.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -6276,13 +6276,17 @@ function applyTokenBudget(fileEntries, maxTokens) {
     else if (isTestFile(e.filePath)) { priority = 8;  dropReason = 'budget: test file'; }
     else if (isConfigFile(e.filePath)) { priority = 6; dropReason = 'budget: config file'; }
     else priority = 4;
-    return { ...e, priority, dropReason };
+    // v4.0: signal quality = sigs per line-of-code (higher = more informative)
+    const loc = e.content ? e.content.split('\n').length : 1;
+    const signalQuality = loc > 0 ? (e.sigs ? e.sigs.length : 0) / loc : 0;
+    return { ...e, priority, dropReason, signalQuality };
   });
 
-  // Within same priority, sort by mtime ascending (oldest first = drop first)
+  // Within same priority: sort by mtime ascending (oldest first), then signalQuality ascending (least informative first)
   withPriority.sort((a, b) => {
     if (b.priority !== a.priority) return b.priority - a.priority;
-    return (a.mtime || 0) - (b.mtime || 0);
+    if ((a.mtime || 0) !== (b.mtime || 0)) return (a.mtime || 0) - (b.mtime || 0);
+    return (a.signalQuality || 0) - (b.signalQuality || 0);
   });
 
   const kept = [];
@@ -6716,11 +6720,17 @@ function writeClaude(content, cwd) {
 // ---------------------------------------------------------------------------
 // Report
 // ---------------------------------------------------------------------------
-function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson, budgetLimit) {
+function _coverageBar(pct, width) {
+  width = width || 16;
+  const filled = Math.round(pct / 100 * width);
+  return '\u2588'.repeat(filled) + '\u2591'.repeat(width - filled);
+}
+
+function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson, budgetLimit, coverageResult) {
   const reduction = inputTokens > 0 ? (100 - (finalTokens / inputTokens) * 100).toFixed(1) : 0;
   const overBudget = finalTokens > (budgetLimit || 6000);
   if (asJson) {
-    process.stdout.write(JSON.stringify({
+    const payload = {
       version: VERSION,
       timestamp: new Date().toISOString(),
       rawTokens: inputTokens,
@@ -6731,7 +6741,22 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
       reductionPct: parseFloat(reduction),
       overBudget,
       budgetLimit: budgetLimit || 6000,
-    }) + '\n');
+    };
+    if (coverageResult) {
+      payload.coverage = {
+        score: coverageResult.score,
+        grade: coverageResult.grade,
+        confidence: coverageResult.confidence,
+        totalFiles: coverageResult.total,
+        includedFiles: coverageResult.included,
+        droppedFiles: coverageResult.dropped,
+        perModule: Object.fromEntries(
+          Array.from(coverageResult.perModule.entries())
+            .map(([k, v]) => [k, v])
+        ),
+      };
+    }
+    process.stdout.write(JSON.stringify(payload) + '\n');
     // Exit 1 in CI if over budget — lets pipelines fail fast
     if (overBudget) process.exitCode = 1;
   } else {
@@ -6743,6 +6768,20 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
     console.log(`  output tokens   : ~${finalTokens}`);
     console.log(`  budget limit    : ${budgetLimit || 6000}`);
     console.log(`  reduction       : ${reduction}%`);
+    if (coverageResult) {
+      console.log(`  coverage        : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} source files included`);
+      console.log(`  confidence      : ${coverageResult.confidence}`);
+      if (coverageResult.perModule && coverageResult.perModule.size > 0) {
+        console.log('');
+        console.log('  Module Coverage:');
+        for (const [dir, mod] of coverageResult.perModule) {
+          if (mod.total === 0) continue;
+          const bar = _coverageBar(mod.pct);
+          const attention = mod.pct < 50 ? '  \u2190 attention needed' : '';
+          console.log(`    ${dir.padEnd(18)} ${bar} ${String(mod.pct).padStart(3)}% (${mod.included}/${mod.total} files)${attention}`);
+        }
+      }
+    }
     if (overBudget) console.warn(`[sigmap] WARNING: output (${finalTokens} tokens) exceeds budget (${budgetLimit || 6000})`);
   }
 }
@@ -7032,6 +7071,41 @@ function runDiff(cwd, config, stagedOnly, baseRef) {
   const scope = baseRef ? `diff-vs-${baseRef}` : (stagedOnly ? 'staged' : 'diff');
   console.warn(`[sigmap] ${scope} files: ${fileEntries.length}, diff tokens: ~${finalTokens}`);
 
+  // v4.0: risk score per changed file
+  try {
+    const { buildFromCwd } = requireSourceOrBundled('./src/graph/builder');
+    const graph = buildFromCwd(cwd, { silent: true });
+    const reverseGraph = graph.reverse || new Map();
+
+    function _isRouteFile(f) {
+      return /\/(routes?|pages?|controllers?|handlers?|api)\//i.test(f)
+        || /\.(route|page|controller|handler)\.\w+$/.test(f);
+    }
+    function _riskScore(filePath, sigs, revGraph) {
+      let s = 0;
+      if (sigs.some(sig => sig.includes('export') || sig.includes('module.exports'))) s += 2;
+      const deps = revGraph.get(filePath) || new Set();
+      if (deps.size > 3) s += 2;
+      if (_isRouteFile(filePath)) s += 1;
+      if (/\.(config|env|settings)\.\w+$/.test(filePath)) s += 1;
+      return s >= 4 ? 'HIGH' : s >= 2 ? 'MEDIUM' : 'LOW';
+    }
+
+    console.warn(`[sigmap] Risk: Changed files (${fileEntries.length}):`);
+    for (const fe of fileEntries) {
+      const level = _riskScore(fe.filePath, fe.sigs, reverseGraph);
+      const rel   = path.relative(cwd, fe.filePath).replace(/\\/g, '/');
+      const deps  = reverseGraph.get(fe.filePath) || new Set();
+      const reasons = [];
+      if (fe.sigs.some(s => s.includes('export') || s.includes('module.exports'))) reasons.push('exports public API');
+      if (deps.size > 0) reasons.push(`${deps.size} downstream dependent${deps.size === 1 ? '' : 's'}`);
+      if (_isRouteFile(fe.filePath)) reasons.push('route file');
+      if (/\.(config|env|settings)\.\w+$/.test(fe.filePath)) reasons.push('config file');
+      const label = level === 'HIGH' ? '[HIGH]  ' : level === 'MEDIUM' ? '[MEDIUM]' : '[LOW]   ';
+      console.warn(`  ${rel.padEnd(40)} ${label}${reasons.length ? '  — ' + reasons.join(', ') : ''}`);
+    }
+  } catch (_) {}
+
   if (process.argv.includes('--report')) {
     // Also show what the full run would cost for comparison
     const fullResult = runGenerate(cwd, config, true);
@@ -7176,11 +7250,17 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
     const droppedCount = beforeCount - budgeted.length;
     const content = formatOutput(budgeted, cwd, false, config, null);
     const finalTokens = estimateTokens(content);
-    result = { inputTokenTotal, finalTokens, fileCount: beforeCount, droppedCount };
+    // v4.0: compute coverage score for --report heatmap
+    let coverageResult = null;
+    try {
+      const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+      coverageResult = coverageScore(cwd, budgeted, config);
+    } catch (_) {}
+    result = { inputTokenTotal, finalTokens, fileCount: beforeCount, droppedCount, coverageResult };
   }
 
   if (reportMode || process.argv.includes('--report')) {
-    printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, config.maxTokens);
+    printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, config.maxTokens, result.coverageResult);
   }
 
   // Usage tracking (v0.9) — optional append-only NDJSON log
@@ -7212,17 +7292,26 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
     const pct  = result.inputTokenTotal > 0
       ? Math.round((1 - result.finalTokens / result.inputTokenTotal) * 100)
       : 0;
-    process.stderr.write([
+    // v4.0: coverage score in post-run summary
+    let coverageLine = '';
+    try {
+      const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+      const cov = coverageScore(cwd, fileEntries, config);
+      coverageLine = ` Coverage       : ${cov.grade} (${cov.score}%)  \u2014 ${cov.included} of ${cov.total} source files included`;
+    } catch (_) {}
+    const lines = [
       bar,
       ` SigMap v${VERSION}`,
       ` Files scanned  : ${result.fileCount}`,
       ` Symbols found  : ${syms.toLocaleString()}`,
       ` Token reduction: ${pct}%  (${result.inputTokenTotal.toLocaleString()} \u2192 ${result.finalTokens.toLocaleString()})`,
-      ` Output         : .github/copilot-instructions.md`,
-      bar,
-      ` Try: "explain the architecture" \u00b7 "find the auth module"`,
-      bar, '',
-    ].join('\n'));
+    ];
+    if (coverageLine) lines.push(coverageLine);
+    lines.push(` Output         : .github/copilot-instructions.md`);
+    lines.push(bar);
+    lines.push(` Try: "explain the architecture" \u00b7 "find the auth module"`);
+    lines.push(bar, '');
+    process.stderr.write(lines.join('\n'));
   }
 
   return result;
@@ -7725,6 +7814,17 @@ function main() {
   if (args.includes('--health')) {
     const { score } = __require('./src/health/scorer');
     const result = score(cwd);
+    // v4.0: compute live coverage score to include in health output
+    let coverageResult = null;
+    try {
+      const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+      const { loadConfig: lc } = requireSourceOrBundled('./src/config/loader');
+      const cfg = lc(cwd);
+      // Use all files from srcDirs as proxies for "included" (no budget applied in health mode)
+      const allFiles = buildFileList(cwd, cfg);
+      const fakeEntries = allFiles.map(f => ({ filePath: f }));
+      coverageResult = coverageScore(cwd, fakeEntries, cfg);
+    } catch (_) {}
     if (args.includes('--json')) {
       // Feature 3 (VS Code) + Feature 5 (JetBrains): emit tokens + reduction for plugins
       const ctxPath = path.join(cwd, '.github', 'copilot-instructions.md');
@@ -7733,10 +7833,21 @@ function main() {
       if (fs.existsSync(ctxPath)) {
         try { tokens = estimateTokens(fs.readFileSync(ctxPath, 'utf8')); } catch (_) {}
       }
-      process.stdout.write(JSON.stringify({ ...result, tokens, reduction }) + '\n');
+      const payload = { ...result, tokens, reduction };
+      if (coverageResult) {
+        payload.coverage = coverageResult.score;
+        payload.coverageGrade = coverageResult.grade;
+        payload.coverageConfidence = coverageResult.confidence;
+        payload.coverageTotalFiles = coverageResult.total;
+        payload.coverageIncludedFiles = coverageResult.included;
+      }
+      process.stdout.write(JSON.stringify(payload) + '\n');
     } else {
       console.log('[sigmap] health:');
       console.log(`  score           : ${result.score}/100 (grade ${result.grade})`);
+      if (coverageResult) {
+        console.log(`  coverage        : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} source files`);
+      }
       console.log(`  strategy        : ${result.strategy}`);
       console.log(`  token reduction : ${result.tokenReductionPct !== null ? result.tokenReductionPct + '%' : 'no history'}`);
       console.log(`  days since regen: ${result.daysSinceRegen !== null ? result.daysSinceRegen : 'context file not found'}`);

package/package.json

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

package/packages/adapters/claude.js

@@ -26,15 +26,26 @@ const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta      = _confidenceMeta(opts);
   return [
     `<!-- Generated by SigMap v${version} — ${timestamp} -->`,
+    meta,
     '',
     context,
   ].join('\n');
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `<!-- sigmap: ${parts.join(' ')} -->`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/adapters/copilot.js

@@ -24,11 +24,13 @@ const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version   || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta = _confidenceMeta(opts);
   const header = [
     `<!-- Generated by SigMap gen-context.js v${version} -->`,
     `<!-- Updated: ${timestamp} -->`,
+    meta,
     `<!-- Do not edit below — regenerate with: node gen-context.js -->`,
     '',
     '# Code signatures',
@@ -37,6 +39,15 @@ function format(context, opts = {}) {
   return header + context;
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `<!-- sigmap: ${parts.join(' ')} -->`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/adapters/cursor.js

@@ -22,17 +22,28 @@ const name = 'cursor';
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta      = _confidenceMeta(opts);
   const header = [
     `# Code signatures — generated by SigMap v${version}`,
     `# Updated: ${timestamp}`,
+    `# ${meta}`,
     `# Regenerate: node gen-context.js`,
     '',
   ].join('\n');
   return header + context;
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/adapters/gemini.js

@@ -36,9 +36,11 @@ function format(context, opts = {}) {
     ? `Project: ${opts.projectName}\n`
     : '';
 
+  const meta = _confidenceMeta(opts);
   return [
     `You are a coding assistant with complete knowledge of this codebase.`,
     `The following code signatures were extracted by SigMap v${version} on ${timestamp}.`,
+    `<!-- ${meta} -->`,
     projectLine,
     `These signatures represent every public function, class, and type in the project.`,
     `Refer to them when answering questions about code structure, APIs, and implementation.`,
@@ -91,4 +93,13 @@ function write(context, cwd, opts = {}) {
   fs.writeFileSync(filePath, newContent, 'utf8');
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 module.exports = { name, format, outputPath, write };

package/packages/adapters/openai.js

@@ -34,9 +34,11 @@ function format(context, opts = {}) {
     ? `Project: ${opts.projectName}\n`
     : '';
 
+  const meta = _confidenceMeta(opts);
   return [
     `You are a coding assistant with full knowledge of this codebase.`,
     `Below are the code signatures extracted by SigMap v${version} on ${timestamp}.`,
+    `<!-- ${meta} -->`,
     projectLine,
     `Use these signatures to answer questions about the code accurately.`,
     `When the user asks about a specific file or function, refer to the signatures below.`,
@@ -57,4 +59,13 @@ function outputPath(cwd) {
   return path.join(cwd, '.github', 'openai-context.md');
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 module.exports = { name, format, outputPath };

package/packages/adapters/windsurf.js

@@ -22,17 +22,28 @@ const name = 'windsurf';
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta      = _confidenceMeta(opts);
   const header = [
     `# Code signatures — generated by SigMap v${version}`,
     `# Updated: ${timestamp}`,
+    `# ${meta}`,
     `# Regenerate: node gen-context.js`,
     '',
   ].join('\n');
   return header + context;
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/cli/package.json

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

package/src/analysis/coverage-score.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * SigMap coverage scorer — v4.0.0
+ *
+ * Measures what fraction of source files made it into the context output
+ * after token-budget application. This is complementary to the health score:
+ *   - Health score = context freshness / reduction quality / budget compliance
+ *   - Coverage score = how much of the codebase is represented in context
+ *
+ * Grade scale:  A ≥ 90%  |  B ≥ 75%  |  C ≥ 50%  |  D < 50%
+ *
+ * @param {string} cwd
+ * @param {Array<{filePath:string}>} fileEntries - files that made it into output
+ * @param {{srcDirs:string[], exclude:string[]}} config
+ * @returns {{
+ *   score: number,
+ *   grade: 'A'|'B'|'C'|'D',
+ *   total: number,
+ *   included: number,
+ *   dropped: number,
+ *   confidence: 'HIGH'|'MEDIUM'|'LOW',
+ *   perModule: Map<string, {total:number, included:number, pct:number}>,
+ * }}
+ */
+function coverageScore(cwd, fileEntries, config) {
+  const fs   = require('fs');
+  const path = require('path');
+
+  const srcDirs = (config && Array.isArray(config.srcDirs) && config.srcDirs.length > 0)
+    ? config.srcDirs
+    : ['src', 'app', 'lib'];
+
+  const excludeSet = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+    '.next', 'coverage', 'target', 'vendor', '.context',
+  ]);
+  if (config && Array.isArray(config.exclude)) {
+    for (const x of config.exclude) excludeSet.add(String(x));
+  }
+
+  const includedSet = new Set((fileEntries || []).map(f => f.filePath));
+
+  // Walk all source files from srcDirs
+  const allSource = [];
+  for (const relDir of srcDirs) {
+    const absDir = path.resolve(cwd, relDir);
+    if (fs.existsSync(absDir)) _walk(absDir, excludeSet, allSource);
+  }
+
+  const total    = allSource.length;
+  const included = allSource.filter(f => includedSet.has(f)).length;
+  const dropped  = total - included;
+  const pct      = total > 0 ? Math.round((included / total) * 100) : 100;
+
+  const grade = pct >= 90 ? 'A' : pct >= 75 ? 'B' : pct >= 50 ? 'C' : 'D';
+  const confidence = pct >= 90 ? 'HIGH' : pct >= 70 ? 'MEDIUM' : 'LOW';
+
+  // Per-module breakdown (one entry per srcDir)
+  const perModule = new Map();
+  for (const relDir of srcDirs) {
+    const absDir   = path.resolve(cwd, relDir);
+    const modFiles = allSource.filter(f => f.startsWith(absDir + path.sep) || f === absDir);
+    const modIncl  = modFiles.filter(f => includedSet.has(f)).length;
+    const modPct   = modFiles.length > 0 ? Math.round((modIncl / modFiles.length) * 100) : 100;
+    perModule.set(relDir, { total: modFiles.length, included: modIncl, pct: modPct });
+  }
+
+  return { score: pct, grade, total, included, dropped, confidence, perModule };
+}
+
+function _walk(dir, excludeSet, out) {
+  const fs   = require('fs');
+  const path = require('path');
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+  for (const e of entries) {
+    if (excludeSet.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) { _walk(full, excludeSet, out); }
+    else if (e.isFile())  { out.push(full); }
+  }
+}
+
+module.exports = { coverageScore };

package/src/eval/analyzer.js

@@ -147,6 +147,9 @@ function analyzeFiles(files, cwd, opts) {
     const tokens   = tokenCount(sigs);
     const covered  = hasCoverage(filePath, cwd);
     const isSlow   = slow && elapsedMs > slowMs;
+    // v4.0: signal quality = sigs per line-of-code (higher = more informative to LLMs)
+    const linesOfCode    = content.split('\n').length;
+    const signalQuality  = linesOfCode > 0 ? parseFloat((sigs.length / linesOfCode).toFixed(4)) : 0;
 
     stats.push({
       file:          rel,
@@ -154,6 +157,8 @@ function analyzeFiles(files, cwd, opts) {
       sigs:          sigs.length,
       tokens,
       covered,
+      linesOfCode,
+      signalQuality,
       elapsedMs:     slow ? elapsedMs : undefined,
       slow:          slow ? isSlow : undefined,
     });

package/src/mcp/server.js

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