sigmap

README

⚡ SigMap

WITHOUT SIGMAP, YOUR AI IS GUESSING.
Without structured context, AI often reads the wrong file and fills the gaps with guesses.

_{Run one command. Force every answer to come from real code.}

npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again.

What you get in ~10 seconds

• A compact signature map of your codebase
• The right file in context far more often (84.4% hit@5 vs 13.6% random)
• Fewer retries (1.59 vs 2.84 prompts per task)
• Far smaller context (~2K–4K tokens instead of ~80K)

Latest: v4.1.0 — Smart Budget. Token budget now auto-scales to your repo size, targeting 80% source-file coverage by default. No config change needed — it just works.

Trust signals

Full benchmark breakdown →

_{90 tasks · 18 real repos · no LLM API · full methodology →}

	Without SigMap	With SigMap
Task success	10%	59%
Prompts per task	2.84	1.59
Tokens per session	~80,000	~2,000
Right file found	13.6%	84.4%
Hallucination risk	92%	0%

Measured on 90 coding tasks across 18 real public repos. Full methodology and raw benchmark pages are linked below.

---

Table of contents

What it does	Token reduction table, pipeline overview
Quick start	Install (binary or npm), generate in 60 seconds
Standalone binaries	macOS, Linux, Windows — no Node required
VS Code extension	Status bar, stale alerts, commands
JetBrains plugin	IntelliJ IDEA, WebStorm, PyCharm support
Languages supported	25 languages
Context strategies	full / per-module / hot-cold
MCP server	8 on-demand tools
CLI reference	All flags
Configuration	Config file + .contextignore
Observability	Health score, reports, CI
Programmatic API	Use as a Node.js library
Testing	Run the test suite
Project structure	File-by-file map
Principles	Design decisions

📖 New to SigMap? Read the Complete Getting Started Guide — token savings walkthrough, every command, VS Code plugin, and CI setup.

---

🔍 What it does

SigMap scans your source files and extracts only the function and class signatures — no bodies, no imports, no comments — then writes a compact context file that Copilot, Claude, Cursor, and Windsurf read automatically. Every session starts with full codebase awareness at a fraction of the token cost.

Your codebase
    │
    ▼
sigmap ─────────► extracts signatures from 25 languages
    │
    ▼
.github/copilot-instructions.md   ◄── auto-read by Copilot / Claude / Cursor
    │
    ▼
AI agent session starts with full context

Dogfooding: SigMap runs on itself — 40 JS files, 8,600 lines of code. View the generated context: .github/copilot-instructions.md

Token reduction at every stage

Stage	Tokens	Reduction
Raw source files	~80,000	—
Repomix compressed	~8,000	90%
SigMap signatures	~4,000	95%
SigMap + MCP (hot-cold)	~200	99.75%

97% fewer tokens. The same codebase understanding.

Benchmark: real-world repos

Reproduced with node scripts/run-benchmark.mjs on public repos:

Repo	Language	Raw tokens	After SigMap	Reduction
express	JavaScript	70.6K	911	98.7%
flask	Python	147.9K	6.7K	95.4%
gin	Go	216.4K	6.0K	97.2%
spring-petclinic	Java	97.9K	3.4K	96.5%
rails	Ruby	1.5M	7.1K	99.5%
axios	TypeScript	105.7K	6.1K	94.3%
rust-analyzer	Rust	3.5M	6.3K	99.8%
abseil-cpp	C++	2.3M	6.3K	99.7%
serilog	C#	195.5K	6.9K	96.4%
riverpod	Dart	747.2K	6.5K	99.1%
okhttp	Kotlin	31.3K	1.4K	95.5%
laravel	PHP	1.7M	7.2K	99.6%
akka	Scala	790.5K	7.1K	99.1%
vapor	Swift	171.4K	6.4K	96.2%
vue-core	Vue	414.4K	8.6K	97.9%
svelte	Svelte	438.2K	8.0K	98.2%
fastify	JavaScript	54.4K	2.6K	95.3%
fastapi	Python	178.4K	5.2K	97.1%

Average: 97.6% reduction across 18 repos (16 languages). See benchmarks/reports/token-reduction.md or reproduce with node scripts/run-benchmark.mjs.

---

⚡ Installation

Pick the method that fits your workflow — all produce the same output.

npx — try without installing

npx sigmap

Runs the latest version without any permanent install. Great for a quick try.

npm global — install once, run anywhere

npm install -g sigmap
sigmap

Available from any directory on your machine.

