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 Priority Category Impact Prefix 1 AST Understanding CRITICAL ast- 2 Pattern Efficiency CRITICAL pattern- 3 Parsing Strategy CRITICAL parse- 4 Node Traversal HIGH traverse- 5 Semantic Analysis HIGH semantic- 6 Edit Operations MEDIUM-HIGH edit- 7 Workflow Design MEDIUM-HIGH workflow- 8 Testing Strategy MEDIUM test- 9 State Management MEDIUM state- 10 Security and Capabilities LOW-MEDIUM security- 11 Package Structure LOW 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.