sigmap 6.11.1 → 6.13.0

package/gen-context.js

@@ -916,61 +916,92 @@ __factories["./src/extractors/java"] = function(module, exports) {
 
 // ── ./src/extractors/javascript ──
 __factories["./src/extractors/javascript"] = function(module, exports) {
-  
+
+  const { lineAt, withAnchor } = __require('./src/extractors/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) {
     let depth = 1;
     let i = startIndex;
@@ -982,16 +1013,22 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
     }
     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);
   }
@@ -1016,18 +1053,17 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
   }
 
   function formatReturnHint(type) {
-    return type ? ` \u2192 ${type}` : '';
+    return type ? ` → ${type}` : '';
   }
-  
+
   function normalizeParams(params) {
     if (!params) return '';
     return params.trim().replace(/\s+/g, ' ');
   }
-  
+
   module.exports = { extract };
-  
-};
 
+};
 // ── ./src/extractors/kotlin ──
 __factories["./src/extractors/kotlin"] = function(module, exports) {
   
@@ -1799,101 +1835,164 @@ __factories["./src/extractors/swift"] = function(module, exports) {
 
 // ── ./src/extractors/typescript ──
 __factories["./src/extractors/typescript"] = function(module, exports) {
-  
+
+  const { lineAt, withAnchor } = __require('./src/extractors/line-anchor');
+
   /**
    * Extract signatures from TypeScript source code.
+   * Top-level declarations carry a `:start-end` line anchor (see line-anchor.js);
+   * indented members do not.
    * @param {string} src - Raw file content
    * @returns {string[]} Array of signature strings
    */
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
-  
-    // Strip single-line comments
+    // anchors[i] is [start, end] for a top-level sig, or null for an indented member.
+    // Kept parallel to `sigs` so existing push/mutation logic stays untouched;
+    // anchors are applied once at return.
+    const anchors = [];
+
+    // Strip comments to simplify matching. Block comments are blanked
+    // newline-by-newline (non-newline chars → spaces) so character offsets AND
+    // line numbers stay exact. Line comments preserve their trailing newline.
     const stripped = src
       .replace(/\/\/.*$/gm, '')
-      .replace(/\/\*[\s\S]*?\*\//g, '');
-  
+      .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+
+    // Index of the closing brace for a block whose body starts at bodyStart.
+    const blockEndIdx = (bodyStart) => bodyStart + extractBlock(stripped, bodyStart).length;
+
     // Exported interfaces
     for (const m of stripped.matchAll(/^export\s+interface\s+(\w+)(?:<[^{]*>)?\s*(?:extends\s+[^{]+)?\{/gm)) {
+      const bodyStart = m.index + m[0].length;
       sigs.push(`export interface ${m[1]}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
       // Collect members
-      const start = m.index + m[0].length;
-      const block = extractBlock(stripped, start);
+      const block = extractBlock(stripped, bodyStart);
       const members = extractInterfaceMembers(block);
-      for (const mem of members) sigs.push(`  ${mem}`);
+      for (const mem of members) {
+        sigs.push(`  ${mem.text}`);
+        anchors.push([lineAt(stripped, bodyStart + mem.start), lineAt(stripped, bodyStart + mem.end)]);
+      }
     }
-  
+
     // Exported type aliases
     for (const m of stripped.matchAll(/^export\s+type\s+(\w+)(?:<[^=]*>)?\s*=/gm)) {
       sigs.push(`export type ${m[1]}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, m.index + m[0].length)]);
     }
-  
+
     // Exported enums
     for (const m of stripped.matchAll(/^export\s+(?:const\s+)?enum\s+(\w+)\s*\{/gm)) {
+      const bodyStart = m.index + m[0].length;
       sigs.push(`export enum ${m[1]}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
     }
-  
+
     // Classes (exported and internal)
     const classRegex = /^(export\s+)?(abstract\s+)?class\s+(\w+)(?:<[^{]*>)?(?:\s+extends\s+[\w<>, .]+)?(?:\s+implements\s+[\w<> ,]+)?\s*\{/gm;
     for (const m of stripped.matchAll(classRegex)) {
       const prefix = m[1] ? 'export ' : '';
       const abs = m[2] ? 'abstract ' : '';
+      const bodyStart = m.index + m[0].length;
       sigs.push(`${prefix}${abs}class ${m[3]}`);
-      const start = m.index + m[0].length;
-      const block = extractBlock(stripped, start);
+      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}`);
+      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)
     for (const m of stripped.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)(?:\s*:\s*[^{]+)?\s*\{/gm)) {
       const asyncKw = /export\s+async/.test(m[0]) ? 'async ' : '';
       const params = normalizeParams(m[2]);
       const retMatch = m[0].match(/\)\s*:\s*([^{]+)\s*\{/);
       const retType = retMatch ? retMatch[1].trim().replace(/\s+/g, ' ').slice(0, 30) : '';
-      const retStr = retType ? ` \u2192 ${retType}` : '';
+      const retStr = retType ? ` → ${retType}` : '';
+      const bodyStart = m.index + m[0].length;
       sigs.push(`export ${asyncKw}function ${m[1]}(${params})${retStr}`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
+
+      // Hooks: capture compact return object shape for use* functions.
+      if (m[1].startsWith('use')) {
+        const body = stripped.slice(bodyStart, bodyStart + 800);
+        const ret = body.match(/return\s*\{([^}]{1,260})\}/);
+        if (ret) {
+          const keys = ret[1]
+            .split(',')
+            .map((s) => s.trim().split(':')[0].split('(')[0].trim())
+            .filter(Boolean)
+            .slice(0, 8);
+          if (keys.length) {
+            sigs[sigs.length - 1] += ` → { ${keys.join(', ')} }`;
+          }
+        }
+      }
     }
-  
+
     // Exported arrow functions / const functions
     for (const m of stripped.matchAll(/^export\s+const\s+(\w+)\s*(?::\s*[^=]+)?\s*=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*[^=>{]+)?\s*=>/gm)) {
       const asyncKw = /=\s*async\s+/.test(m[0]) ? 'async ' : '';
       const params = normalizeParams(m[2]);
       sigs.push(`export const ${m[1]} = ${asyncKw}(${params}) =>`);
+      const bodyStart = stripped.indexOf('{', m.index + m[0].length);
+      const endLn = bodyStart !== -1
+        ? lineAt(stripped, blockEndIdx(bodyStart + 1))
+        : lineAt(stripped, m.index + m[0].length);
+      anchors.push([lineAt(stripped, m.index), endLn]);
+
+      // Hooks: capture compact return object shape for use* functions.
+      if (m[1].startsWith('use')) {
+        if (bodyStart !== -1) {
+          const body = stripped.slice(bodyStart, bodyStart + 800);
+          const ret = body.match(/return\s*\{([^}]{1,260})\}/);
+          if (ret) {
+            const keys = ret[1]
+              .split(',')
+              .map((s) => s.trim().split(':')[0].split('(')[0].trim())
+              .filter(Boolean)
+              .slice(0, 8);
+            if (keys.length) {
+              sigs[sigs.length - 1] += ` → { ${keys.join(', ')} }`;
+            }
+          }
+        }
+      }
     }
 
     // Zustand stores: export const useXxxStore = create<State>()(...)
     for (const m of stripped.matchAll(/^export\s+const\s+(use\w+Store)\s*=\s*create(?:<[^>]*>)?\s*\(/gm)) {
-      // Extract the State interface name from create<StateName>
       const stateType = m[0].match(/create<([\w]+)>/)?.[1] || '';
+      const startLn = lineAt(stripped, m.index);
       sigs.push(`export const ${m[1]} = create<${stateType}>(...)`);
-      // Extract action/state keys from the embedded interface in same file
+      anchors.push([startLn, startLn]);
       const ifaceRe = new RegExp(`interface\\s+${stateType}\\s*\\{([\\s\\S]*?)\\}`);
       const ifm = stripped.match(ifaceRe);
       if (ifm) {
-        for (const fm of ifm[1].matchAll(/^\s+(\w+)\s*(?:\([^)]*\))?\s*:/gm)) {
-          sigs.push(`  ${fm[1]}`);
-        }
+        for (const fm of ifm[1].matchAll(/^\s+(\w+)\s*(?:\([^)]*\))?\s*:/gm)) { sigs.push(`  ${fm[1]}`); anchors.push(null); }
       }
     }
 
-    // API client objects: export default { method: async (...) => ... }
-    // Pattern: const xxxApi = { methodName: async ... }
+    // API client objects: const xxxApi = { method: async () => {} }
     for (const m of stripped.matchAll(/^(?:export\s+default\s+|const\s+)(\w*[Aa]pi\w*)\s*=\s*\{/gm)) {
-      const apiName = m[1];
-      const start = m.index + m[0].length;
-      const block = extractBlock(stripped, start);
-      const methods = [];
-      for (const mm of block.matchAll(/^\s+(\w+)\s*:\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/gm)) {
-        methods.push(mm[1]);
+      const bodyStart = m.index + m[0].length;
+      const block = extractBlock(stripped, bodyStart);
+      const methods = [...block.matchAll(/^\s+(\w+)\s*:\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/gm)].map(mm => mm[1]);
+      if (methods.length) {
+        sigs.push(`${m[1]}: { ${methods.join(', ')} }`);
+        anchors.push([lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)]);
       }
-      if (methods.length) sigs.push(`${apiName}: { ${methods.join(', ')} }`);
     }
-  
-    return sigs.slice(0, 35);
+
+    return sigs
+      .map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s))
+      .slice(0, 35);
   }
-  
+
   function extractBlock(src, startIndex) {
     let depth = 1;
     let i = startIndex;
@@ -1905,47 +2004,59 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
     }
     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)
+    // Public methods (skip private/protected/_ prefixed and control-flow keywords)
     const methodRe = /^\s+(?:public\s+|static\s+|async\s+|override\s+)*(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)(?:\s*:\s*[^{;]+)?\s*\{/gm;
     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 ? ` \u2192 ${retType}` : '';
-      members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      const retStr = retType ? ` → ${retType}` : '';
+      members.push({ text: `${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`, start, end });
     }
     return members.slice(0, 8);
   }
-  
+
   function normalizeParams(params) {
     if (!params) return '';
     return params.trim().replace(/\s+/g, ' ').replace(/:[^,)]+/g, '').trim();
   }
-  
+
   module.exports = { extract };
-  
-};
 
