Docs rewrite

2026-07-03 10:23:45 +02:00
parent 6cda69044a
commit ec857525b4
23 changed files with 1084 additions and 1134 deletions
@@ -0,0 +1,48 @@
+---
+title: Compiler Architecture
+description: High-level pipeline overview of the Mist compiler and crate organization.
+icon: Building2
+---
+
+### Pipeline Overview
+
+The Mist compiler operates in distinct phases:
+
+```
+Source (.mist)
+    │
+    ▼
+┌─────────────┐
+│   Lexer     │  (pest PEG grammar)
+│   & Parser  │
+└─────────────┘
+    │  AST
+    ▼
+┌─────────────┐
+│  Semantics  │  (field init checking)
+└─────────────┘
+    │
+    ▼
+┌─────────────┐
+│  Codegen    │  (AST → Rust source)
+└─────────────┘
+    │  .rs + .map.json
+    ▼
+┌─────────────┐
+│    cargo    │  (Rust compilation)
+└─────────────┘
+    │
+    ▼
+  Binary / Library
+```
+
+### Crate Organization
+
+The compiler is written in Rust and Mist itself, organized into four main crates:
+
+| Crate | Language | Role |
+|-------|----------|------|
+| **mist-parser** | Rust | PEG parsing via pest, AST construction, semantic checks, position mapping |
+| **mist-codegen** | Rust | AST → Rust source code generation |
+| **mist-analyzer** | Rust | Language server bridging mist-editor ↔ rust-analyzer |
+| **mist-api** | Mist | Orchestrates transpilation, module tree building, cargo invocation, error remapping |
@@ -0,0 +1,32 @@
+---
+title: Attributes
+description: Inner and outer attributes for modules, items, and metadata.
+icon: Hash
+---
+
+Inner attributes apply to the containing module:
+
+```mist
+#![allow(unused_variables)]
+```
+
+Outer attributes apply to the next item:
+
+```mist
+#[derive(Debug, Clone)]
+struct Point {
+    i32 x,
+    i32 y,
+}
+
+#[test]
+void my_test()
+{
+    assert_eq!(1, 1);
+}
+```
+
+Attribute syntax:
+- `#[path]`
+- `#[path = literal]`
+- `#[path(item1, item2, ...)]`
@@ -0,0 +1,69 @@
+---
+title: Classes
+description: Class declarations, constructors, inheritance, virtual dispatch, and the override keyword.
+icon: Shapes
+---
+
+Mist introduces `class` as syntactic sugar for a Rust struct with a virtual method table (vtable).
+
+```mist
+pub class Animal {
+    str& name,
+
+    pub constructor(str& name)
+    {
+        self.name = name;
+    }
+
+    pub void speak(&self)
+    {
+        println!("...");
+    }
+}
+```
+
+Class fields can have default initializers:
+
+```mist
+class Player {
+    i32 health = 100,
+    str& name,
+}
+```
+
+### Inheritance
+
+```mist
+class Dog : Animal {
+    pub constructor(str& name)
+    {
+        super(name);
+    }
+
+    override void speak(&self)
+    {
+        println!("Woof!");
+    }
+}
+```
+
+The `override` keyword supports explicit base class targeting:
+
+```mist
+override(Animal) void speak(&self)
+{
+    println!("Woof!");
+}
+```
+
+### Under the Hood
+
+A class `Dog : Animal` generates:
+
+1. A Rust struct with a `_super: Animal` field (or `_vptr: &'static [*const c_void]` for root classes)
+2. A vtable constant with function pointers for each public method
+3. An `impl` block with `Deref<Target = Animal>` and `DerefMut`
+4. Method trampolines (`__m_<name>`) that are dispatched through the vtable
+5. A `new()` constructor that initializes via `MaybeUninit` and calls the user's `constructor(&mut self)`
+
+The vtable is unified: parent entries are copied, overridden entries replace parent slots, and new methods are appended.
@@ -0,0 +1,87 @@
+---
+title: Control Flow
+description: If/else, while, for, c-style for, loop, match, break, continue, and return.
+icon: ArrowLeftRight
+---
+
+### If/Else
+
+```mist
+if condition {
+    // body
+} else if other_condition {
+    // body
+} else {
+    // body
+}
+```
+
+Conditions must be parenthesized: `if (expr) { }` or `if expr_no_struct { }` (struct literals require parentheses).
+
+Used as an expression:
+
+```mist
+let x = if true { 1 } else { 2 };
+```
+
+### While
+
+```mist
+while condition {
+    // body
+}
+```
+
+### For
+
+```mist
+for pattern in iterator {
+    // body
+}
+
+for i in 0 .. 10 {
+    // body
+}
+```
+
+### C-Style For
+
+```mist
+for (let mut i = 0; i < 10; i++) {
+    // body
+}
+```
+
+### Loop
+
+```mist
+loop {
+    // infinite loop
+}
+```
+
+### Match
+
+```mist
+match value {
+    pattern1 => expr,
+    pattern2 => {
+        // block body
+    }
+    pattern3 | pattern4 => expr,
+}
+```
+
+### Break / Continue
+
+```mist
+break;
+continue;
+```
+
+### Return
+
+```mist
+return;
+return value;
+```
@@ -0,0 +1,58 @@
+---
+title: Functions
+description: Function declarations, self parameters, return types, and unsafe functions.
+icon: Function
+---
+
+```mist
+// Return type is `void` (unit)
+void greet(str& name)
+{
+    println!("Hello, {name}");
+}
+
+// With return type
+i32 add(i32 a, i32 b)
+{
+    return a + b;
+}
+
+// Expression body (last expression is the return value)
+i32 square(i32 x)
+{
+    x * x
+}
+
+// Public function
+pub i32 multiply(i32 a, i32 b)
+{
+    a * b
+}
+
+// Generic function
+T identity<T>(T value)
+{
+    value
+}
+
+// Unsafe function
+unsafe i32 dangerous()
+{
+    42
+}
+```
+
+Function syntax: `[pub] [void | <type>] <name>[<generics>](<params>) [override] { <body> }`
+
+Functions use **Allman brace style** (opening brace on the next line).
+
+### Self Parameter
+
+Methods can take `self`, `&self`, `&mut self`, or `self` with lifetimes:
+
+```mist
+pub void set_value(&mut self, i32 v)
+{
+    self.value = v;
+}
+```
@@ -0,0 +1,39 @@
+---
+title: Generics
+description: Generic functions, structs, enums, trait bounds, and lifetimes.
+icon: Braces
+---
+
+```mist
+// Generic function
+T id<T>(T x)
+{
+    x
+}
+
+// Generic struct
+struct Pair<A, B> {
+    A first,
+    B second,
+}
+
+// Generic enum
+enum Result<T, E> {
+    Ok(T),
+    Err(E),
+}
+
+// Generic with trait bounds
+T max<T : Ord>(T a, T b)
+{
+    if a > b { a } else { b }
+}
+
+// Lifetime generics
+void process<'a>(&'a str& data)
+{
+    // ...
+}
+```
+
+Generic syntax uses `<` `>` delimiters. Lifetimes are prefixed with `'`.
@@ -0,0 +1,29 @@
+---
+title: Modules & Imports
+description: Module declarations, imports, re-exports, and module resolution rules.
+icon: FolderTree
+---
+
+```mist
+// Declare a submodule
+pub module foo;
+
+// Import
+use std::collections::HashMap;
+
+// Re-exporting import
+pub use my_module::MyType;
+```
+
+### Module Resolution
+
+Mist maps the module tree to Rust's module system:
+
+| Mist Path                    | Rust Output                  |
+|------------------------------|------------------------------|
+| `src/main.mist`              | `.mist/src/main.rs`          |
+| `src/utils/package.mist`     | `.mist/src/utils/mod.rs`     |
+| `src/foo.mist`               | `.mist/src/foo.rs`           |
+| `src/utils/helper.mist`      | `.mist/src/utils/helper.rs`  |
+
+A `package.mist` file acts as a directory's module root, analogous to `mod.rs`.
@@ -0,0 +1,98 @@
+---
+title: Operators, Macros & Closures
+description: Binary, prefix, and postfix operators, macro calls, and closure expressions.
+icon: Plus
+---
+
+### Binary Operators
+
+| Operator | Description          |
+|----------|----------------------|
+| `+`      | Addition             |
+| `-`      | Subtraction          |
+| `*`      | Multiplication       |
+| `/`      | Division             |
+| `%`      | Modulus              |
+| `==`     | Equality             |
+| `!=`     | Inequality           |
+| `<`      | Less than            |
+| `>`      | Greater than         |
+| `<=`     | Less or equal        |
+| `>=`     | Greater or equal     |
+| `&&`     | Logical AND          |
+| `\|\|`   | Logical OR           |
+| `&`      | Bitwise AND          |
+| `\|`     | Bitwise OR           |
+| `^`      | Bitwise XOR          |
+| `<<`     | Left shift           |
+| `>>`     | Right shift          |
+| `=`      | Assignment           |
+| `+=`     | Add assign           |
+| `-=`     | Subtract assign      |
+| `*=`     | Multiply assign      |
+| `/=`     | Divide assign        |
+| `%=`     | Modulus assign       |
+| `&=`     | Bitwise AND assign   |
+| `\|=`    | Bitwise OR assign    |
+| `^=`     | Bitwise XOR assign   |
+| `<<=`    | Left shift assign    |
+| `>>=`    | Right shift assign   |
+| `..`     | Range (exclusive)    |
+| `..=`    | Range (inclusive)    |
+| `->`     | Pointer write        |
+
+### Prefix Operators
+
+| Operator | Description       |
+|----------|-------------------|
+| `*`      | Dereference       |
+| `&`      | Reference         |
+| `&mut`   | Mutable reference |
+| `!`      | Logical NOT       |
+| `-`      | Numeric negation  |
+
+### Postfix Operators
+
+| Operator   | Description          |
+|------------|----------------------|
+| `.field`   | Field access         |
+| `.0`       | Tuple field access   |
+| `()`       | Function call        |
+| `[]`       | Index                |
+| `{ f: v }` | Struct literal       |
+| `as Type`  | Type cast            |
+| `?`        | Try (error prop)     |
+| `++`       | Increment            |
+| `--`       | Decrement            |
+| `!()`      | Macro call (paren)   |
+| `![]`      | Macro call (bracket) |
+| `!{}`      | Macro call (brace)   |
+
+### Macros
+
+Mist reuses Rust's macro system directly:
+
+```mist
+println!("hello");
+assert_eq!(a, b);
+vec![1, 2, 3];
+```
+
+Macro calls use `!` followed by parentheses, brackets, or braces.
+
+### Closures
+
+```mist
+let add = (a, b) => a + b;
+let result = add(2, 3);  // 5
+
+let square = f64 x => x * x;
+```
+
+Closures can have explicit return types:
+
+```mist
+let transform = i32 x => {
+    x * 2
+};
+```
@@ -0,0 +1,41 @@
+---
+title: Patterns
+description: Pattern matching with literals, tuples, structs, named tuples, wildcards, and mutable bindings.
+icon: Split
+---
+
+```mist
+// Literal patterns
+match x {
+    1 => "one",
+    2 => "two",
+    _ => "other",
+}
+
+// Tuple patterns
+let (a, b) = (1, 2);
+
+// Struct patterns
+match value {
+    Point { x, y } => x + y,
+    Point { x: 0, y } => y,
+    _ => 0,
+}
+
+// Named tuple patterns (newtype)
+let MyType(value) = my_var;
+
+// Wildcard / etc
+let _ = get_side_effect();
+match x {
+    1 => ...,
+    .. => ...,  // rest / etc
+}
+
+// Mutable binding in pattern
+let mut x = 42;
+match ref_to_option {
+    Some(mut value) => value += 1,
+    None => {},
+}
+```
@@ -0,0 +1,47 @@
+---
+title: Structs & Enums
+description: Defining structs and enums with named, tuple, and struct variants.
+icon: Box
+---
+
+### Structs
+
+```mist
+pub struct Point {
+    i32 x,
+    i32 y,
+}
+
+pub struct Generic<T> {
+    T value,
+}
+```
+
+Fields can be public or private:
+
+```mist
+struct User {
+    pub str& name,
+    i32 age,  // private
+}
+```
+
+### Enums
+
+```mist
+pub enum Option<T> {
+    Some(T),
+    None,
+}
+
+pub enum Message {
+    Quit,
+    Move(i32, i32),
+    Write { str& content, i32 length },
+}
+```
+
+Enum variants can be:
+- **Named** — `Variant`
+- **Tuple** — `Variant(T1, T2)`
+- **Struct** — `Variant { T1 field1, T2 field2 }`
@@ -0,0 +1,45 @@
+---
+title: Syntax Overview
+description: Comments, literals, identifiers, and keywords in Mist.
+icon: Code
+---
+
+### Comments
+
+```mist
+// Line comments only
+```
+
+### Literals
+
+```mist
+42              // Integer
+3.14            // Float
+true            // Boolean
+false           // Boolean
+"hello"         // String
+(1, true, "x")  // Tuple
+```
+
+### Identifiers & Keywords
+
+Keywords are reserved and cannot be used as identifiers:
+
+`if`, `else`, `fn`, `for`, `while`, `match`, `return`, `break`, `continue`, `struct`, `enum`, `class`, `trait`, `impl`, `use`, `pub`, `mut`, `let`, `true`, `false`, `dyn`, `loop`, `unsafe`, `override`, `const`, `type`
+
+Identifiers follow the pattern `[a-zA-Z_][a-zA-Z0-9_]*`.
+
+### Visibility
+
+```mist
+// Private (default)
+void internal() { }
+
+// Public
+pub void external() { }
+
+// Public to specific path
+pub(crate) void crate_only() { }
+pub(super) void parent_only() { }
+pub(in my::module) void module_only() { }
+```
@@ -0,0 +1,42 @@
+---
+title: Traits & Impls
+description: Defining traits, trait bounds, and implementation blocks.
+icon: Puzzle
+---
+
+### Traits
+
+```mist
+pub trait Drawable {
+    void draw(&self);
+}
+
+pub trait Comparable<T> : Eq {
+    i32 cmp(&self, T other);
+}
+```
+
+Trait requirements are specified after `:`:
+
+```mist
+trait MyTrait : SuperTrait + OtherTrait {
+    void required_method(&self);
+    void another(&self);
+}
+```
+
+### Impl Blocks
+
+```mist
+impl MyType {
+    void method(&self) { }
+}
+
+impl Trait for MyType {
+    void method(&self) { }
+}
+
+impl<T> GenericTrait<T> for MyType {
+    void method(&self, T value) { }
+}
+```
@@ -0,0 +1,47 @@
+---
+title: Types
+description: The Mist type system including references, pointers, tuples, function types, and trait objects.
+icon: Type
+---
+
+### Type System
+
+```mist
+i32                // Path type
+str&               // Reference type
+&mut i32           // Mutable reference
+&'a i32            // Reference with lifetime
+*const i32         // Const pointer
+*mut i32           // Mutable pointer
+(i32, bool)        // Tuple type
+fn(i32) -> bool    // Function pointer type
+Fn(i32) -> bool    // Closure trait (Fn)
+FnMut(i32) -> bool // Closure trait (FnMut)
+FnOnce(i32) -> bool // Closure trait (FnOnce)
+dyn Trait          // Trait object
+void               // Unit type (maps to Rust's ())
+'lifetime          // Lifetime
+```
+
+Type expressions can be composed:
+
+```mist
+type_expr = { (void | path_type | tuple_type | dyn_type) ~ (unsafe_ref_type | ref_type | fn_type)* }
+```
+
+This means types are written left-to-right naturally:
+
+```mist
+i32&              // &i32
+i32&mut           // &mut i32
+i32&'a            // &'a i32
+i32 fn() -> bool  // fn(i32) -> bool
+```
+
+### Type Aliases
+
+```mist
+type MyInt = i32;
+
+type Result<T> = std::result::Result<T, str&>;
+```
@@ -0,0 +1,30 @@
+---
+title: Variables
+description: Variable declarations, mutability, type annotations, and destructuring.
+icon: Variable
+---
+
+```mist
+let x = 42;                    // Type-inferred immutable
+let mut y = 10;                // Mutable variable
+i32 z = 100;                   // Explicit type annotation
+str& s = "hello";              // Typed string reference
+bool b = true;                 // Typed boolean
+f64 f = 3.14;                  // Typed float
+let (a, b) = (1, "two");      // Destructuring
+let (x, (y, z)) = (1, (2, 3)); // Nested destructuring
+```
+
+Variable declarations follow either of two forms:
+
+```mist
+let <pattern> [= <expr>];
+<type> <pattern> [= <expr>];
+```
+
+### Const and Static
+
+```mist
+const MAX: i32 = 100;
+static NAME: str& = "hello";
+```
@@ -0,0 +1,34 @@
+---
+title: Builder & Error Remapping
+description: How Mist invokes cargo and remaps Rust compiler errors back to Mist source locations.
+icon: Bug
+---
+
+The builder module (`builder.mist` in the `mist_api` crate) wraps `cargo` to:
+
+1. Spawn `cargo` with `--message-format=json`
+2. Parse JSON compiler messages
+3. For each diagnostic span, look up the corresponding `.map.json` file
+4. Remap Rust line/column to Mist line/column using the mapping
+5. Display errors/warnings with Mist source locations and context lines
+
+```rust
+pub fn build(args: Vec<String>, root: PathBuf) -> bool {
+    // Spawn cargo with JSON output
+    // Parse CompilerMessage for each span
+    // Look up rev_mapper::Mapping from .map.json
+    // Remap to Mist positions
+    // Print diagnostics
+}
+```
+
+### Diagnostic Output
+
+Errors and warnings are displayed with Mist source context:
+
+```
+src/main.mist:10:5
+ Error: mismatched types
+    let x: i32 = "hello";
+                ^^^^^^^
+```
@@ -0,0 +1,53 @@
+---
+title: Code Generation
+description: How the Mist AST is translated into Rust source code, including class vtables and position mapping.
+icon: Wrench
+---
+
+The code generator converts the Mist AST into Rust source code directly — no intermediate representation.
+
+### Key files
+
+- `src/lib.rs` — `RustCodegen` struct with output buffer, indentation tracking, `Mapping` for position translation
+- `src/top_level.rs` — Generates Rust for top-level items (structs, enums, traits, functions, impls, imports, type aliases, const/static)
+- `src/statement.rs` — Generates Rust for statements and blocks
+- `src/expr.rs` — Generates Rust for expressions (literals, paths, binary ops, closures, arrays, prefix/postfix)
+- `src/class_decl.rs` — Class-specific code generation (struct + vtable + impl blocks + Deref)
+
+### Codegen Design
+
+The `RustCodegen` maintains:
+- A string `output` buffer
+- An `indent` level (4 spaces per level)
+- A `Mapping` that records `(RustMap, MistMap)` pairs for source position remapping
+- A current `position` tracker (`RustMap(line, column)`)
+
+Generation follows the `GenRust` trait:
+
+```rust
+pub trait GenRust {
+    fn gen_rust(&self, ctx: &mut Context, cg: &mut RustCodegen);
+}
+```
+
+And `GetRust` for simple string-returning types:
+
+```rust
+pub trait GetRust {
+    fn get_rust(&self) -> String;
+}
+```
+
+The `Context` carries optional expression path information for class `super` / `Super` resolution.
+
+### Class Codegen
+
+Classes are the most complex codegen path. `ClassProcessedData` analyzes a class declaration and emits:
+
+1. **Struct declaration** — `struct ClassName<G> { pub _super: Parent, pub field1: T1, ... }` (or `_vptr` for root classes)
+2. **Vtable constants** — Index constants `__FN_METHOD` and a `__V_TABLE` static array of function pointers. For inherited classes, parent vtable entries are copied and overridden entries replaced.
+3. **Constructor** — `pub fn new(...) -> Self` that creates an uninitialized instance via `MaybeUninit`, sets the vtable pointer, writes field defaults, calls `self.constructor(...)`, and returns `this`
+4. **Method trampolines** — Public methods with `self` get wrapper functions `__m_method` stored in the vtable, plus virtual dispatch methods
+5. **Override support** — Methods marked `override` are validated at compile time via generated test code
+6. **Deref impls** — `impl Deref<Target = Parent> for Child` and `DerefMut` for inherited classes
+7. **Impl declarations** — Inner `impl` blocks are rewritten to use the self type
@@ -0,0 +1,55 @@
+---
+title: LSP Support
+description: How the Mist Language Server bridges editor requests through rust-analyzer.
+icon: Server
+---
+
+The Mist Language Server Protocol implementation runs a headless `rust-analyzer` instance and bridges Mist editor requests to Rust positions.
+
+### Architecture
+
+```
+Editor (LSP client)
+    │
+    ▼
+┌─────────────────────┐
+│   mist-analyzer     │
+│   (Rust + Mist)     │
+└─────────────────────┘
+    │           ▲
+    │  JSON-RPC │
+    ▼           │
+┌─────────────────────┐
+│   rust-analyzer     │
+│   (headless child)  │
+└─────────────────────┘
+```
+
+### Flow
+
+1. Editor sends Mist file edits to `mist-analyzer` via LSP
+2. `mist-analyzer` transpiles Mist to Rust
+3. The transpiled Rust is forwarded to the headless `rust-analyzer` process
+4. For goto-definition, hover, and completion, a unique marker token is injected at the cursor position
+5. The transpiled output with the marker is sent to `rust-analyzer`
+6. The marker position is located in the response
+7. Results are mapped back to Mist positions using the `rev_mapper`
+
+### Key Features
+
+- **Full document sync** — Open, change, save, close
+- **Go to definition** — Maps through transpiled Rust positions
+- **Completions** — Supports trigger characters `:`, `.`, `'`, `(`
+- **Hover** — Type information and docs
+- **Diagnostics** — Real-time errors from transpilation failures and Rust compilation
+- **Formatting** — Document formatting support
+- **Auto-import** — Automatically inserts `pub module <name>;` when new `.mist` files are created
+- **File watching** — Monitors `**/*.mist` for new files
+
+### Diagnostic Remapping
+
+When a transpilation error occurs in the `mist-analyzer`:
+
+1. Parse errors are converted to `Diagnostic` with Mist source positions
+2. Semantic errors (uninitialized class fields) use the stored line/column
+3. Rust compiler errors are remapped via the `Mapping` system back to Mist positions
@@ -0,0 +1,76 @@
+---
+title: Parsing
+description: PEG grammar structure, AST design, and how Mist source code is parsed.
+icon: FileCode
+---
+
+The parser is built with [pest](https://pest.rs), a PEG parser generator. Grammar rules are defined in `grammar.pest` (693 rules).
+
+### Key files
+
+- `grammar.pest` — PEG grammar defining the entire language syntax
+- `src/parser/common/` — Parse rule → AST conversions for expressions, statements, types, declarations
+- `src/parser/items/` — Parse rule → AST conversions for top-level items (structs, enums, classes, functions, traits, impls, attributes)
+- `src/ast/` — AST node types (expr.rs, statement.rs, top_level.rs)
+- `src/error.rs` — Error types (PreAst parsing errors, Ast generation errors)
+
+### Parsing entry points
+
+```rust
+// Parse a complete program
+pub fn parse<'a>(source: &'a str) -> Result<Program, ParseError<'a>>
+
+// Parse only the module declaration
+pub fn parse_module<'a>(source: &'a str) -> Result<Option<(Visibility, Identifier)>, ParseError<'a>>
+```
+
+### Grammar Structure
+
+The grammar follows a layered approach:
+
+1. **Lexical rules** (silent) — `WHITESPACE`, `COMMENT`, `identifier`, `integer`, `float`, `string_lit`
+2. **Primary expressions** — literals, paths, tuples, arrays, closures, control flow
+3. **Term** — prefix operators + primary + postfix operators
+4. **Expression** — terms joined by binary operators (via Pratt parser)
+5. **Statements** — variable declarations, control flow (`if`, `while`, `for`, `match`, `loop`), blocks
+6. **Top-level items** — functions, structs, enums, classes, traits, impls, type aliases, imports, module declarations, constants
+
+### AST Structure
+
+The AST preserves source positions via `Spanned<T>`:
+
+```rust
+pub struct Spanned<T> {
+    pub line: usize,
+    pub column: usize,
+    pub item: T,
+}
+```
+
+Top-level items are wrapped as:
+
+```rust
+pub struct TopLevel(pub Spanned<TopLevelKind>, pub Vec<Attribute>);
+```
+
+Expressions use a fix-point representation for prefix/postfix operators:
+
+```rust
+Expression::Fix {
+    initial: Box<Expression>,
+    prefixes: Vec<Prefix>,
+    postfixes: Vec<Postfix>,
+}
+```
+
+Binary expressions use Pratt parsing for correct precedence:
+
+```rust
+Expression::Binary {
+    lhs: Box<Expression>,
+    op: String,
+    rhs: Box<Expression>,
+}
+```
+
+All operators are left-associative with a single precedence level.
@@ -0,0 +1,31 @@
+---
+title: Position Mapping
+description: Bidirectional mapping between Mist source positions and Rust output positions for error remapping and LSP features.
+icon: Map
+---
+
+Mist maintains a bidirectional mapping between Mist source positions and Rust output positions. This is essential for:
+
+1. **Error remapping** — Rust compiler errors point to the correct Mist source location
+2. **LSP features** — Go-to-definition, hover, and completion work from Mist source
+
+### Data Structure
+
+The mapping is stored as pairs:
+
+```rust
+pub struct Mapping {
+    pub mist_path: PathBuf,
+    pub map: HashSet<(RustMap, MistMap)>,
+}
+```
+
+- `RustMap(usize, usize)` — line/column in generated Rust
+- `MistMap(usize, usize)` — line/column in original Mist
+
+### Mapping Lifecycle
+
+1. **Codegen** — Each `Spanned<T>` AST node records its Mist position and the current Rust position in the codegen output buffer via `GenSpanTranslation`
+2. **Persistence** — The mapping is serialized to `<output>.map.json` alongside the transpiled `.rs` output
+3. **Build-time remapping** — The builder reads `.map.json` to remap `cargo` diagnostics back to Mist positions
+4. **LSP remapping** — Both Mist→Rust and Rust→Mist direction queries are supported via `find()` and `find_by_mist()`
@@ -0,0 +1,36 @@
+---
+title: Semantic Analysis
+description: Class field initialization verification and the GetMutability analysis system.
+icon: SearchCheck
+---
+
+The semantic checker (`semantics.rs`) performs class field initialization analysis. When a class has a constructor, it verifies that every declared field is mutated (directly or indirectly via method calls) within the constructor body.
+
+### Field Initialization
+
+The primary semantic check ensures all class fields are initialized in the constructor:
+
+```mist
+class Player {
+    i32 health,
+    str& name,
+
+    pub constructor(str& name)
+    {
+        self.name = name;
+        // Error: field 'health' is uninitialized
+    }
+}
+```
+
+### How It Works
+
+The `GetMutability` trait tracks which identifiers are mutated:
+
+1. Collects all identifiers that get `&mut` references
+2. Tracks `self.field = value` patterns
+3. Follows method calls that might initialize fields (transitively)
+4. Ensures all conditional branches initialize the same fields (intersection semantics)
+5. `super` assignments count for `_super` field initialization
+
+If any field is uninitialized after the analysis, a `SemanticError` is reported with the field's source position.
@@ -0,0 +1,61 @@
+---
+title: Transpilation Pipeline
+description: How Mist source files are discovered, transpiled to Rust, and cached.
+icon: Repeat
+---
+
+The transpiler (`transpiler.mist` in `mist_api`) orchestrates the full pipeline.
+
+### Pipeline
+
+1. Read `Mist.toml` configuration
+2. Build a `Module` tree from the filesystem (discovering `package.mist` files)
+3. For each module:
+   a. Parse Mist source
+   b. Run semantic checks
+   c. Generate Rust code and position mapping
+   d. Write `.rs` file and `.map.json` file
+4. Recursively transpile included crates
+
+### Module Tree
+
+The `Module` struct represents the file-to-module mapping:
+
+```rust
+pub class Module {
+    pub String name;
+    pub PathBuf path;
+    pub Vec<Module> children;
+
+    pub constructor(PathBuf mist_path, MistConfig& config) { ... }
+    pub bool is_package(&self) { ... }
+    pub PathBuf output_dir(&self, PathBuf& parent_dir) { ... }
+    pub PathBuf output_path(&self, PathBuf& parent_dir, ...) { ... }
+}
+```
+
+### Transpilation Mapping Rules
+
+| Mist Source                | Rust Output                     |
+|----------------------------|----------------------------------|
+| `src/main.mist`            | `.mist/src/main.rs`              |
+| `src/foo.mist`             | `.mist/src/foo.rs`               |
+| `src/bar/package.mist`     | `.mist/src/bar/mod.rs`           |
+| `src/bar/baz.mist`         | `.mist/src/bar/baz.rs`           |
+
+A `package.mist` file generates `mod.rs` in the output directory and contains `pub mod <child>;` declarations for its children.
+
+### Caching
+
+The transpiler implements basic caching via file modification times:
+
+```rust
+fn is_source_newer(source: &Path, output: &Path) -> io::Result<bool> {
+    if !output.exists() { return Ok(true); }
+    let source_time = fs::metadata(source)?.modified()?;
+    let output_time = fs::metadata(output)?.modified()?;
+    Ok(source_time > output_time)
+}
+```
+
+If a source file has not changed since the last transpilation, the `.rs` file is not regenerated.
@@ -1,8 +1,31 @@
 {
    "pages": [
-        "---[Rocket]Introduction---",
+        "---Introduction---",
        "index",
        "philosophy",
-        "limitations"
+        "limitations",
+        "---Language Guide---",
+        "guide/syntax-overview",
+        "guide/variables",
+        "guide/types",
+        "guide/functions",
+        "guide/control-flow",
+        "guide/structs-enums",
+        "guide/classes",
+        "guide/traits-impls",
+        "guide/generics",
+        "guide/modules",
+        "guide/patterns",
+        "guide/operators",
+        "guide/attributes",
+        "---Compiler Internals---",
+        "internals/architecture",
+        "internals/parsing",
+        "internals/semantic-analysis",
+        "internals/codegen",
+        "internals/transpiler",
+        "internals/builder",
+        "internals/lsp",
+        "internals/position-mapping"
    ]
-}
+}