@eslint/json 0.12.0 → 0.13.0

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 
 /**
- * @import { DocumentNode, Node, Token, AnyNode, MemberNode } from "@humanwhocodes/momoa"
- * @import { SourceLocation, FileProblem, DirectiveType, RulesConfig, TextSourceCode, Language, OkParseResult, ParseResult, File } from "@eslint/core"
+ * @import { DocumentNode, AnyNode, Token, MemberNode } from "@humanwhocodes/momoa"
+ * @import { SourceLocation, FileProblem, DirectiveType, RulesConfig, Language, OkParseResult, ParseResult, File } from "@eslint/core"
  * @import { JSONSyntaxElement, JSONRuleDefinition } from "./types.ts"
  */
 // @ts-self-types="./index.d.ts"
@@ -37,14 +37,14 @@ const INLINE_CONFIG =
 class JSONTraversalStep extends VisitNodeStep {
 	/**
 	 * The target of the step.
-	 * @type {Node}
+	 * @type {AnyNode}
 	 */
 	target = undefined;
 
 	/**
 	 * Creates a new instance.
 	 * @param {Object} options The options for the step.
-	 * @param {Node} options.target The target of the step.
+	 * @param {AnyNode} options.target The target of the step.
 	 * @param {1|2} options.phase The phase of the step.
 	 * @param {Array<any>} options.args The arguments of the step.
 	 */
@@ -55,13 +55,44 @@ class JSONTraversalStep extends VisitNodeStep {
 	}
 }
 
