sigmap 4.1.1 → 4.1.2

package/CHANGELOG.md

@@ -10,6 +10,46 @@ 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

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

@@ -5479,8 +5479,19 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return index;
   }
   function buildSigIndex(cwd, opts) {
-    const path = require('path');
+    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);
@@ -6238,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) {
@@ -6926,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);
@@ -7507,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 {
@@ -7931,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
@@ -8355,19 +8431,28 @@ function main() {
       }
       const { rank, buildSigIndex, formatRankTable, formatRankJSON } = requireSourceOrBundled('./src/retrieval/ranker');
 
-      // Resolve an explicit context file path when --adapter is present.
-      // This lets `--adapter claude --query "..."` read CLAUDE.md instead of
-      // falling through to the default copilot-instructions.md probe.
+      // 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;
-      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 (_) {}
+
+      // 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 (_) {}
+          }
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "4.1.1",
+  "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

@@ -206,26 +206,39 @@ function _parseContextFile(contextPath) {
  * Returns Map<filePath, string[]> where filePath is the relative path
  * as it appears in the ### headers of the context file.
  *
- * When `opts.contextPath` is provided, that specific file is used.
- * This is the case when the caller already knows the path (e.g. via
- * --adapter <name> or --output <file>).
- *
- * Otherwise all known adapter output paths are probed in order and the
- * first file that produces a non-empty index is returned.
+ * 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');
 
-  // Caller supplied an explicit path — use it directly.
+  // 1. Caller supplied an explicit path — use it directly.
   if (opts && opts.contextPath) {
     return _parseContextFile(opts.contextPath);
   }
 
-  // Probe all known adapter output paths; return first non-empty index.
+  // 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);