Skip to content

Resolver: Collect file system observations per resolution under unstable_incrementalResolution - #1949

Open
robhogan wants to merge 3 commits into
pr2230from
robhogan/collect-resolution-observations
Open

robhogan wants to merge 3 commits into
pr2230from
robhogan/collect-resolution-observations

Conversation

@robhogan

@robhogan robhogan commented Sep 18, 2026 •

Copy link
Copy Markdown
Collaborator

The first consumer of the Observations API from #1944. With resolver.unstable_incrementalResolution on, each resolution records everything it looks up in the file map, and the record is returned on the BundlerResolution as unstable_observations. Invalidating from it is the next step, so resolution results are unaffected, and with the flag off nothing is allocated.

This unblocks a few related goals:

  1. Incremental resolution in general - fewer whole graph bailouts (eg, as we do on any package.json or symlink change), more correct handling of a new file that should take priority.
  2. require.context as a standard virtual module - currently has bespoke DeltaCalculator handling, but if it used a resolver-driven virtual module defined by matchFiles we could invalidate it as a resolution.
  3. On-demand file system by throwing more detailed resolution errors - knowing what paths Metro can't see, we can determine whether watching more directories would fix it.

ModuleResolver already builds a resolution context per call, so with the flag on it binds the file system capabilities in that context to the resolution's record:

