[go-fan] Go Module Review: go-yaml

[github-actions[bot]]

🐹 Go Fan Report: github.com/goccy/go-yaml

Module Overview

goccy/go-yaml is a modern, high-performance YAML parser for Go that was written from scratch to replace the legacy go-yaml/yaml library. It's the backbone of gh-aw's GitHub Actions workflow compilation system, providing better parsing capabilities, reversible transformations with comments/anchors, and full encoding/json behavior compatibility.

Key Features:

• Zero dependencies
• Better YAML Test Suite coverage (354 vs 295 test cases)
• AST manipulation with comments and anchors
• YAMLPath query support
• Pretty formatted validation errors
• Performance optimized for Go

Current Usage in gh-aw

The module is extensively used throughout the workflow compilation pipeline:

• Files Using Module: 20+ Go files in pkg/workflow/ and pkg/cli/
• Import Count: Heavy usage across compiler, validation, and generation code
• Key APIs Used:
  • yaml.Unmarshal() - Standard unmarshaling
  • yaml.Marshal() / yaml.MarshalWithOptions() - Custom marshaling with field ordering
  • yaml.MapSlice / yaml.MapItem - Ordered maps for GitHub Actions field order
  • yaml.Indent(), yaml.UseLiteralStyleIfMultiline() - GitHub Actions formatting

Usage Highlights

1. Custom Field Ordering (pkg/workflow/yaml.go:42)

func MarshalWithFieldOrder(data map[string]any, priorityFields []string) ([]byte, error) {
    orderedData := OrderMapFields(data, priorityFields)
    return yaml.MarshalWithOptions(orderedData,
        yaml.Indent(2),
        yaml.UseLiteralStyleIfMultiline(true),
    )
}

2. Schema Validation (pkg/workflow/schema_validation.go:94)

// Parse YAML directly for schema validation without JSON roundtrip
var workflowData any
yaml.Unmarshal([]byte(yamlContent), &workflowData)
schema.Validate(workflowData) // Direct validation

3. Frontmatter Extraction (pkg/workflow/frontmatter_extraction.go:73)

// Extract and re-marshal YAML sections with proper ordering
orderedValue := OrderMapFields(valueMap, []string{})
yaml.MarshalWithOptions(wrappedData, yaml.Indent(2), yaml.UseLiteralStyleIfMultiline(true))

Research Findings

Repository Analysis

• URL: https://github.com/goccy/go-yaml
• Stars: ~1.5k+ stars
• Actively Maintained: ✅ Yes (latest release: Nov 2025)
• Latest Version: v1.19.0 (Released: 2025-11-29)
• Current gh-aw Version: v1.18.0 (one version behind)

Recent Updates (v1.19.0)

The latest version includes several valuable improvements:

1. RawMessage Support - Added yaml.RawMessage similar to json.RawMessage for deferred decoding
2. Field Prefix Support - New decode option to allow specific field prefixes
3. CRLF Normalization - Better handling of CR and CRLF in multi-line strings
4. Non-String Map Keys - Support for non-string map keys
5. Path Operations - Skip directive in path operations
6. Flow Style Indentation - Improved indentation for flow values on new lines

Best Practices from Maintainers

1. Use MapSlice for Field Ordering - Essential for GitHub Actions where field order matters
2. Options for Formatting - yaml.Indent(2) and yaml.UseLiteralStyleIfMultiline(true) are recommended
3. Context-Aware Errors - Wrap errors with context using fmt.Errorf
4. Decoder/Encoder Pattern - Use for streaming or custom options
5. Validation Integration - Parse to any type for JSON Schema validation
6. YAMLPath Queries - Use PathString() for extracting specific values

Improvement Opportunities

🏃 Quick Wins (High Impact, Low Effort)

1. Upgrade to v1.19.0

Impact: Low-risk upgrade with new features

• Get RawMessage support for deferred decoding
• Better CRLF handling in multiline strings
• Non-string map key support
• All bug fixes from the latest release

Action: Update go.mod from v1.18.0 to v1.19.0

2. Add Strict Mode Decoding

Impact: Catch typos and unknown fields early

• Use yaml.Strict() option to detect unknown fields
• Prevents silent failures from typos in workflow YAML
• Better developer experience with early error detection

Example:

if err := yaml.UnmarshalWithOptions(content, &data, yaml.Strict()); err != nil {
    return fmt.Errorf("invalid workflow field: %w", err)
}

Locations: Schema validation, workflow parsing, lock file parsing

3. Enable Colored Error Output

Impact: Better error visibility for developers

• Use yaml.FormatError() for enhanced error messages
• Shows YAML source context with syntax highlighting
• Helps quickly locate and fix YAML issues

Example:

if err := yaml.Unmarshal(content, &data); err != nil {
    formatted := yaml.FormatError(err, true, true) // colorize and show source
    return fmt.Errorf("YAML parse error:\n%v", formatted)
}

4. Centralize YAML Encoding Options

Impact: DRY principle, consistent formatting

• Repeated MarshalWithOptions calls with same options
• Create shared function for GitHub Actions YAML options

Example:

func githubActionsYAMLOptions() []yaml.EncodeOption {
    return []yaml.EncodeOption{
        yaml.Indent(2),
        yaml.UseLiteralStyleIfMultiline(true),
    }
}

Locations: yaml.go, compiler.go, frontmatter_extraction.go, agentic_engine.go

✨ Feature Opportunities (Medium Impact, Medium Effort)

5. Use yaml.RawMessage for Deferred Decoding (v1.19.0+)

Impact: Performance and flexibility

