carveout 0.1.1 → 0.2.0

package/dist/src/mergeback.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Moving changes between a slice and its repository, both ways.
+ *
+ * `applyPatch` brings a repository patch into a slice: it applies the
+ * patch to a scratch clone at the cut's commit, cuts again in memory with
+ * the recorded request, and writes the slice's files the patch touched as
+ * that cut writes them, imports rewritten. A module the patch adds past
+ * the cut's reach joins the slice as an entry of its own, with its tests.
+ * Paths outside the slice and stubs the change would need are reported;
+ * nothing else in the folder or its record changes, so `patch` still diffs
+ * against the cut's commit.
+ *
+ * `mergeProject` takes a slice's edits the other way: `patch`, then
+ * `git apply --3way` into a checkout the caller names, then a verify
+ * command there. It never picks a checkout on its own.
+ */
+import { type CutResult, type Patch } from "./carve.js";
+import { type SandboxSpec } from "./sandbox.js";
+export interface Applied {
+    /** Slice files the patch changed, now as a cut of the patched repository writes them. */
+    readonly changed: readonly string[];
+    /** Files the patch adds that a cut of the patched repository reaches. */
+    readonly added: readonly string[];
+    readonly deleted: readonly string[];
+    /** Paths the patch touches that the slice does not hold. */
+    readonly outside: readonly string[];
+    /**
+     * Stubs a cut of the patched repository writes differently: what the
+     * change needs from the modules the slice cuts. Written only when asked.
+     */
+    readonly stubs: readonly {
+        path: string;
+        detail: string;
+        written: boolean;
+    }[];
+    /** Slice files the folder had edited, the change merged into them (three-way). */
+    readonly merged: readonly string[];
+    /**
+     * Slice files where the folder's edit and the change overlap: left as the
+     * folder had them, for a person to merge.
+     */
+    readonly conflicts: readonly string[];
+    /**
+     * Names the repository goes by that what the command wrote into a folder
+     * in pseudonyms still holds (a term the cut found nowhere, so has no
+     * placeholder for; a binary file): the folder must not go out as it is.
+     * By term, with the folder paths it is in.
+     */
+    readonly leaks: readonly {
+        readonly term: string;
+        readonly files: readonly string[];
+    }[];
+    /**
+     * Slice files not written: in the folder's names their text would not
+     * map back to the repository's byte for byte (a mixed-case name, a
+     * placeholder word the repository's text holds), so a patch of them
+     * would rewrite the repository's. Left as the folder had them.
+     */
+    readonly unmapped: readonly string[];
+}
+export declare function applyPatch(dir: string, patchText: string, options?: {
+    readonly stubs?: boolean;
+    readonly log?: (line: string) => void;
+    /** The repository's checkout; else the one the record names. */
+    readonly repo?: string;
+    /** The cut's receipt file; else the one `CARVEOUT_HOME` keeps for its id. */
+    readonly receipt?: string;
+    /** No receipt: the folder's own record is all there is. */
+    readonly noReceipt?: boolean;
+    /**
+     * Filled with each slice file the command wrote, by repository path:
+     * the hash of the file as the cut of the patched repository writes it,
+     * in the repository's names and in the folder's, whatever the folder's
+     * own edits merged into it. What `refresh` moves the folder's base to.
+     */
+    readonly written?: Map<string, {
+        readonly folderPath: string;
+        readonly sha256: string;
+        readonly folderSha256: string;
+    }>;
+}): Promise<Applied>;
+export interface MergeStep {
+    readonly step: "patch" | "apply" | "setup" | "verify";
+    readonly ok: boolean;
+    readonly output: string;
+}
+export interface Merge {
+    readonly patch: Patch;
+    readonly steps: readonly MergeStep[];
+    readonly ok: boolean;
+}
+/** The install a lockfile names, lifecycle scripts off; null with no package.json. */
+export declare function installCommand(root: string): string | null;
+/**
+ * The folder's edits merged into `into`, a checkout of the repository the
+ * caller chose: `git apply --3way` there, then `verify` as a shell command
+ * at its root. Stops at the first step that fails.
+ */
+export declare function mergeProject(dir: string, options: {
+    readonly into: string;
+    readonly verify?: string;
+    /** The repository's checkout to diff against; else `into`, else the record's. */
+    readonly repo?: string;
+    /** Paths and globs the hand-off policy lets through. */
+    readonly allow?: readonly string[];
+    /** Environment variables the verify command is given, by name. */
+    readonly verifyEnv?: readonly string[];
+    /** The cut's receipt file; else the one `CARVEOUT_HOME` keeps for its id. */
+    readonly receipt?: string;
+    /** No receipt: judge the folder by its own record. */
+    readonly noReceipt?: boolean;
+    /**
+     * Verify in a container (`sandbox.ts`) on a copy of the checkout as the
+     * patch left it (tracked and unignored files: no `node_modules`, no
+     * ignored `.env`): `verifySetup` (else an install the lockfile names,
+     * scripts off) with a network, then `verify` with none.
+     */
+    readonly sandbox?: SandboxSpec;
+    /** The install before a sandboxed verify, run with a network; else one the lockfile names, scripts off. */
+    readonly verifySetup?: string;
+}): Promise<Merge>;
+export interface Widened {
+    /** The new, wider folder. */
+    readonly out: string;
+    readonly cut: CutResult;
+    /** The contributor's work in the folder widened, as a patch for the repository. */
+    readonly patch: Patch;
+    /** That work, brought into the new folder; null when there was none. */
+    readonly applied: Applied | null;
+}
+/**
+ * A folder cut again, wider, with the contributor's work in it: a change
+ * that turns out to need a module the slice cut. The work so far is taken
+ * as a patch (`patchProject`: none of its code runs, and a file the policy
+ * holds stops the widening), the cut is made again with the entries added
+ * and every other bound as it was, its pseudonyms keep the placeholders the
+ * folder had where they fit, and the work is applied to the new folder in
+ * its names. The old folder is left as it was.
+ */
+export declare function widenProject(dir: string, options: {
+    readonly entries: readonly string[];
+    readonly out?: string;
+    readonly maxDepth?: number;
+    readonly maxFiles?: number;
+    readonly receipt?: string;
+    readonly noReceipt?: boolean;
+    readonly repo?: string;
+    readonly allow?: readonly string[];
+    readonly log?: (line: string) => void;
+}): Promise<Widened>;
+/**
+ * The repository's commits since the cut, brought into the folder: the
+ * change from the cut's commit to the checkout's HEAD in the packages the
+ * slice holds files of and in the modules it stubs, applied as `apply`
+ * applies a patch (the folder's own edits merged, an overlap left for a
+ * person, the stubs the change needs written). For a job long enough that
+ * the repository moves under it. Null when nothing it reads has moved.
+ */
+export declare function refreshProject(dir: string, options?: {
+    readonly repo?: string;
+    readonly receipt?: string;
+    readonly noReceipt?: boolean;
+    readonly log?: (line: string) => void;
+    /**
+     * Slice files the folder's holder merged by hand after an overlap, by
+     * repository path: the folder's text stands as resolved, the change
+     * leaves them alone, and their base moves to the new commit.
+     */
+    readonly resolved?: readonly string[];
+}): Promise<{
+    readonly from: string;
+    readonly to: string;
+    readonly applied: Applied;
+    /** Files taken as resolved whose text leaves out some of the repository's change to them. */
+    readonly droppedUpstream?: readonly string[];
+    /** Files taken as resolved where the repository changed the same lines: no merge can say what the folder's text keeps. */
+    readonly overlapResolved?: readonly string[];
+    /** Copied folders' files the repository changed, left as the folder holds them. */
+    readonly copiedLeft?: readonly string[];
+    /** Copied folders' files the folder had not edited, taken as the repository has them. */
+    readonly copiedTaken?: readonly string[];
+} | null>;