Adds regenerate command for explain summaries (wip)

d13 · d13 · commit 432475f74e54 · 2025-06-03T17:45:06.000-04:00
diff --git a/contributions.json b/contributions.json
@@ -3672,6 +3672,26 @@
 				]
 			}
 		},
+		"gitlens.regenerateMarkdownDocument": {
+			"label": "Regenerate",
+			"icon": "$(refresh)",
+			"menus": {
+				"editor/title": [
+					{
+						"when": "resourceScheme == gitlens-markdown && activeCustomEditorId == vscode.markdown.preview.editor",
+						"group": "navigation",
+						"order": 0
+					}
+				],
+				"editor/title/context": [
+					{
+						"when": "resourceScheme == gitlens-markdown && activeCustomEditorId == vscode.markdown.preview.editor",
+						"group": "1_gitlens",
+						"order": 0
+					}
+				]
+			}
+		},
 		"gitlens.reset": {
 			"label": "Reset Stored Data...",
 			"commandPalette": true
diff --git a/docs/telemetry-events.md b/docs/telemetry-events.md
diff --git a/package.json b/package.json
@@ -7554,6 +7554,11 @@
 				"title": "Quick Open File History",
 				"category": "GitLens"
 			},
+			{
+				"command": "gitlens.regenerateMarkdownDocument",
+				"title": "Regenerate",
+				"icon": "$(refresh)"
+			},
 			{
 				"command": "gitlens.reset",
 				"title": "Reset Stored Data...",
@@ -11771,6 +11776,10 @@
 					"command": "gitlens.quickOpenFileHistory",
 					"when": "resource in gitlens:tabs:tracked"
 				},
+				{
+					"command": "gitlens.regenerateMarkdownDocument",
+					"when": "false"
+				},
 				{
 					"command": "gitlens.revealCommitInView",
 					"when": "resource in gitlens:tabs:blameable"
@@ -14110,6 +14119,11 @@
 					"when": "resourceScheme =~ /^(gitlens|pr)$/ && gitlens:enabled && isInDiffEditor",
 					"group": "navigation@-97"
 				},
+				{
+					"command": "gitlens.regenerateMarkdownDocument",
+					"when": "resourceScheme == gitlens-markdown && activeCustomEditorId == vscode.markdown.preview.editor",
+					"group": "navigation@0"
+				},
 				{
 					"command": "gitlens.openPatch",
 					"when": "false && editorLangId == diff"
@@ -14131,6 +14145,11 @@
 					"when": "resourceScheme == gitlens && resourceScheme in gitlens:schemes:trackable",
 					"group": "2_a_gitlens@0"
 				},
