sigmap 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -10,6 +10,27 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [3.2.0] — Planned — Phase A: Cross-Platform Standalone Binaries
+
+### Added
+- **Standalone binaries** — macOS (arm64 + x64), Linux x64, Windows x64 built via Node.js SEA
+  - No Node.js or npm required to run SigMap
+  - Download from GitHub Releases: `sigmap-darwin-arm64`, `sigmap-darwin-x64`, `sigmap-linux-x64`, `sigmap-win32-x64.exe`
+  - SHA-256 checksums in `sigmap-checksums.txt` attached to every release
+- **`scripts/build-binary.mjs`** — reproducible local binary build for the current platform
+- **`scripts/verify-binary.mjs`** — smoke tests `--version`, `--help`, default generate, `--health`, `--report` against a fixture repo
+- **`.github/workflows/release-binaries.yml`** — GHA matrix builds all 4 targets on tag push; attaches artifacts to the GitHub Release
+- **`test/fixtures/binary-smoke/`** — minimal fixture project used by CI smoke tests
+- **`docs/binaries.md`** — install guide covering download, `chmod +x`, macOS Gatekeeper, Windows SmartScreen, and checksum verification
+
+### Technical
+- Uses [Node.js SEA](https://nodejs.org/api/single-executable-applications.html) (Node 20 `--experimental-sea-config` + `postject`)
+- `gen-context.js` was updated to include previously-missing `src/` modules (`todos`, `coverage`, `prdiff`) in the SEA bundle; existing `requireSourceOrBundled()` fallback and DEFAULTS fallback in `writeInitConfig()` remain SEA-compatible
+- Binary builds run natively per OS in GHA (no cross-compilation)
+- `release-attach` job waits for the npm-publish Release to exist before uploading binary assets
+
+---
+
 ## [3.1.0] — 2026-04-07 — Global Command Detection & VS Code Prerelease Fix
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 
 <p>
   Every coding agent session starts with full codebase context at under 4K tokens.<br>
-  No <code>npm install</code>. No setup. Runs on any machine with Node.js 18+.
+  Multiple install options. Zero runtime dependencies. Requires only Node.js 18+.
 </p>
 
 <!-- Status -->
@@ -38,7 +38,8 @@
 | | |
 |---|---|
 | [What it does](#-what-it-does) | Token reduction table, pipeline overview |
-| [Quick start](#-quick-start) | Get running in 60 seconds |
+| [Quick start](#-quick-start) | Install (binary or npm), generate in 60 seconds |
+| [Standalone binaries](docs/binaries.md) | macOS, Linux, Windows — no Node required |
 | [VS Code extension](#-vs-code-extension) | Status bar, stale alerts, commands |
 | [JetBrains plugin](#-jetbrains-plugin) | IntelliJ IDEA, WebStorm, PyCharm support |
 | [Languages supported](#-languages-supported) | 21 languages |
@@ -47,6 +48,7 @@
 | [CLI reference](#-cli-reference) | All flags |
 | [Configuration](#-configuration) | Config file + .contextignore |
 | [Observability](#-observability) | Health score, reports, CI |
+| [Programmatic API](#-programmatic-api) | Use as a Node.js library |
 | [Testing](#-testing) | Run the test suite |
 | [Project structure](#-project-structure) | File-by-file map |
 | [Principles](#-principles) | Design decisions |
@@ -88,58 +90,96 @@ AI agent session starts with full context
 
 ---
 
-## 🆕 What's new in 2.4
+## ⚡ Installation
 
-| Feature | Description |
-|---|---|
-| **Programmatic API** | `require('sigmap')` — use `extract`, `rank`, `buildSigIndex`, `scan`, `score` directly, no CLI subprocess |
-| **`packages/core/`** | New `sigmap-core` package with stable API surface for third-party integrations |
-| **`packages/cli/`** | Thin `sigmap-cli` forward-compat shim for the v3.0 adapter architecture |
-| **15 new tests** | `core-api.test.js` covers all exported functions, edge cases, and backward compat |
+Pick the method that fits your workflow — all produce the same output.
 
-## 🆕 What's new in 2.3
+<details open>
+<summary><strong>npx — try without installing</strong></summary>
 
-| Feature | Description |
-|---|---|
-| **`--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) |
+```bash
+npx sigmap
+```
 
-> **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.
+Runs the latest version without any permanent install. Great for a quick try.
 
----
+</details>
 
-## 🔭 What's next — v2.10 (in progress · [#25](https://github.com/manojmallick/sigmap/issues/25))
+<details>
+<summary><strong>npm global — install once, run anywhere</strong></summary>
 
-### v2.10 — Reporting: Charts + Advanced Metrics
+```bash
+npm install -g sigmap
+sigmap
+```
 
-| Feature | Description |
-|---|---|
-| **Charts in reports** | Visualize token reduction, signature counts, and budget usage per run |
-| **Advanced retrieval metrics** | Add precision@K, recall@K, MRR trend, and query-level diagnostics |
-| **Evaluation dashboard output** | Generate shareable HTML/JSON benchmark summaries from CLI runs |
-| **CI-friendly metrics export** | Persist machine-readable metrics for release gates and regression tracking |
-| **Release quality gates** | Add pass/fail thresholds for hit@5 and precision before publish |
+Available from any directory on your machine.
 
-## 🔌 v3.0 — Platform: Multi-Adapter Architecture
+</details>
 
-SigMap is now an **adapter platform**. Any AI assistant — Copilot, Claude, Cursor, Windsurf, OpenAI, or Gemini — plugs in through a standard interface.
+<details>
+<summary><strong>npm local — per-project, version-pinned</strong></summary>
 
 ```bash
-# Generate for a specific AI assistant
-node gen-context.js --adapter copilot    # → .github/copilot-instructions.md
-node gen-context.js --adapter openai     # → .github/openai-context.md
-node gen-context.js --adapter gemini     # → .github/gemini-context.md
-node gen-context.js --adapter claude     # → CLAUDE.md (append)
+npm install --save-dev sigmap
 ```
 
-```js
-// Programmatic API — fully semver-stable from v3.0
-const { adapt } = require('sigmap');
-const systemPrompt = adapt(context, 'openai', { version: '3.0.0' });
+Add to `package.json` scripts for team consistency:
+
+```json
+{
+  "scripts": {
+    "context": "sigmap",
+    "context:watch": "sigmap --watch"
+  }
+}
+```
+
+Run with `npm run context`. Version is pinned per project.
+
+</details>
+
+<details>
+<summary><strong>Volta — team-friendly, auto-pinned version</strong></summary>
+
+```bash
+volta install sigmap
+sigmap
+```
+
+[Volta](https://volta.sh) pins the exact version in `package.json` — every team member runs the same version automatically without configuration.
+
+</details>
+
+<details>
+<summary><strong>Single-file download — no npm, any machine</strong></summary>
+
+```bash
+curl -O https://raw.githubusercontent.com/manojmallick/sigmap/main/gen-context.js
+node gen-context.js
+```
+
+No npm, no `node_modules`. Drop `gen-context.js` into any project and run it directly. Requires only Node.js 18+. Ideal for CI, locked-down environments, or one-off use.
+
+</details>
+
+> **Note:** When using the single-file download, replace `sigmap` with `node gen-context.js` in all commands below.
+
+---
+
+## 🚀 Features
+
+### Multi-adapter output
+
+Generate context for any AI assistant from a single run:
+
+```bash
+sigmap --adapter copilot    # → .github/copilot-instructions.md
+sigmap --adapter claude     # → CLAUDE.md (appended below marker)
+sigmap --adapter cursor     # → .cursorrules
+sigmap --adapter windsurf   # → .windsurfrules
+sigmap --adapter openai     # → .github/openai-context.md
+sigmap --adapter gemini     # → .github/gemini-context.md
 ```
 
 | Adapter | Output file | AI assistant |
@@ -151,45 +191,80 @@ const systemPrompt = adapt(context, 'openai', { version: '3.0.0' });
 | `openai` | `.github/openai-context.md` | Any OpenAI model |
 | `gemini` | `.github/gemini-context.md` | Google Gemini |
 
-**Backward compat:** existing `outputs` config key silently maps to `adapters` — no migration needed.
+Configure multiple adapters at once in `gen-context.config.json`:
+
+```json
+{ "outputs": ["copilot", "claude", "cursor"] }
+```
+
+### Programmatic API
+
+Use SigMap as a Node.js library without spawning a subprocess. See the [full API reference](#-programmatic-api) below.
+
+### Query-aware retrieval
+
+Find the most relevant files for any task without reading the whole codebase:
 
-See full roadmap: [manojmallick.github.io/sigmap/roadmap.html](https://manojmallick.github.io/sigmap/roadmap.html)
+```bash
+sigmap --query "authentication middleware"   # ranked file list
+sigmap --query "auth" --json                 # machine-readable output
+sigmap --query "auth" --top 5               # top 5 results only
+```
+
+### Diagnostic and evaluation tools
+
+```bash
+sigmap --analyze                  # per-file: sigs, tokens, extractor, coverage
+sigmap --analyze --slow           # include extraction timing
+sigmap --diagnose-extractors      # self-test all 21 extractors against fixtures
+sigmap --benchmark                # hit@5 and MRR retrieval quality
+sigmap --benchmark --json         # machine-readable benchmark results
+```
 
 ---
 
 ## ⚡ Quick start
 
-Download the single-file CLI and generate context immediately:
+### Install
 
-```bash
-# 1. Download
-curl -O https://raw.githubusercontent.com/manojmallick/sigmap/main/gen-context.js
+**Standalone binary** — no Node.js or npm required:
 
-# 2. Generate your context file
-node gen-context.js
+| Platform | Download |
+|---|---|
+| macOS Apple Silicon | [`sigmap-darwin-arm64`](https://github.com/manojmallick/sigmap/releases/latest/download/sigmap-darwin-arm64) |
+| macOS Intel | [`sigmap-darwin-x64`](https://github.com/manojmallick/sigmap/releases/latest/download/sigmap-darwin-x64) |
+| Linux x64 | [`sigmap-linux-x64`](https://github.com/manojmallick/sigmap/releases/latest/download/sigmap-linux-x64) |
+| Windows x64 | [`sigmap-win32-x64.exe`](https://github.com/manojmallick/sigmap/releases/latest/download/sigmap-win32-x64.exe) |
 
-# 3. Output: .github/copilot-instructions.md
-# That file is auto-read by GitHub Copilot in VS Code
+```bash
+# macOS / Linux
+chmod +x ./sigmap-darwin-arm64
+./sigmap-darwin-arm64
 ```
 
-Or via npm (globally):
+See [docs/binaries.md](docs/binaries.md) for Gatekeeper / SmartScreen notes and checksum verification.
+
+**npm** (requires Node.js 18+):
 
 ```bash
-npx sigmap          # run once without installing
-npm install -g sigmap   # install globally
-sigmap              # then use anywhere
+npx sigmap                  # run once without installing
+npm install -g sigmap       # install globally
 ```
 
-### Common workflows
+---
+
+### Generate context
+
+Download the single-file CLI and generate context immediately:
 
 ```bash
-node gen-context.js              # generate once and exit
-node gen-context.js --watch      # regenerate on every file save
-node gen-context.js --setup      # generate + install git hook + start watcher
-node gen-context.js --diff       # context for git-changed files only (PR mode)
-node gen-context.js --diff --staged  # staged files only (pre-commit check)
-node gen-context.js --health     # show context health score (grade A–D)
-node gen-context.js --mcp        # start MCP server on stdio
+sigmap                         # generate once and exit
+sigmap --watch                 # regenerate on every file save
+sigmap --setup                 # generate + install git hook + start watcher
+sigmap --diff                  # context for git-changed files only (PR mode)
+sigmap --diff --staged         # staged files only (pre-commit check)
+sigmap --health                # show context health score (grade A–D)
+sigmap --mcp                   # start MCP server on stdio
 ```
 
 ### Companion tool: Repomix
@@ -202,8 +277,8 @@ SigMap and [Repomix](https://github.com/yamadashy/repomix) are **complementary,
 | **Repomix** | On-demand deep sessions, full file content, broader language support |
 
 ```bash
-node gen-context.js --setup    # always-on context
-npx repomix --compress         # deep dive sessions
+sigmap --setup         # always-on context
+npx repomix --compress # deep dive sessions
 ```
 
 *"SigMap for daily always-on context; Repomix for deep one-off sessions — use both."*
@@ -212,8 +287,6 @@ npx repomix --compress         # deep dive sessions
 
 ## 🧩 VS Code extension
 
-> Introduced in v1.5 — zero runtime npm dependencies.
-
 The `vscode-extension/` directory contains a first-party VS Code extension that keeps you informed without any manual commands.
 
 | Feature | Detail |
@@ -232,8 +305,6 @@ Activate on startup (`onStartupFinished`) — loads within 3 s, never blocks edi
 
 ## 🔧 JetBrains plugin
 
-> Introduced in v2.9 — brings SigMap to IntelliJ IDEA, WebStorm, PyCharm, and all JetBrains IDEs.
-
 The `jetbrains-plugin/` directory contains a Kotlin-based plugin for JetBrains IDEs with the same core features as the VS Code extension.
 
 | Feature | Detail |
@@ -287,7 +358,7 @@ Compatible with **IntelliJ IDEA 2024.1+** (Community & Ultimate), **WebStorm**,
 
 ## 🗂 Context strategies
 
-> Introduced in v1.1. Reduce always-injected tokens by 70–90%.
+> Reduce always-injected tokens by 70–90%.
 
 Set `"strategy"` in `gen-context.config.json`:
 
@@ -334,8 +405,6 @@ Recently committed files are **hot** (auto-injected). Everything else is **cold*
 
 ## 🔌 MCP server
 
-> Introduced in v0.3, expanded to 8 tools through v2.3.
-
 Start the MCP server on stdio:
 
 ```bash
@@ -353,7 +422,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) |
+| `query_context` | `{ query: string, topK?: number }` | Files ranked by relevance to the query |
 
 Reads files on every call — no stale state, no restart needed.
 
@@ -363,7 +432,7 @@ Reads files on every call — no stale state, no restart needed.
 
 ## ⚙️ CLI reference
 
-> All flags live in v1.5. See [CHANGELOG.md](CHANGELOG.md) for when each shipped.
+> See [CHANGELOG.md](CHANGELOG.md) for the full history.
 
 ```
 node gen-context.js                           Generate once and exit
@@ -548,7 +617,7 @@ node gen-context.js --format cache
 
 ---
 
-## 📦 Programmatic API (v2.4+)
+## 📦 Programmatic API
 
 Use SigMap as a library — no CLI subprocess needed:
 
@@ -683,61 +752,6 @@ sigmap/
 
 ---
 
-## 📦 Publishing to npm
-
-Releases are published automatically via GitHub Actions whenever a version tag is pushed.
-
-### One-time setup
-
-1. **Create an npm account** at [npmjs.com](https://www.npmjs.com) (if you haven't already).
-
-2. **Generate an npm access token**:
-   - npmjs.com → Account → Access Tokens → Generate New Token → **Granular Access Token** (or Classic Automation token)
-   - Scope: `sigmap` package, permission: **Read and Write**
-
-3. **Add the secret to GitHub**:
-   ```
-   GitHub repo → Settings → Secrets and variables → Actions → New repository secret
-   Name:  NPM_TOKEN
-   Value: <paste token>
-   ```
-
-### Releasing a new version
-
-```bash
-# 1. Bump version in package.json
-npm version patch   # or minor / major
-
-# 2. Push the commit AND the new tag
-git push && git push --tags
-```
-
-The [npm-publish workflow](.github/workflows/npm-publish.yml) will:
-1. Run the full test suite
-2. Verify `package.json` version matches the pushed tag
-3. Publish to npm with provenance attestation
-4. Create a GitHub Release with auto-generated notes
-
-### Backfilling historical versions
-
-Tags that existed before the workflow was set up can be published retroactively:
-
-```bash
-# Dry run first — see what would be published
-./scripts/backfill-npm.sh
-
-# Actually publish all historical tags
-export NPM_TOKEN=npm_xxxxxxxxxxxx
-./scripts/backfill-npm.sh --publish
-
-# Start from a specific tag
-./scripts/backfill-npm.sh --publish --from v0.5.0
-```
-
-The script assigns `dist-tag: legacy` to all versions except `v1.5.0` (which gets `latest`), so `npm install sigmap` always resolves to the current release.
-
----
-
 ## 🤝 Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a language extractor or new feature.

package/gen-context.js

@@ -1892,6 +1892,152 @@ __factories["./src/extractors/yaml"] = function(module, exports) {
   
 };
 
+// ── ./src/extractors/todos ──
+__factories["./src/extractors/todos"] = function(module, exports) {
+
+  'use strict';
+
+  /**
+   * Extract TODO/FIXME/HACK/XXX comments from source text.
+   * @param {string} src - Raw file content
+   * @returns {{line:number, tag:string, text:string}[]}
+   */
+  function extractTodos(src) {
+    if (!src || typeof src !== 'string') return [];
+    const todos = [];
+    const lines = src.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/(?:\/\/|#)\s*(TODO|FIXME|HACK|XXX)\s*:?\s*(.+)/i);
+      if (!m) continue;
+      todos.push({
+        line: i + 1,
+        tag: m[1].toUpperCase(),
+        text: m[2].trim().slice(0, 70),
+      });
+    }
+
+    return todos;
+  }
+
+  module.exports = { extractTodos };
+
+};
+
+// ── ./src/extractors/coverage ──
+__factories["./src/extractors/coverage"] = function(module, exports) {
+
+  '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] && m[1].length >= 3) names.add(m[1].toLowerCase());
+        }
+
+        for (const m of src.matchAll(/\b([a-zA-Z_][a-zA-Z0-9_]*)\b/g)) {
+          if (m[1] && m[1].length >= 4) names.add(m[1].toLowerCase());
+        }
+      }
+    }
+
+    return names;
+  }
+
+  function isTested(funcName, testIndex) {
+    if (!funcName || funcName.length < 3 || !testIndex || testIndex.size === 0) return false;
+    const lower = funcName.toLowerCase();
+    if (testIndex.has(lower) || testIndex.has(`test_${lower}`)) return true;
+    return false;
+  }
+
+  module.exports = { buildTestIndex, isTested };
+
+};
+
+// ── ./src/extractors/prdiff ──
+__factories["./src/extractors/prdiff"] = function(module, exports) {
+
+  '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 };
+
+};
+
 // ── ./src/format/cache ──
 __factories["./src/format/cache"] = function(module, exports) {
   
@@ -3554,7 +3700,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '2.10.0',
+    version: '3.2.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -4903,7 +5049,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '3.0.1';
+const VERSION = '3.2.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {
@@ -25,7 +25,9 @@
     "report": "node gen-context.js --report",
     "health": "node gen-context.js --health",
     "map": "node gen-project-map.js",
-    "mcp": "node gen-context.js --mcp"
+    "mcp": "node gen-context.js --mcp",
+    "build:binary": "node scripts/build-binary.mjs",
+    "verify:binary": "node scripts/verify-binary.mjs"
   },
   "files": [
     "gen-context.js",

package/src/mcp/server.js

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