sigmap 3.6.0 → 4.0.1

package/AGENTS.md

@@ -12,43 +12,40 @@ Use this marker block for all appendable context files:
 ## Auto-generated signatures
 <!-- Updated by gen-context.js -->
 You are a coding assistant with full knowledge of this codebase.
-Below are the code signatures extracted by SigMap v3.5.1 on 2026-04-14T23:05:11.451Z.
+Below are the code signatures extracted by SigMap v4.0.0 on 2026-04-15T06:03:22.464Z.
 
 Use these signatures to answer questions about the code accurately.
 
 ## Code Signatures
 
-<!-- Generated by SigMap gen-context.js v3.5.1 -->
+<!-- Generated by SigMap gen-context.js v4.0.0 -->
 <!-- DO NOT EDIT below the marker line — run gen-context.js to regenerate -->
 
 # Code signatures
 
-## packages
-
-### packages/core/index.js
+## changes (last 5 commits — 7 minutes ago)
 ```
-module.exports = { extract, rank, buildSigIndex, scan, score, adapt }
-function _resolveExtractor(language)
-function extract(src, language) → string[]
-function rank(query, sigIndex, opts) → { file: string, score: nu
-function buildSigIndex(cwd) → Map<string, string[]>
-function scan(sigs, filePath) → { safe: string[], redacte
-function score(cwd) → { * score: number, * grad
-function adapt(context, adapterName, opts = {}) → string
+src/analysis/coverage-score.js                +coverageScore  +_walk
+src/eval/analyzer.js                          ~analyzeFiles
+src/extractors/generic.js                     +extract
+src/format/llm-txt.js                         +outputPath  +format
+src/format/llms-txt.js                        +outputPath  +getShortCommit  +detectVersion  +format
+packages/adapters/claude.js                   +_confidenceMeta  ~format
+packages/adapters/copilot.js                  +_confidenceMeta  ~format
+packages/adapters/cursor.js                   +_confidenceMeta  ~format
+packages/adapters/gemini.js                   +_confidenceMeta  ~format  ~write
+packages/adapters/llm-full.js                 +outputPath  +format  +write
+packages/adapters/openai.js                   +_confidenceMeta  ~format  ~outputPath
+packages/adapters/windsurf.js                 +_confidenceMeta  ~format
 ```
 
-### packages/adapters/claude.js
-```
-module.exports = { name, format, outputPath, write }
-function format(context, opts = {}) → string
-function outputPath(cwd) → string
-function write(context, cwd, opts = {})
-```
+## packages
 
-### packages/adapters/codex.js
+### packages/adapters/claude.js
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
@@ -57,6 +54,7 @@ function write(context, cwd, opts = {})
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
@@ -65,6 +63,7 @@ function write(context, cwd, opts = {})
 ```
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 ```
 
