simt-dev 0.2.2 → 0.3.1

package/src/index/store.mjs

@@ -0,0 +1,301 @@
+// The local index (ADR-089).
+//
+// `node:sqlite` when this Node has it, including FTS5, and a JSON-lines file
+// otherwise. Either one is a cache: `git ls-files -s` can rebuild it, so a missing
+// file is not a lost database. A blob that has not changed is not read again.
+
+import { execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { readManifest } from '../projection/manifest.mjs';
+import { extract, resolveImports } from './extract.mjs';
+import {
+  JSONL_FILE,
+  SCHEMA_V,
+  SQLITE_FILE,
+  countSqlite,
+  readJsonl,
+  readSchema,
+  readSqliteRows,
+  writeJsonl,
+  writeSqlite,
+} from './persist.mjs';
+
+export { JSONL_FILE, SQLITE_FILE };
+
+const MARKERS = ['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'pom.xml'];
+
+const LANG = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript', kt: 'kotlin', kts: 'kotlin', java: 'java',
+  py: 'python', go: 'go', rs: 'rust', swift: 'swift', dart: 'dart', rb: 'ruby', cs: 'csharp',
+};
+
+/** `sqlite` when this process can open a database and create an FTS5 table. */
+async function probeBackend() {
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const db = new DatabaseSync(':memory:');
+    db.exec('create virtual table fts using fts5(kind, ref, body)');
+    db.close();
+    return 'sqlite';
+  } catch {
+    return 'jsonl';
+  }
+}
+
+/**
+ * Rebuild the index from the git index. Unchanged blobs are left as they are.
+ *
+ * @param {string} root
+ * @param {{backend?: 'sqlite'|'jsonl'}} [opts]
+ */
+export async function reindex(root, opts = {}) {
+  const started = Date.now();
+  const backend = opts.backend ?? await probeBackend();
+  const listed = await lsFiles(root);
+  const version = await readSchema(root, backend);
+  // A cache written before symbols existed has the right blobs and the wrong
+  // tables. Re-extract once, then an unchanged blob stays untouched.
+  const force = version !== SCHEMA_V;
+  const previous = await readFiles(root, { backend });
+  const prior = new Map(previous.map((row) => [row.path, row]));
+  const cache = new Map();
+  const changed = [];
+  for (const entry of listed) {
+    const old = prior.get(entry.path);
+    if (!force && old && old.blob === entry.blob) continue;
+    changed.push(entry);
+  }
+  const sizes = await blobSizes(root, changed.map((entry) => entry.blob));
+  const texts = await blobTexts(root, changed.map((entry) => entry.blob));
+  const adapter = await resolveAdapter(root, opts);
+  const paths = new Set(listed.map((entry) => entry.path));
+  const next = [];
+  const symbols = [];
+  const edges = [];
+  const fts = [];
+  for (const entry of changed) {
+    const lang = langOf(entry.path);
+    next.push({
+      path: entry.path,
+      blob: entry.blob,
+      lang,
+      bytes: sizes.get(entry.blob) ?? 0,
+      pkg: await packageOf(root, entry.path, cache),
+    });
+    const text = texts.get(entry.blob);
+    const pulled = text == null
+      ? { symbols: [], imports: [], edges: null }
+      : await runExtract(entry.path, text, lang, adapter.module);
+    symbols.push(...pulled.symbols);
+    edges.push(...(pulled.edges ?? resolveImports(entry.path, pulled.imports, paths, lang)));
+    const names = [...new Set(pulled.symbols.map((row) => row.name))].sort();
+    if (names.length > 0) fts.push({ kind: 'code', ref: entry.path, body: names.join(' ') });
+  }
+  const removed = previous.filter((row) => !paths.has(row.path)).map((row) => row.path);
+  let stored;
+  if (backend === 'sqlite') {
+    await writeSqlite(root, next, removed, symbols, edges, fts);
+    stored = await countSqlite(root);
+  } else {
+    stored = await writeJsonl(root, previous, next, removed, symbols, edges, fts, force);
+  }
+  return {
+    backend,
+    files: listed.length,
+    updated: next.length,
+    removed: removed.length,
+    symbols: stored.symbols,
+    edges: stored.edges,
+    parsers: adapter.state,
+    ms: Date.now() - started,
+  };
+}
+
+/** File rows, sorted by path. The same blobs read back as the same rows. */
+export async function readFiles(root, opts = {}) {
+  const backend = opts.backend ?? await probeBackend();
+  if (backend === 'sqlite') return readSqliteRows(root, 'select path, blob, lang, bytes, pkg from files order by path');
+  return readJsonl(root, 'files');
+}
+
+/** Symbol rows for the blobs currently indexed. */
+export async function readSymbols(root, opts = {}) {
+  const backend = opts.backend ?? await probeBackend();
+  if (backend === 'sqlite') return readSqliteRows(root, 'select path, name, kind, line, sig, exported from symbols order by path, line, name, kind');
+  return readJsonl(root, 'symbols');
+}
+
+/** Edges currently indexed. An import edge's src is the file that imports. */
+export async function readEdges(root, opts = {}) {
+  const backend = opts.backend ?? await probeBackend();
+  if (backend === 'sqlite') return readSqliteRows(root, 'select src, dst, kind, weight from edges order by src, dst, kind');
+  return readJsonl(root, 'edges');
+}
+
+function langOf(filePath) {
+  const base = filePath.slice(filePath.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return '';
+  return LANG[base.slice(dot + 1)] ?? '';
+}
+
+export async function packageOf(root, filePath, cache) {
+  let dir = dirname(filePath);
+  if (dir === '.') dir = '';
+  const seen = [];
+  for (;;) {
+    if (cache.has(dir)) {
+      const found = cache.get(dir);
+      for (const prior of seen) cache.set(prior, found);
+      return found;
+    }
+    seen.push(dir);
+    let hit = false;
+    for (const name of MARKERS) {
+      try {
+        await stat(join(root, dir, name));
+        hit = true;
+        break;
+      } catch {
+        // This directory is not that kind of package. The next marker may be.
+      }
+    }
+    if (hit || dir === '') {
+      const found = hit ? dir : '';
+      for (const prior of seen) cache.set(prior, found);
+      return found;
+    }
+    const parent = dirname(dir);
+    dir = parent === '.' ? '' : parent;
+  }
+}
+
+function git(root, args, input, binary = false) {
+  return new Promise((resolve, reject) => {
+    const child = execFile('git', args, { cwd: root, encoding: binary ? 'buffer' : 'utf8', maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) reject(Object.assign(error, { stdout, stderr }));
+      else resolve(stdout);
+    });
+    if (input !== undefined) {
+      child.stdin.end(input);
+    }
+  });
+}
+
+async function lsFiles(root) {
+  const stdout = await git(root, ['ls-files', '-s', '-z']);
+  const rows = [];
+  for (const rec of stdout.split('\0')) {
+    if (rec === '') continue;
+    const tab = rec.indexOf('\t');
+    if (tab < 0) continue;
+    const meta = rec.slice(0, tab).split(' ');
+    if (meta[2] !== '0') continue;
+    rows.push({ blob: meta[1], path: rec.slice(tab + 1) });
+  }
+  rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return rows;
+}
+
+async function resolveAdapter(root, opts) {
+  if (opts.adapter) return { module: opts.adapter, state: 'loaded' };
+  let manifest = null;
+  try {
+    const read = await readManifest(root);
+    if (!read.error) manifest = read.manifest;
+  } catch {
+    return { module: null, state: 'off' };
+  }
+  const name = manifest?.index?.parsers;
+  if (typeof name !== 'string' || name === '') return { module: null, state: 'off' };
+  try {
+    const { createRequire } = await import('node:module');
+    const req = createRequire(join(root, 'package.json'));
+    return { module: req(name), state: 'loaded' };
+  } catch {
+    return { module: null, state: 'missing' };
+  }
+}
+
+async function runExtract(filePath, text, lang, adapter) {
+  if (adapter && typeof adapter.extract === 'function') {
+    try {
+      const got = await adapter.extract(filePath, text, lang);
+      if (got && Array.isArray(got.symbols)) return normalise(filePath, got);
+    } catch {
+      // A parser that throws does not sink the index. The built-in rows are the cache.
+    }
+  }
+  return extract(filePath, text, lang);
+}
+
+function normalise(filePath, got) {
+  const symbols = [];
+  for (const row of got.symbols) {
+    if (!row || typeof row.name !== 'string' || row.name === '') continue;
+    symbols.push({
+      path: filePath,
+      name: row.name,
+      kind: typeof row.kind === 'string' ? row.kind : 'symbol',
+      line: Number.isInteger(row.line) ? row.line : 0,
+      sig: typeof row.sig === 'string' ? row.sig.slice(0, 200) : '',
+      exported: row.exported ? 1 : 0,
+    });
+  }
+  symbols.sort((a, b) => a.line - b.line || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  let edges = null;
+  if (Array.isArray(got.edges)) {
+    edges = [];
+    for (const row of got.edges) {
+      if (!row || typeof row.dst !== 'string') continue;
+      edges.push({
+        src: filePath,
+        dst: row.dst,
+        kind: typeof row.kind === 'string' ? row.kind : 'import',
+        weight: typeof row.weight === 'number' ? row.weight : 1,
+      });
+    }
+    edges.sort((a, b) => (a.dst < b.dst ? -1 : a.dst > b.dst ? 1 : 0) || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0));
+  }
+  return { symbols, imports: Array.isArray(got.imports) ? got.imports : [], edges };
+}
+
+async function blobTexts(root, blobs) {
+  const unique = [...new Set(blobs)];
+  const texts = new Map();
+  if (unique.length === 0) return texts;
+  const stdout = await git(root, ['cat-file', '--batch'], `${unique.join('\n')}\n`, true);
+  let offset = 0;
+  while (offset < stdout.length) {
+    const nl = stdout.indexOf(0x0a, offset);
+    if (nl < 0) break;
+    const header = stdout.toString('utf8', offset, nl);
+    const parts = header.split(' ');
+    const size = Number(parts[2]);
+    if (parts[1] !== 'blob' || !Number.isFinite(size)) {
+      offset = nl + 1;
+      continue;
+    }
+    const start = nl + 1;
+    const body = stdout.subarray(start, start + size);
+    offset = start + size + 1;
+    texts.set(parts[0], body.includes(0) ? null : body.toString('utf8'));
+  }
+  return texts;
+}
+
+async function blobSizes(root, blobs) {
+  const unique = [...new Set(blobs)];
+  const sizes = new Map();
+  if (unique.length === 0) return sizes;
+  const stdout = await git(root, ['cat-file', '--batch-check=%(objectname) %(objectsize)'], `${unique.join('\n')}\n`);
+  for (const line of stdout.split('\n')) {
+    if (line === '') continue;
+    const sp = line.indexOf(' ');
+    sizes.set(line.slice(0, sp), Number(line.slice(sp + 1)));
+  }
+  return sizes;
+}

