sigmap 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -10,7 +10,68 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
-## [3.2.0] — Planned — Phase A: Cross-Platform Standalone Binaries
+## [3.3.0] — 2026-04-08 — Context-Aware CLI & Command Switcher
+
+### Added
+- **Context-aware `--help` output** — `gen-context.js` and `gen-project-map.js` now detect how they were invoked and show the matching command in every usage example:
+  - `npx sigmap --help` shows `npx sigmap <flag>`
+  - `sigmap --help` shows `sigmap <flag>`
+  - `gen-context --help` shows `gen-context <flag>`
+  - `node gen-context.js --help` shows `node gen-context.js <flag>` (unchanged for local users)
+  - Detection uses `process.argv[1]` path analysis (npx cache path, basename without `.js`, fallback)
+- **`docs/cli.html` command picker** — four-tab switcher ("How you run it:") above the flags reference terminal updates every code block on the page (all `.tw` spans and `.term-title` bars) to the selected invocation style. Applies equally to `gen-project-map` references. Selection is saved in `localStorage` and restored on next visit.
+- **`docs/readmes/`** — `vscode-extension.md` and `jetbrains-plugin.md` added for docs site cross-linking
+- **`gen-context.config.json`** — example config committed alongside the repo for reference
+- **Gemini adapter context file** — `.github/gemini-context.md` now generated alongside the copilot instructions file
+- **SEO improvements across all docs pages** — structured data, canonical tags, improved meta descriptions, and `sitemap.xml` updated to v3.3.0
+
+### Added (from `fix/defaults-css-coverage-budget-36` · #38)
+- **`--each` flag — multi-repo parent directory support** · [#37](https://github.com/manojmallick/sigmap/issues/37)
+  - Running `node gen-context.js --each` (or `sigmap --each`) from a parent directory that contains multiple independent git repos now processes each repo in one shot.
+  - Scans immediate subdirectories; a subdirectory qualifies when it contains `.git` or a recognised project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `build.gradle`, `pom.xml`, `requirements.txt`).
+  - Each sub-repo is processed independently: it loads its own `gen-context.config.json` when present, uses its own `srcDirs`, and writes its own context files (`.github/copilot-instructions.md` etc.) inside itself.
+  - Summary printed at the end: `[sigmap] --each: done — 3 succeeded`.
+  - Distinct from `--monorepo` (which processes workspace packages inside a single repo); `--each` targets sibling repos under a shared parent directory.
+
+### Fixed
+- **Default excludes expanded + `changesCommits` corrected** · [#36](https://github.com/manojmallick/sigmap/issues/36)
+  - `changesCommits` default raised from `5` to `10` to match the documented recommended value.
+  - Added `playwright-tmp`, `playwright-report`, `test-results`, `.turbo`, `storybook-static`, `.docusaurus` to the default `exclude` list so they are skipped on modern JS/TS projects without requiring manual config.
+- **CSS extractor: utility-class noise elimination** · [#36](https://github.com/manojmallick/sigmap/issues/36)
+  - Files where ≥70% of top-level selectors are single-word (e.g. Tailwind / compiled utility CSS) are now detected automatically and class extraction is skipped entirely, preventing the output from being flooded with low-signal entries like `.p-4`, `.flex`, `.text-sm`.
+  - For semantic CSS, BEM/hyphenated class names (e.g. `.modal-header`, `.btn-primary`) fill output slots first; single-word names only fill remaining slots up to 8.
+- **`testCoverage` false-positive coverage markers eliminated** · [#36](https://github.com/manojmallick/sigmap/issues/36)
+  - Removed the "all word tokens" pass from `buildTestIndex` that caused common words appearing anywhere in a test file (comments, variable names) to mark unrelated functions as `✓` tested.
+  - Index now only includes tokens extracted from test name strings (`it('...')`, `test('...')`, `describe('...')`) and identifiers directly invoked inside `expect(fn())` / `assert(fn())` calls.
+- **Token budget: mock/fixture files drop before test files** · [#36](https://github.com/manojmallick/sigmap/issues/36)
+  - Added `isMockFile()` helper and priority-9 drop tier in `applyTokenBudget`. Paths matching `mock`, `mocks`, `stub`, `stubs`, `fake`, `fakes`, `demo`, `__mocks__`, `fixtures` or file suffixes like `.mock.ts` now drop before test files (priority 8) and after generated files (priority 10), keeping real production code in context longer.
+  - Fixed `applyTokenBudget` loop direction: generated/mock/test files now drop first (as intended) rather than source files being dropped first.
+- **`--monorepo` now respects configured output adapter** · [#39](https://github.com/manojmallick/sigmap/issues/39)
+  - Removed hardcoded `outputs: ['claude']` override — `--monorepo` now inherits `outputs` from the root config, defaulting to `copilot` (writes `copilot-instructions.md` per package).
+- **IDE command resolution parity (VS Code/Open VSX/JetBrains)** · [#34](https://github.com/manojmallick/sigmap/issues/34)
+  - Unified resolver now checks both `sigmap` and `gen-context` executables with consistent fallback order.
+  - Improved cross-platform probing for local workspace bins, Volta/nvm/npm-global installs, and OS-specific command lookup (`where` on Windows, shell lookup on macOS/Linux).
+  - JetBrains plugin now resolves commands more reliably outside Node-only projects and provides OS-aware install guidance when command lookup fails.
+
+### Changed
+- **Installation guidance for plugin users**
+  - Updated VS Code/Open VSX and JetBrains setup docs to include all supported install paths: npm global, npm local, npx, standalone binaries in PATH, and project-local `gen-context.js`.
+
+---
+
+## [3.2.1] — 2026-04-07 — Patch: IDE Command Resolution & Plugin Parity
+
+### Added
+- **IDE command resolution parity (VS Code / Open VSX / JetBrains)** · [#34](https://github.com/manojmallick/sigmap/issues/34)
+  - Unified resolver checks both `sigmap` and `gen-context` executables with consistent fallback order
+  - Improved cross-platform probing for local workspace bins, Volta/nvm/npm-global installs, and OS-specific command lookup (`where` on Windows, shell lookup on macOS/Linux)
+  - JetBrains plugin resolves commands more reliably outside Node-only projects and provides OS-aware install guidance when command lookup fails
+- **`scripts/sync-versions.mjs`** — one-shot script to bump version across all package manifests and `gen-context.js` in sync
+- **Updated plugin docs** — VS Code/Open VSX and JetBrains setup docs updated with all supported install paths (npm global, npm local, npx, standalone binaries, project-local `gen-context.js`)
+
+---
+
+## [3.2.0] — 2026-04-07 — Cross-Platform Standalone Binaries
 
 ### Added
 - **Standalone binaries** — macOS (arm64 + x64), Linux x64, Windows x64 built via Node.js SEA
@@ -25,7 +86,7 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ### Technical
 - Uses [Node.js SEA](https://nodejs.org/api/single-executable-applications.html) (Node 20 `--experimental-sea-config` + `postject`)
-- `gen-context.js` was updated to include previously-missing `src/` modules (`todos`, `coverage`, `prdiff`) in the SEA bundle; existing `requireSourceOrBundled()` fallback and DEFAULTS fallback in `writeInitConfig()` remain SEA-compatible
+- `gen-context.js` updated to include previously-missing `src/` modules (`todos`, `coverage`, `prdiff`) in the SEA bundle; `requireSourceOrBundled()` fallback remains SEA-compatible
 - Binary builds run natively per OS in GHA (no cross-compilation)
 - `release-attach` job waits for the npm-publish Release to exist before uploading binary assets
 

package/README.md

@@ -117,6 +117,91 @@ Available from any directory on your machine.
 
 </details>
 
+<details>
+<summary><strong>Standalone binaries — no Node.js, no npm</strong></summary>
+
+Download from the latest release:
+
+- <https://github.com/manojmallick/sigmap/releases/latest>
+
+Available assets:
+
+- `sigmap-darwin-arm64` (macOS Apple Silicon)
+- `sigmap-linux-x64` (Linux x64)
+- `sigmap-win32-x64.exe` (Windows x64)
+- `sigmap-checksums.txt` (SHA-256 checksums)
+
+<details>
+<summary><strong>macOS / Linux</strong></summary>
+
+Run directly:
+
+```bash
+chmod +x ./sigmap-darwin-arm64   # or ./sigmap-linux-x64
+./sigmap-darwin-arm64 --help
+./sigmap-darwin-arm64
+```
+
+Make it globally available in Bash/Zsh (no `./` needed):
+
+```bash
+# 1) Pick a user bin dir and move/rename the binary
+mkdir -p "$HOME/.local/bin"
+mv ./sigmap-darwin-arm64 "$HOME/.local/bin/sigmap"   # or sigmap-linux-x64
+chmod +x "$HOME/.local/bin/sigmap"
+
+# 2) Add to PATH in your shell profile
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zshrc"    # zsh
+# echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"  # bash
+
+# 3) Reload shell and verify
+source "$HOME/.zshrc"   # or: source "$HOME/.bashrc"
+sigmap --version
+```
+
+</details>
+
+<details>
+<summary><strong>Windows (PowerShell)</strong></summary>
+
+Run directly:
+
+```powershell
+.\sigmap-win32-x64.exe --help
+.\sigmap-win32-x64.exe
+```
+
+Make it globally available:
+
+```powershell
+# 1) Create a user bin directory and rename the binary
+New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
+Move-Item .\sigmap-win32-x64.exe "$HOME\bin\sigmap.exe"
+
+# 2) Add user bin to PATH (current user)
+[Environment]::SetEnvironmentVariable(
+  "Path",
+  $env:Path + ";$HOME\bin",
+  "User"
+)
+
+# 3) Restart PowerShell and verify
+sigmap --version
+```
+
+</details>
+
+Optional checksum verification:
+
+```bash
+shasum -a 256 sigmap-darwin-arm64
+# Compare with sigmap-checksums.txt
+```
+
+Full guide: [docs/binaries.md](docs/binaries.md)
+
+</details>
+
 <details>
 <summary><strong>npm local — per-project, version-pinned</strong></summary>
 
@@ -466,7 +551,8 @@ node gen-context.js --health --json           Machine-readable health JSON
 node gen-context.js --suggest-tool "<task>"   Recommend model tier for a task
 node gen-context.js --suggest-tool "<task>" --json  Machine-readable tier recommendation
 
-node gen-context.js --monorepo                Per-package context for monorepos
+node gen-context.js --monorepo                Per-package context for monorepos (packages/, apps/, services/)
+node gen-context.js --each                    Process each sub-repo under a parent directory
 node gen-context.js --routing                 Include model routing hints in output
 node gen-context.js --format cache            Write Anthropic prompt-cache JSON
 node gen-context.js --track                   Append run metrics to .context/usage.ndjson

package/gen-context.js

@@ -3700,7 +3700,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '3.2.0',
+    version: '3.2.1',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -5049,7 +5049,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '3.2.0';
+const VERSION = '3.3.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -5251,6 +5251,13 @@ function isGeneratedFile(filePath) {
   return /(\.generated\.|\.pb\.|_pb\.)/.test(filePath);
 }
 
+function isMockFile(filePath) {
+  const p = filePath.replace(/\\/g, '/');
+  return /\/(mock|mocks|stub|stubs|fake|fakes|demo|demos|__mocks__|fixtures)\//i.test(p) ||
+    /\.(mock|stub|fake)\.[jt]sx?$/.test(p) ||
+    /mock\.(ts|js|tsx|jsx)$/.test(p);
+}
+
 function applyTokenBudget(fileEntries, maxTokens) {
   // fileEntries: [{ filePath, sigs, mtime }]
   // Reserve ~10% for formatting overhead (section headers, code fences, top-level header)
@@ -5262,6 +5269,7 @@ function applyTokenBudget(fileEntries, maxTokens) {
   const withPriority = fileEntries.map((e) => {
     let priority = 0;
     if (isGeneratedFile(e.filePath)) priority = 10;
+    else if (isMockFile(e.filePath)) priority = 9;
     else if (isTestFile(e.filePath)) priority = 8;
     else if (isConfigFile(e.filePath)) priority = 6;
     else priority = 4;
@@ -5276,14 +5284,15 @@ function applyTokenBudget(fileEntries, maxTokens) {
 
   const kept = [];
   let dropped = 0;
-  for (let i = withPriority.length - 1; i >= 0; i--) {
-    const entry = withPriority[i];
+  // Iterate forward: highest drop-priority files (generated=10, mock=9, test=8) are at index 0
+  // Drop those first until we're under budget, then keep everything else
+  for (const entry of withPriority) {
     const entryTokens = estimateTokens(entry.sigs.join('\n'));
-    if (total <= effectiveBudget) {
-      kept.unshift(entry);
-    } else {
+    if (total > effectiveBudget) {
       total -= entryTokens;
       dropped++;
+    } else {
+      kept.push(entry);
     }
   }
   if (dropped > 0) {
@@ -6206,11 +6215,10 @@ function runMonorepo(cwd, config) {
   for (const pkgPath of packages) {
     const pkgName = path.relative(cwd, pkgPath);
     console.warn(`[sigmap] monorepo: processing ${pkgName}`);
-    // Per-package config: scan src/ and package root, write CLAUDE.md per package
+    // Per-package config: scan src/ and package root, inherit outputs from parent config
     const pkgConfig = {
       ...config,
       srcDirs: ['src', 'lib', 'app', '.'],
-      outputs: ['claude'],
     };
     try {
       runGenerate(pkgPath, pkgConfig, false);
@@ -6218,7 +6226,66 @@ function runMonorepo(cwd, config) {
       console.warn(`[sigmap] monorepo: failed for ${pkgName}: ${err.message}`);
     }
   }
-  console.warn(`[sigmap] monorepo: wrote CLAUDE.md for ${packages.length} packages`);
+  console.warn(`[sigmap] monorepo: done — wrote context files for ${packages.length} packages`);
+}
+
+// ---------------------------------------------------------------------------
+// Multi-repo support  (--each)
+// Run sigmap independently for every immediate subdirectory that looks like
+// an independent git repo or project root.  Each sub-repo gets its own
+// context files written inside it, using its own gen-context.config.json
+// when present.
+// ---------------------------------------------------------------------------
+function detectRepoDirs(cwd) {
+  let entries;
+  try {
+    entries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+  const repos = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+    const abs = path.join(cwd, entry.name);
+    // A directory qualifies if it has its own .git folder
+    // OR contains a recognised project manifest (fallback for un-initialised repos)
+    const hasGit = fs.existsSync(path.join(abs, '.git'));
+    const hasManifest = PKG_MANIFESTS.some((m) => fs.existsSync(path.join(abs, m)));
+    if (hasGit || hasManifest) repos.push(abs);
+  }
+  return repos;
+}
+
+function runEach(cwd, baseConfig) {
+  const repos = detectRepoDirs(cwd);
+  if (repos.length === 0) {
+    console.warn('[sigmap] --each: no project subdirectories found');
+    console.warn('[sigmap]   A subdirectory qualifies when it contains .git or a package manifest');
+    console.warn(`[sigmap]   (package.json / pyproject.toml / Cargo.toml / go.mod / etc.)`);
+    return;
+  }
+  console.warn(`[sigmap] --each: found ${repos.length} repos — ${repos.map((r) => path.basename(r)).join(', ')}`);
+  let ok = 0, failed = 0;
+  for (const repoDir of repos) {
+    const name = path.basename(repoDir);
+    // Load each repo's own config independently, fall back to base config
+    let repoConfig;
+    try {
+      repoConfig = loadConfig(repoDir);
+    } catch (_) {
+      repoConfig = { ...baseConfig };
+    }
+    console.warn(`[sigmap] --each: processing ${name} …`);
+    try {
+      runGenerate(repoDir, repoConfig, false);
+      ok++;
+    } catch (err) {
+      console.warn(`[sigmap] --each: FAILED for ${name}: ${err.message}`);
+      failed++;
+    }
+  }
+  console.warn(`[sigmap] --each: done — ${ok} succeeded${failed > 0 ? `, ${failed} failed` : ''}`);
 }
 
 // ---------------------------------------------------------------------------
@@ -6272,50 +6339,71 @@ function resolveProjectRoot(startDir) {
   return startDir;
 }
 
-function printHelp() {
+function detectInvokedAs() {
+  const argv1 = process.argv[1] || '';
+  const base = path.basename(argv1);
+  const baseNoExt = base.endsWith('.js') ? base.slice(0, -3) : base;
+  // npx: the script path goes through an _npx cache directory
+  if (argv1.includes('/_npx/') || argv1.includes('\\_npx\\') ||
+      argv1.includes('/.npm/_') || argv1.includes('\\.npm\\_')) {
+    return 'npx sigmap';
+  }
+  // globally-installed bin aliases (no .js extension)
+  if (baseNoExt === 'sigmap') return 'sigmap';
+  if (baseNoExt === 'gen-context') return 'gen-context';
+  // default: local file invocation
+  return 'node gen-context.js';
+}
+
+function printHelp(cmd) {
+  cmd = cmd || 'node gen-context.js';
+  const header = cmd === 'node gen-context.js'
+    ? `SigMap — gen-context.js v${VERSION}`
+    : `SigMap v${VERSION}  (${cmd})`;
   console.log(`
-SigMap — gen-context.js v${VERSION}
+${header}
 Zero-dependency AI context engine
 
 Usage:
-  node gen-context.js                                   Generate context once and exit
-  node gen-context.js --monorepo                        Generate per-package context (monorepo)
-  node gen-context.js --routing                         Include model routing hints in output
-  node gen-context.js --format cache                    Also write Anthropic prompt-cache JSON
-  node gen-context.js --track                           Append run metrics to .context/usage.ndjson
-  node gen-context.js --watch                           Generate + watch for file changes
-  node gen-context.js --setup                           Generate + install git hook + watch
-  node gen-context.js --mcp                             Start MCP server on stdio
-  node gen-context.js --report                          Token reduction stats to stdout
-  node gen-context.js --report --json                   Token report as JSON (for CI; exits 1 if over budget)
-  node gen-context.js --report --history                Print usage log summary from .context/usage.ndjson
-  node gen-context.js --report --history --chart        Include inline SVG charts + Unicode sparklines
-  node gen-context.js --dashboard                       Write benchmarks/reports/dashboard.html
-  node gen-context.js --suggest-tool "<task>"           Recommend model tier for a task description
-  node gen-context.js --suggest-tool "<task>" --json    Machine-readable tier recommendation
-  node gen-context.js --health                          Print composite health score
-  node gen-context.js --health --json                   Machine-readable health score
-  node gen-context.js --diff                            Generate context for git-changed files only
-  node gen-context.js --diff <base-ref>                 Generate context + structural diff vs base ref (e.g. main)
-  node gen-context.js --diff --staged                   Generate context for staged files only
-  node gen-context.js --benchmark                       Run retrieval benchmark (benchmarks/tasks/retrieval.jsonl)
-  node gen-context.js --adapter <name>                  Generate for a specific adapter only (v3.0+)
-  node gen-context.js --adapter <name> --json           Show adapter output path as JSON
-  node gen-context.js --benchmark --json                Benchmark results as JSON
-  node gen-context.js --eval                            Alias for --benchmark
-  node gen-context.js --analyze                         Per-file breakdown: sigs, tokens, extractor, coverage
-  node gen-context.js --analyze --json                  Breakdown as JSON
-  node gen-context.js --analyze --slow                  Re-time each extractor; flag files >50ms
-  node gen-context.js --diagnose-extractors             Run all 21 extractors vs fixtures; show pass/fail + diff
-  node gen-context.js --query "<text>"                  Rank files by relevance to a query
-  node gen-context.js --query "<text>" --json           Ranked results as JSON
-  node gen-context.js --query "<text>" --top <n>        Limit results to top N files (default 10)
-  node gen-context.js --impact <file>                   Show every file impacted by changing <file>
-  node gen-context.js --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
-  node gen-context.js --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
-  node gen-context.js --init                            Write example config + .contextignore scaffold
-  node gen-context.js --help                            Show this message
-  node gen-context.js --version                         Show version
+  ${cmd}                                   Generate context once and exit
+  ${cmd} --monorepo                        Generate per-package context (monorepo)
+  ${cmd} --each                            Run for every repo in the current directory
+  ${cmd} --routing                         Include model routing hints in output
+  ${cmd} --format cache                    Also write Anthropic prompt-cache JSON
+  ${cmd} --track                           Append run metrics to .context/usage.ndjson
+  ${cmd} --watch                           Generate + watch for file changes
+  ${cmd} --setup                           Generate + install git hook + watch
+  ${cmd} --mcp                             Start MCP server on stdio
+  ${cmd} --report                          Token reduction stats to stdout
+  ${cmd} --report --json                   Token report as JSON (for CI; exits 1 if over budget)
+  ${cmd} --report --history                Print usage log summary from .context/usage.ndjson
+  ${cmd} --report --history --chart        Include inline SVG charts + Unicode sparklines
+  ${cmd} --dashboard                       Write benchmarks/reports/dashboard.html
+  ${cmd} --suggest-tool "<task>"           Recommend model tier for a task description
+  ${cmd} --suggest-tool "<task>" --json    Machine-readable tier recommendation
+  ${cmd} --health                          Print composite health score
+  ${cmd} --health --json                   Machine-readable health score
+  ${cmd} --diff                            Generate context for git-changed files only
+  ${cmd} --diff <base-ref>                 Generate context + structural diff vs base ref (e.g. main)
+  ${cmd} --diff --staged                   Generate context for staged files only
+  ${cmd} --benchmark                       Run retrieval benchmark (benchmarks/tasks/retrieval.jsonl)
+  ${cmd} --adapter <name>                  Generate for a specific adapter only (v3.0+)
+  ${cmd} --adapter <name> --json           Show adapter output path as JSON
+  ${cmd} --benchmark --json                Benchmark results as JSON
+  ${cmd} --eval                            Alias for --benchmark
+  ${cmd} --analyze                         Per-file breakdown: sigs, tokens, extractor, coverage
+  ${cmd} --analyze --json                  Breakdown as JSON
+  ${cmd} --analyze --slow                  Re-time each extractor; flag files >50ms
+  ${cmd} --diagnose-extractors             Run all 21 extractors vs fixtures; show pass/fail + diff
+  ${cmd} --query "<text>"                  Rank files by relevance to a query
+  ${cmd} --query "<text>" --json           Ranked results as JSON
+  ${cmd} --query "<text>" --top <n>        Limit results to top N files (default 10)
+  ${cmd} --impact <file>                   Show every file impacted by changing <file>
+  ${cmd} --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
+  ${cmd} --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
+  ${cmd} --init                            Write example config + .contextignore scaffold
+  ${cmd} --help                            Show this message
+  ${cmd} --version                         Show version
 
 Strategies (set via config "strategy" key):
   "full"        Single file, all signatures. Works everywhere. (default)
@@ -6380,7 +6468,7 @@ function main() {
   }
 
   if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
+    printHelp(detectInvokedAs());
     process.exit(0);
   }
 
@@ -6779,6 +6867,11 @@ function main() {
     process.exit(0);
   }
 
+  if (args.includes('--each')) {
+    runEach(cwd, config);
+    process.exit(0);
+  }
+
   if (args.includes('--setup')) {
     runGenerate(cwd, config, false);
     installHook(cwd, scriptPath);

package/gen-project-map.js

@@ -24,19 +24,32 @@ const OUTPUT_FILE = 'PROJECT_MAP.md';
 // ---------------------------------------------------------------------------
 const args = process.argv.slice(2);
 
+function detectInvokedAs() {
+  const argv1 = process.argv[1] || '';
+  const base = path.basename(argv1);
+  const baseNoExt = base.endsWith('.js') ? base.slice(0, -3) : base;
+  if (argv1.includes('/_npx/') || argv1.includes('\\_npx\\') ||
+      argv1.includes('/.npm/_') || argv1.includes('\\.npm\\_')) {
+    return 'npx gen-project-map';
+  }
+  if (baseNoExt === 'gen-project-map') return 'gen-project-map';
+  return 'node gen-project-map.js';
+}
+
 if (args.includes('--version')) {
   console.log(`gen-project-map.js v${VERSION}`);
   process.exit(0);
 }
 
 if (args.includes('--help')) {
+  const cmd = detectInvokedAs();
   console.log([
-    `gen-project-map.js v${VERSION} — SigMap project map generator`,
+    `SigMap project map generator v${VERSION}  (${cmd})`,
     '',
     'Usage:',
-    '  node gen-project-map.js           Generate PROJECT_MAP.md',
-    '  node gen-project-map.js --version Print version and exit',
-    '  node gen-project-map.js --help    Print this message',
+    `  ${cmd}           Generate PROJECT_MAP.md`,
+    `  ${cmd} --version Print version and exit`,
+    `  ${cmd} --help    Print this message`,
     '',
     'Configuration: gen-context.config.json (same file as gen-context.js)',
     '  srcDirs  — directories to scan  (default: ["src","app","lib",...])',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {
@@ -27,7 +27,8 @@
     "map": "node gen-project-map.js",
     "mcp": "node gen-context.js --mcp",
     "build:binary": "node scripts/build-binary.mjs",
-    "verify:binary": "node scripts/verify-binary.mjs"
+    "verify:binary": "node scripts/verify-binary.mjs",
+    "version:sync": "node scripts/sync-versions.mjs"
   },
   "files": [
     "gen-context.js",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "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.1.0",
+  "version": "3.3.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/config/defaults.js

@@ -29,6 +29,12 @@ const DEFAULTS = {
     'node_modules', '.git', 'dist', 'build', 'out',
     '__pycache__', '.next', 'coverage', 'target', 'vendor',
     '.context',
+    // CI/test artifacts
+    'playwright-tmp', 'playwright-report', 'test-results',
+    // build/monorepo caches
+    '.turbo',
+    // documentation build output
+    'storybook-static', '.docusaurus',
   ],
 
   // Maximum directory depth to recurse
@@ -86,7 +92,7 @@ const DEFAULTS = {
   changes: true,
 
   // Number of commits used for changes section
-  changesCommits: 5,
+  changesCommits: 10,
 
   // Add test coverage markers to extracted function signatures (opt-in)
   testCoverage: false,

package/src/extractors/coverage.js

@@ -34,12 +34,26 @@ function buildTestIndex(cwd, testDirs) {
         continue;
       }
 
-      for (const m of src.matchAll(/\b(?:test_|it\(|test\(|describe\()\s*['"`]?([\w_]+)/g)) {
-        if (m[1] && m[1].length >= 3) names.add(m[1].toLowerCase());
+      // Extract tokens from JS/TS test name strings (it/test/describe calls)
+      for (const m of src.matchAll(/\b(?:it|test|describe)\s*\(\s*['"\`]([\w_ ]+)['"\`]/g)) {
+        if (!m[1]) continue;
+        const full = m[1].replace(/[\s_]+/g, '_').toLowerCase();
+        names.add(full); // also keep whole phrase: "validate_user"
+        for (const word of m[1].split(/[\s_]+/)) {
+          if (word.length >= 3) names.add(word.toLowerCase());
+        }
       }
-
-      for (const m of src.matchAll(/\b([a-zA-Z_][a-zA-Z0-9_]*)\b/g)) {
-        if (m[1] && m[1].length >= 4) names.add(m[1].toLowerCase());
+      // Python/Ruby style: def test_funcname() / def test_funcname: → index the suffix
+      for (const m of src.matchAll(/\bdef\s+test_([\w]+)\s*[(:]/g)) {
+        if (!m[1]) continue;
+        names.add(m[1].toLowerCase()); // full suffix: "validate_user"
+        for (const word of m[1].split('_')) {
+          if (word.length >= 3) names.add(word.toLowerCase());
+        }
+      }
+      // Also capture identifiers directly invoked in expect/assert calls
+      for (const m of src.matchAll(/\b(?:expect|assert)\s*\(\s*(?:await\s+)?([\w]+)\s*\(/g)) {
+        if (m[1] && m[1].length >= 3) names.add(m[1].toLowerCase());
       }
     }
   }
@@ -50,7 +64,15 @@ function buildTestIndex(cwd, testDirs) {
 function isTested(funcName, testIndex) {
   if (!funcName || funcName.length < 3 || !testIndex || testIndex.size === 0) return false;
   const lower = funcName.toLowerCase();
+  // Direct match or test_ prefix match
   if (testIndex.has(lower) || testIndex.has(`test_${lower}`)) return true;
+  // Token-level match: split camelCase and snake_case, check if all meaningful tokens are covered
+  const tokens = funcName
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .split(/[_\s]+/)
+    .filter(t => t.length >= 3);
+  if (tokens.length >= 2 && tokens.every(t => testIndex.has(t))) return true;
   return false;
 }
 

package/src/extractors/css.js

@@ -37,13 +37,31 @@ function extract(src) {
     sigs.push(`@function ${m[1]}(${m[2].trim()})`);
   }
 
-  // Key class names (top-level)
-  const classNames = new Set();
-  for (const m of stripped.matchAll(/^\.([\w-]+)(?=[^{]*\{)/gm)) {
-    classNames.add(m[1]);
-    if (classNames.size >= 10) break;
+  // Key class names (top-level) — prefer hyphenated BEM/component names over utilities
+  const allClassMatches = [...stripped.matchAll(/^\.([\w-]+)(?=[^{]*\{)/gm)];
+  // Utility-class detection: classes are "utility-like" if they have no hyphen (e.g. .flex)
+  // OR match Tailwind patterns: -digit suffix (.p-4, .bg-blue-500) or common size abbreviations
+  // (.text-sm, .py-lg). Files where ≥70% of selectors are utility-like are skipped to avoid noise.
+  function looksLikeUtility(name) {
+    if (!name.includes('-')) return true;
+    if (/-\d/.test(name)) return true;
+    if (/-(?:sm|md|lg|xl|xs|2xl|3xl|px|py|full|auto|none|screen)$/.test(name)) return true;
+    return false;
+  }
+  const utilityCount = allClassMatches.filter(m => looksLikeUtility(m[1])).length;
+  const isUtilityFile = allClassMatches.length >= 5 && (utilityCount / allClassMatches.length) >= 0.70;
+  if (!isUtilityFile) {
+    const hyphenated = [];
+    const singleWord = [];
+    for (const m of allClassMatches) {
+      if (m[1].includes('__') || m[1].includes('--')) hyphenated.push(m[1]); // BEM names first
+      else if (m[1].includes('-')) hyphenated.push(m[1]); // other hyphenated component names
+      else singleWord.push(m[1]);
+    }
+    // Up to 8 slots: hyphenated classes (semantic) first, then single-word to fill remaining
+    const selected = [...hyphenated, ...singleWord].slice(0, 8);
+    for (const name of selected) sigs.push(`.${name}`);
   }
-  for (const name of classNames) sigs.push(`.${name}`);
 
   return sigs.slice(0, 25);
 }

package/src/mcp/server.js

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