Chapter 14: The Ruchy Toolchain - Professional Development Tools

Chapter Status: ✅ 100% Validated (5/5 code examples) + 🆕 3 New Tools Documented

Chapter Type: Tooling Documentation (not language features)

Last updated: 2025-11-01 Ruchy version: v3.169.0

Validated Examples (5/5) - 100% Pass Rate:

Example 1: Basic greet function ✅
Example 2: Calculator with add ✅
Example 3: Calculator with add and multiply ✅
Example 4: Recursive factorial ✅
Example 5: Iterative fibonacci ✅

Tools Documented:

✅ ruchy check - Syntax validation
✅ ruchy test - Testing with coverage
✅ ruchy lint - Style analysis
✅ ruchy score - Quality scoring (A+ grades achieved)
✅ ruchy runtime - Performance analysis
✅ ruchy fmt - Code formatting
✅ ruchy doc - Documentation generation
✅ ruchy prove - Formal verification
✅ ruchy ast - AST analysis
✅ ruchy bench - Benchmarking
✅ ruchy-coverage - Coverage reporting
🆕 ruchy publish - Package publishing (v3.169.0)
🆕 ruchy mcp - Real-time quality server (v3.169.0)
🆕 ruchy optimize - Hardware optimization analysis (v3.169.0)

Note: This chapter documents HOW to use Ruchy’s professional tooling suite. All code examples have been validated to compile and run successfully.

The Ruchy programming language comes with a comprehensive suite of professional development tools that ensure code quality, performance, and maintainability. This chapter teaches you to master the entire Ruchy toolchain, from basic syntax validation to advanced formal verification.

The Problem

Professional software development requires more than just writing code that works. Modern developers need:

Quality Assurance: Automated code quality checking
Performance Analysis: Understanding code efficiency
Team Collaboration: Consistent formatting and standards
Continuous Integration: Automated testing and validation
Documentation: Generated API docs and examples

The Ruchy toolchain provides all these capabilities through a unified command-line interface.

Quick Example

Let’s start with a simple program and see how the toolchain helps us maintain professional quality:

fun greet(name: String) -> String {
    "Hello, " + name + "!"
}

fun main() {
    let message = greet("Ruchy Developer");
    println(message);
}

Core Development Tools

Syntax Validation - `ruchy check`

The foundation of quality is correct syntax. The check command validates your code structure:

# Validate a single file
$ ruchy check hello_world.ruchy
✓ Syntax is valid