try {
const result = Resolver.resolve(
{
allowHaste,
assetExts,
customResolverOptions: resolverOptions.customResolverOptions ?? {},
dependency,
dev: resolverOptions.dev,
disableHierarchicalLookup,
extraNodeModules,
fileSystemLookup,
getPackage,
getPackageForModule,
isESMImport: dependency.data.isESMImport,
mainFields,
nodeModulesPaths,
originModulePath,
preferNativePlatform,
resolveAsset,
resolveHasteModule: (name: string) =>
this._options.getHasteModulePath(name, platform),
resolveHastePackage: (name: string) =>
this._options.getHastePackagePath(name, platform),

A custom resolveRequest therefore records whatever it looks up through the context without knowing about any of this, and DependencyGraph's whole-resolution cache carries the record along with the cached resolution.

Still to follow: package.json contents, which are still read outside the file map, Haste lookups (#1952), and failed resolutions.

With the flag on this costs ~13% of resolution time (~2µs per resolution) and 2.1x the retained heap (5.3MB -> 11.1MB on our benchmark app). Nearly all of that is extension and platform candidates that missed (a.ios.js, a.native.js, ...), which is what to go after before this is worth turning on, eg by recording the directory once. With the flag off, everything is within noise.

No plans to turn the flag on for all resolution just yet.

Benchmark

AI-driven. Every resolveDependency call of one iOS dev build replayed through the whole-resolution cache, 7 interleaved rounds. Heap is measured in a fresh process per configuration. Resolutions are identical with the flag on and off.

scenario main this PR, flag off this PR, flag on
first build (ms) 129.0 131.0 (+1.6%) 137.4 (+6.6%)
rebuild, nothing changed (ms) 7.98 7.96 (-0.3%) 8.04 (+0.8%)
after a source edit, re-resolving the edited module's dependencies (µs) 229 219 (-4.3%) 256 (+11.8%)
after a package.json change, re-resolving everything (ms) 102.5 101.9 (-0.6%) 116.2 (+13.3%)
heap retained after resolving (MB) 5.3 5.3 11.1 (2.1x)

Changelog: Internal

Test plan

New tests assert the exact sets recorded for a relative import, a package walk, a symlink, asset variants and the empty module, and that nothing is present by default.

Benchmark app: the synthetic RN 0.87 app described in #1945 (2.8k-module bundle, 34k-file file map).

@robhogan
robhogan added this pull request to stack #1947 September 18, 2026 18:54
@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Sep 18, 2026
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from b2faf45 to 4e24402 Compare September 18, 2026 19:01
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 4e24402 to 04896ea Compare September 25, 2026 18:04
robhogan added a commit that referenced this pull request Sep 25, 2026
Stacked on #1949.

## Summary
#1949 records what a resolution looks up in the file map. It doesn't record Haste lookups, which aren't paths - the resolver asks the Haste map for a module or package by name, for every bare specifier when `allowHaste` is set. A module of that name appearing later changes the result, so the name needs observing whether or not it was found.

This adds `haste` to `ResolutionObservations`, the set of Haste names a resolution looked up. They're recorded in the two Haste closures that `ModuleResolver` already creates per resolution, so nothing else changes and the resolution context is untouched. It's the bare name that's recorded, not the platform - `HastePlugin` falls back from the platform to `native` and then to the generic module of that name, so a change to any of those bindings can change the answer. Haste packages share the bucket, since they share the namespace.

`metro-file-map` doesn't change. Its `Observations` is an interface, and Metro's record is a wider type that satisfies it, which is why that type wasn't exported.

Two things keep this cheap:
 - Nothing is observed when no file can be given a Haste name - no `hasteImplModulePath` and `enableGlobalPackages: false`, which is Metro's default. The Haste map is empty then and always will be, so every lookup is a guaranteed miss, and recording one per bare specifier would be paying to observe something that can't change. `createModuleResolver` works this out from config, by the same rule `HastePlugin`'s filter uses.
 - The set is created on the first name recorded, and `haste` is `null` until then. Most resolutions are relative imports that never consult Haste. Allocating a set for each when Haste is enabled cost ~0.9MB on the benchmark app for ~0.2MB of entries.

Nothing reads these yet. Invalidating from them needs `HastePlugin` to report which names changed binding in a batch - it's the only thing that knows, since a removed file's name is gone from the map by the time anyone else sees the change event. That's to follow, alongside invalidation generally.

The empty module is resolved with `allowHaste: false`, so it observes no names and there's nothing to merge for it.

## Benchmark
Resolution time in isolation, flag on in both columns, through the whole-resolution cache (see the test plan). No measurable cost either way - everything is within about half a percent, inside the run-to-run spread.

| scenario | #1949 | this diff | #1949, Haste enabled | this diff, Haste enabled |
|---|---|---|---|---|
| first build (ms) | 112.4 | 111.8 | 111.2 | 110.6 |
| rebuild, nothing changed (ms) | 7.75 | 7.78 | 7.81 | 7.79 |
| after a source edit, the edited module's dependencies (µs) | 177 | 168 | 170 | 172 |
| after a `package.json` change, re-resolving everything (ms) | 93.2 | 93.2 | 93.6 | 94.1 |
| heap retained after resolving (MB) | 18.8 | 18.8 | | 19.1 |

With Haste enabled, 27% of distinct resolutions look up a name (1.9k of 6.9k), one name each, over 72 distinct names. With it inert, no resolution carries a set.

## Test plan
```
yarn jest packages/metro-file-map packages/metro-resolver packages/metro/src/node-haste packages/metro/src/DeltaBundler packages/metro/src/integration_tests
yarn flow check
yarn typecheck-ts
yarn verify-api-snapshots
```
New tests in `resolver-test.js`: nothing is observed when no file can be given a Haste name, a name is recorded when it's found and when it isn't, a deep import records only its package name, a relative import records nothing, and a global package name is recorded. The existing exact-set expectations gain `haste: null`.

**Benchmark app** - a synthetic mid-size RN 0.87 app: 23 common dependencies (Reanimated, React Navigation, TanStack Query, lodash, etc.) and ~1,000 generated first-party modules, 60% of them in a workspace package outside `projectRoot` with its own `node_modules`. The iOS dev bundle is 2.8k modules, from a file map of 34k files. Timings replay the `resolveDependency` calls a real build of it makes against a fresh `DependencyGraph` per process, in interleaved rounds, with source and `package.json` edits made on disk and picked up by the watcher. "Haste enabled" is the same app with `enableGlobalPackages: true`, which gives its first-party packages Haste names. These timings isolate resolution - no transformation, serialisation or file reads are included. A real build of this app takes around 4s even with a warm transform cache, so resolution is about 2% of it.

Changelog: Internal
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch 2 times, most recently from 97d1a02 to 476f5ab Compare September 29, 2026 14:36
@robhogan
robhogan removed this pull request from stack #1947 October 9, 2026 15:33
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 476f5ab to 526109e Compare October 9, 2026 15:34
@robhogan
robhogan added this pull request to stack #2045 October 9, 2026 15:34
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 526109e to 8226d83 Compare October 9, 2026 15:42
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 8226d83 to 4437f0b Compare October 19, 2026 07:10
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 4437f0b to 6ff51cb Compare October 19, 2026 07:23
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 6ff51cb to 69e67ba Compare October 19, 2026 07:34
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 69e67ba to c5e27e6 Compare October 19, 2026 07:48
Base automatically changed from robhogan/remove-closest-package-memo to main October 21, 2026 15:39
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from c5e27e6 to d83ae43 Compare October 21, 2026 17:01
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from d83ae43 to d0ced09 Compare October 30, 2026 14:19
robhogan added a commit that referenced this pull request Oct 30, 2026
Stacked on #1949.

## Summary
#1949 records what a resolution looks up in the file map. It doesn't record Haste lookups, which aren't paths - the resolver asks the Haste map for a module or package by name, for every bare specifier when `allowHaste` is set. A module of that name appearing later changes the result, so the name needs observing whether or not it was found.

This adds `haste` to `ResolutionObservations`, the set of Haste names a resolution looked up. They're recorded in the two Haste closures that `ModuleResolver` already creates per resolution, so nothing else changes and the resolution context is untouched. It's the bare name that's recorded, not the platform - `HastePlugin` falls back from the platform to `native` and then to the generic module of that name, so a change to any of those bindings can change the answer. Haste packages share the bucket, since they share the namespace.

`metro-file-map` doesn't change. Its `Observations` is an interface, and Metro's record is a wider type that satisfies it, which is why that type wasn't exported.

Two things keep this cheap:
 - Nothing is observed when no file can be given a Haste name - no `hasteImplModulePath` and `enableGlobalPackages: false`, which is Metro's default. The Haste map is empty then and always will be, so every lookup is a guaranteed miss, and recording one per bare specifier would be paying to observe something that can't change. `createModuleResolver` works this out from config, by the same rule `HastePlugin`'s filter uses.
 - The set is created on the first name recorded, and `haste` is `null` until then. Most resolutions are relative imports that never consult Haste. Allocating a set for each when Haste is enabled cost ~0.9MB on the benchmark app for ~0.2MB of entries.

Nothing reads these yet. Invalidating from them needs `HastePlugin` to report which names changed binding in a batch - it's the only thing that knows, since a removed file's name is gone from the map by the time anyone else sees the change event. That's to follow, alongside invalidation generally.

The empty module is resolved with `allowHaste: false`, so it observes no names and there's nothing to merge for it.

## Benchmark
Resolution time in isolation, flag on in both columns, through the whole-resolution cache (see the test plan). No measurable cost either way - everything is within about half a percent, inside the run-to-run spread.

| scenario | #1949 | this diff | #1949, Haste enabled | this diff, Haste enabled |
|---|---|---|---|---|
| first build (ms) | 112.4 | 111.8 | 111.2 | 110.6 |
| rebuild, nothing changed (ms) | 7.75 | 7.78 | 7.81 | 7.79 |
| after a source edit, the edited module's dependencies (µs) | 177 | 168 | 170 | 172 |
| after a `package.json` change, re-resolving everything (ms) | 93.2 | 93.2 | 93.6 | 94.1 |
| heap retained after resolving (MB) | 18.8 | 18.8 | | 19.1 |

With Haste enabled, 27% of distinct resolutions look up a name (1.9k of 6.9k), one name each, over 72 distinct names. With it inert, no resolution carries a set.

## Test plan
```
yarn jest packages/metro-file-map packages/metro-resolver packages/metro/src/node-haste packages/metro/src/DeltaBundler packages/metro/src/integration_tests
yarn flow check
yarn typecheck-ts
yarn verify-api-snapshots
```
New tests in `resolver-test.js`: nothing is observed when no file can be given a Haste name, a name is recorded when it's found and when it isn't, a deep import records only its package name, a relative import records nothing, and a global package name is recorded. The existing exact-set expectations gain `haste: null`.

**Benchmark app** - a synthetic mid-size RN 0.87 app: 23 common dependencies (Reanimated, React Navigation, TanStack Query, lodash, etc.) and ~1,000 generated first-party modules, 60% of them in a workspace package outside `projectRoot` with its own `node_modules`. The iOS dev bundle is 2.8k modules, from a file map of 34k files. Timings replay the `resolveDependency` calls a real build of it makes against a fresh `DependencyGraph` per process, in interleaved rounds, with source and `package.json` edits made on disk and picked up by the watcher. "Haste enabled" is the same app with `enableGlobalPackages: true`, which gives its first-party packages Haste names. These timings isolate resolution - no transformation, serialisation or file reads are included. A real build of this app takes around 4s even with a warm transform cache, so resolution is about 2% of it.

Changelog: Internal
robhogan added a commit that referenced this pull request Oct 30, 2026
Stacked on #1949.

## Summary
#1949 records what a resolution looks up in the file map. It doesn't record Haste lookups, which aren't paths - the resolver asks the Haste map for a module or package by name, for every bare specifier when `allowHaste` is set. A module of that name appearing later changes the result, so the name needs observing whether or not it was found.

This adds `haste` to `ResolutionObservations`, the set of Haste names a resolution looked up. They're recorded in the two Haste closures that `ModuleResolver` already creates per resolution, so nothing else changes and the resolution context is untouched. It's the bare name that's recorded, not the platform - `HastePlugin` falls back from the platform to `native` and then to the generic module of that name, so a change to any of those bindings can change the answer. Haste packages share the bucket, since they share the namespace.

`metro-file-map` doesn't change. Its `Observations` is an interface, and Metro's record is a wider type that satisfies it, which is why that type wasn't exported.

Two things keep this cheap:
 - Nothing is observed when no file can be given a Haste name - no `hasteImplModulePath` and `enableGlobalPackages: false`, which is Metro's default. The Haste map is empty then and always will be, so every lookup is a guaranteed miss, and recording one per bare specifier would be paying to observe something that can't change. `createModuleResolver` works this out from config, by the same rule `HastePlugin`'s filter uses.
 - The set is created on the first name recorded, and `haste` is `null` until then. Most resolutions are relative imports that never consult Haste. Allocating a set for each when Haste is enabled cost ~0.9MB on the benchmark app for ~0.2MB of entries.

Nothing reads these yet. Invalidating from them needs `HastePlugin` to report which names changed binding in a batch - it's the only thing that knows, since a removed file's name is gone from the map by the time anyone else sees the change event. That's to follow, alongside invalidation generally.

The empty module is resolved with `allowHaste: false`, so it observes no names and there's nothing to merge for it.

## Benchmark
Resolution time in isolation, flag on in both columns, through the whole-resolution cache (see the test plan). No measurable cost either way - everything is within about half a percent, inside the run-to-run spread.

| scenario | #1949 | this diff | #1949, Haste enabled | this diff, Haste enabled |
|---|---|---|---|---|
| first build (ms) | 112.4 | 111.8 | 111.2 | 110.6 |
| rebuild, nothing changed (ms) | 7.75 | 7.78 | 7.81 | 7.79 |
| after a source edit, the edited module's dependencies (µs) | 177 | 168 | 170 | 172 |
| after a `package.json` change, re-resolving everything (ms) | 93.2 | 93.2 | 93.6 | 94.1 |
| heap retained after resolving (MB) | 18.8 | 18.8 | | 19.1 |

With Haste enabled, 27% of distinct resolutions look up a name (1.9k of 6.9k), one name each, over 72 distinct names. With it inert, no resolution carries a set.

## Test plan
```
yarn jest packages/metro-file-map packages/metro-resolver packages/metro/src/node-haste packages/metro/src/DeltaBundler packages/metro/src/integration_tests
yarn flow check
yarn typecheck-ts
yarn verify-api-snapshots
```
New tests in `resolver-test.js`: nothing is observed when no file can be given a Haste name, a name is recorded when it's found and when it isn't, a deep import records only its package name, a relative import records nothing, and a global package name is recorded. The existing exact-set expectations gain `haste: null`.

**Benchmark app** - a synthetic mid-size RN 0.87 app: 23 common dependencies (Reanimated, React Navigation, TanStack Query, lodash, etc.) and ~1,000 generated first-party modules, 60% of them in a workspace package outside `projectRoot` with its own `node_modules`. The iOS dev bundle is 2.8k modules, from a file map of 34k files. Timings replay the `resolveDependency` calls a real build of it makes against a fresh `DependencyGraph` per process, in interleaved rounds, with source and `package.json` edits made on disk and picked up by the watcher. "Haste enabled" is the same app with `enableGlobalPackages: true`, which gives its first-party packages Haste names. These timings isolate resolution - no transformation, serialisation or file reads are included. A real build of this app takes around 4s even with a warm transform cache, so resolution is about 2% of it.

Changelog: Internal
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 920d7a5 to 4a700b3 Compare October 30, 2026 16:05
robhogan added a commit that referenced this pull request Oct 30, 2026
Stacked on #1949.

## Summary
#1949 records what a resolution looks up in the file map. It doesn't record Haste lookups, which aren't paths - the resolver asks the Haste map for a module or package by name, for every bare specifier when `allowHaste` is set. A module of that name appearing later changes the result, so the name needs observing whether or not it was found.

This adds `haste` to `ResolutionObservations`, the set of Haste names a resolution looked up. They're recorded in the two Haste closures that `ModuleResolver` already creates per resolution, so nothing else changes and the resolution context is untouched. It's the bare name that's recorded, not the platform - `HastePlugin` falls back from the platform to `native` and then to the generic module of that name, so a change to any of those bindings can change the answer. Haste packages share the bucket, since they share the namespace.

`metro-file-map` doesn't change. Its `Observations` is an interface, and Metro's record is a wider type that satisfies it, which is why that type wasn't exported.

Two things keep this cheap:
 - Nothing is observed when no file can be given a Haste name - no `hasteImplModulePath` and `enableGlobalPackages: false`, which is Metro's default. The Haste map is empty then and always will be, so every lookup is a guaranteed miss, and recording one per bare specifier would be paying to observe something that can't change. `createModuleResolver` works this out from config, by the same rule `HastePlugin`'s filter uses.
 - The set is created on the first name recorded, and `haste` is `null` until then. Most resolutions are relative imports that never consult Haste. Allocating a set for each when Haste is enabled cost ~0.9MB on the benchmark app for ~0.2MB of entries.

Nothing reads these yet. Invalidating from them needs `HastePlugin` to report which names changed binding in a batch - it's the only thing that knows, since a removed file's name is gone from the map by the time anyone else sees the change event. That's to follow, alongside invalidation generally.

The empty module is resolved with `allowHaste: false`, so it observes no names and there's nothing to merge for it.

## Benchmark
Resolution time in isolation, flag on in both columns, through the whole-resolution cache (see the test plan). No measurable cost either way - everything is within about half a percent, inside the run-to-run spread.

| scenario | #1949 | this diff | #1949, Haste enabled | this diff, Haste enabled |
|---|---|---|---|---|
| first build (ms) | 112.4 | 111.8 | 111.2 | 110.6 |
| rebuild, nothing changed (ms) | 7.75 | 7.78 | 7.81 | 7.79 |
| after a source edit, the edited module's dependencies (µs) | 177 | 168 | 170 | 172 |
| after a `package.json` change, re-resolving everything (ms) | 93.2 | 93.2 | 93.6 | 94.1 |
| heap retained after resolving (MB) | 18.8 | 18.8 | | 19.1 |

With Haste enabled, 27% of distinct resolutions look up a name (1.9k of 6.9k), one name each, over 72 distinct names. With it inert, no resolution carries a set.

## Test plan
```
yarn jest packages/metro-file-map packages/metro-resolver packages/metro/src/node-haste packages/metro/src/DeltaBundler packages/metro/src/integration_tests
yarn flow check
yarn typecheck-ts
yarn verify-api-snapshots
```
New tests in `resolver-test.js`: nothing is observed when no file can be given a Haste name, a name is recorded when it's found and when it isn't, a deep import records only its package name, a relative import records nothing, and a global package name is recorded. The existing exact-set expectations gain `haste: null`.

**Benchmark app** - a synthetic mid-size RN 0.87 app: 23 common dependencies (Reanimated, React Navigation, TanStack Query, lodash, etc.) and ~1,000 generated first-party modules, 60% of them in a workspace package outside `projectRoot` with its own `node_modules`. The iOS dev bundle is 2.8k modules, from a file map of 34k files. Timings replay the `resolveDependency` calls a real build of it makes against a fresh `DependencyGraph` per process, in interleaved rounds, with source and `package.json` edits made on disk and picked up by the watcher. "Haste enabled" is the same app with `enableGlobalPackages: true`, which gives its first-party packages Haste names. These timings isolate resolution - no transformation, serialisation or file reads are included. A real build of this app takes around 4s even with a warm transform cache, so resolution is about 2% of it.

Changelog: Internal
robhogan added a commit that referenced this pull request Oct 30, 2026
Stacked on #1949.

## Summary
#1949 records what a resolution looks up in the file map. It doesn't record Haste lookups, which aren't paths - the resolver asks the Haste map for a module or package by name, for every bare specifier when `allowHaste` is set. A module of that name appearing later changes the result, so the name needs observing whether or not it was found.

This adds `haste` to `ResolutionObservations`, the set of Haste names a resolution looked up. They're recorded in the two Haste closures that `ModuleResolver` already creates per resolution, so nothing else changes and the resolution context is untouched. It's the bare name that's recorded, not the platform - `HastePlugin` falls back from the platform to `native` and then to the generic module of that name, so a change to any of those bindings can change the answer. Haste packages share the bucket, since they share the namespace.

`metro-file-map` doesn't change. Its `Observations` is an interface, and Metro's record is a wider type that satisfies it, which is why that type wasn't exported.

Two things keep this cheap:
 - Nothing is observed when no file can be given a Haste name - no `hasteImplModulePath` and `enableGlobalPackages: false`, which is Metro's default. The Haste map is empty then and always will be, so every lookup is a guaranteed miss, and recording one per bare specifier would be paying to observe something that can't change. `createModuleResolver` works this out from config, by the same rule `HastePlugin`'s filter uses.
 - The set is created on the first name recorded, and `haste` is `null` until then. Most resolutions are relative imports that never consult Haste. Allocating a set for each when Haste is enabled cost ~0.9MB on the benchmark app for ~0.2MB of entries.

Nothing reads these yet. Invalidating from them needs `HastePlugin` to report which names changed binding in a batch - it's the only thing that knows, since a removed file's name is gone from the map by the time anyone else sees the change event. That's to follow, alongside invalidation generally.

The empty module is resolved with `allowHaste: false`, so it observes no names and there's nothing to merge for it.

## Benchmark
Resolution time in isolation, flag on in both columns, through the whole-resolution cache (see the test plan). No measurable cost either way - everything is within about half a percent, inside the run-to-run spread.

| scenario | #1949 | this diff | #1949, Haste enabled | this diff, Haste enabled |
|---|---|---|---|---|
| first build (ms) | 112.4 | 111.8 | 111.2 | 110.6 |
| rebuild, nothing changed (ms) | 7.75 | 7.78 | 7.81 | 7.79 |
| after a source edit, the edited module's dependencies (µs) | 177 | 168 | 170 | 172 |
| after a `package.json` change, re-resolving everything (ms) | 93.2 | 93.2 | 93.6 | 94.1 |
| heap retained after resolving (MB) | 18.8 | 18.8 | | 19.1 |

With Haste enabled, 27% of distinct resolutions look up a name (1.9k of 6.9k), one name each, over 72 distinct names. With it inert, no resolution carries a set.

## Test plan
```
yarn jest packages/metro-file-map packages/metro-resolver packages/metro/src/node-haste packages/metro/src/DeltaBundler packages/metro/src/integration_tests
yarn flow check
yarn typecheck-ts
yarn verify-api-snapshots
```
New tests in `resolver-test.js`: nothing is observed when no file can be given a Haste name, a name is recorded when it's found and when it isn't, a deep import records only its package name, a relative import records nothing, and a global package name is recorded. The existing exact-set expectations gain `haste: null`.

**Benchmark app** - a synthetic mid-size RN 0.87 app: 23 common dependencies (Reanimated, React Navigation, TanStack Query, lodash, etc.) and ~1,000 generated first-party modules, 60% of them in a workspace package outside `projectRoot` with its own `node_modules`. The iOS dev bundle is 2.8k modules, from a file map of 34k files. Timings replay the `resolveDependency` calls a real build of it makes against a fresh `DependencyGraph` per process, in interleaved rounds, with source and `package.json` edits made on disk and picked up by the watcher. "Haste enabled" is the same app with `enableGlobalPackages: true`, which gives its first-party packages Haste names. These timings isolate resolution - no transformation, serialisation or file reads are included. A real build of this app takes around 4s even with a warm transform cache, so resolution is about 2% of it.

Changelog: Internal
@robhogan
robhogan removed this pull request from stack #2045 November 16, 2026 16:18
@robhogan
robhogan changed the base branch from main to pr2230 November 16, 2026 16:18
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 4a700b3 to 33ce98c Compare November 16, 2026 16:19
@robhogan
robhogan added this pull request to stack #2235 November 16, 2026 16:19
…ble_incrementalResolution

The first consumer of the `Observations` API from #1944. With `resolver.unstable_incrementalResolution` on, each resolution records everything it looks up in the file map, and the record is returned on the `BundlerResolution` as `unstable_observations`. Invalidating from it is the next step, so resolution results are unaffected, and with the flag off nothing is allocated.

`ModuleResolver` already builds a resolution context per call, so with the flag on it binds the file system capabilities in that context to the resolution's record:

https://github.com/react/metro/blob/8f49d3681cfd567c821aaadc958b99fa1d58b4ca/packages/metro/src/node-haste/DependencyGraph/ModuleResolution.js#L144-L166

A custom `resolveRequest` therefore records whatever it looks up through the context without knowing about any of this, and `DependencyGraph`'s whole-resolution cache carries the record along with the cached resolution.

Still to follow: `package.json` contents, which are still read outside the file map, Haste lookups (#1952), and failed resolutions.

With the flag on this costs ~13% of resolution time (~2µs per resolution) and 2.1x the retained heap (5.3MB -> 11.1MB on our benchmark app). Nearly all of that is extension and platform candidates that missed (`a.ios.js`, `a.native.js`, ...), which is what to go after before this is worth turning on, eg by recording the directory once. With the flag off, everything is within noise.

## Benchmark

AI-driven. Every `resolveDependency` call of one iOS dev build replayed through the whole-resolution cache, 7 interleaved rounds. Heap is measured in a fresh process per configuration. Resolutions are identical with the flag on and off.

| scenario | `main` | this PR, flag off | this PR, flag on |
|---|---|---|---|
| first build (ms) | 129.0 | 131.0 (+1.6%) | 137.4 (+6.6%) |
| rebuild, nothing changed (ms) | 7.98 | 7.96 (-0.3%) | 8.04 (+0.8%) |
| after a source edit, re-resolving the edited module's dependencies (µs) | 229 | 219 (-4.3%) | 256 (+11.8%) |
| after a `package.json` change, re-resolving everything (ms) | 102.5 | 101.9 (-0.6%) | 116.2 (+13.3%) |
| heap retained after resolving (MB) | 5.3 | 5.3 | 11.1 (2.1x) |

Changelog: Internal

## Test plan

New tests assert the exact sets recorded for a relative import, a package walk, a symlink, asset variants and the empty module, and that nothing is present by default.

Benchmark app: the synthetic RN 0.87 app described in #1945 (2.8k-module bundle, 34k-file file map).
@robhogan
robhogan force-pushed the robhogan/collect-resolution-observations branch from 33ce98c to 6b94381 Compare November 18, 2026 13:05
@robhogan
robhogan requested a review from huntie November 18, 2026 16:37
@robhogan
robhogan marked this pull request as ready for review November 18, 2026 16:37
@github-actions

Copy link
Copy Markdown

Metro review: Looks good

Risk: low · Commit: addafc8 · 6 commands run

With resolver.unstable_incrementalResolution on, this PR gives each resolution a record and threads it through the file-system capabilities on ModuleResolver's per-call context, getPackageForModule and resolveAsset. The record is returned as unstable_observations on the BundlerResolution, and an empty-module result also gets what resolving the empty module observed. Nothing reads the record yet and the default path doesn't change, so it looks good. With the flag off, a paired head-vs-base benchmark showed no significant change. Typecheck, lint and the resolver tests pass.

Findings

Verified
  • ✅ yarn jest --no-watchman packages/metro/src/DeltaBundler/__tests__/resolver-test.js packages/metro/src/node-haste — 5 suites, 290 tests
  • ✅ yarn typecheck
  • ✅ yarn lint packages/metro/src/node-haste packages/metro/src/DeltaBundler/types.js packages/metro/src/DeltaBundler/__tests__/resolver-test.js — 0 errors. yarn lint printed 1 warning; eslint run on just the changed files printed none.
  • ✅ yarn jest --no-watchman packages/metro/src/DeltaBundler/__tests__/resolver-test.js -t unstable_incrementalResolution (with a new test: custom resolveRequest records context lookups) — The custom resolver's context.fileSystemLookup and the delegated default resolution both land in the record
  • ✅ node bench/resolve-bench.js off 30 — Flag off, head vs base: median ratio 0.988 (0.955-1.013)
  • ✅ node bench/resolve-bench.js on 30 — Flag on in head vs base: median ratio 1.059 (1.028-1.096). Resolved counts match (988/1054).

Benchmarks (base vs this PR)

Benchmark Base This PR Change
DependencyGraph.resolveDependency, cold resolution cache, flag off 32.6ms (31.6-34.5) 32.2ms (31.5-33.3) no significant change
Same benchmark, head with unstable_incrementalResolution on 32.3ms (31.8-33.5) 34.5ms (33.5-35.7) +6% (paired ratio 1.03-1.10)
Method
  • DependencyGraph.resolveDependency, cold resolution cache, flag off: Fixture: copy of the Metro repo's packages/ with node_modules excluded, crawled as projectRoot (1,054 require/import specifiers, 988 resolve). Head and base DependencyGraph run in one process. Cache cleared every round; 3 warm-up rounds, then 30 ABAB rounds. Medians with min-max. Script: bench/resolve-bench.js
  • Same benchmark, head with unstable_incrementalResolution on: Same fixture and script with argument 'on'. Base ignores the flag. 30 ABAB rounds after warm-up; the change is the median of per-round paired ratios, with their range. Close to the description's +6.6% first-build figure.

Not run: No heap measurement, so the description's 2.1x retained-heap figure is unchecked. The benchmark fixture is Metro's own packages, not an RN app: it has a flat node_modules-free layout and no assets. Windows paths are not checked: the observations come from TreeFS canonical paths and the tests build expectations with system separators, but nothing was run on Windows.

Automated review by Claude. Advisory only: it never approves or blocks, and a maintainer makes the call.

});
});

test('origins sharing a cached resolution share its observations', async () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit · No test covers a custom resolveRequest's lookups being recorded

The description gives one property of the design: the capabilities are bound to the record in the context, so a custom resolveRequest gets whatever it looks up through context recorded without knowing about it. The new tests only cover the default resolver. A later refactor could rebuild the context the custom resolver receives, or pass it the unbound this._options.fileSystemLookup. Observations would then quietly stop covering custom resolvers, and no test would fail.

A test like this one pins it, and it passes on this head:

test('a custom resolveRequest records lookups made through context', async () => {
  setMockFileSystem({'index.js': '', 'a.js': ''});
  resolver = await createResolver({resolver: {
    unstable_incrementalResolution: true,
    resolveRequest: (context, name, platform) => {
      context.fileSystemLookup(p('/root/probe.js'));
      return context.resolveRequest(context, name, platform);
    },
  }}, 'ios');
  const res = resolver.resolve(p('/root/index.js'), dep('./a'));
  expect(res.unstable_observations?.existence).toContain('probe.js');
});

Evidence: I added the test above to the head checkout's resolver-test.js, in the unstable_incrementalResolution describe block, and it passes. None of the PR's tests set resolveRequest. · id a61da185

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants