report

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: MPL-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package report is the agent-facing result boundary: the complete Report of a build or check, its compact Summary, targeted queries over a saved report, the untrusted-file decoder, the embedded JSON Schema, and the Builder that accumulates diagnostics in stable input order.

A saved report never causes a PDF to be read. Queries describe the captured run only.

Index

Constants

View Source 
const (
	// StageUsage is a rejected command line or query.
	StageUsage Stage = "usage"
	// StageRead is reading a file, cancellation, and the byte limit.
	StageRead Stage = "read"
	// StageWrite is producing or writing a report.
	StageWrite Stage = "write"
	// StageSyntax is the JSON lexical and grammar rules.
	StageSyntax Stage = "syntax"
	// StageShape is member names, types, domains, and references.
	StageShape Stage = "shape"
	// StageLimit is the declared resource bounds.
	StageLimit Stage = "limit"

	CodeInterrupted        Code = "report_interrupted"
	CodeReadFailed         Code = "report_read_failed"
	CodeWriteFailed        Code = "report_write_failed"
	CodeTooLarge           Code = "report_too_large"
	CodeEmpty              Code = "report_json_empty"
	CodeSyntax             Code = "report_json_syntax"
	CodeDuplicateMember    Code = "report_json_duplicate_member"
	CodeTrailingData       Code = "report_json_trailing_data"
	CodeNotObject          Code = "report_not_object"
	CodeUnknownMember      Code = "report_unknown_member"
	CodeNull               Code = "report_null_not_allowed"
	CodeMissingMember      Code = "report_missing_member"
	CodeWrongType          Code = "report_wrong_type"
	CodeUnsupportedVersion Code = "report_unsupported_version"
	CodeWrongKind          Code = "report_wrong_kind"
	CodeLimitNodes         Code = "report_limit_nodes"
	CodeLimitDepth         Code = "report_limit_depth"
	CodeInvalidValue       Code = "report_invalid_value"
	CodeDanglingReference  Code = "report_dangling_reference"
	CodeDuplicateID        Code = "report_duplicate_id"
	CodeInvalidRange       Code = "report_invalid_range"

	CodeSelectionConflict  Code = "report_selection_conflict"
	CodePagingNeedsView    Code = "report_paging_needs_view"
	CodeDetailsNeedSelect  Code = "report_details_need_selection"
	CodeInvalidPaging      Code = "report_invalid_paging"
	CodeInvalidNumber      Code = "report_invalid_number"
	CodeInvalidExpectation Code = "report_invalid_expectation"
	CodeAttemptMismatch    Code = "report_attempt_mismatch"
	CodeUnknownView        Code = "report_unknown_view"
	CodePartNotFound       Code = "report_part_not_found"
	CodePageOutOfRange     Code = "report_page_out_of_range"
	CodeLayoutIncomplete   Code = "report_layout_incomplete"
)

Stages name the phase that produced a diagnostic; codes are the stable identifiers of what went wrong.

