feat: Add token methods to JSONSourceCode (#112)

* feat: Add token methods to JSONSourceCode

fixes #83

* Remove package-lock.json

* Fix test comment

* Update src/languages/json-source-code.js

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Update src/languages/json-source-code.js

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Update src/languages/json-source-code.js

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Update tests/languages/json-source-code.test.js

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Remove getTokenOrCommentBefore/After

* Update tests/languages/json-source-code.test.js

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Fix formatting error

* Move comment processing into constructor

* Fix getTokenAfter() to work with nodes of multiple tokens

---------

Co-authored-by: 루밀LuMir <rpfos@naver.com>

Author: nzakas

.gitignore

@@ -60,3 +60,6 @@ dist
 *.code-workspace
 .idea
 .cursor
+
+# Lock files
+package-lock.json

docs/rules/no-unnormalized-keys.md

@@ -60,7 +60,6 @@ The following options are available on this rule:
 - `form: "NFC" | "NFD" | "NFKC" | "NFKD"` - specifies which Unicode normalization form to use when checking keys. Must be one of: `"NFC"` (default), `"NFD"`, `"NFKC"`, or `"NFKD"`.
 
     Each normalization form has specific characteristics:
-
     - **NFC**: Canonical Decomposition followed by Canonical Composition (default)
     - **NFD**: Canonical Decomposition
     - **NFKC**: Compatibility Decomposition followed by Canonical Composition

src/languages/json-source-code.js

@@ -59,6 +59,37 @@ 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
 //-----------------------------------------------------------------------------
@@ -93,11 +124,23 @@ export 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.
@@ -107,9 +150,11 @@ export 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;
 	}
 
 	/**
@@ -283,4 +328,83 @@ export 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;
+	}
 }