Skip to content

Commit ba45d3f

Browse files
author
codegen-bot
committed
.
1 parent c5cd7a8 commit ba45d3f

File tree

3 files changed

+153
-54
lines changed

3 files changed

+153
-54
lines changed

‎docs/building-with-codegen/reusable-codemods.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: "Reusable Codemods"
3+
sidebarTitle: "Reusable Codemods"
4+
icon: "arrows-rotate"
5+
iconType: "solid"
6+
---
7+
8+
Codegen enables you to create reusable code transformations using Python functions decorated with `@codegen.function`. These codemods can be shared, versioned, and run by your team.
9+
10+
## Creating Codemods
11+
12+
The easiest way to create a new codemod is using the CLI [create](/cli/create) command:
13+
14+
```bash
15+
codegen create rename-function
16+
```
17+
18+
This creates a new codemod in your `.codegen/codemods` directory:
19+
20+
```python
21+
import codegen
22+
from codegen import Codebase
23+
24+
@codegen.function("rename-function")
25+
def run(codebase: Codebase):
26+
"""Add a description of what this codemod does."""
27+
# Add your code here
28+
pass
29+
```
30+
31+
<Note>
32+
Codemods are stored in `.codegen/codemods/name/name.py` and are tracked in Git for easy sharing.
33+
</Note>
34+
35+
### AI-Powered Generation with `-d`
36+
37+
You can use AI to generate an initial implementation by providing a description:
38+
39+
```bash
40+
codegen create rename-function -d "Rename the getUserData function to fetchUserProfile"
41+
```
42+
43+
This will:
44+
1. Generate an implementation based on your description
45+
2. Create a custom system prompt that you can provide to an IDE chat assistant (learn more about [working with AI](/introduction/work-with-ai))
46+
3. Place both files in the codemod directory
47+
48+
## Running Codemods
49+
50+
Once created, run your codemod using:
51+
52+
```bash
53+
codegen run rename-function
54+
```
55+
56+
The execution flow:
57+
1. Codegen parses your codebase into a graph representation
58+
2. Your codemod function is executed against this graph
59+
3. Changes are tracked and applied to your filesystem
60+
4. A diff preview shows what changed
61+
62+
63+
## Codemod Structure
64+
65+
A codemod consists of three main parts:
66+
67+
1. The `@codegen.function` decorator that names your codemod
68+
2. A `run` function that takes a `Codebase` parameter
69+
3. Your transformation logic using the Codebase API
70+
71+
```python
72+
import codegen
73+
from codegen import Codebase
74+
75+
@codegen.function("update-imports")
76+
def run(codebase: Codebase):
77+
"""Update import statements to use new package names."""
78+
for file in codebase.files:
79+
for imp in file.imports:
80+
if imp.module == "old_package":
81+
imp.rename("new_package")
82+
codebase.commit()
83+
```
84+
85+
## Arguments
86+
87+
Codemods can accept arguments using Pydantic models:
88+
89+
```python
90+
from pydantic import BaseModel
91+
92+
class RenameArgs(BaseModel):
93+
old_name: str
94+
new_name: str
95+
96+
@codegen.function("rename-function")
97+
def run(codebase: Codebase, arguments: RenameArgs):
98+
"""Rename a function across the codebase."""
99+
old_func = codebase.get_function(arguments.old_name)
100+
if old_func:
101+
old_func.rename(arguments.new_name)
102+
codebase.commit()
103+
```
104+
105+
Run it with:
106+
```bash
107+
codegen run rename-function --arguments '{"old_name": "getUserData", "new_name": "fetchUserProfile"}'
108+
```
109+
110+
## Directory Structure
111+
112+
Your codemods live in a dedicated directory structure:
113+
114+
```
115+
.codegen/
116+
└── codemods/
117+
└── rename_function/
118+
├── rename_function.py # The codemod implementation
119+
└── rename_function_prompt.md # System prompt (if using AI)
120+
```

‎docs/cli/create.mdx‎

Lines changed: 32 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,12 @@ icon: "plus"
55
iconType: "solid"
66
---
77

8-
The `create` command generates new codemods.
8+
The `create` command generates a new codemod function with the necessary boilerplate.
99

