Jett

Jett is a general-purpose programming language designed from the ground up for LLM consumption, generation, and maintenance.

It is not an AI framework. It is a small, explicit, statically typed language whose syntax and semantics are shaped around the way coding agents read files, search code, apply patches, and recover from compiler feedback.

Why Jett Exists

Most programming languages were designed for humans typing into editors. Jett starts from a different premise: a growing share of code will be written, reviewed, and refactored by large language models and coding agents.

That changes the tradeoffs.

• One canonical form beats many clever shortcuts.
• Local context beats implicit global behavior.
• Explicit effects beat hidden side effects.
• Predictable syntax beats flexible syntax.
• Structured compiler errors beat prose diagnostics.
• Small, bounded functions beat sprawling control flow.

Jett is meant to feel pragmatic rather than academic: close in spirit to Go or Rust, with straightforward imperative code, strong static checking, explicit ownership/view semantics, and purity enforced through capability parameters.

Language Shape

namespace app

struct User:
    id: string serialize "userId"
    name: string
    token: secret[string]

function greeting(view user: User) returns string:
    return "hello, {user.name}"

function main(stdout: Stdout) returns nothing:
    User user = User(id: "u1", name: "Ada", token: "private")
    Stdout.write(view stdout, greeting(view user))

Core ideas already present in the implementation include:

• type-checked functions, structs, enums, interfaces, generics, and methods
• ownership analysis with view parameters and move tracking
• explicit capability parameters for impure operations
• result[T, E] and optional[T] handling with required handle blocks
• refinement types and compile-time verify / property blocks
• actors, structured concurrency, bitfields, closures, and pipelines
• comptime type reflection and reflected JSON serialization/parsing work
• a formatter, LSP server, and agent-oriented diagnostic output

Current Status

Jett is experimental, but the compiler front half is substantial.

• The lexer, parser, formatter, resolver, typechecker, ownership checker, comptime interpreter, runtime interpreter, CLI, fixture suite, and VS Code extension are working.
• jett build emits native executables through Cranelift on x86-64 Linux GNU and Windows MSVC. build --check validates source without an executable or runtime bundle.
• jett run executes programs through the tree-walking interpreter.
• jett test runs verify and property blocks.
• graphics.run can open a native 2D window through an explicit Graphics capability, with pure Jett state-update/render callbacks, rectangles, bitmap text, and keyboard input. The initial session API and its current limits are documented in the graphics contract.
• The standard library is partly Rust-backed and partly written in .jett; JSON uses trusted .jett bodies behind compiler-owned policy gates, while random and wall-clock effects use source-owned APIs with runtime-injected capabilities.
• json.parse[T] is the lenient compatibility parser, while json.parse_exact[T] rejects unknown object fields for closed contracts such as config files, protocols, and tests.
• Raw JSON uses the sole canonical json.JsonTree spelling. The former bare and namespaced JsonValue aliases are no longer supported.

See docs/progress.md for the detailed implementation matrix.

Quick Start

Build the compiler workspace:

cargo build

Run a sample Jett program:

cargo run -p jett_cli -- run tests/run_pass/hello_print.jett

Type-check a file:

cargo run -p jett_cli -- build --check tests/run_pass/hello_print.jett

Format a file:

cargo run -p jett_cli -- format tests/run_pass/hello_print.jett

Run the fixture suite:

cargo test -p jett_driver --test fixture_suite

Run the lower-level compiler tests:

cargo test -p jett_typecheck
cargo test -p jett_comptime

CLI

The main binary is jett.

jett format [--check] [--agent] <file.jett>
jett build [--check] [--release] [--agent] [--target <triple>] [-o <output>] [--runtime-bundle <manifest>] <file.jett>
jett run [--agent] <file.jett>
jett test [--agent] [file.jett]
jett bundle [--agent] --output <file.jett> [project-file-or-directory]
jett query [--agent] (--namespaces | --symbols <file> | --type-at <file:line:column> | --definition-at <file:line:column> | --references-at <file:line:column> | --complete-at <file:line:column> | --signature <namespace.function>)
jett lsp

