sigmap 8.17.0 → 8.19.0

package/AGENTS.md

@@ -33,16 +33,18 @@ Always run `sigmap ask` (or `sigmap --query`) before searching for files relevan
 src/extractors/python_ast.py ← ast
 ```
 
-## changes (last 5 commits — 1 second ago)
+## changes (last 5 commits — 0 seconds ago)
 ```
 src/extractors/csharp.js                      ~extract  ~extractMembers
+src/extractors/dart.js                        ~extract  ~extractMembers
 src/extractors/go.js                          ~extract  ~extractInterfaceMethods
 src/extractors/java.js                        ~extract  ~extractMembers
+src/extractors/kotlin.js                      ~extract  ~extractMembers
+src/extractors/php.js                         ~extract  ~extractMembers
 src/extractors/rust.js                        ~extract  ~extractMethods  ~extractReturnType
+src/extractors/scala.js                       ~extract  ~extractMembers
+src/extractors/swift.js                       ~extract  ~extractMembers  ~extractArrowType
 src/evidence/pack.js                          +riskFactorsFor  ~parseAnchor  ~buildEvidencePack  ~formatMarkdown
-src/graph/call-graph.js                       +buildCallFileGraph  ~buildCallGraph  ~formatCallGraphJSON  ~_resolveSymbol
-src/mcp/handlers.js                           ~queryContext
-src/retrieval/ranker.js                       ~scoreFile  ~rank
 ```
 
 ## packages
@@ -174,6 +176,11 @@ code-fence ---
 
 ## src
 
+### src/config/defaults.js
+```
+module.exports = { DEFAULTS }  :165-165
+```
+
 ### src/extractors/csharp.js
 ```
 module.exports = { extract }  :71-71
@@ -184,6 +191,15 @@ function normalizeParams(params)  :61-64
 function normalizeType(type)  :66-69
 ```
 
+### src/extractors/dart.js
+```
+module.exports = { extract }  :84-84
+function extract(src) → string[]  :12-84
+function extractBlock(src, startIndex)  :54-63
+function extractMembers(block)  :65-77
+function normalizeParams(params)  :79-81
+```
+
 ### src/extractors/go.js
 ```
 module.exports = { extract }  :81-81
@@ -203,6 +219,25 @@ function normalizeParams(params)  :61-64
 function normalizeType(type)  :66-69
 ```
 
+### src/extractors/kotlin.js
+```
+module.exports = { extract }  :90-90
+function extract(src) → string[]  :12-90
+function extractBlock(src, startIndex)  :54-63
+function extractMembers(block)  :65-90
+function normalizeParams(params)  :81-88
+```
+
+### src/extractors/php.js
+```
+module.exports = { extract }  :96-96
+function extract(src) → string[]  :12-96
+function extractBlock(src, startIndex)  :58-67
+function extractMembers(block)  :69-96
+function normalizeParams(params)  :86-89
+function normalizeType(type)  :91-94
+```
+
 ### src/extractors/rust.js
 ```
 module.exports = { extract }  :110-110
@@ -213,6 +248,26 @@ function normalizeParams(params)  :97-100
 function extractReturnType(afterParen)  :102-110
 ```
 
+### src/extractors/scala.js
+```
+module.exports = { extract }  :88-88
+function extract(src) → string[]  :12-88
+function extractBlock(src, startIndex)  :47-56
+function extractMembers(block)  :58-88
+function normalizeParams(params)  :74-81
+function normalizeType(type)  :83-86
+```
+
+### src/extractors/swift.js
+```
+module.exports = { extract }  :97-97
+function extract(src) → string[]  :12-97
+function extractBlock(src, startIndex)  :54-63
+function extractMembers(block)  :65-97
+function normalizeParams(params)  :80-87
+function extractArrowType(str)  :89-97
+```
+
 ### src/mcp/server.js
 ```
 module.exports = { start }  :141-141
@@ -222,6 +277,12 @@ function dispatch(msg, cwd)  :41-108
 function start(cwd)  :113-139
 ```
 
+### src/retrieval/enrich-from-maps.js
+```
+module.exports = { enrichWithSurfaces }  :55-55
+function enrichWithSurfaces(index, cwd) → number  :25-53
+```
+
 ### src/analysis/coverage-score.js
 ```
 module.exports = { coverageScore, CODE_EXTS }  :105-105
