feat(walkthrough): guided AI walkthrough for diffs, branches, and PRs (#2572)
A diff is ordered by file path, which is almost never the order in which a change makes sense. This adds a Walkthrough surface that reorders it: the model groups related hunks into stops, explains what each group changes about behavior, and orders the stops so each builds on the last. It explains and orders; judging code stays with the existing Review action. Reviews uncommitted work (all, staged, unstaged), a branch against its base, or a pull request. Generation is always user-initiated — nothing runs on a timer, on a file change, or as a side effect of opening a panel. Invariants worth preserving: - Hunk identity is derived on the server and only there. Ids are content hashes, so an anchor that no longer resolves is proof the code it described changed, and staleness needs no heuristics. The client matches ids to ids and never recomputes them; two implementations would have to agree forever. - The digest is never truncated. A diff that does not fit the model's context is refused with an actionable reason, because a walkthrough written against half a diff reads as confident and is wrong. - Nothing disappears. Lockfiles and other generated output are excluded from the model's input by name — never by size — and everything no stop covers is listed at the end, so "have I seen all of it" stays answerable. - Cost is explicit. Results are content-addressed, so returning the working tree to an earlier state costs nothing; generation outlives its request, so a refresh detaches the client rather than discarding paid-for work, and only an explicit cancel stops it. Supporting changes to shared modules: - git: expose the existing getRangeDiff as GET /api/git listUntrackedPaths and getUntrackedDiffs. The latter resolve the repository once for a batch instead of per file, taking a panel ~340ms on an 80-file working tree. - small-model: structured output across four wire forma and abort signal, and an onOverflow policy so an oversized prompt fails loudly instead of being silently clipped. A provider remembered so the prompt-side fallback goes first next time. - models.dev metadata: surface structured_output as tri false blocks a model, a missing field does not, because the catalog omits it for roughly half of all models. Desktop and tablet only: VS Code serves Git through its these routes, and the mobile shell does not consume the surface registry. Docs: packages/docs walkthrough page in English and all eight locales.
This commit is contained in:
Bohdan Triapitsyn
committed by
GitHub
GitHub
parent
b1ec34162e
commit
34d0ff7383
@@ -0,0 +1,106 @@
|
||||
import { runtimeFetch } from '@/lib/runtime-fetch';
|
||||
import {
|
||||
WalkthroughError,
|
||||
type WalkthroughResult,
|
||||
type WalkthroughSource,
|
||||
type WalkthroughStage,
|
||||
} from './types';
|
||||
|
||||
const BASE = '/api/walkthrough';
|
||||
|
||||
interface ErrorPayload {
|
||||
error?: unknown;
|
||||
code?: unknown;
|
||||
model?: unknown;
|
||||
requiredChars?: unknown;
|
||||
availableChars?: unknown;
|
||||
}
|
||||
|
||||
// An authoritative read that fails must never look like "there is nothing
|
||||
// here" — the caller would clear a perfectly good walkthrough off the screen.
|
||||
const throwFromResponse = async (response: Response, fallback: string): Promise<never> => {
|
||||
const payload = (await response.json().catch(() => null)) as ErrorPayload | null;
|
||||
throw new WalkthroughError(typeof payload?.error === 'string' ? payload.error : fallback, {
|
||||
code: typeof payload?.code === 'string' ? (payload.code as WalkthroughError['code']) : undefined,
|
||||
model: (payload?.model as WalkthroughResult['model']) ?? undefined,
|
||||
requiredChars: typeof payload?.requiredChars === 'number' ? payload.requiredChars : undefined,
|
||||
availableChars: typeof payload?.availableChars === 'number' ? payload.availableChars : undefined,
|
||||
});
|
||||
};
|
||||
|
||||
export async function fetchWalkthrough(
|
||||
directory: string,
|
||||
source: WalkthroughSource,
|
||||
options: { model?: string; signal?: AbortSignal } = {}
|
||||
): Promise<WalkthroughResult> {
|
||||
const response = await runtimeFetch(BASE, {
|
||||
query: {
|
||||
directory,
|
||||
source: JSON.stringify(source),
|
||||
...(options.model ? { model: options.model } : {}),
|
||||
},
|
||||
signal: options.signal,
|
||||
});
|
||||
if (!response.ok) {
|
||||
return throwFromResponse(response, 'Failed to load walkthrough');
|
||||
}
|
||||
return response.json();
|
||||
}
|
||||
|
||||
export async function generateWalkthrough(
|
||||
directory: string,
|
||||
source: WalkthroughSource,
|
||||
options: { force?: boolean; model?: string; signal?: AbortSignal } = {}
|
||||
): Promise<WalkthroughResult> {
|
||||
const response = await runtimeFetch(`${BASE}/generate`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
directory,
|
||||
source,
|
||||
force: options.force === true,
|
||||
...(options.model ? { model: options.model } : {}),
|
||||
}),
|
||||
signal: options.signal,
|
||||
});
|
||||
if (!response.ok) {
|
||||
return throwFromResponse(response, 'Failed to generate walkthrough');
|
||||
}
|
||||
return response.json();
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop a running generation. Explicit, because merely leaving the page must not
|
||||
* throw away work the user is paying for.
|
||||
*/
|
||||
export async function cancelWalkthroughGeneration(
|
||||
directory: string,
|
||||
source: WalkthroughSource
|
||||
): Promise<void> {
|
||||
const response = await runtimeFetch(`${BASE}/cancel`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ directory, source }),
|
||||
});
|
||||
if (!response.ok) {
|
||||
await throwFromResponse(response, 'Failed to cancel walkthrough generation');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Current stage of a running generation. Reads server memory only, so this is
|
||||
* safe to poll — unlike the full read, which re-runs the whole git pipeline.
|
||||
*/
|
||||
export async function fetchWalkthroughStage(
|
||||
directory: string,
|
||||
source: WalkthroughSource,
|
||||
signal?: AbortSignal
|
||||
): Promise<WalkthroughStage | null> {
|
||||
const response = await runtimeFetch(`${BASE}/progress`, {
|
||||
query: { directory, source: JSON.stringify(source) },
|
||||
signal,
|
||||
});
|
||||
if (!response.ok) return null;
|
||||
const payload = (await response.json().catch(() => null)) as { stage?: unknown } | null;
|
||||
return typeof payload?.stage === 'string' ? (payload.stage as WalkthroughStage) : null;
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
import { describe, expect, test as it } from 'bun:test';
|
||||
import { buildWalkthroughView, groupHunksByFile, mergeRunPatch, summarizeHunkFiles } from './model';
|
||||
import type { WalkthroughHunk, WalkthroughResult } from './types';
|
||||
|
||||
const hunk = (id: string, path: string, overrides: Partial<WalkthroughHunk> = {}): WalkthroughHunk => ({
|
||||
id,
|
||||
path,
|
||||
oldPath: null,
|
||||
status: 'modified',
|
||||
scope: 'working',
|
||||
header: '@@ -1,2 +1,3 @@',
|
||||
newStart: 1,
|
||||
added: 1,
|
||||
deleted: 0,
|
||||
patch: `diff --git a/${path} b/${path}\n--- a/${path}\n+++ b/${path}\n@@ -1,2 +1,3 @@\n+line\n`,
|
||||
...overrides,
|
||||
});
|
||||
|
||||
const result = (overrides: Partial<WalkthroughResult> = {}): WalkthroughResult => ({
|
||||
source: { kind: 'working-tree', scope: 'all' },
|
||||
walkthrough: {
|
||||
title: 'Change',
|
||||
focus: 'why',
|
||||
chapters: [
|
||||
{
|
||||
id: 'chapter-1',
|
||||
title: 'Data',
|
||||
icon: 'doc',
|
||||
blurb: '',
|
||||
stops: [
|
||||
{ id: 'stop-1-1', title: 'First', hunkIds: ['a', 'b'], importance: 'critical', prose: 'p1' },
|
||||
{ id: 'stop-1-2', title: 'Second', hunkIds: ['c'], importance: 'normal', prose: 'p2' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
hunks: [hunk('a', 'src/a.ts'), hunk('b', 'src/a.ts'), hunk('c', 'src/b.ts')],
|
||||
hunkCount: 3,
|
||||
...overrides,
|
||||
});
|
||||
|
||||
describe('buildWalkthroughView', () => {
|
||||
it('resolves stops and numbers them globally', () => {
|
||||
const view = buildWalkthroughView(result())!;
|
||||
|
||||
expect(view.stops).toHaveLength(2);
|
||||
expect(view.stops.map((stop) => stop.position)).toEqual([1, 2]);
|
||||
expect(view.stops[0].hunks.map((h) => h.id)).toEqual(['a', 'b']);
|
||||
expect(view.isStale).toBe(false);
|
||||
expect(view.uncoveredHunks).toEqual([]);
|
||||
});
|
||||
|
||||
it('marks only the stops whose code changed', () => {
|
||||
const view = buildWalkthroughView(result({
|
||||
hunks: [hunk('a', 'src/a.ts'), hunk('c', 'src/b.ts')],
|
||||
}))!;
|
||||
|
||||
expect(view.stops[0].isStale).toBe(true);
|
||||
expect(view.stops[0].missingHunkIds).toEqual(['b']);
|
||||
expect(view.stops[0].hunks.map((h) => h.id)).toEqual(['a']);
|
||||
expect(view.stops[1].isStale).toBe(false);
|
||||
expect(view.staleStopCount).toBe(1);
|
||||
expect(view.isStale).toBe(true);
|
||||
});
|
||||
|
||||
it('surfaces hunks no stop covers instead of dropping them', () => {
|
||||
const view = buildWalkthroughView(result({
|
||||
hunks: [hunk('a', 'src/a.ts'), hunk('b', 'src/a.ts'), hunk('c', 'src/b.ts'), hunk('d', 'src/c.ts')],
|
||||
}))!;
|
||||
|
||||
expect(view.uncoveredHunks.map((h) => h.id)).toEqual(['d']);
|
||||
});
|
||||
|
||||
it('returns null without a walkthrough', () => {
|
||||
expect(buildWalkthroughView(null)).toBeNull();
|
||||
expect(buildWalkthroughView(result({ walkthrough: null }))).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('groupHunksByFile', () => {
|
||||
it('coalesces consecutive hunks from the same file only', () => {
|
||||
const runs = groupHunksByFile([
|
||||
hunk('a', 'src/a.ts'),
|
||||
hunk('b', 'src/a.ts'),
|
||||
hunk('c', 'src/b.ts'),
|
||||
hunk('d', 'src/a.ts'),
|
||||
]);
|
||||
|
||||
expect(runs.map((run) => [run.path, run.hunks.length])).toEqual([
|
||||
['src/a.ts', 2],
|
||||
['src/b.ts', 1],
|
||||
['src/a.ts', 1],
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('mergeRunPatch', () => {
|
||||
it('keeps a single patch untouched', () => {
|
||||
const single = hunk('a', 'src/a.ts');
|
||||
expect(mergeRunPatch([single])).toBe(single.patch);
|
||||
});
|
||||
|
||||
it('joins hunks under one file header', () => {
|
||||
const first = hunk('a', 'src/a.ts');
|
||||
const second = hunk('b', 'src/a.ts', {
|
||||
patch: 'diff --git a/src/a.ts b/src/a.ts\n--- a/src/a.ts\n+++ b/src/a.ts\n@@ -10,2 +11,3 @@\n+second\n',
|
||||
});
|
||||
|
||||
const merged = mergeRunPatch([first, second]);
|
||||
|
||||
expect(merged.match(/^diff --git/gm)).toHaveLength(1);
|
||||
expect(merged.match(/^@@/gm)).toHaveLength(2);
|
||||
expect(merged).toContain('+line');
|
||||
expect(merged).toContain('+second');
|
||||
});
|
||||
|
||||
it('returns nothing for an empty run', () => {
|
||||
expect(mergeRunPatch([])).toBe('');
|
||||
});
|
||||
});
|
||||
|
||||
describe('summarizeHunkFiles', () => {
|
||||
it('totals per file in first-appearance order', () => {
|
||||
const files = summarizeHunkFiles([
|
||||
hunk('a', 'src/b.ts', { added: 2, deleted: 1 }),
|
||||
hunk('b', 'src/a.ts', { added: 1, deleted: 0 }),
|
||||
hunk('c', 'src/b.ts', { added: 3, deleted: 4 }),
|
||||
]);
|
||||
|
||||
expect(files).toEqual([
|
||||
{ path: 'src/b.ts', added: 5, deleted: 5 },
|
||||
{ path: 'src/a.ts', added: 1, deleted: 0 },
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,151 @@
|
||||
import type {
|
||||
Walkthrough,
|
||||
WalkthroughChapter,
|
||||
WalkthroughHunk,
|
||||
WalkthroughResult,
|
||||
WalkthroughStop,
|
||||
} from './types';
|
||||
|
||||
/**
|
||||
* Flattens a walkthrough plus the current hunk index into the ordered stream
|
||||
* the view renders: every stop with its resolved hunks, followed by everything
|
||||
* the walkthrough did not cover.
|
||||
*
|
||||
* Resolution is pure id matching — the server owns hunk identity, so a stop
|
||||
* whose hunks are missing is not a bug to paper over, it is a stop whose code
|
||||
* has changed.
|
||||
*/
|
||||
|
||||
export interface WalkthroughStopView {
|
||||
stop: WalkthroughStop;
|
||||
chapter: WalkthroughChapter;
|
||||
chapterIndex: number;
|
||||
/** Global 1-based position, used for the stepper and keyboard navigation. */
|
||||
position: number;
|
||||
hunks: WalkthroughHunk[];
|
||||
/** Anchors that no longer resolve: their code changed or was removed. */
|
||||
missingHunkIds: string[];
|
||||
isStale: boolean;
|
||||
}
|
||||
|
||||
export interface WalkthroughView {
|
||||
walkthrough: Walkthrough;
|
||||
stops: WalkthroughStopView[];
|
||||
chapters: Array<{ chapter: WalkthroughChapter; stops: WalkthroughStopView[] }>;
|
||||
/** Current hunks no stop covers. Never dropped — rendered as a collapsed tail. */
|
||||
uncoveredHunks: WalkthroughHunk[];
|
||||
staleStopCount: number;
|
||||
isStale: boolean;
|
||||
}
|
||||
|
||||
export const buildWalkthroughView = (result: WalkthroughResult | null): WalkthroughView | null => {
|
||||
if (!result?.walkthrough) return null;
|
||||
|
||||
const index = new Map(result.hunks.map((hunk) => [hunk.id, hunk]));
|
||||
const covered = new Set<string>();
|
||||
const stops: WalkthroughStopView[] = [];
|
||||
const chapters: WalkthroughView['chapters'] = [];
|
||||
|
||||
for (const [chapterIndex, chapter] of result.walkthrough.chapters.entries()) {
|
||||
const chapterStops: WalkthroughStopView[] = [];
|
||||
|
||||
for (const stop of chapter.stops) {
|
||||
const hunks: WalkthroughHunk[] = [];
|
||||
const missingHunkIds: string[] = [];
|
||||
|
||||
for (const id of stop.hunkIds) {
|
||||
const hunk = index.get(id);
|
||||
if (hunk) {
|
||||
hunks.push(hunk);
|
||||
covered.add(id);
|
||||
} else {
|
||||
missingHunkIds.push(id);
|
||||
}
|
||||
}
|
||||
|
||||
const view: WalkthroughStopView = {
|
||||
stop,
|
||||
chapter,
|
||||
chapterIndex,
|
||||
position: stops.length + 1,
|
||||
hunks,
|
||||
missingHunkIds,
|
||||
isStale: missingHunkIds.length > 0,
|
||||
};
|
||||
stops.push(view);
|
||||
chapterStops.push(view);
|
||||
}
|
||||
|
||||
chapters.push({ chapter, stops: chapterStops });
|
||||
}
|
||||
|
||||
return {
|
||||
walkthrough: result.walkthrough,
|
||||
stops,
|
||||
chapters,
|
||||
uncoveredHunks: result.hunks.filter((hunk) => !covered.has(hunk.id)),
|
||||
staleStopCount: stops.filter((stop) => stop.isStale).length,
|
||||
isStale: stops.some((stop) => stop.isStale),
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* Files touched by a set of hunks, in first-appearance order, with their
|
||||
* per-file totals. Used for the table of contents rows.
|
||||
*/
|
||||
export const summarizeHunkFiles = (
|
||||
hunks: WalkthroughHunk[]
|
||||
): Array<{ path: string; added: number; deleted: number }> => {
|
||||
const byPath = new Map<string, { path: string; added: number; deleted: number }>();
|
||||
for (const hunk of hunks) {
|
||||
const existing = byPath.get(hunk.path);
|
||||
if (existing) {
|
||||
existing.added += hunk.added;
|
||||
existing.deleted += hunk.deleted;
|
||||
continue;
|
||||
}
|
||||
byPath.set(hunk.path, { path: hunk.path, added: hunk.added, deleted: hunk.deleted });
|
||||
}
|
||||
return [...byPath.values()];
|
||||
};
|
||||
|
||||
/**
|
||||
* Consecutive hunks from the same file are rendered as one diff block so the
|
||||
* reader sees continuous code instead of a stack of one-hunk cards.
|
||||
*/
|
||||
export const groupHunksByFile = (
|
||||
hunks: WalkthroughHunk[]
|
||||
): Array<{ path: string; hunks: WalkthroughHunk[] }> => {
|
||||
const runs: Array<{ path: string; hunks: WalkthroughHunk[] }> = [];
|
||||
for (const hunk of hunks) {
|
||||
const last = runs.at(-1);
|
||||
if (last && last.path === hunk.path) {
|
||||
last.hunks.push(hunk);
|
||||
continue;
|
||||
}
|
||||
runs.push({ path: hunk.path, hunks: [hunk] });
|
||||
}
|
||||
return runs;
|
||||
};
|
||||
|
||||
/**
|
||||
* Merge a file's hunk patches back into one patch so a run renders as a single
|
||||
* diff. All hunks in a run share a file header, so only the first one's header
|
||||
* is kept.
|
||||
*/
|
||||
export const mergeRunPatch = (hunks: WalkthroughHunk[]): string => {
|
||||
if (hunks.length === 0) return '';
|
||||
if (hunks.length === 1) return hunks[0].patch;
|
||||
|
||||
const first = hunks[0].patch;
|
||||
const headerEnd = first.indexOf('\n@@');
|
||||
if (headerEnd === -1) return first;
|
||||
|
||||
const header = first.slice(0, headerEnd);
|
||||
const bodies = hunks.map((hunk) => {
|
||||
const start = hunk.patch.indexOf('\n@@');
|
||||
return start === -1 ? '' : hunk.patch.slice(start + 1);
|
||||
});
|
||||
|
||||
return `${header}\n${bodies.join('')}`;
|
||||
};
|
||||
@@ -0,0 +1,132 @@
|
||||
/**
|
||||
* Contract for the AI diff walkthrough, mirrored from
|
||||
* `packages/web/server/lib/walkthrough`.
|
||||
*
|
||||
* Hunk ids are opaque here on purpose: the server owns how they are derived,
|
||||
* and the client only ever matches them against the index it is handed.
|
||||
*/
|
||||
|
||||
export type WalkthroughWorkingTreeScope = 'all' | 'staged' | 'working';
|
||||
|
||||
export type WalkthroughSource =
|
||||
| { kind: 'working-tree'; scope: WalkthroughWorkingTreeScope }
|
||||
| { kind: 'branch'; baseRef: string; headRef: string }
|
||||
| { kind: 'pr'; number: number };
|
||||
|
||||
export type WalkthroughChapterIcon = 'bug' | 'wrench' | 'path' | 'flask' | 'doc' | 'gear';
|
||||
export type WalkthroughStopImportance = 'critical' | 'normal' | 'context';
|
||||
|
||||
export interface WalkthroughStop {
|
||||
id: string;
|
||||
title: string;
|
||||
hunkIds: string[];
|
||||
importance: WalkthroughStopImportance;
|
||||
prose: string;
|
||||
}
|
||||
|
||||
export interface WalkthroughChapter {
|
||||
id: string;
|
||||
title: string;
|
||||
icon: WalkthroughChapterIcon;
|
||||
blurb: string;
|
||||
stops: WalkthroughStop[];
|
||||
}
|
||||
|
||||
export interface Walkthrough {
|
||||
title: string;
|
||||
focus: string;
|
||||
chapters: WalkthroughChapter[];
|
||||
}
|
||||
|
||||
export interface WalkthroughHunk {
|
||||
id: string;
|
||||
path: string;
|
||||
oldPath: string | null;
|
||||
status: 'added' | 'deleted' | 'modified' | 'renamed';
|
||||
scope: string;
|
||||
header: string;
|
||||
newStart: number;
|
||||
added: number;
|
||||
deleted: number;
|
||||
/** Standalone patch for this hunk, including the file header. */
|
||||
patch: string;
|
||||
}
|
||||
|
||||
export interface WalkthroughModel {
|
||||
providerID: string;
|
||||
modelID: string;
|
||||
source?: string;
|
||||
}
|
||||
|
||||
export interface WalkthroughResult {
|
||||
source: WalkthroughSource;
|
||||
walkthrough: Walkthrough | null;
|
||||
model?: WalkthroughModel;
|
||||
generatedAt?: string;
|
||||
fromCache?: boolean;
|
||||
hunks: WalkthroughHunk[];
|
||||
hunkCount: number;
|
||||
/** True when at least one stop points at code that has since changed. */
|
||||
isStale?: boolean;
|
||||
missingHunkIds?: string[];
|
||||
staleStopIds?: string[];
|
||||
/** Hunks in the current diff that no stop covers. Rendered as a tail. */
|
||||
uncoveredHunkIds?: string[];
|
||||
/** Whether generating is possible at all, computed from the same diff. */
|
||||
readiness?: WalkthroughReadiness;
|
||||
/** A generation is already running on the server for this source. */
|
||||
generating?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Only phases a person can wait on. Building the digest and reading the cache
|
||||
* take milliseconds; naming them would imply progress that is not happening.
|
||||
*/
|
||||
export type WalkthroughStage = 'collecting' | 'asking' | 'retrying' | 'assembling';
|
||||
|
||||
export type WalkthroughBlockedReason =
|
||||
| 'no-model'
|
||||
| 'empty-diff'
|
||||
| 'only-generated'
|
||||
| 'context-too-small'
|
||||
| 'structured-output-unsupported'
|
||||
| 'output-exhausted';
|
||||
|
||||
export interface WalkthroughReadiness {
|
||||
ready: boolean;
|
||||
reason?: WalkthroughBlockedReason;
|
||||
model?: WalkthroughModel & {
|
||||
inputCharBudget?: number;
|
||||
contextTokens?: number;
|
||||
structuredOutput?: boolean | null;
|
||||
};
|
||||
requiredChars?: number;
|
||||
availableChars?: number;
|
||||
hunkCount?: number;
|
||||
fileCount?: number;
|
||||
generatedFileCount?: number;
|
||||
}
|
||||
|
||||
export class WalkthroughError extends Error {
|
||||
readonly code?: WalkthroughBlockedReason | 'invalid-walkthrough' | 'github-not-connected' | 'no-github-remote';
|
||||
readonly model?: WalkthroughModel;
|
||||
readonly requiredChars?: number;
|
||||
readonly availableChars?: number;
|
||||
|
||||
constructor(
|
||||
message: string,
|
||||
details: {
|
||||
code?: WalkthroughError['code'];
|
||||
model?: WalkthroughModel;
|
||||
requiredChars?: number;
|
||||
availableChars?: number;
|
||||
} = {}
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'WalkthroughError';
|
||||
this.code = details.code;
|
||||
this.model = details.model;
|
||||
this.requiredChars = details.requiredChars;
|
||||
this.availableChars = details.availableChars;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user