Go Codemod Implementation Guide

Use this skill when adding or updating codemods used by gh aw fix.

Understand the fix pipeline first

1. Review pkg/cli/fix_command.go to understand execution flow:

• codemods are loaded once via GetAllCodemods()
• each codemod is applied in registry order
• frontmatter is re-parsed before each codemod
• codemods must return (newContent, applied, error) and be safe for no-op input

1. Review the codemod registry in pkg/cli/fix_codemods.go.
2. Review helper utilities in pkg/cli/yaml_frontmatter_utils.go and reusable codemod helper constructors in pkg/cli/codemod_factory.go.

Implementation steps

1. Create a new codemod file in pkg/cli/ named codemod_<feature>.go.
2. Add a package logger with logger.New("cli:codemod_<feature>").
3. Implement get<Feature>Codemod() Codemod and populate all metadata fields:

• ID (stable, unique)
• Name (human-readable)
• Description (clear migration behavior)
• IntroducedIn (release version)

1. In Apply:

• check frontmatter preconditions first
• return unchanged content and applied=false when migration is not needed
• transform only frontmatter using applyFrontmatterLineTransform from pkg/cli/yaml_frontmatter_utils.go
• preserve comments/formatting/markdown body
• avoid lossy rewrites and avoid touching unrelated keys

1. Prefer existing helpers before writing custom parsing logic:

• findAndReplaceInLine
• removeFieldFromBlock
• removeParentBlockIfTrulyEmpty
• newFieldRemovalCodemod
• newMoveTopLevelKeyToOnBlockCodemod

1. If the codemod depends on external data or side effects, inject dependencies through a ...WithDeps constructor so tests can mock behavior.
2. Register the codemod in pkg/cli/fix_codemods.go within GetAllCodemods().

Testing requirements

Create pkg/cli/codemod_<feature>_test.go and cover:

1. Metadata correctness (ID, Name, Description, IntroducedIn, Apply != nil).
2. Happy path migration with expected output.
3. No-op behavior when deprecated input is absent.
4. Idempotence behavior (already-migrated input remains unchanged).
5. Preservation guarantees:

• inline comments
• indentation
• markdown body after frontmatter

1. Edge cases specific to the codemod (nested fields, mixed forms, ordering constraints, strict-mode checks, etc.).
2. Dependency-injection behavior if ...WithDeps exists (success and fallback/error paths).

When complexity is high (expression rewriting, parser-like behavior), add fuzz tests in codemod_<feature>_fuzz_test.go using the pattern in pkg/cli/codemod_steps_run_secrets_env_fuzz_test.go.

Registry/order tests

After adding a codemod, update pkg/cli/fix_codemods_test.go:

1. Expected codemod IDs list.
2. Expected codemod order list.

Order matters because codemods run sequentially and later codemods observe prior transformations.

Validation commands

Run targeted checks first:

1. go test -v ./pkg/cli -run Codemod -count=1
2. go test -v ./pkg/cli -run Fix -count=1

Then run repository standards:

1. make build
2. make test-unit
3. make lint

Quality bar

A codemod is ready only when it is:

• deterministic
• safe on repeated runs
• conservative (no unrelated rewrites)
• fully covered by tests for migration and no-op paths
• registered and order-verified in fix codemod registry tests