Add typed rescue error matching

Author: mgomes

ROADMAP.md

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

docs/errors.md

@@ -70,7 +70,7 @@ Use `begin` with `rescue` and/or `ensure` for script-level recovery:
 def safe_div(a, b)
   begin
     a / b
-  rescue
+  rescue(RuntimeError)
     "fallback"
   ensure
     audit("safe_div attempted")
@@ -81,9 +81,11 @@ end
 Semantics:
 
 - `rescue` runs only when the `begin` body raises an error.
+- `rescue` supports optional typed matching via `rescue(<Type>)`.
+- `rescue` supports `AssertionError`, `RuntimeError`, and unions such as `rescue(AssertionError | RuntimeError)`.
 - `ensure` always runs (success, rescue path, or failure path).
 - Without `rescue`, original runtime errors still propagate after `ensure` executes.
-- `rescue` currently catches runtime failures broadly (typed matching and re-raise semantics are separate work).
+- Unmatched typed rescues do not swallow the original error.
 
 ## REPL Debugging
 

vibes/ast.go

@@ -156,6 +156,7 @@ func (s *NextStmt) Pos() Position { return s.position }
 
 type TryStmt struct {
 	Body     []Statement
+	RescueTy *TypeExpr
 	Rescue   []Statement
 	Ensure   []Statement
 	position Position

vibes/builtins.go

@@ -1,7 +1,6 @@
 package vibes
 
 import (
-	"errors"
 	"fmt"
 	"time"
 )
@@ -20,7 +19,7 @@ func builtinAssert(exec *Execution, receiver Value, args []Value, kwargs map[str
 	} else if msg, ok := kwargs["message"]; ok {
 		message = msg.String()
 	}
-	return NewNil(), errors.New(message)
+	return NewNil(), newAssertionFailureError(message)
 }
 
 func builtinMoney(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {

vibes/execution.go

@@ -89,11 +89,25 @@ type StackFrame struct {
 }
 
 type RuntimeError struct {
+	Type      string
 	Message   string
 	CodeFrame string
 	Frames    []StackFrame
 }
 
+type assertionFailureError struct {
+	message string
+}
+
+func (e *assertionFailureError) Error() string {
+	return e.message
+}
+
+const (
+	runtimeErrorTypeBase      = "RuntimeError"
+	runtimeErrorTypeAssertion = "AssertionError"
+)
+
 var (
 	errLoopBreak = errors.New("loop break")
 	errLoopNext  = errors.New("loop next")
@@ -127,6 +141,37 @@ func (re *RuntimeError) Unwrap() error {
 	return nil
 }
 
+func canonicalRuntimeErrorType(name string) (string, bool) {
+	switch {
+	case strings.EqualFold(name, runtimeErrorTypeBase), strings.EqualFold(name, "Error"):
+		return runtimeErrorTypeBase, true
+	case strings.EqualFold(name, runtimeErrorTypeAssertion):
+		return runtimeErrorTypeAssertion, true
+	default:
+		return "", false
+	}
+}
+
+func classifyRuntimeErrorType(err error) string {
+	if err == nil {
+		return runtimeErrorTypeBase
+	}
+	var assertionErr *assertionFailureError
+	if errors.As(err, &assertionErr) {
+		return runtimeErrorTypeAssertion
+	}
+	if runtimeErr, ok := err.(*RuntimeError); ok {
+		if kind, known := canonicalRuntimeErrorType(runtimeErr.Type); known {
+			return kind
+		}
+	}
+	return runtimeErrorTypeBase
+}
+
+func newAssertionFailureError(message string) error {
+	return &assertionFailureError{message: message}
+}
+
 func (exec *Execution) step() error {
 	exec.steps++
 	if exec.quota > 0 && exec.steps > exec.quota {
@@ -152,6 +197,16 @@ func (exec *Execution) errorAt(pos Position, format string, args ...any) error {
 }
 
 func (exec *Execution) newRuntimeError(message string, pos Position) error {
+	return exec.newRuntimeErrorWithType(runtimeErrorTypeBase, message, pos)
+}
+
+func (exec *Execution) newRuntimeErrorWithType(kind string, message string, pos Position) error {
+	if canonical, ok := canonicalRuntimeErrorType(kind); ok {
+		kind = canonical
+	} else {
+		kind = runtimeErrorTypeBase
+	}
+
 	frames := make([]StackFrame, 0, len(exec.callStack)+1)
 
 	if len(exec.callStack) > 0 {
@@ -172,7 +227,7 @@ func (exec *Execution) newRuntimeError(message string, pos Position) error {
 	if exec.script != nil {
 		codeFrame = formatCodeFrame(exec.script.source, pos)
 	}
-	return &RuntimeError{Message: message, CodeFrame: codeFrame, Frames: frames}
+	return &RuntimeError{Type: kind, Message: message, CodeFrame: codeFrame, Frames: frames}
 }
 
 func (exec *Execution) wrapError(err error, pos Position) error {
@@ -182,7 +237,7 @@ func (exec *Execution) wrapError(err error, pos Position) error {
 	if _, ok := err.(*RuntimeError); ok {
 		return err
 	}
-	return exec.newRuntimeError(err.Error(), pos)
+	return exec.newRuntimeErrorWithType(classifyRuntimeErrorType(err), err.Error(), pos)
 }
 
 func (exec *Execution) pushReceiver(v Value) {
@@ -1317,7 +1372,7 @@ func (exec *Execution) evalUntilStatement(stmt *UntilStmt, env *Env) (Value, boo
 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 {
+	if err != nil && len(stmt.Rescue) > 0 && runtimeErrorMatchesRescueType(err, stmt.RescueTy) {
 		rescueVal, rescueReturned, rescueErr := exec.evalStatements(stmt.Rescue, env)
 		if rescueErr != nil {
 			val = NewNil()
@@ -1346,6 +1401,36 @@ func (exec *Execution) evalTryStatement(stmt *TryStmt, env *Env) (Value, bool, e
 	return val, returned, nil
 }
 
+func runtimeErrorMatchesRescueType(err error, rescueTy *TypeExpr) bool {
+	if rescueTy == nil {
+		return true
+	}
+	errKind := classifyRuntimeErrorType(err)
+	return rescueTypeMatchesErrorKind(rescueTy, errKind)
+}
+
+func rescueTypeMatchesErrorKind(ty *TypeExpr, errKind string) bool {
+	if ty == nil {
+		return false
+	}
+	if ty.Kind == TypeUnion {
+		for _, option := range ty.Union {
+			if rescueTypeMatchesErrorKind(option, errKind) {
+				return true
+			}
+		}
+		return false
+	}
+	canonical, ok := canonicalRuntimeErrorType(ty.Name)
+	if !ok {
+		return false
+	}
+	if canonical == runtimeErrorTypeBase {
+		return true
+	}
+	return canonical == errKind
+}
+
 func (exec *Execution) getMember(obj Value, property string, pos Position) (Value, error) {
 	switch obj.Kind() {
 	case KindHash, KindObject:

vibes/parser.go

@@ -440,8 +440,24 @@ func (p *parser) parseBeginStatement() Statement {
 	p.nextToken()
 	body := p.parseBlock(tokenRescue, tokenEnsure, tokenEnd)
 
+	var rescueTy *TypeExpr
 	var rescueBody []Statement
 	if p.curToken.Type == tokenRescue {
+		rescuePos := p.curToken.Pos
+		if p.peekToken.Type == tokenLParen && p.peekToken.Pos.Line == rescuePos.Line {
+			p.nextToken()
+			p.nextToken()
+			rescueTy = p.parseTypeExpr()
+			if rescueTy == nil {
+				return nil
+			}
+			if !p.validateRescueTypeExpr(rescueTy, rescuePos) {
+				return nil
+			}
+			if !p.expectPeek(tokenRParen) {
+				return nil
+			}
+		}
 		p.nextToken()
 		rescueBody = p.parseBlock(tokenEnsure, tokenEnd)
 	}
@@ -462,7 +478,34 @@ func (p *parser) parseBeginStatement() Statement {
 		return nil
 	}
 
-	return &TryStmt{Body: body, Rescue: rescueBody, Ensure: ensureBody, position: pos}
+	return &TryStmt{Body: body, RescueTy: rescueTy, Rescue: rescueBody, Ensure: ensureBody, position: pos}
+}
+
+func (p *parser) validateRescueTypeExpr(ty *TypeExpr, pos Position) bool {
+	if ty == nil {
+		p.addParseError(pos, "rescue type cannot be empty")
+		return false
+	}
+
+	if ty.Kind == TypeUnion {
+		ok := true
+		for _, option := range ty.Union {
+			if !p.validateRescueTypeExpr(option, option.position) {
+				ok = false
+			}
+		}
+		return ok
+	}
+
+	if len(ty.TypeArgs) > 0 || len(ty.Shape) > 0 {
+		p.addParseError(pos, fmt.Sprintf("rescue type must be an error class, got %s", formatTypeExpr(ty)))
+		return false
+	}
+	if _, ok := canonicalRuntimeErrorType(ty.Name); !ok {
+		p.addParseError(pos, fmt.Sprintf("unknown rescue error type %s", ty.Name))
+		return false
+	}
+	return true
 }
 
 func (p *parser) parseBlock(stop ...TokenType) []Statement {

vibes/runtime_test.go

@@ -1014,6 +1014,96 @@ func TestBeginRescueEnsure(t *testing.T) {
 	}
 }
 
+func TestBeginRescueTypedMatching(t *testing.T) {
+	script := compileScript(t, `
+    def typed_assertion()
+      begin
+        assert false, "boom"
+      rescue(AssertionError)
+        "assertion"
+      end
+    end
+
+    def typed_runtime()
+      begin
+        assert false, "boom"
+      rescue(RuntimeError)
+        "runtime"
+      end
+    end
+
+    def typed_union()
+      begin
+        assert false, "boom"
+      rescue(AssertionError | RuntimeError)
+        "union"
+      end
+    end
+
+    def rescue_mismatch()
+      begin
+        1 / 0
+      rescue(AssertionError)
+        "nope"
+      end
+    end
+
+    def assertion_passthrough()
+      assert false, "raw"
+    end
+    `)
+
+	if got := callFunc(t, script, "typed_assertion", nil); !got.Equal(NewString("assertion")) {
+		t.Fatalf("typed_assertion mismatch: %v", got)
+	}
+	if got := callFunc(t, script, "typed_runtime", nil); !got.Equal(NewString("runtime")) {
+		t.Fatalf("typed_runtime mismatch: %v", got)
+	}
+	if got := callFunc(t, script, "typed_union", nil); !got.Equal(NewString("union")) {
+		t.Fatalf("typed_union mismatch: %v", got)
+	}
+
+	_, err := script.Call(context.Background(), "rescue_mismatch", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "division by zero") {
+		t.Fatalf("expected typed rescue mismatch to preserve original error, got %v", err)
+	}
+	var divideErr *RuntimeError
+	if !errors.As(err, &divideErr) {
+		t.Fatalf("expected RuntimeError, got %T", err)
+	}
+	if divideErr.Type != runtimeErrorTypeBase {
+		t.Fatalf("expected runtime error type %s, got %s", runtimeErrorTypeBase, divideErr.Type)
+	}
+
+	_, err = script.Call(context.Background(), "assertion_passthrough", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "raw") {
+		t.Fatalf("expected assertion passthrough error, got %v", err)
+	}
+	var assertionErr *RuntimeError
+	if !errors.As(err, &assertionErr) {
+		t.Fatalf("expected RuntimeError, got %T", err)
+	}
+	if assertionErr.Type != runtimeErrorTypeAssertion {
+		t.Fatalf("expected runtime error type %s, got %s", runtimeErrorTypeAssertion, assertionErr.Type)
+	}
+}
+
+func TestBeginRescueTypedUnknownTypeFailsCompile(t *testing.T) {
+	engine := MustNewEngine(Config{})
+	_, err := engine.Compile(`
+    def bad()
+      begin
+        1 / 0
+      rescue(NotARealError)
+        "fallback"
+      end
+    end
+    `)
+	if err == nil || !strings.Contains(err.Error(), "unknown rescue error type NotARealError") {
+		t.Fatalf("expected unknown rescue type compile error, got %v", err)
+	}
+}
+
 func TestLoopControlBreakAndNext(t *testing.T) {
 	script := compileScript(t, `
     def for_break()