Standalone binaries — no Node.js, no npm

Download from the latest release:

• https://github.com/manojmallick/sigmap/releases/latest

Available assets:

• sigmap-darwin-arm64 (macOS Apple Silicon)
• sigmap-linux-x64 (Linux x64)
• sigmap-win32-x64.exe (Windows x64)
• sigmap-checksums.txt (SHA-256 checksums)

macOS / Linux

Run directly:

chmod +x ./sigmap-darwin-arm64   # or ./sigmap-linux-x64
./sigmap-darwin-arm64 --help
./sigmap-darwin-arm64

Make it globally available in Bash/Zsh (no ./ needed):

# 1) Pick a user bin dir and move/rename the binary
mkdir -p "$HOME/.local/bin"
mv ./sigmap-darwin-arm64 "$HOME/.local/bin/sigmap"   # or sigmap-linux-x64
chmod +x "$HOME/.local/bin/sigmap"

# 2) Add to PATH in your shell profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zshrc"    # zsh
# echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"  # bash

# 3) Reload shell and verify
source "$HOME/.zshrc"   # or: source "$HOME/.bashrc"
sigmap --version

Windows (PowerShell)

Run directly:

.\sigmap-win32-x64.exe --help
.\sigmap-win32-x64.exe

Make it globally available:

# 1) Create a user bin directory and rename the binary
New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
Move-Item .\sigmap-win32-x64.exe "$HOME\bin\sigmap.exe"

# 2) Add user bin to PATH (current user)
[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";$HOME\bin",
  "User"
)

# 3) Restart PowerShell and verify
sigmap --version

Optional checksum verification:

shasum -a 256 sigmap-darwin-arm64
# Compare with sigmap-checksums.txt

Full guide: docs/readmes/binaries.md

npm local — per-project, version-pinned

npm install --save-dev sigmap

Add to package.json scripts for team consistency:

{
  "scripts": {
    "context": "sigmap",
    "context:watch": "sigmap --watch"
  }
}

Run with npm run context. Version is pinned per project.

Volta — team-friendly, auto-pinned version

volta install sigmap
sigmap

Volta pins the exact version in package.json — every team member runs the same version automatically without configuration.

Single-file download — no npm, any machine

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.

---

🚀 Features

Multi-adapter output

Generate context for any AI assistant from a single run:

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 (appended below marker)
sigmap --adapter codex      # → AGENTS.md (appended below marker)

Adapter	Output file	AI assistant
copilot	.github/copilot-instructions.md (append)	GitHub Copilot
claude	CLAUDE.md (append)	Claude / Claude Code
cursor	.cursorrules	Cursor
windsurf	.windsurfrules	Windsurf
openai	.github/openai-context.md	Any OpenAI model
gemini	.github/gemini-context.md (append)	Google Gemini
codex	AGENTS.md (append)	OpenAI Codex

Configure multiple adapters at once in gen-context.config.json:

{ "outputs": ["copilot", "claude", "cursor"] }

Programmatic API

Use SigMap as a Node.js library without spawning a subprocess. See the full API reference below.

Custom output path

Write signatures to any file location — useful for shared docs folders, monorepos, or tooling that expects context at a non-standard path:

sigmap --output .context/ai-context.md           # write to custom path
sigmap --adapter claude --output shared/sigs.md  # adapter + custom path

The path is persisted to gen-context.config.json, so --query finds it automatically on subsequent runs — no need to pass --output again:

sigmap --output .context/ai-context.md  # generates and saves the path
sigmap --query "add an extractor"        # auto-discovers .context/ai-context.md

Query-aware retrieval

Find the most relevant files for any task without reading the whole codebase:

sigmap --query "authentication middleware"   # ranked file list
sigmap --query "auth" --json                 # machine-readable output
sigmap --query "auth" --top 5               # top 5 results only
sigmap --query "auth" --adapter claude       # query against CLAUDE.md specifically

Diagnostic and evaluation tools

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

Install

Standalone binary — no Node.js or npm required:

Platform	Download
macOS Apple Silicon	sigmap-darwin-arm64
macOS Intel	sigmap-darwin-x64
Linux x64	sigmap-linux-x64
Windows x64	sigmap-win32-x64.exe

# macOS / Linux
chmod +x ./sigmap-darwin-arm64
./sigmap-darwin-arm64

See docs/readmes/binaries.md for Gatekeeper / SmartScreen notes and checksum verification.

npm (requires Node.js 18+):

