Merge pull request #46 from mgomes/mgomes/v0-15-0

v0.15.0: type system v2

Author: mgomes

ROADMAP.md

@@ -20,8 +20,9 @@ Release status legend:
 ## Historical Completed Releases
 
 These releases are already shipped and tagged.
+Completion dates reflect the corresponding git tag date.
 
-### v0.1.0
+### v0.1.0 (completed 2025-12-15)
 
 - [x] Added GitHub Actions CI workflow.
 - [x] Added stack traces to runtime errors.
@@ -30,95 +31,95 @@ These releases are already shipped and tagged.
 - [x] Added initial CLI support.
 - [x] Fixed package/versioning setup for release tagging.
 
-### v0.2.0
+### v0.2.0 (completed 2025-12-15)
 
 - [x] Added GoReleaser-based release automation.
 - [x] Added recursion depth limit enforcement.
 - [x] Added recursion limit test coverage.
 
-### v0.2.1
+### v0.2.1 (completed 2025-12-15)
 
 - [x] Pinned GoReleaser version for stable release builds.
 
-### v0.2.2
+### v0.2.2 (completed 2025-12-15)
 
 - [x] Adjusted GoReleaser configuration.
 
-### v0.3.0
+### v0.3.0 (completed 2025-12-20)
 
 - [x] Added `Number#times`.
 - [x] Added `Duration` class modeled after ActiveSupport-style duration semantics.
 
-### v0.4.0
+### v0.4.0 (completed 2025-12-21)
 
 - [x] Added duration arithmetic support.
 - [x] Improved optional-parens behavior for zero-arg methods.
 - [x] Implemented `Time` class.
 
-### v0.4.1
+### v0.4.1 (completed 2025-12-21)
 
 - [x] Renamed `Time#strftime` to `Time#format` for Go layout alignment.
 - [x] Added Duration and Time documentation.
 
-### v0.5.0
+### v0.5.0 (completed 2025-12-26)
 
 - [x] Added first pass of gradual typing.
 - [x] Added support for classes.
 - [x] Added block arguments in method definitions.
 - [x] Added numeric literal underscore separators.
 - [x] Expanded complex tests/examples coverage.
 
-### v0.5.1
+### v0.5.1 (completed 2026-02-07)
 
 - [x] Expanded test suite breadth.
 - [x] Landed performance optimizations and refactors.
 - [x] Exported `CallBlock()` for embedders.
 
-### v0.6.0
+### v0.6.0 (completed 2026-02-11)
 
 - [x] Added runtime memory quota enforcement.
 - [x] Enforced strict effects for globals and `require`.
 - [x] Isolated `Script.Call` runtime state per invocation.
 - [x] Replaced panicking constructors with error-returning APIs.
 - [x] Increased CLI/REPL test coverage and added execution benchmarks.
 
-### v0.7.0
+### v0.7.0 (completed 2026-02-12)
 
 - [x] Shipped multi-phase string helper expansion.
 - [x] Added regex/byte helper coverage and bang-method parity improvements.
 
-### v0.8.0
+### v0.8.0 (completed 2026-02-12)
 
 - [x] Expanded Hash built-ins and hash manipulation support.
 - [x] Refreshed hash docs and examples.
 
-### v0.9.0
+### v0.9.0 (completed 2026-02-12)
 
 - [x] Expanded Array helper surface and enumerable workflows.
 
-### v0.10.0
+### v0.10.0 (completed 2026-02-12)
 
 - [x] Made Time and numeric APIs coherent with documented behavior.
 
-### v0.11.0
+### v0.11.0 (completed 2026-02-12)
 
 - [x] Improved parse/runtime error feedback and debugging quality.
 
-### v0.12.0
+### v0.12.0 (completed 2026-02-13)
 
 - [x] Hardened `require` behavior for safer module composition.
 - [x] Improved private helper/module boundary behavior.
 - [x] Improved circular dependency diagnostics for modules.
 
-### v0.13.0
+### v0.13.0 (completed 2026-02-17)
 
 - [x] Enforced capability contracts at runtime boundaries.
 - [x] Added contract validation paths for capability args and returns.
 - [x] Improved capability isolation and contract binding behavior.
 
 ---
 
-## v0.14.0 - Capability Foundations
+## v0.14.0 - Capability Foundations (completed 2026-02-18)
 
 Goal: make host integrations first-class and safe enough for production workflows.
 
@@ -167,11 +168,11 @@ Goal: make types expressive enough for real workflows while keeping runtime chec
 
 ### Type Features
 
-- [ ] Add parametric container types: `array<T>`, `hash<K, V>`.
-- [ ] Add union types beyond nil: `A | B`.
-- [ ] Add typed object/hash shape syntax for common payload contracts.
-- [ ] Add typed block signatures where appropriate.
-- [ ] Define type display formatting for readable runtime errors.
+- [x] Add parametric container types: `array<T>`, `hash<K, V>`.
+- [x] Add union types beyond nil: `A | B`.
+- [x] Add typed object/hash shape syntax for common payload contracts.
+- [x] Add typed block signatures where appropriate.
+- [x] Define type display formatting for readable runtime errors.
 
 ### Type Semantics
 
@@ -182,23 +183,23 @@ Goal: make types expressive enough for real workflows while keeping runtime chec
 
 ### Runtime and Parser
 
