From 62a75f0e28a7e92bf7d3191c05da1b6fb4fa7219 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Dec 2025 00:32:21 +0000 Subject: [PATCH 1/4] docs: add comprehensive language roadmap and wiki Add extensive documentation covering: Roadmap (ROADMAP.md): - Complete development roadmap through v1.0 - Phase-by-phase implementation plan - Testing strategy with property-based testing - Standard library and framework ecosystem plans - Milestone definitions and release schedule Wiki documentation (wiki/): - Language reference: lexical structure, types, ownership, effects, traits, modules, dependent types, row polymorphism, patterns, functions - Compiler implementation guides: architecture, lexer, parser, type checker, borrow checker, code generation - Tooling: CLI reference, REPL guide - Testing: comprehensive testing guide with property-based testing inspired by Echidna/QuickCheck - Standard library overview - Tutorials: introduction and quick start guide This documentation provides a foundation for contributors and users to understand the language design and implementation. --- ROADMAP.md | 1225 ++++++++++++++++++++ wiki/README.md | 162 +++ wiki/compiler/architecture.md | 424 +++++++ wiki/compiler/borrow-checker.md | 375 ++++++ wiki/compiler/codegen.md | 431 +++++++ wiki/compiler/lexer.md | 360 ++++++ wiki/compiler/parser.md | 336 ++++++ wiki/compiler/type-checker.md | 406 +++++++ wiki/language-reference/dependent-types.md | 455 ++++++++ wiki/language-reference/effects.md | 578 +++++++++ wiki/language-reference/functions.md | 494 ++++++++ wiki/language-reference/lexical.md | 484 ++++++++ wiki/language-reference/modules.md | 468 ++++++++ wiki/language-reference/ownership.md | 499 ++++++++ wiki/language-reference/patterns.md | 389 +++++++ wiki/language-reference/rows.md | 449 +++++++ wiki/language-reference/traits.md | 484 ++++++++ wiki/language-reference/types.md | 603 ++++++++++ wiki/stdlib/overview.md | 421 +++++++ wiki/testing/guide.md | 630 ++++++++++ wiki/testing/property-based.md | 391 +++++++ wiki/tooling/cli.md | 302 +++++ wiki/tooling/repl.md | 289 +++++ wiki/tutorials/introduction.md | 173 +++ wiki/tutorials/quickstart.md | 399 +++++++ 25 files changed, 11227 insertions(+) create mode 100644 ROADMAP.md create mode 100644 wiki/README.md create mode 100644 wiki/compiler/architecture.md create mode 100644 wiki/compiler/borrow-checker.md create mode 100644 wiki/compiler/codegen.md create mode 100644 wiki/compiler/lexer.md create mode 100644 wiki/compiler/parser.md create mode 100644 wiki/compiler/type-checker.md create mode 100644 wiki/language-reference/dependent-types.md create mode 100644 wiki/language-reference/effects.md create mode 100644 wiki/language-reference/functions.md create mode 100644 wiki/language-reference/lexical.md create mode 100644 wiki/language-reference/modules.md create mode 100644 wiki/language-reference/ownership.md create mode 100644 wiki/language-reference/patterns.md create mode 100644 wiki/language-reference/rows.md create mode 100644 wiki/language-reference/traits.md create mode 100644 wiki/language-reference/types.md create mode 100644 wiki/stdlib/overview.md create mode 100644 wiki/testing/guide.md create mode 100644 wiki/testing/property-based.md create mode 100644 wiki/tooling/cli.md create mode 100644 wiki/tooling/repl.md create mode 100644 wiki/tutorials/introduction.md create mode 100644 wiki/tutorials/quickstart.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..c14a3cb --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,1225 @@ +# AffineScript Language Roadmap + +> A comprehensive development roadmap for AffineScript: a next-generation systems programming language with affine types, dependent types, row polymorphism, and extensible effects. + +**Version**: 0.1.0-alpha +**Status**: Active Development +**Target**: Production-ready v1.0 by Q4 2026 + +--- + +## Table of Contents + +1. [Vision & Goals](#vision--goals) +2. [Phase Overview](#phase-overview) +3. [Phase 1: Foundation](#phase-1-foundation-current) +4. [Phase 2: Core Language](#phase-2-core-language) +5. [Phase 3: Advanced Features](#phase-3-advanced-features) +6. [Phase 4: Tooling & Ecosystem](#phase-4-tooling--ecosystem) +7. [Phase 5: Optimization & Production](#phase-5-optimization--production) +8. [Testing Strategy](#testing-strategy) +9. [Standard Library Roadmap](#standard-library-roadmap) +10. [Framework Ecosystem](#framework-ecosystem) +11. [Milestones & Releases](#milestones--releases) + +--- + +## Vision & Goals + +### Core Language Principles + +1. **Safety by Default**: Memory safety through affine types without garbage collection +2. **Expressive Types**: Dependent types for compile-time guarantees +3. **Flexible Records**: Row polymorphism for extensible, type-safe records +4. **Controlled Effects**: First-class effect system with algebraic effect handlers +5. **Predictable Performance**: Zero-cost abstractions targeting WebAssembly + +### Target Use Cases + +- **Systems Programming**: OS components, embedded systems, device drivers +- **WebAssembly Applications**: High-performance web applications +- **Blockchain & Smart Contracts**: Formally verified contract code +- **Safety-Critical Systems**: Aerospace, medical, automotive software +- **High-Performance Computing**: Numerical computing with static guarantees + +--- + +## Phase Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 1: FOUNDATION (Current) │ +│ ├── Lexer (95% complete) │ +│ ├── Parser (0% - PRIORITY) │ +│ ├── AST & Core Types (100%) │ +│ └── Error Infrastructure (100%) │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ PHASE 2: CORE LANGUAGE │ +│ ├── Name Resolution │ +│ ├── Bidirectional Type Checker │ +│ ├── Borrow Checker │ +│ └── Basic Code Generation │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ PHASE 3: ADVANCED FEATURES │ +│ ├── Dependent Types │ +│ ├── Row Polymorphism │ +│ ├── Effect System │ +│ └── Trait System │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ PHASE 4: TOOLING & ECOSYSTEM │ +│ ├── REPL & Interpreter │ +│ ├── Package Manager │ +│ ├── LSP Server │ +│ └── Formatter & Linter │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ PHASE 5: OPTIMIZATION & PRODUCTION │ +│ ├── WASM Backend Optimization │ +│ ├── Standard Library │ +│ ├── Documentation & Tutorials │ +│ └── Framework Libraries │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Phase 1: Foundation (Current) + +### 1.1 Lexer (sedlex-based) - 95% Complete + +**Status**: ✅ Functional, needs refinement + +| Feature | Status | Notes | +|---------|--------|-------| +| Keywords | ✅ Complete | All 40+ keywords recognized | +| Identifiers | ✅ Complete | Unicode support via sedlex | +| Numeric literals | ✅ Complete | Int, float, hex, binary, octal | +| String literals | ✅ Complete | Escape sequences, Unicode | +| Operators | ✅ Complete | All operators and punctuation | +| Comments | ✅ Complete | Line `//`, nested block `/* */` | +| Quantity annotations | ✅ Complete | `0`, `1`, `ω` (omega) | +| Row variables | ✅ Complete | `..rest` syntax | +| Source locations | ✅ Complete | Span tracking | + +**Remaining Work**: +- [ ] Raw string literals (`r"..."`, `r#"..."#`) +- [ ] String interpolation lexing (`${}`) +- [ ] Documentation comments (`///`, `//!`) +- [ ] Attribute syntax (`#[...]`) + +### 1.2 Parser (Menhir) - 0% Complete + +**Status**: 🔴 Not Started - HIGHEST PRIORITY + +**Implementation Plan**: + +``` +Parser Implementation Phases: +├── 1.2.1 Basic Expressions +│ ├── Literals (int, float, string, char, bool) +│ ├── Identifiers and paths +│ ├── Unary and binary operators +│ ├── Parenthesized expressions +│ └── Operator precedence +│ +├── 1.2.2 Type Expressions +│ ├── Simple types (Int, Bool, String) +│ ├── Type constructors (Option[T], Vec[n, T]) +│ ├── Function types (A -> B, A -{E}-> B) +│ ├── Tuple and record types +│ ├── Ownership modifiers (own, ref, mut) +│ └── Row types ({x: Int, ..r}) +│ +├── 1.2.3 Patterns +│ ├── Wildcard and variable patterns +│ ├── Literal patterns +│ ├── Constructor patterns +│ ├── Tuple and record patterns +│ ├── Or-patterns (p1 | p2) +│ └── Binding patterns (p @ pattern) +│ +├── 1.2.4 Statements & Control Flow +│ ├── Let bindings +│ ├── Assignment statements +│ ├── If/else expressions +│ ├── Match expressions +│ ├── While/for loops +│ └── Return/break/continue +│ +├── 1.2.5 Functions & Declarations +│ ├── Function declarations +│ ├── Type parameters and constraints +│ ├── Where clauses +│ ├── Total/partial annotations +│ └── Effect annotations +│ +├── 1.2.6 Type Declarations +│ ├── Type aliases +│ ├── Struct definitions +│ ├── Enum definitions +│ ├── Associated types +│ └── Dependent type parameters +│ +├── 1.2.7 Traits & Effects +│ ├── Trait declarations +│ ├── Trait implementations +│ ├── Effect declarations +│ ├── Effect handlers +│ └── Effect rows +│ +└── 1.2.8 Modules + ├── Module declarations + ├── Import statements + ├── Visibility modifiers + └── Re-exports +``` + +**Grammar Conflicts to Resolve**: +- Function application vs tuple construction +- Type ascription vs ternary expressions +- Generic types vs comparison operators +- Closure syntax vs blocks + +### 1.3 AST & Core Types - 100% Complete + +**Status**: ✅ Complete + +All AST node types defined in `lib/ast.ml`: +- Expression AST nodes +- Type expression nodes +- Pattern nodes +- Statement nodes +- Declaration nodes +- Module system nodes + +### 1.4 Error Infrastructure - 100% Complete + +**Status**: ✅ Complete + +- Error codes organized by category (E0001-E0799, W0001-W0999) +- Diagnostic message system with labels and notes +- Terminal formatting with ANSI colors +- Source code display with error indicators + +--- + +## Phase 2: Core Language + +### 2.1 Name Resolution + +**Dependencies**: Parser + +**Implementation Tasks**: + +```ocaml +(* Name resolution module structure *) +module Name_resolution : sig + type scope = { + variables: (string, var_info) Hashtbl.t; + types: (string, type_info) Hashtbl.t; + modules: (string, module_info) Hashtbl.t; + parent: scope option; + } + + val resolve_program : Ast.program -> Resolved.program + val resolve_imports : Ast.import list -> import_info list +end +``` + +| Task | Description | Priority | +|------|-------------|----------| +| Scope management | Lexical scope tracking with nesting | High | +| Variable resolution | Link uses to definitions | High | +| Type name resolution | Resolve type constructors | High | +| Module resolution | Handle import paths | High | +| Shadowing rules | Correct shadowing semantics | Medium | +| Forward references | Handle mutual recursion | Medium | +| Visibility checking | Public/private enforcement | Medium | + +### 2.2 Bidirectional Type Checker + +**Dependencies**: Name Resolution + +**Architecture**: + +``` +Type Checker Phases: +├── Kind Checking +│ ├── Type well-formedness +│ ├── Kind inference for type constructors +│ └── Kind unification +│ +├── Type Inference (Bidirectional) +│ ├── Synthesis mode (infer type from term) +│ ├── Checking mode (check term against type) +│ ├── Application synthesis +│ └── Subsumption checking +│ +├── Unification +│ ├── First-order unification +│ ├── Occurs check +│ ├── Constraint generation +│ └── Constraint solving +│ +├── Quantity Checking +│ ├── Usage counting (0, 1, ω) +│ ├── Subquantity relation +│ └── Linearity enforcement +│ +└── Effect Inference (Basic) + ├── Effect synthesis + ├── Effect subsumption + └── Effect constraints +``` + +**Type Rules Implementation Order**: + +1. **Literals & Variables** - Basic type lookup +2. **Functions** - Arrow types, application +3. **Let bindings** - Polymorphism, generalization +4. **Records** - Record types, field access +5. **Tuples** - Product types +6. **Match expressions** - Pattern typing +7. **If expressions** - Boolean conditions +8. **Loops** - Unit typing + +### 2.3 Borrow Checker + +**Dependencies**: Type Checker + +**Implementation Strategy**: + +``` +Borrow Checking Phases: +├── Ownership Analysis +│ ├── Owned value tracking +│ ├── Move semantics +│ ├── Drop insertion +│ └── Use-after-move detection +│ +├── Borrow Analysis +│ ├── Shared borrow (&T) +│ ├── Mutable borrow (&mut T) +│ ├── Borrow lifetime tracking +│ └── Reborrow rules +│ +├── Linearity Checking +│ ├── Linear type enforcement +│ ├── Affine type enforcement +│ └── Quantity verification +│ +└── Region Inference + ├── Lifetime inference + ├── Region constraints + └── Outlives relations +``` + +**Key Algorithms**: +- Non-lexical lifetimes (NLL) +- Polonius-style borrow checking +- Linear type consumption tracking + +### 2.4 Basic Code Generation + +**Dependencies**: Borrow Checker + +**Initial Target**: WASM (text format) + +``` +Code Generation Phases: +├── IR Lowering +│ ├── ANF transformation +│ ├── Closure conversion +│ ├── Monomorphization +│ └── Defunctionalization (for effects) +│ +├── WASM Emission (MVP) +│ ├── Function compilation +│ ├── Local variable allocation +│ ├── Control flow (if, loop, block) +│ ├── Memory operations +│ └── Function calls +│ +└── Runtime Support + ├── Memory allocator stub + ├── Drop glue + └── Panic handler +``` + +--- + +## Phase 3: Advanced Features + +### 3.1 Dependent Types + +**Implementation Complexity**: High + +``` +Dependent Types Features: +├── Pi Types (Dependent Functions) +│ ├── (x: A) -> B[x] +│ ├── Implicit arguments +│ └── Type-level computation +│ +├── Sigma Types (Dependent Pairs) +│ ├── (x: A, B[x]) +│ └── Dependent records +│ +├── Indexed Types +│ ├── Vec[n, T] - length-indexed vectors +│ ├── Matrix[m, n, T] - dimension-indexed matrices +│ └── Bounded integers +│ +├── Refinement Types +│ ├── Int where (x > 0) +│ ├── Refinement checking +│ └── SMT solver integration +│ +└── Equality Types + ├── Propositional equality + ├── Rewrite rules + └── Transport +``` + +**SMT Integration for Refinements**: +- Z3 or CVC5 for constraint solving +- Liquid types style inference +- Decidable fragment restrictions + +### 3.2 Row Polymorphism + +**Implementation Strategy**: + +``` +Row Polymorphism Components: +├── Row Types +│ ├── {x: Int, y: String} - Closed row +│ ├── {x: Int, ..r} - Open row +│ └── {..r} - Row variable +│ +├── Row Operations +│ ├── Field access - record.field +│ ├── Field extension - {z: Bool, ..record} +│ ├── Field restriction - record \ field +│ └── Field update - {record with x = 5} +│ +├── Row Unification +│ ├── Row variable unification +│ ├── Lacks constraints - r lacks x +│ └── Presence constraints - r has x: T +│ +├── Row Kinds +│ ├── Row : * -> Row +│ ├── Record : Row -> * +│ └── Variant : Row -> * +│ +└── Applications + ├── Extensible records + ├── Polymorphic variants + ├── Effect rows + └── Module signatures +``` + +### 3.3 Effect System + +**Algebraic Effects Implementation**: + +``` +Effect System Architecture: +├── Effect Declarations +│ │ effect State[S] { +│ │ fn get() -> S +│ │ fn put(s: S) -> Unit +│ │ } +│ └── Operation signatures +│ +├── Effect Handlers +│ │ handle expr { +│ │ get() -> resume(state) +│ │ put(s) -> { state = s; resume(()) } +│ │ return(x) -> x +│ │ } +│ └── Handler semantics +│ +├── Effect Rows +│ ├── Effect polymorphism +│ ├── Effect constraints +│ └── Effect subsumption +│ +├── Effect Compilation +│ ├── CPS transformation +│ ├── Evidence passing +│ └── Handler optimization +│ +└── Standard Effects + ├── IO - I/O operations + ├── Exn - Exceptions + ├── Async - Async/await + ├── State[S] - Mutable state + ├── Reader[R] - Environment reading + ├── Writer[W] - Logging/accumulation + └── Div - Divergence/non-termination +``` + +### 3.4 Trait System + +**Trait Implementation**: + +``` +Trait System Components: +├── Trait Declarations +│ │ trait Eq { +│ │ fn eq(self: &Self, other: &Self) -> Bool +│ │ } +│ └── Method signatures +│ +├── Implementations +│ │ impl Eq for Int { +│ │ fn eq(self: &Int, other: &Int) -> Bool = ... +│ │ } +│ └── Instance definitions +│ +├── Associated Types +│ │ trait Iterator { +│ │ type Item +│ │ fn next(self: &mut Self) -> Option[Item] +│ │ } +│ └── Type family support +│ +├── Trait Bounds +│ ├── fn sort[T: Ord](xs: Vec[T]) -> Vec[T] +│ ├── Where clauses +│ └── Higher-ranked bounds +│ +├── Coherence Checking +│ ├── Orphan rules +│ ├── Overlap detection +│ └── Instance resolution +│ +└── Trait Objects (Optional) + ├── dyn Trait + ├── Vtable generation + └── Object safety rules +``` + +--- + +## Phase 4: Tooling & Ecosystem + +### 4.1 REPL (Read-Eval-Print Loop) + +**Features**: + +``` +REPL Implementation: +├── Core REPL +│ ├── Expression evaluation +│ ├── Type inference display +│ ├── Multi-line input +│ └── History management +│ +├── Interactive Features +│ ├── :type - Show type +│ ├── :kind - Show kind +│ ├── :effect - Show effects +│ ├── :doc - Show documentation +│ ├── :source - Show definition +│ └── :browse - List exports +│ +├── Development Tools +│ ├── :load - Load module +│ ├── :reload - Reload changes +│ ├── :set