@theia/scm 1.75.0-next.8 → 1.75.0

package/src/browser/scm-history-graph-contribution.ts

@@ -0,0 +1,273 @@
+// *****************************************************************************
+// Copyright (C) 2026 Safi Seid-Ahmad, K2view and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { injectable, inject, named, optional } from '@theia/core/shared/inversify';
+import { ILogger } from '@theia/core';
+import { Command, CommandContribution, CommandRegistry } from '@theia/core/lib/common/command';
+import { MenuContribution, MenuModelRegistry } from '@theia/core/lib/common/menu';
+import { nls } from '@theia/core/lib/common/nls';
+import { CancellationTokenSource } from '@theia/core/lib/common/cancellation';
+import { QuickInputService } from '@theia/core/lib/browser';
+import { QuickPickItem, QuickPickSeparator } from '@theia/core/lib/common/quick-pick-service';
+import { codicon } from '@theia/core/lib/browser/widgets/widget';
+import { ScmHistoryGraphModel, ScmHistoryGraphModelProvider } from './scm-history-graph-model';
+import { ScmService } from './scm-service';
+import { ScmContextKeyService } from './scm-context-key-service';
+import { ScmHistoryItemRef, ScmHistoryProvider } from './scm-provider';
+import { SCM_HISTORY_TITLE_MENU } from './scm-history-graph-widget';
+import { getRefBadgeClass } from './scm-history-graph-helpers';
+
+export namespace ScmHistoryGraphCommands {
+    export const REFRESH = Command.toDefaultLocalizedCommand({
+        id: 'scmHistoryGraph.refresh',
+        category: 'Source Control',
+        label: 'Refresh',
+        iconClass: codicon('refresh')
+    });
+    export const PICK_HISTORY_ITEM_REFS = Command.toLocalizedCommand({
+        id: 'scmHistoryGraph.pickHistoryItemRefs',
+        category: 'Source Control',
+        label: 'Pick History Item Reference...',
+        iconClass: codicon('git-branch')
+    }, 'theia/scm/pickHistoryItemRefs');
+    export const REVEAL_CURRENT_HISTORY_ITEM = Command.toDefaultLocalizedCommand({
+        id: 'scmHistoryGraph.revealCurrentHistoryItem',
+        category: 'Source Control',
+        label: 'Go to Current History Item',
+        iconClass: codicon('target')
+    });
+    export const SET_LIST_VIEW_MODE = Command.toDefaultLocalizedCommand({
+        id: 'scmHistoryGraph.setListViewMode',
+        category: 'Source Control',
+        label: 'View as List'
+    });
+    export const SET_TREE_VIEW_MODE = Command.toDefaultLocalizedCommand({
+        id: 'scmHistoryGraph.setTreeViewMode',
+        category: 'Source Control',
+        label: 'View as Tree'
+    });
+}
+
+type RefPickItem = QuickPickItem & { refId?: string; auto?: boolean };
+
+/**
+ * Contributes the native toolbar actions of the SCM history graph: the
+ * history item reference filter picker (VS Code's "Auto" dropdown) and the
+ * refresh action. Extension actions (e.g. fetch/pull/push from vscode.git)
+ * are contributed separately via the `scm/history/title` menu.
+ */
+@injectable()
+export class ScmHistoryGraphContribution implements CommandContribution, MenuContribution {
+
+    @inject(ScmService) protected readonly scmService: ScmService;
+    @inject(ScmHistoryGraphModelProvider) protected readonly modelProvider: ScmHistoryGraphModelProvider;
+    @inject(QuickInputService) @optional() protected readonly quickInputService: QuickInputService;
+    @inject(ILogger) @named('scm:ScmHistoryGraphContribution') protected readonly logger: ILogger;
+    @inject(ScmContextKeyService) protected readonly scmContextKeys: ScmContextKeyService;
+
+    /**
+     * The graph model, resolved lazily: instantiating it starts loading
+     * history, so it must only be resolved when a graph command actually
+     * runs or the graph toolbar renders (the widget has created the model
+     * by then). In particular, `isEnabled`/`isVisible` are also queried by
+     * the command palette and therefore consult the `ScmService` instead.
+     */
+    protected get model(): ScmHistoryGraphModel {
+        return this.modelProvider();
+    }
+
+    protected get historyProvider(): ScmHistoryProvider | undefined {
+        return this.scmService.selectedRepository?.provider.historyProvider;
+    }
+
+    registerCommands(commands: CommandRegistry): void {
+        commands.registerCommand(ScmHistoryGraphCommands.REFRESH, {
+            isEnabled: () => !!this.historyProvider,
+            isVisible: () => !!this.historyProvider,
+            execute: () => this.model.refresh()
+        });
+        commands.registerCommand(ScmHistoryGraphCommands.PICK_HISTORY_ITEM_REFS, {
+            isEnabled: () => !!this.historyProvider && !!this.quickInputService,
+            isVisible: () => !!this.historyProvider,
+            isToggled: () => !!this.model.historyItemRefFilter,
+            execute: () => this.pickHistoryItemRefs()
+        });
+        commands.registerCommand(ScmHistoryGraphCommands.REVEAL_CURRENT_HISTORY_ITEM, {
+            // There is nothing to reveal while the filter excludes the current ref,
+            // mirroring VS Code's precondition for this action.
+            isEnabled: () => !!this.historyProvider && this.scmContextKeys.scmCurrentHistoryItemRefInFilter.get() === true,
+            isVisible: () => !!this.historyProvider,
+            execute: () => this.model.revealCurrentHistoryItem()
+        });
+        commands.registerCommand(ScmHistoryGraphCommands.SET_LIST_VIEW_MODE, {
+            isEnabled: () => !!this.historyProvider,
+            isVisible: () => !!this.historyProvider,
+            isToggled: () => this.model.viewMode === 'list',
+            execute: () => this.model.setViewMode('list')
+        });
+        commands.registerCommand(ScmHistoryGraphCommands.SET_TREE_VIEW_MODE, {
+            isEnabled: () => !!this.historyProvider,
+            isVisible: () => !!this.historyProvider,
+            isToggled: () => this.model.viewMode === 'tree',
+            execute: () => this.model.setViewMode('tree')
+        });
+    }
+
+    registerMenus(menus: MenuModelRegistry): void {
+        // Extension actions from vscode.git sit at order 900-902; the picker
+        // goes before them and refresh last, matching VS Code's graph toolbar.
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, 'navigation'], {
+            commandId: ScmHistoryGraphCommands.PICK_HISTORY_ITEM_REFS.id,
+            order: '100'
+        });
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, 'navigation'], {
+            commandId: ScmHistoryGraphCommands.REVEAL_CURRENT_HISTORY_ITEM.id,
+            order: '200'
+        });
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, 'navigation'], {
+            commandId: ScmHistoryGraphCommands.REFRESH.id,
+            order: '999'
+        });
+        // Groups other than 'navigation' are rendered in the toolbar's overflow menu,
+        // which is where VS Code places the view mode toggles as well.
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, '9_viewmode'], {
+            commandId: ScmHistoryGraphCommands.SET_LIST_VIEW_MODE.id,
+            order: '1'
+        });
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, '9_viewmode'], {
+            commandId: ScmHistoryGraphCommands.SET_TREE_VIEW_MODE.id,
+            order: '2'
+        });
+    }
+
+    protected async pickHistoryItemRefs(): Promise<void> {
+        if (!this.quickInputService) {
+            return;
+        }
+        const model = this.model;
+        const provider = model.provider;
+        if (!provider) {
+            return;
+        }
+        const picker = this.quickInputService.createQuickPick<RefPickItem>();
+        const cts = new CancellationTokenSource();
+        try {
+            picker.placeholder = nls.localize('theia/scm/pickHistoryItemRefsPlaceholder', 'Select one or more history item references');
+            picker.canSelectMany = true;
+            picker.matchOnDescription = true;
+            // Show the picker right away and populate it once the refs arrive,
+            // so that a slow ref lookup surfaces as a busy picker instead of a
+            // command that appears to do nothing.
+            picker.busy = true;
+
+            const selection = await new Promise<readonly RefPickItem[] | undefined>(resolve => {
+                picker.onDidAccept(() => {
+                    resolve(picker.selectedItems);
+                    picker.hide();
+                });
+                // Also cancels a still-running ref lookup when the picker is dismissed.
+                picker.onDidHide(() => {
+                    cts.cancel();
+                    resolve(undefined);
+                });
+                picker.show();
+
+                provider.provideHistoryItemRefs(undefined, cts.token).then(refs => {
+                    if (cts.token.isCancellationRequested) {
+                        return;
+                    }
+                    const currentFilter = model.historyItemRefFilter;
+                    const items = this.createRefPickItems(refs ?? [], provider);
+                    picker.items = items;
+                    picker.selectedItems = items.filter((item): item is RefPickItem => !QuickPickSeparator.is(item)
+                        && (currentFilter ? !!item.refId && currentFilter.includes(item.refId) : item.auto === true));
+
+                    // "Auto" is exclusive: checking it unchecks everything else and vice versa
+                    let lastSelection: readonly RefPickItem[] = picker.selectedItems;
+                    picker.onDidChangeSelection(newSelection => {
+                        const autoNow = newSelection.some(item => item.auto);
+                        if (autoNow && newSelection.length > 1) {
+                            const autoBefore = lastSelection.some(item => item.auto);
+                            picker.selectedItems = autoBefore ? newSelection.filter(item => !item.auto) : newSelection.filter(item => item.auto);
+                        }
+                        lastSelection = picker.selectedItems;
+                    });
+                    picker.busy = false;
+                }, err => {
+                    if (!cts.token.isCancellationRequested) {
+                        this.logger.error('Failed to load history item refs', err);
+                    }
+                    picker.hide();
+                });
+            });
+
+            if (!selection) {
+                return;
+            }
+            // The selected repository may have changed while the picker was open;
+            // the picked refs belong to the old provider and must not be applied
+            // to the new one.
+            if (model.provider !== provider) {
+                return;
+            }
+            const refIds = selection.filter(item => item.refId !== undefined).map(item => item.refId!);
+            const auto = selection.some(item => item.auto) || refIds.length === 0;
+            model.setHistoryItemRefFilter(auto ? undefined : refIds);
+        } finally {
+            picker.dispose();
+            cts.dispose();
+        }
+    }
+
+    protected createRefPickItems(refs: readonly ScmHistoryItemRef[], provider: ScmHistoryProvider): (RefPickItem | QuickPickSeparator)[] {
+        const autoRefs = [provider.currentHistoryItemRef, provider.currentHistoryItemRemoteRef, provider.currentHistoryItemBaseRef]
+            .filter((ref): ref is ScmHistoryItemRef => !!ref);
+        const items: (RefPickItem | QuickPickSeparator)[] = [{
+            label: nls.localizeByDefault('Auto'),
+            description: autoRefs.map(ref => ref.name).join(', '),
+            auto: true
+        }];
+
+        const groups: { label: string; badgeClass: string }[] = [
+            { label: nls.localize('theia/scm/refPickerBranches', 'branches'), badgeClass: 'head' },
+            { label: nls.localize('theia/scm/refPickerRemoteBranches', 'remote branches'), badgeClass: 'remote' },
+            { label: nls.localize('theia/scm/refPickerTags', 'tags'), badgeClass: 'tag' }
+        ];
+        const grouped = new Set<ScmHistoryItemRef>();
+        for (const group of groups) {
+            const groupRefs = refs.filter(ref => getRefBadgeClass(ref) === group.badgeClass);
+            if (groupRefs.length > 0) {
+                groupRefs.forEach(ref => grouped.add(ref));
+                items.push({ type: 'separator', label: group.label });
+                items.push(...groupRefs.map(ref => this.toRefPickItem(ref)));
+            }
+        }
+        const remaining = refs.filter(ref => !grouped.has(ref));
+        if (remaining.length > 0) {
+            items.push({ type: 'separator' });
+            items.push(...remaining.map(ref => this.toRefPickItem(ref)));
+        }
+        return items;
+    }
+
+    protected toRefPickItem(ref: ScmHistoryItemRef): RefPickItem {
+        return {
+            label: ref.name,
+            description: ref.description,
+            refId: ref.id
+        };
+    }
+}

