@bamboocss/parser 1.45.4 → 1.46.0

package/dist/index.mjs

@@ -876,6 +876,8 @@ var ParserResult = class {
 	pattern = /* @__PURE__ */ new Map();
 	filePath;
 	encoder;
+	/** Resolver targets crossed while extracting values which contributed CSS. */
+	dependencies = /* @__PURE__ */ new Set();
 	/**
 	* `css()` calls whose styles the build could not fully see.
 	*
@@ -1041,6 +1043,33 @@ var ParserResult = class {
 		this.filePath = filePath;
 		return this;
 	}
+	/** @internal Called only by the extractor-facing resolver, not by import classification. */
+	addDependency(filePath) {
+		this.dependencies.add(filePath.replaceAll("\\", "/"));
+	}
+	/**
+	* Local source paths crossed while resolving values this extraction actually encoded.
+	*
+	* The Project ledger deliberately records every local import, including ordinary runtime
+	* bindings. Box nodes retain the declaration node followed while resolving a style value,
+	* so this is the narrow semantic target set consumers can feed back to that ledger to recover
+	* re-export/barrel paths without watching unrelated imports.
+	*/
+	getDependencies() {
+		const own = this.filePath?.replaceAll("\\", "/");
+		const paths = new Set(this.dependencies);
+		const seen = /* @__PURE__ */ new Set();
+		const visit = (node) => {
+			if (!node || seen.has(node)) return;
+			seen.add(node);
+			const path = node.getNode?.()?.getSourceFile().getFilePath().replaceAll("\\", "/");
+			if (path && path !== own) paths.add(path);
+			if (box.isMap(node)) for (const child of node.value.values()) visit(child);
+			else if (box.isArray(node)) for (const child of node.value) visit(child);
+		};
+		for (const item of this.all) if (item.type !== "cva-call") visit(item.box);
+		return [...paths].sort();
+	}
 	merge(result) {
 		result.css.forEach((item) => this.css.add(this.append(item)));
 		result.cva.forEach((item) => this.cva.add(this.append(item)));
@@ -1057,6 +1086,7 @@ var ParserResult = class {
 			items.forEach((item) => set.add(this.append(item)));
 		});
 		if (result.unresolved.length) this.unresolved.push(...result.unresolved);
+		for (const dependency of result.dependencies) this.dependencies.add(dependency);
 		return this;
 	}
 	toArray() {
@@ -1141,6 +1171,7 @@ function createParser(context) {
 				reason: "unresolved-raw"
 			});
 		};