-- [ ] Extend parser grammar for generic and union type expressions.
-- [ ] Extend type resolver and internal type representation.
-- [ ] Add runtime validators for composite/union types.
+- [x] Extend parser grammar for generic and union type expressions.
+- [x] Extend type resolver and internal type representation.
+- [x] Add runtime validators for composite/union types.
 - [ ] Add contract interop so capability contracts can reuse type validators.
 
 ### Testing and Docs
 
-- [ ] Add parser tests for all new type syntax forms.
-- [ ] Add runtime tests for nested composite type checks.
-- [ ] Add regression tests for existing `any` and nullable behavior.
-- [ ] Expand `docs/typing.md` with migration examples.
+- [x] Add parser tests for all new type syntax forms.
+- [x] Add runtime tests for nested composite type checks.
+- [x] Add regression tests for existing `any` and nullable behavior.
+- [x] Expand `docs/typing.md` with migration examples.
 
 ### v0.15.0 Definition of Done
 
-- [ ] Existing scripts without annotations remain compatible.
-- [ ] Type errors include parameter name, expected type, and actual type.
-- [ ] Capability contract validation can use the same type primitives.
+- [x] Existing scripts without annotations remain compatible.
+- [x] Type errors include parameter name, expected type, and actual type.
+- [x] Capability contract validation can use the same type primitives.
 
 ---
 

docs/typing.md

@@ -12,8 +12,22 @@ Type names are case-insensitive:
 - `array`, `hash`/`object`, `function`
 - `any` (no checks)
 
+Parametric containers:
+
+- `array<T>` checks every element against `T`
+- `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`).
+
 ## Function definitions
 
 Method declarations omit parentheses when there are no args:
@@ -27,6 +41,14 @@ def pick_optional(label: string? = nil) -> string?
   label
 end
 
+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
@@ -50,12 +72,119 @@ Unknown keyword args and missing required args raise errors.
 
 If a return type is annotated, the returned value is checked. If omitted, no return check is enforced.
 
+## Migration examples
+
+Use a boundary-first strategy: annotate entrypoints that receive external data, then tighten helpers and block callbacks.
+
+### 1) Start with function boundaries
+
+Before:
+
+```vibe
+def calculate_total(items)
+  items.reduce(0) do |acc, item|
+    acc + item[:amount]
+  end
+end
+```
+
+After:
+
+```vibe
+def calculate_total(items: array<{ amount: int }>) -> int
+  items.reduce(0) do |acc: int, item: { amount: int }|
+    acc + item[:amount]
+  end
+end
+```
+
+### 2) Migrate optional values with nullable or unions
+
+Before:
+
+```vibe
+def normalize_id(id)
+  if id == nil
+    "unknown"
+  else
+    id.string
+  end
+end
+```
+
+After:
+
+```vibe
+def normalize_id(id: int | string | nil) -> string
+  if id == nil
+    "unknown"
+  else
+    id.string
+  end
+end
+```
+
+Use `T?` when the only optional case is `nil`, and use unions when multiple concrete kinds are allowed.
+
+### 3) Convert loose hashes to shape contracts
+
+Before:
+
+```vibe
+def reward(payload)
+  { id: payload[:id], points: payload[:points] + 10 }
+end
+```
+
+After:
+
+```vibe
+def reward(payload: { id: string, points: int }) -> { id: string, points: int }
+  { id: payload[:id], points: payload[:points] + 10 }
+end
+```
+
+Shapes are strict. Missing or extra keys fail checks.
+
+### 4) Annotate block signatures where callbacks matter
+
+Before:
+
+```vibe
+def render_scores(scores)
+  scores.map do |s|
+    s + 1
+  end
+end
+```
+
+After:
+
+```vibe
+def render_scores(scores: array<int>) -> array<int>
+  scores.map do |s: int|
+    s + 1
+  end
+end
+```
+
+Typed blocks catch callback mismatches at runtime with errors that include parameter name, expected type, and actual type.
+
+### 5) Roll out incrementally
+
+- Add annotations to one high-value path first.
+- Keep internal helpers untyped until boundary contracts stabilize.
+- Use `any` as a temporary bridge during migration.
+- Replace `any` with concrete or shape types once call sites are clean.
+- Watch runtime type errors in staging, then tighten signatures further.
+
 ## Time and Duration
 
 Duration methods like `ago`/`after` return `Time`. Typed signatures use `time` or `time?` for those values.
 
 ## Notes and limitations
 
-- Types are nominal by kind (no generics like `array<int>` yet).
-- Nullable via `?` only; unions beyond `nil` are not supported yet.
+- 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`).

vibes/ast.go

@@ -61,13 +61,18 @@ const (
 	TypeArray
 	TypeHash
 	TypeFunction
+	TypeShape
+	TypeUnion
 	TypeUnknown
 )
 
 type TypeExpr struct {
 	Name     string
 	Kind     TypeKind
 	Nullable bool
+	TypeArgs []*TypeExpr
+	Shape    map[string]*TypeExpr
+	Union    []*TypeExpr
 	position Position
 }
 
@@ -272,7 +277,7 @@ func (e *RangeExpr) exprNode()     {}
 func (e *RangeExpr) Pos() Position { return e.position }
 
 type BlockLiteral struct {
-	Params   []string
+	Params   []Param
 	Body     []Statement
 	position Position
 }