Documentation
¶
Overview ¶
Package diagnostic provides a standardized diagnostic reporting mechanism that can report in various output formats, including:
- GitHub Actions annotations
- JSON objects for downstream processing
- ANSI-formatted messages for terminal output
- Plain text messages for log output
- Log messages for the standard log package
Index ¶
- type Annotation
- func Code(code string) Annotation
- func Column(column int) Annotation
- func ColumnRange(start, end int) Annotation
- func End(line, column int) Annotation
- func File(file string) Annotation
- func Line(line int) Annotation
- func LineRange(start, end int) Annotation
- func Start(line, column int) Annotation
- func Title(title string) Annotation
- type Diagnostic
- type Emitter
- type Flags
- type Metrics
- type Position
- type Reporter
- func NewGitHubReporter(w io.Writer) *Reporter
- func NewJSONReporter(w io.Writer) *Reporter
- func NewLogReporter(w io.Writer) *Reporter
- func NewNoopReporter() *Reporter
- func NewReporter(e Emitter) *Reporter
- func NewTerminalReporter(w io.Writer, opts *TerminalOptions) *Reporter
- func NewTextReporter(w io.Writer) *Reporter
- func (r *Reporter) Debugf(format string, args ...any) error
- func (r *Reporter) Errorf(format string, args ...any) error
- func (r *Reporter) Fatalf(format string, args ...any)
- func (r *Reporter) Metrics() *Metrics
- func (r *Reporter) Noticef(format string, args ...any) error
- func (r *Reporter) Report(msg *Diagnostic) error
- func (r *Reporter) ShowDebug(b bool)
- func (r *Reporter) Warningf(format string, args ...any) error
- type Severity
- type TerminalOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Annotation ¶
type Annotation interface {
// contains filtered or unexported methods
}
Annotation is an optional annotation that can be connected to Diagnostic objects.
func Code ¶
func Code(code string) Annotation
Code returns an annotation that sets the code of the diagnostic message.
func Column ¶
func Column(column int) Annotation
Column returns an annotation that sets the column of the diagnostic message.
func ColumnRange ¶
func ColumnRange(start, end int) Annotation
ColumnRange returns an annotation that sets the column range of the diagnostic message.
func End ¶
func End(line, column int) Annotation
End returns an annotation that sets the end position of the diagnostic message.
func File ¶
func File(file string) Annotation
File returns an annotation that sets the file of the diagnostic message.
func Line ¶
func Line(line int) Annotation
Line returns an annotation that sets the line of the diagnostic message.
func LineRange ¶
func LineRange(start, end int) Annotation
LineRange returns an annotation that sets the line range of the diagnostic message.
func Start ¶
func Start(line, column int) Annotation
Start returns an annotation that sets the start position of the diagnostic message.
func Title ¶
func Title(title string) Annotation
Title returns an annotation that sets the title of the diagnostic message.
type Diagnostic ¶
type Diagnostic struct {
// Severity is the severity of the diagnostic message. This field is
// required.
Severity Severity `json:"severity"`
// Code is an optional 'code' for the diagnostic being emitted that will
// appear connected to the severity (e,g, `error[E1234]`). This field is
// optional.
Code string `json:"code,omitempty"`
// Title is an optional title for the diagnostic message.
// This field is optional.
Title string `json:"title,omitempty"`
// Message is the actual diagnostic message to be reported. This field is
// required.
Message string `json:"message"`
// File is the file path where the diagnostic message is located. This field
// is optional.
File string `json:"file,omitempty"`
// Start is the starting position of the diagnostic message. This field is
// optional.
Start *Position `json:"position,omitempty"`
// End is the ending position of the diagnostic message. This field is
// optional, but if provided, Start must also be provided.
End *Position `json:"end,omitempty"`
}
Diagnostic represents a diagnostic message that can be reported to the user.
func Debugf ¶
func Debugf(format string, args ...any) *Diagnostic
Debugf creates a new debug-level diagnostic message with the provided format and arguments.
func Errorf ¶
func Errorf(format string, args ...any) *Diagnostic
Errorf creates a new error-level diagnostic message with the provided format and arguments.
func New ¶
func New(severity Severity, message string) *Diagnostic
New creates a new diagnostic message with the provided severity, format, and arguments.
func Noticef ¶
func Noticef(format string, args ...any) *Diagnostic
Noticef creates a new notice-level diagnostic message with the provided format and arguments.
func Warningf ¶
func Warningf(format string, args ...any) *Diagnostic
Warningf creates a new warning-level diagnostic message with the provided format and arguments.
func (*Diagnostic) With ¶
func (d *Diagnostic) With(annotations ...Annotation) *Diagnostic
With adds the provided annotations to the diagnostic message.
type Emitter ¶
type Emitter interface {
// Emit emits a diagnostic message.
Emit(msg *Diagnostic) error
}
Emitter represents a mechanism to emit Diagnostic messages.
type Flags ¶
type Flags struct {
// contains filtered or unexported fields
}
Flags is a simple embeddable struct that provides a common set of flags for configuring diagnostic output
func (*Flags) RegisterFlags ¶
RegisterFlags registers the diagnostic flags with the given flagset
type Metrics ¶
type Metrics struct {
// Errors is the number of error diagnostics emitted.
Errors int
// Warnings is the number of warning diagnostics emitted.
Warnings int
// Notices is the number of notice diagnostics emitted.
Notices int
// Debugs is the number of debug diagnostics emitted.
Debugs int
}
Metrics collects the number of diagnostics emitted by a Reporter.
type Position ¶
type Position struct {
// Line is the line number in the file or source content. Begins at 1,
// 0 if unknown.
Line int `json:"line,omitempty"`
// Column is the column number in the file or source content. Begins at 1,
// 0 if unknown.
Column int `json:"column,omitempty"`
}
Position represents the (line, column) pair location in a file or source content.
type Reporter ¶
type Reporter struct {
// contains filtered or unexported fields
}
Reporter reports Diagnostic messages to a given output.
func NewGitHubReporter ¶
NewGitHubReporter creates a new Reporter that emits diagnostics to the given writer in a format that is suitable for GitHub Actions. If the writer is nil, the returned reporter will not emit any diagnostics.
func NewJSONReporter ¶
NewJSONReporter creates a new Reporter that emits diagnostics to the given writer in a JSON format. If the writer is nil, the returned reporter will not emit any diagnostics.
func NewLogReporter ¶
NewLogReporter creates a new Reporter that emits diagnostics to the given writer in a log format. If the writer is nil, the returned reporter will not emit any diagnostics.
func NewNoopReporter ¶
func NewNoopReporter() *Reporter
NewNoopReporter creates a new Reporter that does not emit any diagnostics.
func NewReporter ¶
NewReporter creates a new Reporter that emits diagnostics to the given Emitter. If the Emitter is nil, the returned reporter will not emit any diagnostics.
func NewTerminalReporter ¶
func NewTerminalReporter(w io.Writer, opts *TerminalOptions) *Reporter
NewTerminalReporter creates a new Reporter that emits diagnostics to the given writer in a format that is suitable for ANSI terminals. If the writer is nil, the returned reporter will not emit any diagnostics.
func NewTextReporter ¶
NewTextReporter creates a new Reporter that emits diagnostics to the given writer in a text format. If the writer is nil, the returned reporter will not emit any diagnostics.
func (*Reporter) Fatalf ¶
Fatalf emits a formatted error diagnostic message and exits the program with a non-zero exit code.
func (*Reporter) Report ¶
func (r *Reporter) Report(msg *Diagnostic) error
Report emits a diagnostic message to the underlying Emitter. If the provided diagnostic message is invalid -- such as having an invalid severity, or missing a required field -- an error will be returned.
type Severity ¶
type Severity string
Severity represents the severity of a diagnostic message.
const ( // SeverityError is used for error-level diagnostics SeverityError Severity = "error" // SeverityWarning is used for warning-level diagnostics SeverityWarning Severity = "warning" // SeverityNotice is used for notice-level diagnostics SeverityNotice Severity = "notice" // SeverityDebug is used for debug-level diagnostics SeverityDebug Severity = "debug" )
func (*Severity) UnmarshalText ¶
UnmarshalText unmarshals a severity from a string.
type TerminalOptions ¶
type TerminalOptions struct {
// BasePath is the path to show files relative to when emitting terminal
// diagnostics. If unspecified, the current working directory is used.
BasePath string
}
TerminalOptions represents options for terminal reporters.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package diagnostictest provides mechanisms for testing diagnostics emitted by diagnostic reporters.
|
Package diagnostictest provides mechanisms for testing diagnostics emitted by diagnostic reporters. |