Add explicit module export controls

Author: mgomes

ROADMAP.md

@@ -249,7 +249,7 @@ Goal: make multi-file script projects easier to compose and maintain.
 
 ### Module System
 
-- [ ] Add explicit export controls (beyond underscore naming).
+- [x] 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.

docs/builtins.md

@@ -60,7 +60,7 @@ For time manipulation in VibeScript, use the `Time` object (`Time.now`, `Time.pa
 
 ### `require(module_name)`
 
-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:
 
 ```vibe
 def calculate_total(amount)

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()
@@ -44,8 +44,9 @@ 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.
 
 Inside modules, explicit relative requires are supported:
 

docs/integration.md

@@ -75,7 +75,9 @@ and caches compiled modules so subsequent calls to `require` are inexpensive.
 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.
 
 ### Capability Adapters
 

vibes/ast.go

@@ -31,6 +31,7 @@ type FunctionStmt struct {
 	ReturnTy      *TypeExpr
 	Body          []Statement
 	IsClassMethod bool
+	Exported      bool
 	Private       bool
 	position      Position
 }

vibes/execution.go

@@ -22,6 +22,7 @@ type ScriptFunction struct {
 	Body     []Statement
 	Pos      Position
 	Env      *Env
+	Exported bool
 	Private  bool
 	owner    *Script
 }
@@ -3502,7 +3503,7 @@ func (e *Engine) Compile(source string) (*Script, error) {
 			if _, exists := functions[s.Name]; exists {
 				return nil, fmt.Errorf("duplicate function %s", s.Name)
 			}
-			functions[s.Name] = &ScriptFunction{Name: s.Name, Params: s.Params, ReturnTy: s.ReturnTy, Body: s.Body, Pos: s.Pos()}
+			functions[s.Name] = &ScriptFunction{Name: s.Name, Params: s.Params, ReturnTy: s.ReturnTy, Body: s.Body, Pos: s.Pos(), Exported: s.Exported}
 		case *ClassStmt:
 			if _, exists := classes[s.Name]; exists {
 				return nil, fmt.Errorf("duplicate class %s", s.Name)

vibes/lexer.go

@@ -395,6 +395,8 @@ func lookupIdent(ident string) TokenType {
 		return tokenDef
 	case "class":
 		return tokenClass
+	case "export":
+		return tokenExport
 	case "self":
 		return tokenSelf
 	case "private":

vibes/modules.go

@@ -346,6 +346,22 @@ func isPublicModuleExport(name string) bool {
 	return name != "" && !strings.HasPrefix(name, "_")
 }
 
+func moduleHasExplicitExports(functions map[string]*ScriptFunction) bool {
+	for _, fn := range functions {
+		if fn != nil && fn.Exported {
+			return true
+		}
+	}
+	return false
+}
+
+func shouldExportModuleFunction(name string, fn *ScriptFunction, hasExplicitExports bool) bool {
+	if hasExplicitExports {
+		return fn != nil && fn.Exported
+	}
+	return isPublicModuleExport(name)
+}
+
 func builtinRequire(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
 	if exec.strictEffects && !exec.allowRequire {
 		return NewNil(), fmt.Errorf("strict effects: require is disabled without CallOptions.AllowRequire")
@@ -399,11 +415,12 @@ func builtinRequire(exec *Execution, receiver Value, args []Value, kwargs map[st
 
 	moduleEnv := newEnv(exec.root)
 	exports := make(map[string]Value, len(entry.script.functions))
+	hasExplicitExports := moduleHasExplicitExports(entry.script.functions)
 	for name, fn := range entry.script.functions {
 		clone := cloneFunctionForEnv(fn, moduleEnv)
 		fnVal := NewFunction(clone)
 		moduleEnv.Define(name, fnVal)
-		if isPublicModuleExport(name) {
+		if shouldExportModuleFunction(name, fn, hasExplicitExports) {
 			exports[name] = fnVal
 		}
 	}

vibes/modules_test.go

@@ -406,6 +406,82 @@ end`)
 	}
 }
 
+func TestRequireSupportsExplicitExportControls(t *testing.T) {
+	engine := MustNewEngine(Config{ModulePaths: []string{filepath.Join("testdata", "modules")}})
+
+	script, err := engine.Compile(`def run(value)
+  mod = require("explicit_exports")
+  {
+    has_exposed: mod["exposed"] != nil,
+    has_explicit_hidden: mod["_explicit_hidden"] != nil,
+    has_helper: mod["helper"] != nil,
+    has_internal: mod["_internal"] != nil,
+    exposed: mod.exposed(value),
+    explicit_hidden: mod._explicit_hidden(value)
+  }
+end`)
+	if err != nil {
+		t.Fatalf("compile failed: %v", err)
+	}
+
+	result, err := script.Call(context.Background(), "run", []Value{NewInt(3)}, CallOptions{})
+	if err != nil {
+		t.Fatalf("call failed: %v", err)
+	}
+	if result.Kind() != KindHash {
+		t.Fatalf("expected hash result, got %#v", result)
+	}
+	out := result.Hash()
+	if !out["has_exposed"].Bool() || !out["has_explicit_hidden"].Bool() {
+		t.Fatalf("expected explicit exports to be present, got %#v", out)
+	}
+	if out["has_helper"].Bool() || out["has_internal"].Bool() {
+		t.Fatalf("expected non-exported helpers to be hidden, got %#v", out)
+	}
+	if out["exposed"].Kind() != KindInt || out["exposed"].Int() != 10 {
+		t.Fatalf("expected exposed(3)=10, got %#v", out["exposed"])
+	}
+	if out["explicit_hidden"].Kind() != KindInt || out["explicit_hidden"].Int() != 103 {
+		t.Fatalf("expected _explicit_hidden(3)=103, got %#v", out["explicit_hidden"])
+	}
+}
+
+func TestRequireNonExportedFunctionsAreNotInjectedAsGlobalsWhenUsingExplicitExports(t *testing.T) {
+	engine := MustNewEngine(Config{ModulePaths: []string{filepath.Join("testdata", "modules")}})
+
+	script, err := engine.Compile(`def run(value)
+  require("explicit_exports")
+  helper(value)
+end`)
+	if err != nil {
+		t.Fatalf("compile failed: %v", err)
+	}
+
+	if _, err := script.Call(context.Background(), "run", []Value{NewInt(2)}, CallOptions{}); err == nil {
+		t.Fatalf("expected undefined helper error")
+	} else if !strings.Contains(err.Error(), "undefined variable helper") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestExportKeywordValidation(t *testing.T) {
+	engine := MustNewEngine(Config{})
+
+	_, err := engine.Compile(`export helper`)
+	if err == nil || !strings.Contains(err.Error(), "expected 'def'") {
+		t.Fatalf("expected export def parse error, got %v", err)
+	}
+
+	_, err = engine.Compile(`class Example
+  export def value()
+    1
+  end
+end`)
+	if err == nil || !strings.Contains(err.Error(), "export is only supported for top-level functions") {
+		t.Fatalf("expected top-level export parse error, got %v", err)
+	}
+}
+
 func TestRequirePrivateFunctionsAreNotInjectedAsGlobals(t *testing.T) {
 	engine := MustNewEngine(Config{ModulePaths: []string{filepath.Join("testdata", "modules")}})
 

vibes/parser.go

@@ -121,6 +121,8 @@ func (p *parser) parseStatement() Statement {
 		return p.parseFunctionStatement()
 	case tokenClass:
 		return p.parseClassStatement()
+	case tokenExport:
+		return p.parseExportStatement()
 	case tokenReturn:
 		return p.parseReturnStatement()
 	case tokenRaise:
@@ -223,6 +225,32 @@ func (p *parser) parseFunctionStatement() Statement {
 	return &FunctionStmt{Name: name, Params: params, ReturnTy: returnTy, Body: body, IsClassMethod: isClassMethod, Private: private, position: pos}
 }
 
+func (p *parser) parseExportStatement() Statement {
+	pos := p.curToken.Pos
+	if p.insideClass {
+		p.addParseError(pos, "export is only supported for top-level functions")
+		return nil
+	}
+	if !p.expectPeek(tokenDef) {
+		return nil
+	}
+	fnStmt := p.parseFunctionStatement()
+	if fnStmt == nil {
+		return nil
+	}
+	fn, ok := fnStmt.(*FunctionStmt)
+	if !ok {
+		p.addParseError(pos, "export expects a function definition")
+		return nil
+	}
+	if fn.IsClassMethod {
+		p.addParseError(pos, "export cannot be used with class methods")
+		return nil
+	}
+	fn.Exported = true
+	return fn
+}
+
 func (p *parser) parseParams() []Param {
 	params := []Param{}
 	for {
@@ -1181,6 +1209,8 @@ func tokenLabel(tt TokenType) string {
 		return "'def'"
 	case tokenClass:
 		return "'class'"
+	case tokenExport:
+		return "'export'"
 	case tokenSelf:
 		return "'self'"
 	case tokenPrivate: