Skip to content
zit Artifact [5b02ecfed0]
Login

Artifact [5b02ecfed0]

Artifact 5b02ecfed02029134b4786ba3b7399d3479f33ef388dfbae6ea308e278e656bf:


//! `zit log`: walk a check-in's ancestry, or one PATH's history, newest
//! first.

const std = @import("std");
const zit = @import("zit");
const cli = @import("zit").cli;
const cmd_sync = @import("sync.zig");
const logstore = @import("zit").logstore;
const storage = @import("zit").storage;
const Repository = @import("zit").Repository;
const Io = std.Io;
const artifact = zit.artifact;
const diagnostics = @import("../diagnostics.zig");
const help_pages = @import("../help.zig");
const reasonOf = diagnostics.reasonOf;
const stateOom = diagnostics.stateOom;
const not_a_repo_msg = diagnostics.not_a_repo_msg;
const repoOpenFail = diagnostics.repoOpenFail;
const packSeedBlob = cmd_sync.packSeedBlob;
const packSeedCheckin = cmd_sync.packSeedCheckin;
const packEvolvingBlob = cmd_sync.packEvolvingBlob;
const packOpenWritable = cmd_sync.packOpenWritable;
const packOpenReadOnly = cmd_sync.packOpenReadOnly;
const log_help = help_pages.log_help;

// The PATH walk is the library core's, shared with the daemon's `log`.
const filelog = zit.filelog;
const LogRow = filelog.LogRow;
const LogRows = filelog.LogRows;
const PathProbe = filelog.PathProbe;
const walkLog = filelog.walkLog;
const walkLogDerived = filelog.walkLogDerived;
const loadPathIndex = filelog.loadPathIndex;

/// `log CHECKIN PATH -F json`: the check-ins the PATH walk lists, in its
/// order, each with what it did to PATH (`filelog.Entry` has the fields).
/// `time` is RFC 3339 with milliseconds, under its own name because
/// Fossil's `timestamp` is an integer. A version whose content is absent by
/// policy has a null `size` and a `content` field naming why (purged,
/// shunned or elided); no other row carries `content`.
fn runLogPathJson(
    gpa: std.mem.Allocator,
    io: std.Io,
    streams: cli.Streams,
    root_dir: std.Io.Dir,
    repo: *Repository,
    root_id: []const u8,
    q: filelog.PathQuery,
    after: ?[]const u8,
) cli.Exit {
    // The text walk decides which check-ins are listed and in what order, so
    // the two forms can never disagree on that.
    var arena_state = std.heap.ArenaAllocator.init(gpa);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var rows: LogRows = .{ .arena = arena, .after = after };
    // One row past a page says whether another follows, as the daemon's
    // page does, so the document can name the cursor of the next.
    var walk_q = q;
    if (q.limit) |n| walk_q.limit = n + 1;
    var discard: std.Io.Writer.Discarding = .init(&.{});
    // The rows' facts are the walk's own answers: each row's content and
    // its parent's were reconstructed to list it, so they are read back
    // from the walk's memos rather than rebuilt.
    var plaintext: logstore.PlaintextCache = .{};
    defer plaintext.deinit(gpa);
    var probe = PathProbe.init(gpa, &plaintext);
    defer probe.deinit(gpa);
    const walked = runLogPath(gpa, io, .{ .out = &discard.writer, .err = streams.err }, root_dir, repo, root_id, walk_q, &rows, &probe);
    if (walked != .ok) return walked;
    const kept = rows.rows.items;
    const shown = if (q.limit) |n| kept[0..@min(n, kept.len)] else kept;
    const next: ?[]const u8 = if (shown.len < kept.len)
        (filelog.formatCursor(arena, root_id, shown[shown.len - 1].id) catch return stateOom(streams, "log"))
    else
        null;
    // Under the differential seam the rows are read with fresh memos, as
    // they were before they reused the walk's.
    var fresh_plaintext: logstore.PlaintextCache = .{};
    defer fresh_plaintext.deinit(gpa);
    var fresh = PathProbe.init(gpa, &fresh_plaintext);
    defer fresh.deinit(gpa);
    const rows_probe = if (Repository.parse_every_node) &fresh else &probe;
    var why: AbsenceCtx = .{ .gpa = gpa, .io = io, .root_dir = root_dir, .repo = repo };
    var aw: std.Io.Writer.Allocating = .init(gpa);
    defer aw.deinit();
    var jw: std.json.Stringify = .{ .writer = &aw.writer };
    writeLogPathJson(gpa, arena, repo, rows_probe, &jw, shown, q.path, if (q.limit != null) .{ .next = next } else .none, why.classify()) catch |e| switch (e) {
        error.OutOfMemory, error.WriteFailed => return stateOom(streams, "log"),
        error.Storage => {
            streams.err.writeAll("zit log: cannot read repository: input/output error\n") catch {};
            return .failure;
        },
        else => {
            streams.err.writeAll("zit log: cannot read repository: repository is corrupt\n") catch {};
            return .failure;
        },
    };
    aw.writer.writeByte('\n') catch return stateOom(streams, "log");
    streams.out.writeAll(aw.written()) catch {};
    return .ok;
}

