lux/docs/PRIORITY_PLAN.md

# Lux Priority Implementation Plan

*Based on analysis of what makes developers love languages*

## Core Insight

From studying successful languages (Rust, Elm, Go, Gleam), the pattern is clear:

1. **Elm** has 0% runtime exceptions and legendary error messages → developers evangelize it
2. **Rust** has "if it compiles, it works" confidence → 72% admiration
3. **Go** has simplicity and fast feedback → massive adoption
4. **Gleam** has type safety on BEAM → 70% admiration (2nd highest)

**Lux's unique pitch**: Effects you can see. Tests you can trust. No mocks needed.

---

## Phase 1: Make Developers Smile (Highest Impact)

### 1.1 Elm-Quality Error Messages
**Why**: Elm's error messages are the #1 reason people recommend it. This is free marketing.

**Current state**: Basic errors with location
**Target state**: Conversational, helpful, with suggestions

```
Current:
  Type error at 5:12: Cannot unify Int with String

Target:
  ── TYPE MISMATCH ─────────────────────────── src/main.lux

  The `age` field expects an Int, but I found a String:

  5│      age: "twenty-five"
               ^^^^^^^^^^^^

  Hint: Did you mean to use String.parseInt?

      age: String.parseInt("twenty-five") |> Option.getOrElse(0)
```

**Implementation**:
- Add error code catalog (E001, E002, etc.)
- "Did you mean?" suggestions using Levenshtein distance
- Show expected vs actual with visual diff
- Context-aware hints based on error type

**Effort**: 2-3 weeks
**Impact**: HIGH - This is what people tweet about

### 1.2 HTTP Framework (Routing + Middleware)
**Why**: Web services are the most common use case. Without this, Lux is a toy.

```lux
// Target API
let app = Router.new()
    |> Router.get("/users", listUsers)
    |> Router.get("/users/:id", getUser)
    |> Router.post("/users", createUser)
    |> Router.use(loggerMiddleware)
    |> Router.use(authMiddleware)

fn main(): Unit with {HttpServer} =
    HttpServer.serve(app, 3000)
```

**Implementation**:
- Path pattern matching with params
- Middleware composition
- Request/Response types
- JSON body parsing integration

**Effort**: 2 weeks
**Impact**: HIGH - Enables real projects

### 1.3 PostgreSQL Driver
**Why**: SQLite is nice for demos, real apps need Postgres/MySQL.

```lux
effect Postgres {
    fn connect(url: String): Connection
    fn query(conn: Connection, sql: String, params: List<Value>): List<Row>
    fn execute(conn: Connection, sql: String, params: List<Value>): Int
    fn transaction<T>(conn: Connection, f: fn(): T with {Postgres}): T
}
```

**Implementation**:
- Native Rust driver (tokio-postgres)
- Connection pooling
- Parameterized queries (SQL injection prevention)
- Transaction support

**Effort**: 2 weeks
**Impact**: HIGH - Enables production backends

---

## Phase 2: Showcase Unique Features

### 2.1 Property-Based Testing Framework
**Why**: This showcases behavioral types - Lux's most unique feature.

```lux
test "reverse is involutive" =
    forAll(listOf(int), fn(xs) =>
        List.reverse(List.reverse(xs)) == xs
    ) is pure is total  // Compiler verifies!

test "sort produces sorted output" =
    forAll(listOf(int), fn(xs) =>
        let sorted = List.sort(xs)
        isSorted(sorted) && sameElements(xs, sorted)
    ) where result is idempotent  // Compiler verifies!
```

**Implementation**:
- Generator combinators (int, string, listOf, oneOf, etc.)
- Shrinking for minimal failing cases
- Integration with behavioral type checker
- Nice failure output

**Effort**: 2 weeks
**Impact**: HIGH - Unique selling point

### 2.2 Schema Evolution Showcase
**Why**: This is unique to Lux. Need a compelling demo.

**Build**: Database migration tool that generates SQL from Lux types

```lux
type User @v1 = { name: String, email: String }
type User @v2 = { name: String, email: String, age: Option<Int> }
    from @v1 = fn(u) => { ...u, age: None }

// Tool generates:
// ALTER TABLE users ADD COLUMN age INTEGER;
```

**Effort**: 1 week
**Impact**: MEDIUM - Differentiator for data teams

### 2.3 Effect Visualization
**Why**: Make the invisible visible. Show effect flow in code.

```
lux visualize src/main.lux

processOrder: Order -> Receipt
  ├── Database.query (line 12)
  │   └── SQL: "SELECT * FROM inventory"
  ├── PaymentGateway.charge (line 18)
  │   └── Amount: order.total
  └── Email.send (line 25)
      └── To: order.customer.email
```

**Effort**: 1 week
**Impact**: MEDIUM - Educational, impressive in demos

---

## Phase 3: Developer Experience Polish

### 3.1 Better REPL
**Why**: First impression matters. REPL is how people try the language.