package/src/index/tests.mjs

@@ -0,0 +1,294 @@
+// Which tests exercise a source file (R24, ADR-092).
+//
+// Three precise signals, and one historical one kept apart. An import from a
+// test file, a conventional name beside that test, and a coverage record that
+// names both sides are test edges. A stem that is unique somewhere else in
+// the tree is not a guess. Co-change is a different kind: files that land in
+// the same commit are not, by that fact, a test.
+
+import { isTestPath } from '../bench/mine.mjs';
+import { extract, resolveImports } from './extract.mjs';
+
+const HISTORY = 200;
+const COCHANGE_MIN = 2;
+const COCHANGE_CAP = 8;
+const WIDE_TESTS = 5;
+const WIDE_SOURCES = 15;
+
+export { HISTORY };
+
+/**
+ * @param {{files: {path: string}[]|string[], imports?: {src: string, dst: string, kind?: string}[], coverage?: string[], commits?: string[][]}} input
+ * @returns {{src: string, dst: string, kind: string, weight: number}[]}
+ */
+export function testEdges({ files, imports = [], coverage = [], commits = [] }) {
+  const paths = [...new Set(files.map((file) => (typeof file === 'string' ? file : file.path)))].sort();
+  const have = new Set(paths);
+  const edges = [];
+  for (const edge of imports) {
+    if (edge.kind && edge.kind !== 'import') continue;
+    if (!isTestPath(edge.src) || isTestPath(edge.dst) || !have.has(edge.dst)) continue;
+    edges.push({ src: edge.src, dst: edge.dst, kind: 'test', weight: 1 });
+  }
+  for (const test of paths) {
+    if (!isTestPath(test)) continue;
+    const source = namedSource(test, have);
+    if (source) edges.push({ src: test, dst: source, kind: 'test', weight: 1 });
+  }
+  for (const text of coverage) edges.push(...coverageEdges(text, have));
+  edges.push(...cochangeEdges(commits));
+  return dedupe(edges);
+}
+
+/** Test files for one source file. Co-change is included only when asked. */
+export function testsFor(source, edges, { cochange = false } = {}) {
+  const direct = new Set();
+  const history = [];
+  for (const edge of edges) {
+    if (edge.dst !== source) continue;
+    if (edge.kind === 'test') direct.add(edge.src);
+    else if (edge.kind === 'cochange') history.push(edge);
+  }
+  const found = [...direct].sort();
+  if (!cochange) return found;
+  history.sort((a, b) => b.weight - a.weight || cmp(a.src, b.src));
+  for (const edge of history) {
+    if (direct.has(edge.src)) continue;
+    found.push(edge.src);
+  }
+  return found;
+}
+
+/** Import specifiers in a script, including an import that spans lines. */
+export function scriptSpecifiers(text) {
+  const specs = [];
+  const lines = String(text).split('\n');
+  let buf = '';
+  let open = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!open) {
+      if (!/^(?:import|export)\b/.test(trimmed)) continue;
+      // A declaration is not an import. Capturing it would swallow the next
+      // import's `from` and report a specifier the file does not have.
+      if (/^export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var)\b/.test(trimmed) && !trimmed.includes(' from ')) continue;
+      buf = trimmed;
+      open = true;
+    } else {
+      buf += `\n${trimmed}`;
+    }
+    const done = /\bfrom\s+['"][^'"]+['"]/.test(buf) || /^import\s+['"][^'"]+['"]/.test(buf) || buf.includes(';') || buf.length > 2000;
+    if (!done) continue;
+    const from = buf.match(/\bfrom\s+['"]([^'"]+)['"]/);
+    const side = buf.match(/^import\s+['"]([^'"]+)['"]/);
+    if (from) specs.push(from[1]);
+    else if (side) specs.push(side[1]);
+    buf = '';
+    open = false;
+  }
+  for (const match of String(text).matchAll(/require\(\s*['"]([^'"]+)['"]\s*\)/g)) specs.push(match[1]);
+  for (const match of String(text).matchAll(/\bimport\(\s*['"]([^'"]+)['"]\s*\)/g)) specs.push(match[1]);
+  return [...new Set(specs)];
+}
+
+export function parseCoverage(text) {
+  const body = String(text).replace(/^\uFEFF/, '');
+  const start = body.trimStart();
+  if (start.startsWith('TN:') || start.startsWith('SF:') || start.includes('\nSF:')) return parseLcov(body);
+  if (start.startsWith('mode:')) return parseGoCover(body);
+  if (start.startsWith('<')) return parseJacoco(body);
+  if (start.startsWith('{')) return parseCoveragePy(body);
+  return [];
+}
+
+export function parseLcov(text) {
+  const pairs = [];
+  let test = '';
+  for (const line of String(text).split('\n')) {
+    if (line.startsWith('TN:')) test = line.slice(3).trim();
+    else if (line.startsWith('SF:') && test) pairs.push({ test, source: line.slice(3).trim() });
+    else if (line === 'end_of_record') test = '';
+  }
+  return pairs;
+}
+
+export function parseJacoco(text) {
+  const sources = [...String(text).matchAll(/<sourcefile\s+name="([^"]+)"/g)].map((match) => match[1]);
+  const tests = [...String(text).matchAll(/<class\s+name="([^"]+)"/g)]
+    .map((match) => match[1].split(/[./]/).pop())
+    .filter((name) => /Tests?$/.test(name));
+  const pairs = [];
+  for (const source of sources) {
+    const stem = source.slice(0, source.lastIndexOf('.'));
+    const hit = tests.filter((name) => name === `${stem}Test` || name === `${stem}Tests`);
+    if (hit.length === 1) pairs.push({ test: hit[0], source });
+  }
+  return pairs;
+}
+
+function parseCoveragePy(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const pairs = [];
+  const files = parsed?.files;
+  if (!files || typeof files !== 'object') return pairs;
+  for (const [source, info] of Object.entries(files)) {
+    const contexts = info?.contexts;
+    if (!contexts || typeof contexts !== 'object') continue;
+    for (const name of Object.keys(contexts)) {
+      if (name) pairs.push({ test: name, source });
+    }
+  }
+  return pairs;
+}
+
+export function parseGoCover(text) {
+  const sources = new Set();
+  for (const line of String(text).split('\n')) {
+    const match = /^(.+):\d+\.\d+,\d+\.\d+ \d+ (\d+)/.exec(line);
+    if (match && Number(match[2]) > 0) sources.add(match[1]);
+  }
+  return [...sources].map((source) => ({ test: '', source }));
+}
+
+/**
+ * Pairs that changed together. A commit that touches the whole tree is not a
+ * mapping, and a pair seen once is a coincidence. Each test keeps its strongest
+ * pairs, so one wide test cannot point at every file it ever met.
+ */
+export function cochangeEdges(commits) {
+  const counts = new Map();
+  for (const commit of commits) {
+    const tests = [];
+    const sources = [];
+    for (const path of commit) {
+      if (isTestPath(path)) tests.push(path);
+      else sources.push(path);
+    }
+    if (tests.length === 0 || sources.length === 0) continue;
+    if (tests.length > WIDE_TESTS || sources.length > WIDE_SOURCES) continue;
+    for (const test of tests) {
+      for (const source of sources) {
+        const key = `${test}\0${source}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  const byTest = new Map();
+  for (const [key, weight] of counts) {
+    if (weight < COCHANGE_MIN) continue;
+    const split = key.indexOf('\0');
+    const edge = { src: key.slice(0, split), dst: key.slice(split + 1), kind: 'cochange', weight };
+    const list = byTest.get(edge.src) ?? [];
+    list.push(edge);
+    byTest.set(edge.src, list);
+  }
+  const edges = [];
+  for (const list of byTest.values()) {
+    list.sort((a, b) => b.weight - a.weight || cmp(a.dst, b.dst));
+    edges.push(...list.slice(0, COCHANGE_CAP));
+  }
+  edges.sort(byEdge);
+  return edges;
+}
+
+function coverageEdges(text, files) {
+  const edges = [];
+  for (const pair of parseCoverage(text)) {
+    const source = resolveToken(pair.source, files);
+    if (!source || isTestPath(source)) continue;
+    let test = pair.test ? resolveToken(pair.test, files) : '';
+    if (!test && pair.test === '') test = goTestFor(source, files);
+    if (!test || !isTestPath(test)) continue;
+    edges.push({ src: test, dst: source, kind: 'test', weight: 1 });
+  }
+  return edges;
+}
+
+function goTestFor(source, files) {
+  if (!source.endsWith('.go')) return '';
+  const slash = source.lastIndexOf('/');
+  const dir = slash < 0 ? '' : source.slice(0, slash);
+  const stem = source.slice(slash + 1, -3);
+  const exact = dir ? `${dir}/${stem}_test.go` : `${stem}_test.go`;
+  if (files.has(exact)) return exact;
+  const tests = [];
+  const prefix = dir ? `${dir}/` : '';
+  for (const file of files) {
+    if (!file.startsWith(prefix) || file.slice(prefix.length).includes('/')) continue;
+    if (file.endsWith('_test.go')) tests.push(file);
+  }
+  return tests.length === 1 ? tests[0] : '';
+}
+
+function namedSource(test, files) {
+  // Same directory, or the main tree mirrored from src/test. A stem that is
+  // unique somewhere else in the repo is still a guess: test/hooks.test.mjs
+  // is not the test for src/commands/hooks.mjs.
+  const exact = conventional(test);
+  return exact && files.has(exact) ? exact : null;
+}
+
+function conventional(test) {
+  const moved = test.match(/^(?:(.*)\/)?src\/test\/(java|kotlin)\/(.+?)Tests?\.(java|kt)$/);
+  if (moved) {
+    const prefix = moved[1] ? `${moved[1]}/` : '';
+    return `${prefix}src/main/${moved[2]}/${moved[3]}.${moved[4]}`;
+  }
+  const slash = test.lastIndexOf('/');
+  const dir = slash < 0 ? '' : test.slice(0, slash);
+  const base = test.slice(slash + 1);
+  let source = '';
+  if (/_test\.go$/.test(base)) source = `${base.slice(0, -'_test.go'.length)}.go`;
+  else if (/^test_.+\.py$/.test(base)) source = `${base.slice('test_'.length)}`;
+  else if (/Tests?\.(java|kt)$/.test(base)) source = base.replace(/Tests?(\.(?:java|kt))$/, '$1');
+  else if (/\.(?:test|spec)\.[A-Za-z0-9]+$/.test(base)) source = base.replace(/\.(?:test|spec)(\.[A-Za-z0-9]+)$/, '$1');
+  if (!source || source === base) return '';
+  return dir ? `${dir}/${source}` : source;
+}
+
+function resolveToken(token, files) {
+  const norm = String(token).replaceAll('\\', '/').replace(/^\.\//, '');
+  if (files.has(norm)) return norm;
+  const parts = norm.split('/');
+  for (let i = 0; i < parts.length; i += 1) {
+    const suffix = parts.slice(i).join('/');
+    const hits = [];
+    for (const file of files) {
+      if (file === suffix || file.endsWith(`/${suffix}`)) hits.push(file);
+    }
+    if (hits.length === 1) return hits[0];
+    if (hits.length > 1) return '';
+  }
+  return '';
+}
+
+function dedupe(edges) {
+  const byKey = new Map();
+  for (const edge of edges) {
+    const key = `${edge.kind}\0${edge.src}\0${edge.dst}`;
+    const prior = byKey.get(key);
+    if (!prior || edge.weight > prior.weight) byKey.set(key, edge);
+  }
+  return [...byKey.values()].sort(byEdge);
+}
+
+function byEdge(a, b) {
+  return cmp(a.kind, b.kind) || cmp(a.src, b.src) || cmp(a.dst, b.dst);
+}
+
+function cmp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/** Relative imports in a test file, resolved against the tracked tree. */
+export function importsOf(testPath, text, lang, files) {
+  const specs = lang === 'javascript' || lang === 'typescript' ? scriptSpecifiers(text) : extract(testPath, text, lang).imports;
+  return resolveImports(testPath, specs, files, lang);
+}

package/src/kernel/budget.mjs

@@ -0,0 +1,100 @@
+// Budgeted compilation: which kernel lines may be cut so a repository's declared budget
+// is met (plan 0003 R08).
+//
+// A budget nobody enforces is a number in a JSON file. ADR-072 shipped the number and
+// reported it; what it could not do is meet it, because meeting a budget means something
+// gives. Kernel mode is what gives (ADR-073), and this module is the half of it that
+// measures first and cuts second — the half that turns "your projection is over the line"
+// from a finding a reader has to act on alone into a projection that was already under it.
+//
+// Two rulings live here and nowhere else, because both are the kind of decision that
+// looks like arithmetic until it is written down:
+//
+//   1. Nothing is cut in `full` mode. ADR-072's finding already words the consequence —
+//      "nothing was cut: the projection is still in full mode" — and a full projection
+//      that quietly lost a rule would turn that sentence into a lie told by the tool
+//      about itself. A repository that has not asked for a kernel gets its rules.
+//   2. `hard` is the floor. A priority class exists to say what a reader loses by not
+//      having the line (ADR-073), and a byte count is not a reader. Cutting a hard
+//      constraint to reach a ceiling would remove the one class whose whole claim is that
+//      its absence produces a defect, and it would report itself as compliance.
+//
+// Everything here is a pure function of its arguments: no clock, no network, no PATH. Two
+// machines given the same repository and the same budget cut the same rules in the same
+// order, which is R08's second accept criterion and the only reason a pull request can
+// diff the result.
+
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+
+/** The class a budget may not cut. Ruling 2 above. */
+const BUDGET_FLOOR = 'hard';
+
+/**
+ * Cut candidates, least valuable first, until the region fits `ceiling`.
+ *
+ * The candidate order is the caller's, not this module's. Which class a reader loses least
+ * is a judgement about the rules, and the rules declare their own class in their own
+ * frontmatter (ADR-073); this module is handed a list already in the order it should lose
+ * them and does the one thing that is arithmetic.
+ *
+ * `costs` is called with the ids cut so far and returns what the document then weighs. It
+ * is re-rendered per attempt rather than subtracting each rule's own size, because the
+ * three things that change the total when a rule leaves are not the rule's length: the
+ * provenance header lists every source, the deferred section gains a line naming what left,
+ * and both shrink as the cut list grows. Arithmetic that ignored them would be a budget
+ * that is either never quite met or overshot by the width of a comment.
+ *
+ * @param {{candidates: {id: string, priority: string}[], ceiling: number,
+ *          costs: (cut: Set<string>) => number}} input
+ * @returns {{cut: string[], before: number, after: number, floorHeld: boolean}}
+ */
+export function packToBudget({ candidates, ceiling, costs }) {
+  const cut = new Set();
+  const before = costs(cut);
+  let after = before;
+  for (const candidate of candidates) {
+    if (after <= ceiling) break;
+    if (candidate.priority === BUDGET_FLOOR) continue;
+    cut.add(candidate.id);
+    after = costs(cut);
+  }
+  // `floorHeld` is not a cut count. It says the kernel is over the line with everything
+  // cuttable already cut, which is a different fact from "we cut some rules" and is
+  // reported differently: nothing else can shrink it, so the reader is told to move a rule
+  // out of the two classes kernel mode packs, exactly as ADR-072's kernel wording says.
+  return { cut: [...cut], before, after, floorHeld: after > ceiling };
+}
+
+/**
+ * Report that the kernel was cut to fit the budget this repository declared.
+ *
+ * Non-blocking, and for the same reason `budget` is (ADR-072): the cut is the tool doing
+ * what the repository asked, and the remedy is a decision about the number, not a missing
+ * file. A gate that failed here would fail a repository for shipping a smaller projection.
+ *
+ * The detail carries the three numbers a reader needs to judge the cut and names every
+ * rule that left, because a cut line that is not named is indistinguishable from a rule
+ * that was never written (ADR-073 ruling 6). `before` is the size the reader would have
+ * had, so the remedy can quote a number rather than sending them to go and measure one.
+ *
+ * The remedy's number is the one that ends the cut, and it is `before + reserve`, because
+ * the ceiling the region was cut against is the budget less what was held back for the
+ * files loading beside it.
+ *
+ * @param {{file: string, bytes: number, reserve: number, before: number, after: number,
+ *          cuts: {id: string, priority: string}[]}} input
+ * @returns {{file: string, status: string, detail: string, remedy: string}}
+ */
+export function budgetCutFinding({ file, bytes, reserve, before, after, cuts }) {
+  const named = cuts.map((c) => `${c.id} (${c.priority})`).join(', ');
+  return {
+    file,
+    status: 'budget-cut',
+    detail: `BUDGET-CUT: the kernel projection was cut from ${before} to ${after} bytes against a declared budget of ${bytes}${reserve > 0 ? `, with ${reserve} bytes reserved for the generated files that load beside the region` : ''}; cut: ${named}`,
+    // The number has to be `before + reserve`, not `before`. The region is cut against a
+    // ceiling that already holds the rule files back, so a budget of `before` leaves the
+    // cut standing and the reader has followed the remedy to no effect — which is worse
+    // than naming no number at all, because they will believe they were told what to do.
+    remedy: `raise budget.bytes to ${before + reserve} in ${MANIFEST_FILE}, or move a cut rule out of the hard and command classes so kernel mode leaves it out; ${CLI} rules show <id> reads any of them`,
+  };
+}