@arjunkhera/atlas 0.3.46 → 0.3.49

package/door/lib/owner-only.mjs

@@ -0,0 +1,778 @@
+// The owner-only reader. It answers one question for the gate and the review
+// job: which files of a diff must come to the owner, and why.
+//
+//   loadClasses()                     the package file owner-only.yaml, checked
+//   listPaths({ root, ref })          the floor, the named paths and the repo's list at ref
+//   classify({ root, base, head })    { owner, rows }: one row { path, class, cause } for each hit
+//   closure({ root })                 the files that the entry points of a repo load
+//
+// Rules that hold everywhere here (design: docs/design-docs/owner-only-list/):
+//
+// 1. The floor, the named paths and the repo's own list come from the base
+//    commit, never from the head. A pull request cannot take itself off.
+// 2. The reader reads text only. It never runs code from either commit.
+// 3. It fails closed. A changed path that no rule clears, and that is outside
+//    `product_paths:`, is owner-only.
+// 4. It reads the real bytes: no rename detection, no textconv, no external
+//    diff, and a .gitattributes `-diff` cannot hide a line.
+// 5. A path matches on whole folder names, with no case, after `./` and `..`
+//    are cleaned.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const LIST_FILE = join(HERE, '..', '..', 'owner-only.yaml');
+
+export const SIGN_TYPES = Object.freeze(['path', 'added_line', 'secret', 'json_keys', 'surface', 'schema', 'any_change']);
+const NETS = ['code', 'review'];
+
+export class OwnerOnlyError extends Error {
+  constructor(message) { super(message); this.name = 'OwnerOnlyError'; }
+}
+
+// Sources are written with a leading (?i), which JavaScript spells as a flag.
+export function compile(source, extra = '') {
+  const insensitive = source.startsWith('(?i)');
+  return new RegExp(insensitive ? source.slice(4) : source, `${insensitive ? 'i' : ''}${extra}`);
+}
+
+// ------------------------------------------------------------------ the file
+
+export function loadClasses(text = readFileSync(LIST_FILE, 'utf8')) {
+  const data = parseYaml(text, { strict: true });
+  if (!data || !Array.isArray(data.classes)) throw new OwnerOnlyError('owner-only.yaml: there is no list of classes');
+  const ids = data.classes.map((entry) => entry?.id);
+  const known = ['money', 'credentials', 'outside-visibility', 'lost-data', 'security', 'new-service', 'rule-book', 'direction'];
+  for (const id of ids) if (!known.includes(id)) throw new OwnerOnlyError(`owner-only.yaml: unknown class "${id}". The classes are ${known.join(', ')}.`);
+  for (const id of known) if (!ids.includes(id)) throw new OwnerOnlyError(`owner-only.yaml: the class "${id}" is missing`);
+  if (new Set(ids).size !== ids.length) throw new OwnerOnlyError('owner-only.yaml: a class appears twice');
+  const signIds = new Set();
+  for (const entry of data.classes) {
+    if (!Array.isArray(entry.examples) || entry.examples.length !== 2) throw new OwnerOnlyError(`owner-only.yaml: the class "${entry.id}" needs two examples`);
+    if (!Array.isArray(entry.net) || !entry.net.length || entry.net.some((net) => !NETS.includes(net))) throw new OwnerOnlyError(`owner-only.yaml: the class "${entry.id}" has no net; a net is code, review or both`);
+    const signs = entry.signs ?? [];
+    if (entry.net.includes('code') && !signs.length && !['repo', 'floor'].includes(entry.signs_from)) throw new OwnerOnlyError(`owner-only.yaml: the code class "${entry.id}" has no sign`);
+    for (const sign of signs) {
+      if (!SIGN_TYPES.includes(sign.type)) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" has the unknown type "${sign.type}"`);
+      if (signIds.has(sign.id)) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" appears twice`);
+      signIds.add(sign.id);
+      if (sign.type !== 'secret' && !(Array.isArray(sign.paths) && sign.paths.length)) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" has no paths`);
+      for (const key of ['pattern', 'line', 'part']) if (sign[key] !== undefined) compile(sign[key]);
+      if (sign.type === 'added_line' && !sign.pattern) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" has no pattern`);
+      if (sign.type === 'surface' && !sign.line) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" has no line pattern`);
+      if (sign.version_key !== undefined && (sign.type !== 'any_change' || typeof sign.version_key !== 'string' || !/^[A-Za-z_]+$/.test(sign.version_key))) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" has a bad version_key`);
+      if (sign.type === 'json_keys' && !(Array.isArray(sign.keys) && sign.keys.length)) throw new OwnerOnlyError(`owner-only.yaml: the sign "${sign.id}" has no keys`);
+    }
+  }
+  if (!Array.isArray(data.floor) || !data.floor.length) throw new OwnerOnlyError('owner-only.yaml: there is no floor');
+  for (const entry of data.floor) if (typeof entry?.path !== 'string' || typeof entry?.rule !== 'string') throw new OwnerOnlyError('owner-only.yaml: each floor entry needs a path and a rule');
+  return data;
+}
+
+// ------------------------------------------------------------------ paths
+
+// `./a/../b` becomes `b`. A path that climbs out of the repo is kept as it is,
+// and nothing matches it but the fail-closed rule.
+export function clean(path) {
+  const out = posix.normalize(String(path).replaceAll('\\', '/')).replace(/^\.\/+/, '').replace(/\/+$/, '');
+  return out === '.' ? '' : out;
+}
+
+const escape = (text) => text.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+
+// A pattern of owner-only.yaml or atlas.yaml. `**/` is any depth, `*` is one
+// name, `?` one character, and a trailing `/` is a folder. It matches with no
+// case and on whole names: `door/` never matches `door-x/`.
+export function matcher(pattern) {
+  const folder = pattern.endsWith('/');
+  const body = clean(pattern);
+  let out = '';
+  for (let index = 0; index < body.length; index += 1) {
+    const character = body[index];
+    if (body.startsWith('**/', index)) { out += '(?:.*/)?'; index += 2; continue; }
+    if (body.startsWith('**', index)) { out += '.*'; index += 1; continue; }
+    if (character === '*') { out += '[^/]*'; continue; }
+    if (character === '?') { out += '[^/]'; continue; }
+    out += escape(character);
+  }
+  const regex = new RegExp(`^${out}${folder ? '/.+' : '(?:/.+)?'}$`, 'i');
+  return (path) => regex.test(clean(path));
+}
+
+const matchesAny = (patterns, path) => (patterns ?? []).some((pattern) => matcher(pattern)(path));
+
+// ------------------------------------------------------------------ git
+
+function git(root, args, { allowFail = false } = {}) {
+  try {
+    return execFileSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], { encoding: 'buffer', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (error) {
+    if (allowFail) return null;
+    throw new OwnerOnlyError(`git ${args[0]} failed: ${String(error.stderr ?? error.message).trim().split('\n')[0]}`);
+  }
+}
+
+// The text of one file at a commit, or null when it is not there. `ref` null
+// reads the working tree.
+export function readAt(root, ref, path) {
+  if (ref === null) {
+    const full = join(root, path);
+    try { return statSync(full).isFile() ? readFileSync(full, 'utf8') : null; } catch { return null; }
+  }
+  const out = git(root, ['cat-file', 'blob', `${ref}:${path}`], { allowFail: true });
+  return out === null ? null : out.toString('utf8');
+}
+
+// Every entry of the tree at a commit: { path, mode }.
+export function treeAt(root, ref) {
+  if (ref === null) return walk(root).map((path) => ({ path, mode: '100644' }));
+  const out = git(root, ['ls-tree', '-r', '-z', '--full-tree', ref]).toString('utf8');
+  return out.split('\0').filter(Boolean).map((line) => {
+    const tab = line.indexOf('\t');
+    const [mode] = line.slice(0, tab).split(' ');
+    return { path: line.slice(tab + 1), mode };
+  });
+}
+
+function walk(root, prefix = '') {
+  const out = [];
+  for (const name of readdirSync(join(root, prefix)).sort()) {
+    if (name === '.git' || name === 'node_modules') continue;
+    const rel = prefix ? `${prefix}/${name}` : name;
+    let stat;
+    try { stat = statSync(join(root, rel)); } catch { continue; }
+    if (stat.isDirectory()) out.push(...walk(root, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+// Each changed path, from the raw diff: { status, path, oldMode, newMode }.
+// Rename detection is off, so a move is a delete of the old path and an add of
+// the new one, and both reach the rules.
+export function changedPaths(root, base, head) {
+  const out = git(root, ['diff', '--raw', '-z', '--no-renames', '--no-ext-diff', '--no-textconv', base, head]).toString('utf8');
+  const fields = out.split('\0');
+  const rows = [];
+  for (let index = 0; index < fields.length - 1; index += 2) {
+    const meta = fields[index];
+    if (!meta.startsWith(':')) { index -= 1; continue; }
+    const [oldMode, newMode, , , status] = meta.slice(1).split(' ');
+    rows.push({ status, path: fields[index + 1], oldMode, newMode });
+  }
+  return rows;
+}
+
+// The added and removed lines of one file, from the real bytes.
+export function lineChanges(root, base, head, path) {
+  const out = git(root, ['diff', '--no-renames', '--text', '--no-textconv', '--no-ext-diff', '--no-color', '-U0', base, head, '--', path]).toString('utf8');
+  const added = [], removed = [];
+  // The header lines (`+++ b/path`, `--- a/path`) come before the first hunk.
+  // Inside a hunk, an added line that starts with `++` is still an added line.
+  let inHunk = false;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('diff --git ')) { inHunk = false; continue; }
+    if (line.startsWith('@@')) { inHunk = true; continue; }
+    if (!inHunk) continue;
+    if (line.startsWith('+')) added.push(line.slice(1));
+    else if (line.startsWith('-')) removed.push(line.slice(1));
+  }
+  return { added, removed };
+}
+
+// ------------------------------------------------------------------ atlas.yaml
+
+function readYaml(text) {
+  if (text === null) return { data: null, error: null };
+  try { return { data: parseYaml(text, { strict: true }), error: null }; } catch (error) { return { data: null, error: error.message }; }
+}
+
+export function repoFacts(root, ref) {
+  const { data } = readYaml(readAt(root, ref, 'atlas.yaml'));
+  const facts = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  const list = Array.isArray(facts.owner_only) ? facts.owner_only.filter((entry) => entry && typeof entry.path === 'string') : [];
+  const product = Array.isArray(facts.product_paths) ? facts.product_paths.filter((entry) => typeof entry === 'string') : null;
+  return { facts, list, product };
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// The key rule for atlas.yaml. It returns the reason the change is owner-only,
+// or null when the change only adds entries under an add-only key.
+export function atlasYamlCause(baseText, headText, rules) {
+  if (baseText === headText) return null;
+  const base = readYaml(baseText), head = readYaml(headText);
+  if (base.error || head.error) return 'atlas.yaml cannot be read in strict mode';
+  if (baseText === null || headText === null) return 'atlas.yaml added or removed';
+  const a = base.data ?? {}, b = head.data ?? {};
+  const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])];
+  const changed = keys.filter((key) => !same(a[key], b[key]));
+  if (!changed.length) return 'atlas.yaml text changed outside its keys';
+  for (const key of changed) {
+    if (rules.fixed.includes(key)) return `atlas.yaml key ${key} changed`;
+    if (!rules.add_only.includes(key)) return `atlas.yaml key ${key} changed, and R62 does not list it yet`;
+    if (!onlyAdds(a[key], b[key])) return `atlas.yaml key ${key}: an entry was removed, moved or changed`;
+  }
+  return null;
+}
+
+function onlyAdds(before, after) {
+  if (before === undefined || before === null) return true;
+  if (Array.isArray(before)) return Array.isArray(after) && after.length >= before.length && before.every((entry, index) => same(entry, after[index]));
+  if (typeof before === 'object') return after && typeof after === 'object' && !Array.isArray(after) && Object.keys(before).every((key) => same(before[key], after[key])) && same(Object.keys(before), Object.keys(after).slice(0, Object.keys(before).length));
+  return false;
+}
+
+// ------------------------------------------------------------------ named paths
+
+const NAME_FORMS = [
+  /(?:^|\s)@([A-Za-z0-9_.~\-/]+[A-Za-z0-9_\-])/g,            // @ import
+  /\]\(\s*<?([^)\s>#]+)/g,                                   // Markdown link
+];
+
+// The repo paths that one text names, by the three forms. A name is read from
+// the folder of the file that names it, and from the repo root. `imports`
+// keeps only the @ import form.
+export function namesIn(text, fromFile, exists, { imports = false } = {}) {
+  const found = new Set();
+  const folder = posix.dirname(fromFile);
+  const words = [];
+  for (const form of imports ? NAME_FORMS.slice(0, 1) : NAME_FORMS) for (const match of text.matchAll(form)) words.push(match[1]);
+  // A command in backticks, such as `bash scripts/cloud/session.sh`, names
+  // each of its words.
+  if (!imports) for (const match of text.matchAll(/`([^`\n]+)`/g)) words.push(...match[1].split(/\s+/));
+  for (const word of words) {
+    const raw = word.replace(/[.,;:]+$/, '');
+    if (/^[a-z]+:\/\//i.test(raw) || raw.startsWith('#') || raw.startsWith('$') || raw.includes('*')) continue;
+    const candidates = [clean(posix.join(folder, raw)), clean(raw.replace(/^\/+/, ''))];
+    // Both readings count when both files are there, so the reader fails
+    // closed.
+    for (const candidate of candidates) {
+      if (candidate && !candidate.startsWith('..') && exists(candidate)) found.add(candidate);
+    }
+  }
+  return [...found];
+}
+
+// A name joins the floor when it is an instruction, a setting or a script:
+// a doc, a data file, a shell script, a file with no extension, or a file in
+// a scripts/ or bin/ folder. A source file that a rule only points at, such
+// as `src/db.ts`, is product code and stays off the floor.
+const isInstruction = (path) => /\.(md|markdown|mdx|txt|ya?ml|json|toml|sh|bash)$/i.test(path) || !/\.[A-Za-z0-9]+$/.test(posix.basename(path)) || /(^|\/)(scripts|bin)\//i.test(path);
+
+const isText = (path) => /\.(md|markdown|txt|ya?ml|json)$/i.test(path) || !/\.[A-Za-z0-9]+$/.test(posix.basename(path));
+
+// The plugin roots that a marketplace file or a plugin.json names.
+function pluginRoots(tree, read) {
+  const roots = new Set();
+  for (const { path } of tree) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith('.claude-plugin/plugin.json')) roots.add(clean(posix.dirname(posix.dirname(path))));
+    if (lower.endsWith('.claude-plugin/marketplace.json')) {
+      let data = null;
+      try { data = JSON.parse(read(path) ?? 'null'); } catch { data = null; }
+      const base = clean(posix.dirname(posix.dirname(path)));
+      // `metadata.pluginRoot` is a folder put in front of each plain source.
+      // Both readings count, so a root is never missed.
+      const prefix = typeof data?.metadata?.pluginRoot === 'string' ? data.metadata.pluginRoot : null;
+      for (const plugin of data?.plugins ?? []) {
+        const source = typeof plugin?.source === 'string' ? plugin.source : null;
+        if (!source || /^[a-z]+:\/\//i.test(source)) continue;
+        roots.add(clean(posix.join(base, source)));
+        if (prefix) roots.add(clean(posix.join(base, prefix, source)));
+      }
+    }
+  }
+  return [...roots];
+}
+
+// ------------------------------------------------------------------ the list
+
+// Every rule that holds at a commit: the floor, the plugin roots, the named
+// paths and the repo's own list. Each rule: { pattern, class, cause, except,
+// version_only_exempt, atlas_yaml }. `named` holds exact paths.
+export function rulesAt({ root, ref, classes = loadClasses() }) {
+  const tree = treeAt(root, ref);
+  const files = new Set(tree.map((entry) => entry.path));
+  const folders = new Set();
+  for (const path of files) { let at = posix.dirname(path); while (at !== '.' && !folders.has(at)) { folders.add(at); at = posix.dirname(at); } }
+  const exists = (path) => files.has(path) || folders.has(path);
+  const read = (path) => readAt(root, ref, path);
+  const rules = [];
+  for (const entry of classes.floor) {
+    rules.push({ pattern: entry.path, class: 'rule-book', cause: `floor: ${entry.rule}`, version_only_exempt: entry.version_only_exempt === true, atlas_yaml: entry.path === 'atlas.yaml', follow: entry.follow === true });
+  }
+  for (const pluginRoot of pluginRoots(tree, read)) {
+    for (const part of ['skills/', 'agents/', 'hooks/', 'commands/', '.mcp.json', '.claude-plugin/']) {
+      const pattern = pluginRoot ? `${pluginRoot}/${part}` : part;
+      rules.push({ pattern, class: 'rule-book', cause: `floor: plugin root ${pluginRoot || '.'}`, follow: part !== '.claude-plugin/' });
+    }
+  }
+  // Each script that a session start runs: the hook commands of the root
+  // settings and of each plugin root.
+  for (const { path, from } of hookScripts([''].concat(pluginRoots(tree, read)), read, (path) => files.has(path)).scripts) {
+    rules.push({ pattern: path, class: 'rule-book', cause: `floor: a session start runs it (${from})` });
+  }
+  // Names, followed from file to file, out of every floor file. The entry map
+  // is exempt: it is not on the floor for what only it names, and the reader
+  // does not follow names out of it.
+  const entryMap = clean(classes.entry_map ?? 'docs/index.md');
+  const floorMatch = (path) => rules.some((rule) => matcher(rule.pattern)(path));
+  const followed = rules.filter((rule) => rule.follow);
+  const seeds = [...files].filter((path) => followed.some((rule) => matcher(rule.pattern)(path)) && isText(path));
+  const named = new Map();
+  // Names are followed two steps: a file that a floor file names, and a file
+  // that such a file names. The other floor areas (archive/, docs/intake/, the
+  // locked design, atlas/) are history and facts, so no name is read out of
+  // them.
+  const stops = rules.filter((rule) => !rule.follow);
+  // A name is read from the folder of the file that names it first, then from
+  // the repo root. A nested entry file, such as src/CLAUDE.md, that says
+  // `bash scripts/check.sh` can mean a root script, so both count.
+  const queue = seeds.map((path) => ({ path, depth: 0 }));
+  const seen = new Set(seeds);
+  while (queue.length) {
+    const { path: from, depth } = queue.shift();
+    const text = read(from);
+    if (text === null) continue;
+    for (const name of namesIn(text, from, exists)) {
+      // A named folder is not followed: "the package lives in packages/atlas/"
+      // names a place, not a file of instructions.
+      for (const target of files.has(name) ? [name] : []) {
+        // The entry map is exempt by whichever file names it. "List the doc in
+        // docs/index.md" asks for an edit of the index; it does not make the
+        // index a file of instructions. Each new doc edits it, and a new doc
+        // that does not ship may merge alone.
+        if (target.toLowerCase() === entryMap.toLowerCase()) continue;
+        if (!isInstruction(target)) continue;
+        if (!named.has(target) && !floorMatch(target)) named.set(target, from);
+        const stop = stops.some((rule) => matcher(rule.pattern)(target));
+        if (!seen.has(target) && isText(target) && !stop && depth < 1) { seen.add(target); queue.push({ path: target, depth: depth + 1 }); }
+      }
+    }
+  }
+  // An @ import loads into every session, and Claude Code follows imports up
+  // to five steps deep, through any file, the entry map too. So each import
+  // chain from an entry file is on the floor, to that depth.
+  const importQueue = seeds.map((path) => ({ path, depth: 0 }));
+  const imported = new Set(seeds);
+  while (importQueue.length) {
+    const { path: from, depth } = importQueue.shift();
+    if (depth >= 5) continue;
+    const text = read(from);
+    if (text === null) continue;
+    for (const target of namesIn(text, from, exists, { imports: true })) {
+      if (!files.has(target) || imported.has(target)) continue;
+      imported.add(target);
+      if (!named.has(target) && !floorMatch(target)) named.set(target, `${from} (an @ import)`);
+      if (isText(target)) importQueue.push({ path: target, depth: depth + 1 });
+    }
+  }
+  for (const [path, from] of [...named].sort()) rules.push({ pattern: path, class: 'rule-book', cause: `floor: named in ${from}` });
+  const { list, product } = repoFacts(root, ref);
+  for (const entry of list) rules.push({ pattern: entry.path, class: entry.class, cause: `list: ${entry.path}`, except: Array.isArray(entry.except) ? entry.except : [] });
+  return { rules, product, tree };
+}
+
+const ruleHits = (rule, path) => matcher(rule.pattern)(path) && !matchesAny(rule.except, path);
+
+export function listPaths({ root, ref = 'HEAD', classes = loadClasses() }) {
+  const { rules, product } = rulesAt({ root, ref, classes });
+  return { rows: rules.map((rule) => ({ path: rule.pattern, class: rule.class, cause: rule.cause, except: rule.except ?? [] })), product_paths: product };
+}
+
+// Does a path sit under the floor or the repo's list at that commit?
+export function onList(rules, path) {
+  return rules.find((rule) => ruleHits(rule, path)) ?? null;
+}
+
+// ------------------------------------------------------------------ signs
+
+// True when two JSON texts differ only in the value of one top-level key,
+// line for line. A release moves `version` in package.json and plugin.json,
+// and `atlas` in the kit manifest.
+function versionOnly(baseText, headText, key = 'version') {
+  let a, b;
+  try { a = strictJson(baseText); b = strictJson(headText); } catch { return false; }
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) || Array.isArray(b)) return false;
+  const { [key]: va, ...ra } = a, { [key]: vb, ...rb } = b;
+  if (typeof va !== 'string' || typeof vb !== 'string' || va === vb || !same(sorted(ra), sorted(rb))) return false;
+  const lines = (text) => text.split('\n');
+  const x = lines(baseText), y = lines(headText);
+  if (x.length !== y.length) return false;
+  const keyLine = new RegExp(`^\\s*"${key}"\\s*:`);
+  return x.every((line, index) => line === y[index] || (keyLine.test(line) && keyLine.test(y[index])));
+}
+
+function sorted(value) {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]));
+  return value;
+}
+
+// JSON.parse keeps the last of two equal keys. Refuse them, so that two
+// readers never see two different files.
+function strictJson(text) {
+  if (text === null) return null;
+  const keys = /"((?:[^"\\]|\\.)*)"\s*:/g;
+  const stack = [];
+  let depth = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (character === '"') {
+      keys.lastIndex = index;
+      const match = keys.exec(text);
+      if (match && match.index === index) {
+        const set = stack[depth - 1];
+        if (set) { if (set.has(match[1])) throw new Error(`the key "${match[1]}" appears twice`); set.add(match[1]); }
+        index = match.index + match[0].length - 1;
+        continue;
+      }
+      const end = /"((?:[^"\\]|\\.)*)"/y; end.lastIndex = index; const string = end.exec(text);
+      index = string ? index + string[0].length - 1 : index;
+      continue;
+    }
+    if (character === '{') { stack[depth] = new Set(); depth += 1; }
+    else if (character === '[') { stack[depth] = null; depth += 1; }
+    else if (character === '}' || character === ']') depth -= 1;
+  }
+  return JSON.parse(text);
+}
+
+function surfaceLost(sign, baseText, headText) {
+  if (baseText === null) return null;
+  const line = compile(sign.line);
+  const part = sign.part ? compile(sign.part, 'g') : null;
+  const read = (text) => {
+    const out = new Map();
+    for (const row of (text ?? '').split('\n')) {
+      const match = line.exec(row);
+      if (!match) continue;
+      const parts = part ? [...row.slice(match.index + match[0].indexOf(match[1]) + match[1].length).matchAll(part)].map((hit) => hit[1]) : [];
+      out.set(match[1], new Set([...(out.get(match[1]) ?? []), ...parts]));
+    }
+    return out;
+  };
+  const before = read(baseText), after = read(headText);
+  for (const [key, parts] of before) {
+    if (!after.has(key)) return `${key} removed`;
+    for (const name of parts) if (!after.get(key).has(name)) return `${key} lost ${name}`;
+  }
+  return null;
+}
+
+function flatten(value, prefix = '', out = { keys: new Set(), enums: new Set(), required: new Set() }) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => flatten(entry, `${prefix}[${entry && typeof entry === 'object' && typeof entry.name === 'string' ? entry.name : index}]`, out));
+    return out;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, entry] of Object.entries(value)) {
+      const at = `${prefix}.${key}`;
+      out.keys.add(at);
+      if ((key === 'enum') && Array.isArray(entry)) for (const option of entry) out.enums.add(`${at}=${JSON.stringify(option)}`);
+      if ((key === 'required' || key === '$required') && Array.isArray(entry)) { for (const name of entry) out.required.add(`${at}=${name}`); continue; }
+      flatten(entry, at, out);
+    }
+  }
+  return out;
+}
+
+function schemaNarrowed(baseText, headText) {
+  let a, b;
+  try { a = flatten(strictJson(baseText)); b = flatten(strictJson(headText)); } catch { return 'the schema cannot be read'; }
+  for (const key of a.keys) if (!b.keys.has(key)) return `field ${key} removed`;
+  for (const option of a.enums) if (!b.enums.has(option)) return `enum value ${option} removed`;
+  for (const name of b.required) if (!a.required.has(name)) return `required field ${name} added`;
+  return null;
+}
+
+const versionOf = (path) => (/(\d+)\.(\d+)\.(\d+)/.exec(posix.basename(path)) ?? []).slice(1).map(Number);
+const newer = (a, b) => { const x = versionOf(a), y = versionOf(b); for (let i = 0; i < 3; i += 1) if ((x[i] ?? -1) !== (y[i] ?? -1)) return (x[i] ?? -1) > (y[i] ?? -1); return a > b; };
+const newest = (paths) => paths.reduce((best, path) => (best === null || newer(path, best) ? path : best), null);
+
+// ------------------------------------------------------------------ classify
+
+export function classify({ root, base, head, classes = loadClasses() }) {
+  const { rules, product, tree: baseTree } = rulesAt({ root, ref: base, classes });
+  const headTree = treeAt(root, head);
+  const changes = changedPaths(root, base, head);
+  const rows = [];
+  const add = (path, klass, cause) => { if (!rows.some((row) => row.path === path && row.cause === cause)) rows.push({ path, class: klass, cause }); };
+  const signs = classes.classes.flatMap((entry) => (entry.signs ?? []).map((sign) => ({ ...sign, class: entry.id })));
+  const secrets = SECRET_PATTERNS.map((pattern) => ({ id: pattern.id, regex: compile(pattern.source) }));
+
+  for (const change of changes) {
+    const { path } = change;
+    const hits = [];
+    // A symlink or a submodule can point anywhere, so it always comes to the owner.
+    if ([change.oldMode, change.newMode].includes('120000')) hits.push(['rule-book', 'a symlink changed']);
+    if ([change.oldMode, change.newMode].includes('160000')) hits.push(['rule-book', 'a submodule changed']);
+
+    const baseText = change.status === 'A' ? null : readAt(root, base, path);
+    const headText = change.status === 'D' ? null : readAt(root, head, path);
+    // A manifest whose version alone changed is a release, and the owner took
+    // releases off the list. The exemption holds for every rule on that path.
+    const release = change.status === 'M' && rules.some((rule) => rule.version_only_exempt && ruleHits(rule, path)) && versionOnly(baseText, headText);
+    // The kit manifest keeps its version under "atlas". A move of that key
+    // alone skips the kit-manifest sign and the repo's own list, never the
+    // floor.
+    const kitRelease = change.status === 'M' && signs.some((sign) => sign.version_key && matchesAny(sign.paths, path) && versionOnly(baseText, headText, sign.version_key));
+    for (const rule of release ? [] : rules) {
+      if (!ruleHits(rule, path)) continue;
+      if (kitRelease && rule.cause.startsWith('list: ')) continue;
+      if (rule.atlas_yaml) {
+        const cause = atlasYamlCause(baseText, headText, classes.atlas_yaml);
+        if (cause) hits.push([rule.class, `floor: ${cause}`]);
+        else hits.push([null, 'cleared']);
+        continue;
+      }
+      hits.push([rule.class, rule.cause]);
+    }
+
+    let lines = null;
+    const changesOf = () => (lines ??= lineChanges(root, base, head, path));
+    for (const sign of signs) {
+      if (sign.type !== 'secret' && !matchesAny(sign.paths, path)) continue;
+      const cause = `sign: ${sign.id}`;
+      if (kitRelease && sign.version_key) continue;
+      if (sign.type === 'path' || sign.type === 'any_change') hits.push([sign.class, cause]);
+      else if (sign.type === 'secret') {
+        const found = secrets.find((pattern) => changesOf().added.some((line) => pattern.regex.test(line)));
+        if (found) hits.push([sign.class, `${cause} (${found.id})`]);
+      } else if (sign.type === 'added_line') {
+        const regex = compile(sign.pattern);
+        if (changesOf().added.some((line) => regex.test(line))) hits.push([sign.class, cause]);
+      } else if (sign.type === 'json_keys') {
+        let a = null, b = null;
+        try { a = strictJson(baseText) ?? {}; b = strictJson(headText) ?? {}; } catch { hits.push([sign.class, `${cause} (the file cannot be read)`]); continue; }
+        const key = sign.keys.find((name) => !same(sorted(a[name]), sorted(b[name])));
+        if (key) hits.push([sign.class, `${cause} (${key})`]);
+      } else if (sign.type === 'surface') {
+        const lost = surfaceLost(sign, baseText, headText);
+        if (lost) hits.push([sign.class, `${cause} (${lost})`]);
+      } else if (sign.type === 'schema') {
+        const pick = (tree) => newest(tree.map((entry) => entry.path).filter((name) => matchesAny(sign.paths, name)));
+        const before = pick(baseTree), after = pick(headTree);
+        if (path !== before && path !== after) continue;
+        if (before === null) continue;
+        const narrowed = after === null ? 'the schema file is gone' : schemaNarrowed(readAt(root, base, before), readAt(root, head, after));
+        if (narrowed) hits.push([sign.class, `${cause} (${narrowed})`]);
+      }
+    }
+
+    const owner = hits.filter(([klass]) => klass !== null);
+    for (const [klass, cause] of owner) add(path, klass, cause);
+    const cleared = hits.some(([klass]) => klass === null);
+    if (!owner.length && !cleared && !(product && matchesAny(product, path))) {
+      add(path, null, product ? 'outside product_paths' : 'the repo names no product_paths');
+    }
+  }
+  return { owner: rows.length > 0, rows };
+}
+
+// ------------------------------------------------------------------ closure
+
+// The entry points of a repo: each script that a workflow step, a session hook
+// or an MCP server runs. Then every file that they load, by a static import or
+// a fixed relative path that the code opens. A step that names a file that is
+// not there is an error, so the closure cannot miss a script quietly.
+const RUNS = /\b(?:node|bash|sh)\s+((?:--?[A-Za-z][\w-]*(?:=\S+)?\s+)*)([^\s'"|;&)]+)/g;
+
+// The shell text of a workflow: each `run:` value, inline or as a block.
+// Comments and every other key are left out.
+export function runText(yaml) {
+  const out = [];
+  const lines = yaml.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = /^(\s*)(?:-\s+)?run:\s*(.*)$/.exec(lines[index]);
+    if (!match) continue;
+    const rest = match[2].trim();
+    if (rest && !/^[|>][-+]?$/.test(rest)) { out.push(rest); continue; }
+    const indent = match[1].length;
+    while (index + 1 < lines.length && (lines[index + 1].trim() === '' || lines[index + 1].length - lines[index + 1].trimStart().length > indent)) {
+      index += 1;
+      const line = lines[index].trim();
+      if (line && !line.startsWith('#')) out.push(line);
+    }
+  }
+  return out.join('\n');
+}
+
+// The scripts that the hook commands of each root run. `read` reads a file,
+// `exists` says whether a path is there. A command that names a script that
+// is not there is an error.
+export function hookScripts(roots, read, exists) {
+  const scripts = [], errors = [];
+  const under = (pluginRoot, name) => (pluginRoot ? `${pluginRoot}/${name}` : name);
+  const parse = (file) => {
+    const text = read(file);
+    if (text === null) return undefined;
+    try { return JSON.parse(text); } catch { errors.push(`${file} cannot be read`); return undefined; }
+  };
+  // One command line, split into words. "$CLAUDE_PROJECT_DIR"/hooks/x.sh and
+  // ${CLAUDE_PLUGIN_ROOT}/x.mjs both name a repo file. Quotes may sit inside
+  // the word.
+  const take = (command, pluginRoot, from) => {
+    for (const word of String(command).split(/\s+/)) {
+      const bare = word.replace(/["']/g, '');
+      const path = clean(bare.replace(/\$\{?CLAUDE_PLUGIN_ROOT\}?/g, pluginRoot || '.').replace(/\$\{?CLAUDE_PROJECT_DIR\}?/g, '.'));
+      const script = /\.(m?js|cjs|sh|bash|py)$/.test(path);
+      // A script with no extension counts when the command names it by a
+      // path and the file is there.
+      if (!script && !(path.includes('/') && !path.startsWith('$') && exists(path))) continue;
+      if (exists(path)) scripts.push({ path, from });
+      else errors.push(`${from} runs ${word}, which is not in the repo`);
+    }
+  };
+  const hooksIn = (data, pluginRoot, from) => { for (const command of commandsIn(data)) take(command, pluginRoot, from); };
+  // Each server runs its command with its args.
+  const serversIn = (data, pluginRoot, from) => {
+    for (const server of Object.values(data ?? {})) {
+      if (!server || typeof server !== 'object') continue;
+      for (const word of [server.command, ...(Array.isArray(server.args) ? server.args : [])]) if (typeof word === 'string') take(word, pluginRoot, from);
+    }
+  };
+  // A plugin.json names hooks and servers inline, or by a path, or by a list
+  // of paths.
+  const byPath = (value, pluginRoot, from, each) => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) { each(value, pluginRoot, from); return; }
+    for (const name of [value].flat()) {
+      if (typeof name !== 'string') continue;
+      const file = clean(posix.join(pluginRoot || '.', name.replace(/\$\{?CLAUDE_PLUGIN_ROOT\}?/g, '.')));
+      const data = parse(file);
+      if (data === undefined) { if (!exists(file)) errors.push(`${from} names ${name}, which is not in the repo`); continue; }
+      each(data, pluginRoot, file);
+    }
+  };
+  for (const pluginRoot of [...new Set(roots)]) {
+    const base = clean(pluginRoot || '.');
+    for (const name of ['hooks/hooks.json', '.claude/settings.json', '.claude/settings.local.json']) {
+      const data = parse(under(pluginRoot, name));
+      if (data !== undefined) hooksIn(data, base, under(pluginRoot, name));
+    }
+    const mcp = parse(under(pluginRoot, '.mcp.json'));
+    if (mcp !== undefined) serversIn(mcp?.mcpServers ?? mcp, base, under(pluginRoot, '.mcp.json'));
+    const manifestFile = under(pluginRoot, '.claude-plugin/plugin.json');
+    const manifest = parse(manifestFile);
+    if (manifest && typeof manifest === 'object') {
+      if (manifest.hooks !== undefined) byPath(manifest.hooks, base, manifestFile, hooksIn);
+      if (manifest.mcpServers !== undefined) byPath(manifest.mcpServers, base, manifestFile, (data, root, from) => serversIn(data?.mcpServers ?? data, root, from));
+    }
+  }
+  return { scripts, errors };
+}
+
+function commandsIn(value, out = []) {
+  if (Array.isArray(value)) for (const entry of value) commandsIn(entry, out);
+  else if (value && typeof value === 'object') for (const [key, entry] of Object.entries(value)) {
+    if (key === 'command' && typeof entry === 'string') out.push(entry);
+    else commandsIn(entry, out);
+  }
+  return out;
+}
+
+export function entryPoints(root) {
+  const entries = [], errors = [];
+  const workflows = join(root, '.github', 'workflows');
+  const tests = [];
+  if (existsSync(workflows)) {
+    for (const name of readdirSync(workflows).sort()) {
+      if (!/\.ya?ml$/.test(name)) continue;
+      const raw = readFileSync(join(workflows, name), 'utf8');
+      // `npm test` and `npm run <name>` run a script of the root package.json.
+      let scripts = {};
+      try { scripts = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).scripts ?? {}; } catch { scripts = {}; }
+      const text = runText(raw).replace(/\bnpm\s+(?:run\s+)?([\w:-]+)/g, (whole, script) => (typeof scripts[script] === 'string' ? `${whole}\n${scripts[script]}\n` : whole));
+      for (const match of text.matchAll(RUNS)) {
+        const flags = match[1] ?? '';
+        const target = match[2];
+        if (target.includes('$') || target.startsWith('-')) continue;
+        if (/--test\b/.test(flags)) {
+          // node --test <globs>: the test files are entries, and only what
+          // they load counts. Collect each glob after --test on that line.
+          const lineEnd = text.indexOf('\n', match.index);
+          const rest = text.slice(match.index, lineEnd === -1 ? undefined : lineEnd).split(/\s+/).slice(1).filter((word) => !word.startsWith('-') && !word.includes('$'));
+          for (const glob of rest) tests.push(glob);
+          continue;
+        }
+        const path = clean(target);
+        if (!existsSync(join(root, path))) { errors.push(`.github/workflows/${name} runs ${target}, which is not in the repo`); continue; }
+        entries.push({ path, from: `.github/workflows/${name}`, counts: true });
+      }
+    }
+  }
+  const tree = walk(root).map((path) => ({ path }));
+  const roots = ['', ...pluginRoots(tree, (path) => readAt(root, null, path))];
+  const under = (pluginRoot, name) => (pluginRoot ? `${pluginRoot}/${name}` : name);
+  const present = (path) => existsSync(join(root, path));
+  const hooks = hookScripts(roots, (path) => readAt(root, null, path), present);
+  for (const { path, from } of hooks.scripts) entries.push({ path, from, counts: true });
+  errors.push(...hooks.errors);
+  const all = tree.map((entry) => entry.path);
+  for (const glob of tests) {
+    const match = matcher(glob);
+    for (const path of all.filter((file) => match(file))) entries.push({ path, from: 'node --test', counts: false });
+  }
+  return { entries, errors };
+}
+
+const IMPORTS = [
+  /\bimport\s+(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/g,
+  /\bexport\s+[^'"]*?\s+from\s+['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\bnew URL\(\s*['"]([^'"]+)['"]\s*,\s*import\.meta\.url\s*\)/g,
+];
+
+// `join(HERE, 'a', 'b.json')`, where HERE is the folder of the module: the
+// way this repo opens a file beside its code.
+const JOINS = /\b(?:join|resolve)\(\s*(?:HERE|__dirname)\s*((?:,\s*['"][^'"]+['"]\s*)+)\)/g;
+
+export function closure({ root }) {
+  const { entries, errors } = entryPoints(root);
+  const files = new Map();
+  const queue = entries.map((entry) => ({ ...entry }));
+  const visited = new Set();
+  while (queue.length) {
+    const { path, from, counts } = queue.shift();
+    const key = `${path}|${counts}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+    if (counts && !files.has(path)) files.set(path, from);
+    if (!/\.(m?js)$/.test(path) && !isNodeScript(root, path)) continue;
+    const text = readAt(root, null, path);
+    if (text === null) continue;
+    const specs = [];
+    for (const form of IMPORTS) for (const match of text.matchAll(form)) specs.push(match[1]);
+    for (const match of text.matchAll(JOINS)) specs.push(`./${[...match[1].matchAll(/['"]([^'"]+)['"]/g)].map((part) => part[1]).join('/')}`);
+    for (const spec of specs) {
+      if (!spec.startsWith('.')) continue;
+      const target = clean(posix.join(posix.dirname(path), spec));
+      if (!existsSync(join(root, target))) continue;
+      if (statSync(join(root, target)).isDirectory()) continue;
+      // What a unit test loads from its own test folders is part of the
+      // suite, not of what defines green. It is still followed.
+      const suite = !counts && /(^|\/)(test|tests|fixtures)\//.test(target) && !/^packages\//.test(target);
+      queue.push({ path: target, from: path, counts: !suite });
+    }
+  }
+  return { files: [...files].map(([path, from]) => ({ path, from })).sort((a, b) => a.path.localeCompare(b.path)), errors };
+}
+
+function isNodeScript(root, path) {
+  const text = readAt(root, null, path);
+  return text !== null && /^#!.*\bnode\b/.test(text);
+}
+
+// The files of a closure that no rule covers. A test file that an `except`
+// takes off a list still counts as uncovered here: code that the checks load
+// is never exempt as a test.
+export function uncovered({ root, ref = 'HEAD', classes = loadClasses() }) {
+  const { rules } = rulesAt({ root, ref, classes });
+  const { files, errors } = closure({ root });
+  const missing = files.filter(({ path }) => !rules.some((rule) => ruleHits(rule, path)));
+  return { missing, errors };
+}