npx sigmap                  # run once without installing
npm install -g sigmap       # install globally

---

Generate context

Once installed, run from your project root:

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

SigMap and Repomix are complementary, not competing:

Tool	When to use
SigMap	Always-on, git hooks, daily signature index (~4K tokens)
Repomix	On-demand deep sessions, full file content, broader language support

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."

---

🧩 VS Code extension

The official SigMap VS Code extension keeps your context fresh without any manual commands. Install it once and it runs silently in the background.

Feature	Detail
Status bar item	Shows health grade (A/B/C/D) + time since last regen; refreshes every 60 s
Stale notification	Warns when copilot-instructions.md is > 24 h old; one-click regeneration
Regenerate command	SigMap: Regenerate Context — runs sigmap in the integrated terminal
Open context command	SigMap: Open Context File — opens .github/copilot-instructions.md
Script path setting	sigmap.scriptPath — override the path to the sigmap binary or gen-context.js

Activates on startup (onStartupFinished) — loads within 3 s, never blocks editor startup.

Install: VS Code Marketplace | Open VSX Registry

---

🔧 JetBrains plugin

The official SigMap JetBrains plugin brings the same features to IntelliJ-based IDEs. Install it from the JetBrains Marketplace and it works identically to the VS Code extension.

Feature	Detail
Status bar widget	Shows health grade (A-F) + time since last regen; updates every 60 s
Regenerate action	Tools → SigMap → Regenerate Context or Ctrl+Alt+G — runs sigmap
Open context action	Tools → SigMap → Open Context File — opens .github/copilot-instructions.md
View roadmap action	Tools → SigMap → View Roadmap — opens roadmap in browser
One-click regen	Click status bar widget to regenerate context instantly

Compatible with IntelliJ IDEA 2024.1+ (Community & Ultimate), WebStorm, PyCharm, GoLand, RubyMine, PhpStorm, and all other IntelliJ-based IDEs.

Install: JetBrains Marketplace | Manual setup guide

---

🌐 Languages supported

25 languages. All implemented with zero external dependencies — pure regex + Node built-ins.

Also includes lightweight config/doc extraction for .toml, .properties, .xml, and .md to improve real-repo coverage beyond source-code files.

Show all 25 languages

Language	Extensions	Extracts
TypeScript	.ts .tsx	interfaces, classes, functions, types, enums
JavaScript	.js .jsx .mjs .cjs	classes, functions, exports
Python	.py .pyw	classes, methods, functions
Java	.java	classes, interfaces, methods
Kotlin	.kt .kts	classes, data classes, functions
Go	.go	structs, interfaces, functions
Rust	.rs	structs, impls, traits, functions
C#	.cs	classes, interfaces, methods
C/C++	.cpp .c .h .hpp .cc	classes, functions, templates
Ruby	.rb .rake	classes, modules, methods
PHP	.php	classes, interfaces, functions
Swift	.swift	classes, structs, protocols, functions
Dart	.dart	classes, mixins, functions
Scala	.scala .sc	objects, classes, traits, functions
Vue	.vue	<script> functions and components
Svelte	.svelte	<script> functions and exports
HTML	.html .htm	custom elements and script functions
CSS/SCSS	.css .scss .sass .less	custom properties and keyframes
YAML	.yml .yaml	top-level keys and pipeline jobs
Shell	.sh .bash .zsh .fish	function declarations
SQL	.sql	tables, views, indexes, functions, procedures
GraphQL	.graphql .gql	types, interfaces, enums, operations, fragments
Terraform	.tf .tfvars	resources, modules, variables, outputs
Protobuf	.proto	messages, services, rpc, enums
Dockerfile	Dockerfile Dockerfile.*	stages and key instructions

---

🗂 Context strategies

Reduce always-injected tokens by 70–90%.

Set "strategy" in gen-context.config.json:

Strategy	Always-injected	Context lost?	Needs MCP?	Best for
full	~4,000 tokens	No	No	Starting out, cross-module work
per-module	~100–300 tokens	No	No	Large codebases, module-focused sessions
hot-cold	~200–800 tokens	Cold files only	Yes	Claude Code / Cursor with MCP enabled

full — default, works everywhere

{ "strategy": "full" }

One file, all signatures, always injected on every question.

per-module — 70% fewer injected tokens, zero context loss

{ "strategy": "per-module" }

One .github/context-<module>.md per top-level source directory, plus a tiny overview table. Load the relevant module file for focused sessions. No MCP required.

