@animus-ui/extract 0.1.7 → 0.1.9

package/dist/index.cjs

@@ -24,13 +24,14 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let crypto = require("crypto");
 let fs = require("fs");
 let path = require("path");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = __toESM(node_path);
 let module$1 = require("module");
 let browserslist = require("browserslist");
 browserslist = __toESM(browserslist);
 let lightningcss = require("lightningcss");
 let _animus_ui_properties = require("@animus-ui/properties");
-let node_fs = require("node:fs");
-let node_path = require("node:path");
 //#region pipeline/assemble-stylesheet.ts
 /**
 * The 7 Animus cascade layers. Always prefixed with `anm-` to avoid
@@ -123,7 +124,8 @@ function buildAnalyzeProjectArgs(inputs) {
 		inputs.keyframesJson,
 		inputs.staticCssJson,
 		inputs.conditionAliasesJson,
-		inputs.externalDirsJson
+		inputs.externalDirsJson,
+		inputs.transformSourcesJson
 	];
 }
 //#endregion
@@ -142,7 +144,7 @@ function createV2EngineApi(deps) {
 		return {
 			loadSystemModule: (...args) => native.loadSystemModule(...args),
 			scanKeyframesExports: (entryPath, rootDir) => native.scanKeyframesExports(entryPath, rootDir) ?? null,
-			analyzeProject: (filesJsonRaw, scalesJson, variableMapJson, contextualVarsJson, propConfigJson, groupRegistryJson, packageResolutionJson, devMode, emitterConfigJson, selectorAliasesJson, _selectorOrderJson, globalStyleBlocksJson, pathAliasesJson, keyframesJson, staticCssJson, conditionAliasesJson, externalDirsJson) => {
+			analyzeProject: (filesJsonRaw, scalesJson, variableMapJson, contextualVarsJson, propConfigJson, groupRegistryJson, packageResolutionJson, devMode, emitterConfigJson, selectorAliasesJson, _selectorOrderJson, globalStyleBlocksJson, pathAliasesJson, keyframesJson, staticCssJson, conditionAliasesJson, externalDirsJson, transformSourcesJson) => {
 				const filesJson = deps.rehydrateFilesJson ? deps.rehydrateFilesJson(filesJsonRaw) : filesJsonRaw;
 				const sent = /* @__PURE__ */ new Map();
 				for (const entry of JSON.parse(filesJson)) sent.set(entry.path, entry.source);
@@ -166,6 +168,7 @@ function createV2EngineApi(deps) {
 					pathAliasesJson: pathAliasesJson ?? void 0,
 					staticCssJson: staticCssJson ?? void 0,
 					externalDirsJson: externalDirsJson ?? void 0,
+					transformSourcesJson: transformSourcesJson ?? void 0,
 					devMode
 				};
 				const engine = new native.ExtractEngine(config);
@@ -337,6 +340,126 @@ function discoverFiles(dir, rootDir, excludePatterns, extensionsSet) {
 	return results;
 }
 //#endregion