+				{
+					"command": "gitlens.regenerateMarkdownDocument",
+					"when": "resourceScheme == gitlens-markdown && activeCustomEditorId == vscode.markdown.preview.editor",
+					"group": "1_gitlens@0"
+				},
 				{
 					"command": "gitlens.copyRemoteFileUrlWithoutRange",
 					"when": "resourceScheme in gitlens:schemes:trackable && gitlens:enabled && gitlens:repos:withRemotes && config.gitlens.menus.editorTab.clipboard",
diff --git a/src/commands.ts b/src/commands.ts
@@ -53,6 +53,7 @@ import './commands/patches';
 import './commands/quickWizard';
 import './commands/rebaseEditor';
 import './commands/refreshHover';
+import './commands/regenerateMarkdownDocument';
 import './commands/remoteProviders';
 import './commands/repositories';
 import './commands/resets';
diff --git a/src/commands/explainBranch.ts b/src/commands/explainBranch.ts
@@ -1,6 +1,7 @@
 import type { TextEditor, Uri } from 'vscode';
 import { ProgressLocation } from 'vscode';
 import type { Container } from '../container';
+import type { MarkdownContentMetadata } from '../documents/markdown';
 import { GitUri } from '../git/gitUri';
 import type { GitBranchReference } from '../git/models/reference';
 import { getBranchMergeTargetName } from '../git/utils/-webview/branch.utils';
@@ -139,7 +140,27 @@ export class ExplainBranchCommand extends GlCommandBase {
 
 			const content = `# Branch Summary\n\n> Generated by ${result.model.name}\n\n## ${branch.name}\n\n${result.parsed.summary}\n\n${result.parsed.body}`;
 
-			showMarkdownPreview(content);
+			const contentMetadata = {
+				header: {
+					title: 'Branch Summary',
+					subtitle: branch.name,
+					aiModel: result.model.name,
+				},
+				command: {
+					label: 'Explain Branch Changes',
+					name: 'gitlens.ai.explainBranch',
+					args: { repoPath: repository.path, ref: branch.ref, source: args.source },
+				},
+			};
+
+			const documentUri = this.container.markdown.openDocument(
+				content,
+				`/explain/branch/${branch.ref}/${result.model.id}`,
+				branch.name,
+				contentMetadata as MarkdownContentMetadata,
+			);
+
+			showMarkdownPreview(documentUri);
 		} catch (ex) {
 			Logger.error(ex, 'ExplainBranchCommand', 'execute');
 			void showGenericErrorMessage('Unable to explain branch');
diff --git a/src/commands/explainStash.ts b/src/commands/explainStash.ts
@@ -1,6 +1,7 @@
 import type { TextEditor, Uri } from 'vscode';
 import { ProgressLocation } from 'vscode';
 import type { Container } from '../container';
+import type { MarkdownContentMetadata } from '../documents/markdown';
 import { GitUri } from '../git/gitUri';
 import type { GitCommit, GitStashCommit } from '../git/models/commit';
 import { showGenericErrorMessage } from '../messages';
@@ -101,8 +102,27 @@ export class ExplainStashCommand extends GlCommandBase {
 				commit.message || commit.ref
 			}\n\n${result.parsed.summary}\n\n${result.parsed.body}`;
 
-			// showMarkdownPreview(this.container, content, { filename: `stash-${commit.ref}` });
-			showMarkdownPreview(content);
+			const contentMetadata = {
+				header: {
+					title: 'Stash Summary',
+					subtitle: commit.message || commit.ref,
+					aiModel: result.model.name,
+				},
+				command: {
+					label: 'Explain Stash Changes',
+					name: 'gitlens.ai.explainStash',
+					args: { repoPath: repository.path, ref: commit.ref, source: args.source },
+				},
+			};
+
+			const documentUri = this.container.markdown.openDocument(
+				content,
+				`/explain/stash/${commit.ref}/${result.model.id}`,
+				commit.message || commit.ref,
+				contentMetadata as MarkdownContentMetadata,
+			);
+
+			showMarkdownPreview(documentUri);
 		} catch (ex) {
 			Logger.error(ex, 'ExplainStashCommand', 'execute');
 			void showGenericErrorMessage('Unable to explain stash');
diff --git a/src/commands/explainWip.ts b/src/commands/explainWip.ts
@@ -1,6 +1,7 @@
 import type { TextEditor, Uri } from 'vscode';
 import { ProgressLocation } from 'vscode';
 import type { Container } from '../container';
+import type { MarkdownContentMetadata } from '../documents/markdown';
 import type { GitRepositoryService } from '../git/gitRepositoryService';
 import { GitUri } from '../git/gitUri';
 import { uncommitted, uncommittedStaged } from '../git/models/revision';
@@ -67,6 +68,8 @@ export class ExplainWipCommand extends GlCommandBase {
 			return;
 		}
 
+		args.repoPath ??= svc.path;
+
 		try {
 			let label;
 			let to;
@@ -130,9 +133,30 @@ export class ExplainWipCommand extends GlCommandBase {
 			}
 
 			const title = `${capitalize(label)} Changes Summary${worktreeDisplayName}`;
-			const content = `# ${title}\n\n> Generated by ${result.model.name}\n\n## ${label} Changes\n\n${result.parsed.summary}\n\n${result.parsed.body}`;
+			const subtitle = `${capitalize(label)} Changes`;
+			const content = `# ${title}\n\n> Generated by ${result.model.name}\n\n## ${subtitle}\n\n${result.parsed.summary}\n\n${result.parsed.body}`;
+
+			const contentMetadata = {
+				header: {
+					title: title,
+					subtitle: subtitle,
+					aiModel: result.model.name,
+				},
+				command: {
+					label: 'Explain Working Changes',
+					name: 'gitlens.ai.explainWip',
+					args: args,
+				},
+			};
+
+			const documentUri = this.container.markdown.openDocument(
+				content,
+				`/explain/wip/${result.model.id}`,
+				subtitle,
+				contentMetadata as MarkdownContentMetadata,
+			);
 
-			showMarkdownPreview(content);
+			showMarkdownPreview(documentUri);
 		} catch (ex) {
 			Logger.error(ex, 'ExplainWipCommand', 'execute');
 			void showGenericErrorMessage('Unable to explain working changes');
diff --git a/src/commands/regenerateMarkdownDocument.ts b/src/commands/regenerateMarkdownDocument.ts
@@ -0,0 +1,51 @@
+import type { TextEditor, Uri } from 'vscode';
+import { window } from 'vscode';
+import { Schemes } from '../constants';
+import type { MarkdownContentMetadata } from '../documents/markdown';
+import { decodeGitLensRevisionUriAuthority } from '../git/gitUri.authority';
+import { command, executeCommand } from '../system/-webview/command';
+import { Logger } from '../system/logger';
+import { ActiveEditorCommand } from './commandBase';
+import { getCommandUri } from './commandBase.utils';
+
+@command()
+export class RegenerateMarkdownDocumentCommand extends ActiveEditorCommand {
+	constructor() {
+		super('gitlens.regenerateMarkdownDocument');
+	}
+
+	async execute(editor?: TextEditor, uri?: Uri): Promise<void> {
+		uri = getCommandUri(uri, editor);
+		if (uri == null) return;
+
+		// Only work with gitlens-markdown scheme documents
+		if (uri.scheme !== Schemes.GitLensMarkdown) {
+			void window.showErrorMessage('This action can only be used on GitLens markdown documents.');
+			return;
+		}
+
+		// Extract the command from the authority
+		const authority = uri.authority;
+		if (authority == null || authority.length === 0) {
+			void window.showErrorMessage('No regeneration command found for this document.');
+			return;
+		}
+
+		try {
+			const metadata = decodeGitLensRevisionUriAuthority<MarkdownContentMetadata>(authority);
+
+			if (metadata.command == null) {
+				void window.showErrorMessage('No regeneration command found for this document.');
+				return;
+			}
+
+			// Execute the command that was encoded in the authority
+			// The openDocument method in the regeneration command will automatically
+			// detect content changes and fire the _onDidChange event to refresh the preview
+			await executeCommand(metadata.command.name, metadata.command.args);
+		} catch (ex) {
+			Logger.error(ex, 'RegenerateMarkdownDocumentCommand');
+			void window.showErrorMessage('Failed to regenerate document. See output for more details.');
+		}
+	}
+}
diff --git a/src/constants.commands.generated.ts b/src/constants.commands.generated.ts
@@ -151,6 +151,7 @@ export type ContributedCommands =
 	| 'gitlens.openFolderHistory'
 	| 'gitlens.openPullRequestOnRemote'
 	| 'gitlens.plus.cloudIntegrations.connect'
+	| 'gitlens.regenerateMarkdownDocument'
 	| 'gitlens.showInCommitGraph'
 	| 'gitlens.showInCommitGraphView'
 	| 'gitlens.showInDetailsView'
diff --git a/src/constants.commands.ts b/src/constants.commands.ts
@@ -127,6 +127,7 @@ type InternalGlCommands =
 	| 'gitlens.openOnRemote'
 	| 'gitlens.openWalkthrough'
 	| 'gitlens.refreshHover'
+	| 'gitlens.regenerateMarkdownDocument'
 	| 'gitlens.visualizeHistory'
 	| InternalGraphWebviewCommands
 	| InternalHomeWebviewCommands
diff --git a/src/documents/markdown.ts b/src/documents/markdown.ts
@@ -3,7 +3,6 @@ import { EventEmitter, Uri, workspace } from 'vscode';
 import { Schemes } from '../constants';
 import type { GlCommands } from '../constants.commands';
 import { decodeGitLensRevisionUriAuthority, encodeGitLensRevisionUriAuthority } from '../git/gitUri.authority';
-import { createMarkdownCommandLink } from '../system/commands';
 
 // gitlens-markdown:{explain}/{entity}/{entityID}/{model}[{/friendlyName}].md
 
@@ -49,14 +48,26 @@ export class MarkdownContentProvider implements TextDocumentContentProvider {
 		return `# ${uri.path}\n\nNo content available.`;
 	}
 
-	openDocument(content: string, path: string, label: string, metadata?: Record<string, unknown>): Uri {
+	openDocument(content: string, path: string, label: string, metadata?: MarkdownContentMetadata): Uri {
 		const uri = Uri.from({
 			scheme: Schemes.GitLensMarkdown,
 			authority: metadata ? encodeGitLensRevisionUriAuthority(metadata) : undefined,
 			path: `${path}.md`,
 			query: JSON.stringify({ label: label }),
 		});
-		this.contents.set(uri.toString(), content);
+
+		const uriString = uri.toString();
+		const existingContent = this.contents.get(uriString);
+		const contentChanged = existingContent !== content;
+
+		this.contents.set(uriString, content);
+
+		// If this document already exists and the content changed, fire the change event
+		// This will automatically refresh any open previews
+		if (contentChanged) {
+			this._onDidChange.fire(uri);
+		}
+
 		return uri;
 	}
 
@@ -95,10 +106,7 @@ function getContentFromMarkdownUri(uri: Uri): string | undefined {
 
 	if (metadata.command == null) return `${headerContent}\n\nNo content available.`;
 
-	const commandContent = `\n\n\n\n[${metadata.command.label}](${createMarkdownCommandLink(
-		metadata.command.name,
-		metadata.command.args,
-	)})`;
+	const commandContent = `\n\n\n\n${metadata.command.label} using the \`Regenerate\` editor action in the editor toolbar.`;
 
 	return `${headerContent}\n\n${commandContent}`;
 }
diff --git a/src/system/-webview/markdown.ts b/src/system/-webview/markdown.ts
@@ -1,5 +1,6 @@
 import type { TextDocumentShowOptions, Uri } from 'vscode';
 import type { Container } from '../../container';
+import type { MarkdownContentMetadata } from '../../documents/markdown';
 import { Logger } from '../logger';
 import { executeCoreCommand } from './command';
 
@@ -17,6 +18,12 @@ export function showMarkdownPreview(
 	}
 }
 
-export function createGLMarkdownDocument(container: Container, content: string, path: string, label: string): Uri {
-	return container.markdown.openDocument(content, path, label);
+export function createGLMarkdownDocument(
+	container: Container,
+	content: string,
+	path: string,
+	label: string,
+	metadata?: MarkdownContentMetadata,
+): Uri {
+	return container.markdown.openDocument(content, path, label, metadata);
 }
