sigmap 4.1.0 → 4.1.2

package/CHANGELOG.md

@@ -10,6 +10,91 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [4.1.2] — 2026-04-16 — Feat: --output <file> flag for custom context path
+
+### Added
+
+- **`--output <file>` flag** — write signatures to any custom path, not just
+  an adapter's fixed location:
+  ```bash
+  sigmap --output .context/ai-context.md          # default generation
+  sigmap --adapter claude --output shared/sigs.md # adapter + custom path
+  ```
+  The custom file is written **in addition to** the adapter's default output so
+  existing tooling is unaffected.
+
+- **Automatic discovery for `--query`** — the resolved path is persisted to
+  `gen-context.config.json` as `customOutput` so subsequent `--query` runs
+  find it automatically without needing to pass `--output` again:
+  ```bash
+  sigmap --output .context/ai-context.md          # generates + persists path
+  sigmap --query "add a new extractor"             # auto-finds .context/ai-context.md
+  ```
+
+- **Priority order for `--query` context resolution** (most specific first):
+  1. `--output <file>` flag — explicit path
+  2. `--adapter <name>` flag — adapter's fixed output path
+  3. `customOutput` in `gen-context.config.json` — persisted from last `--output` run
+  4. Probe all known adapter output paths — existing fallback behaviour
+
+- **Nested directories created automatically** — `--output a/b/c/file.md`
+  creates any missing parent directories.
+
+### Tests
+
+- Added `test/integration/output-flag.test.js` (13 tests) covering: custom
+  file creation, parseable headers, config persistence, nested dirs, missing
+  arg error, `--adapter` + `--output` combo, explicit `--query` with `--output`,
+  auto-discovery via persisted config, missing-file error, `--output` overrides
+  `--adapter` during `--query`.
+
+---
+
+## [4.1.1] — 2026-04-16 — Fix: --query works with any adapter output
+
+### Fixed
+
+- **`--query` fails after `--adapter` generation** (`[sigmap] no context file found`):  
+  `buildSigIndex` hardcoded `.github/copilot-instructions.md` as the only
+  context file path, so `--query` always failed when any adapter other than
+  `copilot` wrote to a different location (`CLAUDE.md`, `AGENTS.md`,
+  `.cursorrules`, `.windsurfrules`, etc.).
+
+  `buildSigIndex` now probes all nine known adapter output paths in priority
+  order and returns the first non-empty index:
+  ```
+  copilot → claude → codex → cursor → windsurf → openai → gemini → llm-full → llm
+  ```
+  Human-written preamble before the `## Auto-generated signatures` marker
+  (e.g. custom content in `CLAUDE.md`) is skipped so those `###` sections
+  don't pollute the signature index.
+
+- **`--adapter <name> --query "..."` combination ignored the adapter flag**:  
+  The `--query` handler now detects a co-present `--adapter` flag, resolves
+  that adapter's output path, and reads from it directly — so both forms work:
+  ```bash
+  # generate with claude adapter, then query without re-specifying adapter
+  node gen-context.js --adapter claude
+  node gen-context.js --query "add a new extractor"
+
+  # or pin explicitly in one command
+  node gen-context.js --adapter claude --query "add a new extractor"
+  ```
+
+- **`--analyze --json` output truncated at ~8 KB on macOS**:  
+  Calling `process.exit(0)` immediately after `process.stdout.write(largeJson)`
+  truncated output because the underlying pipe write is asynchronous even
+  when `write()` returns `true`. Fixed by using the write callback so the
+  process exits only after the OS has accepted all bytes.
+
+### Tests
+
+- Added `test/integration/query-adapter.test.js` (17 tests) covering every
+  adapter output path (unit + CLI), probe order, marker-skipping, explicit
+  `opts.contextPath` override, and empty-project fallback.
+
+---
+
 ## [4.1.0] — 2026-04-15 — Smart Budget: auto-scaling token budget
 
 ### Added

