Ruchy

🚀 ruchy

ruchy 是一種用於數據科學和科學計算的現代編程語言，具備自託管編譯器、全面的工具集以及企業級的質量標準。

🚀 快速開始

啟動交互式 REPL

ruchy

運行 Ruchy 腳本

ruchy script.ruchy
# 或者顯式指定
ruchy run script.ruchy

編譯為生產二進制文件

ruchy compile script.ruchy -o myapp

格式化代碼

ruchy fmt src/

運行測試

ruchy test tests/

✨ 主要特性

• 自託管編譯器：用 Rust 編寫，具備完整的自舉能力。
• 交互式 REPL：高級 REPL，支持語法高亮和自動補全。
• WebAssembly 支持：可編譯為 WASM，用於瀏覽器和邊緣設備部署。
• Notebook 集成：支持類似 Jupyter 的 Notebook，並帶有測試框架。
• 類型系統：支持雙向類型檢查和類型推斷。
• 包管理：通過 ruchy add 與 Cargo 集成，可使用超過 140K 個 crate。
• 質量優先：遵循豐田生產方式原則，代碼達到 PMAT A+ 標準。
• 內存安全：生成的代碼無不安全代碼，所有代碼線程安全。
• Rust 併發：支持與 Rust 相同的併發機制，包括線程、async/await 和通道。

📦 安裝指南

從 crates.io 安裝

cargo install ruchy

安裝支持 MCP 服務器的版本

cargo install ruchy --features mcp

從源代碼構建

git clone https://github.com/paiml/ruchy
cd ruchy
cargo build --release

💻 使用示例

基礎用法

// 變量
let x = 42
let name = "Ruchy"
println(f"Hello, {name}! x = {x}")

// 函數
fun add(a, b) {
    a + b
}
let result = add(10, 20)
println(f"10 + 20 = {result}")

// 模式匹配
let value = Some(5)
match value {
    Some(x) => println(f"Got {x}"),
    None => println("Nothing"),
}

// 集合
let numbers = [1, 2, 3, 4, 5]
println(f"Numbers: {numbers:?}")

高級用法 - 包管理

# 創建新的 Ruchy 項目並集成 Cargo
ruchy new my_project

# 從 crates.io 添加依賴
cd my_project
ruchy add serde
ruchy add tokio@1.0

# 添加開發依賴
ruchy add --dev proptest

# 構建項目（自動將 .ruchy 文件轉譯為 .rs）
ruchy build
ruchy build --release

# 運行項目
cargo run

高級用法 - DataFrame 數據科學特性

// 創建 DataFrame（通過 polars-rs 後端）
let df = dataframe::from_columns(vec![
    ("age", vec![25, 30, 35]),
    ("score", vec![95, 87, 92])
]).unwrap();

// 支持的操作（經過 200K+ 屬性測試）
// - df.select("column_name")
// - df.filter(predicate)
// - df.sort_by("column", descending)
// - df.groupby("column")
// - df.sum(), mean(), min(), max(), std(), var()
// - df.join(other_df, "key_column")

📚 詳細文檔

語法實現狀態

100% 完成 - 所有 89/89 個語法特性均已實現並驗證（v3.94.0+）。

Ruchy 已實現全面的語法覆蓋並進行了綜合驗證：

• handler_expr (SPEC-001-J)：支持模式匹配的效果處理程序 - handle expr with { operation => body }
• expression_roundtrip：通過 1,536+ 個屬性測試用例驗證瞭解析器/格式化器的等價性。

驗證結果：

• 三種模式驗證：26 個測試（解釋器、轉譯、編譯模式）
• 屬性測試：11 個測試，包含 1,536+ 個隨機測試用例
• 核心工具驗證：10 個測試，驗證了所有核心工具（檢查、 lint、AST、格式化、運行、轉譯、編譯、測試、覆蓋率）
• 總計：47+ 個綜合驗證測試

所有語法特性在所有執行模式和工具中均可正常工作。完整規範請參閱 grammar/ruchy-grammar.yaml。

MCP 服務器

Ruchy 提供了一個模型上下文協議（MCP）服務器，該服務器向 Claude 和其他 MCP 客戶端提供代碼分析、評分、 lint 和轉譯功能。

安裝

# 安裝支持 MCP 的 Ruchy
cargo install ruchy --features mcp

配置

將以下內容添加到你的 Claude Desktop 配置文件中（macOS 上的路徑為 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ruchy": {
      "command": "ruchy",
      "args": ["mcp"]
    }
  }
}

可用工具

Ruchy MCP 服務器提供 7 種工具：

