The jazz-next Workspace
Relevant source files
The following files were used as context for generating this wiki page:
The jazz-next workspace serves as the active, canonical compiler implementation path for the Jazz programming language. Unlike legacy directories such as jazz-hs/ and jazz2/, which are maintained as read-only historical and experimental references, jazz-next is the primary target for all net-new compiler behavior, including parser, analyzer, and codegen changes.
This workspace implements a functional language inspired by Elixir and Haskell, focusing on a simplified type system (avoiding category theory jargon), strong static typing, type inference, and immutable bindings. The implementation leverages a modular architecture in Haskell to handle everything from lexical analysis to warning-aware compilation results.
Sources: README.md:1-25, AGENTS.md:3-12, jazz-next/README.md:3-10
Compiler Architecture
The jazz-next compiler is organized into distinct implementation slices that handle the lifecycle of source code from parsing to diagnostic reporting.
Core Pipeline Components
The compilation process follows a standard front-end pipeline, moving from raw text to a lowered AST suitable for analysis and type inference.
| Component | Responsibility | Source Path |
|---|---|---|
| Lexer | Minimal tokenization for bootstrap | src/JazzNext/Compiler/Parser/Lexer.hs |
| Parser | Surface syntax parsing | src/JazzNext/Compiler/Parser.hs |
| Lowering | Transition from parse-AST to analyzer-AST | src/JazzNext/Compiler/Parser/Lower.hs |
| Analyzer | Scope analysis, rebinding warnings, and binding coherence | src/JazzNext/Compiler/Analyzer.hs |
| Inference | Type inference and semantic error plumbing | src/JazzNext/Compiler/TypeInference.hs |
| Driver | Execution gating and error propagation | src/JazzNext/Compiler/Driver.hs |
Sources: jazz-next/README.md:12-25
Data Flow Diagram
The following diagram illustrates the flow of data through the compiler components in the jazz-next workspace.
The diagram shows the linear progression from source to result, with side-car logic for warning configuration and diagnostic rendering.
Sources: jazz-next/README.md:12-25
Warning and Configuration System
A significant focus of the jazz-next implementation is a robust warning and diagnostic system. This system allows for fine-grained control over compiler feedback through CLI flags, environment variables, and configuration files.
Configuration Precedence
Warning configurations follow a specific merge precedence to determine the final behavior of the compiler:
- CLI Flags: Highest priority.
- Environment Variables: Overrides config and defaults.
- Config Files: Overrides system defaults.
- Default Settings: Baseline compiler behavior.
Sources: jazz-next/README.md:14-16
Diagnostic Logic
The system uses deterministic sorting for warnings and specific payload shapes defined in src/JazzNext/Compiler/Diagnostics.hs. The Analyzer is responsible for triggering specific warning codes, such as W0001 for scope-aware rebinding.
| Diagnostic Feature | Description | File Reference |
|---|---|---|
| Warning IDs | Unique identifiers for warning categories | Compiler/Warnings.hs |
| Deterministic Sorting | Ensures consistent output order | Compiler/Diagnostics.hs |
| Gating | Warnings-as-errors promotion logic | Compiler/Driver.hs |
Sources: jazz-next/README.md:13-26
Testing Infrastructure
The jazz-next workspace includes an extensive test suite executed via a custom test runner and a runghc wrapper.
Test Categories
Tests are categorized by the compiler layer they validate, located within the test/JazzNext/ directory:
- Semantics: Covers lambda semantics, purity (
!), if-expressions, and ADT patterns. - Modules: Validates prelude loading, module resolution, and the loader.
- Parser: Ensures operator fixity, sections, and surface syntax are correctly handled.
- CLI: Tests flag resolution and environment interaction.
Sources: jazz-next/README.md:28-40, jazz-next/scripts/test-warning-config.sh:11-37
Test Execution Flow
The test script iterates through a defined list of spec files (e.g., LambdaParserSpec.hs, PuritySemanticsSpec.hs) and executes them using the local source tree.
Sources: jazz-next/scripts/test-warning-config.sh:44-65
Governance and Implementation Rules
Development within the workspace is governed by a strict "Spec Authority" policy.
- Canonical Authority: The definitive language behavior is defined by
docs/spec/*and the implemented behavior/tests withinjazz-next/. - Read-Only Paths: Modification of
jazz2/orjazz-hs/is prohibited unless for legacy maintenance. - Change Control: Semantic changes require an RFC or decision record, while internal changes can be implementation-first if documentation and tests are updated simultaneously.
Sources: README.md:27-35, AGENTS.md:3-12, scripts/check-spec-authority.sh:30-34
Summary
The jazz-next workspace represents the future-facing evolution of the Jazz compiler. It transitions the project from legacy Haskell and experimental stubs to a modular, warning-aware, and strictly governed implementation. By centralizing the AST, analysis, and diagnostic logic, it provides a stable foundation for implementing planned features like ADTs, pattern matching, and the LLVM backend.
Sources: README.md:20-25, jazz-next/README.md:3-5