.github/copilot-instructions.md   ← overview table, ~117 tokens (always-on)
.github/context-server.md         ← server/ signatures, ~2,140 tokens
.github/context-web.md            ← web/ signatures,    ~335 tokens
.github/context-desktop.md        ← desktop/ signatures, ~1,583 tokens

hot-cold — 90% fewer injected tokens, requires MCP

{ "strategy": "hot-cold", "hotCommits": 10 }

Recently committed files are hot (auto-injected). Everything else is cold (on-demand via MCP). Best reduction available — ~200 tokens always-on.

📖 Full guide: docs/readmes/CONTEXT_STRATEGIES.md — decision tree, scenario comparisons, migration steps.

---

🔌 MCP server

Start the MCP server on stdio:

sigmap --mcp

Available tools

Tool	Input	Output
read_context	{ module?: string }	Signatures for one module or entire codebase
search_signatures	{ query: string }	Matching signatures with file paths
get_map	{ type: "imports"|"classes"|"routes" }	Structural section from PROJECT_MAP.md
explain_file	{ path: string }	Signatures + imports + reverse callers for one file
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

Reads files on every call — no stale state, no restart needed.

📖 Setup guide: docs/readmes/MCP_SETUP.md

---

⚙️ CLI reference

See CHANGELOG.md for the full history.

All flags are the same regardless of how you invoke SigMap — swap the prefix to match your install:

sigmap · npx sigmap · gen-context · node gen-context.js

All flags

sigmap                                        Generate once and exit
sigmap --watch                                Generate and watch for file changes
sigmap --setup                                Generate + install git hook + start watcher
sigmap --diff                                 Generate context for git-changed files only
sigmap --diff --staged                        Staged files only (pre-commit check)
sigmap --mcp                                  Start MCP server on stdio

sigmap --output <file>                        Write signatures to a custom path (persists for --query)
sigmap --output <file> --adapter <name>       Adapter output + custom copy

sigmap --query "<text>"                       Rank files by relevance to a query
sigmap --query "<text>" --json                Ranked results as JSON
sigmap --query "<text>" --top <n>             Limit results to top N files (default 10)
sigmap --query "<text>" --adapter <name>      Query against a specific adapter's output file
sigmap --query "<text>" --output <file>       Query against a specific custom file

sigmap --analyze                              Per-file breakdown (sigs / tokens / extractor / coverage)
sigmap --analyze --json                       Analysis as JSON
sigmap --analyze --slow                       Include extraction timing per file
sigmap --diagnose-extractors                  Self-test all 21 extractors against fixtures

sigmap --benchmark                            Run retrieval quality benchmark (hit@5 / MRR)
sigmap --benchmark --json                     Benchmark results as JSON
sigmap --eval                                 Alias for --benchmark

sigmap --report                               Token reduction stats
sigmap --report --json                        Structured JSON report (exits 1 if over budget)
sigmap --report --history                     Usage log summary
sigmap --report --history --json              Usage history as JSON

sigmap --health                               Composite health score (0–100, grade A–D)
sigmap --health --json                        Machine-readable health JSON

sigmap --suggest-tool "<task>"                Recommend model tier for a task
sigmap --suggest-tool "<task>" --json         Machine-readable tier recommendation

sigmap --monorepo                             Per-package context for monorepos (packages/, apps/, services/)
sigmap --each                                 Process each sub-repo under a parent directory
sigmap --routing                              Include model routing hints in output
sigmap --format cache                         Write Anthropic prompt-cache JSON
sigmap --track                                Append run metrics to .context/usage.ndjson

sigmap --init                                 Write config + .contextignore scaffold
sigmap --version                              Version string
sigmap --help                                 Usage information

Task classification — --suggest-tool

sigmap --suggest-tool "security audit of the auth module"
# tier   : powerful
# models : claude-opus-4-6, gpt-5-4, gemini-2-5-pro

sigmap --suggest-tool "fix a typo in the yaml config" --json
# {"tier":"fast","label":"Fast (low-cost)","models":"claude-haiku-4-5, ...","costHint":"~$0.0008 / 1K tokens"}

Tiers: fast (config/markup/typos) · balanced (features/tests/debug) · powerful (architecture/security/multi-file)

---

🔒 Security scanning

SigMap automatically redacts secrets from all extracted signatures. Ten patterns are checked on every file:

