feat: support ESLint 8.x

BREAKING CHANGE: Requires ESLint@^7.0.0 || ^8.0.0

Author: MichaelDeBoey

.README/rules/check-examples.md

@@ -1,5 +1,8 @@
 ### `check-examples`
 
+> **NOTE**: This rule currently does not work in ESLint 8 (we are waiting for
+> [issue 14745](https://github.com/eslint/eslint/issues/14745)).
+
 Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
 has options to lint the default values of optional `@param`/`@arg`/`@argument`
 and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags.

.travis.yml

@@ -10,18 +10,7 @@ node_js:
 before_install:
   - npm config set depth 0
 before_script: >
-  node_version=$(node -v);
-  if [ ${node_version:3:1} = "." ]; then
-    echo "Node 10+"
-    if [ ${ESLINT} = "6" ]; then
-      npm install --legacy-peer-deps --no-save "eslint@${ESLINT}" [email protected]
-    else
-      npm install --legacy-peer-deps --no-save "eslint@${ESLINT}"
-    fi
-    else
-      echo "Node 8+"
-      npm install --legacy-peer-deps --no-save "eslint@${ESLINT}" [email protected] [email protected] [email protected]
-  fi
+  npm install --legacy-peer-deps --no-save "eslint@${ESLINT}"
 notifications:
   email: false
 script:
@@ -30,16 +19,13 @@ script:
   - npm run build
 env:
   jobs:
+    - ESLINT=8
     - ESLINT=7
-    - ESLINT=6
 jobs:
   fast_finish: true
   include:
     - node_js: 'lts/*'
       env: LINT=true
-  exclude:
-    - node_js: 8
-      env: ESLINT=7
 after_success:
   - export NODE_ENV=production
   - npm run build

README.md

@@ -945,6 +945,9 @@ function quux (foo) {
 <a name="eslint-plugin-jsdoc-rules-check-examples"></a>
 ### <code>check-examples</code>
 
+> **NOTE**: This rule currently does not work in ESLint 8 (we are waiting for
+> [issue 14745](https://github.com/eslint/eslint/issues/14745)).
+
 Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
 has options to lint the default values of optional `@param`/`@arg`/`@argument`
 and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags.
@@ -12907,7 +12910,7 @@ export class MyComponentComponent {
   @Input()
   public value = new EventEmitter();
 }
-// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ClassProperty:has(Decorator[expression.callee.name=\"Input\"])"]}]
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ClassProperty > Decorator[expression.callee.name=\"Input\"]"]}]
 // Message: Missing JSDoc comment.
 
 requestAnimationFrame(draw)

package.json

@@ -26,12 +26,12 @@
     "@babel/preset-env": "^7.15.8",
     "@babel/register": "^7.15.3",
     "@hkdobrev/run-if-changed": "^0.3.1",
-    "@typescript-eslint/parser": "^4.33.0",
+    "@typescript-eslint/parser": "^5.0.0-0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^6.0.0",
     "chai": "^4.3.4",
     "cross-env": "^7.0.3",
-    "eslint": "7.32.0",
+    "eslint": "^8.0.0",
     "eslint-config-canonical": "^28.0.0",
     "gitdown": "^3.1.4",
     "glob": "^7.2.0",
@@ -65,7 +65,7 @@
   "main": "./dist/index.js",
   "name": "eslint-plugin-jsdoc",
   "peerDependencies": {
-    "eslint": "^6.0.0 || ^7.0.0"
+    "eslint": "^7.0.0 || ^8.0.0"
   },
   "repository": {
     "type": "git",

src/rules/checkExamples.js

@@ -1,9 +1,5 @@
-// Todo: When peerDeps bump to ESLint 7, see about replacing `CLIEngine`
-//  with non-deprecated `ESLint` class:
-// https://github.com/eslint/eslint/blob/master/docs/user-guide/migrating-to-7.0.0.md#-the-cliengine-class-has-been-deprecated
-import {
-  CLIEngine,
-} from 'eslint';
+import { ESLint } from 'eslint';
+import semver from 'semver'
 import iterateJsdoc from '../iterateJsdoc';
 
 const zeroBasedLineIndexAdjust = -1;
@@ -85,6 +81,13 @@ export default iterateJsdoc(({
   context,
   globalState,
 }) => {
+  if(semver.gte(ESLint.version, '8.0.0')) {
+    return context.report({
+      loc: { start: { column: 1, line: 1 } },
+      message: `This rule cannot yet be supported for ESLint 8; you should either downgrade to ESLint 7 or disable this rule. The possibility for ESLint 8 support is being tracked at https://github.com/eslint/eslint/issues/14745`,
+    });
+  }
+
   if (!globalState.has('checkExamples-matchingFileName')) {
     globalState.set('checkExamples-matchingFileName', new Map());
   }
@@ -172,16 +175,16 @@ export default iterateJsdoc(({
       if (matchingFileNameMap.has(fileNameMapKey)) {
         cliFile = matchingFileNameMap.get(fileNameMapKey);
       } else {
-        const cli = new CLIEngine(cliConfig);
+        const cli = new ESLint(cliConfig);
         let config;
         if (filename || checkEslintrc) {
-          config = cli.getConfigForFile(file);
+          config = cli.calculateConfigForFile(file);
         }
 
         // We need a new instance to ensure that the rules that may only
         //  be available to `file` (if it has its own `.eslintrc`),
         //  will be defined.
-        cliFile = new CLIEngine({
+        cliFile = new ESLint({
           allowInlineConfig,
           baseConfig: {
             ...baseConfig,
@@ -196,8 +199,7 @@ export default iterateJsdoc(({
         matchingFileNameMap.set(fileNameMapKey, cliFile);
       }
 
-      const {results: [{messages}]} =
-        cliFile.executeOnText(src);
+      const { results: [{ messages }] } = cliFile.lintText(src);
 
       if (!('line' in tag)) {
         tag.line = tag.source[0].number;

test/rules/assertions/requireJsdoc.js

@@ -2,10 +2,6 @@
  * @see https://github.com/eslint/eslint/blob/master/tests/lib/rules/require-jsdoc.js
  */
 
-import {
-  CLIEngine,
-} from 'eslint';
-
 export default {
   invalid: [
     {
@@ -3016,15 +3012,7 @@ function quux (foo) {
         },
       ],
       options: [{
-        contexts: [
-          // Only fixed to support `:has()` with TS later in ESLint 7, but
-          //  for our testing of ESLint 6, we use `>` which is equivalent in
-          //  this case; after having peerDeps. to ESLint 7+, we can remove
-          //  this check and use of `CLIEngine`
-          CLIEngine.version.startsWith('6') ?
-            'ClassProperty > Decorator[expression.callee.name="Input"]' :
-            'ClassProperty:has(Decorator[expression.callee.name="Input"])',
-        ],
+        contexts: ['ClassProperty > Decorator[expression.callee.name="Input"]'],
       }],
       output: `
       export class MyComponentComponent {

test/rules/index.js

@@ -1,13 +1,18 @@
-import {
-  RuleTester,
-} from 'eslint';
+import { ESLint, RuleTester } from 'eslint';
 import _ from 'lodash';
+import semver from 'semver'
 import config from '../../src';
 import ruleNames from './ruleNames.json';
 
 const ruleTester = new RuleTester();
 
 (process.env.npm_config_rule ? process.env.npm_config_rule.split(',') : ruleNames).forEach(async (ruleName) => {
+  if(semver.gte(ESLint.version, '8.0.0') && ruleName === 'check-examples') {
+    // This rule cannot yet be supported for ESLint 8;
+    // The possibility for ESLint 8 support is being tracked at https://github.com/eslint/eslint/issues/14745
+    return;
+  }
+
   const rule = config.rules[ruleName];
 
   const parserOptions = {