fix: update context.report types (#19751)

snitin315 · fasttime · web-flow · commit a467de39f6e5 · 2025-05-29T11:31:01.000-04:00
* fix: udpate `context.report` types

* test: add tests

* docs: fix context.report() nodeType description

* fix: udpate `Rule.RuleModule` types

* refactor: udpate types

* chore: fix formatting

* fix: export JSSyntaxElement

Co-authored-by: Francesco Trotta &lt;github@fasttime.org&gt;

* chore: add tests

---------

Co-authored-by: Francesco Trotta &lt;github@fasttime.org&gt;
diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md
@@ -163,7 +163,7 @@ The main method you'll use when writing custom rules is `context.report()`, whic
 
 - `messageId`: (`string`) The ID of the message (see [messageIds](#messageids)) (recommended over `message`).
 - `message`: (`string`) The problem message (alternative to `messageId`).
-- `node`: (optional `object`) The AST node related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem.
+- `node`: (optional `object`) This can be an AST node, a token, or a comment related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem.
 - `loc`: (optional `object`) Specifies the location of the problem. If both `loc` and `node` are specified, then the location is used from `loc` instead of `node`.
     - `start`: An object of the start location.
         - `line`: (`number`) The 1-based line number at which the problem occurred.
diff --git a/docs/src/integrate/nodejs-api.md b/docs/src/integrate/nodejs-api.md
@@ -672,7 +672,7 @@ The information available for each linting message is:
 - `line` - the line on which the error occurred.
 - `message` - the message that should be output.
 - `messageId` - the ID of the message used to generate the message (this property is omitted if the rule does not use message IDs).
-- `nodeType` - (**Deprecated:** This property will be removed in a future version of ESLint.) the node or token type that was reported with the problem.
+- `nodeType` - (**Deprecated:** This property will be removed in a future version of ESLint.) the node, comment, or token type that was reported with the problem.
 - `ruleId` - the ID of the rule that triggered the messages (or null if `fatal` is true).
 - `severity` - either 1 or 2, depending on your configuration.
 - `endColumn` - the end column of the range on which the error occurred (this property is omitted if it's not range).
diff --git a/lib/types/index.d.ts b/lib/types/index.d.ts
@@ -584,14 +584,19 @@ export namespace SourceCode {
 
 // #endregion
 
+export type JSSyntaxElement = {
+	type: string;
+	loc?: ESTree.SourceLocation | null | undefined;
+};
+
 export namespace Rule {
 	interface RuleModule
 		extends RuleDefinition<{
 			LangOptions: Linter.LanguageOptions;
 			Code: SourceCode;
 			RuleOptions: any[];
 			Visitor: NodeListener;
-			Node: ESTree.Node;
+			Node: JSSyntaxElement;
 			MessageIds: string;
 			ExtRuleDocs: {};
 		}> {
@@ -1159,10 +1164,10 @@ export namespace Rule {
 		/**
 		 * Indicates the type of rule:
 		 * - `"problem"` means the rule is identifying code that either will cause an error or may cause a confusing behavior. Developers should consider this a high priority to resolve.
-		 * - `"suggestion"` means the rule is identifying something that could be done in a better way but no errors will occur if the code isn’t changed.
+		 * - `"suggestion"` means the rule is identifying something that could be done in a better way but no errors will occur if the code isn't changed.
 		 * - `"layout"` means the rule cares primarily about whitespace, semicolons, commas, and parentheses,
 		 *   all the parts of the program that determine how the code looks rather than how it executes.
-		 *   These rules work on parts of the code that aren’t specified in the AST.
+		 *   These rules work on parts of the code that aren't specified in the AST.
 		 */
 		type?: "problem" | "suggestion" | "layout" | undefined;
 		/**
@@ -1177,7 +1182,7 @@ export namespace Rule {
 			LangOptions: Linter.LanguageOptions;
 			Code: SourceCode;
 			RuleOptions: any[];
-			Node: ESTree.Node;
+			Node: JSSyntaxElement;
 			MessageIds: string;
 		}> {
 		/*
@@ -1275,7 +1280,7 @@ export type JSRuleDefinition<
 		LangOptions: Linter.LanguageOptions;
 		Code: SourceCode;
 		Visitor: Rule.NodeListener;
-		Node: ESTree.Node;
+		Node: JSSyntaxElement;
 	} & Required<
 		// Rule specific type options (custom)
 		Options &
diff --git a/tests/lib/types/types.test.ts b/tests/lib/types/types.test.ts
@@ -35,6 +35,7 @@ import {
 	RuleTester,
 	Scope,
 	SourceCode,
+	JSSyntaxElement,
 } from "eslint";
 import { defineConfig, globalIgnores } from "eslint/config";
 import { ESLintRules } from "eslint/rules";
@@ -149,9 +150,9 @@ sourceCode.getFirstToken(AST, { includeComments: true }); // $ExpectType Comment
 sourceCode.getFirstToken(AST, { includeComments: true, skip: 0 });
 // prettier-ignore
 sourceCode.getFirstToken(AST, { // $ExpectType (Token & { type: "Identifier"; }) | null
-    includeComments: true,
-    skip: 0,
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	includeComments: true,
+	skip: 0,
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 
 sourceCode.getFirstTokens(AST); // $ExpectType Token[]
@@ -169,16 +170,16 @@ sourceCode.getFirstTokens(AST, {
 });
 // prettier-ignore
 sourceCode.getFirstTokens(AST, { // $ExpectType (Token & { type: "Identifier"; })[]
-    count: 0,
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	count: 0,
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 sourceCode.getFirstTokens(AST, { includeComments: true }); //  $ ExpectType (Comment | Token)[]
 sourceCode.getFirstTokens(AST, { includeComments: true, count: 0 }); //  $ ExpectType (Comment | Token)[]
 // prettier-ignore
 sourceCode.getFirstTokens(AST, { // $ExpectType (Token & { type: "Identifier"; })[]
-    includeComments: true,
-    count: 0,
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	includeComments: true,
+	count: 0,
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 
 sourceCode.getLastToken(AST);
@@ -302,7 +303,7 @@ sourceCode.getFirstTokenBetween(
 );
 // prettier-ignore
 sourceCode.getFirstTokenBetween(AST, AST, { // $ExpectType (Token & { type: "Identifier"; }) | null
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 sourceCode.getFirstTokenBetween(AST, AST, {
 	skip: 0,
@@ -313,9 +314,9 @@ sourceCode.getFirstTokenBetween(AST, AST, { includeComments: true }); // $Expect
 sourceCode.getFirstTokenBetween(AST, AST, { includeComments: true, skip: 0 });
 // prettier-ignore
 sourceCode.getFirstTokenBetween(AST, AST, { // $ExpectType (Token & { type: "Identifier"; }) | null
-    includeComments: true,
-    skip: 0,
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	includeComments: true,
+	skip: 0,
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 
 sourceCode.getFirstTokensBetween(AST, AST); // $ExpectType Token[]
@@ -329,7 +330,7 @@ sourceCode.getFirstTokensBetween(
 );
 // prettier-ignore
 sourceCode.getFirstTokensBetween(AST, AST, { // $ExpectType (Token & { type: "Identifier"; })[]
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 sourceCode.getFirstTokensBetween(AST, AST, {
 	count: 0,
@@ -339,9 +340,9 @@ sourceCode.getFirstTokensBetween(AST, AST, { includeComments: true }); // $Expec
 sourceCode.getFirstTokensBetween(AST, AST, { includeComments: true, count: 0 });
 // prettier-ignore
 sourceCode.getFirstTokensBetween(AST, AST, { // $ExpectType (Token & { type: "Identifier"; })[]
-    includeComments: true,
-    count: 0,
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	includeComments: true,
+	count: 0,
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 
 sourceCode.getLastTokenBetween(AST, AST);
@@ -401,8 +402,8 @@ sourceCode.getTokens(AST, {
 sourceCode.getTokens(AST, { includeComments: true }); // $ExpectType (Comment | Token)[]
 // prettier-ignore
 sourceCode.getTokens(AST, { // $ExpectType (Token & { type: "Identifier"; })[]
-    includeComments: true,
-    filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
+	includeComments: true,
+	filter: (t): t is AST.Token & { type: "Identifier" } => t.type === "Identifier",
 });
 
 sourceCode.commentsExistBetween(AST, AST);
@@ -2202,3 +2203,40 @@ defineConfig([
 ]);
 
 // #endregion
+
+// #region JSSyntaxElement
+
+const fooRule1: Rule.RuleModule = {
+	create(context) {
+		return {
+			Program(node) {
+				for (const comment of node.comments ?? []) {
+					context.report({
+						node: comment,
+						messageId: "foo",
+					});
+				}
+			},
+		};
+	},
+};
+
+const fooRule2: JSRuleDefinition = {
+	create(context) {
+		return {
+			Program(node) {
+				for (const comment of node.comments ?? []) {
+					context.report({
+						node: comment,
+						messageId: "foo",
+					});
+				}
+			},
+		};
+	},
+};
+
+const SYNTAX_ELEMENT_COMMENT: JSSyntaxElement = COMMENT;
+const SYNTAX_ELEMENT_TOKEN: JSSyntaxElement = TOKEN;
+
+// #endregion JSSyntaxElement
