diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 9683202..892fecb 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -67,9 +67,13 @@ TODO: - [Pattern matching](internal/specs/06_pattern_matching.md) - [Core IR for real programs](internal/specs/07_core_ir_for_real_programs.md) - [WASM backend and runtime](internal/specs/08_wasm_backend_and_runtime.md) - - [Standard library and host interop](internal/specs/09_stdlib_and_host_interop.md) - - [CLI and build outputs](internal/specs/10_cli_and_build_outputs.md) + - [Gleam language completeness](internal/specs/09_gleam_language_completeness.md) + - [WASM backend completeness](internal/specs/10_wasm_backend_completeness.md) + - [Standard library and host interop](internal/specs/11_stdlib_and_host_interop.md) + - [CLI and build outputs](internal/specs/12_cli_and_build_outputs.md) - [Tasks]() - [WASM backend and runtime](internal/tasks/08_wasm_backend_and_runtime.md) - - [Standard library and host interop](internal/tasks/09_stdlib_and_host_interop.md) - - [CLI and build outputs](internal/tasks/10_cli_and_build_outputs.md) + - [Gleam language completeness](internal/tasks/09_gleam_language_completeness.md) + - [WASM backend completeness](internal/tasks/10_wasm_backend_completeness.md) + - [Standard library and host interop](internal/tasks/11_stdlib_and_host_interop.md) + - [CLI and build outputs](internal/tasks/12_cli_and_build_outputs.md) diff --git a/docs/src/internal/specs/09_gleam_language_completeness.md b/docs/src/internal/specs/09_gleam_language_completeness.md new file mode 100644 index 0000000..5b08cc4 --- /dev/null +++ b/docs/src/internal/specs/09_gleam_language_completeness.md @@ -0,0 +1,82 @@ +# Gleam language completeness + +The compiler should eventually accept and compile the whole Gleam language, not +only the current experimental subset. Completeness means every language feature +has a documented path through parsing, AST construction, resolution, type +checking, lowering, code generation, and diagnostics. + +## Scope + +This spec covers language semantics before target-specific code generation. The +WASM-specific requirements are in +[WASM backend completeness](./10_wasm_backend_completeness.md). + +## Syntax and declarations + +The compiler should provide structured AST and semantic support for: + +- modules, imports, aliases, and unqualified imports +- public and private functions +- constants +- custom types, opaque types, constructors, and record fields +- type aliases and external types +- external functions and target-specific declarations +- attributes, documentation comments, and deprecation metadata +- all expression and pattern forms accepted by Gleam + +Raw syntax can remain a temporary parser escape hatch, but executable language +features should not depend on raw text parsing in later phases. + +## Name resolution + +Resolution should match Gleam module rules for: + +- values, types, constructors, fields, modules, and labels +- qualified and unqualified imports +- aliases and shadowing +- public, private, and opaque module boundaries +- dependency package modules and package interfaces +- prelude names and generated names + +Unknown, private, duplicate, and ambiguous names should produce source-spanned +diagnostics. + +## Type checking + +The type layer should support Gleam's full type system: + +- local and top-level type inference +- generic functions and generic custom types +- function types, anonymous functions, and captures +- tuples, lists, records, bit arrays, strings, and numbers +- constructor calls, labeled fields, and record updates +- modules interfaces, opaque types, and imported types +- operators, guards, pipelines, `use`, `panic`, `todo`, and `assert` +- pattern typing and branch result compatibility + +The compiler may import type information from the official Gleam compiler where +that is more reliable than reimplementing all inference rules locally. + +## Pattern matching + +All pattern forms should be represented, typed, and lowered explicitly: + +- literals, discards, variables, aliases, and nested patterns +- tuple, list, record, constructor, and bit-string patterns +- multiple subjects and guards +- `let assert` patterns + +The compiler should report impossible, unreachable, redundant, and +non-exhaustive patterns where practical. + +## Lowering contract + +Lowering should receive typed, resolved syntax and produce IR that no longer +requires Gleam-specific parsing decisions. Evaluation order, scopes, captures, +pattern bindings, failure paths, and module initialization should be explicit. + +## Done when + +A project using the complete Gleam language can be compiled through typed IR, +and unsupported target behavior is reported as a target/backend limitation rather +than a missing language feature. diff --git a/docs/src/internal/specs/10_wasm_backend_completeness.md b/docs/src/internal/specs/10_wasm_backend_completeness.md new file mode 100644 index 0000000..bf5feaa --- /dev/null +++ b/docs/src/internal/specs/10_wasm_backend_completeness.md @@ -0,0 +1,77 @@ +# WASM backend completeness + +The WASM backend should support every typed IR form needed by complete Gleam +programs. Backend completeness means any program accepted by the language phases +can either be emitted as valid WebAssembly for the selected target, or rejected +with a precise target/ABI diagnostic. + +## Scope + +This spec covers target representation, runtime support, imports, exports, and +WebAssembly emission. Language semantics before code generation are covered in +[Gleam language completeness](./09_gleam_language_completeness.md). + +## Value representation + +The backend must define and implement WASM representations for: + +- integers, floats, bools, nil, and ordering values +- strings and UTF-8 data +- bit arrays and segment operations +- lists, tuples, records, and custom types +- results, options, errors, and panic values +- function values, closures, captures, and indirect calls +- opaque and dependency-defined runtime values + +Managed values should use the documented runtime object layout unless a later +representation replaces it with an equivalent contract. + +## Runtime operations + +The runtime should provide allocation, access, and helper operations for: + +- string creation, comparison, concatenation, and inspection +- bit-array construction, append, slicing, and pattern matching +- list construction, traversal, equality, and deconstruction +- tuple, record, and custom-type field access +- closure allocation and invocation +- structural equality and ordering where Gleam requires them +- panic, todo, assert, and pattern-match failure paths +- debug rendering for arbitrary values + +## Control flow and calls + +Code generation should emit deterministic WASM for: + +- blocks, lets, assignments to locals, and module initialization +- branches, guards, and lowered pattern matching +- direct calls, imported calls, exported calls, and indirect calls +- tail-position calls where useful, without changing semantics +- all operators and short-circuiting boolean expressions + +## Imports, exports, and ABI + +The backend must define target-specific ABI rules for: + +- module exports +- module imports +- host imports +- scalar and managed values crossing boundaries +- ownership and lifetime of managed values +- adapters for ABI shapes that raw WASM cannot express directly + +Targets should include Wasmtime first, then browser and WASI support when their +host interfaces are defined. + +## Validation + +Every emitted module should assemble and validate as WebAssembly. Tests should +cover WAT snapshots, Wasmtime execution, memory-layout inspection, import/export +ABI checks, runtime helper behavior, and diagnostics for unsupported target +combinations. + +## Done when + +Any typed IR produced for supported Gleam language features can be emitted and +run for the selected WASM target, or fails before assembly with a clear +source-spanned backend or ABI diagnostic. diff --git a/docs/src/internal/specs/09_stdlib_and_host_interop.md b/docs/src/internal/specs/11_stdlib_and_host_interop.md similarity index 100% rename from docs/src/internal/specs/09_stdlib_and_host_interop.md rename to docs/src/internal/specs/11_stdlib_and_host_interop.md diff --git a/docs/src/internal/specs/10_cli_and_build_outputs.md b/docs/src/internal/specs/12_cli_and_build_outputs.md similarity index 100% rename from docs/src/internal/specs/10_cli_and_build_outputs.md rename to docs/src/internal/specs/12_cli_and_build_outputs.md diff --git a/docs/src/internal/tasks/09_gleam_language_completeness.md b/docs/src/internal/tasks/09_gleam_language_completeness.md new file mode 100644 index 0000000..f5513e3 --- /dev/null +++ b/docs/src/internal/tasks/09_gleam_language_completeness.md @@ -0,0 +1,60 @@ +# Gleam language completeness tasks + +## Goal + +Compile the complete Gleam language through typed IR, independent of any single +backend target. + +## Tasks + +### Syntax and AST + +- [ ] Replace raw executable syntax with structured AST nodes. +- [ ] Add structured constants, attributes, externals, target groups, and docs. +- [ ] Add structured operators, pipelines, `use`, anonymous functions, and + captures. +- [ ] Add structured record construction, record updates, tuples, lists, and bit + arrays. +- [ ] Preserve spans and source order for every new AST node. + +### Resolution + +- [ ] Resolve all value, type, constructor, field, module, and label names. +- [ ] Resolve aliases, unqualified imports, dependency modules, and prelude + names according to Gleam rules. +- [ ] Enforce public, private, and opaque module boundaries. +- [ ] Load dependency package interfaces or official compiler metadata. +- [ ] Add diagnostics for unknown, duplicate, private, and ambiguous names. + +### Type checking + +- [ ] Implement or import full local and top-level type inference. +- [ ] Type-check generic functions and generic custom types. +- [ ] Type-check records, updates, labels, constructors, tuples, lists, strings, + bit arrays, functions, captures, and operators. +- [ ] Type-check pipelines, `use`, guards, `panic`, `todo`, `assert`, and + `let assert`. +- [ ] Type-check imported functions, types, constructors, and opaque values. +- [ ] Preserve complete module interfaces for downstream phases. + +### Pattern matching + +- [ ] Support all pattern forms in AST, resolver, type checker, and lowering. +- [ ] Lower patterns into explicit decision logic or match IR. +- [ ] Bind names from nested patterns, aliases, records, lists, and bit strings. +- [ ] Add exhaustiveness, unreachable branch, and redundant pattern diagnostics + where practical. + +### Lowering + +- [ ] Lower every typed expression into compiler IR. +- [ ] Make evaluation order, captures, scopes, failure paths, and initialization + explicit. +- [ ] Represent module constants, module initialization, and dependency calls. +- [ ] Reject only target/backend limitations after language lowering succeeds. + +## Done when + +A complete Gleam program can be parsed, resolved, type-checked, and lowered to +IR without relying on raw executable syntax or ad-hoc stdlib tables for language +semantics. diff --git a/docs/src/internal/tasks/10_wasm_backend_completeness.md b/docs/src/internal/tasks/10_wasm_backend_completeness.md new file mode 100644 index 0000000..15a7087 --- /dev/null +++ b/docs/src/internal/tasks/10_wasm_backend_completeness.md @@ -0,0 +1,59 @@ +# WASM backend completeness tasks + +## Goal + +Emit and run valid WebAssembly for every typed IR form produced by complete +Gleam language support. + +## Tasks + +### Value representation + +- [ ] Define final WASM representations for all scalar and managed Gleam values. +- [ ] Support strings, bit arrays, lists, tuples, records, custom types, + closures, opaque values, results, options, errors, and panics. +- [ ] Document memory layout, tags, alignment, ownership, and lifetime rules. +- [ ] Add layout tests for every managed value kind. + +### Runtime helpers + +- [ ] Implement dynamic allocation for all managed values. +- [ ] Implement string helpers, including comparison, concatenation, and + inspection. +- [ ] Implement bit-array helpers for construction, append, slicing, and + matching. +- [ ] Implement list, tuple, record, custom-type, closure, equality, ordering, + panic, assertion, and debug helpers. +- [ ] Ensure runtime helpers are deterministic and target-independent where + possible. + +### Code generation + +- [ ] Emit every IR expression and instruction form. +- [ ] Emit branches, guards, lowered patterns, and failure paths. +- [ ] Emit all operators and short-circuiting boolean expressions. +- [ ] Emit direct calls, imported calls, exported calls, indirect calls, and + closure calls. +- [ ] Emit module constants and module initialization in dependency order. + +### Imports, exports, and targets + +- [ ] Define ABI rules for module exports, module imports, and host imports. +- [ ] Add adapters for ABI shapes that raw WASM cannot express directly. +- [ ] Define Wasmtime, browser, and WASI target host interfaces. +- [ ] Diagnose unsupported target/function/type combinations before assembly. +- [ ] Keep generated WAT and Wasm deterministic for tests. + +### Validation + +- [ ] Add WAT snapshots for all backend forms. +- [ ] Add Wasmtime execution tests for scalar, managed, control-flow, closure, + import, and export behavior. +- [ ] Add memory inspection tests for dynamic and static objects. +- [ ] Add diagnostics tests for unsupported ABI and target combinations. + +## Done when + +Every typed IR form from supported Gleam programs either emits valid WebAssembly +and runs for the selected target, or fails with a source-spanned backend or ABI +diagnostic before WAT assembly. diff --git a/docs/src/internal/tasks/09_stdlib_and_host_interop.md b/docs/src/internal/tasks/11_stdlib_and_host_interop.md similarity index 100% rename from docs/src/internal/tasks/09_stdlib_and_host_interop.md rename to docs/src/internal/tasks/11_stdlib_and_host_interop.md diff --git a/docs/src/internal/tasks/10_cli_and_build_outputs.md b/docs/src/internal/tasks/12_cli_and_build_outputs.md similarity index 100% rename from docs/src/internal/tasks/10_cli_and_build_outputs.md rename to docs/src/internal/tasks/12_cli_and_build_outputs.md