sigmap 6.11.1 → 6.13.0

package/package.json

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

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "6.11.1",
+  "version": "6.13.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "6.11.1",
+  "version": "6.13.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/extractors/javascript.js

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

package/src/extractors/typescript.js

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

package/src/format/dashboard.js

@@ -304,6 +304,106 @@ function sparkline(values) {
   }).join('');
 }
 
+function escapeAttr(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}
+
+// Surgical Context (v6.12.0): read the published token-reduction benchmark and
+// aggregate it for the dashboard panel. Numbers are never hand-typed — they come
+// straight from benchmarks/reports/token-reduction.json.
+function readTokenReduction(cwd) {
+  const p = path.join(cwd, 'benchmarks', 'reports', 'token-reduction.json');
+  let data;
+  try { data = JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+  const repos = Array.isArray(data.repos) ? data.repos : [];
+  if (repos.length === 0) return null;
+
+  let baseline = 0, signatures = 0, surgical = 0, hasSurgical = false;
+  for (const r of repos) {
+    baseline += toNumber(r.rawTokens) || 0;
+    signatures += toNumber(r.finalTokens) || 0;
+    const s = toNumber(r.surgicalTokens);
+    if (s !== null) { surgical += s; hasSurgical = true; }
+  }
+
+  const out = {
+    version: data.version || null,
+    repoCount: repos.length,
+    baseline,
+    signatures,
+    savedPct: baseline > 0 ? Math.round((1 - signatures / baseline) * 1000) / 10 : 0,
+    perRepo: repos.map((r) => ({
+      repo: r.repo,
+      language: r.language,
+      rawTokens: toNumber(r.rawTokens) || 0,
+      finalTokens: toNumber(r.finalTokens) || 0,
+      reductionPct: toNumber(r.reductionPct) || 0,
+    })),
+  };
+  if (hasSurgical) {
+    out.surgical = surgical;
+    out.surgicalSavedPct = baseline > 0 ? Math.round((1 - surgical / baseline) * 1000) / 10 : 0;
+  }
+  return out;
+}
+
+function tokenReductionPanelHtml(tr) {
+  if (!tr) {
+    return '<div class="panel"><div class="label">Token Reduction</div>' +
+      '<div class="value" style="font-size:13px">No token-reduction benchmark found — run the token benchmark to populate this panel.</div></div>';
+  }
+  const fmt = (n) => Number(n).toLocaleString('en-US');
+  const tiers = [
+    { label: 'Whole-file baseline', value: fmt(tr.baseline) + ' tok' },
+    { label: 'Ranked signatures (ask)', value: fmt(tr.signatures) + ' tok' },
+  ];
+  if (tr.surgical != null) {
+    tiers.push({ label: 'Surgical (index + delta)', value: fmt(tr.surgical) + ' tok' });
+    tiers.push({ label: 'Saved (surgical)', value: tr.surgicalSavedPct + '%' });
+  } else {
+    tiers.push({ label: 'Saved', value: tr.savedPct + '%' });
+  }
+  const tierHtml = tiers.map((t) =>
+    `<div class="card"><div class="label">${escapeAttr(t.label)}</div><div class="value">${escapeAttr(t.value)}</div></div>`
+  ).join('');
+
+  // Proportional comparison bar (baseline = full width).
+  const sigPct = tr.baseline > 0 ? Math.max(0.4, (tr.signatures / tr.baseline) * 100) : 0;
+  const surgPct = (tr.surgical != null && tr.baseline > 0) ? Math.max(0.4, (tr.surgical / tr.baseline) * 100) : null;
+  const barRow = (label, pct, color) =>
+    `<div style="margin:4px 0;font-size:11px;color:#8ea0d9">${escapeAttr(label)}</div>` +
+    `<div style="background:#0a0f1e;border:1px solid #223056;border-radius:6px;height:14px;overflow:hidden">` +
+    `<div style="width:${pct.toFixed(1)}%;height:100%;background:${color}"></div></div>`;
+  const bars = [
+    barRow('Whole-file baseline (100%)', 100, '#3a4a78'),
+    barRow(`Ranked signatures — ${tr.savedPct}% saved`, sigPct, '#2e7d6b'),
+    surgPct != null ? barRow(`Surgical — ${tr.surgicalSavedPct}% saved`, surgPct, '#5ad1a8') : '',
+  ].filter(Boolean).join('');
+
+  const rows = tr.perRepo.slice(0, 8).map((r) =>
+    `<tr><td>${escapeAttr(r.repo)}</td><td>${escapeAttr(r.language)}</td>` +
+    `<td style="text-align:right">${fmt(r.rawTokens)}</td>` +
+    `<td style="text-align:right">${fmt(r.finalTokens)}</td>` +
+    `<td style="text-align:right">${r.reductionPct}%</td></tr>`
+  ).join('');
+
+  return [
+    '<div class="panel">',
+    `<div class="label">Token Reduction — ${tr.repoCount} benchmark repos${tr.version ? ' · v' + escapeAttr(tr.version) : ''}</div>`,
+    `<div class="grid" style="margin:8px 0">${tierHtml}</div>`,
+    bars,
+    '<table style="width:100%;border-collapse:collapse;margin-top:10px;font-size:12px">',
+    '<thead><tr style="color:#8ea0d9;text-align:left">',
+    '<th>Repo</th><th>Lang</th><th style="text-align:right">Baseline</th><th style="text-align:right">Signatures</th><th style="text-align:right">Saved</th>',
+    '</tr></thead>',
+    `<tbody>${rows}</tbody>`,
+    '</table>',
+    '</div>',
+  ].join('');
+}
+
 function buildDashboardData(cwd, health) {
   const entries = readLog(cwd);
   const recent = entries.slice(-30);
@@ -326,15 +426,19 @@ function buildDashboardData(cwd, health) {
     extractorCoverage: coverage.pct,
   };
 
+  const tokenReduction = readTokenReduction(cwd);
+
   return {
     summary,
     tokenReductionTrend,
     hitAt5Trend,
     coverage,
+    tokenReduction,
     charts: {
       tokenReductionSvg: lineChartSvg(tokenReductionTrend, 'Token reduction trend (last 30 tracked runs)', '%'),
       hitAt5Svg: lineChartSvg(hitAt5Trend, 'hit@5 trend (last 30 benchmark runs)', ''),
       coverageSvg: barChartSvg(coverage.perLanguage),
+      tokenSavingsPanel: tokenReductionPanelHtml(tokenReduction),
     },
   };
 }
@@ -379,6 +483,7 @@ function generateDashboardHtml(cwd, health) {
     '<h1>SigMap v2.10 dashboard</h1>',
     '<div class="sub">Self-contained report. No external scripts, styles, or network calls.</div>',
     `<div class="grid">${cardHtml}</div>`,
+    data.charts.tokenSavingsPanel,
     `<div class="panel">${data.charts.tokenReductionSvg}</div>`,
     `<div class="panel">${data.charts.hitAt5Svg}</div>`,
     `<div class="panel">${data.charts.coverageSvg}</div>`,

package/src/mcp/handlers.js

@@ -448,4 +448,61 @@ function getImpact(args, cwd) {
   }
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
+/**
+ * get_lines({ file, start, end }) → string
+ *
+ * Surgical Context demand-driven fetch: returns an exact, clamped line range from a
+ * source file. The path is resolved inside the project root (no traversal escape) and
+ * the returned lines are secret-scanned via the same redactor used for signatures.
+ */
+function getLines(args, cwd) {
+  if (!args || !args.file) return 'Missing required argument: file';
+
+  const rel = String(args.file).replace(/\\/g, '/').replace(/^\//, '');
+  const abs = path.resolve(cwd, rel);
+
+  // Sandbox: refuse paths that resolve outside the project root.
+  const root = path.resolve(cwd);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    return `Refused: ${rel} resolves outside the project root`;
+  }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    return `File not found: ${rel}`;
+  }
+
+  const start = parseInt(args.start, 10);
+  const end = parseInt(args.end, 10);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    return 'Arguments "start" and "end" must be numbers (1-based line numbers).';
+  }
+
+  let lines;
+  try {
+    lines = fs.readFileSync(abs, 'utf8').split('\n');
+  } catch (err) {
+    return `Could not read ${rel}: ${err.message}`;
+  }
+
+  const total = lines.length;
+  const from = Math.max(1, Math.min(start, end));
+  const to = Math.min(total, Math.max(start, end));
+  if (from > total) return `${rel} has only ${total} lines; requested ${start}-${end}`;
+
+  const slice = lines.slice(from - 1, to);
+
+  // Redaction scan: reuse the signature secret scanner line-by-line.
+  let safeLines = slice;
+  try {
+    const { scan } = require('../security/scanner');
+    safeLines = scan(slice, rel).safe;
+  } catch (_) {} // non-fatal: fall back to raw slice
+
+  return [
+    `# ${rel}:${from}-${to}`,
+    '```',
+    ...safeLines,
+    '```',
+  ].join('\n');
+}
+
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines };

