codemod

name	codemod
description	Codemod (JSSG, ast-grep, workflows) best practices for writing efficient, safe, and maintainable code transformations. This skill should be used when writing, reviewing, or debugging codemods, AST transformations, or automated refactoring tools. Triggers on tasks involving codemod, ast-grep, JSSG, code transformation, or automated migration.

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.