Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
24.2 KB
Raw Blame
//! grok-build-style directory listing, served as `codedb list_dir`.
//!
//! Not a new catalog tool (that tax is how #574 lost its first A/B). The
//! model already has `codedb` and is told to prefer it over bash ls. This
//! subcommand is in-process — PathConfine, extra `--add-dir` roots, works
//! without a codedb binary. The same command lives in the codedb repo
//! (`src/list_dir.zig` there, issue #696) for CLI/MCP; keep the output
//! aligned. `codedb ls` / `tree` remain index queries.
//!
//! BFS seed of depth-1 first, then a budgeted deep walk. `.gitignore` (and
//! `.git/info/exclude`) hide noise. Output is capped at 10k characters;
//! unexpanded dirs collapse to `[N files in subtree: K *.ext, …]`.
//! `.git` is never listed. Other dotfiles stay visible (`.github` is load-
//! bearing here; grok-build hides every dot).
//! A path that does not exist answers with its closest siblings and the
//! parent's entries (list_dir_nearmiss.zig) instead of a bare not-found.

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;

const tools = @import("tools.zig");
const approvals = @import("approvals.zig");
const gitignore = @import("gitignore.zig");
const nearmiss = @import("list_dir_nearmiss.zig");

pub const max_output_chars: usize = 10_000;
pub const max_walk_items: usize = 20_000;
pub const top_k_exts: usize = 3;

const root_truncation_notice =
    \\    ...
    \\
    \\Note: this directory is too large to list fully. Try codedb list_dir on a narrower path, or use codedb search / bash.
;

const walk_truncation_notice =
    \\
    \\Note: the 20000-entry scan limit was reached; the listing and subtree counts may be incomplete.
;

const Node = struct {
    name: []const u8,
    is_dir: bool,
    depth: usize,
    parent: ?*Node,
    kids: std.ArrayList(*Node),
    file_count: usize,
    ext: std.StringHashMap(usize),
    expanded: bool,
    partial: bool = false,
};

fn newNode(arena: Allocator, name: []const u8, is_dir: bool, depth: usize, parent: ?*Node) !*Node {
    const n = try arena.create(Node);
    n.* = .{
        .name = name,
        .is_dir = is_dir,
        .depth = depth,
        .parent = parent,
        .kids = .empty,
        .file_count = 0,
        .ext = std.StringHashMap(usize).init(arena),
        .expanded = false,
    };
    return n;
}

fn extKey(arena: Allocator, name: []const u8) ![]const u8 {
    const dot = std.mem.lastIndexOfScalar(u8, name, '.') orelse return "no-ext";
    if (dot == 0 or dot + 1 == name.len) return "no-ext";
    const raw = name[dot + 1 ..];
    const out = try arena.alloc(u8, raw.len);
    for (raw, out) |c, *d| d.* = std.ascii.toLower(c);
    return out;
}

fn addFile(arena: Allocator, node: *Node, name: []const u8) !void {
    const key = try extKey(arena, name);
    var p: ?*Node = node;
    while (p) |n| {
        n.file_count += 1;
        const gop = try n.ext.getOrPut(key);
        if (!gop.found_existing) gop.value_ptr.* = 0;
        gop.value_ptr.* += 1;
        p = n.parent;
    }
}

fn join(arena: Allocator, a: []const u8, b: []const u8) ![]const u8 {
    if (a.len == 0) return b;
    return std.fmt.allocPrint(arena, "{s}/{s}", .{ a, b });
}

fn isGitComponent(name: []const u8) bool {
    return std.mem.eql(u8, name, ".git");
}

const Walk = struct {
    io: Io,
    arena: Allocator,
    root_abs: []const u8,
    rules: std.ArrayList(gitignore.Rule),
    items: usize = 0,
    scanned: usize = 0,
    truncated: bool = false,
};

fn skip(w: *Walk, abs: []const u8, is_dir: bool) !bool {
    if (isGitComponent(std.fs.path.basename(abs))) return true;
    return gitignore.ignored(w.arena, w.rules.items, w.root_abs, abs, is_dir);
}

