Something went wrong. Try again.
Convert CSV banking statements to hledger journals
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405//! Atomic target creation (M1-JRN-013, M1-JRN-014, M1-SAFE-002, M1-SAFE-003).//!//! DESIGN_M1.md D7: write a sibling temporary file, then hard-link it to the//! target. The link fails with PathAlreadyExists when anything occupies that//! path, which gives both halves of M1-JRN-014 -- atomic creation, and refusal//! to overwrite -- from one syscall.//!//! The point of doing it this way is what it makes unnecessary. There is no//! pre-flight existence check, so there is no window between checking and//! creating in which a target could appear. M1-PROJ-014 requires that a target//! created after discovery but before finalization never be treated as//! writable, and here that holds because the kernel decides, not us.//!//! No fsync. Milestone one does not treat process interruption: an interrupted//! run may leave a temporary file, which is inert, and the target either//! exists complete or does not exist. Ordinary write errors are covered,//! because a failed write never reaches the link.
const std = @import("std");const diag = @import("diag.zig");
pub const Error = error{ FinalizeFailed, OutOfMemory };
/// A file to write: the directory it goes in, the path within it, and the/// bytes. `finalize` and `replace` differ in how they put it there, not in/// what they are given.const Target = @This();
contents: []const u8,path: []const u8,root: std.Io.Dir,
/// Creates `self.path` under `self.root` holding `self.contents`, or/// fails leaving everything as it was.pub fn finalize(self: Target, arena: std.mem.Allocator, io: std.Io, diags: *diag.List) Error!void { // A sibling of the target, so the link stays within one filesystem. const temporary = try self.temporaryFor(arena, io);
self.root.writeFile(io, .{ .sub_path = temporary, .data = self.contents }) catch { // Nothing was linked, so no target exists (M1-JRN-013). // zlinter-disable-next-line no_swallow_error - a cleanup failure must not mask the write failure self.root.deleteFile(io, temporary) catch {}; return self.report(diags, "the journal could not be written", .{}); };
self.root.hardLink(temporary, self.root, self.path, io, .{}) catch |err| { // Only ever remove our own temporary: whatever is at the target // belongs to someone else and must be left untouched (M1-SAFE-002). // zlinter-disable-next-line no_swallow_error - a cleanup failure must not mask the link failure self.root.deleteFile(io, temporary) catch {}; return switch (err) { error.PathAlreadyExists => self.report( diags, "something already exists there, and an approved journal is never overwritten", .{}, ), else => self.report(diags, "the target could not be created", .{}), }; };
// The target is now a second name for the same content; the temporary name // is redundant (M1-SAFE-003: only the target remains). // zlinter-disable-next-line no_swallow_error - the target exists, so a stray temporary is harmless self.root.deleteFile(io, temporary) catch {};}
/// Replaces `self.path` under `self.root` with `self.contents`,/// atomically. Unlike `finalize`, an existing file is the expected case:/// M1-UI-017 rewrites the configured rules file in place, and every/// reader either sees the whole old file or the whole new one.////// The temporary is a sibling for the same reason as above -- rename works/// only within a filesystem -- and only ever the rules file is touched/// (M1-UI-017: the manifest, CSVs and journals are not).pub fn replace(self: Target, arena: std.mem.Allocator, io: std.Io, diags: *diag.List) Error!void { const temporary = try self.temporaryFor(arena, io);
self.root.writeFile(io, .{ .sub_path = temporary, .data = self.contents }) catch { // zlinter-disable-next-line no_swallow_error - a cleanup failure must not mask the write failure self.root.deleteFile(io, temporary) catch {}; return self.report(diags, "the file could not be written", .{}); };
// Nothing is unlinked first: an interrupted rename leaves the old file. self.root.rename(temporary, self.root, self.path, io) catch { // zlinter-disable-next-line no_swallow_error - a cleanup failure must not mask the rename failure self.root.deleteFile(io, temporary) catch {}; return self.report(diags, "the file could not be replaced", .{}); };}
/// Random rather than derived, so two runs cannot collide on one name.fn temporaryFor(self: Target, arena: std.mem.Allocator, io: std.Io) Error![]const u8 { var bytes: [8]u8 = undefined; io.random(&bytes); return arena.print("{s}.tmp{x}", .{ self.path, std.mem.readInt(u64, &bytes, .little), });}
/// The caller's sentence stands on its own rather than continuing the path,/// so the two join with a colon: "'2026.csv.journal': the journal could not/// be written".fn report(self: Target, diags: *diag.List, comptime fmt: []const u8, args: anytype) Error { diags.addFmt("'{s}': " ++ fmt, .{self.path} ++ args, .{ .file = self.path }) catch return error.OutOfMemory; return error.FinalizeFailed;}
// -- 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 order = @import("util/order.zig");
const Tree = struct { tmp: std.testing.TmpDir,
fn init() Tree { return .{ .tmp = std.testing.tmpDir(.{ .iterate = true }) }; }
fn deinit(self: *Tree) void { self.tmp.cleanup(); }
fn write(self: *Tree, path: []const u8, data: []const u8) !void { try self.tmp.dir.writeFile(test_io, .{ .sub_path = path, .data = data }); }
fn read(self: *Tree, arena: std.mem.Allocator, path: []const u8) ![]const u8 { return self.tmp.dir.readFileAlloc(test_io, path, arena, .unlimited); }
fn names(self: *Tree, arena: std.mem.Allocator) ![]const []const u8 { var list: std.ArrayList([]const u8) = .empty; var entries = self.tmp.dir.iterate(); while (try entries.next(test_io)) |entry| { try list.append(arena, try arena.dupe(u8, entry.name)); } order.sortBytewise(list.items); return list.items; }
fn finalizeInto( self: *Tree, arena: std.mem.Allocator, path: []const u8, contents: []const u8, ) Error!void { const diags = diag.List.create(arena) catch return error.OutOfMemory; const target: Target = .{ .root = self.tmp.dir, .path = path, .contents = contents }; return target.finalize(arena, test_io, diags); }};
test "M1-JRN-014: the target is created with exactly the given contents" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.finalizeInto(alloc, "2026.csv.journal", "2026-09-11 x\n"); try expectEqualStrings("2026-09-11 x\n", try tree.read(alloc, "2026.csv.journal"));}
test "M1-SAFE-003: only the target is left behind" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.finalizeInto(alloc, "out.journal", "x\n"); const entries = try tree.names(alloc); try expectEqual(@as(usize, 1), entries.len); try expectEqualStrings("out.journal", entries[0]);}
test "M1-JRN-011: empty contents produce a zero-byte target" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.finalizeInto(alloc, "empty.journal", ""); try expectEqualStrings("", try tree.read(alloc, "empty.journal"));}
test "M1-JRN-014: an existing file at the target is refused and left alone" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.write("taken.journal", "original\n"); try expectError(error.FinalizeFailed, tree.finalizeInto(alloc, "taken.journal", "replacement\n")); try expectEqualStrings("original\n", try tree.read(alloc, "taken.journal"));}
test "M1-AC-007: identical contents are refused too, not quietly accepted" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
// M1-JRN-014 is explicit: never rewrite, even when the candidate would be // structurally equal. try tree.write("same.journal", "identical\n"); try expectError(error.FinalizeFailed, tree.finalizeInto(alloc, "same.journal", "identical\n")); try expectEqualStrings("identical\n", try tree.read(alloc, "same.journal"));}
test "M1-AC-007: any filesystem object at the target refuses creation" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.tmp.dir.createDirPath(test_io, "occupied.journal"); try expectError(error.FinalizeFailed, tree.finalizeInto(alloc, "occupied.journal", "x\n"));}
test "M1-SAFE-002: a refused finalization leaves no temporary behind" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.write("taken.journal", "original\n"); const before = try tree.names(alloc); _ = tree.finalizeInto(alloc, "taken.journal", "x\n") catch {}; const after = try tree.names(alloc);
try expectEqual(before.len, after.len); for (before, after) |b, c| try expectEqualStrings(b, c);}
test "M1-JRN-013: a target in a subdirectory is created there" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.tmp.dir.createDirPath(test_io, "bank"); try tree.finalizeInto(alloc, "bank/2026.csv.journal", "x\n"); try expectEqualStrings("x\n", try tree.read(alloc, "bank/2026.csv.journal"));
// The temporary was a sibling of the target, so nothing is left in it. var bank = try tree.tmp.dir.openDir(test_io, "bank", .{ .iterate = true }); defer bank.close(test_io); var count: usize = 0; var entries = bank.iterate(); while (try entries.next(test_io)) |_| count += 1; try expectEqual(@as(usize, 1), count);}
test "M1-JRN-014: a refusal is reported with the target path" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc);
try tree.write("taken.journal", "original\n"); const target: Target = .{ .root = tree.tmp.dir, .path = "taken.journal", .contents = "x\n" }; _ = target.finalize(alloc, test_io, diags) catch {};
try expect(!diags.isEmpty()); try expectEqualStrings("taken.journal", diags.items.items[0].file.?);}
test "M1-JRN-014: two finalizations of the same target, the second refuses" { var tree = Tree.init(); defer tree.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator();
try tree.finalizeInto(alloc, "once.journal", "first\n"); try expectError(error.FinalizeFailed, tree.finalizeInto(alloc, "once.journal", "second\n")); try expectEqualStrings("first\n", try tree.read(alloc, "once.journal"));}
test "M1-UI-017: replacing swaps the contents of an existing file" { var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); try tmp.dir.writeFile(test_io, .{ .sub_path = "rules.yaml", .data = "old\n" });
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var diags = diag.List.init(alloc);
try Target.replace(.{ .root = tmp.dir, .path = "rules.yaml", .contents = "new\n" }, alloc, test_io, &diags);
const after = try tmp.dir.readFileAlloc(test_io, "rules.yaml", alloc, .unlimited); try std.testing.expectEqualStrings("new\n", after); try expectEqual(@as(usize, 0), diags.items.items.len);}
test "M1-UI-017: replacing creates the file when it is absent" { var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var diags = diag.List.init(alloc);
try Target.replace(.{ .root = tmp.dir, .path = "rules.yaml", .contents = "new\n" }, alloc, test_io, &diags); const after = try tmp.dir.readFileAlloc(test_io, "rules.yaml", alloc, .unlimited); try std.testing.expectEqualStrings("new\n", after);}
test "M1-UI-017: replacing swaps the file rather than writing over it" { var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); try tmp.dir.writeFile(test_io, .{ .sub_path = "rules.yaml", .data = "old\n" }); // A second name for the file as it stands. If the replacement wrote into // the existing file instead of renaming a new one over it, this name // would see the new contents -- and a reader holding the file open during // the save would see a half-written one. try tmp.dir.hardLink("rules.yaml", tmp.dir, "witness", test_io, .{});
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var diags = diag.List.init(alloc);
try Target.replace(.{ .root = tmp.dir, .path = "rules.yaml", .contents = "new\n" }, alloc, test_io, &diags);
try std.testing.expectEqualStrings( "old\n", try tmp.dir.readFileAlloc(test_io, "witness", alloc, .unlimited), );}
test "M1-UI-017: replacing leaves no temporary behind" { var tmp = std.testing.tmpDir(.{ .iterate = true }); defer tmp.cleanup(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var diags = diag.List.init(alloc);
try Target.replace(.{ .root = tmp.dir, .path = "rules.yaml", .contents = "new\n" }, alloc, test_io, &diags);
var count: usize = 0; var iterator = tmp.dir.iterate(); while (try iterator.next(test_io)) |_| count += 1; try expectEqual(@as(usize, 1), count);}
test "M1-UI-017: a failed replace leaves the old file and says so" { var tmp = std.testing.tmpDir(.{ .iterate = true }); defer tmp.cleanup(); try tmp.dir.writeFile(test_io, .{ .sub_path = "rules.yaml", .data = "old\n" }); // A directory cannot be renamed over by a file, so the rename fails after // the temporary has been written. try tmp.dir.createDirPath(test_io, "adir");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); var diags = diag.List.init(alloc);
try std.testing.expectError( error.FinalizeFailed, Target.replace(.{ .root = tmp.dir, .path = "adir", .contents = "new\n" }, alloc, test_io, &diags), ); try expectEqual(@as(usize, 1), diags.items.items.len); try expect(std.mem.find(u8, diags.items.items[0].message, "adir") != null);
// And the temporary is gone, not left next to the rules file. var count: usize = 0; var iterator = tmp.dir.iterate(); while (try iterator.next(test_io)) |_| count += 1; try expectEqual(@as(usize, 2), count);}
test "M1-SAFE-004: report reports exhaustion rather than the finalize failure" { // Recording the diagnostic is the only allocation `report` makes, and it // makes it from the list's own arena. var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 }); var diags = diag.List.init(failing.allocator()); defer diags.deinit();
// `report` only ever reads the path; nothing here touches the directory. const target: Target = .{ .root = .cwd(), .path = "data/2026.csv.journal", .contents = "" }; const outcome: Error = target.report(&diags, "could not be written", .{}); try expectEqual(Error.OutOfMemory, outcome);}