# Check multiple files
$ ruchy check **/*.ruchy
✓ All 25 files passed syntax validation

# Use in scripts (exits with error code on failure)
$ ruchy check src/ || exit 1

When to use: Before every commit, in CI/CD pipelines, during development.

Testing - `ruchy test`

Professional development requires comprehensive testing:

// calculator_test.ruchy
fun add(a: i32, b: i32) -> i32 {
    a + b
}

fun test_addition() {
    let result = add(2, 3);
    assert_eq(result, 5);
    println("Addition test passed");
}

fun main() {
    test_addition();
}

# Run tests with coverage
$ ruchy test calculator_test.ruchy
🧪 Running test...
✓ All tests passed
📊 Coverage: 100%

Code Quality - `ruchy lint`

Style consistency and best practices enforcement:

# Style analysis
$ ruchy lint hello_world.ruchy
✓ No style issues found

# Get detailed feedback
$ ruchy lint --verbose calculator.ruchy
📊 Quality Analysis Complete

The linter checks for common issues like unused variables, complex functions, and style violations.

Quality Scoring - `ruchy score`

Unified quality metrics for your code:

$ ruchy score hello_world.ruchy
=== Quality Score ===
File: hello_world.ruchy
Score: 1.00/1.0 (A+)
Analysis Depth: standard

Score Interpretation:

1.00 (A+): Production ready
0.85-0.99 (A): High quality
0.70-0.84 (B): Good quality
< 0.70: Needs improvement

Real-Time Quality Server - `ruchy mcp` 🆕

New in v3.169.0 - Model Context Protocol server for real-time quality analysis:

# Start MCP server for IDE integration
$ ruchy mcp
🚀 Ruchy MCP Server started
📡 Listening on: stdio
🔧 Quality threshold: 0.8
⚡ Streaming: disabled

# Start with custom configuration
$ ruchy mcp --name my-project-quality \\
           --min-score 0.9 \\
           --max-complexity 8 \\
           --streaming \\
           --verbose
🚀 Ruchy MCP Server: my-project-quality
📊 Min quality score: 0.9
🔧 Max complexity: 8
⚡ Streaming updates: enabled
📡 Ready for connections

# With timeout configuration
$ ruchy mcp --timeout 7200
⏱️  Session timeout: 2 hours

MCP Server Options:

--name <NAME>: Server name for MCP identification (default: ruchy-mcp)
--streaming: Enable streaming quality updates
--timeout <TIMEOUT>: Session timeout in seconds (default: 3600)
--min-score <MIN_SCORE>: Minimum quality score threshold (default: 0.8)
--max-complexity <MAX_COMPLEXITY>: Maximum complexity threshold (default: 10)
-v, --verbose: Enable verbose logging
-c, --config <CONFIG>: Configuration file path

Use Cases:

IDE Integration - Real-time quality feedback in editors (VS Code, Cursor, etc.)
CI/CD Monitoring - Continuous quality analysis during builds
Team Dashboards - Live quality metrics visualization
Code Review - Automated quality checks during PR reviews

Example Integration with VS Code:

{
  "ruchy.mcp": {
    "enabled": true,
    "server": "ruchy mcp --streaming --min-score 0.9",
    "autoStart": true
  }
}

MCP Protocol Features:

Real-time syntax validation
Live quality scoring
Streaming complexity analysis
Instant lint feedback
Coverage monitoring
Performance metrics

When to use:

During active development for immediate feedback
In team environments for shared quality standards
With CI/CD for continuous monitoring
For dashboard integration and visualization

Advanced Quality Tools

Performance Analysis - `ruchy runtime`

Understanding your code’s performance characteristics:

fun calculate_factorial(n: i32) -> i32 {
    if n <= 1 {
        1
    } else {
        n * calculate_factorial(n - 1)
    }
}

fun main() {
    let result = calculate_factorial(10);
    println(result);
}

$ ruchy runtime factorial.ruchy
=== Performance Analysis ===
- Time Complexity: O(n)
- Space Complexity: O(n)
- Optimization Score: 85%

Hardware-Aware Optimization - `ruchy optimize` 🆕

New in v3.169.0 - Analyze code for hardware-specific optimization opportunities:

# Quick optimization analysis
$ ruchy optimize factorial.ruchy --depth quick
=== Optimization Analysis ===
File: factorial.ruchy
Hardware Profile: detect
Analysis Depth: quick
Threshold: 5.00%

=== Recommendations ===
• Consider loop unrolling for tight loops
• Use const generics where possible
• Profile-guided optimization recommended

# Deep analysis with all details
$ ruchy optimize factorial.ruchy --depth deep --cache --branches --vectorization
=== Deep Optimization Analysis ===

📊 Cache Behavior:
• L1 cache misses: Low (< 5%)
• L2 cache utilization: Good
• Recommendation: Data locality is optimal

🔀 Branch Prediction:
• Branch mispredictions: 2.3%
• Recommendation: Consider branch-free algorithms for hot paths

⚡ Vectorization:
• SIMD opportunities: 3 found
• Recommendation: Use array operations for auto-vectorization

💰 Abstraction Cost:
• Function call overhead: Minimal
• Recommendation: Current abstraction level is optimal

# Benchmark hardware characteristics
$ ruchy optimize --benchmark
=== Hardware Benchmarking ===
CPU: Intel Core i7-9750H @ 2.60GHz
Architecture: x86_64
Cache sizes: L1: 64KB, L2: 256KB, L3: 12MB
SIMD: AVX2, AVX512 available
Branch predictor: Modern (> 95% accuracy)

# Generate HTML report
$ ruchy optimize factorial.ruchy --format html --output optimization_report.html
📊 Saved optimization analysis to: optimization_report.html

Optimization Analysis Options:

--hardware <HARDWARE>: Target hardware profile (detect, intel, amd, arm)
--depth <DEPTH>: Analysis depth (quick, standard, deep)
--cache: Show cache behavior analysis
--branches: Show branch prediction analysis
--vectorization: Show SIMD vectorization opportunities
--abstractions: Show abstraction cost analysis
--benchmark: Benchmark hardware characteristics
--format <FORMAT>: Output format (text, json, html)
--output <OUTPUT>: Save analysis to file
--threshold <THRESHOLD>: Minimum impact threshold (0.0-1.0)

When to use:

Optimizing performance-critical code
Understanding hardware-specific bottlenecks
Planning SIMD/vectorization strategies
Analyzing cache behavior
Making informed optimization decisions

Formal Verification - `ruchy prove`

Mathematical verification of code properties:

$ ruchy prove math_functions.ruchy
=== Provability Analysis ===
- add_function: ✓ Mathematically sound
- multiply_function: ✓ Properties verified  
- Provability Score: 95%

This tool analyzes mathematical properties of your functions and verifies logical correctness.

Code Formatting - `ruchy fmt`

Consistent code formatting across your project:

# Check formatting
$ ruchy fmt hello_world.ruchy
✓ Code is properly formatted

# Auto-format files
$ ruchy fmt --write src/
✓ Formatted 15 files

# Check in CI (exit code 1 if formatting needed)
$ ruchy fmt --check src/

Documentation Generation - `ruchy doc`

Automatic API documentation from your code:

# Generate documentation
$ ruchy doc --output docs/ src/
📚 Generated documentation for 25 functions
🌐 Available at: docs/index.html

The doc tool extracts function signatures, comments, and examples to create professional documentation.

Package Publishing - `ruchy publish` 🆕

New in v3.169.0 - Publish your Ruchy packages to the registry for community sharing:

# Validate package before publishing (dry-run)
$ ruchy publish --dry-run
🔍 Dry-run mode: Validating package 'my-package'
✅ Package validation successful
📦 Package: my-package v1.0.0
👤 Authors: Your Name <you@example.com>
📝 License: MIT

✨ Would publish package (skipped in dry-run mode)

# Publish to Ruchy registry
$ ruchy publish
📦 Publishing my-package v1.0.0 to https://ruchy.dev/registry
✅ Successfully published my-package v1.0.0
🌐 Available at: https://ruchy.dev/registry/my-package

Package Configuration - Create a Ruchy.toml manifest:

[package]
name = "my-awesome-library"
version = "1.0.0"
authors = ["Your Name <you@example.com>"]
description = "A fantastic Ruchy library"
license = "MIT"
repository = "https://github.com/username/my-awesome-library"

[dependencies]
# Add dependencies here

Publishing Options:

# Specify version explicitly
$ ruchy publish --version 1.0.1

# Allow publishing with uncommitted changes
$ ruchy publish --allow-dirty

# Use custom registry
$ ruchy publish --registry https://custom-registry.example.com

Publishing Workflow:

Validate locally: ruchy publish --dry-run
Run quality gates: Ensure all tests pass, A+ score
Publish: ruchy publish
Verify: Check package at registry URL

When to publish:

After achieving quality gates (A+ score, 100% tests)
For reusable libraries and tools
To share with the Ruchy community

Professional Workflow Integration

Pre-commit Quality Gates

Integrate quality tools into your development workflow:

#!/bin/bash
# .git/hooks/pre-commit
echo "🔒 Running Ruchy quality gates..."

# Must pass all checks
ruchy check **/*.ruchy || exit 1
ruchy test **/*_test.ruchy || exit 1  
ruchy lint **/*.ruchy || exit 1
ruchy score **/*.ruchy | grep -q "A" || exit 1

echo "✅ All quality gates passed"

CI/CD Pipeline Example

# .github/workflows/quality.yml
name: Ruchy Quality Gates
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Ruchy
        run: curl -sSL install.ruchy.org | bash
        
      - name: Syntax Validation
        run: ruchy check **/*.ruchy
        
      - name: Run Tests
        run: ruchy test **/*_test.ruchy
        
      - name: Quality Analysis  
        run: ruchy score **/*.ruchy
        
      - name: Performance Check
        run: ruchy runtime **/*.ruchy

Advanced Development Tools

AST Analysis - `ruchy ast`

Understand your code’s structure:

$ ruchy ast hello_world.ruchy
=== Abstract Syntax Tree ===
Program
├── Function: greet
│   ├── Parameter: name (String)
│   └── Body: BinaryOp(+)
└── Function: main
    └── Body: FunctionCall(greet)

Performance Benchmarking - `ruchy bench`

Measure and compare performance:

fun fibonacci_recursive(n: i32) -> i32 {
    if n <= 1 {
        n
    } else {
        fibonacci_recursive(n - 1) + fibonacci_recursive(n - 2)
    }
}

fun fibonacci_iterative(n: i32) -> i32 {
    let mut a = 0;
    let mut b = 1;
    let mut i = 0;
    
    while i < n {
        let temp = a + b;
        a = b;
        b = temp;
        i = i + 1;
    }
    
    a
}

fun main() {
    let result1 = fibonacci_recursive(10);
    let result2 = fibonacci_iterative(10);
    println(result1);
    println(result2);
}

$ ruchy bench fibonacci.ruchy
=== Benchmark Results ===
fibonacci_recursive: 12.4ms ± 0.8ms
fibonacci_iterative: 0.1ms ± 0.01ms
Winner: fibonacci_iterative (124x faster)

Coverage Analysis - `ruchy-coverage`

Detailed test coverage reporting:

$ ruchy-coverage calculator_test.ruchy
=== Coverage Report ===
Lines: 45/50 (90%)
Branches: 8/10 (80%)
Functions: 5/5 (100%)

Missing Coverage:
- Line 23: Error handling branch
- Line 31: Edge case validation

Real-World Development Workflow

Here’s a complete development cycle using all tools:

# 1. Create new project
$ mkdir my_ruchy_project && cd my_ruchy_project

# 2. Write your code
$ cat > calculator.ruchy << 'EOF'
fun add(a: i32, b: i32) -> i32 {
    a + b
}

fun multiply(a: i32, b: i32) -> i32 {
    a * b
}

fun main() {
    let sum = add(10, 20);
    let product = multiply(5, 6);
    println(sum);
    println(product);
}
EOF

# 3. Validate syntax
$ ruchy check calculator.ruchy
✓ Syntax is valid

# 4. Check code quality
$ ruchy score calculator.ruchy
Score: 1.00/1.0 (A+)

# 5. Run style analysis
$ ruchy lint calculator.ruchy  
✓ No style issues found

# 6. Format code consistently
$ ruchy fmt --write calculator.ruchy
✓ Code formatted

# 7. Run performance analysis
$ ruchy runtime calculator.ruchy
Optimization Score: 98%

# 8. Generate documentation
$ ruchy doc --output docs/ calculator.ruchy
📚 Documentation generated

# 9. Commit with confidence
$ git add . && git commit -m "Add calculator with 100% quality"

Tool Integration Best Practices

Development Environment Setup

Add these to your shell profile (~/.bashrc or ~/.zshrc):

# Ruchy development aliases
alias rc='ruchy check'
alias rt='ruchy test'  
alias rs='ruchy score'
alias rl='ruchy lint'
alias rf='ruchy fmt --write'

# Quality gate shortcut
alias rq='ruchy check **/*.ruchy && ruchy test **/*_test.ruchy && ruchy lint **/*.ruchy'

