Something went wrong. Try again.
Convert CSV banking statements to hledger journals
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463//! Discovery and pairing (M1-PROJ-006 .. M1-PROJ-014).//!//! The convention carries the state: within the input root, `example.csv` is//! paired with the colocated `example.csv.journal`, and the sole CSV without//! one is the current import. Nothing is recorded anywhere, which is what//! M1-PROJ-017 asks for -- there is no private history store because there is//! nothing to store.//!//! Symlinks are treated by what they point at, not by being symlinks. One at a//! CSV or journal path is the file at that path, even if its target lies//! outside the root (M1-PROJ-011); one pointing at a directory is skipped//! rather than walked (M1-PROJ-010). M1-PROJ-013 excuses us from noticing that//! two names reach the same underlying file.
const std = @import("std");const diag = @import("diag.zig");const order = @import("util/order.zig");
pub const Error = error{ DiscoveryFailed, OutOfMemory };
/// Paths are relative to the input root and use '/' separators, which is the/// form M1-TPL-004 interpolates and M1-DIAG-001 reports.pub const Pair = struct { csv: []const u8, journal: []const u8,};
pub const Discovery = struct { /// The sole CSV with no journal beside it (M1-PROJ-008). current: []const u8, /// Approved history, in ascending path order (M1-SAFE-001). history: []const Pair,};
const journal_suffix = ".csv.journal";const csv_suffix = ".csv";
const Classification = enum { csv, journal, other };
/// M1-PROJ-006: exact, case-sensitive suffixes. Anything else is unrelated and/// does not affect pairing.fn classify(name: []const u8) Classification { if (std.mem.endsWith(u8, name, journal_suffix)) return .journal; if (std.mem.endsWith(u8, name, csv_suffix)) return .csv; return .other;}
pub fn discover( arena: std.mem.Allocator, io: std.Io, root: std.Io.Dir, diags: *diag.List,) Error!Discovery { var walker: Walker = .{ .arena = arena, .io = io, .diags = diags }; try walker.walk(root, "");
order.sortBytewise(walker.csvs.items); order.sortBytewise(walker.journals.items);
// M1-PROJ-009: a journal without its CSV is an orphan, not history. for (walker.journals.items) |journal| { const expected = journal[0 .. journal.len - ".journal".len]; if (!contains(walker.csvs.items, expected)) { return failAt(diags, journal, "no CSV matches this journal", .{}); } }
var history: std.ArrayList(Pair) = .empty; var current: ?[]const u8 = null;
for (walker.csvs.items) |csv| { const expected = try arena.print("{s}.journal", .{csv}); if (contains(walker.journals.items, expected)) { try history.append(arena, .{ .csv = csv, .journal = expected }); continue; } // M1-PROJ-008: exactly one CSV may be unpaired. if (current) |first| { return failAt( diags, csv, "more than one CSV has no journal; '{s}' is also unpaired", .{first}, ); } current = csv; }
return .{ .current = current orelse return failRoot( diags, "no CSV is without a journal, so there is nothing to import", .{}, ), .history = history.items, };}
const Walker = struct { arena: std.mem.Allocator, csvs: std.ArrayList([]const u8) = .empty, diags: *diag.List, io: std.Io, journals: std.ArrayList([]const u8) = .empty,
fn walk(self: *Walker, dir: std.Io.Dir, prefix: []const u8) Error!void { var iterator = dir.iterate(); while (true) { const entry = (iterator.next(self.io) catch return failAt(self.diags, prefix, "cannot be read", .{})) orelse break;
const path = try self.join(prefix, entry.name); switch (entry.kind) { .directory => { // M1-PROJ-012: a directory at a classified path is not a // regular file, so it fails rather than being walked. if (classify(entry.name) != .other) { return failAt(self.diags, path, "is a directory, not a regular file", .{}); } var child = dir.openDir(self.io, entry.name, .{ .iterate = true }) catch return failAt(self.diags, path, "cannot be opened", .{}); defer child.close(self.io); try self.walk(child, path); },
.sym_link => { const target = dir.statFile(self.io, entry.name, .{ .follow_symlinks = true }) catch { // A broken link matters only where the name is one we // would otherwise read (M1-PROJ-011). if (classify(entry.name) == .other) continue; return failAt(self.diags, path, "symlink cannot be resolved", .{}); }; // M1-PROJ-010: never walk into a directory symlink. if (target.kind == .directory) continue; try self.record(path, entry.name, target.kind); },
.block_device, .character_device, .named_pipe, .file, .unix_domain_socket, .whiteout, .door, .event_port, .unknown => { try self.record(path, entry.name, entry.kind); }, } } }
fn record( self: *Walker, path: []const u8, name: []const u8, kind: std.Io.File.Kind, ) Error!void { const classification = classify(name); // M1-PROJ-012: unrelated entries are ignored whatever they are. if (classification == .other) return; if (kind != .file) { return failAt(self.diags, path, "is not a regular file", .{}); } switch (classification) { .csv => try self.csvs.append(self.arena, path), .journal => try self.journals.append(self.arena, path), .other => unreachable, } }
fn join(self: *Walker, prefix: []const u8, name: []const u8) Error![]const u8 { if (prefix.len == 0) return self.arena.dupe(u8, name); return self.arena.print("{s}/{s}", .{ prefix, name }); }};
fn contains(haystack: []const []const u8, needle: []const u8) bool { for (haystack) |candidate| { if (std.mem.eql(u8, candidate, needle)) return true; } return false;}
/// The path is the subject of the sentence the caller supplies, so the two/// join with a space: "'bank/2026.csv' cannot be read".fn failAt( diags: *diag.List, path: []const u8, comptime fmt: []const u8, args: anytype,) Error { diags.addFmt("'{s}' " ++ fmt, .{path} ++ args, .{ .file = path }) catch return error.OutOfMemory; return error.DiscoveryFailed;}
fn failRoot(diags: *diag.List, comptime fmt: []const u8, args: anytype) Error { diags.addFmt(fmt, args, .{}) catch return error.OutOfMemory; return error.DiscoveryFailed;}
// -- 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 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 file(self: *Tree, path: []const u8) !void { if (std.Io.Dir.path.dirname(path)) |parent| { try self.tmp.dir.createDirPath(test_io, parent); } try self.tmp.dir.writeFile(test_io, .{ .sub_path = path, .data = "x\n" }); }
fn dir(self: *Tree, path: []const u8) !void { try self.tmp.dir.createDirPath(test_io, path); }
fn link(self: *Tree, target: []const u8, path: []const u8) !void { try self.tmp.dir.symLink(test_io, target, path, .{}); }
fn run(self: *Tree, arena: *std.heap.ArenaAllocator) Error!Discovery { const alloc = arena.allocator(); const diags = diag.List.create(alloc) catch return error.OutOfMemory; return discover(alloc, test_io, self.tmp.dir, diags); }};
test "M1-PROJ-006: discovery recurses and pairs by name" { var tree = Tree.init(); defer tree.deinit(); try tree.file("bank/2025.csv"); try tree.file("bank/2025.csv.journal"); try tree.file("bank/2026.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const found = try tree.run(&arena);
try expectEqualStrings("bank/2026.csv", found.current); try expectEqual(@as(usize, 1), found.history.len); try expectEqualStrings("bank/2025.csv", found.history[0].csv); try expectEqualStrings("bank/2025.csv.journal", found.history[0].journal);}
test "M1-PROJ-006: classification is case-sensitive" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); // Neither of these is a CSV, so neither affects pairing. try tree.file("b.CSV"); try tree.file("c.Csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const found = try tree.run(&arena); try expectEqualStrings("a.csv", found.current); try expectEqual(@as(usize, 0), found.history.len);}
test "M1-PROJ-006: unrelated files and directories are ignored" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.file("notes.txt"); try tree.file("README"); try tree.dir("empty"); try tree.file("deep/nested/note.md");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const found = try tree.run(&arena); try expectEqualStrings("a.csv", found.current);}
test "M1-PROJ-007: a journal pairs only when colocated and exactly named" { var tree = Tree.init(); defer tree.deinit(); try tree.file("bank/a.csv"); // Right name, wrong directory: an orphan, not a pair. try tree.file("other/a.csv.journal");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-PROJ-008: zero unpaired CSVs fails" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.file("a.csv.journal");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-PROJ-008: more than one unpaired CSV fails" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.file("b.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-PROJ-009: an orphan journal fails" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.file("ghost.csv.journal");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-PROJ-010: a directory symlink is not traversed" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.file("real/x.csv"); try tree.file("real/x.csv.journal"); // The pair under real/ is found once by ordinary recursion. Were the link // followed too, the same files would be found again under shortcut/ and // counted as a second, distinct pair. try tree.link("real", "shortcut");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const found = try tree.run(&arena); try expectEqualStrings("a.csv", found.current); try expectEqual(@as(usize, 1), found.history.len); try expectEqualStrings("real/x.csv", found.history[0].csv);}
test "M1-PROJ-011: a symlink at a CSV path is the file at that path" { var tree = Tree.init(); defer tree.deinit(); try tree.file("elsewhere/real.csv"); try tree.link("elsewhere/real.csv", "a.csv"); try tree.file("elsewhere/real.csv.journal"); try tree.link("elsewhere/real.csv.journal", "a.csv.journal"); try tree.file("current.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const found = try tree.run(&arena);
// elsewhere/real.csv is itself a CSV and pairs with its own journal, so // the link pair and the real pair are both history. try expectEqualStrings("current.csv", found.current); try expectEqual(@as(usize, 2), found.history.len);}
test "M1-PROJ-011: a broken symlink at a CSV path fails" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.link("nowhere.csv", "b.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-PROJ-012: a non-regular object at a CSV path fails" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); // A directory that happens to be named like a CSV. try tree.dir("b.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-PROJ-012: a directory named like a journal also fails" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.dir("a.csv.journal");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-SAFE-001: history comes back in a deterministic order" { var tree = Tree.init(); defer tree.deinit(); for ([_][]const u8{ "z", "a", "m" }) |name| { const csv = try std.testing.allocator.print("{s}.csv", .{name}); defer std.testing.allocator.free(csv); const journal = try std.testing.allocator.print("{s}.csv.journal", .{name}); defer std.testing.allocator.free(journal); try tree.file(csv); try tree.file(journal); } try tree.file("current.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const found = try tree.run(&arena); try expectEqual(@as(usize, 3), found.history.len); try expectEqualStrings("a.csv", found.history[0].csv); try expectEqualStrings("m.csv", found.history[1].csv); try expectEqualStrings("z.csv", found.history[2].csv);}
test "M1-AC-002: failures name what went wrong" { var tree = Tree.init(); defer tree.deinit(); try tree.file("a.csv"); try tree.file("b.csv");
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); _ = discover(alloc, test_io, tree.tmp.dir, diags) catch {}; try expect(!diags.isEmpty());
// "names what went wrong" means both paths, in the order that says which // one tripped the check and which one it collided with. A message naming // only one of them sends the reader looking for the wrong file. try expectEqualStrings( "'b.csv' more than one CSV has no journal; 'a.csv' is also unpaired", diags.items.items[0].message, );}
test "M1-PROJ-008: an empty input root fails, having no current import" { var tree = Tree.init(); defer tree.deinit();
var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.DiscoveryFailed, tree.run(&arena));}
test "M1-SAFE-004: failAt reports exhaustion rather than the discovery failure" { // Recording the diagnostic is the only allocation `failAt` 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();
const outcome: Error = failAt(&diags, "data", "is missing", .{}); try expectEqual(Error.OutOfMemory, outcome);}