[Code Quality] Create reusable validation error message components

[github-actions]

Description

Extract common validation error message patterns into reusable components to ensure consistency and reduce duplication across 87 validation files. Currently, each validator reinvents error formatting, leading to inconsistent developer experience.

Current Situation

Reusability Gap:

• 0 error message constants or templates despite common patterns
• 127 fmt.Errorf error sites across 87 validation files
• Each validator reinvents error formatting independently
• Common scenarios (missing field, invalid type, configuration conflict) lack reusable message components
• Inconsistent error message structure and quality

Current Pattern (Repeated 127 times in different forms):

return fmt.Errorf("field '%s' has invalid value: %v", field, value)

❌ No example, no valid options listed, no fix suggestion, generic message

Proposed Solution

Create a new file pkg/workflow/validation_messages.go with reusable message builders:

package workflow

// MissingRequiredFieldError creates an error for a missing required field
func MissingRequiredFieldError(fieldName, example string) error

// InvalidFieldTypeError creates an error for incorrect field type
func InvalidFieldTypeError(fieldName string, expected, actual string, example string) error

// InvalidFieldValueError creates an error for invalid field value with valid options
func InvalidFieldValueError(fieldName string, value any, validOptions []string, example string) error

// ConfigurationConflictError creates an error for mutually exclusive fields
func ConfigurationConflictError(fields []string, resolution string, example string) error

// FormatYAMLExample formats a YAML example with proper indentation
func FormatYAMLExample(yamlString string) string

// FormatValidOptions formats a list of valid options for error messages
func FormatValidOptions(options []string) string

// WithDocReference adds a documentation reference to an error
func WithDocReference(err error, docURL string) error

Implementation Plan

Phase 1: Design Message Builders (Day 1)

• Define function signatures for common error scenarios
• Design consistent output format for each builder
• Document usage patterns and examples

Phase 2: Implement Core Builders (Day 1-2)

• Implement 7+ reusable message builder functions
• Add comprehensive tests in validation_messages_test.go
• Ensure all builders produce consistent, high-quality messages

Phase 3: Refactor Examples (Day 2)
Demonstrate usage by refactoring 3 validators:

1. pkg/workflow/runtime_validation.go
2. pkg/workflow/npm_validation.go
3. pkg/workflow/pip_validation.go

Example Usage

Before:

return fmt.Errorf("missing field 'engine'")

After:

return MissingRequiredFieldError("engine", "engine: copilot")

Benefits:

• Consistent error message structure
• Automatic inclusion of examples
• Easier to improve all error messages at once
• Simplified validator code

Message Builders

1. MissingRequiredFieldError

return MissingRequiredFieldError("engine", "engine: copilot")
// Output: "missing required field 'engine'. Example:\nengine: copilot"

2. InvalidFieldTypeError

return InvalidFieldTypeError("timeout", "number", "string", "timeout: 30")
// Output: "field 'timeout' has invalid type: expected number, got string. Example:\ntimeout: 30"

3. InvalidFieldValueError

return InvalidFieldValueError("engine", "invalid", []string{"copilot", "claude", "codex"}, "engine: copilot")
// Output: "field 'engine' has invalid value: 'invalid'. Valid values are: copilot, claude, codex. Example:\nengine: copilot"

4. ConfigurationConflictError

return ConfigurationConflictError(
    []string{"mcp-servers", "tools"},
    "Use 'tools' field instead",
    "tools:\n  github:\n    mode: remote"
)
// Output: "configuration conflict: fields 'mcp-servers' and 'tools' are mutually exclusive. Resolution: Use 'tools' field instead. Example:\ntools:\n  github:\n    mode: remote"

Success Criteria

• New file pkg/workflow/validation_messages.go created
• At least 7 reusable message builders implemented
• Functions cover: missing field, invalid type, invalid value, configuration conflict, example formatting
• At least 3 existing validators refactored to use new helpers
• Comprehensive tests in validation_messages_test.go
• Documentation in file explaining when to use each helper
• Run make agent-finish successfully

Expected Outcomes

• Consistent error message structure across all validators
• Reduced code duplication (127 error sites → reusable components)
• Easier to improve error message quality across the codebase
• Simplified creation of new validators

Priority

Medium - Code quality improvement, enables consistency

Estimated Effort

Medium (1-2 days)

Dependencies

Should reference:

• Validation error message style guide (defines what "good" looks like)

Files to Create

• pkg/workflow/validation_messages.go (new file)
• pkg/workflow/validation_messages_test.go (new file)

Files to Update (Examples)

• pkg/workflow/runtime_validation.go
• pkg/workflow/npm_validation.go
• pkg/workflow/pip_validation.go

Source

Extracted from Repository Quality Improvement Report #11292 - Validation Message Clarity & Developer Guidance (Task 4)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 12, 2026, 9:09 PM UTC