package/README.md

@@ -353,6 +353,24 @@ Configure multiple adapters at once in `gen-context.config.json`:
 
 Use SigMap as a Node.js library without spawning a subprocess. See the [full API reference](#-programmatic-api) below.
 
+### Custom output path
+
+Write signatures to any file location — useful for shared docs folders, monorepos,
+or tooling that expects context at a non-standard path:
+
+```bash
+sigmap --output .context/ai-context.md           # write to custom path
+sigmap --adapter claude --output shared/sigs.md  # adapter + custom path
+```
+
+The path is persisted to `gen-context.config.json`, so `--query` finds it
+automatically on subsequent runs — no need to pass `--output` again:
+
+```bash
+sigmap --output .context/ai-context.md  # generates and saves the path
+sigmap --query "add an extractor"        # auto-discovers .context/ai-context.md
+```
+
 ### Query-aware retrieval
 
 Find the most relevant files for any task without reading the whole codebase:
@@ -361,6 +379,7 @@ Find the most relevant files for any task without reading the whole codebase:
 sigmap --query "authentication middleware"   # ranked file list
 sigmap --query "auth" --json                 # machine-readable output
 sigmap --query "auth" --top 5               # top 5 results only
+sigmap --query "auth" --adapter claude       # query against CLAUDE.md specifically
 ```
 
 ### Diagnostic and evaluation tools
@@ -616,9 +635,14 @@ sigmap --diff                                 Generate context for git-changed f
 sigmap --diff --staged                        Staged files only (pre-commit check)
 sigmap --mcp                                  Start MCP server on stdio
 
+sigmap --output <file>                        Write signatures to a custom path (persists for --query)
+sigmap --output <file> --adapter <name>       Adapter output + custom copy
+
 sigmap --query "<text>"                       Rank files by relevance to a query
 sigmap --query "<text>" --json                Ranked results as JSON
 sigmap --query "<text>" --top <n>             Limit results to top N files (default 10)
+sigmap --query "<text>" --adapter <name>      Query against a specific adapter's output file
+sigmap --query "<text>" --output <file>       Query against a specific custom file
 
 sigmap --analyze                              Per-file breakdown (sigs / tokens / extractor / coverage)
 sigmap --analyze --json                       Analysis as JSON

package/gen-context.js

@@ -5449,12 +5449,24 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     scored.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
     return scored.slice(0, topK);
   }
-  function buildSigIndex(cwd) {
-    const fs = require('fs'); const path = require('path');
-    const contextPath = path.join(cwd, '.github', 'copilot-instructions.md');
+  const ADAPTER_OUTPUT_PATHS = [
+    ['.github', 'copilot-instructions.md'],
+    ['CLAUDE.md'],
+    ['AGENTS.md'],
+    ['.cursorrules'],
+    ['.windsurfrules'],
+    ['.github', 'openai-context.md'],
+    ['.github', 'gemini-context.md'],
+    ['llm-full.txt'],
+    ['llm.txt'],
+  ];
+  function _parseContextFile(contextPath) {
+    const fs = require('fs');
     const index = new Map();
     if (!fs.existsSync(contextPath)) return index;
-    const content = fs.readFileSync(contextPath, 'utf8');
+    let content = fs.readFileSync(contextPath, 'utf8');
+    const markerIdx = content.indexOf('## Auto-generated signatures');
+    if (markerIdx !== -1) content = content.slice(markerIdx);
     const lines = content.split('\n');
     let currentFile = null; let inBlock = false; let sigs = [];
     for (const line of lines) {
@@ -5466,6 +5478,27 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     if (currentFile !== null) index.set(currentFile, sigs);
     return index;
   }
+  function buildSigIndex(cwd, opts) {
+    const fs = require('fs'); const path = require('path');
+    if (opts && opts.contextPath) return _parseContextFile(opts.contextPath);
+    // Check gen-context.config.json for a persisted customOutput path.
+    try {
+      const cfgPath = path.join(cwd, 'gen-context.config.json');
+      if (fs.existsSync(cfgPath)) {
+        const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+        if (cfg.customOutput) {
+          const idx = _parseContextFile(path.resolve(cwd, cfg.customOutput));
+          if (idx.size > 0) return idx;
+        }
+      }
+    } catch (_) {}
+    for (const parts of ADAPTER_OUTPUT_PATHS) {
+      const contextPath = path.join(cwd, ...parts);
+      const index = _parseContextFile(contextPath);
+      if (index.size > 0) return index;
+    }
+    return new Map();
+  }
   function formatRankTable(results, query) {
     if (!results || results.length === 0) return `No matching files found for query: "${query}"\n`;
     const lines = [`## Query: ${query}`, '', '| Rank | File | Score | Sigs | Tokens |', '|------|------|-------|------|--------|',
@@ -6216,7 +6249,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '4.1.0';
+const VERSION = '4.1.2';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -6904,6 +6937,19 @@ function writeOutputs(content, targets, cwd, config) {
     if (ADAPTER_TARGETS.has(target)) {
       try {
         const adapterMod = __require('./packages/adapters/' + target);
+        // copilot: honour config.output custom path (redirects away from default .github/copilot-instructions.md)
+        if (target === 'copilot') {
+          const outPath = resolveAdapterPath('copilot', cwd, config);
+          const defaultPath = path.join(cwd, '.github', 'copilot-instructions.md');
+          if (outPath !== defaultPath) {
+            // custom path: format and write directly (no append logic)
+            const formatted = adapterMod.format(content, { version: VERSION });
+            ensureDir(outPath);
+            fs.writeFileSync(outPath, formatted, 'utf8');
+            console.warn(`[sigmap] wrote ${path.relative(cwd, outPath)}`);
+            continue;
+          }
+        }
         if (typeof adapterMod.write === 'function') {
           adapterMod.write(content, cwd, { version: VERSION });
           const outPath = adapterMod.outputPath(cwd);
@@ -7485,6 +7531,25 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
         writeOutputs(content, config.outputs, cwd, config);
       }
       if (formatValue === 'cache') writeCacheOutput(content, cwd);
+
+      // --output <file>: write a copy of the formatted context to the custom path.
+      if (config.customOutput) {
+        try {
+          const absCustom = path.resolve(cwd, config.customOutput);
+          const SIGMAP_HEADER = [
+            `<!-- Generated by SigMap v${VERSION} -->`,
+            `<!-- Updated: ${new Date().toISOString()} -->`,
+            `<!-- Regenerate: node gen-context.js --output ${config.customOutput} -->`,
+            '',
+          ].join('\n');
+          fs.mkdirSync(path.dirname(absCustom), { recursive: true });
+          fs.writeFileSync(absCustom, SIGMAP_HEADER + content, 'utf8');
+          console.warn(`[sigmap] wrote ${path.relative(cwd, absCustom)} (custom output)`);
+        } catch (err) {
+          console.warn(`[sigmap] --output write failed: ${err.message}`);
+        }
+      }
+
       result = { inputTokenTotal, finalTokens, fileCount: beforeCount, droppedCount };
     }
   } else {
@@ -7909,6 +7974,39 @@ function main() {
 
   const config = loadConfig(cwd);
 
+  // ── --output <file> — parse early so every subsequent block can use it ─────
+  // Resolves the custom output path and merges it into config.customOutput.
+  // Also persists the resolved relative path to gen-context.config.json so
+  // future --query calls (without --output) find the file automatically.
+  (function resolveOutputFlag() {
+    const outIdx = args.indexOf('--output');
+    if (outIdx < 0) return;
+    const raw = (args[outIdx + 1] || '').trim();
+    if (!raw || raw.startsWith('--')) {
+      console.error('[sigmap] --output requires a file path');
+      console.error('  Example: node gen-context.js --output .context/ai-context.md');
+      process.exit(1);
+    }
+    const abs  = path.resolve(cwd, raw);
+    const rel  = path.relative(cwd, abs);
+    config.customOutput = rel; // consumed by runGenerate
+
+    // Persist to gen-context.config.json for future --query calls
+    const cfgPath = path.join(cwd, 'gen-context.config.json');
+    try {
+      let savedCfg = {};
+      if (fs.existsSync(cfgPath)) {
+        try { savedCfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); } catch (_) {}
+      }
+      if (savedCfg.customOutput !== rel) {
+        savedCfg.customOutput = rel;
+        fs.writeFileSync(cfgPath, JSON.stringify(savedCfg, null, 2) + '\n', 'utf8');
+      }
+    } catch (err) {
+      console.warn(`[sigmap] could not persist customOutput to config: ${err.message}`);
+    }
+  })();
+
   // Feature 2: `--mode fast|full|both`
   const modeIdx = args.indexOf('--mode');
   const mode = modeIdx !== -1
@@ -8220,7 +8318,13 @@ function main() {
       const stats = analyzeFiles(allFiles, cwd, { slow, maxSigs: cfg.maxSigsPerFile || 25 });
 
       if (args.includes('--json')) {
-        process.stdout.write(JSON.stringify(formatAnalysisJSON(stats)) + '\n');
+        const out = JSON.stringify(formatAnalysisJSON(stats)) + '\n';
+        // Use the write callback to exit only after the OS has accepted all
+        // bytes. Calling process.exit(0) synchronously after write() truncates
+        // large outputs because the underlying pipe write is asynchronous even
+        // when write() returns true.
+        process.stdout.write(out, 'utf8', () => process.exit(0));
+        return; // exit is handled by the callback above
       } else {
         const table = formatAnalysisTable(stats, slow);
         process.stdout.write(table);
@@ -8326,9 +8430,38 @@ function main() {
         process.exit(1);
       }
       const { rank, buildSigIndex, formatRankTable, formatRankJSON } = requireSourceOrBundled('./src/retrieval/ranker');
-      const index = buildSigIndex(cwd);
+
+      // Resolve the context file path to query against.
+      // Priority: --output flag > --adapter flag > buildSigIndex probe order
+      //   (customOutput from config is handled inside buildSigIndex itself)
+      let queryOpts;
+
+      // 1. --output <file> pins to an explicit path
+      if (config.customOutput) {
+        queryOpts = { contextPath: path.resolve(cwd, config.customOutput) };
+      }
+
+      // 2. --adapter <name> pins to that adapter's output path (if --output not given)
+      if (!queryOpts) {
+        const adpIdx = args.indexOf('--adapter');
+        if (adpIdx >= 0) {
+          const adapterName = (args[adpIdx + 1] || '').trim().toLowerCase();
+          const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
+          if (VALID_ADAPTERS.includes(adapterName)) {
+            try {
+              const adapterMod = __require('./packages/adapters/' + adapterName);
+              queryOpts = { contextPath: adapterMod.outputPath(cwd) };
+            } catch (_) {}
+          }
+        }
+      }
+
+      const index = buildSigIndex(cwd, queryOpts);
       if (index.size === 0) {
         console.error('[sigmap] no context file found. Run: node gen-context.js');
+        if (adpIdx >= 0) {
+          console.error('  (tried the path for --adapter ' + (args[adpIdx + 1] || '') + ')');
+        }
         process.exit(1);
       }
       const topIdx = args.indexOf('--top');

package/package.json

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

package/src/retrieval/ranker.js

@@ -141,24 +141,45 @@ function rank(query, sigIndex, opts) {
 }
 
 /**
- * Build a signature index from the generated context file.
- * Returns Map<filePath, string[]> where filePath is the relative path
- * as it appears in the ### headers of copilot-instructions.md.
+ * All paths where sigmap adapters write their context files, in probe order.
+ * The first existing file with a non-empty index wins when no explicit path
+ * is supplied.
+ */
+const ADAPTER_OUTPUT_PATHS = [
+  ['.github', 'copilot-instructions.md'], // copilot (default)
+  ['CLAUDE.md'],                           // claude
+  ['AGENTS.md'],                           // codex
+  ['.cursorrules'],                        // cursor
+  ['.windsurfrules'],                      // windsurf
+  ['.github', 'openai-context.md'],        // openai
+  ['.github', 'gemini-context.md'],        // gemini
+  ['llm-full.txt'],                        // llm-full
+  ['llm.txt'],                             // llm
+];
+
+/**
+ * Parse a single context file into a Map<filePath, string[]>.
  *
- * @param {string} cwd
+ * Files that contain human-written content before an
+ * "## Auto-generated signatures" marker (e.g. CLAUDE.md) are handled
+ * by skipping everything above the marker before scanning for ### headers.
+ *
+ * @param {string} contextPath  - absolute path to the context file
  * @returns {Map<string, string[]>}
  */
-function buildSigIndex(cwd) {
-  const fs   = require('fs');
-  const path = require('path');
-  const contextPath = path.join(cwd, '.github', 'copilot-instructions.md');
+function _parseContextFile(contextPath) {
+  const fs = require('fs');
   const index = new Map();
 
   if (!fs.existsSync(contextPath)) return index;
 
-  const content = fs.readFileSync(contextPath, 'utf8');
-  const lines = content.split('\n');
+  let content = fs.readFileSync(contextPath, 'utf8');
 
+  // Skip any human-written preamble that sits above the auto-generated block.
+  const markerIdx = content.indexOf('## Auto-generated signatures');
+  if (markerIdx !== -1) content = content.slice(markerIdx);
+
+  const lines = content.split('\n');
   let currentFile = null;
   let inBlock = false;
   let sigs = [];
@@ -180,6 +201,53 @@ function buildSigIndex(cwd) {
   return index;
 }
 
+/**
+ * Build a signature index from the generated context file.
+ * Returns Map<filePath, string[]> where filePath is the relative path
+ * as it appears in the ### headers of the context file.
+ *
+ * Resolution priority:
+ *  1. `opts.contextPath` — explicit path from --output or --adapter flag
+ *  2. `customOutput` key in gen-context.config.json — persisted from a
+ *     previous `--output <file>` generation run
+ *  3. All known adapter output paths probed in order (first non-empty wins)
+ *
+ * @param {string} cwd
+ * @param {{ contextPath?: string }} [opts]
+ * @returns {Map<string, string[]>}
+ */
+function buildSigIndex(cwd, opts) {
+  const fs   = require('fs');
+  const path = require('path');
+
+  // 1. Caller supplied an explicit path — use it directly.
+  if (opts && opts.contextPath) {
+    return _parseContextFile(opts.contextPath);
+  }
+
+  // 2. Check gen-context.config.json for a persisted customOutput path.
+  try {
+    const cfgPath = path.join(cwd, 'gen-context.config.json');
+    if (fs.existsSync(cfgPath)) {
+      const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      if (cfg.customOutput) {
+        const customPath = path.resolve(cwd, cfg.customOutput);
+        const index = _parseContextFile(customPath);
+        if (index.size > 0) return index;
+      }
+    }
+  } catch (_) {}
+
+  // 3. Probe all known adapter output paths; return first non-empty index.
+  for (const parts of ADAPTER_OUTPUT_PATHS) {
+    const contextPath = path.join(cwd, ...parts);
+    const index = _parseContextFile(contextPath);
+    if (index.size > 0) return index;
+  }
+
+  return new Map();
+}
+
 /**
  * Format ranked results as a markdown table string.
  *