sigmap 6.10.11 → 6.11.0

package/CHANGELOG.md

@@ -10,6 +10,27 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [6.11.0] — 2026-06-03
+
+### Added
+
+- **Line anchors on signatures (Surgical Context Phase 1)** — top-level TypeScript and Python signatures now carry a `:start-end` line anchor (e.g. `export class UserRepository  :18-36`), so agents can read the exact lines instead of re-opening whole files. Rendered automatically by `ask`, `CLAUDE.md`, and every adapter — no consumer changes (closes #212).
+- New shared `src/extractors/line-anchor.js` helper (`lineAt`, `anchor`, `withAnchor`).
+
+### Fixed
+
+- **Block-comment / docstring line-shift bug** — comment stripping that blanked `/* */` and `"""…"""` to `''` destroyed newlines and corrupted line numbers. Replaced with a newline-preserving strip so char-offset → line-number stays exact. The Python AST and regex fallback paths now produce identical anchors.
+
+---
+
+## [6.10.12] — 2026-05-27
+
+### Added
+
+- **Portable `.mcp.json` support** — MCP server registration now detects and prioritizes `.mcp.json` at the project root, making MCP configuration portable across multiple agentic harnesses (Claude, Cursor, Windsurf, etc.). Falls back to `.claude/settings.json` if `.mcp.json` doesn't exist (closes #209).
+
+---
+
 ## [6.10.11] — 2026-05-22
 
 ### Fixed

package/gen-context.js

@@ -5901,7 +5901,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '6.10.11',
+  version: '6.11.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -8655,7 +8655,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '6.10.11';
+const VERSION = '6.11.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -10455,9 +10455,11 @@ function registerMcp(cwd, scriptPath) {
     args: [path.resolve(scriptPath), '--mcp'],
   };
 