package/src/browser/scm-history-graph-helpers.spec.ts

@@ -0,0 +1,193 @@
+// *****************************************************************************
+// Copyright (C) 2026 Safi Seid-Ahmad, K2view and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import {
+    buildChangeTreeRows, ChangeTreeFileRow, ChangeTreeRow, filterRefsForBadges, getFileName, getRefBadgePresentation, getRefColorIndex
+} from './scm-history-graph-helpers';
+import { ScmHistoryItemChange, ScmHistoryItemRef, ScmHistoryProvider } from './scm-provider';
+
+describe('getRefColorIndex', () => {
+
+    const mainRef: ScmHistoryItemRef = { id: 'refs/heads/main', name: 'main' };
+    const remoteRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/main', name: 'origin/main' };
+    const baseRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/develop', name: 'origin/develop' };
+    const otherRef: ScmHistoryItemRef = { id: 'refs/heads/feature', name: 'feature' };
+
+    const provider = {
+        currentHistoryItemRef: mainRef,
+        currentHistoryItemRemoteRef: remoteRef,
+        currentHistoryItemBaseRef: baseRef,
+    } as ScmHistoryProvider;
+
+    it('returns 0 for the current history item ref', () => {
+        expect(getRefColorIndex(mainRef, provider)).to.equal(0);
+    });
+
+    it('returns 1 for the current remote ref', () => {
+        expect(getRefColorIndex(remoteRef, provider)).to.equal(1);
+    });
+
+    it('returns 2 for the current base ref', () => {
+        expect(getRefColorIndex(baseRef, provider)).to.equal(2);
+    });
+
+    it('returns undefined for any other ref', () => {
+        expect(getRefColorIndex(otherRef, provider)).to.be.undefined;
+    });
+
+    it('returns undefined without a provider', () => {
+        expect(getRefColorIndex(mainRef, undefined)).to.be.undefined;
+    });
+});
+
+describe('getRefBadgePresentation', () => {
+
+    const mainRef: ScmHistoryItemRef = { id: 'refs/heads/main', name: 'main' };
+    const remoteRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/main', name: 'origin/main' };
+
+    const provider = {
+        currentHistoryItemRef: mainRef,
+        currentHistoryItemRemoteRef: remoteRef,
+    } as ScmHistoryProvider;
+
+    it('prefers the codicon icon transferred from the provider', () => {
+        const ref: ScmHistoryItemRef = { ...mainRef, icon: 'codicon codicon-target' };
+        expect(getRefBadgePresentation(ref, undefined).iconClass).to.equal('codicon-target');
+    });
+
+    it('falls back to the target icon for the current ref', () => {
+        expect(getRefBadgePresentation(mainRef, provider).iconClass).to.equal('codicon-target');
+    });
+
+    it('falls back to category icons for remote, tag, and other local refs', () => {
+        expect(getRefBadgePresentation(remoteRef, provider).iconClass).to.equal('codicon-cloud');
+        expect(getRefBadgePresentation({ id: 'refs/tags/v1', name: 'v1' }, provider).iconClass).to.equal('codicon-tag');
+        expect(getRefBadgePresentation({ id: 'refs/heads/feature', name: 'feature' }, provider).iconClass).to.equal('codicon-git-branch');
+    });
+
+    it('carries the ref color index', () => {
+        expect(getRefBadgePresentation(mainRef, provider).colorIndex).to.equal(0);
+        expect(getRefBadgePresentation(remoteRef, provider).colorIndex).to.equal(1);
+        expect(getRefBadgePresentation({ id: 'refs/heads/feature', name: 'feature' }, provider).colorIndex).to.be.undefined;
+    });
+});
+
+describe('filterRefsForBadges', () => {
+
+    const mainRef: ScmHistoryItemRef = { id: 'refs/heads/main', name: 'main' };
+    const remoteRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/main', name: 'origin/main' };
+    const featureRef: ScmHistoryItemRef = { id: 'refs/heads/feature', name: 'feature' };
+    const refs = [mainRef, remoteRef, featureRef];
+
+    const provider = {
+        currentHistoryItemRef: mainRef,
+        currentHistoryItemRemoteRef: remoteRef,
+    } as ScmHistoryProvider;
+
+    it("returns all refs in 'all' mode", () => {
+        expect(filterRefsForBadges(refs, provider, 'all')).to.deep.equal(refs);
+    });
+
+    it("keeps only the refs used as a filter in 'filter' mode", () => {
+        expect(filterRefsForBadges(refs, provider, 'filter')).to.deep.equal([mainRef, remoteRef]);
+    });
+
+    it("returns all refs in 'filter' mode when no provider is available", () => {
+        expect(filterRefsForBadges(refs, undefined, 'filter')).to.deep.equal(refs);
+    });
+
+    it("keeps only the explicitly picked refs in 'filter' mode with an explicit filter", () => {
+        expect(filterRefsForBadges(refs, provider, 'filter', ['refs/heads/feature'])).to.deep.equal([featureRef]);
+    });
+
+    it("ignores an explicit filter in 'all' mode", () => {
+        expect(filterRefsForBadges(refs, provider, 'all', ['refs/heads/feature'])).to.deep.equal(refs);
+    });
+});
+
+describe('buildChangeTreeRows', () => {
+
+    const rootUri = 'file:///repo';
+
+    function change(path: string): ScmHistoryItemChange {
+        return { uri: `${rootUri}/${path}`, modifiedUri: `${rootUri}/${path}` };
+    }
+
+    /** Renders the rows as indented lines, so the expectations read like a tree. */
+    function describeRows(rows: readonly ChangeTreeRow[]): string[] {
+        return rows.map(row => `${'  '.repeat(row.depth)}${row.type === 'folder' ? row.label + '/' : getFileName(row.path)}`);
+    }
+
+    it('keeps files at the root at depth 0', () => {
+        const rows = buildChangeTreeRows([change('a.ts'), change('b.ts')], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['a.ts', 'b.ts']);
+    });
+
+    it('groups files under their folder', () => {
+        const rows = buildChangeTreeRows([change('src/a.ts'), change('src/b.ts')], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['src/', '  a.ts', '  b.ts']);
+    });
+
+    it('compacts folder chains that hold a single child folder', () => {
+        const rows = buildChangeTreeRows([change('src/browser/a.ts')], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['src/browser/', '  a.ts']);
+    });
+
+    it('stops compacting where a folder chain branches', () => {
+        const rows = buildChangeTreeRows([change('src/browser/a.ts'), change('src/node/b.ts')], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['src/', '  browser/', '    a.ts', '  node/', '    b.ts']);
+    });
+
+    it('does not compact a folder that also holds files', () => {
+        const rows = buildChangeTreeRows([change('src/a.ts'), change('src/browser/b.ts')], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['src/', '  browser/', '    b.ts', '  a.ts']);
+    });
+
+    it('sorts folders before files, each alphabetically', () => {
+        const rows = buildChangeTreeRows([change('z.ts'), change('a.ts'), change('src/b.ts')], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['src/', '  b.ts', 'a.ts', 'z.ts']);
+    });
+
+    it('hides the descendants of a collapsed folder', () => {
+        const rows = buildChangeTreeRows([change('src/a.ts'), change('b.ts')], rootUri, new Set(['src']));
+        expect(describeRows(rows)).to.deep.equal(['src/', 'b.ts']);
+    });
+
+    it('addresses a compacted folder by its full path', () => {
+        const rows = buildChangeTreeRows([change('src/browser/a.ts')], rootUri, new Set(['src/browser']));
+        expect(describeRows(rows)).to.deep.equal(['src/browser/']);
+    });
+
+    it('carries the original change on each file row', () => {
+        const first = change('src/a.ts');
+        const rows = buildChangeTreeRows([first], rootUri, new Set());
+        expect(rows[1].type).to.equal('file');
+        expect((rows[1] as ChangeTreeFileRow).change).to.equal(first);
+    });
+
+    it('keeps the index of the change in the original list, so row keys stay stable', () => {
+        const rows = buildChangeTreeRows([change('z.ts'), change('src/a.ts')], rootUri, new Set());
+        // Sorted as: src/, src/a.ts (index 1), z.ts (index 0).
+        expect(rows.filter(row => row.type === 'file').map(row => (row as ChangeTreeFileRow).index)).to.deep.equal([1, 0]);
+    });
+
+    it('falls back to the full path when the change is outside the repository root', () => {
+        const outside: ScmHistoryItemChange = { uri: 'file:///elsewhere/x.ts', modifiedUri: 'file:///elsewhere/x.ts' };
+        const rows = buildChangeTreeRows([outside], rootUri, new Set());
+        expect(describeRows(rows)).to.deep.equal(['elsewhere/', '  x.ts']);
+    });
+});

