Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

6.9 KB
Raw Blame
import { realpathSync } from 'node:fs';
import {
  type CheckoutFailureReason,
  isBranchNotFoundGitError,
  REFUSED_SYMLINK_PATHS_CAP,
} from '@inkeep/open-knowledge-core';
import { truncateError } from './error-format.ts';
import { dirtyFilesOverlapWith } from './git-dirty.ts';
import { createGitInstance } from './git-handle.ts';
import {
  assertIncomingSymlinksSafe,
  resolveIncomingCommit,
  UnsafeIncomingSymlinkError,
} from './incoming-symlink-guard.ts';
import { getLogger } from './logger.ts';

const log = getLogger('git-checkout');

const FF_FETCH_TIMEOUT_MS = 15_000;

export type CheckoutOutcome =
  | { ok: true }
  | {
      ok: false;
      reason: CheckoutFailureReason;
      files?: string[];
      otherWorktreePath?: string;
      refusedSymlinkPaths?: string[];
    };

const BRANCH_IN_OTHER_WORKTREE_RE =
  /'[^']+' is already (?:checked out|used by worktree) at '([^']+)'/;

export function isBranchInOtherWorktreeError(
  err: unknown,
): { held: true; path: string } | { held: false } {
  const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
  const match = message.match(BRANCH_IN_OTHER_WORKTREE_RE);
  if (match === null) return { held: false };
  const rawPath = match[1];
  if (rawPath === undefined || rawPath.length === 0) return { held: false };
  let canonicalPath: string;
  try {
    canonicalPath = realpathSync(rawPath);
  } catch {
    canonicalPath = rawPath;
  }
  return { held: true, path: canonicalPath };
}

export const CHECKOUT_HANDLER_TAG = 'git-checkout';

export const isBranchNotFoundFetchError = isBranchNotFoundGitError;

export async function runCheckoutFlow(
  projectDir: string,
  branch: string,
  opts: { readonly fastForward?: boolean; readonly credentialConfig: string[] },
): Promise<CheckoutOutcome> {
  if (opts.fastForward) {
    const ff = await fastForwardBranchToOrigin(projectDir, branch, opts.credentialConfig);
    if (ff === 'diverged') {
      return { ok: false, reason: 'ff-diverged' };
    }
  }

  const { git, env: gitEnv } = createGitInstance(projectDir, {
    credentialConfig: opts.credentialConfig,
  });

  const branchIsLocal = await git
    .raw(['rev-parse', '--verify', `refs/heads/${branch}`])
    .then(() => true)
    .catch(() => false);

  if (!branchIsLocal) {
    try {
      await git.raw(['fetch', 'origin', branch]);
    } catch (err) {
      return {
        ok: false,
        reason: isBranchNotFoundFetchError(err) ? 'branch-not-found' : 'fetch-failed',
      };
    }
  }

  let target: string;
  try {
    target = await resolveIncomingCommit(
      git,
      branchIsLocal ? `refs/heads/${branch}` : `refs/remotes/origin/${branch}`,
    );
  } catch (err) {
    log.warn({ branch, err }, `action=checkout-failed branch=${branch}`);
    return { ok: false, reason: 'checkout-failed' };
  }

  const overlap = await dirtyFilesOverlapWith(projectDir, target);
  if (overlap.conflicts) {
    return { ok: false, reason: 'dirty-conflict', files: overlap.files };
  }

  try {
    await assertIncomingSymlinksSafe(git, target, 'checkout', gitEnv);
  } catch (err) {
    if (err instanceof UnsafeIncomingSymlinkError) {
      log.warn(
        {
          event: 'unsafe-incoming-symlinks',
          branch,
          target,
          links: err.unsafe.slice(0, REFUSED_SYMLINK_PATHS_CAP),
          refusedCount: err.unsafe.length,
        },
        `action=checkout-refused branch=${branch}`,
      );
      return {
        ok: false,
        reason: 'unsafe-symlinks',
        refusedSymlinkPaths: err.displayPaths(),
      };
    }
    log.warn({ branch, target, err }, `action=symlink-check-failed branch=${branch}`);
    return { ok: false, reason: 'symlink-check-failed' };
  }

  const readHeadRef = (): Promise<string> =>
    git
      .raw(['symbolic-ref', '--quiet', 'HEAD'])
      .then((ref) => ref.trim())
      .catch(() => '');
  const targetHeadRef = `refs/heads/${branch}`;
  const headRefBefore = await readHeadRef();
  let createdBranch = false;
  try {
    if (!branchIsLocal) {
      await git.raw(['branch', '--no-track', branch, target]);
      createdBranch = true;
      await git.raw(['branch', `--set-upstream-to=refs/remotes/origin/${branch}`, branch]);
    }
    await git.raw(['checkout', branch]);
    return { ok: true };
  } catch (err) {
    if (headRefBefore !== targetHeadRef && (await readHeadRef()) === targetHeadRef) {
      log.warn(
        { branch, target, err },
        `action=checkout-hook-failed branch=${branch} error=${truncateError(err)}`,
      );
      return { ok: true };
    }
    if (createdBranch) {
      await git.raw(['branch', '-D', branch]).catch((cleanupErr: unknown) => {
        log.warn(
          { branch, target, err: cleanupErr },
          `action=checkout-cleanup-failed branch=${branch}`,
        );
      });
    }
    const heldElsewhere = isBranchInOtherWorktreeError(err);
    if (heldElsewhere.held) {
      log.warn(
        { branch, heldAt: heldElsewhere.path },
        `reason=branch-in-other-worktree branch=${branch} held_at=${heldElsewhere.path}`,
      );
      return {
        ok: false,
        reason: 'branch-in-other-worktree',
        otherWorktreePath: heldElsewhere.path,
      };
    }
    log.warn(
      { branch, err },
      `action=checkout-failed branch=${branch} error=${truncateError(err)}`,
    );
    return { ok: false, reason: 'checkout-failed' };
  }
}

export type FastForwardOutcome = 'advanced' | 'up-to-date' | 'diverged' | 'unavailable';

export async function fastForwardBranchToOrigin(
  projectDir: string,
  branch: string,
  credentialConfig: string[],
): Promise<FastForwardOutcome> {
  const { git } = createGitInstance(projectDir, {
    timeoutMs: FF_FETCH_TIMEOUT_MS,
    credentialConfig,
  });

  const revParse = (ref: string): Promise<string | null> =>
    git
      .raw(['rev-parse', '--verify', ref])
      .then((sha) => sha.trim())
      .catch(() => null);

  try {
    await git.raw(['fetch', 'origin', branch]);
  } catch (err) {
    log.warn(
      { branch, err },
      `action=ff-fetch-failed branch=${branch} error=${truncateError(err)}`,
    );
    return 'unavailable';
  }

  const originTip = await revParse(`refs/remotes/origin/${branch}`);
  if (!originTip) return 'unavailable';

  const localTip = await revParse(`refs/heads/${branch}`);
  if (!localTip || localTip === originTip) return 'up-to-date';

  const mergeBase = await git
    .raw(['merge-base', localTip, originTip])
    .then((sha) => sha.trim())
    .catch(() => '');

  if (mergeBase === localTip) {
    try {
      await git.raw(['fetch', 'origin', `${branch}:${branch}`]);
    } catch (err) {
      log.warn(
        { branch, err },
        `action=ff-advance-failed branch=${branch} error=${truncateError(err)}`,
      );
      return 'unavailable';
    }
    const after = await revParse(`refs/heads/${branch}`);
    return after === originTip ? 'advanced' : 'unavailable';
  }
  if (mergeBase === originTip) return 'up-to-date';
  return 'diverged';
}