RuchyRuchy - Bootstrap Infrastructure & Educational Resource 🛠️

Bootstrap infrastructure and educational resource supporting the Ruchy programming language ecosystem. While the main Ruchy project has achieved actual self-hosting, RuchyRuchy provides educational examples, development tools, and performance validation for learning compiler construction concepts.

🏆 IMPORTANT: The main Ruchy project achieved real self-hosting in August 2025. This project serves as bootstrap infrastructure and education to support that ecosystem.

🎯 Project Purpose: Bootstrap Education & Tooling

Objective: Provide educational resources and development tools for understanding how bootstrap compilers work, complementing the production Ruchy compiler with:

Educational Stages:
├── Stage 0 (Lexer)     → Learn tokenization concepts
├── Stage 1 (Parser)    → Understand AST construction  
├── Stage 2 (TypeCheck) → Explore type inference (Algorithm W)
└── Stage 3 (CodeGen)   → Master code generation techniques

Value Proposition: Learn compiler construction through working implementations while supporting the Ruchy ecosystem with development tools and performance validation.

🚀 Quick Start

Install via Cargo (Recommended)

# Install the debugging toolkit
cargo install ruchyruchy

# Validate debugging tools
ruchydbg validate

Install from Source

# Install the production Ruchy compiler (required)
cargo install ruchy

# Clone the educational bootstrap project
git clone https://github.com/pragmatic-ai-labs/ruchyruchy.git
cd ruchyruchy

# Build and install
cargo build --release
cargo install --path .

# Explore educational examples
make stage0-demo      # Learn tokenization
make performance-demo # See code generation benchmarks
make concepts-demo    # Understand bootstrap principles

✨ Educational Architecture

📚 Learning-Focused Design

Design Principle: Demonstrate compiler construction concepts through progressive stages, with each stage teaching different aspects of compilation while supporting the main Ruchy ecosystem.

🏗️ Repository Structure

ruchyruchy/
├── bootstrap/                   # Educational compiler stages
│   ├── stage0/                 # Tokenization examples (educational)
│   │   ├── lexer.ruchy        # Example tokenizer
│   │   └── performance_test.ruchy # Speed validation
│   ├── stage1/                 # Parsing examples (educational)  
│   │   ├── parser.ruchy       # Example parser
│   │   └── ast.ruchy          # AST concepts
│   ├── stage2/                 # Type system concepts (educational)
│   │   ├── algorithm_w.ruchy  # Type inference examples
│   │   └── unification.ruchy  # Constraint solving
│   └── stage3/                 # Code generation tools (functional)
│       ├── real_codegen.rs    # Working Ruchy→Rust generator
│       └── performance_benchmark.rs # Speed validation
├── src/                        # Rust implementations (infrastructure)
│   ├── stage3_real_codegen.rs # Production code generator
│   └── bootstrap_pipeline.rs  # Pipeline integration
├── validation/                 # Educational testing examples
└── docs/                      # Learning resources

🔧 What This Project Provides

🎓 Educational Value

1. Compiler Construction Learning: Step-by-step examples of building compiler stages
2. Bootstrap Concepts: Clear demonstration of self-hosting principles
3. Performance Analysis: Understanding compilation speed requirements
4. Architecture Patterns: Real examples of compiler pipeline design

🛠️ Infrastructure Tools

1. Debugging Toolkit: Source map generation, time-travel debugging infrastructure
2. Ruchy→Rust Code Generator: Working tool for transpilation
3. Performance Benchmarks: Validation of code generation speeds
4. Development Examples: Templates for ecosystem development
5. Integration Testing: Tools for validating compilation pipelines

🔍 Debugging Tools (Phase 1 Complete)

• Source Map Generation: Line-number mapping for debugging (DEBUG-001)
• Record-Replay Engine: Time-travel debugging proof of concept (DEBUG-008)
• CLI Validation Tool: Fast-feedback debugging validation (ruchydbg)
• Pre-commit Integration: Continuous validation in production workflow
• Performance: 0.013s validation (461x faster than target!)

📊 Validated Performance

• Code Generation: 24,082,232 LOC/s measured throughput
• Pipeline Integration: Complete end-to-end compilation flow
• Quality Validation: Comprehensive testing frameworks
• Real Compilation: Actual working Ruchy→Rust→executable flow

🛠️ Development Commands

Educational Exploration

# Learn compiler concepts through examples
make concepts-demo     # Understand bootstrap principles
make stage0-demo      # See tokenization in action
make stage1-demo      # Explore parsing concepts
make type-demo        # Learn Algorithm W type inference

# Performance validation and benchmarking  
make performance-test # Validate code generation speeds
make pipeline-test    # Test end-to-end compilation
make showcase        # Full capability demonstration

Infrastructure Development

# Development tools for Ruchy ecosystem
make build-tools     # Build code generation tools
make test-tools      # Validate tool functionality  
make performance     # Run speed benchmarks
make quality-check   # Toyota Way validation

📊 Relationship to Main Ruchy Project

🏆 Main Ruchy Project - Production Compiler

• Status: ✅ Actual self-hosting achieved (August 2025)
• Repository: https://github.com/paiml/ruchy
• Achievement: Complete bootstrap compiler written in Ruchy
• Evidence: Working /src/self_hosting/ directory with real implementation

🛠️ RuchyRuchy Project - Supporting Infrastructure

• Status: ✅ Educational resource & development tools
• Purpose: Bootstrap education and ecosystem tooling
• Achievement: Working infrastructure with validated performance
• Value: Learning resource and development support

📝 Official Recognition

From Ruchy v1.9.1 Release Notes:

ruchyruchy: Bootstrap infrastructure complete, ready for Stage 0

🎓 Interactive Learning Resources

✨ NEW: Interactive Educational Modules

EDUCATION-001 Complete: Four interactive learning tools now available:

1. 📝 Tokenization Tutorial

   • Step-by-step lexical analysis guide
   • Character recognition examples
   • Keyword vs identifier distinction
   • Interactive tokenization exercises

2. 🌳 AST Explorer

   • Interactive parsing visualization
   • Click any AST node to see details
   • Multiple Ruchy code examples
   • Real-time syntax tree generation

3. 🧠 Type Inference Playground

   • Algorithm W step-by-step demonstration
   • Constraint generation and unification
   • Polymorphic type inference examples
   • Visual substitution process

4. ⚡ Code Generation Visualizer

   • Ruchy→Rust transformation visualization
   • Performance metrics (24M+ LOC/s)
   • Optimization pass demonstration
   • Side-by-side code comparison

Understanding Bootstrap Concepts

// Example: Simple compiler pipeline (educational)
struct Token { kind: String, value: String }

fn simple_compile_demo(source: String) -> String {
    // Stage 1: Tokenization
    let tokens = tokenize(source)
    
    // Stage 2: Parsing  
    let ast = parse(tokens)
    
    // Stage 3: Code Generation
    let rust_code = generate_rust(ast)
    
    rust_code
}

// This demonstrates the concept - real implementation in main Ruchy project

Performance Validation Tools

// Working infrastructure: Code generation benchmark
fn benchmark_code_generation() {
    let test_program = generate_test_ruchy_code();
    let start = Instant::now();
    let generated_rust = compile_ruchy_to_rust(&test_program);  
    let duration = start.elapsed();
    
    println!("Generated {} lines in {:.2}ms", 
             test_program.lines().count(), 
             duration.as_secs_f64() * 1000.0);
}

📈 Current Status & Roadmap

✅ Completed Infrastructure

• Code generation tools (24M+ LOC/s validated)
• Pipeline integration framework
• Performance benchmarking suite
• Educational concept demonstrations
• Quality assurance frameworks

🎯 Active Development Areas

See ROADMAP.md for detailed ticket-based development plan:

• INFRA-001: Enhanced educational examples
• INFRA-002: Integration with main Ruchy toolchain
• INFRA-003: Advanced performance optimization
• INFRA-004: Community learning resources

🤝 Contributing

We welcome contributions! See our comprehensive CONTRIBUTING.md for detailed guidelines.

Quick Start for Contributors

1. Choose a ticket from ROADMAP.md
2. Use our templates in /templates/ for new content
3. Follow quality gates: make quality-gate must pass
4. Submit PR using our PR template

Contribution Framework Features

📝 Educational Content Templates

• HTML Tutorial Template: Interactive learning experiences
• Markdown Tutorial Template: Comprehensive written guides
• Both templates include learning objectives, exercises, and feedback widgets

🔍 Review Process

• Automated quality checks on all PRs
• Peer review for educational value
• Performance validation for code changes
• Clear acceptance criteria for all contributions

💬 Feedback System

• Interactive feedback form: Provide Feedback
• GitHub issue templates for bugs, features, and educational content
• Community feedback statistics and tracking
• Multiple feedback channels for different needs

Development Principles

1. Educational Focus: All work should teach compiler concepts
2. Infrastructure Support: Tools should help Ruchy ecosystem
3. Quality Standards: Toyota Way principles maintained
4. Ecosystem Integration: Complement, don't compete with main project

📊 Success Metrics

Educational Impact

1. Learning Outcomes: Clear understanding of compiler construction
2. Concept Demonstration: Working examples of all compilation stages
3. Performance Understanding: Empirical validation of speed requirements
4. Ecosystem Support: Tools that help Ruchy development

Infrastructure Quality

1. Code Generation Speed: 24M+ LOC/s validated performance
2. Pipeline Integration: Complete end-to-end compilation flow
3. Tool Reliability: Robust development infrastructure
4. Educational Clarity: Clear, understandable examples

🔗 Links

• Main Ruchy Project: https://github.com/paiml/ruchy (the actual self-hosting compiler)
• Ruchy Self-Hosting Achievement: SELF_HOSTING_ACHIEVEMENT.md
• Project Relationship: PROJECT_RELATIONSHIP_CLARIFICATION.md
• Performance Validation: BOOTSTRAP_COMPLETE.md

📄 License

MIT License - See LICENSE for details.

🎓 Educational Excellence in Compiler Construction

Supporting the Ruchy Ecosystem: While the main Ruchy project delivers production self-hosting capability, RuchyRuchy provides the educational foundation and development tools to understand and contribute to that remarkable achievement.