Home
Relevant source files
The following files were used as context for generating this wiki page:
Jazz is a functional programming language heavily inspired by Elixir and Haskell. It aims to provide a category theory-free approach to typeclasses, replacing complex concepts like monads and semigroupoids with more standard structures such as Collection and Orderable. The project emphasizes strong, static typing and type inference for its core expression subset while maintaining developer-friendly syntax.
The repository follows a strict governance model where jazz-next/ serves as the active compiler implementation target. Legacy implementations, specifically jazz2/ and jazz-hs/, are maintained as read-only historical or experimental references and do not represent the normative behavior of the current language specification.
Sources: README.md:5-12, AGENTS.md:5-12, jazz-next/README.md:3-8
Project Architecture and Governance
The Jazz project is structured into distinct workspace slices, each serving a specific role in the language's evolution. Governance policies ensure that the normative authority of the language is anchored in the documentation and the active compiler path.
Workspace Hierarchy
| Component | Status | Purpose |
|---|---|---|
jazz-next/ | Active | Primary target for compiler implementation, including parser, analyzer, and codegen. |
docs/spec/ | Canonical | The normative source of truth for language behavior and specification. |
jazz2/ | Legacy/Experimental | Reference-only design source for future ideas; non-normative. |
jazz-hs/ | Legacy/Reference | Read-only historical reference evidence. |
The following diagram illustrates the authority and implementation flow within the repository:
The diagram shows that normative authority is derived from specifications and the jazz-next implementation, while legacy directories are isolated from active development.
Sources: README.md:31-38, AGENTS.md:5-12, scripts/check-spec-authority.sh:30-32
Language Features and Specification
Jazz implements a subset of functional programming features with a focus on immutability and type safety.
Implemented Functionality
- Type System: Strong, static typing with type inference for core expressions.
- Bindings: Support for immutable bindings.
- Functions: First-class, curried by default, with support for partial application.
- Runtime: A bundled prelude providing helpers like
map,filter,hd,tl, andprint!. - Syntax: Dot-terminated source forms and brace-bodied module declarations.
Purity and Side Effects
Jazz enforces a distinction between pure and impure functions. Impure functions must be denoted with a trailing ! (e.g., println!). Pure functions are prohibited from calling impure functions directly.
Purity is currently enforced via stub-v1 direct-call checks in the jazz-next compiler.
Sources: README.md:14-23, README.md:95-98
Active Compiler Implementation (jazz-next)
The jazz-next directory contains the modern compiler pipeline, organized into modular components.
Compiler Pipeline Stages
| Module | File Path | Responsibility |
|---|---|---|
| Lexer | src/JazzNext/Compiler/Parser/Lexer.hs | Minimal tokenization for parser bootstrap. |
| Parser | src/JazzNext/Compiler/Parser.hs | Surface parsing for current syntax slices. |
| Lowering | src/JazzNext/Compiler/Parser/Lower.hs | Converting Parse-AST to Analyzer-facing core AST. |
| Analyzer | src/JazzNext/Compiler/Analyzer.hs | Scope analysis, rebinding warnings (W0001), and signature coherence. |
| Inference | src/JazzNext/Compiler/TypeInference.hs | Plumbing for warnings and semantic errors during type checking. |
| Driver | src/JazzNext/Compiler/Driver.hs | Warning-as-error gating and result propagation. |
Development Utilities
The project includes automated scripts to maintain documentation integrity and specification authority. For instance, scripts/check-docs.sh verifies that the README.md and docs/feature-status.md are synchronized and meet the project's formatting requirements.
Sources: jazz-next/README.md:12-25, scripts/check-docs.sh:1-40
Dependency Management
The project utilizes Haskell's stack and hpack (package.yaml) for dependency management.
Core Dependencies
- Parsing:
megaparsec,parser-combinators. - Diagnostics:
diagnosefor rendering compiler errors and warnings. - Internal Data:
containers,text,lens,bifunctors. - Backend/Interface:
process,unix,haskeline.
Sources: jazz2/package.yaml:20-50, jazz-hs/package.yaml:18-45
Summary
The Jazz project provides a structured environment for developing a functional language that balances Haskell's power with Elixir's approachability. By enforcing a strict implementation path through jazz-next/ and maintaining a clear hierarchy of authority, the project ensures that development remains focused on the normative specification while preserving historical context in legacy directories.
Sources: README.md:31-38, AGENTS.md:5-15