@@ -259,11 +320,6 @@ function getChangedFiles(files, cache) → { changed: string[], unch  :71-88
 function updateCacheEntries(cache, extracted)  :96-103
 ```
 
-### src/config/defaults.js
-```
-module.exports = { DEFAULTS }  :163-163
-```
-
 ### src/config/loader.js
 ```
 module.exports = { loadConfig, loadBaseConfig }  :313-313
@@ -520,15 +576,6 @@ module.exports = { extract }  :69-69
 function extract(src) → string[]  :8-17
 ```
 
-### src/extractors/dart.js
-```
-module.exports = { extract }  :60-60
-function extract(src) → string[]  :8-60
-function extractBlock(src, startIndex)  :34-43
-function extractMembers(block)  :45-53
-function normalizeParams(params)  :55-57
-```
-
 ### src/extractors/deps.js
 ```
 module.exports = { extractPythonDeps, extractTSDeps, extractRDeps, buildReverseDepMap }  :110-110
@@ -589,15 +636,6 @@ function formatReturnHint(type)  :138-140
 function normalizeParams(params)  :142-145
 ```
 
-### src/extractors/kotlin.js
-```
-module.exports = { extract }  :66-66
-function extract(src) → string[]  :8-66
-function extractBlock(src, startIndex)  :34-43
-function extractMembers(block)  :45-66
-function normalizeParams(params)  :57-64
-```
-
 ### src/extractors/line-anchor.js
 ```
 module.exports = { lineAt, anchor, withAnchor }  :52-52
@@ -618,16 +656,6 @@ module.exports = { extract }  :135-135
 function extract(src) → string[]  :10-133
 ```
 
-### src/extractors/php.js
-```
-module.exports = { extract }  :71-71
-function extract(src) → string[]  :8-71
-function extractBlock(src, startIndex)  :37-46
-function extractMembers(block)  :48-71
-function normalizeParams(params)  :61-64
-function normalizeType(type)  :66-69
-```
-
 ### src/extractors/prdiff.js
 ```
 module.exports = { diffSignatures, extractName }  :70-70
@@ -709,16 +737,6 @@ function normalizeParams(params)  :40-43
 function extractReturnHint(stripped, index)  :45-52
 ```
 
-### src/extractors/scala.js
-```
-module.exports = { extract }  :76-76
-function extract(src) → string[]  :8-76
-function extractBlock(src, startIndex)  :39-48
-function extractMembers(block)  :50-76
-function normalizeParams(params)  :62-69
-function normalizeType(type)  :71-74
-```
-
 ### src/extractors/shell.js
 ```
 module.exports = { extract }  :43-43
@@ -741,16 +759,6 @@ function normalizeParams(params)  :48-51
 function normalizeType(type)  :53-56
 ```
 
-### src/extractors/swift.js
-```
-module.exports = { extract }  :73-73
-function extract(src) → string[]  :8-73
-function extractBlock(src, startIndex)  :34-43
-function extractMembers(block)  :45-73
-function normalizeParams(params)  :56-63
-function extractArrowType(str)  :65-73
-```
-
 ### src/extractors/terraform.js
 ```
 module.exports = { extract }  :74-74
@@ -1088,41 +1096,6 @@ function walk(dir, cwd, depth, out)  :31-62
 function analyze(files, cwd)  :64-82
 ```
 
-### src/map/route-table.js
-```
-module.exports = { analyze }  :127-127
-function shouldSkipFile(rel)  :18-21
-function analyze(files, cwd)  :23-125
-```
-
-### src/mcp/handlers.js
-```
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput }  :975-975
-function _readContextFiles(cwd)  :10-17
-function readContext(args, cwd)  :36-66
-function searchSignatures(args, cwd)  :74-100
-function getMap(args, cwd)  :108-131
-function createCheckpoint(args, cwd)  :143-215
-function getRouting(args, cwd)  :224-261
-function explainFile(args, cwd)  :269-356
-function listModules(args, cwd)  :364-403
-function queryContext(args, cwd)  :411-438
-function getMethodImpact(args, cwd)  :446-460
-function getImpact(args, cwd)  :468-480
-function getLines(args, cwd)  :489-537
-function readMemory(args, cwd)  :545-580
-function getCalleeSignatures(args, cwd)  :589-634
-function _pkgVersion(cwd)  :641-644
-function notifyFileCreated(args, cwd)  :648-670
-function notifySymbolAdded(args, cwd)  :673-693
-function notifyFileDeleted(args, cwd)  :696-710
-function _changedFiles(cwd, args)  :716-728
-function getDiffContext(args, cwd)  :737-808
-function getArchitectureOverview(args, cwd)  :817-885
-function verifySuggestion(args, cwd)  :895-930
-function squeezeOutput(args, cwd)  :940-973
-```
-
 ### src/mcp/install.js
 ```
 module.exports = { CLIENTS, listClients, installClient, resolveTarget }  :142-142