package/src/mcp/server.js

@@ -8,17 +8,17 @@
  *
  * Supported methods:
  *   initialize        → serverInfo + capabilities
- *   tools/list        → 3 tool definitions
+ *   tools/list        → 10 tool definitions
  *   tools/call        → dispatch to handler, return result
  */
 
 const readline = require('readline');
 const { TOOLS } = require('./tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '6.11.1',
+  version: '6.13.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -75,6 +75,7 @@ function dispatch(msg, cwd) {
       else if (name === 'list_modules') text = listModules(args, cwd);
       else if (name === 'query_context') text = queryContext(args, cwd);
       else if (name === 'get_impact') text = getImpact(args, cwd);
+      else if (name === 'get_lines') text = getLines(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -1,8 +1,9 @@
 'use strict';
 
 /**
- * MCP tool definitions for SigMap.
- * Three tools: read_context, search_signatures, get_map.
+ * MCP tool definitions for SigMap (10 tools).
+ * read_context, search_signatures, get_map, create_checkpoint, get_routing,
+ * explain_file, list_modules, query_context, get_impact, get_lines.
  */
 
 const TOOLS = [
@@ -168,6 +169,34 @@ const TOOLS = [
       required: ['file'],
     },
   },
+  {
+    name: 'get_lines',
+    description:
+      'Fetch an exact line range from a source file on demand — the Surgical Context ' +
+      'workhorse. Signatures carry `path:start-end` anchors; call this to read just those ' +
+      'lines instead of re-opening the whole file. Lines are clamped to the file bounds and ' +
+      'secret-scanned (redacted) before return. Path is sandboxed to the project root.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          description:
+            'Relative path from the project root (e.g. "src/config/loader.js"). ' +
+            'Use the path shown in a signature anchor. Use forward slashes.',
+        },
+        start: {
+          type: 'number',
+          description: '1-based start line (inclusive). Clamped to the file bounds.',
+        },
+        end: {
+          type: 'number',
+          description: '1-based end line (inclusive). Clamped to the file bounds.',
+        },
+      },
+      required: ['file', 'start', 'end'],
+    },
+  },
 ];
 
 module.exports = { TOOLS };