View Source 
const (
	// Version is the shared public JSON format version for responses and complete reports.
	Version = 2

	// KindReport marks a complete report.
	KindReport = "report"
	// KindSummary marks a summary of one.
	KindSummary = "summary"

	// MaxReportBytes bounds a saved report, whether written or read.
	MaxReportBytes = 256 << 20
	// MaxNesting bounds the JSON nesting of a saved report.
	MaxNesting = 64
	// MaxNodes bounds the JSON values of a saved report.
	MaxNodes = 2_000_000

	// MaxTextRunes bounds the text of one style, in Unicode scalar values.
	MaxTextRunes = 10000

	// BackgroundNone is the background of an unpainted page.
	BackgroundNone = "none"
)
View Source 
const (
	// ViewParts names the paged view of parts.
	ViewParts = "parts"
	// ViewDiagnostics names the paged view of diagnostics.
	ViewDiagnostics = "diagnostics"

	// DefaultLimit is the records of a paged view without an explicit limit.
	DefaultLimit = 20
	// MaxLimit bounds the records of a paged view.
	MaxLimit = 100
	// MaxResponseBytes bounds a paged response, except for one oversized first record.
	MaxResponseBytes = 128 << 10
)
View Source 
const (
	// SummaryBytes is the maximum encoded default result, including its newline.
	SummaryBytes = 2048

	// PreviewRunes caps a text or message preview, in Unicode scalar values.
	PreviewRunes = 160
	// PreviewDiagnostics is how many diagnostics a summary shows.
	PreviewDiagnostics = 5
)
View Source 
const (

	// SeverityError marks an error of the operation or captured run.
	SeverityError Severity = "error"
	// SeverityWarning marks a measured or detected material advisory.
	SeverityWarning Severity = "warning"
	// RecoveryCurrent means the retained file describes the actual committed failure.
	RecoveryCurrent RecoveryState = "current"
	// RecoveryPending means complete layout data remains but publication metadata could not be refreshed.
	RecoveryPending RecoveryState = "publication_pending"
	// RecoveryUnavailable means the retained file identity was lost and its content must not be trusted.
	RecoveryUnavailable RecoveryState = "unavailable"
	// StatusOK is success, exit 0.
	StatusOK Status = "ok"
	// StatusInvalid is invalid instructions or a usage error, exit 2.
	StatusInvalid Status = "invalid"
	// StatusFailed is an I/O, backend, or publication failure, exit 1.
	StatusFailed Status = "failed"
	// StatusInterrupted is cancellation, exit 130.
	StatusInterrupted Status = "interrupted"

	// PhaseNotRun means the phase never started.
	PhaseNotRun PhaseState = "not_run"
	// PhaseIncomplete means the phase stopped early.
	PhaseIncomplete PhaseState = "incomplete"
	// PhaseComplete means the phase finished without stopping early.
	PhaseComplete PhaseState = "complete"

	// PartPDF is a source PDF.
	PartPDF PartKind = "pdf"
	// PartBlank is generated pages.
	PartBlank PartKind = "blank"

	// SizeExplicit is a size written in the job.
	SizeExplicit SizeOrigin = "explicit"
	// SizeFollowingSource is a size inherited from the next source page.
	SizeFollowingSource SizeOrigin = "following_source"
	// SizePrecedingSource is a size inherited from the previous source page.
	SizePrecedingSource SizeOrigin = "preceding_source"
	// SizeFitTarget is a canvas resolved directly from the effective fit declaration.
	SizeFitTarget SizeOrigin = "fit_target"

	// ReportNotRequested means no report was requested.
	ReportNotRequested WriteState = "not_requested"
	// ReportWritten means the requested report was written.
	ReportWritten WriteState = "written"
	// ReportFailed means the requested report could not be written.
	ReportFailed WriteState = "failed"
)

Variables

This section is empty.

Functions

func ArgvID 

func ArgvID(n int) string

ArgvID is the part ID of command-line operand n.

func BoundPreview 

func BoundPreview(value string) (string, bool)

BoundPreview limits a preview by encoded JSON bytes, preserving UTF-8 and marking omissions separately.

func ContentOf 

func ContentOf[T any](response Response) (*T, bool)

ContentOf returns the response's content as a *T, and whether it is one.

func Encode 

func Encode(value any) ([]byte, error)

Encode returns the compact JSON of any report value (a summary or a query response).

func EncodePretty 

func EncodePretty(value any) ([]byte, error)

EncodePretty renders explicit complete detail as readable JSON, preserving every value.

func HexDigest 

func HexDigest(sum [sha256.Size]byte) string

HexDigest formats a SHA-256 digest as the 64 lower-case hexadecimal digits reports use.

func ParseNumber 

func ParseNumber(flag, text string) (int64, error)

ParseNumber parses a decimal integer flag value: optional minus sign, ASCII digits, nothing else, and it must fit an int64. Overflow is a usage error, never a wrapped value.

func ResponseSchema added in v0.2.0 

func ResponseSchema() string

ResponseSchema returns the local structured response union for the current format.

func Schema 

func Schema() string

Schema returns the JSON Schema (draft 2020-12) of the current saved-report format. It states the structural rules. Duplicate members, Unicode and byte-level rules, table references (source, style, and font indexes), ID uniqueness, range order and contiguity, count sums, status relations, and the byte, nesting, and node limits are enforced by Decode and Validate only.

func Write 

func Write(w io.Writer, r *Report, limit int64) (int64, error)

