# Loom

> Loom is a programming language for safe-by-construction software, implemented in Rust. Every function is a `recipe` that declares its dependencies, return type, failure modes, effects, and scaling properties — the compiler verifies them statically, so runtime surprises are caught at build time. A single `.loom` file compiles to Rust, TypeScript, Go, or WebAssembly, and `loom exec` drives the full Loom → Rust → rustc → run pipeline with content-addressed caching.

Loom is a single-repo Rust project (no workspaces). The compiler has five phases — lexer, parser, bidirectional type checker, effect verifier, and codegen — each isolated in its own module under `src/`. There is no `cargo` dependency in the emitted code: the Rust backend produces a self-contained `.rs` file that `rustc --edition 2021` compiles in one shot. The same AST feeds four codegen backends (Rust / TypeScript / Go / WASM) that share refinement-validation semantics at the dispatcher boundary.

Installs from crates.io with `cargo install --lock loom-lang` — the crate name is `loom-lang` (the short `loom` name was taken) but the binary is `loom`. See `Cargo.toml` for the `[package]` / `[[bin]]` split.

Key conventions any LLM editing this repo should follow:

- Rust 2021, `cargo fmt` + `cargo clippy -- -D warnings` must be clean before commit.
- `miette` is used for every user-facing error. New diagnostics must carry spans.
- Tests live in `src/**/mod tests` (unit) and `tests/integration.rs` (integration). Target 80%+ line coverage; 247 tests currently pass (206 unit + 41 integration).
- No new Rust dependencies without a strong justification — the compiler binary intentionally has a small crate graph.
- The generated code (every backend) stays zero-dependency.

## Docs

- [README](README.md): Full language tour — `recipe` syntax, refinement/sum/record types, effect rows, modes, pattern matching, modules, protocols, concurrency, the whole CLI, and `loom build` target matrix.
- [docs/exec-pipeline.md](docs/exec-pipeline.md): Deep dive on the `loom exec` utility — the three-stage Loom → Rust → rustc → run pipeline, caching model, failure modes, and example transcripts.

## Source layout

- [src/main.rs](src/main.rs): CLI dispatcher. Entry point for every `loom <command>`. The `exec` arm (lines 172-277) implements the full compile-and-run pipeline with FNV-1a cache lookup.
- [src/lexer.rs](src/lexer.rs): Phase 1 — `logos`-based tokenizer. Contextual keywords (`channel`, `race`, `all`, `import`) are handled here.
- [src/ast.rs](src/ast.rs): AST node definitions shared across all phases.
- [src/parser.rs](src/parser.rs): Phase 2 — recursive-descent parser with error recovery via `MultipleErrors`.
- [src/typecheck.rs](src/typecheck.rs): Phase 3 — bidirectional type checker with inference, refinement narrowing, match exhaustiveness, and Levenshtein "did you mean" suggestions.
- [src/effects.rs](src/effects.rs): Phase 4 — effect row inference and verification. Merges `IO`, `Async`, `Fail<E>`, `Mut<S>`, `Rand`, `Time`.
- [src/codegen.rs](src/codegen.rs): Phase 5a — Rust code generation. Emits self-contained `.rs` with embedded stdlib, `LoomError`, `LoomChannel<T>`, protocol HTTP server, and the argv dispatcher used by `loom exec`.
- [src/codegen_ts.rs](src/codegen_ts.rs): Phase 5b — TypeScript backend (Node strip-only types).
- [src/codegen_go.rs](src/codegen_go.rs): Phase 5c — Go backend (goroutines + channels).
- [src/codegen_wasm.rs](src/codegen_wasm.rs): Phase 5d — WebAssembly Text (WAT) backend for the arithmetic subset.
- [src/modules.rs](src/modules.rs): Module loader. Resolves `import "..."` statements, detects cycles, consults the manifest for named-package imports.
- [src/manifest.rs](src/manifest.rs): `loom.json` package manifest + semver `VersionConstraint` (`Any`, `Exact`, `Caret`, `Tilde`, `GreaterEq`).
- [src/lockfile.rs](src/lockfile.rs): `loom.lock` writer/reader with schema versioning.
- [src/registry.rs](src/registry.rs): Remote dependency fetcher. Shells out to `curl`, caches under `.loom/deps/<url-hash>/`.
- [src/cache.rs](src/cache.rs): FNV-1a content-addressed compile cache used by `loom exec`.
- [src/json.rs](src/json.rs): Hand-rolled JSON parser (avoids a `serde_json` dependency).
- [src/lsp.rs](src/lsp.rs): Language server — JSON-RPC over stdio, `textDocument/didOpen|didChange`, diagnostics downcast from miette.
- [src/source_map.rs](src/source_map.rs): Byte-offset → (line, UTF-16 character) for LSP positions.
- [src/diagnostic.rs](src/diagnostic.rs): `Diagnostic` + `Severity` with LSP codes.
- [src/fmt.rs](src/fmt.rs): Canonical formatter (idempotent).

## Examples

- [examples/01_hello.loom](examples/01_hello.loom): Pure recipes, no side effects.
- [examples/02_types.loom](examples/02_types.loom): Refinement, sum, and record types.
- [examples/03_effects.loom](examples/03_effects.loom): `needs:`, `await`, `may fail with:`, `handle` blocks.
- [examples/04_full.loom](examples/04_full.loom): Committed recipe (`recipe!`), protocol, traces, scales.
- [examples/05_exec.loom](examples/05_exec.loom): Executable primitives — math, factorial, port validation.
- [examples/06_refinement_exec.loom](examples/06_refinement_exec.loom): Refinement runtime validation via `loom exec`.
- [examples/07_tests.loom](examples/07_tests.loom): `test_*` recipes driven by `loom test`.
- [examples/08_spawn.loom](examples/08_spawn.loom): `spawn { expr }` → `thread::spawn`.
- [examples/09_concurrency.loom](examples/09_concurrency.loom): `race` / `all` combinators.
- [examples/10_protocol_server.loom](examples/10_protocol_server.loom): Schema-first HTTP server via `protocol`.
- [examples/11_channel.loom](examples/11_channel.loom): `channel()` / `send` / `recv` over `LoomChannel<T>`.
- [examples/12_builtins.loom](examples/12_builtins.loom): Stdlib composition — `println`, `toString`, `abs`, `max`, `min`.
- [examples/13_fibonacci.loom](examples/13_fibonacci.loom): Recursion (`fib`, `gcd`, `power`) behind a `NonNeg` refinement.
- [examples/14_pipeline.loom](examples/14_pipeline.loom): Channel pipeline + fan-in with helper recipes for single-expression spawn bodies.
- [examples/15_refinements.loom](examples/15_refinements.loom): Layered refinements (`Score`, `Age`) with dispatcher-boundary validation and `min`/`max` clamping.
- [examples/modules/analytics.loom](examples/modules/analytics.loom): Three-level import chain (`analytics → geometry → math`) demonstrating diamond dedup.

## Tests

- [tests/integration.rs](tests/integration.rs): 41 integration tests covering `exec`, `fmt`, `test`, `lsp`, HTTP server, package manager, lockfile drift, compilation cache, and the Rust/TS/Go/WASM backends.

## Optional

- [Cargo.toml](Cargo.toml): Binary crate manifest — keep the dep list short (`logos`, `miette`, `thiserror`).
- [.gitignore](.gitignore): Covers `target/`, `.loom/`, editor junk.
- [examples/modules/](examples/modules): Transitive-import demo for `loom exec`.
- [examples/packages/](examples/packages): `loom.json` / `loom.lock` demo for the package manager.