fn fill(w: *Walk, node: *Node, rel: []const u8) !void {
    const abs = if (rel.len == 0) w.root_abs else try join(w.arena, w.root_abs, rel);
    var dir = try Io.Dir.cwd().openDir(w.io, abs, .{ .iterate = true, .follow_symlinks = false });
    defer dir.close(w.io);

    // Load rules before the bounded scan, regardless of directory entry order.
    if (rel.len > 0) {
        if (dir.openFile(w.io, ".gitignore", .{ .follow_symlinks = false })) |opened| {
            var file = opened;
            defer file.close(w.io);
            if ((try file.stat(w.io)).kind == .file) {
                var buffer: [4096]u8 = undefined;
                var reader = file.reader(w.io, &buffer);
                const text = try reader.interface.allocRemaining(w.arena, .limited(64 * 1024));
                const extra = try gitignore.parse(w.arena, text, abs);
                try w.rules.appendSlice(w.arena, extra);
            }
        } else |err| switch (err) {
            error.FileNotFound, error.SymLinkLoop => {},
            else => return err,
        }
    }
    var it = dir.iterate();
    while (true) {
        // Count physical entries, including ignored entries and symlinks. Do not
        // enumerate or allocate an unbounded directory before applying the cap.
        if (w.scanned >= max_walk_items) {
            w.truncated = true;
            return;
        }
        const ent = (try it.next(w.io)) orelse return;
        w.scanned += 1;
        if (ent.kind == .sym_link or isGitComponent(ent.name)) continue;
        const is_dir = ent.kind == .directory;
        const child_abs = try join(w.arena, abs, ent.name);
        if (try skip(w, child_abs, is_dir)) continue;
        const name = try w.arena.dupe(u8, ent.name);
        const child = try newNode(w.arena, name, is_dir, node.depth + 1, node);
        try node.kids.append(w.arena, child);
        if (!is_dir) try addFile(w.arena, node, name);
        w.items += 1;
    }
}

fn nameLess(_: void, a: *Node, b: *Node) bool {
    const an = a.name;
    const bn = b.name;
    const n = @min(an.len, bn.len);
    var i: usize = 0;
    while (i < n) : (i += 1) {
        const ca = std.ascii.toLower(an[i]);
        const cb = std.ascii.toLower(bn[i]);
        if (ca < cb) return true;
        if (ca > cb) return false;
    }
    return an.len < bn.len;
}

fn sortTree(n: *Node, partial: bool) void {
    n.partial = partial;
    @import("stable_sort.zig").sort(*Node, n.kids.items, {}, nameLess);
    for (n.kids.items) |k| sortTree(k, partial);
}

const ExtPair = struct { k: []const u8, n: usize };

fn extLess(_: void, a: ExtPair, b: ExtPair) bool {
    if (a.n != b.n) return a.n > b.n;
    return std.mem.lessThan(u8, a.k, b.k);
}

fn summary(arena: Allocator, n: *Node) ![]const u8 {
    if (n.file_count == 0) return "";
    var pairs: std.ArrayList(ExtPair) = .empty;
    var it = n.ext.iterator();
    while (it.next()) |e| try pairs.append(arena, .{ .k = e.key_ptr.*, .n = e.value_ptr.* });
    @import("stable_sort.zig").sort(ExtPair, pairs.items, {}, extLess);
    const take = @min(pairs.items.len, top_k_exts);
    var aw: Io.Writer.Allocating = .init(arena);
    const word: []const u8 = if (n.file_count == 1) "file" else "files";
    if (n.partial) try aw.writer.writeAll("[at least ") else try aw.writer.writeByte('[');
    try aw.writer.print("{d} {s} in subtree: ", .{ n.file_count, word });
    var shown: usize = 0;
    for (pairs.items[0..take], 0..) |p, i| {
        if (i > 0) try aw.writer.writeAll(", ");
        if (std.mem.eql(u8, p.k, "no-ext")) {
            try aw.writer.print("{d} *no-ext", .{p.n});
        } else {
            try aw.writer.print("{d} *.{s}", .{ p.n, p.k });
        }
        shown += p.n;
    }
    if (shown < n.file_count) try aw.writer.writeAll(", ...");
    try aw.writer.writeByte(']');
    return aw.writer.buffered();
}

fn writeKidLine(w: *Io.Writer, n: *Node, child: *Node) !void {
    var i: usize = 0;
    while (i < n.depth + 1) : (i += 1) try w.writeAll("  ");
    try w.writeAll("- ");
    try w.writeAll(child.name);
    if (child.is_dir) try w.writeByte('/');
    try w.writeByte('\n');
}

