@nestledjs/upgrades 0.3.0 → 0.3.2

package/src/lib/changes.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Every path with uncommitted changes at this moment — staged, unstaged, or untracked (each file of an
+ * untracked directory individually) — excluding our own `.nestled/` bookkeeping, the same exclusion
+ * `hasUncommittedChanges` makes. Both sides of a staged rename are included.
+ */
+export declare function dirtyPaths(cwd: string): Set<string>;
+/**
+ * Ignored paths that exist right now, as `git status --ignored` reports them, as a test of whether a
+ * path existed (as an ignored file) at this moment. Git collapses an ignored directory to one entry,
+ * so its files are listed here directly, up to a limit; inside a directory too large to list (a
+ * `node_modules`), every path counts as pre-existing, which can only ever leave a file behind.
+ */
+export declare function ignoredPaths(cwd: string): (path: string) => boolean;
+/**
+ * Every path a unified diff would create, modify, delete or rename (both sides), relative to the
+ * directory `git apply` runs in, minus paths matching `excludes` (the `--exclude` globs passed to
+ * `git apply`). Hunk bodies are skipped by their line counts, so a removed line that happens to read
+ * `-- a/x` is never mistaken for a header.
+ */
+export declare function patchPaths(diffText: string, excludes?: string[]): string[];
+/** What is at a path on disk, captured so it can be put back exactly. */
+type FileState = {
+    kind: 'absent';
+} | {
+    kind: 'file';
+    contents: Buffer;
+    mode: number;
+} | {
+    kind: 'link';
+    target: string;
+}
+/** A directory or special file: never captured, never overwritten. A directory above a path keeps its mode. */
+ | {
+    kind: 'other';
+    mode?: number;
+};
+/** A path's state together with the state of each directory above it (a real directory, or a link). */
+interface Captured {
+    state: FileState;
+    ancestors: {
+        absolute: string;
+        state: FileState;
+    }[];
+}
+/**
+ * The paths one apply run changes, each with how it looked before the run first touched it, so a
+ * rollback can put back exactly those paths and leave every other file alone.
+ *
+ * Call `willTouch` before writing a path. Its state at that moment is the pre-run state, because
+ * the run never writes a path it has not declared, and a path the user had uncommitted is refused
+ * before it gets here.
+ */
+export declare class RunChanges {
+    private readonly root;
+    private readonly startCommit;
+    private readonly prior;
+    /** Pre-existing ignored files a step surfaced: restored on rollback, never committed as the run's. */
+    private readonly preserved;
+    /** A pre-existing ignored file a step surfaced: the user's, so no later note may write it. */
+    isPreserved(path: string): boolean;
+    /** `root` is the repository root; `startCommit` is HEAD before the run ('' on an unborn branch). */
+    constructor(root: string, startCommit: string);
+    get paths(): string[];
+    has(path: string): boolean;
+    willTouch(paths: Iterable<string>): void;
+    /**
+     * Record paths something the run did has already changed (an install's or a hook's side effects).
+     * Only paths that were clean before that step may be passed. Each was tracked at the start commit,
+     * did not exist, or existed but was ignored (`existedIgnored`): a step that changes an ignore rule,
+     * or force-adds and commits, can surface a file it never wrote. That last kind is the user's: it is
+     * kept as it is now and, after a rollback, put back the same way, unstaged. Returns the paths among
+     * `paths` that the run now owns, which never include the user's.
+     */
+    didChange(paths: Iterable<string>, existedIgnored?: (path: string) => boolean): string[];
+    /**
+     * Put `paths` (default: every path this run touched) back to their pre-run state, in both the
+     * index and the working tree. Nothing outside them is read or written.
+     */
+    restore(paths?: Iterable<string>): void;
+    /** Paths of `paths` present in the start commit's tree. */
+    private trackedAtStart;
+    /** Remove directories a created file left empty, up to (never including) the repository root. */
+    private pruneEmptyParents;
+}
+/**
+ * Every file and link under `dir` (repository-root-relative, ending in `/`), as root-relative paths,
+ * without following directory links. With `limit`, null once more than that many are found.
+ */
+export declare function listFiles(root: string, dir: string, limit?: number): string[] | null;
+/** The user's uncommitted work at a set of paths: what is on disk, and what is staged. */
+export interface UserState {
+    files: Map<string, Captured>;
+    index: Map<string, string[]>;
+}
+/** Capture `paths` as they are now, on disk and in the index. */
+export declare function snapshotFiles(root: string, paths: Iterable<string>): UserState;
+/**
+ * Put back every snapshotted path whose file (contents, mode, symlink target, or presence) or index
+ * entry no longer matches, and return those paths. Used around steps that run third-party code (a
+ * package install, verification commands) on a dirty tree, so a script that rewrites, replaces or
+ * re-stages a file the user has uncommitted work in cannot cost them that work.
+ */
+export interface RestoreResult {
+    /** Paths found changed and put back (or attempted): the caller blocks on any. */
+    restored: string[];
+    /** Paths that could not be put back, with where their saved state was written instead. */
+    unrecovered: {
+        path: string;
+        savedTo: string;
+    }[];
+}
+export declare function restoreChangedFiles(root: string, snapshot: UserState): RestoreResult;
+/**
+ * Commit only `paths`, leaving anything else the user has staged or modified out of the commit and
+ * exactly as it was. Returns the new HEAD (short), the unchanged HEAD when none of `paths` changed,
+ * or '' when staging or committing failed (a commit hook rejecting it, say), like `commitAll`.
+ */
+export declare function commitPaths(root: string, message: string, paths: string[]): string;
+export {};