1010
```bash
11-
codegen create organize-types --description "put all types in a single file"
11+
codegen create rename-function
1212
```
1313

14-
<Tip>
15-
If you provide a `--description`, The Codegen CLI will use AI to generate a first implementation.
16-
</Tip>
17-
1814
## Usage
1915

2016
```bash
@@ -23,73 +19,55 @@ codegen create NAME [OPTIONS]
2319

2420
## Arguments
2521

26-
- `NAME`: The name/label for your codemod
22+
- `NAME`: The name of the codemod to create (e.g., "rename-function")
2723

2824
## Options
2925

30-
- `--description`, `-d`: Description of what the codemod should do. When provided, uses AI to generate an implementation.
31-
- `--overwrite`: Overwrites the codemod if it already exists at the target path.
26+
- `--description`, `-d`: A description of what the codemod should do. This will be used to generate an AI-powered implementation.
3227

33-
## Examples
28+
## Generated Files
3429

35-
Create a basic codemod in the current directory:
36-
```bash
37-
codegen create update-imports
38-
```
30+
When you run `codegen create rename-function`, it creates:
3931

40-
Create a codemod with AI assistance:
41-
```bash
42-
codegen create rename-function --description "Rename the getUserData function to fetchUserProfile across the codebase"
4332
```
44-
45-
Create a codemod in a specific directory, overwriting if it exists:
46-
```bash
47-
codegen create api-migration --overwrite
33+
.codegen/
34+
└── codemods/
35+
└── rename_function/
36+
├── rename_function.py # The codemod implementation
37+
└── rename_function_prompt.md # System prompt (if --description used)
4838
```
4939

50-
## Generated Files
40+
The generated codemod will have this structure:
5141

52-
When you run `create`, new files are added to your `.codegen` directory structure:
42+
```python
43+
import codegen
44+
from codegen import Codebase
5345

54-
```bash
55-
.codegen/
56-
├── config.toml
57-
├── codemods/
58-
│ └── rename_function.py # ← Generated by create
59-
├── docs/
60-
│ ├── api/
61-
│ ├── examples/
62-
│ └── tutorials/
63-
└── prompts/
64-
└── rename-function.md # ← Generated by create with --description
46+
@codegen.function("rename-function")
47+
def run(codebase: Codebase):
48+
"""Add a description of what this codemod does."""
49+
# Add your code here
50+
pass
6551
```
6652

67-
The command creates:
68-
1. A codemod implementation file in `.codegen/codemods/` (automatically converted to snake_case)
69-
2. A system prompt file in `.codegen/prompts/` (when using `--description`)
70-
71-
<Note>
72-
The `prompts/` directory is automatically added to `.gitignore`, while your codemod in `codemods/` is tracked in Git.
73-
</Note>
74-
75-
## AI-Assisted Generation
53+
## Examples
7654

77-
When you provide a `--description`, Codegen:
78-
1. Analyzes your request using AI (~30 seconds)
79-
2. Generates a codemod implementation
80-
3. Creates a system prompt file for future AI interactions
81-
4. Wraps the code with necessary CLI decorators
55+
Create a basic codemod:
56+
```bash
57+
codegen create rename-function
58+
```
8259

83-
The generated codemod is ready to run but can be customized to fit your specific needs.
60+
Create with an AI-powered implementation:
61+
```bash
62+
codegen create rename-function -d "Rename the getUserData function to fetchUserProfile"
63+
```
8464

8565
## Next Steps
8666

8767
After creating a codemod:
88-
1. Review and edit the implementation to customize its behavior
89-
2. Run it with [`codegen run`](/cli/run):
90-
```bash
91-
codegen run NAME
92-
```
68+
1. Edit the implementation in the generated .py file
69+
2. Test it with `codegen run rename-function`
70+
3. Deploy it for team use with `codegen deploy rename-function`
9371

9472
## Common Issues
9573

‎docs/mint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@
9191
"pages": [
9292
"building-with-codegen/at-a-glance",
9393
"building-with-codegen/parsing-codebases",
94+
"building-with-codegen/reusable-codemods",
9495
"building-with-codegen/dot-codegen",
9596
"building-with-codegen/language-support",
9697
"building-with-codegen/commit-and-reset",

0 commit comments

Comments
 (0)