Scripts & Automation
Relevant source files
The following files were used as context for generating this wiki page:
The Scripts & Automation system in the Jazz project provides a suite of validation and testing tools designed to ensure architectural integrity, documentation accuracy, and compiler correctness. These scripts enforce project governance policies, verify that the language specification remains the "source of truth," and automate the execution of the test suite for the active compiler implementation.
Automation is primarily handled through Bash scripts located in the root scripts/ directory and the jazz-next/scripts/ directory. These tools are critical for maintaining the project's "hybrid semantic-change workflow," where documentation and implementation must remain synchronized.
Sources: scripts/check-spec-authority.sh:35-41, README.md:27-35, jazz-next/README.md:1-5
Governance and Policy Enforcement
A core component of the automation suite is the enforcement of repository governance. Scripts ensure that the different compiler versions (jazz-hs, jazz2, and jazz-next) are correctly categorized and that no unsupported normative claims are made about legacy or reference code.
Spec Authority Validation
The check-spec-authority.sh script validates that the project's documentation correctly identifies the hierarchy of authority. It uses regular expressions to verify that:
jazz2is labeled as reference-only and non-normative.- The canonical authority is anchored to
docs/spec/andjazz-next/. - Semantic changes require an RFC or decision record.
Sources: scripts/check-spec-authority.sh:24-32, README.md:27-33
Documentation Consistency
The check-docs.sh script ensures that high-level project status remains accurate. It verifies the presence of specific section headings in the README.md and checks that the docs/feature-status.md file contains mandatory maintenance checklists and verification anchors.
Sources: scripts/check-docs.sh:24-42
The following diagram illustrates the documentation and policy validation flow:
The script specifically targets README.md, docs/feature-status.md, and docs/jazz-language-state.md to prevent documentation drift.
Sources: scripts/check-docs.sh:20-60
Specification Verification
The check-clarification-specs.sh script automates the validation of deep technical specifications. It ensures that every core language feature has a corresponding specification file with required architectural sections.
Required Specification Components
The script verifies that specific folders within docs/spec/ contain the necessary technical details:
| Specification Area | Required Sections |
|---|---|
| If Expressions | Surface Form, Desugaring, Typing Rules |
| Operators | Operator Table, AST Contract, Extensibility Model |
| Primitive Semantics | Contract Table, Equality Contract, Failure Model |
| Compiler Warnings | Categories/IDs, Precedence Rules, Migration Notes |
Sources: scripts/check-clarification-specs.sh:24-52
Compiler Testing Automation
Automation for the active compiler implementation (jazz-next) is handled via specialized test runners. These scripts manage the environment and dependencies required to execute Haskell-based tests.
Test Warning Configuration
The test-warning-config.sh script serves as the entry point for local jazz-next testing. It wraps runghc and ensures that the environment is correctly configured, specifically checking that the wrapper handles missing HOME variables without crashing.
Sources: jazz-next/scripts/test-warning-config.sh:3-56
Test Suite Organization
The testing automation targets a wide range of compiler components, including:
- Parser: Lambda, If-expression, and ADT pattern parsing.
- Semantics: Rebinding warnings, purity semantics, and type inference.
- Modules: Prelude loading and module resolution.
Sources: jazz-next/scripts/test-warning-config.sh:13-39, jazz-next/README.md:21-30
The following sequence diagram shows how the test runner interacts with the compiler source and test files:
The script uses a list of 25+ specific test files to ensure full coverage of the jazz-next compiler subset.
Sources: jazz-next/scripts/test-warning-config.sh:13-63
Summary of Automation Scripts
| Script Path | Purpose | Key Dependency |
|---|---|---|
scripts/check-docs.sh | Verifies documentation status and formatting | ripgrep (rg), prettier |
scripts/check-spec-authority.sh | Enforces governance and authority hierarchy | ripgrep (rg) |
scripts/check-clarification-specs.sh | Validates technical spec completeness | ripgrep (rg) |
jazz-next/scripts/test-warning-config.sh | Executes compiler test suite | runghc, bash |
Sources: scripts/check-docs.sh:1, scripts/check-spec-authority.sh:1, scripts/check-clarification-specs.sh:1, jazz-next/scripts/test-warning-config.sh:1
Conclusion
Scripts & Automation in Jazz are primarily focused on maintaining the integrity of the project's specifications and the correctness of the jazz-next implementation. By automating the verification of documentation patterns and enforcing a strict hierarchy of authority through shell scripts, the project ensures that development adheres to its established governance policies.