diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 120000 index 0000000..9602cb9 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +docs/src/CHANGELOG.md \ No newline at end of file diff --git a/docs/src/CHANGELOG.md b/docs/src/CHANGELOG.md new file mode 100644 index 0000000..c9f0fd4 --- /dev/null +++ b/docs/src/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## [Unreleased] + +### [0.1.0] - 2026-06-04 + +#### Added + +- Project model and module loading now reads Gleam project metadata, discovers modules, assigns + stable source IDs, and reports project graph diagnostics. +- Full Gleam syntax is represented in the compiler AST or rejected with targeted source-spanned + diagnostics for known limitations. +- Name resolution now uses Gleam-like namespaces across values, types, constructors, fields, + modules, imports, and project visibility checks. +- Type checking now records module interfaces, constructors, fields, generics, typed expressions, + and real-language pattern metadata for lowering. +- Runtime representation now documents and tests object headers, tags, alignment, strings, lists, + tuples, records, custom values, closures, managed pointers, and allocation helpers. +- Pattern matching now parses, resolves, type-checks, lowers, diagnoses, and emits the supported + scalar and structured pattern forms with explicit branch behavior. +- Core IR now represents module declarations, constants, managed value forms, function values, call + ABI metadata, structured control flow, failure paths, and stable debug output. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 3c1e46e..5db0da1 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -53,6 +53,7 @@ TODO: # Development - [Supported subset](internal/supported_subset.md) +- [Development changelog](CHANGELOG.md) - [Tests & Documentation](internal/testing_docs.md) # Internal Docs @@ -69,13 +70,6 @@ TODO: - [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) - [Tasks]() - - [Project model and modules](internal/tasks/01_project_model_and_modules.md) - - [Full Gleam syntax](internal/tasks/02_full_gleam_syntax.md) - - [Full name resolution](internal/tasks/03_full_name_resolution.md) - - [Gleam types and interfaces](internal/tasks/04_gleam_types_and_interfaces.md) - - [Runtime representation](internal/tasks/05_runtime_representation.md) - - [Pattern matching](internal/tasks/06_pattern_matching.md) - - [Core IR for real programs](internal/tasks/07_core_ir_for_real_programs.md) - [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) diff --git a/docs/src/internal/tasks/01_project_model_and_modules.md b/docs/src/internal/tasks/01_project_model_and_modules.md deleted file mode 100644 index ecc7e34..0000000 --- a/docs/src/internal/tasks/01_project_model_and_modules.md +++ /dev/null @@ -1,21 +0,0 @@ -# Project model and modules tasks - -## Goal - -Compile projects instead of only isolated source strings. - -## Tasks - -- [x] Read `gleam.toml` into a project configuration type. -- [x] Discover source files under project source directories. -- [x] Map source files to Gleam module names. -- [x] Assign stable source file IDs across a project. -- [x] Build a package/module graph for project modules. -- [x] Add dependency package metadata hooks. -- [x] Report duplicate modules and missing module files. -- [x] Keep single-file compilation available for tests. - -## Done when - -The compiler can load a small Gleam project and produce a module graph with -stable source IDs and useful project diagnostics. diff --git a/docs/src/internal/tasks/02_full_gleam_syntax.md b/docs/src/internal/tasks/02_full_gleam_syntax.md deleted file mode 100644 index 871b2c3..0000000 --- a/docs/src/internal/tasks/02_full_gleam_syntax.md +++ /dev/null @@ -1,23 +0,0 @@ -# Full Gleam syntax tasks - -## Goal - -Represent all tree-sitter Gleam syntax in the compiler AST. - -## Tasks - -- [x] Add AST nodes for constants, attributes, external declarations, type - aliases, and custom types. -- [x] Add AST nodes for records, tuples, lists, bit arrays, and record updates. -- [x] Add AST nodes for anonymous functions, pipelines, operators, `use`, - `panic`, `todo`, `assert`, and `let assert`. -- [x] Add AST nodes for full `case` syntax and guards. -- [x] Add AST nodes for all pattern forms. -- [x] Convert each supported tree-sitter node into AST. -- [x] Add diagnostics for malformed or unsupported grammar edge cases. -- [x] Add AST fixtures for each language construct. - -## Done when - -A valid Gleam module using any language syntax can be parsed into AST or produce -a targeted diagnostic for a known limitation. diff --git a/docs/src/internal/tasks/03_full_name_resolution.md b/docs/src/internal/tasks/03_full_name_resolution.md deleted file mode 100644 index 79b2fb7..0000000 --- a/docs/src/internal/tasks/03_full_name_resolution.md +++ /dev/null @@ -1,22 +0,0 @@ -# Full name resolution tasks - -## Goal - -Resolve all value, type, constructor, field, module, and imported names across a -project. - -## Tasks - -- [x] Split symbols into namespaces that match Gleam's rules. -- [x] Resolve qualified module references across project modules. -- [x] Resolve unqualified imports for values, types, and constructors. -- [x] Resolve prelude names. -- [x] Resolve custom type constructors and record fields. -- [x] Enforce visibility rules for public and private declarations. -- [x] Detect ambiguous imports and private-name access. -- [x] Add cross-module resolver fixtures. - -## Done when - -Every supported reference either resolves to a stable symbol ID or produces a -specific diagnostic with a source span. diff --git a/docs/src/internal/tasks/04_gleam_types_and_interfaces.md b/docs/src/internal/tasks/04_gleam_types_and_interfaces.md deleted file mode 100644 index 13f2936..0000000 --- a/docs/src/internal/tasks/04_gleam_types_and_interfaces.md +++ /dev/null @@ -1,21 +0,0 @@ -# Gleam types and interfaces tasks - -## Goal - -Provide full Gleam type information to lowering. - -## Tasks - -- [x] Define type data for tuples, lists, records, custom types, generics, and - opaque types. -- [x] Represent module interfaces, constructors, and fields. -- [x] Decide the official Gleam compiler interop format. -- [x] Import dependency module type information. -- [x] Type-check records, constructors, operators, guards, and patterns. -- [x] Preserve typed expression and declaration metadata for lowering. -- [x] Add tests for valid and invalid generic/custom-type programs. - -## Done when - -Typed data is available for real Gleam modules, including imported declarations -and custom types. diff --git a/docs/src/internal/tasks/05_runtime_representation.md b/docs/src/internal/tasks/05_runtime_representation.md deleted file mode 100644 index 1bca444..0000000 --- a/docs/src/internal/tasks/05_runtime_representation.md +++ /dev/null @@ -1,21 +0,0 @@ -# Runtime representation tasks - -## Goal - -Design and implement the in-memory representation for Gleam values in WASM. - -## Tasks - -- [x] Specify object headers, tags, and alignment. -- [x] Specify string encoding and layout. -- [x] Specify list, tuple, record, and custom-type layouts. -- [x] Specify closure and function-value representation. -- [x] Choose allocation and ownership or garbage-collection strategy. -- [x] Define the host ABI for managed values. -- [x] Implement runtime allocation helpers. -- [x] Add memory-layout tests in Wasmtime. - -## Done when - -The backend can allocate, pass, inspect, and return runtime-managed values using -a documented representation. diff --git a/docs/src/internal/tasks/06_pattern_matching.md b/docs/src/internal/tasks/06_pattern_matching.md deleted file mode 100644 index 8db1e5d..0000000 --- a/docs/src/internal/tasks/06_pattern_matching.md +++ /dev/null @@ -1,90 +0,0 @@ -# Pattern matching tasks - -## Goal - -Support full Gleam pattern matching through type checking, lowering, and code -generation. - -## Completed current subset - -- [x] Bind names introduced by variable patterns in `case` branches. -- [x] Preserve wildcard/discard patterns through lowering. -- [x] Parse scalar literal patterns, including `True`, `False`, and `Nil`. -- [x] Type-check scalar literal, variable, and discard patterns. -- [x] Type-check multiple-subject `case` pattern counts. -- [x] Lower supported `case` patterns into explicit IR branch clauses. -- [x] Represent pattern bindings in IR so branch bodies can read captured - values. -- [x] Emit WebAssembly control flow for scalar `case` expressions. -- [x] Emit WebAssembly local bindings for successful variable patterns. -- [x] Add Wasmtime tests for scalar branch fallthrough, bool patterns, and - captured pattern values. - -## Remaining full Gleam support - -### AST and parsing - -- [x] Replace raw executable pattern handling with explicit AST pattern nodes for - tuple, list, record, constructor, nested, spread/rest, and aliased patterns - where Gleam allows them. -- [x] Represent guards on case clauses with source spans. -- [x] Represent `let assert` as a pattern-bearing binding form, including its - failure semantics. -- [x] Preserve source spans for each pattern node, constructor name, field name, - and bound variable. -- [x] Add AST fixtures/snapshots for nested, constructor, record, list, tuple, - guard, multi-subject, and `let assert` patterns. - -### Name resolution - -- [x] Bind names introduced by tuple, list, record, constructor, nested, and - `let assert` patterns. -- [x] Resolve constructor names in patterns separately from variable bindings. -- [x] Resolve record fields used in record patterns. -- [x] Resolve qualified and imported constructors in patterns, including public - and private visibility checks. -- [x] Reject duplicate variable bindings in one pattern where Gleam disallows - them. -- [x] Ensure branch-local bindings are visible to the guard and branch body, but - not outside the branch. -- [x] Add resolver fixtures for shadowing, imported constructors, branch-local - names, and invalid duplicate bindings. - -### Type checking and diagnostics - -- [x] Type-check tuple patterns by arity and element type. -- [x] Type-check list patterns by element type, including empty lists and - spread/rest patterns where supported. -- [x] Type-check record patterns against record field metadata. -- [x] Type-check constructor patterns against constructor parameter metadata, - including imported constructors and generic custom types. -- [x] Type-check nested patterns recursively while preserving useful diagnostic - spans. -- [x] Type-check guards as `Bool` expressions. -- [x] Type-check `let assert` patterns and report impossible static matches - where possible. -- [x] Continue checking branch result compatibility after pattern checking. -- [x] Add exhaustiveness diagnostics for booleans, tuples, lists, and custom-type - constructors where the compiler can prove missing cases. -- [x] Add redundancy diagnostics for unreachable branches where the compiler can - prove a previous branch already covers the same values. -- [x] Treat guards conservatively so guarded branches do not incorrectly make a - match exhaustive. -- [x] Add diagnostic snapshots for invalid patterns, non-exhaustive matches, and - redundant branches. - -### Lowering and WebAssembly - -- [x] Lower supported scalar, alias, guard, multi-subject, and `let assert` - patterns into explicit matching IR. -- [x] Ensure lowered matching logic for supported patterns no longer depends on - Gleam pattern syntax. -- [x] Emit guard checks after structural pattern tests and before branch bodies. -- [x] Emit fallback code for non-matching branches and `let assert` failures. -- [x] Add Wasmtime tests for scalar alias patterns, guards, multi-subject - matches, and assertion failures. - -## Done when - -Supported patterns compile to explicit matching logic, and invalid patterns -produce source-spanned diagnostics. diff --git a/docs/src/internal/tasks/07_core_ir_for_real_programs.md b/docs/src/internal/tasks/07_core_ir_for_real_programs.md deleted file mode 100644 index d6a246f..0000000 --- a/docs/src/internal/tasks/07_core_ir_for_real_programs.md +++ /dev/null @@ -1,69 +0,0 @@ -# Core IR for real programs tasks - -## Goal - -Extend core IR so it can represent real Gleam programs and runtime-managed -values without depending on parser or resolver syntax details. - -## Tasks - -### Module structure and declarations - -- [x] Add IR support for constants and constant evaluation order. -- [x] Add module initialization for constants, static data, and runtime setup. -- [x] Represent imports, exports, and module-qualified references in a form the - backend can emit or reject with targeted diagnostics. -- [x] Represent public/private declaration metadata needed by build outputs and - debug dumps. -- [x] Preserve source spans for declarations, expressions, and generated failure - paths. - -### Values and representation types - -- [x] Add IR representation types for scalar values and heap-managed values. -- [x] Add IR forms for strings, tuples, lists, records, and custom-type - constructors. -- [x] Add IR forms for record field access and record updates. -- [x] Add IR forms for list construction, list deconstruction, and tuple element - access. -- [x] Add IR forms for equality and comparison operations, including runtime - equality calls for managed values. -- [x] Add explicit memory-operation forms needed by the WASM backend. - -### Functions and calls - -- [x] Add closure and function-value representation. -- [x] Add indirect-call support for function values. -- [x] Represent anonymous functions and captured variables. -- [x] Represent pipeline, `use`, labelled argument, and higher-order call - lowering once the type checker supplies enough metadata. -- [x] Add call ABI metadata for values crossing module or host boundaries. - -### Control flow and failures - -- [x] Add lowered pattern-matching control flow for all supported pattern forms. -- [x] Lower tuple, list, record, constructor, and nested managed-value patterns - once IR can construct and inspect those runtime values. -- [x] Represent guards, branch fallthrough, successful bindings, and failure - paths explicitly. -- [x] Represent `let assert`, `panic`, `todo`, and `assert` failure paths. -- [x] Represent blocks, sequencing, and evaluation order without relying on AST - statement shape. -- [x] Consider splitting high-level IR, lowered control-flow IR, and - WASM-oriented IR if one structure becomes too broad. - -### Testing and debug output - -- [x] Add deterministic IR snapshots for real-language fixtures. -- [x] Add fixtures that cover carried-forward syntax forms: records, tuples, - lists, custom types, constructors, pipelines, anonymous functions, guards, - and `let assert`. -- [x] Add diagnostics for typed constructs that still cannot lower, with spans - on the unsupported construct. -- [x] Keep IR debug output stable enough for contributor-facing snapshots. - -## Done when - -Typed Gleam modules lower to IR without depending on parser or name-resolution -syntax details, and every unsupported typed construct fails with a precise -source-spanned diagnostic.