Compiler Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Jazz compiler is a multi-stage system designed to transform high-level functional source code into executable form. It draws architectural inspiration from Elixir and Haskell, emphasizing strong static typing, type inference, and immutability. The project is currently transitioning to a new implementation phase, with all active development occurring within the jazz-next/ directory, while jazz-hs/ and jazz2/ are maintained as read-only historical and experimental references.
The architecture follows a standard pipeline: lexical analysis, parsing into a surface AST, lowering to a core AST, semantic analysis (including scope-aware rebinding and type inference), and eventually code generation. The current verified implementation supports core expression subsets, curried functions, and a bundled prelude for runtime operations like list manipulation and basic I/O.
Sources: README.md:3-33, jazz-next/README.md:1-10, AGENTS.md:3-15
Workspace Policy and Implementation Slices
The compiler workspace is strictly partitioned to separate legacy research from the active implementation target. jazz-next/ is the sole directory for net-new compiler behavior, including the parser, analyzer, and codegen.
Core Implementation Components
The jazz-next implementation is divided into modular slices, each responsible for a specific phase of the compilation or configuration process:
| Component | File Path | Description |
|---|---|---|
| Lexer | Lexer.hs | Minimal tokenization for parser bootstrap. |
| Parser | Parser.hs | Surface parser for current syntax slices (e.g., lambdas, if-expressions). |
| Surface AST | Parser/AST.hs | Represents the parse-surface structure of the code. |
| Lowering | Parser/Lower.hs | Boundary layer that converts Parse-AST to Analyzer-AST. |
| Core AST | AST.hs | Analyzer-facing core structure used after lowering. |
| Analyzer | Analyzer.hs | Handles scope-aware rebinding, binding/signature coherence, and diagnostics. |
| Type Inference | TypeInference.hs | Plumbs inference results, warnings, and semantic errors. |
| Driver | Driver.hs | Manages the compilation flow and warning-as-error gating. |
Sources: jazz-next/README.md:13-25, AGENTS.md:5-15
Compiler Pipeline Flow
The compilation process begins with raw source text and proceeds through several distinct stages of abstraction. The transition from the Parser to the Analyzer is bridged by a "Lowering" phase that simplifies surface syntax into a core representation suitable for type checking.
The diagram above illustrates the data flow from raw source input through the modular components of the jazz-next compiler.
Sources: jazz-next/README.md:13-25, jazz-next/scripts/test-warning-config.sh:11-45
Semantic Analysis and Diagnostics
The Analyzer is responsible for enforcing language rules beyond basic syntax. This includes binding/signature coherence (ensuring signatures are adjacent to their definitions) and unbound variable diagnostics.
Warning and Configuration System
The compiler features a sophisticated warning management system that resolves configurations based on a specific hierarchy of precedence: CLI > environment variables > config files > defaults.
- Warning Config: Handles
-Wtoken parsing and merging. - Diagnostics: Defines the payload shape for errors and ensures deterministic sorting of warnings.
- Purity Enforcement: The compiler performs stub-v1 purity enforcement, ensuring that impure functions (denoted with
!) cannot be called from pure functions.
Sources: jazz-next/README.md:14-23, README.md:112-115
Runtime and Prelude
The compiler architecture includes a bundled prelude loaded by default during CLI execution. This prelude provides essential functions that are not built directly into the compiler's core namespace, facilitating higher-level abstractions.
Provided Runtime Helpers
- List Operations:
map,filter,hd(head),tl(tail). - I/O:
print!. - Purity: Denoted by the
!suffix on functions that perform side effects or access external state.
Sources: README.md:41-45, README.md:112-118
Infrastructure and Governance
The project uses a structured script-based verification system to ensure documentation, spec authority, and compiler behavior remain synchronized.
The sequence above shows how automated scripts enforce the "Spec Authority" policy, which treats docs/spec/ and jazz-next/ as the canonical sources of truth.
Sources: scripts/check-docs.sh:1-40, scripts/check-spec-authority.sh:1-35, README.md:52-63
Summary
The Jazz compiler architecture emphasizes a clean separation between legacy research and active implementation within the jazz-next/ directory. By utilizing a modular pipeline of lexing, parsing, lowering, and semantic analysis, the system provides a robust framework for implementing functional language features like type inference and currying. The integration of a strictly ordered configuration hierarchy and a comprehensive diagnostic system ensures that the compiler is both flexible for developers and deterministic in its output.
Sources: jazz-next/README.md:13-25, README.md:52-63