Ruchy Programming Language

A modern, expressive programming language for data science and scientific computing, featuring a self-hosting compiler, comprehensive tooling, and enterprise-grade quality standards.

⚠️ PRODUCTION READINESS: Ruchy v3.94.0 is NOT production-ready. While demonstrating exceptional engineering quality (TDG A-, 3,987 tests, EXTREME TDD), it lacks ecosystem maturity, security audits, and stability guarantees required for production use. Estimated time to production: 18-30 months. See docs/PRODUCTION-READINESS-ASSESSMENT.md for detailed analysis.

Appropriate uses: Research, education, prototyping, experimentation Inappropriate uses: Production services, mission-critical systems, public-facing products

Features

• Self-Hosting Compiler: Written in Rust with full bootstrapping capabilities
• Interactive REPL: Advanced REPL with syntax highlighting and completion
• WebAssembly Support: Compile to WASM for browser and edge deployment
• Notebook Integration: Jupyter-style notebooks with testing framework
• Type System: Bidirectional type checking with inference
• Package Management: Cargo integration with 140K+ crates via ruchy add
• Quality First: Toyota Way principles with PMAT A+ code standards

Installation

# Install from crates.io
cargo install ruchy

# Install with MCP server support
cargo install ruchy --features mcp

# Or build from source
git clone https://github.com/paiml/ruchy
cd ruchy
cargo build --release

MCP Server

Ruchy provides a Model Context Protocol (MCP) server that exposes code analysis, scoring, linting, and transpilation capabilities to Claude and other MCP clients.

Installation

# Install Ruchy with MCP support
cargo install ruchy --features mcp

Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Available Tools

The Ruchy MCP server provides 7 tools:

• ruchy-score: Analyze code quality with unified 0.0-1.0 scoring system
• ruchy-lint: Real-time code linting with auto-fix suggestions
• ruchy-format: Format Ruchy source code with configurable style
• ruchy-analyze: Comprehensive code analysis with AST, metrics, and insights
• ruchy-eval: Evaluate Ruchy expressions with type safety
• ruchy-transpile: Transpile Ruchy code to Rust
• ruchy-type-check: Type check Ruchy expressions

Usage

# Start MCP server (typically called by Claude Desktop)
ruchy mcp --verbose

For more details, see docs/mcp-registry-publish.md.

Quick Start

# Start the interactive REPL (no args)
ruchy

# Run a Ruchy script (interprets immediately, <1s)
ruchy script.ruchy
# or explicitly:
ruchy run script.ruchy

# Compile to production binary
ruchy compile script.ruchy -o myapp

# Format code
ruchy fmt src/

# Run tests
ruchy test tests/

Language Examples

Basic Syntax

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

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

// Pattern matching
let value = Some(5)
match value {
    Some(x) => println(f"Got {x}"),
    None => println("Nothing"),
}

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

Package Management (NEW in v3.76.0)

# Create new Ruchy project with Cargo integration
ruchy new my_project

# Add dependencies from crates.io
cd my_project
ruchy add serde
ruchy add [email protected]

# Add dev dependencies
ruchy add --dev proptest

# Build project (auto-transpiles .ruchy → .rs)
ruchy build
ruchy build --release

# Run project
cargo run

Data Science Features (DataFrame - 80% Complete)

Status: DataFrame implementation is ~80% complete with 200K+ property tests proving correctness

Implemented Features ✅:

• ✅ DataFrame creation and basic operations (via polars-rs)
• ✅ CSV reading/writing
• ✅ Filtering with predicates (100K property tests - mathematical proof of correctness)
• ✅ Group by operations with aggregations
• ✅ Aggregation functions: sum, count, mean, min, max, std, var
• ✅ Sorting (ascending/descending, 100K property tests - stable sort verified)
• ✅ Joins (inner join)
• ✅ Export: to_csv(), to_json()
• ✅ Selection and slicing: select(), slice(), head(), tail()
• ✅ Metadata: shape(), columns(), rows()

Test Quality:

• 137 unit tests passing
• 200,000+ property test iterations (filter + sort)
• Complexity ≤10 for all functions (Toyota Way compliant)
• Comprehensive edge case coverage

Example API (from test suite):

// Note: DataFrame API is primarily tested at Rust level
// High-level Ruchy syntax is under development

// Create DataFrame (via polars-rs backend)
let df = dataframe::from_columns(vec![
    ("age", vec![25, 30, 35]),
    ("score", vec![95, 87, 92])
]).unwrap();

// Operations supported (tested with 200K+ property tests):
// - 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")

In Progress:

• High-level Ruchy syntax for DataFrame operations
• Advanced join types (left, right, outer)
• Multi-column grouping
• Plotting integration

