feat(valid-types): require whitelist of types and prevent names with suppress tag

Author: brettz9

README.md

@@ -20561,6 +20561,27 @@ parseArray = function(parser) {
 };
 // Settings: {"jsdoc":{"mode":"closure"}}
 // Message: Syntax error in namepath: R<~
+
+/**
+ * @suppress
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: Tag @suppress must have a type in "closure" mode.
+
+/**
+ * @suppress {visibility} sth
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: @suppress should not have a name in "closure" mode.
+
+/**
+ * @suppress {visibility|blah}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: Syntax error in supresss type: blah
 ````
 
 The following patterns are not considered problems:
@@ -20876,6 +20897,13 @@ type ComplicatedType<T, U, V, W, X> = never
  */
 class quux {}
 // Settings: {"jsdoc":{"mode":"typescript"}}
+
+/**
+ * @suppress {visibility|underscore}
+ */
+function quux() {
+}
+// Settings: {"jsdoc":{"mode":"closure"}}
 ````
 
 

src/getDefaultTagStructureForMode.js

@@ -396,6 +396,11 @@ const getDefaultTagStructureForMode = (mode) => {
       ['typeAllowed', isClosureOrPermissive],
     ])],
 
+    ['suppress', new Map([
+      ['nameContents', !isClosure],
+      ['typeRequired', isClosure],
+    ])],
+
     ['template', new Map([
       ['nameContents', isJsdoc ? 'text' : 'namepath-referencing'],
 

src/rules/validTypes.js

@@ -1,10 +1,67 @@
 import {
-  tryParse, parse,
+  tryParse, parse, traverse,
 } from 'jsdoc-type-pratt-parser';
 import iterateJsdoc from '../iterateJsdoc';
 
 const asExpression = /as\s+/u;
 
+const suppressTypes = new Set([
+  // https://github.com/google/closure-compiler/wiki/@suppress-annotations
+  // https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/ParserConfig.properties#L154
+  'accessControls',
+  'checkDebuggerStatement',
+  'checkPrototypalTypes',
+  'checkRegExp',
+  'checkTypes',
+  'checkVars',
+  'closureDepMethodUsageChecks',
+  'const',
+  'constantProperty',
+  'deprecated',
+  'duplicate',
+  'es5Strict',
+  'externsValidation',
+  'extraProvide',
+  'extraRequire',
+  'globalThis',
+  'invalidCasts',
+  'lateProvide',
+  'legacyGoogScopeRequire',
+  'lintChecks',
+  'messageConventions',
+  'misplacedTypeAnnotation',
+  'missingOverride',
+  'missingPolyfill',
+  'missingProperties',
+  'missingProvide',
+  'missingRequire',
+  'missingSourcesWarnings',
+  'moduleLoad',
+  'nonStandardJsDocs',
+  'partialAlias',
+  'polymer',
+  'reportUnknownTypes',
+  'strictMissingProperties',
+  'strictModuleDepCheck',
+  'strictPrimitiveOperators',
+  'suspiciousCode',
+
+  // Not documented in enum
+  'switch',
+  'transitionalSuspiciousCodeWarnings',
+  'undefinedNames',
+  'undefinedVars',
+  'underscore',
+  'unknownDefines',
+  'untranspilableFeatures',
+  'unusedLocalVariables',
+  'unusedPrivateMembers',
+  'useOfGoogProvide',
+  'uselessCode',
+  'visibility',
+  'with',
+]);
+
 const tryParsePathIgnoreError = (path) => {
   try {
     tryParse(path);
@@ -111,6 +168,25 @@ export default iterateJsdoc(({
       continue;
     }
 
+    if (tag.tag === 'suppress' && mode === 'closure') {
+      let parsedTypes;
+
+      try {
+        parsedTypes = tryParse(tag.type);
+      } catch {
+        // Ignore
+      }
+
+      if (parsedTypes) {
+        traverse(parsedTypes, (node) => {
+          const {value: type} = node;
+          if (type !== undefined && !suppressTypes.has(type)) {
+            report(`Syntax error in supresss type: ${type}`, null, tag);
+          }
+        });
+      }
+    }
+
     const otherModeMaps = ['jsdoc', 'typescript', 'closure', 'permissive'].filter(
       (mde) => {
         return mde !== mode;

test/rules/assertions/validTypes.js

@@ -721,6 +721,66 @@ export default {
         },
       },
     },
+    {
+      code: `
+      /**
+       * @suppress
+       */
+      function quux () {}
+
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Tag @suppress must have a type in "closure" mode.',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @suppress {visibility} sth
+       */
+      function quux () {}
+
+      `,
+      errors: [
+        {
+          line: 3,
+          message: '@suppress should not have a name in "closure" mode.',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @suppress {visibility|blah}
+       */
+      function quux () {}
+
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Syntax error in supresss type: blah',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
   valid: [
     {
@@ -1278,5 +1338,19 @@ export default {
         },
       },
     },
+    {
+      code: `
+      /**
+       * @suppress {visibility|underscore}
+       */
+      function quux() {
+      }
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
 };