@applesnort/crosscheck 0.2.0 → 0.2.2

package/README.md

@@ -19,7 +19,38 @@ or your own wrapper. crosscheck owns prompt construction, routing, fan-out, dedu
 and output; you own the model. `--dry-run` prints the roster and prompts without
 spawning anything.
 
-No dependencies, no install step, 153 tests.
+No dependencies, no install step, 183 tests.
+
+## Configuration
+
+Retyping `--exec` on every run pushes people toward shell aliases nobody else on
+the team can see. Commit a `.crosscheckrc.json` instead:
+
+```json
+{
+  "exec": "claude -p",
+  "concurrency": 2,
+  "skip": ["ux"],
+  "sarif": "panel.sarif"
+}
+```
+
+Then the whole command is:
+
+```bash
+npx @applesnort/crosscheck run src/
+```
+
+The nearest config is used, searching upward from the working directory and
+stopping at a repo root, so running from a subdirectory still picks up the
+project's settings. The loaded path is printed on every run — a run silently
+reshaped by a forgotten file is the kind of thing this tool refuses everywhere
+else. Command-line flags override the file, `--config <file>` points elsewhere,
+and an unrecognised key is an error rather than a silent no-op, because a
+misspelled `exec` that quietly does nothing is worse than a crash.
+
+Accepted keys: `exec`, `lenses`, `concurrency`, `only`, `skip`, `mixed`, `out`,
+`sarif`, `baseline`, `overlap`. Keys beginning `//` are treated as comments.
 
 > **v0.x — the API is unstable.** The CLI commands and the `lib/` exports may
 > change shape before 1.0. Pin an exact version if you depend on it.
@@ -168,6 +199,7 @@ lib/
 lib/
   prompt.mjs            lens prompt construction
   run.mjs               roster planning and bounded fan-out
+  config.mjs            .crosscheckrc.json discovery and validation
 bin/crosscheck.mjs      CLI: run | report | sarif | baseline | overlap | calibrate
 fixtures/calibration/   planted defects, ground truth, and the calibration record
 fixtures/deception/     20 modules that look safe and are not, or the reverse
@@ -211,7 +243,7 @@ band.** A parallel fan-out that renders inline floods the session you are workin
 in and has to be killed to recover it.
 
 ```bash
-npm test   # 153 tests, no dependencies
+npm test   # 183 tests, no dependencies
 ```
 
 ## Adding a lens

package/bin/crosscheck.mjs

@@ -28,6 +28,12 @@
 //
 // Options: --overlap <file>  independence data from `overlap` (report/sarif)
 //          --lenses <dir>    lens directory (routing + SARIF rule metadata)
+//          --config <file>   config file (default: nearest .crosscheckrc.json,
+//                            searching upward and stopping at a repo root)
+//
+// Settings may live in .crosscheckrc.json so a team shares one panel definition
+// instead of a shell alias nobody else can see. Command-line flags win over it.
+//   {"exec": "claude -p", "concurrency": 2, "skip": ["ux"]}
 //
 // `run` dispatches the lenses itself. crosscheck never talks to a model: --exec
 // names a command that receives one lens prompt on stdin and returns findings on
@@ -43,6 +49,7 @@ import {
 } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { formatScore, score } from '../lib/calibrate.mjs';
+import { findConfig, mergeConfig, validateConfig } from '../lib/config.mjs';
 import { parseFrontmatter } from '../lib/lenses.mjs';
 import {
   countsBySeverity, lensOverlap, mergeFindings, panelVerdict
@@ -175,7 +182,11 @@ function collectFiles(targets) {
       }
       return;
     }
