eslint-config-complete 1.0.0

package/configs/base-import-x.js

@@ -0,0 +1,298 @@
+import ESLintPluginImportX from "eslint-plugin-import-x";
+import tseslint from "typescript-eslint";
+
+/** @type {Record<string, import("@typescript-eslint/utils").TSESLint.SharedConfig.RuleEntry>} */
+const HELPFUL_WARNINGS = {
+  "import-x/export": "warn",
+
+  /**
+   * Superseded by the `deprecation/deprecation` rule. (That rule is better because it catches
+   * deprecated usage that does not come from import statements specifically.)
+   */
+  "import-x/no-deprecated": "off",
+
+  "import-x/no-empty-named-blocks": "warn",
+
+  /**
+   * The options are [copied from
+   * Airbnb](https://github.com/airbnb/javascript/blob/master/packages/eslint-config-airbnb-base/rules/import.js).
+   *
+   * We also add a "scripts" directory entry for "devDependencies".
+   */
+  "import-x/no-extraneous-dependencies": [
+    "warn",
+    {
+      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
+
+        "**/scripts/*.{js,cjs,mjs,ts,cts,mts}", // Files inside of a "scripts" directory.
+      ],
+      optionalDependencies: false,
+    },
+  ],
+
+  "import-x/no-mutable-exports": "warn",
+  "import-x/no-named-as-default": "warn",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://typescript-eslint.io/linting/troubleshooting/performance-troubleshooting/#eslint-plugin-import).
+   */
+  "import-x/no-named-as-default-member": "off",
+
+  /**
+   * Disabled since this check is better performed by the [`knip`](https://github.com/webpro/knip)
+   * tool.
+   */
+  "import-x/no-unused-modules": "off",
+};
+
+/** @type {Record<string, import("@typescript-eslint/utils").TSESLint.SharedConfig.RuleEntry>} */
+const MODULE_SYSTEMS = {
+  "import-x/no-amd": "warn",
+  "import-x/no-commonjs": "warn",
+  "import-x/no-import-module-exports": "warn",
+
+  /** Disabled because it is only used in specific environments (like the browser). */
+  "import-x/no-nodejs-modules": "off",
+
+  /** Disabled because this is already handled by the TypeScript compiler. */
+  "import-x/unambiguous": "off",
+};
+
+/** @type {Record<string, import("@typescript-eslint/utils").TSESLint.SharedConfig.RuleEntry>} */
+const STATIC_ANALYSIS = {
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://typescript-eslint.io/linting/troubleshooting/performance-troubleshooting/#eslint-plugin-import).
+   */
+  "import-x/default": "off",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://typescript-eslint.io/linting/troubleshooting/performance-troubleshooting/#eslint-plugin-import).
+   */
+  "import-x/named": "off",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://typescript-eslint.io/linting/troubleshooting/performance-troubleshooting/#eslint-plugin-import).
+   */
+  "import-x/namespace": "off",
+
+  "import-x/no-absolute-path": "warn",
+  "import-x/no-cycle": "warn",
+  "import-x/no-dynamic-require": "warn",
+
+  /** Disabled since a prescribed import pattern is not generalizable enough across projects. */
+  "import-x/no-internal-modules": "off",
+
+  "import-x/no-relative-packages": "warn",
+
+  /**
+   * Disabled since a forward import direction pattern is not generalizable enough across projects.
+   */
+  "import-x/no-relative-parent-imports": "off",
+
+  /** Disabled since this rule should only contain a project-specific path restriction. */
+  "import-x/no-restricted-paths": "off",
+
+  "import-x/no-self-import": "warn",
+
+  /**
+   * Disabled because this is [already handled by the TypeScript
+   * compiler](https://github.com/iamturns/eslint-config-airbnb-typescript/blob/master/lib/shared.js).
+   */
+  "import-x/no-unresolved": "off",
+
+  "import-x/no-useless-path-segments": "warn",
+  "import-x/no-webpack-loader-syntax": "warn",
+};
+
+/** @type {Record<string, import("@typescript-eslint/utils").TSESLint.SharedConfig.RuleEntry>} */
+const STYLE_GUIDE = {
+  "import-x/consistent-type-specifier-style": "warn",
+
+  /** Disabled because it is only useful in environments that use webpack. */
+  "import-x/dynamic-import-chunkname": "off",
+
+  /** Disabled because this style is not generally used. */
+  "import-x/exports-last": "off",
+
+  /** Disabled because this is already handled by the TypeScript compiler. */
+  "import-x/extensions": "off",
+
+  "import-x/first": "warn",
+
+  /** Disabled because this style is not generally used. */
+  "import-x/group-exports": "off",
+
+  /** Disabled because this rule is deprecated. */
+  "import-x/imports-first": "off",
+
+  /** Disabled since it will trigger false positives in codebases that prefer smaller files. */
+  "import-x/max-dependencies": "off",
+
+  "import-x/newline-after-import": "warn",
+
+  /**
+   * Disabled since we disallow default exports elsewhere in this config (in favor of named
+   * exports).
+   */
+  "import-x/no-anonymous-default-export": "off",
+
+  /**
+   * The case against default exports is [laid out by Basarat Ali
+   * Syed](https://basarat.gitbook.io/typescript/main-1/defaultisbad).
+   */
+  "import-x/no-default-export": "warn",
+
+  "import-x/no-duplicates": "warn",
+  "import-x/no-named-default": "warn",
+
+  /**
+   * Disabled since we disallow default exports elsewhere in this config (in favor of named
+   * exports).
+   */
+  "import-x/no-named-export": "off",
+
+  /**
+   * Disabled since it is too prescriptive for a general audience. (Using `import * as` is common.)
+   */
+  "import-x/no-namespace": "off",
+
+  "import-x/no-unassigned-import": "warn",
+
+  /** Disabled because this is automatically handled by `prettier-plugin-organize-imports`. */
+  "import-x/order": "off",
+
+  /**
+   * Disabled because we disallow default exports elsewhere in this config (in favor of named
+   * exports).
+   */
+  "import-x/prefer-default-export": "off",
+};
+
+/**
+ * Omit `.d.ts` because:
+ * 1. TypeScript compilation already confirms that types are resolved.
+ * 2. It would mask an unresolved `.ts`/`.tsx`/`.js`/`.jsx` implementation.
+ */
+const TYPESCRIPT_EXTENSIONS = [".ts", ".cts", ".mts", ".tsx"];
+
+const ALL_EXTENSIONS = [
+  ...TYPESCRIPT_EXTENSIONS,
+  ".js",
+  ".cjs",
+  ".mjs",
+  ".jsx",
+];
+
+/**
+ * This ESLint config only contains rules from `eslint-plugin-import-x`:
+ * https://github.com/un-ts/eslint-plugin-import-x
+ *
+ * Rules are separated into categories:
+ * 1) Helpful warnings
+ * 2) Module systems
+ * 3) Static analysis
+ * 4) Style guide
+ */
+export const baseImportX = tseslint.config(
+  {
+    plugins: {
+      "import-x": ESLintPluginImportX,
+    },
+
+    // Beyond just specifying the plugin, additional configuration is necessary to make the plugin
+    // work properly with TypeScript:
+
+    // - First, the "eslint-import-resolver-typescript" package needs to be installed, or else an
+    //   error will appear: "Resolve error: typescript with invalid interface loaded as resolver"
+    // - However, it is discussed in this issue to include that dep as part of
+    //   "eslint-plugin-import-x" itself:
+    // https://github.com/un-ts/eslint-plugin-import-x/issues/150
+    // - Second, we extend the upstream TypeScript configuration:
+    // https://github.com/un-ts/eslint-plugin-import-x/blob/master/src/config/typescript.ts
+    // - Third, we need to specify "typescript: true" under the resolver, as documented here:
+    // https://github.com/un-ts/eslint-plugin-import-x/issues/29
+    // (Otherwise, the "no-cycle" rule will not work.)
+    settings: {
+      "import-x/extensions": ALL_EXTENSIONS,
+      "import-x/external-module-folders": [
+        "node_modules",
+        "node_modules/@types",
+      ],
+      "import-x/parsers": {
+        "@typescript-eslint/parser": TYPESCRIPT_EXTENSIONS,
+      },
+      "import-x/resolver": {
+        typescript: true,
+        node: {
+          extensions: ALL_EXTENSIONS,
+        },
+      },
+    },
+
+    rules: {
+      ...HELPFUL_WARNINGS,
+      ...MODULE_SYSTEMS,
+      ...STATIC_ANALYSIS,
+      ...STYLE_GUIDE,
+    },
+  },
+
+  // Disable some TypeScript-specific rules in JavaScript files.
+  {
+    files: ["**/*.js", "**/*.cjs", "**/*.mjs", "**/*.jsx"],
+    rules: {
+      "import-x/no-commonjs": "off",
+    },
+  },
+
+  // Some configuration files must export a default object as a design limitation.
+  {
+    files: [
+      ".remarkrc.js",
+      ".remarkrc.mjs",
+      "eslint.config.js",
+      "eslint.config.mjs",
+      "jest.config.js",
+      "jest.config.mjs",
+      "knip.js",
+      "knip.ts",
+      "knip.config.js",
+      "knip.config.ts",
+      "prettier.config.js",
+      "prettier.config.mjs",
+      "typedoc.config.js",
+      "typedoc.config.mjs",
+      "vite.config.js",
+      "vite.config.mjs",
+    ],
+    rules: {
+      "import-x/no-default-export": "off",
+    },
+  },
+);