@@ -74,15 +73,7 @@ module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
-```
-
-### packages/adapters/index.js
-```
-module.exports = { getAdapter, listAdapters, adapt, outputsToAdapters }
-function getAdapter(name) → { name: string, format: F
-function listAdapters() → string[]
-function adapt(context, adapterName, opts = {}) → string
-function outputsToAdapters(outputs) → string[]
+function _confidenceMeta(opts)
 ```
 
 ### packages/adapters/llm-full.js
@@ -98,15 +89,34 @@ function write(context, cwd, opts)
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
 function outputPath(cwd) → string
+function _confidenceMeta(opts)
 ```
 
 ### packages/adapters/windsurf.js
 ```
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
+function _confidenceMeta(opts)
 function outputPath(cwd) → string
 ```
 
+### packages/adapters/codex.js
+```
+module.exports = { name, format, outputPath, write }
+function format(context, opts = {}) → string
+function outputPath(cwd) → string
+function write(context, cwd, opts = {})
+```
+
+### packages/adapters/index.js
+```
+module.exports = { getAdapter, listAdapters, adapt, outputsToAdapters }
+function getAdapter(name) → { name: string, format: F
+function listAdapters() → string[]
+function adapt(context, adapterName, opts = {}) → string
+function outputsToAdapters(outputs) → string[]
+```
+
 ### packages/cli/index.js
 ```
 module.exports = { CLI_ENTRY, run }
@@ -133,19 +143,25 @@ code-fence js
 code-fence ---
 ```
 
-## src
-
-### src/config/defaults.js
+### packages/core/index.js
 ```
-module.exports = { DEFAULTS }
+module.exports = { extract, rank, buildSigIndex, scan, score, adapt }
+function _resolveExtractor(language)
+function extract(src, language) → string[]
+function rank(query, sigIndex, opts) → { file: string, score: nu
+function buildSigIndex(cwd) → Map<string, string[]>
+function scan(sigs, filePath) → { safe: string[], redacte
+function score(cwd) → { * score: number, * grad
+function adapt(context, adapterName, opts = {}) → string
 ```
 
-### src/config/loader.js
+## src
+
+### src/analysis/coverage-score.js
 ```
-module.exports = { loadConfig }
-function detectAutoSrcDirs(cwd, excludeList) → string[]
-function loadConfig(cwd) → object
-function deepClone(obj)
+module.exports = { coverageScore }
+function coverageScore(cwd, fileEntries, config) → { * score: number, * grad
+function _walk(dir, excludeSet, out)
 ```
 
 ### src/eval/analyzer.js
@@ -161,52 +177,26 @@ function formatAnalysisTable(stats, showSlow) → string
 function formatAnalysisJSON(stats) → object
 ```
 
-### src/extractors/markdown.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/patterns.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/properties.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/python_dataclass.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/toml.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-```
-
-### src/extractors/typescript_react.js
+### src/extractors/generic.js
 ```
 module.exports = { extract }
-function extract(src) → string[]
+function extract(src)
 ```
 
-### src/extractors/vue_sfc.js
+### src/format/llm-txt.js
 ```
-module.exports = { extract }
-function extract(src) → string[]
+module.exports = { format, outputPath }
+function outputPath(cwd)
+function format(context, cwd, version)
 ```
 
-### src/extractors/xml.js
+### src/format/llms-txt.js
 ```
-module.exports = { extract }
-function extract(src) → string[]
+module.exports = { format, outputPath }
+function outputPath(cwd)
+function getShortCommit(cwd)
+function detectVersion(cwd)
+function format(context, cwd, writtenFiles, sigmapVersion)
 ```
 
 ### src/mcp/server.js
@@ -218,6 +208,19 @@ function dispatch(msg, cwd)
 function start(cwd)
 ```
 
+### src/config/defaults.js
+```
+module.exports = { DEFAULTS }
+```
+
+### src/config/loader.js
+```
+module.exports = { loadConfig }
+function detectAutoSrcDirs(cwd, excludeList) → string[]
+function loadConfig(cwd) → object
+function deepClone(obj)
+```
+
 ### src/eval/runner.js
 ```
 module.exports = { run, rank, loadTasks, buildSigIndex, formatTable, formatMetrics, tokenize }
@@ -301,12 +304,6 @@ module.exports = { extract }
 function extract(src) → string[]
 ```
 
-### src/extractors/generic.js
-```
-module.exports = { extract }
-function extract(src)
-```
-
 ### src/extractors/go.js
 ```
 module.exports = { extract }
@@ -359,6 +356,18 @@ function extractMembers(block)
 function normalizeParams(params)
 ```
 
+### src/extractors/markdown.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
+### src/extractors/patterns.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/php.js
 ```
 module.exports = { extract }
@@ -376,6 +385,12 @@ function diffSignatures(baseSigs, currentSigs) → {added:string[], removed:
 function extractName(sig)
 ```
 
+### src/extractors/properties.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/protobuf.js
 ```
 module.exports = { extract }
@@ -395,6 +410,12 @@ function normalizeParams(params)
 function extractDocHint(src, fnName, fnSigLine)
 ```
 
+### src/extractors/python_dataclass.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/ruby.js
 ```
 module.exports = { extract }
@@ -467,6 +488,12 @@ module.exports = { extractTodos }
 function extractTodos(src) → {line:number, tag:string,
 ```
 
+### src/extractors/toml.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/typescript.js
 ```
 module.exports = { extract }
@@ -477,6 +504,12 @@ function extractClassMembers(block)
 function normalizeParams(params)
 ```
 
+### src/extractors/typescript_react.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/vue.js
 ```
 module.exports = { extract }
@@ -485,6 +518,18 @@ function normalizeParams(params)
 function normalizeType(type)
 ```
 
+### src/extractors/vue_sfc.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
+### src/extractors/xml.js
+```
+module.exports = { extract }
+function extract(src) → string[]
+```
+
 ### src/extractors/yaml.js
 ```
 module.exports = { extract }
@@ -518,22 +563,6 @@ function generateDashboardHtml(cwd, health)
 function renderHistoryCharts(cwd, health)
 ```
 
-### src/format/llm-txt.js
-```
-module.exports = { format, outputPath }
-function outputPath(cwd)
-function format(context, cwd, version)
-```
-
-### src/format/llms-txt.js
-```
-module.exports = { format, outputPath }
-function outputPath(cwd)
-function getShortCommit(cwd)
-function detectVersion(cwd)
-function format(context, cwd, writtenFiles, sigmapVersion)
-```
-
 ### src/graph/builder.js
 ```
 module.exports = { build, buildFromCwd, extractFileDeps }

package/CHANGELOG.md

@@ -10,6 +10,62 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [4.0.1] — 2026-04-15 — Config auto-detection fix
+
+### Fixed
+- **Bundled `loadConfig` lacked `detectAutoSrcDirs`**: the inline `__factories["./src/config/loader"]` copy inside `gen-context.js` was a stripped-down version that returned raw `DEFAULTS` without filesystem auto-detection. After `--init` wrote a config with 6 hardcoded `srcDirs`, auto-detection was bypassed and custom project directories were missed — causing coverage to drop for any project whose source lives outside those 6 dirs. The bundled loader is now fully in sync with `src/config/loader.js`.
+- **`--init` config hardcoded `srcDirs`**: `gen-context.config.json.example` had `"srcDirs": ["src","app","lib","packages","services","api"]` as a plain value. Any project that ran `--init` would lock into those 6 dirs and lose auto-detection. The example now omits `srcDirs` entirely and uses `_comment` keys to explain that auto-detection runs automatically. Users who need custom dirs can add `srcDirs` manually.
+- **`gen-context.config.json` (SigMap repo)**: restored explicit `"srcDirs": ["src","packages"]` so the repo's own context generation is not affected by auto-detection picking up `docs-vp/`, `scripts/`, `test/`, and `vscode-extension/`.
+- **Example `outputs` updated**: `gen-context.config.json.example` now lists all four standard adapters — `["copilot","codex","claude","gemini"]` — matching the recommended setup.
+
+### Benchmarks (v4.0.1)
+- Token reduction: **97.6% average** across 18 repos ✅
+- Retrieval hit@5: **84.4%** (up from 83.3% in v4.0.0)
+
+---
+
+## [4.0.0] — 2026-04-15 — Intelligence Layer
+
+### Added
+- **Coverage score** (`src/analysis/coverage-score.js`): measures what fraction of source files made it into context after token-budget application.
+  - Grade scale: A ≥ 90% · B ≥ 75% · C ≥ 50% · D < 50%
+  - Confidence indicator: HIGH / MEDIUM / LOW
+  - Per-module breakdown per srcDir via `perModule` Map
+- **Confidence indicators in all output writers**: every generated file now includes a metadata comment:
+  ```
+  <!-- sigmap: version=4.0.0 confidence=HIGH coverage=94% dropped=9 commit=abc1234 -->
+  ```
+  Applies to: `copilot`, `claude`, `cursor`, `windsurf`, `openai`, `gemini` adapters.
+- **`--report` module heatmap**: ASCII bar chart per srcDir showing coverage percentage:
+  ```
+  Module Coverage:
+    src                ████████████████ 100% (64/64 files)
+    packages           ██████████████░░  86% (12/14 files)
+  ```
+  `--report --json` gains a `coverage` object with `score`, `grade`, `confidence`, `totalFiles`, `includedFiles`, `droppedFiles`, and `perModule`.
+- **`--diff` risk score**: each changed file is now classified LOW / MEDIUM / HIGH based on reverse-dependency BFS, public API exports, route status, and config-file status:
+  ```
+  [sigmap] Risk: Changed files (3):
+    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
+  ```
+- **Coverage in post-run summary**: every normal run now prints a `Coverage` line:
+  ```
+   Coverage       : A (97%)  — 76 of 78 source files included
+  ```
+- **Coverage in `--health` and `--health --json`**: coverage grade, score, and file counts are included in both text and JSON health output. `--health --json` adds `coverage`, `coverageGrade`, `coverageConfidence`, `coverageTotalFiles`, `coverageIncludedFiles`.
+
+### Changed
+- **Token budget drop order step 5**: now uses `signalQuality = sigs / linesOfCode` (least-informative files dropped first) instead of the previous "fewest sigs" heuristic.
+- **`src/eval/analyzer.js` `analyzeFiles()` output**: each file stat now includes `linesOfCode` and `signalQuality` fields.
+
+### Benchmark (v4.0.0)
+- Token reduction: **97.6% average** across 18 repos (target ≥ 97.0%) ✅
+- Retrieval hit@5: 83.3% (retrieval improvement targeted in v4.5 with adaptive query)
+
+---
+
 ## [3.5.0] — 2026-04-14 — Phase C/D Intelligence Expansion
 
 ### Added

package/README.md

@@ -19,7 +19,7 @@
 npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again.
 ```
 
-> Latest: **v3.5.0** adds Phase C/D intelligence expansion with framework-specialized extractors and cross-module pattern detection.
+> Latest: **v4.0.0** — Intelligence Layer. Coverage score, confidence indicators in every output file, `--report` module heatmap, `--diff` risk scoring, and extractor quality-based drop order.
 
 <div align="center">
 <img src="demo.gif" alt="SigMap demo — reducing 80K tokens to 4K in under 10 seconds" width="760" />
@@ -145,7 +145,7 @@ Reproduced with `node scripts/run-benchmark.mjs` on public repos:
 | fastify | JavaScript | 54.4K | 2.6K | **95.3%** |
 | fastapi | Python | 178.4K | 5.2K | **97.1%** |
 
-**Average: 97.5% reduction across 18 repos (16 languages).** See [`benchmarks/reports/token-reduction.md`](benchmarks/reports/token-reduction.md) or reproduce with `node scripts/run-benchmark.mjs`.
+**Average: 97.6% reduction across 18 repos (16 languages).** See [`benchmarks/reports/token-reduction.md`](benchmarks/reports/token-reduction.md) or reproduce with `node scripts/run-benchmark.mjs`.
 
 ---
 
@@ -746,17 +746,89 @@ 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.0.0
+ Files scanned  : 76
+ Symbols found  : 332
+ Token reduction: 94%  (65,227 → 4,103)
+ Coverage       : A (97%)  — 76 of 78 source files included
+ 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`
+
 ```bash
-# Append run metrics to .context/usage.ndjson
-sigmap --track
+sigmap --report
+```
 
-# Structured JSON report for CI (exits 1 if over budget)
+```
+[sigmap] report:
+  version         : 4.0.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):
+
+```bash
 sigmap --report --json
-# { "version": "2.0.0", "finalTokens": 3200, "reductionPct": 92.4, "overBudget": false }
+# { "version": "4.0.0", "finalTokens": 4103, "reductionPct": 93.7,
+#   "coverage": { "score": 97, "grade": "A", "confidence": "HIGH", ... } }
+```
+
+### Composite health score
 
-# Composite health score
+```bash
 sigmap --health
-# score: 95/100 (grade A) | reduction: 91.2% | 1 day since regen | 47 runs
+```
+
+```
+[sigmap] health:
+  score    : 80/100 (grade B)
+  coverage : A (97%)  — 76 of 78 source files
+  strategy : full
+  ...
+```
+
+```bash
+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
+
+```bash
+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

package/gen-context.config.json.example

@@ -1,11 +1,14 @@
 {
-  "_comment": "SigMap configuration — all keys are optional (defaults shown)",
+  "_comment": "SigMap configuration — all keys are optional (defaults shown). Copy to gen-context.config.json.",
 
   "output": ".github/copilot-instructions.md",
 
-  "outputs": ["copilot", "codex"],
+  "outputs": ["copilot", "codex", "claude", "gemini"],
 
-  "srcDirs": ["src", "app", "lib", "packages", "services", "api"],
+  "_srcDirs_comment": "Source directories to scan. OMIT this key to use auto-detection (recommended).",
+  "_srcDirs_comment2": "Auto-detection reads package.json/go.mod/Cargo.toml and scans top-level dirs automatically.",
+  "_srcDirs_comment3": "Only set this explicitly if auto-detection misses part of your project layout.",
+  "_srcDirs_example": ["src", "app", "lib", "packages", "services", "api"],
 
   "exclude": [
     "node_modules", ".git", "dist", "build", "out",

package/gen-context.js

@@ -116,14 +116,98 @@ __factories["./src/config/defaults"] = function(module, exports) {
 
 // ── ./src/config/loader ──
 __factories["./src/config/loader"] = function(module, exports) {
-  
+
   const fs = require('fs');
   const path = require('path');
   const { DEFAULTS } = __require('./src/config/defaults');
-  
+
   // Keys that are valid in gen-context.config.json
   const KNOWN_KEYS = new Set(Object.keys(DEFAULTS));
-  
+
+  // Common top-level folder names that reliably hold source code
+  const COMMON_CODE_DIRS = new Set([
+    'src', 'app', 'lib', 'packages', 'services', 'api', 'core', 'cmd',
+    'internal', 'pkg', 'handlers', 'controllers', 'models', 'views',
+    'components', 'pages', 'routes', 'middleware', 'utils', 'helpers',
+    'modules', 'plugins', 'extensions', 'adapters', 'drivers',
+    'hooks', 'composables', 'stores', 'features', 'domain', 'infra',
+    'infrastructure', 'application', 'data', 'Sources', 'Tests',
+  ]);
+
+  const SUPPORTED_CODE_EXTS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.py', '.pyw', '.java', '.kt', '.kts', '.go', '.rs', '.cs',
+    '.cpp', '.c', '.h', '.hpp', '.cc', '.rb', '.rake', '.php',
+    '.swift', '.dart', '.scala', '.sc', '.vue', '.svelte',
+    '.html', '.htm', '.css', '.scss', '.sass', '.less',
+    '.yml', '.yaml', '.sh', '.bash', '.zsh', '.fish',
+    '.sql', '.graphql', '.gql', '.tf', '.tfvars', '.proto',
+    '.toml', '.properties', '.xml', '.md',
+  ]);
+
+  function detectAutoSrcDirs(cwd, excludeList) {
+    const excludeSet = new Set(excludeList || []);
+    const candidates = new Set(DEFAULTS.srcDirs);
+
+    // Manifest-based detection
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+        if (allDeps.react || allDeps.next)
+          for (const d of ['src', 'app', 'pages', 'components', 'hooks', 'lib', 'utils']) candidates.add(d);
+        if (allDeps['@angular/core'])
+          for (const d of ['src', 'projects', 'apps', 'libs']) candidates.add(d);
+        if (allDeps['@nestjs/core'])
+          for (const d of ['src', 'libs', 'apps']) candidates.add(d);
+        if (allDeps.vue)
+          for (const d of ['src', 'components', 'views', 'stores', 'composables', 'plugins']) candidates.add(d);
+        if (allDeps.svelte || allDeps['@sveltejs/kit'])
+          for (const d of ['src', 'lib', 'routes']) candidates.add(d);
+        if (allDeps.nx || allDeps.turbo || allDeps.lerna || pkg.workspaces)
+          for (const d of ['packages', 'apps', 'libs', 'services']) candidates.add(d);
+      } catch (_) {}
+    }
+    if (fs.existsSync(path.join(cwd, 'pyproject.toml')) || fs.existsSync(path.join(cwd, 'requirements.txt')) || fs.existsSync(path.join(cwd, 'setup.py')))
+      for (const d of ['src', 'app', 'apps', 'tests', 'examples', 'instance', 'blueprints']) candidates.add(d);
+    if (fs.existsSync(path.join(cwd, 'Gemfile')))
+      for (const d of ['app', 'lib', 'config', 'db', 'spec', 'test']) candidates.add(d);
+    if (fs.existsSync(path.join(cwd, 'composer.json')))
+      for (const d of ['app', 'resources', 'routes', 'database', 'tests']) candidates.add(d);
+    if (fs.existsSync(path.join(cwd, 'go.mod')))
+      for (const d of ['cmd', 'internal', 'pkg', 'api', 'handler', 'handlers', 'middleware', 'service']) candidates.add(d);
+    if (fs.existsSync(path.join(cwd, 'Cargo.toml')))
+      for (const d of ['src', 'crates', 'examples', 'tests', 'benches']) candidates.add(d);
+    if (fs.existsSync(path.join(cwd, 'pubspec.yaml')))
+      for (const d of ['lib', 'test', 'integration_test', 'example', 'bin']) candidates.add(d);
+    if (fs.existsSync(path.join(cwd, 'Package.swift')))
+      for (const d of ['Sources', 'Tests']) candidates.add(d);
+
+    // Top-level directory scan
+    try {
+      const entries = fs.readdirSync(cwd, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || excludeSet.has(entry.name)) continue;
+        const lname = entry.name.toLowerCase();
+        if (COMMON_CODE_DIRS.has(entry.name) || COMMON_CODE_DIRS.has(lname)) { candidates.add(entry.name); continue; }
+        const dirPath = path.join(cwd, entry.name);
+        try {
+          const subs = fs.readdirSync(dirPath, { withFileTypes: true });
+          if (subs.some(s => s.isFile() && (SUPPORTED_CODE_EXTS.has(path.extname(s.name).toLowerCase()) || s.name === 'Dockerfile'))) {
+            candidates.add(entry.name); continue;
+          }
+          if (subs.some(s => s.isDirectory() && ['src', 'lib', 'main', 'java', 'kotlin', 'scala', 'python'].includes(s.name)))
+            candidates.add(entry.name);
+        } catch (_) {}
+      }
+    } catch (_) {}
+
+    return Array.from(candidates).filter(d => {
+      try { return fs.statSync(path.join(cwd, d)).isDirectory(); } catch (_) { return false; }
+    });
+  }
+
   /**
    * Load and merge configuration for a given working directory.
    *
@@ -133,18 +217,24 @@ __factories["./src/config/loader"] = function(module, exports) {
   function loadConfig(cwd) {
     const configPath = path.join(cwd, 'gen-context.config.json');
     if (!fs.existsSync(configPath)) {
-      return deepClone(DEFAULTS);
+      const cfg = deepClone(DEFAULTS);
+      const detected = detectAutoSrcDirs(cwd, cfg.exclude);
+      if (detected.length > 0) cfg.srcDirs = detected;
+      return cfg;
     }
-  
+
     let userConfig;
     try {
       const raw = fs.readFileSync(configPath, 'utf8');
       userConfig = JSON.parse(raw);
     } catch (err) {
       console.warn(`[sigmap] config parse error in ${configPath}: ${err.message}`);
-      return deepClone(DEFAULTS);
+      const cfg = deepClone(DEFAULTS);
+      const detected = detectAutoSrcDirs(cwd, cfg.exclude);
+      if (detected.length > 0) cfg.srcDirs = detected;
+      return cfg;
     }
-  
+
     // Warn on unknown keys (helps catch typos)
     for (const key of Object.keys(userConfig)) {
       if (key.startsWith('_')) continue; // allow _comment etc.
@@ -152,7 +242,7 @@ __factories["./src/config/loader"] = function(module, exports) {
         console.warn(`[sigmap] unknown config key: "${key}" (ignored)`);
       }
     }
-  
+
     // Deep merge: top-level known keys from user override defaults
     // For object values (e.g. mcp), merge one level deep
     const merged = deepClone(DEFAULTS);
@@ -167,6 +257,13 @@ __factories["./src/config/loader"] = function(module, exports) {
         merged[key] = val;
       }
     }
+
+    // If user didn't specify srcDirs, auto-detect; fall back to DEFAULTS if nothing found
+    if (!Array.isArray(userConfig.srcDirs)) {
+      const detected = detectAutoSrcDirs(cwd, merged.exclude);
+      merged.srcDirs = detected.length > 0 ? detected : deepClone(DEFAULTS.srcDirs);
+    }
+
     // Backward compat (v3.0+): if user specified 'adapters', use it as 'outputs' too.
     // If user specified only 'outputs' (old configs), mirror to 'adapters'.
     if (merged.adapters && !Array.isArray(merged.adapters)) merged.adapters = null;
@@ -177,13 +274,13 @@ __factories["./src/config/loader"] = function(module, exports) {
     }
     return merged;
   }
-  
+
   function deepClone(obj) {
     return JSON.parse(JSON.stringify(obj));
   }
-  
-  module.exports = { loadConfig };
-  
+
+  module.exports = { loadConfig, detectAutoSrcDirs };
+
 };
 
 // ── ./src/extractors/cpp ──
@@ -4478,7 +4575,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '3.5.0',
+    version: '4.0.1',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -6040,7 +6137,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '3.6.0';
+const VERSION = '4.0.1';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -6276,13 +6373,17 @@ function applyTokenBudget(fileEntries, maxTokens) {
     else if (isTestFile(e.filePath)) { priority = 8;  dropReason = 'budget: test file'; }
     else if (isConfigFile(e.filePath)) { priority = 6; dropReason = 'budget: config file'; }
     else priority = 4;
-    return { ...e, priority, dropReason };
+    // v4.0: signal quality = sigs per line-of-code (higher = more informative)
+    const loc = e.content ? e.content.split('\n').length : 1;
+    const signalQuality = loc > 0 ? (e.sigs ? e.sigs.length : 0) / loc : 0;
+    return { ...e, priority, dropReason, signalQuality };
   });
 
-  // Within same priority, sort by mtime ascending (oldest first = drop first)
+  // Within same priority: sort by mtime ascending (oldest first), then signalQuality ascending (least informative first)
   withPriority.sort((a, b) => {
     if (b.priority !== a.priority) return b.priority - a.priority;
-    return (a.mtime || 0) - (b.mtime || 0);
+    if ((a.mtime || 0) !== (b.mtime || 0)) return (a.mtime || 0) - (b.mtime || 0);
+    return (a.signalQuality || 0) - (b.signalQuality || 0);
   });
 
   const kept = [];
@@ -6716,11 +6817,17 @@ function writeClaude(content, cwd) {
 // ---------------------------------------------------------------------------
 // Report
 // ---------------------------------------------------------------------------
-function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson, budgetLimit) {
+function _coverageBar(pct, width) {
+  width = width || 16;
+  const filled = Math.round(pct / 100 * width);
+  return '\u2588'.repeat(filled) + '\u2591'.repeat(width - filled);
+}
+
+function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson, budgetLimit, coverageResult) {
   const reduction = inputTokens > 0 ? (100 - (finalTokens / inputTokens) * 100).toFixed(1) : 0;
   const overBudget = finalTokens > (budgetLimit || 6000);
   if (asJson) {
-    process.stdout.write(JSON.stringify({
+    const payload = {
       version: VERSION,
       timestamp: new Date().toISOString(),
       rawTokens: inputTokens,
@@ -6731,7 +6838,22 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
       reductionPct: parseFloat(reduction),
       overBudget,
       budgetLimit: budgetLimit || 6000,
-    }) + '\n');
+    };
+    if (coverageResult) {
+      payload.coverage = {
+        score: coverageResult.score,
+        grade: coverageResult.grade,
+        confidence: coverageResult.confidence,
+        totalFiles: coverageResult.total,
+        includedFiles: coverageResult.included,
+        droppedFiles: coverageResult.dropped,
+        perModule: Object.fromEntries(
+          Array.from(coverageResult.perModule.entries())
+            .map(([k, v]) => [k, v])
+        ),
+      };
+    }
+    process.stdout.write(JSON.stringify(payload) + '\n');
     // Exit 1 in CI if over budget — lets pipelines fail fast
     if (overBudget) process.exitCode = 1;
   } else {
@@ -6743,6 +6865,20 @@ function printReport(inputTokens, finalTokens, fileCount, droppedCount, asJson,
     console.log(`  output tokens   : ~${finalTokens}`);
     console.log(`  budget limit    : ${budgetLimit || 6000}`);
     console.log(`  reduction       : ${reduction}%`);
+    if (coverageResult) {
+      console.log(`  coverage        : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} source files included`);
+      console.log(`  confidence      : ${coverageResult.confidence}`);
+      if (coverageResult.perModule && coverageResult.perModule.size > 0) {
+        console.log('');
+        console.log('  Module Coverage:');
+        for (const [dir, mod] of coverageResult.perModule) {
+          if (mod.total === 0) continue;
+          const bar = _coverageBar(mod.pct);
+          const attention = mod.pct < 50 ? '  \u2190 attention needed' : '';
+          console.log(`    ${dir.padEnd(18)} ${bar} ${String(mod.pct).padStart(3)}% (${mod.included}/${mod.total} files)${attention}`);
+        }
+      }
+    }
     if (overBudget) console.warn(`[sigmap] WARNING: output (${finalTokens} tokens) exceeds budget (${budgetLimit || 6000})`);
   }
 }
@@ -7032,6 +7168,41 @@ function runDiff(cwd, config, stagedOnly, baseRef) {
   const scope = baseRef ? `diff-vs-${baseRef}` : (stagedOnly ? 'staged' : 'diff');
   console.warn(`[sigmap] ${scope} files: ${fileEntries.length}, diff tokens: ~${finalTokens}`);
 
+  // v4.0: risk score per changed file
+  try {
+    const { buildFromCwd } = requireSourceOrBundled('./src/graph/builder');
+    const graph = buildFromCwd(cwd, { silent: true });
+    const reverseGraph = graph.reverse || new Map();
+
+    function _isRouteFile(f) {
+      return /\/(routes?|pages?|controllers?|handlers?|api)\//i.test(f)
+        || /\.(route|page|controller|handler)\.\w+$/.test(f);
+    }
+    function _riskScore(filePath, sigs, revGraph) {
+      let s = 0;
+      if (sigs.some(sig => sig.includes('export') || sig.includes('module.exports'))) s += 2;
+      const deps = revGraph.get(filePath) || new Set();
+      if (deps.size > 3) s += 2;
+      if (_isRouteFile(filePath)) s += 1;
+      if (/\.(config|env|settings)\.\w+$/.test(filePath)) s += 1;
+      return s >= 4 ? 'HIGH' : s >= 2 ? 'MEDIUM' : 'LOW';
+    }
+
+    console.warn(`[sigmap] Risk: Changed files (${fileEntries.length}):`);
+    for (const fe of fileEntries) {
+      const level = _riskScore(fe.filePath, fe.sigs, reverseGraph);
+      const rel   = path.relative(cwd, fe.filePath).replace(/\\/g, '/');
+      const deps  = reverseGraph.get(fe.filePath) || new Set();
+      const reasons = [];
+      if (fe.sigs.some(s => s.includes('export') || s.includes('module.exports'))) reasons.push('exports public API');
+      if (deps.size > 0) reasons.push(`${deps.size} downstream dependent${deps.size === 1 ? '' : 's'}`);
+      if (_isRouteFile(fe.filePath)) reasons.push('route file');
+      if (/\.(config|env|settings)\.\w+$/.test(fe.filePath)) reasons.push('config file');
+      const label = level === 'HIGH' ? '[HIGH]  ' : level === 'MEDIUM' ? '[MEDIUM]' : '[LOW]   ';
+      console.warn(`  ${rel.padEnd(40)} ${label}${reasons.length ? '  — ' + reasons.join(', ') : ''}`);
+    }
+  } catch (_) {}
+
   if (process.argv.includes('--report')) {
     // Also show what the full run would cost for comparison
     const fullResult = runGenerate(cwd, config, true);
@@ -7176,11 +7347,17 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
     const droppedCount = beforeCount - budgeted.length;
     const content = formatOutput(budgeted, cwd, false, config, null);
     const finalTokens = estimateTokens(content);
-    result = { inputTokenTotal, finalTokens, fileCount: beforeCount, droppedCount };
+    // v4.0: compute coverage score for --report heatmap
+    let coverageResult = null;
+    try {
+      const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+      coverageResult = coverageScore(cwd, budgeted, config);
+    } catch (_) {}
+    result = { inputTokenTotal, finalTokens, fileCount: beforeCount, droppedCount, coverageResult };
   }
 
   if (reportMode || process.argv.includes('--report')) {
-    printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, config.maxTokens);
+    printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, config.maxTokens, result.coverageResult);
   }
 
   // Usage tracking (v0.9) — optional append-only NDJSON log
@@ -7212,17 +7389,26 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
     const pct  = result.inputTokenTotal > 0
       ? Math.round((1 - result.finalTokens / result.inputTokenTotal) * 100)
       : 0;
-    process.stderr.write([
+    // v4.0: coverage score in post-run summary
+    let coverageLine = '';
+    try {
+      const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+      const cov = coverageScore(cwd, fileEntries, config);
+      coverageLine = ` Coverage       : ${cov.grade} (${cov.score}%)  \u2014 ${cov.included} of ${cov.total} source files included`;
+    } catch (_) {}
+    const lines = [
       bar,
       ` SigMap v${VERSION}`,
       ` Files scanned  : ${result.fileCount}`,
       ` Symbols found  : ${syms.toLocaleString()}`,
       ` Token reduction: ${pct}%  (${result.inputTokenTotal.toLocaleString()} \u2192 ${result.finalTokens.toLocaleString()})`,
-      ` Output         : .github/copilot-instructions.md`,
-      bar,
-      ` Try: "explain the architecture" \u00b7 "find the auth module"`,
-      bar, '',
-    ].join('\n'));
+    ];
+    if (coverageLine) lines.push(coverageLine);
+    lines.push(` Output         : .github/copilot-instructions.md`);
+    lines.push(bar);
+    lines.push(` Try: "explain the architecture" \u00b7 "find the auth module"`);
+    lines.push(bar, '');
+    process.stderr.write(lines.join('\n'));
   }
 
   return result;
@@ -7725,6 +7911,17 @@ function main() {
   if (args.includes('--health')) {
     const { score } = __require('./src/health/scorer');
     const result = score(cwd);
+    // v4.0: compute live coverage score to include in health output
+    let coverageResult = null;
+    try {
+      const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+      const { loadConfig: lc } = requireSourceOrBundled('./src/config/loader');
+      const cfg = lc(cwd);
+      // Use all files from srcDirs as proxies for "included" (no budget applied in health mode)
+      const allFiles = buildFileList(cwd, cfg);
+      const fakeEntries = allFiles.map(f => ({ filePath: f }));
+      coverageResult = coverageScore(cwd, fakeEntries, cfg);
+    } catch (_) {}
     if (args.includes('--json')) {
       // Feature 3 (VS Code) + Feature 5 (JetBrains): emit tokens + reduction for plugins
       const ctxPath = path.join(cwd, '.github', 'copilot-instructions.md');
@@ -7733,10 +7930,21 @@ function main() {
       if (fs.existsSync(ctxPath)) {
         try { tokens = estimateTokens(fs.readFileSync(ctxPath, 'utf8')); } catch (_) {}
       }
-      process.stdout.write(JSON.stringify({ ...result, tokens, reduction }) + '\n');
+      const payload = { ...result, tokens, reduction };
+      if (coverageResult) {
+        payload.coverage = coverageResult.score;
+        payload.coverageGrade = coverageResult.grade;
+        payload.coverageConfidence = coverageResult.confidence;
+        payload.coverageTotalFiles = coverageResult.total;
+        payload.coverageIncludedFiles = coverageResult.included;
+      }
+      process.stdout.write(JSON.stringify(payload) + '\n');
     } else {
       console.log('[sigmap] health:');
       console.log(`  score           : ${result.score}/100 (grade ${result.grade})`);
+      if (coverageResult) {
+        console.log(`  coverage        : ${coverageResult.grade} (${coverageResult.score}%)  — ${coverageResult.included} of ${coverageResult.total} source files`);
+      }
       console.log(`  strategy        : ${result.strategy}`);
       console.log(`  token reduction : ${result.tokenReductionPct !== null ? result.tokenReductionPct + '%' : 'no history'}`);
       console.log(`  days since regen: ${result.daysSinceRegen !== null ? result.daysSinceRegen : 'context file not found'}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "3.6.0",
+  "version": "4.0.1",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {

package/packages/adapters/claude.js

@@ -26,15 +26,26 @@ const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta      = _confidenceMeta(opts);
   return [
     `<!-- Generated by SigMap v${version} — ${timestamp} -->`,
+    meta,
     '',
     context,
   ].join('\n');
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `<!-- sigmap: ${parts.join(' ')} -->`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/adapters/copilot.js

@@ -24,11 +24,13 @@ const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version   || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta = _confidenceMeta(opts);
   const header = [
     `<!-- Generated by SigMap gen-context.js v${version} -->`,
     `<!-- Updated: ${timestamp} -->`,
+    meta,
     `<!-- Do not edit below — regenerate with: node gen-context.js -->`,
     '',
     '# Code signatures',
@@ -37,6 +39,15 @@ function format(context, opts = {}) {
   return header + context;
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `<!-- sigmap: ${parts.join(' ')} -->`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/adapters/cursor.js

@@ -22,17 +22,28 @@ const name = 'cursor';
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta      = _confidenceMeta(opts);
   const header = [
     `# Code signatures — generated by SigMap v${version}`,
     `# Updated: ${timestamp}`,
+    `# ${meta}`,
     `# Regenerate: node gen-context.js`,
     '',
   ].join('\n');
   return header + context;
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/adapters/gemini.js

@@ -36,9 +36,11 @@ function format(context, opts = {}) {
     ? `Project: ${opts.projectName}\n`
     : '';
 
+  const meta = _confidenceMeta(opts);
   return [
     `You are a coding assistant with complete knowledge of this codebase.`,
     `The following code signatures were extracted by SigMap v${version} on ${timestamp}.`,
+    `<!-- ${meta} -->`,
     projectLine,
     `These signatures represent every public function, class, and type in the project.`,
     `Refer to them when answering questions about code structure, APIs, and implementation.`,
@@ -91,4 +93,13 @@ function write(context, cwd, opts = {}) {
   fs.writeFileSync(filePath, newContent, 'utf8');
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 module.exports = { name, format, outputPath, write };

package/packages/adapters/openai.js

@@ -34,9 +34,11 @@ function format(context, opts = {}) {
     ? `Project: ${opts.projectName}\n`
     : '';
 
+  const meta = _confidenceMeta(opts);
   return [
     `You are a coding assistant with full knowledge of this codebase.`,
     `Below are the code signatures extracted by SigMap v${version} on ${timestamp}.`,
+    `<!-- ${meta} -->`,
     projectLine,
     `Use these signatures to answer questions about the code accurately.`,
     `When the user asks about a specific file or function, refer to the signatures below.`,
@@ -57,4 +59,13 @@ function outputPath(cwd) {
   return path.join(cwd, '.github', 'openai-context.md');
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 module.exports = { name, format, outputPath };

package/packages/adapters/windsurf.js

@@ -22,17 +22,28 @@ const name = 'windsurf';
  */
 function format(context, opts = {}) {
   if (!context || typeof context !== 'string') return '';
-  const version = opts.version || 'unknown';
+  const version   = opts.version || 'unknown';
   const timestamp = new Date().toISOString();
+  const meta      = _confidenceMeta(opts);
   const header = [
     `# Code signatures — generated by SigMap v${version}`,
     `# Updated: ${timestamp}`,
+    `# ${meta}`,
     `# Regenerate: node gen-context.js`,
     '',
   ].join('\n');
   return header + context;
 }
 
+function _confidenceMeta(opts) {
+  const parts = [`version=${opts.version || 'unknown'}`];
+  if (opts.confidence)    parts.push(`confidence=${opts.confidence}`);
+  if (opts.coverage != null) parts.push(`coverage=${opts.coverage}%`);
+  if (opts.dropped  != null) parts.push(`dropped=${opts.dropped}`);
+  if (opts.commit)        parts.push(`commit=${opts.commit}`);
+  return `sigmap: ${parts.join(' ')}`;
+}
+
 /**
  * Return the output file path for this adapter.
  * @param {string} cwd - Project root

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "3.5.0",
+  "version": "4.0.1",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "3.5.0",
+  "version": "4.0.1",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/analysis/coverage-score.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * SigMap coverage scorer — v4.0.0
+ *
+ * Measures what fraction of source files made it into the context output
+ * after token-budget application. This is complementary to the health score:
+ *   - Health score = context freshness / reduction quality / budget compliance
+ *   - Coverage score = how much of the codebase is represented in context
+ *
+ * Grade scale:  A ≥ 90%  |  B ≥ 75%  |  C ≥ 50%  |  D < 50%
+ *
+ * @param {string} cwd
+ * @param {Array<{filePath:string}>} fileEntries - files that made it into output
+ * @param {{srcDirs:string[], exclude:string[]}} config
+ * @returns {{
+ *   score: number,
+ *   grade: 'A'|'B'|'C'|'D',
+ *   total: number,
+ *   included: number,
+ *   dropped: number,
+ *   confidence: 'HIGH'|'MEDIUM'|'LOW',
+ *   perModule: Map<string, {total:number, included:number, pct:number}>,
+ * }}
+ */
+function coverageScore(cwd, fileEntries, config) {
+  const fs   = require('fs');
+  const path = require('path');
+
+  const srcDirs = (config && Array.isArray(config.srcDirs) && config.srcDirs.length > 0)
+    ? config.srcDirs
+    : ['src', 'app', 'lib'];
+
+  const excludeSet = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+    '.next', 'coverage', 'target', 'vendor', '.context',
+  ]);
+  if (config && Array.isArray(config.exclude)) {
+    for (const x of config.exclude) excludeSet.add(String(x));
+  }
+
+  const includedSet = new Set((fileEntries || []).map(f => f.filePath));
+
+  // Walk all source files from srcDirs
+  const allSource = [];
+  for (const relDir of srcDirs) {
+    const absDir = path.resolve(cwd, relDir);
+    if (fs.existsSync(absDir)) _walk(absDir, excludeSet, allSource);
+  }
+
+  const total    = allSource.length;
+  const included = allSource.filter(f => includedSet.has(f)).length;
+  const dropped  = total - included;
+  const pct      = total > 0 ? Math.round((included / total) * 100) : 100;
+
+  const grade = pct >= 90 ? 'A' : pct >= 75 ? 'B' : pct >= 50 ? 'C' : 'D';
+  const confidence = pct >= 90 ? 'HIGH' : pct >= 70 ? 'MEDIUM' : 'LOW';
+
+  // Per-module breakdown (one entry per srcDir)
+  const perModule = new Map();
+  for (const relDir of srcDirs) {
+    const absDir   = path.resolve(cwd, relDir);
+    const modFiles = allSource.filter(f => f.startsWith(absDir + path.sep) || f === absDir);
+    const modIncl  = modFiles.filter(f => includedSet.has(f)).length;
+    const modPct   = modFiles.length > 0 ? Math.round((modIncl / modFiles.length) * 100) : 100;
+    perModule.set(relDir, { total: modFiles.length, included: modIncl, pct: modPct });
+  }
+
+  return { score: pct, grade, total, included, dropped, confidence, perModule };
+}
+
+function _walk(dir, excludeSet, out) {
+  const fs   = require('fs');
+  const path = require('path');
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+  for (const e of entries) {
+    if (excludeSet.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) { _walk(full, excludeSet, out); }
+    else if (e.isFile())  { out.push(full); }
+  }
+}
+
+module.exports = { coverageScore };

package/src/eval/analyzer.js

@@ -147,6 +147,9 @@ function analyzeFiles(files, cwd, opts) {
     const tokens   = tokenCount(sigs);
     const covered  = hasCoverage(filePath, cwd);
     const isSlow   = slow && elapsedMs > slowMs;
+    // v4.0: signal quality = sigs per line-of-code (higher = more informative to LLMs)
+    const linesOfCode    = content.split('\n').length;
+    const signalQuality  = linesOfCode > 0 ? parseFloat((sigs.length / linesOfCode).toFixed(4)) : 0;
 
     stats.push({
       file:          rel,
@@ -154,6 +157,8 @@ function analyzeFiles(files, cwd, opts) {
       sigs:          sigs.length,
       tokens,
       covered,
+      linesOfCode,
+      signalQuality,
       elapsedMs:     slow ? elapsedMs : undefined,
       slow:          slow ? isSlow : undefined,
     });

package/src/mcp/server.js

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