https://github.com/wellkilo/codemod-pilot

🛩️ Transform your codebase by example — an intelligent codemod engine that infers AST-level transformation rules from before/after code snippets, then safely applies them across your entire codebase. No AST knowledge required.
https://github.com/wellkilo/codemod-pilot

ast automation ci-cd cli code-migration code-quality code-transformation codemod developer-tools javascript linter multi-language open-source pattern-matching productivity refactoring rust search-and-replace tree-sitter typescript

Last synced: about 3 hours ago
JSON representation

🛩️ Transform your codebase by example — an intelligent codemod engine that infers AST-level transformation rules from before/after code snippets, then safely applies them across your entire codebase. No AST knowledge required.

• Host: GitHub
• URL: https://github.com/wellkilo/codemod-pilot
• Owner: wellkilo
• License: apache-2.0
• Created: 2026-04-08T02:35:11.000Z (about 12 hours ago)
• Default Branch: main
• Last Pushed: 2026-04-08T03:38:28.000Z (about 11 hours ago)
• Last Synced: 2026-04-08T05:21:35.546Z (about 10 hours ago)
• Topics: ast, automation, ci-cd, cli, code-migration, code-quality, code-transformation, codemod, developer-tools, javascript, linter, multi-language, open-source, pattern-matching, productivity, refactoring, rust, search-and-replace, tree-sitter, typescript
• Language: Rust
• Homepage:
• Size: 116 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Support: docs/supported-languages.md

Awesome Lists containing this project

README

          


# codemod-pilot 🛩️

**Transform your codebase by example. No AST knowledge required.**

