eslint 8.57.1 → 9.39.1

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 };

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

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview SourceCodeVisitor class
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+const emptyArray = Object.freeze([]);
+
+//------------------------------------------------------------------------------
+// Exports
+//------------------------------------------------------------------------------
+
+/**
+ * A structure to hold a list of functions to call for a given name.
+ * This is used to allow multiple rules to register functions for a given name
+ * without having to know about each other.
+ */
+class SourceCodeVisitor {
+	/**
+	 * The functions to call for a given name.
+	 * @type {Map<string, Function[]>}
+	 */
+	#functions = new Map();
+
+	/**
+	 * Adds a function to the list of functions to call for a given name.
+	 * @param {string} name The name of the function to call.
+	 * @param {Function} func The function to call.
+	 * @returns {void}
+	 */
+	add(name, func) {
+		if (this.#functions.has(name)) {
+			this.#functions.get(name).push(func);
+		} else {
+			this.#functions.set(name, [func]);
+		}
+	}
+
+	/**
+	 * Gets the list of functions to call for a given name.
+	 * @param {string} name The name of the function to call.
+	 * @returns {Function[]} The list of functions to call.
+	 */
+	get(name) {
+		if (this.#functions.has(name)) {
+			return this.#functions.get(name);
+		}
+
+		return emptyArray;
+	}
+
+	/**
+	 * Iterates over all names and calls the callback with the name.
+	 * @param {(name:string) => void} callback The callback to call for each name.
+	 * @returns {void}
+	 */
+	forEachName(callback) {
+		this.#functions.forEach((funcs, name) => {
+			callback(name);
+		});
+	}
+
+	/**
+	 * Calls the functions for a given name with the given arguments.
+	 * @param {string} name The name of the function to call.
+	 * @param {any[]} args The arguments to pass to the function.
+	 * @returns {void}
+	 */
+	callSync(name, ...args) {
+		if (this.#functions.has(name)) {
+			this.#functions.get(name).forEach(func => func(...args));
+		}
+	}
+}
+
+module.exports = { SourceCodeVisitor };

package/lib/linter/timing.js

@@ -5,6 +5,8 @@
 
 "use strict";
 
+const { startTime, endTime } = require("../shared/stats");
+
 //------------------------------------------------------------------------------
 // Helpers
 //------------------------------------------------------------------------------
@@ -13,26 +15,26 @@
 /**
  * Align the string to left
  * @param {string} str string to evaluate
- * @param {int} len length of the string
+ * @param {number} len length of the string
  * @param {string} ch delimiter character
  * @returns {string} modified string
  * @private
  */
 function alignLeft(str, len, ch) {
-    return str + new Array(len - str.length + 1).join(ch || " ");
+	return str + new Array(len - str.length + 1).join(ch || " ");
 }
 
 /* c8 ignore next */
 /**
  * Align the string to right
  * @param {string} str string to evaluate
- * @param {int} len length of the string
+ * @param {number} len length of the string
  * @param {string} ch delimiter character
  * @returns {string} modified string
  * @private
  */
 function alignRight(str, len, ch) {
-    return new Array(len - str.length + 1).join(ch || " ") + str;
+	return new Array(len - str.length + 1).join(ch || " ") + str;
 }
 
 //------------------------------------------------------------------------------
@@ -49,19 +51,21 @@ const ALIGN = [alignLeft, alignRight, alignRight];
  * @returns {number} the number of rules to show
  */
 function getListSize() {
-    const MINIMUM_SIZE = 10;
+	const MINIMUM_SIZE = 10;
 
-    if (typeof process.env.TIMING !== "string") {
-        return MINIMUM_SIZE;
-    }
+	if (typeof process.env.TIMING !== "string") {
+		return MINIMUM_SIZE;
+	}
 
-    if (process.env.TIMING.toLowerCase() === "all") {
-        return Number.POSITIVE_INFINITY;
-    }
+	if (process.env.TIMING.toLowerCase() === "all") {
+		return Number.POSITIVE_INFINITY;
+	}
 
-    const TIMING_ENV_VAR_AS_INTEGER = Number.parseInt(process.env.TIMING, 10);
+	const TIMING_ENV_VAR_AS_INTEGER = Number.parseInt(process.env.TIMING, 10);
 
-    return TIMING_ENV_VAR_AS_INTEGER > 10 ? TIMING_ENV_VAR_AS_INTEGER : MINIMUM_SIZE;
+	return TIMING_ENV_VAR_AS_INTEGER > 10
+		? TIMING_ENV_VAR_AS_INTEGER
+		: MINIMUM_SIZE;
 }
 
 /* c8 ignore next */
