Merge pull request #48 from mgomes/mgomes/v0-17-0

v0.17.0: module ergonomics and hardening

Author: mgomes

ROADMAP.md

@@ -217,9 +217,9 @@ Goal: improve language ergonomics for complex script logic and recovery behavior
 
 ### Error Handling Constructs
 
-- [ ] Add structured error handling syntax (`begin/rescue/ensure` or equivalent).
-- [ ] Add typed error matching where feasible.
-- [ ] Define re-raise semantics and stack preservation.
+- [x] Add structured error handling syntax (`begin/rescue/ensure` or equivalent).
+- [x] Add typed error matching where feasible.
+- [x] Define re-raise semantics and stack preservation.
 - [x] Ensure runtime errors preserve original position and call frames.
 
 ### Runtime Behavior
@@ -238,7 +238,7 @@ Goal: improve language ergonomics for complex script logic and recovery behavior
 ### v0.16.0 Definition of Done
 
 - [x] No regressions in existing `if/for/range` behavior.
-- [ ] Structured error handling works with assertions and runtime errors.
+- [x] Structured error handling works with assertions and runtime errors.
 - [x] Coverage includes nested/edge control-flow paths.
 
 ---
@@ -249,29 +249,29 @@ Goal: make multi-file script projects easier to compose and maintain.
 
 ### Module System
 
-- [ ] Add explicit export controls (beyond underscore naming).
-- [ ] Add import aliasing for module objects.
-- [ ] Define and enforce module namespace conflict behavior.
-- [ ] Improve cycle error diagnostics with concise chain rendering.
-- [ ] Add module cache invalidation policy for long-running hosts.
+- [x] Add explicit export controls (beyond underscore naming).
+- [x] Add import aliasing for module objects.
+- [x] Define and enforce module namespace conflict behavior.
+- [x] Improve cycle error diagnostics with concise chain rendering.
+- [x] Add module cache invalidation policy for long-running hosts.
 
 ### Security and Isolation
 
-- [ ] Tighten module root boundary checks and path normalization.
-- [ ] Add test coverage for path traversal attempts.
-- [ ] Add explicit policy hooks for module allow/deny lists.
+- [x] Tighten module root boundary checks and path normalization.
+- [x] Add test coverage for path traversal attempts.
+- [x] Add explicit policy hooks for module allow/deny lists.
 
 ### Developer UX
 
-- [ ] Add docs for module project layout best practices.
-- [ ] Add examples for reusable helper modules and namespaced imports.
-- [ ] Add migration guide for existing `require` users.
+- [x] Add docs for module project layout best practices.
+- [x] Add examples for reusable helper modules and namespaced imports.
+- [x] Add migration guide for existing `require` users.
 
 ### v0.17.0 Definition of Done
 
-- [ ] Module APIs are explicit and predictable.
-- [ ] Error output for cycle/import failures is actionable.
-- [ ] Security invariants around module paths are fully tested.
+- [x] Module APIs are explicit and predictable.
+- [x] Error output for cycle/import failures is actionable.
+- [x] Security invariants around module paths are fully tested.
 
 ---
 

docs/builtins.md