format, build, run, test, bundle, and query accept --agent to emit structured TOON output that a coding agent can parse mechanically. query requires exactly one of the listed query options.

Package the compiler, stdlib, debug/release runtime archives, and dependency notices:

python3 tools/package_native.py --output target/package
python3 tools/smoke_native_package.py target/package
target/package/bin/jett build tests/run_pass/hello_print.jett

Native builds require the host C linker and SDK. Keep the package's bin and lib directories together when relocating it. The installed compiler never invokes Cargo. The default output is target/<host>/<debug|release>/<source-stem> (with .exe on Windows); -o selects another destination. --release optimizes code, rejects debug printing, and removes traces and breakpoint conditions. --target accepts only the current supported host triple; cross-compilation is not implemented.

--runtime-bundle or JETT_NATIVE_RUNTIME_BUNDLE can select an explicit launcher.json; the driver validates its compiler version, target, ABI, CRT, profile, and ordered system libraries. Stdlib discovery uses JETT_STDLIB_DIR when set, then the package's lib/jett/stdlib, then the development checkout.

Repository Layout

crates/
    jett_common        shared spans, file ids, and symbols
    jett_diagnostics   human and TOON diagnostics
    jett_lexer         tokenization and indentation handling
    jett_parser        current direct, source-spanned AST parser
    jett_ast           reserved future AST boundary (not yet implemented)
    jett_resolve       namespaces, imports, and name resolution
    jett_types         type representations and definitions
    jett_typecheck     type checking, ownership, capabilities, complexity limits
    jett_comptime      comptime interpreter, verify blocks, runtime interpreter
    jett_fmt           canonical formatter
    jett_driver        pipeline orchestration
    jett_lsp           editor integration
    jett_cli           command-line entry point
stdlib/                standard library .jett modules
tests/                 compile-pass, compile-fail, and run-pass fixtures
docs/                  design notes, architecture, and staging plans
editor/vscode/         VS Code extension

Design Documents

• Docs index
• Language design
• Compiler architecture
• Implementation progress
• Frontend syntax tree staging
• JsonValue to JsonTree transition
• JSON stdlib extraction plan
• Random capability and entropy contract
• Time and Clock capability contract

Development Notes

Useful commands while working on the compiler:

cargo fmt
cargo test -p jett_driver --test fixture_suite
cargo test -p jett_typecheck
cargo test -p jett_comptime

Compile-fail fixtures live in tests/compile_fail and assert specific diagnostics. Run-pass fixtures live in tests/run_pass and exercise interpreter behavior.

Private Resource native gates

The archive measurement helper builds fresh compiler-test runtimes and runs pinned Source execution gates. On Linux GNU, its default target measures the dynamic CRT. On Windows MSVC, use an x64 Visual Studio Developer PowerShell with link.exe on PATH and LLVM's llvm-nm and llvm-readobj installed:

python tools/measure_resource_native_archives.py prepare --target x86_64-pc-windows-msvc --nm llvm-nm --readobj llvm-readobj --linker link.exe --output target/native/private-resource
python tools/measure_resource_native_archives.py run --target x86_64-pc-windows-msvc --suite occupied-structs --reuse-target-dir --receipt RECEIPT_PATH --expected-sha256 MEASURED_DIGEST --target-dir target/native

Preparation returns the receipt path and measured digest. The MSVC path checks static CRT, exact runtime exports, compiler and linker identity, and the SDK LIB environment. The two occupied-struct gates use both fresh archive profiles; ordinary Runtime test counts do not establish their linked Source execution. Reusing the MSVC test target requires a newly compiled gate with that receipt pin. The default original suite retains the complete shared Source gate.

The language intentionally enforces function complexity limits. The current checker caps functions at 100 statements, nesting depth 4, and cyclomatic complexity 10.

License

The Cargo workspace declares this project as MIT licensed.