Include module file globals in builtin.proto

This allows consumers of the proto to learn about globals only available in `MODULE.bazel` under a new `ApiContext`.

Also adds a smoke test to verify that common symbols are contained in the proto for each API context.

Author: fmeum

src/main/java/com/google/devtools/build/docgen/ApiExporter.java

@@ -375,6 +375,12 @@ public static void main(String[] args) {
           builtins, symbols.getGlobals(), globalToDoc, typeNameToConstructor, ApiContext.ALL);
       appendGlobals(
           builtins, symbols.getBzlGlobals(), globalToDoc, typeNameToConstructor, ApiContext.BZL);
+      appendGlobals(
+          builtins,
+          symbols.getModuleFileGlobals(),
+          globalToDoc,
+          typeNameToConstructor,
+          ApiContext.MODULE);
       appendNativeRules(builtins, symbols.getNativeRules());
       writeBuiltins(options.outputFile, builtins);
 

src/main/java/com/google/devtools/build/docgen/BUILD

@@ -77,6 +77,7 @@ java_binary(
     srcs = ["ApiExporter.java"],
     main_class = "com.google.devtools.build.docgen.ApiExporter",
     runtime_deps = [
+        "//src/main/java/com/google/devtools/build/lib/bazel/bzlmod:resolution",
         "//src/main/java/com/google/devtools/build/lib/bazel/repository",
         "//src/main/java/net/starlark/java/syntax",
     ],

src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java

@@ -39,6 +39,7 @@ public class SymbolFamilies {
   // Mappings between Starlark names and Starlark entities generated from the fakebuildapi.
   private final ImmutableMap<String, Object> globals;
   private final ImmutableMap<String, Object> bzlGlobals;
+  private final ImmutableMap<String, Object> moduleFileGlobals;
 
   public SymbolFamilies(
       StarlarkDocExpander expander,
@@ -53,7 +54,8 @@ public SymbolFamilies(
           IllegalAccessException,
           BuildEncyclopediaDocException,
           ClassNotFoundException,
-          IOException {
+          IOException,
+          InstantiationException {
     ConfiguredRuleClassProvider configuredRuleClassProvider = createRuleClassProvider(provider);
     this.nativeRules =
         ImmutableList.copyOf(
@@ -66,6 +68,7 @@ public SymbolFamilies(
                 denyList));
     this.globals = Starlark.UNIVERSE;
     this.bzlGlobals = collectBzlGlobals(configuredRuleClassProvider);
+    this.moduleFileGlobals = collectModuleFileGlobals();
     this.allDocPages = StarlarkDocumentationCollector.getAllDocPages(expander);
   }
 
@@ -92,6 +95,14 @@ public Map<String, Object> getBzlGlobals() {
     return bzlGlobals;
   }
 
+  /*
+   * Returns a mapping between Starlark names and Starlark entities that are available only in MODULE.bazel
+   * files.
+   */
+  public Map<String, Object> getModuleFileGlobals() {
+    return moduleFileGlobals;
+  }
+
   // Returns a mapping between type names and module/type documentation.
   public ImmutableMap<Category, ImmutableList<StarlarkDocPage>> getAllDocPages() {
     return allDocPages;
@@ -132,10 +143,25 @@ private List<RuleDocumentation> collectNativeRules(
   }
 
   private ConfiguredRuleClassProvider createRuleClassProvider(String classProvider)
-      throws NoSuchMethodException, InvocationTargetException, IllegalAccessException,
+      throws NoSuchMethodException,
+          InvocationTargetException,
+          IllegalAccessException,
           ClassNotFoundException {
     Class<?> providerClass = Class.forName(classProvider);
     Method createMethod = providerClass.getMethod("create");
     return (ConfiguredRuleClassProvider) createMethod.invoke(null);
   }
+
+  private ImmutableMap<String, Object> collectModuleFileGlobals()
+      throws ClassNotFoundException,
+          NoSuchMethodException,
+          InvocationTargetException,
+          InstantiationException,
+          IllegalAccessException {
+    Class<?> moduleFileGlobals =
+        Class.forName("com.google.devtools.build.lib.bazel.bzlmod.ModuleFileGlobals");
+    ImmutableMap.Builder<String, Object> moduleFileEnv = ImmutableMap.builder();
+    Starlark.addMethods(moduleFileEnv, moduleFileGlobals.getConstructor().newInstance());
+    return moduleFileEnv.buildOrThrow();
+  }
 }

src/main/protobuf/builtin.proto

@@ -57,6 +57,7 @@ enum ApiContext {
   ALL = 0;
   BZL = 1;
   BUILD = 2;
+  MODULE = 3;
 }
 
 // Generic representation for a Starlark object. If the object is callable

src/test/java/com/google/devtools/build/lib/BUILD

@@ -149,3 +149,15 @@ test_suite(
     name = "others",
     tags = ["-" + n for n in TEST_SUITES],
 )
+
+java_test(
+    name = "BuiltinProtoSmokeTest",
+    srcs = ["BuiltinProtoSmokeTest.java"],
+    data = ["//src/main/java/com/google/devtools/build/lib:gen_api_proto"],
+    env = {"BUILTIN_PROTO": "$(rlocationpath //src/main/java/com/google/devtools/build/lib:gen_api_proto)"},
+    deps = [
+        "//src/main/protobuf:builtin_java_proto",
+        "//third_party:truth",
+        "@bazel_tools//tools/java/runfiles",
+    ],
+)

src/test/java/com/google/devtools/build/lib/BuiltinProtoSmokeTest.java

@@ -0,0 +1,45 @@
+package com.google.devtools.build.lib;
+
+import static com.google.common.truth.Truth.assertThat;
+import static java.util.stream.Collectors.toMap;
+
+import com.google.devtools.build.docgen.builtin.BuiltinProtos;
+import com.google.devtools.build.runfiles.Runfiles;
+import java.io.BufferedInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+public final class BuiltinProtoSmokeTest {
+  static BuiltinProtos.Builtins builtins;
+
+  @BeforeClass
+  public static void loadProto() throws IOException {
+    Path protoPath =
+        Path.of(Runfiles.preload().unmapped().rlocation(System.getenv("BUILTIN_PROTO")));
+    try (InputStream inputStream = Files.newInputStream(protoPath);
+        BufferedInputStream bufferedInputStream = new BufferedInputStream(inputStream)) {
+      builtins = BuiltinProtos.Builtins.parseFrom(bufferedInputStream);
+    }
+  }
+
+  @Test
+  public void hasGlobalCallableFromEachApiContext() {
+    assertThat(
+            builtins.getGlobalList().stream()
+                .filter(BuiltinProtos.Value::hasCallable)
+                .filter(global -> !global.getCallable().getParamList().isEmpty())
+                .collect(toMap(BuiltinProtos.Value::getName, BuiltinProtos.Value::getApiContext)))
+        .containsAtLeast(
+            "range", BuiltinProtos.ApiContext.ALL,
+            "glob", BuiltinProtos.ApiContext.BUILD,
+            "DefaultInfo", BuiltinProtos.ApiContext.BZL,
+            "bazel_dep", BuiltinProtos.ApiContext.MODULE);
+  }
+}