Write validates r and streams its compact JSON, newline terminated, to w. It stops with CodeTooLarge as soon as more than limit bytes would be written (MaxReportBytes is the format's limit), so the caller can stage next to the target before committing anything. It returns the bytes written.

Types

type Builder 

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

Builder accumulates one Report. It is safe for concurrent use, so bounded workers can add the diagnostics of their own inputs; Build orders them by input position, never by completion time.

func NewBuilder 

func NewBuilder(command string) *Builder

NewBuilder starts a report for command. All phases start as not run.

func (*Builder) AddDiagnostic 

func (b *Builder) AddDiagnostic(order int, d Diagnostic)

AddDiagnostic records a diagnostic. order is the stage's input-order key (for example a contribution or distinct-source ordinal); Build sorts stably by order, retaining append order for equal keys. Locations carry the original declaration independently of this private sorting key.

func (*Builder) AddPart 

func (b *Builder) AddPart(p Part) int

AddPart appends a part, in output order, and returns its index.

func (*Builder) AttemptID added in v0.2.0 

func (b *Builder) AttemptID() string

AttemptID identifies the report being captured without constructing a snapshot.

func (*Builder) Build 

func (b *Builder) Build(status Status) *Report

Build returns the report with the given status and the diagnostics sorted stably by input order. The builder can keep being used afterwards; the result does not share its diagnostics slice.

func (*Builder) Font 

func (b *Builder) Font(f Font) int

Font interns a font and returns its index in the fonts table.

func (*Builder) Geometry added in v0.2.0 

func (b *Builder) Geometry(geometry Geometry) int

Geometry interns captured scalar geometry so repeated styles and sources can refer to it.

func (*Builder) SetCounts 

func (b *Builder) SetCounts(c Counts)

SetCounts records the page totals; nil is unknown.

func (*Builder) SetFit added in v0.2.0 

func (b *Builder) SetFit(fit *FitDeclaration)

SetFit records the effective declaration without borrowing mutable caller locations.

func (*Builder) SetPhases 

func (b *Builder) SetPhases(p Phases)

SetPhases records how far each phase got.

func (*Builder) SetPublication 

func (b *Builder) SetPublication(p Publication)

SetPublication records the publication state.

func (*Builder) Source 

func (b *Builder) Source(s Source) int

Source interns a source and returns its index in the sources table.

func (*Builder) Style 

func (b *Builder) Style(s *Style) int

Style interns a resolved style and returns its index in the styles table, so a million identical blanks share one entry. Source and Font are interned the same way.

type Code 

type Code string

Code is a stable snake_case diagnostic identifier. Messages are not stable; codes are.

type CommandError added in v0.2.0 

type CommandError struct {
	Command            *string          `json:"command"`
	Next               *[]string        `json:"next"`
	Kind               string           `json:"kind"`
	Status             Status           `json:"status"`
	ExecutableFrom     string           `json:"executable_from,omitempty"`
	Diagnostics        []DiagnosticView `json:"diagnostics"`
	TruncatedFields    []string         `json:"truncated_fields,omitempty"`
	FormatVersion      int              `json:"format_version"`
	DiagnosticCount    int              `json:"diagnostic_count"`
	ErrorCount         int              `json:"error_count"`
	WarningCount       int              `json:"warning_count"`
	DiagnosticsOmitted int              `json:"diagnostics_omitted,omitzero"`
	NextOmitted        bool             `json:"next_omitted,omitzero"`
}

CommandError describes a command rejected before a job begins, without job lifecycle fields.

func NewCommandError added in v0.2.0 

func NewCommandError(command string, status Status, diagnostics []Diagnostic, executable string) *CommandError

NewCommandError creates a compact command failure.

func (*CommandError) RenderText added in v0.2.0 

func (e *CommandError) RenderText(w io.Writer) error

RenderText writes the current command fault and its recovery guidance.

type ContinuationReference added in v0.2.0 

type ContinuationReference struct {
	Executable string `json:"executable_from"`
	Report     string `json:"report_from"`
	Action     string `json:"action"`
	View       string `json:"view"`
	AttemptID  string `json:"expect_attempt"`
}

ContinuationReference reconstructs an omitted argv from caller-owned invocation data. Executable means the current invoking executable, never the saved report's producer. Report means --report's value for a job, or the report command's FILE operand. Relative arguments resolve in that invocation's working directory.

type Counts 

type Counts struct {
	SourcePages    *int64 `json:"source_pages"`
	GeneratedPages *int64 `json:"generated_pages"`
	TotalPages     *int64 `json:"total_pages"`
}

Counts holds page totals. A nil count is unknown, which is not zero.

type Diagnostic 

type Diagnostic struct {
	Recovery           *Recovery `json:"recovery,omitempty"`
	Location           *Location `json:"location,omitempty"`
	Severity           Severity  `json:"severity"`
	ConsequenceContext string    `json:"consequence_context,omitempty"`
	Stage              Stage     `json:"stage"`
	Code               Code      `json:"code"`
	Path               string    `json:"path,omitempty"`
	Message            string    `json:"message"`
	Cause              string    `json:"cause,omitempty"`
	Consumers          []string  `json:"consumers,omitempty"`
}

Diagnostic is one discovered problem. Codes are stable; messages are not.

type DiagnosticCounts added in v0.2.0 

type DiagnosticCounts struct {
	DiagnosticCount int `json:"diagnostic_count"`
	ErrorCount      int `json:"error_count"`
	WarningCount    int `json:"warning_count"`
}

DiagnosticCounts counts captured diagnostic records after aggregation, never pages or consumers.

type DiagnosticView 

type DiagnosticView struct {
	Recovery           *Recovery `json:"recovery,omitempty"`
	Location           *Location `json:"location,omitempty"`
	Severity           Severity  `json:"severity"`
	ConsequenceContext string    `json:"consequence_context,omitempty"`
	Stage              Stage     `json:"stage"`
	Code               Code      `json:"code"`
	Path               string    `json:"path,omitempty"`
	Message            string    `json:"message"`
	Cause              string    `json:"cause,omitempty"`
	Consumers          []string  `json:"consumers,omitempty"`

	MessageTruncated bool `json:"message_truncated,omitzero"`
	// contains filtered or unexported fields
}

DiagnosticView is a diagnostic as a query or a summary shows it: the message is cut to PreviewRunes characters and marked, unless the full record was asked for.

type Error 

type Error struct {
	// Option is request adapter metadata, not a report or wire-format member.
	Option string
	Err    error

	Diagnostic Diagnostic
	// contains filtered or unexported fields
}

Error is a coded, located report failure: a saved report that cannot be read, or a query that cannot be answered. The command layer turns Diagnostic into a structured error report and Status into the exit code.

func AsError 

func AsError(err error) (*Error, bool)

AsError returns the *Error in err's chain, if any.

func (*Error) Error 

func (e *Error) Error() string

Error formats the failure as "file: message [code]".

func (*Error) Status 

func (e *Error) Status() Status

Status is StatusInvalid for rejected input or usage, StatusFailed for a read failure, and StatusInterrupted for cancellation.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the underlying cause.

type FitDeclaration added in v0.2.0 

type FitDeclaration struct {
	Location *Location `json:"location"`
	Paper    string    `json:"paper"`
	Size     PageSize  `json:"size"`
}

FitDeclaration identifies the effective global target and where it was declared.

type Font 

type Font struct {
	Digest string `json:"digest"`
	Name   string `json:"name"`
	File   string `json:"file,omitempty"`
}

Font is the identity of a font used by a resolved style. File is the absolute path of a supplied font file and is absent for the built-in font.

type GeneratedBrief 

type GeneratedBrief struct {
	Text       *TextBrief `json:"text,omitempty"`
	Background string     `json:"background"`
	Width      float64    `json:"width"`
	Height     float64    `json:"height"`
}

GeneratedBrief is a bounded description of a generated page.

type Geometry added in v0.2.0 

type Geometry struct {
	Media    [4]float64 `json:"media_box"`
	Crop     [4]float64 `json:"crop_box"`
	Visible  [4]float64 `json:"visible_box"`
	Matrix   [6]float64 `json:"matrix"`
	Width    float64    `json:"original_width"`
	Height   float64    `json:"original_height"`
	Scale    float64    `json:"physical_scale"`
	UserUnit float64    `json:"user_unit"`
	Rotation int        `json:"rotation"`
	HasCrop  bool       `json:"has_crop_box"`
}

Geometry is captured original effective geometry and its source-to-sheet transformation. Target dimensions belong to the report's one global Fit declaration.

type GeometryEntry added in v0.2.0 

type GeometryEntry struct {
	Geometry Geometry `json:"geometry"`
	Index    int      `json:"index"`
}

GeometryEntry materializes one captured table row in a selected query.

type GeometryRange added in v0.2.0 

type GeometryRange struct {
	First    int `json:"first"`
	Last     int `json:"last"`
	Geometry int `json:"geometry"`
}

GeometryRange maps consecutive source pages to one shared geometry entry.

type Limits 

type Limits struct {
	MaxBytes   int64
	MaxNesting int
	MaxNodes   int64
}

Limits bound the decoding of an untrusted saved report.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits are the format's limits: 256 MiB, nesting 64, 2,000,000 decoded structural nodes.

type Location 

type Location struct {
	ArgvIndex *int   `json:"argv_index,omitempty"`
	Offset    *int64 `json:"offset,omitempty"`
	File      string `json:"file"`
	Pointer   string `json:"pointer,omitempty"`
	Line      int    `json:"line,omitzero"`
	Column    int    `json:"column,omitzero"`
}

Location is a Position with the JSON pointer of the node, or the zero-based command-line operand. It repeats the Position fields rather than embedding Position, which keeps the pointer-bearing fields together.

func LocationOf 

func LocationOf(loc assembly.Location) *Location

LocationOf converts a job location. A command-line operand becomes ArgvIndex instead of a pointer.

func (Location) String 

func (l Location) String() string

String formats the location as "file:line:column (byte N) at pointer".

type PageRange 

type PageRange struct {
	Start int64 `json:"start"`
	End   int64 `json:"end"`
}

PageRange is the inclusive 1-based range of output pages of a part.

type PageResponse 

type PageResponse struct {
	Geometry      *Geometry `json:"geometry,omitempty"`
	Kind          string    `json:"kind"`
	Part          PartView  `json:"part"`
	Page          int64     `json:"page"`
	PageInPart    int64     `json:"page_in_part"`
	FormatVersion int       `json:"format_version"`
}

PageResponse answers a page query: the part covering the page, and the page's 1-based position in it.

func (*PageResponse) RenderText 

func (p *PageResponse) RenderText(w io.Writer) error

RenderText writes the page's part as human text.

type PageSize 

type PageSize struct {
	Origin SizeOrigin `json:"origin"`
	Width  float64    `json:"width"`
	Height float64    `json:"height"`
}

PageSize is a resolved canvas or final sheet size in physical points.

type Part 

type Part struct {
	Range *PageRange `json:"range"`
	Pages *int64     `json:"pages"`
	// Source indexes Report.Sources; set for a PDF part.
	Source *int `json:"source,omitempty"`
	// Style indexes Report.Styles; set for a blank part whose appearance was resolved.
	Style  *int     `json:"style,omitempty"`
	ID     string   `json:"id"`
	Kind   PartKind `json:"kind"`
	Origin Position `json:"origin"`
}

Part is one contribution to the output. A blank part with Pages > 1 is a compact run of identical pages.

type PartKind 

type PartKind string

PartKind distinguishes a source PDF from generated pages.

type PartResponse 

type PartResponse struct {
	Kind          string   `json:"kind"`
	Part          PartView `json:"part"`
	FormatVersion int      `json:"format_version"`
}

PartResponse answers a part query.

func (*PartResponse) RenderText 

func (p *PartResponse) RenderText(w io.Writer) error

RenderText writes the part as human text.

type PartView 

type PartView struct {
	Fit          *FitDeclaration `json:"fit,omitempty"`
	Geometries   []GeometryEntry `json:"geometries,omitempty"`
	FinalSize    *PageSize       `json:"final_size,omitempty"`
	Range        *PageRange      `json:"range"`
	Pages        *int64          `json:"pages"`
	Generated    *GeneratedBrief `json:"generated,omitempty"`
	Source       *Source         `json:"source,omitempty"`
	Style        *StyleDetail    `json:"style,omitempty"`
	ID           string          `json:"id"`
	Kind         PartKind        `json:"kind"`
	Path         string          `json:"path,omitempty"`
	Origin       Position        `json:"origin"`
	WarningCount int             `json:"warning_count"`
}

PartView is a part as a query shows it. Brief records carry Path (a PDF) or Generated (a blank); detailed records carry the materialized Source or Style instead, so one call is enough.

type PhaseState 

type PhaseState string

PhaseState says how far one phase of a run got.

type Phases 

type Phases struct {
	Instructions       PhaseState `json:"instructions"`
	InputInspection    PhaseState `json:"input_inspection"`
	Layout             PhaseState `json:"layout"`
	OutputVerification PhaseState `json:"output_verification"`
}

Phases records how far each phase got. Counts and ranges are only trustworthy for completed phases.

type Position 

type Position struct {
	Offset *int64 `json:"offset,omitempty"`
	File   string `json:"file"`
	Line   int    `json:"line,omitzero"`
	Column int    `json:"column,omitzero"`
}

Position is a place in a document. Offset is the absolute byte offset including a leading byte order mark; Line and Column are 1-based and Column counts bytes. A command line has no offset, line, or column.

func OriginOf 

func OriginOf(loc assembly.Location) Position

OriginOf is the Position part of a job location.

type Producer 

type Producer struct {
	Tool     string `json:"tool"`
	Version  string `json:"version"`
	Commit   string `json:"commit"`
	Go       string `json:"go"`
	Platform string `json:"platform"`
}

Producer identifies the executable that captured this run; it is provenance, not quality certification.

type Publication 

type Publication struct {
	ReportWrite             string     `json:"report_write,omitempty"`
	ReportTargetObservation string     `json:"report_target_observation,omitempty"`
	OutputDigest            string     `json:"output_digest,omitempty"`
	Output                  string     `json:"output,omitempty"`
	ReportStatus            WriteState `json:"report_status"`
	ReportPath              string     `json:"report_path,omitempty"`
	ReportFrom              string     `json:"report_from,omitempty"`
	// RecoveryReport names retained recovery data after the PDF commit. RecoveryState says
	// whether its publication metadata is current, still planned, or its owned identity was lost.
	RecoveryReport string        `json:"recovery_report,omitempty"`
	RecoveryState  RecoveryState `json:"recovery_state,omitempty"`
	Published      bool          `json:"published"`
}

Publication states what happened to the output PDF and to the requested report. A published PDF is never described as untouched, whatever happened to the report afterwards.

type QueryResult added in v0.2.0 

type QueryResult struct {
	DiagnosticsReference *ContinuationReference `json:"diagnostics_reference,omitempty"`
	Result               Response               `json:"result"`
	Kind                 string                 `json:"kind"`
	Command              string                 `json:"command"`
	Status               Status                 `json:"status"`
	SavedRun             SavedRun               `json:"saved_run"`
	SelectionCounts      DiagnosticCounts       `json:"selection_counts"`
	FormatVersion        int                    `json:"format_version"`
	DiagnosticCount      int                    `json:"diagnostic_count"`
	ErrorCount           int                    `json:"error_count"`
	WarningCount         int                    `json:"warning_count"`
}

QueryResult records successful selection from a saved attempt. Result is captured evidence; any publication target inside it is historical, never the file selected by this query.

func QueryResultOf added in v0.2.0 

func QueryResultOf(saved *Report, response Response, executable, path string) *QueryResult

QueryResultOf binds summary navigation to the actual file and current executable. saved must be valid and response must be the result of saved.Query; Validate can check a separately constructed outcome's scopes before another consumer serializes it.

func (*QueryResult) RenderText added in v0.2.0 

func (q *QueryResult) RenderText(w io.Writer) error

RenderText distinguishes successful querying from the saved job's outcome.

func (*QueryResult) Validate added in v0.2.0 

func (q *QueryResult) Validate() error

Validate checks the query operation's diagnostic scope separately from its captured evidence. It does not authenticate artifacts or replace complete-report validation before selection.

type Recovery added in v0.2.0 

type Recovery struct {
	LocationFrom string    `json:"location_from,omitempty"`
	Action       string    `json:"action"`
	Command      string    `json:"command"`
	Location     *Location `json:"location,omitempty"`
	Replacement  string    `json:"replacement,omitempty"`
	ReportFrom   string    `json:"report_from,omitempty"`
	RecoveryFrom string    `json:"recovery_from,omitempty"`
}

Recovery is guidance, never an automatically executed action. Location and references preserve the caller's declaration rather than constructing a shell command.

type RecoveryState 

type RecoveryState string

RecoveryState describes the retained recovery file, separately from the original report target.

type Rect 

type Rect struct {
	X      float64 `json:"x"`
	Y      float64 `json:"y"`
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

Rect is a rectangle in page coordinates (points, y up): bottom-left corner and size.

type Report 

type Report struct {
	Fit             *FitDeclaration `json:"fit,omitempty"`
	Geometries      []Geometry      `json:"geometries,omitempty"`
	AttemptID       string          `json:"attempt_id"`
	Producer        *Producer       `json:"producer,omitempty"`
	Counts          Counts          `json:"counts"`
	Kind            string          `json:"kind"`
	Status          Status          `json:"status"`
	Command         string          `json:"command"`
	Phases          Phases          `json:"phases"`
	Publication     Publication     `json:"publication"`
	Diagnostics     []Diagnostic    `json:"diagnostics"`
	Parts           []Part          `json:"parts"`
	Sources         []Source        `json:"sources"`
	Fonts           []Font          `json:"fonts"`
	Styles          []Style         `json:"styles"`
	FormatVersion   int             `json:"format_version"`
	DiagnosticCount int             `json:"diagnostic_count"`
	ErrorCount      int             `json:"error_count"`
	WarningCount    int             `json:"warning_count"`
	// ProgressInterrupted records observed loss of requested live telemetry.
	// Absence is not proof of complete delivery; staged reports can predate it.
	ProgressInterrupted bool `json:"progress_interrupted,omitzero"`
}

Report is the complete captured result of a build or check. Command errors use CommandError.

func Decode 

func Decode(ctx context.Context, name string, reader io.Reader) (*Report, error)

Decode reads a saved report as an untrusted file with the default limits.

func DecodeLimited 

func DecodeLimited(ctx context.Context, name string, reader io.Reader, limits Limits) (*Report, error)

DecodeLimited reads one saved report from reader. The input is rejected, with a located *Error, when it is larger than the byte limit, not exactly one strict JSON object, nested or populated beyond the limits, an unsupported version, or not shaped like a report: unknown, duplicate, missing, or null members, wrong types, dangling references, duplicate IDs, impossible ranges. The first fault is reported.

func (*Report) FinalizeDiagnostics added in v0.2.0 

func (r *Report) FinalizeDiagnostics()

FinalizeDiagnostics assigns construction defaults and derives counts/context for a captured snapshot. It is for controlled report production, never decoding or repairing untrusted wire evidence.

func (*Report) Query 

func (r *Report) Query(req Request) (Response, error)

Query answers a request from a saved report without touching any PDF. The report must be valid: one returned by Decode, or one for which Validate succeeds. Errors are *Error values: usage errors for bad requests, not-found errors for missing parts and pages.

func (*Report) RenderText 

func (r *Report) RenderText(w io.Writer) error

RenderText writes every complete report value as readable JSON for explicit human details.

func (*Report) Summary 

func (r *Report) Summary() *Summary

Summary returns the compact result: counts, publication state, and the first PreviewDiagnostics diagnostics, retaining the primary fault and prioritizing report-write recovery before other previews.

func (*Report) Validate 

func (r *Report) Validate() error

Validate checks every invariant of a report that JSON syntax and types cannot: enumerations, references, ranges, counts, and the relations between status, phases, and publication. It returns an *Error.

type Request 

type Request struct {
	Part   *string
	Page   *int64
	Offset *int64
	Limit  *int64
	View   string
	// ExpectAttempt optionally guards the saved report identity.
	ExpectAttempt string
	// Details expands the selected records to their full resolved values.
	Details bool
}

Request selects what to read from a saved report. At most one of Part, Page, and View is set; with none, the result is the summary. Details requires a selection. Offset and Limit page a View only.

func (Request) Validate added in v0.2.0 

func (q Request) Validate() error

Validate checks request semantics without artifact access. Errors are *Error values; Option names the corresponding command-line declaration for adapters that can supply provenance.

type Response 

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

Response is a query result: its content is a *Summary, *Report, *PartResponse, *PageResponse, or *ViewResponse. It renders as bounded human text, and its JSON form is the content's.

func NewResponse 

func NewResponse(content TextRenderer) Response

NewResponse wraps a result value as a Response.

func (Response) MarshalJSONTo 

func (r Response) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo writes the content's JSON.

func (Response) RenderText 

func (r Response) RenderText(w io.Writer) error

RenderText writes the content as human text.

func (Response) WithProgressInterrupted added in v0.2.0 

func (r Response) WithProgressInterrupted() Response

WithProgressInterrupted records unavailable requested telemetry in the final response while retaining the work outcome and the summary's byte budget.

type SavedRun added in v0.2.0 

type SavedRun struct {
	AttemptID       string `json:"attempt_id"`
	Command         string `json:"command"`
	Status          Status `json:"status"`
	DiagnosticCount int    `json:"diagnostic_count"`
	ErrorCount      int    `json:"error_count"`
	WarningCount    int    `json:"warning_count"`
	Published       bool   `json:"published"`
}

SavedRun identifies the captured attempt, independent of the current read-only query.

func SavedRunOf added in v0.2.0 

func SavedRunOf(saved *Report) SavedRun

SavedRunOf captures the original run's outcome without absorbing later query or delivery failures.

type Severity added in v0.2.0 

type Severity string

Severity distinguishes a fatal operation problem from a captured nonfatal consequence.

type SizeOrigin 

type SizeOrigin string

SizeOrigin says where a generated page's size came from.

type Source 

type Source struct {
	Bytes      *int64          `json:"bytes"`
	Path       string          `json:"path"`
	Digest     string          `json:"digest,omitempty"`
	Geometries []GeometryRange `json:"geometries,omitempty"`
}

Source is the identity of a captured source PDF. Digest is the SHA-256 of the captured bytes.

type Stage 

type Stage string

Stage names the phase that produced a diagnostic: lower-case snake_case.

type Status 

type Status string

Status is the outcome class of a command.

func (Status) ExitCode 

func (s Status) ExitCode() int

ExitCode is the process exit code for the status; StatusFailed and any unknown status are a failure.

type Style 

type Style struct {
	FinalText  *TextPlacement `json:"final_text,omitempty"`
	Geometry   *int           `json:"geometry,omitempty"`
	Text       *Text          `json:"text,omitempty"`
	Background string         `json:"background"`
	Size       PageSize       `json:"size"`
}

Style is the resolved authored canvas and appearance, stored once and referenced by parts. Geometry and FinalText distinguish a fitted sheet from the authored Size/Text settings. Background is "none" or "#rrggbb"; Text is absent for a page without text.

type StyleDetail 

type StyleDetail struct {
	CanvasSize *PageSize      `json:"canvas_size,omitempty"`
	Geometry   *Geometry      `json:"geometry,omitempty"`
	FinalText  *TextPlacement `json:"final_text,omitempty"`
	Text       *TextDetail    `json:"text,omitempty"`
	Background string         `json:"background"`
	Size       PageSize       `json:"size"`
}

StyleDetail is a style with its font materialized.

type Summary 

type Summary struct {
	FitTarget             string                 `json:"fit_target,omitempty"`
	Counts                Counts                 `json:"counts"`
	Next                  *[]string              `json:"next"`
	NextReference         *ContinuationReference `json:"next_reference,omitempty"`
	Phases                Phases                 `json:"phases"`
	RecoveryBasename      string                 `json:"recovery_basename,omitempty"`
	AttemptID             string                 `json:"attempt_id"`
	RecoveryDirectoryFrom string                 `json:"recovery_directory_from,omitempty"`
	Command               string                 `json:"command"`
	Kind                  string                 `json:"kind"`
	Status                Status                 `json:"status"`
	PublicationContext    string                 `json:"publication_context,omitempty"`
	Publication           Publication            `json:"publication"`
	Diagnostics           []DiagnosticView       `json:"diagnostics"`
	TruncatedFields       []string               `json:"truncated_fields,omitempty"`

	FormatVersion       int  `json:"format_version"`
	PartCount           int  `json:"part_count"`
	DiagnosticCount     int  `json:"diagnostic_count"`
	ErrorCount          int  `json:"error_count"`
	WarningCount        int  `json:"warning_count"`
	DiagnosticsOmitted  int  `json:"diagnostics_omitted,omitzero"`
	ProgressInterrupted bool `json:"progress_interrupted,omitzero"`
	NextOmitted         bool `json:"next_omitted,omitzero"`
	// contains filtered or unexported fields
}

Summary is the compact default result. It is labeled as a summary, never lists every diagnostic of a large failure, and points at the saved report for the rest.

func (*Summary) BindContinuation added in v0.2.0 

func (s *Summary) BindContinuation(executable, path, reference string)

BindContinuation supplies exact invocation authority after projecting a saved report.

func (*Summary) RenderText 

func (s *Summary) RenderText(w io.Writer) error

RenderText writes the summary as human text: the same bounded preview as the JSON summary.

type Text 

type Text struct {
	TextSettings

	Font     int           `json:"font"`
	Findings []TextFinding `json:"findings,omitempty"`
}

Text is TextSettings with its font referenced by index into Report.Fonts.

type TextBrief 

type TextBrief struct {
	Preview     string `json:"preview"`
	Chars       int    `json:"chars"`
	Truncated   bool   `json:"truncated,omitzero"`
	HasFindings bool   `json:"has_findings"`
}

TextBrief is a bounded description of generated text.

type TextDetail 

type TextDetail struct {
	TextSettings

	Findings []TextFinding `json:"findings,omitempty"`

	Font Font `json:"font"`
}

TextDetail is the text of a style with its font materialized.

type TextFinding 

type TextFinding struct {
	Kind   string `json:"kind"`
	Detail string `json:"detail"`
	Line   int    `json:"line"`
}

TextFinding is a computed overflow finding retained for either overflow policy.

type TextPlacement added in v0.2.0 

type TextPlacement struct {
	Bounds    *Rect   `json:"bounds"`
	InkBounds *Rect   `json:"ink_bounds"`
	FontSize  float64 `json:"font_size"`
}

TextPlacement captures final physical bounds and font size after canvas fitting.

type TextRenderer 

type TextRenderer interface {
	RenderText(w io.Writer) error
}

TextRenderer is a value that renders itself as human text; its JSON form is its own encoding.

type TextSettings 

type TextSettings struct {
	Bounds    *Rect   `json:"bounds"`
	InkBounds *Rect   `json:"ink_bounds"`
	Value     string  `json:"value"`
	Color     string  `json:"color"`
	Anchor    string  `json:"anchor"`
	Align     string  `json:"align"`
	Overflow  string  `json:"overflow"`
	Size      float64 `json:"size"`
	X         float64 `json:"x"`
	Y         float64 `json:"y"`
	Width     float64 `json:"width"`
	Leading   float64 `json:"leading"`
}

TextSettings is the resolved text appearance except the font reference. Bounds is computed geometry; every other value is the resolved configuration.

type ViewResponse 

type ViewResponse[T any] struct {
	NextOffset *int64 `json:"next_offset"`
	Kind       string `json:"kind"`
	View       string `json:"view"`
	Records    []T    `json:"records"`
	// OversizedRecord marks a single record larger than the response bound, returned alone.
	OversizedRecord bool  `json:"oversized_record,omitzero"`
	Offset          int64 `json:"offset"`
	Total           int   `json:"total"`
	Returned        int   `json:"returned"`
	FormatVersion   int   `json:"format_version"`
}

ViewResponse is one page of a paged view. NextOffset is null after the last record.

func (*ViewResponse[T]) RenderText 

func (v *ViewResponse[T]) RenderText(w io.Writer) error

RenderText writes the page of records as human text.

type WriteState 

type WriteState string

WriteState is the write state of the requested full report.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.