-    out.push(relative(process.cwd(), path) || path);
+    // Relative when the target is under cwd, absolute when it is not: a
+    // ../../../ chain is harder to read than the full path, and the model has
+    // to resolve whatever we print.
+    const rel = relative(process.cwd(), path);
+    out.push(!rel || rel.startsWith('..') ? path : rel);
   };
   for (const target of targets) {
     if (!existsSync(target)) {
@@ -274,27 +285,68 @@ function write(options, text) {
   }
 }
 
-async function runCommand(options, positional) {
+// Load the nearest config file, stopping at a repo root so a stray file in a
+// parent directory cannot silently reshape the run. The path is always
+// reported: a run configured by a file the user forgot about is the sort of
+// invisible behaviour this tool rejects everywhere else.
+function loadConfig(explicitPath) {
+  const path = explicitPath ?? findConfig(process.cwd(), {
+    exists: p => existsSync(p),
+    isRoot: dir => existsSync(join(dir, '.git'))
+  });
+  if (!path) {
+    return { config: {}, path: null };
+  }
+  if (!existsSync(path)) {
+    fail(`no such config file: ${path}`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    fail(`${path} is not valid JSON: ${error.message}`);
+  }
+  const { config, problems } = validateConfig(raw, path);
+  if (problems.length) {
+    for (const problem of problems) {
+      process.stderr.write(`crosscheck: ${problem}\n`);
+    }
+    fail('fix the config file, or pass --config to point elsewhere');
+  }
+  return { config, path };
+}
+
+async function runCommand(cliOptions, positional) {
+  const { config, path: configPath } = loadConfig(cliOptions.config);
+  const options = mergeConfig(config, cliOptions);
+  if (configPath) {
+    process.stderr.write(`crosscheck: config ${configPath}\n`);
+  }
   if (positional.length === 0) {
     fail('run needs at least one path to audit');
   }
+  // Resolve the target first: a bad path is the more fundamental error, and
+  // reporting a missing flag instead sends the user after the wrong problem.
+  const files = collectFiles(positional);
   if (!options.exec && !options['dry-run']) {
     fail("run needs --exec '<command>' (or --dry-run to see the prompts)");
   }
-  const files = collectFiles(positional);
   const lensDir = resolveLensDir(options.lenses);
   const lenses = loadLenses(lensDir);
-  const overrides = {
-    only: options.only?.split(',').map(s => s.trim()).filter(Boolean),
-    skip: options.skip?.split(',').map(s => s.trim()).filter(Boolean)
-  };
-  const { roster, skipped } = planRun(lenses, files, overrides);
+  // mergeConfig has already normalised these to arrays from either source.
+  const overrides = { only: options.only, skip: options.skip };
+  const { roster, skipped, unmatched } = planRun(lenses, files, overrides);
 
   process.stderr.write(
     `crosscheck: ${files.length} file(s), lenses from ${lensDir}\n` +
     `  roster:  ${roster.map(l => l.name).join(', ') || '(none)'}\n` +
     (skipped.length
       ? skipped.map(s => `  skipped: ${s.lens} — ${s.reason}`).join('\n') + '\n'
+      : '') +
+    (unmatched.length
+      ? `  UNREVIEWED: ${unmatched.length} file(s) matched no lens in the ` +
+        `roster — ${unmatched.slice(0, 5).join(', ')}` +
+        (unmatched.length > 5 ? `, +${unmatched.length - 5} more` : '') + '\n'
       : ''));
 
   if (roster.length === 0) {

package/lib/config.mjs

@@ -0,0 +1,136 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Project configuration.
+//
+// Retyping --exec on every invocation is friction that pushes people toward
+// shell aliases, which are invisible to everyone else on the team. A committed
+// config file makes the panel reproducible: the same command produces the same
+// roster and the same model for whoever runs it.
+//
+// Precedence is defaults < config file < command line, and the loaded path is
+// always reported — a run shaped by a file the user forgot about is exactly the
+// kind of silent behaviour this tool refuses everywhere else.
+
+export const CONFIG_FILENAMES = [
+  '.crosscheckrc.json',
+  '.crosscheckrc',
+  'crosscheck.config.json'
+];
+
+// Keys a config file may set. Anything else is a typo worth reporting rather
+// than ignoring: a misspelled `exec` that silently does nothing is worse than
+// an error.
+export const CONFIG_KEYS = new Set([
+  'exec', 'lenses', 'concurrency', 'only', 'skip', 'mixed',
+  'out', 'sarif', 'baseline', 'overlap'
+]);
+
+const LIST_KEYS = new Set(['only', 'skip']);
+
+export function validateConfig(raw, source = 'config') {
+  if (raw == null) {
+    return { config: {}, problems: [] };
+  }
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return {
+      config: {},
+      problems: [`${source}: expected a JSON object at the top level`]
+    };
+  }
+  const config = {};
+  const problems = [];
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.startsWith('//') || key === '$schema') {
+      continue;
+    }
+    if (!CONFIG_KEYS.has(key)) {
+      problems.push(
+        `${source}: unknown key "${key}" — expected one of ` +
+        [...CONFIG_KEYS].sort().join(', '));
+      continue;
+    }
+    if (LIST_KEYS.has(key)) {
+      if (Array.isArray(value)) {
+        config[key] = value.map(String);
+      } else if (typeof value === 'string') {
+        config[key] = value.split(',').map(s => s.trim()).filter(Boolean);
+      } else {
+        problems.push(`${source}: "${key}" must be a list or a comma string`);
+      }
+      continue;
+    }
+    if (key === 'concurrency') {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n < 1) {
+        problems.push(`${source}: "concurrency" must be a positive integer`);
+        continue;
+      }
+      config[key] = n;
+      continue;
+    }
+    if (key === 'mixed') {
+      if (typeof value !== 'boolean') {
+        problems.push(`${source}: "mixed" must be true or false`);
+        continue;
+      }
+      config[key] = value;
+      continue;
+    }
+    if (typeof value !== 'string' || value === '') {
+      problems.push(`${source}: "${key}" must be a non-empty string`);
+      continue;
+    }
+    config[key] = value;
+  }
+  return { config, problems };
+}
+
+// Command-line flags always win. `only`/`skip` arrive as comma strings from the
+// CLI and as lists from a file, so both are normalised to lists here.
+export function mergeConfig(fileConfig = {}, cliOptions = {}) {
+  const merged = { ...fileConfig };
+  for (const [key, value] of Object.entries(cliOptions)) {
+    if (value === undefined) {
+      continue;
+    }
+    merged[key] = LIST_KEYS.has(key) && typeof value === 'string'
+      ? value.split(',').map(s => s.trim()).filter(Boolean)
+      : value;
+  }
+  for (const key of LIST_KEYS) {
+    if (typeof merged[key] === 'string') {
+      merged[key] = merged[key].split(',').map(s => s.trim()).filter(Boolean);
+    }
+  }
+  return merged;
+}
+
+// Walk from `startDir` toward the filesystem root looking for a config file, so
+// running from a subdirectory of a project still picks up its settings.
+// `readFile` and `exists` are injected to keep this testable without a disk.
+export function findConfig(startDir, { exists, isRoot = null } = {}) {
+  if (typeof exists !== 'function') {
+    throw new Error('findConfig requires an exists() probe');
+  }
+  let dir = startDir;
+  const seen = new Set();
+  while (dir && !seen.has(dir)) {
+    seen.add(dir);
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = dir.endsWith('/') ? `${dir}${name}` : `${dir}/${name}`;
+      if (exists(candidate)) {
+        return candidate;
+      }
+    }
+    if (isRoot?.(dir)) {
+      return null;
+    }
+    const parent = dir.replace(/\/[^/]*\/?$/, '');
+    if (parent === dir || parent === '') {
+      return null;
+    }
+    dir = parent;
+  }
+  return null;
+}

