exadev-eslint-config 2.10.6 → 2.12.0

package/README.md

@@ -16,7 +16,7 @@ Consumers need `eslint >=10.0.0` and `typescript-eslint >=8.0.0` as required pee
 pnpm add -D @exadev/eslint-config typescript-eslint eslint
 ```
 
-The default export is the full, type-checked ruleset: typescript-eslint's `strictTypeChecked` + `stylisticTypeChecked` presets (`strictTypeChecked` subsumes `recommendedTypeChecked`, so it already includes `no-deprecated`, `no-misused-spread`, `no-mixed-enums`, `no-unnecessary-condition`, `use-unknown-in-catch-callback-variable`, `return-await`, `related-getter-setter-pairs`, `no-unnecessary-type-parameters`, and more -- those are no longer re-listed below), `exadev/barrel-policy` at `mode: 'banned'` (see [Barrel policy](#barrel-policy)), `exadev/no-object-assign`, `exadev/no-mutable-union-array-param`, `exadev/no-array-isarray-mutation`, `exadev/no-enum-number-widening`, `exadev/no-enum-reverse-lookup-widening`, `exadev/no-map-instanceof-mutation`, `exadev/no-set-instanceof-mutation`, `exadev/prefer-readonly-array-param`, `exadev/prefer-readonly-object-param`, `exadev/prefer-numeric-sort-compare`, `exadev/no-pointless-reassignment`, `linterOptions.noInlineConfig`, `@typescript-eslint/consistent-type-assertions` banning all type assertions, `@typescript-eslint/consistent-type-imports`, `@typescript-eslint/consistent-type-exports`, `@typescript-eslint/consistent-return` (a function that implicitly returns `undefined` on one path and a real value on another -- a common real bug, not a deliberate design), `@typescript-eslint/no-non-null-assertion` banning the `!` operator (the same manual-override escape hatch as a type assertion, under a different spelling), `@typescript-eslint/no-redeclare`, `@typescript-eslint/no-shadow`, `@typescript-eslint/no-use-before-define` set to `{ functions: false }` (a genuine temporal-dead-zone crash risk for `let`/`const`/`class`/enum bindings, but exempting function declarations, which are fully hoisted and therefore runtime-safe to call before their point of textual declaration -- this codebase's own rule files consistently define their helper functions after the logic that calls them), `@typescript-eslint/ban-ts-comment` banning `@ts-expect-error` outright, `@typescript-eslint/method-signature-style` set to `'property'` (method-shorthand signatures are checked bivariantly under `strictFunctionTypes`, which is unsound), `@typescript-eslint/prefer-readonly`, `@typescript-eslint/promise-function-async`, `@typescript-eslint/require-array-sort-compare`, `@typescript-eslint/strict-void-return` (not yet in any typescript-eslint preset -- disallows passing a value-returning function where a void-returning one is expected, e.g. `arr.forEach(x => otherArray.push(x))`, which typechecks today under TS's own void-return contravariance leniency), `@typescript-eslint/switch-exhaustiveness-check`, `@typescript-eslint/strict-boolean-expressions` at the rule's own bare defaults (an unambiguous non-nullable truthy check stays allowed; an ambiguous nullable check does not), and `@typescript-eslint/no-magic-numbers` tuned to exempt array indexes, enum members, readonly class properties, default parameter values, and the handful of universally-idiomatic bare numbers (`-1`, `0`, `1`, `2`) -- the type-assertion and ts-comment rules are relaxed in test files, and `no-magic-numbers` is not (see below). Spread it directly into `tseslint.config(...)`:
+The default export is the full, type-checked ruleset: typescript-eslint's `strictTypeChecked` + `stylisticTypeChecked` presets (`strictTypeChecked` subsumes `recommendedTypeChecked`, so it already includes `no-deprecated`, `no-misused-spread`, `no-mixed-enums`, `no-unnecessary-condition`, `use-unknown-in-catch-callback-variable`, `return-await`, `related-getter-setter-pairs`, `no-unnecessary-type-parameters`, and more -- those are no longer re-listed below), `exadev/barrel-policy` at `mode: 'banned'` (see [Barrel policy](#barrel-policy)), `exadev/no-object-assign`, `exadev/no-mutable-union-array-param`, `exadev/no-array-isarray-mutation`, `exadev/no-enum-number-widening`, `exadev/no-enum-reverse-lookup-widening`, `exadev/no-map-instanceof-mutation`, `exadev/no-set-instanceof-mutation`, `exadev/prefer-readonly-array-param`, `exadev/prefer-readonly-object-param`, `exadev/prefer-numeric-sort-compare`, `exadev/no-pointless-reassignment`, `linterOptions.noInlineConfig`, `@typescript-eslint/consistent-type-assertions` banning all type assertions, `@typescript-eslint/consistent-type-imports`, `@typescript-eslint/consistent-type-exports`, `@typescript-eslint/consistent-return` (a function that implicitly returns `undefined` on one path and a real value on another -- a common real bug, not a deliberate design), `@typescript-eslint/no-non-null-assertion` banning the `!` operator (the same manual-override escape hatch as a type assertion, under a different spelling), `@typescript-eslint/no-redeclare`, `@typescript-eslint/no-shadow`, `@typescript-eslint/no-use-before-define` set to `{ functions: false }` (a genuine temporal-dead-zone crash risk for `let`/`const`/`class`/enum bindings, but exempting function declarations, which are fully hoisted and therefore runtime-safe to call before their point of textual declaration -- this codebase's own rule files consistently define their helper functions after the logic that calls them), `@typescript-eslint/ban-ts-comment` banning `@ts-expect-error` outright, `@typescript-eslint/method-signature-style` set to `'property'` (method-shorthand signatures are checked bivariantly under `strictFunctionTypes`, which is unsound), `@typescript-eslint/prefer-readonly`, `@typescript-eslint/promise-function-async`, `@typescript-eslint/require-array-sort-compare`, `@typescript-eslint/strict-void-return` (not yet in any typescript-eslint preset -- disallows passing a value-returning function where a void-returning one is expected, e.g. `arr.forEach(x => otherArray.push(x))`, which typechecks today under TS's own void-return contravariance leniency), `@typescript-eslint/switch-exhaustiveness-check`, `@typescript-eslint/strict-boolean-expressions` at the rule's own bare defaults (an unambiguous non-nullable truthy check stays allowed; an ambiguous nullable check does not), `@typescript-eslint/no-magic-numbers` tuned to exempt array indexes, enum members, readonly class properties, default parameter values, and the handful of universally-idiomatic bare numbers (`-1`, `0`, `1`, `2`), `max-lines` set to `{ max: 800, skipBlankLines: true, skipComments: true }` (counting only real code, so a file isn't pushed over the limit by whitespace or its own WHY-explanation comments), and `no-warning-comments` banning any comment containing `Stryker disable` (Stryker's own mutation-testing suppression directive, invisible to ESLint's `noInlineConfig` above since it isn't an eslint-disable comment at all) -- the type-assertion and ts-comment rules are relaxed in test files, and `no-magic-numbers`/`max-lines`/`no-warning-comments` are not (see below). Spread it directly into `tseslint.config(...)`:
 
 ```ts
 // eslint.config.ts

