Adds AI-powered explanation for unpushed branch changes on Graph View

Also adds more item context for new AI-assisted commands to explain
unpushed changes
(#4443, #4522)

Author: sergeibbb

contributions.json

@@ -113,6 +113,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_ai",
+						"order": 20
+					}
+				]
+			}
+		},
 		"gitlens.ai.explainWip": {
 			"label": "Explain Working Changes (Preview)...",
 			"commandPalette": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled"

package.json

@@ -6251,6 +6251,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)...",
@@ -11371,6 +11376,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"
@@ -24162,6 +24171,11 @@
 					"when": "webviewItem =~ /gitlens:branch\\b/ && !listMultiSelection && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled",
 					"group": "1_gitlens_ai@10"
 				},
+				{
+					"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_ai@20"
+				},
 				{
 					"command": "gitlens.graph.openBranchOnRemote",
 					"when": "webviewItem =~ /gitlens:branch\\b(?=.*?\\b\\+(tracking|remote)\\b)/ && gitlens:repos:withRemotes",

src/commands/explainBranch.ts

@@ -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/constants.commands.generated.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/env/node/git/sub-providers/graph.ts

@@ -359,7 +359,9 @@ export class GraphGitSubProvider implements GitGraphSubProvider {
 										: branchIdOfMainWorktree === branchId
 											? '+checkedout'
 											: ''
-								}${branch?.starred ? '+starred' : ''}`,
+								}${branch?.starred ? '+starred' : ''}${branch?.upstream?.state.ahead ? '+ahead' : ''}${
+									branch?.upstream?.state.behind ? '+behind' : ''
+								}`,
 								webviewItemValue: {
 									type: 'branch',
 									ref: createReference(tip, repoPath, {

src/webviews/plus/graph/graphWebview.ts

@@ -719,6 +719,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),
@@ -3990,6 +3991,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', context: { type: 'branch' } },
+			});
+		}
+
+		return Promise.resolve();
+	}
 	@log()
 	private explainBranch(item?: GraphItemContext) {
 		const ref = this.getGraphItemRef(item, 'branch');