@xnoxs/flux-lang 3.4.0 → 3.4.2

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.4.2] — 2026-06-25
+
+### Added
+- **`## Flux Ecosystem`** — tabel + diagram ASCII lengkap semua 18 modul, perintah yang terkait, dan fungsinya
+- **`## flux.json — Konfigurasi Proyek`** — dokumentasi lengkap setiap field (name, version, entry, outDir, sourcemap, typecheck, mangle, jsx, jsxTarget, ignore, scripts, dependencies, devDependencies), tabel referensi, prioritas konfigurasi, dan penggunaan `flux.local.json`
+- **`## Dari Nol ke Production`** — panduan 10-langkah lengkap: instalasi → init → run → tulis kode → type check & lint → test → bundle → deploy (Node.js / Vercel / Railway / Render / Cloudflare Workers) → manajemen dependensi → ringkasan alur kerja
+- README versi bumped ke v3.4.1
+
+### Changed
+- `package.json` version bumped ke `3.4.2`
+
+---
+
 ## [3.4.0] — 2026-06-25
 
 ### Added

package/README.md

@@ -1,4 +1,4 @@
-# ⚡ Flux Lang v3.4.0
+# ⚡ Flux Lang v3.4.1
 
 **Flux** is a modern programming language that transpiles to clean JavaScript — combining Python-style indentation, TypeScript-grade type safety, Rust-inspired pattern matching, and a rich standard library — all with **zero runtime overhead**.
 
@@ -91,6 +91,464 @@ console.log(result.output);
 
 ---
 
