From 702770d5eb2b8ed2aabb5a54ee2ead2e380679bb Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Mon, 16 Nov 2026 15:29:25 +0000 Subject: [PATCH 1/3] metro-file-map: Record observations from matchFiles Since https://github.com/react/metro/pull/1944, `lookup` and `hierarchicalLookup` take an optional `Observations` record, but `matchFiles` doesn't. That leaves listing a directory as the one file system query whose dependencies can't be recorded, so anything built on an enumeration (`require.context` today, resolver-provided virtual modules later) can't be invalidated precisely. This adds the same optional trailing parameter to `matchFiles`. Each directory listed is recorded in `content`, since adding or removing an entry is a modification of the directory. Each symlink encountered is recorded along with what it resolved to. A `rootDir` that is a file, or the first missing segment of one that doesn't exist, is recorded in `existence`. Recording happens as the result is iterated. Metro doesn't pass a record yet - `require.context` lists files when the context module is transformed, outside any resolution. Changelog: Internal Test plan: New unit tests, on posix and win32. Listing from an ancestor of the project root doesn't resolve symlinks inside the project (existing behaviour, with or without a record), so that case only asserts the directories listed. --- packages/metro-file-map/API.md | 19 +-- packages/metro-file-map/src/flow-types.js | 39 ++++-- packages/metro-file-map/src/lib/TreeFS.js | 47 ++++++- .../src/lib/__tests__/TreeFS-test.js | 130 ++++++++++++++++++ 4 files changed, 210 insertions(+), 25 deletions(-) diff --git a/packages/metro-file-map/API.md b/packages/metro-file-map/API.md index 87af82ff8c..f9415e41fe 100644 --- a/packages/metro-file-map/API.md +++ b/packages/metro-file-map/API.md @@ -195,14 +195,17 @@ interface FileSystem_2 { ): null | undefined | {absolutePath: string; containerRelativePath: string}; linkStats(file: Path): null | undefined | FileStats; lookup(mixedPath: Path, observations?: null | undefined | Observations): LookupResult; - matchFiles(opts: { - filter?: RegExp | null | undefined; - filterCompareAbsolute?: boolean | undefined; - filterComparePosix?: boolean | undefined; - follow?: boolean | undefined; - recursive?: boolean | undefined; - rootDir?: Path | null | undefined; - }): Iterable; + matchFiles( + opts: { + filter?: RegExp | null | undefined; + filterCompareAbsolute?: boolean | undefined; + filterComparePosix?: boolean | undefined; + follow?: boolean | undefined; + recursive?: boolean | undefined; + rootDir?: Path | null | undefined; + }, + observations?: null | undefined | Observations, + ): Iterable; } export {FileSystem_2 as FileSystem}; diff --git a/packages/metro-file-map/src/flow-types.js b/packages/metro-file-map/src/flow-types.js index 24a8524779..6dbb969016 100644 --- a/packages/metro-file-map/src/flow-types.js +++ b/packages/metro-file-map/src/flow-types.js @@ -453,20 +453,31 @@ export interface FileSystem { */ lookup(mixedPath: Path, observations?: ?Observations): LookupResult; - matchFiles(opts: { - /* Filter relative paths against a pattern. */ - filter?: RegExp | null, - /* `filter` is applied against absolute paths, vs rootDir-relative. (default: false) */ - filterCompareAbsolute?: boolean, - /* `filter` is applied against posix-delimited paths, even on Windows. (default: false) */ - filterComparePosix?: boolean, - /* Follow symlinks when enumerating paths. (default: false) */ - follow?: boolean, - /* Should search for files recursively. (default: true) */ - recursive?: boolean, - /* Match files under a given root, or null for all files */ - rootDir?: Path | null, - }): Iterable; + /** + * Enumerate the files under `rootDir` that match `filter`. + * + * If `observations` is given, records the paths the result depends upon as + * it is iterated: every directory enumerated, any symlink traversed or + * enumerated and what it resolved to, and either `rootDir` or the first + * segment of it that did not exist. + */ + matchFiles( + opts: { + /* Filter relative paths against a pattern. */ + filter?: RegExp | null, + /* `filter` is applied against absolute paths, vs rootDir-relative. (default: false) */ + filterCompareAbsolute?: boolean, + /* `filter` is applied against posix-delimited paths, even on Windows. (default: false) */ + filterComparePosix?: boolean, + /* Follow symlinks when enumerating paths. (default: false) */ + follow?: boolean, + /* Should search for files recursively. (default: true) */ + recursive?: boolean, + /* Match files under a given root, or null for all files */ + rootDir?: Path | null, + }, + observations?: ?Observations, + ): Iterable; } export type JsonData = diff --git a/packages/metro-file-map/src/lib/TreeFS.js b/packages/metro-file-map/src/lib/TreeFS.js index 88b3a76410..184d4cf16c 100644 --- a/packages/metro-file-map/src/lib/TreeFS.js +++ b/packages/metro-file-map/src/lib/TreeFS.js @@ -508,7 +508,10 @@ export default class TreeFS implements MutableFileSystem { * The query matches against normalized paths which start with `./`, * for example: `a/b.js` -> `./a/b.js` */ - *matchFiles(opts: MatchFilesOptions): Iterable { + *matchFiles( + opts: MatchFilesOptions, + observations?: ?Observations, + ): Iterable { const { filter = null, filterCompareAbsolute = false, @@ -520,9 +523,12 @@ export default class TreeFS implements MutableFileSystem { const normalRoot = rootDir == null ? '' : this.#normalizePath(rootDir); const contextRootResult = this.#lookupByNormalPath( normalRoot, - LOOKUP_OPTIONS, + observations == null ? LOOKUP_OPTIONS : {...LOOKUP_OPTIONS, observations}, ); if (!contextRootResult.exists) { + if (observations) { + observations.existence.add(contextRootResult.canonicalMissingPath); + } return; } const { @@ -532,6 +538,9 @@ export default class TreeFS implements MutableFileSystem { parentNode: contextRootParent, } = contextRootResult; if (!isDirectory(contextRoot)) { + if (observations) { + observations.existence.add(rootRealPath); + } return; } const contextRootAbsolutePath = @@ -554,6 +563,7 @@ export default class TreeFS implements MutableFileSystem { alwaysYieldPosix: filterComparePosix, canonicalPathOfRoot: rootRealPath, follow, + observations: observations ?? null, recursive, subtreeOnly: rootDir != null, }, @@ -1374,6 +1384,9 @@ export default class TreeFS implements MutableFileSystem { alwaysYieldPosix: boolean, canonicalPathOfRoot: string, follow: boolean, + // Records each directory enumerated as `content`, by canonical path, + // and what each symlink resolved to. + observations: ?Observations, recursive: boolean, subtreeOnly: boolean, }>, @@ -1381,6 +1394,10 @@ export default class TreeFS implements MutableFileSystem { followedLinks: ReadonlySet = new Set(), ): Iterable { const pathSep = opts.alwaysYieldPosix ? '/' : path.sep; + const {observations} = opts; + if (observations) { + observations.content.add(opts.canonicalPathOfRoot); + } const stack = [ { entries: this.#directoryNodeIterator( @@ -1388,6 +1405,8 @@ export default class TreeFS implements MutableFileSystem { iterationRootParentNode, ancestorOfRootIdx, ), + // Tracked only when observing. + canonicalPath: opts.canonicalPathOfRoot, parentNode: iterationRootParentNode, ancestorOfRootIdx, prefixWithSep: pathPrefix === '' ? '' : pathPrefix + pathSep, @@ -1433,12 +1452,20 @@ export default class TreeFS implements MutableFileSystem { // the canonical symlink, and then to its target. const resolved = this.#lookupByNormalPath( normalPathOfSymlink, - LOOKUP_OPTIONS, + observations == null + ? LOOKUP_OPTIONS + : {...LOOKUP_OPTIONS, observations}, ); if (!resolved.exists) { // Symlink goes nowhere, nothing to report. + if (observations) { + observations.existence.add(resolved.canonicalMissingPath); + } continue; } + if (observations) { + observations.existence.add(resolved.canonicalPath); + } const target = resolved.node; if (!isDirectory(target)) { // Symlink points to a file, just yield the path of the symlink. @@ -1450,12 +1477,16 @@ export default class TreeFS implements MutableFileSystem { ) { // Symlink points to a directory - iterate over its contents using // the path where we found the symlink as a prefix. + if (observations) { + observations.content.add(resolved.canonicalPath); + } stack.push({ entries: this.#directoryNodeIterator( target, resolved.parentNode, resolved.ancestorOfRootIdx, ), + canonicalPath: resolved.canonicalPath, parentNode: resolved.parentNode, ancestorOfRootIdx: resolved.ancestorOfRootIdx, prefixWithSep: nodePath + pathSep, @@ -1468,12 +1499,22 @@ export default class TreeFS implements MutableFileSystem { frame.ancestorOfRootIdx != null && frame.ancestorOfRootIdx > 0 ? frame.ancestorOfRootIdx - 1 : null; + // A directory reached without traversing a symlink is canonical. + const canonicalPath = + observations == null + ? '' + : this.#pathUtils.joinNormalToRelative(frame.canonicalPath, name) + .normalPath; + if (observations) { + observations.content.add(canonicalPath); + } stack.push({ entries: this.#directoryNodeIterator( node, frame.parentNode, childAncestorOfRootIdx, ), + canonicalPath, parentNode: frame.parentNode, ancestorOfRootIdx: childAncestorOfRootIdx, prefixWithSep: nodePath + pathSep, diff --git a/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js b/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js index 43faac6d99..868d0b3001 100644 --- a/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js +++ b/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js @@ -1166,6 +1166,136 @@ describe.each([['win32'], ['posix']])('TreeFS on %s', platform => { ), ).toEqual([]); }); + + describe('observations', () => { + function observe(opts: Parameters[0]) { + const observations = emptyObservations(); + const files = Array.from(tfs.matchFiles(opts, observations)); + return {files, observations}; + } + + // Every symlink listed is resolved, to decide whether it is a file or a + // directory, so each is recorded with what it resolved to. + const topLevelSymlinks = [ + p('/project/link-to-foo'), + p('/project/abs-link-out'), + p('/project/root'), + p('/project/link-to-nowhere'), + p('/project/link-to-self'), + p('/project/link-cycle-1'), + p('/project/link-cycle-2'), + ]; + const topLevelSymlinkTargets = [ + p('/project/foo'), + p('/outside'), + p('/'), + p('/project/nowhere'), + p('/project/link-to-self'), + p('/project/link-cycle-2'), + p('/project/link-cycle-1'), + ]; + + test.each([ + [ + 'records the directory enumerated, non-recursively', + {recursive: false, rootDir: p('/project')}, + [p('/project'), ...topLevelSymlinks], + topLevelSymlinkTargets, + ], + [ + 'records each directory enumerated, recursively', + {follow: false, recursive: true, rootDir: p('/project')}, + [ + p('/project'), + p('/project/foo'), + p('/project/foo/owndir'), + p('/project/foo/link-to-bar.js'), + p('/project/foo/link-to-another.js'), + ...topLevelSymlinks, + p('/project/node_modules'), + p('/project/node_modules/pkg'), + ], + [ + p('/project/foo'), + p('/project/bar.js'), + p('/project/foo/another.js'), + ...topLevelSymlinkTargets, + ], + ], + [ + 'records a followed symlink to a directory by its target', + {follow: true, recursive: true, rootDir: p('/project/foo')}, + [ + p('/project/foo'), + p('/project/foo/owndir'), + p('/project/foo/link-to-bar.js'), + p('/project/foo/link-to-another.js'), + ], + [ + p('/project/foo'), + p('/project/bar.js'), + p('/project/foo/another.js'), + ], + ], + [ + 'records a symlink traversed to reach rootDir', + {follow: true, recursive: false, rootDir: p('/project/link-to-foo')}, + [ + p('/project/link-to-foo'), + p('/project/foo'), + p('/project/foo/owndir'), + p('/project/foo/link-to-bar.js'), + p('/project/foo/link-to-another.js'), + ], + [ + p('/project/foo'), + p('/project/bar.js'), + p('/project/foo/another.js'), + ], + ], + [ + 'records the first missing segment of a missing rootDir', + {rootDir: p('/project/missing/deeper')}, + [], + [p('/project/missing')], + ], + [ + 'records a rootDir that is a file', + {rootDir: p('/project/bar.js')}, + [], + [p('/project/bar.js')], + ], + ])('%s', (_name, opts, content, existence) => { + expect(observe(opts).observations).toEqual({ + content: new Set(content.map(canonical)), + existence: new Set(existence.map(canonical)), + }); + }); + + test('records directories outside the project root by canonical path', () => { + expect( + observe({follow: false, recursive: true, rootDir: p('/')}) + .observations.content, + ).toEqual( + new Set( + [ + p('/'), + p('/project'), + p('/project/foo'), + p('/project/node_modules'), + p('/project/node_modules/pkg'), + p('/outside'), + ].map(canonical), + ), + ); + }); + + test('records only once iterated', () => { + const observations = emptyObservations(); + tfs.matchFiles({rootDir: p('/project/foo')}, observations); + expect(observations).toEqual(emptyObservations()); + }); + }); }); test('compare absolute', () => { From b2d0173c204617521e419854b6b66b3f7289117e Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Wed, 18 Nov 2026 13:16:36 +0000 Subject: [PATCH 2/3] Test matchFiles observations through a symlink to a separate directory --- .../src/lib/__tests__/TreeFS-test.js | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js b/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js index d797e8f1e9..0c1c6368a2 100644 --- a/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js +++ b/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js @@ -1500,6 +1500,39 @@ describe.each([['win32'], ['posix']])('TreeFS on %s', platform => { }); }); + test('records a followed symlink target, and directories beneath it, by canonical path', () => { + tfs = new TreeFS({ + rootDir: p('/project'), + files: new Map([ + [p('src/index.js'), [0, 0, 0, null, 0, null]], + [p('src/link-to-lib'), [0, 0, 0, null, 'lib', null]], + [p('lib/nested/deep.js'), [0, 0, 0, null, 0, null]], + ]), + processFile: () => { + throw new Error('Not implemented'); + }, + }); + expect( + observe({follow: true, recursive: true, rootDir: p('/project/src')}), + ).toEqual({ + files: [ + p('/project/src/index.js'), + p('/project/src/link-to-lib/nested/deep.js'), + ], + observations: { + content: new Set( + [ + p('/project/src'), + p('/project/src/link-to-lib'), + p('/project/lib'), + p('/project/lib/nested'), + ].map(canonical), + ), + existence: new Set([p('/project/lib')].map(canonical)), + }, + }); + }); + test('records only once iterated', () => { const observations = emptyObservations(); tfs.matchFiles({rootDir: p('/project/foo')}, observations); From 295419dea2d1ef3e2f6faacd8b86bef33f6f977a Mon Sep 17 00:00:00 2001 From: Rob Hogan <2590098+robhogan@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:39:21 +0000 Subject: [PATCH 3/3] Build the symlink lookup options once and drop a redundant test row --- packages/metro-file-map/src/lib/TreeFS.js | 8 ++++---- .../src/lib/__tests__/TreeFS-test.js | 15 --------------- 2 files changed, 4 insertions(+), 19 deletions(-) diff --git a/packages/metro-file-map/src/lib/TreeFS.js b/packages/metro-file-map/src/lib/TreeFS.js index b65ceb2085..c05a8088e8 100644 --- a/packages/metro-file-map/src/lib/TreeFS.js +++ b/packages/metro-file-map/src/lib/TreeFS.js @@ -561,7 +561,7 @@ export default class TreeFS implements MutableFileSystem { alwaysYieldPosix: filterComparePosix, canonicalPathOfRoot: rootRealPath, follow, - observations: observations ?? null, + observations, recursive, subtreeOnly: rootDir != null, }, @@ -1410,6 +1410,8 @@ export default class TreeFS implements MutableFileSystem { ): Iterable { const pathSep = opts.alwaysYieldPosix ? '/' : path.sep; const {observations} = opts; + const symlinkLookupOptions = + observations == null ? LOOKUP_OPTIONS : {...LOOKUP_OPTIONS, observations}; // Symlinks are resolved from the canonical path of their directory. The // path where they were found differs when it passes through followed // symlinks, or re-enters the root from an ancestor ('..' + 'project/link'). @@ -1482,9 +1484,7 @@ export default class TreeFS implements MutableFileSystem { const resolved = this.#lookupByNormalPath( this.#pathUtils.joinNormalToRelative(frame.canonicalPath, name) .normalPath, - observations == null - ? LOOKUP_OPTIONS - : {...LOOKUP_OPTIONS, observations}, + symlinkLookupOptions, ); if (!resolved.exists) { // Symlink goes nowhere, nothing to report. diff --git a/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js b/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js index 0c1c6368a2..aae5b81ea1 100644 --- a/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js +++ b/packages/metro-file-map/src/lib/__tests__/TreeFS-test.js @@ -1450,21 +1450,6 @@ describe.each([['win32'], ['posix']])('TreeFS on %s', platform => { ...topLevelSymlinkTargets, ], ], - [ - 'records a followed symlink to a directory by its target', - {follow: true, recursive: true, rootDir: p('/project/foo')}, - [ - p('/project/foo'), - p('/project/foo/owndir'), - p('/project/foo/link-to-bar.js'), - p('/project/foo/link-to-another.js'), - ], - [ - p('/project/foo'), - p('/project/bar.js'), - p('/project/foo/another.js'), - ], - ], [ 'records a symlink traversed to reach rootDir', {follow: true, recursive: false, rootDir: p('/project/link-to-foo')},