fn renderKids(arena: Allocator, n: *Node) ![]const u8 {
    var aw: Io.Writer.Allocating = .init(arena);
    for (n.kids.items) |child| {
        try writeKidLine(&aw.writer, n, child);
        if (!child.is_dir) continue;
        if (child.expanded) {
            try aw.writer.writeAll(try renderKids(arena, child));
        } else {
            const sum = try summary(arena, child);
            if (sum.len == 0) continue;
            var i: usize = 0;
            while (i < n.depth + 2) : (i += 1) try aw.writer.writeAll("  ");
            try aw.writer.writeAll(sum);
            try aw.writer.writeByte('\n');
        }
    }
    return aw.writer.buffered();
}

fn truncateRoot(arena: Allocator, root: *Node, budget: usize) ![]const u8 {
    var aw: Io.Writer.Allocating = .init(arena);
    var used: usize = 0;
    for (root.kids.items) |child| {
        var chunk: Io.Writer.Allocating = .init(arena);
        try writeKidLine(&chunk.writer, root, child);
        if (child.is_dir) {
            const sum = try summary(arena, child);
            if (sum.len > 0) {
                try chunk.writer.writeAll("    ");
                try chunk.writer.writeAll(sum);
                try chunk.writer.writeByte('\n');
            }
        }
        const bytes = chunk.writer.buffered();
        if (used + bytes.len > budget) break;
        try aw.writer.writeAll(bytes);
        used += bytes.len;
    }
    try aw.writer.writeAll(root_truncation_notice);
    return aw.writer.buffered();
}

fn budgetExpand(arena: Allocator, root: *Node, max_chars: usize, walk_cut: bool) ![]const u8 {
    const cutoff: []const u8 = if (walk_cut) walk_truncation_notice else "";
    if (root.kids.items.len == 0) return cutoff;
    root.expanded = true;
    const first = try renderKids(arena, root);
    if (first.len > max_chars) {
        return std.fmt.allocPrint(arena, "{s}{s}", .{ try truncateRoot(arena, root, max_chars), cutoff });
    }
    var remaining = max_chars - first.len;
    var q: std.ArrayList(*Node) = .empty;
    for (root.kids.items) |k| {
        if (k.is_dir) try q.append(arena, k);
    }
    var qi: usize = 0;
    while (qi < q.items.len) : (qi += 1) {
        const node = q.items[qi];
        node.expanded = true;
        const expanded = try renderKids(arena, node);
        const sum = try summary(arena, node);
        const sum_cost: usize = if (sum.len == 0) 0 else (node.depth + 1) * 2 + sum.len + 1;
        if (expanded.len > remaining + sum_cost) {
            node.expanded = false;
            continue;
        }
        remaining += sum_cost;
        remaining -= expanded.len;
        for (node.kids.items) |k| {
            if (k.is_dir) try q.append(arena, k);
        }
    }
    return std.fmt.allocPrint(arena, "{s}{s}", .{ try renderKids(arena, root), cutoff });
}

fn walkTree(io: Io, arena: Allocator, abs: []const u8) !struct { root: *Node, truncated: bool } {
    const climbed = try gitignore.loadClimb(io, arena, abs);
    var w: Walk = .{
        .io = io,
        .arena = arena,
        .root_abs = abs,
        .rules = .empty,
    };
    try w.rules.appendSlice(arena, climbed);
    const root = try newNode(arena, "", true, 0, null);
    try fill(&w, root, "");
    var q: std.ArrayList(struct { n: *Node, rel: []const u8 }) = .empty;
    for (root.kids.items) |k| {
        if (k.is_dir) try q.append(arena, .{ .n = k, .rel = k.name });
    }
    var qi: usize = 0;
    while (qi < q.items.len and !w.truncated) : (qi += 1) {
        const item = q.items[qi];
        try fill(&w, item.n, item.rel);
        for (item.n.kids.items) |k| {
            if (k.is_dir) try q.append(arena, .{ .n = k, .rel = try join(arena, item.rel, k.name) });
        }
    }
    sortTree(root, w.truncated);
    return .{ .root = root, .truncated = w.truncated };
}

