refactor(project): Rename matchResourceMetadataStrict to isResourceUnchanged

Drop the unused matchResourceMetadata variant (no longer used) and
rename matchResourceMetadataStrict to isResourceUnchanged.

Author: RandomByte

.claude/skills/incremental-build/architecture.md

@@ -218,14 +218,15 @@ Key operations:
 - `removeResources(paths)`: Remove resources, recompute affected hashes
 - `_computeHash(node)`: Recursive hash computation
 
-The `matchResourceMetadataStrict` utility (`utils.js`) determines if a resource is "unchanged" using a tiered comparison (cheapest first):
+The `isResourceUnchanged` utility (`utils.js`) determines if a resource is "unchanged" using a tiered comparison (cheapest first):
 
-1. If `lastModified` matches cached value AND differs from `indexTimestamp`: unchanged (fast path)
-2. If `lastModified` equals `indexTimestamp`: racy-git edge case -- file may have changed during indexing, fall through to integrity check
-3. Compare `size` -- if different, changed
-4. Compare `integrity` hash -- expensive, last resort
+1. Compare `size` -- if different, changed (definite signal; mtime preservation via `cp -p`/`tar -x`/atomic rename does not imply unchanged content)
+2. Compare `inode` -- if different, the file was replaced; fall through to integrity check rather than rejecting outright (content may still be identical)
+3. If `lastModified` matches cached value AND differs from `indexTimestamp` AND inode matches: unchanged (fast path)
+4. If `lastModified` equals `indexTimestamp`: racy-git edge case -- file may have changed during indexing, fall through to integrity check
+5. Compare `integrity` hash -- expensive, last resort
 
-Note: inode comparison is defined but currently commented out. `inode` is still stored in TreeNode for future use.
+`inode` is optional on both sides (virtual resources, older caches without inode); the inode check is skipped when either side is undefined.
 
 ### SharedHashTree and TreeRegistry
 

.claude/skills/incremental-build/performance-investigation.md

@@ -18,7 +18,7 @@ UI5_CLI_NO_LOCAL=X UI5_BUILD_NO_WRITE_DEST=X UI5_CACHE_PERF=1 ui5 build --log-le
 Flags:
 - `UI5_CLI_NO_LOCAL=X` — Use the globally linked CLI (i.e., the development version)
 - `UI5_BUILD_NO_WRITE_DEST=X` — Skip writing output to `./dist` (isolates cache/build overhead from disk I/O)
-- `UI5_CACHE_PERF=1` — Enable low-level `matchResourceMetadataStrict` counters (see below)
+- `UI5_CACHE_PERF=1` — Enable low-level `isResourceUnchanged` counters (see below)
 - `--log-level perf` — Show all perf-level log statements
 
 ### Three build scenarios
@@ -150,7 +150,7 @@ Per-task index update:
 
 ```
 perf updateIndices for task 'replaceVersion' of project 'sap.m' resource fetch completed in 3.89 ms: 0 cache hits, 783 cache misses
-perf TreeRegistry.flush completed: phase1(removals)=0.00 ms, phase2(upserts)=7.13 ms, phase3(rehash)=9.56 ms | matchMetadataStrictCalls=783, matchMetadataUnchanged=782, modifiedNodesSkips=0
+perf TreeRegistry.flush completed: phase1(removals)=0.00 ms, phase2(upserts)=7.13 ms, phase3(rehash)=9.56 ms | isUnchangedCalls=783, isUnchangedHits=782, modifiedNodesSkips=0
 perf #flushTreeChanges for task 'replaceVersion' completed in 16.79 ms across 1 registries
 perf Updated project indices for task replaceVersion in project sap.m in 21.71 ms
 ```
@@ -160,7 +160,7 @@ Key metrics:
 - **phase1(removals)**: Time removing deleted resources from the Merkle tree.
 - **phase2(upserts)**: Time inserting/updating resources in the tree.
 - **phase3(rehash)**: Time propagating hash changes up from modified leaves to root. High rehash with few changed resources indicates deep tree structure.
-- **matchMetadataStrictCalls / matchMetadataUnchanged**: How many resources were compared, and how many were unchanged (short-circuited by lastModified check). If `calls >> unchanged`, many resources needed content hashing.
+- **isUnchangedCalls / isUnchangedHits**: How many resources were compared, and how many were unchanged (short-circuited by lastModified check). If `calls >> hits`, many resources needed content hashing.
 
 Then task execution or skip:
 
