diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 79f191f..a823329 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -28,7 +28,11 @@ when reporting validation. ## Stage 1 — Implement the shared classifier -Status — pending. +Status — complete. Added the shared classifier and focused tests for the +selected diagnostic codes, fallback evidence, wrappers, joins, cancellation, +and real ConfigKit loading errors. Verified with Go 1.27.0 using +`GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckconfig -run 'TestConfigurationDiagnosticClassification|TestClassifyConfigurationError' -count=1` +in the aligned workspace (with a temporary writable Go build cache). Add `integrations/ckconfig/errors.go` with the following exported function and GoDoc describing its CLI classification purpose, accepted evidence, fallback, diff --git a/integrations/ckconfig/errors.go b/integrations/ckconfig/errors.go new file mode 100644 index 0000000..c5b7465 --- /dev/null +++ b/integrations/ckconfig/errors.go @@ -0,0 +1,102 @@ +package ckconfig + +import ( + "context" + "errors" + + "go.maximumdirect.net/commandkit" + "go.maximumdirect.net/configkit" +) + +// ClassifyConfigurationError selects a CLI outcome from ConfigKit loading +// diagnostics. A nil error is success. A loading error is usage only when it +// contains at least one error diagnostic and all error diagnostics identify +// invalid configuration input; warnings are ignored. Unknown evidence and +// other errors are operational. Wrappers and joined errors are inspected, and +// any operational branch, cancellation, or deadline takes precedence. +// The caller remains responsible for constructing an outcome and its cause. +func ClassifyConfigurationError(err error) commandkit.OutcomeKind { + if err == nil { + return commandkit.OutcomeSuccess + } + if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) { + return commandkit.OutcomeOperational + } + return classifyConfigurationTree(err) +} + +func classifyConfigurationTree(err error) commandkit.OutcomeKind { + if load, ok := err.(*configkit.LoadError); ok { + if load == nil { + return commandkit.OutcomeOperational + } + return classifyConfigurationDiagnostics(load.Diagnostics()) + } + switch wrapped := err.(type) { + case interface{ Unwrap() []error }: + found := false + for _, child := range wrapped.Unwrap() { + if child == nil { + continue + } + found = true + if classifyConfigurationTree(child) != commandkit.OutcomeUsage { + return commandkit.OutcomeOperational + } + } + if found { + return commandkit.OutcomeUsage + } + case interface{ Unwrap() error }: + if child := wrapped.Unwrap(); child != nil { + return classifyConfigurationTree(child) + } + } + return commandkit.OutcomeOperational +} + +func classifyConfigurationDiagnostics(diagnostics []configkit.Diagnostic) commandkit.OutcomeKind { + found := false + for _, diagnostic := range diagnostics { + switch diagnostic.Severity { + case configkit.SeverityWarning: + continue + case configkit.SeverityError: + found = true + if !configurationInputCode(diagnostic.Code) { + return commandkit.OutcomeOperational + } + default: + return commandkit.OutcomeOperational + } + } + if found { + return commandkit.OutcomeUsage + } + return commandkit.OutcomeOperational +} + +func configurationInputCode(code configkit.Code) bool { + switch code { + case configkit.CodeYAMLInvalid, configkit.CodeYAMLEmpty, configkit.CodeYAMLMultipleDocuments, + configkit.CodeYAMLRootType, configkit.CodeYAMLDuplicateKey, configkit.CodeYAMLTag, + configkit.CodeYAMLAnchor, configkit.CodeYAMLAlias, configkit.CodeYAMLMergeKey, + configkit.CodeYAMLScalar, configkit.CodeYAMLDepthLimit, configkit.CodeYAMLNodeLimit, + configkit.CodeDecodeType, configkit.CodeDecodeNull, configkit.CodeDecodeRange, + configkit.CodeDecodeDuration, configkit.CodeDecodeText, configkit.CodeDecodeUnknownField, + configkit.CodeDecodeArrayLength, configkit.CodeSourceLimitExceeded, + configkit.CodeImportDisabled, configkit.CodeImportCycle, configkit.CodeImportRepeated, + configkit.CodeImportVersion, configkit.CodeSequenceInvalid, configkit.CodeSequenceConflict, + configkit.CodeComposeInvalid, configkit.CodeComposeConflict, configkit.CodeUnderlayVersion, + configkit.CodeOverlayVersion, configkit.CodeOverlayRepeated, configkit.CodeOverlayDirective, + configkit.CodeVersionType, configkit.CodeVersionError, configkit.CodeResolveError, + configkit.CodeValidateError, configkit.CodeInheritanceInvalid, configkit.CodeInheritanceMissing, + configkit.CodeInheritanceCycle, configkit.CodeInheritanceVersion, configkit.CodeOverrideInvalidPath, + configkit.CodeOverrideDuplicate, configkit.CodeOverrideOverlap, configkit.CodeOverrideDirective, + configkit.CodeOverrideVersion, configkit.CodeOverrideLimitExceeded, configkit.CodeSecretRequired, + configkit.CodeSecretInvalidName: + return true + default: + return false + } +} diff --git a/integrations/ckconfig/errors_test.go b/integrations/ckconfig/errors_test.go new file mode 100644 index 0000000..d1602d0 --- /dev/null +++ b/integrations/ckconfig/errors_test.go @@ -0,0 +1,93 @@ +package ckconfig + +import ( + "context" + "errors" + "fmt" + "testing" + + "go.maximumdirect.net/commandkit" + "go.maximumdirect.net/configkit" +) + +func TestConfigurationDiagnosticClassification(t *testing.T) { + usageCodes := []configkit.Code{ + configkit.CodeYAMLInvalid, configkit.CodeYAMLEmpty, configkit.CodeYAMLMultipleDocuments, configkit.CodeYAMLRootType, configkit.CodeYAMLDuplicateKey, configkit.CodeYAMLTag, configkit.CodeYAMLAnchor, configkit.CodeYAMLAlias, configkit.CodeYAMLMergeKey, configkit.CodeYAMLScalar, configkit.CodeYAMLDepthLimit, configkit.CodeYAMLNodeLimit, + configkit.CodeDecodeType, configkit.CodeDecodeNull, configkit.CodeDecodeRange, configkit.CodeDecodeDuration, configkit.CodeDecodeText, configkit.CodeDecodeUnknownField, configkit.CodeDecodeArrayLength, configkit.CodeSourceLimitExceeded, + configkit.CodeImportDisabled, configkit.CodeImportCycle, configkit.CodeImportRepeated, configkit.CodeImportVersion, configkit.CodeSequenceInvalid, configkit.CodeSequenceConflict, configkit.CodeComposeInvalid, configkit.CodeComposeConflict, configkit.CodeUnderlayVersion, configkit.CodeOverlayVersion, configkit.CodeOverlayRepeated, configkit.CodeOverlayDirective, + configkit.CodeVersionType, configkit.CodeVersionError, configkit.CodeResolveError, configkit.CodeValidateError, configkit.CodeInheritanceInvalid, configkit.CodeInheritanceMissing, configkit.CodeInheritanceCycle, configkit.CodeInheritanceVersion, configkit.CodeOverrideInvalidPath, configkit.CodeOverrideDuplicate, configkit.CodeOverrideOverlap, configkit.CodeOverrideDirective, configkit.CodeOverrideVersion, configkit.CodeOverrideLimitExceeded, configkit.CodeSecretRequired, configkit.CodeSecretInvalidName, + } + for _, code := range usageCodes { + t.Run(string(code), func(t *testing.T) { + ds := []configkit.Diagnostic{{Severity: configkit.SeverityWarning, Code: configkit.CodeSourceRead}, {Severity: configkit.SeverityError, Code: code}} + if got := classifyConfigurationDiagnostics(ds); got != commandkit.OutcomeUsage { + t.Fatalf("got %s", got) + } + }) + } + for _, code := range []configkit.Code{configkit.CodeSourceMissing, configkit.CodeSourcePermission, configkit.CodeImportInvalid, configkit.CodeImportOutsideRoot, configkit.CodeImportLimitExceeded, configkit.CodeOverlayInvalid, configkit.CodeOverlayOutsideRoot, configkit.CodeOverlayLimitExceeded, configkit.CodeSchemaRoot, configkit.CodeOptionsInvalid, configkit.CodeHistoryLimitExceeded, configkit.CodeResolveHookFailed, configkit.CodeValidateMutation, configkit.CodeOverrideInvalidLabel, configkit.CodeOverrideInvalidValue, configkit.CodeSecretUnset, configkit.CodeSecretEmpty, configkit.CodeSecretsMissing, "future.code"} { + t.Run(string(code), func(t *testing.T) { + ds := []configkit.Diagnostic{{Severity: configkit.SeverityError, Code: configkit.CodeYAMLInvalid}, {Severity: configkit.SeverityError, Code: code}} + if got := classifyConfigurationDiagnostics(ds); got != commandkit.OutcomeOperational { + t.Fatalf("got %s", got) + } + }) + } + for _, ds := range [][]configkit.Diagnostic{nil, {{Severity: configkit.SeverityWarning, Code: configkit.CodeYAMLInvalid}}, {{Severity: "future", Code: configkit.CodeYAMLInvalid}}, {{Severity: configkit.SeverityError, Code: configkit.CodeYAMLInvalid}, {Severity: "future"}}} { + if got := classifyConfigurationDiagnostics(ds); got != commandkit.OutcomeOperational { + t.Fatalf("%v: got %s", ds, got) + } + } +} + +type emptyChildren struct{} + +func (emptyChildren) Error() string { return "empty" } +func (emptyChildren) Unwrap() []error { return nil } + +func TestClassifyConfigurationError(t *testing.T) { + _, invalid := configkit.Load[map[string]any](configkit.Bytes("invalid", []byte("broken: ["))) + _, missing := configkit.Load[map[string]any](configkit.File("/nonexistent-commandkit-classifier-test")) + var load *configkit.LoadError + if !errors.As(invalid, &load) || load == nil { + t.Fatalf("invalid fixture: %v", invalid) + } + if missing == nil { + t.Fatal("missing fixture unexpectedly succeeded") + } + var typedNil *configkit.LoadError + opaque := errors.New("opaque") + cases := []struct { + name string + err error + want commandkit.OutcomeKind + }{ + {"nil", nil, commandkit.OutcomeSuccess}, + {"invalid", invalid, commandkit.OutcomeUsage}, + {"wrapped", fmt.Errorf("wrapped: %w", invalid), commandkit.OutcomeUsage}, + {"all input", errors.Join(invalid, fmt.Errorf("wrapped: %w", invalid)), commandkit.OutcomeUsage}, + {"mixed first", errors.Join(missing, invalid), commandkit.OutcomeOperational}, + {"mixed last", errors.Join(invalid, missing), commandkit.OutcomeOperational}, + {"nested", errors.Join(invalid, errors.Join(invalid, opaque)), commandkit.OutcomeOperational}, + {"canceled", errors.Join(invalid, context.Canceled), commandkit.OutcomeOperational}, + {"deadline", fmt.Errorf("deadline: %w", context.DeadlineExceeded), commandkit.OutcomeOperational}, + {"missing", missing, commandkit.OutcomeOperational}, + {"opaque", opaque, commandkit.OutcomeOperational}, + {"empty load", &configkit.LoadError{}, commandkit.OutcomeOperational}, + {"typed nil", typedNil, commandkit.OutcomeOperational}, + {"empty children", emptyChildren{}, commandkit.OutcomeOperational}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := ClassifyConfigurationError(tc.err); got != tc.want { + t.Fatalf("got %s, want %s", got, tc.want) + } + if errors.Is(tc.err, invalid) { + var got *configkit.LoadError + if !errors.As(tc.err, &got) || got == nil { + t.Fatal("load identity lost") + } + } + }) + } +}