feat: ✨ jsdoc rules and remove old config

configs/js/src/@types/eslint-plugin-i.d.ts

@@ -2,24 +2,24 @@
 import type { ESLint, Linter } from 'eslint';
 
 /**
- * @see {@link https://www.npmjs.com/package/eslint-plugin-import npm package}
  * @summary ESLint plugin with rules that help validate proper imports.
  *
  * ---
  * **Note:** Types in this project where overridden to be compatible with ESLint new flat
  * config types. ESlint already has backwards compatibility for plugins not created in the
  * new flat config.
+ * @see {@link https://www.npmjs.com/package/eslint-plugin-import npm package}
  */
 declare module 'eslint-plugin-i' {
 	interface importEslintPlugin extends ESLint.Plugin {
 		configs: {
 			recommended: {
-				rules: Linter.RulesRecord
-			}
+				rules: Linter.RulesRecord,
+			},
 			typescript: {
-				rules: Linter.RulesRecord
-			}
-		}
+				rules: Linter.RulesRecord,
+			},
+		},
 	}
 	declare const plugin: importEslintPlugin;
 	export default plugin;

configs/js/src/@types/eslint-plugin-jsdoc.d.ts

@@ -1,25 +1,25 @@
 import type { ESLint } from 'eslint';
 
 /**
- * @see {@link https://www.npmjs.org/package/eslint-plugin-jsdoc npm package}
  * @summary JSDoc specific linting rules for ESLint.
  *
  * ---
  * **Note:** Types in this project where overridden to be compatible with ESLint new flat
  * config types. ESlint already has backwards compatibility for plugins not created in the
  * new flat config.
+ * @see {@link https://www.npmjs.org/package/eslint-plugin-jsdoc npm package}
  */
 declare module 'eslint-plugin-jsdoc' {
 	// eslint-disable-next-line unicorn/prevent-abbreviations
 	interface jsDocESlintPlugin extends ESLint.Plugin {
 		configs: ESLint.Plugin['configs'] & {
-			recommended: ESLint.ConfigData
-			'recommended-error': ESLint.ConfigData
-			'recommended-typescript': ESLint.ConfigData
-			'recommended-typescript-error': ESLint.ConfigData
-			'recommended-typescript-flavor': ESLint.ConfigData
-			'recommended-typescript-flavor-error': ESLint.ConfigData
-		}
+			recommended: ESLint.ConfigData,
+			'recommended-error': ESLint.ConfigData,
+			'recommended-typescript': ESLint.ConfigData,
+			'recommended-typescript-error': ESLint.ConfigData,
+			'recommended-typescript-flavor': ESLint.ConfigData,
+			'recommended-typescript-flavor-error': ESLint.ConfigData,
+		},
 	}
 	declare const plugin: jsDocESlintPlugin;
 	export default plugin;

configs/js/src/@types/globals.d.ts

@@ -1,10 +1,10 @@
 declare module 'globals' {
 	const globals: {
-		browser: { [rule: string]: boolean }
-		builtin: { [rule: string]: boolean }
-		commonjs: { [rule: string]: boolean }
-		node: { [rule: string]: boolean }
-		nodeBuiltin: { [rule: string]: boolean }
+		browser: { [rule: string]: boolean, },
+		builtin: { [rule: string]: boolean, },
+		commonjs: { [rule: string]: boolean, },
+		node: { [rule: string]: boolean, },
+		nodeBuiltin: { [rule: string]: boolean, },
 	};
 	export default globals;
 }

configs/js/src/@types/typescript-eslint.d.ts

