refactor(project): Detect file replacement via inode in cache check

Extend matchResourceMetadataStrict to compare the resource inode against
the cached inode. When both sides expose an inode and they disagree, the
file has been replaced (atomic rename, cp, tar extraction, ...) — the
mtime+size short-circuit is suppressed and the comparison falls through
to the integrity check.

Inode is now always populated by createResourceIndex; the optional
includeInode flag is removed. When either side has no inode (virtual
resources, caches written before this change), the inode check is
skipped and behavior matches the previous mtime+size path.

Falling through to integrity rather than returning false avoids
unnecessary task re-execution when the replacement preserves content
(e.g. an idempotent rsync). When the replacement also alters content,
the integrity check correctly classifies the resource as changed,
closing a stale-cache blind spot that mtime+size alone could not detect.

Author: RandomByte

packages/project/lib/build/cache/utils.js

@@ -11,6 +11,7 @@ const perfCounters = {
 	calls: 0,
 	shortCircuitTrue: 0,
 	sizeMismatch: 0,
+	inodeMismatch: 0,
 	integrityFallback: 0,
 };
 export {perfCounters as matchResourceMetadataStrictCounters};
@@ -82,14 +83,7 @@ export async function matchResourceMetadataStrict(resource, cachedMetadata, inde
 	}
 	if (PERF_TRACKING) perfCounters.calls++;
 
-	// Check 1: Inode mismatch would indicate file replacement (comparison only if inodes are provided)
-	// const currentInode = resource.getInode();
-	// if (cachedMetadata.inode !== undefined && currentInode !== undefined &&
-	// 	currentInode !== cachedMetadata.inode) {
-	// 	return false;
-	// }
-
-	// Check 2: Size mismatch indicates definite content change. Required before any
+	// Size mismatch indicates a definite content change. Required before any
 	// "unchanged" decision because mtime preservation (cp -p, tar -x, rsync -t,
 	// atomic rename) does not imply content unchanged.
 	const currentSize = await resource.getSize();
@@ -98,21 +92,30 @@ export async function matchResourceMetadataStrict(resource, cachedMetadata, inde
 		return false;
 	}
 
-	// Check 3: Modification time + size both match → unchanged, unless we're in
-	// the racy-git window (mtime === indexTimestamp), where content may have
-	// changed during indexing without mtime moving.
+	// Inode mismatch indicates the file was replaced (atomic rename, cp, tar
+	// extraction, ...). Content may still be identical, so fall through to the
+	// integrity check rather than returning false. Inode is optional on both
+	// sides (e.g. virtual resources, older caches without inode); skip the
+	// check when either is undefined.
+	const currentInode = resource.getInode();
+	const inodeMismatch =
+		cachedMetadata.inode !== undefined && currentInode !== undefined &&
+		currentInode !== cachedMetadata.inode;
+	if (inodeMismatch && PERF_TRACKING) perfCounters.inodeMismatch++;
+
+	// mtime + size both match and the file has not been replaced → unchanged,
+	// unless we are in the racy-git window (mtime === indexTimestamp), where
+	// content may have changed during indexing without mtime moving.
 	const currentLastModified = resource.getLastModified();
-	if (currentLastModified === cachedMetadata.lastModified) {
+	if (!inodeMismatch && currentLastModified === cachedMetadata.lastModified) {
 		if (indexTimestamp && currentLastModified !== indexTimestamp) {
 			if (PERF_TRACKING) perfCounters.shortCircuitTrue++;
 			return true;
-		} // else: Edge case. File modified exactly at index time
-		// Race condition possible - content may have changed during indexing
-		// Fall through to integrity check
+		}
+		// Race condition possible — fall through to integrity check
 	}
 
-	// Check 4: Compare integrity (expensive)
-	// lastModified has changed, but the content might be the same. E.g. in case of a metadata-only update
+	// mtime differs, file was replaced, or racy window — verify content.
 	if (PERF_TRACKING) perfCounters.integrityFallback++;
 	const currentIntegrity = await resource.getIntegrity();
 	return currentIntegrity === cachedMetadata.integrity;
