Merge branch 'master' into add-more-type-checks-to-valid-types

* master:
  chore: report unused disable directives in eslint
  refactor: remove unused disable directives
  fix(require-jsdoc): avoid exported functions possessing jsdoc blocks causing other non-public functions to be treated as exported; fixes gajus#358
  refactor(require-jsdoc): remove redundant check
  docs(require-returns): Fix typo
  chore: update devDeps; avoid `lint-staged`
  Add type "symbol" to noUndefinedTypes
  chore: update `lint-staged` for husky issue: typicode/husky#247
  chore(CI): stop running broken npm script `check-readme`
  fix(no-undefined-types): avoid `flat-map-polyfill` entirely; further further fix for gajus#366
  fix(check-tag-names): ensure `replacement` field overrides a default tag name preference; fixes gajus#367
  chore: update comment-parser dep. and devDeps; avoid buggy eslint6.2 and for eslint 6 tests, avoid breaking typescript-eslint/parser update
  fix(`no-undefined-types`): import flat-map polyfill directly to avoid renamed `flatten` method from polluting prototype (gajus#366)

Author: brettz9

.README/rules/require-returns.md

@@ -15,7 +15,7 @@ Will also report if multiple `@returns` tags are present.
 - `forceReturnsWithAsync` - By default `async` functions that do not explicitly return a value pass this rule. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` to `true` on the options object. This may be useful as an `async` function will always return a `Promise`, even if the `Promise` returns void. Defaults to `false`.
 
 ```js
-'jsdoc/require-jsdoc': ['error', {forceReturnsWithAsync: true}]
+'jsdoc/require-returns': ['error', {forceReturnsWithAsync: true}]
 ```
 
 |||

.travis.yml

@@ -7,15 +7,14 @@ node_js:
 before_install:
   - npm config set depth 0
 before_script:
-  - 'if [ "${ESLINT-}" == "6" ]; then npm install --no-save "eslint@${ESLINT}" ; fi'
-  - 'if [ "${ESLINT-}" == "5" ]; then npm install --no-save "eslint@${ESLINT}" [email protected] [email protected] ; fi'
+  - 'if [ "${ESLINT-}" == "6" ]; then npm install --no-save "eslint@${ESLINT}.1" ; fi'
+  - 'if [ "${ESLINT-}" == "5" ]; then npm install --no-save "eslint@${ESLINT}" [email protected] [email protected] @typescript-eslint/[email protected] ; fi'
 notifications:
   email: false
 sudo: false
 script:
   - npm run test
   - 'if [ -n "${LINT-}" ]; then npm run lint; fi'
-  - 'if [ -n "${CHECK_README-}" ]; then npm run check-readme; fi'
   - npm run build
 env:
   matrix:
@@ -26,8 +25,6 @@ matrix:
   include:
     - node_js: 'lts/*'
       env: LINT=true
-    - node_js: 'lts/*'
-      env: CHECK_README=true
   exclude:
     - node_js: 6
       env: ESLINT=6

README.md

@@ -1550,6 +1550,14 @@ function quux (foo) {
 function quux () {
 
 }
+
+/**
+ * @extends Foo
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"augments":{"message":"@extends is to be used over @augments.","replacement":"extends"}}}}
 ````
 
 
@@ -5630,6 +5638,15 @@ const myObject = {
   myProp: true
 };
 // Options: [{"contexts":[]}]
+
+function bear() {}
+/**
+ *
+ */
+function quux () {
+}
+export default quux;
+// Options: [{"publicOnly":true,"require":{"FunctionExpression":true}}]
 ````
 
 
@@ -6860,7 +6877,7 @@ Will also report if multiple `@returns` tags are present.
 - `forceReturnsWithAsync` - By default `async` functions that do not explicitly return a value pass this rule. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` to `true` on the options object. This may be useful as an `async` function will always return a `Promise`, even if the `Promise` returns void. Defaults to `false`.
 
 ```js
-'jsdoc/require-jsdoc': ['error', {forceReturnsWithAsync: true}]
+'jsdoc/require-returns': ['error', {forceReturnsWithAsync: true}]
 ```
 
 |||

package.json

@@ -5,9 +5,8 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "comment-parser": "^0.6.1",
+    "comment-parser": "^0.6.2",
     "debug": "^4.1.1",
-    "flat-map-polyfill": "^0.3.8",
     "jsdoctypeparser": "5.0.1",
     "lodash": "^4.17.15",
     "object.entries-ponyfill": "^1.0.1",
@@ -21,19 +20,19 @@
     "@babel/plugin-transform-flow-strip-types": "^7.4.4",
     "@babel/preset-env": "^7.5.5",
     "@babel/register": "^7.5.5",
-    "@typescript-eslint/parser": "^1.13.0",
-    "babel-eslint": "^10.0.2",
+    "@typescript-eslint/parser": "^2.0.0",
+    "babel-eslint": "^10.0.3",
     "babel-plugin-add-module-exports": "^1.0.2",
     "babel-plugin-istanbul": "^5.2.0",
     "chai": "^4.2.0",
-    "eslint": "^6.1.0",
-    "eslint-config-canonical": "^17.3.4",
+    "eslint": "6.2.2",
+    "eslint-config-canonical": "^17.4.0",
     "gitdown": "^3.1.1",
     "glob": "^7.1.4",
-    "husky": "^3.0.3",
+    "husky": "^3.0.4",
     "mocha": "^6.2.0",
     "nyc": "^14.1.1",
-    "semantic-release": "^15.13.19",
+    "semantic-release": "^15.13.24",
     "typescript": "^3.5.3"
   },
   "engines": {
@@ -63,8 +62,8 @@
     "build": "rm -fr ./dist && NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps",
     "check-readme": "babel-node ./src/bin/generateReadme.js --check",
     "create-readme": "babel-node ./src/bin/generateReadme.js",
-    "lint-fix": "eslint --fix ./src ./test",
-    "lint": "eslint ./src ./test",
+    "lint-fix": "eslint --report-unused-disable-directives --fix ./src ./test",
+    "lint": "eslint --report-unused-disable-directives ./src ./test",
     "test-cov": "BABEL_ENV=test nyc mocha --recursive --require @babel/register --reporter progress --timeout 9000",
     "test-no-cov": "BABEL_ENV=test mocha --recursive --require @babel/register --reporter progress --timeout 9000",
     "test-index": "BABEL_ENV=test mocha --recursive --require @babel/register --reporter progress --timeout 9000 test/rules/index.js",

src/eslint/getJSDocComment.js

@@ -26,7 +26,6 @@ const looksLikeExport = function (astNode) {
     astNode.type === 'ExportAllDeclaration' || astNode.type === 'ExportSpecifier';
 };
 
-/* eslint-disable complexity */
 /**
  * Retrieves the JSDoc comment for a given node.
  *
@@ -107,6 +106,5 @@ const getJSDocComment = function (sourceCode, node, settings) {
     return findJSDocComment(node);
   }
 };
-/* eslint-enable complexity */
 
 export default getJSDocComment;

src/exportParser.js

@@ -340,9 +340,7 @@ const findExportedNode = function (block, node, cache) {
     if (Object.prototype.hasOwnProperty.call(props, key)) {
       blockCache.push(props[key]);
       if (props[key].exported) {
-        // If not always true, we need a test
-        /* istanbul ignore next */
-        if (findNode(node, block)) {
+        if (node === props[key].value || findNode(node, props[key].value)) {
           return true;
         }
       }

src/jsdocUtils.js

@@ -61,7 +61,10 @@ const getJsdocParameterNames = (jsdoc : Object, targetTagName : string) : Array<
 };
 
 const getPreferredTagName = (name : string, tagPreference : Object = {}) : string => {
-  if (_.values(tagPreference).includes(name)) {
+  const prefValues = _.values(tagPreference);
+  if (prefValues.includes(name) || prefValues.some((prefVal) => {
+    return prefVal && typeof prefVal === 'object' && prefVal.replacement === name;
+  })) {
     return name;
   }
 

src/rules/noUndefinedTypes.js

@@ -1,14 +1,12 @@
-// eslint-disable-next-line import/no-unassigned-import
-import 'flat-map-polyfill';
 import _ from 'lodash';
 import {parse as parseType, traverse} from 'jsdoctypeparser';
 import iterateJsdoc, {parseComment} from '../iterateJsdoc';
 import jsdocUtils from '../jsdocUtils';
 
 const extraTypes = [
-  'null', 'undefined', 'string', 'boolean', 'object',
+  'null', 'undefined', 'string', 'symbol', 'boolean', 'object',
   'function',
-  'number', 'NaN', 'Infinity',
+  'number', 'bigint', 'NaN', 'Infinity',
   'any', '*',
   'Array', 'Object', 'RegExp', 'Date', 'Function',
 ];
@@ -78,7 +76,7 @@ export default iterateJsdoc(({
     );
   }
 
-  const closureGenericTypes = templateTags.flatMap((tag) => {
+  const closureGenericTypes = _.flatMap(templateTags, (tag) => {
     return jsdocUtils.parseClosureTemplateTag(tag);
   });
 

src/rules/requireJsdoc.js

@@ -182,7 +182,7 @@ export default {
         const parseResult = exportParser.parse(sourceCode.ast, node, opt);
         const exported = exportParser.isExported(node, parseResult, opt);
 
-        if (exported && !jsDocNode) {
+        if (exported) {
           context.report({
             fix,
             messageId: 'missingJsDoc',

src/rules/requireParam.js

@@ -1,6 +1,5 @@
 import iterateJsdoc from '../iterateJsdoc';
 
-// eslint-disable-next-line complexity
 export default iterateJsdoc(({
   report,
   utils,

test/rules/assertions/checkExamples.js

@@ -1,5 +1,3 @@
-/* eslint-disable no-restricted-syntax */
-
 export default {
   invalid: [
     {

test/rules/assertions/checkTagNames.js

@@ -517,5 +517,25 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           * @extends Foo
+           */
+          function quux () {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            augments: {
+              message: '@extends is to be used over @augments.',
+              replacement: 'extends',
+            },
+          },
+        },
+      },
+    },
   ],
 };

test/rules/assertions/requireJsdoc.js

@@ -2163,5 +2163,24 @@ export default {
         contexts: [],
       },
     ],
+  }, {
+    code: `
+      function bear() {}
+      /**
+       *
+       */
+      function quux () {
+      }
+      export default quux;
+    `,
+    options: [{
+      publicOnly: true,
+      require: {
+        FunctionExpression: true,
+      },
+    }],
+    parserOptions: {
+      sourceType: 'module',
+    },
   }],
 };