chore: restore eslint-plugin-jsdoc rules (#324)

* chore: restore eslint-plugin-jsdoc rules

* add `coverage/` to global ignores

Author: Pixel998

eslint.config.js

@@ -9,18 +9,14 @@
 
 import eslintConfigESLint from "eslint-config-eslint";
 import eslintPlugin from "eslint-plugin-eslint-plugin";
+import globals from "globals";
 import json from "@eslint/json";
 import { defineConfig, globalIgnores } from "eslint/config";
-import css from "./src/index.js";
 
 //-----------------------------------------------------------------------------
 // Helpers
 //-----------------------------------------------------------------------------
 
-const eslintPluginJSDoc = eslintConfigESLint.find(
-	config => config.plugins?.jsdoc,
-).plugins.jsdoc;
-
 const eslintPluginRulesRecommendedConfig =
 	eslintPlugin.configs["flat/rules-recommended"];
 const eslintPluginTestsRecommendedConfig =
@@ -31,66 +27,38 @@ const eslintPluginTestsRecommendedConfig =
 //-----------------------------------------------------------------------------
 
 export default defineConfig([
-	globalIgnores([
-		"**/tests/fixtures/",
-		"**/dist/",
-		"test.css",
-		"coverage/",
-		"src/build/",
-	]),
-
-	...eslintConfigESLint.map(config => ({
-		files: ["**/*.js"],
-		...config,
-	})),
-	{
-		plugins: { json },
-		files: ["**/*.json", ".c8rc"],
-		language: "json/json",
-		extends: ["json/recommended"],
-	},
+	globalIgnores(["coverage/", "dist/", "src/build/"], "css/global-ignores"),
 	{
+		name: "css/js",
 		files: ["**/*.js"],
+		extends: [eslintConfigESLint],
 		rules: {
-			// disable rules we don't want to use from eslint-config-eslint
 			"no-undefined": "off",
 			"class-methods-use-this": "off",
-
-			// TODO: re-enable eslint-plugin-jsdoc rules
-			...Object.fromEntries(
-				Object.keys(eslintPluginJSDoc.rules).map(name => [
-					`jsdoc/${name}`,
-					"off",
-				]),
-			),
 		},
 	},
 	{
-		files: ["**/tests/**"],
+		name: "css/tools",
+		files: ["tools/**/*.js"],
+		rules: {
+			"no-console": "off",
+		},
+	},
+	{
+		name: "css/tests",
+		files: ["tests/**/*.js"],
+		ignores: ["tests/rules/*.js"],
 		languageOptions: {
 			globals: {
-				describe: "readonly",
-				xdescribe: "readonly",
-				it: "readonly",
-				xit: "readonly",
-				beforeEach: "readonly",
-				afterEach: "readonly",
-				before: "readonly",
-				after: "readonly",
+				...globals.mocha,
 			},
 		},
 	},
 	{
+		name: "css/rules",
 		files: ["src/rules/*.js"],
 		extends: [eslintPluginRulesRecommendedConfig],
 		rules: {
-			"eslint-plugin/require-meta-docs-url": [
-				"error",
-				{
-					pattern:
-						"https://github.com/eslint/css/blob/main/docs/rules/{{name}}.md",
-				},
-			],
 			"eslint-plugin/require-meta-schema": "off", // `schema` defaults to []
 			"eslint-plugin/prefer-placeholders": "error",
 			"eslint-plugin/prefer-replace-text": "error",
@@ -99,9 +67,17 @@ export default defineConfig([
 				"error",
 				{ pattern: "^(Enforce|Require|Disallow) .+[^. ]$" },
 			],
+			"eslint-plugin/require-meta-docs-url": [
+				"error",
+				{
+					pattern:
+						"https://github.com/eslint/css/blob/main/docs/rules/{{name}}.md",
+				},
+			],
 		},
 	},
 	{
+		name: "css/rules-tests",
 		files: ["tests/rules/*.test.js"],
 		extends: [eslintPluginTestsRecommendedConfig],
 		rules: {
@@ -122,15 +98,10 @@ export default defineConfig([
 		},
 	},
 	{
-		files: ["**/*.css"],
-		language: "css/css",
-		plugins: { css },
-		extends: ["css/recommended"],
-	},
-	{
-		files: ["tools/**/*.js"],
-		rules: {
-			"no-console": "off",
-		},
+		name: "css/json",
+		plugins: { json },
+		files: ["**/*.json", ".c8rc"],
+		language: "json/json",
+		extends: ["json/recommended"],
 	},
 ]);

package.json

@@ -95,6 +95,7 @@
     "eslint": "^9.36.0",
     "eslint-config-eslint": "^13.0.0",
     "eslint-plugin-eslint-plugin": "^6.3.2",
+    "globals": "^16.5.0",
     "lint-staged": "^15.2.7",
     "mdast-util-from-markdown": "^2.0.2",
     "mdn-data": "^2.25.0",

src/languages/css-language.js

@@ -54,7 +54,6 @@ const blockCloserTokenTypes = new Map([
 /**
  * Recursively replaces all function values in an object with boolean true.
  * Used to make objects serializable for JSON output.
- *
  * @param {Record<string,any>|unknown[]|unknown} object The object to process.
  * @returns {Record<string,any>|unknown[]|unknown} A copy of the object with all functions replaced by true.
  */

src/rules/no-invalid-at-rules.js

@@ -100,6 +100,7 @@ export default {
 		 * - Ensures the rule has a prelude
 		 * - Validates the prelude matches the expected pattern
 		 * @param {AtrulePlain} node The node representing the rule.
+		 * @returns {void}
 		 */
 		function validateCharsetRule(node) {
 			const { name, prelude, loc } = node;

src/rules/no-invalid-properties.js

@@ -32,8 +32,8 @@ const varFunctionPattern = /var\(\s*(--[^,\s)]+)\s*(?:,([\s\S]+))?\)/iu;
 
 /**
  * Parses a var() function text and extracts the custom property name and fallback.
- * @param {string} text
- * @returns {{ name: string, fallbackText: string | null } | null}
+ * @param {string} text The text containing a var() function.
+ * @returns {{ name: string, fallbackText: string | null } | null} The parsed variable name and optional fallback, or null if not a var().
  */
 function parseVarFunction(text) {
 	const match = text.match(varFunctionPattern);
@@ -50,7 +50,7 @@ function parseVarFunction(text) {
  * Extracts the list of fallback value or variable name used in a `var()` that is used as fallback function.
  * For example, for `var(--my-color, var(--fallback-color, red));` it will return `["--fallback-color", "red"]`.
  * @param {string} value The fallback value that is used in `var()`.
- * @return {Array<string>} The list of variable names of fallback value.
+ * @returns {Array<string>} The list of variable names of fallback value.
  */
 function getVarFallbackList(value) {
 	const list = [];
@@ -220,10 +220,10 @@ export default {
 		/**
 		 * Resolves a fallback text which can contain nested var() calls.
 		 * Returns the first resolvable value or null if none resolve.
-		 * @param {string} rawFallbackText
-		 * @param {Map<string, string>} cache Cache for memoization within a single resolution scope
-		 * @param {Set<string>} [seen] Set of already seen variables to detect cycles
-		 * @returns {string | null}
+		 * @param {string} rawFallbackText The raw fallback text to resolve.
+		 * @param {Map<string, string>} cache Cache for memoization within a single resolution scope.
+		 * @param {Set<string>} [seen] Set of already seen variables to detect cycles.
+		 * @returns {string | null} The resolved fallback value, or null if none can be resolved.
 		 */
 		function resolveFallback(rawFallbackText, cache, seen = new Set()) {
 			const fallbackVarList = getVarFallbackList(rawFallbackText);

src/rules/use-baseline.js

@@ -589,7 +589,7 @@ export default {
 		 * Checks a property value function to see if it's a baseline feature.
 		 * @param {FunctionNodePlain} child The node to check.
 		 * @returns {void}
-		 **/
+		 */
 		function checkPropertyValueFunction(child) {
 			if (allowFunctions.has(child.name)) {
 				return;