rip-lang 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -5,106 +5,78 @@ All notable changes to Rip will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.0] - 2025-11-01
-
-### Major Enhancements
-
-#### Comprehensions & Loops
-- **Postfix comprehensions with `by` step** - `(x for x in [0...10] by 2)` now works ([#1](https://github.com/shreeve/rip-lang/issues/1))
-- **Range loops without loop variable** - `for [1...N]` for N-time repetition ([#9](https://github.com/shreeve/rip-lang/issues/9))
-- **Nested comprehension optimization** - Eliminated wasteful nested IIFEs, 50%+ output reduction ([#11](https://github.com/shreeve/rip-lang/issues/11))
-- **Unified step handling** - Supports any negative step (`by -2`, `by -3`), 37% code reduction ([#3](https://github.com/shreeve/rip-lang/issues/3))
+## [1.1.1] - 2025-11-01
 
-#### Parameter Handling
-- **Rest parameters in middle position** - `(first, middle..., last)` now generates valid JavaScript ([#15](https://github.com/shreeve/rip-lang/issues/15))
-- **Array destructuring with rest in middle** - `[first, ...middle, last] = arr` works correctly ([#17](https://github.com/shreeve/rip-lang/issues/17))
+### Fixed
+- **Browser REPL launcher (`rip -w`)** - Port fallback now works correctly
+  - Fixed `ReferenceError: assignedPort is not defined`
+  - Server tries port 3000, falls back to OS-assigned port if busy
+  - Browser opens with correct port automatically
+  - Works when installed globally via `npm install -g rip-lang` or `bun install -g rip-lang`
 
-#### Error Handling
-- **Throw in expression position** - `x = fn() || throw "error"` wraps in IIFE for valid JS ([#13](https://github.com/shreeve/rip-lang/issues/13))
-- **Parser error locations** - Errors now show line and column numbers for easy debugging ([#7](https://github.com/shreeve/rip-lang/issues/7))
+### Changed
+- Refactored serve.js to eliminate code duplication
+- Improved port detection by parsing server output
 
-#### Developer Experience
-- **`rip` executes scripts directly** - `rip script.rip` now runs scripts (no `bun` needed) ([#19](https://github.com/shreeve/rip-lang/issues/19))
-- **`rip -w` launches browser REPL** - One command to start local server and open REPL
-- **Beautiful s-expression formatter** - Canonical format with 80% less vertical space
-- **Friendly error messages** - "File not found: X" instead of stack traces
+## [1.1.0] - 2025-11-01
 
-### Browser REPL Enhancements
-- **Resizable panes** - Drag slider between Rip source and JavaScript output
+### Added
+- **Beautiful s-expression formatter** - Canonical format with proper indentation
+  - Deployed in CLI (`-s` flag), browser REPL, and as standalone utility
+  - 80% more compact than JSON, fully parenthesized
+  - Heregex patterns collapsed to single line
+  - Meta-circular: Rip code formatting Rip's data structures!
+- **Script execution** - `rip script.rip` now executes directly (no explicit `bun` needed)
+  - Auto-detects .rip files and uses Bun loader
+  - Passes arguments correctly
+  - Shebang support: `#!/usr/bin/env rip`
+- **Browser REPL launcher** - `rip -w` starts local server and opens browser
+  - One-command workflow
+  - Works offline with local changes
+  - Cross-platform (macOS, Windows, Linux)
+- **Resizable REPL panes** - Drag slider between Rip source and JavaScript output
 - **Local time display** - Build timestamp shown in user's timezone
-- **Canonical s-expression display** - Compact, readable format with proper indentation
-- **Heregex collapse** - Multi-line regexes displayed as single-line quoted strings
-
-### Bug Fixes
-- **Comprehension last-statement context** - Fixed array destructuring comprehensions ([#5](https://github.com/shreeve/rip-lang/issues/5))
-- **Block comments** - Confirmed working (handled by CoffeeScript lexer)
-
-### Infrastructure
-- **GitHub issue templates** - Bug report, feature request, CoffeeScript compatibility, questions
-- **PR template** - Comprehensive checklist for contributions
-- **CONTRIBUTING.md** - Complete workflow guide with real examples
-- **docs/WORKFLOW.md** - Quick command reference
-- **.cursor/rules/rip-agent-onboarding.md** - AI agent onboarding guide
-- **ISSUE-11.md** - Handoff documentation for complex issues
+- **Friendly error messages** - Clear "File not found" instead of stack traces
+
+### Fixed
+- **Postfix `by` step in comprehensions** - `for i in [0..10] by 2` now works
+- **Nested IIFE elimination** - Major code generation optimization (37% smaller)
+- **Throw in expressions** - Properly wrapped in IIFE
+- **Rest parameters in middle position** - Both functions and array destructuring
+  - `def fn(first, ...middle, last)` works
+  - `[first, ...middle, last] = arr` works
+- **Parser error messages** - Now show line and column numbers
+- **Range loops without variable** - `for [1..10]` optimization
+- **Comprehension context detection** - Smart IIFE vs plain loop decisions
+- **Step handling refactoring** - Unified logic, 37% code reduction
+- **Global installation** - `rip -w` works correctly when installed via npm/bun
+
+### Changed
+- Version bumped to 1.1.0
+- Test count: 843 → 864 (+21 tests, all passing)
+- Documentation updated throughout
+- Package.json prepared for NPM publishing
 
 ### Documentation
-- **Real-world output comparison** - Demonstrated 50% smaller output vs CoffeeScript
-- **Heregex interpolation behavior** - Documented #{} vs ${} in regexes
-- **Updated all stats** - Test counts, file references, feature lists
-- **Cleaned up HTML files** - Removed outdated files, renamed for clarity
-
-### Code Quality
-- **Refactored step handling** - Eliminated code duplication, cleaner logic
-- **Consistent formatting** - All s-expressions use canonical parenthesized format
-- **Meta-circular utilities** - S-expression formatter written in Rip itself
-
-### Testing
-- **21 new tests added** - Coverage for all new features
-- **Test count: 843 → 864** - All passing (100%)
-- **Comprehensive coverage** - Nested comprehensions, rest in middle, throw expressions
+- Complete GitHub workflow system (issues, PRs, templates)
+- AI agent onboarding guide
+- CONTRIBUTING.md with real examples
+- Updated README, AGENT.md, COFFEESCRIPT-COMPARISON.md
+- All stats current (864 tests)
 
-### Package
-- **Ready for NPM** - Complete package.json with engines, repository, keywords
-- **Bun requirement** - Clearly specified (Bun >=1.0.0)
-
-### Real-World Validation
-- **bar.coffee migration** - Complex 400-line CoffeeScript file now compiles perfectly
-- **Output quality** - 608 lines (CoffeeScript) → 304 lines (Rip) = 50% smaller
-- **All features working** - Nested switches, comprehensions, rest params, everything!
-
----
+### Infrastructure
+- 10 complete GitHub workflows (issue → branch → test → fix → PR → merge)
+- Comprehensive test coverage (100% passing)
+- Ready for NPM publish
 
 ## [1.0.0] - 2025-10-31
 
 ### Initial Release
-
-- ✅ Complete CoffeeScript-inspired syntax
-- ✅ 843/843 tests passing (100%)
-- ✅ Zero dependencies
-- ✅ Self-hosting compiler
-- ✅ ES2022 output
-- ✅ Triple REPL (terminal, browser, console)
-- ✅ 43KB browser bundle
-- ✅ Comprehensive documentation
-
-**Features:**
-- Dual optional syntax (CoffeeScript soak + ES6 optional chaining)
-- Dammit operator (`!`) for call-and-await
-- Void functions (side-effect only)
-- Heregex (extended regex with comments)
-- Ruby-style regex (`=~` operator, indexing)
-- __DATA__ marker
-- Auto-detection (async/generators)
-- Context-aware comprehensions
-- Smart range optimization
-
-**Implementation:**
-- 9,450 LOC (50% smaller than CoffeeScript's 17,760)
-- S-expression IR (simple arrays vs complex AST)
-- SLR(1) parser generator included (solar.rip)
-- Complete ES6 module support
-
----
-
-[1.1.0]: https://github.com/shreeve/rip-lang/compare/v1.0.0...v1.1.0
-[1.0.0]: https://github.com/shreeve/rip-lang/releases/tag/v1.0.0
+- Complete Rip language compiler
+- CoffeeScript-inspired syntax with modern ES2022 output
+- Zero dependencies (includes SLR(1) parser generator)
+- Self-hosting capability
+- 843/843 tests passing
+- Terminal REPL
+- Browser bundle (43KB brotli-compressed)
+- Complete documentation

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.1.0-blue.svg" alt="Version"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.1.1-blue.svg" alt="Version"></a>
   <a href="#es2022-target"><img src="https://img.shields.io/badge/target-ES2022-blue.svg" alt="Target"></a>
   <a href="#current-status"><img src="https://img.shields.io/badge/tests-864%2F864-brightgreen.svg" alt="Tests"></a>
   <a href="#current-status"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage"></a>
@@ -28,17 +28,16 @@ Rip brings CoffeeScript's elegance to modern JavaScript—but **50% smaller**, c
 #### 💎  Elegant syntax with modern features
 
 ```coffee
-def parseUsers(...inputs)
-  users = for input in inputs
-    # Ruby-style regex with =~ operator and _ captures
-    if input =~ /^(\w+):([^@]+@[\w.]+)$/
-      name = _[1] ?? "guest"          # Nullish coalescing
-      domain = input[/@([\w.]+)/, 1]  # Regex extraction syntax
-      { name, domain }
-
 # Async with dammit operator! (call and await)
 fetchUser = (id) => fetch! "/api/user/${id}"
 
+# Ruby-style regex with =~ operator and _ captures
+def parseUsers(...inputs)
+  users = for input in inputs when input =~ /^(\w+):([^@]+@[\w.]+)$/
+    name = _[1] ?? "guest"          # Nullish coalescing, _ captures
+    domain = input[/@([\w.]+)/, 1]  # Regex extraction syntax
+    { name, domain }
+
 parseUsers "alice:alice@example.com", "bob:bob@test.org"
 ```
 
@@ -47,21 +46,20 @@ parseUsers "alice:alice@example.com", "bob:bob@test.org"
 ```javascript
 let _, fetchUser;
 
+fetchUser = async (id) => await fetch(`/api/user/${id}`);
 function parseUsers(...inputs) {
   let domain, name, users;
-  return (users = (() => {
-    const result = [];
-    for (const input of inputs) {
-      result.push((() => { if ((_ = toSearchable(input).match(/^(\w+):([^@]+@[\w.]+)$/))) {
-        name = (_[1] ?? "guest");
-        domain = (_ = toSearchable(input).match(/@([\w.]+)/)) && _[1];
-        return {name, domain};
-      } })());
+
+  users = [];
+  for (const input of inputs) {
+    if ((_ = toSearchable(input).match(/^(\w+):([^@]+@[\w.]+)$/))) {
+      name = (_[1] ?? "guest");
+      domain = (_ = toSearchable(input).match(/@([\w.]+)/)) && _[1];
+      users.push({name, domain});
     }
-    return result;
-  })());
+  }
+  return users;
 };
-fetchUser = async (id) => await fetch(`/api/user/${id}`);
 parseUsers("alice:alice@example.com", "bob:bob@test.org");
 ```
 
@@ -190,7 +188,7 @@ case '+': {
 | Component | CoffeeScript | Rip | Notes |
 |-----------|--------------|-----|-------|
 | Lexer+Rewriter | 3,558 LOC | **3,145 LOC** | Expanded syntax |
-| Parser Generator | 2,285 LOC (Jison) | **1,047 LOC** (Solar) | Built-in, ~83x faster |
+| Parser Generator | 2,285 LOC (Jison) | **928 LOC** (Solar) | Built-in, ~156× faster! |
 | Compiler | 10,346 LOC (AST Nodes) | **4,738 LOC** (S-expressions) | Powerful capabilities |
 | Tools | 1,571 LOC (Repl, Cake) | **520 LOC** (Repl, Browser) | 3 Repl's + Browser |
 | **Total** | **17,760 LOC** | **9,450 LOC** | **~50% smaller** |
@@ -200,19 +198,131 @@ case '+': {
 - ✅ **Self-hosting** - Rip compiles itself
 - ✅ **No external tools** - Just a JavaScript runtime
 
+### Real-World Example: The Complete Pipeline
+
+Let's see how Rip code flows through the compilation pipeline:
+
+**Step 1: Rip Source Code**
+```coffee
+# Rip code - edit me!
+def fibonacci(n)
+  if n <= 1
+    n
+  else
+    fibonacci(n - 1) + fibonacci(n - 2)
+
+# Try heregex
+pattern = ///
+  ^ \d+      # digits
+  \s*        # space
+  [a-z]+     # letters
+  $
+///i
+
+# Try regex features
+email = "user@example.com"
+domain = email[/@(.+)$/, 1]
+
+console.log "Fib(10):", fibonacci(10)
+console.log "Domain:", domain
+```
+
+**Step 2: S-Expression Intermediate Representation**
+
+The parser converts this to simple arrays (s-expressions):
+
+```lisp
+(program
+  (def fibonacci (n)
+    (block
+      (if (<= n 1) (block n)
+        (block (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))))
+  (= pattern "/^ \\d+\\s*[a-z]+$/i")
+  (= email "user@example.com")
+  (= domain (regex-index email /@(.+)$/ 1))
+  ((. console log) "Fib(10):" (fibonacci 10))
+  ((. console log) "Domain:" domain)
+)
+```
+
+**Key insights:**
+- Each operation is just an array: `["+", left, right]`
+- No complex AST node classes - just plain data
+- Easy to inspect, transform, and debug
+- Pattern matching in codegen is straightforward
+
+**Step 3: JavaScript Output**
+
+The code generator pattern-matches on s-expressions to produce clean JavaScript:
+
+```javascript
+let _, domain, email, pattern;
+
+function fibonacci(n) {
+  return ((n <= 1) ? n : (fibonacci((n - 1)) + fibonacci((n - 2))));
+};
+pattern = /^\d+\s*[a-z]+$/i;
+email = "user@example.com";
+domain = (_ = toSearchable(email).match(/@(.+)$/)) && _[1];
+console.log("Fib(10):", fibonacci(10));
+console.log("Domain:", domain);
+```
+
+**The beauty:** Simple arrays in, clean JavaScript out. No complex AST traversal needed!
+
+**Try it yourself:**
+```bash
+# See the s-expressions
+echo 'x = 42' | ./bin/rip -s
+
+# See the generated JavaScript
+echo 'x = 42' | ./bin/rip -c
+```
+
 ---
 
 ## Quick Start
 
 ### Installation & Setup
 
+**🚀 Fastest Way: Install from Bun Package Registry**
+
+First, install Bun if you haven't already:
+
+```bash
+# Install Bun (macOS, Linux, WSL)
+curl -fsSL https://bun.sh/install | bash
+
+# Or on Windows (PowerShell)
+powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+Then install Rip globally:
+
+```bash
+# Install Rip globally
+bun add -g rip-lang
+
+# Start the REPL immediately!
+rip
+```
+
+That's it! You can now:
+- Run `rip` anywhere for an interactive REPL
+- Compile Rip files: `rip yourfile.rip`
+- Execute `.rip` files: `bun yourfile.rip`
+
+---
+
+**Alternative: Install from Source**
+
 **Step 1: Clone the repository**
 ```bash
 git clone https://github.com/shreeve/rip-lang.git
-cd rip
+cd rip-lang
 ```
 
-**Step 2: Set up global Bun loader (recommended)**
+**Step 2: Set up global Bun loader**
 ```bash
 # Link Rip globally so it's available everywhere
 bun link
@@ -245,10 +355,12 @@ cat ~/.bunfig.toml
 # Should include: preload = ["rip-lang/loader"]
 ```
 
+---
+
 **No npm install needed** - Rip has zero dependencies!
 
 **Requirements:**
-- **Bun** (recommended) - For automatic `.rip` loader
+- **Bun** (recommended) - For automatic `.rip` loader and REPL
 - **Or** any ES2022-compatible runtime: Deno, Node.js 12+, modern browsers
   - Note: Deno/Node require compilation first (`./bin/rip -o output.js input.rip`)
 
@@ -274,7 +386,7 @@ bun hello.rip
 
 **You can also import .rip modules directly:**
 
-```rip
+```coffee
 # utils.rip
 export def add(a, b)
   a + b
@@ -282,7 +394,7 @@ export def add(a, b)
 export multiply = (a, b) => a * b
 ```
 
-```rip
+```coffee
 # main.rip
 import { add, multiply } from "./utils.rip"
 
@@ -300,19 +412,50 @@ bun main.rip  # Works automatically!
 # Interactive REPL
 ./bin/rip
 
-# Compile to JavaScript
+# Execute a Rip script (default behavior)
 ./bin/rip examples/fibonacci.rip
 
-# See s-expressions (the IR)
+# Compile and show JavaScript output
+./bin/rip -c examples/fibonacci.rip
+
+# Compile and save to file
+./bin/rip -o output.js examples/fibonacci.rip
+```
+
+### Debug Flags (Mix and Match!)
+
+Rip supports flexible debugging with flags that can be combined:
+
+```bash
+# Show ONLY s-expressions (no JavaScript)
 ./bin/rip -s examples/fibonacci.rip
 
-# See tokens (from lexer)
+# Show ONLY tokens (no JavaScript)
 ./bin/rip -t examples/fibonacci.rip
 
-# Save compiled output
-./bin/rip -o output.js examples/fibonacci.rip
+# Show s-expressions AND JavaScript
+./bin/rip -s -c examples/fibonacci.rip
+
+# Show tokens AND JavaScript
+./bin/rip -t -c examples/fibonacci.rip
+
+# Show EVERYTHING (full debug mode)
+./bin/rip -s -t -c examples/fibonacci.rip
+
+# Pipe mode (no headers, just output)
+./bin/rip -q -c examples/fibonacci.rip
 ```
 
+**How it works:**
+- `rip script.rip` **executes** the script (default behavior)
+- `echo 'code' | rip` **compiles** and shows JavaScript (stdin defaults to compile mode)
+- `-c` flag **compiles** and shows JavaScript output
+- `-o file.js` **compiles** and saves to file
+- `-s` or `-t` alone show **only** that output (no JavaScript)
+- Add `-c` to **also** show the compiled JavaScript
+- Mix and match as needed for debugging
+- Browser REPL always shows JavaScript (checkboxes toggle `-s` and `-t`)
+
 ### Interactive REPL
 
 Rip includes a full-featured REPL for interactive development:
@@ -423,7 +566,7 @@ bun run serve     # Start dev server (REPL at localhost:3000)
 
 ### Core Syntax
 
-```rip
+```coffee
 # Variables (function-scoped, auto-hoisted)
 x = 42
 name = "Alice"
@@ -469,7 +612,7 @@ greeting = "Hello, ${name}!"
 
 ### Modern Features
 
-```rip
+```coffee
 # Destructuring
 {name, age} = person
 [first, second] = numbers
@@ -625,7 +768,7 @@ Rip provides **two distinct approaches** to safe property/method access:
 
 **Compiles to explicit null/undefined checks:**
 
-```rip
+```coffee
 # Existence check
 arr?
 # → (arr != null)
@@ -657,7 +800,7 @@ a ?= 10
 
 **Passes through to native JavaScript:**
 
-```rip
+```coffee
 # Optional property
 user?.profile?.name
 # → user?.profile?.name
@@ -689,7 +832,7 @@ a ??= 10
 
 **You can combine both styles in the same expression:**
 
-```rip
+```coffee
 # ES6 optional property + CoffeeScript soak index
 obj?.arr?[0]
 # → (obj?.arr != null ? obj?.arr[0] : undefined)
@@ -728,12 +871,12 @@ Both syntaxes handle `null` and `undefined` - pick the style that fits your proj
 ### The Pipeline
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   Source    │────>│   Lexer     │────>│   Parser    │────>│   Codegen   │
-│   Code      │     │  (Coffee)   │     │   (Solar)   │     │   (Rip)     │
-└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
-                       3,145 LOC            1,047 LOC           4,738 LOC
-                     15 yrs tested         Generated!          Optimized!
+┌────────┐    ┌────────────┐    ┌──────────┐    ┌─────────┐
+│ Source │───>│   Lexer    │───>│  Parser  │───>│ Codegen │
+│  Code  │    │  (Coffee)  │    │  (Solar) │    │  (Rip)  │
+└────────┘    └────────────┘    └──────────┘    └─────────┘
+                 3,145 LOC          928 LOC       4,738 LOC
+               15 yrs tested     Generated!   S-expr Optimized!
 ```
 
 ### Components
@@ -748,8 +891,8 @@ Both syntaxes handle `null` and `undefined` - pick the style that fits your proj
 - Solar-generated SLR(1) parser
 - Built from grammar specification
 - Generates s-expressions directly
-- Regenerate with `bun run parser` (~150ms, instant feedback!)
-- **Note:** Solar's 83x speed advantage over Jison (150ms vs 12.5s) made rapid grammar iteration possible
+- Regenerate with `bun run parser` (~80ms, instant feedback!)
+- **Note:** Solar's 156× speed advantage over Jison (80ms vs 12.5s) made rapid grammar iteration possible
 
 **3. Code Generator** (`src/codegen.js`)
 - Pattern matches on s-expressions
@@ -995,7 +1138,7 @@ rip/
    ```
 
 3. **Write tests:**
-   ```rip
+   ```coffee
    test "feature name", "code", expectedResult
    ```
 
@@ -1019,7 +1162,7 @@ rip/
 
 Rip requires parentheses for ALL arrow function parameters:
 
-```rip
+```coffee
 # ✅ Always use parentheses
 () => expr           # Zero params
 (x) => expr          # One param
@@ -1233,7 +1376,7 @@ MIT
 **Inspired by:**
 - CoffeeScript (syntax and lexer)
 - Lisp/Scheme (s-expressions)
-- Solar (parser generator) - **This project wouldn't have been possible without Solar's incredible speed (150ms vs Jison's 12.5 seconds for parser generation). Solar's performance enabled rapid iteration on grammar changes with instant feedback, making development a joy.**
+- Solar (parser generator) - **This project wouldn't have been possible without Solar's incredible speed (80ms vs Jison's 12.5 seconds for parser generation). Solar's performance enabled rapid iteration on grammar changes with instant feedback, making development a joy.**
 - Ruby (regex operators, __DATA__ marker)
 
 **Built by:** Developers who believe simplicity scales