diagnostic

Documentation

Overview

Package diagnostic provides a way to represent diagnostics in a way that can be easily marshalled to JSON.

Index

• Constants
• func DiagnosticCausedBySensitive(diag *hcl.Diagnostic) bool
• func DiagnosticCausedByUnknown(diag *hcl.Diagnostic) bool
• func ExtraInfo[T any](diag *hcl.Diagnostic) T
• func ExtraInfoNext[T any](previous interface{}) T
• type Diagnostic
  • func NewDiagnostic(file *hcl.File, hclDiag *hcl.Diagnostic) *Diagnostic
• type DiagnosticExtraBecauseSensitive
• type DiagnosticExtraBecauseUnknown
• type DiagnosticExtraUnwrapper
• type DiagnosticSeverity
  • func (severity DiagnosticSeverity) MarshalJSON() ([]byte, error)
  • func (severity DiagnosticSeverity) String() string
  • func (severity *DiagnosticSeverity) UnmarshalJSON(val []byte) error
• type Diagnostics
  • func (diags *Diagnostics) Contains(find *Diagnostic) bool
• type ExpressionValue
  • func DescribeExpressionValues(hclDiag *hcl.Diagnostic) []ExpressionValue
• type Function
  • func DescribeFunction(name string, f function.Function) *Function
• type FunctionCall
  • func DescribeFunctionCall(hclDiag *hcl.Diagnostic) *FunctionCall
• type FunctionParam
  • func DescribeFunctionParam(p *function.Parameter) FunctionParam
• type Pos
• type Range
  • func (rng Range) String() string
• type Snippet
  • func NewSnippet(file *hcl.File, hclDiag *hcl.Diagnostic, highlightRange hcl.Range) *Snippet

Constants

const (
	DiagnosticSeverityUnknown = "unknown"
	DiagnosticSeverityError   = "error"
	DiagnosticSeverityWarning = "warning"
)

const (
	// Sensitive indicates that this value is marked as sensitive in the context of Terraform.
	Sensitive = valueMark("Sensitive")
)

Functions

func DiagnosticCausedBySensitive

func DiagnosticCausedBySensitive(diag *hcl.Diagnostic) bool

DiagnosticCausedBySensitive returns true if the given diagnostic has an/ indication that it was caused by the presence of sensitive values during an expression evaluation.

func DiagnosticCausedByUnknown

func DiagnosticCausedByUnknown(diag *hcl.Diagnostic) bool

DiagnosticCausedByUnknown returns true if the given diagnostic has an indication that it was caused by the presence of unknown values during an expression evaluation.

func ExtraInfo

func ExtraInfo[T any](diag *hcl.Diagnostic) T

func ExtraInfoNext

func ExtraInfoNext[T any](previous interface{}) T

ExtraInfoNext takes a value previously returned by ExtraInfo and attempts to find an implementation of interface T wrapped inside of it. The return value meaning is the same as for ExtraInfo.

Types

type Diagnostic

type Diagnostic struct {
	Severity DiagnosticSeverity `json:"severity"`
	Summary  string             `json:"summary"`
	Detail   string             `json:"detail"`
	Range    *Range             `json:"range,omitempty"`
	Snippet  *Snippet           `json:"snippet,omitempty"`
}

func NewDiagnostic

func NewDiagnostic(file *hcl.File, hclDiag *hcl.Diagnostic) *Diagnostic

type DiagnosticExtraBecauseSensitive

type DiagnosticExtraBecauseSensitive interface {
	DiagnosticCausedBySensitive() bool
}

DiagnosticExtraBecauseSensitive is an interface implemented by values in the Extra field of Diagnostic when the diagnostic is potentially caused by the presence of sensitive values in an expression evaluation.

type DiagnosticExtraBecauseUnknown

type DiagnosticExtraBecauseUnknown interface {
	DiagnosticCausedByUnknown() bool
}

DiagnosticExtraBecauseUnknown is an interface implemented by values in the Extra field of Diagnostic when the diagnostic is potentially caused by the presence of unknown values in an expression evaluation.

type DiagnosticExtraUnwrapper

type DiagnosticExtraUnwrapper interface {
	UnwrapDiagnosticExtra() interface{}
}

DiagnosticExtraUnwrapper is an interface implemented by values in the Extra field of Diagnostic when they are wrapping another "Extra" value that was generated downstream.

type DiagnosticSeverity

type DiagnosticSeverity hcl.DiagnosticSeverity

func (DiagnosticSeverity) MarshalJSON

