@vibe-validate/git 0.17.6 → 0.18.0

package/dist/branch-cleanup.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Branch Cleanup - Core Analysis Functions
+ *
+ * Git-aware branch cleanup that safely identifies and removes merged branches.
+ * This module provides the core analysis functionality for determining which
+ * branches are safe to delete automatically and which need manual review.
+ *
+ * Safety principles:
+ * 1. NEVER delete branches with unpushed work
+ * 2. Auto-delete only if 100% safe (merged + no unpushed commits)
+ * 3. All deletions are recoverable via reflog
+ * 4. Never touch protected branches (main/master/develop)
+ *
+ * @packageDocumentation
+ */
+import { type GitHubPullRequest } from './gh-commands.js';
+/**
+ * Remote tracking status for a branch
+ */
+export type RemoteStatus = 'exists' | 'deleted' | 'never_pushed';
+/**
+ * Git metadata about a branch
+ */
+export interface BranchGitFacts {
+    /** Branch name */
+    name: string;
+    /** Is branch merged to default branch */
+    mergedToMain: boolean;
+    /** Remote tracking status */
+    remoteStatus: RemoteStatus;
+    /** Number of unpushed commits */
+    unpushedCommitCount: number;
+    /** Last commit date (ISO 8601) */
+    lastCommitDate: string;
+    /** Last commit author */
+    lastCommitAuthor: string;
+    /** Days since last activity */
+    daysSinceActivity: number;
+}
+/**
+ * GitHub metadata about a branch (from PR data)
+ */
+export interface BranchGitHubFacts {
+    /** Associated PR number */
+    prNumber?: number;
+    /** PR state (open, closed, merged) */
+    prState?: 'open' | 'closed' | 'merged';
+    /** Merge method used */
+    mergeMethod?: 'merge' | 'squash' | 'rebase';
+    /** When PR was merged */
+    mergedAt?: string;
+    /** Who merged the PR */
+    mergedBy?: string;
+}
+/**
+ * Assessment and action commands for a branch
+ */
+export interface BranchAssessment {
+    /** Human-readable assessment */
+    summary: string;
+    /** Exact command to delete branch */
+    deleteCommand: string;
+    /** Command to recover branch after deletion */
+    recoveryCommand: string;
+}
+/**
+ * Complete analysis of a branch
+ */
+export interface BranchAnalysis {
+    /** Git facts about the branch */
+    gitFacts: BranchGitFacts;
+    /** GitHub facts (if available) */
+    githubFacts?: BranchGitHubFacts;
+    /** Assessment and commands */
+    assessment: BranchAssessment;
+}
+/**
+ * Context about the cleanup operation
+ */
+export interface CleanupContext {
+    /** Repository name (owner/repo) */
+    repository: string;
+    /** Remote name (usually 'origin') */
+    remote: string;
+    /** Default branch name (main/master/develop) */
+    defaultBranch: string;
+    /** Branch we were on before switching */
+    previousBranch?: string;
+    /** Current branch after potential switch */
+    currentBranch: string;
+    /** Did we switch branches during cleanup? */
+    switchedBranch: boolean;
+    /** Why we switched (if applicable) */
+    switchReason?: string;
+}
+/**
+ * Detect the repository's default branch
+ *
+ * Tries multiple methods in order of reliability:
+ * 1. Remote HEAD symbolic ref (most reliable)
+ * 2. Git config init.defaultBranch
+ * 3. Fallback to 'main'
+ *
+ * @param options - Options for detection
+ * @returns Default branch name
+ * @throws Error if throwOnError is true and detection fails
+ */
+export declare function detectDefaultBranch(options?: {
+    throwOnError?: boolean;
+}): string;
+/**
+ * Check if a branch is protected (should never be deleted)
+ *
+ * @param name - Branch name
+ * @param defaultBranch - Default branch name
+ * @returns true if branch is protected
+ */
+export declare function isProtectedBranch(name: string, defaultBranch: string): boolean;
+/**
+ * Parse remote tracking status from git branch -vv output
+ *
+ * @param branchVerbose - Output from git branch -vv
+ * @returns Remote status and ref
+ */
+export declare function parseRemoteTracking(branchVerbose: string): {
+    remoteStatus: RemoteStatus;
+    remoteRef: string | null;
+};
+/**
+ * Get unpushed commit count for a branch
+ *
+ * @param branch - Branch name
+ * @param remoteRef - Remote ref (e.g., 'origin/feature/test')
+ * @returns Number of unpushed commits
+ */
+export declare function getUnpushedCommitCount(branch: string, remoteRef: string | null): number;
+/**
+ * Gather git facts about a branch
+ *
+ * @param branch - Branch name
+ * @param _defaultBranch - Default branch name (reserved for future use)
+ * @param mergedBranches - Set of branch names that are merged to main
+ * @returns Git facts about the branch
+ */
+export declare function gatherBranchGitFacts(branch: string, _defaultBranch: string, mergedBranches: Set<string>): Promise<BranchGitFacts>;
+/**
+ * Determine if a branch is 100% safe to auto-delete
+ *
+ * A branch is auto-delete safe if:
+ * - Merged to main (detected by git)
+ * - Zero unpushed commits
+ * - Even if deleted, it's recoverable via reflog
+ *
+ * @param facts - Git facts about the branch
+ * @returns true if safe to auto-delete
+ */
+export declare function isAutoDeleteSafe(facts: BranchGitFacts): boolean;
+/**
+ * Determine if a branch needs manual review before deletion
+ *
+ * A branch needs review if:
+ * - Not merged (could be squash/rebase merged)
+ * - Zero unpushed commits (safe from data loss)
+ * - Remote deleted OR >30 days old
+ * - NOT if has open PR (obviously keep)
+ * - NOT if has unpushed work (obviously keep)
+ *
+ * @param facts - Git facts about the branch
+ * @param githubFacts - GitHub facts (used to check PR state)
+ * @returns true if needs manual review
+ */
+export declare function needsReview(facts: BranchGitFacts, githubFacts?: BranchGitHubFacts): boolean;
+/**
+ * Determine if a branch should be shown in output
+ *
+ * @param analysis - Branch analysis
+ * @returns true if should be shown
+ */
+export declare function shouldShowBranch(analysis: BranchAnalysis): boolean;
+/**
+ * Detect merge method from PR data
+ *
+ * Analyzes PR metadata to determine how it was merged:
+ * - Squash: merge commit exists but PR has multiple commits
+ * - Merge: merge commit with multiple parents (true merge)
+ * - Rebase: commits were rebased onto target branch
+ *
+ * @param pr - Pull request data
+ * @returns Merge method or undefined if cannot determine
+ */
+export declare function detectMergeMethod(pr: GitHubPullRequest): 'merge' | 'squash' | 'rebase' | undefined;
+/**
+ * Fetch PR data for a list of branches
+ *
+ * Efficiently batch-fetches merged PRs from GitHub and creates a map
+ * of branch name → PR data for quick lookups during enrichment.
+ *
+ * @param repository - Repository in owner/repo format
+ * @param _branches - Branch names (reserved for future filtering)
+ * @returns Map of branch name → PR data
+ * @throws Error if gh CLI is not available
+ */
+export declare function fetchPRDataForBranches(repository: string, _branches: string[]): Promise<Map<string, GitHubPullRequest>>;
+/**
+ * Enrich branch analyses with GitHub PR data
+ *
+ * Populates the githubFacts field in each analysis by matching branches
+ * to merged PRs. This helps identify squash-merged branches that git
+ * doesn't recognize as merged.
+ *
+ * @param analyses - Branch analyses to enrich
+ * @param repository - Repository in owner/repo format
+ * @throws Error if gh CLI is not available
+ */
+export declare function enrichWithGitHubData(analyses: BranchAnalysis[], repository: string): Promise<void>;
+/**
+ * Result of branch cleanup operation
+ */
+export interface CleanupResult {
+    /** Context about the cleanup operation */
+    context: CleanupContext;
+    /** Branches that were auto-deleted */
+    autoDeleted: Array<{
+        name: string;
+        reason: string;
+        recoveryCommand: string;
+    }>;
+    /** Branches that need manual review */
+    needsReview: Array<{
+        name: string;
+        verification: BranchGitFacts & Partial<BranchGitHubFacts>;
+        assessment: string;
+        deleteCommand: string;
+        recoveryCommand: string;
+    }>;
+    /** Summary statistics */
+    summary: {
+        autoDeletedCount: number;
+        needsReviewCount: number;
+        totalBranchesAnalyzed: number;
+    };
+    /** Recovery information */
+    recoveryInfo: string;
+}
+/**
+ * Setup cleanup context and handle current branch switching
+ *
+ * If we're on a branch that needs cleanup, switch to default branch first.
+ *
+ * @returns Cleanup context
+ */
+export declare function setupCleanupContext(): Promise<CleanupContext>;
+/**
+ * Generate assessment text for a branch needing review
+ */
+export declare function generateAssessment(gitFacts: BranchGitFacts, githubFacts?: BranchGitHubFacts): string;
+/**
+ * Generate assessment for branch with deleted remote
+ */
+export declare function generateDeletedRemoteAssessment(gitFacts: BranchGitFacts, githubFacts?: BranchGitHubFacts): string;
+/**
+ * Try to delete a safe branch and return result
+ */
+export declare function tryDeleteBranch(gitFacts: BranchGitFacts): {
+    deleted: boolean;
+    error?: string;
+};
+/**
+ * Categorize branches into auto-delete and needs-review
+ */
+export declare function categorizeBranches(analyses: BranchAnalysis[]): {
+    autoDeleted: CleanupResult['autoDeleted'];
+    needsReview: CleanupResult['needsReview'];
+};
+/**
+ * Perform comprehensive branch cleanup
+ *
+ * This is the main entry point for branch cleanup. It:
+ * 1. Sets up context and switches branches if needed
+ * 2. Gathers all local branches
+ * 3. Analyzes each branch (git facts + GitHub enrichment)
+ * 4. Categorizes branches (auto-delete vs needs-review)
+ * 5. Deletes safe branches
+ * 6. Returns structured result with YAML-compatible format
+ *
+ * @returns Cleanup result with detailed analysis
+ */
+export declare function cleanupBranches(): Promise<CleanupResult>;
+//# sourceMappingURL=branch-cleanup.d.ts.map

package/dist/branch-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-cleanup.d.ts","sourceRoot":"","sources":["../src/branch-cleanup.ts"],"names":[],"mappings":"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"}