@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/base/hooks/lib/rust-scan.mjs

@@ -0,0 +1,139 @@
+// Rust's own reading (KWB-75). C's blanker takes a lifetime for a char literal and blanks the rest of its line, and a generic blanker takes '"' for a
+// string opening. Nested block comments and raw strings have no form in either. Offsets are kept, so a match's line is the file's line.
+//   blankRust(src)      comments go; a string or char literal keeps two quotes, so it stays one token
+//   withoutTests(code)  on blanked code: what `#[cfg(test)]` or a `#[test]` attribute marks goes too, since Rust's unit tests live in the file they test
+//   ownDefinitions(code)  on blanked code: tests, impls and traits go, leaving the free functions
+//   lookupMatches(text)  every `match` that is a table of literals on one enum, for dispatch-once
+const spaces = (s) => s.replace(/[^\n]/g, ' ');
+const quoted = (s) => (s.length >= 2 ? `"${spaces(s.slice(1, -1))}"` : spaces(s));
+
+function commentEnd(src, start) {
+  let depth = 1;
+  let i = start + 2;
+  while (i < src.length && depth > 0) {
+    if (src.startsWith('/*', i)) { depth += 1; i += 2; }
+    else if (src.startsWith('*/', i)) { depth -= 1; i += 2; }
+    else i += 1;
+  }
+  return i;
+}
+
+function stringEnd(src, start) {
+  let i = start + 1;
+  while (i < src.length && src[i] !== '"') i += src[i] === '\\' ? 2 : 1;
+  return Math.min(i + 1, src.length);
+}
+
+// r"..", r#".."#, br#".."#, cr#".."#: nothing inside escapes, and the hashes close it. Returns where the opening quote is, and the end, or null.
+function rawString(src, i) {
+  if (/\w/.test(src[i - 1] ?? '')) return null;
+  const open = src.slice(i, i + 80).match(/^(?:b|c)?r(#*)"/);
+  if (!open) return null;
+  const close = src.indexOf(`"${open[1]}`, i + open[0].length);
+  return { quote: i + open[0].length - 1, end: close === -1 ? src.length : close + 1 + open[1].length };
+}
+
+// A quote opens a char literal only when one character, or one escape, then closes it; otherwise it is a lifetime or a label.
+function charEnd(src, i) {
+  if (src[i + 1] === '\\') { const e = src.indexOf("'", i + 3); return e === -1 ? null : e + 1; }
+  const one = String.fromCodePoint(src.codePointAt(i + 1) ?? 32);
+  return src[i + 1 + one.length] === "'" ? i + 2 + one.length : null;
+}
+
+export function blankRust(src) {
+  let out = '';
+  let i = 0;
+  const take = (end, shown) => { out += shown(src.slice(i, end)); i = end; };
+  while (i < src.length) {
+    const raw = src[i] === 'r' || src[i] === 'b' || src[i] === 'c' ? rawString(src, i) : null;
+    const char = src[i] === "'" ? charEnd(src, i) : null;
+    if (src.startsWith('//', i)) { const e = src.indexOf('\n', i); take(e === -1 ? src.length : e, spaces); }
+    else if (src.startsWith('/*', i)) take(commentEnd(src, i), spaces);
+    else if (raw) { out += spaces(src.slice(i, raw.quote)); i = raw.quote; take(raw.end, quoted); }
+    else if (src[i] === '"') take(stringEnd(src, i), quoted);
+    else if (char) take(char, quoted);
+    else { out += src[i]; i += 1; }
+  }
+  return out;
+}
+
+const TEST_MARK = /#\[\s*(?:cfg\s*\(\s*(?:all\s*\(\s*)?test\b[^\]]*\)|(?:\w+::)*test\b[^\]]*)\s*\]/g;
+
+// The end of the item an attribute marks: its closing brace, or the `;` of an item with no body.
+function itemEnd(code, start) {
+  let round = 0;
+  for (let i = start; i < code.length; i += 1) {
+    const c = code[i];
+    if (c === '(' || c === '[') round += 1;
+    else if (c === ')' || c === ']') round -= 1;
+    else if (c === ';' && round === 0) return i + 1;
+    else if (c === '{' && round === 0) {
+      let depth = 0;
+      for (let j = i; j < code.length; j += 1) {
+        if (code[j] === '{') depth += 1;
+        else if (code[j] === '}' && --depth === 0) return j + 1;
+      }
+      return code.length;
+    }
+  }
+  return code.length;
+}
+
+function blankItems(code, mark) {
+  let out = '';
+  let at = 0;
+  for (const m of code.matchAll(mark)) {
+    if (m.index < at) continue;
+    const end = itemEnd(code, m.index + m[0].length);
+    out += code.slice(at, m.index) + spaces(code.slice(m.index, end));
+    at = end;
+  }
+  return out + code.slice(at);
+}
+
+export const withoutTests = (code) => blankItems(code, TEST_MARK);
+
+// A method lives in its type's namespace: `from_str` on a second type is the trait doing its job, and `is_none` on two types is two methods (KWB-81).
+// Only a free function can be made again by name. A method copied is caught by its statements, whatever it is called.
+const TYPE_ITEM = /^[ \t]*(?:pub(?:\([^)]*\))?\s+)?(?:unsafe\s+)?(?:impl|trait)\b[^{;]*(?=\{)/gm;
+export const ownDefinitions = (code) => blankItems(withoutTests(code), TYPE_ITEM);
+
+// What a `match` body holds, arm by arm: the patterns, and what the arm gives.
+function armsOf(body) {
+  const arms = [];
+  let depth = 0;
+  let from = 0;
+  let head = null;
+  for (let i = 0; i < body.length; i += 1) {
+    const c = body[i];
+    if ('({['.includes(c)) depth += 1;
+    else if (')}]'.includes(c)) depth -= 1;
+    else if (depth === 0 && head === null && body.startsWith('=>', i)) { head = body.slice(from, i); from = i + 2; i += 1; }
+    else if (depth === 0 && head !== null && c === ',') { arms.push({ head, value: body.slice(from, i).trim() }); head = null; from = i + 1; }
+  }
+  if (head !== null) arms.push({ head, value: body.slice(from).trim() });
+  return arms;
+}
+
+const LITERAL = /^(?:"\s*"|-?\d[\w.]*)$/; // a table of true and false is a predicate, not data about the kind
+const MIN_VARIANTS = 3;
+const NOT_A_KIND = new Set(['Self', 'Option', 'Result', 'Ordering']); // the standard library's own enums, and an enum inside its own impl
+
+// Every `match` that is only a lookup table: each variant of one enum to a plain value. `owned`: this file declares the enum or has its impl.
+// A match that does real work on an enum is good Rust, in any number of files: the compiler holds every one to every variant. A lookup table is
+// data about the kind, and belongs with the kind. Measured on eight crates: a rule on every match would have refused 7 to 12 in 100 of them.
+export function lookupMatches(text) {
+  const code = withoutTests(blankRust(text));
+  const owns = new Set([...code.matchAll(/\b(?:enum|impl(?:<[^>{]*>)?)\s+([A-Z]\w*)/g)].map((m) => m[1]));
+  const found = [];
+  for (const m of code.matchAll(/\bmatch\s[^{;]+?(?=\{)/g)) {
+    const open = m.index + m[0].length;
+    const arms = armsOf(code.slice(open + 1, itemEnd(code, open) - 1));
+    if (!arms.length || !arms.every((a) => LITERAL.test(a.value))) continue;
+    const paths = arms.flatMap((a) => [...a.head.matchAll(/\b([A-Z]\w*)::([A-Z]\w*)/g)]);
+    const kind = paths[0]?.[1];
+    const labels = new Set(paths.filter((p) => p[1] === kind).map((p) => p[2]));
+    if (kind && labels.size >= MIN_VARIANTS && !NOT_A_KIND.has(kind)) found.push({ kind, labels, owned: owns.has(kind) });
+  }
+  return found;
+}

package/packs/base/hooks/lib/secret-patterns.mjs

@@ -0,0 +1,18 @@
+// What a secret looks like: secrets-guard refuses these in a write, and the logs mask them, so a log can be read and shared.
+//   SECRETS: [[name, regex]]     maskSecrets(text) -> text with each one replaced by its name
+export const SECRETS = [
+  ['a GitHub token', /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,})/g],
+  ['an Anthropic key', /\bsk-ant-[A-Za-z0-9_-]{20,}/g],
+  ['an OpenAI key', /\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{32,}/g],
+  ['an AWS access key', /\bAKIA[0-9A-Z]{16}\b/g],
+  ['a Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/g],
+  ['a Stripe secret key', /\b[rs]k_live_[A-Za-z0-9]{20,}/g],
+  ['a private key', /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----\s+[A-Za-z0-9+/=\s]{64,}/g],
+  // A key's random part runs unbroken; a long identifier (`cap_Filter_Env_Attack_2`) is short words between underscores.
+  ['a prefixed API key', /\b(?!price_|prod_|pk_|[rs]k_live_|github_pat_|gh[pousr]_)(?=[a-z]{2,8}_)(?=[\w-]*[A-Z])(?=[\w-]*\d)(?=[a-z]{2,8}_[\w-]*?[A-Za-z0-9]{20})[a-z]{2,8}_[A-Za-z0-9_-]{24,}\b/g],
+  ['a connection string with its password', /\b(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|redis|amqp):\/\/[^\s:@/'"`]+:(?!\$\{|\$[A-Za-z_]|<|\*+@|[^\s@]*(?:[Pp]ass(?:word|wd)?|[Cc]hange|[Ee]xample|[Yy]our|[Ss]ecret|[Pp]laceholder|xxx|XXX))[^\s@/'"`]{3,}@/g],
+];
+
+const WORDS = /\b(password|passwd|secret|token|api[_-]?key)(\s*[=:]\s*)(['"]?)[^\s'"&]{4,}/gi;
+
+export const maskSecrets = (text) => SECRETS.reduce((t, [name, re]) => t.replace(re, `[${name}]`), String(text)).replace(WORDS, '$1$2$3[masked]');

package/packs/base/hooks/lib/selftest.mjs

@@ -0,0 +1,45 @@
+// What a hook's `--selftest` runs on: a throwaway project, the hook run the way Claude Code runs
+// it (payload on stdin, CLAUDE_PROJECT_DIR set) and its exit code judged. Every hook proves its
+// law this way, so nobody probes a hook by pasting payloads into a shell command, where a guard
+// that judges command text can refuse the probe itself (Sub37 WB-4). doctor runs every selftest.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const made = [];
+
+export const put = (file, text) => { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, text); };
+export const git = (cwd, ...a) => execFileSync('git', ['-c', 'user.email=selftest@local', '-c', 'user.name=selftest', ...a], { cwd, stdio: 'ignore' });
+
+// files: { "rel/path": "text" }; layout, when given, becomes .claude/layout.json.
+export function scratchProject(files = {}, layout = null) {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), 'cp-selftest-')));
+  made.push(dir);
+  if (layout) put(join(dir, '.claude/layout.json'), JSON.stringify(layout));
+  for (const [rel, text] of Object.entries(files)) put(join(dir, rel), text);
+  return dir;
+}
+
+// A hook event goes through run-hooks.mjs, the way settings.json runs every kit hook (KWB-24), so each selftest proves the
+// hook inside the runner; a by-hand mode (args, e.g. --init) runs the hook file itself.
+const RUNNER = fileURLToPath(new URL('../run-hooks.mjs', import.meta.url));
+export const runHook = (hook, dir, payload, args = []) =>
+  spawnSync(process.execPath, args.length || !existsSync(RUNNER) ? [hook, ...args] : [RUNNER, hook], {
+    cwd: dir, input: payload ? JSON.stringify(payload) : '', encoding: 'utf8',
+    env: { ...process.env, CLAUDE_PROJECT_DIR: dir },
+  }).status;
+
+export const writeOf = (file_path, content = '// new\n') => ({ tool_name: 'Write', tool_input: { file_path, content } });
+export const editOf = (file_path, old_string = 'a', new_string = 'b') => ({ tool_name: 'Edit', tool_input: { file_path, old_string, new_string } });
+export const bashOf = (command, cwd) => ({ tool_name: 'Bash', tool_input: { command }, ...(cwd ? { cwd } : {}) });
+
+// cases: [label, actual, wanted]. Prints "<name> selftest: OK (n cases)" or each failure; exit code.
+export function verdicts(name, cases) {
+  for (const dir of made.splice(0)) rmSync(dir, { recursive: true, force: true });
+  const bad = cases.filter(([, got, want]) => got !== want);
+  for (const [label, got, want] of bad) console.error(`${name} selftest FAILED: ${label} (got ${got}, wanted ${want})`);
+  if (!bad.length) console.log(`${name} selftest: OK (${cases.length} cases)`);
+  return bad.length ? 1 : 0;
+}

package/packs/base/hooks/lib/shape-code.mjs

@@ -0,0 +1,126 @@
+// shape-code: what the shape law reads in code beyond literal instances (lib/shape.mjs holds the number rule).
+//   findSelectorDefs(text, file, shape) -> [{ line, text, concept, name, why, kind: 'selector' }]
+//     a function whose name joins a concept word with pick/select/for/first/owner, defined here and not listed as a
+//     selector (or the generator, or a constant) of that concept in design/shape.json
+//   findUnknownTypes(text, file, shape) -> [{ line, text, concept: null, name, why, kind: 'type' }]
+//     a new class/struct/enum whose name holds no concept's word and that looks like an instance container (an index
+//     member, or it is made N times in an array): its concept has no row yet; a type in the manifest's "values" is skipped
+import { conceptOfName, parts, SHAPE_FILE } from './shape.mjs';
+
+export const CODE = /\.(c|cc|cpp|cxx|h|hh|hpp|hxx|inl|mm|m|js|mjs|cjs|ts|tsx|jsx|py|swift|rs|go|java|kt|cs)$/i;
+const KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'sizeof', 'else', 'new', 'delete', 'case', 'throw', 'co_return', 'do', 'function', 'await', 'typeof']);
+const PICKS = [(p) => p.startsWith('pick'), (p) => p.startsWith('select'), (p) => p.startsWith('owner') || p === 'owning', (p) => p === 'for', (p) => p === 'first'];
+const ITERATES = new Set(['each', 'all', 'every', 'count', 'num', 'size']);
+
+function definitions(text) {
+  const out = [];
+  const lines = text.split('\n');
+  const RES = [
+    /^\s*(?:(?:static|inline|constexpr|consteval|virtual|extern|friend|explicit|const|unsigned|signed|\[\[\w+\]\])\s+)*[A-Za-z_][\w:<>,*&]*\s*[*&]?\s+[*&]?([A-Za-z_]\w*)\s*\([^;{}]*\)\s*(?:const\s*)?(?:noexcept\s*)?(?:override\s*)?(?:->\s*[\w:<>*&\s]+)?\s*(?:\{|;|$)/,
+    /\bfunction\s*\*?\s*([A-Za-z_$][\w$]*)\s*\(/,
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/,
+    /^\s*(?:static\s+|async\s+|get\s+)*([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{/,
+    /^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/,
+    /^\s*(?:pub\s+)?fn\s+([A-Za-z_]\w*)\s*[<(]/,
+  ];
+  lines.forEach((l, i) => {
+    for (const re of RES) {
+      const m = l.match(re);
+      if (!m || KEYWORDS.has(m[1])) continue;
+      const first = l.trim().split(/\s+/)[0];
+      if (re === RES[0] && KEYWORDS.has(first)) continue;
+      out.push({ line: i + 1, text: l.trim(), name: m[1] });
+      break;
+    }
+  });
+  return out;
+}
+
+export function findSelectorDefs(text, file, shape) {
+  if (!shape || !CODE.test(file ?? '')) return [];
+  const out = [];
+  for (const d of definitions(text)) {
+    const ps = parts(d.name);
+    if (!PICKS.some((f) => ps.some(f)) || ps.some((p) => ITERATES.has(p))) continue;
+    const concept = conceptOfName(d.name, shape);
+    if (!concept) continue;
+    const c = shape.concepts[concept];
+    if (c.shape !== 'many' || c.selectors.includes(d.name) || c.constants.includes(d.name) || c.generatorName === d.name) continue;
+    const listed = c.selectors.length ? `call a listed one (${c.selectors.join(', ')}) or ` : '';
+    out.push({ ...d, concept, kind: 'selector', why: `defines ${d.name}, a selector for ${concept} that ${SHAPE_FILE} does not list — example, rule, or constant? (a rule is a named selector: ${listed}add "${d.name}": "<what it picks>" to the ${concept} row's selectors first)` });
+  }
+  return out;
+}
+
+function bodyOf(lines, i, python) {
+  if (python) {
+    const ind = lines[i].match(/^\s*/)[0].length;
+    const body = [];
+    for (let k = i + 1; k < lines.length && (lines[k].trim() === '' || lines[k].match(/^\s*/)[0].length > ind); k += 1) body.push(lines[k]);
+    return body.join('\n');
+  }
+  const rest = lines.slice(i).join('\n');
+  const open = rest.indexOf('{');
+  if (open < 0) return '';
+  let depth = 0;
+  for (let k = open; k < rest.length; k += 1) {
+    if (rest[k] === '{') depth += 1;
+    else if (rest[k] === '}' && --depth === 0) return rest.slice(open, k + 1);
+  }
+  return rest.slice(open);
+}
+
+const INDEX_MEMBER = [
+  /\b(?:int|size_t|std::size_t|unsigned|uint\w*|int\w*_t|short|long)\s+(?:index|idx|ix)\s*[;={]/,
+  /\b(?:int|size_t|std::size_t|unsigned|uint\w*|int\w*_t|short|long)\s+\w*(?:Index|Idx|Ix)\s*[;={]/,
+  /\b(?:this|self)\.(?:index|idx|ix|\w*(?:Index|Idx|Ix))\s*=/,
+  /^\s*(?:index|idx|ix|\w*(?:Index|Idx|Ix))\s*[:=]/m,
+];
+
+// The type is made N times, N a named count: an array of it (std::array, T name[N], a vector of N, Array.from, a list comprehension). An
+// array whose name or count holds a known concept word is that concept's (Box slot[4] is per slot, known); a table with a
+// filled-in initializer is data, not instances.
+function madeN(text, name, shape) {
+  const N = '([A-Za-z_]\\w*|\\d+)';
+  const res = [
+    new RegExp(`std::array\\s*<\\s*${name}\\s*,\\s*${N}\\s*>\\s*(\\w*)(\\s*=?\\s*\\{[^}]*)?`, 'g'),
+    new RegExp(`\\b${name}\\s+(?<arr>\\w+)\\s*\\[\\s*${N}\\s*\\](\\s*=?\\s*\\{[^}]*)?`, 'g'),
+    new RegExp(`std::vector\\s*<\\s*${name}\\s*>\\s*(\\w+)\\s*[({]\\s*${N}\\s*[)}]()`, 'g'),
+    new RegExp(`(\\w+)\\s*=\\s*Array\\.from\\(\\s*\\{\\s*length\\s*:\\s*${N}\\s*\\}[^)]*new\\s+${name}\\b()`, 'g'),
+    new RegExp(`(\\w+)\\s*=\\s*\\[\\s*${name}\\(.*\\)\\s+for\\s+\\w+\\s+in\\s+range\\(\\s*${N}\\s*\\)()`, 'g'),
+  ];
+  for (const re of res) {
+    for (const m of text.matchAll(re)) {
+      const [count, arr, init] = re === res[0] ? [m[1], m[2], m[3]] : re === res[1] ? [m[2], m[1], m[3]] : [m[2], m[1], m[3]];
+      if (/^\d+$/.test(count)) continue; // a literal size is a capacity or a fixed table; instances are counted by a named count
+      if (init && /\{\s*[^}\s]/.test(init)) continue; // a table of values
+      if (conceptOfName(arr ?? '', shape) || conceptOfName(count, shape)) continue;
+      return true;
+    }
+  }
+  return false;
+}
+
+export function findUnknownTypes(text, file, shape) {
+  if (!shape || !CODE.test(file ?? '')) return [];
+  const python = /\.py$/i.test(file);
+  const lines = text.split('\n');
+  const out = [];
+  lines.forEach((l, i) => {
+    const m = python ? l.match(/^\s*class\s+([A-Za-z_]\w*)/) : l.match(/\b(?:class|struct|enum(?:\s+class|\s+struct)?)\s+(?:\[\[\w+\]\]\s+)?(?:alignas\([^)]*\)\s+)?([A-Za-z_]\w*)\s*(?:final\s*)?(?:extends\s+[\w.]+\s*)?(?::[^;{]*)?(?:\{|$)/);
+    if (!m || /^\s*(?:\/\/|\*|#)/.test(l) || /\bfriend\b|\btemplate\s*<\s*class\b/.test(l)) return;
+    const name = m[1];
+    if (conceptOfName(name, shape) || shape.values?.has(name)) return; // a listed value type is not a container (KWB-10)
+    const body = bodyOf(lines, i, python);
+    const inArray = madeN(text, name, shape);
+    if (!INDEX_MEMBER.some((re) => re.test(body)) && !inArray) return;
+    out.push({ line: i + 1, text: l.trim(), concept: null, name, kind: 'type', why: `defines ${name}, a container of instances whose concept has no row in ${SHAPE_FILE} — add the row to ${SHAPE_FILE} first (one or many, its generator, its selectors), then build the type` });
+  });
+  return out;
+}
+
+// The definitions an edit adds: names defined after it that were not defined before it.
+export function addedDefs(before, after, find) {
+  const had = new Set(find(before ?? '').map((d) => d.name));
+  return find(after ?? '').filter((d) => !had.has(d.name));
+}

package/packs/base/hooks/lib/shape-lists.mjs

@@ -0,0 +1,31 @@
+// shape-lists: consecutive lines (or ;/, separated pieces of one line) that differ only in one number running over every instance: a hand-listed set, one line
+// per instance. Split out of shape.mjs at its line limit.
+//   handLists(lines, c, out, seen): adds a finding to out for each such set of the concept c
+import { classify, isExampleLine, named, parts } from './shape.mjs';
+
+const templatesOf = (t) => [...t.matchAll(/(?<![\w.])\d+(?![\w.])/g)].map((m) => ({ tpl: t.slice(0, m.index) + '#' + t.slice(m.index + m[0].length), v: Number(m[0]) }));
+
+export function handLists(lines, c, out, seen) {
+  if (!c.count || c.count < 2 || c.shape !== 'many') return;
+  const mentions = (t) => parts(t).some((p) => c.words.includes(p)) || c.arrays.some((a) => named(t, a));
+  const runOver = (pieces, at, whole = null) => {
+    for (let i = 0; i + c.count <= pieces.length; i += 1) {
+      for (const first of templatesOf(pieces[i].trim())) {
+        if (first.v > 1 || !mentions(whole ?? first.tpl)) continue;
+        let ok = true;
+        for (let k = 1; k < c.count && ok; k += 1) ok = templatesOf(pieces[i + k].trim()).some((t) => t.tpl === first.tpl && t.v === first.v + k);
+        if (ok) return at(i);
+      }
+    }
+    return null;
+  };
+  const lineNo = runOver(lines, (i) => i);
+  if (lineNo !== null && !isExampleLine(lines[lineNo]) && !seen.has(`${lineNo}|${c.name}`)) {
+    out.push({ line: lineNo + 1, text: lines[lineNo].trim(), concept: c.name, instance: 'each', why: `a hand-listed set, one line per ${c.name}: write one loop over every ${c.name}, or the generator` });
+  }
+  lines.forEach((l, i) => {
+    if (seen.has(`${i}|${c.name}`) || isExampleLine(l) || classify(l, c, null)) return;
+    const pieces = l.split(/[;,]/);
+    if (pieces.length >= c.count && runOver(pieces, () => true, l)) out.push({ line: i + 1, text: l.trim(), concept: c.name, instance: 'each', why: `a hand-listed set, one piece per ${c.name}: write one loop over every ${c.name}, or the generator` });
+  });
+}

package/packs/base/hooks/lib/shape-prose.mjs

@@ -0,0 +1,78 @@
+// shape-prose: what in a line is English, arithmetic or a name, and so names no instance (KF-13, KF-17, KF-20, KF-28, KF-36: 14 of shape-law's 25 refusals on the
+// MPX 500 were wrong, on words like these). Each test is narrow on purpose: the same line with the bare form stays refused (test/kf-refusals.test.mjs holds both).
+//   blankMessages(line, file) -> line with a sentence in a double-quoted string blanked, same length; a short key ("knob 1") stays
+//   isFirstMatch(line, m)    "the first program with this name", "each bank's first program", the words "first program" in quotes
+//   isSourceRole(line, m)    a comment quoting a role a source gives: "[MAN] Edit knob 1 selects"
+//   isKnownName(role, word, shape)   "EDIT knob", when editKnob is a concept or a listed selector
+//   isLongerName(line, end)  "MIDI Program Change": the word starts a longer proper name
+//   isSum(before)            "x + 1 == program": the number is an operand, not what is compared
+//   isLibraryCall(line, at, shape)   juce::MidiMessage::programChange (1, ...): a library's call, or one on a listed value type
+//   declaredAmount(root, name, text) a call whose declared first parameter is an amount: turnProgram (int steps, ...)
+import { execFileSync } from 'node:child_process';
+import { extname } from 'node:path';
+import { languageOf } from './languages.mjs';
+
+const SENTENCE_WORDS = 3;
+const LIBRARIES = new Set(['juce', 'std', 'boost', 'absl', 'Qt']);
+const AMOUNT = /^(?:steps?|detents?|clicks?|notches|ticks?|amount|delta|by|count|n|offset|increment|distance)$/i;
+const SOURCE_FILES = ['*.h', '*.hh', '*.hpp', '*.c', '*.cc', '*.cpp', '*.mm', '*.js', '*.mjs', '*.ts', '*.tsx', '*.py', '*.go', '*.rs', '*.java', '*.cs', '*.swift', '*.kt'];
+
+export function blankMessages(line, file) {
+  if (!languageOf(extname(file ?? ''))) return line;
+  return line.replace(/"(?:[^"\\]|\\.)*"/g, (s) => (s.trim().split(/\s+/).length >= SENTENCE_WORDS ? ' '.repeat(s.length) : s));
+}
+
+export function isFirstMatch(line, m) {
+  if (!/^first\b/i.test(m[0])) return false;
+  const before = line.slice(0, m.index);
+  const after = line.slice(m.index + m[0].length);
+  if (before.endsWith('"') && after.startsWith('"')) return true;
+  return /(?:'s|\b[Aa]|\b[Ee]ach|\b[Ee]very|\b[Aa]ny)\s+$/.test(before) || /^(?:'s)?\s+(?:with|that|which|whose|where|matching|found|a|an)\b/.test(after);
+}
+
+export function isSourceRole(line, m) {
+  const isComment = /^\s*(?:\/\/|\/\*|\*|#)/.test(line);
+  return isComment && /\[[A-Z]{2,6}\]/.test(line.slice(0, m.index)) && /^\s+[a-z]+s\b/.test(line.slice(m.index + m[0].length));
+}
+
+const named = new WeakMap();
+function namesOf(shape) {
+  if (!named.has(shape)) {
+    const rows = Object.values(shape.concepts);
+    named.set(shape, new Set(rows.flatMap((c) => [c.name, ...c.selectors, ...c.constants]).map((n) => n.toLowerCase())));
+  }
+  return named.get(shape);
+}
+export const isKnownName = (role, word, shape) => namesOf(shape).has(`${role}${word}`.toLowerCase());
+
+export const isLongerName = (line, end) => /^\s+[A-Z][a-z]/.test(line.slice(end));
+export const isSum = (before) => /[+\-*/%]\s*$/.test(before);
+
+export function isLibraryCall(line, at, shape) {
+  const path = line.slice(0, at).match(/([A-Za-z_]\w*)::(?:[A-Za-z_]\w*::)*$/);
+  if (!path) return false;
+  const last = line.slice(0, at).match(/([A-Za-z_]\w*)::$/)?.[1];
+  return LIBRARIES.has(path[1]) || shape.values?.has(last);
+}
+
+// The first parameter of each declaration of `name`, from the text being written and the project's files.
+function firstParameters(root, name, text) {
+  const shape = new RegExp(`\\b${name}\\s*\\(\\s*(?:const\\s+)?(?:[\\w:<>]+[\\s&*]+)+(\\w+)\\s*[,)=]`, 'g');
+  let found = '';
+  try {
+    found = execFileSync('git', ['-C', root, 'grep', '--untracked', '-hE', `\\b${name}[[:space:]]*\\(`, '--', ...SOURCE_FILES], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+  } catch {
+    found = ''; // no match, or no repository: nothing declares it, so the call stays an instance
+  }
+  return [...`${text}\n${found}`.matchAll(shape)].map((m) => m[1]);
+}
+
+const amounts = new Map();
+export function declaredAmount(root, name, text) {
+  const key = `${root}\0${name}`;
+  if (!amounts.has(key)) {
+    const params = firstParameters(root, name, text);
+    amounts.set(key, params.length > 0 && params.every((p) => AMOUNT.test(p)));
+  }
+  return amounts.get(key);
+}