pproenca/dot-skills/codemod

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.