package/src/browser/scm-history-graph-helpers.ts

@@ -14,16 +14,16 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { ScmHistoryItemRef, ScmHistoryItemChange } from './scm-provider';
+import { ScmHistoryItemRef, ScmHistoryItemChange, ScmHistoryProvider } from './scm-provider';
 
 /**
- * Returns the CSS color variable for the given lane index.
+ * Returns the CSS color variable for the given color index.
  * Uses Theia's `--theia-scmGraph-*` variables, mirroring the VS Code
  * scm graph color scheme:
- *   lane 0 (current ref)  → historyItemRefColor
- *   lane 1 (remote ref)   → historyItemRemoteRefColor
- *   lane 2 (base ref)     → historyItemBaseRefColor
- *   lane 3–7              → foreground1–5
+ *   0 (current ref)  → historyItemRefColor
+ *   1 (remote ref)   → historyItemRemoteRefColor
+ *   2 (base ref)     → historyItemBaseRefColor
+ *   3–7 (default rotation) → foreground1–5
  */
 export function laneColor(index: number): string {
     switch (index % 8) {
@@ -83,6 +83,180 @@ export function getRepoRelativePath(uri: string, rootUri: string | undefined): s
     return fullPath;
 }
 
+export interface ChangeTreeRowBase {
+    /** Repo-relative path of the row; the expansion key for folders. */
+    readonly path: string;
+    /** Nesting level, used for indentation. */
+    readonly depth: number;
+}
+
+export interface ChangeTreeFolderRow extends ChangeTreeRowBase {
+    readonly type: 'folder';
+    /** Segments rendered for this row; a compacted chain shows `browser/model`. */
+    readonly label: string;
+}
+
+export interface ChangeTreeFileRow extends ChangeTreeRowBase {
+    readonly type: 'file';
+    readonly change: ScmHistoryItemChange;
+    /** Position of the change in the list it came from, so row keys stay stable. */
+    readonly index: number;
+}
+
+export type ChangeTreeRow = ChangeTreeFolderRow | ChangeTreeFileRow;
+
+interface ChangeTreeFolder {
+    readonly folders: Map<string, ChangeTreeFolder>;
+    readonly files: { change: ScmHistoryItemChange; index: number; name: string }[];
+}
+
+/**
+ * Arranges history item changes into the rows of a file tree: folders before
+ * files, each sorted by name, with single-child folder chains compacted into
+ * one row (`src/browser`) the way VS Code's SCM tree renders them. Folders
+ * listed in `collapsedFolders` (by their full path) hide their descendants.
+ */
+export function buildChangeTreeRows(
+    changes: readonly ScmHistoryItemChange[],
+    rootUri: string | undefined,
+    collapsedFolders: ReadonlySet<string>
+): ChangeTreeRow[] {
+    const root: ChangeTreeFolder = { folders: new Map(), files: [] };
+    changes.forEach((change, index) => {
+        const relativePath = getRepoRelativePath(change.modifiedUri ?? change.originalUri ?? change.uri, rootUri);
+        const segments = relativePath.split('/').filter(segment => segment.length > 0);
+        const name = segments.pop() ?? relativePath;
+        let folder = root;
+        for (const segment of segments) {
+            let child = folder.folders.get(segment);
+            if (!child) {
+                child = { folders: new Map(), files: [] };
+                folder.folders.set(segment, child);
+            }
+            folder = child;
+        }
+        folder.files.push({ change, index, name });
+    });
+
+    const rows: ChangeTreeRow[] = [];
+    collectChangeTreeRows(root, '', '', 0, collapsedFolders, rows);
+    return rows;
+}
+
+function collectChangeTreeRows(
+    folder: ChangeTreeFolder,
+    path: string,
+    label: string,
+    depth: number,
+    collapsedFolders: ReadonlySet<string>,
+    rows: ChangeTreeRow[]
+): void {
+    for (const name of [...folder.folders.keys()].sort(compareNames)) {
+        let child = folder.folders.get(name)!;
+        let childPath = path ? `${path}/${name}` : name;
+        let childLabel = label ? `${label}/${name}` : name;
+        // Compact a chain of folders that each hold nothing but one folder.
+        while (child.files.length === 0 && child.folders.size === 1) {
+            const [onlyName, onlyChild] = [...child.folders][0];
+            child = onlyChild;
+            childPath = `${childPath}/${onlyName}`;
+            childLabel = `${childLabel}/${onlyName}`;
+        }
+        rows.push({ type: 'folder', path: childPath, label: childLabel, depth });
+        if (!collapsedFolders.has(childPath)) {
+            collectChangeTreeRows(child, childPath, '', depth + 1, collapsedFolders, rows);
+        }
+    }
+    for (const file of [...folder.files].sort((left, right) => compareNames(left.name, right.name))) {
+        rows.push({
+            type: 'file',
+            path: path ? `${path}/${file.name}` : file.name,
+            depth,
+            change: file.change,
+            index: file.index
+        });
+    }
+}
+
+function compareNames(left: string, right: string): number {
+    return left.localeCompare(right);
+}
+
+/**
+ * Returns the ref-based color index of the given ref (0 = current ref,
+ * 1 = remote ref, 2 = base ref), or `undefined` when the ref is none of
+ * the provider's current history item refs. Mirrors VS Code's scm graph
+ * color map.
+ */
+export function getRefColorIndex(ref: ScmHistoryItemRef, provider: ScmHistoryProvider | undefined): number | undefined {
+    if (!provider) {
+        return undefined;
+    }
+    if (ref.id === provider.currentHistoryItemRef?.id) {
+        return 0;
+    }
+    if (ref.id === provider.currentHistoryItemRemoteRef?.id) {
+        return 1;
+    }
+    if (ref.id === provider.currentHistoryItemBaseRef?.id) {
+        return 2;
+    }
+    return undefined;
+}
+
+/**
+ * Filters which refs get badges in the graph, following VS Code's
+ * `scm.graph.badges` setting: `'all'` shows every ref, `'filter'` shows only
+ * the refs used as the graph's filter — the explicitly picked ref ids, or,
+ * without an explicit filter (auto mode), the current, remote, and base refs.
+ * Without provider information all refs are kept.
+ */
+export function filterRefsForBadges(
+    refs: readonly ScmHistoryItemRef[],
+    provider: ScmHistoryProvider | undefined,
+    badges: 'all' | 'filter',
+    filter?: readonly string[]
+): readonly ScmHistoryItemRef[] {
+    if (badges === 'all') {
+        return refs;
+    }
+    if (filter) {
+        return refs.filter(ref => filter.includes(ref.id));
+    }
+    if (!provider) {
+        return refs;
+    }
+    return refs.filter(ref => getRefColorIndex(ref, provider) !== undefined);
+}
+
+export interface RefBadgePresentation {
+    /** Icon class for the badge icon, e.g. 'codicon-git-branch'. */
+    iconClass: string;
+    /** Ref-based color index (0-2), or `undefined` to use the row color. */
+    colorIndex?: number;
+}
+
+/**
+ * Resolves how a ref badge is presented: the provider-supplied codicon icon
+ * when available (VS Code renders `ref.icon` unconditionally), otherwise a
+ * category fallback with the `target` icon marking the current ref; plus the
+ * ref-based color index.
+ */
+export function getRefBadgePresentation(ref: ScmHistoryItemRef, provider: ScmHistoryProvider | undefined): RefBadgePresentation {
+    const colorIndex = getRefColorIndex(ref, provider);
+    let iconClass: string;
+    if (ref.icon && ref.icon.startsWith('codicon ')) {
+        iconClass = ref.icon.substring('codicon '.length);
+    } else if (isTagRef(ref)) {
+        iconClass = 'codicon-tag';
+    } else if (isRemoteRef(ref)) {
+        iconClass = 'codicon-cloud';
+    } else {
+        iconClass = colorIndex === 0 ? 'codicon-target' : 'codicon-git-branch';
+    }
+    return { iconClass, colorIndex };
+}
+
 export function getRefBadgeClass(ref: ScmHistoryItemRef): string {
     const cat = (ref.category ?? '').toLowerCase();
     if (cat === 'heads' || cat === 'head' || ref.id.startsWith('refs/heads/')) {