func (severity DiagnosticSeverity) MarshalJSON() ([]byte, error)

func (DiagnosticSeverity) String

func (severity DiagnosticSeverity) String() string

func (*DiagnosticSeverity) UnmarshalJSON

func (severity *DiagnosticSeverity) UnmarshalJSON(val []byte) error

type Diagnostics

type Diagnostics []*Diagnostic

func (*Diagnostics) Contains

func (diags *Diagnostics) Contains(find *Diagnostic) bool

type ExpressionValue

type ExpressionValue struct {
	Traversal string `json:"traversal"`
	Statement string `json:"statement"`
}

ExpressionValue represents an HCL traversal string and a statement about its value while the expression was evaluated.

func DescribeExpressionValues

func DescribeExpressionValues(hclDiag *hcl.Diagnostic) []ExpressionValue

type Function

type Function struct {
	// Name is the leaf name of the function, without any namespace prefix.
	Name string `json:"name"`

	Params        []FunctionParam `json:"params"`
	VariadicParam *FunctionParam  `json:"variadic_param,omitempty"`

	// ReturnType is type constraint which is a static approximation of the possibly-dynamic return type of the function.
	ReturnType json.RawMessage `json:"return_type"`

	Description     string `json:"description,omitempty"`
	DescriptionKind string `json:"description_kind,omitempty"`
}

Function is a description of the JSON representation of the signature of a function callable from the Terraform language.

func DescribeFunction

func DescribeFunction(name string, f function.Function) *Function

DescribeFunction returns a description of the signature of the given cty function, as a pointer to this package's serializable type Function.

type FunctionCall

type FunctionCall struct {
	// CalledAs is the full name that was used to call this function, potentially including namespace prefixes if the function does not belong to the default function namespace.
	CalledAs string `json:"called_as"`

	// Signature is a description of the signature of the function that was/ called, if any.
	Signature *Function `json:"signature,omitempty"`
}

FunctionCall represents a function call whose information is being included as part of a diagnostic snippet.

func DescribeFunctionCall

func DescribeFunctionCall(hclDiag *hcl.Diagnostic) *FunctionCall

type FunctionParam

type FunctionParam struct {
	// Name is a name for the function which is used primarily for documentation purposes.
	Name string `json:"name"`

	// Type is a type constraint which is a static approximation of the possibly-dynamic type of the parameter
	Type json.RawMessage `json:"type"`

	Description     string `json:"description,omitempty"`
	DescriptionKind string `json:"description_kind,omitempty"`
}

FunctionParam represents a single parameter to a function, as represented by type Function.

func DescribeFunctionParam

func DescribeFunctionParam(p *function.Parameter) FunctionParam

type Pos

type Pos struct {
	// Line is a one-based count for the line in the indicated file.
	Line int `json:"line"`

	// Column is a one-based count of Unicode characters from the start of the line.
	Column int `json:"column"`

	// Byte is a zero-based offset into the indicated file.
	Byte int `json:"byte"`
}

Pos represents a position in the source code.

type Range

type Range struct {
	Filename string `json:"filename"`
	Start    Pos    `json:"start"`
	End      Pos    `json:"end"`
}

Range represents the filename and position of the diagnostic subject.

func (Range) String

func (rng Range) String() string

type Snippet

type Snippet struct {
	// Context is derived from HCL's hcled.ContextString output. This gives a high-level summary of the root context of the diagnostic.
	Context string `json:"context"`

	// Code is a possibly-multi-line string of Terraform configuration, which includes both the diagnostic source and any relevant context as defined by the diagnostic.
	Code string `json:"code"`

	// StartLine is the line number in the source file for the first line of the snippet code block.
	StartLine int `json:"start_line"`

	// HighlightStartOffset is the character offset into Code at which the diagnostic source range starts, which ought to be highlighted as such by the consumer of this data.
	HighlightStartOffset int `json:"highlight_start_offset"`

	// HighlightEndOffset is the character offset into Code at which the diagnostic source range ends.
	HighlightEndOffset int `json:"highlight_end_offset"`

	// Values is a sorted slice of expression values which may be useful in understanding the source of an error in a complex expression.
	Values []ExpressionValue `json:"values"`

	// FunctionCall is information about a function call whose failure is being reported by this diagnostic, if any.
	FunctionCall *FunctionCall `json:"function_call,omitempty"`
}

Snippet represents source code information about the diagnostic.

func NewSnippet

func NewSnippet(file *hcl.File, hclDiag *hcl.Diagnostic, highlightRange hcl.Range) *Snippet