perf: back ResolveContext.stack with a lazy linked-list Set

Applies the performance improvement from #443 without breaking the
public API. `resolveContext.stack` remains a `Set<string>` so consumers
like webpack's ResolverCachePlugin continue to work unchanged, but it
is now backed by a singly-linked list of structured stack entries:

- Extending the stack on each `doResolve` call is O(1) instead of
  O(n) for cloning a `Set` (the dominant cost identified in #443).
- Formatted entry strings are computed lazily, only when the set is
  iterated, queried with `has`, or its `size` is read.
- The recursion check uses structural equality on the raw entry
  objects, so the hot path allocates no strings at all.

The `Set<string>` surface (`has`, `size`, iteration, `keys`, `values`,
`entries`, `forEach`, `instanceof Set`) is preserved by having
`StackSet` extend `Set` and override its read operations; the
generated `types.d.ts` is unchanged.

Author: claude

lib/Resolver.js

@@ -370,6 +370,19 @@ const _pathCacheByFs = new WeakMap();
  * @typedef {string} StackEntry
  */
 
+/**
+ * Structured representation of a stack entry used internally for
+ * structural equality checks without allocating a formatted string.
+ * @typedef {object} RawStackEntry
+ * @property {string | undefined} name hook name
+ * @property {string | false} path request path
+ * @property {string} request request string
+ * @property {string} query query string
+ * @property {string} fragment fragment string
+ * @property {boolean} directory directory flag
+ * @property {boolean} module module flag
+ */
+
 /**
  * @template T
  * @typedef {{ add: (item: T) => void }} WriteOnlySet
@@ -410,6 +423,166 @@ function toCamelCase(str) {
 	return str.replace(/-([a-z])/g, (str) => str.slice(1).toUpperCase());
 }
 
+/**
+ * Formats a raw stack entry to its string representation.
+ * @param {RawStackEntry} entry raw entry
+ * @returns {string} formatted stack entry string
+ */
+function formatStackEntry(entry) {
+	return `${entry.name}: (${entry.path}) ${entry.request}${entry.query}${
+		entry.fragment
+	}${entry.directory ? " directory" : ""}${entry.module ? " module" : ""}`;
+}
+
+/**
+ * Structural equality check between two raw stack entries.
+ * Avoids formatting to a string on the hot recursion-check path.
+ * @param {RawStackEntry} a first entry
+ * @param {RawStackEntry} b second entry
+ * @returns {boolean} whether the entries are structurally equal
+ */
+function rawStackEntriesEqual(a, b) {
+	return (
+		a.name === b.name &&
+		a.path === b.path &&
+		a.request === b.request &&
+		a.query === b.query &&
+		a.fragment === b.fragment &&
+		a.directory === b.directory &&
+		a.module === b.module
+	);
+}
+
+/**
+ * A Set<string> that is backed by a singly-linked list of structured
+ * stack entries. Extending the stack with a new entry is O(1) in time
+ * and memory (instead of O(n) for cloning a `Set`), and formatted
+ * entry strings are computed lazily — only when the set is iterated,
+ * queried with `has`, or its `size` is read.
+ *
+ * The public `Set<string>` contract is preserved for backwards
+ * compatibility so that consumers like webpack's `ResolverCachePlugin`
+ * can continue to read `resolveContext.stack` as a `Set<string>`.
+ * @extends {Set<string>}
+ */
+class StackSet extends Set {
+	/**
+	 * @param {Set<string> | undefined} parent previous stack (or undefined)
+	 * @param {RawStackEntry} entry raw entry at the tip of this stack
+	 */
+	constructor(parent, entry) {
+		super();
+		/** @type {Set<string> | undefined} */
+		this._parent = parent;
+		/** @type {RawStackEntry} */
+		this._entry = entry;
+		/** @type {string | undefined} */
+		this._string = undefined;
+	}
+
+	/**
+	 * @returns {string} the formatted string for this tip entry (memoized)
+	 */
+	_getString() {
+		if (this._string === undefined) {
+			this._string = formatStackEntry(this._entry);
+		}
+		return this._string;
+	}
+
+	/**
+	 * Fast structural recursion check without allocating any strings.
+	 * @param {RawStackEntry} query raw entry to look for
+	 * @returns {boolean} whether the entry exists in this stack
+	 */
+	_hasRaw(query) {
+		if (rawStackEntriesEqual(this._entry, query)) return true;
+		const parent = this._parent;
+		if (!parent) return false;
+		if (parent instanceof StackSet) return parent._hasRaw(query);
+		// Fallback for user-provided plain `Set<string>`: pay the string
+		// formatting cost once to query it.
+		return parent.has(formatStackEntry(query));
+	}
+
+	/**
+	 * @param {string} value value to check
+	 * @returns {boolean} whether the stack contains the value
+	 */
+	has(value) {
+		if (this._getString() === value) return true;
+		return this._parent ? this._parent.has(value) : false;
+	}
+
+	/**
+	 * @returns {number} number of entries in the stack
+	 */
+	get size() {
+		return 1 + (this._parent ? this._parent.size : 0);
+	}
+
+	/**
+	 * Walks from the oldest (bottom of stack) to the newest (tip).
+	 * @returns {SetIterator<string>} iterator of formatted stack entries
+	 */
+	[Symbol.iterator]() {
+		return /** @type {SetIterator<string>} */ (
+			// eslint-disable-next-line no-use-before-define
+			/** @type {unknown} */ (iterateStackSet(this))
+		);
+	}
+
+	/**
+	 * @returns {SetIterator<string>} same as [Symbol.iterator]
+	 */
+	keys() {
+		return this[Symbol.iterator]();
+	}
+
+	/**
+	 * @returns {SetIterator<string>} same as [Symbol.iterator]
+	 */
+	values() {
+		return this[Symbol.iterator]();
+	}
+
+	/**
+	 * @returns {SetIterator<[string, string]>} iterator yielding [v, v]
+	 */
+	entries() {
+		return /** @type {SetIterator<[string, string]>} */ (
+			// eslint-disable-next-line no-use-before-define
+			/** @type {unknown} */ (iterateStackSetEntries(this))
+		);
+	}
+
+	/**
+	 * @param {(value: string, value2: string, set: Set<string>) => void} callback callback
+	 * @param {unknown=} thisArg this argument
+	 * @returns {void}
+	 */
+	forEach(callback, thisArg) {
+		for (const v of this) callback.call(thisArg, v, v, this);
+	}
+}
+
+/**
+ * @param {StackSet} set the set to iterate
+ * @returns {Generator<string>} generator yielding formatted entries
+ */
+function* iterateStackSet(set) {
+	if (set._parent) yield* set._parent;
+	yield set._getString();
+}
+
+/**
+ * @param {StackSet} set the set to iterate
+ * @returns {Generator<[string, string]>} generator yielding [v, v] tuples
+ */
+function* iterateStackSetEntries(set) {
+	for (const v of set) yield [v, v];
+}
+
 class Resolver {
 	/**
 	 * @param {ResolveStepHook} hook hook
@@ -739,33 +912,48 @@ class Resolver {
 	 * @returns {void}
 	 */
 	doResolve(hook, request, message, resolveContext, callback) {
-		const stackEntry = Resolver.createStackEntry(hook, request);
+		const parent = resolveContext.stack;
+
+		/** @type {RawStackEntry} */
+		const rawEntry = {
+			name: hook.name,
+			path: request.path,
+			request: request.request || "",
+			query: request.query || "",
+			fragment: request.fragment || "",
+			directory: Boolean(request.directory),
+			module: Boolean(request.module),
+		};
 
-		/** @type {Set<string> | undefined} */
-		let newStack;
-		if (resolveContext.stack) {
-			newStack = new Set(resolveContext.stack);
-			if (resolveContext.stack.has(stackEntry)) {
-				/**
-				 * Prevent recursion
-				 * @type {Error & { recursion?: boolean }}
-				 */
-				const recursionError = new Error(
-					`Recursion in resolving\nStack:\n  ${[...newStack].join("\n  ")}`,
-				);
-				recursionError.recursion = true;
-				if (resolveContext.log) {
-					resolveContext.log("abort resolving because of recursion");
-				}
-				return callback(recursionError);
+		// Fast O(n) structural recursion check without allocating strings.
+		// If the caller supplied a plain `Set<string>` rather than a
+		// `StackSet`, fall back to the string-based `has` check.
+		let recursion = false;
+		if (parent !== undefined) {
+			recursion =
+				parent instanceof StackSet
+					? parent._hasRaw(rawEntry)
+					: parent.has(formatStackEntry(rawEntry));
+		}
+
+		// O(1) extension of the stack via a linked-list node that lazily
+		// formats its string representation. Preserves the `Set<string>`
+		// public contract.
+		const newStack = new StackSet(parent, rawEntry);
+
+		if (recursion) {
+			/**
+			 * Prevent recursion
+			 * @type {Error & { recursion?: boolean }}
+			 */
+			const recursionError = new Error(
+				`Recursion in resolving\nStack:\n  ${[...newStack].join("\n  ")}`,
+			);
+			recursionError.recursion = true;
+			if (resolveContext.log) {
+				resolveContext.log("abort resolving because of recursion");
 			}
-			newStack.add(stackEntry);
-		} else {
-			// creating a set with new Set([item])
-			// allocates a new array that has to be garbage collected
-			// this is an EXTREMELY hot path, so let's avoid it
-			newStack = new Set();
-			newStack.add(stackEntry);
+			return callback(recursionError);
 		}
 		this.hooks.resolveStep.call(hook, request);