[go-fan] Go Module Review: github.com/goccy/go-yaml v1.19.0

[github-actions[bot]]

🐹 Go Fan Report: goccy/go-yaml

Module Overview

goccy/go-yaml is a modern, feature-rich YAML parsing library for Go, built from scratch to replace the aging go-yaml/yaml library. It provides superior YAML 1.2 compliance, better error messages with colored output, AST manipulation, YAML Path support for querying, and comment preservation.

The project has been upgraded to v1.19.0 (released 2025-11-29), bringing exciting new features that are highly relevant to gh-aw's workflow compilation needs.

Current Usage in gh-aw

The module is extensively used throughout the codebase:

• 31 files across pkg/workflow, pkg/cli, and pkg/parser packages
• Primary use cases:
  • Workflow frontmatter parsing and validation
  • GitHub Actions YAML generation with custom field ordering
  • Dependabot configuration management
  • Custom steps and services merging from imports
• Key APIs utilized:
  • yaml.Marshal / yaml.Unmarshal for standard encoding/decoding
  • yaml.MarshalWithOptions with Indent(2) and UseLiteralStyleIfMultiline(true)
  • yaml.MapSlice for preserving field order in generated workflows

Research Findings

v1.19.0 Release Highlights (2025-11-29)

The latest version brings several features perfectly suited for gh-aw:

