Define module namespace conflict behavior

Author: mgomes

ROADMAP.md

@@ -251,7 +251,7 @@ Goal: make multi-file script projects easier to compose and maintain.
 
 - [x] Add explicit export controls (beyond underscore naming).
 - [x] Add import aliasing for module objects.
-- [ ] Define and enforce module namespace conflict behavior.
+- [x] Define and enforce module namespace conflict behavior.
 - [ ] Improve cycle error diagnostics with concise chain rendering.
 - [ ] Add module cache invalidation policy for long-running hosts.
 

docs/builtins.md

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

docs/examples/module_require.md

@@ -46,7 +46,9 @@ 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 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.
+`_` 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:
 

docs/integration.md

@@ -79,7 +79,8 @@ or parent-local helpers. Relative requires are resolved from the calling
 module's directory and are rejected if they escape the module root. Functions
 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.
+remain private. Exported names are only injected into globals when no binding
+already exists, so existing host/script globals keep precedence.
 
 ### Capability Adapters
 

vibes/modules.go

@@ -429,6 +429,15 @@ func bindRequireAlias(root *Env, alias string, module Value) error {
 	return nil
 }
 
+func bindModuleExportsWithoutOverwrite(root *Env, exports map[string]Value) {
+	for name, fnVal := range exports {
+		if _, exists := root.Get(name); exists {
+			continue
+		}
+		root.Define(name, fnVal)
+	}
+}
+
 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")
@@ -499,12 +508,7 @@ func builtinRequire(exec *Execution, receiver Value, args []Value, kwargs map[st
 		}
 	}
 
-	for name, fnVal := range exports {
-		if _, exists := exec.root.Get(name); exists {
-			continue
-		}
-		exec.root.Define(name, fnVal)
-	}
+	bindModuleExportsWithoutOverwrite(exec.root, exports)
 
 	exportsVal := NewObject(exports)
 	exec.modules[entry.key] = exportsVal

vibes/modules_test.go

@@ -149,6 +149,80 @@ end`)
 	}
 }
 
+func TestRequireNamespaceConflictKeepsExistingGlobalBinding(t *testing.T) {
+	engine := MustNewEngine(Config{ModulePaths: []string{filepath.Join("testdata", "modules")}})
+
+	script, err := engine.Compile(`def double(value)
+  value + 1
+end
+
+def run(value)
+  mod = require("helper")
+  {
+    global: double(value),
+    module: mod.double(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["global"].Kind() != KindInt || out["global"].Int() != 4 {
+		t.Fatalf("expected global binding to stay at 4, got %#v", out["global"])
+	}
+	if out["module"].Kind() != KindInt || out["module"].Int() != 6 {
+		t.Fatalf("expected module object function to return 6, got %#v", out["module"])
+	}
+}
+
+func TestRequireNamespaceConflictKeepsFirstModuleBinding(t *testing.T) {
+	engine := MustNewEngine(Config{ModulePaths: []string{filepath.Join("testdata", "modules")}})
+
+	script, err := engine.Compile(`def run(value)
+  first = require("helper")
+  second = require("helper_alt")
+  require("helper_alt", as: "alt")
+  {
+    global: double(value),
+    first: first.double(value),
+    second: second.double(value),
+    alias: alt.double(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["global"].Kind() != KindInt || out["global"].Int() != 6 {
+		t.Fatalf("expected first module binding to stay global at 6, got %#v", out["global"])
+	}
+	if out["first"].Kind() != KindInt || out["first"].Int() != 6 {
+		t.Fatalf("expected first module object to return 6, got %#v", out["first"])
+	}
+	if out["second"].Kind() != KindInt || out["second"].Int() != 30 {
+		t.Fatalf("expected second module object to return 30, got %#v", out["second"])
+	}
+	if out["alias"].Kind() != KindInt || out["alias"].Int() != 30 {
+		t.Fatalf("expected alias module object to return 30, got %#v", out["alias"])
+	}
+}
+
 func TestRequireMissingModule(t *testing.T) {
 	engine := MustNewEngine(Config{ModulePaths: []string{filepath.Join("testdata", "modules")}})
 

vibes/testdata/modules/helper_alt.vibe

@@ -0,0 +1,3 @@
+def double(value)
+  value * 10
+end