@applesnort/crosscheck 0.2.1 → 0.3.0

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,7 +199,9 @@ lib/
 lib/
   prompt.mjs            lens prompt construction
   run.mjs               roster planning and bounded fan-out
-bin/crosscheck.mjs      CLI: run | report | sarif | baseline | overlap | calibrate
+  config.mjs            .crosscheckrc.json discovery and validation
+bin/crosscheck.mjs      CLI: run | lenses | 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
 PROVENANCE.md           where all of this came from
@@ -211,10 +244,83 @@ 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 your own lenses
+
+Lens sources layer, in increasing precedence:
+
+1. the lenses packaged with crosscheck
+2. `./lenses` or `./.crosscheck/lenses` in your project, if present
+3. anything named by `--lenses dir,dir` or the config's `lenses` key
+
+A later source **adds** to the earlier ones. A lens whose `name` matches an
+earlier one **overrides** it, and the override is printed — so customising the
+stock `check` costs one file rather than forking all five and losing upstream
+changes. `--no-builtin` drops the packaged set entirely.
+
+```bash
+mkdir -p .crosscheck/lenses
+$EDITOR .crosscheck/lenses/chaos.md
+npx @applesnort/crosscheck lenses     # what resolved, and from where
+```
+
+A lens is a markdown file: five frontmatter keys, then the prompt.
+
+```markdown
+---
+name: chaos
+summary: adversarial user trying to break the flow
+when: [**/*.{js,jsx,tsx,vue}]
+owns: states reachable by misuse — double-submit, back button, hostile input
+not-owns: correctness, security categories, architecture
+---
+
+# Lens: chaos
+
+You are trying to break this, not review it. ...
+
+Findings only: `file:line — SEVERITY — issue — fix`. SEVERITY is BLOCK, FIX, or
+CONSIDER. If nothing here can be broken, reply exactly `NO FINDINGS`.
 ```
 
-## Adding a lens
+`when` routes it — a lens whose globs match nothing in the target is skipped, with
+the reason printed. `not-owns` is required: a lens that never declines dilutes the
+signal everything else depends on. The body should end by restating the output
+contract, since that is what the parser expects back.
+
+`crosscheck lenses` prints the resolved set with each lens's origin and globs,
+which is the fastest way to see why something did or did not run.
+
+### Local lenses stay local
+
+Nothing in `./lenses` or `./.crosscheck/lenses` is packaged, uploaded, or shared
+by crosscheck. Those files are read off your disk at dispatch time and go nowhere
+else. That has two practical consequences worth knowing before you write any.
+
+**A local lens can be as specific as you like.** The packaged lenses are
+deliberately generic, which also makes them shallow: they cannot know your
+storage conventions, your framework's failure modes, the mistake your team makes
+every quarter, or the review standard one colleague applies better than anyone
+else. A lens that encodes any of that will outperform a generic one on your
+codebase, and it belongs in your repo rather than upstream. The useful ones
+usually aren't portable.
+
+**Distribution is where obligations start, and you are not distributing.** If you
+adapt a lens from a published persona set, a standards document, or a colleague's
+review checklist, keeping it local puts you in the same position as any private
+note-taking. Those materials often carry licences requiring attribution — the UK
+government's accessibility personas are published under the Open Government
+Licence, for one — and that condition attaches when you *publish* a derivative,
+not when you run one. If a local lens later becomes something you want to share,
+that is the moment to check what it derives from and credit it.
+
+The corollary: a lens holding a named individual's review preferences, or a
+description of an unreleased product, is a local lens permanently. Publishing it
+shares something about a person or a project, not just a prompt.
+
+## Writing a good lens
 
 A lens earns its place by finding what the others miss. Give it a remit narrow
 enough that it declines most changes, state what it does *not* own, and make it name

package/bin/crosscheck.mjs

@@ -20,6 +20,7 @@
 //   crosscheck run <path...>     --exec '<command>'  [--lenses dir] [--only a,b]
 //                                [--skip x,y] [--concurrency N] [--out run.json]
 //                                [--sarif f] [--baseline b] [--mixed] [--dry-run]
+//   crosscheck lenses            [--lenses dir,dir] [--no-builtin]
 //   crosscheck report            [--in run.json] [--baseline b.json]
 //   crosscheck sarif             [--in run.json] [--baseline b.json] [--out x.sarif]
 //   crosscheck baseline          [--in run.json] --out baseline.json
@@ -28,6 +29,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,7 +50,8 @@ import {
 } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { formatScore, score } from '../lib/calibrate.mjs';
-import { parseFrontmatter } from '../lib/lenses.mjs';
+import { findConfig, mergeConfig, validateConfig } from '../lib/config.mjs';
+import { parseFrontmatter, resolveLensSet } from '../lib/lenses.mjs';
 import {
   countsBySeverity, lensOverlap, mergeFindings, panelVerdict
 } from '../lib/merge.mjs';
@@ -58,7 +66,7 @@ function fail(message) {
   process.exit(2);
 }
 
