Skip to content

Commit 630f273

Browse files
committed
fix(checkpoints): roll change-card files back to their pre-step state and add restore-latest (B3c, #1375)
A change card is keyed by the checkpoint its own step produced, so restoring a card file to that checkpoint restored the post-write state - a no-op for the newest card and a backwards-time-travel for older ones. Resolve each file's restore target from the B2 journal instead: the file's immediately preceding journal entry's checkpoint (its pre-step state), or the task-start baseline when no earlier step wrote the file (undoing a create removes the file; undoing a delete restores it). Add restoreLatestFile as the forward direction: a file back to its most recent recorded write, a successful no-op when the task never wrote it.
1 parent d64389c commit 630f273

2 files changed

Lines changed: 371 additions & 134 deletions

File tree

‎src/core/checkpoints/__tests__/rollback.spec.ts‎

Lines changed: 220 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@ import path from "path"
55
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
66

77
import type { Task } from "../../task/Task"
8+
import type { ChangeJournalEntry } from "../changeJournal"
89
import { getCheckpointService } from "../index"
910
import { appendChange } from "../changeJournal"
10-
import { rollbackFile, rollbackStep } from "../rollback"
11+
import { restoreLatestFile, rollbackFile, rollbackStep } from "../rollback"
1112

1213
vi.mock("../index", () => ({
1314
getCheckpointService: vi.fn(),
@@ -27,26 +28,104 @@ function makeTask(): Task {
2728
} as unknown as Task
2829
}
2930

31+
/** A checkpoint-service double with a recording restoreFile and a baseline. */
32+
function serviceWith(baseHash: string | undefined) {
33+
const restoreFile = vi.fn().mockResolvedValue(undefined)
34+
return { baseHash, restoreFile }
35+
}
36+
37+
async function seedJournal(entries: ChangeJournalEntry[]): Promise<void> {
38+
for (const entry of entries) {
39+
await appendChange(globalStorageDir, "task-rollback", entry)
40+
}
41+
}
42+
3043
let globalStorageDir: string
3144

3245
beforeEach(async () => {
33-
globalStorageDir = await fs.mkdtemp(path.join(os.tmpdir(), "b3a-rollback-"))
46+
globalStorageDir = await fs.mkdtemp(path.join(os.tmpdir(), "b3c-rollback-"))
3447
mockedGetCheckpointService.mockReset()
3548
})
3649

3750
afterEach(async () => {
3851
await fs.rm(globalStorageDir, { recursive: true, force: true })
3952
})
4053

41-
describe("rollbackFile (B3a)", () => {
42-
it("restores the file through the task's checkpoint service", async () => {
43-
const restoreFile = vi.fn().mockResolvedValue(undefined)
44-
mockedGetCheckpointService.mockResolvedValue({ restoreFile })
54+
describe("rollbackFile (B3c: undo the step's write to the file)", () => {
55+
it("restores the file to the PREVIOUS step's checkpoint when an earlier entry exists", async () => {
56+
await seedJournal([
57+
{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" },
58+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
59+
])
60+
const service = serviceWith("base-0")
61+
mockedGetCheckpointService.mockResolvedValue(service)
62+
63+
const outcome = await rollbackFile(makeTask(), "sha-2", "src/a.ts")
64+
65+
expect(outcome).toEqual({ filePath: "src/a.ts", success: true })
66+
// The pre-step state is the previous step's post-write checkpoint — not
67+
// the step's own (post-write) checkpoint.
68+
expect(service.restoreFile).toHaveBeenCalledTimes(1)
69+
expect(service.restoreFile).toHaveBeenCalledWith("sha-1", "src/a.ts")
70+
})
71+
72+
it("restores from the task-start baseline when the file has no earlier entry", async () => {
73+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
74+
const service = serviceWith("base-0")
75+
mockedGetCheckpointService.mockResolvedValue(service)
4576

4677
const outcome = await rollbackFile(makeTask(), "sha-1", "src/a.ts")
4778

4879
expect(outcome).toEqual({ filePath: "src/a.ts", success: true })
49-
expect(restoreFile).toHaveBeenCalledWith("sha-1", "src/a.ts")
80+
expect(service.restoreFile).toHaveBeenCalledWith("base-0", "src/a.ts")
81+
})
82+
83+
it("resolves through the first entry of a multi-write step", async () => {
84+
// One patch writes the same file twice: two entries share the step
85+
// checkpoint. The pre-step state is still the entry before the first
86+
// one of the step.
87+
await seedJournal([
88+
{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" },
89+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
90+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
91+
])
92+
const service = serviceWith("base-0")
93+
mockedGetCheckpointService.mockResolvedValue(service)
94+
95+
const outcome = await rollbackFile(makeTask(), "sha-2", "src/a.ts")
96+
97+
expect(outcome.success).toBe(true)
98+
expect(service.restoreFile).toHaveBeenCalledWith("sha-1", "src/a.ts")
99+
})
100+
101+
it("fails cleanly when the file is not part of the given step checkpoint", async () => {
102+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
103+
const service = serviceWith("base-0")
104+
mockedGetCheckpointService.mockResolvedValue(service)
105+
106+
const outcome = await rollbackFile(makeTask(), "sha-2", "src/a.ts")
107+
108+
expect(outcome).toEqual({
109+
filePath: "src/a.ts",
110+
success: false,
111+
error: "File is not part of this step's checkpoint",
112+
})
113+
expect(service.restoreFile).not.toHaveBeenCalled()
114+
})
115+
116+
it("fails cleanly when no earlier checkpoint exists and the baseline is unavailable", async () => {
117+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
118+
const service = serviceWith(undefined)
119+
mockedGetCheckpointService.mockResolvedValue(service)
120+
121+
const outcome = await rollbackFile(makeTask(), "sha-1", "src/a.ts")
122+
123+
expect(outcome).toEqual({
124+
filePath: "src/a.ts",
125+
success: false,
126+
error: "No checkpoint available to restore",
127+
})
128+
expect(service.restoreFile).not.toHaveBeenCalled()
50129
})
51130

52131
it("fails cleanly when checkpoints are not enabled", async () => {
@@ -62,107 +141,118 @@ describe("rollbackFile (B3a)", () => {
62141
})
63142

64143
it("reports the service error without throwing", async () => {
65-
mockedGetCheckpointService.mockResolvedValue({
66-
restoreFile: vi.fn().mockRejectedValue(new Error("pathspec did not match")),
67-
})
144+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
145+
const service = serviceWith("base-0")
146+
service.restoreFile.mockRejectedValue(new Error("pathspec did not match"))
147+
mockedGetCheckpointService.mockResolvedValue(service)
68148

69-
const outcome = await rollbackFile(makeTask(), "sha-bad", "src/a.ts")
149+
const outcome = await rollbackFile(makeTask(), "sha-1", "src/a.ts")
70150

71151
expect(outcome.success).toBe(false)
72152
expect(outcome.error).toContain("pathspec did not match")
73153
})
74154

75155
it("stringifies non-Error rejections into the outcome", async () => {
76-
mockedGetCheckpointService.mockResolvedValue({
77-
restoreFile: vi.fn().mockRejectedValue("raw failure"),
78-
})
156+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
157+
const service = serviceWith("base-0")
158+
service.restoreFile.mockRejectedValue("raw failure")
159+
mockedGetCheckpointService.mockResolvedValue(service)
79160

80-
const outcome = await rollbackFile(makeTask(), "sha-bad", "src/a.ts")
161+
const outcome = await rollbackFile(makeTask(), "sha-1", "src/a.ts")
81162

82163
expect(outcome).toEqual({ filePath: "src/a.ts", success: false, error: "raw failure" })
83164
})
84165
})
85166

86-
describe("rollbackStep (B3a)", () => {
87-
it("restores every step file from the step's checkpoint via the journal", async () => {
88-
await appendChange(globalStorageDir, "task-rollback", {
89-
path: "src/a.ts",
90-
operation: "create",
91-
checkpointId: "sha-step",
92-
})
93-
await appendChange(globalStorageDir, "task-rollback", {
94-
path: "src/b.ts",
95-
operation: "update",
96-
checkpointId: "sha-step",
97-
})
98-
99-
const restoreFile = vi.fn().mockResolvedValue(undefined)
100-
mockedGetCheckpointService.mockResolvedValue({ restoreFile })
167+
describe("rollbackStep (B3c: undo every file of the step)", () => {
168+
it("restores every step file to its pre-step state", async () => {
169+
await seedJournal([
170+
{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" },
171+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
172+
{ path: "src/b.ts", operation: "update", checkpointId: "sha-2" },
173+
])
174+
const service = serviceWith("base-0")
175+
mockedGetCheckpointService.mockResolvedValue(service)
101176

102-
const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/b.ts"], "sha-step")
177+
const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/b.ts"], "sha-2")
103178

104-
expect(outcome.checkpointId).toBe("sha-step")
179+
expect(outcome.checkpointId).toBe("sha-2")
105180
expect(outcome.files).toEqual([
106181
{ filePath: "src/a.ts", success: true },
107182
{ filePath: "src/b.ts", success: true },
108183
])
109-
expect(restoreFile).toHaveBeenCalledTimes(2)
110-
expect(restoreFile).toHaveBeenNthCalledWith(1, "sha-step", "src/a.ts")
111-
expect(restoreFile).toHaveBeenNthCalledWith(2, "sha-step", "src/b.ts")
184+
expect(service.restoreFile).toHaveBeenCalledTimes(2)
185+
expect(service.restoreFile).toHaveBeenNthCalledWith(1, "sha-1", "src/a.ts")
186+
// src/b.ts has no earlier entry: its pre-step state is the baseline.
187+
expect(service.restoreFile).toHaveBeenNthCalledWith(2, "base-0", "src/b.ts")
112188
})
113189

114-
it("rejects a file that is not part of the given step checkpoint", async () => {
115-
await appendChange(globalStorageDir, "task-rollback", {
116-
path: "src/a.ts",
117-
operation: "create",
118-
checkpointId: "sha-step",
119-
})
190+
it("keeps per-file failures isolated from the other step files", async () => {
191+
await seedJournal([
192+
{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" },
193+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
194+
{ path: "src/b.ts", operation: "create", checkpointId: "sha-2" },
195+
])
196+
const service = serviceWith("base-0")
197+
service.restoreFile.mockRejectedValueOnce(new Error("pathspec did not match"))
198+
mockedGetCheckpointService.mockResolvedValue(service)
199+
200+
const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/b.ts"], "sha-2")
201+
202+
expect(outcome.files[0].success).toBe(false)
203+
expect(outcome.files[0].error).toContain("pathspec did not match")
204+
expect(outcome.files[1]).toEqual({ filePath: "src/b.ts", success: true })
205+
})
206+
207+
it("fails the file cleanly when no earlier checkpoint exists and the baseline is unavailable", async () => {
208+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-2" }])
209+
const service = serviceWith(undefined)
210+
mockedGetCheckpointService.mockResolvedValue(service)
211+
212+
const outcome = await rollbackStep(makeTask(), ["src/a.ts"], "sha-2")
213+
214+
expect(outcome.checkpointId).toBe("sha-2")
215+
expect(outcome.files).toEqual([
216+
{ filePath: "src/a.ts", success: false, error: "No checkpoint available to restore" },
217+
])
218+
expect(service.restoreFile).not.toHaveBeenCalled()
219+
})
120220

121-
const restoreFile = vi.fn().mockResolvedValue(undefined)
122-
mockedGetCheckpointService.mockResolvedValue({ restoreFile })
221+
it("rejects a file that is not part of the given step checkpoint", async () => {
222+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-2" }])
223+
const service = serviceWith("base-0")
224+
mockedGetCheckpointService.mockResolvedValue(service)
123225

124-
const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/other.ts"], "sha-step")
226+
const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/other.ts"], "sha-2")
125227

126228
expect(outcome.files[0]).toEqual({ filePath: "src/a.ts", success: true })
127229
expect(outcome.files[1].success).toBe(false)
128230
expect(outcome.files[1].error).toBe("File is not part of this step's checkpoint")
129-
expect(restoreFile).toHaveBeenCalledTimes(1)
231+
expect(service.restoreFile).toHaveBeenCalledTimes(1)
130232
})
131233

132234
it("falls back to the latest journal entry per file without a step checkpoint id", async () => {
133-
await appendChange(globalStorageDir, "task-rollback", {
134-
path: "src/a.ts",
135-
operation: "create",
136-
checkpointId: "sha-1",
137-
})
138-
await appendChange(globalStorageDir, "task-rollback", {
139-
path: "src/a.ts",
140-
operation: "update",
141-
checkpointId: "sha-2",
142-
})
143-
144-
const restoreFile = vi.fn().mockResolvedValue(undefined)
145-
mockedGetCheckpointService.mockResolvedValue({ restoreFile })
235+
await seedJournal([
236+
{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" },
237+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
238+
])
239+
const service = serviceWith("base-0")
240+
mockedGetCheckpointService.mockResolvedValue(service)
146241

147242
const outcome = await rollbackStep(makeTask(), ["src/a.ts"])
148243

149-
expect(outcome.checkpointId).toBe("sha-2")
150-
expect(restoreFile).toHaveBeenCalledWith("sha-2", "src/a.ts")
244+
expect(outcome.checkpointId).toBeUndefined()
245+
expect(outcome.files).toEqual([{ filePath: "src/a.ts", success: true }])
246+
expect(service.restoreFile).toHaveBeenCalledWith("sha-2", "src/a.ts")
151247
})
152248

153-
it("fails listed files without journal entries and keeps the checkpoint when resolvable", async () => {
154-
await appendChange(globalStorageDir, "task-rollback", {
155-
path: "src/a.ts",
156-
operation: "create",
157-
checkpointId: "sha-1",
158-
})
159-
160-
const restoreFile = vi.fn().mockResolvedValue(undefined)
161-
mockedGetCheckpointService.mockResolvedValue({ restoreFile })
249+
it("fails listed files without journal entries", async () => {
250+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
251+
const service = serviceWith("base-0")
252+
mockedGetCheckpointService.mockResolvedValue(service)
162253

163254
const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/missing.ts"])
164255

165-
expect(outcome.checkpointId).toBe("sha-1")
166256
expect(outcome.files[0]).toEqual({ filePath: "src/a.ts", success: true })
167257
expect(outcome.files[1].success).toBe(false)
168258
expect(outcome.files[1].error).toBe("No change journal entry for this file")
@@ -175,24 +265,77 @@ describe("rollbackStep (B3a)", () => {
175265
providerRef: { deref: vi.fn().mockReturnValue(undefined) },
176266
} as unknown as Task
177267

178-
const restoreFile = vi.fn().mockResolvedValue(undefined)
179-
mockedGetCheckpointService.mockResolvedValue({ restoreFile })
268+
const service = serviceWith("base-0")
269+
mockedGetCheckpointService.mockResolvedValue(service)
180270

181-
const outcome = await rollbackStep(task, ["src/a.ts"], "sha-step")
271+
const outcome = await rollbackStep(task, ["src/a.ts"], "sha-2")
182272

183-
expect(outcome.checkpointId).toBe("sha-step")
273+
expect(outcome.checkpointId).toBe("sha-2")
184274
expect(outcome.files[0].success).toBe(false)
185275
expect(outcome.files[0].error).toBe("File is not part of this step's checkpoint")
186-
expect(restoreFile).not.toHaveBeenCalled()
276+
expect(service.restoreFile).not.toHaveBeenCalled()
187277
})
278+
188279
it("fails every file when checkpoints are not enabled", async () => {
189280
mockedGetCheckpointService.mockResolvedValue(undefined)
190281

191-
const outcome = await rollbackStep(makeTask(), ["src/a.ts"], "sha-step")
282+
const outcome = await rollbackStep(makeTask(), ["src/a.ts"], "sha-2")
192283

193-
expect(outcome.checkpointId).toBe("sha-step")
284+
expect(outcome.checkpointId).toBe("sha-2")
194285
expect(outcome.files).toEqual([
195286
{ filePath: "src/a.ts", success: false, error: "Checkpoints are not enabled for this task" },
196287
])
197288
})
198289
})
290+
291+
describe("restoreLatestFile (B3c: forward direction)", () => {
292+
it("restores the file to its most recent recorded write checkpoint", async () => {
293+
await seedJournal([
294+
{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" },
295+
{ path: "src/b.ts", operation: "update", checkpointId: "sha-1" },
296+
{ path: "src/a.ts", operation: "update", checkpointId: "sha-2" },
297+
])
298+
const service = serviceWith("base-0")
299+
mockedGetCheckpointService.mockResolvedValue(service)
300+
301+
const outcome = await restoreLatestFile(makeTask(), "src/a.ts")
302+
303+
expect(outcome).toEqual({ filePath: "src/a.ts", success: true })
304+
expect(service.restoreFile).toHaveBeenCalledWith("sha-2", "src/a.ts")
305+
})
306+
307+
it("is a successful no-op for a file the task never wrote", async () => {
308+
await seedJournal([{ path: "src/b.ts", operation: "update", checkpointId: "sha-1" }])
309+
const service = serviceWith("base-0")
310+
mockedGetCheckpointService.mockResolvedValue(service)
311+
312+
const outcome = await restoreLatestFile(makeTask(), "src/a.ts")
313+
314+
expect(outcome).toEqual({ filePath: "src/a.ts", success: true, noOp: true })
315+
expect(service.restoreFile).not.toHaveBeenCalled()
316+
})
317+
318+
it("fails cleanly when checkpoints are not enabled", async () => {
319+
mockedGetCheckpointService.mockResolvedValue(undefined)
320+
321+
const outcome = await restoreLatestFile(makeTask(), "src/a.ts")
322+
323+
expect(outcome).toEqual({
324+
filePath: "src/a.ts",
325+
success: false,
326+
error: "Checkpoints are not enabled for this task",
327+
})
328+
})
329+
330+
it("reports the service error without throwing", async () => {
331+
await seedJournal([{ path: "src/a.ts", operation: "create", checkpointId: "sha-1" }])
332+
const service = serviceWith("base-0")
333+
service.restoreFile.mockRejectedValue(new Error("index.lock held"))
334+
mockedGetCheckpointService.mockResolvedValue(service)
335+
336+
const outcome = await restoreLatestFile(makeTask(), "src/a.ts")
337+
338+
expect(outcome.success).toBe(false)
339+
expect(outcome.error).toContain("index.lock")
340+
})
341+
})

0 commit comments

Comments
 (0)