@shipwithai/loopnote 0.0.0-stage → 2.0.0-bootstrap.0

package/dist/git/candidates.js

@@ -0,0 +1,413 @@
+import { isUtf8 } from 'node:buffer';
+import { isAbsolute } from 'node:path';
+import { GitObjectIdSchema } from '../contracts/comparison.js';
+import { UNAVAILABLE_WORKTREE_REASON, } from '../domain/source.js';
+import { orderByteSequences } from '../domain/path-bytes.js';
+import { discoverGitRepository } from './repository.js';
+import { createGitRunner, GitRunnerError, } from './runner.js';
+const BRANCH_FORMAT = [
+    '%(refname)',
+    '%(refname:short)',
+    '%(objectname)',
+    '',
+].join('%00');
+function stripGitLineTerminator(buffer) {
+    if (buffer.at(-1) !== 0x0a) {
+        throw new Error('Git line output ended without a line terminator');
+    }
+    return buffer.subarray(0, -1);
+}
+function splitNul(buffer) {
+    if (buffer.length !== 0 && buffer.at(-1) !== 0) {
+        throw new Error('Git NUL output ended without a record terminator');
+    }
+    const fields = [];
+    let start = 0;
+    for (let index = 0; index < buffer.length; index += 1) {
+        if (buffer[index] === 0) {
+            fields.push(buffer.subarray(start, index));
+            start = index + 1;
+        }
+    }
+    return fields;
+}
+function splitNulLineTerminated(buffer) {
+    if (buffer.length === 0) {
+        return [];
+    }
+    const payload = stripGitLineTerminator(buffer);
+    if (payload.length === 0) {
+        throw new Error('Git NUL output contained no record content');
+    }
+    return splitNul(payload);
+}
+function parseLocalBranchRef(field, source) {
+    if (!isUtf8(field)) {
+        throw new Error(`${source} contained invalid UTF-8 branch identity`);
+    }
+    const refName = field.toString('utf8');
+    if (refName.length === 0 ||
+        !refName.startsWith('refs/heads/') ||
+        refName.length === 'refs/heads/'.length) {
+        throw new Error(`${source} contained an invalid local branch identity`);
+    }
+    return refName;
+}
+function parseBranchRecords(buffer) {
+    const fields = splitNulLineTerminated(buffer);
+    if (fields.length % 3 !== 0) {
+        throw new Error('Git branch output ended with an incomplete record');
+    }
+    const records = [];
+    const seenRefNames = new Set();
+    for (let index = 0; index < fields.length; index += 3) {
+        let refField = fields[index];
+        if (index > 0) {
+            if (refField[0] !== 0x0a) {
+                throw new Error('Git branch output omitted a record separator');
+            }
+            refField = refField.subarray(1);
+        }
+        const labelField = fields[index + 1];
+        if (!isUtf8(labelField)) {
+            throw new Error('Git branch output contained invalid UTF-8');
+        }
+        const refName = parseLocalBranchRef(refField, 'Git branch output');
+        if (seenRefNames.has(refName)) {
+            throw new Error('Git branch output contained duplicate local branch identity');
+        }
+        seenRefNames.add(refName);
+        const label = labelField.toString('utf8');
+        const commitOid = GitObjectIdSchema.parse(fields[index + 2].toString('latin1'));
+        if (label.length === 0) {
+            throw new Error('Git branch output contained an invalid local branch record');
+        }
+        records.push({ refName, label, commitOid });
+    }
+    return records;
+}
+function escapeBranchPattern(term) {
+    return `*${term.replace(/[\\*?\[\]]/g, '\\$&')}*`;
+}
+function parseAbbreviationRecords(buffer) {
+    const fields = splitNulLineTerminated(buffer);
+    if (fields.length % 2 !== 0) {
+        throw new Error('Git abbreviation output ended with an incomplete record');
+    }
+    const shortByFull = new Map();
+    for (let index = 0; index < fields.length; index += 2) {
+        let fullField = fields[index];
+        if (index > 0) {
+            if (fullField[0] !== 0x0a) {
+                throw new Error('Git abbreviation output omitted a record separator');
+            }
+            fullField = fullField.subarray(1);
+        }
+        const fullOid = GitObjectIdSchema.parse(fullField.toString('latin1'));
+        const shortOid = fields[index + 1].toString('latin1');
+        if (!/^[0-9a-f]{12,}$/.test(shortOid) ||
+            shortOid.length > fullOid.length ||
+            !fullOid.startsWith(shortOid) ||
+            shortByFull.has(fullOid)) {
+            throw new Error('Git abbreviation output contained an invalid record');
+        }
+        shortByFull.set(fullOid, shortOid);
+    }
+    return shortByFull;
+}
+function parseWorktreeRecords(buffer) {
+    const records = [];
+    let current = {
+        detached: false,
+        prunable: false,
+        bare: false,
+    };
+    let open = false;
+    const seen = new Set();
+    const seenPaths = new Set();
+    for (const field of splitNul(buffer)) {
+        if (field.length === 0) {
+            if (!open || current.path === undefined) {
+                throw new Error('Git worktree output contained an incomplete record');
+            }
+            if ((current.detached && current.branchRef !== undefined) ||
+                (current.bare &&
+                    (current.headOid !== undefined ||
+                        current.branchRef !== undefined ||
+                        current.detached))) {
+                throw new Error('Git worktree output contained a contradictory record');
+            }
+            if (seenPaths.has(current.path)) {
+                throw new Error('Git worktree output contained a duplicate worktree identity');
+            }
+            seenPaths.add(current.path);
+            records.push(current);
+            current = { detached: false, prunable: false, bare: false };
+            open = false;
+            seen.clear();
+            continue;
+        }
+        open = true;
+        const separator = field.indexOf(0x20);
+        const keyField = separator === -1 ? field : field.subarray(0, separator);
+        if (keyField.some((byte) => byte > 0x7f)) {
+            throw new Error('Git worktree output contained non-ASCII field name');
+        }
+        const key = keyField.toString('ascii');
+        const value = separator === -1 ? undefined : field.subarray(separator + 1);
+        if (seen.size === 0 && key !== 'worktree') {
+            throw new Error('Git worktree output omitted leading worktree field');
+        }
+        if (seen.has(key)) {
+            throw new Error('Git worktree output contained a duplicate field');
+        }
+        seen.add(key);
+        switch (key) {
+            case 'worktree': {
+                if (value === undefined || value.length === 0 || !isUtf8(value)) {
+                    throw new Error('Git worktree output contained an invalid worktree path');
+                }
+                const path = value.toString('utf8');
+                if (!isAbsolute(path)) {
+                    throw new Error('Git worktree output contained a non-absolute worktree path');
+                }
+                current.path = path;
+                break;
+            }
+            case 'HEAD':
+                if (value === undefined || value.length === 0) {
+                    throw new Error('Git worktree output omitted a HEAD value');
+                }
+                current.headOid = GitObjectIdSchema.parse(value.toString('latin1'));
+                break;
+            case 'branch':
+                if (value === undefined) {
+                    throw new Error('Git worktree output omitted a branch identity');
+                }
+                current.branchRef = parseLocalBranchRef(value, 'Git worktree output');
+                break;
+            case 'detached':
+                if (value !== undefined) {
+                    throw new Error('Git worktree output contained an invalid detached field');
+                }
+                current.detached = true;
+                break;
+            case 'prunable':
+                current.prunable = true;
+                break;
+            case 'bare':
+                if (value !== undefined) {
+                    throw new Error('Git worktree output contained an invalid bare field');
+                }
+                current.bare = true;
+                break;
+            case 'locked':
+                break;
+            default:
+                throw new Error('Git worktree output contained an unknown field');
+        }
+    }
+    if (open) {
+        throw new Error('Git worktree output ended before record separator');
+    }
+    if (records.length === 0) {
+        throw new Error('Git worktree output contained no worktree records');
+    }
+    return records;
+}
+export async function discoverSourceCandidates(options, dependencies = {}) {
+    const runner = dependencies.runner ?? createGitRunner();
+    const repository = await discoverGitRepository(options.cwd, runner, options.signal);
+    options.signal?.throwIfAborted();
+    const worktreeResult = await runner.run(['worktree', 'list', '--porcelain', '-z'], { cwd: repository.root, signal: options.signal });
+    options.signal?.throwIfAborted();
+    const worktreeRecords = parseWorktreeRecords(worktreeResult.stdout);
+    const shortOidByFullOid = new Map();
+    const abbreviate = async (oid) => {
+        const known = shortOidByFullOid.get(oid);
+        if (known !== undefined) {
+            return known;
+        }
+        const pending = (async () => {
+            const result = await runner.run(['rev-parse', '--short=12', oid], {
+                cwd: repository.root,
+                signal: options.signal,
+            });
+            options.signal?.throwIfAborted();
+            const shortOid = stripGitLineTerminator(result.stdout).toString('latin1');
+            if (!/^[0-9a-f]{12,}$/.test(shortOid) ||
+                shortOid.length > oid.length ||
+                !oid.startsWith(shortOid)) {
+                throw new Error('Git worktree abbreviation output contained an invalid OID');
+            }
+            return shortOid;
+        })();
+        shortOidByFullOid.set(oid, pending);
+        return pending;
+    };
+    let currentBranch;
+    const resolveWorktreeIdentity = async (record) => {
+        if (record.path === undefined) {
+            return undefined;
+        }
+        // A missing porcelain HEAD is Git's valid unborn-worktree representation.
+        let commitOid = record.headOid;
+        let availability = record.prunable || record.bare ? 'unavailable' : 'pending';
+        if (availability !== 'unavailable') {
+            try {
+                const headResult = await runner.run(['rev-parse', '--verify', '--end-of-options', 'HEAD^{commit}'], { cwd: record.path, signal: options.signal });
+                options.signal?.throwIfAborted();
+                commitOid = GitObjectIdSchema.parse(stripGitLineTerminator(headResult.stdout).toString('latin1'));
+            }
+            catch (error) {
+                if (options.signal?.aborted) {
+                    throw error;
+                }
+                availability = 'unavailable';
+            }
+        }
+        const branchRef = record.branchRef;
+        const shortOid = commitOid === undefined ? undefined : await abbreviate(commitOid);
+        options.signal?.throwIfAborted();
+        const candidate = {
+            kind: 'worktree',
+            id: `worktree:${record.path}`,
+            label: branchRef === undefined
+                ? 'Detached HEAD'
+                : branchRef.replace(/^refs\/heads\//, ''),
+            path: record.path,
+            ...(branchRef === undefined ? {} : { branchRef }),
+            detached: record.detached || branchRef === undefined,
+            ...(commitOid === undefined || shortOid === undefined
+                ? {}
+                : { commitOid, shortOid }),
+            availability,
+            ...(availability === 'unavailable'
+                ? { unavailableReason: UNAVAILABLE_WORKTREE_REASON }
+                : {}),
+            isCurrentCheckout: record.path === repository.root,
+        };
+        if (record.path === repository.root &&
+            branchRef !== undefined &&
+            commitOid !== undefined &&
+            shortOid !== undefined) {
+            currentBranch = Object.freeze({
+                kind: 'branch',
+                id: `branch:${branchRef}`,
+                label: branchRef.replace(/^refs\/heads\//, ''),
+                refName: branchRef,
+                commitOid,
+                shortOid,
+            });
+        }
+        return Object.freeze(candidate);
+    };
+    const worktreeCandidates = (await Promise.all(worktreeRecords.map(resolveWorktreeIdentity))).filter((candidate) => candidate !== undefined);
+    options.signal?.throwIfAborted();
+    const initialCandidates = Object.freeze([
+        ...(currentBranch === undefined ? [] : [currentBranch]),
+        ...worktreeCandidates,
+    ]);
+    const enrichmentStart = Promise.withResolvers();
+    let enrichmentStarted = false;
+    const startCandidateEnrichment = () => {
+        if (!enrichmentStarted) {
+            enrichmentStarted = true;
+            setImmediate(enrichmentStart.resolve);
+        }
+    };
+    const candidateEnrichment = enrichmentStart.promise.then(async () => {
+        options.signal?.throwIfAborted();
+        const enrichedWorktrees = await Promise.all(worktreeCandidates.map(async (candidate) => {
+            if (candidate.availability === 'unavailable') {
+                return candidate;
+            }
+            try {
+                const statusResult = await runner.run(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], { cwd: candidate.path, signal: options.signal });
+                options.signal?.throwIfAborted();
+                return Object.freeze({
+                    ...candidate,
+                    availability: statusResult.stdout.length === 0
+                        ? 'clean'
+                        : 'dirty',
+                });
+            }
+            catch (error) {
+                if (options.signal?.aborted) {
+                    throw error;
+                }
+                return Object.freeze({
+                    ...candidate,
+                    availability: 'unavailable',
+                    unavailableReason: UNAVAILABLE_WORKTREE_REASON,
+                });
+            }
+        }));
+        return Object.freeze([
+            ...(currentBranch === undefined ? [] : [currentBranch]),
+            ...enrichedWorktrees,
+        ]);
+    });
+    void candidateEnrichment.catch(() => undefined);
+    return Object.freeze({
+        startCandidateEnrichment,
+        initialCandidates,
+        candidateEnrichment,
+        async searchBranches(term, signal) {
+            if (signal?.aborted) {
+                throw new GitRunnerError('aborted', 'Git command was cancelled', {
+                    cause: signal.reason,
+                });
+            }
+            if (term.length === 0) {
+                return Object.freeze([]);
+            }
+            const branchResult = await runner.run([
+                'branch',
+                '--list',
+                '--ignore-case',
+                '--no-color',
+                '--sort=refname',
+                `--format=${BRANCH_FORMAT}`,
+                '--',
+                escapeBranchPattern(term),
+            ], { cwd: repository.root, signal });
+            signal?.throwIfAborted();
+            const query = term.toLowerCase();
+            const records = parseBranchRecords(branchResult.stdout)
+                .filter((record) => record.label.toLowerCase().includes(query))
+                .sort((left, right) => orderByteSequences(Buffer.from(left.refName, 'utf8'), Buffer.from(right.refName, 'utf8')));
+            signal?.throwIfAborted();
+            if (records.length === 0) {
+                return Object.freeze([]);
+            }
+            const requestedOids = [...new Set(records.map((record) => record.commitOid))];
+            const abbreviationResult = await runner.run([
+                'log',
+                '--no-walk=unsorted',
+                '--abbrev=12',
+                '--format=%H%x00%h%x00',
+                '--stdin',
+            ], {
+                cwd: repository.root,
+                input: Buffer.from(`${requestedOids.join('\n')}\n`, 'ascii'),
+                signal,
+            });
+            signal?.throwIfAborted();
+            const shortByFull = parseAbbreviationRecords(abbreviationResult.stdout);
+            if (shortByFull.size !== requestedOids.length ||
+                requestedOids.some((oid) => !shortByFull.has(oid))) {
+                throw new Error('Git abbreviation output did not match requested objects');
+            }
+            signal?.throwIfAborted();
+            return Object.freeze(records.map((record) => Object.freeze({
+                kind: 'branch',
+                id: `branch:${record.refName}`,
+                label: record.label,
+                refName: record.refName,
+                commitOid: record.commitOid,
+                shortOid: shortByFull.get(record.commitOid),
+            })));
+        },
+    });
+}

package/dist/git/comparison.js

@@ -0,0 +1,263 @@
+import { ComparisonSelectionSchema, GitObjectIdSchema, PinnedComparisonSchema, } from '../contracts/comparison.js';
+import { BASE_RECOVERY, FATAL_LAUNCH_MESSAGES, HEAD_RECOVERY, LaunchError, } from '../domain/errors.js';
+import { rangeReviewKey } from '../domain/comparison-key.js';
+import { discoverGitRepository } from './repository.js';
+import { createGitRunner, GitRunnerError, } from './runner.js';
+import { createChangedFileInventory } from './inventory.js';
+function parseSingleLine(buffer, fact) {
+    const lines = buffer
+        .toString('ascii')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length !== 1) {
+        throw new Error(`Expected exactly one ${fact}; Git returned ${lines.length}`);
+    }
+    return lines[0];
+}
+async function resolveObjectFormat(repositoryRoot, runner, signal) {
+    const result = await runner.run(['rev-parse', '--show-object-format=storage'], { cwd: repositoryRoot, signal });
+    const objectFormat = parseSingleLine(result.stdout, 'object format');
+    if (objectFormat !== 'sha1' && objectFormat !== 'sha256') {
+        throw new LaunchError('git-unsupported', FATAL_LAUNCH_MESSAGES.gitUnsupported, { recovery: { kind: 'exit' } });
+    }
+    return objectFormat;
+}
+function recoveryFor(role) {
+    return role === 'base' ? BASE_RECOVERY : HEAD_RECOVERY;
+}
+function endpointMessage(selection, role) {
+    return selection.source?.kind === 'worktree'
+        ? `The selected ${role} worktree cannot resolve a committed HEAD. Choose another ${role} or repair the worktree with Git.`
+        : `The selected ${role} “${selection.label}” no longer resolves to a commit. Choose another ${role} or repair the ref with Git.`;
+}
+async function resolveCommit(selection, role, repositoryRoot, runner, signal) {
+    try {
+        const result = await runner.run([
+            'rev-parse',
+            '--verify',
+            '--end-of-options',
+            `${selection.revision}^{commit}`,
+        ], { cwd: repositoryRoot, signal });
+        return GitObjectIdSchema.parse(parseSingleLine(result.stdout, `${role} commit object`));
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        throw new LaunchError('endpoint-unavailable', endpointMessage(selection, role), { cause: error, recovery: recoveryFor(role) });
+    }
+}
+async function verifyCommit(oid, role, repositoryRoot, runner, signal) {
+    try {
+        await runner.run(['cat-file', '-e', `${oid}^{commit}`], {
+            cwd: repositoryRoot,
+            signal,
+        });
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        throw new LaunchError('object-unavailable', `Required Git object ${oid.slice(0, 12)} is missing or unreadable. Repair the repository's object data with Git, then retry.`, {
+            cause: error,
+            recovery: role === 'base' ? BASE_RECOVERY : HEAD_RECOVERY,
+        });
+    }
+}
+function parseMergeBases(buffer, objectFormat) {
+    const expectedLength = objectFormat === 'sha1' ? 40 : 64;
+    const lines = buffer.length === 0
+        ? []
+        : buffer
+            .toString('ascii')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    for (const line of lines) {
+        if (line.length !== expectedLength ||
+            !/^[0-9a-f]+$/u.test(line) ||
+            !GitObjectIdSchema.safeParse(line).success) {
+            throw new LaunchError('git-unsupported', FATAL_LAUNCH_MESSAGES.gitUnsupported, { recovery: { kind: 'exit' } });
+        }
+    }
+    return lines;
+}
+function freezeComparison(comparison) {
+    if (comparison.base.source !== undefined) {
+        Object.freeze(comparison.base.source);
+    }
+    if (comparison.head.source !== undefined) {
+        Object.freeze(comparison.head.source);
+    }
+    if (comparison.range !== undefined) {
+        Object.freeze(comparison.range.pathspecs);
+        Object.freeze(comparison.range);
+    }
+    Object.freeze(comparison.base);
+    Object.freeze(comparison.head);
+    return Object.freeze(comparison);
+}
+async function resolveRangeCommit(revision, role, repositoryRoot, runner, signal) {
+    try {
+        const result = await runner.run(['rev-parse', '--verify', '--end-of-options', `${revision}^{commit}`], { cwd: repositoryRoot, signal });
+        return GitObjectIdSchema.parse(parseSingleLine(result.stdout, `${role} commit object`));
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        throw new LaunchError('endpoint-unavailable', `The requested ${role} revision does not resolve to a commit. Check the revision and try again.`, { cause: error, recovery: { kind: 'exit' } });
+    }
+}
+async function verifyRangeCommit(oid, repositoryRoot, runner, signal) {
+    try {
+        await runner.run(['cat-file', '-e', `${oid}^{commit}`], {
+            cwd: repositoryRoot,
+            signal,
+        });
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        throw new LaunchError('object-unavailable', `Required Git object ${oid.slice(0, 12)} is missing or unreadable. Repair the repository's object data with Git, then retry.`, { cause: error, recovery: { kind: 'exit' } });
+    }
+}
+export async function createPinnedComparison(options, dependencies = {}) {
+    if (options.cwd.length === 0) {
+        throw new LaunchError('not-worktree', FATAL_LAUNCH_MESSAGES.notWorktree, { recovery: { kind: 'exit' } });
+    }
+    const baseSelection = ComparisonSelectionSchema.parse(options.base);
+    const headSelection = ComparisonSelectionSchema.parse(options.head);
+    const runner = dependencies.runner ?? createGitRunner();
+    const repository = await discoverGitRepository(options.cwd, runner, options.signal);
+    const objectFormat = await resolveObjectFormat(repository.root, runner, options.signal);
+    const baseOid = await resolveCommit(baseSelection, 'base', repository.root, runner, options.signal);
+    const headOid = await resolveCommit(headSelection, 'head', repository.root, runner, options.signal);
+    if (baseOid === headOid) {
+        throw new LaunchError('equal-commits', 'Base and head resolve to the same commit. Choose a different head.', { recovery: HEAD_RECOVERY });
+    }
+    await verifyCommit(baseOid, 'base', repository.root, runner, options.signal);
+    await verifyCommit(headOid, 'head', repository.root, runner, options.signal);
+    let mergeBaseOutput = Buffer.alloc(0);
+    try {
+        const mergeBaseResult = await runner.run(['merge-base', '--all', baseOid, headOid], { cwd: repository.root, signal: options.signal });
+        mergeBaseOutput = mergeBaseResult.stdout;
+    }
+    catch (error) {
+        if (!(error instanceof GitRunnerError &&
+            error.kind === 'exit' &&
+            error.exitCode === 1 &&
+            error.stderr.length === 0)) {
+            throw error;
+        }
+    }
+    const mergeBases = parseMergeBases(mergeBaseOutput, objectFormat);
+    if (mergeBases.length === 0) {
+        throw new LaunchError('unrelated-histories', 'Base and head have unrelated histories; Git could not find a merge base. Choose a different head or go back to change base.', { recovery: HEAD_RECOVERY });
+    }
+    if (mergeBases.length > 1) {
+        throw new LaunchError('multiple-merge-bases', 'Base and head have multiple merge bases, so this comparison cannot be pinned unambiguously. Choose a different head or go back to change base.', { recovery: HEAD_RECOVERY });
+    }
+    const mergeBaseOid = mergeBases[0];
+    await verifyCommit(baseOid, 'base', repository.root, runner, options.signal);
+    await verifyCommit(headOid, 'head', repository.root, runner, options.signal);
+    await verifyCommit(mergeBaseOid, 'merge-base', repository.root, runner, options.signal);
+    const changedFiles = await createChangedFileInventory({
+        repositoryRoot: repository.root,
+        mergeBaseOid,
+        headOid,
+        objectFormat,
+        signal: options.signal,
+    }, { runner });
+    const comparison = PinnedComparisonSchema.parse({
+        repositoryRoot: repository.root,
+        objectFormat,
+        base: {
+            label: baseSelection.label,
+            oid: baseOid,
+            ...(baseSelection.source === undefined
+                ? {}
+                : { source: baseSelection.source }),
+        },
+        head: {
+            label: headSelection.label,
+            oid: headOid,
+            ...(headSelection.source === undefined
+                ? {}
+                : { source: headSelection.source }),
+        },
+        mergeBaseOid,
+        changedFiles,
+        hasCommittedChanges: changedFiles.length > 0,
+    });
+    return freezeComparison(comparison);
+}
+export async function createPinnedRangeComparison(options, dependencies = {}) {
+    if (options.cwd.length === 0) {
+        throw new LaunchError('not-worktree', FATAL_LAUNCH_MESSAGES.notWorktree, { recovery: { kind: 'exit' } });
+    }
+    const runner = dependencies.runner ?? createGitRunner();
+    const repository = await discoverGitRepository(options.cwd, runner, options.signal);
+    const objectFormat = await resolveObjectFormat(repository.root, runner, options.signal);
+    const baseOid = await resolveRangeCommit(options.baseRevision, 'base', repository.root, runner, options.signal);
+    const headOid = await resolveRangeCommit(options.headRevision, 'head', repository.root, runner, options.signal);
+    await verifyRangeCommit(baseOid, repository.root, runner, options.signal);
+    await verifyRangeCommit(headOid, repository.root, runner, options.signal);
+    try {
+        await runner.run(['merge-base', '--is-ancestor', baseOid, headOid], {
+            cwd: repository.root,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        if (options.signal?.aborted) {
+            throw error;
+        }
+        if (error instanceof GitRunnerError &&
+            error.kind === 'exit' &&
+            error.exitCode === 1) {
+            throw new LaunchError('non-ancestor-range', 'The requested base is not an ancestor of the requested head. Choose a contiguous range and try again.', { cause: error, recovery: { kind: 'exit' } });
+        }
+        throw error;
+    }
+    const pathspecs = Object.freeze([...options.pathspecs]);
+    let changedFiles;
+    try {
+        changedFiles = await createChangedFileInventory({
+            repositoryRoot: repository.root,
+            mergeBaseOid: baseOid,
+            headOid,
+            objectFormat,
+            pathspecs,
+            signal: options.signal,
+        }, { runner });
+    }
+    catch (error) {
+        if (pathspecs.length > 0 &&
+            error instanceof GitRunnerError &&
+            error.kind === 'exit') {
+            throw new LaunchError('invalid-pathspec', 'Git rejected the requested pathspec scope. Check native Git pathspec syntax and try again.', { cause: error, recovery: { kind: 'exit' } });
+        }
+        throw error;
+    }
+    return freezeComparison(PinnedComparisonSchema.parse({
+        repositoryRoot: repository.root,
+        objectFormat,
+        base: { label: options.baseRevision, oid: baseOid },
+        head: { label: options.headRevision, oid: headOid },
+        mergeBaseOid: baseOid,
+        changedFiles,
+        hasCommittedChanges: changedFiles.length > 0,
+        range: {
+            kind: 'revisions',
+            requestedBase: options.baseRevision,
+            requestedHead: options.headRevision,
+            baseOid,
+            headOid,
+            pathspecs,
+            reviewKey: rangeReviewKey(baseOid, headOid, pathspecs),
+        },
+    }));
+}