Makefile Integration

# Makefile for Ruchy projects
.PHONY: check test lint score format quality

check:
	ruchy check **/*.ruchy

test:
	ruchy test **/*_test.ruchy

lint:
	ruchy lint **/*.ruchy

score:
	ruchy score **/*.ruchy

format:
	ruchy fmt --write **/*.ruchy

quality: check test lint score
	@echo "✅ All quality gates passed"

clean:
	rm -f **/*.tmp **/*.bak

Editor Integration

For VS Code, add to settings.json:

{
    "files.associations": {
        "*.ruchy": "ruchy"
    },
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.ruchy": true
    }
}

Performance Optimization Workflow

When optimizing code performance:

Baseline measurement: ruchy runtime original.ruchy
Identify bottlenecks: ruchy bench --profile original.ruchy
Make improvements: Edit your code
Verify correctness: ruchy test optimized.ruchy
Measure improvement: ruchy bench original.ruchy optimized.ruchy
Ensure quality: ruchy score optimized.ruchy

Quality Metrics Dashboard

Track your project’s health over time:

#!/bin/bash
# generate_metrics.sh
echo "# Project Quality Dashboard"
echo "Generated: $(date)"
echo ""

echo "## Test Results"
ruchy test **/*_test.ruchy | grep -E "(passed|failed|coverage)"

