tiny.pretty.compact

1pub const Capacity = struct {2    limits: Limits,3    width_bytes: usize,4    output_bytes: usize,5    working_bytes: usize,67    pub fn derive(limits: Limits) error{CapacityOverflow}!Capacity {8        const width_bytes = std.math.mul(9            usize,10            limits.columns,11            @sizeOf(usize),12        ) catch return error.CapacityOverflow;13        const working_bytes = std.math.add(14            usize,15            width_bytes,16            limits.output_bytes,17        ) catch return error.CapacityOverflow;18        std.debug.assert(working_bytes >= width_bytes);19        std.debug.assert(working_bytes >= limits.output_bytes);20        return .{21            .limits = limits,22            .width_bytes = width_bytes,23            .output_bytes = limits.output_bytes,24            .working_bytes = working_bytes,25        };26    }27};

1pub const Limits = struct {2    columns: usize,3    rows: usize,4    maximum_line_bytes: usize,5    footer_bytes: usize,6    output_bytes: usize,78    pub fn inspect(9        columns: []const Column,10        rows: []const []const []const u8,11        total: ?usize,12    ) error{CapacityOverflow}!Limits {13        const maximum_line_bytes = try format.maximumLineBytes(columns, rows);14        const body_lines = std.math.add(usize, rows.len, 2) catch15            return error.CapacityOverflow;16        const body_bytes = std.math.mul(17            usize,18            maximum_line_bytes,19            body_lines,20        ) catch return error.CapacityOverflow;21        const footer_bytes = try format.footerLength(rows.len, total);22        const output_bytes = std.math.add(usize, body_bytes, footer_bytes) catch23            return error.CapacityOverflow;24        std.debug.assert(maximum_line_bytes > 0);25        std.debug.assert(output_bytes >= body_bytes);26        return .{27            .columns = columns.len,28            .rows = rows.len,29            .maximum_line_bytes = maximum_line_bytes,30            .footer_bytes = footer_bytes,31            .output_bytes = output_bytes,32        };33    }34};

1pub const RenderError = error{2    CapacityModelViolation,3    InputChanged,4};

1/// Renders a compact table into storage derived from an exact input inspection.2/// The returned slice is borrowed until the next render or `deinit`.3pub const Table = struct {4    pub const claim: alloc_phase.capacity.Declaration = .{5        .source = .{6            .id = "pretty.compact_table",7            .kind = .phase_static,8            .limit_source = .caller,9            .storage = .{10                .covered = &.{11                    .{12                        .id = "exact_per_column_width_slice",13                        .lifetime = .steady,14                        .detail = "exact per-column width slice",15                    },16                    .{17                        .id = "derived_fixed_worst_case_rendered_output_byte_slice",18                        .lifetime = .steady,19                        .detail = "derived fixed worst-case rendered-output byte slice",20                    },21                },22                .excluded = &.{23                    "caller-owned column, row, header, and cell storage",24                    "the convenience compact.table wrapper result duplicate and its caller-owned lifetime",25                    "destination writes performed after Table.render returns its borrowed output",26                    "glom-owned result preparation, references, snippets, and non-table presentation modes",27                },28            },29            .capacity = .{30                .inputs = &.{31                    alloc_phase.capacity.bindInput(TableLimits, "columns", "columns"),32                    alloc_phase.capacity.bindInput(TableLimits, "maximum_line_bytes", "maximum_line_bytes"),33                    alloc_phase.capacity.bindInput(TableLimits, "rows", "rows"),34                    alloc_phase.capacity.bindInput(TableLimits, "footer_bytes", "footer_bytes"),35                },36                .type_selectors = &.{37                    alloc_phase.capacity.bindType(usize, "usize"),38                },39                .nodes = &.{40                    .{ .input = 0 },41                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },42                    .{ .input = 1 },43                    .{ .input = 2 },44                    .{ .constant = 2 },45                    .{ .add = .{ .left = 3, .right = 4 } },46                    .{ .product = .{ .left = 2, .right = 5 } },47                    .{ .input = 3 },48                    .{ .add = .{ .left = 6, .right = 7 } },49                    .{ .add = .{ .left = 1, .right = 8 } },50                },51                .assertions = &.{.{52                    .scope = .closure_total,53                    .measure = .retained,54                    .relation = .exact,55                    .expression = 9,56                }},57            },58            .overload = .{59                .kind = .reject_before_seal,60                .detail = "capacity arithmetic overflow and initialization OOM fail before activation; render rejects changed derived capacity facts before measuring widths or writing output; content changes that preserve admitted capacity facts remain supported",61            },62            .risks = .{63                .transitive = .{64                    .status = .open,65                    .detail = "the source-reviewed fixed-writer helper chain carries no allocator capability, but no machine-checked call-graph certificate excludes future policy allocator reacquisition",66                },67                .foreign = .{68                    .status = .excluded,69                    .detail = "the owner uses process-local caller-allocated slices and a fixed in-memory writer; destination and operating-system writes are outside the owner",70                },71            },72            .obligations = &.{73                .{ .key = "pretty_compact_table_capacity_capacity_model", .role = .capacity_model },74                .{ .key = "pretty_compact_table_capacity_overload", .role = .overload },75                .{ .key = "pretty_compact_table_oom_retry", .role = .overload },76                .{ .key = "pretty_compact_table_sealed_transitive_risk", .role = .transitive_risk },77                .{ .key = "pretty_compact_table_sealed_foreign_risk", .role = .foreign_risk },78                .{ .key = "pretty_compact_table_limit_drift", .role = .custom },79                .{ .key = "pretty_compact_table_semantics", .role = .transitive_risk },80                .{ .key = "pretty_compact_table_overflow", .role = .overload },81            },82        },83        .bindings = .{84            .owner = @This(),85            .seal = .{86                .family = alloc_phase.capacity.selector(@This().activate),87                .premise = .{88                    .class = .checked_semantic_fact,89                    .authority = .checker,90                },91            },92            .teardown = .{93                .family = alloc_phase.capacity.selector(@This().deinit),94                .premise = .{95                    .class = .checked_semantic_fact,96                    .authority = .checker,97                },98            },99        },100    };101    pub const Limits = TableLimits;102    pub const Capacity = TableCapacity;103104    phase: alloc_phase.capacity.Phase,105    capacity: TableCapacity,106    widths: []usize,107    output: []u8,108    high_water: usize,109110    pub fn init(allocator: Allocator, limits: TableLimits) !Table {111        const capacity = try TableCapacity.derive(limits);112        const widths = try allocator.alloc(usize, capacity.limits.columns);113        errdefer allocator.free(widths);114        const output = try allocator.alloc(u8, capacity.output_bytes);115        return .{116            .phase = .initialization,117            .capacity = capacity,118            .widths = widths,119            .output = output,120            .high_water = 0,121        };122    }123124    pub fn activate(self: *Table) void {125        std.debug.assert(self.phase == .initialization);126        std.debug.assert(self.widths.len == self.capacity.limits.columns);127        std.debug.assert(self.output.len == self.capacity.output_bytes);128        self.phase = .steady;129    }130131    pub fn render(132        self: *Table,133        columns: []const Column,134        rows: []const []const []const u8,135        total: ?usize,136    ) RenderError![]const u8 {137        std.debug.assert(self.phase == .steady);138        const inspected = TableLimits.inspect(columns, rows, total) catch139            return error.CapacityModelViolation;140        if (!std.meta.eql(inspected, self.capacity.limits)) return error.InputChanged;141        format.measureWidths(self.widths, columns, rows);142        var writer = std.Io.Writer.fixed(self.output);143        format.renderInto(&writer, self.widths, columns, rows, total) catch144            return error.CapacityModelViolation;145        const rendered = writer.buffered();146        self.high_water = @max(self.high_water, rendered.len);147        std.debug.assert(self.high_water <= self.capacity.output_bytes);148        return rendered;149    }150151    pub fn highWater(self: *const Table) usize {152        std.debug.assert(self.phase == .steady);153        std.debug.assert(self.high_water <= self.capacity.output_bytes);154        return self.high_water;155    }156157    pub fn deinit(self: *Table, allocator: Allocator) void {158        std.debug.assert(self.phase != .teardown);159        self.phase = .teardown;160        allocator.free(self.output);161        allocator.free(self.widths);162        self.output = &.{};163        self.widths = &.{};164    }165};

