//! Shared parse-diagnostic rendering — the language-agnostic half of fig's
//! diagnostic system (see `languages/fig/parser.zig`'s `Location`/`Diagnostic`/
//! `Warning`, and DESIGN.md's "Authoring-time diagnostics"): locating a byte
//! offset in source text, and rendering the compiler-style `file:line:col:
//! label: message` report.
//!
//! Each language keeps its OWN `Error`/`Warning.Code` enums and `describe()`/
//! `shortLabel()` teaching-message functions (the failure modes differ per
//! format) and its own trivial `Diagnostic { code, offset, end }` /
//! `Report { diag, errors, warnings }` shape (duplicating a 3-field struct
//! per language costs nothing; duplicating the caret-rendering *behavior*
//! would). Only that offset-independent-of-code machinery lives here — fig's
//! parser re-exports `Location`/`locateOffset` from this module too (see its
//! own doc comment), so there is exactly one implementation of "find
//! line/col for a byte offset" in the whole codebase, not one per language.
//!
//! `Rendered` is the CLI/LSP-facing product: a language's `Diagnostic`/
//! `Warning` (which carries a typed `code` only that language's `describe`/
//! `shortLabel` know how to read) gets converted to a plain `Rendered` once,
//! right after parsing — so any generic consumer (the CLI's cargo-style
//! `printDiag` in `main.zig`, a future generalized language server) needs no
//! per-language knowledge at all.
const std = @import("std");
const Allocator = std.mem.Allocator;
/// 1-based line/column plus the full offending source line.
pub const Location = struct { line: usize, column: usize, line_text: []const u8 };
/// Locate `offset` in `source`. A cursor resting exactly past a newline is
/// ambiguous from the offset alone: it could mean "the problem was noticed
/// while finishing the previous line" (an unclosed container discovered only
/// at EOF) — report end-of-that-line, not column 1 of an empty next one — OR
/// it could be a token that genuinely STARTS at column 1 of a real next line
/// (e.g. a duplicate TOML key/table: almost every top-level statement has no
/// indentation at all, so its span starts exactly here). Only backtrack in
/// the FORMER case, when there is nothing at `at` to point at instead (EOF,
/// or another blank line) — a real token at column 1 must be attributed to
/// ITS OWN line, never silently reattributed to the one before it.
pub fn locateOffset(source: []const u8, offset: usize) Location {
var at = @min(offset, source.len);
if (at > 0 and source[at - 1] == '\n' and
(at >= source.len or source[at] == '\n' or source[at] == '\r'))
{
at -= 1;
}
var line: usize = 1;
var line_start: usize = 0;
for (source[0..at], 0..) |c, i| {
if (c == '\n') {
line += 1;
line_start = i + 1;
}
}
const line_end = std.mem.indexOfScalarPos(u8, source, line_start, '\n') orelse source.len;
return .{ .line = line, .column = at - line_start + 1, .line_text = source[line_start..line_end] };
}
/// The compiler-style report every language shares: `file:line:col: <label>:
/// <message>`, then the offending source line and a caret marking the column.
/// Plain/colorless — the CLI's `printDiag` (`main.zig`) lays a fancier
/// cargo/rustc-style caret report on top of `locateOffset` directly instead of
/// calling this; this form is for plain-text consumers (library callers,
/// tests, anything that just wants a string).
pub fn renderReport(w: *std.Io.Writer, loc: Location, file: []const u8, label: []const u8, message: []const u8) std.Io.Writer.Error!void {
try w.print("{s}:{d}:{d}: {s}: {s}\n", .{ file, loc.line, loc.column, label, message });
// The offending line, capped so a pathological line can't flood the
// terminal. The caret line mirrors tabs so it stays aligned under them.
const max_shown = 160;
const shown = loc.line_text[0..@min(loc.line_text.len, max_shown)];
if (shown.len == 0) return; // EOF/blank line: nothing to point into
try w.print(" {s}{s}\n", .{ shown, if (shown.len < loc.line_text.len) "…" else "" });
if (loc.column - 1 <= shown.len) {
try w.writeAll(" ");
for (shown[0 .. loc.column - 1]) |c| try w.writeByte(if (c == '\t') '\t' else ' ');
try w.writeAll("^\n");
}
}
/// `renderReport`, allocating the result. Caller owns the returned bytes.
pub fn renderReportAlloc(allocator: Allocator, source: []const u8, offset: usize, file: []const u8, label: []const u8, message: []const u8) Allocator.Error![]u8 {
const loc = locateOffset(source, offset);
var aw = std.Io.Writer.Allocating.init(allocator);
defer aw.deinit();
renderReport(&aw.writer, loc, file, label, message) catch return error.OutOfMemory;
return aw.toOwnedSlice();
}
/// A fully-resolved diagnostic ready for CLI/LSP rendering — language-agnostic.
/// Pairs a parse-time `[offset, end)` span with the language's own
/// `describe(code)` (long teaching message) / `shortLabel(code)` (a few words,
/// for a caret annotation) strings, computed once at the call site right after
/// parsing.
pub const Rendered = struct {
offset: usize,
end: ?usize = null,
message: []const u8,
short_label: []const u8,
};
const testing = std.testing;
test "locateOffset finds line/column and backtracks past a trailing newline" {
const src = "abc\ndef\nghi";
var loc = locateOffset(src, 5); // 'e' on line 2
try testing.expectEqual(@as(usize, 2), loc.line);
try testing.expectEqual(@as(usize, 2), loc.column);
try testing.expectEqualStrings("def", loc.line_text);
// Resting exactly past a newline at true EOF (nothing follows) reports
// the end of the PREVIOUS line, not column 1 of an empty next one.
loc = locateOffset("abc\n", 4);
try testing.expectEqual(@as(usize, 1), loc.line);
try testing.expectEqual(@as(usize, 4), loc.column);
try testing.expectEqualStrings("abc", loc.line_text);
// Same trailing-newline offset, but a BLANK line (not EOF) follows —
// still nothing there to point at, so this also backtracks.
loc = locateOffset("abc\n\ndef", 4);
try testing.expectEqual(@as(usize, 1), loc.line);
try testing.expectEqual(@as(usize, 4), loc.column);
// But when the offset right after a newline is the start of a line with
// REAL content (e.g. a token that genuinely begins at column 1 — the
// common case for a duplicate TOML key/table, which has no
// indentation), it must NOT be backtracked onto the previous line.
loc = locateOffset("abc\ndef\n", 4);
try testing.expectEqual(@as(usize, 2), loc.line);
try testing.expectEqual(@as(usize, 1), loc.column);
try testing.expectEqualStrings("def", loc.line_text);
}
test "renderReportAlloc renders file:line:col plus the source line and caret" {
const rendered = try renderReportAlloc(testing.allocator, "x = 1\ny = ?\n", 4, "test.txt", "error", "bad value");
defer testing.allocator.free(rendered);
try testing.expectEqualStrings(
"test.txt:1:5: error: bad value\n x = 1\n ^\n",
rendered,
);
}