@@ -1,37 +1,36 @@
 import type { ESLint, Linter } from 'eslint';
 
 /**
- * @see {@link https://www.npmjs.com/package/@typescript-eslint/eslint-plugin npm package}
  * @summary An ESLint plugin which provides lint rules for TypeScript codebases.
  *
  * ---
  * **Note:** Types in this project where overridden to be compatible with ESLint new flat
  * config types. ESlint already has backwards compatibility for plugins not created in the
  * new flat config.
+ * @see {@link https://www.npmjs.com/package/@typescript-eslint/eslint-plugin npm package}
  */
 declare module '@typescript-eslint/eslint-plugin' {
 	interface typescriptEslintPlugin extends ESLint.Plugin {
 		configs: {
 			'eslint-recommended': {
-				rules: Linter.RulesRecord
-			}
+				rules: Linter.RulesRecord,
+			},
 			recommended: {
-				rules: Linter.RulesRecord
-			}
+				rules: Linter.RulesRecord,
+			},
 			'recommended-requiring-type-checking': {
-				rules: Linter.RulesRecord
-			}
+				rules: Linter.RulesRecord,
+			},
 			strict: {
-				rules: Linter.RulesRecord
-			}
-		}
+				rules: Linter.RulesRecord,
+			},
+		},
 	}
 	declare const plugin: typescriptEslintPlugin;
 	export default plugin;
 }
 
 /**
- * @see {@link https://www.npmjs.com/package/@typescript-eslint/parser npm package}
  * @summary An ESLint parser which leverages TypeScript ESTree to allow for ESLint
  * to lint TypeScript source code.
  *
@@ -39,6 +38,7 @@ declare module '@typescript-eslint/eslint-plugin' {
  * **Note:** Types in this project where overridden to be compatible with ESLint new flat
  * config types. ESlint already has backwards compatibility for parsers not created in the
  * new flat config.
+ * @see {@link https://www.npmjs.com/package/@typescript-eslint/parser npm package}
  */
 declare module '@typescript-eslint/parser' {
 	declare const parser: Linter.ParserModule;

configs/js/src/configs/core.js

@@ -9,7 +9,7 @@ import process from 'node:process';
 
 /**
  * This config adds necessary plugins and configuration for ESLint to use in the other configs
- * **This should always be in the top of the configuration array**
+ * **This should always be in the top of the configuration array**.
  * @type {import('eslint').Linter.FlatConfig}
  */
 const config = {

configs/js/src/configs/documentation.js

@@ -0,0 +1,32 @@
+/* eslint-disable unicorn/no-useless-spread */
+// eslint-disable-next-line import/no-relative-parent-imports
+import { jsFiles, tsFiles } from '../constants.js';
+
+/** @type {import('eslint').Linter.FlatConfig} */
+const recommended = {
+	files: [...tsFiles, ...jsFiles],
+	rules: {
+		...{}, // Plugin: eslint-plugin-jsdoc
+		'jsdoc/match-description': 'error',
+		'jsdoc/require-description-complete-sentence': 'error',
+		'jsdoc/require-hyphen-before-param-description': ['error', 'always'],
+		'jsdoc/require-param-description': 'error',
+		'jsdoc/require-property-description': 'error',
+		'jsdoc/require-returns-check': 'error',
+	},
+};
+
+/** @type {import('eslint').Linter.FlatConfig} */
+const strict = {
+	...recommended,
+	rules: {
+		...recommended.rules,
+
+		...{}, // Plugin: eslint-plugin-jsdoc
+		'jsdoc/require-description': 'error',
+		'jsdoc/require-file-overview': 'error',
+	},
+};
+
+const documentation = { recommended, strict };
+export default documentation;

configs/js/src/configs/index.d.ts

@@ -2,6 +2,10 @@ import type { Linter } from 'eslint';
 
 const configs: Readonly<{
 	core: Linter.FlatConfig,
+	documentation: {
+		recommended: Linter.FlatConfig,
+		strict: Linter.FlatConfig,
+	},
 	environments: {
 		browser: {
 			recommended: Linter.FlatConfig,

configs/js/src/configs/index.js

@@ -1,18 +1,18 @@
 
 import typescript from './suggestions-typescript.js';
 import environments from './environments/index.js';
+import documentation from './documentation.js';
 import suggestions from './suggestions.js';
 import formatting from './formatting.js';
-import javascript from './javascript.js';
 import overrides from './overrides.js';
 import naming from './naming.js';
 import core from './core.js';
 
 const configs = {
 	core,
+	documentation,
 	environments,
 	formatting,
-	javascript,
 	naming,
 	overrides,
 	suggestions,

configs/js/src/configs/javascript.js

@@ -1,26 +0,0 @@
-import tsESLint from '@typescript-eslint/eslint-plugin';
-import jsdocPlugin from 'eslint-plugin-jsdoc';
-import importPlugin from 'eslint-plugin-i';
-import js from '@eslint/js';
-
-/** @type {import('eslint').Linter.FlatConfig} */
-const recommended = {
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-	rules: {
-		...js.configs.recommended.rules,
-		...tsESLint.configs.recommended.rules,
-		...tsESLint.configs['recommended-requiring-type-checking'].rules,
-		...tsESLint.configs['eslint-recommended'].rules,
-		...tsESLint.configs.strict.rules,
-		...importPlugin.configs.recommended.rules,
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-		...jsdocPlugin.configs['recommended-typescript-flavor-error'].rules,
-	},
-};
-
-/** @type {import('eslint').Linter.FlatConfig} */
-const strict = {
-	...recommended,
-};
-const javascript = { recommended, strict };
-export default javascript;

configs/js/src/configs/suggestions-typescript.js

@@ -1,3 +1,4 @@
+/* eslint-disable unicorn/no-useless-spread */
 
 // eslint-disable-next-line import/no-relative-parent-imports
 import { tsFiles } from '../constants.js';
@@ -6,7 +7,15 @@ import { tsFiles } from '../constants.js';
 const recommended = {
 	files: [...tsFiles],
 	rules: {
+		...{}, // Plugin: @typescript-eslint/eslint-plugin
 		'@typescript-eslint/explicit-function-return-type': 'error',
+
+		...{}, // Plugin: eslint-plugin-jsdoc
+		'jsdoc/check-tag-names': ['error', { typed: true }],
+		'jsdoc/no-types': 'error',
+		'jsdoc/require-param-type': 'off',
+		'jsdoc/require-property-type': 'off',
+		'jsdoc/require-returns-type': 'off',
 	},
 };
 
@@ -15,6 +24,8 @@ const strict = {
 	...recommended,
 	rules: {
 		...recommended.rules,
+
+		...{}, // Plugin: @typescript-eslint/eslint-plugin
 		'@typescript-eslint/explicit-member-accessibility': 'error',
 		'@typescript-eslint/explicit-module-boundary-types': 'error',
 	},

configs/js/src/configs/suggestions.js

@@ -192,7 +192,7 @@ const recommended = {
 		'unicorn/text-encoding-identifier-case': 'error',
 		'unicorn/throw-new-error': 'error',
 
-		...{}, // Plugin: eslint-plugin-import'error',
+		...{}, // Plugin: eslint-plugin-import
 		'import/no-amd': 'error',
 		'import/no-commonjs': 'error',
 		'import/no-deprecated': 'error',
@@ -202,6 +202,36 @@ const recommended = {
 		'import/no-named-as-default-member': 'error',
 		'import/no-self-import': 'error',
 		'import/no-useless-path-segments': 'error',
+
+		...{}, // Plugin: eslint-plugin-jsdoc
+		'jsdoc/check-alignment': 'error',
+		'jsdoc/check-param-names': 'error',
+		'jsdoc/check-property-names': 'error',
+		'jsdoc/check-syntax': 'error',
+		'jsdoc/check-tag-names': 'error',
+		'jsdoc/check-types': 'error',
+		'jsdoc/check-values': 'error',
+		'jsdoc/empty-tags': 'error',
+		'jsdoc/implements-on-classes': 'error',
+		'jsdoc/multiline-blocks': 'error',
+		'jsdoc/no-multi-asterisks': ['error', { allowWhitespace: true }],
+		'jsdoc/require-asterisk-prefix': ['error', 'always'],
+		'jsdoc/require-jsdoc': 'error',
+		'jsdoc/require-param': 'error',
+		'jsdoc/require-param-name': 'error',
+		'jsdoc/require-param-type': 'error',
+		'jsdoc/require-property': 'error',
+		'jsdoc/require-property-name': 'error',
+		'jsdoc/require-property-type': 'error',
+		'jsdoc/require-returns': 'error',
+		'jsdoc/require-returns-check': 'error',
+		'jsdoc/require-returns-type': 'error',
+		'jsdoc/require-throws': 'error',
+		'jsdoc/require-yields': 'error',
+		'jsdoc/require-yields-check': 'error',
+		'jsdoc/sort-tags': 'error',
+		'jsdoc/valid-types': 'error',
+
 	},
 };
 
@@ -359,6 +389,15 @@ const strict = {
 		'import/prefer-default-export': 'error',
 		'import/unambiguous': 'error',
 
+		...{}, // Plugin: eslint-plugin-jsdoc
+		'jsdoc/check-access': 'error',
+		'jsdoc/check-indentation': 'error',
+		'jsdoc/informative-docs': 'error',
+		'jsdoc/multiline-blocks': ['error', { noSingleLineBlocks: true }],
+		'jsdoc/no-bad-blocks': 'error',
+		'jsdoc/no-blank-block-descriptions': 'error',
+		'jsdoc/no-blank-blocks': 'error',
+
 	},
 };
 

configs/js/src/presets/recommended.js

@@ -4,12 +4,10 @@ import configs from '../configs/index.js';
 /** @type {import('eslint').Linter.FlatConfig[]} */
 const recommended = [
 	configs.core,
-	// TODO [>=1.0.0]: remove .javascript and .typescript configs
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-	configs.javascript.recommended,
 	configs['suggestions-typescript'].recommended,
 	configs.suggestions.recommended,
 	configs.formatting.recommended,
 	configs.naming.recommended,
+	configs.documentation.recommended,
 ];
 export default recommended;

configs/js/src/presets/strict.js

@@ -4,12 +4,10 @@ import configs from '../configs/index.js';
 /** @type {import('eslint').Linter.FlatConfig[]} */
 const strict = [
 	configs.core,
-	// TODO [>=1.0.0]: remove .javascript and .typescript configs
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-	configs.javascript.strict,
 	configs['suggestions-typescript'].strict,
 	configs.suggestions.strict,
 	configs.formatting.strict,
 	configs.naming.strict,
+	configs.documentation.recommended,
 ];
 export default strict;