@applesnort/crosscheck 0.2.2 → 0.3.0

package/README.md

@@ -200,7 +200,8 @@ 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
+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
@@ -246,7 +247,80 @@ in and has to be killed to recover it.
 npm test   # 183 tests, no dependencies
 ```
 
-## Adding a lens
+## 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`.
+```
+
+`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
@@ -50,7 +51,7 @@ import {
 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 { parseFrontmatter, resolveLensSet } from '../lib/lenses.mjs';
 import {
   countsBySeverity, lensOverlap, mergeFindings, panelVerdict
 } from '../lib/merge.mjs';
@@ -65,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;
@@ -132,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);
     }
   }
-  fail(`no lens directory found (looked in ${candidates.join(', ')})`);
+  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);
+  }
+  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) {
@@ -331,14 +351,21 @@ async function runCommand(cliOptions, 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 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'
@@ -403,7 +430,7 @@ async function runCommand(cliOptions, 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`);
   }
@@ -430,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.2",
+  "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",