/**
 * BranchManager Port Interface
 *
 * Manages branch-level git operations (create, merge, diff, delete)
 * across project clones. Works directly on branches without requiring
 * a worktree to be checked out.
 */

import type { MergeResult, BranchCommit } from './types.js';

export interface BranchManager {
  /**
   * Ensure a branch exists. Creates it from baseBranch if it doesn't.
   * Idempotent — no-op if the branch already exists.
   */
  ensureBranch(repoPath: string, branch: string, baseBranch: string): Promise<void>;

  /**
   * Merge sourceBranch into targetBranch.
   * Uses an ephemeral worktree for merge safety.
   * Returns conflict info if merge fails.
   */
  mergeBranch(repoPath: string, sourceBranch: string, targetBranch: string): Promise<MergeResult>;

  /**
   * Get the raw unified diff between two branches.
   * Uses three-dot diff (baseBranch...headBranch) to show changes
   * introduced by headBranch since it diverged from baseBranch.
   */
  diffBranches(repoPath: string, baseBranch: string, headBranch: string): Promise<string>;

  /**
   * Delete a branch. No-op if the branch doesn't exist.
   */
  deleteBranch(repoPath: string, branch: string): Promise<void>;

  /**
   * Check if a branch exists in the repository.
   */
  branchExists(repoPath: string, branch: string): Promise<boolean>;

  /**
   * Check if a branch exists as a remote tracking branch (origin/<branch>).
   * Useful for validating branch names against what the remote has,
   * since local branches may not include all remote branches.
   */
  remoteBranchExists(repoPath: string, branch: string): Promise<boolean>;

  /**
   * List commits that headBranch has but baseBranch doesn't.
   * Used for commit-level navigation in code review.
   */
  listCommits(repoPath: string, baseBranch: string, headBranch: string): Promise<BranchCommit[]>;

  /**
   * Get the raw unified diff for a single commit.
   */
  diffCommit(repoPath: string, commitHash: string): Promise<string>;
}