Docs / Codebase documentation

Codebase documentation

This part of the documentation is for maintainers or anyone curious about the internal structure of Moth's compiler and build system.

It provides a peek behind the curtain at how Moth works under the hood.

Explore the codebase

• Compiler design: staged pipeline, task-reading matrix and cross-cutting contracts
• Memory management: reference semantics, borrow validation, lifetime regions, ownership and backend lowering
• Codebase development standards: implementation style, test strategy and validation gates
• Design scope: accepted mechanisms, constraints and intentionally excluded complexity
• Compiler-facing language reference: bridge to the canonical language overview
• Progress matrix: current implementation status and known gaps
• Roadmap: planned work and design direction
• Repository index: quick module and file locator

Compiler flow

            project files
                -> Stage 0: project structure and source discovery
                -> Stage 1: tokenization
                -> Stage 2: header parsing
                -> Stage 3: dependency sorting
                -> Stage 4: AST construction
                -> Stage 5: HIR generation
                -> Stage 6: borrow validation
                -> lifetime-region and escape validation
                -> build-owned link planning and backend lowering
                -> output files
        

Design docs vs current support

Codebase pages describe accepted end-state architecture. Some pages define design that the compiler and backends are still converging on.

Use the progress matrix to see what is implemented, partial, experimental or still missing. Use the roadmap for sequencing and proposals not yet accepted as design.