Skip to main content
Codemods are automated code transformations that help refactor code across the codebase. We use LibCST for Python codemods.

​
Prerequisites

Your environment needs to have: 
export LIBCST_PARSER_TYPE=native

​
Running a Codemod

From the backend directory: 
# Install codemod dependencies
uv sync --group codemod

# Run a codemod
python -m libcst.tool codemod -- <codemod_name>.<command> <target_path>

​
Example

python -m libcst.tool codemod -- table_cell_value.ConvertTableCellValueCommand server/

​
Available Codemods

Codemods are located in backend/codemod/. Each codemod is a Python module with a command class that extends LibCST’s VisitorBasedCodemodCommand.

​
Writing a New Codemod

  1. Create a new file in backend/codemod/
  2. Define a codemod class:
from libcst.codemod import VisitorBasedCodemodCommand
import libcst as cst

class MyCodemodCommand(VisitorBasedCodemodCommand):
    DESCRIPTION = "Description of what this codemod does"

    def visit_Call(self, node: cst.Call) -> bool:
        # Visit logic
        return True

    def leave_Call(
        self, original_node: cst.Call, updated_node: cst.Call
    ) -> cst.Call:
        # Transform logic
        return updated_node
  1. Run your codemod:
python -m libcst.tool codemod -- my_module.MyCodemodCommand server/

​
Best Practices

  • Always test codemods on a small subset of files first
  • Review the changes before committing
  • Run the test suite after applying codemods
  • Consider adding unit tests for complex codemods