• Defer decoding of complex sections until needed
• Useful for conditional workflow sections
• Similar to json.RawMessage pattern

Example:

type WorkflowData struct {
    On      yaml.RawMessage `yaml:"on"`
    Jobs    yaml.RawMessage `yaml:"jobs"`
    // Decode these only when validation passes
}

6. Use YAMLPath for Value Extraction

Impact: More concise, less error-prone code

• Replace manual map traversal with YAMLPath queries
• Better for complex nested structures
• More maintainable code

Example:

// Instead of manual map walking
path, _ := yaml.PathString("$.jobs.*.runs-on")
var runnerTypes []string
path.Read(strings.NewReader(yamlContent), &runnerTypes)

Locations: frontmatter_extraction.go, schema_validation.go

7. Leverage Decoder Options

Impact: Better control over parsing

• Use yaml.NewDecoder() with custom options
• Add yaml.ReferenceDirs() for anchor resolution across files
• Streaming support for large workflows

Example:

dec := yaml.NewDecoder(reader,
    yaml.Strict(),
    yaml.ReferenceDirs("includes/"),
)

8. Implement Comment Preservation

Impact: Human-readable workflow files

• Use yaml.CommentToMap() to preserve comments
• Useful for maintaining documentation in workflow files
• Better for generated workflows that need explanations

📐 Best Practice Alignment (Code Quality)

9. Audit and Fix Error Handling Patterns

Issue: Inconsistent error handling in compiler.go

• Several if err == nil checks suggest potential silent error ignoring
• Should use explicit error handling with context

Example Issue (compiler.go):

if err := yaml.Unmarshal(...); err == nil {
    // Only processes if successful, but silently ignores errors
}

Recommended Pattern:

if err := yaml.Unmarshal(...); err != nil {
    return fmt.Errorf("failed to parse workflow steps: %w", err)
}
// Process successful case here

Locations: compiler.go (multiple instances)

10. Document MapSlice Usage

Impact: Better code maintainability

• Add comments explaining why MapSlice is used
• Makes field ordering intention clear

Example:

// Use MapSlice to maintain GitHub Actions field order (name, on, jobs, etc.)
// GitHub Actions is sensitive to field order for readability
orderedData := yaml.MapSlice{...}

11. Use Encoder for Large Workflows

Impact: Memory efficiency

• For large workflows, use yaml.NewEncoder() for streaming
• More memory efficient than Marshal for large files

Example:

enc := yaml.NewEncoder(writer)
enc.SetIndent(2)
if err := enc.Encode(workflowData); err != nil {
    return fmt.Errorf("failed to write workflow: %w", err)
}

12. Validate YAML Before Schema Validation

Impact: Better error messages

• Use yaml.Validate() to check YAML syntax first
• Separate YAML syntax errors from schema validation errors
• Clearer feedback to users

Example:

if err := yaml.Validate([]byte(yamlContent)); err != nil {
    return fmt.Errorf("invalid YAML syntax: %w", err)
}
// Proceed with schema validation only if YAML is valid

🔧 General Improvements (Long-term)

13. Consider AST Manipulation for Advanced Cases

Use Cases:

• Comment injection
• Anchor management
• Complex transformations

When to Use: When string manipulation isn't sufficient

14. Add YAML Benchmarks

Purpose:

• Track marshal/unmarshal performance
• Ensure efficient processing for large workflows
• Detect performance regressions

15. Custom Marshalers for Workflow Types

Impact: Better control over output format

• Register custom marshalers for complex workflow structures
• More precise YAML generation

Example:

yaml.RegisterCustomMarshaler(WorkflowStep{}, func(v interface{}) ([]byte, error) {
    // Custom marshaling logic for steps
})

Recommendations

Priority 1 (Immediate - This Week)

1. ✅ Upgrade to v1.19.0 - One version behind, low-risk upgrade
2. ✅ Add Strict Mode - Quick win, prevents common errors
3. ✅ Audit Error Handling - Fix silent error cases in compiler.go

Priority 2 (Short-term - Next Sprint)

4. ⏭️ Centralize YAML Options - Reduce code duplication
5. ⏭️ Enable Colored Errors - Better developer experience
6. ⏭️ Use YAMLPath - Cleaner code for value extraction

Priority 3 (Long-term - Future Iterations)

7. 🔮 RawMessage Support - Performance optimization
8. 🔮 Comment Preservation - Enhanced output quality
9. 🔮 Custom Marshalers - Advanced use cases

Next Steps

1. Create PR to upgrade to v1.19.0

   • Update go.mod: go get github.com/goccy/go-yaml@v1.19.0
   • Run tests to ensure compatibility
   • Update any deprecated APIs if needed

2. Add yaml.Strict() to critical paths

   • Schema validation parsing
   • Workflow file parsing
   • Lock file unmarshaling

3. Refactor error handling in compiler.go

   • Change if err == nil patterns to explicit error handling
   • Add context to all YAML errors

4. Create shared YAML options function

   • Extract repeated MarshalWithOptions calls
   • Centralize GitHub Actions formatting options

5. Add benchmarks for YAML operations

   • Measure current performance baseline
   • Track improvements from v1.19.0

---

Module summary saved to: specs/mods/go-yaml.md

References:

• Repository: https://github.com/goccy/go-yaml
• Documentation: https://pkg.go.dev/github.com/goccy/go-yaml
• Playground: (redacted)
• Latest Release: https://github.com/goccy/go-yaml/releases/tag/v1.19.0

AI generated by Go Fan

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #5271.
Fair winds, matey! 🏴‍☠️