See tests/dataframe_*_properties.rs for comprehensive test examples.

CLI Commands

Core Commands

• ruchy repl - Start interactive REPL
• ruchy run <file> - Execute a Ruchy script
• ruchy fmt <path> - Format code (supports --check flag)

WebAssembly

• ruchy wasm compile <input> -o <output> - Compile to WASM
• ruchy wasm validate <module> - Validate WASM module
• ruchy wasm run <module> - Execute WASM module

Notebook

• ruchy notebook - Start interactive notebook server on http://localhost:8080
• ruchy notebook test <file> - Test notebook with coverage
• ruchy notebook convert <input> <output> - Convert notebook format

Notebook Features (v3.75.0+):

• State Persistence: Variables and functions persist across cell executions (SharedRepl)
• Thread-Safe: Arc-based concurrent access with Mutex synchronization
• Markdown Support: Full markdown rendering with XSS protection
• Load/Save: JSON-based .rnb notebook format
• API Access: RESTful API at /api/execute, /api/render-markdown, /api/notebook/load, /api/notebook/save

Testing

• ruchy test run <path> - Run tests with optional coverage
• ruchy test report - Generate test report (HTML/JSON/JUnit)

Project Structure

ruchy/
├── src/
│   ├── frontend/       # Parser and AST
│   ├── middleend/      # Type system and inference
│   ├── backend/        # Code generation and transpilation
│   ├── runtime/        # REPL and interpreter
│   ├── lsp/           # Language server protocol
│   └── wasm/          # WebAssembly support
├── tests/             # Integration tests
├── examples/          # Example programs
└── docs/             # Documentation

Quality Standards

This project follows strict quality engineering practices:

• Test Coverage: 46.41% line coverage, 50.79% branch coverage
• Mutation Testing: 80%+ mutation coverage via cargo-mutants (Sprint 8 goal)
• Complexity Limits: All functions ≤10 cyclomatic complexity
• Zero Technical Debt: No TODO/FIXME comments allowed
• PMAT A+ Grade: Enforced via automated quality gates
• TDD Practice: Test-first development methodology
• Thread-Safety: Arc-based concurrency, property-tested with 10K+ iterations (v3.75.0+)
• E2E Testing: 21/21 Playwright tests enforced via pre-commit hooks

Mutation Testing Strategy

We use cargo-mutants v25.3.1 for empirical test quality validation:

• Incremental Testing: File-by-file mutation testing (5-30 min vs 10+ hours baseline)
• Evidence-Based: Tests target specific mutations identified by empirical analysis
• Pattern Recognition: Reusable test strategies (match arms, boundaries, stubs)
• Quality Metrics: 80%+ mutation coverage target across all modules

# Run mutation tests on specific file
cargo mutants --file src/frontend/parser/core.rs --timeout 300

# Run mutation tests on module
cargo mutants --file "src/frontend/parser/*.rs" --timeout 600

# See mutation test results
make mutation-test

Development

Basic Development Commands

# Run tests
make test

# Check coverage
make coverage

# Run quality checks
make lint

# Build documentation
make doc

WebAssembly QA Framework

The project includes a comprehensive WebAssembly Quality Assurance Framework v3.0 with 4 validation phases:

# Run complete QA validation
make qa-framework

# Individual phases
make qa-foundation    # Coverage & infrastructure
make qa-browser       # Browser testing & WASM validation
make qa-quality       # Security & complexity analysis
make qa-optimization  # Performance & regression testing

# Quick quality checks
make qa-security      # Security analysis
make qa-complexity    # Complexity analysis
make qa-dashboard     # Interactive quality dashboard

# See all QA commands
make qa-help

Quality Targets:

• 90% branch coverage
• ≤10 cyclomatic complexity per function
• Zero security vulnerabilities
• <500KB optimized WASM binaries
• <5% performance regression tolerance

Documentation

• Language Specification
• Development Roadmap
• Contributing Guide
• Architecture Overview

Related Resources

• Ruchy Book - Comprehensive language guide with 259 examples
• Rosetta Ruchy - 100+ algorithm implementations showcasing language features
• Ruchy REPL Demos - 180+ interactive REPL examples and tutorials
• Ruchy Ruchy - Self-hosting compiler demos and integration tests

Contributing

We welcome contributions! Please see our Contributing Guide for details on our code of conduct and development process.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Rust and the incredible Rust ecosystem
• Inspired by Python's expressiveness and Rust's safety
• Quality practices from Toyota Way and PMAT methodologies

Contact

• Author: Noah Gift
• Repository: github.com/paiml/ruchy
• Issues: GitHub Issues