bahlint 28.58.6934

package/lib/linter/rule-fixer.js

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview An object that creates fix commands for rules.
+ * @author Nicholas C. Zakas
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Typedefs
+//------------------------------------------------------------------------------
+
+/**
+ * @import { SourceRange } from "@eslint/core";
+ */
+
+/* eslint class-methods-use-this: off -- Methods desired on instance */
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+// none!
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+/**
+ * Creates a fix command that inserts text at the specified index in the source text.
+ * @param {number} index The 0-based index at which to insert the new text.
+ * @param {string} text The text to insert.
+ * @returns {Object} The fix command.
+ * @private
+ */
+function insertTextAt(index, text) {
+	return {
+		range: [index, index],
+		text,
+	};
+}
+
+/**
+ * Asserts that the provided text is a string.
+ * @param {unknown} text The text to validate.
+ * @returns {void}
+ * @throws {TypeError} If `text` is not a string.
+ */
+function assertIsString(text) {
+	if (typeof text !== "string") {
+		throw new TypeError("'text' must be a string");
+	}
+}
+
+//------------------------------------------------------------------------------
+// Public Interface
+//------------------------------------------------------------------------------
+
+/**
+ * Creates code fixing commands for rules.
+ */
+class RuleFixer {
+	/**
+	 * The source code object representing the text to be fixed.
+	 * @type {SourceCode}
+	 */
+	#sourceCode;
+
+	/**
+	 * Creates a new instance.
+	 * @param {Object} options The options for the fixer.
+	 * @param {SourceCode} options.sourceCode The source code object representing the text to be fixed.
+	 */
+	constructor({ sourceCode }) {
+		this.#sourceCode = sourceCode;
+	}
+
+	/**
+	 * Creates a fix command that inserts text after the given node or token.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {ASTNode|Token} nodeOrToken The node or token to insert after.
+	 * @param {string} text The text to insert.
+	 * @returns {Object} The fix command.
+	 * @throws {TypeError} If `text` is not a string.
+	 */
+	insertTextAfter(nodeOrToken, text) {
+		assertIsString(text);
+
+		const range = this.#sourceCode.getRange(nodeOrToken);
+
+		return this.insertTextAfterRange(range, text);
+	}
+
+	/**
+	 * Creates a fix command that inserts text after the specified range in the source text.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {SourceRange} range The range to replace, first item is start of range, second
+	 *      is end of range.
+	 * @param {string} text The text to insert.
+	 * @returns {Object} The fix command.
+	 * @throws {TypeError} If `text` is not a string.
+	 */
+	insertTextAfterRange(range, text) {
+		assertIsString(text);
+
+		return insertTextAt(range[1], text);
+	}
+
+	/**
+	 * Creates a fix command that inserts text before the given node or token.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {ASTNode|Token} nodeOrToken The node or token to insert before.
+	 * @param {string} text The text to insert.
+	 * @returns {Object} The fix command.
+	 * @throws {TypeError} If `text` is not a string.
+	 */
+	insertTextBefore(nodeOrToken, text) {
+		assertIsString(text);
+
+		const range = this.#sourceCode.getRange(nodeOrToken);
+
+		return this.insertTextBeforeRange(range, text);
+	}
+
+	/**
+	 * Creates a fix command that inserts text before the specified range in the source text.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {SourceRange} range The range to replace, first item is start of range, second
+	 *      is end of range.
+	 * @param {string} text The text to insert.
+	 * @returns {Object} The fix command.
+	 * @throws {TypeError} If `text` is not a string.
+	 */
+	insertTextBeforeRange(range, text) {
+		assertIsString(text);
+
+		return insertTextAt(range[0], text);
+	}
+
+	/**
+	 * Creates a fix command that replaces text at the node or token.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {ASTNode|Token} nodeOrToken The node or token to remove.
+	 * @param {string} text The text to insert.
+	 * @returns {Object} The fix command.
+	 * @throws {TypeError} If `text` is not a string.
+	 */
+	replaceText(nodeOrToken, text) {
+		assertIsString(text);
+
+		const range = this.#sourceCode.getRange(nodeOrToken);
+
+		return this.replaceTextRange(range, text);
+	}
+
+	/**
+	 * Creates a fix command that replaces text at the specified range in the source text.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {SourceRange} range The range to replace, first item is start of range, second
+	 *      is end of range.
+	 * @param {string} text The text to insert.
+	 * @returns {Object} The fix command.
+	 * @throws {TypeError} If `text` is not a string.
+	 */
+	replaceTextRange(range, text) {
+		assertIsString(text);
+
+		return {
+			range,
+			text,
+		};
+	}
+
+	/**
+	 * Creates a fix command that removes the node or token from the source.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {ASTNode|Token} nodeOrToken The node or token to remove.
+	 * @returns {Object} The fix command.
+	 */
+	remove(nodeOrToken) {
+		const range = this.#sourceCode.getRange(nodeOrToken);
+
+		return this.removeRange(range);
+	}
+
+	/**
+	 * Creates a fix command that removes the specified range of text from the source.
+	 * The fix is not applied until applyFixes() is called.
+	 * @param {SourceRange} range The range to remove, first item is start of range, second
+	 *      is end of range.
+	 * @returns {Object} The fix command.
+	 */
+	removeRange(range) {
+		return {
+			range,
+			text: "",
+		};
+	}
+}
+
+module.exports = { RuleFixer };

