feat: add support for getLocFromIndex and getIndexFromLoc

packages/plugin-kit/README.md

@@ -205,6 +205,8 @@ The `TextSourceCodeBase` class is intended to be a base class that has several o
 
 - `lines` - an array of text lines that is created automatically when the constructor is called.
 - `getLoc(node)` - gets the location of a node. Works for nodes that have the ESLint-style `loc` property and nodes that have the Unist-style [`position` property](https://github.com/syntax-tree/unist?tab=readme-ov-file#position). If you're using an AST with a different location format, you'll still need to implement this method yourself.
+- `getLocFromIndex(index)` - Converts a source text index into a `{ line: number, column: number }` pair.
+- `getIndexFromLoc(loc)` - Converts a `{ line: number, column: number }` pair into a source text index.
 - `getRange(node)` - gets the range of a node within the source text. Works for nodes that have the ESLint-style `range` property and nodes that have the Unist-style [`position` property](https://github.com/syntax-tree/unist?tab=readme-ov-file#position). If you're using an AST with a different range format, you'll still need to implement this method yourself.
 - `getText(nodeOrToken, charsBefore, charsAfter)` - gets the source text for the given node or token that has range information attached. Optionally, can return additional characters before and after the given node or token. As long as `getRange()` is properly implemented, this method will just work.
 - `getAncestors(node)` - returns the ancestry of the node. In order for this to work, you must implement the `getParent()` method yourself.

packages/plugin-kit/src/source-code.js

@@ -63,6 +63,32 @@ function hasPosStyleRange(node) {
 	return "position" in node;
 }
 
+/**
+ * Performs binary search to find the line number containing a given target index.
+ * Returns the lower bound - the index of the first element greater than the target.
+ * **Please note that the `lineStartIndices` should be sorted in ascending order**.
+ * - Time Complexity: O(log n) - Significantly faster than linear search for large files.
+ * @param {number[]} lineStartIndices Sorted array of line start indices.
+ * @param {number} targetIndex The target index to find the line number for.
+ * @returns {number} The line number for the target index.
+ */
+function findLineNumberBinarySearch(lineStartIndices, targetIndex) {
+	let low = 0;
+	let high = lineStartIndices.length - 1;
+
+	while (low < high) {
+		const mid = ((low + high) / 2) | 0; // Use bitwise OR to floor the division.
+
+		if (targetIndex < lineStartIndices[mid]) {
+			high = mid;
+		} else {
+			low = mid + 1;
+		}
+	}
+
+	return low;
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -216,15 +242,27 @@ export class Directive {
 
 /**
  * Source Code Base Object
- * @template {SourceCodeBaseTypeOptions & {SyntaxElementWithLoc: object}} [Options=SourceCodeBaseTypeOptions & {SyntaxElementWithLoc: object}]
+ * @template {SourceCodeBaseTypeOptions & {RootNode: object, SyntaxElementWithLoc: object}} [Options=SourceCodeBaseTypeOptions & {RootNode: object, SyntaxElementWithLoc: object}]
  * @implements {TextSourceCode<Options>}
  */
 export class TextSourceCodeBase {
 	/**
 	 * The lines of text in the source code.
 	 * @type {Array<string>}
 	 */
-	#lines;
+	#lines = [];
+
+	/**
+	 * The indices of the start of each line in the source code.
+	 * @type {Array<number>}
+	 */
+	#lineStartIndices = [0];
+
+	/**
+	 * The pattern to match lineEndings in the source code.
+	 * @type {RegExp}
+	 */
+	#lineEndingPattern;
 
 	/**
 	 * The AST of the source code.
@@ -243,12 +281,102 @@ export class TextSourceCodeBase {
 	 * @param {Object} options The options for the instance.
 	 * @param {string} options.text The source code text.
 	 * @param {Options['RootNode']} options.ast The root AST node.
-	 * @param {RegExp} [options.lineEndingPattern] The pattern to match lineEndings in the source code.
+	 * @param {RegExp} [options.lineEndingPattern] The pattern to match lineEndings in the source code. Defaults to `/\r?\n/u`.
 	 */
 	constructor({ text, ast, lineEndingPattern = /\r?\n/u }) {
 		this.ast = ast;
 		this.text = text;
-		this.#lines = text.split(lineEndingPattern);
+		this.#lineEndingPattern = lineEndingPattern;
+	}
+
+	/**
+	 * Parses the source text into lines and updates the `#lines` and `#lineStartIndices` properties.
+	 * @param {string} text The source text to parse into lines.
+	 * @returns {boolean} `true` if the text was successfully parsed into lines, `false` otherwise.
+	 */
+	#parseText(text) {
+		// Create a new RegExp instance to avoid lastIndex issues.
+		const match = structuredClone(this.#lineEndingPattern).exec(text);
+
+		if (!match) {
+			return false;
+		}
+
+		this.#lines.push(text.slice(0, match.index));
+		this.#lineStartIndices.push(
+			(this.#lineStartIndices.at(-1) ?? 0) +
+				match.index +
+				match[0].length,
+		);
+
+		return true;
+	}
+
+	/**
+	 * Ensures `#lines` is lazily calculated from the source text.
+	 * @returns {void}
+	 */
+	#ensureLines() {
+		// If `#lines` has already been calculated, do nothing.
+		if (this.#lines.length === this.#lineStartIndices.length) {
+			return;
+		}
+
+		while (
+			this.#parseText(this.text.slice(this.#lineStartIndices.at(-1)))
+		) {
+			// Continue parsing until no more matches are found.
+		}
+
+		this.#lines.push(this.text.slice(this.#lineStartIndices.at(-1)));
+
+		Object.freeze(this.#lines);
+	}
+
+	/**
+	 * Ensures `#lineStartIndices` is lazily calculated up to the specified index.
+	 * @param {number} index The index of a character in a file.
+	 * @returns {void}
+	 */
+	#ensureLineStartIndicesFromIndex(index) {
+		// If we've already parsed up to or beyond this index, do nothing.
+		if (index <= (this.#lineStartIndices.at(-1) ?? 0)) {
+			return;
+		}
+
+		while (
+			this.#parseText(
+				this.text.slice(this.#lineStartIndices.at(-1), index + 1),
+			)
+		) {
+			// Continue parsing until no more matches are found.
+		}
+	}
+
+	/**
+	 * Ensures `#lineStartIndices` is lazily calculated up to the specified loc.
+	 * @param {Object} loc A line/column location.
+	 * @param {number} loc.line The line number of the location. (0 or 1-indexed based on language.)
+	 * @param {number} lineStart The line number at which the parser starts counting.
+	 * @returns {void}
+	 */
+	#ensureLineStartIndicesFromLoc(loc, lineStart) {
+		// Calculate line indices up to the potentially next line, as it is needed for the follow‑up calculation.
+		const nextLocLineIndex = loc.line - lineStart + 1;
+		const lastCalculatedLineIndex = this.#lineStartIndices.length - 1;
+		let additionalLinesNeeded = nextLocLineIndex - lastCalculatedLineIndex;
+
+		// If we've already parsed up to or beyond this line, do nothing.
+		if (additionalLinesNeeded <= 0) {
+			return;
+		}
+
+		while (
+			this.#parseText(this.text.slice(this.#lineStartIndices.at(-1))) &&
+			Boolean(additionalLinesNeeded--)
+		) {
+			// Continue parsing until no more matches are found.
+		}
 	}
 
 	/**
@@ -271,6 +399,135 @@ export class TextSourceCodeBase {
 		);
 	}
 
+	/**
+	 * Converts a source text index into a `{ line: number, column: number }` pair.
+	 * @param {number} index The index of a character in a file.
+	 * @throws {TypeError|RangeError} If non-numeric index or index out of range.
+	 * @returns {{line: number, column: number}} A `{ line: number, column: number }` location object with 0 or 1-indexed line and 0 or 1-indexed column based on language.
+	 * @public
+	 */
+	getLocFromIndex(index) {
+		if (typeof index !== "number") {
+			throw new TypeError("Expected `index` to be a number.");
+		}
+
+		if (index < 0 || index > this.text.length) {
+			throw new RangeError(
+				`Index out of range (requested index ${index}, but source text has length ${this.text.length}).`,
+			);
+		}
+
+		const {
+			start: { line: lineStart, column: columnStart },
+			end: { line: lineEnd, column: columnEnd },
+		} = this.getLoc(this.ast);
+
+		// If the index is at the start, return the start location of the root node.
+		if (index === 0) {
+			return {
+				line: lineStart,
+				column: columnStart,
+			};
+		}
+
+		// If the index is `this.text.length`, return the location one "spot" past the last character of the file.
+		if (index === this.text.length) {
+			return {
+				line: lineEnd,
+				column: columnEnd,
+			};
+		}
+
+		// Ensure `#lineStartIndices` are lazily calculated.
+		this.#ensureLineStartIndicesFromIndex(index);
+
+		/*
+		 * To figure out which line `index` is on, determine the last place at which index could
+		 * be inserted into `#lineStartIndices` to keep the list sorted.
+		 */
+		const lineNumber =
+			(index >= (this.#lineStartIndices.at(-1) ?? 0)
+				? this.#lineStartIndices.length
+				: findLineNumberBinarySearch(this.#lineStartIndices, index)) -
+			1 +
+			lineStart;
+
+		return {
+			line: lineNumber,
+			column:
+				index -
+				this.#lineStartIndices[lineNumber - lineStart] +
+				columnStart,
+		};
+	}
+
+	/**
+	 * Converts a `{ line: number, column: number }` pair into a source text index.
+	 * @param {Object} loc A line/column location.
+	 * @param {number} loc.line The line number of the location. (0 or 1-indexed based on language.)
+	 * @param {number} loc.column The column number of the location. (0 or 1-indexed based on language.)
+	 * @throws {TypeError|RangeError} If `loc` is not an object with a numeric
+	 * `line` and `column`, if the `line` is less than or equal to zero or
+	 * the `line` or `column` is out of the expected range.
+	 * @returns {number} The index of the line/column location in a file.
+	 * @public
+	 */
+	getIndexFromLoc(loc) {
+		if (
+			loc === null ||
+			typeof loc !== "object" ||
+			typeof loc.line !== "number" ||
+			typeof loc.column !== "number"
+		) {
+			throw new TypeError(
+				"Expected `loc` to be an object with numeric `line` and `column` properties.",
+			);
+		}
+
+		const {
+			start: { line: lineStart, column: columnStart },
+			end: { line: lineEnd, column: columnEnd },
+		} = this.getLoc(this.ast);
+
+		if (loc.line < lineStart || lineEnd < loc.line) {
+			throw new RangeError(
+				`Line number out of range (line ${loc.line} requested). Valid range: ${lineStart}-${lineEnd}`,
+			);
+		}
+
+		// If the loc is at the start, return the start index of the root node.
+		if (loc.line === lineStart && loc.column === columnStart) {
+			return 0;
+		}
+
+		// If the loc is at the end, return the index one "spot" past the last character of the file.
+		if (loc.line === lineEnd && loc.column === columnEnd) {
+			return this.text.length;
+		}
+
+		// Ensure `#lineStartIndices` are lazily calculated.
+		this.#ensureLineStartIndicesFromLoc(loc, lineStart);
+
+		const isLastLine = loc.line === lineEnd;
+		const lineStartIndex = this.#lineStartIndices[loc.line - lineStart];
+		const lineEndIndex = isLastLine
+			? this.text.length
+			: this.#lineStartIndices[loc.line - lineStart + 1];
+		const positionIndex = lineStartIndex + loc.column - columnStart;
+
+		if (
+			loc.column < columnStart ||
+			(isLastLine && positionIndex > lineEndIndex) ||
+			(!isLastLine && positionIndex >= lineEndIndex)
+		) {
+			throw new RangeError(
+				`Column number out of range (column ${loc.column} requested). Valid range for line ${loc.line}: ${columnStart}-${lineEndIndex - lineStartIndex + columnStart + (isLastLine ? 0 : -1)}`,
+			);
+		}
+
+		return positionIndex;
+	}
+
 	/**
 	 * Returns the range information for the given node or token.
 	 * @param {Options['SyntaxElementWithLoc']} nodeOrToken The node or token to get the range information for.
@@ -356,6 +613,8 @@ export class TextSourceCodeBase {
 	 * @public
 	 */
 	get lines() {
+		this.#ensureLines(); // Ensure `#lines` is lazily calculated.
+
 		return this.#lines;
 	}