Add typed shape syntax for hash payload contracts

mgomes · mgomes · commit 838f1fb7cb99 · 2026-02-18T22:35:51.000-05:00
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -170,7 +170,7 @@ Goal: make types expressive enough for real workflows while keeping runtime chec
 
 - [x] Add parametric container types: `array<T>`, `hash<K, V>`.
 - [x] Add union types beyond nil: `A | B`.
-- [ ] Add typed object/hash shape syntax for common payload contracts.
+- [x] Add typed object/hash shape syntax for common payload contracts.
 - [ ] Add typed block signatures where appropriate.
 - [ ] Define type display formatting for readable runtime errors.
 
@@ -190,8 +190,8 @@ Goal: make types expressive enough for real workflows while keeping runtime chec
 
 ### Testing and Docs
 
-- [ ] Add parser tests for all new type syntax forms.
-- [ ] Add runtime tests for nested composite type checks.
+- [x] Add parser tests for all new type syntax forms.
+- [x] Add runtime tests for nested composite type checks.
 - [ ] Add regression tests for existing `any` and nullable behavior.
 - [ ] Expand `docs/typing.md` with migration examples.
 
diff --git a/docs/typing.md b/docs/typing.md
@@ -18,6 +18,12 @@ Parametric containers:
 - `hash<K, V>` checks each key against `K` and each value against `V`
 - Example: `array<int>`, `array<int | string>`, `hash<string, int>`
 
+Shape types for object/hash payload contracts:
+
+- `{ id: string, score: int }` requires exactly those keys
+- Field values are recursively type-checked
+- Extra keys and missing keys fail validation
+
 Nullable: append `?` to allow `nil` (e.g., `string?`, `time?`, `int?`).
 
 Unions: join allowed types with `|` (e.g., `int | string`, `int | nil`).
@@ -39,6 +45,10 @@ def normalize_id(id: int | string) -> string
   id.string
 end
 
+def apply_bonus(payload: { id: string, points: int }) -> { id: string, points: int }
+  { id: payload[:id], points: payload[:points] + 5 }
+end
+
 def nil_result() -> nil
   nil
 end
@@ -70,4 +80,5 @@ Duration methods like `ago`/`after` return `Time`. Typed signatures use `time` o
 
 - Types are nominal by kind.
 - Hash keys are runtime strings, so `hash<K, V>` key checks run against string keys.
+- Shape types are strict: keys must match exactly.
 - Type names are case-insensitive (`Int` == `int`).
diff --git a/vibes/ast.go b/vibes/ast.go
@@ -61,6 +61,7 @@ const (
 	TypeArray
 	TypeHash
 	TypeFunction
+	TypeShape
 	TypeUnion
 	TypeUnknown
 )
@@ -70,6 +71,7 @@ type TypeExpr struct {
 	Kind     TypeKind
 	Nullable bool
 	TypeArgs []*TypeExpr
+	Shape    map[string]*TypeExpr
 	Union    []*TypeExpr
 	position Position
 }