+/**
+ * Processes tokens to extract comments and their starting tokens.
+ * @param {Array<Token>} tokens The tokens to process.
+ * @returns {{ comments: Array<Token>, starts: Map<number, number>, ends: Map<number, number>}}
+ * An object containing an array of comments, a map of starting token range to token index, and
+ * a map of ending token range to token index.
+ */
+function processTokens(tokens) {
+	/** @type {Array<Token>} */
+	const comments = [];
+
+	/** @type {Map<number, number>} */
+	const starts = new Map();
+
+	/** @type {Map<number, number>} */
+	const ends = new Map();
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+
+		if (token.type.endsWith("Comment")) {
+			comments.push(token);
+		}
+
+		starts.set(token.range[0], i);
+		ends.set(token.range[1], i);
+	}
+
+	return { comments, starts, ends };
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
 
 /**
  * JSON Source Code Object
- * @implements {TextSourceCode<{LangOptions: JSONLanguageOptions, RootNode: DocumentNode, SyntaxElementWithLoc: JSONSyntaxElement, ConfigNode: Token}>}
+ * @extends {TextSourceCodeBase<{LangOptions: JSONLanguageOptions, RootNode: DocumentNode, SyntaxElementWithLoc: JSONSyntaxElement, ConfigNode: Token}>}
  */
 class JSONSourceCode extends TextSourceCodeBase {
 	/**
@@ -72,7 +103,7 @@ class JSONSourceCode extends TextSourceCodeBase {
 
 	/**
 	 * Cache of parent nodes.
-	 * @type {WeakMap<Node, Node>}
+	 * @type {WeakMap<AnyNode, AnyNode>}
 	 */
 	#parents = new WeakMap();
 
@@ -89,11 +120,23 @@ class JSONSourceCode extends TextSourceCodeBase {
 	ast = undefined;
 
 	/**
-	 * The comment node in the source code.
+	 * The comment tokens in the source code.
 	 * @type {Array<Token>|undefined}
 	 */
 	comments;
 
+	/**
+	 * A map of token start positions to their corresponding index.
+	 * @type {Map<number, number>}
+	 */
+	#tokenStarts;
+
+	/**
+	 * A map of token end positions to their corresponding index.
+	 * @type {Map<number, number>}
+	 */
+	#tokenEnds;
+
 	/**
 	 * Creates a new instance.
 	 * @param {Object} options The options for the instance.
@@ -103,9 +146,11 @@ class JSONSourceCode extends TextSourceCodeBase {
 	constructor({ text, ast }) {
 		super({ text, ast });
 		this.ast = ast;
-		this.comments = ast.tokens
-			? ast.tokens.filter(token => token.type.endsWith("Comment"))
-			: [];
+
+		const { comments, starts, ends } = processTokens(this.ast.tokens ?? []);
+		this.comments = comments;
+		this.#tokenStarts = starts;
+		this.#tokenEnds = ends;
 	}
 
 	/**
@@ -240,8 +285,8 @@ class JSONSourceCode extends TextSourceCodeBase {
 
 	/**
 	 * Returns the parent of the given node.
-	 * @param {Node} node The node to get the parent of.
-	 * @returns {Node|undefined} The parent of the node.
+	 * @param {AnyNode} node The node to get the parent of.
+	 * @returns {AnyNode|undefined} The parent of the node.
 	 */
 	getParent(node) {
 		return this.#parents.get(node);
@@ -262,12 +307,15 @@ class JSONSourceCode extends TextSourceCodeBase {
 
 		for (const { node, parent, phase } of iterator(this.ast)) {
 			if (parent) {
-				this.#parents.set(node, parent);
+				this.#parents.set(
+					/** @type {AnyNode} */ (node),
+					/** @type {AnyNode} */ (parent),
+				);
 			}
 
 			steps.push(
 				new JSONTraversalStep({
-					target: node,
+					target: /** @type {AnyNode} */ (node),
 					phase: phase === "enter" ? 1 : 2,
 					args: [node, parent],
 				}),
@@ -276,10 +324,89 @@ class JSONSourceCode extends TextSourceCodeBase {
 
 		return steps;
 	}
+
+	/**
+	 * Gets the token before the given node or token, optionally including comments.
+	 * @param {AnyNode|Token} nodeOrToken The node or token to get the previous token for.
+	 * @param {Object} [options] Options object.
+	 * @param {boolean} [options.includeComments] If true, return comments when they are present.
+	 * @returns {Token|null} The previous token or comment, or null if there is none.
+	 */
+	getTokenBefore(nodeOrToken, { includeComments = false } = {}) {
+		const index = this.#tokenStarts.get(nodeOrToken.range[0]);
+
+		if (index === undefined) {
+			return null;
+		}
+
+		let previousIndex = index - 1;
+		if (previousIndex < 0) {
+			return null;
+		}
+
+		const tokens = this.ast.tokens;
+		let tokenOrComment = tokens[previousIndex];
+
+		if (includeComments) {
+			return tokenOrComment;
+		}
+
+		// skip comments
+		while (tokenOrComment?.type.endsWith("Comment")) {
+			previousIndex--;
+
+			if (previousIndex < 0) {
+				return null;
+			}
+
+			tokenOrComment = tokens[previousIndex];
+		}
+		return tokenOrComment;
+	}
+
+	/**
+	 * Gets the token after the given node or token, skipping any comments unless includeComments is true.
+	 * @param {AnyNode|Token} nodeOrToken The node or token to get the next token for.
+	 * @param {Object} [options] Options object.
+	 * @param {boolean} [options.includeComments=false] If true, return comments when they are present.
+	 * @returns {Token|null} The next token or comment, or null if there is none.
+	 */
+	getTokenAfter(nodeOrToken, { includeComments = false } = {}) {
+		const index = this.#tokenEnds.get(nodeOrToken.range[1]);
+
+		if (index === undefined) {
+			return null;
+		}
+
+		let nextIndex = index + 1;
+		const tokens = this.ast.tokens;
+		if (nextIndex >= tokens.length) {
+			return null;
+		}
+
+		let tokenOrComment = tokens[nextIndex];
+
+		if (includeComments) {
+			return tokenOrComment;
+		}
+
+		// skip comments
+		while (tokenOrComment?.type.endsWith("Comment")) {
+			nextIndex++;
+
+			if (nextIndex >= tokens.length) {
+				return null;
+			}
+
+			tokenOrComment = tokens[nextIndex];
+		}
+
+		return tokenOrComment;
+	}
 }
 
 /**
- * @filedescription Functions to fix up rules to provide missing methods on the `context` object.
+ * @fileoverview The JSONLanguage class.
  * @author Nicholas C. Zakas
  */
 
@@ -440,6 +567,13 @@ class JSONLanguage {
 	/* eslint-enable class-methods-use-this -- Required to complete interface. */
 }
 
+const rules$1 = /** @type {const} */ ({
+    "json/no-duplicate-keys": "error",
+    "json/no-empty-keys": "error",
+    "json/no-unnormalized-keys": "error",
+    "json/no-unsafe-values": "error"
+});
+
 /**
  * @fileoverview Rule to prevent duplicate keys in JSON.
  * @author Nicholas C. Zakas
@@ -465,7 +599,9 @@ const rule$5 = {
 		type: "problem",
 
 		docs: {
+			recommended: true,
 			description: "Disallow duplicate keys in JSON objects",
+			url: "https://github.com/eslint/json/tree/main/docs/rules/no-duplicate-keys.md",
 		},
 
 		messages: {
@@ -536,7 +672,9 @@ const rule$4 = {
 		type: "problem",
 
 		docs: {
+			recommended: true,
 			description: "Disallow empty keys in JSON objects",
+			url: "https://github.com/eslint/json/tree/main/docs/rules/no-empty-keys.md",
 		},
 
 		messages: {
@@ -563,6 +701,80 @@ const rule$4 = {
 	},
 };
 
+/**
+ * @fileoverview Rule to detect unnormalized keys in JSON.
+ * @author Bradley Meck Farias
+ */
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/**
+ *
+ * @typedef {"unnormalizedKey"} NoUnnormalizedKeysMessageIds
+ * @typedef {{ form: string }} NoUnnormalizedKeysOptions
+ * @typedef {JSONRuleDefinition<{ RuleOptions: [NoUnnormalizedKeysOptions], MessageIds: NoUnnormalizedKeysMessageIds }>} NoUnnormalizedKeysRuleDefinition
+ */
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+/** @type {NoUnnormalizedKeysRuleDefinition} */
+const rule$3 = {
+	meta: {
+		type: "problem",
+
+		docs: {
+			recommended: true,
+			description: "Disallow JSON keys that are not normalized",
+			url: "https://github.com/eslint/json/tree/main/docs/rules/no-unnormalized-keys.md",
+		},
+
+		messages: {
+			unnormalizedKey: "Unnormalized key '{{key}}' found.",
+		},
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					form: {
+						enum: ["NFC", "NFD", "NFKC", "NFKD"],
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+	},
+
+	create(context) {
+		const form = context.options.length
+			? context.options[0].form
+			: undefined;
+
+		return {
+			Member(node) {
+				const key =
+					node.name.type === "String"
+						? node.name.value
+						: node.name.name;
+
+				if (key.normalize(form) !== key) {
+					context.report({
+						loc: node.name.loc,
+						messageId: "unnormalizedKey",
+						data: {
+							key,
+						},
+					});
+				}
+			},
+		};
+	},
+};
+
 /**
  * @fileoverview Rule to detect unsafe values in JSON.
  * @author Bradley Meck Farias
@@ -598,12 +810,14 @@ const NON_ZERO = /[1-9]/u;
 //-----------------------------------------------------------------------------
 
 /** @type {NoUnsafeValuesRuleDefinition} */
-const rule$3 = {
+const rule$2 = {
 	meta: {
 		type: "problem",
 
 		docs: {
+			recommended: true,
 			description: "Disallow JSON values that are unsafe for interchange",
+			url: "https://github.com/eslint/json/tree/main/docs/rules/no-unsafe-values.md",
 		},
 
 		messages: {
@@ -714,78 +928,6 @@ const rule$3 = {
 	},
 };
 
-/**
- * @fileoverview Rule to detect unnormalized keys in JSON.
- * @author Bradley Meck Farias
- */
-
-//-----------------------------------------------------------------------------
-// Type Definitions
-//-----------------------------------------------------------------------------
-
-/**
- *
- * @typedef {"unnormalizedKey"} NoUnnormalizedKeysMessageIds
- * @typedef {{ form: string }} NoUnnormalizedKeysOptions
- * @typedef {JSONRuleDefinition<{ RuleOptions: [NoUnnormalizedKeysOptions], MessageIds: NoUnnormalizedKeysMessageIds }>} NoUnnormalizedKeysRuleDefinition
- */
-
-//-----------------------------------------------------------------------------
-// Rule Definition
-//-----------------------------------------------------------------------------
-
-/** @type {NoUnnormalizedKeysRuleDefinition} */
-const rule$2 = {
-	meta: {
-		type: "problem",
-
-		docs: {
-			description: "Disallow JSON keys that are not normalized",
-		},
-
-		messages: {
-			unnormalizedKey: "Unnormalized key '{{key}}' found.",
-		},
-
-		schema: [
-			{
-				type: "object",
-				properties: {
-					form: {
-						enum: ["NFC", "NFD", "NFKC", "NFKD"],
-					},
-				},
-				additionalProperties: false,
-			},
-		],
-	},
-
-	create(context) {
-		const form = context.options.length
-			? context.options[0].form
-			: undefined;
-
-		return {
-			Member(node) {
-				const key =
-					node.name.type === "String"
-						? node.name.value
-						: node.name.name;
-
-				if (key.normalize(form) !== key) {
-					context.report({
-						loc: node.name.loc,
-						messageId: "unnormalizedKey",
-						data: {
-							key,
-						},
-					});
-				}
-			},
-		};
-	},
-};
-
 /**
  * @fileoverview Rule to require JSON object keys to be sorted.
  * Copied largely from https://github.com/eslint/eslint/blob/main/lib/rules/sort-keys.js
@@ -888,7 +1030,9 @@ const rule$1 = {
 		],
 
 		docs: {
+			recommended: false,
 			description: `Require JSON object keys to be sorted`,
+			url: "https://github.com/eslint/json/tree/main/docs/rules/sort-keys.md",
 		},
 
 		messages: {
@@ -1017,7 +1161,7 @@ const rule$1 = {
 };
 
 /**
- * @fileoverview Rule to ensure top-level items are either an array or ojbect.
+ * @fileoverview Rule to ensure top-level items are either an array or object.
  * @author Joe Hildebrand
  */
 
@@ -1041,8 +1185,10 @@ const rule = {
 		type: "problem",
 
 		docs: {
+			recommended: false,
 			description:
 				"Require the JSON top-level value to be an array or object",
+			url: "https://github.com/eslint/json/tree/main/docs/rules/top-level-interop.md",
 		},
 
 		messages: {
@@ -1067,6 +1213,15 @@ const rule = {
 	},
 };
 
+var rules = {
+    "no-duplicate-keys": rule$5,
+    "no-empty-keys": rule$4,
+    "no-unnormalized-keys": rule$3,
+    "no-unsafe-values": rule$2,
+    "sort-keys": rule$1,
+    "top-level-interop": rule,
+};
+
 /**
  * @fileoverview JSON plugin.
  * @author Nicholas C. Zakas
@@ -1080,30 +1235,18 @@ const rule = {
 const plugin = {
 	meta: {
 		name: "@eslint/json",
-		version: "0.12.0", // x-release-please-version
+		version: "0.13.0", // x-release-please-version
 	},
 	languages: {
 		json: new JSONLanguage({ mode: "json" }),
 		jsonc: new JSONLanguage({ mode: "jsonc" }),
 		json5: new JSONLanguage({ mode: "json5" }),
 	},
-	rules: {
-		"no-duplicate-keys": rule$5,
-		"no-empty-keys": rule$4,
-		"no-unsafe-values": rule$3,
-		"no-unnormalized-keys": rule$2,
-		"sort-keys": rule$1,
-		"top-level-interop": rule,
-	},
+	rules,
 	configs: {
 		recommended: {
 			plugins: {},
-			rules: /** @type {const} */ ({
-				"json/no-duplicate-keys": "error",
-				"json/no-empty-keys": "error",
-				"json/no-unsafe-values": "error",
-				"json/no-unnormalized-keys": "error",
-			}),
+			rules: rules$1,
 		},
 	},
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint/json",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "JSON linting plugin for ESLint",
   "author": "Nicholas C. Zakas",
   "type": "module",
@@ -40,7 +40,14 @@
       "eslint --fix",
       "prettier --write"
     ],
-    "!(*.js)": "prettier --write --ignore-unknown"
+    "!(*.js)": "prettier --write --ignore-unknown",
+    "README.md": [
+      "npm run build:update-rules-docs"
+    ],
+    "{src/rules/*.js,tools/update-rules-docs.js}": [
+      "npm run build:update-rules-docs",
+      "git add README.md"
+    ]
   },
   "repository": {
     "type": "git",
@@ -53,14 +60,17 @@
   "scripts": {
     "build:dedupe-types": "node tools/dedupe-types.js dist/cjs/index.cjs dist/esm/index.js",
     "build:cts": "node tools/build-cts.js",
-    "build": "rollup -c && npm run build:dedupe-types && tsc -p tsconfig.esm.json && npm run build:cts",
+    "build:rules": "node tools/build-rules.js",
+    "build": "npm run build:rules && rollup -c && npm run build:dedupe-types && tsc -p tsconfig.esm.json && npm run build:cts",
     "build:readme": "node tools/update-readme.js",
-    "test:jsr": "npx jsr@latest publish --dry-run",
+    "build:update-rules-docs": "node tools/update-rules-docs.js",
+    "prepare": "npm run build",
     "pretest": "npm run build",
     "lint": "eslint",
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check .",
     "test": "mocha tests/**/*.js",
+    "test:jsr": "npx jsr@latest publish --dry-run",
     "test:coverage": "c8 npm test",
     "test:types": "tsc -p tests/types/tsconfig.json"
   },
@@ -73,25 +83,26 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
-    "@eslint/core": "^0.12.0",
-    "@eslint/plugin-kit": "^0.2.7",
+    "@eslint/core": "^0.14.0",
+    "@eslint/plugin-kit": "^0.3.1",
     "@humanwhocodes/momoa": "^3.3.4",
     "natural-compare": "^1.4.0"
   },
   "devDependencies": {
-    "c8": "^9.1.0",
+    "c8": "^10.1.3",
     "dedent": "^1.5.3",
-    "eslint": "^9.23.0",
+    "eslint": "^9.25.1",
     "eslint-config-eslint": "^11.0.0",
     "eslint-plugin-eslint-plugin": "^6.3.2",
     "got": "^14.4.2",
     "lint-staged": "^15.2.7",
-    "mocha": "^10.4.0",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mocha": "^11.3.0",
     "prettier": "^3.4.1",
-    "rollup": "^4.16.2",
+    "rollup": "^4.41.0",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-delete": "^3.0.1",
-    "typescript": "^5.4.5",
+    "typescript": "^5.8.3",
     "yorkie": "^2.0.0"
   },
   "engines": {