/// `cmd_sync.absenceOf` in the core's words, for `filelog.entryOf`.
const AbsenceCtx = struct {
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    repo: *Repository,

    fn classify(self: *AbsenceCtx) filelog.Classify {
        return .{ .ctx = self, .absence = absence };
    }

    fn absence(ctx: ?*anyopaque, hash: []const u8) zit.feed.Absence {
        const self: *AbsenceCtx = @ptrCast(@alignCast(ctx.?));
        return switch (cmd_sync.absenceOf(self.gpa, self.io, self.root_dir, self.repo, hash)) {
            .thinned => .purged,
            .shunned => .shunned,
            .erased => .erased,
            .elided => .elided,
            .missing => .missing,
        };
    }
};

fn writeLogPathJson(
    gpa: std.mem.Allocator,
    arena: std.mem.Allocator,
    repo: *Repository,
    probe: *PathProbe,
    jw: *std.json.Stringify,
    rows: []const LogRow,
    path: []const u8,
    /// Under `-n`, the document names where the next page starts: the
    /// daemon's cursor, null on the last page.
    cursor: union(enum) { none, next: ?[]const u8 },
    classify: filelog.Classify,
) !void {
    try jw.beginObject();
    try jw.objectField("schema_version");
    try jw.write(1);
    try jw.objectField("name");
    try jw.write(path);
    try jw.objectField("checkins");
    try jw.beginArray();
    for (rows) |row| try filelog.writeEntry(jw, try filelog.entryOf(gpa, arena, repo, probe, row, classify), filelog.plainText);
    try jw.endArray();
    switch (cursor) {
        .none => {},
        .next => |c| {
            try jw.objectField("cursor");
            try jw.write(c);
        },
    }
    try jw.endObject();
}

/// `zit log CHECKIN PATH` — the PATH-restricted ancestry walk (B-log-2). Opens
/// the `Repository` facade for the §8 effective-set query, then reuses the
/// unfiltered walk, gating each check-in on the change predicate, and lists
/// what it keeps newest first, as `timeline` orders check-ins. `follow` continues below a rename
/// under the old name. `rows`, when given, receives each listed row with
/// its names. `root_dir` is borrowed (the caller closes it after this
/// returns).
fn runLogPath(
    gpa: std.mem.Allocator,
    io: std.Io,
    streams: cli.Streams,
    root_dir: std.Io.Dir,
    repo: *Repository,
    root_id: []const u8,
    q: filelog.PathQuery,
    rows: ?*LogRows,
    probe: *PathProbe,
) cli.Exit {
    const log = repo.logStore(gpa) catch |e| return repoOpenFail(streams, "log", e);

    // Answer the change predicate from the file index when it can be
    // trusted. Building it costs one pass that reads each manifest once;
    // the walk that used to reconstruct one per visited check-in cost that much
    // per QUERY. Any refusal leaves the index null and the walk computes the
    // same answer the old way.
    var index = loadPathIndex(gpa, io, root_dir, repo, log) catch |e| switch (e) {
        error.OutOfMemory => return stateOom(streams, "log"),
    };
    defer if (index) |*ix| ix.deinit(gpa);

    const walked = filelog.walkPath(gpa, repo, log, if (index) |*ix| ix else null, root_id, q, streams.out, rows, probe);
    walked catch |e| {
        switch (e) {
            error.MissingRoot => {
                streams.err.print("zit log: check-in '{s}' not found\n", .{root_id}) catch {};
                cli.horizonNameHint(gpa, io, root_dir, streams, "log");
            },
            error.InvalidRoot => streams.err.print("zit log: check-in '{s}' is not a valid manifest\n", .{root_id}) catch {},
            error.InvalidTarget => streams.err.writeAll("zit log: reachable check-in is not a valid manifest\n") catch {},
            error.Corrupt => streams.err.writeAll("zit log: cannot read repository: repository is corrupt\n") catch {},
            error.Storage => streams.err.writeAll("zit log: cannot read repository: input/output error\n") catch {},
            error.OutOfMemory => streams.err.writeAll("zit log: out of memory\n") catch {},
        }
        return .failure;
    };
    if (rows) |r| if (r.after != null) {
        streams.err.writeAll("zit log: cursor invalid: its row is not in this walk (another path or --no-follow); start again without one\n") catch {};
        return .cursor_invalid;
    };
    return .ok;
}