@@ -58,13 +58,13 @@ For time manipulation in VibeScript, use the `Time` object (`Time.now`, `Time.pa
 
 ## Module Loading
 
-### `require(module_name)`
+### `require(module_name, as: alias?)`
 
-Loads a module from configured module search paths and returns an object containing the module's exported functions:
+Loads a module from configured module search paths and returns an object containing the module's exported functions. Modules can mark exports explicitly with `export def ...`; when no explicit exports are declared, public (non-underscore) functions are exported by default. Exported functions are injected into globals only when the name is still free (existing globals keep precedence), and `as:` can be used to bind the module object explicitly:
 
 ```vibe
 def calculate_total(amount)
-  helpers = require("fee_calculator")
+  require("fee_calculator", as: "helpers")
   amount + helpers.calculate_fee(amount)
 end
 ```

docs/errors.md

@@ -62,6 +62,44 @@ Loop control diagnostics are explicit:
 
 These boundary errors happen when `break`/`next` are raised inside called blocks/functions and attempt to escape into an outer loop.
 
+## Structured Error Handling
+
+Use `begin` with `rescue` and/or `ensure` for script-level recovery:
+
+```vibe
+def safe_div(a, b)
+  begin
+    a / b
+  rescue(RuntimeError)
+    "fallback"
+  ensure
+    audit("safe_div attempted")
+  end
+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.
+- `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.
+- 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
 
 The REPL stores the previous failure. Use:

docs/examples/module_require.md

@@ -18,12 +18,12 @@ Place `modules/fees.vibe` on disk:
 ```vibe
 # modules/fees.vibe
 
-def rate()
-  1
+export def apply_fee(amount)
+  amount + rate()
 end
 
-def apply_fee(amount)
-  amount + rate()
+def rate()
+  1
 end
 
 def _rounding_hint()
@@ -37,15 +37,28 @@ A main script can load the helpers and use the exported functions:
 # scripts/checkout.vibe
 
 def total_with_fee(amount)
-  fees = require("fees")
+  require("fees", as: "fees")
   fees.apply_fee(amount)
 end
 ```
 
+Namespaced imports scale better as helper sets grow:
+
+```vibe
+def quote_total(amount)
+  require("billing/fees", as: "fees")
+  require("billing/taxes", as: "taxes")
+  taxes.apply(fees.apply(amount))
+end
+```
+
 When `total_with_fee` runs, `require("fees")` resolves the module relative to
 `Config.ModulePaths`, compiles it once, and returns an object containing the
-module’s public exports. Function names starting with `_` stay private to the
-module and are not exposed on the returned object or injected globally.
+module’s exports. Use `export def` for explicit control; if no explicit exports
+are declared, public functions are exported by default and names starting with
+`_` stay private to the module. When an exported name conflicts with an
+existing global, the existing binding keeps precedence and the module object
+remains the conflict-free access path.
 
 Inside modules, explicit relative requires are supported:
 
@@ -57,9 +70,24 @@ def compute(amount)
 end
 ```
 
+Reusable helper modules can be shared from a central namespace:
+
+```vibe
+# modules/shared/currency.vibe
+export def cents(value)
+  value * 100
+end
+
+# modules/billing/taxes.vibe
+export def apply(amount)
+  require("../shared/currency", as: "currency")
+  amount + currency.cents(1)
+end
+```
+
 Relative requires (`./` and `../`) resolve from the requiring module’s
 directory and cannot escape the configured module root.
 
 After the first load the module is cached, making subsequent `require` calls
 cheap. To refresh or hot reload modules, restart the embedding application or
-clear the engine’s module cache.
+call `engine.ClearModuleCache()` between runs.

docs/integration.md

@@ -65,17 +65,31 @@ if err != nil {
 }
 
 script, err := engine.Compile(`def total(amount)
-  helpers = require("fees")
+  require("fees", as: "helpers")
   helpers.apply_fee(amount)
 end`)
 ```
 
 The interpreter searches each configured directory for `<module>.vibe` in order
 and caches compiled modules so subsequent calls to `require` are inexpensive.
+For long-running hosts, call `engine.ClearModuleCache()` between runs when
+module sources can change.
+Use `Config.ModuleAllowList` / `Config.ModuleDenyList` for policy hooks over
+which modules may be loaded (`*` glob patterns against normalized module names,
+with deny-list rules taking precedence).
+When a circular module dependency is detected, the runtime reports a concise
+chain (for example `a -> b -> a`).
+Use the optional `as:` keyword to bind the loaded module object to a global
+alias.
 Inside a module, use explicit relative paths (`./` or `../`) to load siblings
 or parent-local helpers. Relative requires are resolved from the calling
 module's directory and are rejected if they escape the module root. Functions
-whose names start with `_` are private and are not exported.
+can be exported explicitly with `export def ...`; if no explicit exports are
+declared, public names are exported by default and names starting with `_`
+remain private. Exported names are only injected into globals when no binding
+already exists, so existing host/script globals keep precedence.
+Import paths are normalized across slash styles, and traversal/symlink escapes
+outside configured module roots are blocked.
 
 ### Capability Adapters
 

docs/introduction.md

@@ -24,5 +24,9 @@ dives on specific topics.
 - `blocks.md` – using block literals for map/select/reduce style patterns.
 - `integration.md` – host integration patterns showing how Go services can
   expose capabilities to scripts.
+- `module_project_layout.md` – recommended structure for multi-module script
+  repositories.
+- `module_require_migration.md` – migration checklist for modern `require`
+  behavior (exports, aliasing, policy hooks).
 - `examples/module_require.md` – practical example showing how to share
   helpers with `require` and module search paths.

docs/module_project_layout.md

@@ -0,0 +1,48 @@
+# Module Project Layout Best Practices
+
+Use a stable directory layout so module paths stay predictable:
+
+```text
+workflows/
+  modules/
+    shared/
+      math.vibe
+      money.vibe
+    billing/
+      fees.vibe
+      taxes.vibe
+  scripts/
+    checkout.vibe
+    payouts.vibe
+```
+
+Guidelines:
+
+- Keep reusable helpers under `modules/shared/`.
+- Group domain logic by folder (`billing/`, `risk/`, `reporting/`).
+- Prefer `export def ...` for public API surface, keep internals unexported.
+- Use `require("module/path", as: "alias")` to avoid global name collisions.
+- Use relative requires only within a module subtree (`./`, `../`).
+- Configure `ModuleAllowList` and `ModuleDenyList` in hosts that need strict import policy boundaries.
+
+Example:
+
+```vibe
+# modules/billing/fees.vibe
+export def apply(amount)
+  amount + shared_rate()
+end
+
+def shared_rate()
+  rates = require("../shared/math", as: "math")
+  math.double(1)
+end
+```
+
+```vibe
+# scripts/checkout.vibe
+def total(amount)
+  require("billing/fees", as: "fees")
+  fees.apply(amount)
+end
+```

docs/module_require_migration.md

@@ -0,0 +1,60 @@
+# Migration Guide for `require`
+
+This guide helps older scripts move to the current module model.
+
+## 1. Prefer explicit exports
+
+Before:
+
+```vibe
+def apply_fee(amount)
+  amount + 1
+end
+```
+
+After:
+
+```vibe
+export def apply_fee(amount)
+  amount + 1
+end
+```
+
+If a module has no `export def`, non-underscore functions are still exported.
+
+## 2. Use aliases for namespacing
+
+Before:
+
+```vibe
+fees = require("fees")
+fees.apply_fee(amount)
+```
+
+After:
+
+```vibe
+require("fees", as: "fees")
+fees.apply_fee(amount)
+```
+
+Aliases make import intent explicit and reduce global collisions.
+
+## 3. Plan for conflict behavior
+
+- Existing globals are not overwritten by module exports.
+- Access conflicting functions through the returned/aliased module object.
+- Alias collisions raise runtime errors (`alias "<name>" already defined`).
+
+## 4. Add policy boundaries in hosts
+
+For long-running or multi-tenant hosts:
+
+- Configure `ModuleAllowList` and `ModuleDenyList`.
+- Use `engine.ClearModuleCache()` when module sources may change.
+
+## 5. Validate with tests
+
+- Add integration tests for required module paths.
+- Add negative tests for denied modules and traversal attempts.
+- Verify cycle errors are actionable (`a -> b -> a`).

vibes/ast.go

@@ -31,6 +31,7 @@ type FunctionStmt struct {
 	ReturnTy      *TypeExpr
 	Body          []Statement
 	IsClassMethod bool
+	Exported      bool
 	Private       bool
 	position      Position
 }
@@ -84,6 +85,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
@@ -154,6 +163,17 @@ type NextStmt struct {
 func (s *NextStmt) stmtNode()     {}
 func (s *NextStmt) Pos() Position { return s.position }
 
+type TryStmt struct {
+	Body     []Statement
+	RescueTy *TypeExpr
+	Rescue   []Statement
+	Ensure   []Statement
+	position Position
+}
+
+func (s *TryStmt) stmtNode()     {}
+func (s *TryStmt) Pos() Position { return s.position }
+
 type Identifier struct {
 	Name     string
 	position Position