Add regex helper builtins

Author: mgomes

ROADMAP.md

@@ -282,7 +282,7 @@ Goal: reduce host-side boilerplate for common scripting tasks.
 ### Core Utilities
 
 - [x] Add JSON parse/stringify built-ins.
-- [ ] Add regex matching/replacement helpers.
+- [x] Add regex matching/replacement helpers.
 - [x] Add UUID/random identifier utilities with deterministic test hooks.
 - [ ] Add richer date/time parsing helpers for common layouts.
 - [ ] Add safer numeric conversions and clamp/round helpers.

docs/builtins.md

@@ -96,6 +96,27 @@ a JSON string:
 raw = JSON.stringify({ id: "p-1", score: 10, tags: ["a", "b"] })
 ```
 
+## Regex
+
+### `Regex.match(pattern, text)`
+
+Returns the first match string or `nil` when no match exists.
+
+### `Regex.replace(text, pattern, replacement)`
+
+Replaces the first regex match in `text`.
+
+### `Regex.replace_all(text, pattern, replacement)`
+
+Replaces all regex matches in `text`.
+
+```vibe
+Regex.match("ID-[0-9]+", "ID-12 ID-34")                  # "ID-12"
+Regex.replace("ID-12 ID-34", "ID-[0-9]+", "X")           # "X ID-34"
+Regex.replace_all("ID-12 ID-34", "ID-[0-9]+", "X")       # "X X"
+Regex.replace("ID-12", "ID-([0-9]+)", "X-$1")            # "X-12"
+```
+
 ## Module Loading
 
 ### `require(module_name, as: alias?)`

vibes/builtins.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"reflect"
+	"regexp"
 	"strings"
 	"time"
 )
@@ -297,3 +298,77 @@ func vibeValueToJSONValue(val Value, state *jsonStringifyState) (any, error) {
 		return nil, fmt.Errorf("JSON.stringify unsupported value type %s", val.Kind())
 	}
 }
+
+func builtinRegexMatch(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
+	if len(args) != 2 {
+		return NewNil(), fmt.Errorf("Regex.match expects pattern and text")
+	}
+	if len(kwargs) > 0 {
+		return NewNil(), fmt.Errorf("Regex.match does not accept keyword arguments")
+	}
+	if !block.IsNil() {
+		return NewNil(), fmt.Errorf("Regex.match does not accept blocks")
+	}
+	if args[0].Kind() != KindString || args[1].Kind() != KindString {
+		return NewNil(), fmt.Errorf("Regex.match expects string pattern and text")
+	}
+
+	re, err := regexp.Compile(args[0].String())
+	if err != nil {
+		return NewNil(), fmt.Errorf("Regex.match invalid regex: %v", err)
+	}
+	match := re.FindString(args[1].String())
+	if match == "" {
+		return NewNil(), nil
+	}
+	return NewString(match), nil
+}
+
+func builtinRegexReplace(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
+	return builtinRegexReplaceInternal(args, kwargs, block, false)
+}
+
+func builtinRegexReplaceAll(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
+	return builtinRegexReplaceInternal(args, kwargs, block, true)
+}
+
+func builtinRegexReplaceInternal(args []Value, kwargs map[string]Value, block Value, replaceAll bool) (Value, error) {
+	method := "Regex.replace"
+	if replaceAll {
+		method = "Regex.replace_all"
+	}
+
+	if len(args) != 3 {
+		return NewNil(), fmt.Errorf("%s expects text, pattern, replacement", method)
+	}
+	if len(kwargs) > 0 {
+		return NewNil(), fmt.Errorf("%s does not accept keyword arguments", method)
+	}
+	if !block.IsNil() {
+		return NewNil(), fmt.Errorf("%s does not accept blocks", method)
+	}
+	if args[0].Kind() != KindString || args[1].Kind() != KindString || args[2].Kind() != KindString {
+		return NewNil(), fmt.Errorf("%s expects string text, pattern, replacement", method)
+	}
+
+	text := args[0].String()
+	pattern := args[1].String()
+	replacement := args[2].String()
+
+	re, err := regexp.Compile(pattern)
+	if err != nil {
+		return NewNil(), fmt.Errorf("%s invalid regex: %v", method, err)
+	}
+
+	if replaceAll {
+		return NewString(re.ReplaceAllString(text, replacement)), nil
+	}
+
+	loc := re.FindStringIndex(text)
+	if loc == nil {
+		return NewString(text), nil
+	}
+	segment := text[loc[0]:loc[1]]
+	replaced := re.ReplaceAllString(segment, replacement)
+	return NewString(text[:loc[0]] + replaced + text[loc[1]:]), nil
+}

vibes/interpreter.go

@@ -81,6 +81,11 @@ func NewEngine(cfg Config) (*Engine, error) {
 		"parse":     NewBuiltin("JSON.parse", builtinJSONParse),
 		"stringify": NewBuiltin("JSON.stringify", builtinJSONStringify),
 	})
+	engine.builtins["Regex"] = NewObject(map[string]Value{
+		"match":       NewBuiltin("Regex.match", builtinRegexMatch),
+		"replace":     NewBuiltin("Regex.replace", builtinRegexReplace),
+		"replace_all": NewBuiltin("Regex.replace_all", builtinRegexReplaceAll),
+	})
 	engine.builtins["Duration"] = NewObject(map[string]Value{
 		"build": NewBuiltin("Duration.build", func(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
 			if len(args) == 1 && len(kwargs) == 0 {

vibes/runtime_test.go

@@ -1710,6 +1710,50 @@ func TestJSONBuiltins(t *testing.T) {
 	}
 }
 
+func TestRegexBuiltins(t *testing.T) {
+	script := compileScript(t, `
+    def helpers()
+      {
+        match_hit: Regex.match("ID-[0-9]+", "ID-12 ID-34"),
+        match_miss: Regex.match("Z+", "ID-12"),
+        replace_one: Regex.replace("ID-12 ID-34", "ID-[0-9]+", "X"),
+        replace_all: Regex.replace_all("ID-12 ID-34", "ID-[0-9]+", "X"),
+        replace_capture: Regex.replace("ID-12 ID-34", "ID-([0-9]+)", "X-$1")
+      }
+    end
+
+    def invalid_regex()
+      Regex.match("[", "abc")
+    end
+    `)
+
+	result := callFunc(t, script, "helpers", nil)
+	if result.Kind() != KindHash {
+		t.Fatalf("expected hash, got %v", result.Kind())
+	}
+	out := result.Hash()
+	if !out["match_hit"].Equal(NewString("ID-12")) {
+		t.Fatalf("match_hit mismatch: %v", out["match_hit"])
+	}
+	if out["match_miss"].Kind() != KindNil {
+		t.Fatalf("expected match_miss nil, got %v", out["match_miss"])
+	}
+	if !out["replace_one"].Equal(NewString("X ID-34")) {
+		t.Fatalf("replace_one mismatch: %v", out["replace_one"])
+	}
+	if !out["replace_all"].Equal(NewString("X X")) {
+		t.Fatalf("replace_all mismatch: %v", out["replace_all"])
+	}
+	if !out["replace_capture"].Equal(NewString("X-12 ID-34")) {
+		t.Fatalf("replace_capture mismatch: %v", out["replace_capture"])
+	}
+
+	_, err := script.Call(context.Background(), "invalid_regex", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "Regex.match invalid regex") {
+		t.Fatalf("expected invalid regex error, got %v", err)
+	}
+}
+
 func TestRandomIdentifierBuiltins(t *testing.T) {
 	engine := MustNewEngine(Config{
 		RandomReader: bytes.NewReader(bytes.Repeat([]byte{0xAB}, 128)),