//! Operation snapshots (M1-PROJ-015, M1-PROJ-016, M1-PROJ-017). //! //! M1-PROJ-015 requires each file be read at most once per invocation or //! session, and re-evaluation to reuse what was read. That is the whole point //! of this module: after `read` returns, the operation works entirely from //! these bytes, so a file rewritten underneath it cannot make one result //! reflect an older version of a file than another. //! //! M1-PROJ-016 follows from the same arrangement, though it is kept next door //! in ui/editor.zig, where the saved state is compared against the draft. //! Nothing here goes back to disk to find out what happened to a file, and an //! external edit during a session is simply not part of it. //! //! M1-PROJ-017 is satisfied by what is absent. The bytes live in the //! operation's arena and are gone when it ends; nothing is copied anywhere //! that outlives the run. const std = @import("std"); const diag = @import("diag.zig"); const discover = @import("discover.zig"); pub const Error = error{ SnapshotFailed, OutOfMemory }; pub const HistoryFiles = struct { csv: []const u8, /// Paths relative to the input root, as discovery reported them. csv_path: []const u8, journal: []const u8, journal_path: []const u8, }; const Snapshot = @This(); current_csv: []const u8, current_path: []const u8, history: []const HistoryFiles, manifest: []const u8, /// The rules file as it stood when the session opened. An interactive /// save does not come back here: the editor keeps the session's saved /// state (M1-PROJ-016), and nothing is ever reread from disk. rules: []const u8, /// Reads everything the operation will need. `base` resolves the manifest and /// rules paths; `root` resolves the discovered CSV and journal paths. /// Everything a snapshot is read from: the project directory holding the /// manifest and rules, and the input root holding the discovered files. pub const Inputs = struct { base: std.Io.Dir, found: discover.Discovery, manifest_path: []const u8, root: std.Io.Dir, rules_path: []const u8, }; pub fn read( arena: std.mem.Allocator, io: std.Io, inputs: Inputs, diags: *diag.List, ) Error!Snapshot { const base = inputs.base; const manifest_path = inputs.manifest_path; const rules_path = inputs.rules_path; const root = inputs.root; const found = inputs.found; const manifest = try readOnce(arena, io, base, manifest_path, diags); const rules = try readOnce(arena, io, base, rules_path, diags); const current_csv = try readOnce(arena, io, root, found.current, diags); const history = try arena.alloc(HistoryFiles, found.history.len); for (found.history, 0..) |pair, index| { history[index] = .{ .csv_path = pair.csv, .journal_path = pair.journal, .csv = try readOnce(arena, io, root, pair.csv, diags), .journal = try readOnce(arena, io, root, pair.journal, diags), }; } return .{ .manifest = manifest, .rules = rules, .current_path = found.current, .current_csv = current_csv, .history = history, }; } fn readOnce( arena: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, path: []const u8, diags: *diag.List, ) Error![]const u8 { // M1-SAFE-004 sets no size limit; exhaustion surfaces as an allocation // failure rather than a truncated read. return dir.readFileAlloc(io, path, arena, .unlimited) catch { diags.addFmt("'{s}' cannot be read", .{path}, .{ .file = path }) catch return error.OutOfMemory; return error.SnapshotFailed; }; } // -- tests ------------------------------------------------------------------- const expect = std.testing.expect; const expectEqual = std.testing.expectEqual; const expectEqualStrings = std.testing.expectEqualStrings; const expectError = std.testing.expectError; const test_io = std.testing.io; const Fixture = struct { tmp: std.testing.TmpDir, fn init() !Fixture { var fixture: Fixture = .{ .tmp = std.testing.tmpDir(.{ .iterate = true }) }; try fixture.write("project.yaml", "manifest v1\n"); try fixture.write("rules.yaml", "rules v1\n"); try fixture.tmp.dir.createDirPath(test_io, "data"); try fixture.write("data/2025.csv", "old csv\n"); try fixture.write("data/2025.csv.journal", "old journal\n"); try fixture.write("data/2026.csv", "new csv\n"); return fixture; } fn deinit(self: *Fixture) void { self.tmp.cleanup(); } fn write(self: *Fixture, path: []const u8, data: []const u8) !void { try self.tmp.dir.writeFile(test_io, .{ .sub_path = path, .data = data }); } fn take(self: *Fixture, arena: *std.heap.ArenaAllocator) Error!Snapshot { const alloc = arena.allocator(); const diags = diag.List.create(alloc) catch return error.OutOfMemory; var root = self.tmp.dir.openDir(test_io, "data", .{ .iterate = true }) catch return error.SnapshotFailed; defer root.close(test_io); const found = discover.discover(alloc, test_io, root, diags) catch return error.SnapshotFailed; return read(alloc, test_io, .{ .base = self.tmp.dir, .manifest_path = "project.yaml", .rules_path = "rules.yaml", .root = root, .found = found, }, diags); } /// Counts the root and the input directory, which is where a private /// store would have to appear. fn entryCount(self: *Fixture) !usize { var count: usize = 0; var root_entries = self.tmp.dir.iterate(); while (try root_entries.next(test_io)) |_| count += 1; var data = try self.tmp.dir.openDir(test_io, "data", .{ .iterate = true }); defer data.close(test_io); var data_entries = data.iterate(); while (try data_entries.next(test_io)) |_| count += 1; return count; } }; test "M1-PROJ-015: every relevant file is captured once" { var fixture = try Fixture.init(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const snapshot = try fixture.take(&arena); try expectEqualStrings("manifest v1\n", snapshot.manifest); try expectEqualStrings("rules v1\n", snapshot.rules); try expectEqualStrings("new csv\n", snapshot.current_csv); try expectEqualStrings("2026.csv", snapshot.current_path); try expectEqual(@as(usize, 1), snapshot.history.len); try expectEqualStrings("2025.csv", snapshot.history[0].csv_path); try expectEqualStrings("old csv\n", snapshot.history[0].csv); try expectEqualStrings("old journal\n", snapshot.history[0].journal); } test "M1-PROJ-015: later changes on disk do not reach the snapshot" { var fixture = try Fixture.init(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const snapshot = try fixture.take(&arena); // Everything the operation reads is rewritten underneath it. try fixture.write("project.yaml", "manifest v2\n"); try fixture.write("rules.yaml", "rules v2\n"); try fixture.write("data/2026.csv", "changed\n"); try fixture.write("data/2025.csv.journal", "changed\n"); // The snapshot is what the operation keeps working from. try expectEqualStrings("manifest v1\n", snapshot.manifest); try expectEqualStrings("rules v1\n", snapshot.rules); try expectEqualStrings("new csv\n", snapshot.current_csv); try expectEqualStrings("old journal\n", snapshot.history[0].journal); } test "M1-PROJ-017: taking a snapshot creates nothing" { var fixture = try Fixture.init(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const before = try fixture.entryCount(); _ = try fixture.take(&arena); const after = try fixture.entryCount(); try expectEqual(before, after); } test "M1-PROJ-015: an unreadable file fails the operation" { var fixture = try Fixture.init(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); var root = try fixture.tmp.dir.openDir(test_io, "data", .{ .iterate = true }); defer root.close(test_io); const found = try discover.discover(alloc, test_io, root, diags); try expectError(error.SnapshotFailed, read( alloc, test_io, .{ .base = fixture.tmp.dir, .manifest_path = "absent.yaml", .rules_path = "rules.yaml", .root = root, .found = found, }, diags, )); try expect(!diags.isEmpty()); } test "M1-PROJ-015: a history pair with no rows still snapshots" { var fixture = try Fixture.init(); defer fixture.deinit(); try fixture.write("data/2025.csv.journal", ""); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const snapshot = try fixture.take(&arena); try expectEqualStrings("", snapshot.history[0].journal); }