feat(eslint-config-appium-ts)!: enable for JS sources

BREAKING CHANGE: This makes `@appium/eslint-config-appium-ts` also apply to JS sources _and_ requires a new peer dependency (`eslint-import-resolver-typescript`). The `main` file is now a `.js` file. The module is expected to _extend_ `@appium/eslint-config-appium`, not replace it; consumers needn't extend both in their ESLint config. In the not-too-distant past, `@typescript-eslint/parser` was unable to understand docstrings in `.js` files. Evidently this is no longer true. I've rewritten and heavily commented the configuration explaining the intent behind everything.
2026-02-23 03:40:15 -06:00 · 2023-03-17 12:53:52 -07:00
parent 78c6a0b991
commit 43df77f6b6
6 changed files with 256 additions and 31 deletions
--- a/.eslintrc
+++ b/.eslintrc
@@ -1,5 +1,5 @@
 {
-  "extends": ["@appium/eslint-config-appium", "@appium/eslint-config-appium-ts"],
+  "extends": ["@appium/eslint-config-appium-ts"],
  "overrides": [
    {
      "files": "packages/fake-driver/**/*",
@@ -26,9 +26,16 @@
        "sourceType": "script"
      }
    },
+    {
+      "files": ["./test/setup.js", "./**/scripts/**/*.js", "./packages/*/index.js"],
+      "rules": {
+        "@typescript-eslint/no-var-requires": "off"
+      }
+    },
    {
      "files": "./packages/*/test/**/*.js",
      "rules": {
+        "@typescript-eslint/no-var-requires": "off",
        "no-restricted-properties": [
          "error",
          {
--- a/package-lock.json
+++ b/package-lock.json
@@ -37,6 +37,7 @@
        "eslint": "8.36.0",
        "eslint-config-prettier": "8.8.0",
        "eslint-find-rules": "4.1.0",
+        "eslint-import-resolver-typescript": "3.5.3",
        "eslint-plugin-import": "2.27.5",
        "eslint-plugin-mocha": "10.1.0",
        "eslint-plugin-promise": "6.1.1",
@@ -2018,6 +2019,25 @@
        "typescript": "^3 || ^4"
      }
    },
+    "node_modules/@pkgr/utils": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@pkgr/utils/-/utils-2.3.1.tgz",
+      "integrity": "sha512-wfzX8kc1PMyUILA+1Z/EqoE4UCXGy0iRGMhPwdfae1+f0OXlLqCk+By+aMzgJBzR9AzS4CDizioG6Ss1gvAFJw==",
+      "dependencies": {
+        "cross-spawn": "^7.0.3",
+        "is-glob": "^4.0.3",
+        "open": "^8.4.0",
+        "picocolors": "^1.0.0",
+        "tiny-glob": "^0.2.9",
+        "tslib": "^2.4.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.18.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/unts"
+      }
+    },
    "node_modules/@sidvind/better-ajv-errors": {
      "version": "2.1.0",
      "license": "Apache-2.0",
@@ -5528,7 +5548,6 @@
    },
    "node_modules/define-lazy-prop": {
      "version": "2.0.0",
-      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=8"
@@ -5799,6 +5818,18 @@
        "once": "^1.4.0"
      }
    },
+    "node_modules/enhanced-resolve": {
+      "version": "5.12.0",
+      "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.12.0.tgz",
+      "integrity": "sha512-QHTXI/sZQmko1cbDoNAa3mJ5qhWUUNAq3vR0/YiD379fWQrcfuoX1+HW2S0MTt7XmoPLapdaDKUtelUSPic7hQ==",
+      "dependencies": {
+        "graceful-fs": "^4.2.4",
+        "tapable": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
    "node_modules/enquirer": {
      "version": "2.3.6",
      "dev": true,
@@ -6167,6 +6198,48 @@
        "ms": "^2.1.1"
      }
    },
+    "node_modules/eslint-import-resolver-typescript": {
+      "version": "3.5.3",
+      "resolved": "https://registry.npmjs.org/eslint-import-resolver-typescript/-/eslint-import-resolver-typescript-3.5.3.tgz",
+      "integrity": "sha512-njRcKYBc3isE42LaTcJNVANR3R99H9bAxBDMNDr2W7yq5gYPxbU3MkdhsQukxZ/Xg9C2vcyLlDsbKfRDg0QvCQ==",
+      "dependencies": {
+        "debug": "^4.3.4",
+        "enhanced-resolve": "^5.10.0",
+        "get-tsconfig": "^4.2.0",
+        "globby": "^13.1.2",
+        "is-core-module": "^2.10.0",
+        "is-glob": "^4.0.3",
+        "synckit": "^0.8.4"
+      },
+      "engines": {
+        "node": "^14.18.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/unts/projects/eslint-import-resolver-ts"
+      },
+      "peerDependencies": {
+        "eslint": "*",
+        "eslint-plugin-import": "*"
+      }
+    },
+    "node_modules/eslint-import-resolver-typescript/node_modules/globby": {
+      "version": "13.1.3",
+      "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.3.tgz",
+      "integrity": "sha512-8krCNHXvlCgHDpegPzleMq07yMYTO2sXKASmZmquEYWEmCx6J5UTRbp5RwMJkTJGtcQ44YpiUYUiN0b9mzy8Bw==",
+      "dependencies": {
+        "dir-glob": "^3.0.1",
+        "fast-glob": "^3.2.11",
+        "ignore": "^5.2.0",
+        "merge2": "^1.4.1",
+        "slash": "^4.0.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/eslint-module-utils": {
      "version": "2.7.4",
      "license": "MIT",
@@ -7292,6 +7365,14 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/get-tsconfig": {
+      "version": "4.4.0",
+      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.4.0.tgz",
+      "integrity": "sha512-0Gdjo/9+FzsYhXCEFueo2aY1z1tpXrxWZzP7k8ul9qt1U5o8rYJwTJYmaeHdrVosYIVYkOy2iwCJ9FdpocJhPQ==",
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
    "node_modules/gifwrap": {
      "version": "0.9.4",
      "resolved": "https://registry.npmjs.org/gifwrap/-/gifwrap-0.9.4.tgz",
@@ -7497,6 +7578,11 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/globalyzer": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/globalyzer/-/globalyzer-0.1.0.tgz",
+      "integrity": "sha512-40oNTM9UfG6aBmuKxk/giHn5nQ8RVz/SS4Ir6zgzOv9/qC3kKZ9v4etGTcJbEl/NyVQH7FGU7d+X1egr57Md2Q=="
+    },
    "node_modules/globby": {
      "version": "11.1.0",
      "license": "MIT",
@@ -7522,6 +7608,11 @@
        "node": ">=8"
      }
    },
+    "node_modules/globrex": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/globrex/-/globrex-0.1.2.tgz",
+      "integrity": "sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg=="
+    },
    "node_modules/gopd": {
      "version": "1.0.1",
      "license": "MIT",
@@ -12637,7 +12728,6 @@
    },
    "node_modules/open": {
      "version": "8.4.0",
-      "dev": true,
      "license": "MIT",
      "dependencies": {
        "define-lazy-prop": "^2.0.0",
@@ -13265,6 +13355,11 @@
      "resolved": "https://registry.npmjs.org/phin/-/phin-2.9.3.tgz",
      "integrity": "sha512-CzFr90qM24ju5f88quFC/6qohjC144rehe5n6DH900lgXmUe86+xCKc10ev56gRKC4/BkHUoG4uSiQgBiIXwDA=="
    },
+    "node_modules/picocolors": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz",
+      "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ=="
+    },
    "node_modules/picomatch": {
      "version": "2.3.1",
      "license": "MIT",
@@ -14658,7 +14753,6 @@
    },
    "node_modules/slash": {
      "version": "4.0.0",
-      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=12"
@@ -15279,6 +15373,29 @@
        "node": ">=12"
      }
    },
+    "node_modules/synckit": {
+      "version": "0.8.5",
+      "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.8.5.tgz",
+      "integrity": "sha512-L1dapNV6vu2s/4Sputv8xGsCdAVlb5nRDMFU/E27D44l5U6cw1g0dGd45uLc+OXjNMmF4ntiMdCimzcjFKQI8Q==",
+      "dependencies": {
+        "@pkgr/utils": "^2.3.1",
+        "tslib": "^2.5.0"
+      },
+      "engines": {
+        "node": "^14.18.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/unts"
+      }
+    },
+    "node_modules/tapable": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.2.1.tgz",
+      "integrity": "sha512-GNzQvQTOIP6RyTfE2Qxb8ZVlNmw0n88vp1szwWRimP02mnTsx3Wtn5qRdqY9w2XduFNUgvOwhNnQsjwCp+kqaQ==",
+      "engines": {
+        "node": ">=6"
+      }
+    },
    "node_modules/tar": {
      "version": "6.1.12",
      "dev": true,
@@ -15454,6 +15571,15 @@
      "version": "1.7.1",
      "license": "MIT"
    },
+    "node_modules/tiny-glob": {
+      "version": "0.2.9",
+      "resolved": "https://registry.npmjs.org/tiny-glob/-/tiny-glob-0.2.9.tgz",
+      "integrity": "sha512-g/55ssRPUjShh+xkfx9UPDXqhckHEsHr4Vd9zX55oSdGZc/MD0m3sferOkwWtp98bv+kcVfEHtRJgBVJzelrzg==",
+      "dependencies": {
+        "globalyzer": "0.1.0",
+        "globrex": "^0.1.2"
+      }
+    },
    "node_modules/tinycolor2": {
      "version": "1.6.0",
      "resolved": "https://registry.npmjs.org/tinycolor2/-/tinycolor2-1.6.0.tgz",
@@ -15612,8 +15738,9 @@
      }
    },
    "node_modules/tslib": {
-      "version": "2.4.1",
-      "license": "0BSD"
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.5.0.tgz",
+      "integrity": "sha512-336iVw3rtn2BUK7ORdIAHTyxHGRIHVReokCR3XjbckJMK7ms8FysBfhLR8IXnAgy7T0PTPNBWKiH514FOW/WSg=="
    },
    "node_modules/tsutils": {
      "version": "3.21.0",
@@ -17095,6 +17222,7 @@
        "@typescript-eslint/parser": "^5.5.0",
        "eslint": "^8.21.0",
        "eslint-config-prettier": "^8.5.0",
+        "eslint-import-resolver-typescript": "^3.5.0",
        "eslint-plugin-import": "^2.26.0",
        "eslint-plugin-mocha": "^10.1.0",
        "eslint-plugin-promise": "^6.0.0"
--- a/package.json
+++ b/package.json
@@ -100,6 +100,7 @@
    "eslint": "8.36.0",
    "eslint-config-prettier": "8.8.0",
    "eslint-find-rules": "4.1.0",
+    "eslint-import-resolver-typescript": "3.5.3",
    "eslint-plugin-import": "2.27.5",
    "eslint-plugin-mocha": "10.1.0",
    "eslint-plugin-promise": "6.1.1",
--- a/packages/eslint-config-appium-ts/index.js
+++ b/packages/eslint-config-appium-ts/index.js
@@ -0,0 +1,110 @@
+/**
+ * `@appium/eslint-config-appium-ts` is a configuration for ESLint which extends
+ * `@appium/eslint-config-appium` and adds TypeScript support.
+ *
+ * It is **not** a _replacement for_ `@appium/eslint-config-appium`.
+ *
+ * It can be used _without any `.ts` sources_, as long as a `tsconfig.json` exists in the project
+ * root. In that case, it will run on `.js` files which are enabled for checking; this includes the
+ * `checkJs` setting and any `// @ts-check` directive in source files.
+ */
+
+module.exports = {
+  $schema: 'http://json.schemastore.org/eslintrc',
+  parser: '@typescript-eslint/parser',
+  extends: ['@appium/eslint-config-appium', 'plugin:@typescript-eslint/recommended'],
+  rules: {
+    /**
+     * This rule is configured to warn if a `@ts-ignore` or `@ts-expect-error` directive is used
+     * without explanation.
+     * @remarks It's good practice to explain why things break!
+     */
+    '@typescript-eslint/ban-ts-comment': [
+      'warn',
+      {
+        'ts-expect-error': 'allow-with-description',
+        'ts-ignore': 'allow-with-description',
+      },
+    ],
+    /**
+     * Empty functions are allowed.
+     * @remarks This is disabled because I need someone to explain to me why empty functions are bad. I suppose they _could_ be bugs, but so could literally any line of code.
+     */
+    '@typescript-eslint/no-empty-function': 'off',
+    /**
+     * Empty interfaces are allowed.
+     * @remarks This is because empty interfaces have a use case in declaration merging.  Otherwise,
+     * an empty interface can be a type alias, e.g., `type Foo = Bar` where `Bar` is an interface.
+     */
+    '@typescript-eslint/no-empty-interface': 'off',
+    /**
+     * Explicit `any` types are allowed.
+     * @remarks Eventually this should be a warning, and finally an error, as we fully type the codebases.
+     */
+    '@typescript-eslint/no-explicit-any': 'off',
+    /**
+     * Warns if a non-null assertion (`!`) is used.
+     * @remarks Generally, a non-null assertion should be replaced by a proper type guard or
+     * type-safe function, if possible. For example, `Set.prototype.has(x)` is not type-safe, and
+     * does not imply that `Set.prototype.get(x)` is not `undefined` (I do not know why this is, but
+     * I'm sure there's a good reason for it). In this case, a non-null assertion is appropriate.
+     * Often a simple `typeof x === 'y'` conditional is sufficient to narrow the type and avoid the
+     * non-null assertion.
+     */
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    /**
+     * This disallows use of `require()`.
+     * @remarks We _do_ use `require()` fairly often to load files on-the-fly; however, these may
+     * want to be replaced with `import()` (I am not sure if there's a rule about that?).  **If this check fails**, disable the rule for the particular line.
+     */
+    '@typescript-eslint/no-var-requires': 'error',
+    // 'no-unused-vars': 'off',
+    /**
+     * Allow native `Promise`s. **This overrides `@appium/eslint-config-appium`.**
+     * @remarks Originally, this was so that we could use [bluebird](https://npm.im/bluebird)
+     * everywhere, but this is not strictly necessary.
+     */
+    'promise/no-native': 'off',
+    /**
+     * Allow `async` functions without `await`.  **This overrides `@appium/eslint-config-appium`.**
+     * @remarks Originally, this was to be more clear about the return value of a function, but with
+     * the addition of types, this is no longer necessary. Further, both `return somePromise` and
+     * `return await somePromise` have their own use-cases.
+     */
+    'require-await': 'off',
+  },
+  /**
+   * This stuff enables `eslint-plugin-import` to resolve TS modules.
+   */
+  settings: {
+    'import/parsers': {
+      '@typescript-eslint/parser': ['.ts', '.tsx'],
+    },
+    'import/resolver': {
+      typescript: {
+        project: ['tsconfig.json', './packages/*/tsconfig.json'],
+      },
+    },
+  },
+  overrides: [
+    /**
+     * Overrides for tests.
+     */
+    {
+      files: ['**/test/**', '*.spec.js', '-specs.js', '*.spec.ts'],
+      rules: {
+        /**
+         * Both `@ts-expect-error` and `@ts-ignore` are allowed to be used with impunity in tests.
+         * @remarks We often test things which explicitly violate types.
+         */
+        '@typescript-eslint/ban-ts-comment': 'off',
+        /**
+         * Allow non-null assertions in tests; do not even warn.
+         * @remarks The idea is that the assertions themselves will be written in such a way that if
+         * the non-null assertion was invalid, the assertion would fail.
+         */
+        '@typescript-eslint/no-non-null-assertion': 'off',
+      },
+    },
+  ],
+};
--- a/packages/eslint-config-appium-ts/index.json
+++ b/packages/eslint-config-appium-ts/index.json
@@ -1,22 +0,0 @@
-{
-  "$schema": "http://json.schemastore.org/eslintrc",
-  "overrides": [
-    {
-      "files": ["*.ts", "*.tsx"],
-      "parser": "@typescript-eslint/parser",
-      "extends": ["@appium/eslint-config-appium", "plugin:@typescript-eslint/recommended"],
-      "rules": {
-        "@typescript-eslint/no-empty-function": 1,
-        "@typescript-eslint/no-empty-interface": 0,
-        "@typescript-eslint/no-explicit-any": 0,
-        "@typescript-eslint/no-non-null-assertion": 0,
-        "@typescript-eslint/no-var-requires": 1,
-        "import/no-duplicates": 0,
-        "import/no-unresolved": 0,
-        "no-unused-vars": 0,
-        "promise/no-native": 0,
-        "require-await": 0
-      }
-    }
-  ]
-}
--- a/packages/eslint-config-appium-ts/package.json
+++ b/packages/eslint-config-appium-ts/package.json
@@ -20,9 +20,9 @@
  },
  "license": "Apache-2.0",
  "author": "https://github.com/appium",
-  "main": "index.json",
+  "main": "index.js",
  "files": [
-    "index.json"
+    "index.js"
  ],
  "scripts": {
    "test:smoke": "exit 0"
@@ -35,7 +35,8 @@
    "eslint-config-prettier": "^8.5.0",
    "eslint-plugin-import": "^2.26.0",
    "eslint-plugin-mocha": "^10.1.0",
-    "eslint-plugin-promise": "^6.0.0"
+    "eslint-plugin-promise": "^6.0.0",
+    "eslint-import-resolver-typescript": "^3.5.0"
  },
  "engines": {
    "node": "^14.17.0 || ^16.13.0 || >=18.0.0",