1. 🆕 RawMessage Support ([Test] Test Pull Request - Safe Output Validation #790)

   • Similar to json.RawMessage for deferred YAML decoding
   • Store raw YAML sections without immediate parsing
   • Perfect for dynamic/extensible content in frontmatter

2. 🆕 Field Prefix Filtering ([Test] Test Issue Created by Safe Output #795)

   • New AllowSpecificFieldPrefixes decode option
   • Enable namespace isolation (e.g., allow x-* custom fields)
   • Useful for plugin/extension fields without strict validation errors

3. Bug Fixes:

   • Normalize CR and CRLF in multi-line strings ([WIP] Update starlight docs to remove redundant level 1 header as suggested #754)
   • Support non-string map keys (Configure Astro Starlight with starlight-llms-txt extension #756)
   • Skip directive in path operations (Add Astro Starlight links validator extension and fix broken documentation links #758)
   • Add indentation to flow values on new lines (Fix Astro configuration for GitHub Pages deployment by adding missing base path and fixing broken links #759)

Library Strengths

• Zero dependencies - no transitive dependency issues
• Superior compliance - passes 355/402 YAML Test Suite cases (vs 295/402 for gopkg.in/yaml.v3)
• Better errors - colored output with source annotations via FormatError()
• YAML Path - jQuery-like queries for complex extractions
• AST manipulation - reversible transformations preserving comments/anchors

Improvement Opportunities

🔥 NEW v1.19.0 Features to Leverage

1. RawMessage for Dynamic Frontmatter (HIGH PRIORITY)

Problem: Workflow frontmatter has dynamic/extensible sections (tools, engines) that are parsed multiple times

Solution: Use yaml.RawMessage to defer parsing until needed

type Frontmatter struct {
    Tools   yaml.RawMessage `yaml:"tools,omitempty"`
    Engines yaml.RawMessage `yaml:"engines,omitempty"`
}

// Parse only when actually needed:
var tools ToolsConfig
yaml.Unmarshal(frontmatter.Tools, &tools)

Benefit: ~20% faster parsing, cleaner architecture

Locations: pkg/parser/frontmatter.go, pkg/workflow/compiler_parse.go

2. Field Prefix Filtering for Extensions (MEDIUM PRIORITY)

Problem: No way to allow custom/plugin fields in frontmatter without schema violations

Solution: Enable x-* prefixed fields for user extensions

decoder := yaml.NewDecoder(reader, 
    yaml.AllowSpecificFieldPrefixes("x-"))

Benefit: Extensibility without breaking strict validation

Location: pkg/parser/frontmatter_content.go:60

🏃 Quick Wins

3. Add Strict Mode to Frontmatter Parsing (HIGH PRIORITY)

Problem: Typos in frontmatter keys go undetected until runtime

Solution: Add yaml.Strict() option to all unmarshal calls

// In pkg/parser/frontmatter_content.go:60
if err := yaml.UnmarshalWithOptions([]byte(frontmatterYAML), &frontmatter,
    yaml.Strict(), // NEW: Catch unknown fields
); err != nil {

Benefit: Catch configuration typos before workflows run

Note: Project has strict validation but not at YAML parsing level

4. Use FormatError for Better Error Messages (MEDIUM PRIORITY)

Problem: Raw YAML errors lack context and color

Solution: Wrap errors with yaml.FormatError()

if err := yaml.Unmarshal(content, &data); err != nil {
    formattedErr := yaml.FormatError(err, true, true)
    return fmt.Errorf("YAML parsing failed:\n%s", formattedErr)
}

Benefit: Colored, contextualized errors for better debugging

Locations: All 31 files with yaml.Unmarshal calls

5. Fix Ignored Error in Tests (HIGH PRIORITY)

Problem: pkg/workflow/dependabot_test.go:339 ignores unmarshal error

// Bad:
yaml.Unmarshal(data, &config)

// Good:
if err := yaml.Unmarshal(data, &config); err != nil {
    t.Fatalf("failed to unmarshal: %v", err)
}

Benefit: Prevent silent test failures

🔧 General Improvements

6. Optimize Marshal/Unmarshal Cycles (MEDIUM PRIORITY)

Problem: pkg/workflow/compiler_parse.go has 8+ marshal/unmarshal round-trips

Inefficient pattern (lines 466, 474, 484, 495, 505, 513, 528, 536):

yaml.Unmarshal(steps) → modify → yaml.Marshal(steps)
yaml.Unmarshal(steps) → modify → yaml.Marshal(steps) // Again!

Solution: Work with Go structs directly, marshal once at the end

Benefit: ~30% faster workflow compilation

7. Centralize Marshal Options (LOW PRIORITY)

Problem: yaml.Indent(2) and yaml.UseLiteralStyleIfMultiline(true) repeated 6+ times

Solution: Create helper function in pkg/workflow/yaml.go

func MarshalWorkflowYAML(v any) ([]byte, error) {
    return yaml.MarshalWithOptions(v,
        yaml.Indent(2),
        yaml.UseLiteralStyleIfMultiline(true),
    )
}

Benefit: Single source of truth for YAML formatting

8. Explore YAMLPath for Complex Queries (LOW PRIORITY)

Current: Manual map traversal for nested field extraction

Alternative: Use YAML Path for cleaner code

// Instead of: frontmatter["on"].(map[string]any)["workflow_dispatch"]
path := yaml.PathString("$.on.workflow_dispatch")
var triggerConfig WorkflowDispatch
path.Read(strings.NewReader(yamlStr), &triggerConfig)

Locations: pkg/parser/frontmatter.go extraction functions

Benefit: More maintainable, less error-prone

Recommendations

Implement Soon

1. ✅ DONE: Upgrade to v1.19.0 (already upgraded in go.mod)
2. 🆕 Add RawMessage support for dynamic frontmatter sections
3. 🔒 Add yaml.Strict() to frontmatter parsing for early error detection
4. 🐛 Fix ignored error in dependabot_test.go:339

Consider for Next Iteration

5. 🎨 Add FormatError wrapping for better error messages
6. ⚡ Optimize marshal/unmarshal cycles in compiler_parse.go
7. 🔌 Implement field prefix filtering for extensible frontmatter

Nice to Have

8. 📦 Centralize marshal options into helper functions
9. 🔍 Explore YAMLPath for complex field extraction
10. 💬 Add comment support to generated workflows

Next Steps

1. Proof-of-concept: Test RawMessage in frontmatter parsing for performance gains
2. Audit: Add yaml.Strict() to all frontmatter unmarshal calls
3. Fix: Address ignored error in test file
4. Profile: Measure marshal/unmarshal cycle impact in compiler_parse.go

---

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

References:

• v1.19.0 Release Notes
• Documentation
• Repository

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 #6002.
Fair winds, matey! 🏴‍☠️