package/dist/index.cjs

@@ -24,6 +24,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+let eslint_plugin_jsdoc = require("eslint-plugin-jsdoc");
+eslint_plugin_jsdoc = __toESM(eslint_plugin_jsdoc, 1);
+let eslint_plugin_tsdoc = require("eslint-plugin-tsdoc");
+eslint_plugin_tsdoc = __toESM(eslint_plugin_tsdoc, 1);
 let node_module = require("node:module");
 let _eslint_js = require("@eslint/js");
 _eslint_js = __toESM(_eslint_js, 1);
@@ -34,6 +38,39 @@ let _typescript_eslint_utils = require("@typescript-eslint/utils");
 let typescript = require("typescript");
 typescript = __toESM(typescript, 1);
 let ts_api_utils = require("ts-api-utils");
+//#region src/jsdoc.ts
+const jsdocConfig = eslint_plugin_jsdoc.default.configs["flat/recommended-tsdoc-error"];
+const REQUIREMENTS_TIER_RULES = [
+	"jsdoc/require-example",
+	"jsdoc/require-jsdoc",
+	"jsdoc/require-next-type",
+	"jsdoc/require-param",
+	"jsdoc/require-param-description",
+	"jsdoc/require-param-name",
+	"jsdoc/require-param-type",
+	"jsdoc/require-property",
+	"jsdoc/require-property-description",
+	"jsdoc/require-property-name",
+	"jsdoc/require-property-type",
+	"jsdoc/require-returns",
+	"jsdoc/require-returns-description",
+	"jsdoc/require-returns-type",
+	"jsdoc/require-template",
+	"jsdoc/require-throws-type",
+	"jsdoc/require-yields",
+	"jsdoc/require-yields-type"
+];
+const jsdocAndTsdoc = [{
+	...jsdocConfig,
+	rules: {
+		...jsdocConfig.rules,
+		...Object.fromEntries(REQUIREMENTS_TIER_RULES.map((rule) => [rule, "off"]))
+	}
+}, {
+	plugins: { tsdoc: eslint_plugin_tsdoc.default },
+	rules: { "tsdoc/syntax": "error" }
+}];
+//#endregion
 //#region src/optional-plugin.ts
 const nodeRequire = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 function tryRequire(specifier, requireFn = nodeRequire) {
@@ -119,7 +156,7 @@ function buildReactConfig(options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "2.10.6";
+var version = "2.12.0";
 //#endregion
 //#region src/rules/barrel-helpers.ts
 const INDEX_BASENAME$1 = /^index\.[cm]?[tj]sx?$/;
@@ -1409,7 +1446,16 @@ const recommendedTypeChecked = [
 			"@typescript-eslint/require-array-sort-compare": "error",
 			"@typescript-eslint/strict-boolean-expressions": "error",
 			"@typescript-eslint/strict-void-return": "error",
-			"@typescript-eslint/switch-exhaustiveness-check": "error"
+			"@typescript-eslint/switch-exhaustiveness-check": "error",
+			"max-lines": ["error", {
+				max: 800,
+				skipBlankLines: true,
+				skipComments: true
+			}],
+			"no-warning-comments": ["error", {
+				terms: ["stryker disable"],
+				location: "anywhere"
+			}]
 		}
 	},
 	{
@@ -1430,6 +1476,7 @@ function toPublicConfigArray(built) {
 function exadevConfig(options = {}, ...userConfigs) {
 	return toPublicConfigArray([
 		...recommendedTypeChecked,
+		...jsdocAndTsdoc,
 		...buildReactConfig({ enabled: options.react }),
 		...buildNextjsConfig({ enabled: options.nextjs }),
 		...userConfigs

package/dist/index.js

@@ -1,3 +1,5 @@
+import jsdoc from "eslint-plugin-jsdoc";
+import tsdoc from "eslint-plugin-tsdoc";
 import { createRequire } from "node:module";
 import js from "@eslint/js";
 import tseslint from "typescript-eslint";
@@ -5,6 +7,39 @@ import { posix } from "node:path";
 import { AST_NODE_TYPES, ESLintUtils, TSESLint } from "@typescript-eslint/utils";
 import * as ts from "typescript";
 import { isPropertyReadonlyInType, isTypeReference } from "ts-api-utils";
+//#region src/jsdoc.ts
+const jsdocConfig = jsdoc.configs["flat/recommended-tsdoc-error"];
+const REQUIREMENTS_TIER_RULES = [
+	"jsdoc/require-example",
+	"jsdoc/require-jsdoc",
+	"jsdoc/require-next-type",
+	"jsdoc/require-param",
+	"jsdoc/require-param-description",
+	"jsdoc/require-param-name",
+	"jsdoc/require-param-type",
+	"jsdoc/require-property",
+	"jsdoc/require-property-description",
+	"jsdoc/require-property-name",
+	"jsdoc/require-property-type",
+	"jsdoc/require-returns",
+	"jsdoc/require-returns-description",
+	"jsdoc/require-returns-type",
+	"jsdoc/require-template",
+	"jsdoc/require-throws-type",
+	"jsdoc/require-yields",
+	"jsdoc/require-yields-type"
+];
+const jsdocAndTsdoc = [{
+	...jsdocConfig,
+	rules: {
+		...jsdocConfig.rules,
+		...Object.fromEntries(REQUIREMENTS_TIER_RULES.map((rule) => [rule, "off"]))
+	}
+}, {
+	plugins: { tsdoc },
+	rules: { "tsdoc/syntax": "error" }
+}];
+//#endregion
 //#region src/optional-plugin.ts
 const nodeRequire = createRequire(import.meta.url);
 function tryRequire(specifier, requireFn = nodeRequire) {
@@ -90,7 +125,7 @@ function buildReactConfig(options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "2.10.6";
+var version = "2.12.0";
 //#endregion
 //#region src/rules/barrel-helpers.ts
 const INDEX_BASENAME$1 = /^index\.[cm]?[tj]sx?$/;
@@ -1380,7 +1415,16 @@ const recommendedTypeChecked = [
 			"@typescript-eslint/require-array-sort-compare": "error",
 			"@typescript-eslint/strict-boolean-expressions": "error",
 			"@typescript-eslint/strict-void-return": "error",
-			"@typescript-eslint/switch-exhaustiveness-check": "error"
+			"@typescript-eslint/switch-exhaustiveness-check": "error",
+			"max-lines": ["error", {
+				max: 800,
+				skipBlankLines: true,
+				skipComments: true
+			}],
+			"no-warning-comments": ["error", {
+				terms: ["stryker disable"],
+				location: "anywhere"
+			}]
 		}
 	},
 	{
@@ -1401,6 +1445,7 @@ function toPublicConfigArray(built) {
 function exadevConfig(options = {}, ...userConfigs) {
 	return toPublicConfigArray([
 		...recommendedTypeChecked,
+		...jsdocAndTsdoc,
 		...buildReactConfig({ enabled: options.react }),
 		...buildNextjsConfig({ enabled: options.nextjs }),
 		...userConfigs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exadev-eslint-config",
-  "version": "2.10.6",
+  "version": "2.12.0",
   "description": "Shared custom ESLint rules and plugin for ExaDev projects",
   "type": "module",
   "sideEffects": false,
@@ -86,6 +86,8 @@
   "dependencies": {
     "@eslint/js": "^10.0.1",
     "@typescript-eslint/utils": "^8.67.0",
+    "eslint-plugin-jsdoc": "^64.3.9",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "ts-api-utils": "^2.5.0"
   },
   "scripts": {