-  // JSON mcpServers targets: Claude, Cursor, Windsurf project, Windsurf global,
-  // VS Code (GitHub Copilot 1.99+), OpenCode project, OpenCode global, Gemini CLI
+  // JSON mcpServers targets: portable .mcp.json (priority), Claude, Cursor,
+  // Windsurf project, Windsurf global, VS Code (GitHub Copilot 1.99+),
+  // OpenCode project, OpenCode global, Gemini CLI
   const jsonTargets = [
+    path.join(cwd, '.mcp.json'),
     path.join(cwd, '.claude', 'settings.json'),
     path.join(cwd, '.cursor', 'mcp.json'),
     path.join(cwd, '.windsurf', 'mcp.json'),
@@ -10496,6 +10498,8 @@ function registerMcp(cwd, scriptPath) {
 
   // Print manual snippets for all targets
   console.warn('[sigmap] MCP / context server config snippets:');
+  console.warn('  .mcp.json (portable, recommended):');
+  console.warn(JSON.stringify({ mcpServers: { sigmap: serverEntry } }, null, 2));
   console.warn('  Claude / Cursor / Windsurf / VS Code / OpenCode / Gemini CLI:');
   console.warn(JSON.stringify({ mcpServers: { sigmap: serverEntry } }, null, 2));
   console.warn('  Zed (~/.config/zed/settings.json):');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "6.10.11",
+  "version": "6.11.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.10.11",
+  "version": "6.11.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

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

package/src/extractors/line-anchor.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Line-anchor helpers for Surgical Context (v6.11.0).
+ *
+ * Signatures carry their source location as a `:start-end` suffix so an agent
+ * can read the exact lines instead of re-opening the whole file. The anchor is
+ * a plain string suffix, which keeps the existing `string[]` signature contract
+ * intact — ranker, adapters, and CLAUDE.md render it for free.
+ */
+
+/**
+ * 1-based line number of character index `idx` within `src`.
+ * Counts newlines in the prefix, so it stays correct as long as the source
+ * being indexed preserves every newline (see the newline-preserving comment
+ * strips in the extractors).
+ *
+ * @param {string} src
+ * @param {number} idx
+ * @returns {number}
+ */
+function lineAt(src, idx) {
+  let line = 1;
+  const end = Math.min(idx, src.length);
+  for (let i = 0; i < end; i++) {
+    if (src.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+/**
+ * Render an anchor suffix: `  :start-end`.
+ * @param {number} start
+ * @param {number} end
+ * @returns {string}
+ */
+function anchor(start, end) {
+  return `  :${start}-${end}`;
+}
+
+/**
+ * Append a line anchor to a signature string.
+ * @param {string} sig
+ * @param {number} start
+ * @param {number} end
+ * @returns {string}
+ */
+function withAnchor(sig, start, end) {
+  return `${sig}${anchor(start, end)}`;
+}
+
+module.exports = { lineAt, anchor, withAnchor };

package/src/extractors/python.js

@@ -1,6 +1,27 @@
 'use strict';
 
 const path = require('path');
+const { lineAt } = require('./line-anchor');
+
+/**
+ * 1-based line of the last source line belonging to a top-level (indent 0)
+ * def/class body that starts at `startLine` (1-based). Trailing blank lines
+ * are excluded.
+ * @param {string[]} srcLines
+ * @param {number} startLine
+ * @returns {number}
+ */
+function pyBlockEnd(srcLines, startLine) {
+  let end = startLine;
+  for (let i = startLine; i < srcLines.length; i++) {
+    const line = srcLines[i];
+    if (line.trim() === '') continue;
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (indent === 0) break;
+    end = i + 1;
+  }
+  return end;
+}
 
 /**
  * Try to extract signatures using the native Python AST extractor.
@@ -42,21 +63,26 @@ function extract(src, filePath) {
 
   // noComments: strip only # comments, keep docstrings (needed for @decorator detection)
   const noComments = src.replace(/#.*$/gm, '');
-  // stripped: also strip docstrings (safe for regex matching)
+  // stripped: also strip docstrings (safe for regex matching). Docstrings are
+  // blanked newline-by-newline (non-newline chars → spaces) so character
+  // offsets and line numbers stay exact for line anchors.
   const stripped = noComments
-    .replace(/"""[\s\S]*?"""/g, '')
-    .replace(/'''[\s\S]*?'''/g, '');
+    .replace(/"""[\s\S]*?"""/g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/'''[\s\S]*?'''/g, (m) => m.replace(/[^\n]/g, ' '));
+  const srcLines = src.split('\n');
 
   // Classes
   for (const m of stripped.matchAll(/^class\s+(\w+)(?:\s*\(([^)]*)\))?\s*:/gm)) {
     const className = m[1];
     const baseName = m[2] ? m[2].trim() : '';
     const bodyStart = m.index + m[0].length;
+    const clsStart = lineAt(stripped, m.index);
+    const clsAnchor = `  :${clsStart}-${pyBlockEnd(srcLines, clsStart)}`;
 
     // Try @dataclass collapse
     const dcFields = tryExtractDataclassFields(stripped, m.index);
     if (dcFields !== null) {
-      sigs.push(`@dataclass ${className}(${dcFields})`);
+      sigs.push(`@dataclass ${className}(${dcFields})${clsAnchor}`);
       continue;
     }
 
@@ -64,13 +90,13 @@ function extract(src, filePath) {
     if (/(BaseModel|BaseSettings)/.test(baseName)) {
       const bmFields = tryExtractBaseModelFields(stripped, bodyStart);
       if (bmFields) {
-        sigs.push(`class ${className}(${baseName}) ${bmFields}`);
+        sigs.push(`class ${className}(${baseName}) ${bmFields}${clsAnchor}`);
         continue;
       }
     }
 
     const baseStr = baseName ? `(${baseName})` : '';
-    sigs.push(`class ${className}${baseStr}`);
+    sigs.push(`class ${className}${baseStr}${clsAnchor}`);
 
     // Class-level ALL_CAPS constants
     for (const c of extractClassConstants(stripped, bodyStart)) {
@@ -91,7 +117,9 @@ function extract(src, filePath) {
     const retStr = retType ? ` → ${retType}` : '';
     const hint = extractDocHint(src, m[2], m[0]);
     const hintStr = hint ? `  # ${hint}` : '';
-    sigs.push(`${asyncKw}def ${m[2]}(${params})${retStr}${hintStr}`);
+    const fnStart = lineAt(stripped, m.index);
+    const fnAnchor = `  :${fnStart}-${pyBlockEnd(srcLines, fnStart)}`;
+    sigs.push(`${asyncKw}def ${m[2]}(${params})${retStr}${fnAnchor}${hintStr}`);
   }
 
   // FastAPI router endpoints: @router.METHOD("path") + async def name(...)
@@ -103,7 +131,7 @@ function extract(src, filePath) {
     for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
       const fl = lines[j].trim();
       const fm = fl.match(/^(?:async\s+)?def\s+(\w+)/);
-      if (fm) { sigs.push(`${rm[1].toUpperCase()} ${rm[2]}  →  ${fm[1]}()`); break; }
+      if (fm) { const rs = j + 1; sigs.push(`${rm[1].toUpperCase()} ${rm[2]}  →  ${fm[1]}()  :${rs}-${pyBlockEnd(srcLines, rs)}`); break; }
       if (fl && !fl.startsWith('@') && !fl.startsWith('#')) break;
     }
   }

package/src/extractors/python_ast.py

@@ -213,6 +213,12 @@ def extract_class_constants(class_node):
                 yield f"{name}={val}"
 
 
+def _anchor(node):
+    """Return a `  :start-end` line anchor for a top-level node (1-based)."""
+    end = getattr(node, "end_lineno", None) or node.lineno
+    return f"  :{node.lineno}-{end}"
+
+
 def extract_method_sig(func_node):
     """Format a method signature string (already indented by caller)."""
     is_async = isinstance(func_node, ast.AsyncFunctionDef)
@@ -232,7 +238,7 @@ def extract_function_sig(func_node, src_lines=None):
     ret_str = f" → {ret}" if ret else ""
     hint = get_docstring_hint(func_node)
     hint_str = f"  # {hint}" if hint else ""
-    return f"{prefix}def {func_node.name}({params}){ret_str}{hint_str}"
+    return f"{prefix}def {func_node.name}({params}){ret_str}{_anchor(func_node)}{hint_str}"
 
 
 def extract_fastapi_routes(tree, src_lines):
@@ -255,7 +261,7 @@ def extract_fastapi_routes(tree, src_lines):
                 path_node = dec.args[0]
                 if isinstance(path_node, ast.Constant):
                     path = path_node.value
-                    routes.append(f"{method.upper()} {path}  →  {node.name}()")
+                    routes.append(f"{method.upper()} {path}  →  {node.name}(){_anchor(node)}")
     return routes
 
 
@@ -276,10 +282,11 @@ def extract(filepath):
         if isinstance(node, ast.ClassDef):
             bases_str = ", ".join(annotation_to_str(b) for b in node.bases if b)
             dec_names = get_decorator_names(node)
+            cls_anchor = _anchor(node)
 
             if is_dataclass(node):
                 fields = extract_dataclass_fields(node)
-                sigs.append(f"@dataclass {node.name}({fields})")
+                sigs.append(f"@dataclass {node.name}({fields}){cls_anchor}")
             elif is_basemodel(node.bases):
                 bm_fields = extract_basemodel_fields(node)
                 base_label = next(
@@ -288,12 +295,12 @@ def extract(filepath):
                     "BaseModel"
                 )
                 if bm_fields:
-                    sigs.append(f"class {node.name}({base_label}) {bm_fields}")
+                    sigs.append(f"class {node.name}({base_label}) {bm_fields}{cls_anchor}")
                 else:
-                    sigs.append(f"class {node.name}({base_label})")
+                    sigs.append(f"class {node.name}({base_label}){cls_anchor}")
             else:
                 base_part = f"({bases_str})" if bases_str else ""
-                sigs.append(f"class {node.name}{base_part}")
+                sigs.append(f"class {node.name}{base_part}{cls_anchor}")
 
             # Class constants
             for const in extract_class_constants(node):

package/src/extractors/typescript.js

@@ -1,37 +1,54 @@
 'use strict';
 
+const { lineAt, withAnchor } = require('./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}`); anchors.push(null); }
   }
 
   // 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)
@@ -39,11 +56,12 @@ function extract(src) {
   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}`); anchors.push(null); }
   }
 
   // Exported top-level functions (not methods)
@@ -53,11 +71,12 @@ function extract(src) {
     const retMatch = m[0].match(/\)\s*:\s*([^{]+)\s*\{/);
     const retType = retMatch ? retMatch[1].trim().replace(/\s+/g, ' ').slice(0, 30) : '';
     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 bodyStart = m.index + m[0].length;
       const body = stripped.slice(bodyStart, bodyStart + 800);
       const ret = body.match(/return\s*\{([^}]{1,260})\}/);
       if (ret) {
@@ -78,10 +97,14 @@ function extract(src) {
     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')) {
-      const bodyStart = stripped.indexOf('{', m.index + m[0].length);
       if (bodyStart !== -1) {
         const body = stripped.slice(bodyStart, bodyStart + 800);
         const ret = body.match(/return\s*\{([^}]{1,260})\}/);
@@ -102,22 +125,30 @@ function extract(src) {
   // 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)) {
     const stateType = m[0].match(/create<([\w]+)>/)?.[1] || '';
+    const startLn = lineAt(stripped, m.index);
     sigs.push(`export const ${m[1]} = create<${stateType}>(...)`);
+    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: const xxxApi = { method: async () => {} }
   for (const m of stripped.matchAll(/^(?:export\s+default\s+|const\s+)(\w*[Aa]pi\w*)\s*=\s*\{/gm)) {
-    const block = extractBlock(stripped, m.index + m[0].length);
+    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(', ')} }`);
+    if (methods.length) {
+      sigs.push(`${m[1]}: { ${methods.join(', ')} }`);
+      anchors.push([lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)]);
+    }
   }
 
-  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) {

package/src/mcp/server.js

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