codemodとうまく付き合うには

codemodの実装のベストプラクティス（ https://zenn.dev/did0es/articles/17a503c6398c27 ）を踏まえ、より実用的な観点から、codemodの運用方法を考察します。

Transcript

1. codemodと うまく付き合うには 2024/01/19 Hirai Shuta
2. Hirai Shuta(did0es) Software engineer at CyberAgent, Inc. Main organizer at Meguro.es Maintainer for pmndrs/three-stdlib X : https://x.com/did0es GitHub : https://github.com/shuta13
3. 目次 1. 背景 2. ASTとjscodeshift 3. codemodのpros/cons 4. consに対処するための工夫 5. まとめ
4. 1. 背景
5. これの内容を元に、運用目線でcodemodについてお話します codemod zenn [検索]
6. これの内容を元に、運用目線でcodemodについてお話します
7. 対象① ・Deprecatedな文法の修正 　・JSDocでdeprecatedとしているものの削除と置換 　・300ファイル以上のjsx?|tsx?が対象 ・気づいた人が手でRecommendedな文法に直していた 　・が、差分でコンフリクトしまくり 　・自動化して、一撃で全部直したい
8. 対象② ・コード生成した成果物の名前の衝突解消 　・Plop.jsでコード生成する際のHandlebarsの記述をミスった 　　・a/b/c.ts が c.ts として扱われた（親ディレクトリの情報が抜け落ちた） 　・↑に気づかず運用、ある日 CI が落ちて気づく ・すべてのファイルの命名を一定のルールをもとに変更する 　・所属していたプロジェクトは60ファイルだったが... 　・自動化して、一撃で全部直したい
9. 解決案 ・正規表現 　・手っ取り早い 　・複雑な表現は🤯 　　・高度正規表現人材を雇用することが必要 ・AST 　・プログラマブルに置換できる 　・キャッチアップコスト😇 　　・周りにASTを広めることが必要
10. 2. jscodeshiftとAST
11. jscodeshift https://github.com/facebook/jscodeshift ・JavaScriptのASTのラッパー + 置換用CLI ・ASTの操作にはRecast(後述)が使われている ・Meta製 　・一瞬開発止まったが再開した様子
12. Recast ・JavaScript ASTパーサー ・以下を順に行う 　・ソースコードを AST に変換 　・AST を探索・置換 　・AST をソースコードに変換
13. 💡JavaScript ASTクイズ💡
14. これ何のJS AST？
15. Acorn
16. これ何のJS AST？
17. Esprima
18. Esprima ・Recastが使用しているJavaScript AST 　・ふんわり雰囲気だけ掴んでください ・ちなみにJavaScriptのASTを辿っていくと 　これか前述のAcornのどれかにたどり着く(はず)
19. 3. codemodのpros/cons
20. pros：コマンド一発 ・codemodはCLI でオプションを組み合わせて使う想定 ・対話型と違って、コピって人に渡しやすい 　（なんかフロント周辺のCLIは対話型が多い）
21. pros：修正過程がコードで残る ・人に手順を伝えやすい ・コマンド化しやすい ・再利用しやすい
22. pros：(比較的)楽しい ・心を無にして、grepした経験ありませんか？ ・コード書いてるな〜という気持ちになれる 　・機械的な作業感がなくなる 　・不思議とリファクタリングタスクの意欲が出る
23. cons：属人化 ・別にcodemodにだけ当てはまる話ではないが... ・codemodかけます！ASTをゴリゴリtraverseしてます！という人は 　あまり（僕の周りには）いなかった 　・周りにAST分かる人がいるならASTはかなり強力 　・いないなら啓蒙するか、諦めて正規表現100本ノック
24. cons：1回書いたら終わり ・いわゆる「動けばいい」で書かれてしまいがち 　・こういうモチベで書かれたコードは大抵本人も読めなくなる ・script系の宿命かもしれない 　・が、ある日再び必要となるときが来るので、残した（はず） 　　・再利用しないならそもそも共有しない
25. cons：デバッグ難易度が若干高い ・ASTをtraverseするため「今何回目のループ？」になりがち ・console.logを仕込んで粘る ・（後述の）ExplorerでASTを見る
26. 4. consに対処するための工夫
27. 工夫：codemod周辺技術を周りに広める 対象の課題：属人化 ・一般論ではありますが、勉強会しましょう！ 　・周りのcodemodやASTへのリテラシーを上げる 　・jscodeshiftのdocsを輪読、写経など ・ちなみに、実装した後にDesign Doc書いたが読まれなかった😭 　・多分もっと受動的にASTを知れるほうがいい
28. 工夫：jscodeshiftのtestUtilsでテスト書きまくる 対象の課題：1回書いたらおわり
29. jestでも書けるが... ・codemodはテストケース増えがち→tableがモリモリ増えて差分がつらい
30. テストケースの入出力の分離 ・testUtilsでファイルに切り出せる ・jscodeshiftの内部でも同様のテストが行われている
31. AST Explorerを使う 対象の課題：デバッグ難易度が若干高い
32. AST Parserを選ぶ 選択すると貼り付けたJSのASTが見れる + インスペクトできる
33. jscodeshiftのシミュレート AST Explorerでjscodeshiftを走らせて変換結果を見れる
34. これでも無理なら心を込めてconsole.log❤
35. 細かい目のTips
36. Tips①：$から始まる変数 ・jQueryではない ・@next/codemodのコードにちらほらある 　・jscodeshiftのインスタンスを格納する変数 　・jscodeshiftから取り出した値は $ なし ・何が良い？ 　・TSなくてもある程度戦える
37. Tips②：early return ・IOの回数は減らしたい ・jscodeshiftなら、各transformerごとに1回までが理想 　・returnすると変換のプロセスが終わってしまう ・ASTのtypeを見て、その後の処理を続けるかどうか判断する場面 　・ネストの数減らしたいのでearly returnしたくなる 　・なるべく jscodeshift.~~~.forEach 内に留める 　・即時関数などで1層覆っておく
38. Tips②：early return
39. 5. まとめ
40. 今までの所感と今後 ・対象①のケースのcodemodは作ってから3年くらい経つが運用されている 　・周囲にASTが分かる人がいたのが良かった ・対象②のケースは僕が離脱した時点で捨てられた(多分) 　・ASTにかかわらず使う技術は周りに広める　そこまでがセット ・今後 　・腐らないcodemodを書く 　・ESLintのFlat ConfigやTailwindCSSのclassName変換をやってみる
41. ご清聴ありがとうございました