diff --git a/vibes/execution.go b/vibes/execution.go
@@ -3360,6 +3360,33 @@ func valueMatchesType(val Value, ty *TypeExpr) (bool, error) {
 		return true, nil
 	case TypeFunction:
 		return val.Kind() == KindFunction, nil
+	case TypeShape:
+		if val.Kind() != KindHash && val.Kind() != KindObject {
+			return false, nil
+		}
+		entries := val.Hash()
+		if len(ty.Shape) == 0 {
+			return len(entries) == 0, nil
+		}
+		for field, fieldType := range ty.Shape {
+			fieldVal, ok := entries[field]
+			if !ok {
+				return false, nil
+			}
+			matches, err := valueMatchesType(fieldVal, fieldType)
+			if err != nil {
+				return false, err
+			}
+			if !matches {
+				return false, nil
+			}
+		}
+		for field := range entries {
+			if _, ok := ty.Shape[field]; !ok {
+				return false, nil
+			}
+		}
+		return true, nil
 	case TypeUnion:
 		for _, option := range ty.Union {
 			matches, err := valueMatchesType(val, option)
@@ -3420,6 +3447,8 @@ func formatTypeExpr(ty *TypeExpr) string {
 		name = "hash"
 	case TypeFunction:
 		name = "function"
+	case TypeShape:
+		name = formatShapeType(ty)
 	default:
 		name = ty.Name
 	}
@@ -3439,6 +3468,22 @@ func formatTypeExpr(ty *TypeExpr) string {
 	return name
 }
 
+func formatShapeType(ty *TypeExpr) string {
+	if ty == nil || len(ty.Shape) == 0 {
+		return "{}"
+	}
+	fields := make([]string, 0, len(ty.Shape))
+	for field := range ty.Shape {
+		fields = append(fields, field)
+	}
+	sort.Strings(fields)
+	parts := make([]string, len(fields))
+	for i, field := range fields {
+		parts[i] = fmt.Sprintf("%s: %s", field, formatTypeExpr(ty.Shape[field]))
+	}
+	return "{ " + strings.Join(parts, ", ") + " }"
+}
+
 // Function looks up a compiled function by name.
 func (s *Script) Function(name string) (*ScriptFunction, bool) {
 	fn, ok := s.functions[name]
diff --git a/vibes/parser.go b/vibes/parser.go
@@ -1025,6 +1025,9 @@ func (p *parser) parseTypeExpr() *TypeExpr {
 }
 
 func (p *parser) parseTypeAtom() *TypeExpr {
+	if p.curToken.Type == tokenLBrace {
+		return p.parseTypeShape()
+	}
 	if p.curToken.Type != tokenIdent && p.curToken.Type != tokenNil {
 		p.errorExpected(p.curToken, "type name")
 		return nil
@@ -1063,3 +1066,68 @@ func (p *parser) parseTypeAtom() *TypeExpr {
 
 	return ty
 }
+
+func (p *parser) parseTypeShape() *TypeExpr {
+	pos := p.curToken.Pos
+	fields := make(map[string]*TypeExpr)
+
+	if p.peekToken.Type == tokenRBrace {
+		p.nextToken()
+		return &TypeExpr{
+			Kind:     TypeShape,
+			Shape:    fields,
+			position: pos,
+		}
+	}
+
+	p.nextToken()
+	for {
+		key, ok := p.parseTypeShapeFieldName()
+		if !ok {
+			return nil
+		}
+		if p.peekToken.Type != tokenColon {
+			p.errorExpected(p.peekToken, ":")
+			return nil
+		}
+		p.nextToken()
+		p.nextToken()
+		fieldType := p.parseTypeExpr()
+		if fieldType == nil {
+			return nil
+		}
+		if _, exists := fields[key]; exists {
+			p.addParseError(p.curToken.Pos, fmt.Sprintf("duplicate shape field %s", key))
+			return nil
+		}
+		fields[key] = fieldType
+
+		if p.peekToken.Type == tokenComma {
+			p.nextToken()
+			p.nextToken()
+			continue
+		}
+		if p.peekToken.Type != tokenRBrace {
+			p.errorExpected(p.peekToken, "}")
+			return nil
+		}
+		p.nextToken()
+		break
+	}
+
+	return &TypeExpr{
+		Kind:     TypeShape,
+		Shape:    fields,
+		position: pos,
+	}
+}
+
+func (p *parser) parseTypeShapeFieldName() (string, bool) {
+	switch p.curToken.Type {
+	case tokenIdent, tokenString, tokenSymbol:
+		return p.curToken.Literal, true
+	default:
+		p.errorExpected(p.curToken, "shape field name")
+		return "", false
+	}
+}
diff --git a/vibes/parser_types_test.go b/vibes/parser_types_test.go
@@ -0,0 +1,83 @@
+package vibes
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParserTypeSyntaxCompositeForms(t *testing.T) {
+	source := `def run(
+  rows: array<int | string>,
+  payload: { id: string, stats: { wins: int } }
+) -> hash<string, { score: int | nil }>
+  payload
+end`
+
+	p := newParser(source)
+	program, errs := p.ParseProgram()
+	if len(errs) > 0 {
+		t.Fatalf("expected no parse errors, got %v", errs)
+	}
+	if len(program.Statements) != 1 {
+		t.Fatalf("expected 1 statement, got %d", len(program.Statements))
+	}
+	fn, ok := program.Statements[0].(*FunctionStmt)
+	if !ok {
+		t.Fatalf("expected function statement, got %T", program.Statements[0])
+	}
+	if len(fn.Params) != 2 {
+		t.Fatalf("expected 2 params, got %d", len(fn.Params))
+	}
+
+	rowsType := fn.Params[0].Type
+	if rowsType == nil || rowsType.Kind != TypeArray || len(rowsType.TypeArgs) != 1 {
+		t.Fatalf("expected array<T> param, got %#v", rowsType)
+	}
+	elemType := rowsType.TypeArgs[0]
+	if elemType.Kind != TypeUnion || len(elemType.Union) != 2 {
+		t.Fatalf("expected union element type, got %#v", elemType)
+	}
+
+	payloadType := fn.Params[1].Type
+	if payloadType == nil || payloadType.Kind != TypeShape {
+		t.Fatalf("expected shape payload type, got %#v", payloadType)
+	}
+	if _, ok := payloadType.Shape["id"]; !ok {
+		t.Fatalf("expected shape field id")
+	}
+	statsType, ok := payloadType.Shape["stats"]
+	if !ok || statsType.Kind != TypeShape {
+		t.Fatalf("expected nested stats shape, got %#v", statsType)
+	}
+	winsType, ok := statsType.Shape["wins"]
+	if !ok || winsType.Kind != TypeInt {
+		t.Fatalf("expected stats.wins int type, got %#v", winsType)
+	}
+
+	if fn.ReturnTy == nil || fn.ReturnTy.Kind != TypeHash || len(fn.ReturnTy.TypeArgs) != 2 {
+		t.Fatalf("expected hash<K,V> return type, got %#v", fn.ReturnTy)
+	}
+	valueType := fn.ReturnTy.TypeArgs[1]
+	if valueType.Kind != TypeShape {
+		t.Fatalf("expected shaped hash value type, got %#v", valueType)
+	}
+	scoreType, ok := valueType.Shape["score"]
+	if !ok || scoreType.Kind != TypeUnion || len(scoreType.Union) != 2 {
+		t.Fatalf("expected score union type, got %#v", scoreType)
+	}
+}
+
+func TestParserTypeShapeRejectsDuplicateFields(t *testing.T) {
+	source := `def run(payload: { id: string, id: int })
+  payload
+end`
+
+	p := newParser(source)
+	_, errs := p.ParseProgram()
+	if len(errs) == 0 {
+		t.Fatalf("expected parse errors")
+	}
+	if got := errs[0].Error(); !strings.Contains(got, "duplicate shape field id") {
+		t.Fatalf("unexpected parse error: %s", got)
+	}
+}
diff --git a/vibes/runtime_test.go b/vibes/runtime_test.go
@@ -1183,6 +1183,14 @@ func TestTypedFunctions(t *testing.T) {
     def mixed_items(values: array<int | string>) -> array<int | string>
       values
     end
+
+    def player_payload(payload: { id: string, score: int, active: bool? }) -> { id: string, score: int, active: bool? }
+      payload
+    end
+
+    def shaped_rows(rows: array<{ id: string, stats: { wins: int } }>) -> array<{ id: string, stats: { wins: int } }>
+      rows
+    end
     `)
 
 	if fn, ok := script.Function("bad_return"); !ok || fn.ReturnTy == nil {
@@ -1224,6 +1232,23 @@ func TestTypedFunctions(t *testing.T) {
 	if got := callFunc(t, script, "mixed_items", []Value{NewArray([]Value{NewInt(1), NewString("two"), NewInt(3)})}); got.Kind() != KindArray {
 		t.Fatalf("mixed_items expected array result, got %v", got.Kind())
 	}
+	if got := callFunc(t, script, "player_payload", []Value{NewHash(map[string]Value{
+		"id":     NewString("p-1"),
+		"score":  NewInt(42),
+		"active": NewNil(),
+	})}); got.Kind() != KindHash {
+		t.Fatalf("player_payload expected hash result, got %v", got.Kind())
+	}
+	if got := callFunc(t, script, "shaped_rows", []Value{NewArray([]Value{
+		NewHash(map[string]Value{
+			"id": NewString("p-1"),
+			"stats": NewHash(map[string]Value{
+				"wins": NewInt(7),
+			}),
+		}),
+	})}); got.Kind() != KindArray {
+		t.Fatalf("shaped_rows expected array result, got %v", got.Kind())
+	}
 	if got := callFunc(t, script, "nil_result", nil); !got.Equal(NewNil()) {
 		t.Fatalf("nil_result mismatch: %v", got)
 	}
@@ -1288,6 +1313,42 @@ func TestTypedFunctions(t *testing.T) {
 	if err == nil || !strings.Contains(err.Error(), "expected array<int | string>") {
 		t.Fatalf("expected typed union array arg error, got %v", err)
 	}
+
+	_, err = script.Call(context.Background(), "player_payload", []Value{
+		NewHash(map[string]Value{
+			"id":    NewString("p-1"),
+			"score": NewInt(42),
+			"role":  NewString("captain"),
+		}),
+	}, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "expected { active: bool?, id: string, score: int }") {
+		t.Fatalf("expected shape extra-field error, got %v", err)
+	}
+
+	_, err = script.Call(context.Background(), "player_payload", []Value{
+		NewHash(map[string]Value{
+			"id":     NewString("p-1"),
+			"score":  NewString("wrong"),
+			"active": NewBool(true),
+		}),
+	}, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "expected { active: bool?, id: string, score: int }") {
+		t.Fatalf("expected shape field-type error, got %v", err)
+	}
+
+	_, err = script.Call(context.Background(), "shaped_rows", []Value{
+		NewArray([]Value{
+			NewHash(map[string]Value{
+				"id": NewString("p-1"),
+				"stats": NewHash(map[string]Value{
+					"wins": NewString("bad"),
+				}),
+			}),
+		}),
+	}, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "expected array<{ id: string, stats: { wins: int } }>") {
+		t.Fatalf("expected nested shape error, got %v", err)
+	}
 }
 
 func TestArrayAndHashHelpers(t *testing.T) {