@@ -123,27 +126,23 @@ export async function matchResourceMetadataStrict(resource, cachedMetadata, inde
  * Creates an index of resource metadata from an array of resources
  *
  * Processes all resources in parallel, extracting their metadata including
- * path, integrity, lastModified timestamp, and size. Optionally includes inode information.
+ * path, integrity, lastModified timestamp, size and inode (when available).
  *
  * @public
  * @param {Array<@ui5/fs/Resource>} resources Array of resources to index
- * @param {boolean} [includeInode=false] Whether to include inode information in the metadata
  * @returns {Promise<Array<@ui5/project/build/cache/index/HashTree~ResourceMetadata>>}
  *   Array of resource metadata objects
  */
-export async function createResourceIndex(resources, includeInode = false) {
+export async function createResourceIndex(resources) {
 	return await Promise.all(resources.map(async (resource) => {
-		const resourceMetadata = {
+		return {
 			path: resource.getOriginalPath(),
 			integrity: await resource.getIntegrity(),
 			lastModified: resource.getLastModified(),
 			size: await resource.getSize(),
+			inode: resource.getInode(),
 			tags: resource.getTags(),
 		};
-		if (includeInode) {
-			resourceMetadata.inode = resource.getInode();
-		}
-		return resourceMetadata;
 	}));
 }
 

packages/project/test/lib/build/cache/utils.js

@@ -158,12 +158,44 @@ test("matchResourceMetadataStrict: no indexTimestamp - falls through on matching
 	t.true(await matchResourceMetadataStrict(resource, metadata));
 });
 
+// An atomic rename with preserved mtime (cp -p, mv tmp, ...) yields a new inode
+// without changing size or lastModified. The size+mtime cheap path would
+// otherwise short-circuit and serve a stale cache hit; force the integrity
+// check whenever the inode disagrees.
+test("matchResourceMetadataStrict: inode mismatch forces integrity check (content unchanged)",
+	async (t) => {
+		const resource = createMockResource({lastModified: 1000, size: 100, inode: 2, integrity: "hash-a"});
+		const metadata = {lastModified: 1000, size: 100, inode: 1, integrity: "hash-a"};
+		t.true(await matchResourceMetadataStrict(resource, metadata, 2000));
+	});
+
+test("matchResourceMetadataStrict: inode mismatch detects same-size content change",
+	async (t) => {
+		const resource = createMockResource({lastModified: 1000, size: 100, inode: 2, integrity: "hash-different"});
+		const metadata = {lastModified: 1000, size: 100, inode: 1, integrity: "hash-a"};
+		t.false(await matchResourceMetadataStrict(resource, metadata, 2000));
+	});
+
+test("matchResourceMetadataStrict: skips inode check when cached metadata has no inode",
+	async (t) => {
+		const resource = createMockResource({lastModified: 1000, size: 100, inode: 7, integrity: "hash-a"});
+		const metadata = {lastModified: 1000, size: 100, integrity: "hash-a"};
+		t.true(await matchResourceMetadataStrict(resource, metadata, 2000));
+	});
+
+test("matchResourceMetadataStrict: skips inode check when resource has no inode",
+	async (t) => {
+		const resource = createMockResource({lastModified: 1000, size: 100, inode: undefined, integrity: "hash-a"});
+		const metadata = {lastModified: 1000, size: 100, inode: 5, integrity: "hash-a"};
+		t.true(await matchResourceMetadataStrict(resource, metadata, 2000));
+	});
+
 // === createResourceIndex ===
 
 test("createResourceIndex: indexes resources correctly", async (t) => {
 	const resources = [
-		createMockResource({path: "/a.js", integrity: "hash-a", lastModified: 1000, size: 50}),
-		createMockResource({path: "/b.js", integrity: "hash-b", lastModified: 2000, size: 60}),
+		createMockResource({path: "/a.js", integrity: "hash-a", lastModified: 1000, size: 50, inode: 7}),
+		createMockResource({path: "/b.js", integrity: "hash-b", lastModified: 2000, size: 60, inode: 8}),
 	];
 
 	const result = await createResourceIndex(resources);
@@ -173,17 +205,17 @@ test("createResourceIndex: indexes resources correctly", async (t) => {
 	t.is(result[0].integrity, "hash-a");
 	t.is(result[0].lastModified, 1000);
 	t.is(result[0].size, 50);
-	t.is(result[0].inode, undefined);
+	t.is(result[0].inode, 7);
 });
 
-test("createResourceIndex: includes inode when requested", async (t) => {
+test("createResourceIndex: leaves inode undefined when resource has none", async (t) => {
 	const resources = [
-		createMockResource({path: "/a.js", inode: 42}),
+		createMockResource({path: "/a.js", inode: undefined}),
 	];
 
-	const result = await createResourceIndex(resources, true);
+	const result = await createResourceIndex(resources);
 
-	t.is(result[0].inode, 42);
+	t.is(result[0].inode, undefined);
 });
 
 test("createResourceIndex: includes tags", async (t) => {