+## Flux Ecosystem
+
+Flux bukan hanya sebuah bahasa — ia hadir dengan ekosistem lengkap yang semuanya ditulis dalam Flux sendiri.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        FLUX ECOSYSTEM v3.4                          │
+├─────────────────────────┬───────────────────────────────────────────┤
+│  Compiler Pipeline      │  Toolchain                                │
+│  ─────────────────      │  ─────────────────                        │
+│  css-preprocessor.flux  │  formatter.flux  → flux fmt               │
+│  jsx.flux               │  linter.flux     → flux lint              │
+│  lexer.flux             │  bundler.flux    → flux bundle            │
+│  parser.flux            │  test-runner.flux→ flux test              │
+│  checker.flux           │  sourcemap.flux  → .js.map generation     │
+│  type-checker.flux      │  mangler.flux    → minification           │
+│  codegen.flux           │  stdlib.flux     → standard library       │
+│  transpiler.flux        │                                           │
+├─────────────────────────┴───────────────────────────────────────────┤
+│  Ecosystem Tools (baru di v3.4)                                     │
+│  ─────────────────────────────                                      │
+│  config.flux   → membaca flux.json, validasi skema proyek           │
+│  pkg.flux      → package manager (flux add / install / publish)     │
+│  cli.flux      → seluruh CLI flux ditulis dalam Flux itu sendiri    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Deskripsi Setiap Komponen
+
+| Modul | Perintah | Fungsi |
+|---|---|---|
+| `lexer.flux` | — | Mengubah source code menjadi token (angka, kata kunci, operator, dll.) |
+| `parser.flux` | — | Mengubah token menjadi AST (Abstract Syntax Tree) |
+| `checker.flux` | `flux check` | Analisis semantik: scope, variabel tak terdeklarasi, penggunaan salah |
+| `type-checker.flux` | `flux check` | Inferensi & pengecekan tipe secara statis |
+| `codegen.flux` | — | Mengubah AST menjadi kode JavaScript |
+| `transpiler.flux` | — | Koordinator pipeline penuh: lexer → parser → checker → codegen |
+| `jsx.flux` | — | Transform JSX ke `h(...)` calls (target: browser / server / react) |
+| `css-preprocessor.flux` | — | Substitusi variabel CSS, nesting, di-embed dalam Flux |
+| `formatter.flux` | `flux fmt` | Memformat kode Flux ke gaya kanonik |
+| `linter.flux` | `flux lint` | Deteksi: variabel tak dipakai, shadowing, kode tak terjangkau |
+| `bundler.flux` | `flux bundle` | Menyatukan semua `import` menjadi satu file `.js` |
+| `sourcemap.flux` | `--sourcemap` | Membuat file `.js.map` (spec V3) untuk debugging di browser |
+| `mangler.flux` | `--mangle` | Obfuskasi nama identifier untuk output yang lebih kecil |
+| `stdlib.flux` | otomatis | 80+ fungsi standar — hanya yang dipakai yang di-inject (tree-shaking) |
+| `test-runner.flux` | `flux test` | Menemukan dan menjalankan semua `*.test.flux` |
+| `config.flux` | otomatis | Membaca dan memvalidasi `flux.json` dari direktori proyek |
+| `pkg.flux` | `flux add/install` | Package manager Flux — mengelola dependensi di `flux.json` |
+| `cli.flux` | `flux` | Seluruh antarmuka command-line, ditulis dalam Flux |
+
+---
+
+## `flux.json` — Konfigurasi Proyek
+
+`flux.json` adalah file konfigurasi di root proyek Flux. File ini dibaca secara otomatis oleh semua perintah `flux`. Buat dengan `flux init` atau buat manual.
+
+```json
+{
+  "name": "nama-proyek",
+  "version": "1.0.0",
+  "description": "Deskripsi proyek",
+  "author": "Nama Kamu",
+  "license": "MIT",
+
+  "entry": "src/main.flux",
+  "outDir": "dist",
+
+  "sourcemap": false,
+  "typecheck": true,
+  "mangle":    false,
+  "jsx":       false,
+  "jsxTarget": "browser",
+
+  "ignore": ["tests/fixtures/**", "vendor/**"],
+
+  "scripts": {
+    "start": "flux run src/main.flux",
+    "build": "flux bundle src/main.flux -o dist/bundle.js",
+    "dev":   "flux watch src/main.flux",
+    "check": "flux check src/main.flux",
+    "test":  "flux test tests/",
+    "fmt":   "flux fmt src/",
+    "lint":  "flux lint src/"
+  },
+
+  "dependencies": {
+    "express": "^4.18.0"
+  },
+  "devDependencies": {
+    "@xnoxs/flux-lang": "^3.4.1"
+  }
+}
+```
+
+### Referensi Lengkap Setiap Field
+
+| Field | Tipe | Default | Keterangan |
+|---|---|---|---|
+| `name` | `string` | wajib | Nama paket/proyek |
+| `version` | `string` | `"1.0.0"` | Versi semver |
+| `description` | `string` | `""` | Deskripsi singkat |
+| `author` | `string` | `""` | Nama penulis |
+| `license` | `string` | `"MIT"` | Jenis lisensi |
+| `entry` | `string` | `"src/main.flux"` | Entry point default untuk `flux bundle` |
+| `outDir` | `string` | `"dist"` | Direktori output kompilasi |
+| `sourcemap` | `boolean` | `false` | Generate file `.js.map` (untuk debugging di browser DevTools) |
+| `typecheck` | `boolean` | `true` | Jalankan type checker saat kompilasi |
+| `mangle` | `boolean` | `false` | Obfuskasi nama identifier — membuat output lebih kecil |
+| `jsx` | `boolean` | `false` | Aktifkan mode JSX untuk file `.flux` yang berisi JSX |
+| `jsxTarget` | `"browser"\|"server"\|"react"` | `"browser"` | Target JSX transform |
+| `ignore` | `string[]` | `[]` | Pola glob yang diabaikan oleh `flux test` |
+| `scripts` | `object` | `{}` | Perintah yang bisa dijalankan dengan `flux run <nama>` |
+| `dependencies` | `object` | `{}` | Dependensi runtime (kompatibel dengan npm) |
+| `devDependencies` | `object` | `{}` | Dependensi pengembangan saja |
+
+### Prioritas Konfigurasi
+
+Nilai dari sumber yang lebih tinggi **selalu menimpa** yang lebih rendah:
+
+```
+flux.json  <  flux.local.json  <  flag CLI
+(terendah)                       (tertinggi)
+```
+
+Contoh: `flux bundle src/main.flux --mangle --sourcemap` akan mengaktifkan mangle dan sourcemap meski `flux.json` menyetel keduanya ke `false`.
+
+### `flux.local.json` — Override Lokal
+
+Buat `flux.local.json` (jangan di-commit ke git) untuk override lokal:
+
+```json
+{
+  "sourcemap": true,
+  "jsxTarget": "server"
+}
+```
+
+Tambahkan ke `.gitignore`:
+```
+flux.local.json
+```
+
+---
+
+## Dari Nol ke Production
+
+Panduan lengkap membuat, mengembangkan, dan men-deploy proyek Flux.
+
+### 1. Instalasi
+
+```bash
+# Install Flux secara global
+npm install -g @xnoxs/flux-lang
+
+# Verifikasi instalasi
+flux version
+# flux-lang v3.4.1
+```
+
+### 2. Buat Proyek Baru
+
+```bash
+flux init nama-proyek
+cd nama-proyek
+```
+
+Struktur yang dibuat:
+
+```
+nama-proyek/
+├── src/
+│   ├── main.flux        ← entry point utama
+│   └── utils.flux       ← fungsi utilitas (contoh ekspor modul)
+├── tests/
+│   └── main.test.flux   ← suite test siap jalan
+├── flux.json            ← konfigurasi proyek
+├── .gitignore
+└── README.md
+```
+
+### 3. Jalankan Proyek
+
+```bash
+# Jalankan langsung (compile + execute sekaligus)
+flux run src/main.flux
+
+# Mode watch — auto-compile setiap ada perubahan file
+flux watch src/main.flux
+```
+
+### 4. Tulis Kode
+
+Buka `src/main.flux` dan mulai menulis. Beberapa fitur yang bisa dipakai langsung:
+
+```flux
+// src/main.flux
+
+// Variabel immutable dan mutable
+val nama = "Flux"
+var hitung = 0
+
+// Fungsi dengan tipe
+fn sapa(siapa: String) -> String:
+    return "Halo, {siapa}!"
+
+// ADT + pattern matching
+type Hasil = Ok(nilai) | Err(pesan)
+
+fn bagi(a, b):
+    if b == 0: return Err("pembagian dengan nol")
+    return Ok(a / b)
+
+match bagi(10, 3):
+    when Ok(v):  print("Hasil: {v:.2f}")
+    when Err(e): print("Error: {e}")
+
+// Pipe operator
+val angka = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+val hasilAkhir = angka
+    |> filter(n -> n % 2 == 0)    // [2, 4, 6, 8, 10]
+    |> map(n -> n * n)             // [4, 16, 36, 64, 100]
+    |> sum                         // 220
+
+print("Jumlah kuadrat genap: {hasilAkhir}")
+```
+
+### 5. Type Check & Lint
+
+```bash
+# Cek tipe dan analisis statis
+flux check src/main.flux
+
+# Lint — cari masalah kode
+flux lint src/main.flux
+
+# Format kode ke gaya kanonik
+flux fmt src/
+```
+
+Contoh output `flux check`:
+```
+✓ src/main.flux — no errors (12 bindings checked)
+```
+
+Contoh output `flux lint`:
+```
+src/main.flux:15  warn  variabel 'x' dideklarasikan tapi tidak dipakai
+src/main.flux:23  warn  kode setelah 'return' tidak dapat dijangkau
+```
+
+### 6. Tulis dan Jalankan Test
+
+File test menggunakan konvensi `fn test_nama()`:
+
+```flux
+// tests/main.test.flux
+
+fn add(a, b): return a + b
+
+fn test_add():
+    assert(add(1, 2) == 3, "1+2=3")
+    assert(add(-1, 1) == 0, "cancel out")
+
+fn test_string():
+    val s = "Hello, Flux!"
+    assert(s.length == 12, "panjang string")
+    assert(s.startsWith("Hello"), "diawali Hello")
+```
+
+```bash
+# Jalankan semua test di folder tests/
+flux test tests/
+
+# Jalankan file test tertentu
+flux test tests/main.test.flux
+```
+
+Output:
+```
+◈ main.test.flux
+  ✓ add
+  ✓ string
+
+Results: 2 passed, 0 failed (2 total) in 14ms
+```
+
+### 7. Bundle untuk Production
+
+```bash
+# Bundle semua import menjadi satu file
+flux bundle src/main.flux -o dist/bundle.js
+
+# Bundle dengan minifikasi (mangle + no sourcemap)
+flux bundle src/main.flux -o dist/bundle.min.js --mangle
+
+# Bundle dengan sourcemap (untuk debugging)
+flux bundle src/main.flux -o dist/bundle.js --sourcemap
+```
+
+`dist/bundle.js` adalah file JavaScript murni — tidak butuh runtime khusus, langsung bisa dijalankan di Node.js atau browser.
+
+### 8. Deploy ke Production
+
+#### Deploy sebagai aplikasi Node.js
+
+```bash
+# Build
+flux bundle src/server.flux -o dist/server.js --mangle
+
+# Jalankan
+node dist/server.js
+```
+
+Contoh `src/server.flux`:
+
+```flux
+import http from 'http'
+import { createServer } from 'http'
+
+val PORT = process.env.PORT ?? 3000
+
+type Route = { method: String, path: String, handler: Function }
+
+fn handleRequest(req, res):
+    val url = req.url ?? "/"
+    val method = req.method ?? "GET"
+
+    if method == "GET" and url == "/":
+        res.writeHead(200, { "Content-Type": "text/plain" })
+        res.end("⚡ Flux App berjalan!\n")
+        return
+
+    if method == "GET" and url == "/health":
+        res.writeHead(200, { "Content-Type": "application/json" })
+        res.end(JSON.stringify({ status: "ok", version: "1.0.0" }))
+        return
+
+    res.writeHead(404, { "Content-Type": "text/plain" })
+    res.end("404 Not Found\n")
+
+val server = http.createServer(handleRequest)
+server.listen(PORT, fn():
+    print("Server berjalan di port {PORT}")
+)
+```
+
+#### Deploy ke Vercel / Railway / Render
+
+Tambahkan ke `package.json` yang sudah ada, atau buat baru:
+
+```json
+{
+  "name": "nama-proyek",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "flux bundle src/server.flux -o dist/server.js --mangle",
+    "start": "node dist/server.js"
+  },
+  "devDependencies": {
+    "@xnoxs/flux-lang": "^3.4.1"
+  }
+}
+```
+
+```bash
+# Vercel
+vercel --prod
+
+# Railway
+railway up
+
+# Render — set build command: npm run build
+#         set start command: npm start
+```
+
+#### Deploy ke Cloudflare Workers (browser bundle)
+
+```bash
+# Bundle target browser
+flux bundle src/worker.flux -o dist/worker.js --mangle
+
+# Deploy via Wrangler
+wrangler deploy dist/worker.js
+```
+
+### 9. Manajemen Dependensi
+
+```bash
+# Tambah dependensi runtime
+flux add express
+flux add axios@1.6.0
+
+# Tambah devDependency
+flux add typescript --dev
+
+# Install semua dari flux.json
+flux install
+
+# Lihat daftar dependensi terinstal
+flux list
+
+# Hapus dependensi
+flux remove express
+```
+
+`flux.json` diperbarui otomatis:
+
+```json
+{
+  "dependencies": {
+    "express": "^4.18.0",
+    "axios": "1.6.0"
+  }
+}
+```
+
+### 10. Gunakan Dependensi npm di Flux
+
+Dependensi npm bisa di-import langsung:
+
+```flux
+import express from 'express'
+import { readFileSync } from 'fs'
+import path from 'path'
+
+val app = express()
+app.use(express.json())
+
+app.get("/", fn(req, res):
+    res.json({ status: "ok" })
+)
+
+app.listen(3000, fn():
+    print("Express + Flux berjalan di port 3000")
+)
+```
+
+### Ringkasan Alur Kerja
+
+```
+flux init proyek        ← buat proyek baru
+    ↓
+flux run src/main.flux  ← kembangkan (tulis + jalankan)
+    ↓
+flux watch src/main.flux← mode watch untuk development aktif
+    ↓
+flux check src/         ← type check sebelum commit
+flux lint src/          ← cari masalah kode
+flux fmt src/           ← format kode
+flux test tests/        ← jalankan test suite
+    ↓
+flux bundle src/main.flux -o dist/bundle.js --mangle   ← build production
+    ↓
+node dist/bundle.js     ← jalankan production build
+```
+
+---
+
 ## Quick Start
 
 ```flux