fn stripDot(path: []const u8) []const u8 {
    const t = std.mem.trim(u8, path, " \t");
    if (t.len == 0) return ".";
    if (std.mem.eql(u8, t, ".") or std.mem.eql(u8, t, "./")) return ".";
    if (std.mem.startsWith(u8, t, "./")) return t[2..];
    return t;
}

/// Render a listing for an already-resolved absolute directory.
pub fn listAbs(io: Io, arena: Allocator, abs: []const u8, display: []const u8) ![]const u8 {
    const walked = try walkTree(io, arena, abs);
    const body = try budgetExpand(arena, walked.root, max_output_chars, walked.truncated);
    const trimmed = std.mem.trimEnd(u8, body, "\n");
    if (trimmed.len == 0) return std.fmt.allocPrint(arena, "- {s}/", .{display});
    return std.fmt.allocPrint(arena, "- {s}/\n{s}", .{ display, trimmed });
}

fn resolveAbs(gpa: Allocator, path: []const u8, agent_cwd: ?[]const u8) ![]const u8 {
    if (std.fs.path.isAbsolute(path)) return path;
    if (agent_cwd) |base| return std.fmt.allocPrint(gpa, "{s}/{s}", .{ base, path });
    return path;
}

/// PathConfine + list. `rest` is everything after `list_dir` in the codedb command.
pub fn run(io: Io, gpa: Allocator, rest: []const u8, agent_cwd: ?[]const u8) !tools.ToolOutput {
    const path = stripDot(rest);
    if (!approvals.confinedPath(path) or !approvals.noSymlinkEscape(io, path, agent_cwd))
        return tools.outsideCwd(gpa, path);

    var scratch = std.heap.ArenaAllocator.init(gpa);
    defer scratch.deinit();
    const arena = scratch.allocator();

    const resolved = try resolveAbs(gpa, path, agent_cwd);
    defer if (resolved.ptr != path.ptr) gpa.free(resolved);

    const st = Io.Dir.cwd().statFile(io, resolved, .{}) catch |err| switch (err) {
        error.FileNotFound => return .{
            .text = try std.fmt.allocPrint(gpa, "Error: {s} was not found.{s}", .{ path, nearmiss.suggest(io, arena, resolved, path, agent_cwd) orelse "" }),
            .is_error = true,
        },
        error.AccessDenied => return .{
            .text = try std.fmt.allocPrint(gpa, "Permission denied: {s}", .{path}),
            .is_error = true,
        },
        else => return .{
            .text = try std.fmt.allocPrint(gpa, "Error: {s} is not a valid directory.", .{path}),
            .is_error = true,
        },
    };
    if (st.kind == .file) return .{
        .text = try std.fmt.allocPrint(gpa, "Error: {s} is a file, not a directory.", .{path}),
        .is_error = true,
    };
    if (st.kind != .directory) return .{
        .text = try std.fmt.allocPrint(gpa, "Error: {s} is not a valid directory.", .{path}),
        .is_error = true,
    };

    var buf: [std.fs.max_path_bytes]u8 = undefined;
    var opened = Io.Dir.cwd().openDir(io, resolved, .{}) catch return .{
        .text = try std.fmt.allocPrint(gpa, "Error: {s} is not a valid directory.", .{path}),
        .is_error = true,
    };
    defer opened.close(io);
    const n = opened.realPath(io, &buf) catch return .{
        .text = try std.fmt.allocPrint(gpa, "Error: {s} is not a valid directory.", .{path}),
        .is_error = true,
    };
    const abs = buf[0..n];
    const text = try listAbs(io, arena, abs, path);
    return .{ .text = try gpa.dupe(u8, text) };
}

pub fn exec(ctx: tools.ToolCtx, rest: []const u8) !tools.ToolOutput {
    return run(ctx.io, ctx.gpa, rest, ctx.agent_cwd);
}

fn tmpAbs(io: Io, tmp: *std.testing.TmpDir, buf: *[std.fs.max_path_bytes]u8) ![]const u8 {
    const n = try tmp.dir.realPath(io, buf);
    return buf[0..n];
}

