doc: disambiguate overlapping module and bridge names

Names like "os" and "json" exist as both a stdlib module (use) and a
bridge package (import). Previously, "rugo doc os" always showed the
stdlib module with no way to view the bridge package.

Now rugo doc detects the conflict and asks you to be explicit:

  rugo doc use:os      # stdlib module
  rugo doc import:os   # bridge package

Unambiguous names like "http" or "strings" continue to work without a
prefix.

Author: rubiojr

cmd/cmd.go

@@ -142,7 +142,7 @@ func Execute(version string) {
 			{
 				Name:      "doc",
 				Usage:     "Show documentation for files, modules, and bridge packages",
-				ArgsUsage: "<file.rugo|module|package> [symbol]",
+				ArgsUsage: "<file.rugo|[use:|import:]module|package> [symbol]",
 				Flags: []cli.Flag{
 					&cli.BoolFlag{
 						Name:    "all",
@@ -497,6 +497,39 @@ func docAction(ctx context.Context, cmd *cli.Command) error {
 		symbol = cmd.Args().Get(1)
 	}
 
+	// Parse use:/import: prefix for disambiguation
+	forceModule, forceBridge := false, false
+	if strings.HasPrefix(target, "use:") {
+		forceModule = true
+		target = strings.TrimPrefix(target, "use:")
+	} else if strings.HasPrefix(target, "import:") {
+		forceBridge = true
+		target = strings.TrimPrefix(target, "import:")
+	}
+
+	// Forced module lookup (use:)
+	if forceModule {
+		m, ok := modules.Get(target)
+		if !ok {
+			return fmt.Errorf("module %q not found", target)
+		}
+		docOutput(rugodoc.FormatModule(m))
+		return nil
+	}
+
+	// Forced bridge lookup (import:)
+	if forceBridge {
+		if pkg, ok := gobridge.LookupByNS(target); ok {
+			docOutput(rugodoc.FormatBridgePackage(pkg))
+			return nil
+		}
+		if pkg := gobridge.GetPackage(target); pkg != nil {
+			docOutput(rugodoc.FormatBridgePackage(pkg))
+			return nil
+		}
+		return fmt.Errorf("bridge package %q not found", target)
+	}
+
 	// Mode 1: Rugo source file
 	if compiler.IsRugoFile(target) {
 		fd, err := rugodoc.ExtractFile(target)
@@ -520,14 +553,23 @@ func docAction(ctx context.Context, cmd *cli.Command) error {
 		return docLocalDir(target, symbol)
 	}
 
+	// Check for ambiguity: name exists as both module and bridge package
+	_, isModule := modules.Get(target)
+	_, isBridge := gobridge.LookupByNS(target)
+	if isModule && isBridge {
+		return fmt.Errorf("%q is both a module and a bridge package, use \"rugo doc use:%s\" or \"rugo doc import:%s\"", target, target, target)
+	}
+
 	// Mode 3: stdlib module (use)
-	if m, ok := modules.Get(target); ok {
+	if isModule {
+		m, _ := modules.Get(target)
 		docOutput(rugodoc.FormatModule(m))
 		return nil
 	}
 
 	// Mode 4: bridge package by namespace (import)
-	if pkg, ok := gobridge.LookupByNS(target); ok {
+	if isBridge {
+		pkg, _ := gobridge.LookupByNS(target)
 		docOutput(rugodoc.FormatBridgePackage(pkg))
 		return nil
 	}

docs/language.md

@@ -834,5 +834,7 @@ rugo doc file.rugo           # all docs in a file
 rugo doc file.rugo factorial # specific symbol
 rugo doc http              # stdlib module
 rugo doc strings           # bridge package
+rugo doc use:os            # force stdlib module (when name is ambiguous)
+rugo doc import:os         # force bridge package (when name is ambiguous)
 rugo doc --all             # list everything
 ```

docs/quickstart/20-doc-comments.md

@@ -38,6 +38,10 @@ rugo doc http
 rugo doc strings
 rugo doc time
 
+# Disambiguate when a name exists as both module and bridge (e.g. os, json)
+rugo doc use:os            # force stdlib module
+rugo doc import:os         # force bridge package
+
 # Show docs for a remote module
 rugo doc github.com/user/repo
 

rats/stdlib/59_doc_disambiguate_test.rugo

@@ -0,0 +1,79 @@
+# RATS: Test rugo doc disambiguation for overlapping module/bridge names
+use "test"
+use "str"
+
+# Test: rugo doc with ambiguous name (os is both module and bridge) shows error
+rats "rugo doc ambiguous name shows disambiguation error"
+  result = test.run("rugo doc os")
+  test.assert_neq(result["status"], 0)
+  test.assert_contains(result["output"], "is both a module and a bridge package")
+  test.assert_contains(result["output"], "use:os")
+  test.assert_contains(result["output"], "import:os")
+end
+
+# Test: rugo doc use: prefix shows stdlib module
+rats "rugo doc use:os shows module docs"
+  result = test.run("NO_COLOR=1 rugo doc use:os")
+  test.assert_eq(result["status"], 0)
+  test.assert_contains(result["output"], "module os")
+  test.assert_contains(result["output"], "os.exec")
+end
+
+# Test: rugo doc import: prefix shows bridge package
+rats "rugo doc import:os shows bridge docs"
+  result = test.run("NO_COLOR=1 rugo doc import:os")
+  test.assert_eq(result["status"], 0)
+  test.assert_contains(result["output"], "package os")
+  test.assert_contains(result["output"], "Go: os")
+end
+
+# Test: rugo doc json is also ambiguous
+rats "rugo doc json shows disambiguation error"
+  result = test.run("rugo doc json")
+  test.assert_neq(result["status"], 0)
+  test.assert_contains(result["output"], "is both a module and a bridge package")
+  test.assert_contains(result["output"], "use:json")
+  test.assert_contains(result["output"], "import:json")
+end
+
+# Test: rugo doc use:json shows module
+rats "rugo doc use:json shows module docs"
+  result = test.run("NO_COLOR=1 rugo doc use:json")
+  test.assert_eq(result["status"], 0)
+  test.assert_contains(result["output"], "module json")
+end
+
+# Test: rugo doc import:json shows bridge
+rats "rugo doc import:json shows bridge docs"
+  result = test.run("NO_COLOR=1 rugo doc import:json")
+  test.assert_eq(result["status"], 0)
+  test.assert_contains(result["output"], "package json")
+end
+
+# Test: rugo doc use: with nonexistent module fails
+rats "rugo doc use:nonexistent fails"
+  result = test.run("rugo doc use:nonexistent")
+  test.assert_neq(result["status"], 0)
+  test.assert_contains(result["output"], "module \"nonexistent\" not found")
+end
+
+# Test: rugo doc import: with nonexistent bridge fails
+rats "rugo doc import:nonexistent fails"
+  result = test.run("rugo doc import:nonexistent")
+  test.assert_neq(result["status"], 0)
+  test.assert_contains(result["output"], "bridge package \"nonexistent\" not found")
+end
+
+# Test: unambiguous names still auto-resolve without prefix
+rats "rugo doc str auto-resolves to module"
+  result = test.run("NO_COLOR=1 rugo doc str")
+  test.assert_eq(result["status"], 0)
+  test.assert_contains(result["output"], "module str")
+end
+
+# Test: unambiguous bridge auto-resolves
+rats "rugo doc strings auto-resolves to bridge"
+  result = test.run("NO_COLOR=1 rugo doc strings")
+  test.assert_eq(result["status"], 0)
+  test.assert_contains(result["output"], "package strings")
+end