+		const recordDependency = (filePath) => parserResult.addDependency(filePath);
 		extract({
 			ast: sourceFile,
 			tokens: context.tokens ? {
@@ -1189,7 +1220,9 @@ function createParser(context) {
 				if (file.isValidRecipe(name) || file.isValidPattern(name)) reportUnresolvedRaw(name, node);
 				return { environment: Object.assign({}, defaultEnv, { extra: { [name]: { raw: (v) => v } } }) };
 			},
-			flags: { skipTraverseFiles: false }
+			flags: { skipTraverseFiles: false },
+			recordDependency,
+			resolveModule
 		}).forEach((result, alias) => {
 			const name = file.getName(file.normalizeFnName(alias));
 			logger.debug(`ast:${name}`, name !== alias ? {
@@ -1297,23 +1330,61 @@ const invalidateResolutions = () => {
 	clearBoxNodeCache();
 	clearImportedRecipeCache();
 };
-const normalizeCompilerOptions = (raw) => {
+const normalizeCompilerOptions = (raw, basePath = process.cwd()) => {
 	if (!raw) return {};
-	const { options } = ts.convertCompilerOptionsFromJson(raw, process.cwd());
+	const { options } = ts.convertCompilerOptionsFromJson(raw, basePath);
 	return options;
 };
-const createTsProject = (options) => new Project$1({
-	skipAddingFilesFromTsConfig: true,
-	skipFileDependencyResolution: true,
-	skipLoadingLibFiles: true,
-	...options,
-	compilerOptions: {
-		allowJs: true,
-		strictNullChecks: false,
-		skipLibCheck: true,
-		...normalizeCompilerOptions(options.compilerOptions)
+/** Snapshot the JSON-shaped ts-morph options while retaining opaque hosts and callbacks. */
+const snapshotProjectOption = (value) => {
+	if (Array.isArray(value)) return value.map(snapshotProjectOption);
+	if (!value || typeof value !== "object") return value;
+	if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshotProjectOption(entry)]));
+};
+const prepareTsProjectOptions = (options, snapshotNested = false, compilerOptionsBasePath = process.cwd()) => {
+	const snapshot = { ...options };
+	if (snapshotNested) {
+		for (const key of [
+			"compilerOptions",
+			"defaultCompilerOptions",
+			"manipulationSettings"
+		]) if (key in snapshot) snapshot[key] = snapshotProjectOption(snapshot[key]);
 	}
-});
+	return {
+		skipAddingFilesFromTsConfig: true,
+		skipFileDependencyResolution: true,
+		skipLoadingLibFiles: true,
+		...snapshot,
+		compilerOptions: {
+			allowJs: true,
+			strictNullChecks: false,
+			skipLibCheck: true,
+			...normalizeCompilerOptions(snapshot.compilerOptions, compilerOptionsBasePath)
+		}
+	};
+};
+const createTsProject = (options) => new Project$1(options);
+/** Filesystem errors proving a lexical candidate cannot name a resolvable file. */
+const isMissingPathShapeError = (error) => {
+	const code = error?.code;
+	return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" || code === "ENAMETOOLONG";
+};
+/** Match the successful receiver cases of an ordinary writable data-property assignment. */
+const setProjectOnReceiver = (receiver, project) => {
+	if (typeof receiver !== "object" && typeof receiver !== "function" || receiver === null) return;
+	const descriptor = Reflect.getOwnPropertyDescriptor(receiver, "project");
+	if (descriptor) {
+		if ("value" in descriptor && descriptor.writable) Reflect.defineProperty(receiver, "project", { value: project });
+		return;
+	}
+	Reflect.defineProperty(receiver, "project", {
+		configurable: true,
+		enumerable: true,
+		value: project,
+		writable: true
+	});
+};
 /**
 * How to parse a file, decided by its extension.
 *
@@ -1340,35 +1411,188 @@ const scriptKindFor = (filePath) => {
 	return extension === ".ts" || extension === ".mts" || extension === ".cts" ? ScriptKind.TS : ScriptKind.TSX;
 };
 var Project = class {
-	options;
-	project;
+	/**
+	* Source-loading contract for the opt-in deferred mode:
+	*
+	* - materializing: `project`, `getSourceFile`, `getDependents`, every create/add/remove/reload
+	*   API, and non-JSON `parseSourceFile`;
+	* - graph-independent: `files`, `parser`, `parserOptions`, `readFile`, `getFiles`, the
+	*   resolution-ledger/work getters, `getUnresolvedImporters`, `parseJson`/JSON
+	*   `parseSourceFile`, `transformFile`, `classify`.
+	*
+	* Graph-independent means outside the atomic preload. While it is `loading`, every public
+	* wrapper entry rejects reentrancy before returning live state or invoking a callback.
+	*
+	* Private resolution and dependency helpers are reachable only after a materializing parse.
+	*/
 	parser;
+	project;
+	#guardedParser;
+	#parser;
+	#sourceFiles;
+	options;
 	get parserOptions() {
+		this.#assertNotLoading();
 		return this.options.parserOptions;
 	}
 	constructor(options) {
+		const { deferInitialSourceFiles, getFiles, parserOptions } = options;
+		const tsProjectOptions = { ...options };
+		delete tsProjectOptions.deferInitialSourceFiles;
+		delete tsProjectOptions.resolutionConfigFiles;
 		this.options = options;
-		const { parserOptions } = options;
-		this.project = createTsProject(options);
-		this.parser = createParser(parserOptions);
-		this.createSourceFiles();
+		this.#sourceFiles = {
+			accessor: void 0,
+			initialFiles: [],
+			phase: deferInitialSourceFiles ? "pending" : "ready",
+			project: void 0,
+			projectOptions: prepareTsProjectOptions(tsProjectOptions, Boolean(deferInitialSourceFiles), parserOptions.config.cwd || process.cwd()),
+			revision: 0
+		};
+		if (!deferInitialSourceFiles) {
+			this.project = createTsProject(this.#sourceFiles.projectOptions);
+			this.#sourceFiles.project = this.project;
+		}
+		const parser = createParser(parserOptions);
+		this.#parser = parser;
+		if (deferInitialSourceFiles) {
+			this.#guardedParser = (...args) => {
+				this.#assertNotLoading();
+				return this.#parser(...args);
+			};
+			Object.defineProperty(this, "parser", {
+				configurable: false,
+				enumerable: true,
+				get: () => {
+					this.#assertNotLoading();
+					return this.#guardedParser;
+				},
+				set: (next) => {
+					this.#assertNotLoading();
+					if (Object.isFrozen(this)) throw new TypeError("Cannot assign to read only property 'parser' of Project");
+					this.#parser = next;
+				}
+			});
+			this.#sourceFiles.initialFiles = Object.freeze([...getFiles()]);
+			const getProject = () => {
+				this.#ensureSourceFiles();
+				return this.#sourceFiles.project;
+			};
+			const isOwner = (receiver) => receiver === this;
+			const isFrozen = () => Object.isFrozen(this);
+			const setOwnerProject = (project) => {
+				this.#sourceFiles.revision++;
+				if (Object.isFrozen(this)) throw new TypeError("Cannot assign to read only property 'project' of Project");
+				this.#sourceFiles.project = project;
+				this.#sourceFiles.phase = "ready";
+				this.resetResolutionState();
+			};
+			const assertNotLoading = () => this.#assertNotLoading();
+			const setProject = function(project) {
+				assertNotLoading();
+				if (!isOwner(this)) {
+					if (isFrozen()) return;
+					setProjectOnReceiver(this, project);
+					return;
+				}
+				setOwnerProject(project);
+			};
+			this.#sourceFiles.accessor = {
+				get: getProject,
+				set: setProject
+			};
+			Object.defineProperty(this, "project", {
+				configurable: false,
+				enumerable: true,
+				get: getProject,
+				set: setProject
+			});
+		} else {
+			this.parser = parser;
+			this.createSourceFiles();
+		}
 	}
 	get files() {
+		this.#assertNotLoading();
 		return this.options.getFiles();
 	}
 	/**
-	* Reverse dependency graph: imported file -> files importing it, both keyed on
-	* the source file's own normalized path so lookups match regardless of whether
-	* the caller passed a relative, aliased or platform-specific path.
+	* Atomically preload the inventory captured when this wrapper was constructed.
 	*
-	* Populated while parsing. Cross-file extraction folds imported values into the
-	* importer's output, so editing a shared style file has to re-parse everyone who
-	* imports it — re-parsing only the changed file leaves consumers stale.
+	* The candidate ts-morph Project stays local until every non-ENOENT read and AST creation
+	* succeeds. A failure discards it, and the next operation retries with a fresh candidate
+	* over the same frozen membership. A materializing callback that re-enters this wrapper
+	* sees no candidate and fails explicitly rather than observing a partial module graph.
 	*/
+	#hasSourceFilesAccessor = () => {
+		const expected = this.#sourceFiles.accessor;
+		const descriptor = Object.getOwnPropertyDescriptor(this, "project");
+		return Boolean(expected && descriptor?.get === expected.get && descriptor.set === expected.set);
+	};
+	#assertSourceFilesAccessor = () => {
+		if (!this.#hasSourceFilesAccessor()) throw new Error("Project property changed during source initialization");
+	};
+	#assertNotLoading = () => {
+		if (this.#sourceFiles.phase !== "loading") return;
+		this.#sourceFiles.revision++;
+		throw new Error("Project source files are already being initialized");
+	};
+	#assertSourceFilesTransaction = (revision) => {
+		this.#assertSourceFilesAccessor();
+		if (this.#sourceFiles.revision !== revision) throw new Error("Project source files are already being initialized; transaction was re-entered or mutated");
+	};
+	#materializeSourceFiles = (read, skipMissing) => {
+		this.#assertSourceFilesAccessor();
+		const revision = this.#sourceFiles.revision;
+		this.#sourceFiles.phase = "loading";
+		try {
+			const candidate = createTsProject(this.#sourceFiles.projectOptions);
+			this.#assertSourceFilesTransaction(revision);
+			let loaded = 0;
+			for (const [index, file] of this.#sourceFiles.initialFiles.entries()) try {
+				const content = read(file, index);
+				this.#assertSourceFilesTransaction(revision);
+				candidate.createSourceFile(file, content, {
+					overwrite: true,
+					scriptKind: scriptKindFor(file)
+				});
+				this.#assertSourceFilesTransaction(revision);
+				loaded++;
+			} catch (error) {
+				this.#assertSourceFilesTransaction(revision);
+				if (!skipMissing || error?.code !== "ENOENT") throw error;
+			}
+			this.#assertSourceFilesTransaction(revision);
+			if (loaded > 0) invalidateResolutions();
+			this.#moduleResolutionCache = void 0;
+			this.#fileTreeRevision++;
+			this.#assertSourceFilesTransaction(revision);
+			this.#sourceFiles.project = candidate;
+			this.#sourceFiles.phase = "ready";
+			return;
+		} catch (error) {
+			this.#sourceFiles.project = void 0;
+			this.#sourceFiles.phase = "pending";
+			throw error;
+		}
+	};
+	#ensureSourceFiles = () => {
+		if (this.#sourceFiles.phase === "ready") return;
+		this.#assertNotLoading();
+		this.#materializeSourceFiles((file) => this.options.readFile(file), true);
+	};
+	/** Reverse dependency graph: resolved target -> importers. */
 	dependents = /* @__PURE__ */ new Map();
 	/** Forward edges, so a re-parse can retract exactly the previous ones. */
 	dependencies = /* @__PURE__ */ new Map();
 	/**
+	* Deleted targets retain their last importers until those importers are reparsed.
+	*
+	* A watcher commonly removes first and asks second. The ledger itself must say the target
+	* is now unresolved, while this one-turn tombstone keeps that unlink query answerable.
+	*/
+	removedDependents = /* @__PURE__ */ new Map();
+	/**
 	* Path as a caller spells it -> the source file's own path.
 	*
 	* The graph is keyed on the latter, but callers pass whatever the watcher gave
@@ -1379,32 +1603,74 @@ var Project = class {
 	*/
 	canonicalPaths = /* @__PURE__ */ new Map();
 	/**
-	* Files holding at least one import whose specifier resolved to nothing.
+	* Files holding at least one import whose local resolution is not final.
 	*
-	* A broken or not-yet-created import produces no edge, so when the file it wants
-	* finally appears there is nothing in the graph connecting them. These importers
-	* are the only candidates for that, and the set is normally empty.
+	* A broken or not-yet-created import produces no edge. A successful fallback edge
+	* likewise cannot point at the missing higher-priority candidate that may replace it.
+	* These importers are the only candidates for either add-event transition, and the
+	* set is normally empty.
 	*/
 	unresolvedImporters = /* @__PURE__ */ new Set();
-	/** Files whose imports did not all resolve when they were last parsed. */
-	getUnresolvedImporters = () => [...this.unresolvedImporters];
+	/** Exact post-transform resolution facts, one immutable list per importer. */
+	resolutionsByImporter = /* @__PURE__ */ new Map();
+	/** One hook/transform transaction for each source revision Bamboo can semantically read. */
+	sourcePreparations = /* @__PURE__ */ new Map();
+	/** Paths explicitly removed through this wrapper, until an add/create observes them again. */
+	removedSourcePaths = /* @__PURE__ */ new Set();
+	/** File-tree changes invalidate even successful resolutions (extension precedence can move). */
+	#fileTreeRevision = 0;
+	resolutionWork = {
+		moduleResolutionsAttempted: 0,
+		sourceFilesAdded: 0,
+		sourceFilesRead: 0
+	};
+	resetResolutionState = () => {
+		this.#moduleResolutionCache = void 0;
+		this.#fileTreeRevision++;
+		this.dependents = /* @__PURE__ */ new Map();
+		this.dependencies = /* @__PURE__ */ new Map();
+		this.removedDependents = /* @__PURE__ */ new Map();
+		this.canonicalPaths = /* @__PURE__ */ new Map();
+		this.unresolvedImporters = /* @__PURE__ */ new Set();
+		this.resolutionsByImporter = /* @__PURE__ */ new Map();
+		this.sourcePreparations = /* @__PURE__ */ new Map();
+		this.removedSourcePaths = /* @__PURE__ */ new Set();
+		this.resolutionWork = {
+			moduleResolutionsAttempted: 0,
+			sourceFilesAdded: 0,
+			sourceFilesRead: 0
+		};
+	};
+	/** Files whose imports may resolve differently after a local file appears. */
+	getUnresolvedImporters = () => {
+		this.#assertNotLoading();
+		return [...this.unresolvedImporters].sort();
+	};
+	/** @internal Immutable resolution facts in importer/AST order. */
+	getResolutionLedger = () => {
+		this.#assertNotLoading();
+		return Object.freeze([...this.resolutionsByImporter.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).flatMap(([, entry]) => entry.facts));
+	};
+	/** @internal Every distinct local target represented by the current ledger. */
+	getResolvedSourceFiles = () => {
+		this.#assertNotLoading();
+		const paths = /* @__PURE__ */ new Set();
+		for (const entry of this.resolutionsByImporter.values()) for (const fact of entry.facts) if (fact.target) paths.add(fact.target);
+		return Object.freeze([...paths].sort());
+	};
+	/** @internal Deterministic resolver/add/read work, for regression assertions. */
+	getResolutionWork = () => {
+		this.#assertNotLoading();
+		return Object.freeze({ ...this.resolutionWork });
+	};
 	getSourceFile = (filePath) => {
+		this.#assertNotLoading();
 		return this.project.getSourceFile(filePath);
 	};
 	/** ts-morph reports forward slashes; normalize callers' paths to match on Windows. */
 	normalizePath = (filePath) => filePath.replaceAll("\\", "/");
-	/**
-	* Resolves a module specifier to a file already in the project.
-	*
-	* Deliberately not `decl.getModuleSpecifierSourceFile()`: that goes through the
-	* symbol table, which forces `initializeTypeChecker` on first use and costs
-	* hundreds of ms on a cold build. `ts.resolveModuleName` is purely a filesystem
-	* lookup, and a shared cache keeps repeat specifiers off the disk.
-	*
-	* Looks the result up rather than adding it, so resolving `react` cannot pull a
-	* `.d.ts` into the project. The graph only tracks files bamboo already scans.
-	*/
-	moduleResolutionCache;
+	/** Shared filesystem-only resolution cache; no type checker is constructed. */
+	#moduleResolutionCache;
 	/**
 	* Everything memoized against the shape of the file tree, including the negative half.
 	*
@@ -1414,56 +1680,383 @@ var Project = class {
 	* importing it, since resolution is what finds one.
 	*/
 	invalidate = (fileTreeChanged = true) => {
+		this.#assertNotLoading();
 		invalidateResolutions();
-		if (fileTreeChanged) this.moduleResolutionCache = void 0;
-	};
-	resolveImport = (decl) => {
-		const moduleName = decl.getModuleSpecifierValue();
-		if (!moduleName) return;
-		const compilerOptions = this.project.getCompilerOptions();
-		this.moduleResolutionCache ??= ts.createModuleResolutionCache(this.project.getFileSystem().getCurrentDirectory(), (f) => f, compilerOptions);
-		const name = ts.resolveModuleName(moduleName, decl.getSourceFile().getFilePath(), compilerOptions, this.project.getModuleResolutionHost(), this.moduleResolutionCache).resolvedModule?.resolvedFileName;
-		return name ? this.project.getSourceFile(name) : void 0;
+		if (fileTreeChanged) {
+			this.#moduleResolutionCache = void 0;
+			this.#fileTreeRevision++;
+		}
 	};
 	/**
-	* `resolveImport` in the shape a caller can use, for a specifier read off any declaration.
+	* Invalidate module/evaluator state after a resolver configuration byte changes.
+	*
+	* Unlike `resetResolutionState`, this keeps the published dependency graph long enough for
+	* an incremental consumer to take its old dependent closure. Each reparsed importer replaces
+	* its own facts under the bumped revision; unrelated graph entries remain available until
+	* they are next queried instead of forcing a whole-project rebuild.
 	*
-	* Shares the module resolution cache above, so a barrel resolved while tracking
-	* dependencies is not resolved again while looking for recipes.
+	* @internal
 	*/
-	resolveModule = (specifier, from) => this.resolveImport({
-		getModuleSpecifierValue: () => specifier,
-		getSourceFile: () => from
-	});
+	refreshResolutionConfiguration = (compilerOptions, resolutionConfigFiles, replaceCompilerOptions) => {
+		this.#assertNotLoading();
+		this.options.resolutionConfigFiles = Object.freeze([...new Set(resolutionConfigFiles)].sort());
+		if (replaceCompilerOptions) {
+			const next = prepareTsProjectOptions({ compilerOptions }, false, this.options.parserOptions.config.cwd || process.cwd()).compilerOptions ?? {};
+			this.#sourceFiles.projectOptions = {
+				...this.#sourceFiles.projectOptions,
+				compilerOptions: snapshotProjectOption(next)
+			};
+			if (this.#sourceFiles.phase === "ready") {
+				const current = this.project.getCompilerOptions();
+				const cleared = Object.fromEntries(Object.keys(current).map((key) => [key, void 0]));
+				this.project.compilerOptions.set({
+					...cleared,
+					...next
+				});
+			}
+		}
+		invalidateResolutions();
+		this.#moduleResolutionCache = void 0;
+		this.#fileTreeRevision++;
+		this.sourcePreparations.clear();
+	};
+	isLocalAlias = (specifier) => {
+		const paths = this.project.getCompilerOptions().paths;
+		if (!paths) return false;
+		return Object.keys(paths).some((pattern) => {
+			const wildcard = pattern.indexOf("*");
+			if (wildcard === -1) return pattern === specifier;
+			return specifier.startsWith(pattern.slice(0, wildcard)) && specifier.endsWith(pattern.slice(wildcard + 1));
+		});
+	};
+	getLocalFailedLookupCandidates = (failedLookupLocations) => {
+		const seen = /* @__PURE__ */ new Set();
+		const candidates = [];
+		for (const filePath of failedLookupLocations ?? []) {
+			const normalized = this.normalizePath(filePath);
+			if (normalized.includes("/node_modules/") || normalized.endsWith("/package.json")) continue;
+			if (!seen.has(normalized) && this.isInCheckout(normalized)) {
+				seen.add(normalized);
+				candidates.push(normalized);
+			}
+		}
+		return candidates;
+	};
+	isUnresolvedLocalSpecifier = (specifier, pendingCandidates) => specifier.startsWith(".") || specifier.startsWith("/") || this.isLocalAlias(specifier) || pendingCandidates.length > 0;
+	isInCheckout = (filePath) => {
+		if (this.#sourceFiles.projectOptions.useInMemoryFileSystem) return true;
+		const fileSystem = this.project.getFileSystem();
+		const configured = this.options.parserOptions.config.cwd;
+		const spelledRoot = this.normalizePath(configured || fileSystem.getCurrentDirectory()).replace(/\/$/, "");
+		const root = this.normalizePath(fileSystem.realpathSync(spelledRoot)).replace(/\/$/, "");
+		let target;
+		try {
+			target = this.normalizePath(fileSystem.realpathSync(filePath));
+		} catch (error) {
+			if (!isMissingPathShapeError(error)) throw error;
+			target = this.normalizePath(filePath);
+		}
+		return [root, spelledRoot].some((boundary) => target === boundary || target.startsWith(`${boundary}/`));
+	};
+	resolveSpecifier = (moduleName, from) => {
+		this.#assertNotLoading();
+		const project = this.project;
+		const compilerOptions = project.getCompilerOptions();
+		this.#moduleResolutionCache ??= ts.createModuleResolutionCache(project.getFileSystem().getCurrentDirectory(), (f) => f, compilerOptions);
+		const configurationFiles = /* @__PURE__ */ new Set();
+		const resolutionHost = project.getModuleResolutionHost();
+		const recordConfigurationFile = (filePath) => {
+			const normalized = this.normalizePath(filePath);
+			if (!normalized.endsWith("/package.json") || normalized.includes("/node_modules/")) return;
+			if (!this.isInCheckout(normalized)) return;
+			configurationFiles.add(normalized);
+		};
+		const host = {
+			...resolutionHost,
+			fileExists: (filePath) => {
+				recordConfigurationFile(filePath);
+				return resolutionHost.fileExists(filePath);
+			},
+			readFile: (filePath) => {
+				recordConfigurationFile(filePath);
+				return resolutionHost.readFile?.(filePath);
+			}
+		};
+		this.resolutionWork.moduleResolutionsAttempted++;
+		const resolved = ts.resolveModuleName(moduleName, from.getFilePath(), compilerOptions, host, this.#moduleResolutionCache);
+		const failedLookupLocations = resolved.failedLookupLocations;
+		const affectingLocations = resolved.affectingLocations;
+		for (const filePath of affectingLocations ?? []) recordConfigurationFile(filePath);
+		const pendingCandidates = this.getLocalFailedLookupCandidates(failedLookupLocations);
+		const module = resolved.resolvedModule;
+		if (!module) return {
+			configurationFiles: [...configurationFiles].sort(),
+			local: this.isUnresolvedLocalSpecifier(moduleName, pendingCandidates) || moduleName.startsWith("#"),
+			pendingCandidates
+		};
+		const name = this.normalizePath(module.resolvedFileName);
+		if (module.isExternalLibraryImport || name.includes("/node_modules/")) return {
+			configurationFiles: [],
+			local: false,
+			pendingCandidates: []
+		};
+		if (!this.isInCheckout(name)) return {
+			configurationFiles: [...configurationFiles].sort(),
+			local: this.isUnresolvedLocalSpecifier(moduleName, pendingCandidates),
+			pendingCandidates
+		};
+		const existing = project.getSourceFile(name);
+		if (existing) {
+			this.removedSourcePaths.delete(name);
+			return {
+				configurationFiles: [...configurationFiles].sort(),
+				local: true,
+				pendingCandidates,
+				sourceFile: existing
+			};
+		}
+		const withResolvedTarget = pendingCandidates.includes(name) ? pendingCandidates : [...pendingCandidates, name];
+		if (this.removedSourcePaths.has(name)) return {
+			configurationFiles: [...configurationFiles].sort(),
+			local: true,
+			pendingCandidates: withResolvedTarget
+		};
+		try {
+			this.resolutionWork.sourceFilesRead++;
+			const content = project.getFileSystem().readFileSync(name);
+			const sourceFile = project.createSourceFile(name, content, {
+				overwrite: true,
+				scriptKind: scriptKindFor(name)
+			});
+			this.resolutionWork.sourceFilesAdded++;
+			this.canonicalPaths.set(name, this.normalizePath(sourceFile.getFilePath()));
+			return {
+				configurationFiles: [...configurationFiles].sort(),
+				local: true,
+				pendingCandidates,
+				sourceFile
+			};
+		} catch (error) {
+			if (error?.code !== "ENOENT") throw error;
+			return {
+				configurationFiles: [...configurationFiles].sort(),
+				local: true,
+				pendingCandidates: withResolvedTarget
+			};
+		}
+	};
+	retractImporter = (importer) => {
+		for (const previous of this.dependencies.get(importer) ?? []) {
+			const reverse = this.dependents.get(previous);
+			reverse?.delete(importer);
+			if (reverse?.size === 0) this.dependents.delete(previous);
+		}
+		this.dependencies.delete(importer);
+		this.unresolvedImporters.delete(importer);
+		this.resolutionsByImporter.delete(importer);
+		for (const [removed, importers] of this.removedDependents) {
+			importers.delete(importer);
+			if (importers.size === 0) this.removedDependents.delete(removed);
+		}
+	};
+	publishResolutionFacts = (importer, sourceFile, text, facts, pendingCandidates, configurationFiles) => {
+		this.retractImporter(importer);
+		const current = /* @__PURE__ */ new Set();
+		for (const fact of facts) {
+			if (!fact.target || fact.target === importer) continue;
+			const importers = this.dependents.get(fact.target) ?? /* @__PURE__ */ new Set();
+			importers.add(importer);
+			this.dependents.set(fact.target, importers);
+			current.add(fact.target);
+		}
+		this.dependencies.set(importer, current);
+		if (pendingCandidates.length > 0 || facts.some((fact) => fact.target === null)) this.unresolvedImporters.add(importer);
+		this.resolutionsByImporter.set(importer, {
+			configurationFiles: Object.freeze([...configurationFiles]),
+			facts: Object.freeze([...facts]),
+			hasPendingLocalCandidate: pendingCandidates.length > 0,
+			pendingCandidates: Object.freeze([...pendingCandidates]),
+			sourceFile,
+			text,
+			treeRevision: this.#fileTreeRevision
+		});
+	};
+	ensureResolutionFacts = (sourceFile) => {
+		this.#assertNotLoading();
+		const importer = this.normalizePath(sourceFile.getFilePath());
+		const text = sourceFile.getFullText();
+		const cached = this.resolutionsByImporter.get(importer);
+		if (cached?.sourceFile === sourceFile && cached.text === text && cached.treeRevision === this.#fileTreeRevision) return cached;
+		const declarations = [...sourceFile.getImportDeclarations().map((declaration) => ({
+			declaration,
+			kind: "import"
+		})), ...sourceFile.getExportDeclarations().map((declaration) => ({
+			declaration,
+			kind: "export"
+		}))].filter(({ declaration }) => declaration.getModuleSpecifierValue() !== void 0).sort((left, right) => left.declaration.getStart() - right.declaration.getStart());
+		const facts = [];
+		const pendingCandidates = [];
+		const configurationFiles = [];
+		for (const [ordinal, { declaration, kind }] of declarations.entries()) {
+			const specifier = declaration.getModuleSpecifierValue();
+			if (!specifier) continue;
+			const resolved = this.resolveSpecifier(specifier, sourceFile);
+			if (!resolved.local) continue;
+			facts.push(Object.freeze({
+				importer,
+				target: resolved.sourceFile ? this.normalizePath(resolved.sourceFile.getFilePath()) : null,
+				specifier,
+				kind,
+				ordinal
+			}));
+			for (const target of resolved.pendingCandidates) pendingCandidates.push(Object.freeze({
+				importer,
+				target,
+				specifier,
+				kind,
+				ordinal
+			}));
+			for (const target of resolved.configurationFiles) configurationFiles.push(Object.freeze({
+				importer,
+				target,
+				specifier,
+				kind,
+				ordinal
+			}));
+		}
+		this.publishResolutionFacts(importer, sourceFile, text, facts, pendingCandidates, configurationFiles);
+		return this.resolutionsByImporter.get(importer);
+	};
+	/** The sole cross-file source resolver supplied to parser and extractor. */
+	resolveModule = (specifier, from) => {
+		const target = this.ensureResolutionFacts(from).facts.find((fact) => fact.specifier === specifier)?.target;
+		if (!target) return;
+		const sourceFile = this.project.getSourceFile(target);
+		if (!sourceFile) return;
+		this.prepareEffectiveSource(sourceFile.getFilePath(), sourceFile);
+		return sourceFile;
+	};
 	trackDependencies = (filePath, sourceFile) => {
+		this.#assertNotLoading();
 		const importer = this.normalizePath(sourceFile.getFilePath());
 		this.canonicalPaths.set(this.normalizePath(filePath), importer);
-		for (const previous of this.dependencies.get(importer) ?? []) this.dependents.get(previous)?.delete(importer);
-		const current = /* @__PURE__ */ new Set();
-		const declarations = [...sourceFile.getImportDeclarations(), ...sourceFile.getExportDeclarations()];
-		let unresolved = false;
-		for (const decl of declarations) {
-			const imported = this.resolveImport(decl);
-			if (!imported) {
-				if (decl.getModuleSpecifierValue()?.startsWith(".")) unresolved = true;
-				continue;
+		this.canonicalPaths.set(importer, importer);
+		this.ensureResolutionFacts(sourceFile);
+	};
+	invalidateSourcePreparation = (filePath, sourceFile) => {
+		const sourcePath = this.normalizePath(sourceFile?.getFilePath() ?? filePath);
+		const preparation = this.sourcePreparations.get(sourcePath);
+		if (preparation?.state === "preparing") preparation.invalidated = true;
+		this.sourcePreparations.delete(sourcePath);
+		this.retractImporter(sourcePath);
+	};
+	/**
+	* Apply the parser hook and built-in transform once to one source revision.
+	*
+	* Resolver traversal is a semantic read just as surely as an explicit parse: returning a
+	* raw dependency here would let parse order decide both the value extraction sees and the
+	* downstream edges the ledger records. The transaction is published only after the AST and
+	* its facts agree. A failed or re-entered attempt restores the input AST and can be retried.
+	*/
+	prepareEffectiveSource = (filePath, sourceFile) => {
+		this.#assertNotLoading();
+		const sourcePath = this.normalizePath(sourceFile.getFilePath());
+		const currentText = sourceFile.getFullText();
+		const current = this.sourcePreparations.get(sourcePath);
+		if (current?.state === "ready" && current.sourceFile === sourceFile && current.effectiveText === currentText) {
+			this.trackDependencies(filePath, sourceFile);
+			return current;
+		}
+		if (current?.state === "preparing") {
+			current.invalidated = true;
+			throw new Error(`Project source is already being prepared: ${sourcePath}`);
+		}
+		this.sourcePreparations.delete(sourcePath);
+		this.retractImporter(sourcePath);
+		const transaction = {
+			state: "preparing",
+			sourceFile,
+			inputText: currentText,
+			invalidated: false
+		};
+		this.sourcePreparations.set(sourcePath, transaction);
+		const assertTransaction = (expectedText) => {
+			let actualText;
+			try {
+				actualText = sourceFile.getFullText();
+			} catch {
+				transaction.invalidated = true;
+				actualText = "";
 			}
-			const importedPath = this.normalizePath(imported.getFilePath());
-			if (importedPath === importer) continue;
-			const importers = this.dependents.get(importedPath) ?? /* @__PURE__ */ new Set();
-			importers.add(importer);
-			this.dependents.set(importedPath, importers);
-			current.add(importedPath);
+			if (transaction.invalidated || this.sourcePreparations.get(sourcePath) !== transaction || actualText !== expectedText) throw new Error(`Project source changed while it was being prepared: ${sourcePath}`);
+		};
+		const options = {};
+		try {
+			const custom = this.options.hooks["parser:before"]?.({
+				filePath,
+				content: currentText,
+				configure(next) {
+					const { matchTag, matchTagMode, matchTagProp } = next;
+					if (matchTag) options.matchTag = matchTag;
+					if (matchTagMode) options.matchTagMode = matchTagMode;
+					if (matchTagProp) options.matchTagProp = matchTagProp;
+				}
+			});
+			assertTransaction(currentText);
+			const transformed = custom ?? this.transformFile(filePath, currentText);
+			assertTransaction(currentText);
+			if (currentText !== transformed) sourceFile.replaceWithText(transformed);
+			assertTransaction(transformed);
+			this.trackDependencies(filePath, sourceFile);
+			assertTransaction(transformed);
+			const ready = Object.freeze({
+				state: "ready",
+				sourceFile,
+				inputText: currentText,
+				effectiveText: transformed,
+				options: Object.freeze({ ...options })
+			});
+			this.sourcePreparations.set(sourcePath, ready);
+			return ready;
+		} catch (error) {
+			if (this.sourcePreparations.get(sourcePath) === transaction) this.sourcePreparations.delete(sourcePath);
+			this.retractImporter(sourcePath);
+			try {
+				if (sourceFile.getFullText() !== currentText) sourceFile.replaceWithText(currentText);
+			} catch {}
+			throw error;
 		}
-		this.dependencies.set(importer, current);
-		if (unresolved) this.unresolvedImporters.add(importer);
-		else this.unresolvedImporters.delete(importer);
+	};
+	markTargetRemoved = (target, sourceFile) => {
+		const importers = new Set(this.dependents.get(target) ?? []);
+		if (importers.size > 0) this.removedDependents.set(target, importers);
+		for (const importer of importers) {
+			const entry = this.resolutionsByImporter.get(importer);
+			if (!entry) continue;
+			const facts = entry.facts.map((fact) => fact.target === target ? Object.freeze({
+				...fact,
+				target: null
+			}) : fact);
+			this.dependencies.get(importer)?.delete(target);
+			if (facts.some((fact) => fact.target === null)) this.unresolvedImporters.add(importer);
+			this.resolutionsByImporter.set(importer, {
+				...entry,
+				facts: Object.freeze(facts),
+				hasPendingLocalCandidate: true
+			});
+		}
+		this.dependents.delete(target);
+		this.retractImporter(target);
+		this.removedSourcePaths.add(target);
+		this.canonicalPaths.set(target, target);
+		this.canonicalPaths.set(this.normalizePath(sourceFile.getFilePath()), target);
 	};
 	/**
 	* Every file that transitively imports `filePath`, so a watcher can re-parse the
 	* consumers of an edited file. Excludes `filePath` itself.
 	*/
 	getDependents = (filePath) => {
+		this.#assertNotLoading();
 		const given = this.normalizePath(filePath);
 		const resolved = this.project.getSourceFile(filePath)?.getFilePath();
 		const start = resolved ? this.normalizePath(resolved) : this.canonicalPaths.get(given) ?? given;
@@ -1471,23 +2064,139 @@ var Project = class {
 		const queue = [start];
 		while (queue.length) {
 			const current = queue.shift();
-			for (const importer of this.dependents.get(current) ?? []) {
+			const importers = new Set([...this.dependents.get(current) ?? [], ...this.removedDependents.get(current) ?? []]);
+			for (const importer of [...importers].sort()) {
 				if (importer === start || seen.has(importer)) continue;
 				seen.add(importer);
 				queue.push(importer);
 			}
 		}
-		return [...seen];
+		return [...seen].sort();
+	};
+	/**
+	* Every local source transitively read by `filePath`, excluding the file itself. When
+	* `targets` are supplied, retain only paths leading to one of those semantic reads.
+	*
+	* This is the forward half of `getDependents`, exposed for bundler consumers which must
+	* register the complete semantic read-set as watch files. Walking the indexed ledger closure
+	* avoids rescanning every resolution fact once per transformed module.
+	*/
+	getDependencies = (filePath, targets) => {
+		this.#assertNotLoading();
+		const given = this.normalizePath(filePath);
+		const resolved = this.project.getSourceFile(filePath)?.getFilePath();
+		const start = resolved ? this.normalizePath(resolved) : this.canonicalPaths.get(given) ?? given;
+		const seen = /* @__PURE__ */ new Set();
+		const importersByDependency = /* @__PURE__ */ new Map();
+		const queue = [start];
+		while (queue.length) {
+			const current = queue.shift();
+			for (const dependency of [...this.dependencies.get(current) ?? []].sort()) {
+				const importers = importersByDependency.get(dependency) ?? /* @__PURE__ */ new Set();
+				importers.add(current);
+				importersByDependency.set(dependency, importers);
+				if (dependency === start || seen.has(dependency)) continue;
+				seen.add(dependency);
+				queue.push(dependency);
+			}
+		}
+		if (targets === void 0) return [...seen].sort();
+		const selected = /* @__PURE__ */ new Set();
+		const reverse = Array.from(targets, (target) => {
+			const normalized = this.normalizePath(target);
+			const source = this.project.getSourceFile(target)?.getFilePath();
+			return source ? this.normalizePath(source) : this.canonicalPaths.get(normalized) ?? normalized;
+		}).filter((target) => seen.has(target));
+		while (reverse.length) {
+			const dependency = reverse.shift();
+			if (selected.has(dependency)) continue;
+			selected.add(dependency);
+			for (const importer of importersByDependency.get(dependency) ?? []) if (importer !== start && !selected.has(importer)) reverse.push(importer);
+		}
+		return [...selected].sort();
+	};
+	/**
+	* Exact semantic dependencies plus missing local resolver candidates which can supersede
+	* one of those dependencies.
+	*
+	* Candidate provenance stays attached to its import/export fact. Filtering those facts
+	* through the selected dependency closure keeps an unrelated runtime import—even a local
+	* alias with its own fallback—out of the watch set without asking consumers to reinterpret
+	* specifiers or scan the checkout.
+	*/
+	getResolutionReadSet = (filePath, targets, previous) => {
+		const dependencies = this.getDependencies(filePath, targets);
+		const selected = new Set(dependencies);
+		const retained = new Set([...previous?.dependencies ?? [], ...previous?.pendingCandidates ?? []]);
+		const given = this.normalizePath(filePath);
+		const resolved = this.project.getSourceFile(filePath)?.getFilePath();
+		const start = resolved ? this.normalizePath(resolved) : this.canonicalPaths.get(given) ?? given;
+		const pendingCandidates = /* @__PURE__ */ new Set();
+		for (const importer of [start, ...dependencies]) {
+			const resolution = this.resolutionsByImporter.get(importer);
+			if (!resolution) continue;
+			const semanticOrdinals = new Set(resolution.facts.filter((fact) => fact.target !== null && selected.has(fact.target)).map((fact) => fact.ordinal));
+			for (const fact of resolution.facts) {
+				if (fact.target !== null) continue;
+				if (resolution.pendingCandidates.some((candidate) => candidate.ordinal === fact.ordinal && retained.has(candidate.target))) semanticOrdinals.add(fact.ordinal);
+			}
+			for (const candidate of resolution.pendingCandidates) if (semanticOrdinals.has(candidate.ordinal)) pendingCandidates.add(candidate.target);
+		}
+		return Object.freeze({
+			dependencies: Object.freeze([...dependencies]),
+			pendingCandidates: Object.freeze([...pendingCandidates].sort())
+		});
+	};
+	/**
+	* Exact resolution configuration files read by the semantic closure selected by `targets`.
+	*
+	* Package manifests stay attached to their import/export ordinal, so a runtime-only branch
+	* cannot turn an arbitrary package.json into a Builder dependency. Tsconfig files are global
+	* inputs to those same selected facts and are added only when the owner has a semantic
+	* cross-file read.
+	*
+	* @internal
+	*/
+	getResolutionConfigurationFiles = (filePath, targets, previous = []) => {
+		const dependencies = this.getDependencies(filePath, targets);
+		const selected = new Set(dependencies);
+		const retained = new Set(Array.from(previous, (file) => this.normalizePath(file)));
+		const given = this.normalizePath(filePath);
+		const resolved = this.project.getSourceFile(filePath)?.getFilePath();
+		const start = resolved ? this.normalizePath(resolved) : this.canonicalPaths.get(given) ?? given;
+		const files = /* @__PURE__ */ new Set();
+		let hasSemanticFact = false;
+		for (const importer of [start, ...dependencies]) {
+			const resolution = this.resolutionsByImporter.get(importer);
+			if (!resolution) continue;
+			const semanticOrdinals = new Set(resolution.facts.filter((fact) => fact.target !== null && selected.has(fact.target)).map((fact) => fact.ordinal));
+			for (const fact of resolution.facts) {
+				if (fact.target !== null) continue;
+				if (resolution.configurationFiles.some((configuration) => configuration.ordinal === fact.ordinal && retained.has(configuration.target))) semanticOrdinals.add(fact.ordinal);
+			}
+			if (semanticOrdinals.size > 0) hasSemanticFact = true;
+			for (const configuration of resolution.configurationFiles) if (semanticOrdinals.has(configuration.ordinal)) files.add(configuration.target);
+		}
+		if (hasSemanticFact) for (const file of this.options.resolutionConfigFiles ?? []) files.add(this.normalizePath(file));
+		return Object.freeze([...files].sort());
 	};
 	createSourceFile = (filePath) => {
+		this.#assertNotLoading();
+		this.#ensureSourceFiles();
 		const { readFile } = this.options;
+		const content = readFile(filePath);
+		const existing = this.project.getSourceFile(filePath);
+		this.invalidateSourcePreparation(filePath, existing);
+		this.removedSourcePaths.delete(this.normalizePath(filePath));
 		this.invalidate();
-		return this.project.createSourceFile(filePath, readFile(filePath), {
+		return this.project.createSourceFile(filePath, content, {
 			overwrite: true,
 			scriptKind: scriptKindFor(filePath)
 		});
 	};
 	createSourceFiles = () => {
+		this.#assertNotLoading();
+		this.#ensureSourceFiles();
 		const files = this.getFiles();
 		for (const file of files) try {
 			this.createSourceFile(file);
@@ -1496,6 +2205,8 @@ var Project = class {
 		}
 	};
 	addSourceFile = (filePath, content) => {
+		this.#assertNotLoading();
+		this.#ensureSourceFiles();
 		const existing = filePath.includes("/") ? this.project.getSourceFile(filePath) : void 0;
 		/**
 		* Re-adding a file the text it already holds is a no-op, and saying so is what makes the
@@ -1520,6 +2231,8 @@ var Project = class {
 		* matches its own source, falls through, and is overwritten exactly as before.
 		*/
 		if (existing && existing.getFullText() === content) return existing;
+		this.invalidateSourcePreparation(filePath, existing);
+		this.removedSourcePaths.delete(this.normalizePath(filePath));
 		this.invalidate(!existing);
 		return this.project.createSourceFile(filePath, content, {
 			overwrite: true,
@@ -1527,54 +2240,69 @@ var Project = class {
 		});
 	};
 	removeSourceFile = (filePath) => {
+		this.#assertNotLoading();
+		this.#ensureSourceFiles();
 		const sourceFile = this.project.getSourceFile(filePath);
 		if (sourceFile) {
 			this.invalidate();
+			this.invalidateSourcePreparation(filePath, sourceFile);
+			this.markTargetRemoved(this.normalizePath(sourceFile.getFilePath()), sourceFile);
 			this.options.parserOptions.encoder.releaseFile(sourceFile.getFilePath());
 			return this.project.removeSourceFile(sourceFile);
 		}
 		return false;
 	};
 	reloadSourceFile = (filePath) => {
+		this.#assertNotLoading();
+		this.#ensureSourceFiles();
 		this.invalidate(false);
-		return this.getSourceFile(filePath)?.refreshFromFileSystemSync();
+		const sourceFile = this.getSourceFile(filePath);
+		if (!sourceFile) return;
+		this.invalidateSourcePreparation(filePath, sourceFile);
+		return sourceFile.refreshFromFileSystemSync();
 	};
 	reloadSourceFiles = () => {
+		this.#assertNotLoading();
+		this.#ensureSourceFiles();
 		const files = this.getFiles();
 		this.invalidate();
-		for (const file of files) this.getSourceFile(file)?.refreshFromFileSystemSync() ?? this.project.addSourceFileAtPath(file);
+		for (const file of files) {
+			const source = this.getSourceFile(file);
+			if (source) {
+				this.invalidateSourcePreparation(file, source);
+				source.refreshFromFileSystemSync();
+			} else {
+				this.invalidateSourcePreparation(file);
+				this.removedSourcePaths.delete(this.normalizePath(file));
+				this.project.createSourceFile(file, this.options.readFile(file), {
+					overwrite: true,
+					scriptKind: scriptKindFor(file)
+				});
+			}
+		}
 	};
 	get readFile() {
+		this.#assertNotLoading();
 		return this.options.readFile;
 	}
 	get getFiles() {
+		this.#assertNotLoading();
 		return this.options.getFiles;
 	}
 	parseJson = (filePath) => {
+		this.#assertNotLoading();
 		const { readFile, parserOptions } = this.options;
 		const content = readFile(filePath);
 		parserOptions.encoder.fromJSON(JSON.parse(content));
 		return new ParserResult(parserOptions).setFilePath(filePath);
 	};
 	parseSourceFile = (filePath, encoder) => {
+		this.#assertNotLoading();
 		const { hooks } = this.options;
 		if (filePath.endsWith(".json")) return this.parseJson(filePath);
 		const sourceFile = this.project.getSourceFile(filePath);
 		if (!sourceFile) return;
-		this.trackDependencies(filePath, sourceFile);
-		const original = sourceFile.getText();
-		const options = {};
-		const transformed = hooks["parser:before"]?.({
-			filePath,
-			content: original,
-			configure(opts) {
-				const { matchTag, matchTagMode, matchTagProp } = opts;
-				if (matchTag) options.matchTag = matchTag;
-				if (matchTagMode) options.matchTagMode = matchTagMode;
-				if (matchTagProp) options.matchTagProp = matchTagProp;
-			}
-		}) ?? this.transformFile(filePath, original);
-		if (original !== transformed) sourceFile.replaceWithText(transformed);
+		const { options } = this.prepareEffectiveSource(filePath, sourceFile);
 		const result = (encoder ?? this.options.parserOptions.encoder).withOwner("parse", sourceFile.getFilePath(), () => this.parser(sourceFile, encoder, options, this.resolveModule))?.setFilePath(filePath);
 		hooks["parser:after"]?.({
 			filePath,
@@ -1583,9 +2311,11 @@ var Project = class {
 		return result;
 	};
 	transformFile = (_filePath, content) => {
+		this.#assertNotLoading();
 		return content;
 	};
 	classify = (fileMap) => {
+		this.#assertNotLoading();
 		const { parserOptions } = this.options;
 		return classifyProject(parserOptions, fileMap);
 	};