Add a JS lint check for an @externs tag hidden by the @license tag

Any text in a JSDoc block after @license is just considered part of the license, so we expect that an @externs tag is unintentional. PiperOrigin-RevId: 719353476
google · Jan 24, 2025 · 480bf0e · 480bf0e
1 parent 5dcf355
commit 480bf0e
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 1 deletion.
diff --git a/src/com/google/javascript/jscomp/lint/CheckJSDocStyle.java b/src/com/google/javascript/jscomp/lint/CheckJSDocStyle.java
@@ -82,6 +82,13 @@ public final class CheckJSDocStyle extends AbstractPostOrderCallback implements
       DiagnosticType.disabled("JSC_EXTERNS_FILES_SHOULD_BE_ANNOTATED",
           "Externs files should be annotated with @externs in the @fileoverview block.");
 
+  public static final DiagnosticType LICENSE_CONTAINS_AT_EXTERNS =
+      DiagnosticType.disabled(
+          "JSC_LICENSE_CONTAINS_AT_EXTERNS",
+          "@license block contains an @externs annotation, which will be parsed as plain "
+              + "license text instead of an actual @externs annotation. You probably meant to put "
+              + "@externs in a separate @fileoverview block.");
+
   public static final DiagnosticType PREFER_BACKTICKS_TO_AT_SIGN_CODE =
       DiagnosticType.disabled(
           "JSC_PREFER_BACKTICKS_TO_AT_SIGN_CODE",
@@ -99,6 +106,7 @@ public final class CheckJSDocStyle extends AbstractPostOrderCallback implements
           WRONG_NUMBER_OF_PARAMS,
           INCORRECT_PARAM_NAME,
           EXTERNS_FILES_SHOULD_BE_ANNOTATED,
+          LICENSE_CONTAINS_AT_EXTERNS,
           PREFER_BACKTICKS_TO_AT_SIGN_CODE);
 
   public static final DiagnosticGroup ALL_DIAGNOSTICS = new DiagnosticGroup(LINT_DIAGNOSTICS);
@@ -131,7 +139,6 @@ public void visit(NodeTraversal t, Node n, Node unused) {
       case LET:
       case CONST:
       case STRING_KEY:
-      case SCRIPT:
         break;
       case MEMBER_FUNCTION_DEF:
       case GETTER_DEF:
@@ -142,6 +149,9 @@ public void visit(NodeTraversal t, Node n, Node unused) {
           checkStyleForPrivateProperties(t, n);
         }
         break;
+      case SCRIPT:
+        checkLicenseComment(t, n);
+        break;
       default:
         visitNonFunction(t, n);
     }
@@ -465,4 +475,14 @@ public void visit(NodeTraversal t, Node n, Node parent) {
       }
     }
   }
+
+  private void checkLicenseComment(NodeTraversal t, Node n) {
+    if (n.getJSDocInfo() == null || n.getJSDocInfo().getLicense() == null) {
+      return;
+    }
+    String license = n.getJSDocInfo().getLicense();
+    if (license.contains("@externs")) {
+      t.report(n, LICENSE_CONTAINS_AT_EXTERNS);
+    }
+  }
 }
diff --git a/test/com/google/javascript/jscomp/lint/CheckJSDocStyleTest.java b/test/com/google/javascript/jscomp/lint/CheckJSDocStyleTest.java
@@ -19,6 +19,7 @@
 import static com.google.javascript.jscomp.lint.CheckJSDocStyle.EXTERNS_FILES_SHOULD_BE_ANNOTATED;
 import static com.google.javascript.jscomp.lint.CheckJSDocStyle.INCORRECT_ANNOTATION_ON_GETTER_SETTER;
 import static com.google.javascript.jscomp.lint.CheckJSDocStyle.INCORRECT_PARAM_NAME;
+import static com.google.javascript.jscomp.lint.CheckJSDocStyle.LICENSE_CONTAINS_AT_EXTERNS;
 import static com.google.javascript.jscomp.lint.CheckJSDocStyle.MISSING_JSDOC;
 import static com.google.javascript.jscomp.lint.CheckJSDocStyle.MISSING_PARAMETER_JSDOC;
 import static com.google.javascript.jscomp.lint.CheckJSDocStyle.MISSING_RETURN_JSDOC;
@@ -1116,6 +1117,68 @@ public void testValidExternsAnnotation_withES6Modules() {
         srcs(""));
   }
 
+  @Test
+  public void testValidLicenseCommentWithoutExterns() {
+    testSame(
+        srcs(
+            lines(
+                "/**",
+                " * @license",
+                " * Copyright 2024 Google LLC",
+                " */",
+                "",
+                "function Example() {}")));
+  }
+
+  @Test
+  public void testValidLicenseCommentAndExterns_separateBlocks() {
+    testSame(
+        externs(
+            lines(
+                "/**",
+                " * @license",
+                " * Copyright 2024 Google LLC",
+                " */",
+                "/**",
+                " * @fileoverview Some super cool externs.",
+                " * @externs",
+                " */",
+                "",
+                "function Example() {}")),
+        srcs(""));
+  }
+
+  @Test
+  public void testValidLicenseCommentAndExterns_sameBlocks() {
+    testSame(
+        externs(
+            lines(
+                "/**",
+                " * @fileoverview Some super cool externs.",
+                " * @externs",
+                " * @license",
+                " * Copyright 2024 Google LLC",
+                " */",
+                "",
+                "function Example() {}")),
+        srcs(""));
+  }
+
+  @Test
+  public void testInvalidLicenseComment_containsExterns() {
+    test(
+        srcs(
+            lines(
+                "/**",
+                " * @license",
+                " * Copyright 2024 Google LLC",
+                " * @externs - oh no, this tag is treated as part of the @license!",
+                " */",
+                "",
+                "function Example() {}")),
+        warning(LICENSE_CONTAINS_AT_EXTERNS));
+  }
+
   @Test
   public void testAtSignCodeDetectedWhenPresent() {
     testWarning(