Pattern	Example match
AWS Access Key	AKIA...
AWS Secret Key	40-char base64
GCP API Key	AIza...
GitHub Token	ghp_... gho_...
JWT	eyJ...
DB Connection String	postgres://user:pass@...
SSH Private Key	-----BEGIN ... PRIVATE KEY-----
Stripe Key	sk_live_... sk_test_...
Twilio Key	SK[32 hex chars]
Generic secret	password = "...", api_key: "..."

If a match is found, the signature is replaced with [REDACTED — {pattern} detected in {file}]. The run continues — no silent failures.

---

⚙️ Configuration

Copy gen-context.config.json.example to gen-context.config.json:

{
  "output": ".github/copilot-instructions.md",
  "srcDirs": ["src", "app", "lib"],
  "outputs": ["copilot"],
  "secretScan": true,
  "strategy": "full",
  "watchDebounce": 300,
  "tracking": false
}

Key fields:

• output — custom path for the primary markdown output file (used by copilot adapter). Default: .github/copilot-instructions.md
• outputs — which adapters to write to: copilot | claude | cursor | windsurf
• srcDirs — directories to scan (relative to project root)
• secretScan — redact secrets (AWS keys, tokens, etc.) from output
• strategy — output mode: full (default) | per-module | hot-cold

Token budget (v4.1.0 — auto-scaling):

Key	Default	Description
autoMaxTokens	true	Auto-scale budget to repo size. Set false to pin a fixed maxTokens.
coverageTarget	0.80	Fraction of source files to target (0.0–1.0).
modelContextLimit	128000	Model context window size. Hard cap = limit × maxTokensHeadroom.
maxTokensHeadroom	0.20	Fraction of the context window reserved for SigMap output (default: 25 600 tokens).
maxTokens	6000	Used only when autoMaxTokens: false, or as a floor.

The formula: effective = clamp(ceil(totalSigTokens × coverageTarget), 4000, floor(modelContextLimit × maxTokensHeadroom)).

Exclusions go in .contextignore (gitignore syntax). Also reads .repomixignore if present.

# .contextignore
node_modules/
dist/
build/
*.generated.*
test/fixtures/

Run sigmap --init to scaffold both files in one step.

Output targets

Key	Output file	Read by
"copilot"	.github/copilot-instructions.md (or custom path via output)	GitHub Copilot
"claude"	CLAUDE.md (appends below marker)	Claude Code
"cursor"	.cursorrules	Cursor
"windsurf"	.windsurfrules	Windsurf

The output config key sets the primary output file path. It is used by the copilot adapter when enabled. Other adapters always write to their fixed paths.

Example:

{
  "output": ".context/ai-context.md",
  "outputs": ["copilot"]
}

This writes to .context/ai-context.md instead of .github/copilot-instructions.md.

If output is omitted, the default .github/copilot-instructions.md is used.

📊 Observability

Coverage score (v4.0)

Every run now prints a coverage line alongside token reduction:

───────────────────────────────────────────
 SigMap v4.1.0
 Files scanned  : 76
 Symbols found  : 332
 Token reduction: 94%  (65,227 → 4,103)
 Coverage       : A (97%)  — 76 of 78 source files included  [budget: 4000 auto-scaled]
 Output         : .github/copilot-instructions.md
───────────────────────────────────────────

The coverage score answers how much of your codebase is represented in context after the token budget is applied. Grade scale: A ≥ 90% · B ≥ 75% · C ≥ 50% · D < 50%.

Module heatmap in --report

sigmap --report

[sigmap] report:
  version         : 4.1.0
  files processed : 76
  reduction       : 93.7%
  coverage        : A (97%)  — 76 of 78 source files included
  confidence      : HIGH

  Module Coverage:
    src                ████████████████ 100% (64/64 files)
    packages           ██████████████░░  86% (12/14 files)

Machine-readable JSON (suitable for CI dashboards):

sigmap --report --json
# { "version": "4.0.0", "finalTokens": 4103, "reductionPct": 93.7,
#   "coverage": { "score": 97, "grade": "A", "confidence": "HIGH", ... } }

Composite health score

sigmap --health

[sigmap] health:
  score    : 80/100 (grade B)
  coverage : A (97%)  — 76 of 78 source files
  strategy : full
  ...

sigmap --health --json
# { "score": 80, "grade": "B", "coverage": 97, "coverageGrade": "A",
#   "tokens": 4103, "reduction": 93.7, ... }

Confidence indicators in generated files

Every output file now carries a metadata line so you can inspect freshness at a glance:

<!-- sigmap: version=4.0.0 confidence=HIGH coverage=97% dropped=2 commit=8540612 -->

