@xnoxs/flux-lang 3.1.1

package/README.md

@@ -0,0 +1,1089 @@
+# Flux Lang v3.1.1 — TypeScript Parity Edition
+
+**Flux** adalah bahasa pemrograman modern yang di-transpile ke JavaScript — menggabungkan sintaks bersih ala Python (indentasi berbasis blok), tipe statis ala TypeScript, dan ekspresi kuat ala Rust/Haskell.
+
+```
+source.flux  →  [Lexer → Parser → TypeChecker → CodeGen]  →  output.js
+```
+
+---
+
+## Instalasi & Penggunaan
+
+```bash
+# Jalankan langsung
+node bin/flux.js run app.flux
+
+# Compile ke JS
+node bin/flux.js compile app.flux -o dist/app.js
+
+# Type check (temukan kesalahan tipe sebelum runtime)
+node bin/flux.js check app.flux
+
+# Format kode
+node bin/flux.js fmt app.flux
+
+# Jalankan semua test
+node bin/flux.js test tests/
+
+# REPL interaktif
+node bin/flux.js repl
+
+# Bundle beberapa file
+node bin/flux.js bundle main.flux -o bundle.js
+```
+
+---
+
+## Sintaks Dasar
+
+### Variabel
+
+```flux
+val x = 42            // immutable (const)
+var count = 0         // mutable (let)
+
+// Dengan type annotation
+val name: String = "Flux"
+val age: Int = 3
+val score: Float = 9.5
+val active: Bool = true
+val nothing: Null = null
+
+// Tanpa annotation — type diinfer otomatis
+val items = [1, 2, 3]   // infer: Array<Int>
+val greeting = "Hello"   // infer: String
+```
+
+### Print & Template Strings
+
+```flux
+print("Hello, World!")
+print("Dua ditambah dua: {2 + 2}")
+print("Pi: {3.14159:.2f}")     // format spec
+print("Besar: {n:,}")           // separator ribuan
+print("Persen: {rate:.1%}")     // format persen
+```
+
+### Operator
+
+```flux
+// Aritmatika
+val a = 10 + 3    // 13
+val b = 10 - 3    // 7
+val c = 10 * 3    // 30
+val d = 10 / 3    // 3.333...
+val e = 10 % 3    // 1
+val f = 2 ** 10   // 1024
+
+// Perbandingan
+val eq  = a == b    // false
+val neq = a != b    // true
+val lt  = a < b     // false
+
+// Logika
+val and_ = true && false   // false
+val or_  = true || false   // true
+val not_ = !true            // false
+
+// Nullish coalescing
+val result = maybeNull ?? "default"
+
+// Optional chaining
+val len = user?.name?.length
+```
+
+---
+
+## Fungsi
+
+### Deklarasi Dasar
+
+```flux
+// Inline (satu baris)
+fn double(x) -> x * 2
+fn add(a, b) -> a + b
+fn greet(name) -> "Hello, {name}!"
+
+// Block body
+fn factorial(n):
+    if n <= 1: return 1
+    return n * factorial(n - 1)
+```
+
+### Type Annotations
+
+```flux
+// Parameter dan return type
+fn greet(name: String) -> String:
+    return "Hello, {name}!"
+
+fn add(a: Int, b: Int) -> Int:
+    return a + b
+
+fn area(w: Float, h: Float) -> Float:
+    return w * h
+
+// Parameter opsional
+fn greetUser(name: String, title?: String) -> String:
+    val prefix = title ?? ""
+    if prefix != "":
+        return "{prefix} {name}"
+    return name
+```
+
+### Sintaks Return Type
+
+Gunakan `-> ReturnType:` sebelum badan blok fungsi:
+
+```flux
+// Blok body dengan return type annotation
+fn multiply(a: Int, b: Int) -> Int:
+    return a * b
+
+// Inline body (tanpa return type — diinfer otomatis)
+fn square(x) -> x * x
+
+// Nullable return type
+fn findUser(id: Int) -> String?:
+    if id > 0: return "user_{id}"
+    return null
+```
+
+### Tipe Return Khusus
+
+```flux
+// Void — tidak mengembalikan nilai
+fn logMessage(msg: String) -> Void:
+    print(msg)
+
+// Never — selalu melempar error (tidak pernah selesai)
+fn crash(msg: String) -> Never:
+    throw new Error(msg)
+```
+
+### Parameter Rest & Default
+
+```flux
+// Rest parameter
+fn sum(...nums):
+    return nums.reduce((acc, x) -> acc + x, 0)
+
+// Default value
+fn repeat(str: String, times: Int = 3) -> String:
+    return str.repeat(times)
+```
+
+### Fungsi Async
+
+```flux
+async fn fetchData(url: String) -> String:
+    val res = await fetch(url)
+    return await res.text()
+
+async fn main():
+    val data = await fetchData("https://api.example.com")
+    print(data)
+```
+
+### Higher-Order Functions & Lambda
+
+```flux
+// Lambda ekspresi
+val square = x -> x * x
+val add = (a, b) -> a + b
+
+// Fungsi sebagai argumen
+val doubled = [1, 2, 3].map(x -> x * 2)          // [2, 4, 6]
+val evens   = [1, 2, 3, 4, 5].filter(x -> x % 2 == 0)  // [2, 4]
+val total   = [1, 2, 3, 4].reduce((acc, x) -> acc + x, 0)  // 10
+
+// Pipe operator — rantai transformasi
+val result = [1, 2, 3, 4, 5]
+    |> filter(x -> x > 2)
+    |> map(x -> x * 10)
+    |> sum
+```
+
+---
+
+## Tipe Data (Type System)
+
+Flux v3.0.0 memiliki sistem tipe yang diperiksa saat kompilasi (`flux check`). Tipe dihapus pada output JavaScript — sama seperti TypeScript.
+
+### Tipe Primitif
+
+| Tipe      | Deskripsi                    | Contoh                |
+|-----------|------------------------------|-----------------------|
+| `String`  | Teks                         | `"Hello"`, `'World'` |
+| `Int`     | Bilangan bulat               | `42`, `-7`            |
+| `Float`   | Bilangan desimal             | `3.14`, `-0.5`        |
+| `Number`  | Int atau Float               | `100`, `3.14`         |
+| `Bool`    | Benar atau salah             | `true`, `false`       |
+| `Null`    | Nilai null                   | `null`                |
+| `Void`    | Tidak mengembalikan nilai    | return kosong         |
+| `Never`   | Tidak pernah selesai         | throw / infinite loop |
+| `Any`     | Lewati type check            | semua tipe            |
+| `Unknown` | Perlu narrowing dulu         | —                     |
+
+### Union Types
+
+```flux
+val id: Int | String = 42           // Int atau String
+val value: Int | String = "hello"   // juga valid
+
+fn stringify(x: Int | String | Bool) -> String:
+    return "{x}"
+```
+
+### Nullable Types
+
+```flux
+// String? adalah singkatan dari String | Null
+val name: String? = null
+val other: String? = "Flux"
+
+fn findById(id: Int) -> String?:
+    if id > 0: return "item_{id}"
+    return null
+```
+
+### Generic Types
+
+```flux
+val names: Array<String> = ["Andi", "Budi", "Cici"]
+val nums:  Array<Int>    = [1, 2, 3, 4, 5]
+
+fn first(items: Array<String>) -> String?:
+    if items.length == 0: return null
+    return items[0]
+```
+
+---
+
+## Interface
+
+Interface mendefinisikan kontrak yang harus dipenuhi class. `flux check` melaporkan **error** jika ada anggota yang tidak diimplementasi.
+
+```flux
+interface Printable:
+    fn print() -> Void
+
+interface Shape:
+    name: String
+    fn area() -> Float
+    fn perimeter() -> Float
+
+// Interface dengan inheritance
+interface ColoredShape extends Shape:
+    color: String
+    fn setColor(c: String) -> Void
+
+// Generic interface
+interface Container<T>:
+    fn get() -> T
+    fn set(value: T) -> Void
+```
+
+### Class Mengimplementasi Interface
+
+```flux
+class Rectangle implements Shape:
+    name: String
+    width: Float
+    height: Float
+
+    fn area() -> Float:
+        return self.width * self.height
+
+    fn perimeter() -> Float:
+        return 2.0 * (self.width + self.height)
+
+class Circle implements Shape:
+    name: String
+    radius: Float
+
+    fn area() -> Float:
+        return 3.14159 * self.radius * self.radius
+
+    fn perimeter() -> Float:
+        return 2.0 * 3.14159 * self.radius
+
+val r = new Rectangle("Persegi", 5.0, 3.0)
+print(r.area())        // 15
+print(r.perimeter())   // 16
+```
+
+---
+
+## Class
+
+```flux
+class Animal:
+    name: String
+    sound: String
+
+    fn speak() -> String:
+        return "{self.name} says {self.sound}!"
+
+// Inheritance
+class Dog extends Animal:
+    breed: String
+
+    fn info() -> String:
+        return "Dog: {self.name} ({self.breed})"
+
+val dog = new Dog("Rex", "Woof", "Labrador")
+print(dog.speak())   // Rex says Woof!
+print(dog.info())    // Dog: Rex (Labrador)
+```
+
+### Access Modifiers
+
+```flux
+class BankAccount:
+    private balance: Float
+    readonly owner: String
+
+    fn deposit(amount: Float) -> Void:
+        self.balance += amount
+
+    fn getBalance() -> Float:
+        return self.balance
+```
+
+---
+
+## Algebraic Data Types (ADT)
+
+```flux
+// Definisi
+type Option = Some(value) | None
+type Result = Ok(value) | Err(message)
+type Shape  = Circle(radius) | Rectangle(w, h) | Triangle(base, height)
+```
+
+### Pattern Matching dengan ADT
+
+```flux
+fn safeDivide(a: Float, b: Float) -> Result:
+    if b == 0.0: return Err("Division by zero")
+    return Ok(a / b)
+
+val result = safeDivide(10.0, 2.0)
+
+match result:
+    when Ok(v)  -> print("Result: {v}")
+    when Err(e) -> print("Error: {e}")
+
+// Dengan guard
+match result:
+    when Ok(v) if v > 0 -> print("Positive: {v}")
+    when Ok(v)           -> print("Non-positive: {v}")
+    when Err(e)          -> print("Error: {e}")
+```
+
+---
+
+## Enum
+
+```flux
+enum Direction:
+    North = 0
+    South = 1
+    East  = 2
+    West  = 3
+
+enum Status:
+    Active
+    Inactive
+    Pending
+
+print(Direction.North)   // 0
+print(Status.Active)     // 0
+```
+
+---
+
+## Kontrol Alur
+
+### If / Else
+
+```flux
+if x > 0:
+    print("positif")
+else if x < 0:
+    print("negatif")
+else:
+    print("nol")
+```
+
+### For / While / Do-While
+
+```flux
+// Iterasi array
+for item in items:
+    print(item)
+
+// Range
+for i in 0..10:
+    print(i)
+
+// While
+var n = 10
+while n > 0:
+    print(n)
+    n -= 1
+
+// Do-while
+do:
+    print("minimal sekali")
+while false
+```
+
+### Match (Pattern Matching)
+
+```flux
+match nilai:
+    when 0       -> print("nol")
+    when 1..9    -> print("satu digit")
+    when 10..99  -> print("dua digit")
+    when _       -> print("lainnya")
+
+// Match dengan guard
+match score:
+    when s if s >= 90 -> print("A")
+    when s if s >= 80 -> print("B")
+    when s if s >= 70 -> print("C")
+    when _            -> print("D")
+```
+
+---
+
+## Error Handling
+
+```flux
+// Try / Catch / Finally
+try:
+    val data = JSON.parse(input)
+    print(data)
+catch(e):
+    print("Error: {e.message}")
+finally:
+    print("Selesai")
+
+// Throw
+fn validateAge(age: Int) -> Void:
+    if age < 0:
+        throw new Error("Usia tidak boleh negatif: {age}")
+
+// Dengan ADT Result
+type Result = Ok(value) | Err(message)
+
+fn parseNumber(s: String) -> Result:
+    val n = parseInt(s, 10)
+    if isNaN(n): return Err("Bukan angka: {s}")
+    return Ok(n)
+```
+
+---
+
+## Destructuring
+
+```flux
+// Object destructuring
+val person = { name: "Budi", age: 25, city: "Jakarta" }
+val { name, age, city } = person
+
+// Dengan alias
+val { name: personName, age: personAge } = person
+
+// Array destructuring
+val [first, second, ...rest] = [1, 2, 3, 4, 5]
+
+// Dengan default value
+val { title = "Tanpa Judul", content } = post
+```
+
+---
+
+## Import / Export
+
+```flux
+// Import default
+import express from 'express'
+
+// Import named
+import { readFileSync, writeFileSync } from 'fs'
+
+// Import namespace
+import * as path from 'path'
+
+// Export
+export fn calculateTax(amount: Float, rate: Float) -> Float:
+    return amount * rate
+
+export default fn main():
+    print("Hello from main!")
+```
+
+---
+
+## Interop dengan npm
+
+Flux di-transpile ke JavaScript — semua package npm dapat digunakan langsung:
+
+```flux
+import express from 'express'
+import { readFileSync } from 'fs'
+
+val app = express()
+
+app.get("/", fn(req, res):
+    res.json({ status: "ok", lang: "Flux" })
+)
+
+app.listen(3000, fn():
+    print("Server Flux berjalan di port 3000")
+)
+```
+
+---
+
+## JSX (React)
+
+```flux
+// Server-side JSX
+val heading = <h1 class="title">Hello Flux!</h1>
+val card = <div class="card">
+    <h2>{title}</h2>
+    <p>{description}</p>
+</div>
+```
+
+---
+
+## CSS Preprocessor
+
+```flux
+val styles = css`
+    .button {
+        background: var(--primary);
+        border-radius: 8px;
+        padding: 8px 16px;
+
+        &:hover {
+            opacity: 0.9;
+        }
+    }
+`
+```
+
+---
+
+## Perintah CLI
+
+| Perintah                        | Deskripsi                                            |
+|---------------------------------|------------------------------------------------------|
+| `flux init [nama]`              | Buat project Flux baru                               |
+| `flux compile file.flux`        | Compile ke JavaScript                                |
+| `flux compile file.flux -o out` | Compile ke file output tertentu                      |
+| `flux bundle main.flux`         | Bundle semua import menjadi satu file                |
+| `flux run file.flux`            | Compile dan langsung jalankan                        |
+| `flux watch file.flux`          | Pantau perubahan dan compile otomatis                |
+| `flux check file.flux`          | **Type check** + analisis statis                     |
+| `flux lint file.flux`           | **Lint** — unused vars, unreachable code, shadowing  |
+| `flux fmt file.flux`            | Format kode sumber                                   |
+| `flux test [dir]`               | Temukan dan jalankan file `*.test.flux`              |
+| `flux tokens file.flux`         | Tampilkan daftar token dari lexer                    |
+| `flux ast file.flux`            | Tampilkan AST dalam format JSON                      |
+| `flux repl`                     | Mode REPL interaktif                                 |
+| `flux version`                  | Tampilkan versi                                      |
+
+### Flag
+
+```
+--out, -o <file>    File output
+--sourcemap, -m     Hasilkan source map (.js.map)
+--stdout            Cetak output ke terminal
+--no-color          Nonaktifkan warna
+```
+
+---
+
+## Sistem Tipe — TypeScript Parity
+
+Flux v3.1.0 memiliki sistem tipe yang setara dengan TypeScript. Berikut fitur lengkapnya:
+
+### Intersection Types (`A & B`)
+
+```flux
+interface Named:
+    name: String
+
+interface Aged:
+    age: Int
+
+// Intersection: class harus memenuhi SEMUA interface
+class Person implements Named, Aged:
+    name: String
+    age: Int
+```
+
+### Tuple Types
+
+```flux
+fn getCoord() -> [Float, Float]:
+    return [3.14, 2.71]
+
+fn parseKV(pair: String) -> [String, String]:
+    val parts = pair.split("=")
+    return [parts[0], parts[1]]
+
+val [lat, lng] = getCoord()        // destructure tuple
+val [key, val_] = parseKV("a=b")
+```
+
+### Inline Object Types
+
+```flux
+fn makePoint(x: Float, y: Float) -> { x: Float, y: Float }:
+    return { x, y }
+
+fn distance(p1: { x: Float, y: Float }, p2: { x: Float, y: Float }) -> Float:
+    val dx = p1.x - p2.x
+    val dy = p1.y - p2.y
+    return Math.sqrt(dx * dx + dy * dy)
+```
+
+### Structural Typing
+
+```flux
+interface Printable:
+    fn toString() -> String
+
+// Tidak perlu implements jika shape cocok (duck typing)
+class Config implements Printable:
+    key: String
+    fn toString() -> String -> "Config({self.key})"
+```
+
+### Type Narrowing via Control Flow
+
+```flux
+fn getUser(id: Int) -> String?:
+    if id > 0: return "User_{id}"
+    return null
+
+val user = getUser(1)
+
+// Flux mengecilkan tipe di dalam blok null-check
+if user != null:
+    print(user.toUpperCase())   // OK — user adalah String di sini, bukan String?
+
+// typeof narrowing
+fn process(x: Int | String | Bool) -> String:
+    if typeof x == "number": return "num: {x}"
+    if typeof x == "string": return "str: {x}"
+    return "bool: {x}"
+```
+
+### Function Types
+
+```flux
+// Anotasi tipe fungsi sebagai parameter
+fn mapInts(arr: Array<Int>, f: fn(Int) -> Int) -> Array<Int>:
+    return arr.map(f)
+
+fn double(x: Int) -> Int:
+    return x * 2
+
+val results = mapInts([1, 2, 3], double)
+
+// Tipe fungsi di interface
+interface Handler:
+    fn handle(req: String) -> String
+```
+
+### `keyof` & `typeof` di Tipe
+
+```flux
+// keyof T — union dari semua key interface
+fn getField(key: keyof Config) -> String:
+    return key
+
+// typeof x — tipe dari variabel
+val config = new Config("host", "localhost")
+fn cloneConfig(src: typeof config) -> typeof config:
+    return new Config(src.key, src.value)
+```
+
+### Utility Types
+
+```flux
+// Semua utility type TypeScript tersedia:
+fn setPartial(opts: Partial<Config>) -> Void:
+    // semua field optional
+    pass
+
+fn setRequired(opts: Required<Config>) -> Void:
+    // semua field wajib
+    pass
+
+fn makeReadonly(opts: Readonly<Config>) -> Void:
+    // tidak bisa diubah
+    pass
+
+// Record<K, V> — dictionary type
+fn buildMap(keys: Array<String>) -> Record<String, Int>:
+    return {}
+
+// NonNullable<T> — hapus null dari union
+fn safeGet(x: NonNullable<String?>) -> String:
+    return x
+
+// ReturnType<T> — extract return type
+// Pick<T, K>, Omit<T, K>, Exclude<T, U>, Extract<T, U>
+// Awaited<T>, Parameters<T>, InstanceType<T>
+```
+
+### Index Signatures
+
+```flux
+// { [key: String]: T } — map arbitrary keys to type
+fn buildRegistry() -> { [key: String]: String }:
+    return { name: "Flux", version: "3.1.0" }
+```
+
+### Generic Type Parameters di ADT
+
+```flux
+// Type parameter <T> di ADT declarations
+type Result<T> = Ok(value) | Err(message)
+type Option<T> = Some(value) | None
+type Either<L, R> = Left(value) | Right(value)
+
+fn safeDivide(a: Float, b: Float) -> Result:
+    if b == 0.0: return Err("Division by zero")
+    return Ok(a / b)
+```
+
+---
+
+## `flux check` — Type Checker
+
+Perintah `flux check` menjalankan tiga lapisan:
+
+1. **Syntax check** — pastikan kode bisa diparse
+2. **Val immutability** — cegah reassignment `val`
+3. **Type checker** — periksa tipe annotations, return types, interface implementations, dan type narrowing
+
+### Contoh Output
+
+```
+$ flux check app.flux
+
+✗ app.flux: 2 type error(s)
+
+  [TypeError]:12:5  Type 'Int' is not assignable to 'name: String'
+             hint: Change the value to match type 'String', or update the annotation
+    12 │ val name: String = 42
+       │     ^
+
+  [TypeError]:28:1  Class 'Cat' does not implement method 'area()' required by interface 'Shape'
+             hint: Add 'fn area()' to the class
+
+✗ app.flux — 2 type errors
+  Functions: 5  |  Classes: 2  |  JS output: 47 lines
+```
+
+### Hal yang Diperiksa
+
+| Pemeriksaan                   | Contoh yang ditangkap                                     |
+|-------------------------------|-----------------------------------------------------------|
+| Mismatch tipe variabel        | `val name: String = 42` → error                          |
+| Return type mismatch          | `fn f() -> Int: return "hello"` → error                  |
+| Interface tidak diimplementasi| class tidak punya method yang diwajibkan interface        |
+| Val reassignment              | `val x = 1; x = 2` → error                              |
+| Nullable / union assignability| `val x: Int = null` → error                              |
+
+---
+
+## `flux lint` — Linter
+
+Perintah `flux lint` menjalankan **semua** lapisan pemeriksaan `flux check`, ditambah tiga aturan AST-level yang menangkap masalah logika tanpa melihat tipe:
+
+| Lapisan | Aturan | Keparahan |
+|---------|--------|-----------|
+| Syntax  | Parse errors | Error (fatal) |
+| Immutability | Reassignment `val` | Error |
+| Type checker | Mismatch tipe, interface | Error |
+| **unused-var** | `val`/`var` dideklarasi tapi tidak pernah dibaca | Warning |
+| **unreachable** | Statement setelah `return`/`throw`/`break` | Error |
+| **shadow-val** | `val x` di scope dalam menutupi `val x` di scope luar | Warning |
+| Format | File tidak terformat | Warning |
+| Style | Baris terlalu panjang (>120 karakter), TODO/FIXME | Info |
+
+### Perbedaan `flux check` vs `flux lint`
+
+| | `flux check` | `flux lint` |
+|-|---|---|
+| Type errors | ✓ | ✓ |
+| Immutability | ✓ | ✓ |
+| **Unused variables** | ✗ | ✓ |
+| **Unreachable code** | ✗ | ✓ |
+| **Variable shadowing** | ✗ | ✓ |
+| Format check | ✗ | ✓ |
+
+### Contoh Output
+
+```
+$ flux lint app.flux
+
+⊛ Linting: app.flux
+
+  [E] unreachable:15:5  Unreachable code after 'return'
+         hint: Remove or move the unreachable statement
+    15 │     val dead = 99
+       │     ^
+
+  [W] unused-var:8:5  'temp' is declared but never used
+         hint: Prefix with '_' (e.g. '_temp') to silence this warning, or remove the declaration
+     8 │     val temp = calculate()
+       │     ^
+
+  [W] shadow-val:22:9  'x' shadows an outer declaration
+         hint: Rename one of the 'x' variables to avoid confusion
+    22 │         val x = 0
+       │         ^
+
+──────────────────────────────────────────────────
+✗ app.flux — 3 issue(s) (45 lines)
+```
+
+### Cara Menonaktifkan Warning Tertentu
+
+Prefiks nama variabel dengan `_` untuk menonaktifkan `unused-var` dan `shadow-val`:
+
+```flux
+val _ignored = sideEffect()   // tidak dilaporkan unused
+fn process(_unused, value):   // param tidak dilaporkan unused
+    return value * 2
+```
+
+---
+
+## Bug Fixes & Riwayat Perubahan
+
+### v3.1.1 — Perbaikan Bug (Juni 2026)
+
+Empat bug ditemukan melalui analisis statis dan dibuktikan dengan test sebelum diperbaiki. Semua perubahan diverifikasi dengan suite test penuh (71 test, 0 gagal).
+
+---
+
+#### Bug #1 — `codegen.js`: Wildcard arm pertama menghasilkan `else {` tanpa `if`
+
+**Dampak:** `SyntaxError` runtime di JavaScript — kode tidak bisa dijalankan sama sekali.
+
+**Penyebab:** `genMatch` di `src/codegen.js` menghasilkan `else {` untuk arm wildcard, tetapi jika wildcard adalah arm *pertama*, tidak ada `if` sebelumnya → JS tidak valid.
+
+**Sebelum:**
+```javascript
+// Jika wildcard adalah arm pertama, menghasilkan:
+else {        // ← SyntaxError: tidak ada `if` sebelumnya
+  return "matched";
+}
+```
+
+**Sesudah:** Ditambahkan flag `hasOpenIf` — arm wildcard pertama menghasilkan `if (true) {` sehingga JS tetap valid.
+
+```flux
+// Kode Flux ini sekarang berfungsi benar:
+fn classify(x):
+    match x:
+        when _ -> "default"
+        when 1 -> "one"
+```
+
+---
+
+#### Bug #2 — `stdlib.js`: `truncate` menghasilkan string terlalu panjang jika suffix ≥ len
+
+**Dampak:** Hasil `truncate` melebihi panjang yang diminta.
+
+**Penyebab:** `slice(0, len - suffix.length)` menghasilkan indeks negatif jika `suffix.length >= len`, yang diinterpretasi JavaScript sebagai `slice(0, negatif)` → mengembalikan karakter dari akhir string alih-alih awal.
+
+**Sebelum:**
+```javascript
+return str.slice(0, len - suffix.length) + suffix;
+// truncate("hello world", 3, "......") → hasil > 3 karakter ❌
+```
+
+**Sesudah:** Ditambahkan guard — jika `suffix.length >= len`, kembalikan `suffix.slice(0, len)`:
+```javascript
+const cut = len - suffix.length;
+if (cut <= 0) return suffix.slice(0, len);
+return str.slice(0, cut) + suffix;
+// truncate("hello world", 3, "......") → "..." (3 karakter) ✓
+```
+
+---
+
+#### Bug #3 — `parser.js`: `(a, b, c)` tanpa `->` diam-diam membuang nilai
+
+**Dampak:** Nilai di posisi 1, 2, ... dalam ekspresi kurung banyak diam-diam hilang tanpa pesan error apapun — sangat sulit di-debug.
+
+**Penyebab:** Parser membangun `items[]` dari ekspresi berkoma di dalam `(...)`, tetapi jika tidak ada `->` (bukan lambda), ia mengembalikan `items[0]` saja.
+
+**Sebelum:**
+```flux
+val x = (10, 20, 30)
+// Dikompilasi menjadi: const x = 10;  ← 20 dan 30 hilang diam-diam
+```
+
+**Sesudah:** Jika `items.length > 1` tanpa `->`, ParseError yang jelas dilempar:
+```
+ParseError: Unexpected comma in expression — did you mean a lambda?
+  Write (p0, p1, p2) -> expr
+```
+
+---
+
+#### Bug #4 — `parser.js`: Auto-index enum tidak direset setelah nilai eksplisit
+
+**Dampak:** Member enum setelah nilai eksplisit mendapat indeks yang salah.
+
+**Penyebab:** `autoIndex` hanya dimulai dari 0 dan naik +1, tanpa pernah mengambil nilai dari assignment eksplisit `member = N`.
+
+**Sebelum:**
+```flux
+enum Color:
+    Red          // 0 ✓
+    Green = 10   // 10 ✓
+    Blue         // 2 ❌ (seharusnya 11)
+```
+
+**Sesudah:** Setelah nilai eksplisit `N`, `autoIndex` diatur ke `N` sehingga member berikutnya mendapat `N + 1`:
+```flux
+enum Color:
+    Red          // 0 ✓
+    Green = 10   // 10 ✓
+    Blue         // 11 ✓
+```
+
+---
+
+#### Regresi
+
+Semua 4 perbaikan diverifikasi tidak merusak test yang ada:
+
+| Suite | Test | Hasil |
+|-------|------|-------|
+| `01_basics` — `09_ts_compat` | 53 test | ✅ Semua lulus |
+| `10_bugfixes` (baru) | 18 test | ✅ Semua lulus |
+| `prove_bugs.js` (bukti bug) | 7 test | ✅ Semua lulus |
+
+---
+
+## Arsitektur Transpiler
+
+```
+Flux Source (.flux)
+    │
+    ▼
+[CSS Preprocessor]     css`...` → string template
+    │
+    ▼
+[JSX Preprocessor]     <div>...</div> → createElement(...)
+    │
+    ▼
+[Lexer]                Source → Token stream
+    │
+    ▼
+[Parser]               Tokens → AST (Abstract Syntax Tree)
+    │
+    ├──▶ [Val Checker]      AST → immutability errors
+    │
+    ├──▶ [Type Checker]     AST → type errors & warnings
+    │
+    ▼
+[Code Generator]       AST → JavaScript output
+    │
+    ▼
+JavaScript (.js)       Siap dijalankan di Node.js / browser
+```
+
+---
+
+## Perbedaan dengan TypeScript
+
+| Fitur                    | TypeScript         | Flux Lang                       |
+|--------------------------|--------------------|---------------------------------|
+| Sintaks                  | C-style `{}`       | Indentasi (Python-style)        |
+| Type annotations         | `x: string`        | `x: String`                     |
+| Return type              | `(): string {}`    | `() -> String:`                 |
+| Union types              | `string \| number` | `String \| Int`                 |
+| Nullable                 | `string \| null`   | `String?`                       |
+| Pattern matching         | Tidak ada          | `match / when`                  |
+| ADT                      | Tidak ada          | `type Result = Ok(v) \| Err(e)` |
+| Pipe operator            | Tidak ada          | `\|>` (F# style)               |
+| Template strings         | `` `${x}` ``       | `"{x}"`                         |
+| Format spec              | Tidak ada          | `"{n:.2f}"`, `"{n:,}"`         |
+| Val (immutable)          | `const`            | `val`                           |
+| Var (mutable)            | `let`              | `var`                           |
+| npm interop              | Ya                 | Ya (100% kompatibel)            |
+| Transpiler output        | `.js`              | `.js`                           |
+
+---
+
+## Contoh Lengkap — Server HTTP
+
+```flux
+import express from 'express'
+
+type Result = Ok(data) | Err(message)
+
+interface User:
+    id: Int
+    name: String
+    email: String
+
+fn validateEmail(email: String) -> Bool:
+    return email.includes("@")
+
+fn createUser(id: Int, name: String, email: String) -> Result:
+    if !validateEmail(email):
+        return Err("Email tidak valid: {email}")
+    return Ok({ id, name, email })
+
+val app = express()
+app.use(express.json())
+
+var users = []
+
+app.post("/users", fn(req, res):
+    val { id, name, email } = req.body
+    val result = createUser(id, name, email)
+
+    match result:
+        when Ok(user):
+            users.push(user)
+            res.json({ success: true, user })
+        when Err(msg):
+            res.status(400).json({ error: msg })
+)
+
+app.get("/users", fn(req, res):
+    res.json({ users, count: users.length })
+)
+
+app.listen(3000, fn():
+    print("Server Flux berjalan di port 3000")
+)
+```
+
+---
+
+## Lisensi
+
+MIT — Flux Lang v3.0.0