@@ -72,90 +76,134 @@ function getListSize() {
  * @private
  */
 function display(data) {
-    let total = 0;
-    const rows = Object.keys(data)
-        .map(key => {
-            const time = data[key];
-
-            total += time;
-            return [key, time];
-        })
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, getListSize());
-
-    rows.forEach(row => {
-        row.push(`${(row[1] * 100 / total).toFixed(1)}%`);
-        row[1] = row[1].toFixed(3);
-    });
-
-    rows.unshift(HEADERS);
-
-    const widths = [];
-
-    rows.forEach(row => {
-        const len = row.length;
-
-        for (let i = 0; i < len; i++) {
-            const n = row[i].length;
-
-            if (!widths[i] || n > widths[i]) {
-                widths[i] = n;
-            }
-        }
-    });
-
-    const table = rows.map(row => (
-        row
-            .map((cell, index) => ALIGN[index](cell, widths[index]))
-            .join(" | ")
-    ));
-
-    table.splice(1, 0, widths.map((width, index) => {
-        const extraAlignment = index !== 0 && index !== widths.length - 1 ? 2 : 1;
-
-        return ALIGN[index](":", width + extraAlignment, "-");
-    }).join("|"));
-
-    console.log(table.join("\n")); // eslint-disable-line no-console -- Debugging function
+	let total = 0;
+	const rows = Object.keys(data)
+		.map(key => {
+			const time = data[key];
+
+			total += time;
+			return [key, time];
+		})
+		.sort((a, b) => b[1] - a[1])
+		.slice(0, getListSize());
+
+	rows.forEach(row => {
+		row.push(`${((row[1] * 100) / total).toFixed(1)}%`);
+		row[1] = row[1].toFixed(3);
+	});
+
+	rows.unshift(HEADERS);
+
+	const widths = [];
+
+	rows.forEach(row => {
+		const len = row.length;
+
+		for (let i = 0; i < len; i++) {
+			const n = row[i].length;
+
+			if (!widths[i] || n > widths[i]) {
+				widths[i] = n;
+			}
+		}
+	});
+
+	const table = rows.map(row =>
+		row.map((cell, index) => ALIGN[index](cell, widths[index])).join(" | "),
+	);
+
+	table.splice(
+		1,
+		0,
+		widths
+			.map((width, index) => {
+				const extraAlignment =
+					index !== 0 && index !== widths.length - 1 ? 2 : 1;
+
+				return ALIGN[index](":", width + extraAlignment, "-");
+			})
+			.join("|"),
+	);
+
+	console.log(table.join("\n")); // eslint-disable-line no-console -- Debugging function
 }
 
 /* c8 ignore next */
-module.exports = (function() {
-
-    const data = Object.create(null);
-
-    /**
-     * Time the run
-     * @param {any} key key from the data object
-     * @param {Function} fn function to be called
-     * @returns {Function} function to be executed
-     * @private
-     */
-    function time(key, fn) {
-        if (typeof data[key] === "undefined") {
-            data[key] = 0;
-        }
-
-        return function(...args) {
-            let t = process.hrtime();
-            const result = fn(...args);
-
-            t = process.hrtime(t);
-            data[key] += t[0] * 1e3 + t[1] / 1e6;
-            return result;
-        };
-    }
-
-    if (enabled) {
-        process.on("exit", () => {
-            display(data);
-        });
-    }
-
-    return {
-        time,
-        enabled,
-        getListSize
-    };
-
-}());
+module.exports = (function () {
+	const data = Object.create(null);
+	let displayEnabled = true;
+
+	/**
+	 * Time the run
+	 * @param {any} key key from the data object
+	 * @param {Function} fn function to be called
+	 * @param {boolean} stats if 'stats' is true, return the result and the time difference
+	 * @returns {Function} function to be executed
+	 * @private
+	 */
+	function time(key, fn, stats) {
+		return function (...args) {
+			const t = startTime();
+			const result = fn(...args);
+			const tdiff = endTime(t);
+
+			if (enabled) {
+				if (typeof data[key] === "undefined") {
+					data[key] = 0;
+				}
+
+				data[key] += tdiff;
+			}
+
+			return stats ? { result, tdiff } : result;
+		};
+	}
+
+	/**
+	 * Returns a shallow copy of the collected timings data.
+	 * @returns {Record<string, number>} mapping of ruleId to total time in ms
+	 */
+	function getData() {
+		return { ...data };
+	}
+
+	/**
+	 * Merges rule timing totals collected elsewhere into this process' totals.
+	 * @param {Record<string, number>} dataToMerge mapping of ruleId to total time in ms
+	 * @returns {void}
+	 */
+	function mergeData(dataToMerge) {
+		for (const [key, value] of Object.entries(dataToMerge)) {
+			if (typeof data[key] === "undefined") {
+				data[key] = 0;
+			}
+			data[key] += value;
+		}
+	}
+
+	/**
+	 * Disables printing of timing data on process exit.
+	 * Intended for worker threads or non-main contexts.
+	 * @returns {void}
+	 */
+	function disableDisplay() {
+		displayEnabled = false;
+	}
+
+	if (enabled) {
+		process.on("exit", () => {
+			if (displayEnabled && Object.keys(data).length > 0) {
+				display(data);
+			}
+		});
+	}
+
+	return {
+		time,
+		enabled,
+		getListSize,
+		getData,
+		mergeData,
+		disableDisplay,
+	};
+})();