carveout 0.1.1 → 0.2.0

package/dist/src/readiness.js

@@ -0,0 +1,131 @@
+/**
+ * Whether a folder is ready to hand to someone at a fixed scope: its tests
+ * must pass before any edit, or "make the tests pass" is not a task anyone
+ * can finish in it. A test fails at the folder's baseline when it reaches a
+ * mock for something the repository runs for real: pure code past the cut
+ * (a validator, a formatter), a database or queue client, or a folder the
+ * code reads by a name no import spells (drizzle's `drizzle/` migrations,
+ * Prisma's `prisma/`). The cut knows which of these the slice has, and
+ * names the flag that brings each: `--copy-pure`, `--live`, `--copy`.
+ *
+ * The advice is the maintainer's: a public cut prints it and keeps it out
+ * of the folder, since the paths it names may lie outside what the folder
+ * shows.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, posix } from "node:path";
+/** Services a maintainer can run beside the folder, and what each needs. */
+const LIVE_SERVICES = {
+    postgres: "a Postgres server",
+    mysql: "a MySQL server",
+    mongodb: "a MongoDB server",
+    redis: "a Redis server",
+    queue: "the queue's broker",
+    orm: "the database the ORM talks to",
+    sqlite: "nothing: SQLite is a file",
+};
+/** The mocked service packages `--live` could keep real, by name. */
+export function liveCandidates(dependencies, serviceOf) {
+    return dependencies
+        .filter((dependency) => dependency.kind === "package" && dependency.resolution === "runtime-mock")
+        .flatMap((dependency) => {
+        const service = serviceOf(dependency.name);
+        return service !== null && LIVE_SERVICES[service] !== undefined
+            ? [{ name: dependency.name, service }]
+            : [];
+    })
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/** The files under a folder, as a count; 0 when it is not one. */
+function fileCount(absolute) {
+    if (!existsSync(absolute) || !statSync(absolute).isDirectory())
+        return 0;
+    let count = 0;
+    for (const entry of readdirSync(absolute, { recursive: true, withFileTypes: true }))
+        if (entry.isFile())
+            count += 1;
+    return count;
+}
+/** The text of the first of `names` under `dir` that exists, with its name. */
+function firstText(repo, dir, names) {
+    for (const name of names) {
+        const path = join(repo, dir, name);
+        if (existsSync(path) && statSync(path).isFile())
+            return { name, text: readFileSync(path, "utf8") };
+    }
+    return null;
+}
+/** A relative folder named in a config file, under the package, normalized. */
+function underPackage(dir, named) {
+    const joined = posix.normalize(posix.join(dir, named.replace(/^\.\//, ""))).replace(/\/+$/, "");
+    // The package itself (`out: "./"`) is no folder to copy beside the slice.
+    if (joined.startsWith("..") || posix.isAbsolute(joined) || joined === "." || joined === posix.normalize(dir || "."))
+        return null;
+    return joined;
+}
+/**
+ * The folders the slice's packages read by a name their tools default to
+ * or their configuration spells, which the walk cannot follow: drizzle's
+ * migrations (`out` in `drizzle.config.*`, else `drizzle/` with its
+ * journal), Prisma's schema and migrations (`prisma/`), knex's
+ * (`directory` in a knexfile, else `migrations/`), and a package's own
+ * `migrations/` folder. Folders the cut copies already, or holds files of,
+ * are left out.
+ */
+export function configuredFolders(repo, packageDirs, held) {
+    const found = new Map();
+    const add = (path, why) => {
+        if (path === null || found.has(path) || held(path))
+            return;
+        const files = fileCount(join(repo, path));
+        if (files > 0)
+            found.set(path, { path, files, why });
+    };
+    for (const dir of [...new Set(packageDirs)].sort()) {
+        const drizzle = firstText(repo, dir, [
+            "drizzle.config.ts",
+            "drizzle.config.mts",
+            "drizzle.config.js",
+            "drizzle.config.mjs",
+            "drizzle.config.cjs",
+            "drizzle.config.json",
+        ]);
+        const out = drizzle === null ? null : /["']?\bout["']?\s*:\s*["'`]([^"'`]+)["'`]/.exec(drizzle.text)?.[1];
+        if (out !== undefined && out !== null)
+            add(underPackage(dir, out), `drizzle's migrations (out in ${drizzle?.name})`);
+        else if (existsSync(join(repo, dir, "drizzle", "meta", "_journal.json")))
+            add(underPackage(dir, "drizzle"), "drizzle's migrations, which migrate() reads by its default name");
+        if (existsSync(join(repo, dir, "prisma", "schema.prisma")))
+            add(underPackage(dir, "prisma"), "Prisma's schema and migrations");
+        const knex = firstText(repo, dir, ["knexfile.ts", "knexfile.js", "knexfile.mjs", "knexfile.cjs"]);
+        // The migrations' directory, not the seeds': inside `migrations: { … }`.
+        const directory = knex === null ? undefined : /\bmigrations\s*:\s*\{[^}]*?\bdirectory\s*:\s*["'`]([^"'`]+)["'`]/s.exec(knex.text)?.[1];
+        if (directory !== undefined)
+            add(underPackage(dir, directory), `knex's migrations (directory in ${knex?.name})`);
+        add(underPackage(dir, "migrations"), "a migrations folder the code reads by name");
+    }
+    return [...found.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/** Whether the readiness names anything the maintainer could do. */
+export function hasAdvice(readiness) {
+    return ((readiness.copyPure !== null && readiness.copyPure.files.length > 0) ||
+        readiness.live.length > 0 ||
+        readiness.copy.length > 0);
+}
+/**
+ * The advice as lines for a terminal: each flag with what it brings and
+ * what it costs (more of the repository shown, or a service to run).
+ */
+export function renderReadiness(readiness) {
+    const lines = [];
+    if (readiness.copyPure !== null && readiness.copyPure.files.length > 0) {
+        const shown = readiness.copyPure.files.slice(0, 5).join(", ");
+        const more = readiness.copyPure.files.length > 5 ? `, and ${readiness.copyPure.files.length - 5} more` : "";
+        lines.push(`  --copy-pure${readiness.copyPure.needsMaxFiles === undefined ? "" : ` --max-files ${readiness.copyPure.needsMaxFiles}`}: copies ${readiness.copyPure.files.length} module(s) the slice mocks now (${readiness.copyPure.lines} lines: ${shown}${more}): the pure code its tests run, and the workspace source on the way; the contributor reads them.${readiness.copyPure.needsMaxFiles === undefined ? "" : ` The current file budget would leave some out, and the tests with them.`}`);
+    }
+    for (const { name, service } of readiness.live)
+        lines.push(`  --live ${name}: keeps the ${service} client real; the folder's tests then need ${LIVE_SERVICES[service] ?? "the service"}.`);
+    for (const { path, files, why } of readiness.copy)
+        lines.push(`  --copy ${path}: ${why}, ${files} file(s); the contributor reads them.`);
+    return lines;
+}

package/dist/src/receipt.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The maintainer's copy of a cut, kept outside the folder.
+ *
+ * A folder handed to someone outside comes back in their hands: its
+ * `carveout.json` and `carveout/baseline.json` are theirs to edit. The
+ * record decides what a patch may carry (the slice's files and packages)
+ * and how its imports are restored; the baseline decides which failing
+ * tests `npm test` does not count. Both are written again, at the cut and
+ * at the first check, into a receipt under `CARVEOUT_HOME/receipts/`, named
+ * by the cut's random id, which the folder carries. `patch`, `status`,
+ * `apply`, `merge` and `check` read the receipt when there is one, and the
+ * folder's own record only when there is none (a folder cut on another
+ * machine, or a receipt deleted): then the record is checked against the
+ * repository as before.
+ *
+ * With the receipt holding the record, a public folder's own record needs
+ * none of what names the repository beyond the slice: the commit, the
+ * hashes of the repository's other files, the import specifiers the cut
+ * rewrote (workspace package names, path aliases), the private paths.
+ * `publicRecord` leaves them out.
+ */
+import { type CarveoutRecord } from "./carve.js";
+import { type FolderPseudonyms } from "./pseudonyms/index.js";
+import type { Readiness } from "./readiness.js";
+export declare const RECEIPT_SCHEMA_VERSION = 1;
+/** What the maintainer keeps of a cut. */
+export interface Receipt {
+    readonly schemaVersion: typeof RECEIPT_SCHEMA_VERSION;
+    /** The cut's id, which the folder's record carries too. */
+    readonly cutId: string;
+    readonly createdAt: string;
+    /** The checkout the cut read, absolute. */
+    readonly repo: string;
+    /** The folder the cut wrote, absolute, as it was then. */
+    readonly out: string;
+    /** The record as the cut made it, nothing left out. */
+    readonly record: CarveoutRecord;
+    /** The tests that failed on the mocks before any edit, once a check recorded them. */
+    readonly baseline?: readonly string[];
+    /**
+     * The record as the folder holds it, when that differs from `record`: a
+     * public folder's, scrubbed, and in pseudonyms by its own paths and
+     * hashes. What an edit in the folder is measured against.
+     */
+    readonly folderRecord?: CarveoutRecord;
+    /** A public folder's pseudonyms: the table and the kept names. */
+    readonly pseudonyms?: FolderPseudonyms;
+    /**
+     * The generated files as the folder holds them, by folder path: the test
+     * runner, the harness, the stubs and mocks, the manifests. `check` runs a
+     * folder that came back on these, not on what it brought.
+     */
+    readonly generatedText?: Readonly<Record<string, string>>;
+    /** What would make the folder's tests run on real code (`readinessOf`), public cut or not. */
+    readonly readiness?: Readiness;
+    /** Files every cut of this folder reads as absent: the owner's acceptance tests. */
+    readonly unseen?: readonly string[];
+    /**
+     * The test side of the slice as the folder held it at the cut (its tests,
+     * their helpers, the setup files), by folder path: what an acceptance
+     * run puts back where patch keeps the folder's edit out.
+     */
+    readonly testText?: Readonly<Record<string, string>>;
+}
+/** The record as the folder holds it: what its files are measured against. */
+export declare const folderView: (receipt: Receipt) => CarveoutRecord;
+/** A new cut id: 128 random bits, as hex. */
+export declare function newCutId(): string;
+/** Where a cut's receipt is kept unless the maintainer names a file. */
+export declare function receiptPathFor(cutId: string): string;
+/** Writes a receipt where only its owner reads it, replacing it whole. */
+export declare function writeReceipt(path: string, receipt: Receipt): void;
+/** Reads a receipt, or throws when the file is not one. */
+export declare function readReceipt(path: string): Receipt;
+/** A receipt given as data (`api.ts`: kept by the caller, not a file), or throws when it is not one; `label` names it. */
+export declare function asReceipt(parsed: unknown, label?: string): Receipt;
+/** A folder's record, and the receipt that vouches for it when there is one. */
+export interface TrustedCut {
+    /** The record to act on: the receipt's, else the folder's own. */
+    readonly record: CarveoutRecord;
+    /** The folder's own record, as it came back. */
+    readonly folder: CarveoutRecord;
+    readonly receipt: Receipt | null;
+    readonly receiptPath: string | null;
+}
+/**
+ * The record a command on a folder acts on. `given` names a receipt file
+ * (`--receipt`); else the receipt of the cut id the folder's record names
+ * is looked for under `CARVEOUT_HOME`. A receipt of another cut is refused.
+ * Without one, the folder's own record is all there is. `trustedCutWith`
+ * takes the receipt as data instead, and reads no file but the folder's.
+ */
+export declare function trustedCut(dir: string, given?: string, options?: {
+    /**
+     * Go on without a receipt: the folder's own record is all there is,
+     * checked against the repository (`--no-receipt`). Without it, a folder
+     * whose receipt cannot be found is refused: the folder decides which
+     * id it carries, and so whether one is found.
+     */
+    readonly noReceipt?: boolean;
+    /** `check`: go on without one, and trust nothing of the folder's own (its baseline). */
+    readonly optional?: boolean;
+}): TrustedCut;
+/**
+ * The record a command on a folder acts on, by a receipt given as data
+ * (`api.ts`): checked as `trustedCut` checks a receipt file, with no
+ * receipt looked for under `CARVEOUT_HOME`.
+ */
+export declare function trustedCutWith(dir: string, given: unknown): TrustedCut;
+/**
+ * The record a public folder carries: what the folder's own commands need
+ * (its files and their hashes, what it stubs, its tests), less what names
+ * the repository beyond the slice, which the receipt keeps: the commit and
+ * the graph's hash, the hashes of the repository's other files, the
+ * specifiers the cut rewrote (a workspace package's name, a path alias),
+ * and the private paths the owner keeps out.
+ */
+export declare function publicRecord(record: CarveoutRecord): CarveoutRecord;
+/**
+ * The record a public folder holds, made from the cut's: scrubbed
+ * (`publicRecord`), a leak's blocker kept without the name it is about,
+ * and for a folder in pseudonyms, in its names, with its files' folder
+ * paths and the hashes of what the folder holds at them (`dir`), so its
+ * own commands (the coverage guard, check) read it as written.
+ */
+export declare function folderRecordFor(record: CarveoutRecord, table: FolderPseudonyms | undefined, dir: string, 
+/** A hash already known for a folder path, over what the folder holds there now. */
+known?: (folderPath: string) => string | undefined): CarveoutRecord;
+/**
+ * Writes a record a command changed (`apply` growing the slice, writing
+ * stubs) to the folder and, when the cut has one, to its receipt: the
+ * folder's copy public-scrubbed as the cut wrote it.
+ */
+export declare function saveRecord(dir: string, trusted: TrustedCut, updated: CarveoutRecord, 
+/** Generated files the command wrote into the folder, by folder path. */
+written?: Readonly<Record<string, string>>, 
+/**
+ * Slice files whose hash the record takes anew, by folder path: as the
+ * command wrote them, the folder's edits aside (`refresh` moving the
+ * folder's base). Every other path keeps the hash it had.
+ */
+rebased?: ReadonlyMap<string, string>): TrustedCut;
+/**
+ * The baseline a check of the folder reads, given its receipt and the
+ * folder's own `carveout/baseline.json` (its failing names, or null when it
+ * has none): the receipt's when it holds one, none when the receipt holds
+ * none (a baseline the receipt never saw is not read), the folder's own
+ * when there is no receipt to judge it by. `edited` names what the
+ * folder's own adds beyond the receipt's.
+ */
+export declare function trustedBaseline(receipt: Pick<Receipt, "baseline"> | null, folder: readonly string[] | null): {
+    readonly use: readonly string[] | null | "folder";
+    readonly edited: readonly string[];
+};

package/dist/src/receipt.js

@@ -0,0 +1,296 @@
+/**
+ * The maintainer's copy of a cut, kept outside the folder.
+ *
+ * A folder handed to someone outside comes back in their hands: its
+ * `carveout.json` and `carveout/baseline.json` are theirs to edit. The
+ * record decides what a patch may carry (the slice's files and packages)
+ * and how its imports are restored; the baseline decides which failing
+ * tests `npm test` does not count. Both are written again, at the cut and
+ * at the first check, into a receipt under `CARVEOUT_HOME/receipts/`, named
+ * by the cut's random id, which the folder carries. `patch`, `status`,
+ * `apply`, `merge` and `check` read the receipt when there is one, and the
+ * folder's own record only when there is none (a folder cut on another
+ * machine, or a receipt deleted): then the record is checked against the
+ * repository as before.
+ *
+ * With the receipt holding the record, a public folder's own record needs
+ * none of what names the repository beyond the slice: the commit, the
+ * hashes of the repository's other files, the import specifiers the cut
+ * rewrote (workspace package names, path aliases), the private paths.
+ * `publicRecord` leaves them out.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { RECORD_PATH, carveoutHome, readRecord } from "./carve.js";
+import { exactToFolder, recordToFolder, toFolder } from "./pseudonyms/index.js";
+export const RECEIPT_SCHEMA_VERSION = 1;
+/** The record as the folder holds it: what its files are measured against. */
+export const folderView = (receipt) => receipt.folderRecord ?? receipt.record;
+/** A new cut id: 128 random bits, as hex. */
+export function newCutId() {
+    return randomBytes(16).toString("hex");
+}
+const CUT_ID = /^[0-9a-f]{32}$/;
+/** Where a cut's receipt is kept unless the maintainer names a file. */
+export function receiptPathFor(cutId) {
+    if (!CUT_ID.test(cutId))
+        throw new Error(`${JSON.stringify(cutId)} is not a cut id.`);
+    return join(carveoutHome(), "receipts", `${cutId}.json`);
+}
+/** Writes a receipt where only its owner reads it, replacing it whole. */
+export function writeReceipt(path, receipt) {
+    const target = resolve(path);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    // A name no one can have made first: the file is created, never followed.
+    const temporary = `${target}.${randomBytes(6).toString("hex")}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, target);
+}
+/** Reads a receipt, or throws when the file is not one. */
+export function readReceipt(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`${path} is not a receipt: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return asReceipt(parsed, path);
+}
+/** A receipt given as data (`api.ts`: kept by the caller, not a file), or throws when it is not one; `label` names it. */
+export function asReceipt(parsed, label = "The receipt given") {
+    const receipt = parsed;
+    if (receipt === null ||
+        typeof receipt !== "object" ||
+        receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION ||
+        typeof receipt.cutId !== "string" ||
+        !CUT_ID.test(receipt.cutId) ||
+        typeof receipt.repo !== "string" ||
+        receipt.record === undefined)
+        throw new Error(`${label} is not a carveout receipt this version reads.`);
+    return receipt;
+}
+/** A Git object id, SHA-1 or SHA-256. */
+const COMMIT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/**
+ * The record a command on a folder acts on. `given` names a receipt file
+ * (`--receipt`); else the receipt of the cut id the folder's record names
+ * is looked for under `CARVEOUT_HOME`. A receipt of another cut is refused.
+ * Without one, the folder's own record is all there is. `trustedCutWith`
+ * takes the receipt as data instead, and reads no file but the folder's.
+ */
+export function trustedCut(dir, given, options = {}) {
+    const hasRecord = existsSync(join(resolve(dir), RECORD_PATH));
+    const named = given !== undefined ? resolve(given) : null;
+    if (!hasRecord && named === null)
+        readRecord(dir);
+    const folderOwn = hasRecord ? readRecord(dir) : null;
+    const path = named ??
+        (folderOwn !== null && typeof folderOwn.cutId === "string" && CUT_ID.test(folderOwn.cutId) && existsSync(receiptPathFor(folderOwn.cutId))
+            ? receiptPathFor(folderOwn.cutId)
+            : null);
+    if (path === null) {
+        const folder = folderOwn;
+        if (options.noReceipt === true || options.optional === true) {
+            if (folder.publicScrubbed === true && options.optional !== true)
+                throw new Error(`${dir} is a public folder whose record keeps the repository's names out; its receipt holds them. Pass --receipt <file> (the cut printed where it wrote it), or work on the machine that cut it.`);
+            // A folder's own record names the commits patch, refresh and status
+            // pass to git: each must be an object id, never an option.
+            const commits = [folder.manifest?.sourceCommitSha ?? null, ...Object.values(folder.bases ?? {})].filter((commit) => commit !== null);
+            const notCommits = commits.filter((commit) => typeof commit !== "string" || !COMMIT_ID.test(commit));
+            if (notCommits.length > 0)
+                throw new Error(`${dir}/carveout.json names a commit that is not an object id (${notCommits.map(String).join(", ")}): cut the folder again.`);
+            return { record: folder, folder, receipt: null, receiptPath: null };
+        }
+        throw new Error(`No receipt for ${dir}: ${typeof folder.cutId === "string" ? `cut ${folder.cutId.slice(0, 8)} has none under ${dirname(receiptPathFor(CUT_ID.test(folder.cutId) ? folder.cutId : "0".repeat(32)))}` : "its carveout.json names no cut"}. A folder that comes back is judged by the receipt its cut wrote: pass --receipt <file>, or --no-receipt to judge it by its own record, checked against the repository.`);
+    }
+    if (!existsSync(path))
+        throw new Error(`${path}: no such receipt.`);
+    return vouched(dir, folderOwn, readReceipt(path), path);
+}
+/**
+ * The record a command on a folder acts on, by a receipt given as data
+ * (`api.ts`): checked as `trustedCut` checks a receipt file, with no
+ * receipt looked for under `CARVEOUT_HOME`.
+ */
+export function trustedCutWith(dir, given) {
+    const receipt = asReceipt(given);
+    const folderOwn = existsSync(join(resolve(dir), RECORD_PATH)) ? readRecord(dir) : null;
+    return vouched(dir, folderOwn, receipt, null);
+}
+/** The folder's record held to its receipt: refused when they are not one cut's. */
+function vouched(dir, folderOwn, receipt, path) {
+    const named = path ?? "The receipt given";
+    const view = folderView(receipt);
+    const folder = folderOwn ?? view;
+    if (folder.cutId !== undefined && folder.cutId !== receipt.cutId)
+        throw new Error(`${named} is the receipt of cut ${receipt.cutId.slice(0, 8)}, and the folder says it is cut ${String(folder.cutId).slice(0, 8)}: name the receipt of this folder's cut.`);
+    // A folder whose generated files are another cut's is not this receipt's.
+    const shape = (record) => record.generated
+        .map((file) => file.path)
+        .filter((file) => file !== "package-lock.json")
+        .sort()
+        .join("\n");
+    // A folder holds the cut's own files (the folder's view), or, renamed
+    // back for a patch, the cut's record itself.
+    if (folderOwn !== null && shape(folderOwn) !== shape(view) && shape(folderOwn) !== shape(receipt.record))
+        throw new Error(`${dir} does not hold the files of cut ${receipt.cutId.slice(0, 8)}'s folder: name the receipt of the cut that wrote it.`);
+    // A public record names no checkout; the receipt does.
+    const record = receipt.record.repo === undefined ? { ...receipt.record, repo: receipt.repo } : receipt.record;
+    return { record, folder, receipt, receiptPath: path };
+}
+/**
+ * The record a public folder carries: what the folder's own commands need
+ * (its files and their hashes, what it stubs, its tests), less what names
+ * the repository beyond the slice, which the receipt keeps: the commit and
+ * the graph's hash, the hashes of the repository's other files, the
+ * specifiers the cut rewrote (a workspace package's name, a path alias),
+ * and the private paths the owner keeps out.
+ */
+export function publicRecord(record) {
+    const { private: _private, ...params } = record.manifest.params;
+    const { private: _requestPrivate, choices: _choices, task: _task, ...request } = record.request;
+    const { repo: _repo, ...rest } = record;
+    const unnamed = (edge) => ({ ...edge, specifier: null });
+    // A slice file's original hash, blob id and size confirm a guess at what
+    // it held before the cut rewrote it: the folder's own copy's stand in.
+    const copied = new Map((record.copied ?? []).map((file) => [file.path, file.sha256]));
+    return {
+        ...rest,
+        manifest: {
+            ...record.manifest,
+            sourceCommitSha: null,
+            graphSha256: "",
+            boundaryContractSha256: "",
+            params,
+            included: record.manifest.included.map((file) => {
+                const own = copied.get(file.path);
+                return own === undefined ? file : { ...file, blobId: "", sha256: own };
+            }),
+            internalImports: record.manifest.internalImports.map(unnamed),
+            cuts: {
+                ...record.manifest.cuts,
+                outbound: record.manifest.cuts.outbound.map(unnamed),
+                inbound: record.manifest.cuts.inbound.map(unnamed),
+            },
+        },
+        importRewrites: [],
+        inputs: [],
+        request: { ...request, choices: {} },
+        // Commits name the repository's history: the receipt keeps them.
+        bases: undefined,
+        publicScrubbed: true,
+    };
+}
+/**
+ * The record a public folder holds, made from the cut's: scrubbed
+ * (`publicRecord`), a leak's blocker kept without the name it is about,
+ * and for a folder in pseudonyms, in its names, with its files' folder
+ * paths and the hashes of what the folder holds at them (`dir`), so its
+ * own commands (the coverage guard, check) read it as written.
+ */
+export function folderRecordFor(record, table, dir, 
+/** A hash already known for a folder path, over what the folder holds there now. */
+known = () => undefined) {
+    const scrubbed = publicRecord(record);
+    const quiet = {
+        ...scrubbed,
+        blockers: scrubbed.blockers.map((blocker) => blocker.code === "vocabulary_leaked"
+            ? { code: blocker.code, file: null, detail: "A name the repository goes by is still in the folder; the maintainer has the list." }
+            : blocker),
+    };
+    if (table === undefined)
+        return quiet;
+    const renamed = recordToFolder(table, quiet);
+    // A path the cut never saw (a file apply grew) takes its words too, when
+    // they map back.
+    const pathOf = (path) => exactToFolder(table, path, "")?.path ?? toFolder(table, path, "").path;
+    const hashAt = (path) => {
+        const given = known(path);
+        if (given !== undefined)
+            return given;
+        const at = join(resolve(dir), path);
+        return existsSync(at) ? createHash("sha256").update(readFileSync(at)).digest("hex") : "";
+    };
+    const asWritten = (entry) => ({
+        path: pathOf(entry.path),
+        sha256: hashAt(pathOf(entry.path)),
+        ...(entry.applied === true ? { applied: true } : {}),
+    });
+    return {
+        ...renamed,
+        manifest: {
+            ...renamed.manifest,
+            included: record.manifest.included.map((file) => ({ ...file, path: pathOf(file.path), blobId: "", sha256: hashAt(pathOf(file.path)) })),
+        },
+        generated: record.generated.map(asWritten),
+        ...(record.copied === undefined ? {} : { copied: record.copied.map(asWritten) }),
+        ...(record.extras === undefined ? {} : { extras: record.extras.map(asWritten) }),
+    };
+}
+/**
+ * Writes a record a command changed (`apply` growing the slice, writing
+ * stubs) to the folder and, when the cut has one, to its receipt: the
+ * folder's copy public-scrubbed as the cut wrote it.
+ */
+export function saveRecord(dir, trusted, updated, 
+/** Generated files the command wrote into the folder, by folder path. */
+written = {}, 
+/**
+ * Slice files whose hash the record takes anew, by folder path: as the
+ * command wrote them, the folder's edits aside (`refresh` moving the
+ * folder's base). Every other path keeps the hash it had.
+ */
+rebased = new Map()) {
+    const scrub = trusted.receipt !== null && updated.request.public === true;
+    // Each path keeps the hash the folder's record had for it: the folder's
+    // edits since are still edits, and a file an earlier apply wrote still
+    // differs from the cut's, so the next apply merges into it rather than
+    // over it. Only a generated file the command wrote, or a path new to the
+    // record, is hashed as the folder holds it now.
+    const previous = new Map();
+    const before = trusted.receipt?.folderRecord;
+    if (before !== undefined)
+        for (const file of [...before.manifest.included, ...before.generated, ...(before.copied ?? []), ...(before.extras ?? [])])
+            if (file.sha256 !== "")
+                previous.set(file.path, file.sha256);
+    const known = (path) => {
+        const text = written[path];
+        return text !== undefined ? createHash("sha256").update(text).digest("hex") : (rebased.get(path) ?? previous.get(path));
+    };
+    const folder = scrub ? folderRecordFor(updated, trusted.receipt?.pseudonyms, dir, known) : updated;
+    writeFileSync(join(resolve(dir), RECORD_PATH), `${JSON.stringify(folder, null, 2)}\n`);
+    if (trusted.receipt === null || trusted.receiptPath === null)
+        return { ...trusted, record: updated, folder };
+    // The receipt keeps the record as the cut makes it, checkout included,
+    // and the folder's own when it differs.
+    const { repo: _repo, ...kept } = updated;
+    const record = (trusted.receipt.record.repo === undefined ? kept : updated);
+    const receipt = {
+        ...trusted.receipt,
+        record,
+        ...(trusted.receipt.folderRecord === undefined ? {} : { folderRecord: folder }),
+        ...(trusted.receipt.generatedText === undefined
+            ? {}
+            : { generatedText: { ...trusted.receipt.generatedText, ...written } }),
+    };
+    writeReceipt(trusted.receiptPath, receipt);
+    return { ...trusted, record: updated, folder, receipt };
+}
+/**
+ * The baseline a check of the folder reads, given its receipt and the
+ * folder's own `carveout/baseline.json` (its failing names, or null when it
+ * has none): the receipt's when it holds one, none when the receipt holds
+ * none (a baseline the receipt never saw is not read), the folder's own
+ * when there is no receipt to judge it by. `edited` names what the
+ * folder's own adds beyond the receipt's.
+ */
+export function trustedBaseline(receipt, folder) {
+    if (receipt === null)
+        return { use: "folder", edited: [] };
+    const known = receipt.baseline ?? null;
+    const edited = (folder ?? []).filter((name) => known === null || !known.includes(name)).sort();
+    return { use: known, edited };
+}

package/dist/src/sandbox.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Running code that came back from outside in a container.
+ *
+ * A folder that came back holds the contributor's code, and its tests run
+ * it. On the maintainer's machine that code would run as the maintainer,
+ * with their files (the closed repository, the receipts that map the
+ * folder's pseudonyms back to the repository's names, credentials) and
+ * their network. Here each step is its own `docker run --rm` that mounts one
+ * directory, the scratch copy, and nothing else: no HOME, no receipts, no
+ * checkout beyond the copy. Only the install step has a network, and it runs
+ * a package manager with lifecycle scripts off on the receipt's manifests,
+ * so none of the folder's code runs while the network is there. Every other
+ * step (the build, the tests, the owner's acceptance tests, a merge's
+ * verify command) runs with `--network none`, all capabilities dropped, a
+ * read-only root, and bounds on memory and processes.
+ *
+ * Docker by default; `CARVEOUT_CONTAINER` names another runtime that takes
+ * the same arguments (podman), and `CARVEOUT_SANDBOX_IMAGE` the image (a
+ * Node image at this process's major version unless given).
+ */
+export interface SandboxSpec {
+    /** The container runtime's executable: `docker`, or one that takes its arguments. */
+    readonly runtime: string;
+    /** The image every step runs in: it needs `node`, `npm` and `sh`. */
+    readonly image: string;
+}
+/** The runtime and image from the environment, or Docker and a Node image at this process's major version. */
+export declare function defaultSandbox(image?: string): SandboxSpec;
+/**
+ * Why the sandbox cannot run, or null when it can: the runtime answers, its
+ * daemon runs Linux containers, and the image is there or can be pulled.
+ */
+export declare function sandboxUnavailable(spec: SandboxSpec): string | null;
+/** Where a directory under the mounted one is inside the container. */
+export declare const MOUNT = "/work";
+/**
+ * Runs one command in a fresh container that mounts `root` at `/work` and
+ * nothing else, in `cwd` (a directory under `root`). Host paths under
+ * `root` in the arguments are rewritten to the container's, and this Node's
+ * own path to `node`. Only the names in `env` are passed, with HOME and the
+ * npm cache in the container's own /tmp. With `network` false the container
+ * has none. At `limitMs` the container is killed.
+ */
+export declare function sandboxRun(spec: SandboxSpec, root: string, command: readonly string[], options: {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly network: boolean;
+    readonly limitMs?: number;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    status: number | null;
+}>;