[Code Quality] Document YAML processing patterns using map[string]any

[github-actions]

Description

The codebase extensively uses map[string]any for YAML/JSON processing (1,313 occurrences), which might appear as weak typing to newcomers. Add package-level documentation explaining why this is intentional and idiomatic for a workflow compiler that processes user-defined YAML with dynamic structures.

This addresses a finding from the Typist - Go Type Consistency Analysis (#11485).

Suggested Changes

Add package-level documentation to explain the YAML processing pattern:

// Package workflow implements a GitHub Actions workflow compiler.
//
// YAML Processing Pattern:
// This package extensively uses map[string]any for processing user-defined
// YAML workflows. This is intentional and idiomatic:
//   1. User workflows have dynamic, unknown-at-compile-time structures
//   2. YAML unmarshaling produces map[string]any for flexibility
//   3. Parser functions convert untyped maps to strongly-typed config structs
//   4. The any type allows graceful handling of invalid/unknown YAML
//
// When contributing, maintain this pattern: accept map[string]any for parsing,
// validate thoroughly, and return strongly-typed structs.
package workflow

Files Affected

• pkg/workflow/ (package documentation)
• pkg/parser/ (package documentation)
• CONTRIBUTING.md or DEVGUIDE.md (optional: reference the pattern)

Success Criteria

• Package documentation added to pkg/workflow and pkg/parser
• Documentation explains why map[string]any is appropriate
• Guidance provided for contributors on maintaining the pattern
• Optional: Contributing guidelines reference this pattern

Source

Extracted from Typist - Go Type Consistency Analysis discussion #11485

The analysis found the heavy use of any is justified and appropriate for a workflow compiler, but documentation would help new contributors understand the design decision.

Priority

Low - Helps new contributors understand design decisions. Estimated effort: 30 minutes.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 14, 2026, 1:35 AM UTC