package/lib/prompt.mjs

@@ -11,6 +11,13 @@
 export const CONTRACT_LINE =
   'file:line — SEVERITY — issue — fix';
 
+// The frontmatter is routing metadata — globs, cites, owns — consumed by the
+// router before dispatch. Sending it to the model costs tokens on every call and
+// tells it nothing it needs, so the body is what gets inlined.
+export function stripFrontmatter(text) {
+  return String(text ?? '').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
+}
+
 // A lens that reports on everything is useless, and a lens that quietly reviews
 // outside its remit corrupts the consensus signal — so both halves of its scope
 // are restated in the prompt, not just the part it owns.
@@ -33,10 +40,15 @@ export function buildLensPrompt(lens, files, options = {}) {
   parts.push(`You are running the **${lens.name}** audit lens.`);
 
   if (definition) {
+    const body = stripFrontmatter(definition);
+    if (!body) {
+      throw new Error(
+        `lens ${lens.name} has frontmatter but no body to adopt`);
+    }
     parts.push(
       'Adopt this lens completely — its method, its framing, its severity ' +
       'scale, and its output contract:\n\n' +
-      '--- BEGIN LENS DEFINITION ---\n' + definition.trim() +
+      '--- BEGIN LENS DEFINITION ---\n' + body +
       '\n--- END LENS DEFINITION ---');
   } else if (definitionPath) {
     parts.push(

package/lib/run.mjs

@@ -28,6 +28,11 @@ export function planRun(lenses, files, overrides = {}) {
   }
   const routed = routeRoster(lenses, files);
   const { roster, skipped } = applyOverrides(routed, overrides);
+  // A file that no rostered lens will read is a hole in the coverage. Reporting
+  // the file count without it lets a run look complete when part of the target
+  // was never examined.
+  const covered = new Set(roster.flatMap(l => l.files));
+  const unmatched = files.filter(f => !covered.has(f));
   if (overrides.only?.length) {
     const known = new Set((lenses ?? []).map(l => l.name));
     for (const name of overrides.only) {
@@ -36,7 +41,7 @@ export function planRun(lenses, files, overrides = {}) {
       }
     }
   }
-  return { roster, skipped };
+  return { roster, skipped, unmatched };
 }
 
 export function promptsFor(roster, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applesnort/crosscheck",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Run independent review lenses in parallel and merge their findings into one deduped, consensus-ranked report \u2014 with SARIF output.",
   "license": "MIT",
   "author": "Joel Mangin",
@@ -20,7 +20,8 @@
     "./lenses": "./lib/lenses.mjs",
     "./calibrate": "./lib/calibrate.mjs",
     "./run": "./lib/run.mjs",
-    "./prompt": "./lib/prompt.mjs"
+    "./prompt": "./lib/prompt.mjs",
+    "./config": "./lib/config.mjs"
   },
   "files": [
     "bin/",