//! 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); }