package/CHANGELOG.md

@@ -10,6 +10,34 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.19.0] — 2026-07-19
+
+Minor release — **"Honest Numbers" (v8.19, P0)**: the published retrieval lift now comes from a measured grep-agent comparison, not a random-file baseline, and every proxy metric says so on the label.
+
+### Added
+- **Honest grep-agent baseline benchmark (#495, PR #496):** new `scripts/run-honest-benchmark.mjs` (`npm run benchmark:honest`) scores the production ranker against an internal single-shot grep-agent baseline — a pure-Node, zero-dependency, no-child-process repo scan ranked by distinct-term coverage then occurrences, `.gitignore`-aware, deterministic ordering — on the same 110-task / 19-repo corpus and the same scorer. **Measured: SigMap 86.4% hit@5 / MRR .780 vs grep 42.7% / .228 → 2.02× lift (+43.6pt)** → `benchmarks/reports/honest-baseline.json`. `computeLatest` derives `grep_baseline_hit_at_5` + `grep_lift` from the report (optional-report pattern; hermetic fixture unaffected).
+- **Claim-hygiene guard test:** `test/integration/honest-baseline.test.js` (7 checks) — report shape, derived-not-hand-typed metrics, version.json mirror, and a one-way door: the 6.4×-vs-random lift, the 13.6% random baseline, and the unsourced "10% without" claim can never reappear on README or llms surfaces; the benchmark script itself is guarded to stay child-process-free.
+
+### Changed
+- **Random-baseline lift retired from all human surfaces (#495, PR #496):** README and llms.txt/llms-full.txt now quote the measured grep-agent lift (2.02×) instead of 6.4×-vs-random; task success is labeled a **retrieval-tier proxy** ("modeled from retrieval tiers, not measured LLM sessions") and the "baseline 10%" / "up from 10%" claims are removed. The random-baseline fields (`baseline_hit_at_5`, `retrieval_lift`) remain in latest.json/version.json as data only. `readme-structure` guards advanced: README must show the grep baseline and must **not** show the random one.
+
+---
+
+## [8.18.0] — 2026-07-12
+
+Minor release — **the §7.4 Phase-2 closer**: with these three changes, every quality-ceiling row in the master plan's scorecard is done or measure-gated-closed.
+
+### Added
+- **Line anchors for Kotlin, Swift, PHP, Scala, and Dart (#486, PR #487):** the v8.17 recipe applied to the remaining five brace languages — newline-preserving comment strips, brace-matched `:start-end` ranges on types, `:n-n` members, body-scan ranging for top-level functions (expression bodies and PSR next-line braces degrade to single-line anchors). All five fixture files anchor 100%; **9 brace languages** now carry Surgical Context anchors.
+- **Route surface-enrichment, opt-in and measure-gated (#488, PR #489):** `collectRoutes` split out of the route-table analyzer (markdown unchanged); `enrichWithSurfaces` appends deterministic `route METHOD /path` pseudo-signatures to the defining file's rankable index entry (sorted, deduped, copy-on-write, idempotent). Config `retrieval.surfaceEnrichment` (default `false`) wired into `ask`/`--query`/`query_context`. **Measured** by the new `npm run benchmark:surface-enrichment` A/B: 280 route pseudo-sigs across 18 repos, 90 tasks — **delta +0** (the corpus never asks route-worded questions), so the default stays off per the gate; the fixture test proves the value case directly — a route-worded query retrieves the controller *only* when enriched.
+
+### Changed
+- **Docs — the agent's live loop (#490, PR #491):** new "Your agent's live loop" section in the MCP guide framing `query_context` → `get_callee_signatures` → `get_lines` → `verify_suggestion` → `get_method_impact` as what an agentic loop *calls for grounding* (grep finds; SigMap grounds); README gains the framing and the previously missing `get_method_impact` in its tool list.
+- **Ranking is now anchor-invariant:** BM25 strips `:start-end` line anchors before tokenizing, so adding anchors to an extractor never shifts length normalization — this moved one borderline task from partial to **rank-1** (correct 61→62/90, task-success proxy 67.8→68.9%).
+- **Headline metric shift, documented honestly:** anchors on the five new corpus languages consume real context budget, and one already-borderline Swift task (`vapor-t002`, a route-worded query) fell out of top-5 — **hit@5 87.8% → 86.7%** (stable across repeated runs, root-caused to the vapor repo). Rank-1 accuracy and task success went **up**; the trade buys Surgical Context anchors on 9 languages.
+
+---
+
 ## [8.17.0] — 2026-07-12
 
 Minor release — **line anchors for Java, Go, Rust, and C#** (§7.4 Lang ceiling, the roadmap's long-named "anchors for the remaining extractors" item).

package/README.md

@@ -59,10 +59,10 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 
 **Proof it pays off** (full benchmark below):
 <!--SM:whyMetrics-->
-- **87.8% hit@5** — right file found in top 5 results (vs 13.6% baseline)
-- **97.0% token reduction** — average across 21 real repos
-- **67.8% task success rate** — up from 10% without context
-- **1.44 prompts per task** — down from 2.84 (49.2% fewer retries)
+- **86.7% hit@5** — right file in top 5 results (vs 42.7% single-shot grep baseline — 2.02× lift)
+- **96.9% token reduction** — average across 21 real repos
+- **68.9% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
+- **1.44 prompts per task** — down from 2.84 (49.2% fewer retries, modeled)
 <!--/SM:whyMetrics-->
 - **<!--SM:languages-->33<!--/SM:languages--> languages supported** — TypeScript, Python, Go, Rust, Java, R, and more
 - **No vendor lock-in** — works with any AI assistant or local LLM
@@ -98,7 +98,7 @@ sigmap verify answer.md --report        # standalone red/amber/green HTML report
 | Without SigMap | With SigMap |
 |---|---|
 | ❌ Non-reproducible agent guesses | ✅ Deterministic map — same input, same output, every time |
-| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->88%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
+| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->87%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
 | ❌ Embeddings / vector DB required | ✅ Zero deps, no infra, fully offline |
 
 ---
@@ -122,13 +122,13 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.17-main (21 repositories, including R language)
-Date      : 2026-07-12
+Benchmark : sigmap-v8.19-main (21 repositories, including R language)
+Date      : 2026-07-19
 
-Hit@5          : 87.8%   (baseline 13.6%  — 6.5× lift)
-Token reduction: 97.0%   (across 21 repos)
-Prompt reduction : 49.2% (2.84 → 1.44 prompts per task)
-Task success   : 67.8%   (baseline 10%)
+Hit@5          : 86.7%   (grep-agent baseline 42.7%  — 2.02× lift)
+Token reduction: 96.9%   (across 21 repos)
+Prompt reduction : 49.2% (2.84 → 1.44 prompts per task, modeled)
+Task success   : 68.9%   (proxy — modeled from retrieval tiers)
 Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
 ```
 <!--/SM:benchmarkBlock-->
@@ -228,7 +228,9 @@ Use SigMap with open-source tools and fully self-hosted setups:
 sigmap --mcp
 ```
 
-Tools: `read_context`, `search_signatures`, `get_map`, `create_checkpoint`, `get_routing`, `explain_file`, `list_modules`, `query_context`, `get_impact`, `get_lines`, `read_memory`, `get_callee_signatures`, `get_diff_context` (changed files + signatures + blast radius), `get_architecture_overview` (modules, hub files, cycles), `verify_suggestion` (ground AI code against repo + installed libraries), `squeeze_output` (compress noisy tool/log/JSON output mid-session), plus the live-index notifications `sigmap_notify_file_created`, `sigmap_notify_symbol_added`, and `sigmap_notify_file_deleted`. Full reference: [llms-full.txt](llms-full.txt).
+Tools: `read_context`, `search_signatures`, `get_map`, `create_checkpoint`, `get_routing`, `explain_file`, `list_modules`, `query_context`, `get_method_impact` (per-symbol blast radius), `get_impact`, `get_lines`, `read_memory`, `get_callee_signatures`, `get_diff_context` (changed files + signatures + blast radius), `get_architecture_overview` (modules, hub files, cycles), `verify_suggestion` (ground AI code against repo + installed libraries), `squeeze_output` (compress noisy tool/log/JSON output mid-session), plus the live-index notifications `sigmap_notify_file_created`, `sigmap_notify_symbol_added`, and `sigmap_notify_file_deleted`. Full reference: [llms-full.txt](llms-full.txt).
+
+SigMap doesn't compete with your agent's live search — it's what the live loop **calls for grounding**: grep finds the file; `query_context` → `get_callee_signatures` → `get_lines` → `verify_suggestion` → `get_method_impact` prove the symbols, lines, calls, and blast radius — deterministically. See [the agent live-loop guide](https://sigmap.io/guide/mcp#your-agents-live-loop).
 
 ---