diagnostic

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package diagnostic defines application-neutral, source-mapped diagnostics for workflow authors and transports.

Diagnostic codes have the stable form HADR-<PREFIX>-<NNN>. The reserved prefixes and their domains are: 

SOURCE  source syntax and structural validation
REF     source reference and dependency validation
LEGACY  archived source migration
OUTPUT  archived output-shim migration
VALUE   expression, binding, and value evaluation
ARTIFACT artifact storage, authorization, verification, and retention
POLICY  capability and policy enforcement
EFFECT  effect, retry, and idempotency safety
WAIT    wait and external-event handling
PERSIST persistence and recovery
HOST    host integration and capability negotiation

REF, LEGACY, and OUTPUT are source-validation subdomains retained for the migration codes established by the workflow architecture.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EncodeJSON 

func EncodeJSON(d Diagnostic) ([]byte, error)

EncodeJSON validates and encodes one diagnostic for a transport boundary.

Types

type Code 

type Code string

Code is a stable, searchable diagnostic identifier. 

const (
	// CodeUnresolvedReference identifies a value reference that is not visible
	// through the graph's declared dependencies.
	CodeUnresolvedReference Code = "HADR-REF-001"
	// CodeUnsafeEffectRetry identifies an effect/retry combination without an
	// idempotency proof.
	CodeUnsafeEffectRetry Code = "HADR-EFFECT-001"
	// CodeArchivedOutputShim identifies legacy output capture from log text.
	CodeArchivedOutputShim Code = "HADR-OUTPUT-002"
)

func NewCode 

func NewCode(prefix Prefix, number int) (Code, error)

NewCode constructs a code using a reserved prefix and a three-digit number. Numbers start at one; zero is not assigned.

func (Code) Domain 

func (c Code) Domain() (Domain, error)

Domain returns the contract domain encoded in c.

func (Code) Prefix 

func (c Code) Prefix() (Prefix, error)

Prefix returns the reserved prefix encoded in c.

func (Code) Validate 

func (c Code) Validate() error

Validate reports whether c follows the reserved code convention.

type Diagnostic 

type Diagnostic struct {
	Severity    Severity           `json:"severity"`
	Code        Code               `json:"code"`
	Message     string             `json:"message"`
	Source      *graph.SourceRef   `json:"source,omitempty"`
	Related     []RelatedReference `json:"related,omitempty"`
	Remediation *Remediation       `json:"remediation,omitempty"`
}

Diagnostic is the stable transport representation of a workflow finding. Source and Related reuse graph.SourceRef so graph and diagnostics share one source-location contract.

func ArchivedOutputShim 

func ArchivedOutputShim(source graph.SourceRef, stageName string) Diagnostic

ArchivedOutputShim reports legacy output extraction from an archived stage's log stream.

func DecodeJSON 

func DecodeJSON(data []byte) (Diagnostic, error)

DecodeJSON decodes and validates one diagnostic from a transport boundary. Unknown fields and trailing JSON values are rejected to keep the contract explicit and malformed transport payloads detectable.

func UnresolvedReference 

func UnresolvedReference(source graph.SourceRef, nodeID, reference, dependency string) Diagnostic

UnresolvedReference reports a missing or dependency-invisible node output.

func UnsafeEffectRetry 

func UnsafeEffectRetry(source graph.SourceRef, nodeID string) Diagnostic

UnsafeEffectRetry reports a retry policy that lacks an idempotency proof for an effectful node.

func (Diagnostic) Validate 

func (d Diagnostic) Validate() error

Validate checks the invariants required to safely present or transport d. It intentionally does not attempt compiler, policy, or runtime validation.

type Domain 

type Domain string

Domain groups diagnostic prefixes by the workflow contract they describe. 

const (
	DomainSourceValidation Domain = "source-validation"
	DomainValues           Domain = "values"
	DomainPolicy           Domain = "policy"
	DomainEffects          Domain = "effects"
	DomainWaits            Domain = "waits"
	DomainPersistence      Domain = "persistence"
	DomainHostIntegration  Domain = "host-integration"
)

type Prefix 

type Prefix string

Prefix is the reserved middle segment of a diagnostic code. 

const (
	PrefixSource      Prefix = "SOURCE"
	PrefixReference   Prefix = "REF"
	PrefixLegacy      Prefix = "LEGACY"
	PrefixOutput      Prefix = "OUTPUT"
	PrefixValue       Prefix = "VALUE"
	PrefixArtifact    Prefix = "ARTIFACT"
	PrefixPolicy      Prefix = "POLICY"
	PrefixEffect      Prefix = "EFFECT"
	PrefixWait        Prefix = "WAIT"
	PrefixPersistence Prefix = "PERSIST"
	PrefixHost        Prefix = "HOST"
)

func ParseCode 

func ParseCode(raw string) (Prefix, int, error)

ParseCode validates raw and returns its prefix and numeric assignment.

func (Prefix) Domain 

func (p Prefix) Domain() (Domain, bool)

Domain returns the contract domain reserved for p.

func (Prefix) Valid 

func (p Prefix) Valid() bool

Valid reports whether p is reserved by this package.

type RelatedReference 

type RelatedReference struct {
	Message string          `json:"message,omitempty"`
	Source  graph.SourceRef `json:"source"`
}

RelatedReference points to source material that helps explain a diagnostic.

type Remediation 

type Remediation struct {
	Message         string `json:"message"`
	SuggestedSyntax string `json:"suggested_syntax,omitempty"`
	Documentation   string `json:"documentation,omitempty"`
}

Remediation describes an author action and, when useful, target syntax.

type Severity 

type Severity string

Severity describes how a diagnostic affects the requested operation. 

const (
	// SeverityInfo reports actionable context that does not affect validity.
	SeverityInfo Severity = "info"
	// SeverityWarning reports accepted input that should be changed.
	SeverityWarning Severity = "warning"
	// SeverityError reports input or state that prevents the operation.
	SeverityError Severity = "error"
)

func (Severity) Valid 

func (s Severity) Valid() bool

Valid reports whether s is a supported severity.

type ValidationError 

type ValidationError struct {
	Field  string
	Reason string
}

ValidationError identifies one malformed diagnostic transport field.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

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.