chore: add jsdoc type annotation to rules (#15291)

Makefile.js

@@ -789,6 +789,8 @@ target.checkRuleFiles = function() {
     RULE_FILES.forEach(filename => {
         const basename = path.basename(filename, ".js");
         const docFilename = `docs/rules/${basename}.md`;
+        const docText = cat(docFilename);
+        const ruleCode = cat(filename);
 
         /**
          * Check if basename is present in rule-types.json file.
@@ -806,7 +808,6 @@ target.checkRuleFiles = function() {
          * @private
          */
         function hasIdInTitle(id) {
-            const docText = cat(docFilename);
             const idOldAtEndOfTitleRegExp = new RegExp(`^# (.*?) \\(${id}\\)`, "u"); // original format
             const idNewAtBeginningOfTitleRegExp = new RegExp(`^# ${id}: `, "u"); // new format is same as rules index
             /*
@@ -824,14 +825,23 @@ target.checkRuleFiles = function() {
          * @private
          */
         function hasDeprecatedInfo() {
-            const ruleCode = cat(filename);
             const deprecatedTagRegExp = /@deprecated in ESLint/u;
-            const docText = cat(docFilename);
             const deprecatedInfoRegExp = /This rule was .+deprecated.+in ESLint/u;
 
             return deprecatedTagRegExp.test(ruleCode) && deprecatedInfoRegExp.test(docText);
         }
 
+        /**
+         * Check if the rule code has the jsdoc comment with the rule type annotation.
+         * @returns {boolean} true if present
+         * @private
+         */
+        function hasRuleTypeJSDocComment() {
+            const comment = "/** @type {import('../shared/types').Rule} */";
+
+            return ruleCode.includes(comment);
+        }
+
         // check for docs
         if (!test("-f", docFilename)) {
             console.error("Missing documentation for rule %s", basename);
@@ -880,6 +890,11 @@ target.checkRuleFiles = function() {
                     errors++;
                 }
             }
+
+            if (!hasRuleTypeJSDocComment()) {
+                console.error(`Missing rule type JSDoc comment from ${basename} rule code.`);
+                errors++;
+            }
         }
 
         // check for tests

docs/developer-guide/working-with-rules.md

@@ -24,9 +24,7 @@ Here is the basic format of the source file for a rule:
 // Rule Definition
 //------------------------------------------------------------------------------
 
-/**
- * @type {import('eslint').Rule.RuleModule}
- */
+/** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/accessor-pairs.js

@@ -134,6 +134,7 @@ function isPropertyDescriptor(node) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/array-bracket-newline.js

@@ -11,6 +11,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/array-bracket-spacing.js

@@ -10,6 +10,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/array-callback-return.js

@@ -133,6 +133,7 @@ function getArrayMethodName(node) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "problem",

lib/rules/array-element-newline.js

@@ -11,6 +11,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/arrow-body-style.js

@@ -14,6 +14,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/arrow-parens.js

@@ -27,6 +27,7 @@ function hasBlockBody(node) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/arrow-spacing.js

@@ -14,6 +14,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/block-scoped-var.js

@@ -8,6 +8,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/block-spacing.js

@@ -11,6 +11,7 @@ const util = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/brace-style.js

@@ -11,6 +11,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/callback-return.js

@@ -9,6 +9,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         deprecated: true,

lib/rules/camelcase.js

@@ -9,6 +9,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/capitalized-comments.js

@@ -99,6 +99,7 @@ function createRegExpForIgnorePatterns(normalizedOptions) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/class-methods-use-this.js

@@ -15,6 +15,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/comma-dangle.js

@@ -70,6 +70,7 @@ function normalizeOptions(optionValue, ecmaVersion) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/comma-spacing.js

@@ -10,6 +10,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/comma-style.js

@@ -11,6 +11,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/complexity.js

@@ -17,6 +17,7 @@ const { upperCaseFirst } = require("../shared/string-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/computed-property-spacing.js

@@ -10,6 +10,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/consistent-return.js

@@ -40,6 +40,7 @@ function isClassConstructor(node) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/consistent-this.js

@@ -8,6 +8,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/constructor-super.js

@@ -116,6 +116,7 @@ function isPossibleConstructor(node) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "problem",

lib/rules/curly.js

@@ -14,6 +14,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/default-case-last.js

@@ -9,6 +9,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/default-case.js

@@ -10,6 +10,7 @@ const DEFAULT_COMMENT_PATTERN = /^no default$/iu;
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/default-param-last.js

@@ -5,6 +5,7 @@
 
 "use strict";
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/dot-location.js

@@ -11,6 +11,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/dot-notation.js

@@ -20,6 +20,7 @@ const validIdentifier = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/u;
 // `null` literal must be handled separately.
 const literalTypesToCheck = new Set(["string", "boolean"]);
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/eol-last.js

@@ -8,6 +8,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/eqeqeq.js

@@ -15,6 +15,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/for-direction.js

@@ -9,6 +9,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "problem",

lib/rules/func-call-spacing.js

@@ -15,6 +15,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/func-name-matching.js

@@ -68,6 +68,7 @@ const optionsObject = {
     additionalProperties: false
 };
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/func-names.js

@@ -24,6 +24,7 @@ function isFunctionName(variable) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/func-style.js

@@ -8,6 +8,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "suggestion",

lib/rules/function-call-argument-newline.js

@@ -9,6 +9,7 @@
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/function-paren-newline.js

@@ -14,6 +14,7 @@ const astUtils = require("./utils/ast-utils");
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/generator-star-spacing.js

@@ -25,6 +25,7 @@ const OVERRIDE_SCHEMA = {
     ]
 };
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "layout",

lib/rules/getter-return.js

@@ -29,6 +29,7 @@ function isReachable(segment) {
 // Rule Definition
 //------------------------------------------------------------------------------
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         type: "problem",

lib/rules/global-require.js

@@ -48,6 +48,7 @@ function isShadowed(scope, node) {
     return reference && reference.resolved && reference.resolved.defs.length > 0;
 }
 
+/** @type {import('../shared/types').Rule} */
 module.exports = {
     meta: {
         deprecated: true,