Merge pull request #254 from nikomatsakis/main

latest round of changes

Author: nikomatsakis

CLAUDE.md

@@ -0,0 +1,133 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Dada is an experimental programming language that explores what a Rust-like language would look like if designed to feel more like Java/JavaScript rather than C++. It's async-first, uses a permission-based ownership system, and compiles to WebAssembly.
+
+## Development Commands
+
+### Basic Commands
+- `cargo run -- compile <file.dada>` - Compile a Dada source file
+- `cargo run -- run <file.dada>` - Compile and execute a Dada program  
+- `cargo run -- test [files]` - Run test suite on specific Dada files
+- `cargo run -- debug <file.dada>` - Compile with debug server for introspection
+
+### Testing
+- `just test` - Run all tests across the workspace (equivalent to `cargo test --all --workspace --all-targets`)
+- `cargo test` - Run Rust unit tests
+- Test files are in `tests/` directory with `.dada` extension
+
+### Build Tools
+- `cargo xtask build` - Custom build tasks
+- `cargo xtask deploy` - Deployment automation
+
+## Architecture
+
+The compiler is built as a Cargo workspace with these key components:
+
+### Core Pipeline (in compilation order)
+1. **`dada-parser`** - Lexing/parsing source to AST
+2. **`dada-ir-ast`** - AST representation and diagnostics  
+3. **`dada-ir-sym`** - Symbolic IR (type-checked, high-level representation)
+4. **`dada-check`** - Type checking and semantic analysis
+5. **`dada-codegen`** - WebAssembly code generation (currently incomplete)
+
+### Supporting Components
+- **`dada-lang`** - Main CLI entry point
+- **`dada-compiler`** - Compilation orchestration and VFS
+- **`dada-debug`** - Debug server for compiler introspection
+- **`dada-lsp-server`** - Language Server Protocol implementation
+- **`dada-util`** - Shared utilities (arena allocation, logging, etc.)
+
+### Key Design Patterns
+- **Salsa-based**: Uses incremental, memoized computation framework
+- **Database pattern**: Central `Db` trait for accessing compiler state
+- **Async architecture**: Built around async/await throughout
+
+## Current Status & Constraints
+
+- **Early development**: Core language features implemented but not production-ready
+- **Codegen limitations**: Most test files have `#:skip_codegen` as WASM generation is incomplete
+- **Active experimentation**: Language design still evolving (see `tests/spikes/` for experimental features)
+
+## Language Characteristics
+
+- **Async-first**: Functions are async by default
+- **Permission system**: Uses ownership annotations (`my`, `our`, `mut`) for memory management
+- **Classes and structs**: Both reference types (classes) and value types (structs)
+- **Rust-inspired**: Similar memory safety guarantees with more accessible syntax
+- **Comments**: Use `#` not `//`
+
+## Test File Structure
+
+- `tests/parser/` - Parser tests
+- `tests/symbols/` - Symbol resolution tests  
+- `tests/type_check/` - Type checking tests
+- `tests/spikes/` - Experimental language features
+- `tests/default_perms/` - Default permission inference tests
+
+Test files use `.dada` extension and often include `#:skip_codegen` directives.
+
+## Documentation
+
+The compiler uses rustdoc for comprehensive documentation. Major documentation files:
+
+### Generation Commands
+- `just doc` - Generate docs for all crates (recommended)
+- `just doc-open` - Generate and open docs in browser
+- `just doc-serve` - Generate docs and serve locally at http://localhost:8000
+- `cargo doc --workspace --no-deps --document-private-items` - Manual command equivalent to `just doc`
+
+### Documentation Structure
+- **`dada-lang`** - Main landing page and compiler overview
+- **`dada-ir-sym`** - Core type system and symbolic IR documentation
+- **`dada-check`** - Type checking orchestration
+- **Individual modules** - Detailed documentation embedded in source
+
+### Documentation Files
+- `components/*/docs/*.md` - Extended documentation included via `include_str!`
+- Inline module docs using `//!` comments
+- Cross-references using `[`item`]` syntax for automatic linking
+
+Major documentation sections:
+- **Type Checking Pipeline** - Overview of the checking process
+- **Permission System** - Detailed guide to Dada's ownership model  
+- **Type Inference** - How Hindley-Milner inference works in Dada
+- **Subtyping** - Type relationships and conversions
+
+### Documentation Guidelines
+
+#### Cross-Crate Links
+- Use `[text](../crate_name)` format for linking to sibling crates (regular markdown links)
+- Avoid bare `[crate_name]` links that rely on implicit resolution
+
+#### Intra-Crate Links  
+- Use `[item](`path::to::item`)` format with backticks around the path (rustdoc links)
+- For private items, use `pub(crate)` visibility when the item needs to be documented
+- Prefer concrete method names over non-existent placeholder methods
+- Examples: `[MyStruct](`crate::module::MyStruct`)`, `[method](`Self::method_name`)`
+
+#### Code Blocks
+- Always specify language: ```rust, ```text, ```bash, etc.
+- Use ```text for error messages, command output, or mixed syntax
+- Use ```rust only for valid Rust code
+- Avoid bare ``` without language specification
+
+#### Link Style
+- **Intra-crate**: `[item](`path::to::item`)` (with backticks for rustdoc resolution)
+- **Cross-crate**: `[crate](../crate_name)` (without backticks for markdown links)
+- Keep link text descriptive but concise
+
+#### Writing Style
+- Use factual, objective tone
+- Avoid subjective adjectives like "powerful", "innovative", "elegant", "robust"
+- Focus on describing what the code does, not evaluating its quality
+- Let readers draw their own conclusions about the design
+- Prefer "implements X" over "provides powerful X functionality"
+
+#### Error Prevention
+- Verify referenced types/methods actually exist before documenting them
+- Use `--document-private-items` compatible linking for internal docs
+- Test documentation builds regularly with `just doc`

