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

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.