Command Line Interface (CLI)

Relevant source files

The following files were used as context for generating this wiki page:

• jazz-next/README.md
• README.md
• jazz-hs/run.sh
• jazz-next/scripts/test-warning-config.sh
• jazz2/package.yaml
• jazz-hs/package.yaml

The Jazz Command Line Interface (CLI) serves as the primary entry point for interacting with the Jazz compiler and runtime. It provides developers with tools to compile source code, execute programs, and manage compiler configurations, specifically regarding warnings and error gating. The CLI architecture is designed to handle multiple implementation versions, though active development is centralized within the jazz-next path.

Sources: README.md:12-25, jazz-next/README.md:3-10

Architecture and Components

The CLI is structured into several functional layers that handle the transition from raw user input to compiled execution results. In the modern implementation (jazz-next), the CLI specifically manages flag resolution, environment variables, and configuration file parsing to determine compiler behavior.

CLI Module Structure

The active CLI implementation is located in src/JazzNext/CLI/Main.hs. This module is responsible for:

• Resolution: Determining the final configuration by merging inputs from the CLI flags, environment variables, and local config files.
• Compilation Driver: Invoking the Compiler.Driver to process source files.
• Output Management: Handling warning-aware output and diagnostic rendering.

Sources: jazz-next/README.md:16-27

Execution Flow

The following diagram illustrates how the CLI processes a request from the user to execute a Jazz program.

The flow shows the progression from CLI input through the internal compiler stages to the final execution result.
Sources: jazz-next/README.md:16-27, jazz-hs/run.sh:2-9

Configuration and Flag Resolution

The Jazz CLI employs a specific precedence model for resolving configuration tokens, particularly for compiler warnings (-W flags). The order of precedence is:

1. CLI Flags (Highest)
2. Environment Variables
3. Configuration Files
4. Defaults (Lowest)

Sources: jazz-next/README.md:18-19

Warning Management

The CLI supports granular control over diagnostics through the following components:

Component	Description	Source File
WarningConfig	Handles -W token parsing and the precedence merge logic.	jazz-next/src/JazzNext/Compiler/WarningConfig.hs
Warnings	Defines warning categories (e.g., W0001 for rebinding) and severity.	jazz-next/src/JazzNext/Compiler/Warnings.hs
Diagnostics	Manages the shape of warning payloads and deterministic sorting of output.	jazz-next/src/JazzNext/Compiler/Diagnostics.hs
Driver	Implements warning-as-error gating to halt compilation if specified thresholds are met.	jazz-next/src/JazzNext/Compiler/Driver.hs

Sources: jazz-next/README.md:17-27

Execution Environment and Prelude

The CLI automatically manages the inclusion of the "bundled-prelude." This allows common helper functions to be available without explicit imports by the user.

• Default Helpers: When running in CLI mode, jazz-next loads a prelude containing print!, map, filter, hd, and tl.
• Purity Enforcement: The CLI and driver enforce stub-v1 purity checks, preventing impure functions (denoted by !) from being called within pure binding bodies.

Sources: README.md:46-51, README.md:95-97

Shell Wrappers

The repository contains shell scripts that wrap the Haskell-based executables to simplify execution and testing.

# Example from jazz-hs/run.sh
COMPRES=$(stack exec jazz-exe $1)
if [ $? -eq 0 ] 
then 
  node -e $COMPRES
fi

This historical wrapper demonstrates the CLI's role in producing intermediate code (e.g., for Node.js) and immediately executing it.
Sources: jazz-hs/run.sh:2-9

Testing the Interface

The CLI and its configuration logic are verified through a suite of automated tests. This ensures that flag parsing and diagnostic rendering remain consistent.

Test Category	Target	Path
CLI Entrypoint	CLI flag and environment behavior	test/JazzNext/CLI/
Warning Config	Parsing and precedence logic	test/JazzNext/Compiler/Config/
Diagnostics	Metadata and rendering of errors	test/JazzNext/Compiler/Diagnostics/

Sources: jazz-next/README.md:31-38

Summary

The Jazz CLI is the central hub for the jazz-next compiler, managing a sophisticated configuration resolution system that prioritizes explicit user flags over environmental and default settings. It facilitates a streamlined development experience by automatically loading standard library helpers and providing deterministic, category-coded diagnostic feedback.

Sources: jazz-next/README.md:16-27, README.md:46-51