feat(check-types, no-undefined-types, valid-types): use mode-aware type parsing; fixes part of gajus#356; fixes gajus#495

BREAKING CHANGE:

Requires Node 10+

Also:
1. Adds "permissive" mode
2. Checks "param" for valid namepaths

Author: brettz9

.README/README.md

@@ -131,13 +131,18 @@ how many line breaks to add when a block is missing.
 ### Mode
 
 - `settings.jsdoc.mode` - Set to `jsdoc` (the default), `typescript`, or `closure`.
+  Note that if you do not wish to use separate `.eslintrc.*` files for a project
+  containing both JavaScript and TypeScript, you can also use [`overrides`](https://eslint.org/docs/user-guide/configuring). You may also set to `"permissive"` to
+  try to be as accommodating to any of the styles, but this is not recommended.
   Currently is used for the following:
   - Determine valid tags for `check-tag-names`
   - Only check `@template` in `no-undefined-types` for types in "closure" and
     "typescript" modes
   - For type-checking rules, determine which tags will be checked for types
     (Closure allows types on some tags which the others do not,
     so these tags will additionally be checked in "closure" mode)
+  - For type-checking rules, impacts parsing of types (through
+    [jsdoctypeparser](https://github.com/jsdoctypeparser/jsdoctypeparser) dependency)
   - Check preferred tag names
 
 ### Alias Preference

.travis.yml

@@ -3,7 +3,6 @@ node_js:
   - 14
   - 12
   - 10
-  - 8
 before_install:
   - npm config set depth 0
 before_script: >

README.md

@@ -189,13 +189,18 @@ how many line breaks to add when a block is missing.
 ### Mode
 
 - `settings.jsdoc.mode` - Set to `jsdoc` (the default), `typescript`, or `closure`.
+  Note that if you do not wish to use separate `.eslintrc.*` files for a project
+  containing both JavaScript and TypeScript, you can also use [`overrides`](https://eslint.org/docs/user-guide/configuring). You may also set to `"permissive"` to
+  try to be as accommodating to any of the styles, but this is not recommended.
   Currently is used for the following:
   - Determine valid tags for `check-tag-names`
   - Only check `@template` in `no-undefined-types` for types in "closure" and
     "typescript" modes
   - For type-checking rules, determine which tags will be checked for types
     (Closure allows types on some tags which the others do not,
     so these tags will additionally be checked in "closure" mode)
+  - For type-checking rules, impacts parsing of types (through
+    [jsdoctypeparser](https://github.com/jsdoctypeparser/jsdoctypeparser) dependency)
   - Check preferred tag names
 
 <a name="eslint-plugin-jsdoc-settings-alias-preference"></a>
@@ -13256,6 +13261,14 @@ function quux() {
 }
 // Message: Syntax error in namepath: module:namespace.SomeClass<~
 
+/**
+ * @param someParam<~
+ */
+function quux() {
+
+}
+// Message: Syntax error in namepath: someParam<~
+
 /**
  * @memberof module:namespace.SomeClass~<
  */
@@ -13391,6 +13404,15 @@ function quux () {}
  let foo;
 // Settings: {"jsdoc":{"mode":"closure"}}
 // Message: Tag @this must have a type
+
+/**
+ * Foo function.
+ *
+ * @param {[number, string]} bar - The bar array.
+ */
+function foo(bar) {}
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
+// Message: Syntax error in type: [number, string]
 ````
 
 The following patterns are not considered problems:
@@ -13565,6 +13587,22 @@ function quux () {}
  * @define
  */
  function quux () {}
+
+/**
+ * Foo function.
+ *
+ * @param {[number, string]} bar - The bar array.
+ */
+function foo(bar) {}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+
+/**
+ * Foo function.
+ *
+ * @param {[number, string]} bar - The bar array.
+ */
+function foo(bar) {}
+// Settings: {"jsdoc":{"mode":"permissive"}}
 ````
 
 

package.json

@@ -7,7 +7,7 @@
   "dependencies": {
     "comment-parser": "^0.7.5",
     "debug": "^4.1.1",
-    "jsdoctypeparser": "^6.1.0",
+    "jsdoctypeparser": "^7.0.0",
     "lodash": "^4.17.15",
     "regextras": "^0.7.1",
     "semver": "^6.3.0",
@@ -32,14 +32,14 @@
     "gitdown": "^3.1.3",
     "glob": "^7.1.6",
     "husky": "^4.2.5",
-    "mocha": "^7.2.0",
+    "mocha": "^8.0.1",
     "nyc": "^15.1.0",
     "rimraf": "^3.0.2",
     "semantic-release": "^17.0.8",
     "typescript": "^3.9.5"
   },
   "engines": {
-    "node": ">=8"
+    "node": ">=10"
   },
   "husky": {
     "hooks": {

src/jsdocUtils.js

@@ -192,7 +192,7 @@ const getTagNamesForMode = (mode, context) => {
     return jsdocTags;
   case 'typescript':
     return typeScriptTags;
-  case 'closure':
+  case 'closure': case 'permissive':
     return closureTags;
   default:
     if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {
@@ -399,9 +399,10 @@ const namepathDefiningTags = new Set([
 ]);
 
 // The following do not seem to allow curly brackets in their doc
-//  signature or examples (besides `modifies`)
+//  signature or examples (besides `modifies` and `param`)
 const tagsWithOptionalNamePosition = new Set([
   ...namepathDefiningTags,
+  'param',
 
   // `borrows` has a different format, however, so needs special parsing;
   //   seems to require both, and as "namepath"'s

src/rules/checkTypes.js

@@ -38,6 +38,11 @@ const adjustNames = (type, preferred, isGenericMatch, nodeName, node, parentNode
         if (bracketEnd) {
           parentNode.meta.syntax = 'ANGLE_BRACKET';
           ret = preferred.slice(0, -2);
+        } else if (
+          parentNode.meta.syntax === 'SQUARE_BRACKET' &&
+          (nodeName === '[]' || nodeName === 'Array')
+        ) {
+          parentNode.meta.syntax = 'ANGLE_BRACKET';
         }
       }
     }
@@ -64,7 +69,7 @@ export default iterateJsdoc(({
     return utils.tagMightHaveTypePosition(tag.tag);
   });
 
-  const {preferredTypes} = settings;
+  const {preferredTypes, mode} = settings;
   const {
     noDefaults,
     unifyParentAndChildTypeChecks,
@@ -126,7 +131,7 @@ export default iterateJsdoc(({
     let typeAst;
 
     try {
-      typeAst = parse(jsdocTag.type);
+      typeAst = parse(jsdocTag.type, {mode});
     } catch {
       return;
     }

src/rules/noUndefinedTypes.js

@@ -30,7 +30,7 @@ export default iterateJsdoc(({
   const {definedTypes = []} = context.options[0] || {};
 
   let definedPreferredTypes = [];
-  const {preferredTypes} = settings;
+  const {preferredTypes, mode} = settings;
   if (Object.keys(preferredTypes).length) {
     // Replace `_.values` with `Object.values` when we may start requiring Node 7+
     definedPreferredTypes = _.values(preferredTypes).map((preferredType) => {
@@ -139,7 +139,7 @@ export default iterateJsdoc(({
     let parsedType;
 
     try {
-      parsedType = parseType(tag.type);
+      parsedType = parseType(tag.type, {mode});
     } catch {
       // On syntax error, will be handled by valid-types.
       return;

src/rules/requireDescriptionCompleteSentence.js

@@ -11,11 +11,7 @@ const otherDescriptiveTags = new Set([
 ]);
 
 const extractParagraphs = (text) => {
-  // Todo [engine:node@>8.11.0]: Uncomment following line with neg. lookbehind instead
-  // return text.split(/(?<![;:])\n\n/u);
-  return [...text].reverse().join('').split(/\n\n(?![;:])/u).map((par) => {
-    return [...par].reverse().join('');
-  }).reverse();
+  return text.split(/(?<![;:])\n\n/u);
 };
 
 const extractSentences = (text, abbreviationsRegex) => {

src/rules/requireJsdoc.js

@@ -225,67 +225,63 @@ export default {
       }
     };
 
-    // todo[engine:node@>=8.3.0]: Change to object spread
-    // eslint-disable-next-line fp/no-mutating-assign
-    return Object.assign(
-      jsdocUtils.getContextObject(jsdocUtils.enforcedContexts(context, []), checkJsDoc),
-      {
-        ArrowFunctionExpression (node) {
-          if (!requireOption.ArrowFunctionExpression) {
-            return;
-          }
+    return {
+      ...jsdocUtils.getContextObject(jsdocUtils.enforcedContexts(context, []), checkJsDoc),
+      ArrowFunctionExpression (node) {
+        if (!requireOption.ArrowFunctionExpression) {
+          return;
+        }
 
-          if (!['VariableDeclarator', 'ExportDefaultDeclaration', 'AssignmentExpression'].includes(node.parent.type)) {
-            return;
-          }
+        if (!['VariableDeclarator', 'ExportDefaultDeclaration', 'AssignmentExpression'].includes(node.parent.type)) {
+          return;
+        }
 
-          checkJsDoc(node, true);
-        },
+        checkJsDoc(node, true);
+      },
 
-        ClassDeclaration (node) {
-          if (!requireOption.ClassDeclaration) {
-            return;
-          }
+      ClassDeclaration (node) {
+        if (!requireOption.ClassDeclaration) {
+          return;
+        }
 
-          checkJsDoc(node);
-        },
+        checkJsDoc(node);
+      },
 
-        ClassExpression (node) {
-          if (!requireOption.ClassExpression) {
-            return;
-          }
+      ClassExpression (node) {
+        if (!requireOption.ClassExpression) {
+          return;
+        }
 
-          checkJsDoc(node);
-        },
+        checkJsDoc(node);
+      },
 
-        FunctionDeclaration (node) {
-          if (!requireOption.FunctionDeclaration) {
-            return;
-          }
+      FunctionDeclaration (node) {
+        if (!requireOption.FunctionDeclaration) {
+          return;
+        }
 
-          checkJsDoc(node, true);
-        },
+        checkJsDoc(node, true);
+      },
 
-        FunctionExpression (node) {
-          if (requireOption.MethodDefinition && node.parent.type === 'MethodDefinition') {
-            checkJsDoc(node, true);
+      FunctionExpression (node) {
+        if (requireOption.MethodDefinition && node.parent.type === 'MethodDefinition') {
+          checkJsDoc(node, true);
 
-            return;
-          }
+          return;
+        }
 
-          if (!requireOption.FunctionExpression) {
-            return;
-          }
+        if (!requireOption.FunctionExpression) {
+          return;
+        }
 
-          if (
-            ['VariableDeclarator', 'AssignmentExpression', 'ExportDefaultDeclaration'].includes(node.parent.type) ||
-            node.parent.type === 'Property' && node === node.parent.value
-          ) {
-            checkJsDoc(node, true);
-          }
-        },
+        if (
+          ['VariableDeclarator', 'AssignmentExpression', 'ExportDefaultDeclaration'].includes(node.parent.type) ||
+          node.parent.type === 'Property' && node === node.parent.value
+        ) {
+          checkJsDoc(node, true);
+        }
       },
-    );
+    };
   },
   meta: {
     docs: {

src/rules/validTypes.js

@@ -8,19 +8,20 @@ export default iterateJsdoc(({
   report,
   utils,
   context,
+  settings,
 }) => {
   const {
     allowEmptyNamepaths = true,
     checkSeesForNamepaths = false,
   } = context.options[0] || {};
-
+  const {mode} = settings;
   if (!jsdoc.tags) {
     return;
   }
   jsdoc.tags.forEach((tag) => {
     const validNamepathParsing = function (namepath, tagName) {
       try {
-        parse(namepath);
+        parse(namepath, {mode});
       } catch {
         let handled = false;
 
@@ -29,7 +30,7 @@ export default iterateJsdoc(({
             const endChar = namepath.slice(-1);
             if (['#', '.', '~'].includes(endChar)) {
               try {
-                parse(namepath.slice(0, -1));
+                parse(namepath.slice(0, -1), {mode});
                 handled = true;
               } catch {
                 // Use the original error for including the whole type
@@ -39,7 +40,7 @@ export default iterateJsdoc(({
             const startChar = namepath.charAt();
             if (['#', '.', '~'].includes(startChar)) {
               try {
-                parse(namepath.slice(1));
+                parse(namepath.slice(1), {mode});
                 handled = true;
               } catch {
                 // Use the original error for including the whole type
@@ -60,7 +61,7 @@ export default iterateJsdoc(({
 
     const validTypeParsing = function (type) {
       try {
-        parse(type);
+        parse(type, {mode});
       } catch {
         report(`Syntax error in type: ${type}`, null, tag);