• ruchy-score：使用統一的 0.0 - 1.0 評分系統分析代碼質量
• ruchy-lint：即時代碼 lint 檢查，並提供自動修復建議
• ruchy-format：格式化 Ruchy 源代碼，支持可配置的樣式
• ruchy-analyze：全面的代碼分析，包括 AST、指標和洞察
• ruchy-eval：安全地評估 Ruchy 表達式
• ruchy-transpile：將 Ruchy 代碼轉譯為 Rust 代碼
• ruchy-type-check：對 Ruchy 表達式進行類型檢查

使用方法

# 啟動 MCP 服務器（通常由 Claude Desktop 調用）
ruchy mcp --verbose

更多詳細信息，請參閱 docs/mcp-registry-publish.md。

CLI 命令

核心命令

• ruchy - 啟動交互式 REPL（無參數，類似 Deno 的用戶體驗）
• ruchy <file> - 直接執行 Ruchy 腳本（立即解釋執行）
• ruchy run <file> - 執行 Ruchy 腳本（直接執行的別名）
• ruchy -e "<code>" - 直接評估代碼（例如：ruchy -e "println(1+1)"）
• ruchy compile <file> - 編譯為獨立二進制文件
• ruchy fmt <path> - 格式化代碼（支持 --check 標誌）

WebAssembly 相關命令

• ruchy wasm compile <input> -o <output> - 編譯為 WASM
• ruchy wasm validate <module> - 驗證 WASM 模塊
• ruchy wasm run <module> - 執行 WASM 模塊

WASM 分發（v3.99.2+）： Ruchy 提供預構建的 WASM 二進制文件，用於瀏覽器和邊緣設備部署：

# 構建 WASM 包（供維護者使用）
wasm-pack build --target web --no-default-features --features wasm-compile

# WASM 工件位置：
# - pkg/ruchy_bg.wasm (~3.1MB 優化後)
# - pkg/ruchy.js (JavaScript 綁定)
# - pkg/ruchy_bg.wasm.d.ts (TypeScript 定義)

瀏覽器使用示例：

<script type="module">
  import init, { WasmRepl } from './ruchy.js';

  await init();
  const repl = new WasmRepl();
  const result = repl.eval('1 + 2');
  console.log(result); // "3"
</script>

注意：WASM 構建不包含 HTTP 和文件 I/O 操作（瀏覽器沙箱中不可用）。

開發服務器

Ruchy 提供了一個一流的開發服務器，支持熱重載、WASM 編譯和優雅關閉（v3.105.0+）。

基本用法：

# 在端口 8080 上提供當前目錄的服務
ruchy serve

# 在自定義端口上提供特定目錄的服務
ruchy serve ./dist --port 3000

# 啟用監視模式（文件更改時自動重啟）
ruchy serve --watch

# 啟用 WASM 熱重載（保存 .ruchy 文件時自動編譯為 .wasm）
ruchy serve --watch --watch-wasm

高級特性：

# 啟用所有特性的完整開發模式
ruchy serve \
  --watch \                # 文件更改時自動重啟
  --watch-wasm \           # 保存時將 .ruchy 文件編譯為 .wasm
  --debounce 200 \         # 防抖延遲（毫秒，默認值：300）
  --verbose \              # 顯示詳細日誌
  --pid-file server.pid    # 用於進程管理的 PID 文件

# 輸出示例：
#   🚀 Ruchy Dev Server v3.105.0
#
#   ➜  Local:   http://127.0.0.1:8080
#   ➜  Network: http://192.168.1.100:8080
#   📁 Serving: ./dist
#   👀 Watching: ./dist/**/*
#   🦀 WASM: Hot reload enabled for .ruchy files
#
#   Ready Press Ctrl+C to stop

特性說明：

• 熱重載：文件更改時自動重啟服務器（可配置防抖）
• WASM 編譯：保存 .ruchy 文件時自動編譯為 .wasm
• 優雅關閉：使用 Ctrl+C 進行乾淨的關閉（無需 kill -9）
• 網絡訪問：顯示本地和網絡 URL，方便移動測試
• PID 管理：基於 RAII 的 PID 文件，自動清理
• 美觀的用戶體驗：類似 Vite 的彩色輸出和狀態指示器
• 高性能：多線程異步運行時，優化的 TCP 設置

WASM 熱重載工作流程：

# 1. 啟動支持 WASM 監視的開發服務器
ruchy serve --watch --watch-wasm

# 2. 編輯 .ruchy 文件
# 保存 main.ruchy 時：
#   📝 Changed: main.ruchy
#   🦀 Compiling: main.ruchy
#   ✅ Compiled: main.wasm
#   ↻ Restarting server...

# 3. 瀏覽器自動重新加載新的 WASM

