diff options
| author | Can Celik <ogulcancelik@gmail.com> | 2026-09-10 21:51:57 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-09-10 21:51:57 +0300 |
| commit | 425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch) | |
| tree | e52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/src/terminal/snapshot/fixture.zig | |
| parent | 90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff) | |
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/snapshot/fixture.zig')
| -rw-r--r-- | vendor/libghostty-vt/src/terminal/snapshot/fixture.zig | 479 |
1 files changed, 479 insertions, 0 deletions
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/fixture.zig b/vendor/libghostty-vt/src/terminal/snapshot/fixture.zig new file mode 100644 index 00000000..d5c86b2b --- /dev/null +++ b/vendor/libghostty-vt/src/terminal/snapshot/fixture.zig @@ -0,0 +1,479 @@ +//! Test-only support for reviewable snapshot golden fixtures. +//! +//! Snapshot compatibility references are stored as annotated hexadecimal text +//! under `testdata/`. Each byte is written as exactly two hexadecimal digits. +//! Whitespace is insignificant, and `#` begins a comment through the end of the +//! line. This permits field, record, and absolute-offset annotations without +//! changing the bytes embedded by a test. +//! +//! `parse` validates and decodes an `@embedFile` at comptime. Tests should +//! encode their native value, compare the generated bytes with that embedded +//! reference using `expectEqual`, and then decode the reference itself. This +//! keeps encoding regression coverage separate from backwards-decoding +//! coverage. +//! +//! `expectEqual` formats a fresh candidate on every run. Matching candidates +//! remain in the test's temporary directory. A mismatch copies the candidate +//! to the repository root, reports its path and first differing byte, and +//! fails without modifying the checked-in reference. After reviewing an +//! intentional wire change, a maintainer manually replaces the reference. +//! Fixture filenames include the snapshot version so a future format adds new +//! references instead of overwriting compatibility data for an older version. +//! +//! A typical fixed-value test looks like this: +//! +//! ```zig +//! const fixture = @import("fixture.zig"); +//! +//! const reference = fixture.parse( +//! @embedFile("testdata/example-v1.hex"), +//! ); +//! +//! test "example golden encoding and decoding" { +//! var encoded: [Example.len]u8 = undefined; +//! var writer: std.Io.Writer = .fixed(&encoded); +//! try Example.encode(value, &writer); +//! +//! try fixture.expectEqual( +//! .bytes, +//! "src/terminal/snapshot/testdata/example-v1.hex", +//! "snapshot_fixture-example-v1.hex", +//! &reference, +//! writer.buffered(), +//! ); +//! +//! var reader: std.Io.Reader = .fixed(&reference); +//! try std.testing.expectEqualDeep( +//! value, +//! try Example.decode(&reader), +//! ); +//! } +//! ``` +//! +//! ## Kaitai +//! +//! Every fixture has three machine-readable comment fields: +//! +//! ```text +//! # Kaitai type: page_payload +//! # Kaitai params: +//! # Kaitai offset: 0 +//! ``` +//! +//! These select a type from `snapshot.ksy`, its whitespace-separated +//! parameters, and the byte offset where parsing begins. The Kaitai verifier +//! discovers fixtures from the filesystem and uses this metadata instead of +//! maintaining a parallel filename table. Generated candidates copy the +//! metadata from their checked-in reference. +//! + +const std = @import("std"); +const envelope = @import("envelope.zig"); +const record = @import("record.zig"); + +const log = std.log.scoped(.snapshot_fixture); + +pub const Kind = enum { + bytes, + page, + snapshot, +}; + +/// Decode an annotated hexadecimal fixture at comptime. +/// +/// Whitespace is ignored. `#` begins a comment that continues through the end +/// of the line. Every other token must be exactly two hexadecimal digits. +pub fn parse(comptime source: []const u8) [decodedLen(source)]u8 { + comptime { + // Large complete-snapshot fixtures exceed Zig's default comptime + // branch budget while scanning their comments and byte tokens. + @setEvalBranchQuota(100_000_000); + + // The first pass in decodedLen gives this result its exact array type. + // Keeping it an array lets callers use the fixture in comptime slices. + var result: [decodedLen(source)]u8 = undefined; + var source_index: usize = 0; + var result_index: usize = 0; + + while (source_index < source.len) { + // Comments and layout are purely for reviewers and contribute no + // bytes to the embedded reference. + skipIgnored(source, &source_index); + if (source_index == source.len) break; + + // Every data token is one complete byte. Parse it directly rather + // than accepting variable-width integers or other hex syntax. + if (source_index + 1 >= source.len) { + @compileError("snapshot fixture ends with one hex digit"); + } + result[result_index] = + hexNibble(source[source_index]) << 4 | + hexNibble(source[source_index + 1]); + result_index += 1; + source_index += 2; + + // Requiring a separator catches accidental third digits and makes + // the accepted grammar match the formatter below. + if (source_index < source.len and + !std.ascii.isWhitespace(source[source_index]) and + source[source_index] != '#') + { + @compileError( + "snapshot fixture hex bytes must be separated by whitespace", + ); + } + } + + return result; + } +} + +/// Compare generated bytes with a checked-in reference. +/// +/// A formatted candidate is always created in a temporary directory. On a +/// mismatch it is copied into the repository root before the test fails. +pub fn expectEqual( + kind: Kind, + reference_path: []const u8, + candidate_name: []const u8, + expected: []const u8, + actual: []const u8, +) !void { + const testing = std.testing; + const alloc = testing.allocator; + + var tmp = testing.tmpDir(.{}); + defer tmp.cleanup(); + + // Kaitai parser selection lives in the reference itself. Read the textual + // source so generated candidates preserve that metadata even though the + // byte comparison below uses the comptime-decoded reference. + const reference_source = try std.Io.Dir.cwd().readFileAlloc( + testing.io, + reference_path, + alloc, + .unlimited, + ); + defer alloc.free(reference_source); + + // Always materialize a candidate, even when it will match. This keeps the + // generation path exercised on every test run while avoiding repository + // artifacts for the normal successful case. + { + var candidate_file = try tmp.dir.createFile( + testing.io, + candidate_name, + .{}, + ); + defer candidate_file.close(testing.io); + var write_buffer: [4096]u8 = undefined; + var candidate_writer = candidate_file.writer( + testing.io, + &write_buffer, + ); + try format( + kind, + reference_source, + actual, + &candidate_writer.interface, + ); + try candidate_writer.interface.flush(); + } + + // Matching candidates remain in the temporary directory and disappear + // with its cleanup. + if (std.mem.eql(u8, expected, actual)) return; + + // The test temp directory is not necessarily below the working directory. + // Resolve both paths before copying the candidate to the stable, + // user-visible repository-root name. + const tmp_path = try tmp.dir.realPathFileAlloc( + testing.io, + candidate_name, + alloc, + ); + defer alloc.free(tmp_path); + const cwd = try std.Io.Dir.cwd().realPathFileAlloc( + testing.io, + ".", + alloc, + ); + defer alloc.free(cwd); + const candidate_path = try std.fs.path.join( + alloc, + &.{ cwd, candidate_name }, + ); + defer alloc.free(candidate_path); + try std.Io.Dir.copyFileAbsolute( + tmp_path, + candidate_path, + testing.io, + .{}, + ); + + // Report the first useful comparison point. When one byte sequence is a + // prefix of the other, this is the shared length where they diverge. + const difference = difference: { + const shared_len = @min(expected.len, actual.len); + for ( + expected[0..shared_len], + actual[0..shared_len], + 0.., + ) |expected_byte, actual_byte, index| { + if (expected_byte != actual_byte) break :difference index; + } + break :difference shared_len; + }; + log.err( + "snapshot fixture differs reference={s} candidate={s} " ++ + "offset=0x{x} expected_len={} actual_len={}", + .{ + reference_path, + candidate_path, + difference, + expected.len, + actual.len, + }, + ); + return error.TestExpectedEqual; +} + +fn decodedLen(comptime source: []const u8) usize { + comptime { + // This is a complete validation pass, not just a count. Invalid syntax + // therefore fails before parse allocates and fills its result array. + @setEvalBranchQuota(100_000_000); + + var index: usize = 0; + var result: usize = 0; + while (index < source.len) { + skipIgnored(source, &index); + if (index == source.len) break; + + if (index + 1 >= source.len) { + @compileError("snapshot fixture ends with one hex digit"); + } + _ = hexNibble(source[index]); + _ = hexNibble(source[index + 1]); + result += 1; + index += 2; + + if (index < source.len and + !std.ascii.isWhitespace(source[index]) and + source[index] != '#') + { + @compileError( + "snapshot fixture hex bytes must be separated by whitespace", + ); + } + } + return result; + } +} + +fn skipIgnored(comptime source: []const u8, index: *usize) void { + while (index.* < source.len) { + // Layout whitespace is unrestricted so fixtures can group fields and + // keep deterministic sixteen-byte output lines. + if (std.ascii.isWhitespace(source[index.*])) { + index.* += 1; + continue; + } + + // A comment consumes the rest of its line. The newline itself is + // consumed by the whitespace case on the next iteration. + if (source[index.*] != '#') return; + while (index.* < source.len and source[index.*] != '\n') { + index.* += 1; + } + } +} + +fn hexNibble(comptime value: u8) u8 { + return switch (value) { + '0'...'9' => value - '0', + 'a'...'f' => value - 'a' + 10, + 'A'...'F' => value - 'A' + 10, + else => @compileError("snapshot fixture contains a non-hex digit"), + }; +} + +fn format( + kind: Kind, + reference_source: []const u8, + bytes: []const u8, + writer: *std.Io.Writer, +) (std.Io.Writer.Error || error{InvalidKaitaiMetadata})!void { + // Every generated candidate starts with enough maintenance context to be + // understandable when copied out of a failing test's temp directory. + try writer.writeAll("# Ghostty snapshot fixture\n"); + try writeKaitaiMetadata(reference_source, writer); + try writer.print( + "# Wire version: {}\n" ++ + "# Generated by its snapshot test; review before replacing.\n" ++ + "# On mismatch, the candidate is copied to the repository root.\n", + .{envelope.version}, + ); + + // Small values only need a hex dump. Larger compound formats get + // structure-aware section labels without changing their decoded bytes. + switch (kind) { + .bytes => try writeSection( + "encoded bytes", + bytes, + 0, + bytes.len, + writer, + ), + .page => try formatPage(bytes, writer), + .snapshot => try formatSnapshot(bytes, writer), + } +} + +fn writeKaitaiMetadata( + reference_source: []const u8, + writer: *std.Io.Writer, +) (std.Io.Writer.Error || error{InvalidKaitaiMetadata})!void { + const prefixes = [_][]const u8{ + "# Kaitai type:", + "# Kaitai params:", + "# Kaitai offset:", + }; + var found = [_]bool{false} ** prefixes.len; + + var lines = std.mem.splitScalar(u8, reference_source, '\n'); + while (lines.next()) |untrimmed| { + const line = std.mem.trim(u8, untrimmed, " \r"); + for (prefixes, &found) |prefix, *seen| { + if (!std.mem.startsWith(u8, line, prefix)) continue; + if (seen.*) return error.InvalidKaitaiMetadata; + seen.* = true; + try writer.print("{s}\n", .{line}); + break; + } + } + + for (found) |seen| { + if (!seen) return error.InvalidKaitaiMetadata; + } +} + +fn formatPage( + bytes: []const u8, + writer: *std.Io.Writer, +) std.Io.Writer.Error!void { + // PAGE version 1 has a twenty-byte fixed header. The remainder is + // self-describing through the counts and dimensions in that header. + const header_end = @min(bytes.len, 20); + try writeSection("PAGE header", bytes, 0, header_end, writer); + if (header_end < bytes.len) { + try writeSection( + "style and hyperlink tables, rows, and cells", + bytes, + header_end, + bytes.len, + writer, + ); + } +} + +fn formatSnapshot( + bytes: []const u8, + writer: *std.Io.Writer, +) std.Io.Writer.Error!void { + // A complete snapshot begins with its unframed envelope. Clamp this first + // section so a partially generated candidate can still be inspected. + const envelope_end = @min(bytes.len, envelope.encoded_len); + try writeSection("snapshot envelope", bytes, 0, envelope_end, writer); + + // Walk record framing only far enough to annotate boundaries. The emitted + // hex remains authoritative; this formatter never repairs candidate data. + var offset: usize = envelope_end; + while (offset < bytes.len) { + // A partial header cannot provide a safe payload boundary, so preserve + // the remaining bytes as one explicitly incomplete section. + if (bytes.len - offset < record.Header.len) { + try writeSection( + "trailing partial record", + bytes, + offset, + bytes.len, + writer, + ); + return; + } + + // Tag and payload length are the first six bytes of every record + // header. CRC validation belongs to the codec test, not this formatter. + const tag_raw = std.mem.readInt( + u16, + bytes[offset..][0..2], + .little, + ); + const payload_len: u32 = std.mem.readInt( + u32, + bytes[offset + 2 ..][0..4], + .little, + ); + + // Clamp the section to the available candidate bytes. This makes a + // truncated payload reviewable instead of indexing beyond the slice. + const record_end: usize = @min( + bytes.len, + offset + record.Header.len + @as(usize, payload_len), + ); + + // Known tags make the annotated diff readable. Preserve unknown tags + // numerically so formatter output is still useful for encoder bugs. + if (std.enums.fromInt(record.Tag, tag_raw)) |tag| { + try writer.print( + "\n# offset 0x{x:0>8}: {s} record, payload {} bytes\n", + .{ offset, @tagName(tag), payload_len }, + ); + } else { + try writer.print( + "\n# offset 0x{x:0>8}: unknown record {}, payload {} bytes\n", + .{ offset, tag_raw, payload_len }, + ); + } + try writeHex(bytes, offset, record_end, writer); + offset = record_end; + } +} + +fn writeSection( + name: []const u8, + bytes: []const u8, + start: usize, + end: usize, + writer: *std.Io.Writer, +) std.Io.Writer.Error!void { + // Sections begin on a fresh line and carry their absolute wire offset. + try writer.print( + "\n# offset 0x{x:0>8}: {s}\n", + .{ start, name }, + ); + try writeHex(bytes, start, end, writer); +} + +fn writeHex( + bytes: []const u8, + start: usize, + end: usize, + writer: *std.Io.Writer, +) std.Io.Writer.Error!void { + const digits = "0123456789abcdef"; + var offset = start; + while (offset < end) { + // Lowercase, sixteen-byte lines provide stable textual diffs. The + // trailing offset is a comment and is ignored by parse. + const line_end = @min(end, offset + 16); + for (bytes[offset..line_end], 0..) |byte, index| { + if (index != 0) try writer.writeByte(' '); + try writer.writeByte(digits[byte >> 4]); + try writer.writeByte(digits[byte & 0x0f]); + } + try writer.print(" # 0x{x:0>8}\n", .{offset}); + offset = line_end; + } +} |
