perf(lint-cli): spawn the typed pass immediately after a config edit (#671)

* perf(lint-cli): skip the builder when a hash bust cleared the caches

A config-drift or package-resolution bust deletes the variant caches before
the mtime sweep runs, so the sweep can no longer see them and they never
entered `clearedCaches`. Sizing therefore missed its short circuit and ran
the TypeScript builder to invalidate a cache that was already gone.

Report the deleted paths from `applyHashBust` and union every deletion into
`clearedCaches`, so an `eslint.config.*` edit spawns the typed pass at once.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(lint-cli): keep seeding builder state when the cache was cleared

The skip added for a cleared cache also swallowed the one thing only a
builder pass does: establish the incremental state a *later* run invalidates
against. With none on disk (a lint right after an install, which discards
`node_modules`), the next run reports `firstRun` and throws its affected set
away — so a file edited in between re-lints on its own mtime while its
importers keep stale type-aware entries no later run revisits.

Skip the builder only when prior state for the pass's mode and variant
exists, which is every case the drift bust actually meets.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* refactor(lint-cli): tighten the cleared-cache plumbing

Build `clearedCaches` in one guarded step instead of a mutable set fed by a
helper, fold `canSkipBuilder` back into the one condition that used it, and
derive the buildinfo scan prefix from `statePath` so the state-file naming
rule is stated once. Tests share one buildinfo prefix constant and read
absolute paths from `builderStateFiles`.

No behaviour change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(lint-cli): ignore stray temp files in the builder-state scan

Both writers in the state directory stage through a sibling `<name>.<pid>.tmp`
that shares the prefix `hasBuilderState` matches, so a run killed mid-write
left one behind for good — and it read as real state, re-enabling the builder
skip with nothing on disk for the next run to invalidate against.

Also names the `tsgate` base name alongside `tsbuildinfo`, marks
`BustOutcome.cleared` readonly to match its consumer, and disambiguates the
two same-named `clearedPaths` test helpers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: christopher-buss

src/lint-cli/lib/cache/bust.ts

@@ -32,8 +32,15 @@ export interface HashBust {
 
 /** Outcome of a hash-drift check. */
 export interface BustOutcome {
-	/** True when the hash changed and this variant's caches were deleted. */
-	busted: boolean;
+	/**
+	 * Absolute paths of the cache files this bust deleted, empty when the hash
+	 * did not change. Named rather than counted because the planner folds them
+	 * into the set each pass is sized against (see `mutatingDirtyCount`).
+	 *
+	 * Listed whether or not the file was there to delete — an absent cache
+	 * means "everything is dirty" just as a deleted one does.
+	 */
+	cleared: ReadonlyArray<string>;
 	/** True when no prior hash existed (state stored, no bust). */
 	firstRun: boolean;
 }
@@ -90,17 +97,20 @@ export function applyHashBust(
 	hash: string | undefined,
 ): BustOutcome {
 	if (hash === undefined) {
-		return { busted: false, firstRun: false };
+		return { cleared: [], firstRun: false };
 	}
 
 	const swap = swapState(statePath(run.cwd, bust.name, run.key), hash);
 	if (swap !== "changed") {
-		return { busted: false, firstRun: swap === "first" };
+		return { cleared: [], firstRun: swap === "first" };
 	}
 
+	const cleared: Array<string> = [];
 	for (const base of bust.caches) {
-		fs.rmSync(path.resolve(run.cwd, cacheFileFor(base, run.key)), { force: true });
+		const cacheFilePath = path.resolve(run.cwd, cacheFileFor(base, run.key));
+		fs.rmSync(cacheFilePath, { force: true });
+		cleared.push(cacheFilePath);
 	}
 
-	return { busted: true, firstRun: false };
+	return { cleared, firstRun: false };
 }

src/lint-cli/lib/plan/plan.ts

@@ -159,11 +159,12 @@ export function plan(options: LintCliOptions, run: RunContext): StagedPlan {
 	// `--no-cache` never touches cache state, and `--print` (mutate=false) never
 	// mutates.
 	//
-	// The package.json bust runs first and deletes only this variant's type-aware
-	// caches (a syntactic lint is immune to resolution changes), so it does NOT
-	// feed `clearedCaches` — the fast cache survives it. The mtime sweep below is
-	// the wholesale one, and it covers every variant on disk, not just the ones
-	// this run selected.
+	// Every deletion feeds `clearedCaches`, whichever step made it, so that
+	// sizing can tell a pass that re-lints everything from one that does not (see
+	// `mutatingDirtyCount`). The package.json bust spares the fast cache, so it
+	// contributes only the two type-aware ones. The mtime sweep below is the
+	// wholesale one, and it covers every variant on disk, not just the ones this
+	// run selected.
 	const canMutateCaches = mutate && options.cache;
 	const hasTypeAwarePass = descriptors.some((descriptor) => descriptor.invalidation !== "none");
 
@@ -173,6 +174,7 @@ export function plan(options: LintCliOptions, run: RunContext): StagedPlan {
 	// `--no-cache` counts every file dirty regardless.
 	const configHash = options.cache ? computeConfigHash(cwd, files.configFiles) : undefined;
 
+	const cleared: Array<string> = [];
 	if (canMutateCaches) {
 		// Config drift through a module `eslint.config.*` imports shifts ESLint's
 		// per-entry `hashOfConfig` (a full re-lint) but touches no bust file, so
@@ -181,14 +183,19 @@ export function plan(options: LintCliOptions, run: RunContext): StagedPlan {
 		// three of this variant's caches when it changed. Applies to every pass
 		// (a config change can alter a syntactic lint), so it runs before the
 		// type-aware-only package.json bust.
-		applyHashBust(run, CONFIG_DRIFT, configHash);
-	}
+		cleared.push(...applyHashBust(run, CONFIG_DRIFT, configHash).cleared);
+		if (hasTypeAwarePass) {
+			cleared.push(
+				...applyHashBust(run, PACKAGE_RESOLUTION, computePackageJsonHash(cwd)).cleared,
+			);
+		}
 
-	if (canMutateCaches && hasTypeAwarePass) {
-		applyHashBust(run, PACKAGE_RESOLUTION, computePackageJsonHash(cwd));
+		// The sweep runs last, so it lists only the caches the busts left on
+		// disk.
+		cleared.push(...sweepStaleCaches(cwd, newestBustMtime));
 	}
 
-	const clearedCaches = new Set(canMutateCaches ? sweepStaleCaches(cwd, newestBustMtime) : []);
+	const clearedCaches = new Set(cleared);
 
 	// Drop the files ESLint declines to lint before anything sizes from them:
 	// they never enter a cache, so they would otherwise read as dirty forever

src/lint-cli/lib/plan/sizing.ts

@@ -8,6 +8,7 @@ import { applyTypeAwareInvalidation } from "../cache/invalidation.ts";
 import type { LintCliOptions } from "../cli/types.ts";
 import type { RunContext } from "../context.ts";
 import type { RepoFiles } from "../files/collect.ts";
+import { hasBuilderState } from "../typescript/affected.ts";
 import type { WorkerLimits } from "./concurrency.ts";
 import { computeWorkerCount } from "./concurrency.ts";
 import type { PassDescriptor } from "./passes.ts";
@@ -41,9 +42,9 @@ export interface PassPlan {
  */
 export interface SizingInputs {
 	/**
-	 * The cache files the up-front stale sweep deleted (absolute paths). A pass
-	 * whose cache is in here counts every file as dirty and skips the builder —
-	 * everything re-lints regardless.
+	 * The cache files this run deleted up front (absolute paths), from the hash
+	 * busts and the stale sweep alike. A pass whose cache is in here counts
+	 * every file as dirty and skips the builder — everything re-lints anyway.
 	 */
 	clearedCaches: ReadonlySet<string>;
 	/** The lint-target lists, already filtered of ESLint-ignored files. */
@@ -115,10 +116,19 @@ function mutatingDirtyCount(
 	targetFiles: Array<string>,
 	{ clearedCaches, run }: SizePassContext,
 ): number {
-	if (clearedCaches.has(cacheLocation)) {
-		// The up-front sweep already deleted this pass's cache (see `plan`), so
-		// every file is dirty and the builder would be pure waste — everything
-		// re-lints.
+	// Both facts this pass needs about its builder, read off the one field that
+	// records them: whether it builds a TypeScript program at all, and the mode
+	// that program runs under.
+	const buildsProgram = descriptor.invalidation !== "none";
+	const mode = descriptor.invalidation === "only" ? "only" : undefined;
+
+	// A bust or the up-front sweep already deleted this pass's cache (see
+	// `plan`), so every file is dirty and the affected set the builder computes
+	// would have nothing to remove from. Skipping it is only safe once prior
+	// builder state exists: with none, the next run reports `firstRun` and throws
+	// its affected set away, so an importer of a file edited in between would
+	// keep a stale entry (see `hasBuilderState`).
+	if (clearedCaches.has(cacheLocation) && (!buildsProgram || hasBuilderState(run, mode))) {
 		return targetFiles.length;
 	}
 
@@ -127,12 +137,12 @@ function mutatingDirtyCount(
 		(cache?.getUpdatedFiles(targetFiles) ?? targetFiles).map((file) => normalizePath(file)),
 	);
 
-	if (descriptor.invalidation !== "none") {
+	if (buildsProgram) {
 		const outcome = applyTypeAwareInvalidation(run, {
 			alreadyDirty: dirty,
 			cache,
 			cacheLocation,
-			mode: descriptor.invalidation === "only" ? "only" : undefined,
+			mode,
 			targetFiles,
 		});
 		if (outcome.busted) {

src/lint-cli/lib/typescript/affected.ts

@@ -67,6 +67,19 @@ interface ProjectWalkResult {
 
 const warned = new Set<string>();
 
+/**
+ * State-file base name for the builder's incremental state, shared by the
+ * per-project path and the prefix {@link hasBuilderState} scans for.
+ */
+const BUILD_INFO_STATE = "tsbuildinfo";
+
+/**
+ * State-file base name for the gate paired with each buildinfo. Deliberately
+ * not a `tsbuildinfo-` suffix, so anything enumerating a variant's buildinfo
+ * files does not pick a gate up as one (see {@link gateStatePath}).
+ */
+const GATE_STATE = "tsgate";
+
 /**
  * Compute the set of files whose type-aware lint results may have changed since
  * the previous run, using TypeScript's builder API. The builder does a native
@@ -158,6 +171,61 @@ export function computeAffectedFiles(
 	}
 }
 
+/**
+ * Whether a previous run left builder state for this mode and config variant.
+ *
+ * The one thing a builder pass does that nothing else can is establish this
+ * state. Its affected set is disposable — a caller with an empty cache re-lints
+ * regardless — but a run that skips the builder while no state exists only
+ * defers the cost onto the next run, which then reports `firstRun` and throws
+ * its affected set away. A file edited in between would be re-linted on its own
+ * mtime while its importers kept stale type-aware cache entries, which no later
+ * run revisits. Callers that skip the builder as an optimisation ask this
+ * first.
+ *
+ * Any one project's state is enough: {@link computeAffectedFiles} reports
+ * `firstRun` only when no project at all had state, and a newly added project
+ * contributes its whole file set rather than an empty one.
+ *
+ * @param run - The run context.
+ * @param mode - The active ESLint type-aware mode (never `"off"` here).
+ * @returns True when at least one buildinfo for this mode and variant exists.
+ */
+export function hasBuilderState(
+	{ key, cwd }: RunContext,
+	mode: TypeAwareMode | undefined,
+): boolean {
+	// Named through the same `statePath` the buildinfo files themselves are,
+	// minus the per-project digest, so the base name and the hyphen-join rule are
+	// stated once. Spelling the prefix out here would let a rename slip past
+	// silently: the scan would stop matching and the guard would degrade to
+	// "always build", with no error and nothing to fail on.
+	const prefix = `${path.basename(statePath(cwd, BUILD_INFO_STATE, modeSuffix(mode), key))}-`;
+	try {
+		// Both writers in this directory stage through a sibling
+		// `<name>.<pid>.tmp` (see `persistBuilderState` and `writeState`), which
+		// shares the prefix. A run killed mid-write leaves one behind for good,
+		// and counting it as state would re-enable the skip with nothing on disk
+		// to invalidate against.
+		return fs
+			.readdirSync(stateDirectory(cwd))
+			.some((name) => name.startsWith(prefix) && !name.endsWith(".tmp"));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The state-file segment discriminating the type-aware mode a builder ran
+ * under. Two modes resolve different programs, so their state cannot be shared.
+ *
+ * @param mode - The active ESLint type-aware mode (never `"off"` here).
+ * @returns The file-name segment for that mode.
+ */
+function modeSuffix(mode: TypeAwareMode | undefined): string {
+	return mode === "only" ? "typeaware" : "full";
+}
+
 /**
  * Resolve the builder incremental-state (`.tsbuildinfo`) file for a mode and
  * config variant.
@@ -187,8 +255,7 @@ function builderStatePath(
 	key: string,
 	projectId: string,
 ): string {
-	const suffix = mode === "only" ? "typeaware" : "full";
-	return statePath(cwd, "tsbuildinfo", suffix, key, projectId);
+	return statePath(cwd, BUILD_INFO_STATE, modeSuffix(mode), key, projectId);
 }
 
 /**
@@ -219,8 +286,7 @@ function gateStatePath(
 	key: string,
 	projectId: string,
 ): string {
-	const suffix = mode === "only" ? "typeaware" : "full";
-	return statePath(cwd, "tsgate", suffix, key, projectId);
+	return statePath(cwd, GATE_STATE, modeSuffix(mode), key, projectId);
 }
 
 /**