1pub const Align = enum { left, right };

1pub const Column = struct {2    header: []const u8,3    max_width: usize = 40,4    alignment: Align = .left,5};

1pub const body_budget = full_cap - reserved;

1pub fn cap16kb(allocator: std.mem.Allocator, output: []const u8) ![]u8 {2    if (output.len <= body_budget) return try allocator.dupe(u8, output);3    var end: usize = 0;4    var next: usize = 0;5    while (next < output.len and next < body_budget) {6        const line_end = std.mem.indexOfScalarPos(u8, output, next, '\n') orelse break;7        if (line_end + 1 > body_budget) break;8        end = line_end + 1;9        next = line_end + 1;10    }11    var out = std.Io.Writer.Allocating.init(allocator);12    errdefer out.deinit();13    if (end != 0) try out.writer.writeAll(output[0..end]);14    try out.writer.writeAll(truncation_line);15    try out.writer.writeByte('\n');16    return try out.toOwnedSlice();17}

1pub const full_cap = 16 * 1024;

1pub const truncation_line = "(output truncated at 16 KB " ++ footer_dash ++2    " use filters or --limit to scope down, --json for exact records)";

1/// Renders one compact table into a caller-owned allocation.2pub fn table(3    allocator: Allocator,4    columns: []const Column,5    rows: []const []const []const u8,6    total: ?usize,7) ![]u8 {8    const limits = try Limits.inspect(columns, rows, total);9    var owner = try Table.init(allocator, limits);10    owner.activate();11    defer owner.deinit(allocator);12    return try allocator.dupe(u8, try owner.render(columns, rows, total));13}

1//! Bounded tables for compact terminal and agent output.2//! `Table` retains caller-sized storage; `table` returns one caller-owned allocation.34const cap = @import("cap.zig");5const table_mod = @import("table.zig");67pub const Align = table_mod.Align;8pub const Column = table_mod.Column;9pub const Table = table_mod.Table;10pub const TableLimits = table_mod.Limits;11pub const TableCapacity = table_mod.Capacity;12pub const TableRenderError = table_mod.RenderError;13pub const table = table_mod.table;14pub const cap16kb = cap.cap16kb;15pub const truncation_line = cap.truncation_line;16pub const full_cap = cap.full_cap;17pub const body_budget = cap.body_budget;

1pub const compact = @import("compact/root.zig");