生產部署：

# 構建優化的 WASM 文件
ruchy wasm compile *.ruchy -o dist/ --opt-level 3

# 提供生產構建的服務（無監視模式）
ruchy serve ./dist --port 8080

Notebook 相關命令

• ruchy notebook - 在 http://localhost:8080 上啟動交互式 Notebook 服務器
• ruchy notebook test <file> - 測試 Notebook 並生成覆蓋率報告
• ruchy notebook convert <input> <output> - 轉換 Notebook 格式

Notebook 特性（v3.75.0+）：

• 狀態持久化：變量和函數在單元格執行之間保持持久（SharedRepl）
• 線程安全：基於 Arc 的併發訪問，使用 Mutex 同步
• Markdown 支持：完整的 Markdown 渲染，具備 XSS 保護
• 加載/保存：基於 JSON 的 .rnb Notebook 格式
• API 訪問：RESTful API 位於 /api/execute、/api/render-markdown、/api/notebook/load、/api/notebook/save

測試相關命令

• ruchy test run <path> - 運行測試，可選擇生成覆蓋率報告
• ruchy test report - 生成測試報告（HTML/JSON/JUnit）

項目結構

ruchy/
├── src/
│   ├── frontend/       # 解析器和 AST
│   ├── middleend/      # 類型系統和推斷
│   ├── backend/        # 代碼生成和轉譯
│   ├── runtime/        # REPL 和解釋器
│   ├── lsp/           # 語言服務器協議
│   └── wasm/          # WebAssembly 支持
├── tests/             # 集成測試
├── examples/          # 示例程序
└── docs/             # 文檔

質量標準

本項目遵循嚴格的質量工程實踐：

• 測試覆蓋率：行覆蓋率 46.41%，分支覆蓋率 50.79%
• 變異測試：通過 cargo-mutants 實現 80% 以上的變異覆蓋率（Sprint 8 目標）
• 複雜度限制：所有函數的圈複雜度 ≤10
• 零技術債務：不允許有 TODO/FIXME 註釋
• PMAT A+ 等級：通過自動化質量門強制實施
• TDD 實踐：採用測試優先的開發方法
• 線程安全：基於 Arc 的併發機制，經過 10K+ 次屬性測試（v3.75.0+）
• 端到端測試：通過預提交鉤子強制執行 21/21 個 Playwright 測試

變異測試策略

我們使用 cargo-mutants v25.3.1 進行實證測試質量驗證：

• 增量測試：逐文件進行變異測試（5 - 30 分鐘，而基線測試需 10 小時以上）
• 基於證據：測試針對實證分析確定的特定變異
• 模式識別：可複用的測試策略（匹配分支、邊界、樁）
• 質量指標：所有模塊的變異覆蓋率目標為 80% 以上

# 對特定文件運行變異測試
cargo mutants --file src/frontend/parser/core.rs --timeout 300

# 對模塊運行變異測試
cargo mutants --file "src/frontend/parser/*.rs" --timeout 600

# 查看變異測試結果
make mutation-test

開發相關

基本開發命令

# 運行測試
make test

# 檢查覆蓋率
make coverage

# 運行質量檢查
make lint

# 構建文檔
make doc

RuchyRuchy 調試工具

Ruchy 集成了 RuchyRuchy 調試工具包，提供高級調試功能：

• 源映射：Ruchy 到 Rust 轉譯調試的 1:1 行映射
• 時間旅行調試：記錄 - 回放引擎，支持向後步進執行
• 性能驗證：自動檢測迴歸（驗證時間 <6s）

設置方法：

# 將 ruchyruchy 克隆到同級目錄
git clone https://github.com/paiml/ruchyruchy ../ruchyruchy

# 通過預提交鉤子自動運行驗證
# 手動驗證：
./scripts/validate-debugging-tools.sh

預提交集成：每次提交時自動驗證調試工具（3 項檢查，總時間 <6s）。

詳細文檔請參閱 RuchyRuchy README。

WebAssembly 質量保證框架

項目包含一個全面的 WebAssembly 質量保證框架 v3.0，包含 4 個驗證階段：

# 運行完整的 QA 驗證
make qa-framework

# 單個階段
make qa-foundation    # 覆蓋率和基礎設施
make qa-browser       # 瀏覽器測試和 WASM 驗證
make qa-quality       # 安全和複雜度分析
make qa-optimization  # 性能和迴歸測試

# 快速質量檢查
make qa-security      # 安全分析
make qa-complexity    # 複雜度分析
make qa-dashboard     # 交互式質量儀表盤

# 查看所有 QA 命令
make qa-help

質量目標：