pub fn runLog(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    verb_args: []const []const u8,
    streams: cli.Streams,
    amb: cli.Ambient,
) cli.Exit {
    const parsed = switch (cli.parseLogArgs(verb_args)) {
        .ok => |p| p,
        .unknown_option => |tok| return cli.usageError(streams, "log", .unknown_option, tok),
        .extra_argument => |tok| return cli.usageError(streams, "log", .extra_argument, tok),
        .bad_limit => |tok| return cli.usageError(streams, "log", .bad_limit, tok),
        .bad_offset => |tok| return cli.usageError(streams, "log", .bad_offset, tok),
    };
    if (parsed.help) {
        streams.out.writeAll(log_help) catch {};
        return .ok;
    }
    const name = parsed.checkin orelse
        return cli.usageError(streams, "log", .no_checkin, "");
    if (parsed.json and parsed.path == null) {
        streams.err.writeAll("zit log: -F json needs PATH: it reports one file's history\n") catch {};
        return .usage;
    }
    if ((parsed.offset != 0 or parsed.cursor != null) and parsed.path == null) {
        streams.err.writeAll("zit log: --offset and --cursor need PATH: they page one file's history\n") catch {};
        return .usage;
    }
    const cursor: ?filelog.Cursor = if (parsed.cursor) |text| filelog.parseCursor(text) orelse {
        streams.err.writeAll("zit log: cursor invalid: not a cursor 'log -F json' issued; start again without one\n") catch {};
        return .cursor_invalid;
    } else null;

    const root = (cli.resolveRoot(arena, io, amb.repo_override) catch {
        streams.err.writeAll("zit log: out of memory\n") catch {};
        return .failure;
    }) orelse {
        streams.err.writeAll(not_a_repo_msg) catch {};
        return .failure;
    };
    var root_dir = root.dir;
    defer root_dir.close(io);

    // One open, on the zero-parse image path, shared by name resolution, the
    // PATH route and the default listing. `log` used to open the repository
    // with the default mode, which is the full record replay meant for write
    // verbs, and did so twice for a symbolic name; on a million-artifact store
    // that was most of a second before the first row. Nothing here needs what
    // the image does not carry: adjacency, the tag surface and the file index
    // all ride on it. A bare `--long` listing of a full ID opens it too, for
    // the event times a date tag may have moved off the D card (repo-state
    // §4.2 step 6). Fast-read already degrades to a derive on its own, so a
    // failed open is a real fault and is reported, never papered over.
    const literal_id = artifact.validateName(name);
    var repo: Repository = undefined;
    repo.open(gpa, io, root_dir, .{ .mode = .fast_read }) catch |e| return repoOpenFail(streams, "log", e);
    defer repo.deinit(gpa);

    // A full lowercase-hex ID walks exactly as it always has. Anything else —
    // a prefix, a branch, a tag, a reserved form — goes through the §8.3
    // resolver `zit info` uses, then walks by the resolved full ID.
    // A cursor carries the check-in its walk started from, and wins over
    // CHECKIN as it wins over the daemon's `from`, so the pages of one walk
    // stay that walk's while new check-ins land.
    const root_id: []const u8 = if (cursor) |c| blk: {
        const held = if (repo.lookup(c.root)) |rid| repo.state().mtimeOf(rid) != null else false;
        if (!held) {
            streams.err.writeAll("zit log: cursor invalid: the check-in it walks from is not in this store; start again without one\n") catch {};
            return .cursor_invalid;
        }
        break :blk c.root;
    } else if (literal_id) name else blk: {
        const rid = repo.resolve(name, .checkin) catch |e| {
            switch (e) {
                error.NotFound => {
                    streams.err.print("zit log: check-in '{s}' not found\n", .{name}) catch {};
                    cli.horizonNameHint(gpa, io, root_dir, streams, "log");
                },
                error.Ambiguous => streams.err.print("zit log: name '{s}' is ambiguous\n", .{name}) catch {},
                error.OutOfMemory => streams.err.writeAll("zit log: out of memory\n") catch {},
            }
            return .failure;
        };
        break :blk arena.dupe(u8, repo.hashOf(rid)) catch {
            streams.err.writeAll("zit log: out of memory\n") catch {};
            return .failure;
        };
    };

    // With a PATH the walk is restricted to the check-ins that change it
    // (B-log-2), a route that needs the `Repository` facade for §8 effective-set
    // queries; without one the walk is byte-identical to the shipped behavior
    // (B-log-1), so the no-PATH path below is left exactly as it was.
    if (parsed.path) |path| {
        const q: filelog.PathQuery = .{
            .path = path,
            .limit = parsed.limit,
            .offset = parsed.offset,
            .long = parsed.long and !parsed.json,
            .follow = !parsed.no_follow,
        };
        const after: ?[]const u8 = if (cursor) |c| c.after else null;
        if (parsed.json) return runLogPathJson(gpa, io, streams, root_dir, &repo, root_id, q, after);
        var plaintext: logstore.PlaintextCache = .{};
        defer plaintext.deinit(gpa);
        var probe = PathProbe.init(gpa, &plaintext);
        defer probe.deinit(gpa);
        var rows: LogRows = .{ .arena = arena, .after = after };
        const exit = runLogPath(gpa, io, streams, root_dir, &repo, root_id, q, if (after != null) &rows else null, &probe);
        if (exit == .ok) cli.horizonHistoryNote(gpa, io, root_dir, streams, "log");
        return exit;
    }

    // The default listing prints an ID per check-in and reads nothing else, so
    // it takes the derived adjacency and touches no artifact content -- see
    // `walkLogDerived` for why that is the fossil-shaped answer. `--long` needs
    // the D/U/C cards, which only the manifest carries (the derive keeps the
    // comment and mtime but not the user), so it stays on the reading walk.
    if (!parsed.long) {
        if (repo.lookup(root_id) != null) {
            walkLogDerived(gpa, &repo, root_id, streams.out, parsed.limit, null, false, null, null) catch |e| {
                switch (e) {
                    error.MissingRoot => {
                        streams.err.print("zit log: check-in '{s}' not found\n", .{root_id}) catch {};
                        cli.horizonNameHint(gpa, io, root_dir, streams, "log");
                        return .failure;
                    },
                    error.OutOfMemory => {
                        streams.err.writeAll("zit log: out of memory\n") catch {};
                        return .failure;
                    },
                    else => return .failure,
                }
            };
            cli.horizonHistoryNote(gpa, io, root_dir, streams, "log");
            return .ok;
        }
        // A root the derive never saw: fall through to the reading walk,
        // which needs no derived state at all.
    }

    var file = cli.openStoreRead(io, root_dir) catch |e| {
        streams.err.print("zit log: cannot read repository: {s}\n", .{reasonOf(e)}) catch {};
        return .failure;
    };
    defer file.close(io);
    const log_st = file.stat(io) catch {
        streams.err.writeAll("zit log: cannot read repository: input/output error\n") catch {};
        return .failure;
    };
    var fs = storage.FileStorage.init(io, file, log_st.size);
    var log = logstore.LogStore.openReadOnly(gpa, fs.storageFile()) catch |e| {
        switch (e) {
            error.OutOfMemory => streams.err.writeAll("zit log: out of memory\n") catch {},
            else => streams.err.print("zit log: cannot read repository: {s}\n", .{reasonOf(e)}) catch {},
        }
        return .failure;
    };
    defer log.deinit(gpa);

    walkLog(gpa, &log, root_id, streams.out, null, parsed.limit, parsed.long, &repo, null, null) catch |e| {
        switch (e) {
            error.MissingRoot => {
                streams.err.print("zit log: check-in '{s}' not found\n", .{root_id}) catch {};
                cli.horizonNameHint(gpa, io, root_dir, streams, "log");
            },
            error.InvalidRoot => streams.err.print("zit log: check-in '{s}' is not a valid manifest\n", .{root_id}) catch {},
            error.InvalidTarget => streams.err.writeAll("zit log: reachable check-in is not a valid manifest\n") catch {},
            error.Corrupt => streams.err.writeAll("zit log: cannot read repository: repository is corrupt\n") catch {},
            error.Storage => streams.err.writeAll("zit log: cannot read repository: input/output error\n") catch {},
            error.OutOfMemory => streams.err.writeAll("zit log: out of memory\n") catch {},
        }
        return .failure;
    };
    cli.horizonHistoryNote(gpa, io, root_dir, streams, "log");
    return .ok;
}