@@ -217,14 +217,15 @@ The four sub-operations (stages, requests, sourceIndex, result) run in parallel
 
 ## UI5_CACHE_PERF Counters
 
-Setting `UI5_CACHE_PERF=1` enables low-level counters in `utils.js` for `matchResourceMetadataStrict`:
+Setting `UI5_CACHE_PERF=1` enables low-level counters in `utils.js` for `isResourceUnchanged`:
 
 - `calls` — Total invocations
 - `shortCircuitTrue` — Fast-path returns (lastModified matches cached and ≠ indexTimestamp → file unchanged, no I/O needed)
 - `sizeMismatch` — Changes detected via size check (cheap)
+- `inodeMismatch` — File replacement detected via inode change (forces integrity check)
 - `integrityFallback` — Full SHA256 content hash required (expensive)
 
-These counters appear in the `TreeRegistry.flush` log as `matchMetadataStrictCalls` and `matchMetadataUnchanged`.
+These counters are tallied per-flush in `TreeRegistry.flush` as `isUnchangedCalls` and `isUnchangedHits`.
 
 A high `integrityFallback` count means many files have the same size but different content — this is expensive and may indicate that the `lastModified` short-circuit is not working (e.g., due to timestamp resolution issues).
 
@@ -303,13 +304,13 @@ These four operations run in parallel. They share I/O bandwidth, so their indivi
 
 **Note:** In CLI mode, cache writes are deferred to the background. The `Wrote build cache` log line appears after `Build succeeded`. The sub-timings tend to be lower (~250-300ms vs ~1400ms) because background writes don't compete with the build for I/O bandwidth.
 
-### 5. matchMetadataUnchanged vs modifiedNodesSkips
+### 5. isUnchangedHits vs modifiedNodesSkips
 
 In `TreeRegistry.flush` logs:
-- `matchMetadataUnchanged` — Resources whose metadata (lastModified, size, integrity) matched the cached version. No tree modification needed.
+- `isUnchangedHits` — Resources whose metadata (lastModified, size, integrity) matched the cached version. No tree modification needed.
 - `modifiedNodesSkips` — Tree nodes already marked as modified by a previous flush in the same build. Skipped to avoid redundant work.
 
-When `matchMetadataUnchanged` equals `matchMetadataStrictCalls`, ALL resources were unchanged — the flush was pure overhead.
+When `isUnchangedHits` equals `isUnchangedCalls`, ALL resources were unchanged — the flush was pure overhead.
 
 ### 6. Dependency index "changed=true" doesn't always mean task re-execution
 