Diff risk score

sigmap --diff HEAD~3

[sigmap] Risk: Changed files (4):
  src/auth/service.ts         [HIGH]    — exports public API, 5 downstream dependents
  src/config/database.ts      [MEDIUM]  — config file
  src/utils/format.ts         [LOW]     — no dependents, internal utility

Self-healing CI

Copy examples/self-healing-github-action.yml to .github/workflows/ to auto-regenerate context when:

• Context file is more than 7 days old (always active)
• Copilot acceptance rate drops below 30% (requires COPILOT_API_TOKEN — GitHub Enterprise)

- name: SigMap health check
  run: sigmap --health --json
- name: Regenerate context
  run: sigmap

📖 Full guide: docs/readmes/ENTERPRISE_SETUP.md

Prompt caching — 60% API cost reduction

sigmap --format cache
# Writes: .github/copilot-instructions.cache.json
# Format: { type: 'text', text: '...', cache_control: { type: 'ephemeral' } }

📖 Full guide: docs/readmes/REPOMIX_CACHE.md

---

📦 Programmatic API

Use SigMap as a library — no CLI subprocess needed:

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

---

🧪 Testing

# All 21 language extractors
node test/run.js

# Single language
node test/run.js typescript

# Regenerate expected outputs after extractor changes
node test/run.js --update

# Full integration suite
node test/integration/all.js

Validation gates

# Gate 1 — all tests pass
node test/run.js
# Expected: 21/21 PASS

# Gate 2 — zero external dependencies
grep "require(" gen-context.js | grep -v "^.*//.*require"
# Expected: only fs, path, assert, os, crypto, child_process, readline

# Gate 3 — MCP server responds correctly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node gen-context.js --mcp
# Expected: valid JSON with 8 tools

# Gate 4 — npm artifact is clean
npm pack --dry-run
# Expected: no test/, docs/, vscode-extension/ in output

---

📁 Project structure

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)
│   ├── 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
│   ├── health/                  ← composite health scorer
│   ├── format/                  ← Anthropic prompt-cache formatter
│   └── config/                  ← config loader + defaults
│
├── vscode-extension/            ← VS Code extension (v1.5)
│   ├── package.json             ← manifest — commands, settings, activation
│   └── src/extension.js         ← status bar, stale notification, commands
│
├── test/
│   ├── fixtures/                ← one source file per language
│   ├── expected/                ← expected extractor output
│   ├── run.js                   ← zero-dep test runner
│   └── integration/             ← 20 integration test files (304 tests)
│
├── docs/                        ← documentation site (GitHub Pages)
│   ├── index.html               ← homepage
│   ├── quick-start.html
│   ├── strategies.html
│   ├── languages.html
│   ├── roadmap.html
│   └── repomix.html
│
├── scripts/
│   ├── ci-update.sh             ← CI pipeline helper
│   └── release.sh               ← version bump + npm publish helper
│
├── examples/
│   ├── self-healing-github-action.yml
│   ├── github-action.yml            ← ready-to-use CI workflow
│   └── claude-code-settings.json    ← MCP server config example
│
├── .npmignore                   ← excludes docs/, test/, vscode-extension/ from publish
├── .contextignore.example       ← exclusion template
└── gen-context.config.json.example ← annotated config reference

---

🏗 Principles

Principle	Implementation
Zero npm dependencies	npx sigmap on any machine — no install required. Or use the standalone binary for zero Node.js dependency.
Never throw	All extractors return [] on any error — the run always completes
Deterministic	No AI or LLM involved in extraction — only regex + Node built-ins
Repomix is a companion	Use both tools; SigMap never replaces Repomix
No telemetry	Never phones home; all state is files in your repo
Local-first	No cloud service, no database, no accounts

---

🤝 Contributing

See CONTRIBUTING.md for how to add a language extractor or new feature.

Every extractor follows the same contract:

module.exports = { extract };
function extract(src) {   // src: string → string[]
  if (!src || typeof src !== 'string') return [];
  // ... regex extraction only — no external dependencies ...
  return sigs.slice(0, 25);  // never more than 25 signatures per file
}

---

⭐ Support

If SigMap saves you context or API spend, a ⭐ on GitHub helps others find it.

---

📄 License

MIT © 2026 Manoj Mallick · Made in Amsterdam 🇳🇱

---

If SigMap saves you time — a ⭐ on GitHub helps others find it.

Docs · Changelog · Roadmap · Repomix