安装#

# 方式一：官方安装脚本
curl -fsSL https://docs.grit.io/install | bash

# 方式二：npm 安装
npm install -g @getgrit/cli

验证安装#

# 检查版本
grit version

# 诊断环境
grit doctor

第一个转换#

假设我们要把所有的 console.log 调用删除：

# 方式一：使用标准库 pattern（推荐）
grit apply no_console_log src/

# 方式二：使用内联 pattern
grit apply '`console.log($_)`' src/

# 先预览会改什么（dry-run）
grit apply --dry-run no_console_log src/

# 查看某个 pattern 的详细信息
grit patterns describe no_console_log

grit apply - 应用转换#

语法: grit apply [OPTIONS] <PATTERN> [PATHS]...

Pattern 参数形式：

• 标准库 pattern: no_console_log
• 内联模式: 'console.log($_)'（用单引号包裹反引号内的 pattern）
• Pattern 文件: ./patterns/my_pattern.grit

常用选项：

# 预览模式（不实际修改文件）
grit apply --dry-run no_console_log file.js

# 指定语言
grit apply --language python print_to_log file.py

# 限制修改数量
grit apply --limit 10 no_console_log src/

# 紧凑输出
grit apply --output compact no_console_log src/

# 交互式选择（逐个确认）
grit apply --interactive no_console_log src/

# JSONL 格式输出
grit apply --jsonl no_console_log src/

grit list - 列出可用 Patterns#

# 列出所有 patterns
grit list

# 仅列出 JavaScript/TypeScript patterns
grit list --language js

# 仅列出 Python patterns
grit list --language python

# 仅列出本地 patterns
grit list --source local

grit check - 检查代码#

# 检查当前目录
grit check

# 自动修复
grit check --fix

# 详细输出
grit check --verbose

其他有用命令#

# 描述某个 pattern
grit patterns describe no_console_log

# 列出 patterns
grit patterns list

# 诊断环境
grit doctor

代码片段模式#

最基本的模式是用反引号包裹的代码片段：

`console.log('Hello')`

结构化匹配意味着 Grit 忽略格式差异，以下都会被匹配：

console.log('Hello')
console.log ( 'Hello' )     // 换行和空格不影响
console.log("Hello")         // 单双引号等价

变量系统#

使用 $ 前缀定义变量，匹配任意内容：

`console.$method($msg)`      // 匹配 console 的任何方法调用

变量复用规则：同一变量多次出现必须匹配相同值

`$obj && $obj.$prop()`       // foo && foo.bar() ✓
                              // foo && bar.baz()   ✗

条件过滤#

使用 where 子句精确控制匹配范围：

`console.$method($msg)` where {
  $method <: or { `log`, `warn` }    // 只匹配 log 和 warn
}

转换语法#

使用 => 进行代码转换：

`旧代码($args)` => `新代码($args)`

案例 1：清理 console 调试语句#

最简单的场景 —— 直接删除匹配的代码。

// 转换前
console.log('fetching data...');
console.debug('state:', state);
console.info('API called');
console.error('Critical error');  // 保留

// 转换后
console.error('Critical error');

使用标准库 pattern（推荐）：

grit apply no_console_log src/

自定义 GritQL 规则：

`console.log($a)` => ``
`console.debug($a)` => ``
`console.info($a)` => ``

注意: 标准库的 no_console_log 会自动保留 catch 块中的 console.log，更加安全。

案例 2：Python print 转 logger#

将 Python 中的 print 语句转换为 logger 调用。

# 转换前
print("Hello, World")
print(f"User: {username}")
print("Error:", error)

# 转换后
log("Hello, World")
log(f"User: {username}")
log("Error:", error)

使用标准库 pattern：

grit apply --language python print_to_log src/

案例 3：移除 debugger 语句#

清理开发时留下的 debugger 语句。

// 转换前
function processData(data) {
    debugger;  // 调试用
    return data.map(x => x * 2);
}

// 转换后
function processData(data) {
    return data.map(x => x * 2);
}

使用标准库 pattern：

grit apply no_debugger src/

案例 4：import 路径调整#

项目目录重构时的常见需求 —— 批量更新 import 路径。

// 转换前
import { Button } from '@/components/ui/Button'
import { useAuth } from '@/hooks/useAuth'
import { formatDate } from '@/utils/date'

// 转换后
import { Button } from '@/components/Button'
import { useAuth } from '@/hooks/auth'
import { formatDate } from '@/utils/format'

GritQL 规则：

`from '@/components/ui/$name'` => `from '@/components/$name'`
`from '@/hooks/use$name'` => `from '@/hooks/$name'`
`from '@/utils/date'` => `from '@/utils/format'`

案例 5：箭头函数简化#

⚠️ 限制：内联 pattern 对多参数函数的处理有限制，建议仅用于单参数场景。

单行返回的箭头函数可以省略 return 和大括号。

// 转换前
const double = x => { return x * 2; }
const getValue = () => { return config.value; }

// 转换后
const double = x => x * 2
const getValue = () => config.value

异步箭头函数：可以去除 async 和 await（当直接返回 Promise 时）。

// 转换前
const getData = async () => { return await fetch('/api/data'); }

// 转换后
const getData = () => fetch('/api/data')

说明：当函数只是直接返回 await 的结果时，async/await 是冗余的。

GritQL 规则：

# 单参数箭头函数（推荐）
`$param => { return $expr }` => `$param => $expr`

