Support @closureUnaware transpilation using runtime libraries as 'external' names

This adds a new mode to the RuntimeJsLibManager class specifically for @closureUnaware transpilation.

Normally transpilation passes reference runtime library fields by the original, qualified field name, as it appears in the JS file. Examples - "$jscomp.global", "$jscomp.inherits".

In optimized builds: the actual runtime library code is compiled together with the transpiled code.

In --skip_non_transpilation_passes/transpile only builds: the actual runtime library code must be loaded separately, usually via a regular library dependency.

However, for transpilation of @closureUnaware blocks within a larger optimized build, we need to both 1) share runtime library code with the regular optimized build & also minify it, for code size reasons but 2) not break references to the runtime library code from within @closureUnaware blocks.

Naively referring to runtime libraries in @closureUnaware code will break after variable & property renaming runs on the main AST.

So instead, we have to treat the runtime libraries as unknown external code for @closureUnaware transpilation - which is what externs let us do. Then in a followup CL, we'll actually inject the runtime field definitions into the @closureUnaware function as arguments.

PiperOrigin-RevId: 851364465

Author: lauraharker

src/com/google/javascript/jscomp/AstFactory.java

@@ -781,14 +781,17 @@ Node createQName(StaticScope scope, JsLibField field) {
     String qname = field.assertInjected().qualifiedName();
     List<String> parts = DOT_SPLITTER.splitToList(qname);
     String baseName = checkNotNull(Iterables.getFirst(parts, null));
-    checkState(baseName.equals("$jscomp"), "Unexpected Field name %s", baseName);
-    Node baseNameNode = createJscomp();
-    setJSTypeOrColor(type(unknownType, StandardColors.UNKNOWN), baseNameNode);
+    checkState(baseName.startsWith("$jscomp"), "Unexpected Field name %s", baseName);
+
+    Node baseNameNode =
+        baseName.equals("$jscomp")
+            ? createJscomp()
+            : createName(baseName, type(unknownType, StandardColors.UNKNOWN));
     if (lifeCycleStage.isNormalized()) {
       baseNameNode.putBooleanProp(Node.IS_CONSTANT_NAME, true);
     }
     Iterable<String> propertyNames = Iterables.skip(parts, 1);
-    return createQName(scope, "$jscomp", baseNameNode, propertyNames);
+    return createQName(scope, baseName, baseNameNode, propertyNames);
   }
 
   Node createQNameWithUnknownType(String qname) {

src/com/google/javascript/jscomp/ClosureUnawareOptions.java

@@ -45,7 +45,14 @@ private void setTranspilationOptions() {
     // transpilation, in the
     // case we can't prove it's not a subclass of an ES6 class (not being transpiled)
     shadowOptions.setRewritePolyfills(false); // for now, we ignore polyfills that may be needed.
-    shadowOptions.setRuntimeLibraryMode(RuntimeJsLibManager.RuntimeLibraryMode.NO_OP);
+    switch (original.getRuntimeLibraryMode()) {
+      case NO_OP ->
+          shadowOptions.setRuntimeLibraryMode(RuntimeJsLibManager.RuntimeLibraryMode.NO_OP);
+      case RECORD_ONLY, RECORD_AND_VALIDATE_FIELDS, INJECT ->
+          shadowOptions.setRuntimeLibraryMode(
+              RuntimeJsLibManager.RuntimeLibraryMode.EXTERN_FIELD_NAMES);
+      case EXTERN_FIELD_NAMES -> throw new AssertionError();
+    }
     shadowOptions.setOutputFeatureSet(original.getOutputFeatureSet());
   }
 

src/com/google/javascript/jscomp/Compiler.java

@@ -842,7 +842,10 @@ public void initChunks(List<SourceFile> externs, List<JSChunk> chunks, CompilerO
             options.getRuntimeLibraryMode(),
             this::loadResourceContents,
             changeTracker,
-            this::getNodeForRuntimeCodeInsertion);
+            options.getRuntimeLibraryMode()
+                    == RuntimeJsLibManager.RuntimeLibraryMode.EXTERN_FIELD_NAMES
+                ? this::getSynthesizedExternsRoot
+                : this::getNodeForRuntimeCodeInsertion);
   }
 
   @Override
