Semantic Analyzer
Relevant source files
The following files were used as context for generating this wiki page:
The Semantic Analyzer is a core component of the Jazz compiler, specifically residing within the active jazz-next/ implementation path. Its primary purpose is to perform scope-aware analysis and validation on the Abstract Syntax Tree (AST) after the initial parsing and lowering phases. It ensures that the source code adheres to the language's semantic rules, such as proper variable binding, signature coherence, and purity enforcement.
The analyzer acts as a bridge between the raw structural representation of the code and the type inference system, carrying forward warnings and semantic errors that are eventually used by the compiler driver to determine the success or failure of a compilation unit.
Sources: jazz-next/README.md:1-19, README.md:15-20, AGENTS.md:1-12
Architecture and Data Flow
The Semantic Analyzer operates within a multi-staged pipeline. It receives an analyzer-facing core AST from the lowering stage and outputs analyzed results that feed into the type inference and diagnostic systems.
Compiler Pipeline Integration
The analyzer follows the lowering boundary where the parse-surface AST is converted into a core AST suitable for deep analysis.
The flow demonstrates how the Semantic Analyzer consumes the core AST and propagates metadata (warnings and errors) to downstream components.
Sources: jazz-next/README.md:10-22
Components and Responsibilities
The analysis process is subdivided into specific modules within jazz-next/src/JazzNext/Compiler/:
| Component | Responsibility | Relevant File |
|---|---|---|
| AST Definitions | Provides the core AST used for semantic analysis. | AST.hs |
| Core Analyzer | Performs scope-aware rebinding analysis (W0001) and binding/signature coherence. | Analyzer.hs |
| Lowering | Converts surface AST to the analyzer-facing AST. | Lower.hs |
| Diagnostics | Defines warning payloads and ensures deterministic sorting. | Diagnostics.hs |
| Warning Config | Manages warning token parsing and precedence merging. | WarningConfig.hs |
Sources: jazz-next/README.md:10-22
Analysis Logic and Checks
The Semantic Analyzer implements several critical checks to ensure program correctness and safety.
Scope and Binding Analysis
The analyzer is "scope-aware," meaning it tracks variables as they are bound in different contexts. A key feature is the detection of rebinding (categorized as warning W0001), where a variable name is reused in a way that shadows or conflicts with an existing binding.
Signature Coherence
The analyzer validates the relationship between type signatures and their corresponding function bodies. This includes:
- Signature Adjacency: Ensuring that type signatures are correctly placed relative to the functions they describe.
- Unbound Variable Diagnostics: Identifying variables used in an expression that have no valid binding in the current scope.
Sources: jazz-next/README.md:18-20
Purity Enforcement
Jazz distinguishes between pure and impure functions. Impure functions are denoted with a ! suffix. The Semantic Analyzer implements "stub purity enforcement," which prevents direct calls to impure functions (callees) from within pure binding bodies.
This diagram illustrates the logic used to enforce functional purity during the analysis phase.
Sources: README.md:23-24, README.md:79-82
Configuration and Diagnostics
The analyzer's behavior is influenced by the compiler's warning configuration, which follows a specific precedence model for merging flags: CLI > env > config > default.
Warning Precedence
Warnings are parsed as -W tokens. The WarningConfig module handles the resolution of these flags. If a warning is elevated to an error (Warning-as-Error gating), the Driver module intercepts these and prevents the compilation from proceeding to code generation.
Metadata and Sorting
The analyzer produces diagnostic payloads that include metadata for rendering. To ensure consistent compiler behavior across runs, the Diagnostics module performs deterministic sorting of all warnings generated during the semantic analysis phase.
Sources: jazz-next/README.md:11-14, jazz-next/README.md:21-22, docs/spec/tooling/compiler-warning-flags.md
Conclusion
The Semantic Analyzer is the primary gatekeeper for language safety in Jazz. By integrating scope analysis, signature validation, and purity enforcement into a single cohesive phase within jazz-next/, it ensures that the core expression subset remains strongly and statically typed while providing clear diagnostics to the developer through the warning system.