eslint-config-isaacscript 3.7.1 → 4.0.0

package/base-import.js

@@ -0,0 +1,224 @@
+// This ESLint config only contains rules from `eslint-plugin-import`:
+// https://github.com/import-js/eslint-plugin-import
+
+// Rules are separated into categories:
+// 1) Helpful warnings
+// 2) Module systems
+// 3) Static analysis
+// 4) Style guide
+
+/** @type {import("eslint").Linter.RulesRecord} */
+const HELPFUL_WARNINGS = {
+  "import/export": "error",
+
+  /**
+   * Superseded by the `deprecation/deprecation` rule. (That rule is better because it catches
+   * deprecated usage that does not come from import statements specifically.)
+   */
+  "import/no-deprecated": "off",
+
+  "import/no-empty-named-blocks": "error",
+
+  /**
+   * The options are [copied from
+   * Airbnb](https://github.com/airbnb/javascript/blob/master/packages/eslint-config-airbnb-base/rules/import.js).
+   */
+  "import/no-extraneous-dependencies": [
+    "error",
+    {
+      devDependencies: [
+        "test/**", // tape, common npm pattern
+        "tests/**", // also common npm pattern
+        "spec/**", // mocha, rspec-like pattern
+        "**/__tests__/**", // jest pattern
+        "**/__mocks__/**", // jest pattern
+        "test.{js,jsx}", // repos with a single test file
+        "test-*.{js,jsx}", // repos with multiple top-level test files
+        "**/*{.,_}{test,spec}.{js,jsx}", // tests where the extension or filename suffix denotes that it is a test
+        "**/jest.config.js", // jest config
+        "**/jest.setup.js", // jest setup
+        "**/vue.config.js", // vue-cli config
+        "**/webpack.config.js", // webpack config
+        "**/webpack.config.*.js", // webpack config
+        "**/rollup.config.js", // rollup config
+        "**/rollup.config.*.js", // rollup config
+        "**/gulpfile.js", // gulp config
+        "**/gulpfile.*.js", // gulp config
+        "**/Gruntfile{,.js}", // grunt config
+        "**/protractor.conf.js", // protractor config
+        "**/protractor.conf.*.js", // protractor config
+        "**/karma.conf.js", // karma config
+        "**/.eslintrc.js", // eslint config
+      ],
+      optionalDependencies: false,
+    },
+  ],
+
+  "import/no-mutable-exports": "error",
+  "import/no-named-as-default": "error",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://github.com/iamturns/eslint-config-airbnb-typescript/blob/master/lib/shared.js).
+   */
+  "import/no-named-as-default-member": "off",
+
+  /**
+   * Disabled since this check is better performed by the [`knip`](https://github.com/webpro/knip)
+   * tool.
+   */
+  "import/no-unused-modules": "off",
+};
+
+/** @type {import("eslint").Linter.RulesRecord} */
+const MODULE_SYSTEMS = {
+  "import/no-amd": "error",
+  "import/no-commonjs": "error",
+  "import/no-import-module-exports": "error",
+
+  /** Disabled because it is only used in specific environments (like the browser). */
+  "import/no-nodejs-modules": "off",
+
+  /** Disabled because this is already handled by the TypeScript compiler. */
+  "import/unambiguous": "off",
+};
+
+/** @type {import("eslint").Linter.RulesRecord} */
+const STATIC_ANALYSIS = {
+  "import/default": "error",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://github.com/import-js/eslint-plugin-import/blob/main/config/typescript.js).
+   */
+  "import/named": "off",
+
+  "import/namespace": "error",
+  "import/no-absolute-path": "error",
+  "import/no-cycle": "error",
+  "import/no-dynamic-require": "error",
+
+  /** Disabled since a prescribed import pattern is not generalizable enough across projects. */
+  "import/no-internal-modules": "off",
+
+  "import/no-relative-packages": "error",
+
+  /**
+   * Disabled since a forward import direction pattern is not generalizable enough across projects.
+   */
+  "import/no-relative-parent-imports": "off",
+
+  /** Disabled since this rule should only contain a project-specific path restriction. */
+  "import/no-restricted-paths": "off",
+
+  "import/no-self-import": "error",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://github.com/iamturns/eslint-config-airbnb-typescript/blob/master/lib/shared.js).
+   */
+  "import/no-unresolved": "off",
+
+  "import/no-useless-path-segments": "error",
+  "import/no-webpack-loader-syntax": "error",
+};
+
+/** @type {import("eslint").Linter.RulesRecord} */
+const STYLE_GUIDE = {
+  "import/consistent-type-specifier-style": "error",
+
+  /** Disabled because it is only useful in environments that use webpack. */
+  "import/dynamic-import-chunkname": "off",
+
+  /** Disabled because this style is not generally used. */
+  "import/exports-last": "off",
+
+  /** Disabled because this is already handled by the TypeScript compiler. */
+  "import/extensions": "off",
+
+  "import/first": "error",
+
+  /** Disabled because this style is not generally used. */
+  "import/group-exports": "off",
+
+  /** Disabled because this rule is deprecated. */
+  "import/imports-first": "off",
+
+  /** Disabled since it will trigger false positives in codebases that prefer smaller files. */
+  "import/max-dependencies": "off",
+
+  "import/newline-after-import": "error",
+
+  /**
+   * Disabled since we disallow default exports elsewhere in this config (in favor of named
+   * exports).
+   */
+  "import/no-anonymous-default-export": "off",
+
+  /**
+   * The case against default exports is [layed out by Basarat Ali
+   * Syed](https://basarat.gitbook.io/typescript/main-1/defaultisbad).
+   */
+  "import/no-default-export": "error",
+
+  "import/no-duplicates": "error",
+  "import/no-named-default": "error",
+
+  /**
+   * Disabled since we disallow default exports elsewhere in this config (in favor of named
+   * exports).
+   */
+  "import/no-named-export": "off",
+
+  /**
+   * Disabled since it is too prescriptive for a general audience. (Using `import * as` is common.)
+   */
+  "import/no-namespace": "off",
+
+  "import/no-unassigned-import": "error",
+
+  /** Disabled because this is automatically handled by `prettier-plugin-organize-imports`. */
+  "import/order": "off",
+
+  /**
+   * Disabled because we disallow default exports elsewhere in this config (in favor of named
+   * exports).
+   */
+  "import/prefer-default-export": "off",
+};
+
+/*
+ * @type {import("eslint").Linter.Config}
+ */
+const config = {
+  // No additional configuration is necessary to make the plugin work properly with TypeScript.
+  // (This was tested with the `import/no-default-export` rule.)
+  plugins: ["import"],
+
+  rules: {
+    ...HELPFUL_WARNINGS,
+    ...MODULE_SYSTEMS,
+    ...STATIC_ANALYSIS,
+    ...STYLE_GUIDE,
+  },
+
+  overrides: [
+    // Disable some TypeScript-specific rules in JavaScript files.
+    {
+      files: ["*.js", "*.cjs", "*.mjs", "*.jsx"],
+      rules: {
+        "import/no-commonjs": "off",
+      },
+    },
+
+    // Disable some specific rules in config files.
+    {
+      files: [".remarkrc.mjs", "prettier.config.mjs"],
+      rules: {
+        "import/no-default-export": "off",
+      },
+    },
+  ],
+};
+
+module.exports = config;

