sigmap 5.3.0 → 5.5.0

package/CHANGELOG.md

@@ -10,6 +10,34 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [5.5.0] — 2026-04-17
+
+### Fixed
+
+- **Coverage grade now accurate for mixed-content projects** — `coverageScore()` counts only code files (`.ts`, `.js`, `.py`, `.go`, etc.) in the denominator. Previously, `package.json`, `tsconfig.json`, `README.md`, and other non-code files were counted, causing inflated D-grades even when all code was covered (reported in discussion #81).
+- **`--report` coverage label** — now reads `code files` instead of `source files`, and prints `(N non-code files skipped — json, md, config)` when non-code files were excluded.
+- **`--report` actionable guidance** — modules marked `← attention needed` (<50% coverage) now show a tip block listing the three common causes and how to fix each.
+- **`--health` label disambiguation** — coverage line renamed from `coverage … source files` to `file access … files accessible in srcDirs`, making it clearly distinct from the `--report` coverage metric.
+- **`autoMaxTokens` silent-override warning** — when `autoMaxTokens` is active and overrides the user's `maxTokens` config value, `--report` now emits an explicit note explaining the override and how to disable it.
+
+### Changed
+
+- `src/analysis/coverage-score.js` exports `CODE_EXTS` (the allowlist Set) for use by other modules and tests.
+- `coverageScore()` return object gains a `nonCodeSkipped` field (number of non-code files found in srcDirs but excluded from the denominator).
+
+---
+
+## [5.4.0] — 2026-04-17
+
+### Added
+
+- **Neovim plugin (`sigmap.nvim`)** — first-class Neovim integration in `neovim-plugin/`. Provides `:SigMap [args]` (async regen), `:SigMapQuery <text>` (TF-IDF retrieval in a floating window), `auto_run = true` (`BufWritePost` autocmd for source files), `require('sigmap').statusline()` for lualine/statusline widgets, and `:checkhealth sigmap` (validates Node 18+, binary presence, context file freshness).
+- **Binary auto-detection** — plugin resolves the sigmap binary automatically: global `sigmap` → `npx sigmap` → local `gen-context.js` fallback; no manual config needed for most setups.
+- **`release-neovim.yml` workflow** — tag `neovim-v*` to validate Lua files, run the full integration suite across Node 18/20/22, package the plugin as a `.tar.gz`, and create a GitHub Release.
+- **CI now runs integration tests** — `ci.yml` runs both `node test/run.js` and `node test/integration/all.js` on every push and pull request.
+
+---
+
 ## [5.3.0] — 2026-04-17
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again
 - Fewer retries (1.69 vs 2.84 prompts per task)
 - Far smaller context (~2K–4K tokens instead of ~80K)
 
-> Latest: **v5.3.0** — Learning engine + workflow-first release. Use `ask`, `validate`, `judge`, `learn`, `weights`, `compare`, and `share` on top of the core signature pipeline.
+> Latest: **v5.5.0** — Coverage clarity + report UX plugin (`sigmap.nvim`). `:SigMap`, `:SigMapQuery`, auto-run on save, statusline widget, and `:checkhealth sigmap` for the #1 most-admired editor.
 
 **What is new in v5.2**
 - `sigmap ask` creates task-focused context in one step
@@ -99,6 +99,7 @@ Measured on 90 coding tasks across 18 real public repos. Full methodology and ra
 | [Standalone binaries](docs/readmes/binaries.md) | macOS, Linux, Windows — no Node required |
 | [VS Code extension](#-vs-code-extension) | Status bar, stale alerts, commands |
 | [JetBrains plugin](#-jetbrains-plugin) | IntelliJ IDEA, WebStorm, PyCharm support |
+| [Neovim plugin](#-neovim-plugin) | `:SigMap`, `:SigMapQuery`, statusline, health check |
 | [Languages supported](#-languages-supported) | 29 languages |
 | [Context strategies](#-context-strategies) | full / per-module / hot-cold |
 | [MCP server](#-mcp-server) | 8 on-demand tools |
@@ -518,6 +519,39 @@ Compatible with **IntelliJ IDEA 2024.1+** (Community & Ultimate), **WebStorm**,
 
 ---
 
+## 🖥️ Neovim plugin
+
+<a href="https://dotfyle.com/plugins/manojmallick/sigmap.nvim">
+	<img src="https://dotfyle.com/plugins/manojmallick/sigmap.nvim/shield?style=flat" />
+</a>
+
+The official SigMap Neovim plugin (`sigmap.nvim`) brings first-class integration to the #1 most-admired editor (Stack Overflow 2025, 83% admiration rate). Power users who live in the terminal get context regeneration, ranked retrieval, and health checks without leaving Neovim.
+
+| Feature | Detail |
+|---|---|
+| **`:SigMap [args]`** | Regenerate your AI context file asynchronously |
+| **`:SigMapQuery <text>`** | TF-IDF ranked retrieval — results appear in a centered floating window |
+| **Auto-run on save** | `auto_run = true` triggers regen on `BufWritePost` for `.js/ts/py/go/rs/java/rb/lua` |
+| **Statusline widget** | `require('sigmap').statusline()` returns `sm:✓` (fresh) or `sm:⚠ Nh` (stale) |
+| **`:checkhealth sigmap`** | Validates Node 18+, binary presence, and context file freshness |
+| **Binary auto-detection** | Finds `sigmap` → `npx sigmap` → local `gen-context.js` automatically |
+
+**Install (lazy.nvim):**
+```lua
+{ 'manojmallick/sigmap.nvim',
+  config = function()
+    require('sigmap').setup({
+      auto_run    = true,   -- regenerate on save
+      float_query = true,   -- show query results in a floating window
+    })
+  end,
+}
+```
+
+**Repo:** [manojmallick/sigmap.nvim](https://github.com/manojmallick/sigmap.nvim)
+
+---
+
 ## 🌐 Languages supported
 
 > 29 languages and formats. All implemented with zero external dependencies — pure regex + Node built-ins.
@@ -811,7 +845,7 @@ Every run now prints a coverage line alongside token reduction:
 
 ```
 ───────────────────────────────────────────
- SigMap v5.3.0
+ SigMap v5.5.0
  Files scanned  : 76
  Symbols found  : 332
  Token reduction: 94%  (65,227 → 4,103)
@@ -830,7 +864,7 @@ sigmap --report
 
 ```
 [sigmap] report:
-  version         : 5.3.0
+  version         : 5.5.0
   files processed : 76
   reduction       : 93.7%
   coverage        : A (97%)  — 76 of 78 source files included
@@ -874,7 +908,7 @@ sigmap --health --json
 Every output file now carries a metadata line so you can inspect freshness at a glance:
 
 ```
-<!-- sigmap: version=5.3.0 confidence=HIGH coverage=97% dropped=2 commit=8540612 -->
+<!-- sigmap: version=5.5.0 confidence=HIGH coverage=97% dropped=2 commit=8540612 -->
 ```
 
 ### Diff risk score
@@ -1009,6 +1043,11 @@ sigmap/
 │   ├── package.json             ← manifest — commands, settings, activation
 │   └── src/extension.js         ← status bar, stale notification, commands
 │
+├── neovim-plugin/               ← Neovim plugin — sigmap.nvim (v5.4)
+│   ├── lua/sigmap/init.lua      ← M.setup(), M.run(), M.query(), M.statusline()
+│   ├── lua/sigmap/health.lua    ← :checkhealth sigmap
+│   └── plugin/sigmap.lua        ← :SigMap and :SigMapQuery user commands
+│
 ├── test/
 │   ├── fixtures/                ← one source file per language
 │   ├── expected/                ← expected extractor output

package/gen-context.js

@@ -3034,7 +3034,445 @@ __factories["./src/format/cache"] = function(module, exports) {
   }
   
   module.exports = { formatCache, formatCachePayload };
-  
+
+};
+
+// ── ./src/format/benchmark-report ──
+__factories["./src/format/benchmark-report"] = function(module, exports) {
+  'use strict';
+
+  const fs = require('fs');
+  const path = require('path');
+
+  function escapeHtml(value) {
+    return String(value == null ? '' : value)
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  function formatInt(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'n/a';
+    return Math.round(n).toLocaleString('en-US');
+  }
+
+  function formatCompact(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'n/a';
+    if (Math.abs(n) >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+    if (Math.abs(n) >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+    return String(Math.round(n));
+  }
+
+  function formatPct(value, digits = 1) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'n/a';
+    return `${n.toFixed(digits)}%`;
+  }
+
+  function formatMaybePct(value, digits = 1) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'n/a';
+    return `${n.toFixed(digits)}%`;
+  }
+
+  function formatRatio(value, digits = 1) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'n/a';
+    return `${n.toFixed(digits)}x`;
+  }
+
+  function formatMoney(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'n/a';
+    return `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+  }
+
+  function durationLabel(ms) {
+    const n = Number(ms);
+    if (!Number.isFinite(n)) return 'n/a';
+    const sec = n / 1000;
+    if (sec < 60) return `${sec.toFixed(1)}s`;
+    const min = Math.floor(sec / 60);
+    const rem = sec - (min * 60);
+    return `${min}m ${rem.toFixed(1)}s`;
+  }
+
+  function maxOrZero(values) {
+    if (!Array.isArray(values) || values.length === 0) return 0;
+    return Math.max(...values.map((v) => (Number.isFinite(v) ? v : 0)));
+  }
+
+  function readJson(filePath) {
+    try {
+      if (!fs.existsSync(filePath)) return null;
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function loadBenchmarkReports(cwd) {
+    const reportsDir = path.join(cwd, 'benchmarks', 'reports');
+    return {
+      reportsDir,
+      token: readJson(path.join(reportsDir, 'token-reduction.json')),
+      retrieval: readJson(path.join(reportsDir, 'retrieval.json')),
+      quality: readJson(path.join(reportsDir, 'quality.json')),
+      task: readJson(path.join(reportsDir, 'task-benchmark.json')),
+      matrix: readJson(path.join(reportsDir, 'benchmark-matrix.json')),
+    };
+  }
+
+  function buildRetrievalSummary(retrieval) {
+    if (!retrieval || !Array.isArray(retrieval.repos) || retrieval.repos.length === 0) return null;
+    let totalTasks = 0;
+    let weightedHit = 0;
+    let weightedRand = 0;
+    let correct = 0;
+    let partial = 0;
+    let wrong = 0;
+    let repoCount = 0;
+
+    for (const repo of retrieval.repos) {
+      const tasks = Number(repo.tasks) || 0;
+      repoCount++;
+      totalTasks += tasks;
+      weightedHit += (Number(repo.hitAt5) || 0) * tasks;
+      weightedRand += (Number(repo.randomBaseline) || 0) * tasks;
+      correct += Number(repo.tiers && repo.tiers.correct) || 0;
+      partial += Number(repo.tiers && repo.tiers.partial) || 0;
+      wrong += Number(repo.tiers && repo.tiers.wrong) || 0;
+    }
+
+    const hitAt5 = totalTasks > 0 ? (weightedHit / totalTasks) * 100 : null;
+    const randomBaseline = totalTasks > 0 ? (weightedRand / totalTasks) * 100 : null;
+    const lift = hitAt5 && randomBaseline ? hitAt5 / randomBaseline : null;
+
+    return { repoCount, totalTasks, hitAt5, randomBaseline, lift, correct, partial, wrong };
+  }
+
+  function buildBenchmarkSummary(reports, matrixSummary) {
+    const missing = [];
+    if (!reports.token) missing.push('token-reduction.json');
+    if (!reports.retrieval) missing.push('retrieval.json');
+    if (!reports.quality) missing.push('quality.json');
+    if (!reports.task) missing.push('task-benchmark.json');
+
+    const retrievalSummary = buildRetrievalSummary(reports.retrieval);
+    const qualitySummary = reports.quality && reports.quality.summary ? reports.quality.summary : null;
+    const tokenSummary = reports.token && reports.token.summary ? reports.token.summary : null;
+    const taskSummary = reports.task && reports.task.summary ? reports.task.summary : null;
+    const matrix = matrixSummary || reports.matrix || null;
+
+    const generatedCandidates = [
+      matrix && matrix.generated,
+      reports.task && reports.task.generated,
+      reports.retrieval && reports.retrieval.generated,
+      reports.quality && reports.quality.timestamp,
+      reports.token && reports.token.timestamp,
+    ].filter(Boolean);
+    const generatedAt = generatedCandidates
+      .map((value) => ({ value, time: Date.parse(value) }))
+      .filter((item) => Number.isFinite(item.time))
+      .sort((a, b) => b.time - a.time)[0];
+
+    return {
+      generatedAt: (generatedAt && generatedAt.value) || generatedCandidates[0] || new Date().toISOString(),
+      missing,
+      tokenSummary,
+      retrievalSummary,
+      qualitySummary,
+      taskSummary,
+      matrix,
+    };
+  }
+
+  function renderCard(label, value, hint, tone) {
+    const toneClass = tone ? ` ${tone}` : '';
+    return [
+      `<article class="card${toneClass}">`,
+      `<div class="label">${escapeHtml(label)}</div>`,
+      `<div class="value">${escapeHtml(value)}</div>`,
+      `<div class="hint">${escapeHtml(hint || '')}</div>`,
+      '</article>',
+    ].join('');
+  }
+
+  function renderProgress(label, value, max, suffix) {
+    const safeValue = Number.isFinite(value) ? value : 0;
+    const safeMax = Math.max(1, Number.isFinite(max) ? max : 1);
+    const width = Math.max(2, Math.min(100, (safeValue / safeMax) * 100));
+    return [
+      '<div class="progress-row">',
+      `<div class="progress-label">${escapeHtml(label)}</div>`,
+      '<div class="progress-bar"><span style="width:',
+      String(width.toFixed(1)),
+      '%"></span></div>',
+      `<div class="progress-value">${escapeHtml(`${safeValue}${suffix || ''}`)}</div>`,
+      '</div>',
+    ].join('');
+  }
+
+  function renderMatrixSection(matrix) {
+    if (!matrix || !Array.isArray(matrix.steps) || matrix.steps.length === 0) return '';
+    const rows = matrix.steps.map((step) => {
+      const status = step.ok ? 'ok' : 'fail';
+      return [
+        '<tr>',
+        `<td>${escapeHtml(step.name)}</td>`,
+        `<td><span class="badge ${status}">${escapeHtml(step.ok ? 'ok' : `exit ${step.status}`)}</span></td>`,
+        `<td>${escapeHtml(durationLabel(step.durationMs))}</td>`,
+        `<td><code>${escapeHtml(['node', step.script].concat(step.args || []).join(' '))}</code></td>`,
+        '</tr>',
+      ].join('');
+    }).join('');
+
+    return [
+      '<section>',
+      '<h2>Run matrix</h2>',
+      '<p class="section-copy">This shows which benchmark jobs ran, whether they succeeded, and how long each step took.</p>',
+      '<table>',
+      '<thead><tr><th>Step</th><th>Status</th><th>Duration</th><th>Command</th></tr></thead>',
+      `<tbody>${rows}</tbody>`,
+      '</table>',
+      '</section>',
+    ].join('');
+  }
+
+  function renderTokenSection(token) {
+    if (!token || !Array.isArray(token.repos) || token.repos.length === 0) return '';
+    const rows = token.repos
+      .slice()
+      .sort((a, b) => (b.reductionPct || 0) - (a.reductionPct || 0))
+      .map((repo) => [
+        '<tr>',
+        `<td>${escapeHtml(repo.repo)}</td>`,
+        `<td>${escapeHtml(repo.language || 'n/a')}</td>`,
+        `<td>${escapeHtml(formatCompact(repo.rawTokens))}</td>`,
+        `<td>${escapeHtml(formatCompact(repo.finalTokens))}</td>`,
+        `<td>${escapeHtml(formatMaybePct(repo.reductionPct, 1))}</td>`,
+        '</tr>',
+      ].join(''))
+      .join('');
+
+    return [
+      '<section>',
+      '<h2>Token reduction</h2>',
+      '<p class="section-copy">Raw repository tokens versus SigMap output size across the benchmark repos.</p>',
+      '<table>',
+      '<thead><tr><th>Repo</th><th>Language</th><th>Raw tokens</th><th>Final tokens</th><th>Reduction</th></tr></thead>',
+      `<tbody>${rows}</tbody>`,
+      '</table>',
+      '</section>',
+    ].join('');
+  }
+
+  function renderRetrievalSection(retrieval) {
+    if (!retrieval || !Array.isArray(retrieval.repos) || retrieval.repos.length === 0) return '';
+    const rows = retrieval.repos.map((repo) => {
+      const lift = repo.randomBaseline > 0 ? (repo.hitAt5 / repo.randomBaseline) : null;
+      return [
+        '<tr>',
+        `<td>${escapeHtml(repo.repo)}</td>`,
+        `<td>${escapeHtml(formatMaybePct((repo.randomBaseline || 0) * 100, 1))}</td>`,
+        `<td>${escapeHtml(formatMaybePct((repo.hitAt5 || 0) * 100, 1))}</td>`,
+        `<td>${escapeHtml(formatRatio(lift, 1))}</td>`,
+        `<td>${escapeHtml(String((repo.tiers && repo.tiers.correct) || 0))}</td>`,
+        `<td>${escapeHtml(String((repo.tiers && repo.tiers.partial) || 0))}</td>`,
+        `<td>${escapeHtml(String((repo.tiers && repo.tiers.wrong) || 0))}</td>`,
+        '</tr>',
+      ].join('');
+    }).join('');
+
+    return [
+      '<section>',
+      '<h2>Retrieval quality</h2>',
+      '<p class="section-copy">Hit@5 performance against the random baseline, plus the quality-tier mix that drives the task benchmark.</p>',
+      '<table>',
+      '<thead><tr><th>Repo</th><th>Random hit@5</th><th>SigMap hit@5</th><th>Lift</th><th>Correct</th><th>Partial</th><th>Wrong</th></tr></thead>',
+      `<tbody>${rows}</tbody>`,
+      '</table>',
+      '</section>',
+    ].join('');
+  }
+
+  function renderQualitySection(quality) {
+    if (!quality || !Array.isArray(quality.repos) || quality.repos.length === 0) return '';
+    const rows = quality.repos.map((repo) => {
+      const overflow = (repo.rawTokens || 0) > 128000 ? 'overflow' : 'fits';
+      return [
+        '<tr>',
+        `<td>${escapeHtml(repo.repo)}</td>`,
+        `<td>${escapeHtml(formatInt(repo.groundedSymbols))}</td>`,
+        `<td>${escapeHtml(formatInt(repo.darkSymbols))}</td>`,
+        `<td>${escapeHtml(formatMaybePct(repo.groundingPct, 0))}</td>`,
+        `<td>${escapeHtml(String(repo.filesHiddenRaw || 0))}</td>`,
+        `<td><span class="badge ${overflow === 'overflow' ? 'warn' : 'ok'}">${escapeHtml(overflow)}</span></td>`,
+        '</tr>',
+      ].join('');
+    }).join('');
+
+    return [
+      '<section>',
+      '<h2>Quality and hallucination surface</h2>',
+      '<p class="section-copy">How much code stays visible to the model, plus the overflow and dark-symbol risk by repo.</p>',
+      '<table>',
+      '<thead><tr><th>Repo</th><th>Grounded symbols</th><th>Dark symbols</th><th>Grounding</th><th>Hidden files (raw)</th><th>GPT-4o 128K</th></tr></thead>',
+      `<tbody>${rows}</tbody>`,
+      '</table>',
+      '</section>',
+    ].join('');
+  }
+
+  function renderTaskSection(task) {
+    if (!task || !Array.isArray(task.repos) || task.repos.length === 0 || !task.summary) return '';
+    const summary = task.summary;
+    const maxReduction = maxOrZero(task.repos.map((repo) => Number(repo.reductionPct) || 0));
+    const repoBars = task.repos
+      .slice()
+      .sort((a, b) => (b.reductionPct || 0) - (a.reductionPct || 0))
+      .slice(0, 10)
+      .map((repo) => renderProgress(repo.repo, Number(repo.reductionPct) || 0, maxReduction, '%'))
+      .join('');
+
+    return [
+      '<section>',
+      '<h2>Task benchmark</h2>',
+      '<p class="section-copy">A prompt-reduction proxy derived from retrieval quality tiers. Lower prompts means the right file surfaces sooner.</p>',
+      '<div class="split">',
+      '<div class="panel">',
+      '<h3>Answer quality tiers</h3>',
+      renderProgress('Correct', Number(summary.correctPct) || 0, 100, '%'),
+      renderProgress('Partial', Number(summary.partialPct) || 0, 100, '%'),
+      renderProgress('Wrong', Number(summary.wrongPct) || 0, 100, '%'),
+      '</div>',
+      '<div class="panel">',
+      '<h3>Best prompt reduction by repo</h3>',
+      repoBars,
+      '</div>',
+      '</div>',
+      '</section>',
+    ].join('');
+  }
+
+  function generateBenchmarkReportHtml(reports, opts = {}) {
+    const summary = buildBenchmarkSummary(reports, opts.matrixSummary);
+    const cards = [];
+    cards.push(renderCard(
+      'Token reduction',
+      summary.tokenSummary ? formatPct(summary.tokenSummary.overallReductionPct, 1) : 'n/a',
+      summary.tokenSummary ? `${formatInt(summary.tokenSummary.repoCount)} repos • ${formatCompact(summary.tokenSummary.totalRawTokens)} raw -> ${formatCompact(summary.tokenSummary.totalFinalTokens)} final` : 'token-reduction.json missing',
+      'cool'
+    ));
+    cards.push(renderCard(
+      'Retrieval hit@5',
+      summary.retrievalSummary ? formatPct(summary.retrievalSummary.hitAt5, 1) : 'n/a',
+      summary.retrievalSummary ? `${formatPct(summary.retrievalSummary.randomBaseline, 1)} random baseline • ${formatRatio(summary.retrievalSummary.lift, 1)} lift` : 'retrieval.json missing',
+      'warm'
+    ));
+    cards.push(renderCard(
+      'Prompt reduction',
+      summary.taskSummary ? formatPct(summary.taskSummary.avgReductionPct, 0) : 'n/a',
+      summary.taskSummary ? `${summary.taskSummary.avgPromptsWithout} -> ${summary.taskSummary.avgPromptsWith} prompts • ${formatInt(summary.taskSummary.totalTasks)} tasks` : 'task-benchmark.json missing',
+      'neutral'
+    ));
+    cards.push(renderCard(
+      'Overflow risk',
+      summary.qualitySummary ? `${formatInt(summary.qualitySummary.overflowGPT4oCount)} repos` : 'n/a',
+      summary.qualitySummary ? `${formatInt(summary.qualitySummary.totalHiddenFiles)} hidden raw files • ${formatMoney(summary.qualitySummary.gpt4oSavedPerMonth)}/month saved` : 'quality.json missing',
+      summary.qualitySummary && summary.qualitySummary.overflowGPT4oCount > 0 ? 'warn' : 'ok'
+    ));
+
+    const missingHtml = summary.missing.length > 0
+      ? `<div class="notice">Missing source reports: ${escapeHtml(summary.missing.join(', '))}. The page still renders whatever data is available.</div>`
+      : '';
+
+    return [
+      '<!doctype html>',
+      '<html lang="en">',
+      '<head>',
+      '<meta charset="utf-8" />',
+      '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+      '<title>SigMap Benchmark Report</title>',
+      '<style>',
+      ':root { color-scheme: light; --bg:#f5f1e8; --panel:#fffaf2; --ink:#1f1b16; --muted:#6a6258; --line:#dccfbf; --gold:#c87f2a; --green:#2f6f52; --blue:#2f5f8f; --red:#9f4f43; --shadow:0 18px 40px rgba(54,38,14,.10);} ',
+      '*{box-sizing:border-box} body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:linear-gradient(180deg,#f3ecdf 0%,#f7f3ed 100%);color:var(--ink)}',
+      '.page{max-width:1240px;margin:0 auto;padding:28px 20px 56px}',
+      'header{display:flex;justify-content:space-between;gap:24px;align-items:flex-end;margin-bottom:24px}',
+      'h1{margin:0;font-size:clamp(2rem,4vw,3.6rem);line-height:1.02;letter-spacing:-.04em}',
+      '.lede{max-width:760px;color:var(--muted);font-size:1rem;line-height:1.6;margin-top:10px}',
+      '.stamp{font-size:.92rem;color:var(--muted);text-align:right}',
+      '.grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:14px;margin:20px 0 24px}',
+      '.card,.panel,.notice,section{background:var(--panel);border:1px solid var(--line);box-shadow:var(--shadow);border-radius:18px}',
+      '.card{padding:18px 18px 16px}.card.cool{background:#f7f5ff}.card.warm{background:#fff4eb}.card.warn{background:#fff1eb}.card.ok{background:#eff8f1}',
+      '.label{font-size:.84rem;text-transform:uppercase;letter-spacing:.08em;color:var(--muted)}',
+      '.value{font-size:2rem;font-weight:700;letter-spacing:-.04em;margin-top:8px}',
+      '.hint{font-size:.95rem;color:var(--muted);margin-top:8px;line-height:1.5}',
+      '.notice{padding:14px 16px;margin-bottom:20px;color:var(--muted)}',
+      'section{padding:20px;margin-top:18px}',
+      'h2{margin:0 0 6px;font-size:1.4rem;letter-spacing:-.03em}',
+      'h3{margin:0 0 14px;font-size:1rem}',
+      '.section-copy{margin:0 0 16px;color:var(--muted);line-height:1.6}',
+      'table{width:100%;border-collapse:collapse;font-size:.95rem}',
+      'th,td{padding:10px 12px;border-bottom:1px solid var(--line);text-align:left;vertical-align:top}',
+      'th{font-size:.82rem;text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}',
+      'tbody tr:hover{background:rgba(200,127,42,.06)}',
+      '.badge{display:inline-flex;align-items:center;padding:4px 8px;border-radius:999px;font-size:.78rem;font-weight:600;text-transform:uppercase;letter-spacing:.04em}',
+      '.badge.ok{background:#e6f4ea;color:#21573f}.badge.warn{background:#fff0de;color:#8a4a17}.badge.fail{background:#fde8e5;color:#8a2e23}',
+      '.split{display:grid;grid-template-columns:1fr 1fr;gap:16px}',
+      '.panel{padding:16px}',
+      '.progress-row{display:grid;grid-template-columns:140px 1fr 60px;gap:12px;align-items:center;margin:10px 0}',
+      '.progress-label,.progress-value{font-size:.92rem}',
+      '.progress-bar{height:10px;border-radius:999px;background:#efe4d5;overflow:hidden}',
+      '.progress-bar span{display:block;height:100%;border-radius:999px;background:linear-gradient(90deg,var(--gold),#ebbb61)}',
+      'code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.85rem}',
+      '@media (max-width: 1020px){.grid{grid-template-columns:repeat(2,minmax(0,1fr))}.split{grid-template-columns:1fr}header{flex-direction:column;align-items:flex-start}.stamp{text-align:left}}',
+      '@media (max-width: 640px){.grid{grid-template-columns:1fr}.progress-row{grid-template-columns:110px 1fr 52px}th:nth-child(n+5),td:nth-child(n+5){display:none}}',
+      '</style>',
+      '</head>',
+      '<body>',
+      '<div class="page">',
+      '<header>',
+      '<div>',
+      '<h1>SigMap Benchmark Report</h1>',
+      '<p class="lede">A self-contained view of token reduction, retrieval quality, hallucination surface, and task-level prompt reduction. This page reads the saved JSON benchmark artifacts so it stays easy to regenerate locally.</p>',
+      '</div>',
+      `<div class="stamp">Generated: ${escapeHtml(summary.generatedAt)}<br />Source directory: <code>benchmarks/reports</code></div>`,
+      '</header>',
+      missingHtml,
+      `<div class="grid">${cards.join('')}</div>`,
+      renderMatrixSection(summary.matrix),
+      renderTokenSection(reports.token),
+      renderRetrievalSection(reports.retrieval),
+      renderQualitySection(reports.quality),
+      renderTaskSection(reports.task),
+      '</div>',
+      '</body>',
+      '</html>',
+    ].join('');
+  }
+
+  function writeBenchmarkReport(cwd, opts = {}) {
+    const reports = loadBenchmarkReports(cwd);
+    const html = generateBenchmarkReportHtml(reports, opts);
+    const filePath = path.join(reports.reportsDir, opts.fileName || 'benchmark-report.html');
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, html, 'utf8');
+    return {
+      file: filePath,
+      summary: buildBenchmarkSummary(reports, opts.matrixSummary),
+    };
+  }
+
+  module.exports = {
+    loadBenchmarkReports,
+    buildBenchmarkSummary,
+    generateBenchmarkReportHtml,
+    writeBenchmarkReport,
+  };
 };
 
   // ── ./src/format/dashboard ──
@@ -4853,7 +5291,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '5.3.0',
+  version: '5.5.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -6571,7 +7009,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '5.3.0';
+const VERSION = '5.5.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -7325,7 +7763,7 @@ function _coverageBar(pct, width) {
   return '\u2588'.repeat(filled) + '\u2591'.repeat(width - filled);
 }
 
-function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson, budgetLimit, coverageResult, isAutoBudget) {
+function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson, budgetLimit, coverageResult, isAutoBudget, configuredMaxTokens) {
   const reduction = inputTokens > 0 ? (100 - (finalTokens / inputTokens) * 100).toFixed(1) : 0;
   const overBudget = finalTokens > (budgetLimit || 6000);
   if (asJson) {
@@ -7363,6 +7801,10 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
     const budgetLabel = isAutoBudget
       ? `${budgetLimit || 6000} (auto-scaled)`
       : `${budgetLimit || 6000} (fixed)`;
+    if (isAutoBudget && configuredMaxTokens && configuredMaxTokens !== budgetLimit) {
+      console.warn(`[sigmap] note: autoMaxTokens is active — your maxTokens:${configuredMaxTokens} config was overridden by auto-scaled budget (${budgetLimit})`);
+      console.warn(`  to use your value, set "autoMaxTokens": false in gen-context.config.json`);
+    }
     console.log(`[sigmap] report:`);
     console.log(`  version         : ${VERSION}`);
     console.log(`  files processed : ${fileCount}`);
@@ -7372,7 +7814,11 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
     console.log(`  budget limit    : ${budgetLabel}`);
     console.log(`  reduction       : ${reduction}%`);
     if (coverageResult) {
-      console.log(`  coverage        : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} source files included`);
+      const skipNote = coverageResult.nonCodeSkipped > 0
+        ? `  (${coverageResult.nonCodeSkipped} non-code files skipped — json, md, config)`
+        : '';
+      console.log(`  coverage        : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} code files included`);
+      if (skipNote) console.log(`                  ${skipNote}`);
       console.log(`  confidence      : ${coverageResult.confidence}`);
       if (coverageResult.perModule && coverageResult.perModule.size > 0) {
         console.log('');
@@ -7383,6 +7829,15 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
           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}`);
         }
+        const lowModules = [...coverageResult.perModule.entries()].filter(([, m]) => m.pct < 50 && m.total > 0);
+        if (lowModules.length > 0) {
+          console.log('');
+          console.log('  tip: modules marked "\u2190 attention needed" have <50% code-file coverage.');
+          console.log('       Common causes:');
+          console.log('         \u2022 token budget dropped files \u2014 raise maxTokens or use strategy:"per-module"');
+          console.log('         \u2022 srcDir path includes non-code files \u2014 check .contextignore or exclude config');
+          console.log('         \u2022 srcDir path is wrong \u2014 verify srcDirs in gen-context.config.json');
+        }
       }
     }
     if (overBudget) console.warn(`[sigmap] WARNING: output (${finalTokens} tokens) exceeds budget (${budgetLimit || 6000})`);
@@ -7890,7 +8345,7 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
   }
 
   if (reportMode || process.argv.includes('--report')) {
-    printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, effectiveMaxTokens, result.coverageResult, config.autoMaxTokens !== false && effectiveMaxTokens !== config.maxTokens);
+    printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, effectiveMaxTokens, result.coverageResult, config.autoMaxTokens !== false && effectiveMaxTokens !== config.maxTokens, config.maxTokens);
   }
 
   // Usage tracking (v0.9) — optional append-only NDJSON log