package/configs/base-jsdoc.js

@@ -0,0 +1,276 @@
+import ESLintPluginJSDoc from "eslint-plugin-jsdoc";
+import tseslint from "typescript-eslint";
+
+/**
+ * This ESLint config only contains rules from `eslint-plugin-jsdoc`:
+ * https://github.com/gajus/eslint-plugin-jsdoc
+ */
+export const baseJSDoc = tseslint.config(
+  {
+    plugins: {
+      jsdoc: ESLintPluginJSDoc,
+    },
+
+    rules: {
+      /** Disabled because it is not needed in TypeScript. */
+      "jsdoc/check-access": "off",
+
+      /** Superseded by the `complete/limit-jsdoc-comments` rule. */
+      "jsdoc/check-alignment": "off",
+
+      /**
+       * Disabled since it [does not work with ESLint
+       * 8](https://github.com/eslint/eslint/issues/14745).
+       */
+      "jsdoc/check-examples": "off",
+
+      /** Superseded by the `complete/limit-jsdoc-comments` rule. */
+      "jsdoc/check-indentation": "off",
+
+      /**
+       * 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": "warn",
+
+      /** 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",
+        {
+          definedTags: [
+            // Ignore tags used by the TypeScript compiler:
+            // https://www.typescriptlang.org/tsconfig#stripInternal
+            "internal", // Used by TypeScript
+
+            // Ignore tags used in TypeDoc:
+            // https://typedoc.org/guides/doccomments/
+            "category",
+            "hidden",
+            "notExported", // From: typedoc-plugin-not-exported
+            "rename", // From: typedoc-plugin-rename
+
+            // Ignore tags used in TypeScriptToLua:
+            // https://typescripttolua.github.io/docs/advanced/compiler-annotations
+            "customName",
+            "noResolution",
+            "noSelf",
+            "noSelfInFile",
+
+            // Ignore tags used in `ts-json-schema-generator`:
+            // https://github.com/vega/ts-json-schema-generator
+            "minimum",
+            "maximum",
+
+            // Ignore tags used in `eslint-plugin-complete`:
+            // https://github.com/complete-ts/complete/blob/main/packages/eslint-plugin-complete/docs/rules/require-variadic-function-argument.md
+            "allowEmptyVariadic",
+          ],
+        },
+      ],
+
+      "jsdoc/check-template-names": "warn",
+
+      /** Disabled because it is not needed in TypeScript. */
+      "jsdoc/check-types": "off",
+
+      "jsdoc/check-values": "warn",
+
+      /**
+       * Disabled since it is idiomatic in the TypeScript ecosystem to use a mixture of both JSDoc
+       * and non-JSDoc comments.
+       */
+      "jsdoc/convert-to-jsdoc-comments": "off",
+
+      "jsdoc/empty-tags": "warn",
+      "jsdoc/implements-on-classes": "warn",
+
+      /** Disabled since you cannot configure it with a path to the correct "package.json" file. */
+      "jsdoc/imports-as-dependencies": "off",
+
+      "jsdoc/informative-docs": "warn",
+
+      /**
+       * Disabled since it is [currently
+       * bugged](https://github.com/gajus/eslint-plugin-jsdoc/issues/1296).
+       */
+      "jsdoc/lines-before-block": "off",
+
+      /** Superseded by the `complete/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 `complete/limit-jsdoc-comments` rule. */
+      "jsdoc/multiline-blocks": "off",
+
+      /** Superseded by the `complete/limit-jsdoc-comments` rule. */
+      "jsdoc/newline-after-description": "off",
+
+      /**
+       * Disabled because it provides little value; it only detects JSDoc comments with tags in
+       * them.
+       */
+      "jsdoc/no-bad-blocks": "off",
+
+      /** Superseded by the `complete/format-jsdoc-comments` rule. */
+      "jsdoc/no-blank-block-descriptions": "off",
+
+      /** Superseded by the `complete/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 `complete/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",
+        {
+          contexts: ["any"],
+        },
+      ],
+
+      /** Disabled because it is not needed in TypeScript. */
+      "jsdoc/no-undefined-types": "off",
+
+      "jsdoc/require-asterisk-prefix": "warn",
+
+      /** Superseded by the `complete/jsdoc-complete-sentences` rule. */
+      "jsdoc/require-description-complete-sentence": "off",
+
+      /** 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",
+
+      /** Disabled because it is overboard for every file to require an overview. */
+      "jsdoc/require-file-overview": "off",
+
+      /**
+       * The `never` option is provided to make the rule match the format of the official TypeScript
+       * codebase.
+       */
+      "jsdoc/require-hyphen-before-param-description": ["warn", "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",
+        {
+          contexts: ["any"],
+        },
+      ],
+
+      /** The `contexts` option is set to `any` to make the rule stricter. */
+      "jsdoc/require-param-name": [
+        "warn",
+        {
+          contexts: ["any"],
+        },
+      ],
+
+      /** 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",
+        {
+          contexts: [
+            {
+              context: "FunctionDeclaration",
+              comment: 'JsdocBlock:has(JsdocTag[tag="param"])',
+            },
+          ],
+        },
+      ],
+
+      /** Disabled because it is not needed in TypeScript. */
+      "jsdoc/require-property": "off",
+
+      "jsdoc/require-property-description": "warn",
+      "jsdoc/require-property-name": "warn",
+
+      /** Disabled because it is not needed in TypeScript. */
+      "jsdoc/require-property-type": "off",
+
+      /** Disabled because it is overboard for every function to document every return value. */
+      "jsdoc/require-returns-check": "off",
+
+      /** The `contexts` option is set to `any` to make the rule stricter. */
+      "jsdoc/require-returns-description": [
+        "warn",
+        {
+          contexts: ["any"],
+        },
+      ],
+
+      /** 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 generic type variable. */
+      "jsdoc/require-template": "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 `complete/format-jsdoc-comments` rule. */
+      "jsdoc/tag-lines": "off",
+
+      /**
+       * Disabled since it is only useful in certain environments (e.g. when your project converts
+       * JSDoc comments to Markdown).
+       */
+      "jsdoc/text-escaping": "off",
+
+      /** Disabled because it is not needed in TypeScript. */
+      "jsdoc/valid-types": "off",
+    },
+  },
+
+  // Disable some TypeScript-specific rules in JavaScript files.
+  {
+    files: ["**/*.js", "**/*.cjs", "**/*.mjs", "**/*.jsx"],
+    rules: {
+      "jsdoc/no-types": "off",
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns-description": "off",
+    },
+  },
+);