v0.0 → v3.5

Measure the problem. Install Repomix, create .repomixignore, measure token consumption before any optimisation. This is the number we spend every version beating.

The first version that matters. A single file — gen-context.js — with all 21 language extractors inline. Zero npm dependencies. Runs on any machine with Node.js 18+. Writes .github/copilot-instructions.md. Installs a post-commit git hook via --setup.

Secret scanning blocks AWS keys, GitHub tokens, database connection strings, and 10 other credential patterns from ever appearing in the output. The .contextignore file (gitignore syntax) lets teams exclude generated code, test fixtures, and vendor directories. Token budget enforcement with a defined drop order.

A JSON-RPC stdio server implementing the Model Context Protocol. Three tools: read_context (pull signatures for any module on demand), search_signatures (keyword search across all signatures), get_map (structural sections). The MCP server reads files on every call — no stale state, no restart needed.

gen-project-map.js produces PROJECT_MAP.md with three structural views: an import graph showing every file dependency, a class hierarchy showing extends/implements relationships, and a route table extracting HTTP routes from Express, FastAPI, Rails, and similar frameworks.

Monorepo mode generates a separate context file per package — agents working on one service don't receive signatures from all others. The GitHub Action runs on every push and PR, fails CI if token budget is exceeded, and posts a reduction report as a PR comment.

A session compression guide (SESSION_DISCIPLINE.md) that codifies how agents should summarise conversations, checkpoint progress, and restart from a minimal state. The --track flag logs every run to .sigmap/runs.jsonl for monitoring. Reduces per-conversation token cost by 40%.

A file complexity scorer classifies every file as fast (simple CRUD, 0.33× cost), balanced (business logic, 1× cost), or powerful (architecture decisions, 3× cost). The routing table is appended to the context file. Agents use the fast-tier model for 70% of tasks — the ones that don't need powerful reasoning.

The --format cache flag wraps context in Anthropic's cache_control breakpoints. The stable codebase signatures become a cached prefix — the most expensive tokens are computed once and reused across every request in a session. The 60% API cost reduction compounds with the model routing savings from v0.7.

The --report --json flag emits a machine-readable token reduction JSON suitable for CI dashboards and custom monitoring. An ENTERPRISE_SETUP.md consolidates all enterprise configuration. 23 new integration tests bring total coverage to 177 passing tests.

The complete SigMap system. Self-healing CI auto-regenerates the context file when it drifts. The --health flag gives a composite 0–100 score for context freshness, reduction quality, and over-budget run rate. The --suggest-tool flag classifies any task description into fast / balanced / powerful model tiers. All 177 tests pass.

Three output strategies for different workflows. full (default) — one file, all signatures, always injected. per-module — one file per source directory plus a tiny always-on overview (~100–300 tokens); ~70% fewer injected tokens with zero context loss. hot-cold — recently committed files auto-injected (~200–800 tokens); everything else written to a cold file for MCP on-demand retrieval; ~90% fewer always-on tokens when using Claude Code or Cursor with MCP enabled.

Added sigmap npm binary alias alongside gen-context so npx sigmap works from any machine without cloning the repo. Improved --init to scaffold both gen-context.config.json and .contextignore in one step. Added 9 integration tests covering per-module and hot-cold strategy edge cases.

The --diff flag generates context only for files changed in the current git working tree — ideal for PR reviews and CI. --diff --staged restricts to staged files only, making it a perfect pre-commit check. Both modes auto-fall-back to full generate when outside a git repository or when no files have changed. Watch mode debounce is now configurable via watchDebounce in config.

Two new MCP tools: explain_file returns signatures, resolved imports, and reverse callers for any file in a single call — agents get full file context without guessing paths. list_modules returns a token-count table of all top-level module directories so agents know where to look before calling read_context. Strategy-aware health scorer no longer penalises hot-cold or per-module runs for low reduction — intentionally small outputs score correctly. MCP server now exposes 7 tools total.

A zero-dependency VS Code extension shows a status bar item displaying the health grade and time since last regeneration (refreshes every 60 s). It warns when context is stale (>24 h), adds Regenerate Context and Open Context File commands, and supports a configurable script path. All six HTML documentation pages gained client-side keyword search (press / to open). A proper .npmignore prepares the package for npm publish — npx sigmap resolves to the runtime-only artifact.

Major pipeline overhaul adds four new context sections: TODOs (inline TODO/FIXME/HACK extraction), Recent changes (git log summary), Coverage gaps (files lacking tests), and PR diff context (changed-file signatures). New dependency extractors for Python (import/from) and TypeScript (import/require). Three extractor bug fixes: Python BaseModel field bleed, TypeScript union type truncation, and TypeScript function-style hook detection. 262 tests passing across 21 languages and 17 integration suites.

Zero-dependency evaluation pipeline: hit@5, MRR, and precision@5 metrics against a JSONL task file. --benchmark CLI flag runs retrieval tasks and prints a scored results table. --eval alias. New src/eval/runner.js and src/eval/scorer.js modules. 12 new integration tests.

--analyze prints a per-file breakdown of signatures, tokens, extractor language, and test coverage status. --analyze --slow re-times each extractor and flags files taking over 50ms. --diagnose-extractors self-tests all 21 extractors against their fixture files and reports any mismatch. Helps teams identify extraction blind spots and performance bottlenecks.

