From 7866a3a9356d41aa4ce2466580e2e7f270445fbf Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Mon, 16 Nov 2026 15:29:41 +0000 Subject: [PATCH] metro-file-map: Let plugins report what changed in a batch, on the change event ## Context A file map plugin often knows things about a batch of changes that nothing else can work out. For Haste, #1952 records the names a resolution looked up, and invalidating from those means knowing which names a change rebound. The `ChangeEvent` carries paths, and by the time a consumer sees it a removed file's name is already gone from the map, but `HastePlugin.onChanged` has it to hand: https://github.com/react/metro/blob/6dbe97956af0f66f7a1d88014ba0b784a4a4d893/packages/metro-file-map/src/plugins/HastePlugin.js#L241-L245 ## This change This lets a plugin's `onChanged` return a summary, published on `ChangeEvent.pluginChanges` by plugin name. The summary type defaults to `void`, so existing plugins are unaffected. `HastePlugin` reports `changedNames`. Plugin names now have to be unique across all plugins, not just those with a worker. Persisted state was already keyed by name, so two sharing a name were already overwriting each other. Not addressed here: on a cold start `HastePlugin` builds a summary nobody reads (transient, and nothing where Haste is inert), and an edit that changes a file's Haste name is neither applied to the map nor reported, which predates this. Invalidating from the summary is the next PR. Changelog: Internal ## Test plan New unit tests cover the watch and recrawl paths and duplicate plugin names. --- packages/metro-file-map/API.md | 31 ++++++-- .../src/__tests__/index-test.js | 55 ++++++++++++-- packages/metro-file-map/src/flow-types.js | 15 +++- packages/metro-file-map/src/index.js | 74 ++++++++++++------- .../src/lib/getPluginChanges.js | 21 ++++++ .../metro-file-map/src/plugins/HastePlugin.js | 24 +++++- .../haste/__tests__/HastePlugin-test.js | 34 ++++++++- 7 files changed, 211 insertions(+), 43 deletions(-) create mode 100644 packages/metro-file-map/src/lib/getPluginChanges.js diff --git a/packages/metro-file-map/API.md b/packages/metro-file-map/API.md index 11a5df1818..83f3805063 100644 --- a/packages/metro-file-map/API.md +++ b/packages/metro-file-map/API.md @@ -47,6 +47,7 @@ export type CacheManagerWriteOptions = Readonly<{ export type ChangeEvent = Readonly<{ logger?: null | undefined | RootPerfLogger; changes: ReadonlyFileSystemChanges>; + pluginChanges: ReadonlyMap; rootDir: string; }>; @@ -205,6 +206,25 @@ interface FileSystem_2 { } export {FileSystem_2 as FileSystem}; +export function getPluginChanges( + event: ChangeEvent, + plugin: FileMapPlugin< + /** + * > | plugin: FileMapPlugin, + * | ^^^^^ Unsupported feature: Translating "empty type" is currently not supported. + **/ + any, + /** + * > | plugin: FileMapPlugin, + * | ^^^^^ Unsupported feature: Translating "empty type" is currently not supported. + **/ + any, + ChangeSummary + >, +): ChangeSummary | void; + +export type HasteChanges = Readonly<{changedNames: ReadonlySet}>; + export class HasteConflictsError extends Error { constructor(conflicts: ReadonlyArray); getDetailedMessage(pathsRelativeToRoot: null | undefined | string): string; @@ -223,7 +243,7 @@ export type HasteMapItem = { [platform: string]: HasteMapItemMetadata; }; -export class HastePlugin implements HasteMap, FileMapPlugin { +export class HastePlugin implements HasteMap, FileMapPlugin { constructor(options: HasteMapOptions); assertValid(): void; computeConflicts(): Array; @@ -235,7 +255,7 @@ export class HastePlugin implements HasteMap, FileMapPlugin getWorker(): FileMapPluginWorker; initialize(opts: FileMapPluginInitOptions): Promise; readonly name: 'haste'; - onChanged(delta: ReadonlyFileSystemChanges): void; + onChanged(delta: ReadonlyFileSystemChanges): HasteChanges | void; setModule(id: string, module: HasteMapItemMetadata): void; } @@ -261,15 +281,16 @@ export type HealthCheckResult = export type InputFileMapPlugin = FileMapPlugin< /** - * > | export type InputFileMapPlugin = FileMapPlugin; + * > | export type InputFileMapPlugin = FileMapPlugin; * | ^^^^^ Unsupported feature: Translating "empty type" is currently not supported. **/ any, /** - * > | export type InputFileMapPlugin = FileMapPlugin; + * > | export type InputFileMapPlugin = FileMapPlugin; * | ^^^^^ Unsupported feature: Translating "empty type" is currently not supported. **/ - any + any, + unknown >; export type InputOptions = Readonly<{ diff --git a/packages/metro-file-map/src/__tests__/index-test.js b/packages/metro-file-map/src/__tests__/index-test.js index 652da71b5e..fcda132fdf 100644 --- a/packages/metro-file-map/src/__tests__/index-test.js +++ b/packages/metro-file-map/src/__tests__/index-test.js @@ -26,7 +26,7 @@ import type { } from '../flow-types'; import type {DependencyPlugin} from '../index'; import type {default as FileMapT} from '../index'; -import type {HasteMapOptions} from '../plugins/HastePlugin'; +import type HastePluginT, {HasteMapOptions} from '../plugins/HastePlugin'; import type {MockMapOptions} from '../plugins/MockPlugin'; import type {WatcherOptions} from '../watchers/common'; import typeof WorkerModule from '../worker'; @@ -302,7 +302,7 @@ let buildNewFileMap: ( ) => Promise<{ ...BuildResult, fileMap: FileMapT, - hasteMap: HasteMap, + hasteMap: HastePluginT, mockMap: ?MockMap, dependencyPlugin: ?DependencyPlugin, }>; @@ -504,6 +504,24 @@ describe('FileMap', () => { ).toMatchObject({exists: true, type: 'f', data: null}); }); + test('throws on plugins that share a name, with or without a worker', () => { + const MockPlugin = require('../plugins/MockPlugin').default; + const mockConfig = { + console: globalThis.console, + rootDir: defaultConfig.rootDir, + mocksPattern: /__mocks__/, + throwOnModuleCollision: false, + }; + expect( + () => + new FileMap({ + ...defaultConfig, + // MockPlugin has no worker, so holds no plugin data slot + plugins: [new MockPlugin(mockConfig), new MockPlugin(mockConfig)], + }), + ).toThrow('metro-file-map: Duplicate plugin name: mocks'); + }); + test('ignores files given a pattern', async () => { mockFs[p('/project/fruits/Kiwi.js')] = ` // Kiwi! @@ -1743,6 +1761,28 @@ describe('FileMap', () => { } }); + fm_it( + 'publishes what each plugin reports about a batch on the change event', + async ({fileMap, hasteMap}) => { + const getPluginChanges = require('../lib/getPluginChanges').default; + const fruitsRoot = path.join('/', 'project', 'fruits'); + mockFs[path.join(fruitsRoot, 'Tomato.js')] = '// Tomato!'; + mockEmitters[fruitsRoot].emitFileEvent({ + event: 'touch', + relativePath: 'Tomato.js', + metadata: MOCK_CHANGE_FILE, + }); + mockDeleteFile(fruitsRoot, 'Banana.js'); + const changeEvent = await waitForItToChange(fileMap); + + expect(getPluginChanges(changeEvent, hasteMap)).toEqual({ + changedNames: new Set(['Tomato', 'Banana']), + }); + // Only plugins with something to say are present + expect([...changeEvent.pluginChanges.keys()]).toEqual([hasteMap.name]); + }, + ); + function mockDeleteFile(root: string, relativePath: string) { const e = mockEmitters[root]; e.emitFileEvent({event: 'delete', relativePath}); @@ -1757,7 +1797,7 @@ describe('FileMap', () => { function fm_it( title: string, - fn: (fm: Readonly<{fileMap: FileMap, hasteMap: HasteMap}>) => unknown, + fn: (fm: Readonly<{fileMap: FileMap, hasteMap: HastePluginT}>) => unknown, options?: FileMapTestOptions = {}, ): void { options = options || {}; @@ -1780,7 +1820,7 @@ describe('FileMap', () => { fm_it.only = ( title: string, - fn: (fm: Readonly<{fileMap: FileMap, hasteMap: HasteMap}>) => unknown, + fn: (fm: Readonly<{fileMap: FileMap, hasteMap: HastePluginT}>) => unknown, options?: FileMapTestOptions, ): void => fm_it(title, fn, {...options, only: true}); @@ -2620,7 +2660,12 @@ describe('FileMap', () => { relativePath: 'tropical', }); - await waitForItToChange(fileMap); + const changeEvent = await waitForItToChange(fileMap); + + // What plugins report during a recrawl still reaches the event + expect( + require('../lib/getPluginChanges').default(changeEvent, hasteMap), + ).toEqual({changedNames: new Set(['Mango', 'Papaya'])}); // Verify crawl was called with the correct directory expect(mockNodeCrawler).toHaveBeenNthCalledWith( diff --git a/packages/metro-file-map/src/flow-types.js b/packages/metro-file-map/src/flow-types.js index 655fd81438..b5190c196f 100644 --- a/packages/metro-file-map/src/flow-types.js +++ b/packages/metro-file-map/src/flow-types.js @@ -111,6 +111,11 @@ export type ChangedFileMetadata = Readonly<{ export type ChangeEvent = Readonly<{ logger?: ?RootPerfLogger, changes: ReadonlyFileSystemChanges>, + /** + * What each plugin reported about this batch, by name, if anything. Read + * entries with `getPluginChanges`. + */ + pluginChanges: ReadonlyMap, rootDir: string, }>; @@ -300,19 +305,25 @@ export type V8Serializable = V8SerializablePrimitive | V8SerializableCollection; export interface FileMapPlugin< in SerializableState extends void | V8Serializable = void | V8Serializable, in PerFileData extends void | V8Serializable = void | V8Serializable, + out ChangeSummary = void, > { + // Must be unique among the plugins of a file map. readonly name: string; initialize( initOptions: FileMapPluginInitOptions, ): Promise; assertValid(): void; - onChanged(changes: ReadonlyFileSystemChanges): void; + /** + * Update the plugin's state for a batch of changes, synchronously before it + * is emitted. May return a summary for `ChangeEvent.pluginChanges`. + */ + onChanged(changes: ReadonlyFileSystemChanges): ChangeSummary; getSerializableSnapshot(): void | V8Serializable; getCacheKey(): string; getWorker(): ?FileMapPluginWorker; } -export type InputFileMapPlugin = FileMapPlugin; +export type InputFileMapPlugin = FileMapPlugin; export interface MetadataWorker { processFile( diff --git a/packages/metro-file-map/src/index.js b/packages/metro-file-map/src/index.js index 7f3df73144..6cbc40ba64 100644 --- a/packages/metro-file-map/src/index.js +++ b/packages/metro-file-map/src/index.js @@ -123,7 +123,7 @@ type InternalOptions = Readonly<{ type IndexedPlugin = Readonly<{ // $FlowFixMe[unclear-type] Plugin types cannot be known statically - plugin: FileMapPlugin, + plugin: FileMapPlugin, dataIdx: ?number, }>; type InternalEnqueuedEvent = Readonly< @@ -148,7 +148,9 @@ export type {FileDataPluginOptions} from './plugins/FileDataPlugin'; export type {DependencyPluginOptions} from './plugins/DependencyPlugin'; export {DuplicateHasteCandidatesError} from './plugins/haste/DuplicateHasteCandidatesError'; export {HasteConflictsError} from './plugins/haste/HasteConflictsError'; +export {default as getPluginChanges} from './lib/getPluginChanges'; export {default as HastePlugin} from './plugins/HastePlugin'; +export type {HasteChanges} from './plugins/HastePlugin'; export type {HasteMap} from './flow-types'; export type {HealthCheckResult} from './Watcher'; @@ -331,19 +333,19 @@ export default class FileMap extends EventEmitter { const pluginWorkers: Array = []; const pluginDataIndices = new Map(); const plugins = options.plugins ?? []; + const pluginNames = new Set(); for (const plugin of plugins) { + // Slots, persisted state and change summaries are all keyed by name + invariant( + !pluginNames.has(plugin.name), + 'metro-file-map: Duplicate plugin name: %s', + plugin.name, + ); + pluginNames.add(plugin.name); const maybeWorker = plugin.getWorker(); const dataIdx = maybeWorker != null ? dataSlot++ : null; indexedPlugins.push({plugin, dataIdx}); if (dataIdx != null) { - // Crawlers address plugin data by name, so names must be unique among - // plugins holding a slot - otherwise a crawler would silently write to - // the shadowed plugin's slot. - invariant( - !pluginDataIndices.has(plugin.name), - 'metro-file-map: Duplicate plugin name: %s', - plugin.name, - ); pluginDataIndices.set(plugin.name, dataIdx); } if (maybeWorker != null) { @@ -557,7 +559,8 @@ export default class FileMap extends EventEmitter { } // Update `fileSystem` and plugins based on the file delta. - const actualChanges = await this.#applyFileDelta( + // The initial build emits nothing, so plugin summaries are unused + const {changeAggregator: actualChanges} = await this.#applyFileDelta( fileSystem, plugins, fileDelta, @@ -685,7 +688,7 @@ export default class FileMap extends EventEmitter { // end() may have been called during the crawl or while applying it. const abortSignal = this.#crawlerAbortController.signal; abortSignal.throwIfAborted(); - const changeAggregator = await this.#applyFileDelta( + const {changeAggregator, pluginChanges} = await this.#applyFileDelta( fileSystem, this.#plugins, crawlResult, @@ -697,6 +700,7 @@ export default class FileMap extends EventEmitter { const changeEvent: ChangeEvent = { changes: changeAggregator.getMappedView(toPublicMetadata), logger: null, + pluginChanges, rootDir: this.#options.rootDir, }; this.emit('change', changeEvent); @@ -797,6 +801,24 @@ export default class FileMap extends EventEmitter { return null; } + /** Update every plugin with a batch and collect their summaries. */ + #updatePlugins( + changeAggregator: FileSystemChangeAggregator, + ): Map { + const pluginChanges = new Map(); + this.#plugins.forEach(({plugin, dataIdx}) => { + const summary = plugin.onChanged( + changeAggregator.getMappedView( + dataIdx != null ? metadata => metadata[dataIdx] : () => null, + ), + ); + if (summary != null) { + pluginChanges.set(plugin.name, summary); + } + }); + return pluginChanges; + } + async #applyFileDelta( fileSystem: MutableFileSystem, plugins: ReadonlyArray, @@ -805,7 +827,10 @@ export default class FileMap extends EventEmitter { removedFiles: ReadonlySet, clocks?: WatchmanClocks, }>, - ): Promise { + ): Promise<{ + changeAggregator: FileSystemChangeAggregator, + pluginChanges: ReadonlyMap, + }> { this.#startupPerfLogger?.point('applyFileDelta_start'); const {changedFiles, removedFiles} = delta; this.#startupPerfLogger?.point('applyFileDelta_preprocess_start'); @@ -894,17 +919,11 @@ export default class FileMap extends EventEmitter { this.#startupPerfLogger?.point('applyFileDelta_add_end'); this.#startupPerfLogger?.point('applyFileDelta_updatePlugins_start'); - this.#plugins.forEach(({plugin, dataIdx}) => { - plugin.onChanged( - changeAggregator.getMappedView( - dataIdx != null ? metadata => metadata[dataIdx] : () => null, - ), - ); - }); + const pluginChanges = this.#updatePlugins(changeAggregator); this.#startupPerfLogger?.point('applyFileDelta_updatePlugins_end'); this.#startupPerfLogger?.point('applyFileDelta_end'); - return changeAggregator; + return {changeAggregator, pluginChanges}; } /** @@ -1012,13 +1031,7 @@ export default class FileMap extends EventEmitter { } const _netChange = changeAggregator.getView(); - this.#plugins.forEach(({plugin, dataIdx}) => { - plugin.onChanged( - changeAggregator.getMappedView( - dataIdx != null ? metadata => metadata[dataIdx] : () => null, - ), - ); - }); + const pluginChanges = this.#updatePlugins(changeAggregator); const changesWithMetadata = changeAggregator.getMappedView(toPublicMetadata); @@ -1038,6 +1051,7 @@ export default class FileMap extends EventEmitter { const changeEvent: ChangeEvent = { changes: changesWithMetadata, logger: hmrPerfLogger, + pluginChanges, rootDir: this.#options.rootDir, }; this.emit('change', changeEvent); @@ -1182,7 +1196,10 @@ export default class FileMap extends EventEmitter { } // Reuse the same batch processing logic as build() - const recrawlChangeAggregator = await this.#applyFileDelta( + const { + changeAggregator: recrawlChangeAggregator, + pluginChanges: recrawlPluginChanges, + } = await this.#applyFileDelta( fileSystem, this.#plugins, crawlResult, @@ -1203,6 +1220,7 @@ export default class FileMap extends EventEmitter { const changeEvent: ChangeEvent = { changes: changesWithMetadata, logger: null, + pluginChanges: recrawlPluginChanges, rootDir: this.#options.rootDir, }; this.emit('change', changeEvent); diff --git a/packages/metro-file-map/src/lib/getPluginChanges.js b/packages/metro-file-map/src/lib/getPluginChanges.js new file mode 100644 index 0000000000..ac7ce5df2e --- /dev/null +++ b/packages/metro-file-map/src/lib/getPluginChanges.js @@ -0,0 +1,21 @@ +/** + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + * + * @flow strict-local + * @format + * @oncall react_native + */ + +import type {ChangeEvent, FileMapPlugin} from '../flow-types'; + +/** What `plugin`'s `onChanged` returned for `event`'s batch, if anything. */ +export default function getPluginChanges( + event: ChangeEvent, + plugin: FileMapPlugin, +): ChangeSummary | void { + // $FlowFixMe[incompatible-type] Only `plugin` writes the entry under its name + return event.pluginChanges.get(plugin.name); +} diff --git a/packages/metro-file-map/src/plugins/HastePlugin.js b/packages/metro-file-map/src/plugins/HastePlugin.js index 64a7d93fdd..834cb2ae0c 100644 --- a/packages/metro-file-map/src/plugins/HastePlugin.js +++ b/packages/metro-file-map/src/plugins/HastePlugin.js @@ -52,8 +52,14 @@ export type HasteMapOptions = Readonly<{ failValidationOnConflicts: boolean, }>; +/** What `HastePlugin` reports via `getPluginChanges`. */ +export type HasteChanges = Readonly<{ + // Names whose lookup may have changed, on any platform, duplicates included + changedNames: ReadonlySet, +}>; + export default class HastePlugin - implements HasteMap, FileMapPlugin + implements HasteMap, FileMapPlugin { readonly name: 'haste' = 'haste'; @@ -236,14 +242,28 @@ export default class HastePlugin ); } - onChanged(delta: ReadonlyFileSystemChanges): void { + onChanged(delta: ReadonlyFileSystemChanges): HasteChanges | void { + let changedNames: ?Set = null; + const onNameChanged = (name: string) => { + if (changedNames == null) { + changedNames = new Set(); + } + changedNames.add(name); + }; // Process removals first so that moves aren't treated as duplicates. for (const [canonicalPath, maybeHasteId] of delta.removedFiles) { this.#onRemovedFile(canonicalPath, maybeHasteId); + if (maybeHasteId != null) { + onNameChanged(maybeHasteId); + } } for (const [canonicalPath, maybeHasteId] of delta.addedFiles) { this.#onNewFile(canonicalPath, maybeHasteId); + if (maybeHasteId != null) { + onNameChanged(maybeHasteId); + } } + return changedNames != null ? {changedNames} : undefined; } #onNewFile(canonicalPath: string, id: ?string) { diff --git a/packages/metro-file-map/src/plugins/haste/__tests__/HastePlugin-test.js b/packages/metro-file-map/src/plugins/haste/__tests__/HastePlugin-test.js index 00421797d7..ab3ac23ede 100644 --- a/packages/metro-file-map/src/plugins/haste/__tests__/HastePlugin-test.js +++ b/packages/metro-file-map/src/plugins/haste/__tests__/HastePlugin-test.js @@ -101,10 +101,11 @@ describe.each([['win32'], ['posix']])('HastePlugin on %s', platform => { beforeEach(async () => { hasteMap = new HasteMap(opts); - removeFile = (canonicalPath, name) => + removeFile = (canonicalPath, name) => { hasteMap.onChanged( makeChanges({added: [], removed: [[canonicalPath, name]]}), ); + }; await hasteMap.initialize({ files: { fileIterator: jest.fn().mockReturnValue(INITIAL_FILES), @@ -177,6 +178,37 @@ describe.each([['win32'], ['posix']])('HastePlugin on %s', platform => { DuplicateHasteCandidatesError, ); }); + + test('reports the names that were bound and unbound', () => { + expect( + hasteMap.onChanged( + makeChanges({ + added: [ + [p('project/Baz.js'), 'Baz'], + [p('project/other/Bar.js'), 'Bar'], + [p('project/NotHaste.js'), null], + ], + removed: [ + [p('project/Duplicate.js'), 'Duplicate'], + [p('project/Foo.js'), 'NameForFoo'], + ], + }), + ), + ).toEqual({ + changedNames: new Set(['Baz', 'Bar', 'Duplicate', 'NameForFoo']), + }); + }); + + test('reports nothing when no file with a name was added or removed', () => { + expect( + hasteMap.onChanged( + makeChanges({ + added: [[p('project/NotHaste.js'), null]], + removed: [[p('project/AlsoNotHaste.js'), null]], + }), + ), + ).toBeUndefined(); + }); }); describe('getModuleNameByPath', () => {