/// Seed a `depth`-deep linear check-in chain into `log` (index 0 = the deepest
/// ancestor, index depth-1 = the tip), filling `names_out` with each check-in's
/// 64-hex name. The deepest check-in's sole P parent is a check-in NOT stored
/// here — a phantom. Used to witness `walkLog`'s windowed early exit: the
/// phantom line is emitted only if the walk descends past the deepest ancestor.
fn logSeedPhantomChain(
    gpa: std.mem.Allocator,
    log: *logstore.LogStore,
    comptime depth: usize,
    names_out: *[depth][64]u8,
) !void {
    try log.putConfig(.{ .hash_policy = 2, .default_branch = "trunk", .project_id = "pid", .project_code = "code-abc" });
    // A valid 64-hex name for content deliberately absent from the store.
    var phantom: [64]u8 = undefined;
    _ = zit.artifact.artifactName(.sha3_256, "unstored-parent", &phantom);
    var i: usize = 0;
    while (i < depth) : (i += 1) {
        const v = try packEvolvingBlob(gpa, @intCast(i + 1));
        defer gpa.free(v);
        const b = try packSeedBlob(log, v);
        const parent: []const u8 = if (i == 0) &phantom else &names_out[i - 1];
        var ts_buf: [32]u8 = undefined;
        const ts = try std.fmt.bufPrint(&ts_buf, "2020-01-{d:0>2}T00:00:00", .{i + 1});
        try packSeedCheckin(gpa, log, ts, parent, "f.txt", &b, &names_out[i]);
    }
    try log.commit();
}