test "lists files and dirs, hides gitignore and .git" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    tmp.dir.writeFile(io, .{ .sub_path = ".gitignore", .data = "skip.log\nbuild/\n" }) catch unreachable;
    tmp.dir.writeFile(io, .{ .sub_path = "keep.zig", .data = "x" }) catch unreachable;
    tmp.dir.writeFile(io, .{ .sub_path = "skip.log", .data = "x" }) catch unreachable;
    tmp.dir.createDirPath(io, "build") catch unreachable;
    tmp.dir.writeFile(io, .{ .sub_path = "build/a.o", .data = "x" }) catch unreachable;
    tmp.dir.createDirPath(io, ".git/objects") catch unreachable;
    tmp.dir.writeFile(io, .{ .sub_path = ".git/HEAD", .data = "ref\n" }) catch unreachable;
    tmp.dir.createDirPath(io, ".github") catch unreachable;
    tmp.dir.writeFile(io, .{ .sub_path = ".github/ci.yml", .data = "x" }) catch unreachable;

    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const abs = try tmpAbs(io, &tmp, &buf);
    const out = try listAbs(io, arena_state.allocator(), abs, ".");
    try std.testing.expect(std.mem.indexOf(u8, out, "keep.zig") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, ".github") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "skip.log") == null);
    try std.testing.expect(std.mem.indexOf(u8, out, "build") == null);
    try std.testing.expect(std.mem.indexOf(u8, out, ".git/") == null);
}

test "fat sibling collapses; later sibling still listed" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    tmp.dir.createDirPath(io, "aaa") catch unreachable;
    var i: usize = 0;
    while (i < 800) : (i += 1) {
        var name: [48]u8 = undefined;
        const n = std.fmt.bufPrint(&name, "aaa/file_with_a_longer_name_{d:0>3}.zig", .{i}) catch unreachable;
        tmp.dir.writeFile(io, .{ .sub_path = n, .data = "x" }) catch unreachable;
    }
    tmp.dir.createDirPath(io, "zzz") catch unreachable;
    tmp.dir.writeFile(io, .{ .sub_path = "zzz/tail.md", .data = "x" }) catch unreachable;

    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const abs = try tmpAbs(io, &tmp, &buf);
    const out = try listAbs(io, arena_state.allocator(), abs, "root");
    try std.testing.expect(std.mem.indexOf(u8, out, "- aaa/") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "- zzz/") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "files in subtree") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "*.zig") != null);
    try std.testing.expect(out.len < max_output_chars + root_truncation_notice.len + 64);
}

test "run refuses a file and an escaped path" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    tmp.dir.writeFile(io, .{ .sub_path = "only.txt", .data = "x" }) catch unreachable;
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const abs = try tmpAbs(io, &tmp, &buf);
    const file_abs = try std.fmt.allocPrint(std.testing.allocator, "{s}/only.txt", .{abs});
    defer std.testing.allocator.free(file_abs);

    const workspace_roots = @import("workspace_roots.zig");
    workspace_roots.resetForTest();
    defer workspace_roots.resetForTest();
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    try workspace_roots.add(io, arena_state.allocator(), abs);

    const as_file = try run(io, std.testing.allocator, file_abs, null);
    defer std.testing.allocator.free(as_file.text);
    try std.testing.expect(as_file.is_error);
    try std.testing.expect(std.mem.indexOf(u8, as_file.text, "is a file") != null);

    const escaped = try run(io, std.testing.allocator, "../outside", null);
    defer std.testing.allocator.free(escaped.text);
    try std.testing.expect(escaped.is_error);

    const listing = try run(io, std.testing.allocator, abs, null);
    defer std.testing.allocator.free(listing.text);
    try std.testing.expect(!listing.is_error);
    try std.testing.expect(std.mem.indexOf(u8, listing.text, "only.txt") != null);
}

test "not found names the closest sibling instead of a dead end" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    tmp.dir.createDirPath(io, "demos-servers") catch unreachable;
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const abs = try tmpAbs(io, &tmp, &buf);

    const out = try run(io, std.testing.allocator, "demo-server", abs);
    defer std.testing.allocator.free(out.text);
    try std.testing.expect(out.is_error);
    try std.testing.expectEqualStrings("Error: demo-server was not found. Closest match: demos-servers/. Entries in . (1): demos-servers/.", out.text);
}

