Explore codemod tooling for automated migrations #409
Description
Problem
Find/replace patterns work but are error-prone:
- Developers may miss edge cases
- Complex transformations need manual work
- No validation that migration is complete
Codemods (automatic code transformation tools) could provide safer migrations.
Spike Goals
Evaluate codemod options for Python and determine if dioxide should invest in this tooling.
Options to Evaluate
-
LibCST (from Instagram/Meta)
- Concrete syntax tree preserves formatting
- Python-native
- Used by large codebases
-
Bowler (from Facebook)
- Built on LibCST
- Query language for finding patterns
- Simpler API
-
Pyupgrade approach
- Simple pattern matching
- Works for common cases
Prototype Task
Create a proof-of-concept codemod for the v1.x to v2.0 Profile change:
# Before
profile.value
Profile.PRODUCTION.value
# After
str(profile)
str(Profile.PRODUCTION)Evaluation Criteria
| Criteria | Weight | Notes |
|---|---|---|
| Ease of writing codemods | High | Maintainability |
| Preserves formatting | Medium | Developer experience |
| Handles edge cases | High | Safety |
| Easy to distribute | Medium | User experience |
| Maintenance burden | High | Long-term cost |
Deliverable
Recommendation document:
- Tool comparison results
- Prototype codemod (if feasible)
- Recommendation: Invest in codemods or stick to find/replace
- Cost/benefit analysis
Acceptance Criteria
- At least 2 tools evaluated
- Prototype codemod attempted
- Recommendation documented
- If positive: Roadmap for codemod tooling
- If negative: Document why find/replace is sufficient
Blocked By
- BDD Bootstrap: API Stability and Migration Tests #377 (BDD Bootstrap: API Stability and Migration Tests)
- Write comprehensive v1.x to v2.0 migration guide #405 (v2.0 migration guide - understand what needs automating)
Part of Epic
#371 (Breaking Change Prevention and Migration Story)