@@ -9056,7 +9511,7 @@ function main() {
       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(`  file access     : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} files accessible in srcDirs`);
       }
       console.log(`  strategy        : ${result.strategy}`);
       console.log(`  token reduction : ${result.tokenReductionPct !== null ? result.tokenReductionPct + '%' : 'no history'}`);

package/package.json

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

package/src/analysis/coverage-score.js

@@ -1,10 +1,12 @@
 'use strict';
 
 /**
- * SigMap coverage scorer — v4.0.0
+ * SigMap coverage scorer — v5.5.0
+ *
+ * Measures what fraction of *code* files made it into the context output
+ * after token-budget application. Non-code files (json, md, config) are
+ * counted separately as `nonCodeSkipped` so the grade reflects real coverage.
  *
- * 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
  *
@@ -19,10 +21,23 @@
  *   total: number,
  *   included: number,
  *   dropped: number,
+ *   nonCodeSkipped: number,
  *   confidence: 'HIGH'|'MEDIUM'|'LOW',
  *   perModule: Map<string, {total:number, included:number, pct:number}>,
  * }}
  */
+
+const CODE_EXTS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt',
+  '.cs', '.cpp', '.c', '.h', '.hpp',
+  '.swift', '.dart', '.scala', '.php',
+  '.vue', '.svelte', '.css', '.scss',
+  '.sql', '.graphql', '.proto', '.tf',
+  '.lua', '.r', '.jl', '.ex', '.exs',
+  '.sh', '.bash', '.zsh', '.ps1',
+]);
+
 function coverageScore(cwd, fileEntries, config) {
   const fs   = require('fs');
   const path = require('path');
@@ -41,12 +56,17 @@ function coverageScore(cwd, fileEntries, config) {
 
   const includedSet = new Set((fileEntries || []).map(f => f.filePath));
 
-  // Walk all source files from srcDirs
+  // Walk srcDirs: separate code files from non-code files
+  const allFiles  = [];
   const allSource = [];
   for (const relDir of srcDirs) {
     const absDir = path.resolve(cwd, relDir);
-    if (fs.existsSync(absDir)) _walk(absDir, excludeSet, allSource);
+    if (fs.existsSync(absDir)) _walk(absDir, excludeSet, allFiles);
+  }
+  for (const f of allFiles) {
+    if (CODE_EXTS.has(path.extname(f).toLowerCase())) allSource.push(f);
   }
+  const nonCodeSkipped = allFiles.length - allSource.length;
 
   const total    = allSource.length;
   const included = allSource.filter(f => includedSet.has(f)).length;
@@ -66,7 +86,7 @@ function coverageScore(cwd, fileEntries, config) {
     perModule.set(relDir, { total: modFiles.length, included: modIncl, pct: modPct });
   }
 
-  return { score: pct, grade, total, included, dropped, confidence, perModule };
+  return { score: pct, grade, total, included, dropped, nonCodeSkipped, confidence, perModule };
 }
 
 function _walk(dir, excludeSet, out) {
@@ -82,4 +102,4 @@ function _walk(dir, excludeSet, out) {
   }
 }
 
-module.exports = { coverageScore };
+module.exports = { coverageScore, CODE_EXTS };

package/src/mcp/server.js

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