package/lib/linter/source-code-fixer.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview An object that caches and applies source code fixes.
+ * @author Nicholas C. Zakas
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const debug = require("debug")("eslint:source-code-fixer");
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const BOM = "\uFEFF";
+
+/**
+ * Compares items in a messages array by range.
+ * @param {Message} a The first message.
+ * @param {Message} b The second message.
+ * @returns {number} -1 if a comes before b, 1 if a comes after b, 0 if equal.
+ * @private
+ */
+function compareMessagesByFixRange(a, b) {
+	return a.fix.range[0] - b.fix.range[0] || a.fix.range[1] - b.fix.range[1];
+}
+
+/**
+ * Compares items in a messages array by line and column.
+ * @param {Message} a The first message.
+ * @param {Message} b The second message.
+ * @returns {number} -1 if a comes before b, 1 if a comes after b, 0 if equal.
+ * @private
+ */
+function compareMessagesByLocation(a, b) {
+	return a.line - b.line || a.column - b.column;
+}
+
+//------------------------------------------------------------------------------
+// Public Interface
+//------------------------------------------------------------------------------
+
+/**
+ * Utility for apply fixes to source code.
+ * @constructor
+ */
+function SourceCodeFixer() {
+	Object.freeze(this);
+}
+
+/**
+ * Applies the fixes specified by the messages to the given text. Tries to be
+ * smart about the fixes and won't apply fixes over the same area in the text.
+ * @param {string} sourceText The text to apply the changes to.
+ * @param {Message[]} messages The array of messages reported by ESLint.
+ * @param {boolean|Function} [shouldFix=true] Determines whether each message should be fixed
+ * @returns {Object} An object containing the fixed text and any unfixed messages.
+ */
+SourceCodeFixer.applyFixes = function (sourceText, messages, shouldFix) {
+	debug("Applying fixes");
+
+	if (shouldFix === false) {
+		debug("shouldFix parameter was false, not attempting fixes");
+		return {
+			fixed: false,
+			messages,
+			output: sourceText,
+		};
+	}
+
+	// clone the array
+	const remainingMessages = [],
+		fixes = [],
+		bom = sourceText.startsWith(BOM) ? BOM : "",
+		text = bom ? sourceText.slice(1) : sourceText;
+	let lastPos = Number.NEGATIVE_INFINITY,
+		output = bom;
+
+	/**
+	 * Try to use the 'fix' from a problem.
+	 * @param {Message} problem The message object to apply fixes from
+	 * @returns {boolean} Whether fix was successfully applied
+	 */
+	function attemptFix(problem) {
+		const fix = problem.fix;
+		const start = fix.range[0];
+		const end = fix.range[1];
+
+		// Remain it as a problem if it's overlapped or it's a negative range
+		if (lastPos >= start || start > end) {
+			remainingMessages.push(problem);
+			return false;
+		}
+
+		// Remove BOM.
+		if (
+			(start < 0 && end >= 0) ||
+			(start === 0 && fix.text.startsWith(BOM))
+		) {
+			output = "";
+		}
+
+		// Make output to this fix.
+		output += text.slice(Math.max(0, lastPos), Math.max(0, start));
+		output += fix.text;
+		lastPos = end;
+		return true;
+	}
+
+	messages.forEach(problem => {
+		if (Object.hasOwn(problem, "fix") && problem.fix) {
+			fixes.push(problem);
+		} else {
+			remainingMessages.push(problem);
+		}
+	});
+
+	if (fixes.length) {
+		debug("Found fixes to apply");
+		let fixesWereApplied = false;
+
+		for (const problem of fixes.sort(compareMessagesByFixRange)) {
+			if (typeof shouldFix !== "function" || shouldFix(problem)) {
+				attemptFix(problem);
+
+				/*
+				 * The only time attemptFix will fail is if a previous fix was
+				 * applied which conflicts with it.  So we can mark this as true.
+				 */
+				fixesWereApplied = true;
+			} else {
+				remainingMessages.push(problem);
+			}
+		}
+		output += text.slice(Math.max(0, lastPos));
+
+		return {
+			fixed: fixesWereApplied,
+			messages: remainingMessages.sort(compareMessagesByLocation),
+			output,
+		};
+	}
+
+	debug("No fixes to apply");
+	return {
+		fixed: false,
+		messages,
+		output: bom + text,
+	};
+};
+
+module.exports = SourceCodeFixer;

