carveout 0.1.1 → 0.1.2

package/dist/src/carve.d.ts

@@ -0,0 +1,788 @@
+/**
+ * The four things carveout does with a checkout: plan a slice, cut it into
+ * a folder, check that the folder installs, builds and tests on its own,
+ * and turn the edits made there back into a patch for the checkout.
+ *
+ * The plan and the cut read the checkout and never run its code. The cut
+ * may fetch the published types of the packages the slice reads (install
+ * scripts off, the public registry only) and resolves the folder's
+ * lockfile with npm; `offline` skips both.
+ */
+import { type BoundaryContract, type CoverageGate, type DependencyChoice, type GeneratedFile, type ImportRewrite, type ReachResult, type ResolvedDependency, type SliceBudget, type SliceManifest, type SliceExternals, type SliceExposure, type SliceTestLeft, type TestRunner } from "./core.js";
+import { type Refusal } from "./policy.js";
+import { type SandboxSpec } from "./sandbox.js";
+import { type Readiness } from "./readiness.js";
+import { type AliasRule, type FolderPseudonyms } from "./pseudonyms/index.js";
+import { type Receipt } from "./receipt.js";
+export declare const CARVEOUT_VERSION = "0.1.2";
+export declare const RECORD_PATH = "carveout.json";
+export declare const RECORD_SCHEMA_VERSION = 1;
+export declare const BOUNDARY_PATH = "BOUNDARY.md";
+/** What a coding agent reads first in the folder, loaded without asking. */
+export declare const SLICE_AGENTS_PATH = "AGENTS.md";
+/** Claude Code's name for the same: it imports AGENTS.md. */
+export declare const SLICE_CLAUDE_PATH = "CLAUDE.md";
+/**
+ * The folder's AGENTS.md: what an agent needs before its first command.
+ * Agents in slices opened BOUNDARY.md and carveout/test.js in most runs,
+ * and the README, which says this, in under half (E6c and E8 transcripts):
+ * a file the agent's harness loads by itself saves those reads.
+ */
+export declare function renderSliceAgents(input: {
+    readonly entryPoints: readonly string[];
+    readonly testsInFolder: number;
+    readonly testsLeft: number;
+    /** Whether the folder carries a TASK.md: the work asked for, and when it is accepted. */
+    readonly task?: boolean;
+    /** Where the package's test script finds its tests, from the folder's root (`packages/core/test/*.test.ts`). */
+    readonly testsAt?: string;
+    /** The coverage the package's test script holds it to, which the folder's `npm test` holds added files to. */
+    readonly coverage?: CoverageGate;
+    /** The runner the package's own tests run on, by its test script. */
+    readonly runner?: "vitest" | "node:test";
+    /** The Prettier the repository formats with, at the version it locks, and the folder's copy of its settings, if any. */
+    readonly prettier?: {
+        readonly version: string;
+        readonly config: string | null;
+    };
+    /** Whether the package has a lint script, which the folder cannot run. */
+    readonly lint?: boolean;
+}): string;
+/**
+ * The packages whose types a file's errors are about: of the packages
+ * `candidate` accepts that the file imports, those whose imported names a
+ * type names in the declaration around an error's line (`Pick<Stripe.
+ * Customer, …>`), or anywhere in the file for an error with no line. A
+ * service package imported beside one, for its values alone, is not:
+ * installed, it would run against a service the folder has none of.
+ */
+export declare function packagesTypingLines(path: string, text: string, lines: readonly (number | null)[], candidate: (name: string) => boolean): Set<string>;
+/**
+ * The runner the entry points' package's tests run on, by its test script:
+ * `vitest` (Vitest), `node --test` (node:test), or null when the script
+ * says neither or there is none.
+ */
+export declare function packageTestRunner(repo: string, entryPoints: readonly string[]): "vitest" | "node:test" | null;
+/** The folder's TASK.md: the work asked for, in the owner's words, and when it is accepted. */
+export declare function renderTask(input: {
+    readonly task: string;
+    readonly testsInFolder: readonly string[];
+    readonly surface: number;
+    /** How many checks of them `npm test` makes, as its last line counts them. */
+    readonly surfaceChecks?: number;
+    /** The package's own check scripts, by name, for what CI checks. */
+    readonly ci?: readonly string[];
+    /** Where the package's test script finds its tests, from the folder's root. */
+    readonly testsAt?: string;
+    /** Whether the owner keeps acceptance tests of their own, which the folder does not hold. */
+    readonly ownerTests?: boolean;
+}): string;
+export declare const CONTRACT_PATH = "carveout/contract.json";
+/** The repository owner's settings for every cut of it, at its root. */
+export declare const CONFIG_PATH = "carveout.config.json";
+/**
+ * What a repository's owner sets once for every slice cut from it, in
+ * `carveout.config.json` at the root: where the cut may follow and what it
+ * must keep out. A flag on the command line overrides a boolean here; the
+ * lists are joined. Nothing here is read from the slice folder.
+ */
+export interface RepoConfig {
+    /** See `SliceRequest.wholePackage`. */
+    readonly wholePackage?: boolean;
+    /** See `SliceRequest.followWorkspaces`. */
+    readonly followWorkspaces?: boolean;
+    /** Paths or globs never copied; see `SliceRequest.private`. */
+    readonly private?: readonly string[];
+    /** Folders copied in whole beside the slice; see `CutRequest.copy`. */
+    readonly copy?: readonly string[];
+    /** Widen literal types in every stub; see `CutRequest.widenLiterals`. */
+    readonly widenLiterals?: boolean;
+    /** Every cut is for someone outside; see `CutRequest.public`. */
+    readonly public?: boolean;
+    /** Copy pure code rather than mock it; see `SliceRequest.copyPure`. */
+    readonly copyPure?: boolean;
+    /**
+     * Names a public folder must not carry, beyond those carveout finds
+     * (the organization's, its products', its customers'): scanned word by
+     * word and given pseudonyms. See `pseudonyms/folder.ts`.
+     */
+    readonly names?: readonly string[];
+    /**
+     * Renames the owner chooses, applied to a public folder before the ones
+     * carveout drafts: `{ "before": "Acme", "after": "Shop", "kind": "text" }`
+     * (kind `identifier`, `text` or `path`).
+     */
+    readonly pseudonyms?: readonly AliasRule[];
+    /** Names carveout finds that the owner lets a public folder carry (a word the code is about). */
+    readonly keepNames?: readonly string[];
+    /** The most lines a folder may show; see `SliceRequest.maxExposure`. */
+    readonly maxExposureLines?: number;
+    /** The most a folder may show, as a percent of the repository's TypeScript lines; see `SliceRequest.maxExposure`. */
+    readonly maxExposurePercent?: number;
+}
+/** The owner's settings at the repository's root; empty when there are none. */
+export declare function readRepoConfig(repo: string): RepoConfig;
+/**
+ * Whether bytes are text a table may rename: no NUL in their first 8 KiB,
+ * and valid UTF-8 throughout. A PDF or an archive in a copied folder is
+ * not, whatever its name; decoded and written back it would be corrupted.
+ */
+export declare function isTextContent(bytes: Buffer): boolean;
+/** Assets that are not text: copied and compared as bytes. */
+export declare function isBinaryPath(path: string): boolean;
+/** `~/.carveout`, or `CARVEOUT_HOME`: where fetched package types are kept. */
+export declare function carveoutHome(): string;
+export interface SliceRequest {
+    /** The checkout's root: where its lockfile and workspace manifest are. */
+    readonly repo: string;
+    /** Files or directories, relative to the root. */
+    readonly entryPoints: readonly string[];
+    readonly budget?: SliceBudget;
+    /** Also bring along the tests outside the slice that import it. */
+    readonly tests?: boolean;
+    /**
+     * Include every file of the entry points' package the walk reaches, at
+     * any depth, so the cut falls at package and service boundaries only.
+     * Unset: as `carveout.config.json` says, else off.
+     */
+    readonly wholePackage?: boolean;
+    /**
+     * Follow an import of one of the repository's own packages into its
+     * source rather than stubbing the package at the seam. Unset: as the
+     * configuration says, else off.
+     */
+    readonly followWorkspaces?: boolean;
+    /**
+     * Copy the pure code the slice runs (a validator, an error class, a
+     * formatter from another module or package) rather than mock it, so its
+     * tests run against the real code and do not fail on the mocks before
+     * any change. Follows the workspaces unless `followWorkspaces` is false.
+     * The copied code is the contributor's to read. Unset: as the
+     * configuration says, else off.
+     */
+    readonly copyPure?: boolean;
+    /**
+     * Paths or globs from the root that are never copied: cut and stubbed
+     * wherever reached, their literal values widened. Joined with the
+     * configuration's.
+     */
+    readonly private?: readonly string[];
+    /**
+     * Files the cut never reads, as if the checkout had none: the owner's
+     * acceptance tests, which no folder may hold nor be shaped by (a test
+     * that imports the slice would come along, or make what it imports part
+     * of the public surface). Kept in the receipt for later cuts, never in
+     * the folder's record.
+     */
+    readonly unseen?: readonly string[];
+    /**
+     * How much of the repository a folder may show: every line it copies
+     * (entry points, tests and copied code alike, as `plan`'s "Shows" line
+     * counts them), at most `lines`, and at most `percent` of the
+     * repository's TypeScript lines (`.d.ts` and `node_modules` left out). A
+     * cut past either is written with an `exposure_exceeded` blocker, so a
+     * hand-off is not ready. Each unset: as the configuration says
+     * (`maxExposureLines`, `maxExposurePercent`), else no bound.
+     */
+    readonly maxExposure?: {
+        readonly lines?: number;
+        readonly percent?: number;
+    };
+}
+/** A folder's lines against the owner's bound, with the repository's TypeScript lines when a percent is asked. */
+export interface ExposureBudget {
+    readonly lines?: number;
+    readonly percent?: number;
+    /** The repository's TypeScript lines, when `percent` is set. */
+    readonly repositoryLines?: number;
+    /** The folder's lines as a percent of them, when `percent` is set. */
+    readonly shownPercent?: number;
+    /** What is over, in words; null within the bound. */
+    readonly over: string | null;
+}
+/** The repository's TypeScript source lines, as `experiments/hero-exposure.mjs` counts them: tracked `.ts`, `.tsx`, `.mts`, `.cts` files, `.d.ts` and `node_modules` left out. */
+export declare function repositoryTypeScriptLines(repo: string): number;
+/** The folder's exposure against the bound the request settled on; null when there is none. */
+export declare function exposureBudget(repo: string, exposure: SliceExposure, bound: {
+    readonly lines?: number;
+    readonly percent?: number;
+}): ExposureBudget | null;
+export interface Plan {
+    readonly repo: string;
+    readonly entryPoints: readonly string[];
+    readonly budget: SliceBudget;
+    readonly graphFiles: number;
+    readonly walk: ReachResult;
+    readonly externals: SliceExternals;
+    /** Bare specifiers the slice imports, by package name, sorted. */
+    readonly packages: readonly string[];
+    /** Of those, the repository's own workspace packages, which are stubbed. */
+    readonly workspacePackages: readonly string[];
+    /** Files a slice never copies: credentials files it reached. */
+    readonly secretFiles: readonly string[];
+    /** Cut modules, sorted. */
+    readonly cutModules: readonly string[];
+    /** Of those, the ones the slice imports only types from. */
+    readonly typeOnlyCuts: readonly string[];
+    /** How the walk was bounded, after the configuration. */
+    readonly wholePackage: boolean;
+    readonly followWorkspaces: boolean;
+    readonly copyPure: boolean;
+    readonly private: readonly string[];
+    /** The files and lines the cut would copy, by why each is there. */
+    readonly exposure: SliceExposure;
+    /** The exposure against the owner's bound; absent when none is set. */
+    readonly exposureBudget?: ExposureBudget;
+    /**
+     * The slice's modules that code outside it imports, with the names it
+     * takes (`"*"`: the whole module) and the importers, a workspace
+     * package's importers by its name included: what a cut's surface check
+     * holds to its types. Read from the import graph; the cut's
+     * `carveout/contract.json` has the compiler's reading.
+     */
+    readonly surface: readonly PlanSurface[];
+    /** The runner each test brought along runs on, by file. */
+    readonly testRunners: Readonly<Record<string, TestRunner>>;
+}
+/** One module of a plan's public surface. */
+export interface PlanSurface {
+    readonly module: string;
+    readonly names: readonly string[] | "*";
+    readonly importers: readonly string[];
+}
+/** What stops a plan's cut, one line each: entry points that name nothing, imports no slice can carry, credentials files. */
+export declare function planBlockers(plan: Plan): string[];
+/** `purityRules` over the repository's files. */
+export declare function pureRulesFor(repo: string): {
+    readonly package: (specifier: string) => boolean;
+    readonly sideEffects: (file: string) => boolean;
+};
+/** What a cut of the request would hold, from the import graph alone. */
+export declare function planSlice(request: SliceRequest): Plan;
+export interface CutRequest extends SliceRequest {
+    readonly out: string;
+    /** Packages to install or to mock, overriding the default. */
+    readonly choices?: Readonly<Record<string, DependencyChoice>>;
+    /** No network: packages stay untyped and the folder has no lockfile. */
+    readonly offline?: boolean;
+    /**
+     * Widen literal types in stubs (`"live"` to `string`), so no constant's
+     * value from a cut module is written; for a folder handed to someone
+     * outside. Off by default: the stubs then type-check as the source does.
+     */
+    readonly widenLiterals?: boolean;
+    /**
+     * Service packages kept real rather than mocked (`--live`): installed and
+     * typed as the repository has them, and the environment the files that
+     * import them read is left out of `carveout.env`, so the shell's values
+     * or the code's own defaults apply. For a package whose tests need the
+     * service itself: a database driver against a local server.
+     */
+    readonly live?: readonly string[];
+    /**
+     * Folders (or files) copied in whole beside the slice, as paths from the
+     * root: what the code reads by a name the walk cannot follow, such as a
+     * migrations folder. Their files are neither slice nor generated: the
+     * patch carries an edit to one. Joined with the configuration's.
+     */
+    readonly copy?: readonly string[];
+    /**
+     * A folder for someone outside the repository: literals widened unless
+     * asked otherwise, and the maintainer's paths left out of what is
+     * written, the checkout's location and the files outside the slice that
+     * import it (each named by its package folder only). Commands that need
+     * the repository then take `--repo`.
+     */
+    readonly public?: boolean;
+    /**
+     * Where to write the maintainer's receipt (`receipt.ts`): a file path,
+     * or false for none. By default `CARVEOUT_HOME/receipts/<cut id>.json`.
+     * A public folder's own record keeps the repository's names out only
+     * when there is a receipt to hold them.
+     */
+    readonly receipt?: string | false;
+    /**
+     * Keep the receipt as data only (`CutResult.receiptData`), written to no
+     * file: the library's cut (`api.ts`), whose caller stores it.
+     */
+    readonly receiptInMemory?: boolean;
+    /** Where fetched package types are kept; by default `CARVEOUT_HOME/types`. */
+    readonly typesCache?: string;
+    /**
+     * More names a public folder must not carry (`--name`), joined with the
+     * configuration's. See `pseudonyms/folder.ts`.
+     */
+    readonly names?: readonly string[];
+    /**
+     * False writes a public folder in the repository's own names (the leak
+     * scan still runs). On by default for a public cut with a receipt.
+     */
+    readonly pseudonyms?: boolean;
+    /**
+     * The work asked for, in the owner's words: written to the folder's
+     * TASK.md with when it is accepted (renamed with the folder in pseudonyms).
+     */
+    readonly task?: string;
+    /**
+     * An earlier cut's pseudonyms (`widen`): a term keeps the placeholder it
+     * had where it still fits, so the contributor reads the same names.
+     */
+    readonly earlierPseudonyms?: FolderPseudonyms;
+    readonly log?: (line: string) => void;
+}
+/** What `carveout.json` holds: the cut, and how to undo its rewrites. */
+export interface CarveoutRecord {
+    readonly schemaVersion: typeof RECORD_SCHEMA_VERSION;
+    readonly carveoutVersion: string;
+    /**
+     * The cut's random id: the name of the maintainer's receipt
+     * (`receipt.ts`), which holds this record as the cut made it. Absent in
+     * records made before receipts.
+     */
+    readonly cutId?: string;
+    /**
+     * A public folder's record, less what names the repository beyond the
+     * slice (`publicRecord`): commands that need it read the receipt.
+     */
+    readonly publicScrubbed?: boolean;
+    /**
+     * The checkout the slice was cut from, as given. Absent from a `public`
+     * cut, which leaves the maintainer's paths out: commands that need the
+     * repository then take `--repo`.
+     */
+    readonly repo?: string;
+    readonly manifest: SliceManifest;
+    readonly dependencies: readonly ResolvedDependency[];
+    /**
+     * Optional peers of the installed packages the repository installs and
+     * the folder does not; `--install <name>` adds one.
+     */
+    readonly optionalPeers: readonly {
+        name: string;
+        version: string;
+        of: string;
+    }[];
+    readonly importRewrites: readonly ImportRewrite[];
+    /** Files carveout wrote, by path, with their hashes; never the slice's. */
+    readonly generated: readonly {
+        path: string;
+        sha256: string;
+    }[];
+    /**
+     * The slice's own files as written, imports rewritten, with their hashes:
+     * what an edit since the cut is measured against (the coverage gate).
+     */
+    /**
+     * What the folder holds of each slice file as the cut (or a later apply)
+     * wrote it; `applied` marks a file a patch brought in, which no cut of
+     * the repository wrote: the folder holding one is edited.
+     */
+    readonly copied?: readonly {
+        path: string;
+        sha256: string;
+        applied?: true;
+    }[];
+    /**
+     * The commit a slice file's base is at, where refresh moved it on its
+     * own and the record's commit stayed (an overlap elsewhere held it).
+     */
+    readonly bases?: Readonly<Record<string, string>>;
+    readonly lockfile: boolean;
+    readonly blockers: readonly {
+        readonly code: string;
+        readonly file: string | null;
+        readonly detail: string;
+    }[];
+    readonly ready: boolean;
+    /** What the cut was asked, so `status` can ask it again. */
+    readonly request: {
+        readonly entryPoints: readonly string[];
+        readonly budget: SliceBudget;
+        readonly choices: Readonly<Record<string, DependencyChoice>>;
+        readonly offline: boolean;
+        readonly widenLiterals: boolean;
+        /** Absent in records made before tests could be brought along. */
+        readonly tests?: boolean;
+        /** Service packages kept real; absent when none. */
+        readonly live?: readonly string[];
+        /** The cut's bounds after the configuration; absent when off or none. */
+        readonly wholePackage?: boolean;
+        readonly followWorkspaces?: boolean;
+        readonly copyPure?: boolean;
+        readonly private?: readonly string[];
+        readonly copy?: readonly string[];
+        /** A folder for someone outside; see `CutRequest.public`. */
+        readonly public?: boolean;
+        /** The work asked for (`--task`), in the repository's names; the receipt's only. */
+        readonly task?: string;
+    };
+    /**
+     * Files copied in whole from the `copy` folders, with their hashes: not
+     * the slice's, not generated, and in the patch when edited. Absent in
+     * records made before folders could be copied.
+     */
+    readonly extras?: readonly {
+        path: string;
+        sha256: string;
+    }[];
+    /**
+     * The repository's files the cut resolved with, beyond the slice: compiler
+     * and package configuration, workspace manifests and lockfiles.
+     */
+    readonly inputs: readonly {
+        path: string;
+        sha256: string | null;
+    }[];
+    /**
+     * The tests that run the slice's code: those in the folder, and those
+     * left in the repository with the reason (a public cut names each by its
+     * package). Absent in records made before the account.
+     */
+    readonly tests?: {
+        readonly verdict: string;
+        readonly carried: readonly string[];
+        readonly left: readonly SliceTestLeft[];
+    };
+    /** What the folder shows of the repository; see `exposureOf`. */
+    readonly exposure?: SliceExposure;
+    /**
+     * What would make the folder's tests run on real code (`readinessOf`).
+     * Absent from a public cut, whose advice may name paths the folder does
+     * not show, and from records made before it.
+     */
+    readonly readiness?: Readiness;
+}
+export interface CutResult {
+    readonly out: string;
+    readonly record: CarveoutRecord;
+    readonly contract: BoundaryContract;
+    /** What would make the folder's tests run on real code, public cut or not. */
+    readonly readiness: Readiness;
+    /** The receipt the cut wrote, or null when asked for none or kept in memory. */
+    readonly receipt: string | null;
+    /** The receipt as data, written or not; null when asked for none. */
+    readonly receiptData: Receipt | null;
+    /**
+     * A public folder's pseudonyms, as the receipt keeps them (the table and
+     * the kept package names); null for a cut in the repository's names.
+     */
+    readonly pseudonyms: FolderPseudonyms | null;
+}
+/**
+ * What a cut could change so the folder's tests run on the repository's
+ * code instead of mocks (see `readiness.ts`): the pure modules
+ * `--copy-pure` would copy, read from a second walk with it on; the mocked
+ * database, cache and queue clients `--live` could keep real; the folders
+ * the slice's packages read by a configured name, for `--copy`. Only for a
+ * cut that carries tests: a folder without them has nothing to turn green.
+ */
+export declare function readinessOf(request: SliceRequest & {
+    readonly copy?: readonly string[];
+    readonly public?: boolean;
+}, record: Pick<CarveoutRecord, "manifest" | "dependencies" | "tests" | "request">): Readiness;
+export interface LockedPeer {
+    readonly name: string;
+    readonly version: string;
+    /** The installed package whose install tree asks for it. */
+    readonly of: string;
+    readonly optional: boolean;
+}
+/** The version the repository's npm lockfile installs `name` at, at its root. */
+export declare function lockedVersion(repo: string, name: string): string | null;
+/**
+ * A package-lock.json for the folder seeded from the repository's: every
+ * package the repository installs, at the version it installs it, the
+ * slice's workspaces' own installs over the root's (the first workspace
+ * last, so it wins). npm keeps a seeded version that satisfies the range
+ * and prunes the rest, so the folder runs what the repository runs rather
+ * than what the registry has newest. Null without an npm lockfile.
+ */
+export declare function seededLockfile(repo: string, workspaces: readonly string[], root: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * Takes out of a resolved lock what npm left with nothing to install it
+ * under: an entry nested under a package the lock no longer has
+ * (`node_modules/vitest/node_modules/magic-string` once `vitest` went),
+ * and one npm marked extraneous. npm's `--package-lock-only` marks such
+ * entries rather than dropping them, and an npm other than the one that
+ * resolved the lock may install them. How many it took out.
+ */
+export declare function pruneLock(lock: {
+    packages?: Record<string, Record<string, unknown>>;
+}): number;
+/**
+ * Peers of the installed packages, and of what they install, that the
+ * repository's npm lockfile installs at its root for production: a
+ * package the slice does not import but one it installs needs, at the
+ * version the repository runs with. Optional peers are marked; the cut
+ * installs only the others unless asked. Empty without a lockfile.
+ */
+export declare function lockedPeers(repo: string, installed: readonly string[]): LockedPeer[];
+/**
+ * The version the repository gives `name`: its npm lockfile's, else the
+ * pin in the nearest package.json above one of `files`, else the root's.
+ */
+export declare function repositoryVersion(repo: string, name: string, files: readonly string[]): string | null;
+/** A cut held in memory: every file it writes, and its record but the lockfile. */
+export interface ComputedCut {
+    readonly files: readonly GeneratedFile[];
+    /** Included files copied as bytes. */
+    readonly binaries: readonly string[];
+    /** The `copy` folders' files, copied as bytes; see `CarveoutRecord.extras`. */
+    readonly extras: readonly string[];
+    readonly record: Omit<CarveoutRecord, "generated" | "lockfile">;
+    readonly contract: BoundaryContract;
+}
+export declare function computeCut(request: Omit<CutRequest, "out">): Promise<ComputedCut>;
+/**
+ * The packages whose classes the code tests with `instanceof`, by package
+ * name with the class as written: `import Anthropic from
+ * "@anthropic-ai/sdk"` and `instanceof Anthropic.APIError` in the same
+ * file, or a named or namespace import on the right of one. The
+ * repository's own packages and Node's are not among them.
+ */
+export declare function instanceofPackages(sources: readonly {
+    path: string;
+    text: string;
+}[], workspaces: ReadonlySet<string>): Map<string, string>;
+export declare function cutSlice(request: CutRequest): Promise<CutResult>;
+export declare function readRecord(dir: string): CarveoutRecord;
+/**
+ * Throws unless every file the record says the slice holds is one of the
+ * repository's, at the bytes the cut read: its hash must be the blob's at
+ * the cut's commit, or the checkout's file's (a cut of uncommitted bytes).
+ * The record comes back with the folder, and its `included` list decides
+ * which files a patch may edit or delete and which packages may gain a new
+ * file: an entry added there for a cut module, with any hash, would carry
+ * an edit or a deletion of that module past the hand-off policy. Forging
+ * one now takes the file's exact bytes, which a slice never shows.
+ */
+export declare function checkRecordFiles(record: CarveoutRecord, repo: string): void;
+export interface CheckStep {
+    readonly command: string;
+    readonly ok: boolean;
+    readonly output: string;
+    /** Tests that failed in an unedited folder, recorded as its baseline. */
+    readonly baseline?: readonly string[];
+    /**
+     * The `npm test` step's counts of the folder's tests, read from its TAP:
+     * node:test's and Vitest's together, then each runner's, with carveout's
+     * own checks of the public surface (exports and types kept) apart.
+     */
+    readonly counts?: TestCounts;
+    /**
+     * Tests the folder's `carveout/baseline.json` names and the receipt's
+     * does not: added since the check that recorded it, by whoever had the
+     * folder. They were counted.
+     */
+    readonly baselineEdited?: readonly string[];
+    /** Whether the folder holds an edit since the cut (a folder that came back). */
+    readonly edited?: boolean;
+    /** The tests `npm test` did not count: the baseline in effect for the run. */
+    readonly baselineInEffect?: readonly string[];
+    /** Generated files the folder changed, put back from the receipt for the run. */
+    readonly restored?: readonly string[];
+    /** Packages the folder's package.json added, which the run did not install. */
+    readonly addedPackages?: readonly string[];
+    /** Whether a receipt vouched for the record and baseline the run read. */
+    readonly receiptRead?: boolean;
+}
+/** How many of a folder's tests pass, as `npm test` counted them. */
+export interface TestCounts {
+    readonly tests: number;
+    readonly pass: number;
+    readonly fail: number;
+    /** Each runner's: `node:test`, `vitest`. */
+    readonly runners?: Readonly<Record<string, {
+        readonly tests: number;
+        readonly pass: number;
+        readonly fail: number;
+    }>>;
+    /** carveout's own checks that the public surface keeps its exports and their types. */
+    readonly surface?: {
+        readonly checks: number;
+        readonly fail: number;
+    };
+}
+/** The counts the runner wrote as JSON (`COUNTS_PATH`), or undefined when they do not read. */
+export declare function countsFromJson(text: string): TestCounts | undefined;
+/**
+ * The counts in a run's TAP: the runner's `# carveout` lines, or, from a
+ * folder cut before they were written, node:test's own summary (which
+ * counts the interface test's checks among the tests).
+ */
+export declare function countsOf(tap: string): TestCounts | undefined;
+/**
+ * Whether a folder holds someone else's work: edited since the cut, by the
+ * receipt's hashes. With no receipt it is taken as edited: the folder's own
+ * record came back with it and cannot vouch that it is not.
+ */
+export declare function folderCameBack(dir: string, options?: {
+    readonly receipt?: string;
+    readonly noReceipt?: boolean;
+}): boolean;
+/** The package names the slice's files spell as specifiers, at the cut's commit (or as the checkout holds them). */
+export declare function sliceSpecifierPackages(record: CarveoutRecord, repo: string | null | undefined): string[];
+/**
+ * Installs, builds and tests the folder, in a scratch copy so the folder
+ * itself is left as it was; stops at the first step that fails.
+ *
+ * A folder that came back is run as the receipt's cut made it: its
+ * generated files (the test runner, the harness, the manifests and the
+ * stubs) are put back from the receipt, a file the folder added under
+ * `carveout/` is taken out, the baseline read is the receipt's, and a
+ * folder with a symbolic link is not run at all. Its code runs, as the
+ * caller, with the caller's network: the receipt is put back if the run
+ * changed it, and the check fails.
+ */
+export declare function checkProject(dir: string, options?: {
+    readonly inPlace?: boolean;
+    /**
+     * For a folder that came back from someone else: a scratch HOME and npm
+     * cache, so the folder's code cannot read the caller's credentials
+     * through them, and no install scripts. Not a sandbox: the folder's
+     * tests still run with the caller's user, filesystem and network.
+     */
+    readonly isolated?: boolean;
+    /** The cut's receipt file; else the one `CARVEOUT_HOME` keeps for its id. */
+    readonly receipt?: string;
+    /** No receipt: the folder's own record and baseline are all there is. */
+    readonly noReceipt?: boolean;
+    /**
+     * The owner's acceptance tests, never sent: each at its repository
+     * path, in the repository's names. Put in the check's copy in the
+     * folder's names and run with the folder's tests; never recorded in a
+     * baseline, and never in the folder itself.
+     */
+    readonly accept?: readonly {
+        readonly path: string;
+        readonly text: string;
+    }[];
+    /**
+     * With `accept`: the slice files patch keeps out, by repository path.
+     * The acceptance run puts back the test side's as the cut wrote them
+     * and takes out the ones the folder added, so it runs on what patch
+     * would carry.
+     */
+    readonly held?: readonly string[];
+    /**
+     * With `held`: when a file patch keeps out would run as the folder
+     * holds it (neither a test-side file put back nor an added file taken
+     * out), run nothing and say which.
+     */
+    readonly refuseHeld?: boolean;
+    /**
+     * Run every step in a container (`sandbox.ts`): only the scratch copy
+     * mounted, the network only for an install with scripts off. For a
+     * folder that came back.
+     */
+    readonly sandbox?: SandboxSpec;
+}): Promise<readonly CheckStep[]>;
+/** The dependencies one package.json text pins that another does not, as the owner reads them. */
+export declare function packagesAdded(folder: string, cut: string): string[];
+export { undoRewrites } from "./imports.js";
+/** An edit the patch cannot carry: the change reaches past the slice. */
+export interface BoundaryEdit {
+    readonly path: string;
+    /**
+     * `stub`: a cut module's declarations or its mock; `dependency`: the
+     * folder's package.json; `config`: its compiler or runtime
+     * configuration; `mock`: the mock runtime or a mock package.
+     */
+    readonly kind: "stub" | "dependency" | "config" | "mock";
+    readonly detail: string;
+    /** For `dependency`: the packages the folder added, at the versions it pins. */
+    readonly added?: readonly {
+        readonly name: string;
+        readonly version: string;
+    }[];
+}
+export interface Patch {
+    /** A unified diff `git apply` takes at the repository's root. */
+    readonly diff: string;
+    readonly changed: readonly string[];
+    readonly added: readonly string[];
+    /** Slice files the folder no longer holds, deleted by the patch. */
+    readonly deleted: readonly string[];
+    /** Generated files that were edited, which the patch leaves out. */
+    readonly generatedEdits: readonly string[];
+    /** Of those, the edits that mean the change needs more than the slice. */
+    readonly boundary: readonly BoundaryEdit[];
+    /**
+     * New or changed files that import the folder's harness (`carveout/`),
+     * which the repository does not have; the patch leaves them out.
+     */
+    readonly sliceOnly: readonly string[];
+    /** New imports restored as relative paths across packages: no importer names the target. */
+    readonly crossPackage: readonly {
+        file: string;
+        specifier: string;
+    }[];
+    /** Whether the repository's copy moved since the cut. */
+    readonly drifted: readonly string[];
+    /**
+     * Changed files whose base is no blob of the cut's commit (the cut read
+     * uncommitted bytes), so `git apply --3way` cannot merge them.
+     */
+    readonly noThreeWay: readonly string[];
+    /**
+     * What the hand-off policy keeps out of the patch: new files outside the
+     * slice's packages, protected paths, deleted tests. `allow` lets them in.
+     */
+    readonly refused: readonly Refusal[];
+    /**
+     * Where the record the patch was judged by came from: the maintainer's
+     * receipt, or the folder's own (no receipt found), checked against the
+     * repository.
+     */
+    readonly recordFrom: "receipt" | "folder";
+    /**
+     * New files the patch leaves out without judging them: under `carveout/`
+     * (the folder's harness, which never goes back) or hidden by the
+     * folder's `.gitignore`. Named, since the folder's own tests run them.
+     */
+    readonly skipped: readonly string[];
+    /**
+     * New test files the folder added at a path the repository already holds
+     * outside the slice (the owner's acceptance test, kept out of the cut),
+     * carried at a free path beside it instead (`contributedPath`), so the
+     * patch applies without a conflict and both tests run.
+     */
+    readonly renamed?: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
+}
+/**
+ * A free path beside `path` for a contributor's new file that would land on
+ * one the repository already holds (the owner's acceptance test, kept out of
+ * the cut): `-contributed` before the test suffix, or before the extension
+ * (`quote.test.ts` becomes `quote-contributed.test.ts`), numbered past any
+ * name `taken` says is in use. Same folder, so its relative imports hold,
+ * and the same suffix, so the test script still runs it.
+ */
+export declare function contributedPath(path: string, taken: (candidate: string) => boolean): string;
+export interface PatchOptions {
+    /** The repository's checkout; else the one the record names. */
+    readonly repo?: string;
+    /** Paths and globs the hand-off policy lets through. */
+    readonly allow?: readonly string[];
+    /** The cut's receipt file; else the one `CARVEOUT_HOME` keeps for its id. */
+    readonly receipt?: string;
+    /**
+     * The cut's receipt as data (`CutResult.receiptData`), in place of a
+     * file: no receipt is looked for under `CARVEOUT_HOME` (`api.ts`).
+     */
+    readonly receiptData?: Receipt;
+    /** No receipt: judge the folder by its own record, checked against the repository. */
+    readonly noReceipt?: boolean;
+    /** Internal: the folder is a copy already put back in the repository's names. */
+    readonly unaliased?: boolean;
+}
+/**
+ * The edits made in the folder as a patch for the repository: each slice
+ * file that changed or is gone, and each new file outside `carveout/`, with
+ * their imports as the repository writes them (`restoreImports`). Built
+ * outputs, the generated files and the lockfile are not part of it; edits
+ * to generated files that the change needed are reported as `boundary`.
+ */
+export declare function patchProject(dir: string, options?: PatchOptions): Promise<Patch>;