Merge pull request #20 from manojmallick/feat/v2.7-ranking-optimization

feat: v2.7 - Ranking Optimization

Author: manojmallick

.github/copilot-instructions.md

@@ -1,14 +1,8 @@
-<!-- Generated by SigMap gen-context.js v2.4.0 -->
+<!-- Generated by SigMap gen-context.js v2.7.0 -->
 <!-- DO NOT EDIT below the marker line — run gen-context.js to regenerate -->
 
 # Code signatures
 
-## changes (last 5 commits — 15 minutes ago)
-```
-packages/cli/index.js                         +from  +run
-packages/core/index.js                        +_resolveExtractor  +hello  +extract  +rank
-```
-
 ## packages
 
 ### packages/cli/index.js
@@ -30,38 +24,6 @@ function score(cwd) → { * score: number, * grad
 
 ## src
 
-### src/config/defaults.js
-```
-module.exports = { DEFAULTS }
-```
-
-### src/eval/analyzer.js
-```
-module.exports = { analyzeFiles, formatAnalysisTable, formatAnalysisJSON }
-function isDockerfile(name)
-function getExtractorName(filePath)
-function tokenCount(sigs)
-function hasCoverage(filePath, cwd)
-function loadExtractor(name, cwd)
-function analyzeFiles(files, cwd, opts) → object[]
-function formatAnalysisTable(stats, showSlow) → string
-function formatAnalysisJSON(stats) → object
-```
-
-### src/mcp/handlers.js
-```
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact }
-function readContext(args, cwd)
-function searchSignatures(args, cwd)
-function getMap(args, cwd)
-function createCheckpoint(args, cwd)
-function getRouting(args, cwd)
-function explainFile(args, cwd)
-function listModules(args, cwd)
-function queryContext(args, cwd)
-function getImpact(args, cwd)
-```
-
 ### src/mcp/server.js
 ```
 module.exports = { start }
@@ -71,25 +33,9 @@ function dispatch(msg, cwd)
 function start(cwd)
 ```
 
-### src/mcp/tools.js
-```
-module.exports = { TOOLS }
-```
-
-### src/retrieval/ranker.js
-```
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS }
-function scoreFile(filePath, sigs, queryTokens, weights) → number
-function rank(query, sigIndex, opts) → { file: string, score: nu
-function buildSigIndex(cwd) → Map<string, string[]>
-function formatRankTable(results, query) → string
-function formatRankJSON(results, query) → object
-```
-
-### src/retrieval/tokenizer.js
+### src/config/defaults.js
 ```
-module.exports = { tokenize, STOP_WORDS }
-function tokenize(text, opts) → string[]
+module.exports = { DEFAULTS }
 ```
 
 ### src/config/loader.js
@@ -99,6 +45,19 @@ function loadConfig(cwd) → object
 function deepClone(obj)
 ```
 
+### src/eval/analyzer.js
+```
+module.exports = { analyzeFiles, formatAnalysisTable, formatAnalysisJSON }
+function isDockerfile(name)
+function getExtractorName(filePath)
+function tokenCount(sigs)
+function hasCoverage(filePath, cwd)
+function loadExtractor(name, cwd)
+function analyzeFiles(files, cwd, opts) → object[]
+function formatAnalysisTable(stats, showSlow) → string
+function formatAnalysisJSON(stats) → object
+```
+
 ### src/eval/runner.js
 ```
 module.exports = { run, rank, loadTasks, buildSigIndex, formatTable, formatMetrics, tokenize }
@@ -396,6 +355,41 @@ function shouldSkipFile(rel)
 function analyze(files, cwd)
 ```
 
+### src/mcp/handlers.js
+```
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact }
+function readContext(args, cwd)
+function searchSignatures(args, cwd)
+function getMap(args, cwd)
+function createCheckpoint(args, cwd)
+function getRouting(args, cwd)
+function explainFile(args, cwd)
+function listModules(args, cwd)
+function queryContext(args, cwd)
+function getImpact(args, cwd)
+```
+
+### src/mcp/tools.js
+```
+module.exports = { TOOLS }
+```
+
+### src/retrieval/ranker.js
+```
+module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS }
+function scoreFile(filePath, sigs, queryTokens, weights) → number
+function rank(query, sigIndex, opts) → { file: string, score: nu
+function buildSigIndex(cwd) → Map<string, string[]>
+function formatRankTable(results, query) → string
+function formatRankJSON(results, query) → object
+```
+
+### src/retrieval/tokenizer.js
+```
+module.exports = { tokenize, STOP_WORDS }
+function tokenize(text, opts) → string[]
+```
+
 ### src/routing/classifier.js
 ```
 module.exports = { classify, classifyAll }

CHANGELOG.md

@@ -6,7 +6,43 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
-## [2.6.0] — upcoming · [#16](https://github.com/manojmallick/sigmap/issues/16) · branch: `feat/v2.6-research-mode`
+## [2.7.0] — upcoming · [#19](https://github.com/manojmallick/sigmap/issues/19) · branch: `feat/v2.7-ranking-optimization`
+
+### Planned additions
+- **Fine-tuned ranking weights** — optimize `exactToken`, `symbolMatch`, `prefixMatch`, `pathMatch`, and `recencyBoost` weights in `src/retrieval/ranker.js` based on benchmark-driven evaluation
+- **TF-IDF scoring option** — add TF-IDF (term frequency-inverse document frequency) as an alternative scoring method for better semantic relevance in large codebases
+- **Configurable weight presets** — `precision`, `balanced`, `recall` presets for different use cases; configurable via `retrieval.preset` in config
+- **`formatRankTable` and `formatRankJSON` improvements** — better output formatting for ranked results with score breakdown and relevance explanation
+- **Performance optimization** — optimize ranking algorithm for large codebases (10K+ files), target <100ms for --query on 1000-file repos
+- **Regression tests** — ensure hit@5 maintains ≥ 0.80 (no regression from v2.6)
+- **Precision improvement** — target precision@5 improvement of ≥ 5% over v2.6
+
+### Config additions
+```json
+{
+  "retrieval": {
+    "topK": 10,
+    "recencyBoost": 1.5,
+    "preset": "balanced",
+    "weights": {
+      "exactToken": 1.0,
+      "symbolMatch": 0.5,
+      "prefixMatch": 0.3,
+      "pathMatch": 0.8
+    }
+  }
+}
+```
+
+### Go / No-go criteria
+- All tests green (21 extractor + all integration suites)
+- Benchmark hit@5 ≥ 0.80 (no regression from v2.6)
+- Precision@5 improves by ≥ 5%
+- `--query` performance <100ms for 1000-file repos
+
+---
+
+## [2.6.0] — 2026-04-05 · [#16](https://github.com/manojmallick/sigmap/issues/16)
 
 ### Planned additions
 - **`benchmarks/repos/`** — register 5 real open-source repos (express, flask, gin, spring-petclinic, rails) as git submodules or clone targets for evaluation

README.md

@@ -110,24 +110,19 @@ AI agent session starts with full context
 
 ---
 
-## 🔭 What's next — v2.5-v2.6 (in progress · [#14](https://github.com/manojmallick/sigmap/issues/14) · [#16](https://github.com/manojmallick/sigmap/issues/16))
+## 🔭 What's next — v2.7 (in progress · [#19](https://github.com/manojmallick/sigmap/issues/19))
 
-### v2.6 — Research Mode
+### v2.7 — Ranking Optimization
 
 | Feature | Description |
 |---|---|
-| **`--benchmark --repo <path>`** | Run benchmarks against any external repository (express, flask, gin, spring-petclinic, rails) |
-| **`--report --paper`** | Generate paper-ready metrics: markdown + LaTeX tables for academic publishing |
-| **50 real eval tasks** | JSONL task file covering 5 real open-source repos — `benchmarks/tasks/retrieval-real.jsonl` |
-| **`src/eval/paper.js`** | Zero-dependency LaTeX table formatter for token reduction, hit@5, MRR, latency (p50/p95/p99) |
-| **8 new tests** | `paper.test.js` — report generation, LaTeX syntax validation, graceful failures |
+| **Fine-tuned ranking weights** | Optimize weights in `src/retrieval/ranker.js` for better precision based on benchmark evaluation |
+| **TF-IDF scoring** | Add term frequency-inverse document frequency scoring option for better semantic relevance |
+| **Weight presets** | `precision`, `balanced`, `recall` presets — configurable via `retrieval.preset` |
+| **Performance optimization** | <100ms query performance for 1000-file repos, optimized for large codebases (10K+ files) |
+| **Precision improvement** | Target ≥5% precision@5 improvement while maintaining hit@5 ≥ 0.80 |
 
-### v2.5 — Impact Layer
-
-| Feature | Description |
-|---|---|
-| **`--impact <file>`** | Show every file that transitively depends on a changed file — instant blast-radius awareness |
-| **`--impact --json`** | Machine-readable output for CI pipelines |
+---
 | **`get_impact` MCP tool** | 9th MCP tool — `{ file, depth? }` → impacted files + signatures |
 | **`src/map/dep-graph.js`** | Reverse-dependency graph built from the import analysis; circular deps handled safely |
 | **15 new tests** | `impact.test.js` — direct deps, transitive deps, depth limit, JSON output |

docs/cli.html

@@ -185,7 +185,7 @@ <h2>All flags at a glance</h2>
       <span class="term-title">node gen-context.js --help</span>
     </div>
     <div class="term-body">
-      <div><span class="tp">SigMap v2.6.0</span></div>
+      <div><span class="tp">SigMap v2.7.0</span></div>
       <div>&nbsp;</div>
       <div><span class="tc">Usage:</span> <span class="tw">node gen-context.js [flag]</span></div>
       <div>&nbsp;</div>
@@ -609,7 +609,7 @@ <h2>Explore further</h2>
 
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0</span>
+    <span class="footer-logo">sigmap v2.7.0</span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>

docs/config.html

@@ -472,7 +472,7 @@ <h2>Explore further</h2>
 
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0</span>
+    <span class="footer-logo">sigmap v2.7.0</span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>

docs/index.html

@@ -13,7 +13,7 @@
 <meta name="twitter:image" content="https://manojmallick.github.io/sigmap/sigmap-banner.png">
 <link rel="canonical" href="https://manojmallick.github.io/sigmap/">
 <link rel="sitemap" type="application/xml" href="https://manojmallick.github.io/sigmap/sitemap.xml">
-<script type="application/ld+json">{"@context":"https://schema.org","@type":"SoftwareApplication","name":"SigMap","applicationCategory":"DeveloperApplication","description":"Zero-dependency AI context engine. 97% token reduction for AI coding agents. Extracts signatures from 21 languages. No npm install.","url":"https://manojmallick.github.io/sigmap/","downloadUrl":"https://www.npmjs.com/package/sigmap","softwareVersion":"2.6.0","operatingSystem":"Any (Node.js 18+)","offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"author":{"@type":"Person","name":"Manoj Mallick","url":"https://github.com/manojmallick"}}</script>
+<script type="application/ld+json">{"@context":"https://schema.org","@type":"SoftwareApplication","name":"SigMap","applicationCategory":"DeveloperApplication","description":"Zero-dependency AI context engine. 97% token reduction for AI coding agents. Extracts signatures from 21 languages. No npm install.","url":"https://manojmallick.github.io/sigmap/","downloadUrl":"https://www.npmjs.com/package/sigmap","softwareVersion":"2.7.0","operatingSystem":"Any (Node.js 18+)","offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"author":{"@type":"Person","name":"Manoj Mallick","url":"https://github.com/manojmallick"}}</script>
 <link href="https://fonts.googleapis.com/css2?family=Syne:wght@700;800&family=IBM+Plex+Mono:wght@400;500&family=DM+Sans:wght@300;400;500;600&display=swap" rel="stylesheet">
 <script>(function(){var r=document.documentElement;if(localStorage.getItem('cf-theme')==='light')r.classList.add('light');document.addEventListener('DOMContentLoaded',function(){document.querySelectorAll('.theme-toggle').forEach(function(b){b.addEventListener('click',function(){r.classList.toggle('light');localStorage.setItem('cf-theme',r.classList.contains('light')?'light':'dark');});});});})();</script>
 <style>
@@ -438,7 +438,7 @@ <h2>Built for the community</h2>
 <!-- FOOTER -->
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0 &middot; <a href="roadmap.html#v2.6" style="color:var(--gd);text-decoration:none">Latest</a></span>
+    <span class="footer-logo">sigmap v2.7.0 &middot; <a href="roadmap.html#v2.7" style="color:var(--gd);text-decoration:none">Latest</a></span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>

docs/languages.html

@@ -619,7 +619,7 @@ <h2>Contributing is simple</h2>
 
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0 &middot; <a href="roadmap.html#v2.6" style="color:var(--gd);text-decoration:none">Latest</a></span>
+    <span class="footer-logo">sigmap v2.7.0 &middot; <a href="roadmap.html#v2.7" style="color:var(--gd);text-decoration:none">Latest</a></span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>

docs/mcp.html

@@ -512,7 +512,7 @@ <h2>Explore further</h2>
 
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0</span>
+    <span class="footer-logo">sigmap v2.7.0</span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>

docs/quick-start.html

@@ -442,7 +442,7 @@ <h2>Command reference</h2>
       <span class="term-title">node gen-context.js --help</span>
     </div>
     <div class="term-body">
-      <div><span class="tp">SigMap v2.6.0 &middot; <a href="roadmap.html#v2.6" style="color:var(--gd);text-decoration:none">Latest</a></span></div>
+      <div><span class="tp">SigMap v2.7.0 &middot; <a href="roadmap.html#v2.7" style="color:var(--gd);text-decoration:none">Latest</a></span></div>
       <div>&nbsp;</div>
       <div><span class="tc">Usage:</span> <span class="tw">node gen-context.js [flag]</span></div>
       <div>&nbsp;</div>
@@ -495,7 +495,7 @@ <h2>Explore further</h2>
 
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0 &middot; <a href="roadmap.html#v2.6" style="color:var(--gd);text-decoration:none">Latest</a></span>
+    <span class="footer-logo">sigmap v2.7.0 &middot; <a href="roadmap.html#v2.7" style="color:var(--gd);text-decoration:none">Latest</a></span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>

docs/repomix.html

@@ -518,7 +518,7 @@ <h2>Both tools, five minutes</h2>
 
 <footer>
   <div class="footer-inner">
-    <span class="footer-logo">sigmap v2.6.0</span>
+    <span class="footer-logo">sigmap v2.7.0</span>
     <div class="footer-links">
       <a href="quick-start.html">Quick start</a>
       <a href="cli.html">CLI reference</a>