rip-lang 2.9.0 → 2.9.1

package/docs/PHILOSOPHY.md

@@ -1,569 +0,0 @@
-<p><img src="rip.svg" alt="Rip Logo" width="100"></p>
-
-# Rip Philosophy & Design
-
-> Why Rip exists, how it compares to CoffeeScript, and the design decisions that shape it.
-
----
-
-## Table of Contents
-
-1. [Why S-Expressions](#1-why-s-expressions)
-2. [Rip vs CoffeeScript](#2-rip-vs-coffeescript)
-3. [Current Assessment](#3-current-assessment)
-4. [The Full Debate](#4-the-full-debate)
-
----
-
-# 1. Why S-Expressions
-
-**TL;DR:** S-expressions make compilers 50% smaller, 10x easier to maintain, and infinitely more elegant.
-
-## The Central Insight
-
-Most compilers use complex AST node classes. Rip uses **simple arrays**:
-
-```javascript
-// Traditional AST (CoffeeScript, TypeScript, Babel)
-class BinaryOp {
-  constructor(op, left, right) {
-    this.op = op;
-    this.left = left;
-    this.right = right;
-  }
-  compile() { /* 50+ lines */ }
-  optimize() { /* 30+ lines */ }
-  validate() { /* 20+ lines */ }
-}
-
-// Rip's S-Expression
-["+", left, right]  // That's it!
-```
-
-**Result:** CoffeeScript's compiler is 17,760 LOC. Rip's is ~11,000 LOC—smaller, yet includes a complete reactive runtime with state, computed values, and effects.
-
-## The Fundamental Rule
-
-> **Transform the IR (s-expressions), not the output (strings)**
-
-This single principle led to major refactorings that eliminated over 140 lines of fragile code.
-
-## Real-World Example: Flattening Logical Chains
-
-**The Problem:**
-```javascript
-// Parser creates deeply nested s-expressions:
-["&&", ["&&", ["&&", ["!", "a"], ["!", "b"]], ["!", "c"]], "d"]
-
-// Which generates ugly code:
-if (((!a && !b) && !c) && d)
-```
-
-**❌ String Manipulation Approach (What We Didn't Do)**
-
-```javascript
-unwrapLogical(code) {
-  // Try to fix the OUTPUT with regex
-  while (code.includes('((')) {
-    code = code.replace(/* complex regex */, /* replacement */);
-    // 100+ lines of regex hell
-  }
-}
-```
-
-**Problems:**
-- 100+ lines of complex regex
-- Fragile (breaks if format changes)
-- Hard to debug
-- Slow (string parsing)
-
-**✅ S-Expression Approach (What We Actually Did)**
-
-```javascript
-flattenBinaryChain(sexpr) {
-  // Transform the IR directly
-  if (!Array.isArray(sexpr) || sexpr[0] !== '&&') return sexpr;
-
-  const operands = [];
-  const collect = (expr) => {
-    if (Array.isArray(expr) && expr[0] === '&&') {
-      for (let i = 1; i < expr.length; i++) {
-        collect(expr[i]);
-      }
-    } else {
-      operands.push(expr);
-    }
-  };
-
-  collect(sexpr);
-  return ['&&', ...operands];
-}
-
-// Input:  ["&&", ["&&", a, b], c]
-// Output: ["&&", a, b, c]
-// Generate: "a && b && c"
-```
-
-**Benefits:**
-- 50 lines of clear logic
-- Type-safe (works with arrays)
-- Easy to debug (inspect data)
-- Fast (no parsing)
-
-## The Developer Experience Gap
-
-### Debugging Comparison
-
-**String Manipulation:**
-```javascript
-console.log(iifeCode);
-// "(() => {\n  const result = [];\n  for (const x of arr) {\n..."
-// What you see: A blob of text
-// Time to debug: 20-30 minutes
-```
-
-**S-Expression:**
-```javascript
-console.log(sexpr);
-// ["comprehension", ["*", "x", 2], [["for-in", ["x"], ["array", 1, 2, 3], null]], []]
-// What you see: Clear structure
-// Time to debug: 2-3 minutes
-```
-
-### Time to Debug Issue
-
-**String Manipulation:** 58 minutes (and that's if you're lucky!)
-**S-Expression:** 8 minutes (and you're confident it's correct)
-
-**7x faster debugging!**
-
-## The Architecture Lesson
-
-### Why CoffeeScript is 17,760 LOC
-
-**CoffeeScript's approach:**
-```javascript
-class Literal extends Base
-  compile() { ... }
-
-class Block extends Base
-  compile() { ... }
-
-class Op extends Base
-  compile() { ... }
-
-// 50+ AST node classes
-// 10,000+ LOC of node definitions
-// Complex inheritance hierarchies
-```
-
-### Why Rip is ~14,000 LOC (with a complete framework)
-
-**Rip's approach:**
-```javascript
-generate(sexpr, context) {
-  switch (sexpr[0]) {
-    case '+': return `(${left} + ${right})`;
-    case 'if': return `if (${cond}) { ... }`;
-    // Simple pattern matching
-    // No classes, no inheritance
-    // Just data transformation
-  }
-}
-```
-
-**The difference:**
-- CoffeeScript: Object-oriented with inheritance
-- Rip: Functional with pattern matching
-
-## Practical Guidelines
-
-### ✅ DO: Work at S-Expression Level
-
-```javascript
-// Good: Transform before generating
-const flattened = this.flattenBinaryChain(sexpr);
-return this.generate(flattened, context);
-
-// Good: Detect pattern and change generation
-if (this.comprehensionTarget) {
-  return this.generateComprehensionWithTarget(...);
-}
-```
-
-### ❌ DON'T: Manipulate Generated Strings
-
-```javascript
-// Bad: Generate then parse
-const code = this.generate(expr);
-const unwrapped = code.match(/pattern/);
-
-// Bad: String replacement
-return code.replace(/old/g, 'new');
-```
-
-## The Philosophy
-
-### Lisp Got It Right 60 Years Ago
-
-```lisp
-; Code is data, data is code
-(+ 1 2)  ; This is both an expression AND a list
-```
-
-**The insight:** When your IR is simple data (lists/arrays), transformations are trivial!
-
-### Why Other Languages Forgot
-
-**Traditional compiler theory:**
-- "You need typed AST nodes"
-- "Object-oriented design is cleaner"
-- "Visitor pattern for traversal"
-
-**Reality:**
-- AST nodes → Complex inheritance
-- OOP → Boilerplate everywhere
-- Visitor pattern → Indirection hell
-
-**Rip remembered:**
-- Arrays → Simple access
-- Pattern matching → Direct logic
-- Recursion → Natural traversal
-
-## The Bottom Line
-
-**Question:** Why s-expressions?
-
-**Answer:** Because transforming **data** is easier than parsing **strings**.
-
-**Evidence:**
-- 35% smaller compiler
-- 10x easier debugging
-- 7x faster refactoring
-- 100% elimination of regex fragility
-- Infinite improvement in developer joy
-
-**Philosophy:** Simplicity scales. ✨
-
----
-
-# 2. Rip vs CoffeeScript
-
-## Quick Summary
-
-| Metric | CoffeeScript | Rip |
-|--------|--------------|-----|
-| **Feature Parity** | Baseline | ~99% |
-| **Unique Features** | 0 | 10+ innovations |
-| **Dependencies** | Multiple | **ZERO** |
-| **Self-Hosting** | No | **YES** |
-| **Total LOC** | 17,760 | ~14,000 |
-
-## Rip's Killer Features (Not in CoffeeScript)
-
-### 1. Dual Optional Syntax
-
-**CoffeeScript:** 4 soak operators (`?`, `?[]`, `?()`, `?::`)
-
-**Rip:** 10 total operators - **BOTH CoffeeScript soak AND ES6 optional!**
-
-```coffee
-# CoffeeScript soak (transpiled)
-arr?[0]       # → (arr != null ? arr[0] : undefined)
-
-# ES6 optional (native)
-obj?.prop     # → obj?.prop
-arr?.[0]      # → arr?.[0]
-x ?? y        # → x ?? y
-
-# Mix and match!
-obj?.arr?[0]  # ES6 + CoffeeScript together!
-```
-
-### 2. Zero Dependencies + Self-Hosting
-
-```json
-// package.json
-{
-  "dependencies": {}    // ← ZERO dependencies!
-}
-```
-
-**What's included:**
-- ✅ Full compiler (lexer, parser, codegen)
-- ✅ **SLR(1) parser generator** (solar.rip - ~1,000 lines)
-- ✅ Self-hosting capability (Rip compiles itself)
-- ✅ Triple REPL (terminal, browser, console)
-- ✅ Test framework
-- ✅ Browser bundler
-
-**Bootstrap loop:**
-```bash
-# Rip compiles the parser generator
-./bin/rip src/grammar/solar.rip → solar.js
-
-# solar.js compiles the grammar
-bun solar.js src/grammar/grammar.rip → parser.js
-
-# parser.js used by Rip → COMPLETE LOOP ✅
-```
-
-### 3. Ternary Operator (JavaScript Style)
-
-```coffee
-# Both styles work in Rip!
-result = cond ? truthy : falsy          # JavaScript style
-result = if cond then truthy else falsy # CoffeeScript style
-```
-
-**Why possible:** By using `??` for nullish, `?` became available for ternary.
-
-### 4. Heregex (Extended Regular Expressions)
-
-```rip
-pattern = ///
-  ^ \d+      # starts with digits
-  \s*        # optional whitespace
-  [a-z]+     # followed by letters
-  $          # end of string
-  ///gi
-
-# Compiles to: /^\d+\s*[a-z]+$/gi
-# Comments and whitespace automatically stripped!
-```
-
-### 5. Ruby-Style Regex
-
-```rip
-# =~ operator with automatic _ capture
-email =~ /(.+)@(.+)/
-username = _[1]
-domain = _[2]
-
-# Inline extraction
-zip = "12345-6789"[/^(\d{5})/, 1]  # Returns "12345"
-```
-
-### 6. Dammit Operator (Call-and-Await)
-
-```rip
-# The ! operator calls AND awaits
-result = fetchData!      # → await fetchData()
-user = getUser!(id)      # → await getUser(id)
-```
-
-### 7. Void Functions (Side-Effect Only)
-
-```rip
-# ! at definition suppresses implicit returns
-def processItems!
-  for item in items
-    item.update()
-  # ← Returns undefined, not last expression
-```
-
-### 8. Smart Comprehension Optimization
-
-```rip
-fn = ->
-  process x for x in arr    # ← Rip: plain loop!
-  doMore()                  # ← Last statement returns
-```
-
-**CoffeeScript:** Generates IIFE (wasteful array building)
-**Rip:** Context-aware - plain loop when result unused!
-
-### 9. __DATA__ Marker
-
-```rip
-console.log "Config:", DATA
-
-__DATA__
-host=localhost
-port=8080
-debug=true
-```
-
-Ruby-style __DATA__ marker for inline config/templates/test data.
-
-### 10. Auto-Detection
-
-```coffee
-# No manual async keyword needed!
-getData = ->
-  await fetch(url)
-# Automatically becomes: async function getData()
-
-# No manual * needed!
-counter = ->
-  yield 1
-# Automatically becomes: function* counter()
-```
-
-## Key Design Differences
-
-### Module System
-
-| CoffeeScript | Rip | Rationale |
-|-------------|-----|-----------|
-| CommonJS | ES6 modules | Future-proof, tree-shaking |
-| `require()` | `import` | Native browser support |
-
-### Class Compilation
-
-| CoffeeScript | Rip | Rationale |
-|-------------|-----|-----------|
-| ES5 functions | ES6 classes | Cleaner, native, optimized |
-
-### Implementation Comparison
-
-| Component | CoffeeScript 2.7 | Rip | Difference |
-|-----------|------------------|-----|------------|
-| **Lexer+Rewriter** | 3,558 LOC | 3,537 LOC | Expanded syntax |
-| **Parser Generator** | 2,285 LOC (Jison) | ~1,000 LOC (Solar) | Built-in, ~250× faster! |
-| **Compiler** | 10,346 LOC (AST Nodes) | 5,500 LOC (S-expressions) | +Reactive runtime! |
-| **Total** | **17,760 LOC** | **~11,000 LOC** | **Smaller + reactive runtime** |
-
-## Feature Comparison Table
-
-| Feature | CoffeeScript | Rip | Winner |
-|---------|-------------|------|--------|
-| **Optional operators** | 4 soak | 10 (5 soak + 5 ES6) | 🏆 Rip |
-| **Ternary** | ❌ No | ✅ Yes | 🏆 Rip |
-| **Heregex** | ⚠️ Deprecated | ✅ Full support | 🏆 Rip |
-| **Regex features** | Basic | ✅ Ruby-style (=~, indexing) | 🏆 Rip |
-| **REPL modes** | 1 (terminal) | 3 (terminal, browser, console) | 🏆 Rip |
-| **Async shorthand** | ❌ No | ✅ Dammit operator | 🏆 Rip |
-| **Void functions** | ❌ No | ✅ Side-effect only | 🏆 Rip |
-| **__DATA__ marker** | ❌ No | ✅ Ruby-style | 🏆 Rip |
-| **Comprehension optimization** | Always IIFE | Context-aware | 🏆 Rip |
-| **Modules** | CommonJS | ES6 | 🏆 Rip |
-| **Classes** | ES5 | ES6 | 🏆 Rip |
-| **Dependencies** | Multiple | ✅ **ZERO** | 🏆 Rip |
-| **Parser generator** | External (Jison) | ✅ **Built-in (solar.rip)** | 🏆 Rip |
-| **Self-hosting** | ❌ No | ✅ **Yes** | 🏆 Rip |
-| **Extensibility** | Hard | Easy | 🏆 Rip |
-| **Block comments** | ✅ Yes | ✅ Yes | 🤝 Tie |
-| **Chained compare** | ✅ Yes | ❌ No | 🏆 CS |
-
-**Score:** Rip 16, CoffeeScript 1, Tie 1
-
-## When to Use Which
-
-### Use CoffeeScript When:
-- ✅ Legacy codebase (already using CoffeeScript)
-- ✅ Need CommonJS modules
-- ✅ Team has CoffeeScript expertise
-
-### Use Rip When:
-- ✅ Starting new project
-- ✅ Want modern ES6+ output
-- ✅ Value dual optional syntax
-- ✅ Need 100% test coverage
-- ✅ Want unique features (heregex, regex+, dammit)
-- ✅ Need easy extensibility
-- ✅ Want smaller, cleaner implementation
-
----
-
-# 3. Current Assessment
-
-> **v2.5.1 - Production-Ready with Fine-Grained Reactivity**
-
-## Summary
-
-| Layer | Syntax | Runtime | Features | DX | Score |
-|-------|--------|---------|----------|-----|-------|
-| **Reactivity** | A+ | A+ | A+ | A+ | **A+** |
-
-## Reactivity ⭐⭐⭐⭐⭐ (Production-Ready)
-
-**This is genuinely excellent.**
-
-```coffee
-count := 0                    # State
-doubled ~= count * 2          # Computed (auto-tracks)
-log ~> console.log count      # Effect (auto-runs)
-```
-
-| Aspect | Rating | Notes |
-|--------|--------|-------|
-| Syntax | A+ | `:=`, `~=`, `=!` are elegant and unique |
-| Semantics | A | Proper dependency tracking, lazy computed |
-| Performance | A- | Efficient - only recomputes when needed |
-| Scalability | A | Works the same at any scale |
-
-**Competitive with:** SolidJS signals, Vue 3 refs, Preact signals
-
-## Framework-Agnostic Design
-
-Rip's reactivity system is **framework-agnostic** — use it with React, Vue, Svelte, or vanilla JavaScript. The reactive primitives (state, computed, effects) work independently of any UI layer.
-
-## Competitive Analysis
-
-| Framework | Reactivity | DX | Performance | Overall |
-|-----------|------------|-----|-------------|---------|
-| **Rip** | A+ | A+ | A | **A** |
-| SolidJS | A+ | A | A+ | A |
-| Vue 3 | A- | A | B+ | A- |
-| React | B | A- | B | B+ |
-
-**Rip's Position:**
-
-| Strength | Why |
-|----------|-----|
-| **Reactivity A+** | State, computed, effects, batching |
-| **DX A+** | Cleanest syntax of all, no boilerplate |
-| **Framework-agnostic** | Use with any UI framework |
-
-## Completed Features
-
-- [x] Reactivity primitives (state, computed, effects)
-- [x] **Batching** (`__batch()` for grouped updates)
-- [x] **Error primitives** (`__catchErrors`, `__handleError`)
-
-## Best Current Uses
-
-- Building fast web applications
-- Projects requiring minimal bundle size
-- Learning reactive programming concepts
-- Projects valuing clean syntax over ecosystem size
-
-**The framework is production-ready** with performance competitive with the fastest frameworks available.
-
----
-
-# 4. The Full Debate
-
-For a thorough exploration of the arguments for and against languages like Rip in the modern JavaScript ecosystem, see:
-
-- [Why Not CoffeeScript](WHY-NOT-COFFEESCRIPT.md) - The strongest case against revival
-- [Why YES Rip](WHY-YES-RIP.md) - The counter-argument and Rip's answer
-
-These documents present a point/counterpoint debate:
-1. **WHY-NOT-COFFEESCRIPT.md** - Makes the case that CoffeeScript should remain a historical artifact, citing ecosystem abandonment, TypeScript's dominance, and tooling degradation.
-2. **WHY-YES-RIP.md** - Directly rebuts each argument, showing how Rip addresses these concerns with zero dependencies, modern output, and unique features.
-
-The debate structure demonstrates intellectual honesty—Rip acknowledges the valid criticisms and shows how it provides a different path forward.
-
----
-
-## Conclusion
-
-**Rip exists because:**
-
-1. **Simplicity scales** - S-expressions make compilers maintainable
-2. **Zero dependencies** - True autonomy from the npm ecosystem
-3. **Modern output** - ES6+ everywhere, no legacy baggage
-4. **Unique features** - 10+ innovations CoffeeScript lacks
-5. **Best-in-class DX** - Cleanest syntax in the industry
-6. **Production-ready** - 100% test coverage, self-hosting
-
-**Philosophy:** Programming should be joyful, not painful. Rip remembers what we were fighting for.
-
----
-
-**See Also:**
-- [GUIDE.md](GUIDE.md) - Complete language reference
-- [INTERNALS.md](INTERNALS.md) - Compiler architecture
-- [BROWSER.md](BROWSER.md) - Browser usage and REPL guide