[plan] Add file/line context to validation errors

[github-actions]

Objective

Enhance validation errors with file path and line number context so users can quickly locate and fix problematic configuration in their workflow files.

Context

From discussion #33307: Currently, validation errors don't include workflow file path or line number. Users must manually search their entire workflow to find the problematic field. This is similar to compiler errors that show file:line:column for quick navigation.

Approach

1. Extend the frontmatter parser to track line numbers for each field during YAML parsing
2. Store line number metadata alongside parsed configuration
3. Update WorkflowValidationError struct to include File and Line fields
4. Modify error formatting to display location information in a standard format
5. Update validation functions to pass location context when creating errors

Files to Modify

• Update: pkg/parser/frontmatter_parser.go (track line numbers during parsing)
• Update: pkg/workflow/errors.go (add File/Line fields to WorkflowValidationError)
• Update: pkg/workflow/error_formatting.go (format errors with file:line prefix)
• Update: pkg/workflow/*_validation.go (pass line context when creating errors)
• Update: pkg/workflow/frontmatter_types.go (store line metadata with config)

Technical Considerations

YAML Line Tracking:
The goccy/go-yaml library (used for YAML 1.1/1.2 compatibility) provides position information through yaml.Node.GetToken(). Use this to track line numbers during parsing.

Example Implementation:

// Store line metadata during parsing
type FieldLocation struct {
    File string
    Line int
    Column int
}

// Enhanced error creation
return NewValidationErrorWithLocation(
    field,
    value,
    reason,
    suggestion,
    FieldLocation{File: workflowPath, Line: 15, Column: 3}
)

// Error output format
// workflow.md:15:3: validation error in field 'engine'
//   Value: 'copiliot'
//   Reason: engine 'copiliot' is not valid
//   Suggestion: Did you mean 'copilot'?

Acceptance Criteria

• Frontmatter parser tracks line numbers for all fields
• WorkflowValidationError includes File and Line fields
• Error messages display location in format file:line: error message
• All validation errors include location context when available
• Location tracking doesn't break existing error handling
• Performance impact is negligible (line tracking shouldn't slow parsing)
• Error output is compatible with editor/IDE "jump to error" features
• Run make agent-finish successfully before committing

Testing Strategy

1. Create test workflow with validation error on line 10
2. Verify error message includes "workflow.md:10:"
3. Test nested fields show correct line numbers
4. Test errors without location context still work (graceful fallback)
5. Verify all existing tests pass with new error format
6. Benchmark parsing performance before/after changes

Edge Cases

• Handle missing file path (e.g., in-memory workflows)
• Handle YAML anchors/aliases that reference different lines
• Handle multiline field values (which line to report?)
• Handle programmatically generated errors (no source location)

Reference

• Source: Discussion [repository-quality] Repository Quality Improvement Report - Error Message UX & Actionability #33307 (Repository Quality Improvement Report - Error Message UX)
• YAML library: goccy/go-yaml documentation on position tracking
• Similar feature: Go compiler error format, TypeScript compiler errors
• See: scratchpad/yaml-version-gotchas.md for YAML library usage

Generated by 📋 Plan Command · ● 12.7M · ◷

• expires on May 21, 2026, 2:12 PM UTC

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ● 286.5K · ◷