test "empty directory is a header only" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const abs = try tmpAbs(io, &tmp, &buf);
    const out = try listAbs(io, arena_state.allocator(), abs, "empty");
    try std.testing.expectEqualStrings("- empty/", out);
}

test "directory enumeration cannot exceed remaining walk budget" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    for (0..8) |i| {
        var name: [32]u8 = undefined;
        try tmp.dir.writeFile(io, .{ .sub_path = try std.fmt.bufPrint(&name, "entry-{d}.txt", .{i}), .data = "x" });
    }
    var path_buf: [std.fs.max_path_bytes]u8 = undefined;
    const path_len = try tmp.dir.realPath(io, &path_buf);
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    var walk: Walk = .{ .io = io, .arena = arena.allocator(), .root_abs = path_buf[0..path_len], .rules = .empty, .items = max_walk_items - 1, .scanned = max_walk_items - 1 };
    const root = try newNode(arena.allocator(), "", true, 0, null);
    try fill(&walk, root, "");
    try std.testing.expectEqual(max_walk_items, walk.scanned);
    try std.testing.expectEqual(@as(usize, 1), root.kids.items.len);
    try std.testing.expect(walk.truncated);
}

test "bounded nested scan loads ignore rules first and labels partial counts" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    try tmp.dir.createDirPath(io, "nested");
    try tmp.dir.writeFile(io, .{ .sub_path = "nested/hidden.log", .data = "x" });
    try tmp.dir.writeFile(io, .{ .sub_path = "nested/.gitignore", .data = "*.log\n" });
    var path_buf: [std.fs.max_path_bytes]u8 = undefined;
    const path_len = try tmp.dir.realPath(io, &path_buf);
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    var walk: Walk = .{ .io = io, .arena = arena.allocator(), .root_abs = path_buf[0..path_len], .rules = .empty, .scanned = max_walk_items - 2 };
    const root = try newNode(arena.allocator(), "", true, 0, null);
    try fill(&walk, root, "nested");
    try std.testing.expectEqual(max_walk_items, walk.scanned);
    try std.testing.expect(walk.truncated);
    try std.testing.expectEqual(@as(usize, 1), root.kids.items.len);
    try std.testing.expectEqualStrings(".gitignore", root.kids.items[0].name);
    sortTree(root, walk.truncated);
    try std.testing.expect(std.mem.startsWith(u8, try summary(arena.allocator(), root), "[at least 1 file"));
}

test "nested ignore symlinks stay skipped and unreadable rules fail explicitly" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    try tmp.dir.createDirPath(io, "nested");
    try tmp.dir.writeFile(io, .{ .sub_path = "rules", .data = "*.log\n" });
    try tmp.dir.symLink(io, "../rules", "nested/.gitignore", .{});
    try tmp.dir.writeFile(io, .{ .sub_path = "nested/keep.log", .data = "x" });
    var path_buf: [std.fs.max_path_bytes]u8 = undefined;
    const path_len = try tmp.dir.realPath(io, &path_buf);
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    var walk: Walk = .{ .io = io, .arena = arena.allocator(), .root_abs = path_buf[0..path_len], .rules = .empty };
    const root = try newNode(arena.allocator(), "", true, 0, null);
    try fill(&walk, root, "nested");
    try std.testing.expectEqual(@as(usize, 1), root.kids.items.len);
    try std.testing.expectEqualStrings("keep.log", root.kids.items[0].name);
    try tmp.dir.deleteFile(io, "nested/.gitignore");
    const large = try arena.allocator().alloc(u8, 64 * 1024 + 1);
    @memset(large, 'x');
    try tmp.dir.writeFile(io, .{ .sub_path = "nested/.gitignore", .data = large });
    try std.testing.expectError(error.StreamTooLong, fill(&walk, root, "nested"));
    try std.testing.expectError(error.FileNotFound, fill(&walk, root, "missing"));
    try tmp.dir.deleteFile(io, "nested/.gitignore");
    try tmp.dir.createDirPath(io, "nested/.gitignore");
    const directory_root = try newNode(arena.allocator(), "", true, 0, null);
    try fill(&walk, directory_root, "nested");
    sortTree(directory_root, false);
    try std.testing.expectEqualStrings(".gitignore", directory_root.kids.items[0].name);
    try std.testing.expect(directory_root.kids.items[0].is_dir);
}