[![CI](https://github.com/wellkilo/codemod-pilot/actions/workflows/ci.yml/badge.svg)](https://github.com/wellkilo/codemod-pilot/actions/workflows/ci.yml)

[![Crates.io](https://img.shields.io/crates/v/codemod-cli.svg)](https://crates.io/crates/codemod-cli)

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**[🇺🇸 English](#-English) · [🇨🇳 简体中文](#-简体中文)**



---

# 🇺🇸 English

[Features](#-features) · [Quick Start](#-quick-start) · [How It Works](#-how-it-works) · [Examples](#-examples) · [Rule Format](#-rule-format) · [Roadmap](#-roadmap) · [Contributing](#-contributing)

---

## The Problem

Large-scale code refactoring is painful. Renaming an API across 300 files, migrating from one library to another, updating deprecated patterns — these tasks are:

- **Manual**: Find-and-replace is dangerous for code; regex can't understand AST structure

- **Complex**: Writing AST-based codemods with tools like jscodeshift requires deep knowledge of AST manipulation

- **Risky**: Without proper preview and rollback, batch changes can introduce subtle bugs

## The Solution

**codemod-pilot** lets you describe code transformations **by example**. Show it a "before" and "after" snippet, and it will:

1. 🧠 **Infer** the structural transformation pattern from your examples

2. 🔍 **Scan** your entire codebase for matching patterns

3. 👀 **Preview** all proposed changes as a unified diff

4. ✅ **Apply** changes safely with automatic rollback support

```bash

# Show it what you want to change

codemod-pilot learn \

  --before 'fetchUserInfo({ userId: id })' \

  --after  'getUserProfile({ profileId: id })'

# Preview all matches across your codebase

codemod-pilot scan --target ./src/

# Apply with confidence

codemod-pilot apply --execute

```

## ✨ Features

- **Example-Driven** — No AST knowledge needed. Just show before → after.

- **Multi-Example Inference** — Provide multiple examples for complex patterns; the engine finds the common transformation rule.

- **Safe by Default** — Preview all changes before applying. Automatic rollback patch generated.

- **Interactive Conflicts** — Ambiguous cases enter interactive mode for human decision.

- **Reusable Rules** — Export inferred patterns to `.codemod.yaml` files. Share with your team via version control.

- **Built-in Templates** — Common refactoring patterns ready to use out of the box.

- **CI/CD Ready** — `--ci` mode outputs machine-readable JSON. Use `--fail-on-match` for automated checks.

- **Blazing Fast** — Built in Rust with parallel file scanning. Handles 100k+ file codebases in seconds.

- **Multi-Language** — Powered by tree-sitter. Currently supports TypeScript/JavaScript, with Python and Go coming soon.

## 🚀 Quick Start

### Installation

```bash

# Via cargo

cargo install codemod-cli

# Via curl (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/wellkilo/codemod-pilot/main/scripts/install.sh | sh

# Via Homebrew (coming soon)

brew install codemod-pilot

```

### Your First Codemod (30 seconds)

```bash

# 1. Teach it a transformation

codemod-pilot learn \

  --before 'console.log(msg)' \

  --after  'logger.info(msg)'

# 2. See what it found

codemod-pilot scan --target ./src/

# 3. Preview the diff

codemod-pilot apply --preview

# 4. Apply changes

codemod-pilot apply --execute

# 5. Made a mistake? Roll back instantly

codemod-pilot apply --rollback

```

## 🧠 How It Works

```

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐

│   Example    │────▶│   Pattern    │────▶│  Codebase   │────▶│    Apply     │

│ before/after │     │  Inference   │     │   Scanner   │     │  & Rollback  │

└─────────────┘     └──────────────┘     └─────────────┘     └──────────────┘

                          │                     │

                    ┌─────▼─────┐         ┌─────▼─────┐

                    │ AST Diff  │         │ Parallel  │

                    │ Analysis  │         │ Matching  │

                    └───────────┘         └───────────┘

```

1. **Parse**: Both "before" and "after" code snippets are parsed into ASTs using tree-sitter

2. **Diff**: The engine computes a structural diff between the two ASTs, identifying which nodes changed and how

3. **Generalize**: Variable parts (identifiers, literals) are detected and converted into pattern variables

4. **Match**: The generalized pattern is used to scan target files, finding all structurally similar code

5. **Transform**: Matched code is rewritten according to the inferred transformation rule

6. **Validate**: Results are presented for review; a rollback patch is always generated before any writes

## 💡 Examples

### Rename a Function and Its Parameters

```bash

codemod-pilot learn \

  --before 'fetchUserInfo({ userId: id })' \

  --after  'getUserProfile({ profileId: id })'

codemod-pilot apply --target ./src/ --execute

```

### Migrate from Moment.js to Day.js

```bash

# Create examples file

cat > examples.yaml << 'EOF'

examples:

  - before: "moment(date).format('YYYY-MM-DD')"

    after: "dayjs(date).format('YYYY-MM-DD')"

  - before: "moment(date).add(1, 'days')"

    after: "dayjs(date).add(1, 'day')"

  - before: "moment(date).diff(other, 'hours')"

    after: "dayjs(date).diff(other, 'hour')"

EOF

codemod-pilot learn --examples examples.yaml

codemod-pilot apply --target ./src/ --preview

```

### Use a Shared Rule File

```bash

# Apply a team-shared codemod rule

codemod-pilot apply --rule ./codemods/replace-deprecated-api.yaml --target ./src/

# Export your codemod for others

codemod-pilot export --output ./codemods/my-migration.yaml

```

### CI/CD Integration

```yaml

# .github/workflows/codemod-check.yml

name: Codemod Check

on: [pull_request]

jobs:

  check:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: codemod-pilot/action@v1

        with:

          rule: ./codemods/deprecated-apis.yaml

          fail-on-match: true

```

## 📐 Rule Format

Codemod rules are stored as `.codemod.yaml` files:

```yaml

name: replace-fetch-user-info

description: Migrate fetchUserInfo to getUserProfile

language: typescript

version: "1.0"

pattern:

  before: |

    fetchUserInfo({ userId: $id })

  after: |

    getUserProfile({ profileId: $id })

# Optional: restrict to specific file patterns

include:

  - "src/**/*.ts"

  - "src/**/*.tsx"

exclude:

  - "**/*.test.ts"

  - "**/*.spec.ts"

```

Pattern variables (prefixed with `$`) match any expression and are preserved across the transformation.

For the full rule specification, see [docs/rule-format.md](docs/rule-format.md).

## 🗣️ Supported Languages

| Language | Status | Grammar |

|:---|:---:|:---|

| TypeScript | ✅ Stable | tree-sitter-typescript |

| JavaScript | ✅ Stable | tree-sitter-javascript |

| Python | 🚧 Coming in v0.2 | tree-sitter-python |

| Go | 🚧 Coming in v0.3 | tree-sitter-go |

| Rust | 📋 Planned | tree-sitter-rust |

| Java | 📋 Planned | tree-sitter-java |

Want to add a new language? See our [Adding a Language Guide](docs/adding-a-language.md).

## 🗺️ Roadmap

### v0.1 — Core Engine (Current)

- [x] Example-based pattern inference (single example)

- [x] Codebase scanning with parallel file processing

- [x] Diff preview and safe apply with rollback

- [x] TypeScript/JavaScript support

- [x] Basic CLI (`learn`, `scan`, `apply`)

### v0.2 — Team Ready

- [ ] Multi-example inference

- [ ] Rule export/import (`.codemod.yaml`)

- [ ] Built-in rule templates

- [ ] Interactive conflict resolution

- [ ] Python language support

### v0.3 — CI Ready

- [ ] `--ci` mode with JSON output

- [ ] GitHub Action

- [ ] Go language support

- [ ] Incremental scanning (git-diff based)

### v1.0 — Community Edition

- [ ] Plugin system for new languages

- [ ] Community rule marketplace

- [ ] VS Code extension

- [ ] Web playground

## 🏗️ Architecture

See [docs/architecture.md](docs/architecture.md) for a detailed design overview.

```

codemod-pilot/

├── crates/

│   ├── codemod-core/       # Pattern inference, matching, transformation

│   ├── codemod-cli/        # CLI commands and user interaction

│   └── codemod-languages/  # Tree-sitter language adapters

├── rules/                  # Built-in codemod rules

├── tests/                  # Integration tests and fixtures

└── docs/                   # Documentation

```

## 🤝 Contributing

We welcome contributions of all kinds! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

**Quick ways to contribute:**

- 🐛 [Report a bug](https://github.com/codemod-pilot/codemod-pilot/issues/new?template=bug_report.md)

- 💡 [Request a feature](https://github.com/codemod-pilot/codemod-pilot/issues/new?template=feature_request.md)

- 🌍 [Add a new language](https://github.com/codemod-pilot/codemod-pilot/issues/new?template=new_language.md)

- 📝 Submit a built-in codemod rule

- 📖 Improve documentation

## 📄 License

Licensed under [Apache License, Version 2.0](LICENSE).

---

# 🇨🇳 简体中文

[功能特点](#-功能特点) · [快速开始](#-快速开始) · [工作原理](#-工作原理) · [示例](#-示例) · [规则格式](#-规则格式) · [路线图](#-路线图) · [贡献指南](#-贡献指南)

---

## 问题背景

大规模代码重构非常痛苦。跨 300 个文件重命名 API、从一个库迁移到另一个库、更新废弃的模式——这些任务：

- **手动**：查找替换对代码很危险；正则表达式无法理解 AST 结构

- **复杂**：使用 jscodeshift 等工具编写基于 AST 的 codemod 需要深入的 AST 操作知识

- **风险高**：没有适当的预览和回滚，批量更改可能引入细微 bug

## 解决方案

**codemod-pilot** 让你通过**示例**描述代码转换。只需展示"之前"和"之后"的代码片段，它就会：

1. 🧠 **推断**从示例中推断结构性转换模式

2. 🔍 **扫描**在整个代码库中查找匹配的模式

3. 👀 **预览**以统一 diff 格式预览所有建议的更改

4. ✅ **应用**安全地应用更改，支持自动回滚

```bash

# 展示你想要更改的内容

codemod-pilot learn \

  --before 'fetchUserInfo({ userId: id })' \

  --after  'getUserProfile({ profileId: id })'

# 预览代码库中所有匹配项

codemod-pilot scan --target ./src/

# 放心应用更改

codemod-pilot apply --execute

```

## ✨ 功能特点

- **示例驱动** — 无需 AST 知识，只需展示之前 → 之后

- **多示例推断** — 为复杂模式提供多个示例；引擎会找到通用转换规则

- **默认安全** — 应用前预览所有更改，自动生成回滚补丁

- **交互式冲突处理** — 模糊情况进入交互模式由人工决策

- **可复用规则** — 将推断的模式导出为 `.codemod.yaml` 文件，通过版本控制与团队共享

- **内置模板** — 开箱即用的常见重构模式

- **CI/CD 就绪** — `--ci` 模式输出机器可读的 JSON，使用 `--fail-on-match` 进行自动检查

- **极速** — 使用 Rust 构建，支持并行文件扫描，可在数秒内处理 10 万+文件的代码库

- **多语言支持** — 由 tree-sitter 提供支持，目前支持 TypeScript/JavaScript，Python 和 Go 即将推出

## 🚀 快速开始

### 安装

```bash

# 通过 cargo

cargo install codemod-cli

# 通过 curl (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/wellkilo/codemod-pilot/main/scripts/install.sh | sh

# 通过 Homebrew（即将推出）

brew install codemod-pilot

```

### 你的第一个 Codemod（30 秒）

```bash

# 1. 教它一个转换

codemod-pilot learn \

  --before 'console.log(msg)' \

  --after  'logger.info(msg)'

# 2. 查看它找到了什么

codemod-pilot scan --target ./src/

# 3. 预览 diff

codemod-pilot apply --preview

# 4. 应用更改

codemod-pilot apply --execute

# 5. 犯了错误？立即回滚

codemod-pilot apply --rollback

```

## 🧠 工作原理

```

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐

│   示例       │────▶│   模式        │────▶│  代码库      │────▶│    应用      │

│ 之前/之后   │     │   推断        │     │   扫描器     │     │  & 回滚      │

└─────────────┘     └──────────────┘     └─────────────┘     └──────────────┘

                          │                     │

                    ┌─────▼─────┐         ┌─────▼─────┐

                    │  AST Diff │         │  并行     │

                    │   分析     │         │  匹配     │

                    └───────────┘         └───────────┘

```

1. **解析**：使用 tree-sitter 将"之前"和"之后"的代码片段解析为 AST

2. **Diff**：引擎计算两个 AST 之间的结构性 diff，识别哪些节点发生了变化以及如何变化

3. **泛化**：检测变量部分（标识符、字面量）并将其转换为模式变量

4. **匹配**：使用泛化模式扫描目标文件，查找所有结构相似的代码

5. **转换**：根据推断的转换规则重写匹配的代码

6. **验证**：展示结果供审查；在任何写入之前始终生成回滚补丁

## 💡 示例

### 重命名函数及其参数

```bash

codemod-pilot learn \

  --before 'fetchUserInfo({ userId: id })' \

  --after  'getUserProfile({ profileId: id })'

codemod-pilot apply --target ./src/ --execute

```

### 从 Moment.js 迁移到 Day.js

```bash

# 创建示例文件

cat > examples.yaml << 'EOF'

examples:

  - before: "moment(date).format('YYYY-MM-DD')"

    after: "dayjs(date).format('YYYY-MM-DD')"

  - before: "moment(date).add(1, 'days')"

    after: "dayjs(date).add(1, 'day')"

  - before: "moment(date).diff(other, 'hours')"

    after: "dayjs(date).diff(other, 'hour')"

EOF

codemod-pilot learn --examples examples.yaml

codemod-pilot apply --target ./src/ --preview

```

### 使用共享规则文件

```bash

# 应用团队共享的 codemod 规则

codemod-pilot apply --rule ./codemods/replace-deprecated-api.yaml --target ./src/

# 导出你的 codemod 供他人使用

codemod-pilot export --output ./codemods/my-migration.yaml

```

### CI/CD 集成

```yaml

# .github/workflows/codemod-check.yml

name: Codemod Check

on: [pull_request]

jobs:

  check:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: codemod-pilot/action@v1

        with:

          rule: ./codemods/deprecated-apis.yaml

          fail-on-match: true

```

## 📐 规则格式

Codemod 规则存储为 `.codemod.yaml` 文件：

```yaml

name: replace-fetch-user-info

description: Migrate fetchUserInfo to getUserProfile

language: typescript

version: "1.0"

pattern:

  before: |

    fetchUserInfo({ userId: $id })

  after: |

    getUserProfile({ profileId: $id })

# 可选：限制为特定文件模式

include:

  - "src/**/*.ts"

  - "src/**/*.tsx"

exclude:

  - "**/*.test.ts"

  - "**/*.spec.ts"

```

模式变量（以 `$` 为前缀）匹配任何表达式，并在转换过程中保留。

完整的规则规范请参见 [docs/rule-format.md](docs/rule-format.md)。

## 🗣️ 支持的语言

| 语言 | 状态 | 语法分析器 |

|:---|:---:|:---|

| TypeScript | ✅ 稳定 | tree-sitter-typescript |

| JavaScript | ✅ 稳定 | tree-sitter-javascript |

| Python | 🚧 v0.2 推出 | tree-sitter-python |

| Go | 🚧 v0.3 推出 | tree-sitter-go |

| Rust | 📋 计划中 | tree-sitter-rust |

| Java | 📋 计划中 | tree-sitter-java |

想要添加新语言？请参阅我们的[添加语言指南](docs/adding-a-language.md)。

## 🗺️ 路线图

### v0.1 — 核心引擎（当前版本）

- [x] 基于示例的模式推断（单个示例）

- [x] 并行文件处理的代码库扫描

- [x] Diff 预览和安全应用与回滚

- [x] TypeScript/JavaScript 支持

- [x] 基本 CLI（`learn`、`scan`、`apply`）

### v0.2 — 团队就绪

- [ ] 多示例推断

- [ ] 规则导出/导入（`.codemod.yaml`）

- [ ] 内置规则模板

- [ ] 交互式冲突解决

- [ ] Python 语言支持

### v0.3 — CI 就绪

- [ ] 带 JSON 输出的 `--ci` 模式

- [ ] GitHub Action

- [ ] Go 语言支持

- [ ] 增量扫描（基于 git-diff）

### v1.0 — 社区版

- [ ] 新语言插件系统

- [ ] 社区规则市场

- [ ] VS Code 扩展

- [ ] Web playground

## 🏗️ 架构

有关详细设计概述，请参阅 [docs/architecture.md](docs/architecture.md)。

```

codemod-pilot/

├── crates/

│   ├── codemod-core/       # 模式推断、匹配、转换

│   ├── codemod-cli/        # CLI 命令和用户交互

│   └── codemod-languages/  # Tree-sitter 语言适配器

├── rules/                  # 内置 codemod 规则

├── tests/                  # 集成测试和测试用例

└── docs/                   # 文档

```

## 🤝 贡献指南

欢迎各种形式的贡献！详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

**快速贡献方式：**

- 🐛 报告 bug

- 💡 请求新功能

- 🌍 添加新语言

- 📝 提交内置 codemod 规则

- 📖 改进文档

## 📄 许可证

根据 [Apache License, Version 2.0](LICENSE) 获得许可。

---