@@ -367,7 +368,7 @@ When diagnosing slow `writeStageResources`, check the `CAS skipped` vs `CAS writ
 4. **Drill down.** For the dominant phase:
    - Add more granular `log.perf()` statements if needed
    - Use `console.time()`/`console.timeEnd()` for quick local profiling
-   - Check `matchMetadataStrictCalls` vs `matchMetadataUnchanged` to understand if resources are being unnecessarily re-hashed
+   - Check `isUnchangedCalls` vs `isUnchangedHits` to understand if resources are being unnecessarily re-hashed
 
 5. **Validate optimization ideas.** When proposing optimizations:
    - Consider warm vs stale vs cold cache impact separately

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

@@ -7,7 +7,7 @@ import os from "node:os";
 import BuildTaskCache from "./BuildTaskCache.js";
 import StageCache from "./StageCache.js";
 import ResourceIndex from "./index/ResourceIndex.js";
-import {matchResourceMetadataStrict} from "./utils.js";
+import {isResourceUnchanged} from "./utils.js";
 const log = getLogger("build:cache:ProjectBuildCache");
 
 export class SourceChangedDuringBuildError extends Error {
@@ -991,7 +991,7 @@ export default class ProjectBuildCache {
 	 * Re-reads all source files from disk and compares them against the source index
 	 * to detect whether any source files were modified, added, or deleted during the build.
 	 *
-	 * Uses metadata-only comparison via matchResourceMetadataStrict (skipping tags,
+	 * Uses metadata-only comparison via isResourceUnchanged (skipping tags,
 	 * since tags are build artifacts that always differ from fresh disk reads).
 	 *
 	 * @returns {Promise<boolean>} True if source changes were detected during the build
@@ -1028,7 +1028,7 @@ export default class ProjectBuildCache {
 				size: node.size,
 				inode: node.inode,
 			};
-			const isUnchanged = await matchResourceMetadataStrict(
+			const isUnchanged = await isResourceUnchanged(
 				resource, cachedMetadata, tree.getIndexTimestamp()
 			);
 			if (!isUnchanged) {

packages/project/lib/build/cache/index/HashTree.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import path from "node:path/posix";
 import TreeNode from "./TreeNode.js";
-import {matchResourceMetadataStrict} from "../utils.js";
+import {isResourceUnchanged} from "../utils.js";
 
 /**
  * @typedef {object} @ui5/project/build/cache/index/HashTree~ResourceMetadata
@@ -388,7 +388,7 @@ export default class HashTree {
 		const affectedPaths = new Set();
 
 		// Phase 1: Categorize each resource. New resources need integrity+size resolved.
-		// Existing resources are routed through matchResourceMetadataStrict (Phase 2),
+		// Existing resources are routed through isResourceUnchanged (Phase 2),
 		// which handles the mtime/size short-circuit with the racy-git protection.
 		const needsIO = [];
 
@@ -419,7 +419,7 @@ export default class HashTree {
 					};
 				}
 
-				// Existing resource with potential change — use matchResourceMetadataStrict
+				// Existing resource with potential change — use isResourceUnchanged
 				// for the remaining checks (size comparison, integrity comparison)
 				const currentMetadata = {
 					integrity: existingNode.integrity,
@@ -429,13 +429,13 @@ export default class HashTree {
 				};
 
 				const isUnchanged =
-					await matchResourceMetadataStrict(resource, currentMetadata, this.#indexTimestamp);
+					await isResourceUnchanged(resource, currentMetadata, this.#indexTimestamp);
 
 				if (isUnchanged) {
 					return {resourcePath, existingNode, isUnchanged: true, tags: resource.getTags()};
 				}
 
-				// Changed — integrity/size are cached in the Resource from matchResourceMetadataStrict
+				// Changed — integrity/size are cached in the Resource from isResourceUnchanged
 				const [integrity, size] = await Promise.all([
 					resource.getIntegrity(),
 					resource.getSize()

packages/project/lib/build/cache/index/TreeRegistry.js

@@ -1,7 +1,7 @@
 import path from "node:path/posix";
 import TreeNode from "./TreeNode.js";
 import {tagsEqual} from "./HashTree.js";
-import {matchResourceMetadataStrict} from "../utils.js";
+import {isResourceUnchanged} from "../utils.js";
 import {getLogger} from "@ui5/logger";
 const log = getLogger("build:cache:index:TreeRegistry");
 
@@ -274,8 +274,8 @@ export default class TreeRegistry {
 		const upsertsByDir = new Map(); // parentPath -> [{resourceName, resource, fullPath, sourceTree}]
 
 		const phase2Start = perfEnabled ? performance.now() : 0;
-		let matchMetadataStrictCalls = 0;
-		let matchMetadataUnchanged = 0;
+		let isUnchangedCalls = 0;
+		let isUnchangedHits = 0;
 		let modifiedNodesSkips = 0;
 
 		for (const [resourcePath, {resource, sourceTree}] of this.pendingUpserts) {
@@ -290,7 +290,7 @@ export default class TreeRegistry {
 		}
 
 		// Pre-resolve I/O for resources that don't exist in any tree (genuinely new).
-		// For existing resources, matchResourceMetadataStrict's lastModified short-circuit
+		// For existing resources, isResourceUnchanged's lastModified short-circuit
 		// avoids I/O in the common case, so those are handled serially in the loop below.
 		const resolvedNewMetadata = new Map();
 		const newResourcePaths = [];
@@ -413,15 +413,15 @@ export default class TreeRegistry {
 							}
 						} else {
 							// First time seeing this node — do full comparison
-							matchMetadataStrictCalls++;
+							isUnchangedCalls++;
 							const currentMetadata = {
 								integrity: resourceNode.integrity,
 								lastModified: resourceNode.lastModified,
 								size: resourceNode.size,
 								inode: resourceNode.inode
 							};
 
-							const isUnchanged = await matchResourceMetadataStrict(
+							const isUnchanged = await isResourceUnchanged(
 								upsert.resource,
 								currentMetadata,
 								tree.getIndexTimestamp()
@@ -444,7 +444,7 @@ export default class TreeRegistry {
 									updatedResources.push(upsert.fullPath);
 								}
 							} else {
-								matchMetadataUnchanged++;
+								isUnchangedHits++;
 								unchangedNodes.add(resourceNode);
 								const currentTags =
 									upsert.resource.getTags?.() ?? upsert.resource.tags ?? null;
@@ -528,8 +528,8 @@ export default class TreeRegistry {
 				`phase1(removals)=${(phase2Start - phase1Start).toFixed(2)} ms, ` +
 				`phase2(upserts)=${(phase3Start - phase2Start).toFixed(2)} ms, ` +
 				`phase3(rehash)=${(now - phase3Start).toFixed(2)} ms | ` +
-				`matchMetadataStrictCalls=${matchMetadataStrictCalls}, ` +
-				`matchMetadataUnchanged=${matchMetadataUnchanged}, ` +
+				`isUnchangedCalls=${isUnchangedCalls}, ` +
+				`isUnchangedHits=${isUnchangedHits}, ` +
 				`modifiedNodesSkips=${modifiedNodesSkips}`);
 		}
 

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

@@ -14,54 +14,7 @@ const perfCounters = {
 	inodeMismatch: 0,
 	integrityFallback: 0,
 };
-export {perfCounters as matchResourceMetadataStrictCounters};
-
-/**
- * Compares a resource instance with cached resource metadata
- *
- * Optimized for quickly rejecting changed files. Performs a series of checks
- * starting with the cheapest (timestamp) to more expensive (integrity hash).
- *
- * @public
- * @param {@ui5/fs/Resource} resource Resource instance to compare
- * @param {ResourceMetadata} resourceMetadata Resource metadata to compare against
- * @param {number} [indexTimestamp] Timestamp of the metadata creation
- * @returns {Promise<boolean>} True if resource is found to match the metadata
- * @throws {Error} If resource or metadata is undefined
- */
-export async function matchResourceMetadata(resource, resourceMetadata, indexTimestamp) {
-	if (!resource || !resourceMetadata) {
-		throw new Error("Cannot compare undefined resources or metadata");
-	}
-
-	const currentLastModified = resource.getLastModified();
-	if (indexTimestamp && currentLastModified > indexTimestamp) {
-		// Resource modified after index was created, no need for further checks
-		return false;
-	}
-	if (currentLastModified !== resourceMetadata.lastModified) {
-		return false;
-	}
-	if (await resource.getSize() !== resourceMetadata.size) {
-		return false;
-	}
-	const incomingInode = resource.getInode();
-	if (resourceMetadata.inode !== undefined && incomingInode !== undefined &&
-		incomingInode !== resourceMetadata.inode) {
-		return false;
-	}
-
-	if (currentLastModified === indexTimestamp) {
-		// If the source modification time is equal to index creation time,
-		// it's possible for a race condition to have occurred where the file was modified
-		// during index creation without changing its size.
-		// In this case, we need to perform an integrity check to determine if the file has changed.
-		if (await resource.getIntegrity() !== resourceMetadata.integrity) {
-			return false;
-		}
-	}
-	return true;
-}
+export {perfCounters as isResourceUnchangedCounters};
 
 /**
  * Determines if a resource has changed compared to cached metadata
@@ -77,7 +30,7 @@ export async function matchResourceMetadata(resource, resourceMetadata, indexTim
  * @returns {Promise<boolean>} True if resource content is unchanged
  * @throws {Error} If resource or metadata is undefined
  */
-export async function matchResourceMetadataStrict(resource, cachedMetadata, indexTimestamp) {
+export async function isResourceUnchanged(resource, cachedMetadata, indexTimestamp) {
 	if (!resource || !cachedMetadata) {
 		throw new Error("Cannot compare undefined resources or metadata");
 	}

packages/project/test/lib/build/cache/index/HashTree.js

@@ -264,7 +264,7 @@ test("upsertResources returns empty array when no changes", async (t) => {
 	t.deepEqual(updated, [], "Should return empty array when no changes");
 });
 
-// Companion to the matchResourceMetadataStrict test in cache/utils.js: ensure
+// Companion to the isResourceUnchanged test in cache/utils.js: ensure
 // upsertResources also detects size mismatches when the cached mtime is preserved.
 test(
 	"upsertResources: classifies as updated when content changed but mtime preserved (size differs)",