sigmap 2.2.0 → 2.4.0

package/packages/core/README.md

@@ -0,0 +1,133 @@
+# sigmap-core
+
+Programmatic API for [SigMap](https://manojmallick.github.io/sigmap/) — zero-dependency code signature extraction, ranked retrieval, secret scanning, and project health scoring.
+
+## Installation
+
+```bash
+npm install sigmap        # installs the full package (CLI + core)
+```
+
+`require('sigmap')` resolves to this library via the root `exports` field.
+
+## Quick start
+
+```js
+const { extract, rank, buildSigIndex, scan, score } = require('sigmap');
+
+// 1. Extract signatures from any source file
+const sigs = extract('function hello() { return "world"; }', 'javascript');
+// → ['function hello()']
+
+// 2. Scan for secrets before storing signatures
+const { safe, redacted } = scan(sigs, 'src/utils.js');
+
+// 3. Build an index from the generated context file
+const index = buildSigIndex('/path/to/your/project');
+
+// 4. Rank files against a query
+const results = rank('add a new language extractor', index, { topK: 5 });
+// → [{ file: 'src/extractors/python.js', score: 3.5, sigs: [...], tokens: 42 }, ...]
+
+// 5. Check project health
+const health = score('/path/to/your/project');
+// → { score: 92, grade: 'A', strategy: 'full', ... }
+```
+
+## API reference
+
+### `extract(src, language)` → `string[]`
+
+Extract code signatures from source text.
+
+| Param | Type | Description |
+|---|---|---|
+| `src` | `string` | Raw file content |
+| `language` | `string` | Language name (`'typescript'`, `'python'`, etc.) **or** a file path/name with a recognised extension |
+
+Returns an array of signature strings. Never throws — returns `[]` on any error.
+
+**Supported languages:** typescript, javascript, python, java, kotlin, go, rust, csharp, cpp, ruby, php, swift, dart, scala, vue, svelte, html, css, yaml, shell, dockerfile (21 total)
+
+```js
+// By language name
+extract(src, 'python');
+
+// By file path (extension is used to detect language)
+extract(src, 'src/server.ts');
+extract(src, 'Dockerfile');
+```
+
+---
+
+### `rank(query, sigIndex, opts?)` → `Result[]`
+
+Rank all files in a signature index against a natural-language query.
+
+| Param | Type | Description |
+|---|---|---|
+| `query` | `string` | Natural language or keyword query |
+| `sigIndex` | `Map<string, string[]>` | File → signatures map (from `buildSigIndex`) |
+| `opts.topK` | `number` | Max files to return (default: `10`) |
+| `opts.weights` | `object` | Override default scoring weights |
+| `opts.recencySet` | `Set<string>` | Files to boost with `recencyBoost` multiplier |
+
+Each result: `{ file: string, score: number, sigs: string[], tokens: number }`
+
+---
+
+### `buildSigIndex(cwd)` → `Map<string, string[]>`
+
+Build a file→signatures map from the generated `.github/copilot-instructions.md`.
+Requires `node gen-context.js` to have been run first.
+
+```js
+const index = buildSigIndex('/path/to/project');
+// → Map { 'src/extractors/python.js' => ['class Extractor', '  def extract(src)'], ... }
+```
+
+---
+
+### `scan(sigs, filePath)` → `{ safe: string[], redacted: boolean }`
+
+Scan signature strings for secrets (AWS keys, GitHub tokens, DB connection strings, etc.) and redact any matches.
+
+```js
+const { safe, redacted } = scan(
+  ['const SECRET = "ghp_abc123xyz..."'],
+  'src/config.ts'
+);
+// safe → ['[REDACTED — GitHub Token detected in src/config.ts]']
+// redacted → true
+```
+
+**Detected patterns:** AWS Access Key, AWS Secret Key, GCP API Key, GitHub Token, JWT Token, DB Connection String, SSH Private Key, Stripe Key, Twilio Key, Generic Secret
+
+---
+
+### `score(cwd)` → `HealthResult`
+
+Compute a composite health score for the SigMap installation in a project.
+
+```js
+const health = score('/path/to/project');
+// {
+//   score: 92,
+//   grade: 'A',           // A ≥90 | B ≥75 | C ≥60 | D <60
+//   strategy: 'full',
+//   tokenReductionPct: 97.2,
+//   daysSinceRegen: 0.1,
+//   totalRuns: 48,
+//   overBudgetRuns: 0,
+// }
+```
+
+## Migration from v2.3 and earlier
+
+`require('sigmap')` was not available before v2.4. The programmatic API is new — no migration needed for CLI usage.
+
+All existing CLI flags (`--generate`, `--watch`, `--mcp`, `--query`, `--analyze`, `--benchmark`, `--health`, …) are unchanged.
+
+## Zero dependencies
+
+This package has zero runtime npm dependencies. It uses only Node.js built-ins: `fs`, `path`.

package/packages/core/index.js

@@ -0,0 +1,215 @@
+'use strict';
+
+/**
+ * sigmap-core — public programmatic API
+ *
+ * Usage:
+ *   const { extract, rank, scan, score } = require('sigmap');
+ *
+ * All functions are zero-dependency and never throw.
+ */
+
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Language extractor registry
+// ---------------------------------------------------------------------------
+const EXT_MAP = {
+  '.ts': 'typescript', '.tsx': 'typescript',
+  '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+  '.py': 'python',     '.pyw': 'python',
+  '.java': 'java',
+  '.kt': 'kotlin',     '.kts': 'kotlin',
+  '.go': 'go',
+  '.rs': 'rust',
+  '.cs': 'csharp',
+  '.cpp': 'cpp', '.c': 'cpp', '.h': 'cpp', '.hpp': 'cpp', '.cc': 'cpp',
+  '.rb': 'ruby',       '.rake': 'ruby',
+  '.php': 'php',
+  '.swift': 'swift',
+  '.dart': 'dart',
+  '.scala': 'scala',   '.sc': 'scala',
+  '.vue': 'vue',
+  '.svelte': 'svelte',
+  '.html': 'html',     '.htm': 'html',
+  '.css': 'css',       '.scss': 'css', '.sass': 'css', '.less': 'css',
+  '.yml': 'yaml',      '.yaml': 'yaml',
+  '.sh': 'shell',      '.bash': 'shell', '.zsh': 'shell', '.fish': 'shell',
+};
+
+const SRC_ROOT = path.resolve(__dirname, '..', '..', 'src');
+
+function _resolveExtractor(language) {
+  const extPath = path.join(SRC_ROOT, 'extractors', language + '.js');
+  try {
+    return require(extPath);
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// extract(src, language) → string[]
+// ---------------------------------------------------------------------------
+/**
+ * Extract code signatures from source text for the given language.
+ *
+ * @param {string} src       - Raw source file content
+ * @param {string} language  - Language name (e.g. 'typescript', 'python')
+ *                             OR a file path/name with a recognised extension
+ * @returns {string[]} Array of signature strings (never throws)
+ *
+ * @example
+ *   const sigs = extract('function hello() {}', 'javascript');
+ *   // → ['function hello()']
+ *
+ *   const sigs2 = extract(src, 'src/server.ts');
+ *   // → detected as typescript via extension
+ */
+function extract(src, language) {
+  if (!src || typeof src !== 'string') return [];
+  if (!language || typeof language !== 'string') return [];
+
+  // If language looks like a file path, derive language from extension
+  let lang = language;
+  if (language.includes('.') || language.includes('/') || language.includes('\\')) {
+    const ext = path.extname(language).toLowerCase();
+    const base = path.basename(language);
+    if (base === 'Dockerfile' || base.startsWith('Dockerfile.')) {
+      lang = 'dockerfile';
+    } else {
+      lang = EXT_MAP[ext] || null;
+    }
+    if (!lang) return [];
+  } else {
+    // Normalise e.g. 'JavaScript' → 'javascript'
+    lang = language.toLowerCase();
+  }
+
+  const mod = _resolveExtractor(lang);
+  if (!mod || typeof mod.extract !== 'function') return [];
+
+  try {
+    const result = mod.extract(src);
+    return Array.isArray(result) ? result : [];
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rank(query, sigIndex, opts?) → { file, score, sigs, tokens }[]
+// ---------------------------------------------------------------------------
+/**
+ * Rank files in a signature index against a natural-language query.
+ *
+ * @param {string} query   - Natural language or keyword query
+ * @param {Map<string, string[]>} sigIndex - File → signatures map
+ * @param {object} [opts]
+ * @param {number} [opts.topK=10]        - Maximum results to return
+ * @param {number} [opts.recencyBoost]   - Score multiplier for recent files
+ * @param {Set<string>} [opts.recencySet] - Set of file paths considered recent
+ * @param {object} [opts.weights]        - Override default scoring weights
+ * @returns {{ file: string, score: number, sigs: string[], tokens: number }[]}
+ *
+ * @example
+ *   const { rank, buildSigIndex } = require('sigmap');
+ *   const index = buildSigIndex('/path/to/project');
+ *   const results = rank('add a new language extractor', index, { topK: 5 });
+ */
+function rank(query, sigIndex, opts) {
+  try {
+    const { rank: _rank } = require(path.join(SRC_ROOT, 'retrieval', 'ranker.js'));
+    return _rank(query, sigIndex, opts);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// buildSigIndex(cwd) → Map<string, string[]>
+// ---------------------------------------------------------------------------
+/**
+ * Build a file→signatures index from the generated context file.
+ * Requires gen-context.js to have been run first.
+ *
+ * @param {string} cwd - Project root directory
+ * @returns {Map<string, string[]>}
+ */
+function buildSigIndex(cwd) {
+  try {
+    const { buildSigIndex: _build } = require(path.join(SRC_ROOT, 'retrieval', 'ranker.js'));
+    return _build(cwd);
+  } catch (_) {
+    return new Map();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// scan(sigs, filePath) → { safe: string[], redacted: boolean }
+// ---------------------------------------------------------------------------
+/**
+ * Scan an array of signature strings for secrets and redact any matches.
+ *
+ * @param {string[]} sigs      - Signature strings to scan
+ * @param {string}   filePath  - Source file path (used in redaction message)
+ * @returns {{ safe: string[], redacted: boolean }}
+ *
+ * @example
+ *   const { safe, redacted } = scan(['const KEY = "AKIAEXAMPLE123..."'], 'config.js');
+ *   // redacted === true — key was replaced with [REDACTED — AWS Access Key ...]
+ */
+function scan(sigs, filePath) {
+  try {
+    const { scan: _scan } = require(path.join(SRC_ROOT, 'security', 'scanner.js'));
+    return _scan(sigs, filePath);
+  } catch (_) {
+    return { safe: Array.isArray(sigs) ? sigs : [], redacted: false };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// score(cwd) → { score, grade, ... }
+// ---------------------------------------------------------------------------
+/**
+ * Compute a composite health score for the project at cwd.
+ *
+ * @param {string} cwd - Project root directory
+ * @returns {{
+ *   score: number,
+ *   grade: 'A'|'B'|'C'|'D',
+ *   strategy: string,
+ *   tokenReductionPct: number|null,
+ *   daysSinceRegen: number|null,
+ *   totalRuns: number,
+ *   overBudgetRuns: number,
+ * }}
+ *
+ * @example
+ *   const health = score('/path/to/project');
+ *   console.log(health.grade); // 'A'
+ */
+function score(cwd) {
+  try {
+    const { score: _score } = require(path.join(SRC_ROOT, 'health', 'scorer.js'));
+    return _score(cwd);
+  } catch (_) {
+    return { score: 0, grade: 'D', strategy: 'full', tokenReductionPct: null, daysSinceRegen: null, totalRuns: 0, overBudgetRuns: 0 };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+module.exports = {
+  /** Extract signatures from source text */
+  extract,
+  /** Rank project files against a query */
+  rank,
+  /** Build a signature index from the generated context file */
+  buildSigIndex,
+  /** Scan signatures for secrets (redacts matches) */
+  scan,
+  /** Compute project health score */
+  score,
+};

package/packages/core/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "sigmap-core",
+  "version": "2.4.0",
+  "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
+  "main": "index.js",
+  "keywords": [
+    "sigmap",
+    "ai-context",
+    "code-signatures",
+    "extraction",
+    "retrieval",
+    "zero-dependency"
+  ],
+  "author": {
+    "name": "Manoj Mallick",
+    "url": "https://github.com/manojmallick"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manojmallick/sigmap.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://manojmallick.github.io/sigmap/",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config/defaults.js

@@ -92,6 +92,14 @@ const DEFAULTS = {
 
   // Add reverse dependency usage hints on file headings (opt-in)
   impactRadius: false,
+
+  // Query-aware retrieval settings (v2.3)
+  retrieval: {
+    // Maximum number of files to return for --query
+    topK: 10,
+    // Multiplier applied to recently-changed files (>1 boosts them up)
+    recencyBoost: 1.5,
+  },
 };
 
 module.exports = { DEFAULTS };

package/src/mcp/handlers.js

@@ -430,4 +430,31 @@ function listModules(args, cwd) {
   ].join('\n');
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules };
+/**
+ * query_context({ query, topK? }) → string
+ *
+ * Ranks context-file entries by relevance to the query and returns the
+ * top-K most relevant files with their signatures and scores.
+ */
+function queryContext(args, cwd) {
+  if (!args || !args.query) return 'Missing required argument: query';
+
+  const contextPath = path.join(cwd, CONTEXT_FILE);
+  if (!fs.existsSync(contextPath)) {
+    return 'No context file found. Run: node gen-context.js';
+  }
+
+  try {
+    const { rank, buildSigIndex, formatRankTable } = require('../retrieval/ranker');
+    const index = buildSigIndex(cwd);
+    if (index.size === 0) return 'No signatures indexed. Run: node gen-context.js';
+
+    const topK = Math.min(Math.max(1, parseInt(args.topK, 10) || 10), 25);
+    const results = rank(args.query, index, { topK });
+    return formatRankTable(results, args.query);
+  } catch (err) {
+    return `_query_context failed: ${err.message}_`;
+  }
+}
+
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext };

package/src/mcp/server.js

@@ -14,11 +14,11 @@
 
 const readline = require('readline');
 const { TOOLS } = require('./tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '2.2.0',
+  version: '2.4.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -73,6 +73,7 @@ function dispatch(msg, cwd) {
       else if (name === 'get_routing') text = getRouting(args, cwd);
       else if (name === 'explain_file') text = explainFile(args, cwd);
       else if (name === 'list_modules') text = listModules(args, cwd);
+      else if (name === 'query_context') text = queryContext(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -120,6 +120,30 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: 'query_context',
+    description:
+      'Rank and return the most relevant files for a specific task or question. ' +
+      'Uses keyword + symbol + path scoring to surface only the top-K files relevant ' +
+      'to the query — much cheaper than reading all context. ' +
+      'Returns ranked file list with signatures and relevance scores.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description:
+            'Natural language task description or keyword(s) to rank files against. ' +
+            'E.g. "add a new language extractor", "fix secret scanning", "auth module".',
+        },
+        topK: {
+          type: 'number',
+          description: 'Maximum number of files to return (default: 10, max: 25).',
+        },
+      },
+      required: ['query'],
+    },
+  },
 ];
 
 module.exports = { TOOLS };