Codemod Best Practices

Comprehensive best practices guide for Codemod (JSSG, ast-grep, workflows), designed for AI agents and LLMs. Contains 48 rules across 11 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new codemods with JSSG or ast-grep
• Designing workflow configurations for migrations
• Debugging pattern matching or AST traversal issues
• Reviewing codemod code for performance and safety
• Setting up test fixtures for transform validation

Rule Categories by Priority

ast-

pattern-

parse-

traverse-

semantic-

edit-

workflow-

test-

state-

security-

pkg-

Quick Reference

1. AST Understanding (CRITICAL)

• ast-explore-before-writing

  - Use AST Explorer before writing patterns

• ast-understand-named-vs-anonymous

  - Understand named vs anonymous nodes

• ast-use-kind-for-precision

  - Use kind constraint for precision

• ast-field-access-for-structure

  - Use field access for structural queries

• ast-check-null-before-access

  - Check null before property access

2. Pattern Efficiency (CRITICAL)

• pattern-use-meta-variables

  - Use meta variables for flexible matching

• pattern-avoid-overly-generic

  - Avoid overly generic patterns

• pattern-combine-with-rules

  - Combine patterns with rule operators

• pattern-use-constraints

  - Use constraints for reusable matching logic

• pattern-use-relational-patterns

  - Use relational patterns for context

• pattern-ensure-idempotency

  - Ensure patterns are idempotent

3. Parsing Strategy (CRITICAL)

• parse-select-correct-parser

  - Select the correct parser for file type

• parse-handle-embedded-languages

  - Handle embedded languages with parseAsync

• parse-provide-pattern-context

  - Provide context for ambiguous patterns

• parse-early-return-non-applicable

  - Early return for non-applicable files

4. Node Traversal (HIGH)

• traverse-use-find-vs-findall

  - Use find() for single match, findAll() for multiple

• traverse-single-pass-collection

  - Collect multiple patterns in single traversal

• traverse-use-stopby-for-depth

  - Use stopBy to control traversal depth

• traverse-use-siblings-efficiently

  - Use sibling navigation efficiently

• traverse-cache-repeated-lookups

  - Cache repeated node lookups

5. Semantic Analysis (HIGH)

• semantic-use-file-scope-first

  - Use file scope semantic analysis first

• semantic-check-null-results

  - Handle null semantic analysis results

• semantic-verify-file-ownership

  - Verify file ownership before cross-file edits

• semantic-cache-cross-file-results

  - Cache semantic analysis results

6. Edit Operations (MEDIUM-HIGH)

• edit-batch-before-commit

  - Batch edits before committing

• edit-preserve-formatting

  - Preserve surrounding formatting in edits

• edit-handle-overlapping-ranges

  - Handle overlapping edit ranges

• edit-use-flatmap-for-conditional

  - Use flatMap for conditional edits

• edit-add-imports-correctly

  - Add imports at correct position

7. Workflow Design (MEDIUM-HIGH)

• workflow-order-nodes-by-dependency

  - Order nodes by dependency

• workflow-use-matrix-for-parallelism

  - Use matrix strategy for parallelism

• workflow-use-manual-gates

  - Use manual gates for critical steps

• workflow-validate-before-run

  - Validate workflows before running

• workflow-use-conditional-steps

  - Use conditional steps for dynamic workflows

8. Testing Strategy (MEDIUM)

• test-use-fixture-pairs

  - Use input/expected fixture pairs

• test-cover-edge-cases

  - Cover edge cases in test fixtures

• test-use-strictness-levels

  - Choose appropriate test strictness level

• test-update-fixtures-intentionally

  - Update test fixtures intentionally

• test-run-on-subset-first

  - Test on file subset before full run

9. State Management (MEDIUM)

• state-use-for-resumability

  - Use state for resumable migrations

• state-make-transforms-idempotent

  - Make transforms idempotent for safe reruns

• state-log-progress-for-observability

  - Log progress for long-running migrations

10. Security and Capabilities (LOW-MEDIUM)

• security-minimize-capabilities

  - Minimize requested capabilities

• security-validate-external-inputs

  - Validate external inputs before use

• security-review-before-running-third-party

  - Review third-party codemods before running

11. Package Structure (LOW)

• pkg-use-semantic-versioning

  - Use semantic versioning for packages

• pkg-write-descriptive-metadata

  - Write descriptive package metadata

• pkg-organize-by-convention

  - Organize package by convention

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Full Compiled Document

For a complete guide with all rules expanded, see AGENTS.md.