chore(bench): add tinybench-based performance benchmark suite

Introduces benchmark infrastructure for enhanced-resolve, wired to
CodSpeed via @codspeed/tinybench-plugin so the same `npm run benchmark`
command works both locally (walltime fallback) and in CI
(instrumentation). Adds two initial cases: `realistic-midsize`, a
synthetic mid-size project exercising relative/bare/scoped/exports
lookups plus nested node_modules, and `pathological-deep-stack`, a
50-level alias chain that specifically stresses the doResolve
recursion-check path that PR #443 is targeting.

Also excludes benchmark/ from eslint (synthetic fixtures + ESM entry
point conflict with the base config) and adds `codspeed`/`tinybench`
to the spellcheck dictionary.

Refs: #443

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: xiaoxiaojx

.cspell.json

@@ -3,6 +3,8 @@
   "words": [
     "abcxyz",
     "addrs",
+    "codspeed",
+    "tinybench",
     "abortable",
     "anotherhashishere",
     "arcanis",

benchmark/README.md

@@ -0,0 +1,107 @@
+# Benchmarks
+
+Performance benchmarks for `enhanced-resolve`, tracked over time via
+[CodSpeed](https://codspeed.io/).
+
+Runner stack: [tinybench](https://github.com/tinylibs/tinybench) +
+[`@codspeed/tinybench-plugin`](https://www.npmjs.com/package/@codspeed/tinybench-plugin).
+The plugin is a drop-in wrapper: locally it falls back to plain tinybench
+wall-clock measurements, and under `CodSpeedHQ/action` in CI it automatically
+switches to CodSpeed's instrumentation mode.
+
+## Running locally
+
+```sh
+npm run benchmark
+```
+
+Optional substring filter to run only matching cases:
+
+```sh
+npm run benchmark -- realistic
+BENCH_FILTER=pathological npm run benchmark
+```
+
+Locally the runner uses tinybench's wall-clock measurements and prints a
+table of ops/s, mean, p99, and relative margin of error per task. Under CI,
+the plugin detects the CodSpeed runner environment and switches to
+instruction-counting mode automatically.
+
+The V8 flags in `package.json` (`--no-opt --predictable --hash-seed=1` etc.)
+are required by CodSpeed's instrumentation mode for deterministic results —
+do not drop them.
+
+### Optional: running real instruction counts locally
+
+If you want to reproduce CI's exact instrument-count numbers on your own
+machine (Linux only — the underlying Valgrind tooling has no macOS backend),
+install the standalone CodSpeed CLI and wrap `npm run benchmark` with it:
+
+```sh
+curl -fsSL https://codspeed.io/install.sh | bash
+codspeed run npm run benchmark
+```
+
+This is only useful if you want to debug an instruction-count regression
+outside CI. Day-to-day benchmark iteration should use `npm run benchmark`
+directly (wall-clock mode).
+
+## Layout
+
+```
+benchmark/
+├── run.mjs                     # entry point: discovers cases, runs bench
+└── cases/
+    └── <case-name>/
+        ├── index.bench.mjs     # default export: register(bench, ctx)
+        └── fixture/            # optional: project tree to resolve against
+```
+
+Each case directory must contain `index.bench.mjs` exporting a default
+function with the signature:
+
+```js
+export default function register(bench, { caseName, caseDir, fixtureDir }) {
+	bench.add("my case: descriptive name", async () => {
+		// ... resolve calls ...
+	});
+}
+```
+
+`fixtureDir` is the absolute path to the case's `fixture/` subdirectory
+(which may or may not exist). `caseDir` is the parent directory containing
+`index.bench.mjs`.
+
+## Existing cases
+
+| Case                      | What it measures                                                                                             |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `realistic-midsize`       | Mixed batch of relative/bare/scoped/exports/nested-`node_modules` requests against a synthetic mid-size tree |
+| `pathological-deep-stack` | 50-deep alias chain, specifically stresses the `doResolve` recursion-check path                              |
+
+Add new cases by creating a new directory under `cases/` — `run.mjs` will
+pick it up automatically on the next run.
+
+## Adding a CodSpeed-friendly case
+
+A few rules of thumb:
+
+1. **Keep each bench body long enough to be measurable** (batch many resolves
+   per iteration). CodSpeed's simulation mode runs the body exactly once under
+   instrumentation, so a body that does one `resolver.resolve()` will be
+   dominated by instrumentation overhead.
+2. **Avoid randomness.** Fixed request lists, fixed seeds. CodSpeed compares
+   against the base commit and expects identical work across runs.
+3. **Pre-build anything expensive (resolvers, alias lists, fixture paths) outside
+   the `bench.add` callback.** The goal is to measure resolve, not setup.
+4. **Prefer one focused case per bench file**, so the PR report is easy to
+   read.
+
+## CI integration
+
+CI is driven by `.github/workflows/benchmarks.yml`, which uses
+`CodSpeedHQ/action@v4` in `mode: "simulation"` and authenticates via the
+`CODSPEED_TOKEN` repo secret.
+
+Both `CODSPEED_TOKEN` and CodSpeed repo enablement must be configured by a
+repo admin once — see the top-level PR description for the handoff.

benchmark/cases/pathological-deep-stack/fixture/entry.js

@@ -0,0 +1 @@
+module.exports = {};

benchmark/cases/pathological-deep-stack/fixture/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "pathological-deep-stack-fixture",
+  "version": "1.0.0"
+}

benchmark/cases/pathological-deep-stack/fixture/target.js

@@ -0,0 +1 @@
+module.exports = "target";

benchmark/cases/pathological-deep-stack/index.bench.mjs

@@ -0,0 +1,80 @@
+/*
+ * pathological-deep-stack
+ *
+ * Stress the doResolve recursion-check path specifically. Configures a long
+ * chain of alias rewrites so every resolution of `chain-0` produces a stack
+ * of depth O(N) before landing on `./target.js`.
+ *
+ * This is the case that the linked-list rewrite in PR #443 is most likely
+ * to regress, because hasStackEntry walks the parent chain. Keeping the
+ * number here high enough to matter (50+ levels) but low enough to finish
+ * quickly is the point.
+ *
+ * If you're benchmarking the #443 PR, compare this case before and after:
+ *   - "before" (current main): Set<string> clone per level, O(n) cost per
+ *     doResolve, O(n^2) per full chain, but cheap per-step comparison
+ *   - "after" (#443): single linked-list node per level, O(1) alloc, but
+ *     hasStackEntry walks parents -> O(n) per comparison, O(n^2) per chain
+ * Both are quadratic on paper; the question is the constant factor and the
+ * amount of GC pressure. That's exactly what this case measures.
+ */
+
+import fs from "fs";
+import path from "path";
+import enhanced from "../../../lib/index.js";
+
+const { ResolverFactory, CachedInputFileSystem } = enhanced;
+
+const CHAIN_LENGTH = 50;
+
+/**
+ * Build an AliasPlugin-compatible alias list that forms a chain:
+ *   chain-0 -> chain-1 -> chain-2 -> ... -> chain-49 -> ./target
+ *
+ * Each entry rewrites one specifier to the next, so a single resolve of
+ * `chain-0` forces enhanced-resolve to re-enter the pipeline CHAIN_LENGTH
+ * times before bottoming out.
+ */
+function buildChainAliases() {
+	const aliases = [];
+	for (let i = 0; i < CHAIN_LENGTH - 1; i++) {
+		aliases.push({ name: `chain-${i}`, alias: `chain-${i + 1}` });
+	}
+	aliases.push({ name: `chain-${CHAIN_LENGTH - 1}`, alias: "./target" });
+	return aliases;
+}
+
+/**
+ * @param {import('tinybench').Bench} bench
+ * @param {{ fixtureDir: string }} ctx
+ */
+export default function register(bench, { fixtureDir }) {
+	const fileSystem = new CachedInputFileSystem(fs, 4000);
+	const aliases = buildChainAliases();
+
+	const resolver = ResolverFactory.createResolver({
+		fileSystem,
+		extensions: [".js"],
+		alias: aliases,
+	});
+
+	const resolve = () =>
+		new Promise((resolve, reject) => {
+			resolver.resolve({}, fixtureDir, "chain-0", {}, (err, result) => {
+				if (err) return reject(err);
+				if (!result) return reject(new Error("no result"));
+				resolve(result);
+			});
+		});
+
+	bench.add(
+		`pathological-deep-stack: alias chain of ${CHAIN_LENGTH} (warm)`,
+		async () => {
+			// 10 resolves per iteration so the bench body is long enough to be
+			// measurable but short enough to finish quickly.
+			for (let i = 0; i < 10; i++) {
+				await resolve();
+			}
+		},
+	);
+}