@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/adapters/git/gitFacade.js

@@ -0,0 +1,822 @@
+import { join } from 'node:path';
+import { GitCommandError, GitOutputError } from '../../contracts/errors.js';
+import { hasRejectedRef, parseBatch, parseBatchCheck, parseDivergence, parseLsRemote, parseRawDiff, parseStatus, parseUpstream, } from '../../core/git/porcelain.js';
+/** At most this much blob content is requested from one `git cat-file --batch` call. */
+export const GIT_BATCH_CHUNK_BYTES = 67108864;
+/** A hook's stdout and stderr beyond this are dropped, never a failure (design 12.7, Decision 83). */
+export const HOOK_OUTPUT_CAP_BYTES = 65536;
+/** One-invocation override: no hook runs and no config file is written (D10). */
+const HOOKLESS = ['-c', 'core.hooksPath=/dev/null'];
+const INDEX_LOCKED = "index.lock': File exists";
+const REBASE_IN_PROGRESS = /already a rebase-(?:merge|apply) directory/;
+const BRANCH_PREFIX = 'refs/heads/';
+/** What git writes into head-name for a rebase that started on a detached HEAD. */
+const DETACHED_HEAD_NAME = 'detached HEAD';
+/** What separates the action from the rest of a rebase's start entry in HEAD's reflog. */
+const START_ENTRY = ' (start): ';
+/**
+ * How many of HEAD's newest reflog entries headMovedSince reads. The commands
+ * that land while enmetu's rebase is stopped add a handful; the bound keeps a
+ * long reflog from being walked for nothing.
+ */
+const HEAD_MOVE_SCAN = 64;
+const REGULAR_FILE_MODES = ['100644', '100755'];
+const OBJECT_ID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+const STATUS_ARGS = [
+    '--literal-pathspecs',
+    'status',
+    '--porcelain=v1',
+    '-z',
+    '--untracked-files=all',
+    '--no-renames',
+    '--ignore-submodules=dirty',
+];
+const STAGED_DIFF_ARGS = [
+    'diff',
+    '--cached',
+    '--raw',
+    '-z',
+    '--no-renames',
+    '--no-abbrev',
+    '--diff-filter=ACMT',
+];
+/** Files under gitDir whose presence means a person's git operation is in progress, checked in this order. */
+const OPERATION_MARKERS = [
+    { file: 'rebase-merge', operation: 'rebase' },
+    { file: 'rebase-apply', operation: 'rebase' },
+    { file: 'MERGE_HEAD', operation: 'merge' },
+    { file: 'CHERRY_PICK_HEAD', operation: 'cherry-pick' },
+    { file: 'REVERT_HEAD', operation: 'revert' },
+    { file: 'BISECT_LOG', operation: 'bisect' },
+];
+/**
+ * Facade: typed questions and commands over the git CLI, with exactly the
+ * argv and interpretations of design section 1.3. gitDir locates the state
+ * files repositoryState and the rebase readers check.
+ */
+export class GitFacade {
+    runner;
+    fs;
+    gitDir;
+    hookTimeoutMs;
+    hookAbort;
+    constructor(runner, fs, gitDir, 
+    /** A repository hook's own budget (hookTimeoutMs); only runHook uses it (design 12.7, Decision 83). */
+    hookTimeoutMs, 
+    /** Aborted by a stop request: a running hook is ended, which is a rejection (Decision 92); only runHook uses it. */
+    hookAbort) {
+        this.runner = runner;
+        this.fs = fs;
+        this.gitDir = gitDir;
+        this.hookTimeoutMs = hookTimeoutMs;
+        this.hookAbort = hookAbort;
+    }
+    async repositoryState() {
+        const args = ['symbolic-ref', '-q', 'HEAD'];
+        const head = await this.git(args);
+        let branchRef;
+        if (head.exitCode === 0) {
+            branchRef = parseRefName(head.stdout);
+        }
+        else if (head.exitCode === 1) {
+            branchRef = null;
+        }
+        else {
+            throw gitFailed(args, head);
+        }
+        const [indexLock, ...markers] = await Promise.all([
+            this.exists('index.lock'),
+            ...OPERATION_MARKERS.map((marker) => this.exists(marker.file)),
+        ]);
+        const found = OPERATION_MARKERS.find((_, index) => markers[index] === true);
+        return {
+            indexLocked: indexLock === true,
+            operation: found === undefined ? null : found.operation,
+            branchRef,
+        };
+    }
+    async headCommit() {
+        return this.verifyCommit('HEAD');
+    }
+    async hasCommitterIdentity() {
+        const result = await this.git(['var', 'GIT_COMMITTER_IDENT']);
+        return result.exitCode === 0;
+    }
+    async upstream(branchRef) {
+        const result = await this.gitOk([
+            'for-each-ref',
+            '--format=%(upstream:remotename)%00%(upstream:remoteref)%00%(upstream)',
+            branchRef,
+        ]);
+        return parseUpstream(result.stdout.toString('utf8'), branchRef);
+    }
+    async status(paths) {
+        if (paths === undefined) {
+            return parseStatus((await this.gitOk(STATUS_ARGS)).stdout);
+        }
+        // Without paths after `--`, git would report the whole tree.
+        if (paths.length === 0) {
+            return [];
+        }
+        const result = await this.gitOk([...STATUS_ARGS, '--', ...paths]);
+        return parseStatus(result.stdout);
+    }
+    async *stagedFiles(maxBytes) {
+        const blobs = await this.stagedBlobs(maxBytes);
+        let chunk = new Map();
+        for (const [index, blob] of blobs.entries()) {
+            if (blob.size === null) {
+                yield { path: blob.path, content: null };
+                continue;
+            }
+            let content = chunk.get(index);
+            if (content === undefined) {
+                // The previous chunk is released here, before the next one is read.
+                chunk = new Map();
+                chunk = await this.readChunk(blobs, index);
+                content = chunk.get(index);
+            }
+            if (content === undefined) {
+                throw new GitOutputError(`git cat-file --batch did not return blob ${blob.blobId}`);
+            }
+            yield { path: blob.path, content };
+        }
+    }
+    async hasStagedChanges() {
+        const args = ['diff', '--cached', '--quiet', '--ignore-submodules=dirty'];
+        const result = await this.git(args);
+        if (result.exitCode === 0 || result.exitCode === 1) {
+            return result.exitCode === 1;
+        }
+        throw gitFailed(args, result);
+    }
+    /** git diff --cached --name-only -z --no-renames --ignore-submodules=dirty (Decision 98). */
+    async stagedPaths() {
+        const args = [
+            'diff',
+            '--cached',
+            '--name-only',
+            '-z',
+            '--no-renames',
+            '--ignore-submodules=dirty',
+        ];
+        return parseNulPaths((await this.gitOk(args)).stdout, 'git diff --cached --name-only');
+    }
+    async remoteHead(remote, remoteRef) {
+        const run = await this.remoteGit(['ls-remote', remote, remoteRef]);
+        if (run.kind === 'timed-out') {
+            return { kind: 'unreachable', detail: run.detail };
+        }
+        const { result } = run;
+        if (result.exitCode !== 0) {
+            return { kind: 'unreachable', detail: result.stderr };
+        }
+        const sha = parseLsRemote(result.stdout.toString('utf8'), remoteRef);
+        return sha === null ? { kind: 'absent' } : { kind: 'found', sha };
+    }
+    async resolveCommit(ref) {
+        return this.verifyCommit(ref);
+    }
+    async isAncestor(ancestor, descendant) {
+        const args = ['merge-base', '--is-ancestor', ancestor, descendant];
+        const result = await this.git(args);
+        if (result.exitCode === 0 || result.exitCode === 1) {
+            return result.exitCode === 0;
+        }
+        throw gitFailed(args, result);
+    }
+    async divergence(upstreamSha) {
+        const result = await this.gitOk([
+            'rev-list',
+            '--left-right',
+            '--count',
+            `HEAD...${upstreamSha}`,
+        ]);
+        return parseDivergence(result.stdout.toString('utf8'));
+    }
+    async hasUnmergedPaths() {
+        const result = await this.gitOk(['ls-files', '--unmerged', '-z']);
+        return result.stdout.length > 0;
+    }
+    async rebaseOrigHead() {
+        return this.rebaseStateFile('orig-head');
+    }
+    async rebaseOnto() {
+        return this.rebaseStateFile('onto');
+    }
+    /**
+     * The branch a rebase in progress returns to: rebase-merge/head-name, else
+     * rebase-apply/head-name (design 14.4). git writes `detached HEAD` there for
+     * a rebase that started without a branch.
+     */
+    async rebaseHeadName() {
+        const text = (await this.fs.readText(join(this.gitDir, 'rebase-merge', 'head-name'))) ??
+            (await this.fs.readText(join(this.gitDir, 'rebase-apply', 'head-name')));
+        if (text === null) {
+            return null;
+        }
+        return parseHeadName(text);
+    }
+    /**
+     * git reflog exists HEAD, then git log -g -1 --format=%gs
+     * --grep-reflog=" (start): " HEAD (design 13.2, Decision 104). Without a
+     * reflog `git log -g` prints nothing with exit 0, exactly like a reflog
+     * without a start entry, so the first call keeps the two apart.
+     */
+    async rebaseStart() {
+        const existsArgs = ['reflog', 'exists', 'HEAD'];
+        const exists = await this.git(existsArgs);
+        if (exists.exitCode === 1) {
+            return { kind: 'unlogged' };
+        }
+        if (exists.exitCode !== 0) {
+            throw gitFailed(existsArgs, exists);
+        }
+        const entry = await this.gitOk([
+            'log',
+            '-g',
+            '-1',
+            '--format=%gs',
+            `--grep-reflog=${START_ENTRY}`,
+            'HEAD',
+        ]);
+        return parseRebaseStart(entry.stdout.toString('utf8'));
+    }
+    /**
+     * git log -g -n HEAD_MOVE_SCAN --format="%H %gs" HEAD, newest first (design
+     * 14.14). Without a reflog git prints nothing with exit 0, which is also
+     * what a reflog holding no entry of the rebase's yields: null either way.
+     */
+    async headMovedSince(reflogAction) {
+        const entries = parseReflogEntries((await this.gitOk([
+            'log',
+            '-g',
+            '-n',
+            String(HEAD_MOVE_SCAN),
+            '--format=%H %gs',
+            'HEAD',
+        ])).stdout.toString('utf8'));
+        const own = `${reflogAction} (`;
+        const newest = entries[0];
+        if (newest === undefined || newest.subject.startsWith(own)) {
+            return null;
+        }
+        const last = entries.find((entry) => entry.subject.startsWith(own));
+        return last === undefined ? null : { from: last.commit, to: newest.commit };
+    }
+    async commitSubject(commit) {
+        const args = ['log', '-1', '--no-walk', '--format=%s', commit];
+        return (await this.gitOk(args)).stdout.toString('utf8').replace(/\n$/, '');
+    }
+    /**
+     * Two reads, the cheap one first (design 14.15). --since bounds the log's
+     * walk to commits made after enmetu named the orphan (in whole seconds, a
+     * second early, since git's committer dates have no fraction); a time that
+     * does not parse walks every branch.
+     */
+    async onLocalBranch(commit, since) {
+        const containing = await this.gitOk([
+            'for-each-ref',
+            '--count=1',
+            '--contains',
+            commit,
+            '--format=%(refname)',
+            'refs/heads/',
+        ]);
+        if (containing.stdout.length > 0) {
+            return true;
+        }
+        const sinceMs = Date.parse(since);
+        const picked = await this.gitOk([
+            'log',
+            '--branches',
+            '-F',
+            `--grep=(cherry picked from commit ${commit})`,
+            ...(Number.isNaN(sinceMs)
+                ? []
+                : [`--since=${Math.floor(sinceMs / 1000) - 1}`]),
+            '-n',
+            '1',
+            '--format=%H',
+        ]);
+        return picked.stdout.length > 0;
+    }
+    async readBlob(blobId) {
+        return (await this.gitOk(['cat-file', 'blob', blobId])).stdout;
+    }
+    async hashFile(path) {
+        const args = ['hash-object', '--no-filters', '--', path];
+        return parseObjectId((await this.gitOk(args)).stdout, 'git hash-object');
+    }
+    async worktreeBlobId(path) {
+        const args = ['hash-object', '--', path];
+        return parseObjectId((await this.gitOk(args)).stdout, 'git hash-object');
+    }
+    async entryBlobId(path, commit) {
+        // The explicit stage 0 keeps a path like "1:x" from being read for a stage number.
+        const spec = commit === null ? `:0:${path}` : `${commit}:${path}`;
+        const args = ['rev-parse', '-q', '--verify', spec];
+        const result = await this.git(args);
+        if (result.exitCode === 1) {
+            return null;
+        }
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return parseObjectId(result.stdout, 'git rev-parse');
+    }
+    /** git merge-file -p: exit 0 is clean; a conflict count or an error (binary input) is null. */
+    async mergeFile(current, base, other) {
+        const result = await this.git(['merge-file', '-p', current, base, other]);
+        return result.exitCode === 0 ? result.stdout : null;
+    }
+    /** git merge-base <left> <right>: exit 1 is null (design 12.3). */
+    async mergeBase(left, right) {
+        const args = ['merge-base', left, right];
+        const result = await this.git(args);
+        if (result.exitCode === 1) {
+            return null;
+        }
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return parseObjectId(result.stdout, 'git merge-base');
+    }
+    /** git diff --name-only -z --no-renames <from> <to> (design 12.3). */
+    async changedPaths(from, to) {
+        const args = ['diff', '--name-only', '-z', '--no-renames', from, to];
+        return parseNulPaths((await this.gitOk(args)).stdout, 'git diff --name-only');
+    }
+    /**
+     * git -c core.hooksPath=/dev/null read-tree --reset <commit> (design 12.7):
+     * -m's one-tree merge, which keeps the stat data of matching entries, except
+     * that unmerged entries a copied index carries (a conflicted stash pop, a
+     * person's merge) are discarded instead of refused (measured with git 2.52:
+     * -m exits 128 with "You need to resolve your current index first").
+     */
+    async seedFrom(commit) {
+        await this.gitOk([...HOOKLESS, 'read-tree', '--reset', commit]);
+    }
+    /** git -c core.hooksPath=/dev/null write-tree (design 12.7). */
+    async writeTree() {
+        const result = await this.gitOk([...HOOKLESS, 'write-tree']);
+        return parseObjectId(result.stdout, 'git write-tree');
+    }
+    /** git commit-tree <tree> -p <parent> -S|--no-gpg-sign -F - (design 12.7). */
+    async commitTree(input) {
+        const result = await this.gitOk([
+            'commit-tree',
+            input.tree,
+            '-p',
+            input.parent,
+            input.sign ? '-S' : '--no-gpg-sign',
+            '-F',
+            '-',
+        ], input.message);
+        return parseObjectId(result.stdout, 'git commit-tree');
+    }
+    async hookExists(name) {
+        const result = await this.gitOk([
+            'rev-parse',
+            '--path-format=absolute',
+            '--git-path',
+            `hooks/${name}`,
+        ]);
+        const path = result.stdout.toString('utf8').replace(/\n$/, '');
+        const facts = await this.fs.facts(path);
+        return (facts !== null &&
+            (facts.kind === 'symlink' || (facts.kind === 'file' && facts.executable)));
+    }
+    /**
+     * git hook run --ignore-missing <name> [-- <args>] with the runner options
+     * { timeoutMs: hookTimeoutMs, outputCapBytes: HOOK_OUTPUT_CAP_BYTES }
+     * (design 12.7, Decision 83): exit 0 passed; any other exit rejected with
+     * stderr; GIT_TIMEOUT rejected with 'timed out after <n> ms'; GIT_FAILED
+     * without an exit code (ended by a signal) rejected with the error's
+     * message. Throws only GIT_NOT_FOUND.
+     */
+    async runHook(name, args) {
+        const argv = ['hook', 'run', '--ignore-missing', name];
+        if (args.length > 0) {
+            argv.push('--', ...args);
+        }
+        let result;
+        try {
+            // The runner directly, not this.git: a hook's stderr that mentions
+            // index.lock is the hook's verdict, not enmetu's collision.
+            result = await this.runner.run(argv, {
+                timeoutMs: this.hookTimeoutMs,
+                outputCapBytes: HOOK_OUTPUT_CAP_BYTES,
+                abort: this.hookAbort,
+            });
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.code === 'GIT_ABORTED') {
+                return { kind: 'rejected', detail: 'ended because enmetu is stopping' };
+            }
+            if (error instanceof GitCommandError && error.code === 'GIT_TIMEOUT') {
+                return {
+                    kind: 'rejected',
+                    detail: this.hookTimeoutMs === undefined
+                        ? error.message
+                        : `timed out after ${this.hookTimeoutMs} ms`,
+                };
+            }
+            if (error instanceof GitCommandError &&
+                error.code === 'GIT_FAILED' &&
+                error.exitCode === null) {
+                return { kind: 'rejected', detail: error.message };
+            }
+            throw error;
+        }
+        if (result.exitCode === 0) {
+            return { kind: 'passed' };
+        }
+        return {
+            kind: 'rejected',
+            detail: result.stderr === '' ? `exited ${result.exitCode}` : result.stderr,
+        };
+    }
+    async configValue(key) {
+        const args = ['config', '--get', key];
+        const result = await this.git(args);
+        if (result.exitCode === 1) {
+            return null;
+        }
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return stripOneTrailingNewline(result.stdout.toString('utf8'));
+    }
+    async stageAll() {
+        const args = [...HOOKLESS, 'add', '-A', '--ignore-errors'];
+        const result = await this.git(args);
+        if (result.exitCode === 0) {
+            return { partial: false, detail: '' };
+        }
+        if (result.exitCode === 1) {
+            return { partial: true, detail: result.stderr };
+        }
+        throw gitFailed(args, result);
+    }
+    async unstage(paths) {
+        // An empty pathspec file would reset the whole index.
+        if (paths.length === 0) {
+            return;
+        }
+        // Hookless like stageAll: git runs post-index-change on every index
+        // write, and enmetu resets only its own commit index (design 12.7).
+        await this.gitOk([
+            ...HOOKLESS,
+            '--literal-pathspecs',
+            'reset',
+            '-q',
+            '--pathspec-from-file=-',
+            '--pathspec-file-nul',
+        ], paths.join('\0'));
+    }
+    async fetch(remote, remoteRef, intoRef) {
+        const run = await this.remoteGit([
+            'fetch',
+            '--quiet',
+            '--no-tags',
+            '--no-recurse-submodules',
+            '--no-write-fetch-head',
+            // An empty refmap stops git's opportunistic update of the tracking ref
+            // that remote.<name>.fetch maps remoteRef to; only intoRef moves.
+            '--refmap=',
+            remote,
+            `+${remoteRef}:${intoRef}`,
+        ]);
+        if (run.kind === 'timed-out') {
+            return { kind: 'failed', detail: run.detail };
+        }
+        return run.result.exitCode === 0
+            ? { kind: 'fetched' }
+            : { kind: 'failed', detail: run.result.stderr };
+    }
+    async updateRef(ref, newSha, oldSha) {
+        await this.gitOk([
+            ...HOOKLESS,
+            'update-ref',
+            '-m',
+            'enmetu',
+            ref,
+            newSha,
+            oldSha ?? '',
+        ]);
+    }
+    /**
+     * reflogAction is the attempt's token: git writes it into HEAD's reflog
+     * with the rebase's checkout, which rebaseStart reads back (Decision 104).
+     */
+    async rebase(ontoSha, reflogAction) {
+        const result = await this.git([
+            ...HOOKLESS,
+            'rebase',
+            // A person's rebase.backend=apply or rebase.rebaseMerges=true would
+            // otherwise change what enmetu replays and pushes (Decision 120).
+            '--merge',
+            '--no-rebase-merges',
+            '--no-autostash',
+            '--no-autosquash',
+            '--no-update-refs',
+            '--no-fork-point',
+            '--quiet',
+            ontoSha,
+        ], { reflogAction });
+        if (result.exitCode === 0) {
+            return { kind: 'rebased' };
+        }
+        if (REBASE_IN_PROGRESS.test(result.stderr)) {
+            return { kind: 'refused', detail: result.stderr };
+        }
+        // The rebase directories, not git's message, tell a rebase that stopped
+        // from one git refused to start, across versions and locales (Decision 78).
+        const [merge, apply] = await Promise.all([
+            this.exists('rebase-merge'),
+            this.exists('rebase-apply'),
+        ]);
+        if (merge || apply) {
+            return { kind: 'stopped', detail: result.stderr };
+        }
+        return { kind: 'not-started', detail: result.stderr };
+    }
+    async abortRebase() {
+        // The caller verifies the outcome from the repository state, so neither
+        // the exit code nor an index.lock message is interpreted here.
+        await this.runner.run([...HOOKLESS, 'rebase', '--abort']);
+    }
+    /**
+     * git rebase --quit, then git switch -q --discard-changes <name>, both
+     * hookless (design 14.4, Decision 122). Neither exit code nor an index.lock
+     * message is interpreted: the caller verifies HEAD, the branch and the tip.
+     */
+    async endRebaseAtBranch(branchRef) {
+        if (!branchRef.startsWith(BRANCH_PREFIX)) {
+            throw new GitOutputError(`endRebaseAtBranch needs a branch under ${BRANCH_PREFIX}, got ${JSON.stringify(branchRef.slice(0, 120))}`);
+        }
+        const name = branchRef.slice(BRANCH_PREFIX.length);
+        await this.runner.run([...HOOKLESS, 'rebase', '--quit']);
+        await this.runner.run([
+            ...HOOKLESS,
+            'switch',
+            '-q',
+            '--discard-changes',
+            name,
+        ]);
+    }
+    async push(remote, sha, remoteRef) {
+        const run = await this.remoteGit([
+            'push',
+            '--porcelain',
+            '--no-recurse-submodules',
+            '--no-follow-tags',
+            remote,
+            `${sha}:${remoteRef}`,
+        ]);
+        if (run.kind === 'timed-out') {
+            // The push may still have landed; the next cycle's ls-remote tells.
+            return { kind: 'failed', detail: run.detail };
+        }
+        const { result } = run;
+        if (result.exitCode === 0) {
+            return { kind: 'pushed' };
+        }
+        if (result.exitCode === 1 &&
+            hasRejectedRef(result.stdout.toString('utf8'))) {
+            return { kind: 'rejected', detail: result.stderr };
+        }
+        return { kind: 'failed', detail: result.stderr };
+    }
+    async storeBlob(path) {
+        const args = ['hash-object', '-w', '--no-filters', '--', path];
+        return parseObjectId((await this.gitOk(args)).stdout, 'git hash-object');
+    }
+    async restoreFromIndex(paths) {
+        if (paths.length === 0) {
+            return;
+        }
+        await this.gitOk([
+            ...HOOKLESS,
+            '--literal-pathspecs',
+            'checkout',
+            '--quiet',
+            '--pathspec-from-file=-',
+            '--pathspec-file-nul',
+        ], paths.join('\0'));
+    }
+    /** Runs git and turns an index.lock collision into GIT_INDEX_LOCKED; every other exit code is the caller's to read. */
+    async git(args, options) {
+        const result = options === undefined
+            ? await this.runner.run(args)
+            : await this.runner.run(args, options);
+        if (result.exitCode !== 0 && result.stderr.includes(INDEX_LOCKED)) {
+            throw new GitCommandError(`git ${args.join(' ')}: another git process holds index.lock`, 'GIT_INDEX_LOCKED', args, result.exitCode, result.stderr);
+        }
+        return result;
+    }
+    /**
+     * Runs a command that talks to the remote. A timeout there is the network or
+     * a credential prompt (ssh connect, passphrase, pinentry), so it comes back as
+     * a value the cycle reports (OFFLINE, or PUSH_FAILED with UNPUSHED, D2),
+     * never an error that ends the cycle in CYCLE_FAILED.
+     */
+    async remoteGit(args) {
+        try {
+            return { kind: 'ran', result: await this.git(args) };
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.code === 'GIT_TIMEOUT') {
+                return { kind: 'timed-out', detail: error.message };
+            }
+            throw error;
+        }
+    }
+    /** Runs git and expects exit code 0. */
+    async gitOk(args, stdin) {
+        const result = await this.git(args, stdin === undefined ? undefined : { stdin });
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return result;
+    }
+    async verifyCommit(ref) {
+        const args = ['rev-parse', '-q', '--verify', `${ref}^{commit}`];
+        const result = await this.git(args);
+        if (result.exitCode === 1) {
+            return null;
+        }
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return parseObjectId(result.stdout, 'git rev-parse');
+    }
+    async exists(file) {
+        return (await this.fs.facts(join(this.gitDir, file))) !== null;
+    }
+    async rebaseStateFile(name) {
+        const text = (await this.fs.readText(join(this.gitDir, 'rebase-merge', name))) ??
+            (await this.fs.readText(join(this.gitDir, 'rebase-apply', name)));
+        if (text === null) {
+            return null;
+        }
+        return parseObjectId(Buffer.from(text), `rebase ${name}`);
+    }
+    /** The staged files in diff order, with the size of each blob whose content will be read. */
+    async stagedBlobs(maxBytes) {
+        const entries = parseRawDiff((await this.gitOk(STAGED_DIFF_ARGS)).stdout);
+        const regular = entries.filter((entry) => REGULAR_FILE_MODES.includes(entry.mode));
+        const sizes = await this.blobSizes(regular.map((entry) => entry.blobId));
+        let next = 0;
+        return entries.map((entry) => {
+            if (!REGULAR_FILE_MODES.includes(entry.mode)) {
+                return { path: entry.path, blobId: entry.blobId, size: null };
+            }
+            const size = sizes[next];
+            next += 1;
+            if (size === undefined) {
+                throw new GitOutputError(`git cat-file --batch-check gave no size for blob ${entry.blobId}`);
+            }
+            return {
+                path: entry.path,
+                blobId: entry.blobId,
+                size: size <= maxBytes ? size : null,
+            };
+        });
+    }
+    /** Sizes in request order; the blob ids of a staged diff must all exist. */
+    async blobSizes(blobIds) {
+        if (blobIds.length === 0) {
+            return [];
+        }
+        const result = await this.gitOk(['cat-file', '--batch-check'], idLines(blobIds));
+        const checked = parseBatchCheck(result.stdout.toString('utf8'));
+        if (checked.length !== blobIds.length) {
+            throw new GitOutputError(`git cat-file --batch-check answered ${checked.length} of ${blobIds.length} blobs`);
+        }
+        return checked.map((entry, index) => {
+            if (entry.kind === 'missing' || entry.id !== blobIds[index]) {
+                throw new GitOutputError(`git cat-file --batch-check has no blob ${blobIds[index] ?? entry.id}`);
+            }
+            return entry.size;
+        });
+    }
+    /**
+     * Reads the readable blobs from `start` on, in diff order, until the next
+     * one would push the chunk past GIT_BATCH_CHUNK_BYTES; the first blob is
+     * always taken, so a blob larger than a chunk is read alone.
+     */
+    async readChunk(blobs, start) {
+        const indexes = [];
+        const ids = [];
+        let total = 0;
+        for (let index = start; index < blobs.length; index += 1) {
+            const blob = blobs[index];
+            if (blob === undefined || blob.size === null) {
+                continue;
+            }
+            if (indexes.length > 0 && total + blob.size > GIT_BATCH_CHUNK_BYTES) {
+                break;
+            }
+            indexes.push(index);
+            ids.push(blob.blobId);
+            total += blob.size;
+        }
+        const result = await this.gitOk(['cat-file', '--batch'], idLines(ids));
+        const read = parseBatch(result.stdout);
+        if (read.length !== ids.length) {
+            throw new GitOutputError(`git cat-file --batch returned ${read.length} of ${ids.length} blobs`);
+        }
+        const chunk = new Map();
+        read.forEach((blob, position) => {
+            const index = indexes[position];
+            if (index === undefined || blob.id !== ids[position]) {
+                throw new GitOutputError(`git cat-file --batch returned blob ${blob.id} out of order`);
+            }
+            chunk.set(index, blob.content);
+        });
+        return chunk;
+    }
+}
+function gitFailed(args, result) {
+    const firstLine = result.stderr.split('\n')[0] ?? '';
+    return new GitCommandError(`git ${args.join(' ')} exited ${result.exitCode}: ${firstLine}`, 'GIT_FAILED', args, result.exitCode, result.stderr);
+}
+function idLines(ids) {
+    return ids.map((id) => `${id}\n`).join('');
+}
+function stripOneTrailingNewline(text) {
+    return text.endsWith('\n') ? text.slice(0, -1) : text;
+}
+function parseObjectId(stdout, source) {
+    const id = stdout.toString('utf8').trim();
+    if (!OBJECT_ID.test(id)) {
+        throw new GitOutputError(`unexpected ${source} output: ${JSON.stringify(id.slice(0, 120))}`);
+    }
+    return id;
+}
+/**
+ * `-z` path output: every path is NUL-terminated, so output that does not end
+ * in NUL was cut off. Paths are text from outside and are never interpreted.
+ */
+function parseNulPaths(stdout, source) {
+    const text = stdout.toString('utf8');
+    if (text === '') {
+        return [];
+    }
+    if (!text.endsWith('\0')) {
+        throw new GitOutputError(`unexpected ${source} output: ${JSON.stringify(text.slice(0, 120))}`);
+    }
+    return text.slice(0, -1).split('\0');
+}
+/**
+ * The newest start entry's subject, `<action> (start): <rest>`; empty output
+ * is a reflog without one. The action is text from outside, compared, never
+ * interpreted.
+ */
+function parseRebaseStart(text) {
+    const subject = stripOneTrailingNewline(text);
+    if (subject === '') {
+        return { kind: 'none' };
+    }
+    const end = subject.indexOf(START_ENTRY);
+    if (end === -1 || subject.includes('\n')) {
+        throw new GitOutputError(`unexpected git log -g output: ${JSON.stringify(subject.slice(0, 120))}`);
+    }
+    return { kind: 'entry', action: subject.slice(0, end) };
+}
+/** `%H %gs` lines of git log -g: an object id, one space, the entry's message. */
+function parseReflogEntries(text) {
+    return stripOneTrailingNewline(text)
+        .split('\n')
+        .filter((line) => line !== '')
+        .map((line) => {
+        const space = line.indexOf(' ');
+        const commit = space === -1 ? line : line.slice(0, space);
+        if (!OBJECT_ID.test(commit)) {
+            throw new GitOutputError(`unexpected git log -g output: ${JSON.stringify(line.slice(0, 120))}`);
+        }
+        return { commit, subject: line.slice(space + 1) };
+    });
+}
+/** head-name's one line: a branch ref, or `detached HEAD` (null). */
+function parseHeadName(text) {
+    const name = stripOneTrailingNewline(text);
+    if (name === DETACHED_HEAD_NAME) {
+        return null;
+    }
+    if (!name.startsWith(BRANCH_PREFIX) ||
+        name.length === BRANCH_PREFIX.length ||
+        name.includes('\n')) {
+        throw new GitOutputError(`unexpected rebase head-name: ${JSON.stringify(name.slice(0, 120))}`);
+    }
+    return name;
+}
+function parseRefName(stdout) {
+    const ref = stripOneTrailingNewline(stdout.toString('utf8'));
+    if (!ref.startsWith('refs/') || ref.includes('\n')) {
+        throw new GitOutputError(`unexpected git symbolic-ref output: ${JSON.stringify(ref.slice(0, 120))}`);
+    }
+    return ref;
+}