Add raise re-raise semantics with stack preservation

Author: mgomes

ROADMAP.md

@@ -219,7 +219,7 @@ Goal: improve language ergonomics for complex script logic and recovery behavior
 
 - [x] Add structured error handling syntax (`begin/rescue/ensure` or equivalent).
 - [x] Add typed error matching where feasible.
-- [ ] Define re-raise semantics and stack preservation.
+- [x] Define re-raise semantics and stack preservation.
 - [x] Ensure runtime errors preserve original position and call frames.
 
 ### Runtime Behavior

docs/errors.md

@@ -78,6 +78,17 @@ def safe_div(a, b)
 end
 ```
 
+Re-raise the current rescued error with `raise`:
+
+```vibe
+begin
+  risky_call()
+rescue(AssertionError)
+  audit("recovering assertion")
+  raise
+end
+```
+
 Semantics:
 
 - `rescue` runs only when the `begin` body raises an error.
@@ -86,6 +97,8 @@ Semantics:
 - `ensure` always runs (success, rescue path, or failure path).
 - Without `rescue`, original runtime errors still propagate after `ensure` executes.
 - Unmatched typed rescues do not swallow the original error.
+- `raise` inside `rescue` re-raises the original error and preserves its stack frames.
+- `raise "message"` raises a new runtime error. Bare `raise` outside `rescue` is a runtime error.
 
 ## REPL Debugging
 

vibes/ast.go

@@ -84,6 +84,14 @@ type ReturnStmt struct {
 func (s *ReturnStmt) stmtNode()     {}
 func (s *ReturnStmt) Pos() Position { return s.position }
 
+type RaiseStmt struct {
+	Value    Expression
+	position Position
+}
+
+func (s *RaiseStmt) stmtNode()     {}
+func (s *RaiseStmt) Pos() Position { return s.position }
+
 type AssignStmt struct {
 	Target   Expression
 	Value    Expression

vibes/execution.go

@@ -63,6 +63,7 @@ type Execution struct {
 	receiverStack             []Value
 	envStack                  []*Env
 	loopDepth                 int
+	rescuedErrors             []error
 	strictEffects             bool
 	allowRequire              bool
 }
@@ -315,6 +316,24 @@ func (exec *Execution) currentModuleContext() *moduleContext {
 	return &ctx
 }
 
+func (exec *Execution) pushRescuedError(err error) {
+	exec.rescuedErrors = append(exec.rescuedErrors, err)
+}
+
+func (exec *Execution) popRescuedError() {
+	if len(exec.rescuedErrors) == 0 {
+		return
+	}
+	exec.rescuedErrors = exec.rescuedErrors[:len(exec.rescuedErrors)-1]
+}
+
+func (exec *Execution) currentRescuedError() error {
+	if len(exec.rescuedErrors) == 0 {
+		return nil
+	}
+	return exec.rescuedErrors[len(exec.rescuedErrors)-1]
+}
+
 func (exec *Execution) evalStatements(stmts []Statement, env *Env) (Value, bool, error) {
 	exec.pushEnv(env)
 	defer exec.popEnv()
@@ -356,6 +375,8 @@ func (exec *Execution) evalStatement(stmt Statement, env *Env) (Value, bool, err
 	case *ReturnStmt:
 		val, err := exec.evalExpression(s.Value, env)
 		return val, true, err
+	case *RaiseStmt:
+		return exec.evalRaiseStatement(s, env)
 	case *AssignStmt:
 		val, err := exec.evalExpression(s.Value, env)
 		if err != nil {
@@ -1369,11 +1390,29 @@ func (exec *Execution) evalUntilStatement(stmt *UntilStmt, env *Env) (Value, boo
 	}
 }
 
+func (exec *Execution) evalRaiseStatement(stmt *RaiseStmt, env *Env) (Value, bool, error) {
+	if stmt.Value != nil {
+		val, err := exec.evalExpression(stmt.Value, env)
+		if err != nil {
+			return NewNil(), false, err
+		}
+		return NewNil(), false, exec.errorAt(stmt.Pos(), "%s", val.String())
+	}
+
+	err := exec.currentRescuedError()
+	if err == nil {
+		return NewNil(), false, exec.errorAt(stmt.Pos(), "raise used outside of rescue")
+	}
+	return NewNil(), false, err
+}
+
 func (exec *Execution) evalTryStatement(stmt *TryStmt, env *Env) (Value, bool, error) {
 	val, returned, err := exec.evalStatements(stmt.Body, env)
 
 	if err != nil && len(stmt.Rescue) > 0 && runtimeErrorMatchesRescueType(err, stmt.RescueTy) {
+		exec.pushRescuedError(err)
 		rescueVal, rescueReturned, rescueErr := exec.evalStatements(stmt.Rescue, env)
+		exec.popRescuedError()
 		if rescueErr != nil {
 			val = NewNil()
 			returned = false

vibes/lexer.go

@@ -411,6 +411,8 @@ func lookupIdent(ident string) TokenType {
 		return tokenRescue
 	case "ensure":
 		return tokenEnsure
+	case "raise":
+		return tokenRaise
 	case "end":
 		return tokenEnd
 	case "return":

vibes/parser.go

@@ -123,6 +123,8 @@ func (p *parser) parseStatement() Statement {
 		return p.parseClassStatement()
 	case tokenReturn:
 		return p.parseReturnStatement()
+	case tokenRaise:
+		return p.parseRaiseStatement()
 	case tokenIf:
 		return p.parseIfStatement()
 	case tokenFor:
@@ -263,6 +265,19 @@ func (p *parser) parseReturnStatement() Statement {
 	return &ReturnStmt{Value: value, position: pos}
 }
 
+func (p *parser) parseRaiseStatement() Statement {
+	pos := p.curToken.Pos
+	if p.peekToken.Type == tokenEOF || p.peekToken.Type == tokenEnd || p.peekToken.Type == tokenEnsure || p.peekToken.Type == tokenRescue || p.peekToken.Pos.Line != pos.Line {
+		return &RaiseStmt{position: pos}
+	}
+	p.nextToken()
+	value := p.parseExpression(lowestPrec)
+	if value == nil {
+		return nil
+	}
+	return &RaiseStmt{Value: value, position: pos}
+}
+
 func (p *parser) parseClassStatement() Statement {
 	pos := p.curToken.Pos
 	if !p.expectPeek(tokenIdent) {
@@ -1178,6 +1193,8 @@ func tokenLabel(tt TokenType) string {
 		return "'setter'"
 	case tokenEnd:
 		return "'end'"
+	case tokenRaise:
+		return "'raise'"
 	case tokenReturn:
 		return "'return'"
 	case tokenYield:

vibes/runtime_test.go

@@ -1104,6 +1104,90 @@ func TestBeginRescueTypedUnknownTypeFailsCompile(t *testing.T) {
 	}
 }
 
+func TestBeginRescueReraisePreservesStack(t *testing.T) {
+	script := compileScript(t, `
+    def inner()
+      assert false, "boom"
+    end
+
+    def middle()
+      begin
+        inner()
+      rescue(AssertionError)
+        raise
+      end
+    end
+
+    def outer()
+      middle()
+    end
+
+    def catches_reraise()
+      begin
+        middle()
+      rescue(AssertionError)
+        "caught"
+      end
+    end
+
+    def raise_outside()
+      raise
+    end
+
+    def raise_new_message()
+      raise "custom boom"
+    end
+    `)
+
+	if got := callFunc(t, script, "catches_reraise", nil); !got.Equal(NewString("caught")) {
+		t.Fatalf("catches_reraise mismatch: %v", got)
+	}
+
+	_, err := script.Call(context.Background(), "outer", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "boom") {
+		t.Fatalf("expected reraise error, got %v", err)
+	}
+	var rtErr *RuntimeError
+	if !errors.As(err, &rtErr) {
+		t.Fatalf("expected RuntimeError, got %T", err)
+	}
+	if rtErr.Type != runtimeErrorTypeAssertion {
+		t.Fatalf("expected assertion error type %s, got %s", runtimeErrorTypeAssertion, rtErr.Type)
+	}
+	if len(rtErr.Frames) < 4 {
+		t.Fatalf("expected at least 4 frames, got %d", len(rtErr.Frames))
+	}
+	if rtErr.Frames[0].Function != "inner" {
+		t.Fatalf("expected inner frame first, got %s", rtErr.Frames[0].Function)
+	}
+	if rtErr.Frames[1].Function != "inner" {
+		t.Fatalf("expected inner call site second, got %s", rtErr.Frames[1].Function)
+	}
+	if rtErr.Frames[2].Function != "middle" {
+		t.Fatalf("expected middle frame third, got %s", rtErr.Frames[2].Function)
+	}
+	if rtErr.Frames[3].Function != "outer" {
+		t.Fatalf("expected outer frame fourth, got %s", rtErr.Frames[3].Function)
+	}
+
+	_, err = script.Call(context.Background(), "raise_outside", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "raise used outside of rescue") {
+		t.Fatalf("expected raise outside rescue error, got %v", err)
+	}
+
+	_, err = script.Call(context.Background(), "raise_new_message", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "custom boom") {
+		t.Fatalf("expected raise message error, got %v", err)
+	}
+	var raisedErr *RuntimeError
+	if !errors.As(err, &raisedErr) {
+		t.Fatalf("expected RuntimeError, got %T", err)
+	}
+	if raisedErr.Type != runtimeErrorTypeBase {
+		t.Fatalf("expected runtime error type %s, got %s", runtimeErrorTypeBase, raisedErr.Type)
+	}
+}
+
 func TestLoopControlBreakAndNext(t *testing.T) {
 	script := compileScript(t, `
     def for_break()

vibes/token.go

@@ -54,6 +54,7 @@ const (
 	tokenBegin    TokenType = "BEGIN"
 	tokenRescue   TokenType = "RESCUE"
 	tokenEnsure   TokenType = "ENSURE"
+	tokenRaise    TokenType = "RAISE"
 	tokenEnd      TokenType = "END"
 	tokenReturn   TokenType = "RETURN"
 	tokenYield    TokenType = "YIELD"