/// Count the lines of `text` that begin with `prefix` (test-only line tally).
fn logCountLinePrefix(text: []const u8, prefix: []const u8) usize {
    var n: usize = 0;
    var it = std.mem.splitScalar(u8, text, '\n');
    while (it.next()) |line| {
        if (std.mem.startsWith(u8, line, prefix)) n += 1;
    }
    return n;
}

test "log walk: `zit log CHECKIN` prints every reachable ancestor in P-card DFS order then the missing parent as a phantom" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const depth = 6;
    var names: [depth][64]u8 = undefined;
    {
        var wfs: storage.FileStorage = undefined;
        var wlog = try packOpenWritable(gpa, io, tmp.dir, &wfs);
        defer wfs.file.close(io);
        defer wlog.deinit(gpa);
        try logSeedPhantomChain(gpa, &wlog, depth, &names);
    }
    var sfs: storage.FileStorage = undefined;
    var log = try packOpenReadOnly(gpa, io, tmp.dir, &sfs);
    defer sfs.file.close(io);
    defer log.deinit(gpa);

    const tip: []const u8 = &names[depth - 1];

    // The unbounded walk prints all `depth` check-ins tip->root in P-card DFS
    // order, then the deepest ancestor's phantom parent — exactly once each.
    var buf: [4096]u8 = undefined;
    var w = Io.Writer.fixed(&buf);
    try walkLog(gpa, &log, tip, &w, null, null, false, null, null, null);
    const out = w.buffered();
    try std.testing.expectEqual(@as(usize, depth), logCountLinePrefix(out, "checkin "));
    try std.testing.expectEqual(@as(usize, 1), logCountLinePrefix(out, "phantom "));

    var ebuf: [4096]u8 = undefined;
    var stream = Io.Writer.fixed(&ebuf);
    var d: usize = depth;
    while (d > 0) : (d -= 1) stream.print("checkin {s}\n", .{names[d - 1][0..]}) catch unreachable;
    const want_checkins = stream.buffered();
    try std.testing.expectEqualStrings(want_checkins, out[0..want_checkins.len]);
}