@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,11 @@
+// What a reader reads as prose in a markdown file (0.15.0): frontmatter, fenced code, inline code, HTML comments, link targets and URLs
+// are blanked, line for line, so a check on public text never reads `npm test -- x` as a double dash. The same length and lines stay.
+const blank = (s) => s.replace(/[^\n]/g, ' ');
+
+export const blankProse = (text) => text
+  .replace(/^---\n[\s\S]*?\n---\n/, blank)
+  .replace(/^(```+|~~~+)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, blank)
+  .replace(/<!--[\s\S]*?-->/g, blank)
+  .replace(/`[^`\n]*`/g, blank)
+  .replace(/\]\([^)\n]*\)/g, blank)
+  .replace(/https?:\/\/\S+/g, blank);

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

@@ -0,0 +1,201 @@
+// pushed: what a repo holds that GitHub does not (KWB-26: eight kit branches lived on one machine only, and nothing said so).
+// git-guard reads it twice: before a `git commit` (the branch's earlier commits must be on GitHub; the first commit of a new
+// branch passes, the next waits for its push) and at Stop (no local branch may be ahead of GitHub or missing there).
+// GitHub's branch heads come from `git ls-remote --heads <remote>`: no objects are fetched and nothing local changes. The last
+// look is kept in the repo's git dir (claude-packs-heads.json) and only ever lets work through: a commit seen on GitHub stays
+// there (the house laws never force a push or delete a branch), so a commit or a Stop the last look already clears makes no
+// network call, however old the look. Anything it would refuse is looked up again live first, so a push made seconds
+// ago is seen at once. (Measured 2026-11-03 at load 27: a Stop the cache clears 0.3 s; a live look 4 to 7 s.)
+// A private GitHub repo needs the token: it is read from the environment or ~/.env (guards.git.tokenVar) and handed to git
+// as an Authorization header through the child's environment (GIT_CONFIG_COUNT/KEY/VALUE: never on its command line, so
+// never in ps); it is never written to a remote, a config or a file. Protocol v0 answers with every head in one request
+// with the header sent at once (measured 2026-11-03: 4 s against 12 s for v2 with a credential helper, GitHub slow).
+// GitHub out of reach (offline, no token): the caller lets the work through and says so.
+// A repo that pushes by URL only and has no remote (Stellix) names its GitHub repo in guards.git.repo ("owner/name", or a URL
+// or path); with neither, there is nothing to compare with and nothing is judged.
+//   remoteHeads(cwd, remote, { tokenVar, repo, live }) -> { url, heads: Map<branch, sha>, cached } | { url, error }
+//   forRepo(cwd, projectDir, cfg) -> cfg, without guards.git.repo when cwd is another repo
+//   unpushed(cwd, branch, cfg) -> null | { error } | { branch, remote, url, commits: [{ sha, subject }] }
+//   localBranches(cwd, cfg) -> null | { error } | [{ branch, url, missing, ahead }]   (only the ones not on GitHub)
+//   pushCommand(url, branches, cfg) -> the push form with the token named
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const CACHE = 'claude-packs-heads.json';
+
+const git = (cwd, args, env = {}, input = undefined) => {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', input, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], timeout: 15000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...env } });
+  } catch (e) {
+    return { error: (e.signal ? 'no answer in 15 s' : String(e.stderr ?? e.message).trim().split('\n').pop()) || 'git failed' };
+  }
+};
+const out = (r) => (typeof r === 'string' ? r.trim() : null);
+
+export function tokenFor(tokenVar) {
+  if (process.env[tokenVar]) return process.env[tokenVar];
+  try {
+    const m = readFileSync(join(homedir(), '.env'), 'utf8').match(new RegExp(`^\\s*(?:export\\s+)?${tokenVar}=(['"]?)(.*?)\\1\\s*$`, 'm'));
+    return m?.[2] || null;
+  } catch { return null; }
+}
+
+export const isGitHub = (url) => /^https:\/\/([^@/]+@)?github\.com\//.test(url ?? '');
+const cacheFile = (cwd) => { const d = out(git(cwd, ['rev-parse', '--git-common-dir'])); return d ? join(resolve(cwd, d), CACHE) : null; };
+const readCache = (file) => { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return {}; } };
+
+// the URL a remote name stands for, else the layout's repo
+export function urlOf(cwd, remote, { repo = null } = {}) {
+  const url = out(git(cwd, ['remote', 'get-url', remote]));
+  if (url || !repo) return url || null;
+  return /^(https?:|file:|\/)/.test(repo) ? repo : `https://github.com/${repo.replace(/\.git$/, '')}.git`;
+}
+
+export function remoteHeads(cwd, remote, { tokenVar = 'PERSONAL_GITHUB_TOKEN', repo = null, live = false, now = Date.now() } = {}) {
+  const url = urlOf(cwd, remote, { repo });
+  if (!url) return { url: null, error: `no remote named ${remote}` };
+  const file = cacheFile(cwd);
+  const cache = file ? readCache(file) : {};
+  const hit = cache[url];
+  if (!live && hit) return { url, heads: new Map(Object.entries(hit.heads)), cached: true };
+  const args = ['-c', 'protocol.version=0', 'ls-remote', '--heads', url];
+  let env = {};
+  const token = isGitHub(url) ? tokenFor(tokenVar) : null;
+  if (token) {
+    const basic = Buffer.from(`x-access-token:${token}`).toString('base64');
+    env = { GIT_CONFIG_COUNT: '2', GIT_CONFIG_KEY_0: 'http.extraHeader', GIT_CONFIG_VALUE_0: `Authorization: Basic ${basic}`, GIT_CONFIG_KEY_1: 'credential.helper', GIT_CONFIG_VALUE_1: '' };
+  }
+  const r = git(cwd, args, env);
+  if (typeof r !== 'string') return { url, error: r.error };
+  const heads = new Map(r.split('\n').filter(Boolean).map((l) => l.split('\t')).map(([sha, ref]) => [ref.replace(/^refs\/heads\//, ''), sha]));
+  if (file) { try { writeFileSync(file, JSON.stringify({ ...cache, [url]: { time: now, heads: Object.fromEntries(heads) } })); } catch { /* the check still holds */ } }
+  return { url, heads, cached: false };
+}
+
+// The remote a branch pushes to and its name there: its upstream, else origin and the same name.
+function target(cwd, branch) {
+  const remote = out(git(cwd, ['config', `branch.${branch}.remote`]));
+  const merge = out(git(cwd, ['config', `branch.${branch}.merge`]));
+  if (remote && remote !== '.') return { remote, name: merge ? merge.replace(/^refs\/heads\//, '') : branch };
+  return { remote: 'origin', name: branch };
+}
+
+// the heads whose commits this repo has (one git call for all of them: a call each took 20 s at load 27 on 28 branches)
+const known = (cwd, heads) => {
+  const shas = [...new Set(heads.values())];
+  const r = out(git(cwd, ['cat-file', '--batch-check'], {}, shas.join('\n') + '\n'));
+  return r === null ? [] : r.split('\n').filter((l) => / commit /.test(l)).map((l) => l.split(' ')[0]);
+};
+// commits on `ref` that no GitHub branch holds (only heads whose commits this repo has can be subtracted)
+const ownCommits = (cwd, ref, heads, have = known(cwd, heads)) => {
+  const r = out(git(cwd, ['log', '--format=%h %s', ref, '--not', ...have, '--']));
+  return r === null ? null : r.split('\n').filter(Boolean).map((l) => ({ sha: l.slice(0, l.indexOf(' ')), subject: l.slice(l.indexOf(' ') + 1) }));
+};
+
+// Looks with the cache first; anything it would refuse is looked up again live.
+function withHeads(cwd, remote, cfg, judge) {
+  let h = remoteHeads(cwd, remote, cfg);
+  if (h.error) return { error: `${h.url ?? remote} could not be reached (${h.error})` };
+  let found = judge(h);
+  if (found && h.cached) {
+    h = remoteHeads(cwd, remote, { ...cfg, live: true });
+    if (h.error) return { error: `${h.url} could not be reached (${h.error})` };
+    found = judge(h);
+  }
+  return found;
+}
+
+// guards.git.repo names the project's own repo: a command in another repo is not judged against it (KWB-48; it told a repo with
+// no remote to push its history into the project's repo). A worktree of the project shares its git dir, so it stays judged.
+export function forRepo(cwd, projectDir, cfg = {}) {
+  const common = (dir) => { const d = out(git(dir, ['rev-parse', '--git-common-dir'])); return d ? resolve(dir, d) : null; };
+  return cfg.repo && common(cwd) !== common(projectDir) ? { ...cfg, repo: null } : cfg;
+}
+
+export function unpushed(cwd, branch, cfg = {}) {
+  if (!branch || branch === 'HEAD' || out(git(cwd, ['rev-parse', '-q', '--verify', 'HEAD'])) === null) return null;
+  const { remote } = target(cwd, branch);
+  if (!urlOf(cwd, remote, cfg)) return null; // no remote and no guards.git.repo: nothing to compare with
+  return withHeads(cwd, remote, cfg, (h) => {
+    const commits = ownCommits(cwd, 'HEAD', h.heads);
+    return commits?.length ? { branch, remote, url: h.url, commits } : null;
+  });
+}
+
+export function localBranches(cwd, cfg = {}) {
+  // every branch, its commit and its upstream in one call
+  const r = out(git(cwd, ['for-each-ref', '--format=%(refname:short)%09%(objectname)%09%(upstream:remotename)%09%(upstream:remoteref)', 'refs/heads']));
+  if (r === null) return null;
+  const byRemote = new Map();
+  for (const [branch, sha, up, ref] of r.split('\n').filter(Boolean).map((l) => l.split('\t'))) {
+    if (cfg.trunkNeedsYes && (cfg.trunks ?? []).includes(branch)) continue; // only the owner pushes it
+    const remote = up && up !== '.' ? up : 'origin';
+    const name = up && up !== '.' && ref ? ref.replace(/^refs\/heads\//, '') : branch;
+    if (!byRemote.has(remote)) byRemote.set(remote, []);
+    byRemote.get(remote).push({ branch, sha, name });
+  }
+  const found = [];
+  for (const [remote, branches] of byRemote) {
+    if (!urlOf(cwd, remote, cfg)) continue;
+    const f = withHeads(cwd, remote, cfg, (h) => {
+      const off = [];
+      let have = null;
+      for (const { branch, sha: local, name } of branches) {
+        const sha = h.heads.get(name);
+        if (!sha) { off.push({ branch, url: h.url, missing: true }); continue; }
+        if (local === sha) continue;
+        have ??= known(cwd, h.heads);
+        const ahead = ownCommits(cwd, branch, h.heads, have)?.length ?? 0;
+        if (ahead) off.push({ branch, url: h.url, ahead });
+      }
+      return off.length ? off : null;
+    });
+    if (f?.error) return f;
+    if (f) found.push(...f);
+  }
+  return found;
+}
+
+// GitHub's push form, the token named and never stored; the repo is the remote's own name.
+// The owner an SSH GitHub URL names (git@github.com:Owner/repo.git, an ssh config alias git@github-<name>:Owner/..., or
+// ssh://git@github.com/Owner/...), else null. Over SSH the key picks the account, so the URL alone names the repo (KWB-39).
+export function sshOwner(url) {
+  return (url ?? '').match(/^(?:ssh:\/\/)?git@github(?:\.com|-[\w.-]+)[:/]([\w.-]+)\/[\w.-]+?(?:\.git)?\/?$/)?.[1] ?? null;
+}
+
+export function pushCommand(url, branches, { owner, tokenVar = 'PERSONAL_GITHUB_TOKEN' } = {}) {
+  if (owner && sshOwner(url) === owner) return `git push ${url} ${branches.join(' ')}`;
+  const m = (url ?? '').match(/github\.com[:/]([^/]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+  const repo = m ? `${m[1]}/${m[2]}` : `${owner ?? '<owner>'}/${(url ?? 'repo').split('/').pop().replace(/\.git$/, '')}`;
+  return `source ~/.env && git push https://x-access-token:$${tokenVar}@github.com/${repo}.git ${branches.join(' ')}`;
+}
+
+const NEVER_DELETE = 'A branch is never deleted, renamed or left behind to get past this: push it.';
+
+export function unpushedMessage(u, cfg = {}) {
+  const list = u.commits.slice(0, 8).map((c) => `    ${c.sha} ${c.subject}`).join('\n') + (u.commits.length > 8 ? `\n    ... ${u.commits.length - 8} more` : '');
+  return `${u.branch} has ${u.commits.length} commit(s) that are not on GitHub (${u.url}):\n${list}\n` +
+    `Every branch is pushed from its first commit (KWB-26): push, then commit:\n  ${pushCommand(u.url, [u.branch], cfg)}\n${NEVER_DELETE}`;
+}
+
+// Stop: -> { code, stdout, stderr }. Three refusals with the same list end the session, the list going to the user.
+export const MAX_SENDS = 3;
+export function stopVerdict(root, cfg = {}, session = 'session', stateDir = process.env.TMPDIR ?? '/tmp') {
+  const found = localBranches(root, cfg);
+  if (found?.error) return { code: 0, stdout: JSON.stringify({ systemMessage: `git-guard: GitHub was not checked at the end of this session: ${found.error}. Check by hand that every branch is pushed (KWB-26).` }) };
+  const file = join(stateDir, `git-guard-stop-${String(session).replace(/[^\w-]/g, '')}.json`);
+  if (!found?.length) { try { writeFileSync(file, '{}'); } catch { /* nothing to count */ } return { code: 0 }; }
+  const byUrl = new Map();
+  for (const f of found) byUrl.set(f.url, [...(byUrl.get(f.url) ?? []), f.branch]);
+  const text = `${found.length} local branch(es) are not on GitHub:\n` +
+    found.map((f) => `    ${f.branch}: ${f.missing ? 'not on GitHub at all' : `${f.ahead} commit(s) ahead of GitHub`}`).join('\n') +
+    `\nPush them before the session ends (KWB-26):\n${[...byUrl].map(([url, b]) => `  ${pushCommand(url, b, cfg)}`).join('\n')}\n${NEVER_DELETE}`;
+  let st = {};
+  try { st = JSON.parse(readFileSync(file, 'utf8')); } catch { /* first */ }
+  const count = st.text === text ? (st.count ?? 0) + 1 : 1;
+  try { writeFileSync(file, JSON.stringify({ text, count })); } catch { /* still refused */ }
+  if (count > MAX_SENDS) return { code: 0, stdout: JSON.stringify({ systemMessage: `git-guard refused the end of this session ${MAX_SENDS} times; it ends here for you to decide.\n${text}` }) };
+  return { code: 2, stderr: `git-guard: ${text}\n` };
+}

package/packs/base/hooks/lib/repo-index.mjs

@@ -0,0 +1,52 @@
+// What a checkout already holds, per file: its element shapes, its statements and its definitions, kept between calls in the temp folder and read
+// again only for a file whose time or size moved. template-law judges a write against it; reuse-hint shows it at the prompt.
+//   repoIndex(root, skipGlobs, layout) -> { rel: { m, s, shapes: [[id, line, what]], st: [[hash, line]], defs: [[name, line]] } }
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { extname, join } from 'node:path';
+import { isContent } from './content.mjs';
+import { MARKUP, codeFiles, shapesOf } from './elements.mjs';
+import { ALL_CODE } from './languages.mjs';
+import { definesOf, fingerprint } from './near-copies.mjs';
+
+export const EXTS = new Set([...ALL_CODE, ...MARKUP]);
+const GENERATED = /\b(?:auto-?generated|generated by|do not edit|@generated)\b/i;
+
+// A `one-off:` line covers what follows it, down to the next blank line.
+export function oneOffLines(text) {
+  const out = new Set();
+  let on = false;
+  text.split('\n').forEach((l, i) => { on = /one-off:/.test(l) || (on && l.trim() !== ''); if (on) out.add(i + 1); });
+  return out;
+}
+
+// One object set up twice is one object; a copy of a set-up has another receiver.
+const distinct = (list) => list.filter((s, i) => s.kind !== 'setup' || list.findIndex((x) => x.id === s.id && x.what === s.what) === i);
+
+// What a text holds, with its marked one-offs left out: all the law ever compares.
+export function readText(text, rel) {
+  if (GENERATED.test(text.slice(0, 400))) return { shapes: [], st: [], defs: [] };
+  const off = oneOffLines(text);
+  const ext = extname(rel);
+  const open = (list) => list.filter(([, line]) => !off.has(line));
+  return { shapes: distinct(shapesOf(text, ext).filter((s) => !off.has(s.line))), st: open(fingerprint(text, ext)), defs: open(definesOf(text, ext)) };
+}
+
+const fileOf = (root) => join(tmpdir(), `claude-packs-repo-${createHash('sha256').update(root).digest('hex').slice(0, 12)}.json`);
+
+export function repoIndex(root, skip, layout = {}) {
+  const file = fileOf(root);
+  let old = {};
+  try { old = JSON.parse(readFileSync(file, 'utf8')); } catch { /* the first call builds it */ }
+  const now = {};
+  for (const rel of codeFiles(root, skip, EXTS).filter((f) => !isContent(f, layout))) {
+    const st = statSync(join(root, rel));
+    const had = old[rel];
+    if (had && had.m === st.mtimeMs && had.s === st.size) { now[rel] = had; continue; }
+    const read = readText(readFileSync(join(root, rel), 'utf8'), rel);
+    now[rel] = { m: st.mtimeMs, s: st.size, shapes: read.shapes.map((x) => [x.id, x.line, x.what]), st: read.st, defs: read.defs };
+  }
+  try { writeFileSync(file, JSON.stringify(now)); } catch { /* an index that cannot be kept is built again */ }
+  return now;
+}

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));
+}