Adds support for going to next/previous change in Changes annotation (wip)

Fixes missing disposal of heatmap decorations
Cleans up file annotations code

Author: eamodio

package.json

@@ -5555,6 +5555,16 @@
 					"light": "images/light/icon-git.svg"
 				}
 			},
+			{
+				"command": "gitlens.annotations.nextChange",
+				"title": "Next Change",
+				"icon": "$(arrow-down)"
+			},
+			{
+				"command": "gitlens.annotations.previousChange",
+				"title": "Previous Change",
+				"icon": "$(arrow-up)"
+			},
 			{
 				"command": "gitlens.clearFileAnnotations",
 				"title": "Clear File Annotations",
@@ -8993,9 +9003,17 @@
 					"command": "gitlens.toggleFileBlameInDiffRight",
 					"when": "false"
 				},
+				{
+					"command": "gitlens.annotations.nextChange",
+					"when": "false"
+				},
+				{
+					"command": "gitlens.annotations.previousChange",
+					"when": "false"
+				},
 				{
 					"command": "gitlens.clearFileAnnotations",
-					"when": "gitlens:activeFileStatus =~ /blameable/ && gitlens:annotationStatus == computed"
+					"when": "gitlens:activeFileStatus =~ /blameable/ && gitlens:annotationStatus =~ /computed\\b/"
 				},
 				{
 					"command": "gitlens.computingFileAnnotations",
@@ -11105,12 +11123,12 @@
 				},
 				{
 					"command": "gitlens.computingFileAnnotations",
-					"when": "gitlens:activeFileStatus =~ /blameable/ && gitlens:annotationStatus == computing && config.gitlens.menus.editorGroup.blame",
+					"when": "gitlens:activeFileStatus =~ /blameable/ && gitlens:annotationStatus =~ /computing\\b/ && config.gitlens.menus.editorGroup.blame",
 					"group": "navigation@100"
 				},
 				{
 					"command": "gitlens.clearFileAnnotations",
-					"when": "gitlens:activeFileStatus =~ /blameable/ && gitlens:annotationStatus == computed && config.gitlens.menus.editorGroup.blame",
+					"when": "gitlens:activeFileStatus =~ /blameable/ && gitlens:annotationStatus =~ /computed\\b/ && config.gitlens.menus.editorGroup.blame",
 					"group": "navigation@100"
 				},
 				{

src/annotations/annotationProvider.ts

@@ -1,18 +1,12 @@
-import type {
-	DecorationOptions,
-	Range,
-	TextDocument,
-	TextEditor,
-	TextEditorDecorationType,
-	TextEditorSelectionChangeEvent,
-	Uri,
-} from 'vscode';
+import type { TextEditor, TextEditorDecorationType, TextEditorSelectionChangeEvent } from 'vscode';
 import { Disposable, window } from 'vscode';
 import type { FileAnnotationType } from '../config';
+import type { Container } from '../container';
 import { setContext } from '../system/context';
 import { Logger } from '../system/logger';
 import type { GitDocumentState } from '../trackers/gitDocumentTracker';
 import type { TrackedDocument } from '../trackers/trackedDocument';
+import type { Decoration } from './annotations';
 
 export type AnnotationStatus = 'computing' | 'computed';
 
@@ -28,23 +22,16 @@ export function getEditorCorrelationKey(editor: TextEditor | undefined): TextEdi
 export abstract class AnnotationProviderBase<TContext extends AnnotationContext = AnnotationContext>
 	implements Disposable
 {
-	annotationContext: TContext | undefined;
-	correlationKey: TextEditorCorrelationKey;
-	document: TextDocument;
-	status: AnnotationStatus | undefined;
-
-	private decorations:
-		| { decorationType: TextEditorDecorationType; rangesOrOptions: Range[] | DecorationOptions[] }[]
-		| undefined;
+	private decorations: Decoration[] | undefined;
 	protected disposable: Disposable;
 
 	constructor(
+		protected readonly container: Container,
 		public readonly annotationType: FileAnnotationType,
-		public editor: TextEditor,
+		editor: TextEditor,
 		protected readonly trackedDocument: TrackedDocument<GitDocumentState>,
 	) {
-		this.correlationKey = getEditorCorrelationKey(this.editor);
-		this.document = this.editor.document;
+		this.editor = editor;
 
 		this.disposable = Disposable.from(
 			window.onDidChangeTextEditorSelection(this.onTextEditorSelectionChanged, this),
@@ -57,36 +44,98 @@ export abstract class AnnotationProviderBase<TContext extends AnnotationContext
 		this.disposable.dispose();
 	}
 
+	private _annotationContext: TContext | undefined;
+	get annotationContext(): TContext | undefined {
+		return this._annotationContext;
+	}
+	protected set annotationContext(value: TContext | undefined) {
+		this._annotationContext = value;
+	}
+
+	private _correlationKey!: TextEditorCorrelationKey;
+	get correlationKey(): TextEditorCorrelationKey {
+		return this._correlationKey;
+	}
+
+	private _editor!: TextEditor;
+	get editor(): TextEditor {
+		return this._editor;
+	}
+	protected set editor(value: TextEditor) {
+		this._editor = value;
+		this._correlationKey = getEditorCorrelationKey(value);
+	}
+
+	private _status: AnnotationStatus | undefined;
+	get status(): AnnotationStatus | undefined {
+		return this._status;
+	}
+
+	get statusContextValue(): string | undefined {
+		return this.status != null ? `${this.status}+${this.annotationType}` : undefined;
+	}
+
+	private async setStatus(value: AnnotationStatus | undefined, editor: TextEditor | undefined): Promise<void> {
+		if (this.status === value) return;
+
+		this._status = value;
+		if (editor != null && editor === window.activeTextEditor) {
+			await setContext('gitlens:annotationStatus', this.statusContextValue);
+		}
+	}
+
 	private onTextEditorSelectionChanged(e: TextEditorSelectionChangeEvent) {
-		if (this.document !== e.textEditor.document) return;
+		if (this.editor.document !== e.textEditor.document) return;
 
-		void this.selection({ line: e.selections[0].active.line });
+		void this.selection?.({ line: e.selections[0].active.line });
 	}
 
-	get editorUri(): Uri | undefined {
-		return this.editor?.document?.uri;
+	canReuse(_context?: TContext): boolean {
+		return true;
 	}
 
 	clear() {
+		const decorations = this.decorations;
+		this.decorations = undefined;
 		this.annotationContext = undefined;
-		this.status = undefined;
+		void this.setStatus(undefined, this.editor);
+
 		if (this.editor == null) return;
 
-		if (this.decorations?.length) {
-			for (const d of this.decorations) {
+		if (decorations?.length) {
+			for (const d of decorations) {
 				try {
 					this.editor.setDecorations(d.decorationType, []);
+					if (d.dispose) {
+						d.decorationType.dispose();
+					}
 				} catch {}
 			}
-
-			this.decorations = undefined;
 		}
 	}
 
-	mustReopen(_context?: TContext): boolean {
+	nextChange?(): void;
+	previousChange?(): void;
+
+	async provideAnnotation(context?: TContext, force?: boolean): Promise<boolean> {
+		void this.setStatus('computing', this.editor);
+
+		try {
+			if (await this.onProvideAnnotation(context, force)) {
+				void this.setStatus('computed', this.editor);
+				await this.selection?.(force ? { line: this.editor.selection.active.line } : context?.selection);
+				return true;
+			}
+		} catch (ex) {
+			Logger.error(ex);
+		}
+
+		void this.setStatus(undefined, this.editor);
 		return false;
 	}
 
+	protected abstract onProvideAnnotation(context?: TContext, force?: boolean): Promise<boolean>;
+
 	refresh(replaceDecorationTypes: Map<TextEditorDecorationType, TextEditorDecorationType | null>) {
 		if (this.editor == null || !this.decorations?.length) return;
 
@@ -106,65 +155,60 @@ export abstract class AnnotationProviderBase<TContext extends AnnotationContext
 		this.setDecorations(this.decorations);
 	}
 
-	async restore(editor: TextEditor) {
+	restore(editor: TextEditor, force?: boolean) {
 		// If the editor isn't disposed then we don't need to do anything
 		// Explicitly check for `false`
 		if ((this.editor as any)._disposed === false) return;
 
-		this.status = 'computing';
-		if (editor === window.activeTextEditor) {
-			await setContext('gitlens:annotationStatus', this.status);
+		if (force || this.decorations == null) {
+			void this.provideAnnotation(this.annotationContext, force);
+			return;
 		}
 
+		void this.setStatus('computing', this.editor);
+
 		this.editor = editor;
-		this.correlationKey = getEditorCorrelationKey(editor);
-		this.document = editor.document;
 
 		if (this.decorations?.length) {
 			for (const d of this.decorations) {
 				this.editor.setDecorations(d.decorationType, d.rangesOrOptions);
 			}
 		}
 
-		this.status = 'computed';
-		if (editor === window.activeTextEditor) {
-			await setContext('gitlens:annotationStatus', this.status);
-		}
+		void this.setStatus('computed', this.editor);
 	}
 
-	async provideAnnotation(context?: TContext): Promise<boolean> {
-		this.status = 'computing';
-		try {
-			if (await this.onProvideAnnotation(context)) {
-				this.status = 'computed';
-				return true;
-			}
-		} catch (ex) {
-			Logger.error(ex);
-		}
-
-		this.status = undefined;
-		return false;
-	}
+	selection?(selection?: TContext['selection']): Promise<void>;
+	validate?(): boolean | Promise<boolean>;
 
-	protected abstract onProvideAnnotation(context?: TContext): Promise<boolean>;
+	protected setDecorations(decorations: Decoration[]) {
+		if (this.decorations?.length) {
+			// If we have no new decorations, just completely clear the old ones
+			if (!decorations?.length) {
+				this.clear();
 
-	abstract selection(selection?: TContext['selection']): Promise<void>;
+				return;
+			}
 
-	protected setDecorations(
-		decorations: { decorationType: TextEditorDecorationType; rangesOrOptions: Range[] | DecorationOptions[] }[],
-	) {
-		if (this.decorations?.length) {
-			this.clear();
+			// Only remove the decorations that are no longer needed
+			const remove = this.decorations.filter(
+				decoration => !decorations.some(d => d.decorationType.key === decoration.decorationType.key),
+			);
+			for (const d of remove) {
+				try {
+					this.editor.setDecorations(d.decorationType, []);
+					if (d.dispose) {
+						d.decorationType.dispose();
+					}
+				} catch {}
+			}
 		}
 
 		this.decorations = decorations;
-		if (this.decorations?.length) {
-			for (const d of this.decorations) {
+		if (decorations?.length) {
+			for (const d of decorations) {
 				this.editor.setDecorations(d.decorationType, d.rangesOrOptions);
 			}
 		}
 	}
-
-	abstract validate(): Promise<boolean>;
 }

src/annotations/annotations.ts

@@ -24,6 +24,12 @@ export interface ComputedHeatmap {
 	computeOpacity(date: Date): number;
 }
 
+export type Decoration<T extends Range[] | DecorationOptions[] = Range[] | DecorationOptions[]> = {
+	decorationType: TextEditorDecorationType;
+	rangesOrOptions: T;
+	dispose?: boolean;
+};
+
 interface RenderOptions
 	extends DecorationInstanceRenderOptions,
 		ThemableDecorationRenderOptions,
@@ -93,7 +99,7 @@ export function addOrUpdateGutterHeatmapDecoration(
 	date: Date,
 	heatmap: ComputedHeatmap,
 	range: Range,
-	map: Map<string, { decorationType: TextEditorDecorationType; rangesOrOptions: Range[] }>,
+	map: Map<string, Decoration<Range[]>>,
 ) {
 	const [r, g, b, a] = getHeatmapColor(date, heatmap);
 
@@ -122,6 +128,7 @@ export function addOrUpdateGutterHeatmapDecoration(
 				overviewRulerColor: scrollbar ? `rgba(${r},${g},${b},${a * 0.7})` : undefined,
 			}),
 			rangesOrOptions: [range],
+			dispose: true,
 		};
 		map.set(key, colorDecoration);
 	} else {

src/annotations/blameAnnotationProvider.ts

@@ -21,14 +21,14 @@ export abstract class BlameAnnotationProviderBase extends AnnotationProviderBase
 	protected hoverProviderDisposable: Disposable | undefined;
 
 	constructor(
+		container: Container,
 		annotationType: FileAnnotationType,
 		editor: TextEditor,
 		trackedDocument: TrackedDocument<GitDocumentState>,
-		protected readonly container: Container,
 	) {
-		super(annotationType, editor, trackedDocument);
+		super(container, annotationType, editor, trackedDocument);
 
-		this.blame = this.container.git.getBlame(this.trackedDocument.uri, editor.document);
+		this.blame = container.git.getBlame(this.trackedDocument.uri, editor.document);
 
 		if (editor.document.isDirty) {
 			trackedDocument.setForceDirtyStateChangeOnNextDocumentChange();
@@ -43,14 +43,17 @@ export abstract class BlameAnnotationProviderBase extends AnnotationProviderBase
 		super.clear();
 	}
 
-	async validate(): Promise<boolean> {
+	override async validate(): Promise<boolean> {
 		const blame = await this.blame;
-		return blame != null && blame.lines.length !== 0;
+		return Boolean(blame?.lines.length);
 	}
 
-	protected async getBlame(): Promise<GitBlame | undefined> {
+	protected async getBlame(force?: boolean): Promise<GitBlame | undefined> {
+		if (force) {
+			this.blame = this.container.git.getBlame(this.trackedDocument.uri, this.editor.document);
+		}
 		const blame = await this.blame;
-		if (blame == null || blame.lines.length === 0) return undefined;
+		if (!blame?.lines.length) return undefined;
 
 		return blame;
 	}
@@ -142,8 +145,9 @@ export abstract class BlameAnnotationProviderBase extends AnnotationProviderBase
 			return;
 		}
 
+		this.hoverProviderDisposable?.dispose();
 		this.hoverProviderDisposable = languages.registerHoverProvider(
-			{ pattern: this.document.uri.fsPath },
+			{ pattern: this.editor.document.uri.fsPath },
 			{
 				provideHover: (document: TextDocument, position: Position, token: CancellationToken) =>
 					this.provideHover(providers, document, position, token),
@@ -159,7 +163,7 @@ export abstract class BlameAnnotationProviderBase extends AnnotationProviderBase
 	): Promise<Hover | undefined> {
 		if (configuration.get('hovers.annotations.over') !== 'line' && position.character !== 0) return undefined;
 
-		if (this.document.uri.toString() !== document.uri.toString()) return undefined;
+		if (this.editor.document.uri.toString() !== document.uri.toString()) return undefined;
 
 		const blame = await this.getBlame();
 		if (blame == null) return undefined;