sigmap 1.5.1 → 2.0.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "1.5.1",
+  "version": "2.0.0-beta.1",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "bin": {
@@ -11,6 +11,7 @@
   "scripts": {
     "test": "node test/run.js",
     "test:integration": "node test/integration/strategy.test.js && node test/integration/secret-scan.test.js && node test/integration/token-budget.test.js && node test/integration/mcp-server.test.js",
+    "test:integration:all": "node test/integration/all.js",
     "test:all": "node test/run.js && node test/integration/strategy.test.js && node test/integration/secret-scan.test.js",
     "generate": "node gen-context.js",
     "watch": "node gen-context.js --watch",

package/src/config/defaults.js

@@ -12,7 +12,13 @@ const DEFAULTS = {
   outputs: ['copilot'],
 
   // Directories to scan (relative to project root)
-  srcDirs: ['src', 'app', 'lib', 'packages', 'services', 'api'],
+  srcDirs: [
+    'src', 'app', 'lib', 'packages', 'services', 'api',
+    // common monorepo / multi-project top-level names
+    'server', 'client', 'web', 'frontend', 'backend',
+    'desktop', 'mobile', 'shared', 'common', 'core',
+    'workers', 'functions', 'lambda', 'cmd',
+  ],
 
   // Directory/file names to exclude entirely
   exclude: [
@@ -39,6 +45,15 @@ const DEFAULTS = {
   // Sort recently git-committed files higher in output
   diffPriority: true,
 
+  // Context strategy controls how the output is split and injected.
+  // 'full'       -> single context file (default)
+  // 'per-module' -> one context-<module>.md per top-level srcDir + thin overview
+  // 'hot-cold'   -> recent files in primary output, older files in context-cold.md
+  strategy: 'full',
+
+  // For hot-cold strategy: how many recent git commits count as "hot"
+  hotCommits: 10,
+
   // Debounce delay (ms) between file-system events and regeneration in watch mode
   watchDebounce: 300,
 
@@ -56,6 +71,33 @@ const DEFAULTS = {
   mcp: {
     autoRegister: true,
   },
+
+  // Enrich signatures with return types, type hints, and schema field collapse
+  enrichSignatures: true,
+
+  // Include a compact import dependency map at top of output
+  depMap: true,
+
+  // Collapse Pydantic BaseModel / @dataclass fields to a single line
+  schemaFields: true,
+
+  // Include TODO/FIXME/HACK/XXX comments as compact section
+  todos: true,
+
+  // Include compact recent git changes section
+  changes: true,
+
+  // Number of commits used for changes section
+  changesCommits: 5,
+
+  // Add test coverage markers to extracted function signatures (opt-in)
+  testCoverage: false,
+
+  // Directories scanned for tests when testCoverage is enabled
+  testDirs: ['tests', 'test', '__tests__', 'spec'],
+
+  // Add reverse dependency usage hints on file headings (opt-in)
+  impactRadius: false,
 };
 
 module.exports = { DEFAULTS };

package/src/extractors/coverage.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function walkFiles(dir) {
+  let out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out = out.concat(walkFiles(full));
+    else if (entry.isFile()) out.push(full);
+  }
+  return out;
+}
+
+function buildTestIndex(cwd, testDirs) {
+  const dirs = Array.isArray(testDirs) && testDirs.length ? testDirs : ['tests', 'test', '__tests__', 'spec'];
+  const names = new Set();
+
+  for (const dir of dirs) {
+    const abs = path.join(cwd, dir);
+    if (!fs.existsSync(abs)) continue;
+    for (const file of walkFiles(abs)) {
+      let src = '';
+      try {
+        src = fs.readFileSync(file, 'utf8');
+      } catch (_) {
+        continue;
+      }
+
+      for (const m of src.matchAll(/\b(?:test_|it\(|test\(|describe\()\s*['"`]?([\w_]+)/g)) {
+        if (m[1]) names.add(m[1].toLowerCase());
+      }
+
+      for (const m of src.matchAll(/\b([a-zA-Z_][a-zA-Z0-9_]*)\b/g)) {
+        if (m[1]) names.add(m[1].toLowerCase());
+      }
+    }
+  }
+
+  return names;
+}
+
+function isTested(funcName, testIndex) {
+  if (!funcName || !testIndex || testIndex.size === 0) return false;
+  const lower = funcName.toLowerCase();
+  if (testIndex.has(lower) || testIndex.has(`test_${lower}`)) return true;
+  for (const token of testIndex) {
+    if (token.includes(lower)) return true;
+  }
+  return false;
+}
+
+module.exports = { buildTestIndex, isTested };

package/src/extractors/cpp.js

@@ -23,9 +23,11 @@ function extract(src) {
   }
 
   // Top-level function declarations/definitions (not inside a class)
-  for (const m of stripped.matchAll(/^(?!class|struct|if|for|while|switch)[\w:*&<> ]+\s+(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?\{/gm)) {
-    if (m[1].startsWith('_')) continue;
-    sigs.push(`${m[1]}(${normalizeParams(m[2])})`);
+  for (const m of stripped.matchAll(/^(?!class|struct|if|for|while|switch)([\w:*&<> ]+?)\s+(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?\{/gm)) {
+    if (m[2].startsWith('_')) continue;
+    const ret = normalizeType(m[1]);
+    const retStr = ret ? ` → ${ret}` : '';
+    sigs.push(`${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
 
   return sigs.slice(0, 25);
@@ -44,10 +46,12 @@ function extractBlock(src, startIndex) {
 
 function extractMembers(block) {
   const members = [];
-  const methodRe = /^\s+(?:virtual\s+|static\s+|inline\s+)?(?!private:|protected:|public:)[\w:*&<> ]+\s+(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?(?:override\s*)?(?:=\s*0\s*)?;/gm;
+  const methodRe = /^\s+(?:virtual\s+|static\s+|inline\s+)?(?!private:|protected:|public:)([\w:*&<> ]+?)\s+(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?(?:override\s*)?(?:=\s*0\s*)?;/gm;
   for (const m of block.matchAll(methodRe)) {
-    if (m[1].startsWith('_')) continue;
-    members.push(`${m[1]}(${normalizeParams(m[2])})`);
+    if (m[2].startsWith('_')) continue;
+    const ret = normalizeType(m[1]);
+    const retStr = ret ? ` → ${ret}` : '';
+    members.push(`${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
   return members.slice(0, 8);
 }
@@ -57,4 +61,9 @@ function normalizeParams(params) {
   return params.trim().replace(/\s+/g, ' ');
 }
 
+function normalizeType(type) {
+  if (!type) return '';
+  return type.trim().replace(/\s+/g, ' ').slice(0, 30);
+}
+
 module.exports = { extract };

package/src/extractors/csharp.js

@@ -37,12 +37,23 @@ function extractBlock(src, startIndex) {
 
 function extractMembers(block) {
   const members = [];
-  const methodRe = /^\s+(?:public|internal|protected)\s+(?:static\s+|virtual\s+|override\s+|async\s+)*(?:[\w<>\[\]?]+\s+)+(\w+)\s*\(([^)]*)\)/gm;
+  const methodRe = /^\s+(?:public|internal|protected)\s+(?:static\s+|virtual\s+|override\s+|async\s+)*(?:where\s+\w+\s*:\s*[^\n]+\s+)?([\w<>\[\]?., ]+)\s+(\w+)\s*\(([^)]*)\)/gm;
   for (const m of block.matchAll(methodRe)) {
-    const sig = m[0].trim().split('{')[0].trim();
-    members.push(sig);
+    const ret = normalizeType(m[1]);
+    const retStr = ret ? ` → ${ret}` : '';
+    members.push(`${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
   return members.slice(0, 8);
 }
 
+function normalizeParams(params) {
+  if (!params) return '';
+  return params.trim().replace(/\s+/g, ' ');
+}
+
+function normalizeType(type) {
+  if (!type) return '';
+  return type.trim().replace(/\s+/g, ' ').slice(0, 30);
+}
+
 module.exports = { extract };

package/src/extractors/dart.js

@@ -21,10 +21,11 @@ function extract(src) {
     for (const meth of extractMembers(block)) sigs.push(`  ${meth}`);
   }
 
-  // Top-level functions
-  for (const m of stripped.matchAll(/^(?:Future|void|[\w<>?]+)\s+(\w+)\s*\(([^)]*)\)/gm)) {
-    if (m[1].startsWith('_')) continue;
-    sigs.push(`${m[1]}(${normalizeParams(m[2])})`);
+  // Top-level functions — capture return type (prefix before name) and show as suffix
+  for (const m of stripped.matchAll(/^((?:Future<[\w<>?,\s]*>|[\w<>?]+))\s+(\w+)\s*\(([^)]*)\)/gm)) {
+    if (m[2].startsWith('_')) continue;
+    const retStr = (m[1] && m[1] !== 'void') ? ` \u2192 ${m[1].replace(/\s+/g, '').slice(0, 25)}` : '';
+    sigs.push(`${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
 
   return sigs.slice(0, 25);
@@ -43,9 +44,10 @@ function extractBlock(src, startIndex) {
 
 function extractMembers(block) {
   const members = [];
-  for (const m of block.matchAll(/^\s+(?:@override\s+)?(?:Future|void|[\w<>?]+)\s+(\w+)\s*\(([^)]*)\)/gm)) {
-    if (m[1].startsWith('_')) continue;
-    members.push(`${m[1]}(${normalizeParams(m[2])})`);
+  for (const m of block.matchAll(/^\s+(?:@override\s+)?(?:@\w+\s+)*((?:Future<[\w<>?,\s]*>|[\w<>?]+))\s+(\w+)\s*\(([^)]*)\)/gm)) {
+    if (m[2].startsWith('_')) continue;
+    const retStr = (m[1] && m[1] !== 'void') ? ` \u2192 ${m[1].replace(/\s+/g, '').slice(0, 25)}` : '';
+    members.push(`${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
   return members.slice(0, 8);
 }

package/src/extractors/deps.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Extract import dependencies from Python and TypeScript/JavaScript files.
+ * Returns compact dependency arrays for the dep-map section of the context output.
+ */
+
+const PYTHON_STDLIB = new Set([
+  'os', 'sys', 're', 'json', 'time', 'threading', 'logging', 'typing',
+  'dataclasses', 'datetime', 'uuid', 'pathlib', 'collections', 'functools',
+  'itertools', 'math', 'random', 'string', 'struct', 'io', 'copy', 'pprint',
+  'traceback', 'inspect', 'abc', 'enum', 'contextlib', 'weakref', 'gc',
+  'socket', 'ssl', 'http', 'urllib', 'email', 'html', 'xml', 'csv', 'sqlite3',
+  'argparse', 'subprocess', 'shutil', 'tempfile', 'glob', 'fnmatch', 'stat',
+  'hashlib', 'hmac', 'base64', 'binascii', 'codecs', 'unicodedata', 'locale',
+  'decimal', 'fractions', 'numbers', 'cmath', 'heapq', 'bisect', 'array',
+  'queue', 'asyncio', 'concurrent', 'multiprocessing', 'signal', 'mmap',
+  'builtins', 'warnings', 'operator', 'textwrap', 'difflib', 'readline',
+]);
+
+/**
+ * Extract project-level import dependencies from Python source.
+ * @param {string} src
+ * @returns {string[]}
+ */
+function extractPythonDeps(src) {
+  const deps = new Set();
+  for (const m of src.matchAll(/^from\s+([\w.]+)\s+import/gm)) {
+    const mod = m[1];
+    const root = mod.replace(/^\.+/, '').split('.')[0];
+    // Include relative imports and non-stdlib modules
+    if (mod.startsWith('.') || (root && !PYTHON_STDLIB.has(root))) {
+      deps.add(root || mod);
+    }
+  }
+  for (const m of src.matchAll(/^import\s+([\w.]+)/gm)) {
+    const root = m[1].split('.')[0];
+    if (root && !PYTHON_STDLIB.has(root)) deps.add(root);
+  }
+  return [...deps].filter(Boolean).slice(0, 5);
+}
+
+/**
+ * Extract relative import dependencies from TypeScript/JavaScript source.
+ * @param {string} src
+ * @returns {string[]}
+ */
+function extractTSDeps(src) {
+  // Strip single-line comments to avoid matching commented-out imports
+  const stripped = src.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+  const deps = new Set();
+  for (const m of stripped.matchAll(/from\s+['"](\.[\/\w.-]+)['"]/g)) {
+    // Normalise: '../store/authStore' → store/authStore, './utils' → utils
+    const clean = m[1]
+      .replace(/^\.\.\//, '')
+      .replace(/^\.\//,  '')
+      .replace(/\.\w+$/, '');
+    if (clean) deps.add(clean);
+  }
+  return [...deps].slice(0, 5);
+}
+
+/**
+ * Build reverse dependency map from forward map.
+ * @param {Map<string, string[]>} forwardMap
+ * @returns {Map<string, string[]>}
+ */
+function buildReverseDepMap(forwardMap) {
+  const reverse = new Map();
+  if (!forwardMap || typeof forwardMap.entries !== 'function') return reverse;
+  for (const [file, deps] of forwardMap.entries()) {
+    if (!Array.isArray(deps)) continue;
+    for (const dep of deps) {
+      if (!reverse.has(dep)) reverse.set(dep, []);
+      reverse.get(dep).push(file);
+    }
+  }
+  return reverse;
+}
+
+module.exports = { extractPythonDeps, extractTSDeps, buildReverseDepMap };

package/src/extractors/go.js

@@ -25,10 +25,12 @@ function extract(src) {
     for (const method of extractInterfaceMethods(block)) sigs.push(`  ${method}`);
   }
 
-  // Functions and methods
-  for (const m of stripped.matchAll(/^func\s+(?:\((\w+)\s+[\w*]+\)\s+)?(\w+)\s*\(([^)]*)\)(?:\s*[\w*()\[\],\s]+)?\s*\{/gm)) {
+  // Functions and methods — capture return type between ) and {
+  for (const m of stripped.matchAll(/^func\s+(?:\((\w+)\s+[\w*]+\)\s+)?(\w+)\s*\(([^)]*)\)([^{]*)\{/gm)) {
     const receiver = m[1] ? `(${m[1]}) ` : '';
-    sigs.push(`func ${receiver}${m[2]}(${normalizeParams(m[3])})`);
+    const retType = m[4] ? m[4].trim().replace(/\s+/g, ' ') : '';
+    const retStr = retType ? ` \u2192 ${retType.slice(0, 30)}` : '';
+    sigs.push(`func ${receiver}${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
 
   return sigs.slice(0, 25);
@@ -47,8 +49,10 @@ function extractBlock(src, startIndex) {
 
 function extractInterfaceMethods(block) {
   const methods = [];
-  for (const m of block.matchAll(/^\s+(\w+)\s*\(([^)]*)\)/gm)) {
-    methods.push(`${m[1]}(${normalizeParams(m[2])})`);
+  for (const m of block.matchAll(/^\s+(\w+)\s*\(([^)]*)\)([^\n]*)/gm)) {
+    const retType = m[3] ? m[3].trim().replace(/\s+/g, ' ') : '';
+    const retStr = retType ? ` \u2192 ${retType.slice(0, 30)}` : '';
+    methods.push(`${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
   return methods.slice(0, 8);
 }

package/src/extractors/java.js

@@ -38,12 +38,23 @@ function extractBlock(src, startIndex) {
 
 function extractMembers(block) {
   const members = [];
-  const methodRe = /^\s+(?:public|protected)\s+(?:static\s+)?(?:final\s+)?(?:[\w<>\[\]]+\s+)+(\w+)\s*\(([^)]*)\)/gm;
+  const methodRe = /^\s+(?:public|protected)\s+(?:static\s+)?(?:final\s+)?(?:synchronized\s+)?(?:<[^>]+>\s+)?([\w<>\[\], ?.]+)\s+(\w+)\s*\(([^)]*)\)/gm;
   for (const m of block.matchAll(methodRe)) {
-    const sig = m[0].trim().split('{')[0].trim();
-    members.push(sig);
+    const ret = normalizeType(m[1]);
+    const retStr = ret ? ` → ${ret}` : '';
+    members.push(`${m[2]}(${normalizeParams(m[3])})${retStr}`);
   }
   return members.slice(0, 8);
 }
 
+function normalizeParams(params) {
+  if (!params) return '';
+  return params.trim().replace(/\s+/g, ' ');
+}
+
+function normalizeType(type) {
+  if (!type) return '';
+  return type.trim().replace(/\s+/g, ' ').slice(0, 30);
+}
+
 module.exports = { extract };

package/src/extractors/javascript.js

@@ -8,6 +8,7 @@
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  const returnHints = buildReturnHints(src);
 
   const stripped = src
     .replace(/\/\/.*$/gm, '')
@@ -19,19 +20,21 @@ function extract(src) {
     const prefix = m[1] ? m[1].trim() + ' ' : '';
     sigs.push(`${prefix}class ${m[2]}`);
     const block = extractBlock(stripped, m.index + m[0].length);
-    for (const meth of extractClassMembers(block)) sigs.push(`  ${meth}`);
+    for (const meth of extractClassMembers(block, returnHints)) sigs.push(`  ${meth}`);
   }
 
   // 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 ' : '';
-    sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})`);
+    const retStr = formatReturnHint(returnHints.get(m[1]));
+    sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
 
   // 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 ' : '';
-    sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>`);
+    const retStr = formatReturnHint(returnHints.get(m[1]));
+    sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>${retStr}`);
   }
 
   // module.exports = { ... }
@@ -44,7 +47,8 @@ function extract(src) {
   // 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 ' : '';
-    sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})`);
+    const retStr = formatReturnHint(returnHints.get(m[1]));
+    sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
 
   return sigs.slice(0, 25);
@@ -62,18 +66,42 @@ function extractBlock(src, startIndex) {
   return src.slice(startIndex, i - 1);
 }
 
-function extractClassMembers(block) {
+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 isAsync = m[0].includes('async ') ? 'async ' : '';
     const isStatic = m[0].includes('static ') ? 'static ' : '';
-    members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})`);
+    const retStr = formatReturnHint(returnHints.get(m[1]));
+    members.push(`${isStatic}${isAsync}${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
   return members.slice(0, 8);
 }
 
+function buildReturnHints(src) {
+  const hints = new Map();
+  for (const m of src.matchAll(/\/\*\*[\s\S]*?@returns?\s+\{([^}]+)\}[\s\S]*?\*\/\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g)) {
+    hints.set(m[2], normalizeType(m[1]));
+  }
+  for (const m of src.matchAll(/\/\*\*[\s\S]*?@returns?\s+\{([^}]+)\}[\s\S]*?\*\/\s*export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g)) {
+    hints.set(m[2], normalizeType(m[1]));
+  }
+  for (const m of src.matchAll(/\/\*\*[\s\S]*?@returns?\s+\{([^}]+)\}[\s\S]*?\*\/\s*(?:static\s+|async\s+|get\s+|set\s+)*(\w+)\s*\(/g)) {
+    hints.set(m[2], normalizeType(m[1]));
+  }
+  return hints;
+}
+
+function normalizeType(type) {
+  if (!type) return '';
+  return type.trim().replace(/\s+/g, ' ').slice(0, 25);
+}
+
+function formatReturnHint(type) {
+  return type ? ` → ${type}` : '';
+}
+
 function normalizeParams(params) {
   if (!params) return '';
   return params.trim().replace(/\s+/g, ' ');

package/src/extractors/kotlin.js

@@ -20,10 +20,12 @@ function extract(src) {
     for (const meth of extractMembers(block)) sigs.push(`  ${meth}`);
   }
 
-  // Top-level functions
-  for (const m of stripped.matchAll(/^(?:public\s+|internal\s+)?(?:suspend\s+)?fun\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)/gm)) {
+  // Top-level functions — capture `: RetType` after params
+  for (const m of stripped.matchAll(/^(?:public\s+|internal\s+)?(?:suspend\s+)?fun\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)(?:\s*:\s*([^\n{=]+))?/gm)) {
     const suspend = m[0].includes('suspend') ? 'suspend ' : '';
-    sigs.push(`${suspend}fun ${m[1]}(${normalizeParams(m[2])})`);
+    const retType = m[3] ? m[3].trim().replace(/\s+/g, ' ') : '';
+    const retStr = retType ? ` \u2192 ${retType.slice(0, 25)}` : '';
+    sigs.push(`${suspend}fun ${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
 
   return sigs.slice(0, 25);
@@ -42,10 +44,12 @@ function extractBlock(src, startIndex) {
 
 function extractMembers(block) {
   const members = [];
-  for (const m of block.matchAll(/^\s+(?:public\s+|internal\s+|override\s+)?(?:suspend\s+)?fun\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)/gm)) {
+  for (const m of block.matchAll(/^\s+(?:public\s+|internal\s+|override\s+)?(?:suspend\s+)?fun\s+(\w+)\s*(?:<[^(]*>)?\s*\(([^)]*)\)(?:\s*:\s*([^\n{=]+))?/gm)) {
     if (m[1].startsWith('_')) continue;
     const suspend = m[0].includes('suspend') ? 'suspend ' : '';
-    members.push(`${suspend}fun ${m[1]}(${normalizeParams(m[2])})`);
+    const retType = m[3] ? m[3].trim().replace(/\s+/g, ' ') : '';
+    const retStr = retType ? ` \u2192 ${retType.slice(0, 25)}` : '';
+    members.push(`${suspend}fun ${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
   return members.slice(0, 8);
 }

package/src/extractors/php.js

@@ -25,8 +25,10 @@ function extract(src) {
   }
 
   // Top-level functions
-  for (const m of stripped.matchAll(/^function\s+(\w+)\s*\(([^)]*)\)/gm)) {
-    sigs.push(`function ${m[1]}(${normalizeParams(m[2])})`);
+  for (const m of stripped.matchAll(/^function\s+(\w+)\s*\(([^)]*)\)\s*(?::\s*([^\n{]+))?/gm)) {
+    const ret = normalizeType(m[3]);
+    const retStr = ret ? ` → ${ret}` : '';
+    sigs.push(`function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
 
   return sigs.slice(0, 25);
@@ -45,11 +47,13 @@ function extractBlock(src, startIndex) {
 
 function extractMembers(block) {
   const members = [];
-  const methodRe = /^\s+(?:public|protected)\s+(?:static\s+)?function\s+(\w+)\s*\(([^)]*)\)/gm;
+  const methodRe = /^\s+(?:public|protected)\s+(?:static\s+)?function\s+(\w+)\s*\(([^)]*)\)\s*(?::\s*([^\n{]+))?/gm;
   for (const m of block.matchAll(methodRe)) {
     if (m[1].startsWith('_')) continue;
     const isStatic = m[0].includes('static ') ? 'static ' : '';
-    members.push(`${isStatic}function ${m[1]}(${normalizeParams(m[2])})`);
+    const ret = normalizeType(m[3]);
+    const retStr = ret ? ` → ${ret}` : '';
+    members.push(`${isStatic}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
   }
   return members.slice(0, 8);
 }
@@ -59,4 +63,9 @@ function normalizeParams(params) {
   return params.trim().replace(/\s+/g, ' ');
 }
 
+function normalizeType(type) {
+  if (!type) return '';
+  return type.trim().replace(/[;\s]+$/g, '').replace(/\s+/g, ' ').slice(0, 25);
+}
+
 module.exports = { extract };

package/src/extractors/prdiff.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Compare signature arrays and produce compact diff markers.
+ * @param {string[]} baseSigs
+ * @param {string[]} currentSigs
+ * @returns {{added:string[], removed:string[], modified:string[]}}
+ */
+function diffSignatures(baseSigs, currentSigs) {
+  const base = new Set(baseSigs || []);
+  const curr = new Set(currentSigs || []);
+
+  const added = [...curr].filter((s) => !base.has(s));
+  const removed = [...base].filter((s) => !curr.has(s));
+
+  const byName = (arr) => {
+    const m = new Map();
+    for (const s of arr) {
+      const n = extractName(s);
+      if (!n) continue;
+      if (!m.has(n)) m.set(n, []);
+      m.get(n).push(s);
+    }
+    return m;
+  };
+
+  const aBy = byName(added);
+  const rBy = byName(removed);
+  const modified = [];
+
+  for (const [name] of aBy) {
+    if (rBy.has(name)) modified.push(name);
+  }
+
+  return { added, removed, modified };
+}
+
+function extractName(sig) {
+  if (!sig) return '';
+  const t = sig.trim();
+  const m = t.match(/(?:def|function|func|class|interface|trait|struct|enum|record)?\s*([A-Za-z_][A-Za-z0-9_]*)\s*(?:\(|$)/);
+  return m ? m[1] : '';
+}
+
+module.exports = { diffSignatures, extractName };