-const BOOLEAN_FLAGS = new Set(['dry-run', 'mixed']);
+const BOOLEAN_FLAGS = new Set(['dry-run', 'mixed', 'no-builtin']);
 
 function parseArgs(argv) {
   const [command, ...rest] = argv;
@@ -125,18 +133,37 @@ function loadLensMeta(dir) {
   return meta;
 }
 
-// Lens directory: an explicit --lenses, else ./lenses, else the copy shipped
-// with the package. Resolved loudly so a typo does not silently run zero lenses.
-function resolveLensDir(dir) {
-  const candidates = dir
-    ? [resolve(dir)]
-    : [resolve('lenses'), new URL('../lenses/', import.meta.url).pathname];
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) {
-      return candidate;
+const BUILTIN_LENS_DIR = new URL('../lenses/', import.meta.url).pathname;
+
+// Lens sources, in increasing precedence: the packaged lenses, then ./lenses or
+// .crosscheck/lenses if present, then anything named by --lenses. Layering
+// rather than replacing means adding one lens costs one file instead of forking
+// all of them and losing upstream changes.
+function lensSources(option, { includeBuiltin = true } = {}) {
+  const dirs = [];
+  if (includeBuiltin) {
+    dirs.push(BUILTIN_LENS_DIR);
+  }
+  for (const local of ['lenses', '.crosscheck/lenses']) {
+    const path = resolve(local);
+    if (existsSync(path) && path !== resolve(BUILTIN_LENS_DIR)) {
+      dirs.push(path);
+    }
+  }
+  const explicit = Array.isArray(option)
+    ? option
+    : (option ? String(option).split(',').map(d => d.trim()).filter(Boolean) : []);
+  for (const dir of explicit) {
+    const path = resolve(dir);
+    if (!existsSync(path)) {
+      fail(`no such lens directory: ${dir}`);
     }
+    dirs.push(path);
   }
-  fail(`no lens directory found (looked in ${candidates.join(', ')})`);
+  if (dirs.length === 0) {
+    fail('no lens directories to load (--no-builtin with no --lenses?)');
+  }
+  return dirs.map(dir => ({ origin: dir, lenses: loadLenses(dir) }));
 }
 
 function loadLenses(dir) {
@@ -278,7 +305,43 @@ 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');
   }
@@ -288,16 +351,21 @@ async function runCommand(options, positional) {
   if (!options.exec && !options['dry-run']) {
     fail("run needs --exec '<command>' (or --dry-run to see the prompts)");
   }
-  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 sources = lensSources(options.lenses,
+    { includeBuiltin: !options['no-builtin'] });
+  const { lenses, shadowed } = resolveLensSet(sources);
+  const lensDir = sources.at(-1).origin;
+  for (const s of shadowed) {
+    process.stderr.write(
+      `crosscheck: lens "${s.name}" from ${s.winner} overrides ${s.shadowedFrom}\n`);
+  }
+  // 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` +
+    `crosscheck: ${files.length} file(s), ${lenses.length} lens(es) from ` +
+    `${sources.length} source(s)\n` +
     `  roster:  ${roster.map(l => l.name).join(', ') || '(none)'}\n` +
     (skipped.length
       ? skipped.map(s => `  skipped: ${s.lens} — ${s.reason}`).join('\n') + '\n'
@@ -362,7 +430,7 @@ async function runCommand(options, positional) {
 
   if (options.sarif) {
     writeFileSync(options.sarif, toSarifJson(merged, {
-      lensMeta: loadLensMeta(lensDir)
+      lensMeta: Object.fromEntries(lenses.map(l => [l.name, l]))
     }));
     process.stderr.write(`crosscheck: wrote ${options.sarif}\n`);
   }
@@ -389,6 +457,22 @@ async function main() {
     return;
   }
 
+  if (command === 'lenses') {
+    const sources = lensSources(options.lenses,
+      { includeBuiltin: !options['no-builtin'] });
+    const { lenses, shadowed } = resolveLensSet(sources);
+    const out = [`${lenses.length} lens(es) from ${sources.length} source(s):`];
+    for (const lens of lenses) {
+      out.push(`  ${lens.name.padEnd(16)} ${lens.origin}`);
+      out.push(`    when: ${(lens.when ?? []).join(', ')}`);
+    }
+    for (const s of shadowed) {
+      out.push(`  override: "${s.name}" from ${s.winner} shadows ${s.shadowedFrom}`);
+    }
+    process.stdout.write(out.join('\n') + '\n');
+    return;
+  }
+
   if (command === 'report') {
     write(options, report(buildMerged(options)));
     return;

package/lib/lenses.mjs

@@ -198,3 +198,38 @@ export function applyOverrides(routed, { only, skip } = {}) {
   }
   return { roster, skipped };
 }
+
+// Layered lens resolution.
+//
+// A single lens directory has to be either yours or the packaged one, which
+// forces anyone adding a lens to fork all of them and lose upstream changes.
+// Sources are layered instead, in increasing precedence: a later source with the
+// same lens `name` shadows an earlier one, so overriding one lens costs one file
+// rather than a fork.
+//
+// sources: [{origin, lenses: [{name, ...}]}] — origin is a label for reporting,
+// usually the directory the lenses were read from.
+export function resolveLensSet(sources) {
+  const byName = new Map();
+  const shadowed = [];
+  for (const source of sources ?? []) {
+    for (const lens of source.lenses ?? []) {
+      if (!lens?.name) {
+        continue;
+      }
+      const previous = byName.get(lens.name);
+      if (previous) {
+        shadowed.push({
+          name: lens.name,
+          winner: source.origin,
+          shadowedFrom: previous.origin
+        });
+      }
+      byName.set(lens.name, { ...lens, origin: source.origin });
+    }
+  }
+  return {
+    lenses: [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    shadowed
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applesnort/crosscheck",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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/",