/** * Mechanical retakes after review (GST-1560, docs/ship-policy.md#mechanical-retake). After a base merge a branch may * have to retake a version or rules number the base just took (founderstar#563: RULE_NUMBERS 80 to 81 in one line, the * same value in 8 save fixtures, one regenerated golden). /ship finish routes such paths as mechanical, with no reader, * only when the base policy's `mechanical_retake` declares them and the diff proves each one: * - the constant: exactly one line matching its template on each side, a value the reviewed branch took (not the * reviewed base's), a current value above both the reviewed one and the current base's, and the file's patch with * that line masked is the reviewed patch (lib/ship-patch.ts comparePath); * - a fixture field: the masked patch is the reviewed one, and each field line either kept its value or moved from the * constant's reviewed value to its current value; * - a golden: a base .gstack/generated.json entry the constant names regenerates it byte-identically (lib/regen.ts). * A declared path that fails its proof is refused with the reason and stays behavior; nothing is inferred. */ import { spawnSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import { isGatePath } from './review-depth'; import { isRegistryUnavailable, loadRegistryFromBase, runRegen } from './regen'; import { comparePath, type PatchSides } from './ship-patch'; import { matchesAny } from './ship-policy'; import { constantValue, fieldValue, VALUE_SLOT, type MechanicalConstant } from './ship-policy-mechanical'; import { sidecarLine } from './ship-sidecar'; export interface MechanicalRefusal { path: string; reason: string } export interface MechanicalInput { sides?: PatchSides; base: string; candidates: readonly string[]; declared: readonly MechanicalConstant[] } const SIDES = ['reviewedBase', 'reviewed', 'currentBase', 'current'] as const; type Side = typeof SIDES[number]; function git(cwd: string, args: string[], env: NodeJS.ProcessEnv = process.env, input?: string): string | null { const r = spawnSync('git', ['--literal-pathspecs', ...args], { cwd, encoding: 'latin1', input: input === undefined ? undefined : Buffer.from(input, 'latin1'), timeout: 120_000, maxBuffer: 256 * 1024 * 1024, env }); return r.status === 0 ? r.stdout : null; } /** The four sides with `rel` rewritten by `mask` (an absent file stays absent), and each side's masked blob; a string says why not. */ function maskedSides(cwd: string, s: PatchSides, rel: string, mask: (text: string) => string): { sides: PatchSides; blobs: Record } | string { const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-mechanical-')); const env = { ...process.env, GIT_INDEX_FILE: path.join(dir, 'index') }; try { const sides = { ...s }; const blobs = {} as Record; for (const side of SIDES) { const ls = git(cwd, ['ls-tree', s[side], '--', rel], env); if (ls === null) return `git could not read it at ${side} ${s[side].slice(0, 12)}`; if (!ls.trim()) { blobs[side] = null; continue; } const entry = /^(100644|100755) blob ([0-9a-f]{40,64})\t/.exec(ls); const text = entry && git(cwd, ['cat-file', 'blob', entry[2]!], env); if (!entry || text === null) return `is not a regular file at ${side} ${s[side].slice(0, 12)}`; const blob = git(cwd, ['hash-object', '-w', '--stdin'], env, mask(text))?.trim(); const tree = blob && git(cwd, ['read-tree', s[side]], env) !== null && git(cwd, ['update-index', '--cacheinfo', `${entry[1]},${blob},${rel}`], env) !== null ? git(cwd, ['write-tree'], env)?.trim() : undefined; if (!tree) return `git could not build its masked tree at ${side}`; sides[side] = tree; blobs[side] = `${entry[1]} ${blob}`; } return { sides, blobs }; } finally { fs.rmSync(dir, { recursive: true, force: true }); } } /** Why the branch's patch to `rel`, with `mask` applied on every side, is not the reviewed patch; null when it is. */ function maskedChange(cwd: string, s: PatchSides, rel: string, mask: (text: string) => string): string | null { const m = maskedSides(cwd, s, rel, mask); if (typeof m === 'string') return m; if (m.blobs.reviewedBase === m.blobs.reviewed && m.blobs.currentBase === m.blobs.current) return null; return comparePath(cwd, m.sides, rel) === 'same' ? null : 'changes more than the declared values since review (the masked patch is not the reviewed one)'; } /** * The declared paths among `candidates` whose post-review change is a proven mechanical retake (path -> what moved), * and each declared candidate that failed its proof with the reason. Paths no declaration names are neither. */ export function mechanicalPaths(cwd: string, i: MechanicalInput): { proven: Record; refused: MechanicalRefusal[] } { const proven: Record = Object.create(null); const refused: MechanicalRefusal[] = []; const retaken = new Map(); const s = i.sides; const refuse = (p: string, reason: string) => refused.push({ path: p, reason }); const gate = (p: string) => isGatePath(p) || /^\.(gstack|github)\//.test(p); const text = (side: Side, rel: string) => s && git(cwd, ['show', `${s[side]}:${rel}`]); for (const c of i.declared.filter(d => i.candidates.includes(d.path))) { if (!s) { refuse(c.path, 'needs --reviewed-base'); continue; } if (gate(c.path)) { refuse(c.path, 'is a gate path or under .gstack/ or .github/'); continue; } const values = SIDES.map(side => (text(side, c.path) ?? '').split('\n').map(l => constantValue(l, c.template)).filter((v): v is number => v !== null)); const odd = SIDES.find((_, k) => values[k]!.length !== 1); if (odd) { refuse(c.path, `does not hold exactly one line matching ${JSON.stringify(c.template)} at ${odd}`); continue; } const [rb, rv, cb, cv] = values.map(v => v[0]!) as [number, number, number, number]; if (rv === rb) { refuse(c.path, `the reviewed branch did not take the constant (${rv} at the reviewed base too), so a new take is behavior`); continue; } if (!(cv > rv && cv > cb)) { refuse(c.path, `retakes ${rv} as ${cv}, not above the reviewed ${rv} and the base's ${cb}`); continue; } const why = maskedChange(cwd, s, c.path, t => t.split('\n').map(l => (constantValue(l, c.template) === null ? l : c.template)).join('\n')); if (why) { refuse(c.path, why); continue; } proven[c.path] = `constant ${rv} → ${cv}`; retaken.set(c, { from: rv, to: cv }); } const rest = i.candidates.filter(p => !i.declared.some(d => d.path === p)); const goldens: string[] = []; for (const p of rest) { const c = i.declared.find(d => d.fields.some(f => matchesAny([f.glob], p))); if (!c) { if (i.declared.some(d => d.regen.length)) goldens.push(p); continue; } const take = retaken.get(c); if (!take || !s) { refuse(p, `its constant ${c.path} is not a proven retake`); continue; } if (gate(p)) { refuse(p, 'is a gate path or under .gstack/ or .github/'); continue; } const fields = c.fields.filter(f => matchesAny([f.glob], p)).map(f => f.field); const valueOf = (l: string) => fields.map(f => fieldValue(l, f)).find(v => v !== null) ?? null; const [was, now] = (['reviewed', 'current'] as const).map(side => text(side, p)?.split('\n').map(valueOf).filter((v): v is number => v !== null) ?? null); if (!was || !now || !now.length || was.length !== now.length) { refuse(p, `does not hold the same number of ${fields.join(', ')} lines at the reviewed and the current tree`); continue; } const bad = now.findIndex((v, k) => v !== was[k] && !(was[k] === take.from && v === take.to)); if (bad >= 0) { refuse(p, `writes ${now[bad]} into ${fields.join(', ')} where it held ${was[bad]}, not the constant's ${take.from} → ${take.to}`); continue; } if (now.every((v, k) => v === was[k])) { refuse(p, `changes no ${fields.join(', ')} value`); continue; } const why = maskedChange(cwd, s, p, t => t.split('\n').map(l => (valueOf(l) === null ? l : l.replace(/\d+(\s*,?\s*\r?)$/, `${VALUE_SLOT}$1`))).join('\n')); if (why) { refuse(p, why); continue; } proven[p] = `${fields.join(', ')} ${take.from} → ${take.to}`; } if (!goldens.length) return { proven, refused }; const load = loadRegistryFromBase(cwd, i.base); const registry = isRegistryUnavailable(load) || load.errors.length ? { entries: [] } : load.registry; const entries = registry.entries.filter(e => e.command); const named = (p: string, cs: readonly MechanicalConstant[]) => entries.filter(e => cs.some(c => c.regen.includes(e.id)) && matchesAny(e.outputs, p)); const claimed = goldens.filter(p => named(p, i.declared).length); const ids = [...new Set(claimed.flatMap(p => named(p, [...retaken.keys()]).map(e => e.id)))]; const results = ids.length && claimed.some(p => !gate(p)) ? runRegen({ repoRoot: cwd, registry, mode: 'check', only: ids, prove: claimed }).results : []; for (const p of claimed) { const by = named(p, [...retaken.keys()]); if (!by.length) { refuse(p, 'its constant is not a proven retake'); continue; } if (gate(p)) { refuse(p, 'is a gate path or under .gstack/ or .github/'); continue; } const ok = results.find(r => by.some(e => e.id === r.id) && r.status === 'fresh' && r.proven?.includes(p)); if (!ok) { refuse(p, `does not regenerate byte-identically from ${by.map(e => e.id).join(', ')} (${results.filter(r => by.some(e => e.id === r.id)).map(r => r.status).join(', ') || 'not run'})`); continue; } proven[p] = `golden, regenerated by ${ok.id}`; } return { proven, refused }; } /** The PR body and receipt line for one mechanical path. */ export const mechanicalLine = (p: string, what: string) => `Mechanical retake: ${p} (${what})`; function recordFile(cwd: string, tree: string): string { const rel = spawnSync('git', ['rev-parse', '--git-path', `gstack/mechanical-${tree.slice(0, 12)}.json`], { cwd, encoding: 'utf8', timeout: 30_000 }).stdout?.trim(); return path.resolve(cwd, rel || `.git/gstack/mechanical-${tree.slice(0, 12)}.json`); } /** Saves finish's mechanical paths and Godot UID sidecars (path -> sibling) for the tree it routed, for gstack-ship-receipt write; the error message when it cannot. */ export function writeMechanicalRecord(cwd: string, tree: string, proven: Readonly>, sidecars: Readonly> = {}): string | null { const file = recordFile(cwd, tree); try { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify({ tree, paths: proven, sidecars }) + '\n'); return null; } catch (e) { return `${file}: ${(e as Error).message.split('\n')[0]}`; } } /** The mechanical and sidecar lines finish recorded for exactly this tree, which the receipt's `mechanical` lists; none when it recorded none. */ export function readMechanicalLines(cwd: string, tree: string): string[] { try { const v = JSON.parse(fs.readFileSync(recordFile(cwd, tree), 'utf8')); if (v?.tree !== tree || !v.paths || typeof v.paths !== 'object') return []; const lines = (o: unknown, line: (p: string, w: string) => string) => Object.entries(o && typeof o === 'object' ? o : {}).filter(([, w]) => typeof w === 'string').map(([p, w]) => line(p, w as string)); return [...lines(v.paths, mechanicalLine), ...lines(v.sidecars, sidecarLine)].sort(); } catch { return []; } }