+//#region pipeline/source-identity.ts
+/**
+* SourceId derivation authority + allowlist membership (openspec:
+* external-source-watch-ingestion, design D1/D2/D5).
+*
+* One shared derivation produces the canonical source identity consumed by
+* discovery, watch ingestion, ownership, deletion pruning, and diagnostics
+* — raw event paths are lookup INPUTS only, so event spelling (symlink
+* alias vs canonical, lexical vs realpath) can never fork identity.
+*
+* The containment and volume helpers are pure and path-API-injectable so
+* Windows semantics are unit-testable via `path.win32` on any host; runtime
+* callers use the ambient platform implementation.
+*/
+/**
+* Structural containment: `target` is the root itself or a descendant of it,
+* decided by `relative()` shape — never by string prefixing, so `/ui` can
+* never claim `/ui-old`, and a cross-drive win32 target (whose relative()
+* result is absolute) is never contained.
+*/
+function isPathWithinRoot(root, target, pathApi = node_path.default) {
+	const rel = pathApi.relative(root, target);
+	return rel === "" || !pathApi.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + pathApi.sep);
+}
+/**
+* Cross-volume gate (design D5): two paths share a platform path root
+* (win32 drive letter or UNC share; always true on posix). Compared
+* case-insensitively — win32 drive letters are case-insensitive.
+*/
+function sharesVolumeRoot(a, b, pathApi = node_path.default) {
+	const volumeOf = (p) => pathApi.parse(pathApi.resolve(p)).root.toLowerCase();
+	return volumeOf(a) === volumeOf(b);
+}
+function canonicalize(p) {
+	try {
+		return (0, node_fs.realpathSync)(p);
+	} catch {
+		return null;
+	}
+}
+function createSourceIdentity(rootDir) {
+	const normalizedRootDir = node_path.default.normalize(rootDir);
+	const canonicalRootDir = canonicalize(normalizedRootDir) ?? normalizedRootDir;
+	const roots = [];
+	const aliases = /* @__PURE__ */ new Map();
+	const owningRecord = (canonicalPath) => {
+		let owner = null;
+		for (const record of roots) {
+			if (!isPathWithinRoot(record.canonical, canonicalPath)) continue;
+			if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+		}
+		return owner;
+	};
+	return {
+		rootDir: normalizedRootDir,
+		canonicalRootDir,
+		registerExternalRoot(root) {
+			const asRegistered = node_path.default.normalize(root);
+			const canonical = canonicalize(asRegistered) ?? asRegistered;
+			const existing = roots.find((record) => record.canonical === canonical);
+			if (existing) return existing.canonical;
+			roots.push({
+				asRegistered,
+				canonical
+			});
+			return canonical;
+		},
+		externalRoots() {
+			return roots.map((record) => record.canonical);
+		},
+		resolveSourceId(inputPath) {
+			const lexical = node_path.default.normalize(inputPath);
+			const canonical = canonicalize(lexical);
+			if (canonical === null) return null;
+			const owner = owningRecord(canonical);
+			const ownedBy = (record) => {
+				const pathInRoot = node_path.default.relative(record.canonical, canonical);
+				return {
+					sourceKey: node_path.default.relative(normalizedRootDir, node_path.default.join(record.asRegistered, pathInRoot)),
+					owningRoot: record.canonical,
+					pathInRoot
+				};
+			};
+			const ownerIsMoreSpecific = owner !== null && owner.canonical.length > canonicalRootDir.length;
+			let resolved;
+			if (!ownerIsMoreSpecific && isPathWithinRoot(canonicalRootDir, canonical)) {
+				const key = node_path.default.relative(canonicalRootDir, canonical);
+				resolved = {
+					sourceKey: key,
+					owningRoot: null,
+					pathInRoot: key
+				};
+			} else if (owner) resolved = ownedBy(owner);
+			else return null;
+			aliases.set(lexical, resolved);
+			aliases.set(canonical, resolved);
+			return resolved;
+		},
+		resolveDeletedSourceId(inputPath) {
+			return aliases.get(node_path.default.normalize(inputPath)) ?? null;
+		},
+		containingExternalRoot(inputPath) {
+			const lexical = node_path.default.normalize(inputPath);
+			let owner = null;
+			for (const record of roots) {
+				if (!(isPathWithinRoot(record.canonical, lexical) || isPathWithinRoot(record.asRegistered, lexical))) continue;
+				if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+			}
+			if (owner) return owner.canonical;
+			const canonical = canonicalize(lexical);
+			if (canonical === null) return null;
+			for (const record of roots) {
+				if (!isPathWithinRoot(record.canonical, canonical)) continue;
+				if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+			}
+			return owner?.canonical ?? null;
+		}
+	};
+}
+//#endregion
 //#region pipeline/discover-packages.ts
 /**
 * Walk up from a resolved package entry file to the nearest directory
@@ -361,6 +484,20 @@ const PACKAGE_SRC_EXCLUDES = [
 	".test.",
 	".spec."
 ];
+/** True when a PACKAGE-RELATIVE path matches a package-source exclusion
+*  fragment (the "within the package" filter — see PACKAGE_SRC_EXCLUDES). */
+function isExcludedPackageRelativePath(rel) {
+	return PACKAGE_SRC_EXCLUDES.some((pattern) => rel.includes(pattern));
+}
+/**
+* THE package-source walk (guardrail G1 — one policy): shared discovery with
+* no consumer patterns, then exclusion by package-relative path so fragments
+* in the package's own location can't blank out its sources. Used by the
+* collector, hosts' dirty-root rewalks, and watch-path classification alike.
+*/
+function walkPackageSources(packageDir, extensionsSet) {
+	return discoverFiles(packageDir, packageDir, [], extensionsSet).filter((absPath) => !isExcludedPackageRelativePath((0, path.relative)(packageDir, absPath)));
+}
 /** Exclusions for the compiled-output fallback when a package does not ship src/. */
 const PACKAGE_OUTPUT_EXCLUDES = [
 	"node_modules",
@@ -369,9 +506,9 @@ const PACKAGE_OUTPUT_EXCLUDES = [
 	".d.ts",
 	".map"
 ];
-const isFile = (path$2) => {
+const isFile = (path$3) => {
 	try {
-		return (0, fs.statSync)(path$2).isFile();
+		return (0, fs.statSync)(path$3).isFile();
 	} catch {
 		return false;
 	}
@@ -399,7 +536,7 @@ function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
 	if ((0, path.isAbsolute)(specifier)) {
 		const resolved = resolveAbsolutePathSpecifier(specifier, extensionsSet);
 		if (!resolved) return null;
-		return !(0, path.relative)(srcDir, resolved).startsWith("..") ? resolved : null;
+		return isPathWithinRoot(srcDir, resolved) ? resolved : null;
 	}
 	const packageName = bareSpecifierPackageName(specifier);
 	return resolveAbsolutePathSpecifier((0, path.join)(srcDir, specifier.slice(packageName.length + 1) || "index"), extensionsSet);
@@ -413,7 +550,7 @@ function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
 * file's mtime is readable. Detection only — reporting is the caller's policy.
 */
 function distEntryIsStale(absEntry, srcDir, srcFiles) {
-	if (!(0, path.relative)(srcDir, absEntry).startsWith("..")) return false;
+	if (isPathWithinRoot(srcDir, absEntry)) return false;
 	let distMtime;
 	try {
 		distMtime = (0, fs.statSync)(absEntry).mtimeMs;
@@ -445,15 +582,20 @@ function distEntryIsStale(absEntry, srcDir, srcFiles) {
 * them — any warning or gate is the caller's policy.
 */
 async function collectExternalPackageSources(opts) {
-	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable } = opts;
+	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable, onPackageResolved } = opts;
 	const entries = [];
 	const pushed = /* @__PURE__ */ new Set();
 	const packageMap = {};
 	const sourceEntries = /* @__PURE__ */ new Map();
+	const keyframesScanEntries = /* @__PURE__ */ new Map();
 	const packageDirs = [];
-	const dirOwners = {};
+	const dirOwnerSets = {};
+	const dirExtensions = {};
 	const fileOwners = {};
 	const outcomes = [];
+	const claimDir = (dir, specifier) => {
+		(dirOwnerSets[dir] ??= []).push(specifier);
+	};
 	const alreadyIngested = (relPath) => hasEntry(relPath) || pushed.has(relPath);
 	for (const specifier of specifiers) {
 		let absEntry;
@@ -476,12 +618,15 @@ async function collectExternalPackageSources(opts) {
 		let staleDist = false;
 		if ((0, fs.existsSync)(srcDir)) {
 			packageDirs.push(srcDir);
-			dirOwners[srcDir] ??= specifier;
+			claimDir(srcDir, specifier);
+			dirExtensions[srcDir] = [...extensionsSet];
+			onPackageResolved?.(specifier, srcDir);
 			const srcEntry = sourceEntryForSpecifier(specifier, srcDir, extensionsSet);
 			if (srcEntry) {
 				packageMap[specifier] = (0, path.relative)(rootDir, srcEntry);
 				sourceEntries.set(specifier, srcEntry);
 			} else packageMap[specifier] = (0, path.relative)(rootDir, absEntry);
+			keyframesScanEntries.set(specifier, srcEntry ?? absEntry);
 			if (!(0, path.isAbsolute)(specifier)) {
 				const packageName = bareSpecifierPackageName(specifier);
 				if (packageName !== specifier && !(packageName in packageMap)) {
@@ -489,13 +634,11 @@ async function collectExternalPackageSources(opts) {
 					if (rootEntry) {
 						packageMap[packageName] = (0, path.relative)(rootDir, rootEntry);
 						sourceEntries.set(packageName, rootEntry);
+						keyframesScanEntries.set(packageName, rootEntry);
 					}
 				}
 			}
-			const pkgFiles = discoverFiles(srcDir, srcDir, [], extensionsSet).filter((absPath) => {
-				const inPkg = (0, path.relative)(srcDir, absPath);
-				return !PACKAGE_SRC_EXCLUDES.some((pattern) => inPkg.includes(pattern));
-			});
+			const pkgFiles = walkPackageSources(srcDir, extensionsSet);
 			staleDist = distEntryIsStale(absEntry, srcDir, pkgFiles);
 			for (const pkgFile of pkgFiles) {
 				const relPath = (0, path.relative)(rootDir, pkgFile);
@@ -523,10 +666,13 @@ async function collectExternalPackageSources(opts) {
 		} else {
 			const outputDir = (0, path.dirname)(absEntry);
 			packageDirs.push(outputDir);
-			dirOwners[outputDir] ??= specifier;
+			claimDir(outputDir, specifier);
+			onPackageResolved?.(specifier, outputDir);
 			packageMap[specifier] = (0, path.relative)(rootDir, absEntry);
+			keyframesScanEntries.set(specifier, absEntry);
 			const outputExtensions = new Set(extensionsSet);
 			outputExtensions.add((0, path.extname)(absEntry));
+			dirExtensions[outputDir] = [...outputExtensions];
 			const outputFiles = discoverFiles(outputDir, outputDir, [], outputExtensions).filter((file) => {
 				const relToOutput = (0, path.relative)(outputDir, file);
 				return !PACKAGE_OUTPUT_EXCLUDES.some((pattern) => relToOutput.includes(pattern));
@@ -566,12 +712,78 @@ async function collectExternalPackageSources(opts) {
 		entries,
 		packageMap,
 		sourceEntries,
+		keyframesScanEntries,
 		packageDirs,
-		dirOwners,
+		dirOwnerSets,
+		dirExtensions,
 		fileOwners,
 		outcomes
 	};
 }
+/** First-declared specifier per package dir — the single-value ownership
+*  view correlation consumers key on, derived from `dirOwnerSets`. */
+function firstOwners(dirOwnerSets) {
+	const owners = {};
+	for (const [dir, specifiers] of Object.entries(dirOwnerSets)) if (specifiers.length > 0) owners[dir] = specifiers[0];
+	return owners;
+}
+/**
+* Excise a set of rejected specifiers from a collection result ATOMICALLY
+* (openspec: external-source-watch-ingestion, design D5): the returned copy
+* carries no entries, package-map targets, source entries, package dirs, or
+* ownership for the rejected packages — a package dir is removed only when
+* EVERY specifier that claimed it is rejected (a dir-level rejection, such
+* as the cross-volume gate, always rejects them together). Outcome records
+* are reporting inputs, not membership, and pass through untouched.
+*/
+function excludeCollectedPackages(collected, rejectedSpecifiers, rootDir) {
+	if (rejectedSpecifiers.size === 0) return collected;
+	const rejectedDirs = Object.entries(collected.dirOwnerSets).filter(([, specs]) => specs.every((s) => rejectedSpecifiers.has(s))).map(([dir]) => dir);
+	const underRejectedDir = (absPath) => rejectedDirs.some((dir) => isPathWithinRoot(dir, absPath));
+	const targetRejected = (specifier, absTarget) => rejectedSpecifiers.has(specifier) || underRejectedDir(absTarget);
+	const packageMap = {};
+	for (const [specifier, relTarget] of Object.entries(collected.packageMap)) {
+		if (targetRejected(specifier, (0, path.resolve)(rootDir, relTarget))) continue;
+		packageMap[specifier] = relTarget;
+	}
+	const sourceEntries = /* @__PURE__ */ new Map();
+	for (const [specifier, absEntry] of collected.sourceEntries) {
+		if (targetRejected(specifier, absEntry)) continue;
+		sourceEntries.set(specifier, absEntry);
+	}
+	const keyframesScanEntries = /* @__PURE__ */ new Map();
+	for (const [specifier, absEntry] of collected.keyframesScanEntries) {
+		if (targetRejected(specifier, absEntry)) continue;
+		keyframesScanEntries.set(specifier, absEntry);
+	}
+	const dirOwnerSets = {};
+	for (const [dir, specs] of Object.entries(collected.dirOwnerSets)) {
+		const kept = specs.filter((s) => !rejectedSpecifiers.has(s));
+		if (kept.length === 0) continue;
+		dirOwnerSets[dir] = kept;
+	}
+	const dirExtensions = {};
+	for (const [dir, exts] of Object.entries(collected.dirExtensions)) {
+		if (rejectedDirs.includes(dir)) continue;
+		dirExtensions[dir] = exts;
+	}
+	const fileOwners = {};
+	for (const [relPath, owner] of Object.entries(collected.fileOwners)) {
+		if (rejectedSpecifiers.has(owner)) continue;
+		fileOwners[relPath] = owner;
+	}
+	return {
+		entries: collected.entries.filter((entry) => !rejectedSpecifiers.has(collected.fileOwners[entry.path])),
+		packageMap,
+		sourceEntries,
+		keyframesScanEntries,
+		packageDirs: collected.packageDirs.filter((dir) => !rejectedDirs.includes(dir)),
+		dirOwnerSets,
+		dirExtensions,
+		fileOwners,
+		outcomes: collected.outcomes
+	};
+}
 /**
 * Extract external DS package names from inheritance declarations in the
 * system file.
@@ -941,7 +1153,7 @@ function buildSourceTokenIndex(opts) {
 		if ((0, fs.existsSync)((0, path.join)(packageRoot, "package.json"))) addOwnerDir(packageRoot, specifier);
 	}
 	for (const [modulePath, exports] of Object.entries(manifests)) {
-		const owner = realDirOwners.find(({ dir }) => modulePath === dir || modulePath.startsWith(dir + path.sep));
+		const owner = realDirOwners.find(({ dir }) => isPathWithinRoot(dir, modulePath));
 		if (!owner) continue;
 		let tokens = index.get(owner.specifier);
 		if (!tokens) {
@@ -1082,16 +1294,42 @@ function postProcessCss(css, opts) {
 /** Stable code for selector forms with no substitutable subject.
 *  Mirrors the Rust constant in `extract-v2/src/eval.rs`. */
 const SELECTOR_UNSUPPORTED_SUBJECT = "animus.selector.unsupported-subject";
+/** Unresolved-parent chain-drop message (mirrors the Rust diagnostic in
+*  `extract-v2` — the ONE encoding of this message shape; consumers match
+*  through the helpers below, never their own regex copies). */
+const UNRESOLVED_PARENT_RE = /chain dropped: could not resolve parent component '([^']+)'/;
+/** True when the diagnostic reports a chain dropped for an unresolved
+*  parent component. */
+function isUnresolvedParentDrop(diagnostic) {
+	return typeof diagnostic?.message === "string" && UNRESOLVED_PARENT_RE.test(diagnostic.message);
+}
+/** The parent binding named by an unresolved-parent drop, or null when the
+*  diagnostic is not one. */
+function unresolvedParentName(diagnostic) {
+	if (typeof diagnostic?.message !== "string") return null;
+	return UNRESOLVED_PARENT_RE.exec(diagnostic.message)?.[1] ?? null;
+}
 /** True when the selector string carries at least one substitutable `&`
 *  subject outside quoted text (mirrors the Rust `selector_subject` walk —
 *  ancestor, leading, and repeated subjects all count; a `&` inside a
 *  quoted attribute value does not). */
 function hasSelectorSubject(value) {
 	let quote = null;
-	for (const c of value) if (quote !== null) {
-		if (c === quote) quote = null;
-	} else if (c === "\"" || c === "'") quote = c;
-	else if (c === "&") return true;
+	let escaped = false;
+	for (const c of value) {
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (c === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote !== null) {
+			if (c === quote) quote = null;
+		} else if (c === "\"" || c === "'") quote = c;
+		else if (c === "&") return true;
+	}
 	return false;
 }
 /**
@@ -1221,6 +1459,7 @@ function buildAnalysisInputs(opts) {
 		keyframesJson: opts.system.keyframesJson,
 		staticCssJson: opts.staticCssJson ?? null,
 		conditionAliasesJson: opts.system.conditionAliasesJson ?? null,
+		transformSourcesJson: opts.system.transformSourcesJson ?? null,
 		externalDirsJson: opts.externalDirs?.length && hasSourceThemeManifests(opts.system) ? JSON.stringify(opts.externalDirs) : null
 	};
 }
@@ -1362,6 +1601,7 @@ function loadSystemConfig(engineApi, opts) {
 		contextualVarsJson,
 		selectorAliasesJson: config.selectorAliases || null,
 		conditionAliasesJson: config.conditionAliases || null,
+		transformSourcesJson: config.transformSources || null,
 		globalStyleBlocksJson: config.globalStyleBlocks || null,
 		keyframesJson: config.keyframesBlocks || null,
 		dependencies: config.dependencies ?? [],
@@ -1509,17 +1749,17 @@ function stripJsonc(text) {
 	}
 	return out.replace(/,(\s*[}\]])/g, "$1");
 }
-function readConfig(path$1) {
+function readConfig(path$2) {
 	let raw;
 	try {
-		raw = (0, fs.readFileSync)(path$1, "utf-8");
+		raw = (0, fs.readFileSync)(path$2, "utf-8");
 	} catch {
 		return null;
 	}
 	try {
 		const json = JSON.parse(stripJsonc(raw));
 		return {
-			dir: (0, path.dirname)(path$1),
+			dir: (0, path.dirname)(path$2),
 			compilerOptions: json.compilerOptions ?? {},
 			extends: json.extends
 		};
@@ -1607,6 +1847,22 @@ function readTsconfigAliasPairs(rootDir) {
 	return pairs;
 }
 //#endregion
+//#region pipeline/error-diagnostics.ts
+/**
+* Throw when the diagnostics carry any `kind: "error"` entry — one
+* aggregated `Error` naming EVERY offender (component, file, message — one
+* line per entry, each prefixed `[animus]`). Warning-only diagnostics
+* (`bail`/`skip`/`warn`, any severity) never trip this gate; their routing
+* stays with `surfaceManifestDiagnostics`. Callers accept the manifest only
+* past this point, so no stylesheet from a failing analysis is published.
+*/
+function assertNoErrorDiagnostics(diagnostics) {
+	const errors = (diagnostics ?? []).filter((diagnostic) => diagnostic.kind === "error");
+	if (errors.length === 0) return;
+	const lines = [...new Set(errors.map((diagnostic) => `[animus] ${diagnostic.component || "<unknown component>"} (${diagnostic.file || "<unknown file>"}): ${diagnostic.message || "<no message>"}`))];
+	throw new Error(lines.join("\n"));
+}
+//#endregion
 //#region pipeline/mdx-preprocessor.ts
 /**
 * MDX source preprocessor for the extraction pipeline.
@@ -1664,6 +1920,79 @@ async function preprocessMdx(source, filename) {
 	}
 }
 //#endregion
+//#region pipeline/replacement-plans.ts
+const snapshotByManifest = /* @__PURE__ */ new WeakMap();
+function snapshotFilePlans(manifest) {
+	const memoKey = manifest !== null && typeof manifest === "object" ? manifest : null;
+	if (memoKey) {
+		const cached = snapshotByManifest.get(memoKey);
+		if (cached) return cached;
+	}
+	const entriesByFile = /* @__PURE__ */ new Map();
+	for (const [id, desc] of Object.entries(manifest?.components ?? {})) {
+		const file = desc.file;
+		if (!file) continue;
+		const list = entriesByFile.get(file) ?? [];
+		list.push([id, desc.replacement ?? ""]);
+		entriesByFile.set(file, list);
+	}
+	const snapshot = /* @__PURE__ */ new Map();
+	for (const [file, entries] of entriesByFile) {
+		entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+		snapshot.set(file, JSON.stringify(entries));
+	}
+	if (memoKey) snapshotByManifest.set(memoKey, snapshot);
+	return snapshot;
+}
+/**
+* Rel paths whose plan changed between two snapshots: absent→present,
+* present→absent, and any change to membership or replacement content.
+* `exclude` drops one path (the changed file itself on the edit path — its
+* own modules are already in the update set).
+*/
+function diffFilePlans(prev, next, opts) {
+	const changed = /* @__PURE__ */ new Set();
+	for (const [file, plan] of next) if (prev.get(file) !== plan) changed.add(file);
+	for (const file of prev.keys()) if (!next.has(file)) changed.add(file);
+	if (opts?.exclude) changed.delete(opts.exclude);
+	return [...changed].sort();
+}
+/** Domain prefix keeping the epoch hash disjoint from every other
+*  contentHash use in the pipeline (design D5). */
+const REPLACEMENT_PLANS_DOMAIN = "animus-replacement-plans-v1\0";
+/** Section marker for the served-dependency witness. Leads with NUL: every
+*  plan entry ends `…\0` and neither file paths nor plan JSON contain NUL,
+*  so `\0\0` is unreachable from entry serialization alone — a snapshot can
+*  never forge the witness section. */
+const SERVED_DEPENDENCY_DOMAIN = "\0animus-served-dependency-v1\0";
+/**
+* Canonical replacement epoch: contentHash over the domain-prefixed, sorted
+* canonical serialization of a file-plan snapshot — each entry contributes
+* `file + '\0' + plan + '\0'` (unambiguous: neither file paths nor the
+* JSON plan strings contain NUL). Byte-identical plans → identical epoch;
+* any membership/replacement/absent↔present change moves it.
+*
+* `servedDependencyWitness` extends the epoch to content the plans cannot
+* see but restored modules depend on: transformed modules import the
+* session's served system-props artifact, so a consumer passes that
+* artifact's content here and an offline change to it moves the epoch —
+* invalidating persistent-cache snapshots that reference the old epoch
+* artifact. Absence and empty-string are distinct values.
+*
+* This is THE epoch definition — integrations consume this hash (or the
+* snapshot diff) and never define their own. Epoch values compare only for
+* equality (a moved value invalidates), so the serialization is free to
+* evolve with a domain bump: sessions running different serializations
+* simply disagree once and rebuild.
+*/
+function hashReplacementPlans(snapshot, servedDependencyWitness) {
+	const entries = [...snapshot.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	let serialized = REPLACEMENT_PLANS_DOMAIN;
+	for (const [file, plan] of entries) serialized += file + "\0" + plan + "\0";
+	if (servedDependencyWitness !== void 0) serialized += SERVED_DEPENDENCY_DOMAIN + servedDependencyWitness;
+	return contentHash(serialized);
+}
+//#endregion
 //#region pipeline/utils.ts
 /** Convert camelCase CSS property names to kebab-case. */
 function camelToKebab(str) {
@@ -1723,6 +2052,7 @@ exports.RETIRED_ENGINE_MESSAGE = RETIRED_ENGINE_MESSAGE;
 exports.applyPrefix = applyPrefix;
 exports.applyUnitFallback = applyUnitFallback;
 exports.assembleStylesheet = assembleStylesheet;
+exports.assertNoErrorDiagnostics = assertNoErrorDiagnostics;
 exports.assertNoRetiredEngineSelection = assertNoRetiredEngineSelection;
 exports.buildAnalysisInputs = buildAnalysisInputs;
 exports.buildAnalyzeProjectArgs = buildAnalyzeProjectArgs;
@@ -1733,27 +2063,40 @@ exports.camelToKebab = camelToKebab;
 exports.clearEngineCache = clearEngineCache;
 exports.collectExternalPackageSources = collectExternalPackageSources;
 exports.contentHash = contentHash;
+exports.createSourceIdentity = createSourceIdentity;
 exports.createV2EngineApi = createV2EngineApi;
+exports.diffFilePlans = diffFilePlans;
 exports.discoverFiles = discoverFiles;
 exports.enforceExternalTokenContracts = enforceExternalTokenContracts;
+exports.excludeCollectedPackages = excludeCollectedPackages;
 exports.extractSystemFilePackages = extractSystemFilePackages;
 exports.findAssetSpecifiers = findAssetSpecifiers;
 exports.findPackageRoot = findPackageRoot;
+exports.firstOwners = firstOwners;
 exports.formatRustTimingWaterfall = formatRustTimingWaterfall;
+exports.hashReplacementPlans = hashReplacementPlans;
+exports.isExcludedPackageRelativePath = isExcludedPackageRelativePath;
+exports.isPathWithinRoot = isPathWithinRoot;
+exports.isUnresolvedParentDrop = isUnresolvedParentDrop;
 exports.loadSystemConfig = loadSystemConfig;
 exports.mergeExternalKeyframes = mergeExternalKeyframes;
 exports.postProcessCss = postProcessCss;
 exports.preprocessMdx = preprocessMdx;
 exports.readTsconfigAliasPairs = readTsconfigAliasPairs;
+exports.resolveAbsolutePathSpecifier = resolveAbsolutePathSpecifier;
 exports.resolveAssetFile = resolveAssetFile;
 exports.resolveLightningTargets = resolveLightningTargets;
 exports.resolveThroughPathAliases = resolveThroughPathAliases;
 exports.runProjectAnalysis = runProjectAnalysis;
 exports.serializeStaticCss = serializeStaticCss;
+exports.sharesVolumeRoot = sharesVolumeRoot;
+exports.snapshotFilePlans = snapshotFilePlans;
 exports.staleDistIncludesMessage = staleDistIncludesMessage;
 exports.stripLeadingLayerDeclaration = stripLeadingLayerDeclaration;
 exports.substituteAssetPlaceholders = substituteAssetPlaceholders;
 exports.surfaceManifestDiagnostics = surfaceManifestDiagnostics;
 exports.toWatchKeys = toWatchKeys;
 exports.unresolvableIncludesMessage = unresolvableIncludesMessage;
+exports.unresolvedParentName = unresolvedParentName;
 exports.validateLayerOrder = validateLayerOrder;
+exports.walkPackageSources = walkPackageSources;

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export { KEYFRAMES_EXPORT_COLLISION, KEYFRAMES_EXTERNAL_ENTRY_FAILED, mergeExter
 export type { ExternalKeyframesMerge } from './external-keyframes';
 export { discoverFiles } from './discover-files';
 export type { CollectedExternalPackages, ExternalPackageOutcome, } from './discover-packages';
-export { collectExternalPackageSources, extractSystemFilePackages, findPackageRoot, staleDistIncludesMessage, unresolvableIncludesMessage, } from './discover-packages';
+export { collectExternalPackageSources, excludeCollectedPackages, extractSystemFilePackages, findPackageRoot, firstOwners, isExcludedPackageRelativePath, resolveAbsolutePathSpecifier, staleDistIncludesMessage, unresolvableIncludesMessage, walkPackageSources, } from './discover-packages';
+export type { ResolvedSourceId, SourceIdentity } from './source-identity';
+export { createSourceIdentity, isPathWithinRoot, sharesVolumeRoot, } from './source-identity';
 export { findAssetSpecifiers, substituteAssetPlaceholders, } from './asset-placeholders';
 export { resolveAssetFile, resolveThroughPathAliases } from './resolve-asset';
 export { enforceExternalTokenContracts } from './correlate-external-tokens';
@@ -28,11 +30,15 @@ export { formatRustTimingWaterfall } from './timing-waterfall';
 export { readTsconfigAliasPairs } from './tsconfig-paths';
 export type { DynamicPropConfigEntry, DynamicPropMeta, } from './dynamic-prop-config';
 export { buildDynamicPropConfig } from './dynamic-prop-config';
+export type { CssDiagnosticLike } from './error-diagnostics';
+export { assertNoErrorDiagnostics } from './error-diagnostics';
 export type { ManifestDiagnostic } from './manifest-diagnostics';
-export { surfaceManifestDiagnostics } from './manifest-diagnostics';
+export { isUnresolvedParentDrop, surfaceManifestDiagnostics, unresolvedParentName, } from './manifest-diagnostics';
 export type { DefaultExtension, PreprocessMdxResult } from './mdx-preprocessor';
 export { DEFAULT_EXTENSIONS, preprocessMdx } from './mdx-preprocessor';
 export { applyPrefix } from './prefix';
+export type { FilePlanSnapshot } from './replacement-plans';
+export { diffFilePlans, hashReplacementPlans, snapshotFilePlans, } from './replacement-plans';
 export { applyUnitFallback } from './unit-fallback';
 export { camelToKebab } from './utils';
 export { toWatchKeys } from './watch-keys';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../pipeline/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../pipeline/index.ts"],"names":[],"mappings":"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"}