Add explain branch (wip)

Author: d13

contributions.json

@@ -23,6 +23,10 @@
 				]
 			}
 		},
+		"gitlens.ai.explainBranch": {
+			"label": "Explain Branch (Preview)...",
+			"commandPalette": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled"
+		},
 		"gitlens.ai.explainCommit": {
 			"label": "Explain Commit...",
 			"commandPalette": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled && config.gitlens.ai.enabled",

docs/telemetry-events.md

@@ -114,7 +114,7 @@
 
 ```typescript
 {
-  'changeType': 'wip' | 'stash' | 'commit' | 'draft-stash' | 'draft-patch' | 'draft-suggested_pr_change',
+  'changeType': 'wip' | 'stash' | 'commit' | 'branch' | 'draft-stash' | 'draft-patch' | 'draft-suggested_pr_change',
   'config.largePromptThreshold': number,
   'config.usedCustomInstructions': boolean,
   'duration': number,
@@ -2063,7 +2063,7 @@ or
   'context.webview.type': string,
   'period': 'all' | `${number}|D` | `${number}|M` | `${number}|Y`,
   'showAllBranches': boolean,
-  'sliceBy': 'author' | 'branch'
+  'sliceBy': 'branch' | 'author'
 }
 ```
 

package.json

@@ -6074,6 +6074,11 @@
 				"category": "GitLens",
 				"icon": "$(person-add)"
 			},
+			{
+				"command": "gitlens.ai.explainBranch",
+				"title": "Explain Branch (Preview)...",
+				"category": "GitLens"
+			},
 			{
 				"command": "gitlens.ai.explainCommit",
 				"title": "Explain Commit...",
@@ -10409,6 +10414,10 @@
 					"command": "gitlens.addAuthors",
 					"when": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && !gitlens:hasVirtualFolders"
 				},