+};
 // ── ./src/extractors/graphql ──
 __factories["./src/extractors/graphql"] = function(module, exports) {
   
@@ -4052,6 +4163,96 @@ __factories["./src/format/benchmark-report"] = function(module, exports) {
       }).join('');
     }
 
+    function escapeAttr(s) {
+      return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+      ));
+    }
+
+    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('');
+      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);
@@ -4070,15 +4271,18 @@ __factories["./src/format/benchmark-report"] = function(module, exports) {
         overBudgetStreak: overBudgetStreak(entries),
         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),
         },
       };
     }
@@ -4112,6 +4316,7 @@ __factories["./src/format/benchmark-report"] = function(module, exports) {
         '<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>`,
@@ -5719,7 +5924,56 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     }
   }
 
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
+  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);
+
+    let safeLines = slice;
+    try {
+      const { scan } = __require('./src/security/scanner');
+      safeLines = scan(slice, rel).safe;
+    } catch (_) {}
+
+    return [
+      `# ${rel}:${from}-${to}`,
+      '```',
+      ...safeLines,
+      '```',
+    ].join('\n');
+  }
+
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines };
 };
 
 // ── ./src/learning/weights ──
@@ -5890,17 +6144,17 @@ __factories["./src/mcp/server"] = function(module, exports) {
    *
    * 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('./src/mcp/tools');
-  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact } = __require('./src/mcp/handlers');
-  
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines } = __require('./src/mcp/handlers');
+
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '6.11.1',
+  version: '6.13.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -5957,6 +6211,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
         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;