# 无参数箭头函数
`() => { return $expr }` => `() => $expr`

# 异步箭头函数 - 去除 async/await
`async () => { return await $expr }` => `() => $expr`

注意：多参数函数 (a, b) => ... 的转换存在括号处理问题，建议手动处理或使用 .grit 文件。

案例 6：框架升级迁移#

Grit 提供了丰富的框架升级 patterns，可自动化常见的迁移工作。

// 转换前
class UserList extends React.Component {
  state = { users: [], loading: false }
  componentDidMount() {
    this.fetchUsers()
  }
  fetchUsers() {
    this.setState({ loading: true })
    api.getUsers().then(users => this.setState({ users, loading: false }))
  }
  render() {
    if (this.state.loading) return <div>Loading...</div>
    return <div>{this.state.users.length} users</div>
  }
}

// 转换后
function UserList() {
  const [users, setUsers] = useState([])
  const [loading, setLoading] = useState(false)

  useEffect(() => {
    fetchUsers()
  }, [])

  function fetchUsers() {
    setLoading(true)
    api.getUsers().then(data => { setUsers(data); setLoading(false) })
  }

  if (loading) return <div>Loading...</div>
  return <div>{users.length} users</div>
}

# 预览转换结果
grit apply --dry-run react_to_hooks src/

# 执行转换
grit apply react_to_hooks src/

# 交互式选择（逐个确认）
grit apply --interactive react_to_hooks src/

# Jest 迁移到 Vitest
grit apply --dry-run jest_to_vitest src/
grit apply jest_to_vitest src/

# OpenAI SDK 升级
grit apply --dry-run openai_v4 src/
grit apply openai_v4 src/

# 测试框架迁移（Cypress → Playwright）
grit apply --dry-run cypress_to_playwright tests/
grit apply cypress_to_playwright tests/

案例 7：对象简写属性#

⚠️ 限制：必须使用 .grit 文件，内联语法不支持，且转换后需要人工检查。

ES6 允许属性名和变量名相同时省略冒号。

// 转换前
const user = { name: name, age: age, userId: id }
return { data: data, isLoading: loading }

// 转换后
const user = { name, age, userId: id }
return { data, isLoading: loading }

创建 shorthand.grit 文件：

# 指定使用的引擎版本（marzano 是 Grit 的匹配引擎）
engine marzano(0.1)
# 指定目标语言
language js

`{ $props }` where {
  $props <: some {
    `$k: $k` => `$k`
  }
}

engine marzano(0.1)：Grit 的匹配引擎版本，所有 .grit 文件都需要在开头声明。

使用方式：

# 应用转换（可能需要运行多次直到所有属性都转换完成）
grit apply shorthand.grit src/

测试结果：

• ✅ 可以匹配并转换 { name: name } → { name }
• ⚠️ 多个属性需要运行多次才能全部转换
• ⚠️ 转换后建议人工检查结果

JavaScript/TypeScript 常用 Patterns#

Python 常用 Patterns#

语言列表#

使用示例#

# Python 项目 - 将 print 转换为 logger
grit apply --language python print_to_log src/

# Go 项目 - 移除 debugger 语句
grit apply --language go no_debugger src/

# Java 项目 - 列出可用的 Java patterns
grit list --language java

# Rust 项目 - 应用自定义 pattern
grit apply --language rust ./patterns/custom.grit src/

# Vue 项目 - 检查代码规范
grit check --language vue src/

# 多语言项目 - 同时处理多种文件类型
grit apply --language js no_console_log src/
grit apply --language python print_to_log src/

# 查看某个语言的可用 patterns
grit patterns list --language python

推荐工作流程#

# 1. 列出可用的 patterns
grit list --language js

# 2. 查看 pattern 详情
grit patterns describe no_console_log

# 3. 预览模式（不会修改文件）
grit apply --dry-run no_console_log src/

# 4. 限制范围测试
grit apply no_console_log src/components/

# 5. 交互式应用（逐个确认）
grit apply --interactive no_console_log src/

# 6. 确认后正式应用
grit apply no_console_log src/

使用配置文件#

创建 .grit/grit.yaml 管理项目规则：

patterns:
  - no_console_log
  - no_debugger
  - .grit/patterns/**/*.grit

ignored:
  - node_modules/**
  - dist/**
  - build/**
  - "**/*.min.js"

enforcement:
  level: fix

CI 集成#

在 GitHub Actions 中集成代码检查：

name: Grit Code Quality

on: [pull_request]

jobs:
  grit-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Grit
        run: npm install -g @getgrit/cli
      - name: Check code patterns
        run: grit check --github-actions

处理流程#

源代码
    ↓
┌─────────────────────────────────────┐
│  Tree-sitter 解析器                 │
│  (多语言支持，增量解析)              │
└─────────────────────────────────────┘
    ↓ AST
┌─────────────────────────────────────┐
│  Grit 模式匹配引擎                  │
│  (变量绑定，条件过滤)                │
└─────────────────────────────────────┘
    ↓ 匹配结果
┌─────────────────────────────────────┐
│  AST 转换引擎                       │
│  (语义保持，结构转换)                │
└─────────────────────────────────────┘
    ↓ 修改后的 AST
┌─────────────────────────────────────┐
│  代码生成器                         │
│  (保留格式，生成代码)                │
└─────────────────────────────────────┘
    ↓
转换后代码

为什么比正则更安全？#