Add AI-powered explanation for unpushed branch changes.

(#4443, #4522)

Author: sergeibbb

contributions.json

@@ -24,7 +24,7 @@
 			}
 		},
 		"gitlens.ai.aiRebaseBranch:graph": {
-			"label": "AI Recompose branch commits (Preview)...",
+			"label": "AI Recompose Branch Commits (Preview)",
 			"icon": "$(sparkle)",
 			"menus": {
 				"webview/context": [
@@ -37,7 +37,7 @@
 			}
 		},
 		"gitlens.ai.aiRebaseUnpushed:graph": {
-			"label": "AI Recompose unpushed commits (Preview)...",
+			"label": "AI Recompose Unpushed Commits (Preview)",
 			"icon": "$(sparkle)",
 			"menus": {
 				"webview/context": [
@@ -139,6 +139,19 @@
 				]
 			}
 		},
+		"gitlens.ai.explainUnpushed:graph": {
+			"label": "Explain Unpushed Changes (Preview)",
+			"icon": "$(sparkle)",
+			"menus": {
+				"webview/context": [
+					{
+						"when": "webviewItem =~ /gitlens:branch\\b(?=.*?\\b\\+ahead\\b)/ && !listMultiSelection && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled",
+						"group": "1_gitlens_actions_4",
+						"order": 102
+					}
+				]
+			}
+		},
 		"gitlens.ai.explainWip": {
 			"label": "Explain Working Changes (Preview)...",
 			"commandPalette": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled"

docs/telemetry-events.md

@@ -6149,12 +6149,12 @@
 			},
 			{
 				"command": "gitlens.ai.aiRebaseBranch:graph",
-				"title": "AI Recompose branch commits (Preview)...",
+				"title": "AI Recompose Branch Commits (Preview)",
 				"icon": "$(sparkle)"
 			},
 			{
 				"command": "gitlens.ai.aiRebaseUnpushed:graph",
-				"title": "AI Recompose unpushed commits (Preview)...",
+				"title": "AI Recompose Unpushed Commits (Preview)",
 				"icon": "$(sparkle)"
 			},
 			{
@@ -6202,6 +6202,11 @@
 				"title": "Explain Changes (Preview)",
 				"icon": "$(sparkle)"
 			},
+			{
+				"command": "gitlens.ai.explainUnpushed:graph",
+				"title": "Explain Unpushed Changes (Preview)",
+				"icon": "$(sparkle)"
+			},
 			{
 				"command": "gitlens.ai.explainWip",
 				"title": "Explain Working Changes (Preview)...",
@@ -10850,6 +10855,10 @@
 					"command": "gitlens.ai.explainStash:views",
 					"when": "false"
 				},
+				{
+					"command": "gitlens.ai.explainUnpushed:graph",
+					"when": "false"
+				},
 				{
 					"command": "gitlens.ai.explainWip",
 					"when": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled"
@@ -22935,6 +22944,11 @@
 					"when": "webviewItem =~ /gitlens:branch\\b/ && !listMultiSelection && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled",
 					"group": "1_gitlens_actions_4@100"
 				},
+				{
+					"command": "gitlens.ai.explainUnpushed:graph",
+					"when": "webviewItem =~ /gitlens:branch\\b(?=.*?\\b\\+ahead\\b)/ && !listMultiSelection && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled",
+					"group": "1_gitlens_actions_4@102"
+				},
 				{
 					"command": "gitlens.graph.openBranchOnRemote",
 					"when": "webviewItem =~ /gitlens:branch\\b(?=.*?\\b\\+(tracking|remote)\\b)/ && gitlens:repos:withRemotes",

package.json

@@ -16,6 +16,7 @@ import { ExplainCommandBase } from './explainBase';
 
 export interface ExplainBranchCommandArgs extends ExplainBaseArgs {
 	ref?: string;
+	baseBranch?: string;
 }
 
 @command()
@@ -67,15 +68,25 @@ export class ExplainBranchCommand extends ExplainCommandBase {
 			}
 
 			// Clarifying the base branch
-			const baseBranchNameResult = await getBranchMergeTargetName(this.container, branch);
 			let baseBranch;
-			if (!baseBranchNameResult.paused) {
-				baseBranch = await svc.branches.getBranch(baseBranchNameResult.value);
-			}
-
-			if (!baseBranch) {
-				void showGenericErrorMessage(`Unable to find the base branch for branch ${branch.name}.`);
-				return;
+			if (args.baseBranch) {
+				// Use the provided base branch
+				baseBranch = await svc.branches.getBranch(args.baseBranch);
+				if (!baseBranch) {
+					void showGenericErrorMessage(`Unable to find the specified base branch: ${args.baseBranch}`);
+					return;
+				}
+			} else {
+				// Fall back to automatic merge target detection
+				const baseBranchNameResult = await getBranchMergeTargetName(this.container, branch);
+				if (!baseBranchNameResult.paused) {
+					baseBranch = await svc.branches.getBranch(baseBranchNameResult.value);
+				}
+
+				if (!baseBranch) {
+					void showGenericErrorMessage(`Unable to find the base branch for branch ${branch.name}.`);
+					return;
+				}
 			}
 
 			// Get the diff between the branch and its upstream or base

src/commands/explainBranch.ts

@@ -12,6 +12,7 @@ export type ContributedCommands =
 	| 'gitlens.ai.explainCommit:views'
 	| 'gitlens.ai.explainStash:graph'
 	| 'gitlens.ai.explainStash:views'
+	| 'gitlens.ai.explainUnpushed:graph'
 	| 'gitlens.ai.explainWip:graph'
 	| 'gitlens.ai.explainWip:views'
 	| 'gitlens.ai.feedback.helpful'

src/constants.commands.generated.ts

@@ -700,6 +700,7 @@ export class GraphWebviewProvider implements WebviewProvider<State, State, Graph
 				this.copyWorkingChangesToWorktree,
 			),
 			this.host.registerWebviewCommand('gitlens.ai.generateCommitMessage:graph', this.generateCommitMessage),
+			this.host.registerWebviewCommand('gitlens.ai.explainUnpushed:graph', this.aiExplainUnpushed),
 			this.host.registerWebviewCommand('gitlens.ai.explainBranch:graph', this.explainBranch),
 			this.host.registerWebviewCommand('gitlens.ai.explainCommit:graph', this.explainCommit),
 			this.host.registerWebviewCommand('gitlens.ai.explainStash:graph', this.explainStash),
@@ -3893,6 +3894,25 @@ export class GraphWebviewProvider implements WebviewProvider<State, State, Graph
 		});
 	}
 
+	@log()
+	private aiExplainUnpushed(item?: GraphItemContext) {
+		if (isGraphItemRefContext(item, 'branch')) {
+			const { ref } = item.webviewItemValue;
+
+			if (!ref.upstream) {
+				return Promise.resolve();
+			}
+
+			return executeCommand<ExplainBranchCommandArgs>('gitlens.ai.explainBranch', {
+				repoPath: ref.repoPath,
+				ref: ref.ref,
+				baseBranch: ref.upstream.name,
+				source: { source: 'graph', type: 'branch' },
+			});
+		}
+
+		return Promise.resolve();
+	}
 	@log()
 	private explainBranch(item?: GraphItemContext) {
 		const ref = this.getGraphItemRef(item, 'branch');