atris 3.46.1 → 3.48.0

package/scripts/det/json.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// det/json.js — deterministic JSON reshaping. The reformat/validate/flatten asks
+// an LLM does by hand (and mis-escapes). Reads JSON on stdin, writes stdout.
+//
+// Usage:
+//   cat data.json | node json.js pretty          # 2-space indent
+//   node json.js min      < data.json             # minified, one line
+//   node json.js validate < data.json             # prints "valid" or errors (exit 2)
+//   node json.js keys     < data.json             # top-level keys, one per line
+//   node json.js csv      < array.json            # array of objects -> RFC-4180 CSV
+//
+// Modes: pretty | min | validate | keys | csv
+// Exit 0 on success, 2 on invalid JSON or bad mode/shape.
+
+'use strict';
+
+function parse(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+// RFC-4180: quote a field if it holds comma, quote, CR or LF; double inner quotes.
+function csvField(v) {
+  let s;
+  if (v === null || v === undefined) s = '';
+  else if (typeof v === 'object') s = JSON.stringify(v);
+  else s = String(v);
+  if (/[",\r\n]/.test(s)) s = '"' + s.replace(/"/g, '""') + '"';
+  return s;
+}
+
+function toCsv(arr) {
+  if (!Array.isArray(arr)) throw new Error('csv mode needs a JSON array of objects');
+  if (arr.length === 0) return '';
+  // Column order = first-seen key order across all rows (stable, deterministic).
+  const cols = [];
+  const seen = new Set();
+  for (const row of arr) {
+    if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+      throw new Error('csv mode needs each item to be an object');
+    }
+    for (const k of Object.keys(row)) {
+      if (!seen.has(k)) {
+        seen.add(k);
+        cols.push(k);
+      }
+    }
+  }
+  const lines = [cols.map(csvField).join(',')];
+  for (const row of arr) {
+    lines.push(cols.map((c) => csvField(row[c])).join(','));
+  }
+  return lines.join('\n');
+}
+
+// Returns { text } on success or { error } on failure. Pure — unit-testable.
+function run(mode, input) {
+  if (mode === 'validate') {
+    const p = parse(input);
+    return p.ok ? { text: 'valid' } : { error: p.error };
+  }
+  const p = parse(input);
+  if (!p.ok) return { error: p.error };
+  const v = p.value;
+  switch (mode) {
+    case 'pretty':
+      return { text: JSON.stringify(v, null, 2) };
+    case 'min':
+      return { text: JSON.stringify(v) };
+    case 'keys':
+      if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+        return { error: 'keys mode needs a JSON object' };
+      }
+      return { text: Object.keys(v).join('\n') };
+    case 'csv':
+      try {
+        return { text: toCsv(v) };
+      } catch (e) {
+        return { error: e.message };
+      }
+    default:
+      return { error: `unknown mode: ${mode}` };
+  }
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    if (process.stdin.isTTY) resolve('');
+  });
+}
+
+const MODES = ['pretty', 'min', 'validate', 'keys', 'csv'];
+
+async function main() {
+  const mode = process.argv.slice(2).find((a) => !a.startsWith('-'));
+  if (!mode || !MODES.includes(mode)) {
+    process.stderr.write(`unknown mode: ${mode || '(none)'}\nmodes: ${MODES.join(' | ')}\n`);
+    process.exit(2);
+  }
+  const input = await readStdin();
+  const res = run(mode, input);
+  if (res.error) {
+    process.stderr.write(res.error + '\n');
+    process.exit(2);
+  }
+  if (res.text.length) process.stdout.write(res.text + '\n');
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { run, toCsv, MODES };

package/scripts/det/pr-description.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// det/pr-description.js — draft a PR description from the branch's diff vs a base.
+// Replaces the "write a PR description" ask: the title comes from the commits,
+// the summary bullets from which areas changed, and the test-plan skeleton from
+// the touched test files — all read off the diff, so it is exact and never
+// invents a rationale or a checklist item that isn't backed by a real change.
+//
+// Usage:
+//   node pr-description.js                     # diff origin/master...HEAD -> markdown
+//   node pr-description.js origin/main         # different base
+//   node pr-description.js origin/main HEAD    # explicit base + head
+//   node pr-description.js --json              # structured {title,summary,testPlan,...}
+//
+// Reads git itself; no stdin. The pure core build({commits, files}) is exported
+// and unit-tested. Reuses parseSubject (changelog) and leadFile (commit-msg) so
+// the library stays coherent.
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const { parseSubject, SECTIONS } = require('./changelog');
+const { leadFile } = require('./commit-msg');
+
+// --- pure core (no git, no process) ---------------------------------------
+
+function topDir(p) {
+  const i = p.indexOf('/');
+  return i === -1 ? '.' : p.slice(0, i);
+}
+function isTest(p) {
+  // a test/ dir, a foo.test.js, or a file literally named test.js/test.ts
+  return /(^|\/)tests?\//.test(p) || /\.test\.[jt]s$/.test(p) || /(^|\/)tests?\.[jt]s$/.test(p);
+}
+
+// title: one commit -> its subject; many -> dominant Conventional type + the
+// lead file. Dominant type ties break in SECTIONS order (feat before fix ...).
+function pickTitle(commits, files) {
+  if (commits.length === 1) return (commits[0].subject || '').trim();
+  const counts = {};
+  for (const c of commits) {
+    const t = parseSubject(c.subject || '').type;
+    counts[t] = (counts[t] || 0) + 1;
+  }
+  let lead = 'other';
+  let best = -1;
+  for (const [type] of SECTIONS) {
+    if ((counts[type] || 0) > best) {
+      best = counts[type] || 0;
+      lead = type;
+    }
+  }
+  if (!files.length) return `${lead}: ${commits.length} commits`;
+  const f = leadFile(files);
+  const name = f.path.split('/').pop();
+  return `${lead}: ${name}${files.length > 1 ? ` (+${files.length - 1} more)` : ''}`;
+}
+
+// one summary bullet per top-level area (first-seen order), with add/change/
+// remove counts and exact churn — so a reviewer sees the shape at a glance.
+function areaBullets(files) {
+  const groups = new Map();
+  for (const f of files) {
+    const k = topDir(f.path);
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(f);
+  }
+  const bullets = [];
+  for (const [area, fs] of groups) {
+    const counts = { A: 0, M: 0, D: 0 };
+    let added = 0;
+    let deleted = 0;
+    for (const f of fs) {
+      counts[f.status] = (counts[f.status] || 0) + 1;
+      added += f.added || 0;
+      deleted += f.deleted || 0;
+    }
+    const parts = [];
+    if (counts.A) parts.push(`${counts.A} added`);
+    if (counts.M) parts.push(`${counts.M} changed`);
+    if (counts.D) parts.push(`${counts.D} removed`);
+    bullets.push(`- **${area}** — ${parts.join(', ')} (+${added}/-${deleted})`);
+  }
+  return bullets;
+}
+
+// test-plan skeleton: list the touched test files to run, then one check per
+// non-test area. Every line is backed by a real change; no invented steps.
+function testPlan(files) {
+  const lines = [];
+  const tests = files.filter((f) => isTest(f.path) && f.status !== 'D').map((f) => f.path);
+  if (tests.length) {
+    lines.push('- [ ] Run the touched tests:');
+    for (const t of tests) lines.push(`  - \`${t}\``);
+  }
+  const areas = [];
+  for (const f of files) {
+    if (isTest(f.path)) continue;
+    const a = topDir(f.path);
+    if (!areas.includes(a)) areas.push(a);
+  }
+  for (const a of areas) lines.push(`- [ ] Exercise **${a}** and confirm no regression`);
+  if (!lines.length) lines.push('- [ ] Manual verification of the changed files');
+  return lines;
+}
+
+// { commits, files } -> { title, summary, testPlan, total, commits }
+function build(input) {
+  const commits = (input && input.commits) || [];
+  const files = (input && input.files) || [];
+  if (!commits.length && !files.length) {
+    return { error: 'no commits or files vs base — is the branch ahead of it?' };
+  }
+  const totals = files.reduce(
+    (a, f) => ({ added: a.added + (f.added || 0), deleted: a.deleted + (f.deleted || 0) }),
+    { added: 0, deleted: 0 }
+  );
+  return {
+    title: pickTitle(commits, files),
+    summary: areaBullets(files),
+    testPlan: testPlan(files),
+    totals,
+    fileCount: files.length,
+    commitCount: commits.length,
+  };
+}
+
+function render(res) {
+  const out = [`# ${res.title}`, ''];
+  out.push('## Summary');
+  out.push(...(res.summary.length ? res.summary : ['- (no file changes)']));
+  out.push(`- ${res.commitCount} commit${res.commitCount === 1 ? '' : 's'}, ${res.fileCount} file${
+    res.fileCount === 1 ? '' : 's'
+  }, +${res.totals.added}/-${res.totals.deleted}`);
+  out.push('', '## Test plan');
+  out.push(...res.testPlan);
+  return out.join('\n');
+}
+
+// --- git plumbing (impure, only in main) ----------------------------------
+
+function readCommits(range) {
+  const out = execFileSync('git', ['log', '--no-merges', '--pretty=%h%x09%s', range], {
+    encoding: 'utf8',
+  });
+  const commits = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    const tab = line.indexOf('\t');
+    commits.push({ hash: line.slice(0, tab), subject: line.slice(tab + 1) });
+  }
+  return commits;
+}
+
+// merge-base diff (three-dot) so the PR shows only this branch's changes.
+function readFiles(threeDot) {
+  const numstat = execFileSync('git', ['diff', '--numstat', threeDot], { encoding: 'utf8' });
+  const names = execFileSync('git', ['diff', '--name-status', threeDot], { encoding: 'utf8' });
+  const stat = {};
+  for (const line of numstat.split('\n')) {
+    if (!line.trim()) continue;
+    const [added, deleted, path] = line.split('\t');
+    stat[path] = {
+      added: added === '-' ? 0 : Number(added),
+      deleted: deleted === '-' ? 0 : Number(deleted),
+    };
+  }
+  const files = [];
+  for (const line of names.split('\n')) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    const status = parts[0][0];
+    const path = parts[parts.length - 1];
+    files.push({
+      path,
+      status,
+      added: (stat[path] || {}).added || 0,
+      deleted: (stat[path] || {}).deleted || 0,
+    });
+  }
+  return files;
+}
+
+function main() {
+  const args = process.argv.slice(2).filter((a) => a !== '--json');
+  const wantJson = process.argv.includes('--json');
+  const base = args[0] || 'origin/master';
+  const head = args[1] || 'HEAD';
+  let commits;
+  let files;
+  try {
+    commits = readCommits(`${base}..${head}`);
+    files = readFiles(`${base}...${head}`);
+  } catch (e) {
+    process.stderr.write(`git failed: ${e.message}\n`);
+    process.exit(2);
+  }
+  const res = build({ commits, files });
+  if (res.error) {
+    process.stderr.write(res.error + '\n');
+    process.exit(2);
+  }
+  if (wantJson) {
+    process.stdout.write(JSON.stringify({ base, head, ...res }, null, 2) + '\n');
+  } else {
+    process.stdout.write(render(res) + '\n');
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { build, pickTitle, areaBullets, testPlan, render };

package/scripts/det/test.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// det/test.js — self-test for the deterministic task scripts.
+// Zero deps, exits non-zero on any failure so CI and agents can trust the lib.
+'use strict';
+
+const assert = require('assert');
+const extractModule = require('./extract');
+const { extract } = extractModule;
+const jsonModule = require('./json');
+const { run } = jsonModule;
+const text = require('./text');
+const hash = require('./hash');
+const date = require('./date');
+const commitMsg = require('./commit-msg');
+const changelog = require('./changelog');
+const prDesc = require('./pr-description');
+const { CATALOG, catalogJson, catalogText, GIT_SCRIPTS } = require('./det');
+
+let passed = 0;
+function check(name, actual, expected) {
+  assert.deepStrictEqual(actual, expected, name);
+  passed += 1;
+}
+
+// urls: strip trailing punctuation, dedupe, keep order
+check(
+  'urls',
+  extract('urls', 'see https://a.com/x. and http://b.io, then https://a.com/x again'),
+  ['https://a.com/x', 'http://b.io']
+);
+
+check('emails', extract('emails', 'a@b.com and c@d.co and a@b.com'), ['a@b.com', 'c@d.co']);
+
+check(
+  'code',
+  extract('code', 'text\n```js\nconst x = 1;\n```\nmore\n```\nplain\n```'),
+  ['const x = 1;', 'plain']
+);
+
+check('numbers', extract('numbers', 'got 1,234 items at 9.5 each, -3 lost'), ['1,234', '9.5', '-3']);
+
+check('ipv4', extract('ipv4', 'from 192.168.0.1 not 999.1.1.1'), ['192.168.0.1']);
+
+check('hashtags', extract('hashtags', 'ship #atris and #det #atris'), ['#atris', '#det']);
+
+// unknown kind -> null
+check('unknown', extract('nope', 'x'), null);
+
+// empty input -> empty list
+check('empty', extract('urls', ''), []);
+
+// --- json.js ---
+check('json.pretty', run('pretty', '{"a":1}'), { text: '{\n  "a": 1\n}' });
+check('json.min', run('min', '{ "a" : 1 }'), { text: '{"a":1}' });
+check('json.validate.ok', run('validate', '[1,2,3]'), { text: 'valid' });
+check('json.validate.bad', run('validate', '{bad}').error !== undefined, true);
+check('json.keys', run('keys', '{"a":1,"b":2}'), { text: 'a\nb' });
+// csv: header from first-seen key order, proper RFC-4180 quoting of commas/quotes
+check(
+  'json.csv',
+  run('csv', '[{"name":"a, b","n":1},{"name":"c\\"d","n":2}]'),
+  { text: 'name,n\n"a, b",1\n"c""d",2' }
+);
+check('json.csv.notArray', run('csv', '{"a":1}').error !== undefined, true);
+check('json.badMode', run('nope', '{}').error !== undefined, true);
+
+// --- text.js ---
+check('text.dedupe', text.run('dedupe', 'a\nb\na\nc'), { text: 'a\nb\nc' });
+check('text.sort', text.run('sort', 'c\na\nb'), { text: 'a\nb\nc' });
+check('text.rsort', text.run('rsort', 'a\nc\nb'), { text: 'c\nb\na' });
+check('text.count', text.run('count', 'a b\nc'), { text: 'lines\t2\nwords\t3\nchars\t5' });
+check('text.slug', text.slugify('Hello, World! 2026'), 'hello-world-2026');
+check('text.slug.accents', text.slugify('Café Déjà Vu'), 'cafe-deja-vu');
+check('text.trim', text.run('trim', 'a  \n\n  \nb'), { text: 'a\nb' });
+check('text.empty', text.run('dedupe', ''), { text: '' });
+check('text.badMode', text.run('nope', 'x').error !== undefined, true);
+
+// --- hash.js ---
+check('hash.b64', hash.run('b64', 'hi'), { text: 'aGk=' });
+check('hash.b64.roundtrip', hash.run('b64d', hash.run('b64', 'hello').text), { text: 'hello' });
+check('hash.sha256', hash.run('sha256', 'hi'), {
+  text: '8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4',
+});
+check('hash.md5', hash.run('md5', 'hi'), { text: '49f68a5c8493ec2c0bf489821c21fc3b' });
+check('hash.hex.roundtrip', hash.run('hexdec', hash.run('hexenc', 'yo').text), { text: 'yo' });
+check('hash.newlineStripped', hash.run('b64', 'hi\n'), { text: 'aGk=' }); // echo == printf
+check('hash.hexdec.bad', hash.run('hexdec', 'xyz').error !== undefined, true);
+check('hash.badMode', hash.run('nope', 'x').error !== undefined, true);
+
+// --- date.js ---
+check('date.iso.sec', date.run('iso', '1700000000'), { text: '2023-11-14T22:13:20.000Z' });
+check('date.iso.ms', date.run('iso', '1700000000000'), { text: '2023-11-14T22:13:20.000Z' });
+check('date.epoch', date.run('epoch', '2026-07-07'), { text: '1783382400' });
+check('date.epochms', date.run('epochms', '2026-07-07'), { text: '1783382400000' });
+check('date.weekday', date.run('weekday', '2026-07-07'), { text: 'Tuesday' });
+check('date.epoch0', date.run('iso', '0'), { text: '1970-01-01T00:00:00.000Z' });
+check('date.utcPinned', date.run('epoch', '2026-07-07T00:00:00'), { text: '1783382400' }); // no zone -> UTC
+check('date.bad', date.run('iso', 'not-a-date').error !== undefined, true);
+check('date.badMode', date.run('nope', '0').error !== undefined, true);
+
+// --- commit-msg.js (git-facing) ---
+// type from paths: all under scripts/ -> chore, scope = deepest common dir
+{
+  const d = commitMsg.draft([
+    { path: 'scripts/det/date.js', status: 'A', added: 90, deleted: 0 },
+    { path: 'scripts/det/test.js', status: 'M', added: 11, deleted: 1 },
+  ]);
+  // names the lead (added) file, not an anonymous "update 2 files" count
+  check('commit.subject', d.subject, 'chore(det): add date.js (+1 more)');
+  check('commit.totals', d.totals, { added: 101, deleted: 1 });
+  check('commit.body.stat', /2 files changed, \+101\/-1$/.test(d.body), true);
+}
+// lead file = biggest churn when nothing is added; tie broken by path
+check(
+  'commit.lead.churn',
+  commitMsg.draft([
+    { path: 'lib/a.js', status: 'M', added: 2, deleted: 1 },
+    { path: 'lib/b.js', status: 'M', added: 40, deleted: 5 },
+  ]).subject,
+  'fix(lib): update b.js (+1 more)'
+);
+// added file wins over a higher-churn modified file
+check(
+  'commit.lead.added',
+  commitMsg.leadFile([
+    { path: 'lib/big.js', status: 'M', added: 99, deleted: 0 },
+    { path: 'lib/new.js', status: 'A', added: 3, deleted: 0 },
+  ]).path,
+  'lib/new.js'
+);
+check(
+  'commit.docs',
+  commitMsg.draft([{ path: 'README.md', status: 'M', added: 3, deleted: 0 }]).subject,
+  'docs: update README.md'
+);
+check(
+  'commit.test',
+  commitMsg.draft([{ path: 'test/foo.test.js', status: 'A', added: 5, deleted: 0 }]).subject,
+  'test: add foo.test.js'
+);
+check(
+  'commit.feat',
+  commitMsg.draft([{ path: 'lib/parser.js', status: 'A', added: 40, deleted: 0 }]).subject,
+  'feat(lib): add parser.js'
+);
+check(
+  'commit.fix',
+  commitMsg.draft([{ path: 'lib/parser.js', status: 'M', added: 2, deleted: 2 }]).subject,
+  'fix(lib): update parser.js'
+);
+check('commit.scope.root', commitMsg.commonDirScope(['package.json']), '');
+check('commit.empty', commitMsg.draft([]).error !== undefined, true);
+
+// --- changelog.js (git-facing) ---
+// header grammar: type(scope)!: subject -> parsed fields, breaking flagged
+check('changelog.parse', changelog.parseSubject('feat(cli): add reel'), {
+  type: 'feat',
+  scope: 'cli',
+  breaking: false,
+  subject: 'add reel',
+});
+check('changelog.parse.bang', changelog.parseSubject('feat!: drop v1').breaking, true);
+// unknown type -> "other" bucket, whole line kept (nothing dropped)
+check('changelog.parse.unknown', changelog.parseSubject('wip: poke').type, 'other');
+check('changelog.parse.freeform', changelog.parseSubject('just a note').subject, 'just a note');
+{
+  const r = changelog.build([
+    { hash: 'a1', subject: 'feat(cli): add reel' },
+    { hash: 'b2', subject: 'fix(det): guard empty range' },
+    { hash: 'c3', subject: 'feat: add card' },
+    { hash: 'd4', subject: 'chore!: bump major' },
+  ]);
+  // sections come back in SECTIONS order: feat before fix before chore
+  check('changelog.order', r.sections.map((s) => s.type), ['feat', 'fix', 'chore']);
+  check('changelog.counts', r.counts, { feat: 2, fix: 1, chore: 1 });
+  check('changelog.breaking', r.breaking.length, 1);
+  check('changelog.total', r.total, 4);
+  // rendered markdown groups under human headings, breaking first
+  const md = changelog.render(r);
+  check('changelog.render.breaking', /^### ⚠ BREAKING CHANGES/.test(md), true);
+  check('changelog.render.feat', md.includes('### Features'), true);
+  check('changelog.render.item', md.includes('- add reel (cli) [a1]'), true);
+}
+check('changelog.empty', changelog.render(changelog.build([])), 'No changes.');
+check('changelog.badInput', changelog.build('nope').error !== undefined, true);
+
+// --- pr-description.js (git-facing) ---
+// single commit -> title is that subject verbatim
+check(
+  'pr.title.one',
+  prDesc.pickTitle([{ subject: 'feat(cli): add reel' }], [{ path: 'commands/reel.js', status: 'A' }]),
+  'feat(cli): add reel'
+);
+// many commits -> dominant type + lead file (feat wins the tie by SECTIONS order)
+check(
+  'pr.title.many',
+  prDesc.pickTitle(
+    [{ subject: 'feat: a' }, { subject: 'fix: b' }, { subject: 'feat: c' }],
+    [
+      { path: 'lib/new.js', status: 'A', added: 3, deleted: 0 },
+      { path: 'lib/old.js', status: 'M', added: 1, deleted: 1 },
+    ]
+  ),
+  'feat: new.js (+1 more)'
+);
+// summary bullets: one per top-level area, first-seen order, with counts + churn
+check(
+  'pr.summary.areas',
+  prDesc.areaBullets([
+    { path: 'scripts/det/a.js', status: 'A', added: 10, deleted: 0 },
+    { path: 'scripts/det/b.js', status: 'M', added: 2, deleted: 1 },
+    { path: 'test/x.test.js', status: 'A', added: 5, deleted: 0 },
+  ]),
+  ['- **scripts** — 1 added, 1 changed (+12/-1)', '- **test** — 1 added (+5/-0)']
+);
+// test plan lists touched test files, then a check per non-test area
+check(
+  'pr.testplan',
+  prDesc.testPlan([
+    { path: 'scripts/det/a.js', status: 'M' },
+    { path: 'scripts/det/test.js', status: 'M' },
+  ]),
+  [
+    '- [ ] Run the touched tests:',
+    '  - `scripts/det/test.js`',
+    '- [ ] Exercise **scripts** and confirm no regression',
+  ]
+);
+// no test files -> generic fallback line
+check('pr.testplan.none', prDesc.testPlan([{ path: 'README.md', status: 'M' }]), [
+  '- [ ] Exercise **.** and confirm no regression',
+]);
+{
+  const r = prDesc.build({
+    commits: [{ hash: 'a1', subject: 'feat(det): add pr-description.js' }],
+    files: [{ path: 'scripts/det/pr-description.js', status: 'A', added: 100, deleted: 0 }],
+  });
+  const md = prDesc.render(r);
+  check('pr.render.title', /^# feat\(det\): add pr-description\.js/.test(md), true);
+  check('pr.render.summary', md.includes('## Summary'), true);
+  check('pr.render.testplan', md.includes('## Test plan'), true);
+  check('pr.render.stat', md.includes('1 commit, 1 file, +100/-0'), true);
+}
+check('pr.empty', prDesc.build({ commits: [], files: [] }).error !== undefined, true);
+
+// --- det.js dispatcher ---
+check('det.catalog', Object.keys(CATALOG).sort(), ['date', 'extract', 'hash', 'json', 'text', 'voice']);
+check('det.voice.pass', CATALOG.voice.run('scan', 'The build is green.').text, 'PASS');
+check('det.voice.fail', CATALOG.voice.run('scan', 'fixed the worktree').text.startsWith('FAIL'), true);
+check('det.date.route', CATALOG.date.run('weekday', '2026-07-07'), { text: 'Tuesday' });
+check('det.date.modes', CATALOG.date.modes, date.MODES);
+check('det.hash.route', CATALOG.hash.run('b64', 'hi'), { text: 'aGk=' });
+check('det.hash.modes', CATALOG.hash.modes, hash.MODES);
+// every catalog entry advertises modes and routes to a working run()
+check('det.extract.route', CATALOG.extract.run('emails', 'x a@b.com'), { text: 'a@b.com' });
+check('det.json.route', CATALOG.json.run('min', '{ "a": 1 }'), { text: '{"a":1}' });
+check('det.text.route', CATALOG.text.run('dedupe', 'a\na'), { text: 'a' });
+check('det.badMode', CATALOG.extract.run('nope', 'x').error !== undefined, true);
+// catalog modes must equal what each script actually exports (no drift)
+check('det.extract.modes', CATALOG.extract.modes, Object.keys(extractModule.EXTRACTORS));
+check('det.json.modes', CATALOG.json.modes, jsonModule.MODES);
+check('det.text.modes', CATALOG.text.modes, text.MODES);
+// git-facing scripts surface at the front door so all 8 tools are discoverable
+check('det.git.names', GIT_SCRIPTS.map((g) => g.name), ['commit-msg', 'changelog', 'pr-description']);
+check('det.git.text', catalogText().includes('git-facing') && catalogText().includes('pr-description'), true);
+check('det.git.json', JSON.parse(catalogJson()).git['commit-msg'].usage.includes('commit-msg.js'), true);
+// stdin catalog stays separate from the git list (routing must not mix them)
+check('det.git.notRoutable', CATALOG['commit-msg'], undefined);
+
+console.log(`ok — ${passed} checks passed`);
+
+// hunk-filter: keeps only matching hunks, drops non-matching files entirely
+{
+  const { filterHunks } = require('./hunk-filter');
+  const diff = [
+    'diff --git a/f.md b/f.md',
+    'index 111..222 100644',
+    '--- a/f.md',
+    '+++ b/f.md',
+    '@@ -1,2 +1,2 @@',
+    ' keep me',
+    '-old horizon line',
+    '+new horizon line',
+    '@@ -9,2 +9,2 @@',
+    ' other',
+    '-their churn',
+    '+their new churn',
+    ''
+  ].join('\n');
+  const filtered = filterHunks(diff, 'horizon');
+  assert.ok(filtered.includes('+new horizon line'), 'hunk-filter keeps matching hunk');
+  assert.ok(!filtered.includes('their churn'), 'hunk-filter drops non-matching hunk');
+  assert.ok(filtered.includes('diff --git a/f.md'), 'hunk-filter keeps file header');
+  assert.deepStrictEqual(filterHunks(diff, 'nomatch-xyz'), '', 'hunk-filter empty when nothing matches');
+  passed += 4;
+}