sigmap 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [2.4.0] — 2026-04-05
+
+### Added
+- **`packages/core/`** — new `sigmap-core` package exposing a stable programmatic API: `{ extract, rank, buildSigIndex, scan, score }`. Third-party tools can now `require('sigmap')` and use all extraction/retrieval/security/health APIs without spawning a CLI process.
+- **`packages/cli/`** — new `sigmap-cli` thin wrapper that exposes `{ CLI_ENTRY, run }` for programmatic CLI invocation and forward-compat with the v3.0 adapter architecture.
+- **`packages/core/README.md`** — full programmatic API reference with usage examples for all five exported functions.
+- **`exports` field in `package.json`** — `require('sigmap')` resolves to `packages/core/index.js`; `require('sigmap/cli')` resolves to `packages/cli/index.js`.
+- **`test/integration/core-api.test.js`** — 15 integration tests covering: all exports present, `extract` for JS/TS/Python, file-path extension detection, unknown language returns `[]`, never throws on bad input, `rank` with empty map, `rank` sorted shape, `scan` clean/redact, `score` shape, `buildSigIndex` returns Map, CLI `--version` backward compat, CLI `--help` no crash.
+
+### Changed
+- `package.json` `"version"` bumped to `2.4.0`.
+- `package.json` `"files"` — added `"packages/"` so `sigmap-core` and `sigmap-cli` are published with the root package.
+- `gen-context.js` `VERSION` constant bumped to `2.4.0`.
+- `src/mcp/server.js` `SERVER_INFO.version` bumped to `2.4.0`.
+
+### Validation gate
+- 21/21 extractor unit tests passed
+- 21/21 integration suites passed (0 failures, including new `core-api.test.js`)
+- `node gen-context.js --version` → `2.4.0`
+- `node -e "const { extract } = require('.'); console.log(extract('function hello(){}', 'javascript').length > 0 ? 'OK' : 'FAIL')"` → `OK`
+- `require('sigmap')` works from any directory
+
+---
+
 ## [2.3.0] — 2026-04-07
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@
 
 <!-- Status -->
 [![npm version](https://img.shields.io/npm/v/sigmap?color=7c6af7&label=latest&logo=npm)](https://www.npmjs.com/package/sigmap)
-[![Tests](https://img.shields.io/badge/tests-262%20passing-22c55e)](https://github.com/manojmallick/sigmap/tree/main/test)
+[![Tests](https://img.shields.io/badge/tests-325%20passing-22c55e)](https://github.com/manojmallick/sigmap/tree/main/test)
 [![Zero deps](https://img.shields.io/badge/dependencies-zero-22c55e)](package.json)
 [![Last commit](https://img.shields.io/github/last-commit/manojmallick/sigmap?color=7c6af7)](https://github.com/manojmallick/sigmap/commits/main)
 
@@ -41,7 +41,7 @@
 | [VS Code extension](#-vs-code-extension) | Status bar, stale alerts, commands |
 | [Languages supported](#-languages-supported) | 21 languages |
 | [Context strategies](#-context-strategies) | full / per-module / hot-cold |
-| [MCP server](#-mcp-server) | 7 on-demand tools |
+| [MCP server](#-mcp-server) | 8 on-demand tools |
 | [CLI reference](#-cli-reference) | All flags |
 | [Configuration](#-configuration) | Config file + .contextignore |
 | [Observability](#-observability) | Health score, reports, CI |
@@ -86,20 +86,18 @@ AI agent session starts with full context
 
 ---
 
-## 🆕 What's new in 2.0
+## 🆕 What's new in 2.3
 
 | Feature | Description |
 |---|---|
-| **Enriched signatures** | Return types, type hints, and schema field collapse (Python `@dataclass` / `BaseModel`) |
-| **Dependency map** | Compact import dependency section at the top of output (~50–100 extra tokens) |
-| **TODO/FIXME section** | Auto-harvested TODO/FIXME/HACK/XXX comments (max 20 entries) |
-| **Recent changes section** | Git-based recent changes summary in output |
-| **Test coverage markers** | Per-function `✓`/`✗` hints by scanning test directories |
-| **Structural diff mode** | `--diff <base-ref>` writes a signature-level diff section |
-| **Impact radius hints** | Reverse dependency annotations (used by: ...) |
-| **New helper extractors** | `deps.js`, `todos.js`, `coverage.js`, `prdiff.js` |
+| **`--query "<text>"` CLI** | Rank all context files by relevance to a free-text query — scored table + top-3 signature blocks |
+| **`--query --json`** | Machine-readable ranked results (`{ query, results[], totalResults }`) |
+| **`--query --top <n>`** | Limit results (default 10, configurable via `retrieval.topK`) |
+| **`query_context` MCP tool** | 8th MCP tool — `{ query, topK? }` returns ranked file list, usable live in any MCP session |
+| **`--analyze` / `--diagnose-extractors`** | Per-file breakdown of sigs/tokens/extractor/coverage; self-tests all 21 extractors (v2.2) |
+| **`--benchmark` / `--eval`** | Measure hit@5 and MRR retrieval quality against a JSONL task file (v2.1) |
 
-Several v2 enhancements (deps map, TODOs, recent changes) are enabled by default. All v2 sections can be tuned or disabled via `gen-context.config.json`.
+> **Previous v2.0 additions:** enriched signatures, dependency map, TODO/FIXME section, test coverage markers, structural diff mode, impact radius hints. See [CHANGELOG.md](CHANGELOG.md) for the full history.
 
 ---
 
@@ -258,7 +256,7 @@ Recently committed files are **hot** (auto-injected). Everything else is **cold*
 
 ## 🔌 MCP server
 
-> Introduced in v0.3, expanded to 7 tools through v1.4.
+> Introduced in v0.3, expanded to 8 tools through v2.3.
 
 Start the MCP server on stdio:
 
@@ -277,6 +275,7 @@ node gen-context.js --mcp
 | `list_modules` | — | Token-count table of all top-level module directories |
 | `create_checkpoint` | `{ summary: string }` | Write a session checkpoint to `.context/` |
 | `get_routing` | — | Full model routing table |
+| `query_context` | `{ query: string, topK?: number }` | Files ranked by relevance to the query (v2.3) |
 
 Reads files on every call — no stale state, no restart needed.
 
@@ -296,6 +295,19 @@ node gen-context.js --diff                    Generate context for git-changed f
 node gen-context.js --diff --staged           Staged files only (pre-commit check)
 node gen-context.js --mcp                     Start MCP server on stdio
 
+node gen-context.js --query "<text>"          Rank files by relevance to a query
+node gen-context.js --query "<text>" --json   Ranked results as JSON
+node gen-context.js --query "<text>" --top <n> Limit results to top N files (default 10)
+
+node gen-context.js --analyze                 Per-file breakdown (sigs / tokens / extractor / coverage)
+node gen-context.js --analyze --json          Analysis as JSON
+node gen-context.js --analyze --slow          Include extraction timing per file
+node gen-context.js --diagnose-extractors     Self-test all 21 extractors against fixtures
+
+node gen-context.js --benchmark               Run retrieval quality benchmark (hit@5 / MRR)
+node gen-context.js --benchmark --json        Benchmark results as JSON
+node gen-context.js --eval                    Alias for --benchmark
+
 node gen-context.js --report                  Token reduction stats
 node gen-context.js --report --json           Structured JSON report (exits 1 if over budget)
 node gen-context.js --report --history        Usage log summary
@@ -435,6 +447,31 @@ node gen-context.js --format cache
 
 ---
 
+## 📦 Programmatic API (v2.4+)
+
+Use SigMap as a library — no CLI subprocess needed:
+
+```js
+const { extract, rank, buildSigIndex, scan, score } = require('sigmap');
+
+// Extract signatures from source code
+const sigs = extract('function hello() {}', 'javascript');
+
+// Build an index and rank files by query
+const index = buildSigIndex('/path/to/project');
+const results = rank('authentication middleware', index);
+
+// Scan signatures for secrets before storing
+const { safe, redacted } = scan(sigs, 'src/config.ts');
+
+// Get a composite health score for a project
+const health = score('/path/to/project');
+```
+
+📖 Full API reference: [packages/core/README.md](packages/core/README.md)
+
+---
+
 ## 🧪 Testing
 
 ```bash
@@ -464,7 +501,7 @@ grep "require(" gen-context.js | grep -v "^.*//.*require"
 
 # Gate 3 — MCP server responds correctly
 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node gen-context.js --mcp
-# Expected: valid JSON with 7 tools
+# Expected: valid JSON with 8 tools
 
 # Gate 4 — npm artifact is clean
 npm pack --dry-run
@@ -481,9 +518,16 @@ sigmap/
 ├── gen-context.js               ← PRIMARY ENTRY POINT — single file, zero deps
 ├── gen-project-map.js           ← import graph, class hierarchy, route table
 │
+├── packages/
+│   ├── core/                    ← programmatic API — require('sigmap') (v2.4)
+│   │   └── index.js             ← extract, rank, buildSigIndex, scan, score
+│   └── cli/                     ← thin CLI wrapper / v3 compat shim (v2.4)
+│
 ├── src/
 │   ├── extractors/              ← 21 language extractors (one file per language)
-│   ├── mcp/                     ← MCP stdio server — 7 tools
+│   ├── retrieval/               ← query-aware ranker + tokenizer (v2.3)
+│   ├── eval/                    ← benchmark runner + scorer (v2.1), analyzer (v2.2)
+│   ├── mcp/                     ← MCP stdio server — 8 tools
 │   ├── security/                ← secret scanner — 10 patterns
 │   ├── routing/                 ← model routing hints
 │   ├── tracking/                ← NDJSON usage logger
@@ -499,7 +543,7 @@ sigmap/
 │   ├── fixtures/                ← one source file per language
 │   ├── expected/                ← expected extractor output
 │   ├── run.js                   ← zero-dep test runner
-│   └── integration/             ← 17 integration test files (241 tests)
+│   └── integration/             ← 20 integration test files (304 tests)
 │
 ├── docs/                        ← documentation site (GitHub Pages)
 │   ├── index.html               ← homepage

package/gen-context.js

@@ -4091,7 +4091,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '2.3.0';
+const VERSION = '2.4.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "sigmap",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
+  "exports": {
+    ".": "./packages/core/index.js",
+    "./cli": "./packages/cli/index.js",
+    "./core": "./packages/core/index.js"
+  },
   "bin": {
     "sigmap": "./gen-context.js",
     "gen-context": "./gen-context.js",
@@ -26,6 +31,7 @@
     "gen-context.js",
     "gen-project-map.js",
     "src/",
+    "packages/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/packages/cli/index.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * sigmap-cli — thin CLI wrapper around sigmap-core.
+ *
+ * This module is required by the root gen-context.js entry point.
+ * All --flag handling lives here; business logic lives in src/ or packages/core.
+ *
+ * NOTE: This file intentionally does NOT duplicate business logic.
+ * It re-exports the entry-point function from gen-context.js so that
+ * `require('sigmap-cli')` can be used by tooling that wraps SigMap.
+ *
+ * In v2.4 the root gen-context.js is kept fully intact for backward compat.
+ * packages/cli is a forward-compat shim for the v3.0 adapter architecture.
+ */
+
+const path = require('path');
+
+/**
+ * The CLI entry point path.
+ * External tools can use this to spawn the CLI as a child process.
+ */
+const CLI_ENTRY = path.resolve(__dirname, '..', '..', 'gen-context.js');
+
+/**
+ * Run the SigMap CLI programmatically with the given argv array.
+ *
+ * @param {string[]} [argv]  - Arguments to pass (default: process.argv)
+ * @param {string}   [cwd]   - Working directory (default: process.cwd())
+ * @returns {void}
+ *
+ * @example
+ *   const { run } = require('sigmap-cli');
+ *   run(['--report'], '/path/to/project');
+ */
+function run(argv, cwd) {
+  const origArgv = process.argv;
+  const origCwd = process.cwd();
+
+  if (cwd) {
+    try { process.chdir(cwd); } catch (_) {}
+  }
+
+  if (argv) {
+    process.argv = [process.argv[0], CLI_ENTRY, ...argv];
+  }
+
+  try {
+    require(CLI_ENTRY);
+  } finally {
+    process.argv = origArgv;
+    if (cwd) {
+      try { process.chdir(origCwd); } catch (_) {}
+    }
+  }
+}
+
+module.exports = {
+  /** Absolute path to the gen-context.js entry point */
+  CLI_ENTRY,
+  /** Run the SigMap CLI programmatically */
+  run,
+};

package/packages/cli/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "sigmap-cli",
+  "version": "2.4.0",
+  "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
+  "main": "index.js",
+  "keywords": [
+    "sigmap",
+    "cli",
+    "ai-context",
+    "code-signatures"
+  ],
+  "author": {
+    "name": "Manoj Mallick",
+    "url": "https://github.com/manojmallick"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manojmallick/sigmap.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://manojmallick.github.io/sigmap/",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.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/mcp/server.js

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