package/lib/linter/source-code-traverser.js

@@ -0,0 +1,333 @@
+/**
+ * @fileoverview Traverser for SourceCode objects.
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const { parse, matches } = require("./esquery");
+const vk = require("eslint-visitor-keys");
+
+//-----------------------------------------------------------------------------
+// Typedefs
+//-----------------------------------------------------------------------------
+
+/**
+ * @import { Language, SourceCode } from "@eslint/core";
+ * @import { ESQueryOptions } from "esquery";
+ * @import { ESQueryParsedSelector } from "./esquery.js";
+ * @import { SourceCodeVisitor } from "./source-code-visitor.js";
+ */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+const STEP_KIND_VISIT = 1;
+const STEP_KIND_CALL = 2;
+
+/**
+ * Compares two ESQuery selectors by specificity.
+ * @param {ESQueryParsedSelector} a The first selector to compare.
+ * @param {ESQueryParsedSelector} b The second selector to compare.
+ * @returns {number} A negative number if `a` is less specific than `b` or they are equally specific and `a` <= `b` alphabetically, a positive number if `a` is more specific than `b`.
+ */
+function compareSpecificity(a, b) {
+	return a.compare(b);
+}
+
+/**
+ * Helper to wrap ESQuery operations.
+ */
+class ESQueryHelper {
+	/**
+	 * Creates a new instance.
+	 * @param {SourceCodeVisitor} visitor The visitor containing the functions to call.
+	 * @param {ESQueryOptions} esqueryOptions `esquery` options for traversing custom nodes.
+	 */
+	constructor(visitor, esqueryOptions) {
+		/**
+		 * The visitor to use during traversal.
+		 * @type {SourceCodeVisitor}
+		 */
+		this.visitor = visitor;
+
+		/**
+		 * The options for `esquery` to use during matching.
+		 * @type {ESQueryOptions}
+		 */
+		this.esqueryOptions = esqueryOptions;
+
+		/**
+		 * A map of node type to selectors targeting that node type on the
+		 * enter phase of traversal.
+		 * @type {Map<string, ESQueryParsedSelector[]>}
+		 */
+		this.enterSelectorsByNodeType = new Map();
+
+		/**
+		 * A map of node type to selectors targeting that node type on the
+		 * exit phase of traversal.
+		 * @type {Map<string, ESQueryParsedSelector[]>}
+		 */
+		this.exitSelectorsByNodeType = new Map();
+
+		/**
+		 * An array of selectors that match any node type on the
+		 * enter phase of traversal.
+		 * @type {ESQueryParsedSelector[]}
+		 */
+		this.anyTypeEnterSelectors = [];
+
+		/**
+		 * An array of selectors that match any node type on the
+		 * exit phase of traversal.
+		 * @type {ESQueryParsedSelector[]}
+		 */
+		this.anyTypeExitSelectors = [];
+
+		visitor.forEachName(rawSelector => {
+			const selector = parse(rawSelector);
+
+			/*
+			 * If this selector has identified specific node types,
+			 * add it to the map for these node types for faster lookup.
+			 */
+			if (selector.nodeTypes) {
+				const typeMap = selector.isExit
+					? this.exitSelectorsByNodeType
+					: this.enterSelectorsByNodeType;
+
+				selector.nodeTypes.forEach(nodeType => {
+					if (!typeMap.has(nodeType)) {
+						typeMap.set(nodeType, []);
+					}
+					typeMap.get(nodeType).push(selector);
+				});
+				return;
+			}
+
+			/*
+			 * Remaining selectors are added to the "any type" selectors
+			 * list for the appropriate phase of traversal. This ensures
+			 * that all selectors will still be applied even if no
+			 * specific node type is matched.
+			 */
+			const selectors = selector.isExit
+				? this.anyTypeExitSelectors
+				: this.anyTypeEnterSelectors;
+
+			selectors.push(selector);
+		});
+
+		// sort all selectors by specificity for prioritizing call order
+		this.anyTypeEnterSelectors.sort(compareSpecificity);
+		this.anyTypeExitSelectors.sort(compareSpecificity);
+		this.enterSelectorsByNodeType.forEach(selectorList =>
+			selectorList.sort(compareSpecificity),
+		);
+		this.exitSelectorsByNodeType.forEach(selectorList =>
+			selectorList.sort(compareSpecificity),
+		);
+	}
+
+	/**
+	 * Checks if a node matches a given selector.
+	 * @param {ASTNode} node The node to check
+	 * @param {ASTNode[]} ancestry The ancestry of the node being checked.
+	 * @param {ESQueryParsedSelector} selector An AST selector descriptor
+	 * @returns {boolean} `true` if the selector matches the node, `false` otherwise
+	 */
+	matches(node, ancestry, selector) {
+		return matches(node, selector.root, ancestry, this.esqueryOptions);
+	}
+
+	/**
+	 * Calculates all appropriate selectors to a node, in specificity order
+	 * @param {ASTNode} node The node to check
+	 * @param {ASTNode[]} ancestry The ancestry of the node being checked.
+	 * @param {boolean} isExit `false` if the node is currently being entered, `true` if it's currently being exited
+	 * @returns {string[]} An array of selectors that match the node.
+	 */
+	calculateSelectors(node, ancestry, isExit) {
+		const nodeTypeKey = this.esqueryOptions?.nodeTypeKey || "type";
+		const selectors = [];
+
+		/*
+		 * Get the selectors that may match this node. First, check
+		 * to see if the node type has specific selectors,
+		 * then gather the "any type" selectors.
+		 */
+		const selectorsByNodeType =
+			(isExit
+				? this.exitSelectorsByNodeType
+				: this.enterSelectorsByNodeType
+			).get(node[nodeTypeKey]) || [];
+		const anyTypeSelectors = isExit
+			? this.anyTypeExitSelectors
+			: this.anyTypeEnterSelectors;
+
+		/*
+		 * selectorsByNodeType and anyTypeSelectors were already sorted by specificity in the constructor.
+		 * Iterate through each of them, applying selectors in the right order.
+		 */
+		let selectorsByNodeTypeIndex = 0;
+		let anyTypeSelectorsIndex = 0;
+
+		while (
+			selectorsByNodeTypeIndex < selectorsByNodeType.length ||
+			anyTypeSelectorsIndex < anyTypeSelectors.length
+		) {
+			/*
+			 * If we've already exhausted the selectors for this node type,
+			 * or if the next any type selector is more specific than the
+			 * next selector for this node type, apply the any type selector.
+			 */
+			const hasMoreNodeTypeSelectors =
+				selectorsByNodeTypeIndex < selectorsByNodeType.length;
+			const hasMoreAnyTypeSelectors =
+				anyTypeSelectorsIndex < anyTypeSelectors.length;
+			const anyTypeSelector = anyTypeSelectors[anyTypeSelectorsIndex];
+			const nodeTypeSelector =
+				selectorsByNodeType[selectorsByNodeTypeIndex];
+
+			// Only compare specificity if both selectors exist
+			const isAnyTypeSelectorLessSpecific =
+				hasMoreAnyTypeSelectors &&
+				hasMoreNodeTypeSelectors &&
+				anyTypeSelector.compare(nodeTypeSelector) < 0;
+
+			if (!hasMoreNodeTypeSelectors || isAnyTypeSelectorLessSpecific) {
+				anyTypeSelectorsIndex++;
+
+				if (this.matches(node, ancestry, anyTypeSelector)) {
+					selectors.push(anyTypeSelector.source);
+				}
+			} else {
+				selectorsByNodeTypeIndex++;
+
+				if (this.matches(node, ancestry, nodeTypeSelector)) {
+					selectors.push(nodeTypeSelector.source);
+				}
+			}
+		}
+
+		return selectors;
+	}
+}
+
+//------------------------------------------------------------------------------
+// Public Interface
+//------------------------------------------------------------------------------
+
+/**
+ * Traverses source code and ensures that visitor methods are called when
+ * entering and leaving each node.
+ */
+class SourceCodeTraverser {
+	/**
+	 * The language of the source code being traversed.
+	 * @type {Language}
+	 */
+	#language;
+
+	/**
+	 * Map of languages to instances of this class.
+	 * @type {WeakMap<Language, SourceCodeTraverser>}
+	 */
+	static instances = new WeakMap();
+
+	/**
+	 * Creates a new instance.
+	 * @param {Language} language The language of the source code being traversed.
+	 */
+	constructor(language) {
+		this.#language = language;
+	}
+
+	static getInstance(language) {
+		if (!this.instances.has(language)) {
+			this.instances.set(language, new this(language));
+		}
+
+		return this.instances.get(language);
+	}
+
+	/**
+	 * Traverses the given source code synchronously.
+	 * @param {SourceCode} sourceCode The source code to traverse.
+	 * @param {SourceCodeVisitor} visitor The emitter to use for events.
+	 * @param {Object} options Options for traversal.
+	 * @param {ReturnType<SourceCode["traverse"]>} options.steps The steps to take during traversal.
+	 * @returns {void}
+	 * @throws {Error} If an error occurs during traversal.
+	 */
+	traverseSync(sourceCode, visitor, { steps } = {}) {
+		const esquery = new ESQueryHelper(visitor, {
+			visitorKeys: sourceCode.visitorKeys ?? this.#language.visitorKeys,
+			fallback: vk.getKeys,
+			matchClass: this.#language.matchesSelectorClass ?? (() => false),
+			nodeTypeKey: this.#language.nodeTypeKey,
+		});
+
+		const currentAncestry = [];
+
+		for (const step of steps ?? sourceCode.traverse()) {
+			switch (step.kind) {
+				case STEP_KIND_VISIT: {
+					try {
+						if (step.phase === 1) {
+							esquery
+								.calculateSelectors(
+									step.target,
+									currentAncestry,
+									false,
+								)
+								.forEach(selector => {
+									visitor.callSync(
+										selector,
+										...(step.args ?? [step.target]),
+									);
+								});
+							currentAncestry.unshift(step.target);
+						} else {
+							currentAncestry.shift();
+							esquery
+								.calculateSelectors(
+									step.target,
+									currentAncestry,
+									true,
+								)
+								.forEach(selector => {
+									visitor.callSync(
+										selector,
+										...(step.args ?? [step.target]),
+									);
+								});
+						}
+					} catch (err) {
+						err.currentNode = step.target;
+						throw err;
+					}
+					break;
+				}
+
+				case STEP_KIND_CALL: {
+					visitor.callSync(step.target, ...step.args);
+					break;
+				}
+
+				default:
+					throw new Error(
+						`Invalid traversal step found: "${step.kind}".`,
+					);
+			}
+		}
+	}
+}
+
+module.exports = { SourceCodeTraverser };