Cargo.toml

@@ -17,6 +17,9 @@ url = "2.5.3"
 annotate-snippets = "0.11.4"
 wasm-encoder = "0.220.0"
 
+[workspace.lints.clippy]
+needless_lifetimes = "allow"
+
 [package]
 name = "dada"
 version.workspace = true

components/dada-check/Cargo.toml

@@ -3,6 +3,9 @@ name = "dada-check"
 version.workspace = true
 edition.workspace = true
 
+[lib]
+doctest = false
+
 [dependencies]
 dada-ir-ast = { version = "0.1.0", path = "../dada-ir-ast" }
 dada-ir-sym = { version = "0.1.0", path = "../dada-ir-sym" }

components/dada-check/docs/overview.md

@@ -0,0 +1,63 @@
+# Type Checking Orchestration
+
+This crate provides the high-level orchestration for Dada's type checking process. It implements the [`Check`] trait that defines what it means for a Dada program to successfully compile.
+
+## Purpose
+
+While the detailed type checking logic lives in [`dada_ir_sym::check`], this crate provides:
+- **Top-level entry points** for type checking entire programs
+- **Orchestration logic** that coordinates different phases of checking
+- **The [`Check`] trait** that unifies type checking across different AST nodes
+
+## The Check Trait
+
+The core abstraction is the [`Check`] trait:
+
+```rust
+pub trait Check<'db> {
+    fn check(&self, db: &'db dyn crate::Db);
+}
+```
+
+This trait is implemented for all major AST and IR nodes:
+- **[`SourceFile`]** - Check an entire source file
+- **[`SymModule`]** - Check a module and all its items
+- **[`SymFunction`]** - Check a function signature and body
+- **[`SymAggregate`]** - Check class definitions and members
+
+## Checking Pipeline
+
+When you call `.check()` on a source file, it triggers a cascading validation:
+
+1. **Module checking** - Validates module structure and use statements
+2. **Item checking** - Validates each top-level item (classes, functions)  
+3. **Signature checking** - Validates function signatures and generic parameters
+4. **Body checking** - Validates function implementations
+5. **Field checking** - Validates class field types
+
+## Error Accumulation
+
+The checking process accumulates errors rather than failing fast. This allows the compiler to report multiple issues at once.
+
+## Integration with Symbolic IR
+
+This crate serves as a bridge between the parsed AST and the detailed type checking in [`dada_ir_sym`]. It:
+- Converts AST nodes to symbolic IR
+- Invokes the appropriate type checking logic
+- Ensures all necessary validations are performed
+
+## Usage
+
+Typically, you'll check an entire program like this:
+
+```rust
+use dada_check::Check;
+
+// Check a source file
+source_file.check(db);
+
+// Or check a specific function
+sym_function.check(db);
+```
+
+The actual type checking algorithms and detailed analysis are implemented in [`dada_ir_sym::check`].