@@ -3938,6 +3941,11 @@ CompilerInput getSynthesizedExternsInput() {
     return input;
   }
 
+  private Node getSynthesizedExternsRoot() {
+    CompilerInput externsInput = getSynthesizedExternsInput();
+    return externsInput.getAstRoot(this);
+  }
+
   @Override
   CompilerInput getSynthesizedTypeSummaryInput() {
     if (syntheticTypeSummaryInput != null) {

src/com/google/javascript/jscomp/js/RuntimeJsLibManager.java

@@ -19,6 +19,7 @@
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.base.Preconditions.checkState;
+import static com.google.common.collect.ImmutableList.toImmutableList;
 
 import com.google.common.base.Splitter;
 import com.google.common.base.Strings;
@@ -27,6 +28,7 @@
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.javascript.jscomp.ChangeTracker;
 import com.google.javascript.jscomp.resources.ResourceLoader;
+import com.google.javascript.rhino.IR;
 import com.google.javascript.rhino.Node;
 import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
@@ -61,6 +63,13 @@ public enum RuntimeLibraryMode {
     // inject a runtime library, and will also validate injection in JsLibField::assertInjected, but
     // does not modify the AST.
     RECORD_AND_VALIDATE_FIELDS,
+    // for @closureUnaware nested compilation. When asked to inject a field, the compiler adds an
+    // @extern definition of the field name to prevent misoptimization, and uses a different
+    // identifier from the original uncompiled field name.
+    // The RuntimeJsLibManager is not responsible for actually defining the external field name
+    // definitions; the code using EXTERN_FIELD_NAMES mode must enure that everything field from
+    // getExternedFields() is actually loaded at runtime.
+    EXTERN_FIELD_NAMES,
   }
 
   /** Loads /js resources into AST format */
@@ -155,6 +164,18 @@ public ImmutableList<String> getInjectedLibraries() {
     return ImmutableList.copyOf(injectedLibs);
   }
 
+  /**
+   * Returns a list of all fields previously injected, via one of the other methods on this class.
+   */
+  public ImmutableList<ExternedField> getExternedFields() {
+    if (this.mode != RuntimeLibraryMode.EXTERN_FIELD_NAMES) {
+      return ImmutableList.of();
+    }
+    return internedFields.values().stream()
+        .filter(InternalField::isInjected)
+        .collect(toImmutableList());
+  }
+
   private InternalField createField(String fieldName) {
     checkArgument(!fieldName.isEmpty(), fieldName);
 
@@ -166,27 +187,43 @@ private InternalField createField(String fieldName) {
 
     String resourceName =
         checkNotNull(FieldsTable.INSTANCE.get(propName), "Cannot find definition of %s", fieldName);
-    // TODO: b/421971366 - allow @closureUnaware transpilation to use a different local name for
-    // fields.
-    return new InternalField(resourceName, fieldName);
+
+    String compiledName =
+        switch (mode) {
+          case EXTERN_FIELD_NAMES -> fieldName.replace('.', '_');
+          case NO_OP, RECORD_ONLY, RECORD_AND_VALIDATE_FIELDS, INJECT -> fieldName;
+        };
+
+    return new InternalField(resourceName, compiledName, fieldName);
   }
 
   /**
    * A $jscomp.* field (could be a method, class, or any arbitrary value) that exists in some
    * runtime library under the js/ directory.
    */
-  private final class InternalField implements InjectedJsLibField {
+  private final class InternalField implements ExternedField {
     /** The file containing this field, e.g. "es6/generator". */
     private final String resourceName;
 
-    /** The name by which compiler passes should refer to this field. */
+    /**
+     * The name by which compiler passes should refer to this field, e.g. `$jscomp.inherits` or
+     * `$jscomp_inherits`.
+     */
     private final String qualifiedName;
 
+    /** The original fully qualified name of this field, e.g. `$jscomp.inherits`. */
+    private final String uncompiledName;
+
     private boolean injected = false;
 
-    private InternalField(String resourceName, String qualifiedName) {
+    private InternalField(String resourceName, String qualifiedName, String uncompiledName) {
       this.resourceName = resourceName;
       this.qualifiedName = qualifiedName;
+      this.uncompiledName = uncompiledName;
+    }
+
+    private boolean isInjected() {
+      return this.injected;
     }
 
     private void markInjected() {
@@ -198,8 +235,8 @@ private void markInjected() {
     public InternalField assertInjected() {
       switch (mode) {
         case NO_OP, RECORD_ONLY -> {}
-        case RECORD_AND_VALIDATE_FIELDS, INJECT ->
-            checkState(this.injected, "Field %s is not injected", this.qualifiedName);
+        case RECORD_AND_VALIDATE_FIELDS, INJECT, EXTERN_FIELD_NAMES ->
+            checkState(this.injected, "Field %s is not injected", this.uncompiledName);
       }
       return this;
     }
@@ -214,13 +251,23 @@ public boolean matches(Node node) {
 
     @Override
     public String toString() {
-      return Strings.lenientFormat("Field<%s, %s>", qualifiedName, resourceName);
+      return Strings.lenientFormat("Field<%s, %s>", uncompiledName, resourceName);
     }
 
     @Override
     public String qualifiedName() {
       return this.qualifiedName;
     }
+
+    @Override
+    public String uncompiledName() {
+      return this.uncompiledName;
+    }
+
+    @Override
+    public String resourceName() {
+      return this.resourceName;
+    }
   }
 
   /**
@@ -245,6 +292,8 @@ private InternalField getJsLibFieldInternal(String fieldName) {
   public interface JsLibField {
     boolean matches(Node node);
 
+    String resourceName();
+
     InjectedJsLibField assertInjected();
   }
 
@@ -256,13 +305,40 @@ public interface JsLibField {
    * to prevent code from creating new AST references to a field that's not actually injected (yet).
    */
   public interface InjectedJsLibField extends JsLibField {
+    /** Returns the name of the field as it is available to the compiler. */
     String qualifiedName();
   }
 
+  /**
+   * A {@link InjectedJsLibField} that was injected in {@link RuntimeLibraryMode#EXTERN_FIELD_NAMES}
+   * mode, and so has both a regular "qualified name" by which transpilation passes should refer to
+   * it - this is the externed name - but also provides the uncompiled, raw name of the field.
+   *
+   * <p>Only {@link ExternedField} instances provide access to the uncompiled name. Most use sites
+   * should use the compiled/qualified name, which may or may not equal the uncompiled name. So to
+   * try and minimize confusion, we only expose the uncompiled name when this is actually an
+   * external field injection.
+   */
+  public interface ExternedField extends InjectedJsLibField {
+
+    /** Returns the uncompiled name of the field, as it is seen in the raw runtime lib. */
+    String uncompiledName();
+  }
+
   /** Injects the runtime library that defines the given $jscomp.* field. */
   public void injectLibForField(String fieldName) {
     InternalField field = getJsLibFieldInternal(fieldName);
+    if (field.isInjected()) {
+      return; // already done.
+    }
     field.markInjected();
+    if (this.mode == RuntimeLibraryMode.EXTERN_FIELD_NAMES) {
+      Node externRoot = nodeForCodeInsertion.get();
+      checkState(externRoot.isFromExterns(), externRoot);
+      Node declaration = IR.var(IR.name(field.qualifiedName()));
+      declaration.getFirstChild().putBooleanProp(Node.IS_CONSTANT_NAME, true);
+      externRoot.addChildToBack(declaration);
+    }
     ensureLibraryInjected(field.resourceName, /* force= */ false);
   }
 
@@ -287,7 +363,7 @@ public void injectLibForField(String fieldName) {
         case NO_OP -> {
           return lastInjectedLibrary;
         }
-        case RECORD_ONLY, RECORD_AND_VALIDATE_FIELDS -> {
+        case RECORD_ONLY, RECORD_AND_VALIDATE_FIELDS, EXTERN_FIELD_NAMES -> {
           this.recordLibraryInjected(resourceName);
           return lastInjectedLibrary;
         }

test/com/google/javascript/jscomp/AstFactoryTest.java

@@ -37,6 +37,7 @@
 import com.google.javascript.rhino.IR;
 import com.google.javascript.rhino.Node;
 import com.google.javascript.rhino.StaticScope;
+import com.google.javascript.rhino.StaticSourceFile.SourceKind;
 import com.google.javascript.rhino.Token;
 import com.google.javascript.rhino.jstype.FunctionType;
 import com.google.javascript.rhino.jstype.JSType;
@@ -2076,6 +2077,29 @@ public void testCreateRuntimeField_succeeds() {
     assertNode(result).matchesQualifiedName("$jscomp.global");
   }
 
+  @Test
+  public void testCreateRuntimeField_inExternMode_succeeds_andUsesUnderscoredName() {
+    // Given
+    Node externs = IR.script();
+    externs.setStaticSourceFile(SourceFile.fromCode("externs.js", "", SourceKind.EXTERN));
+    this.runtimeJsLibManager =
+        RuntimeJsLibManager.create(
+            RuntimeJsLibManager.RuntimeLibraryMode.EXTERN_FIELD_NAMES,
+            new TestResourceProvider(),
+            compiler.getChangeTracker(),
+            () -> externs);
+    AstFactory astFactory = createTestAstFactoryWithoutTypes();
+    StaticScope scope = new MapBasedScope(ImmutableMap.of());
+    RuntimeJsLibManager.JsLibField field = runtimeJsLibManager.getJsLibField("$jscomp.global");
+    runtimeJsLibManager.injectLibForField("$jscomp.global");
+
+    // When
+    var result = astFactory.createQName(scope, field);
+
+    // Then
+    assertNode(result).matchesName("$jscomp_global");
+  }
+
   @Test
   public void testCreateJscompMakeIteratorCall_throwsIfJscompMakeIteratorNotInjected() {
     // Given

test/com/google/javascript/jscomp/TranspileAndOptimizeClosureUnawareTest.java

@@ -17,10 +17,8 @@
 package com.google.javascript.jscomp;
 
 import static com.google.common.collect.ImmutableList.toImmutableList;
-import static com.google.common.truth.Truth.assertThat;
 import static com.google.javascript.jscomp.CompilerTestCase.srcs;
 import static java.util.stream.Collectors.joining;
-import static org.junit.Assert.assertThrows;
 
 import com.google.common.collect.ImmutableList;
 import com.google.javascript.rhino.Node;
@@ -293,28 +291,43 @@ public void transpileOnlyMode_doesNotRunConstantFolding() {
   @Test
   public void classInheritance_injectsRequiredRuntimeLibraries() {
     setLanguageOut(CompilerOptions.LanguageMode.ECMASCRIPT5);
-    // TODO: b/830636484 - enable runtime library injection and fix this test.
-    var ex =
-        assertThrows(
-            Exception.class,
-            () ->
-                test(
-                    srcs(
-                        """
-                        /** @fileoverview @closureUnaware */
-                        goog.module('test');
-                        /** @closureUnaware */
-                        (function() {
-                          class Parent {
-                            method() {
-                              return 10;
-                            }
-                          }
-                          class Child extends Parent {}
-                          return new Child();
-                        }).call(globalThis);
-                        """)));
-    assertThat(ex).hasCauseThat().hasMessageThat().contains("NAME $jscomp");
+
+    test(
+        srcs(
+            """
+            /** @fileoverview @closureUnaware */
+            goog.module('test');
+            /** @closureUnaware */
+            (function() {
+              class Parent {
+                method() {
+                  return 10;
+                }
+              }
+              class Child extends Parent {}
+              return new Child();
+            }).call(globalThis);
+            """),
+        expected(
+            // TODO: b/830636484 inject $jscomp_inherits as a parameter in the closure unaware fn.
+            """
+            /** @fileoverview @closureUnaware */
+            goog.module("test");
+            /** @closureUnaware */
+            (function() {
+              /** @constructor */
+              var a = function() {};
+              a.prototype.method = function() {
+                return 10;
+              };
+              /** @constructor */
+              var b = function() {
+                return a.apply(this, arguments) || this;
+              };
+              $jscomp_inherits(b, a);
+              return new b();
+            }).call(globalThis);
+            """));
   }
 
   @Test