echo "## Quality Scores"  
ruchy score **/*.ruchy | grep "Score:"

echo "## Style Analysis"
ruchy lint **/*.ruchy | grep "Summary:"

echo "## Performance"
ruchy runtime **/*.ruchy | grep "Optimization Score:"

Run this script regularly to track quality trends.

Troubleshooting Common Issues

Build Failures

# Debug syntax issues
$ ruchy check --verbose problematic.ruchy

# Check for common problems
$ ruchy lint --strict problematic.ruchy  

# Validate with different modes
$ ruchy check --pedantic problematic.ruchy

Performance Problems

# Profile performance bottlenecks
$ ruchy runtime --profile slow.ruchy

# Compare algorithms
$ ruchy bench algorithm1.ruchy algorithm2.ruchy

# Check complexity analysis
$ ruchy runtime --complexity slow.ruchy

Quality Issues

# Get detailed quality breakdown
$ ruchy score --verbose low_quality.ruchy

# Focus on specific issues
$ ruchy lint --only warnings low_quality.ruchy

# Track improvement over time
$ ruchy score --history low_quality.ruchy

Summary

The Ruchy toolchain provides professional-grade development tools:

Core Development Tools:

✅ ruchy check: Syntax validation and compilation verification
✅ ruchy test: Comprehensive testing with coverage analysis
✅ ruchy fmt: Consistent code formatting
✅ ruchy ast: Code structure analysis

Quality Analysis Tools:

✅ ruchy lint: Style analysis and best practices enforcement
✅ ruchy score: Unified quality scoring (target: A+ grade)
🆕 ruchy mcp: Real-time quality server via Model Context Protocol (v3.169.0)

Performance Tools:

✅ ruchy runtime: Performance analysis and optimization
🆕 ruchy optimize: Hardware-aware optimization analysis (v3.169.0)
✅ ruchy bench: Performance benchmarking

Advanced Tools:

✅ ruchy prove: Formal verification capabilities
✅ ruchy-coverage: Detailed coverage reporting
✅ ruchy doc: Automated documentation generation
🆕 ruchy publish: Package publishing to Ruchy registry (v3.169.0)

Key Takeaways

Use tools continuously: Integrate into daily development workflow
Automate quality gates: Set up pre-commit hooks and CI/CD
Target A+ scores: Maintain high quality standards
Profile performance: Use runtime analysis for optimization
Generate documentation: Keep docs current with ruchy doc
Test comprehensively: Aim for 100% coverage

The Ruchy toolchain transforms code quality from an afterthought into a built-in development practice, enabling professional software development with confidence and speed.

Exercises

Set up pre-commit hooks with all quality tools
Create a CI/CD pipeline for a Ruchy project
Use benchmarking to optimize a recursive function
Generate documentation for a multi-file project
Achieve A+ quality scores on a complex codebase

Keyboard shortcuts

The Ruchy Programming Language