package/base-jsdoc.js

@@ -1,51 +1,44 @@
-// This is a shared configuration file for ESLint:
-// https://eslint.org/docs/latest/user-guide/configuring
-// This config contains only rules from the "jsdoc" ESLint plugin.
-module.exports = {
-  plugins: [
-    /**
-     * Lint JSDoc style comments:
-     * https://github.com/gajus/eslint-plugin-jsdoc
-     */
-    "jsdoc",
-  ],
+/**
+ * This ESLint config only contains rules from `eslint-plugin-jsdoc`:
+ * https://github.com/gajus/eslint-plugin-jsdoc
+ *
+ * @type {import("eslint").Linter.Config}
+ */
+const config = {
+  plugins: ["jsdoc"],
 
-  /**
-   * Instead of using the recommended config, we specifically turn on every rule that is useful.
-   *
-   * We must specify `contexts: ["any"]` for some rules because by default, only a subset of AST
-   * node types will be affected.
-   */
   rules: {
-    // - jsdoc/check-access - Not needed in TypeScript.
-    // - jsdoc/check-alignment - Overlaps with `isaacscript/limit-jsdoc-comments`.
-
-    // - jsdoc/check-examples - Does not work with ESLint 8; see:
-    // https://github.com/eslint/eslint/issues/14745
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/check-access": "off",
 
-    // - jsdoc/check-indentation - Overlaps with `isaacscript/limit-jsdoc-comments`.
-    // - jsdoc/check-line-alignment - This is not a common formatting scheme in the wild. It's also
-    //   not recommended by the plugin.
+    /** Superseded by the `isaacscript/limit-jsdoc-comments` rule. */
+    "jsdoc/check-alignment": "off",
 
     /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#check-param-names
-     *
-     * Ensures that parameter names in JSDoc match those in the function declaration.
+     * Disabled since it [does not work with ESLint
+     * 8](https://github.com/eslint/eslint/issues/14745).
      */
-    "jsdoc/check-param-names": "warn",
+    "jsdoc/check-examples": "off",
 
-    // - jsdoc/check-property-names - Not needed in TypeScript.
-    // - jsdoc/check-syntax - Not needed in TypeScript.
+    /** Superseded by the `isaacscript/limit-jsdoc-comments` rule. */
+    "jsdoc/check-indentation": "off",
 
     /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#check-tag-names
-     *
-     * Reports invalid block tag names.
+     * Disabled since this is not a common formatting scheme. It is also not recommended by the
+     * plugin authors.
      */
+    "jsdoc/check-line-alignment": "off",
+
+    "jsdoc/check-param-names": "error",
+
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/check-property-names": "off",
+
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/check-syntax": "off",
+
     "jsdoc/check-tag-names": [
-      "warn",
+      "error",
       {
         definedTags: [
           // Ignore tags used by the TypeScript compiler:
@@ -77,115 +70,110 @@ module.exports = {
       },
     ],
 
-    // - jsdoc/check-types - Not needed in TypeScript.
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/check-types": "off",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#check-values
-     *
-     * Validates the content of some uncommon JSDoc tags.
-     */
-    "jsdoc/check-values": "warn",
+    "jsdoc/check-values": "error",
+    "jsdoc/empty-tags": "error",
+    "jsdoc/implements-on-classes": "error",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#check-values
-     *
-     * Validates that specific tags are never empty.
-     */
-    "jsdoc/empty-tags": "warn",
+    /** Disabled since you cannot configure it with a path to the correct "package.json" file. */
+    "jsdoc/imports-as-dependencies": "off",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#implements-on-classes
-     *
-     * Reports issues with incorrect usage of `@implements`.
-     */
-    "jsdoc/implements-on-classes": "warn",
-
-    // - jsdoc/match-description - Overlaps with `isaacscript/jsdoc-full-sentences`.
-    // - jsdoc/match-name - Only needed for projects with specific JSDoc requirements.
-    // - jsdoc/multiline-blocks - Overlaps with `isaacscript/limit-jsdoc-comments`.
-    // - jsdoc/newline-after-description - Overlaps with `isaacscript/limit-jsdoc-comments`.
-    // - jsdoc/no-bad-blocks - Provides little value, since it only detects JSDoc comments with tags
-    //   in them.
-    // - jsdoc/no-defaults - Provides little value, since the @default tag is rare.
-    // - jsdoc/no-missing-syntax - Not generally relevant.
-    // - jsdoc/no-multi-asterisks - Overlaps with `isaacscript/limit-jsdoc-comments`.
-    // - jsdoc/no-restricted-syntax - Not generally relevant.
+    "jsdoc/informative-docs": "error",
+
+    /** Superseded by the `isaacscript/jsdoc-full-sentences` rule. */
+    "jsdoc/match-description": "off",
+
+    /** Disabled because it is only needed for projects with specific JSDoc requirements. */
+    "jsdoc/match-name": "off",
+
+    /** Superseded by the `isaacscript/limit-jsdoc-comments` rule. */
+    "jsdoc/multiline-blocks": "off",
+
+    /** Superseded by the `isaacscript/limit-jsdoc-comments` rule. */
+    "jsdoc/newline-after-description": "off",
 
     /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#no-types
-     *
-     * Disallows types being used on `@param` or `@returns`.
+     * Disabled because it provides little value; it only detects JSDoc comments with tags in them.
      */
+    "jsdoc/no-bad-blocks": "off",
+
+    /** Superseded by the `isaacscript/format-jsdoc-comments` rule. */
+    "jsdoc/no-blank-block-descriptions": "off",
+
+    /** Superseded by the `isaacscript/no-empty-jsdoc` rule. */
+    "jsdoc/no-blank-blocks": "off",
+
+    /** Disabled because it provides little value; the `@default` tag is rare. */
+    "jsdoc/no-defaults": "off",
+
+    /** Disabled because it is too project-specific. */
+    "jsdoc/no-missing-syntax": "off",
+
+    /** Superseded by the `isaacscript/limit-jsdoc-comments` rule. */
+    "jsdoc/no-multi-asterisks": "off",
+
+    /** Disabled because it is intended for disabling of specific language features per-project. */
+    "jsdoc/no-restricted-syntax": "off",
+
+    /** The `contexts` option is set to `any` to make the rule stricter. */
     "jsdoc/no-types": [
-      "warn",
+      "error",
       {
         contexts: ["any"],
       },
     ],
 
-    // - jsdoc/no-undefined-types - Not needed in TypeScript.
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/no-undefined-types": "off",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-asterisk-prefix
-     *
-     * Requires that each JSDoc line starts with an `*`.
-     */
-    "jsdoc/require-asterisk-prefix": "warn",
+    "jsdoc/require-asterisk-prefix": "error",
 
-    // - jsdoc/require-description-complete-sentence - Overlaps with
-    //   `isaacscript/jsdoc-complete-sentences`.
-    // - jsdoc/require-description - It's overboard for every function to have a description.
-    // - jsdoc/require-example - It's overboard for every function to require an example.
-    // - jsdoc/require-file-overview - It's overboard for every file to require an overview.
+    /** Superseded by the `isaacscript/jsdoc-complete-sentences` rule. */
+    "jsdoc/require-description-complete-sentence": "off",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-hyphen-before-param-description
-     *
-     * Disallow hyphens before parameter descriptions, as it is non-standard syntax.
-     */
-    "jsdoc/require-hyphen-before-param-description": ["warn", "never"],
+    /** Disabled because it is overboard for every function to have a description. */
+    "jsdoc/require-description": "off",
+
+    /** Disabled because it is overboard for every function to require an example. */
+    "jsdoc/require-example": "off",
 
-    // - jsdoc/require-jsdoc - It's overboard for every function to have a JSDoc comment.
+    /** Disabled because it is overboard for every file to require an overview. */
+    "jsdoc/require-file-overview": "off",
 
     /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-param-description
-     *
-     * Requires that each `@param` tag has a description.
+     * The `never` option is provided to make the rule match the format of the official TypeScript
+     * codebase.
      */
+    "jsdoc/require-hyphen-before-param-description": ["error", "never"],
+
+    /** Disabled since it is overboard for every function to have a JSDoc comment. */
+    "jsdoc/require-jsdoc": "off",
+
+    /** The `contexts` option is set to `any` to make the rule stricter. */
     "jsdoc/require-param-description": [
-      "warn",
+      "error",
       {
         contexts: ["any"],
       },
     ],
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-param-name
-     *
-     * Requires that each `@param` tag has a name.
-     */
+    /** The `contexts` option is set to `any` to make the rule stricter. */
     "jsdoc/require-param-name": [
-      "warn",
+      "error",
       {
         contexts: ["any"],
       },
     ],
 
-    // - jsdoc/require-param-type - Not needed in TypeScript.
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/require-param-type": "off",
 
+    /** Configured to only apply when there are one or more parameters. */
     "jsdoc/require-param": [
-      "warn",
+      "error",
       {
-        // We only activate the rule when there are one or more parameters.
-        // https://github.com/gajus/eslint-plugin-jsdoc/issues/920
         contexts: [
           {
             context: "FunctionDeclaration",
@@ -195,58 +183,58 @@ module.exports = {
       },
     ],
 
-    // - jsdoc/require-property - Probably not needed in TypeScript.
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/require-property": "off",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-property-description
-     *
-     * Requires that each `@property` tag has a description.
-     */
-    "jsdoc/require-property-description": "warn",
+    "jsdoc/require-property-description": "error",
+    "jsdoc/require-property-name": "error",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-property-name
-     *
-     * Requires that each `@property` tag has a name.
-     */
-    "jsdoc/require-property-name": "warn",
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/require-property-type": "off",
 
-    // - jsdoc/require-property-type - Not needed in TypeScript.
-    // - jsdoc/require-returns-check - It's overboard for every function to document every return
-    //   value.
+    /** Disabled because it is overboard for every function to document every return value. */
+    "jsdoc/require-returns-check": "off",
 
-    /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#require-returns-description
-     *
-     * Requires that each `@returns` tag has a description.
-     */
+    /** The `contexts` option is set to `any` to make the rule stricter. */
     "jsdoc/require-returns-description": [
-      "warn",
+      "error",
       {
         contexts: ["any"],
       },
     ],
 
-    // - jsdoc/require-returns-type - Not needed in TypeScript.
-    // - jsdoc/require-returns - It's overboard for every function to document every return value.
-    // - jsdoc/require-throws - It's overboard to document every throw statement.
-    // - jsdoc/require-yields - It's overboard to document every yield.
-    // - jsdoc/require-yields-check - It's overboard to document every yield.
-    // - jsdoc/sort-tags - Not very useful since there are typically only `@param` and `@return`
-    //   tags.
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/require-returns-type": "off",
+
+    /** Disabled because it is overboard for every function to document every return value. */
+    "jsdoc/require-returns": "off",
+
+    /** Disabled because it is overboard to document every throw statement. */
+    "jsdoc/require-throws": "off",
+
+    /** Disabled because it is overboard to document every yield. */
+    "jsdoc/require-yields": "off",
+
+    /** Disabled because it is overboard to document every yield. */
+    "jsdoc/require-yields-check": "off",
+
+    /**
+     * Disabled because it is not very useful. In most cases, a function will only have `@param` and
+     * `@return` tags, making sorting unnecessary.
+     */
+    "jsdoc/sort-tags": "off",
+
+    /** Superseded by the `isaacscript/format-jsdoc-comments` rule. */
+    "jsdoc/tag-lines": "off",
 
     /**
-     * Documentation:
-     * https://github.com/gajus/eslint-plugin-jsdoc#tag-lines
-     *
-     * Enforces no lines between tags.
+     * Disabled since it is only useful in certain environments (e.g. when your project converts
+     * JSDoc comments to Markdown).
      */
-    "jsdoc/tag-lines": "warn",
+    "jsdoc/text-escaping": "off",
 
-    // - jsdoc/valid-types - Not needed in TypeScript.
+    /** Disabled because it is not needed in TypeScript. */
+    "jsdoc/valid-types": "off",
   },
 
   overrides: [
@@ -259,3 +247,5 @@ module.exports = {
     },
   ],
 };
+
+module.exports = config;