A Comprehensive Guide to Code Modification (Codemod) Tools and AST Transformations

Code modification (codemod) is a powerful technique for automating large‑scale codebase changes, and the article showcases many real‑world scenarios such as migrating native WeChat mini‑programs to Taro, fixing Sonar/Eslint issues, extracting multilingual strings, and upgrading frameworks like Next.js or Vue 3.

The recommended workflow consists of five stages: file discovery (e.g., using Glob ), AST parsing (choosing a parser like Babel , Esprima , Acorn , or swc ), AST transformation (using tools such as Jscodeshift or gogocode ), code generation (preserving original formatting with recast or prettier ), and writing the transformed files back to disk.

Key libraries are introduced:

Recast

Recast provides a nondestructive AST transformer that retains original code layout. Its core API includes parse and print :

import { parse, print } from "recast";
console.log(print(parse(source)).code);

It works with various parsers (Esprima by default, also Babel, Acorn) and relies on the ESTree standard.

jscodeshift

jscodeshift, a Meta open‑source codemod runner, wraps Recast and offers a jQuery‑like API for finding and transforming nodes. Example runner skeleton:

module.exports = function(fileInfo, api, options) {
  // transform `fileInfo.source` here
  // ...
  return source;
};

Its Collection class provides chainable methods such as find , replaceWith , and toSource .

gogocode

gogocode, an Alibaba‑Mama project, supports wildcard selectors (e.g., 'const a = $_$' ) and converts selectors into a "Selector AST" for matching against the source AST. It uses Recast under the hood and can handle Vue and HTML files.

// Example selector with wildcard
ast.find('const a = $_$');

Note that wildcard groups are not automatically validated for equality.

ast‑grep

ast‑grep is a Rust‑based, tree‑sitter powered tool for fast pattern matching across many languages. Example usage:

$ sg --pattern '$PROP && $PROP()' --lang ts src
$ sg --pattern 'var code = $PAT' --rewrite 'let code = $PAT' --lang js

It excels at simple find‑and‑replace tasks but may require lower‑level parsers for complex migrations.

The article concludes with a pyramid comparison of the tools, emphasizing that higher‑level solutions require less custom code, while low‑level parsers offer maximum flexibility for intricate refactoring needs.