failure

package

v0.7.0 Latest Latest Go to latest Published: Jun 2, 2026 License: GPL-2.0, GPL-2.0-only Imports: 3 Imported by: 0

Documentation ¶

Overview ¶

Package failure defines structured machine-readable terminal errors.

Index ¶

func MarshalJSON(err error) ([]byte, error)
func Prefix(err error, message string) error
func Wrap(err error, code Code, stage Stage, message string, opts ...Option) error
func WrapUnknown(err error, code Code, stage Stage, message string, opts ...Option) error
type Code
type Error
- func As(err error) (*Error, bool)
- func New(code Code, stage Stage, message string, opts ...Option) *Error
- func (e *Error) Error() string
- func (e *Error) Unwrap() error
type Option
type Payload
- func ToPayload(err error) Payload
type Stage

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func MarshalJSON ¶

func MarshalJSON(err error) ([]byte, error)

MarshalJSON serializes any error into the machine-readable payload.

func Prefix ¶

func Prefix(err error, message string) error

Prefix adds human-readable context without changing the underlying typed failure.

func Wrap ¶

func Wrap(err error, code Code, stage Stage, message string, opts ...Option) error

Wrap constructs a new structured failure that preserves the cause.

func WrapUnknown ¶

func WrapUnknown(err error, code Code, stage Stage, message string, opts ...Option) error

WrapUnknown wraps plain errors into structured failures while preserving already-typed failures.

Types ¶

type Code ¶

type Code string

Code is a stable machine-readable failure identifier.

const (
	CodeUnknown                     Code = "unknown_error"
	CodeInvalidArguments            Code = "invalid_arguments"
	CodeInvalidTimeout              Code = "invalid_timeout"
	CodeConfigInitializationFailed  Code = "config_initialization_failed"
	CodeJavaRuntimeConfigInvalid    Code = "java_runtime_config_invalid"
	CodeCacheInitializationFailed   Code = "cache_initialization_failed"
	CodeRulesLoadFailed             Code = "rules_load_failed"
	CodeScannerUnavailable          Code = "scanner_unavailable"
	CodeScannerInitializationFailed Code = "scanner_initialization_failed"
	CodeScannerExecutionFailed      Code = "scanner_execution_failed"
	CodeScannerTimeout              Code = "scanner_timeout"
	CodeScannerCancelled            Code = "scanner_canceled"
	CodeScannerOutputParseFailed    Code = "scanner_output_parse_failed"
	CodeLanguageDetectionFailed     Code = "language_detection_failed"
	CodeDependencyResolutionFailed  Code = "dependency_resolution_failed"
	CodeDependencyBuildToolUnknown  Code = "java_build_tool_unknown"
	CodeJavaBuildToolAmbiguous      Code = "java_build_tool_ambiguous"
	CodeGradleToolMissing           Code = "gradle_tool_missing"
	CodeGradleExportFailed          Code = "gradle_export_failed"
	CodeGradleJavaIncompatible      Code = "gradle_java_incompatible"
	CodeCallGraphBuildFailed        Code = "callgraph_build_failed"
	CodeCallGraphExportFailed       Code = "callgraph_export_failed"
	CodeOutputWriterUnavailable     Code = "output_writer_unavailable"
	CodeOutputWriteFailed           Code = "output_write_failed"
	CodeFindingsDetected            Code = "findings_detected"
)

Failure codes are stable machine-readable identifiers for terminal errors.

type Error ¶

type Error struct {
	Code      Code
	Stage     Stage
	Retryable bool
	Message   string
	Details   map[string]string
	Cause     error
}

Error is a structured machine-readable terminal failure.

func As ¶

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

As extracts a structured failure from the error chain.

func New ¶

func New(code Code, stage Stage, message string, opts ...Option) *Error

New constructs a new structured failure.

func (*Error) Error ¶

func (e *Error) Error() string

Error implements the error interface. When both Message and Cause are present, the cause is appended so the underlying reason surfaces in CLI output instead of being silently dropped.

func (*Error) Unwrap ¶

func (e *Error) Unwrap() error

Unwrap returns the underlying cause.

type Option ¶

type Option func(*Error)

Option configures a structured failure.

func WithDetail ¶

func WithDetail(key, value string) Option

WithDetail adds a structured detail field.

func WithDetails ¶

func WithDetails(details map[string]string) Option

WithDetails adds multiple structured detail fields.

func WithRetryable ¶

func WithRetryable(retryable bool) Option

WithRetryable sets whether the failure should be retried.

type Payload ¶

type Payload struct {
	Code      Code              `json:"code"`
	Stage     Stage             `json:"stage"`
	Retryable bool              `json:"retryable"`
	Message   string            `json:"message"`
	Details   map[string]string `json:"details,omitempty"`
	Cause     string            `json:"cause,omitempty"`
	RawError  string            `json:"raw_error,omitempty"`
}

Payload is the machine-readable representation emitted by CLI adapters.

func ToPayload ¶

func ToPayload(err error) Payload

ToPayload converts any error into a machine-readable payload.

type Stage ¶

type Stage string

Stage identifies the pipeline stage that produced the failure.

const (
	StageUnknown    Stage = "unknown"
	StageInput      Stage = "input"
	StageConfig     Stage = "config"
	StageRules      Stage = "rules"
	StageScan       Stage = "scan"
	StageDependency Stage = "dependency"
	StageCallGraph  Stage = "callgraph"
	StageExport     Stage = "export"
	StageOutput     Stage = "output"
	StagePolicy     Stage = "policy"
)

Failure stages identify which pipeline phase produced a terminal error.

Source Files ¶

View all Source files

error.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL