Contributing to Phaser

This directory contains documentation and guidelines for contributors to the Phaser compiler project.

🔧 Compiler Implementation Documents

Architecture and Design

• Compilation Pipeline - Five-phase compilation architecture and coordination
• Code Organization - Physical file structure and implementation patterns
• AST Specification - Abstract Syntax Tree structure and node definitions

Implementation Specifications

• Lexical Analysis - Tokenization, lexer implementation, and error handling
• Error Handling - Comprehensive compiler error system and diagnostics
• Testing Strategy - Testing approach for all compiler phases and integration

Development Guidelines (Coming Soon)

• Development Workflow - How to build, test, and contribute to the compiler
• API Design Guidelines - Interface design principles and patterns
• Performance Guidelines - Performance considerations and benchmarking strategies

🚀 Quick Start for Contributors

Understanding the Architecture

1. Compilation Pipeline - Learn the five-phase design (Lexer → Parser → Analysis → Comptime → Codegen)
2. Code Organization - Understand file structure and 800 LOC limits
3. AST Specification - Study the internal data structures

Implementation Details

4. Lexical Analysis - See how source code becomes tokens
5. Error Handling - Learn the comprehensive error system
6. Testing Strategy - Follow testing best practices

🏗️ Core Implementation Principles

The Phaser compiler follows these research-backed principles:

Code Quality Standards

• 800 LOC file limit - Based on software engineering research for optimal maintainability
• Interface-first design - Clear API boundaries between all components
• Zero external dependencies - Maintain simplicity and full control over the codebase
• Comprehensive testing - Every feature must have thorough test coverage

Architectural Principles

• Phase isolation - Strict separation between the five compilation phases
• WASM-first design - All phases can be compiled to WASM modules for modularity
• Capability-based security - Controlled access to system resources
• Error-first development - Test error conditions before success paths

Development Standards

• Local reasoning - Code should be understandable without distant context
• Explicit over implicit - All behavior should be clear and unambiguous
• Performance awareness - Monitor compilation speed and memory usage
• Documentation-driven - Specifications guide implementation

📁 Implementation Areas

Phase 1: Lexical Analysis

Status: 📋 Specification Complete, Implementation Needed

• Token recognition and classification
• Source position tracking
• Unicode handling and string parsing
• Error detection and recovery

Phase 2: Syntactic Analysis

Status: 📋 Specification Complete, Implementation Needed

• AST construction from token stream
• Grammar rule implementation
• Error recovery strategies
• Operator precedence handling

Phase 3: Semantic Analysis

Status: 📋 Specification Complete, Implementation Needed

• Name resolution and scope management
• Type checking and inference
• Borrow checking and lifetime analysis
• Symbol table construction

Phase 4: Compile-time Evaluation

Status: 📋 Specification Complete, Implementation Needed

• Constant expression evaluation
• Meta-programming execution in WASM sandbox
• Code generation from templates
• Resource limit enforcement

Phase 5: Code Generation

Status: 📋 Specification Complete, Implementation Needed

• LLVM IR generation
• Native assembly generation
• WASM module generation
• Optimization passes

🛠️ Development Environment

Prerequisites

• Rust (edition 2024) - Primary implementation language
• No external dependencies - By design for maximum control
• Standard tools - cargo, rustfmt, clippy for development

Build Commands

# Development
cargo run                    # Run the compiler
cargo test                   # Run all tests
cargo clippy                 # Linting
cargo fmt                    # Format code
 
# Validation
cargo check                  # Fast compile check
cargo test --lib            # Library tests only
cargo bench                  # Performance benchmarks

File Organization

src/
├── lib.rs              # Public API (< 200 LOC)
├── main.rs             # CLI driver (< 100 LOC)
├── common/             # Shared utilities
├── lexer/              # Phase 1: Lexical Analysis
├── parser/             # Phase 2: Syntactic Analysis
├── analysis/           # Phase 3: Semantic Analysis
├── comptime/           # Phase 4: Compile-time Evaluation
└── codegen/            # Phase 5: Code Generation

📋 Contributing Guidelines

Before Contributing

1. Read the relevant specifications for the area you’re working on
2. Understand the phase boundaries - don’t mix concerns between phases
3. Follow the 800 LOC limit - split large files appropriately
4. Write tests first - especially for error conditions

Code Standards

• Use PhaserResult<T> for all fallible operations
• Include source position information in all errors
• Implement From traits for error type conversions
• Follow Rust naming conventions consistently
• Document public APIs with /// comments

Testing Requirements

• Unit tests for each module and function
• Integration tests for phase interactions
• Error condition coverage - test all error paths
• Performance regression tests - monitor compilation speed

Pull Request Process

1. Open an issue to discuss significant changes
2. Follow established patterns when adding new functionality
3. Include comprehensive tests for all new code
4. Update documentation to reflect changes
5. Ensure CI passes - all tests, linting, and formatting

🎯 Contribution Areas

High Priority

• Core Infrastructure - Error handling, source management, phase interfaces
• Lexer Implementation - Token recognition and source position tracking
• Parser Implementation - AST construction and error recovery
• Basic Testing - Unit tests for implemented components

Medium Priority

• Semantic Analysis - Name resolution and type checking
• Error Diagnostics - Rich error messages with suggestions
• Integration Testing - End-to-end compilation tests
• Performance Benchmarks - Compilation speed measurements

Future Work

• Comptime Evaluation - WASM sandbox and meta-programming
• Code Generation - LLVM and native backends
• Optimization Passes - Performance improvements
• IDE Integration - Language server protocol support

🤝 Getting Help

• Check existing documentation - Most questions are answered in the specifications
• Open an issue for questions or clarifications about the design
• Follow established patterns when adding new functionality
• Ask before major changes - Discuss architectural changes in issues first

📊 Project Status

🚧 Active Development - The compiler is under active development.

Implementation Priority:

1. Core Infrastructure (In Progress) - Error handling, source management
2. Basic Pipeline (Next) - Lexer → Parser → Basic semantic analysis
3. Advanced Features (Future) - Full semantic analysis, comptime, codegen
4. Optimization (Future) - Performance tuning, incremental compilation

Current Focus:

• Establishing core infrastructure and interfaces
• Implementing the lexical analysis phase
• Building comprehensive test suites
• Creating development workflows and CI/CD

Welcome to the Phaser compiler project! Your contributions help build a powerful, safe, and efficient systems programming language.