+				{
+					"command": "gitlens.ai.explainBranch",
+					"when": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled"
+				},
 				{
 					"command": "gitlens.ai.explainCommit",
 					"when": "gitlens:enabled && !gitlens:readonly && !gitlens:untrusted && gitlens:gk:organization:ai:enabled && config.gitlens.ai.enabled"

src/commands.ts

@@ -21,6 +21,7 @@ import './commands/diffWithRevision';
 import './commands/diffWithRevisionFrom';
 import './commands/diffWithWorking';
 import './commands/externalDiff';
+import './commands/explainBranch';
 import './commands/explainCommit';
 import './commands/explainStash';
 import './commands/explainWip';

src/commands/explainBranch.ts

@@ -0,0 +1,265 @@
+import type { TextEditor, Uri } from 'vscode';
+import { ProgressLocation } from 'vscode';
+import type { Source } from '../constants.telemetry';
+import type { Container } from '../container';
+import { GitUri } from '../git/gitUri';
+import type { GitBranchReference } from '../git/models/reference';
+import { showGenericErrorMessage } from '../messages';
+import type { AIExplainSource } from '../plus/ai/aiProviderService';
+import { showComparisonPicker } from '../quickpicks/comparisonPicker';
+import { ReferencesQuickPickIncludes, showReferencePicker } from '../quickpicks/referencePicker';
+import { getBestRepositoryOrShowPicker, getRepositoryOrShowPicker } from '../quickpicks/repositoryPicker';
+import { command } from '../system/-webview/command';
+import { showMarkdownPreview } from '../system/-webview/markdown';
+import { Logger } from '../system/logger';
+import { getSettledValue, getSettledValues } from '../system/promise';
+import { GlCommandBase } from './commandBase';
+import { getCommandUri } from './commandBase.utils';
+import type { CommandContext } from './commandContext';
+
+export interface ExplainBranchCommandArgs {
+	repoPath?: string | Uri;
+	ref?: string;
+	source?: AIExplainSource;
+}
+
+@command()
+export class ExplainBranchCommand extends GlCommandBase {
+	constructor(private readonly container: Container) {
+		super('gitlens.ai.explainBranch');
+	}
+
+	protected override preExecute(context: CommandContext, args?: ExplainBranchCommandArgs): Promise<void> {
+		return this.execute(context.editor, context.uri, args);
+	}
+
+	async execute(editor?: TextEditor, uri?: Uri, args?: ExplainBranchCommandArgs): Promise<void> {
+		uri = getCommandUri(uri, editor);
+
+		const gitUri = uri != null ? await GitUri.fromUri(uri) : undefined;
+
+		const repository = await getBestRepositoryOrShowPicker(
+			gitUri,
+			editor,
+			'Explain Branch',
+			'Choose which repository to explain a branch from',
+		);
+		if (repository == null) return;
+
+		args = { ...args };
+
+		try {
+			// If no ref is provided, show a picker to select a branch
+			if (args.ref == null) {
+				const pick = await showReferencePicker(
+					repository.path,
+					'Explain Branch',
+					'Choose a branch to explain',
+					{
+						include: ReferencesQuickPickIncludes.Branches,
+						sort: { branches: { current: true } },
+					},
+				);
+				if (pick?.ref == null) return;
+				args.ref = pick.ref;
+			}
+
+			// Get the branch
+			const branch = await repository.git.branches().getBranch(args.ref);
+			if (branch == null) {
+				void showGenericErrorMessage('Unable to find the specified branch');
+				return;
+			}
+
+			// Get the diff between the branch and its upstream or base
+			const diffService = repository.git.diff();
+			if (diffService?.getDiff === undefined) {
+				void showGenericErrorMessage('Unable to get diff service');
+				return;
+			}
+
+			const diff = await diffService.getDiff(branch.ref);
+			if (!diff?.contents) {
+				void showGenericErrorMessage('No changes found to explain');
+				return;
+			}
+
+			// Call the AI service to explain the changes
+			const result = await this.container.ai.explainChanges(
+				{
+					diff: diff.contents,
+					message: `Changes in branch ${branch.name}`,
+				},
+				args.source ?? { source: 'commandPalette', type: 'commit' },
+				{
+					progress: { location: ProgressLocation.Notification, title: 'Explaining branch changes...' },
+				},
+			);
+
+			// Display the result
+			let content = `# Branch: ${branch.name}\n`;
+			if (result != null) {
+				content += `> Generated by ${result.model.name}\n\n----\n\n${result?.parsed.summary}\n\n${result?.parsed.body}`;
+			} else {
+				content += `> No changes found to explain.`;
+			}
+			void showMarkdownPreview(content);
+		} catch (ex) {
+			Logger.error(ex, 'ExplainBranchCommand', 'execute');
+			void showGenericErrorMessage('Unable to explain branch');
+		}
+	}
+}
+
+export interface ExplainBranchCommandArgs2 {
+	repoPath: string;
+	branch: string;
+	source?: Source;
+}
+
+@command()
+export class ExplainBranchCommand2 extends GlCommandBase {
+	constructor(private readonly container: Container) {
+		super('gitlens.ai.explainBranch');
+	}
+
+	async execute(args?: ExplainBranchCommandArgs2): Promise<void> {
+		let repo;
+		if (args?.repoPath != null) {
+			repo = this.container.git.getRepository(args.repoPath);
+		}
+		repo ??= await getRepositoryOrShowPicker(
+			'Explain Branch',
+			'Choose which repository to explain a branch from',
+			undefined,
+		);
+		if (repo == null) return;
+
+		try {
+			// If no ref is provided, show a picker to select a branch
+			if (args == null) {
+				const pick = await showReferencePicker(repo.path, 'Explain Branch', 'Choose a branch to explain', {
+					include: ReferencesQuickPickIncludes.Branches,
+					sort: { branches: { current: true } },
+				});
+				if (pick?.ref == null) return;
+
+				args = {
+					repoPath: repo.path,
+					branch: pick.ref,
+				};
+			}
+
+			// Get the branch
+			const branch = await repo.git.branches().getBranch(args.branch);
+			if (branch == null) {
+				void showGenericErrorMessage('Unable to find the specified branch');
+				return;
+			}
+			const headRef = branch.ref;
+			const baseRef = branch.upstream?.name;
+
+			// Get the diff between the branch and its upstream or base
+			const [diffResult, logResult] = await Promise.allSettled([
+				repo.git.diff().getDiff?.(headRef, baseRef, { notation: '...' }),
+				repo.git.commits().getLog(`${baseRef}..${headRef}`),
+			]);
+
+			const diff = getSettledValue(diffResult);
+			const log = getSettledValue(logResult);
+
+			if (!diff?.contents || !log?.commits?.size) {
+				void showGenericErrorMessage('No changes found to explain');
+			}
+		} catch (ex) {
+			Logger.error(ex, 'ExplainBranchCommand', 'execute');
+			void showGenericErrorMessage('Unable to explain branch');
+		}
+	}
+}
+
+// export interface ExplainBranchCommandArgs {
+// 	repoPath: string;
+// 	branch: GitBranchReference;
+// 	source?: Source;
+// }
+
+// @command()
+// export class ExplainBranchCommand extends GlCommandBase {
+// 	constructor(private readonly container: Container) {
+// 		super('gitlens.ai.explainBranch');
+// 	}
+
+// 	async execute(args?: ExplainBranchCommandArgs): Promise<void> {
+// 		try {
+// 			const comparisonResult = await showComparisonPicker(this.container, args?.repoPath, {
+// 				head: args?.branch,
+// 				getTitleAndPlaceholder: step => {
+// 					switch (step) {
+// 						case 1:
+// 							return {
+// 								title: 'Explain Branch',
+// 								placeholder: 'Choose a branch to explain',
+// 							};
+// 						case 2:
+// 							return {
+// 								title: `Explain Branch \u2022 Select Base to Start From`,
+// 								placeholder: 'Choose a base branch to explain from',
+// 							};
+// 					}
+// 				},
+// 			});
+// 			if (comparisonResult == null) return;
+
+// 			const repo = this.container.git.getRepository(comparisonResult.repoPath);
+// 			if (repo == null) return;
+
+// 			const mergeBase = await repo.git.refs().getMergeBase(comparisonResult.head.ref, comparisonResult.base.ref);
+
+// 			const [diffResult, logResult] = await Promise.allSettled([
+// 				repo.git.diff().getDiff?.(comparisonResult.head.ref, mergeBase, { notation: '...' }),
+// 				repo.git.commits().getLog(`${mergeBase}..${comparisonResult.head.ref}`),
+// 			]);
+
+// 			const diff = getSettledValue(diffResult);
+// 			const log = getSettledValue(logResult);
+
+// 			if (!diff?.contents || !log?.commits?.size) {
+// 				void showGenericErrorMessage('No changes found to explain');
+// 				return;
+// 			}
+
+// 			const commitMessages: string[] = [];
+// 			for (const commit of [...log.commits.values()].sort((a, b) => a.date.getTime() - b.date.getTime())) {
+// 				commitMessages.push(commit.message ?? commit.summary);
+// 			}
+
+// 			const result = await this.container.ai.explainChanges(
+// 				{
+// 					diff: diff.contents,
+// 					message: commitMessages.join('\n\n'),
+// 				},
+// 				{
+// 					source: 'commandPalette',
+// 					...args?.source,
+// 					type: 'branch',
+// 				},
+// 				{
+// 					progress: { location: ProgressLocation.Notification, title: 'Explaining branch changes...' },
+// 				},
+// 			);
+
+// 			// Display the result
+// 			let content = `# Branch: ${comparisonResult.head.name}\n`;
+// 			if (result != null) {
+// 				content += `> Generated by ${result.model.name}\n\n----\n\n${result?.parsed.summary}\n\n${result?.parsed.body}`;
+// 			} else {
+// 				content += `> No changes found to explain.`;
+// 			}
+// 			void showMarkdownPreview(content);
+// 		} catch (ex) {
+// 			Logger.error(ex, 'ExplainBranchCommand', 'execute');
+// 			void showGenericErrorMessage('Unable to explain branch');
+// 		}
+// 	}
+// }

src/constants.commands.generated.ts

@@ -614,6 +614,7 @@ export type ContributedCommands =
 
 export type ContributedPaletteCommands =
 	| 'gitlens.addAuthors'
+	| 'gitlens.ai.explainBranch'
 	| 'gitlens.ai.explainCommit'
 	| 'gitlens.ai.explainStash'
 	| 'gitlens.ai.explainWip'

src/constants.telemetry.ts

@@ -336,7 +336,7 @@ interface AIEventDataBase {
 
 interface AIExplainEvent extends AIEventDataBase {
 	type: 'change';
-	changeType: 'wip' | 'stash' | 'commit' | `draft-${'patch' | 'stash' | 'suggested_pr_change'}`;
+	changeType: 'wip' | 'stash' | 'commit' | 'branch' | `draft-${'patch' | 'stash' | 'suggested_pr_change'}`;
 }
 
 export interface AIGenerateCommitEventData extends AIEventDataBase {