diagnostics

Documentation

Index

• func EmptyItem() contract.DiagnosticItem
• func ItemFromError(err error) (contract.DiagnosticItem, bool)
• func NewItem(id string, code string, category string, title string, message string, ...) contract.DiagnosticItem
• func Redact(text string) string
• func RedactAndBound(text string, maxBytes int) string
• func RedactEvidence(evidence map[string]any) map[string]any
• func RedactItem(item contract.DiagnosticItem) contract.DiagnosticItem
• func RedactJSON(raw []byte) ([]byte, error)
• func RedactValue(value any) any
• func RegisterDynamicSecret(value string) func()
• type ItemOption
  • func WithDocURL(url string) ItemOption
  • func WithEvidence(evidence map[string]any) ItemOption
  • func WithSuggestedCommand(command string) ItemOption
• type StructuredError
  • func NewStructuredError(item contract.DiagnosticItem, cause error) *StructuredError
  • func (e *StructuredError) DiagnosticItem() contract.DiagnosticItem
  • func (e *StructuredError) Error() string
  • func (e *StructuredError) Unwrap() error

Functions

func EmptyItem

func EmptyItem() contract.DiagnosticItem

EmptyItem returns the zero DiagnosticItem from the diagnostics package so production callers do not construct DiagnosticItem literals directly.

func ItemFromError

func ItemFromError(err error) (contract.DiagnosticItem, bool)

ItemFromError extracts a redacted DiagnosticItem from any diagnostic-bearing error.

func NewItem

func NewItem(
	id string,
	code string,
	category string,
	title string,
	message string,
	severity string,
	freshness string,
	options ...ItemOption,
) contract.DiagnosticItem

NewItem builds the canonical redacted DiagnosticItem.

func Redact

func Redact(text string) string

Redact removes common credential shapes from diagnostic text before the text is persisted or exposed to operators.

func RedactAndBound

func RedactAndBound(text string, maxBytes int) string

RedactAndBound redacts diagnostic text and caps it to a deterministic byte budget. Callers should use this before storing crash evidence.

func RedactEvidence

func RedactEvidence(evidence map[string]any) map[string]any

RedactEvidence recursively redacts evidence values without mutating the input map.

func RedactItem

func RedactItem(item contract.DiagnosticItem) contract.DiagnosticItem

RedactItem reapplies the diagnostics redaction boundary to an existing item.

func RedactJSON

func RedactJSON(raw []byte) ([]byte, error)

RedactJSON recursively redacts secret-shaped values inside a JSON document.

func RedactValue

func RedactValue(value any) any

RedactValue recursively redacts diagnostic evidence values.

func RegisterDynamicSecret

func RegisterDynamicSecret(value string) func()

RegisterDynamicSecret registers one runtime-resolved secret for diagnostic redaction.

Types

type ItemOption

type ItemOption func(*itemOptions)

ItemOption customizes a DiagnosticItem built by NewItem.

func WithDocURL

func WithDocURL(url string) ItemOption

WithDocURL records the documentation URL for a diagnostic.

func WithEvidence

func WithEvidence(evidence map[string]any) ItemOption

WithEvidence attaches structured diagnostic evidence after recursive redaction.

func WithSuggestedCommand

func WithSuggestedCommand(command string) ItemOption

WithSuggestedCommand records the exact recovery command for an operator or agent.

type StructuredError

type StructuredError struct {
	Item  contract.DiagnosticItem
	Cause error
}

StructuredError carries a DiagnosticItem while preserving the underlying cause.

func NewStructuredError

func NewStructuredError(item contract.DiagnosticItem, cause error) *StructuredError

NewStructuredError creates a diagnostic-bearing error.

func (*StructuredError) DiagnosticItem

func (e *StructuredError) DiagnosticItem() contract.DiagnosticItem

DiagnosticItem returns the carried diagnostic for common error renderers.

func (*StructuredError) Error

func (e *StructuredError) Error() string

func (*StructuredError) Unwrap

func (e *StructuredError) Unwrap() error