components/dada-check/src/lib.rs

@@ -1,3 +1,6 @@
+//! Type checking orchestration for Dada programs.
+#![doc = include_str!("../docs/overview.md")]
+
 use dada_ir_ast::{
     ast::Identifier,
     diagnostic::{Diagnostic, Level},
@@ -119,7 +122,7 @@ fn check_for_duplicates<'db, S: Spanned<'db>>(
         Diagnostic::error(
             db,
             value.span(db),
-            format!("duplicate parameter name `{}`", id),
+            format!("duplicate parameter name `{id}`"),
         )
         .label(
             db,

components/dada-codegen/src/cx/generate_expr.rs

@@ -139,6 +139,10 @@ impl<'cx, 'db> ExprCodegen<'cx, 'db> {
                     PermissionOp::Give => {
                         self.push_from(&wasm_place_repr);
                     }
+
+                    PermissionOp::Share => {
+                        todo!()
+                    }
                 }
             }
             SymExprKind::Call {
@@ -232,10 +236,9 @@ impl<'cx, 'db> ExprCodegen<'cx, 'db> {
             }
             Err(e) => match e {
                 NotPrimitive::DeadCode => (),
-                NotPrimitive::OtherType => panic!(
-                    "don't know how to execute a binary op on ({:?}, {:?})",
-                    lhs_ty, rhs_ty
-                ),
+                NotPrimitive::OtherType => {
+                    panic!("don't know how to execute a binary op on ({lhs_ty:?}, {rhs_ty:?})")
+                }
             },
         }
     }

components/dada-codegen/src/cx/generate_expr/wasm_place_repr.rs

@@ -13,9 +13,8 @@ use crate::cx::wasm_repr::WasmRepr;
 use super::ExprCodegen;
 
 /// The WASM representation for a Dada place. Dada places can be
-/// spread across the WASM local variables and
-/// The [`EmplacedWasmRepr`][] type tells you which values are stored
-/// where.
+/// spread across the WASM local variables and WASM memory.
+/// This type tells you which values are stored where.
 #[derive(Debug)]
 pub enum WasmPlaceRepr {
     /// A primitive value stored in a WASM local variable.
@@ -27,8 +26,8 @@ pub enum WasmPlaceRepr {
 }
 
 impl<'db> ExprCodegen<'_, 'db> {
-    /// Returns a [`WasmPointer`][] to the current start of a callee's stack frame.
-    /// This value is only valid until [`Self::insert_variable`][] is next called.
+    /// Returns a [`WasmPointer`] to the current start of a callee's stack frame.
+    /// This value is only valid until [`Self::insert_variable`] is next called.
     pub(super) fn next_stack_frame(&self) -> WasmPointer {
         WasmPointer {
             base_variable: self.wasm_stack_pointer,
@@ -38,7 +37,7 @@ impl<'db> ExprCodegen<'_, 'db> {
 
     /// Introduce the variable `lv` into scope and create a place for it.
     /// This can allocate more stack space in WASM memory.
-    /// You can find this place by invoking [`Self::local`][] later on.
+    /// You can find this place by invoking [`Self::place_for_local`] later on.
     pub(super) fn insert_variable(&mut self, lv: SymVariable<'db>, ty: SymTy<'db>) {
         let ty_repr = self.wasm_repr_of_type(ty);
         let emplaced_repr = self.emplace_local(&ty_repr);

components/dada-debug/Cargo.toml

@@ -4,6 +4,9 @@ version.workspace = true
 repository.workspace = true
 edition.workspace = true
 
+[lints.clippy]
+result_large_err = "allow"
+
 [dependencies]
 anyhow.workspace = true
 axum = "0.8.1"

components/dada-debug/src/error.rs

@@ -1,3 +1,3 @@
 pub fn error(e: anyhow::Error) -> String {
-    format!("<html><body><h1>Oh geez</h1><p>{}</p></body></html>", e)
+    format!("<html><body><h1>Oh geez</h1><p>{e}</p></body></html>")
 }

components/dada-debug/src/events.rs

@@ -20,7 +20,7 @@ pub async fn events(
     state: &State,
 ) -> anyhow::Result<Vec<crate::root::RootEvent>> {
     check_accept_header(headers)?;
-    crate::root::root_data(&state).await
+    crate::root::root_data(state).await
 }
 
 pub async fn try_event_data(