• 90% 分支覆蓋率
• 每個函數的圈複雜度 ≤10
• 零安全漏洞
• 優化後的 WASM 二進制文件 <500KB
• 性能迴歸容忍度 <5%

文檔資源

• 語言規範
• 開發路線圖

相關資源

• Ruchy 手冊 - 全面的語言指南，包含 259 個示例
• Rosetta Ruchy - 100+ 個算法實現，展示語言特性
• Ruchy REPL 演示 - 180+ 個交互式 REPL 示例和教程
• Ruchy Ruchy - 自託管編譯器演示和集成測試

🔧 技術細節

安全性與併發

零不安全策略：Ruchy 從不生成不安全的 Rust 代碼（GitHub Issue #132）。

默認線程安全

// 頂級可變變量自動線程安全
let mut counter = 0;

fun increment() {
    counter = counter + 1;  // ✅ Thread-safe (LazyLock<Mutex<T>>)
}

與 Rust 等效的併發機制

Ruchy 支持與 Rust 完全相同的併發機制 - 無抽象，直接 1:1 映射：

// 線程（與 Rust 相同）
let handle = std::thread::spawn(|| {
    println!("Hello from thread!");
    42
});
let result = handle.join().unwrap();

// Async/await (tokio)
async fun fetch_data(url: String) -> Result<String, Error> {
    let response = reqwest::get(url).await?;
    response.text().await
}

// 共享狀態 (Arc<Mutex<T>>)
use std::sync::{Arc, Mutex};
let data = Arc::new(Mutex::new(vec![]));

// 通道 (mpsc)
use std::sync::mpsc;
let (tx, rx) = mpsc::channel();

安全保證：

• ✅ 生成的代碼無不安全代碼
• ✅ 所有全局變量使用 LazyLock<Mutex<T>>（線程安全）
• ✅ 內存安全（Rust 所有權 + 借用檢查器）
• ✅ 無數據競爭（Send/Sync 特性強制）

詳細文檔請參閱 。

DataFrame 數據科學特性

狀態：DataFrame 實現約完成 80%，通過 200K+ 屬性測試證明正確性

已實現的特性 ✅：

• ✅ DataFrame 創建和基本操作（通過 polars-rs）
• ✅ CSV 讀寫
• ✅ 謂詞過濾（100K 屬性測試 - 數學證明正確性）
• ✅ 分組聚合操作
• ✅ 聚合函數：sum、count、mean、min、max、std、var
• ✅ 排序（升序/降序，100K 屬性測試 - 驗證穩定排序）
• ✅ 連接（內連接）
• ✅ 導出：to_csv()、to_json()
• ✅ 選擇和切片：select()、slice()、head()、tail()
• ✅ 元數據：shape()、columns()、rows()

測試質量：

• 137 個單元測試通過
• 200,000+ 次屬性測試迭代（過濾 + 排序）
• 所有函數複雜度 ≤10（符合豐田生產方式）
• 全面的邊界情況覆蓋

示例 API（來自測試套件）：

// 注意：DataFrame API 主要在 Rust 級別進行測試
// 高級 Ruchy 語法正在開發中

// 創建 DataFrame（通過 polars-rs 後端）
let df = dataframe::from_columns(vec![
    ("age", vec![25, 30, 35]),
    ("score", vec![95, 87, 92])
]).unwrap();

// 支持的操作（經過 200K+ 屬性測試）
// - df.select("column_name")
// - df.filter(predicate)
// - df.sort_by("column", descending)
// - df.groupby("column")
// - df.sum(), mean(), min(), max(), std(), var()
// - df.join(other_df, "key_column")

正在進行的工作：

• 用於 DataFrame 操作的高級 Ruchy 語法
• 高級連接類型（左連接、右連接、外連接）
• 多列分組
• 繪圖集成

完整測試示例請參閱 tests/dataframe_*_properties.rs。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

⚠️ 重要提示

Ruchy v3.94.0 不適合生產環境。雖然它展示了卓越的工程質量（TDG A-，3,987 個測試，極端 TDD），但缺乏生產使用所需的生態系統成熟度、安全審計和穩定性保證。預計達到生產就緒的時間為 18 - 30 個月。詳細分析請參閱 。

適用場景：研究、教育、原型設計、實驗 不適用場景：生產服務、關鍵任務系統、面向公眾的產品

致謝

• 基於 Rust 和出色的 Rust 生態系統構建
• 受 Python 的表達性和 Rust 的安全性啟發
• 借鑑豐田生產方式和 PMAT 方法論的質量實踐

聯繫信息

• 作者：Noah Gift
• 倉庫地址：github.com/paiml/ruchy
• 問題反饋：GitHub Issues