**Add**:
- Syntax highlighting
- Multi-line editing
- Tab completion for modules
- `:doc` command for documentation
- `:browse Module` to list exports
- Pretty-printed output

**Effort**: 1 week
**Impact**: MEDIUM

### 3.2 LSP Improvements
**Why**: IDE experience is expected in 2025.

**Add**:
- Inlay hints (show inferred types)
- Code actions (import suggestions, fix suggestions)
- Rename symbol
- Find all references
- Semantic highlighting

**Effort**: 2 weeks
**Impact**: MEDIUM

### 3.3 Documentation Generator
**Why**: Rust's docs.rs is beloved. Good docs = adoption.

```lux
/// Calculate the factorial of a number.
///
/// # Examples
/// ```
/// factorial(5)  // => 120
/// ```
///
/// # Properties
/// - factorial(n) is pure
/// - factorial(n) is total for n >= 0
fn factorial(n: Int): Int is pure is total = ...
```

**Effort**: 1 week
**Impact**: MEDIUM

---

## Phase 4: Performance & Production

### 4.1 Performance Benchmarks
**Why**: Need to prove Lux is fast. Numbers matter.

**Targets**:
| Benchmark | Target | Comparison |
|-----------|--------|------------|
| Fibonacci(40) | < 1s | Rust: 0.3s |
| HTTP req/sec | > 50k | Go: 100k |
| JSON parse 1MB | < 50ms | Node: 30ms |

**Effort**: 1 week
**Impact**: MEDIUM - Removes adoption blocker

### 4.2 Production Hardening
**Why**: Memory leaks and crashes kill adoption.

**Add**:
- Memory leak detection in debug mode
- Graceful shutdown handling
- Signal handling (SIGTERM, SIGINT)
- Structured logging

**Effort**: 2 weeks
**Impact**: MEDIUM

---

## Phase 5: Ecosystem Growth

### 5.1 Package Registry
**Why**: Central place to share code.

- Host at packages.lux-lang.org
- `lux pkg publish`
- `lux pkg search`
- Version resolution

**Effort**: 2 weeks
**Impact**: HIGH long-term

### 5.2 Starter Templates
**Why**: Reduce friction for new projects.

```bash
lux new my-api --template web-api
lux new my-cli --template cli-tool
lux new my-lib --template library
```

**Effort**: 1 week
**Impact**: LOW-MEDIUM

---

## Implementation Order (Bang for Buck)

| Priority | Feature | Effort | Impact | Why First |
|----------|---------|--------|--------|-----------|
| P0 | Elm-quality errors | 2-3 weeks | HIGH | Free marketing, retention |
| P0 | HTTP framework | 2 weeks | HIGH | Enables real projects |
| P0 | PostgreSQL driver | 2 weeks | HIGH | Production database |
| P1 | Property testing | 2 weeks | HIGH | Unique selling point |
| P1 | Better REPL | 1 week | MEDIUM | First impression |
| P1 | Performance benchmarks | 1 week | MEDIUM | Removes doubt |
| P2 | LSP improvements | 2 weeks | MEDIUM | Developer experience |
| P2 | Documentation generator | 1 week | MEDIUM | Ecosystem |
| P2 | Schema evolution tool | 1 week | MEDIUM | Differentiator |
| P3 | Effect visualization | 1 week | MEDIUM | Demos |
| P3 | Package registry | 2 weeks | HIGH | Long-term ecosystem |
| P3 | Production hardening | 2 weeks | MEDIUM | Enterprise readiness |

---

## Success Metrics

### Short-term (3 months)
- [ ] 10 example projects building without issues
- [ ] Error messages rated "helpful" by 80% of users
- [ ] HTTP "hello world" benchmark > 30k req/sec
- [ ] 5 external contributors

### Medium-term (6 months)
- [ ] 1000 GitHub stars
- [ ] 50 packages on registry
- [ ] 3 production users
- [ ] 1 conference talk

### Long-term (1 year)
- [ ] Self-hosted compiler
- [ ] 100 packages
- [ ] 10 production users
- [ ] Featured in "State of Developer Ecosystem" survey

---

## What NOT to Build (Yet)

| Feature | Why Skip |
|---------|----------|
| WASM backend | JS backend covers browser use case |
| Mobile targets | Small market, high effort |
| GUI framework | Web handles most UI needs |
| AI/ML libraries | Python dominates, wrong battle |
| Distributed systems | Need core stability first |
| Advanced optimizations | Correctness before speed |

---

## The Pitch After Phase 1

> **Lux**: A functional language where the compiler tells you exactly what your code does.
>
> - **See effects in signatures**: `fn save(user: User): Unit with {Database, Email}`
> - **Test without mocks**: Just swap the handler. No DI framework needed.
> - **Evolve your schemas**: Types track versions. Migrations are code.
> - **Compiler catches more**: Pure, total, idempotent - verified, not hoped.
>
> *Effects you can see. Tests you can trust.*