Zero-dependency TF-IDF retrieval ranks all files by relevance to a free-text query. --query "<text>" prints a scored file table plus the top-3 signature blocks. --query --json returns machine-readable { query, results[], totalResults }. New 8th MCP tool query_context exposes the same ranking live in any MCP session. Config keys retrieval.topK (default 10) and retrieval.recencyBoost (default 1.5×). New modules: src/retrieval/tokenizer.js and src/retrieval/ranker.js. 325 tests passing across 21 languages and 20 integration suites.

Splits gen-context.js into a proper package structure. packages/core/index.js (sigmap-core) exposes a stable programmatic API: extract, rank, buildSigIndex, scan, score. Third-party tools can now require('sigmap') without spawning a CLI process. packages/cli/index.js (sigmap-cli) is a thin forward-compat shim for the v3.0 adapter architecture. Root gen-context.js entry and all CLI flags unchanged — full backward compat. New exports field in root package.json. 15 new integration tests.

Adds a reverse-dependency graph to SigMap. --impact <file> traces every file that transitively imports the given file — giving agents instant blast-radius awareness when a change is made. src/map/dep-graph.js builds the reverse index; src/map/impact.js runs BFS/DFS traversal with optional depth limit. New get_impact MCP tool (9th tool) returns impacted files with signatures. Circular deps handled safely — no infinite loops. --impact --json for CI integration.

Generate publishable evaluation results. Run against real open-source repos (express, flask, gin, spring-petclinic, rails) and output paper-ready metrics. --benchmark --repo <path> runs benchmarks on external repos. --report --paper generates markdown + LaTeX tables ready for academic papers: token reduction table, hit@5/MRR per repo, latency (p50/p95/p99), all copy-paste ready. 50 real evaluation tasks across 5 repos. Zero-dependency paper formatting in src/eval/paper.js.

Fine-tuned ranking algorithm weights for better precision. Benchmark-driven optimization of exactToken, symbolMatch, prefixMatch, pathMatch, and recencyBoost weights. TF-IDF scoring option for semantic relevance. Configurable weight presets (precision, balanced, recall) via retrieval.preset. Performance optimization for large codebases — --query completes in <100ms on 1000-file repos. Precision@5 improved by ≥5% while maintaining hit@5 ≥ 0.80.

Returns not just relevant files, but the exact code snippets within those files that match the query. Hybrid approach combining file-level and snippet-level retrieval. --query --snippets CLI flag returns top-k snippets with line numbers and smart context (2-3 lines before/after). MCP query_context tool enhanced with snippets: true option — response includes snippet text + line ranges. src/retrieval/snippets.js extracts relevant code blocks; hybrid scoring combines file score + snippet-local score. Performance <150ms for 1000-file repos.

Expands SigMap beyond VS Code to JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, GoLand, RubyMine). Native plugin with toolbar actions ("Regenerate Context", "Open Context File", "View Roadmap"), settings panel (configure srcDirs, exclude patterns, maxTokens, routing presets), and file watcher integration (auto-regenerate on changes, opt-in). jetbrains-plugin/ with Gradle build + plugin.xml manifest. Automated JetBrains Marketplace publishing via GitHub Actions. docs/JETBRAINS_SETUP.md installation guide. Plugin passes JetBrains Plugin Verifier.

Adds chart-ready reporting for token reduction and signature coverage, plus advanced benchmark metrics such as precision@K, recall@K, and MRR trends. Includes richer CLI report output and CI-friendly JSON artifacts for release quality gates.

SigMap becomes an adapter platform. Six output adapters ship: copilot, claude, cursor, windsurf, openai, and gemini. New --adapter <name> CLI flag generates output for a specific adapter. packages/core gains adapt(context, adapterName) for programmatic use. Old outputs config key silently maps to adapters — full backward compatibility. API stability guarantee: breaking changes require v4.0.

Detects whether SigMap is installed globally (npm install -g sigmap) and automatically switches the invocation from node gen-context.js to the global sigmap command. VS Code extension prerelease channel bug fixed — extensions no longer fail to activate when installed from the prerelease channel. Improved first-run experience: clearer console messages, better error recovery on missing config.

Standalone binaries built with Node.js SEA (Single Executable Application) for macOS arm64/x64, Linux x64, and Windows x64 — no Node.js runtime required. Four pipeline quality fixes: applyTokenBudget loop direction, CSS utility heuristic, coverage.js Python test patterns, and isTested token splitting. New --each [dirs] flag runs context generation independently per sub-directory. Bug fix: --monorepo no longer hardcodes the claude output adapter.

The --help output now adapts to how you invoke SigMap — running npx sigmap --help, sigmap --help, gen-context --help, or node gen-context.js --help each shows the matching command in every usage example. The CLI reference docs page gains a four-tab command picker ("How you run it:") that rewrites all terminal blocks on the page to the selected invocation style, persisted in localStorage. Includes SEO improvements across all docs pages and new Gemini adapter context generation.

Phase C ships framework-specialized extraction for React TSX, Vue SFC, and Python dataclass/model code paths. Phase D adds architectural pattern inference for dependency injection, service and repository layers, controller boundaries, type linkage, and high-risk unsafe code signals.