@@ -6184,8 +6439,36 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         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 };
   
 };
@@ -8695,7 +8978,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '6.11.1';
+const VERSION = '6.13.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -8982,13 +9265,42 @@ function computeEffectiveMaxTokens(fileEntries, config) {
 
 function applyTokenBudget(fileEntries, maxTokens) {
   // fileEntries: [{ filePath, sigs, mtime }]
-  // Reserve ~10% for formatting overhead (section headers, code fences, top-level header)
-  const effectiveBudget = Math.floor(maxTokens * 0.90);
-  let total = fileEntries.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')), 0);
-  if (total <= effectiveBudget) return fileEntries;
+  // Per-file rendered overhead: "### <path>", code fences, trailing blank line.
+  // A signature-only budget undercounts this, so when many files survive the
+  // section headers alone can blow maxTokens.
+  const sectionOverhead = (e) => estimateTokens(String(e.filePath || '')) + 6;
+  const renderedTotal = (entries) =>
+    entries.reduce((s, e) => s + estimateTokens(e.sigs.join('\n')) + sectionOverhead(e), 0);
+  // The generated file also carries a ~150-token fixed preamble (SigMap command
+  // table + headers). Reserve at least that much so small budgets don't overflow;
+  // for large budgets this matches the historical 10% reserve.
+  const budgetForEntries = Math.max(1, maxTokens - Math.max(200, Math.ceil(maxTokens * 0.10)));
+  let total = renderedTotal(fileEntries);
+  if (total <= budgetForEntries) return fileEntries;
+
+  // v6.12 Surgical Context — progressive disclosure: before dropping whole files,
+  // collapse signature BODIES to their line-anchor pointers (keep `symbol :start-end`).
+  // Only sigs that actually carry an anchor shrink; the agent can re-fetch bodies via
+  // the get_lines MCP tool. This degrades gracefully instead of losing files outright.
+  let working = fileEntries;
+  const collapsed = fileEntries.map((e) => {
+    const slim = (e.sigs || []).map((s) => {
+      const line = toIndexLine(s);
+      return line && /:\d+-\d+/.test(line) ? line : s; // replace only when it yields an anchor
+    });
+    return { ...e, sigs: slim };
+  });
+  const collapsedRendered = renderedTotal(collapsed);
+  if (collapsedRendered < total) {
+    console.warn(`[sigmap] budget: collapsed bodies to anchors, reclaimed ~${total - collapsedRendered} tokens`);
+    working = collapsed;
+    total = collapsedRendered;
+    // Collapsing keeps every file, so the section overhead must fit too — not just sigs.
+    if (total <= budgetForEntries) return working;
+  }
 
   // Sort by drop priority (drop first = index 0)
-  const withPriority = fileEntries.map((e) => {
+  const withPriority = working.map((e) => {
     let priority = 0;
     let dropReason = 'budget: low recency';
     if (isGeneratedFile(e.filePath)) { priority = 10; dropReason = 'budget: generated file'; }
@@ -9011,12 +9323,13 @@ function applyTokenBudget(fileEntries, maxTokens) {
 
   const kept = [];
   const verboseDropped = [];
-  // Iterate forward: highest drop-priority files (generated=10, mock=9, test=8) are at index 0
-  // Drop those first until we're under budget, then keep everything else
+  // Iterate forward: highest drop-priority files (generated=10, mock=9, test=8) are at index 0.
+  // Drop those first until the RENDERED total (sigs + section overhead) fits maxTokens,
+  // then keep everything else.
+  let rendered = renderedTotal(withPriority);
   for (const entry of withPriority) {
-    const entryTokens = estimateTokens(entry.sigs.join('\n'));
-    if (total > effectiveBudget) {
-      total -= entryTokens;
+    if (rendered > budgetForEntries) {
+      rendered -= estimateTokens(entry.sigs.join('\n')) + sectionOverhead(entry);
       verboseDropped.push({ filePath: entry.filePath, reason: entry.dropReason });
     } else {
       kept.push(entry);
@@ -10576,6 +10889,40 @@ function buildMiniContext(ranked, cwd) {
   return lines.join('\n');
 }
 
+// Surgical Context Phase 2 (v6.12.0): collapse one signature to a symbol-header
+// pointer — `<declaration head>  :start-end` — dropping param lists, return types,
+// and any body so the agent fetches the real lines on demand via the get_lines MCP tool.
+function toIndexLine(sig) {
+  if (typeof sig !== 'string') return '';
+  // Anchor is `:start-end`, optionally followed by a `# doc hint` (Python extractor).
+  const m = sig.match(/\s*:(\d+)-(\d+)(?:\s*#.*)?\s*$/);
+  if (!m) {
+    // No anchor (e.g. an indented member) — keep a trimmed head so it stays listed.
+    return sig.trim().slice(0, 60);
+  }
+  const range = `:${m[1]}-${m[2]}`;
+  let head = sig.slice(0, m.index).trim();
+  const paren = head.indexOf('(');
+  if (paren > 0) head = head.slice(0, paren).trim();      // drop params
+  head = head.replace(/\s*[=→].*$/, '').trim();           // drop return type / assignment tail
+  return head ? `${head}  ${range}` : range;
+}
+
+// Two-tier index output: emit only `file → [symbol:start-end]` headers (no bodies).
+function buildIndexContext(ranked, cwd) {
+  const lines = [
+    '# SigMap Query Context (index mode)',
+    `Generated: ${new Date().toISOString()}`,
+    '> Symbol index only — fetch exact lines on demand via the `get_lines` MCP tool.',
+    '',
+  ];
+  for (const { file, sigs } of ranked) {
+    const idx = sigs.slice(0, 40).map(toIndexLine).filter(Boolean);
+    lines.push(`## ${file}`, '```', ...idx, '```', '');
+  }
+  return lines.join('\n');
+}
+
 function computeCurrentRisk(cwd) {
   try {
     const { execSync } = require('child_process');
@@ -10746,7 +11093,7 @@ function main() {
   const mode = modeIdx !== -1
     ? args[modeIdx + 1]
     : (config.mode || 'default');
-  const VALID_MODES = ['default', 'fast', 'full', 'both'];
+  const VALID_MODES = ['default', 'fast', 'full', 'both', 'index'];
   if (mode && !VALID_MODES.includes(mode)) {
     console.error(`[sigmap] unknown --mode "${mode}". Valid: ${VALID_MODES.join(', ')}`);
     process.exit(1);
@@ -10825,9 +11172,23 @@ function main() {
       }
     }
 
+    // v6.12: Delta context — restrict to files changed since a git ref (--since <ref>).
+    const sinceIdx = args.indexOf('--since');
+    if (sinceIdx !== -1 && args[sinceIdx + 1]) {
+      const baseRef = args[sinceIdx + 1];
+      const changed = getFilesChangedSinceBase(cwd, baseRef);
+      const before = ranked.length;
+      ranked = ranked.filter((r) => changed.has(path.resolve(cwd, r.file)));
+      if (!args.includes('--json')) {
+        process.stderr.write(`[sigmap] Δ since ${baseRef}: ${ranked.length}/${before} ranked files changed\n`);
+      }
+    }
+
     // v6.8: Save session for future --followup calls
     saveSession(cwd, { intent, topFiles: ranked.slice(0, 5).map(r => ({ file: r.file, score: r.score })), query });
-    const miniCtx = buildMiniContext(ranked, cwd);
+    // v6.12: Two-tier output — `--mode index` emits symbol pointers only (bodies via get_lines).
+    const indexMode = mode === 'index' || args.includes('--index');
+    const miniCtx = indexMode ? buildIndexContext(ranked, cwd) : buildMiniContext(ranked, cwd);
     const outPath = path.join(cwd, '.context', 'query-context.md');
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, miniCtx, 'utf8');