output

type Column[T any] struct {
	// Header is the column heading. Prose: it may be reworded freely, because no
	// machine reads it.
	Header string

	// Cell renders one row in this column.
	Cell func(T) string
}

type DiffData struct {
	// Text is the complete pretty rendering, without a trailing newline. Style
	// it freely: it is written through the wrapped stream, so escapes are
	// stripped when the destination cannot render them.
	Text string

	// Records are the machine's projection, one object per NDJSON line in the
	// order given. Their json tags are the public contract, not the text.
	Records []any
}

type Format string

type JSONWriter struct {
	// contains filtered or unexported fields
}

type PrettyWriter struct {
	// contains filtered or unexported fields
}

type TableData struct {
	// Headers are the column headings, in order.
	Headers []string

	// Cells are the rendered rows, each with one entry per header.
	Cells [][]string

	// Records are the source rows, one per entry in Cells, marshalled as-is by
	// [JSONWriter.WriteTable].
	Records []any
}

type Writer interface {
	// Info reports normal progress on stderr. Progress is narration, not the
	// result the command exists to produce: it must not land in the file when a
	// user redirects stdout. If a command needs a result line that is not a
	// table, that is a new method, not this one.
	Info(format string, args ...any)

	// Warn reports a recoverable problem on stderr — a skipped repository, say.
	Warn(format string, args ...any)

	// Error reports a failure on stderr.
	Error(format string, args ...any)

	// WriteErr renders err as an error-level message on stderr. JSON output
	// carries an "error_kind" field when err wraps a known labelsync sentinel.
	WriteErr(err error)

	// WriteEvent reports a structured diagnostic on stderr: pretty output writes
	// the formatted text, JSON output marshals record and ignores the text.
	//
	// It is [Writer.Warn] for the messages a machine has to act on rather than
	// read — today, the rate-limit countdown, where a consumer needs the number of
	// seconds left and the resume time as fields rather than as a sentence it
	// would have to parse back out.
	//
	// stderr, not stdout, and deliberately: this is the story of making the
	// product, not the product. record must carry its own "level" so the stderr
	// stream stays one shape.
	WriteEvent(record any, format string, args ...any)

	// WriteTable renders a prepared table. Pretty output aligns the cells into a
	// bordered table; JSON output marshals one source record per line.
	//
	// Call [Table] rather than this: the generic constructor is what keeps the
	// cells aligned with the headers and pairs each rendered row with the record
	// it came from.
	WriteTable(t TableData)

	// WriteDiff renders a prepared diff on stdout. Pretty output writes the
	// assembled text; JSON output emits one object per record and ignores the
	// text entirely, so the stdout stream stays one typed object per line.
	//
	// This is the third product-level method, and it exists because a diff is
	// neither a table nor a single value: it is grouped, ragged, and ends in a
	// summary. Call `plan.Render` rather than this — the vocabulary of actions
	// belongs to the planner, not to output.
	WriteDiff(d DiffData)

	// WriteResult renders a single-line result on stdout: the product of a
	// command whose answer is not a table. Pretty output writes the formatted
	// text; JSON output marshals record and ignores the text entirely, so the
	// stdout stream stays one typed object per line.
	//
	// This is not a general-purpose print. A command reaches for it only when its
	// whole answer is one value — `labelsync version` — and a user piping stdout
	// would expect exactly that value in the file. Anything narrating the work is
	// [Writer.Info], on stderr.
	WriteResult(record any, format string, args ...any)
}