@atlaspack/core 2.16.2-dev.14 → 2.16.2-dev.55

package/src/RequestTracker.js

@@ -69,6 +69,7 @@ import type {
   InternalGlob,
 } from './types';
 import {BuildAbortError, assertSignalNotAborted, hashFromOption} from './utils';
+import {performance} from 'perf_hooks';
 
 export const requestGraphEdgeTypes = {
   subrequest: 2,
@@ -446,6 +447,11 @@ export class RequestGraph extends ContentGraph<
     this.removeCachedRequestChunkForNode(nodeId);
   }
 
+  /**
+   * Nodes that are invalidated on start-up, such as JavaScript babel configuration files which are
+   * imported when the build kicks-off and might doing arbitrary work such as reading from the file
+   * system.
+   */
   invalidateUnpredictableNodes() {
     for (let nodeId of this.unpredicatableNodeIds) {
       let node = nullthrows(this.getNode(nodeId));
@@ -454,6 +460,9 @@ export class RequestGraph extends ContentGraph<
     }
   }
 
+  /**
+   * Effectively uncacheable nodes.
+   */
   invalidateOnBuildNodes() {
     for (let nodeId of this.invalidateOnBuildNodeIds) {
       let node = nullthrows(this.getNode(nodeId));
@@ -462,11 +471,20 @@ export class RequestGraph extends ContentGraph<
     }
   }
 
-  invalidateEnvNodes(env: EnvMap) {
+  /**
+   * Nodes invalidated by environment changes, corresponds to `env: ...` inputs.
+   */
+  invalidateEnvNodes(env: EnvMap): string[] {
+    const invalidatedKeys = [];
+
     for (let nodeId of this.envNodeIds) {
       let node = nullthrows(this.getNode(nodeId));
       invariant(node.type === ENV);
-      if (env[keyFromEnvContentKey(node.id)] !== node.value) {
+
+      const key = keyFromEnvContentKey(node.id);
+      if (env[key] !== node.value) {
+        invalidatedKeys.push(key);
+
         let parentNodes = this.getNodeIdsConnectedTo(
           nodeId,
           requestGraphEdgeTypes.invalidated_by_update,
@@ -476,15 +494,23 @@ export class RequestGraph extends ContentGraph<
         }
       }
     }
+
+    return invalidatedKeys;
   }
 
-  invalidateOptionNodes(options: AtlaspackOptions) {
+  /**
+   * Nodes invalidated by option changes.
+   */
+  invalidateOptionNodes(options: AtlaspackOptions): string[] {
+    const invalidatedKeys = [];
+
     for (let nodeId of this.optionNodeIds) {
       let node = nullthrows(this.getNode(nodeId));
       invariant(node.type === OPTION);
-      if (
-        hashFromOption(options[keyFromOptionContentKey(node.id)]) !== node.hash
-      ) {
+      const key = keyFromOptionContentKey(node.id);
+
+      if (hashFromOption(options[key]) !== node.hash) {
+        invalidatedKeys.push(key);
         let parentNodes = this.getNodeIdsConnectedTo(
           nodeId,
           requestGraphEdgeTypes.invalidated_by_update,
@@ -494,6 +520,8 @@ export class RequestGraph extends ContentGraph<
         }
       }
     }
+
+    return invalidatedKeys;
   }
 
   invalidateOnConfigKeyChange(
@@ -907,7 +935,10 @@ export class RequestGraph extends ContentGraph<
      * True if this is the start-up (loading phase) invalidation.
      */
     isInitialBuild: boolean = false,
-  ): Async<boolean> {
+  ): Promise<{|
+    didInvalidate: boolean,
+    invalidationsByPath: Map<string, number>,
+  |}> {
     let didInvalidate = false;
     let count = 0;
     let predictedTime = 0;
@@ -945,7 +976,10 @@ export class RequestGraph extends ContentGraph<
       return above;
     };
 
+    const invalidationsByPath = new Map();
     for (let {path: _path, type} of events) {
+      const invalidationsBefore = this.getInvalidNodeCount();
+
       if (
         !enableOptimization &&
         process.env.ATLASPACK_DISABLE_CACHE_TIMEOUT !== 'true' &&
@@ -991,7 +1025,10 @@ export class RequestGraph extends ContentGraph<
             this.invalidNodeIds.add(id);
           }
         }
-        return true;
+        return {
+          didInvalidate: true,
+          invalidationsByPath: new Map(),
+        };
       }
 
       // sometimes mac os reports update events as create events.
@@ -1104,6 +1141,13 @@ export class RequestGraph extends ContentGraph<
           }
         }
       }
+
+      const invalidationsAfter = this.getInvalidNodeCount();
+      const invalidationsForEvent = invalidationsAfter - invalidationsBefore;
+      invalidationsByPath.set(
+        _path,
+        (invalidationsByPath.get(_path) ?? 0) + invalidationsForEvent,
+      );
     }
 
     if (getFeatureFlag('fixQuadraticCacheInvalidation')) {
@@ -1124,7 +1168,10 @@ export class RequestGraph extends ContentGraph<
       },
     });
 
-    return didInvalidate && this.invalidNodeIds.size > 0;
+    return {
+      didInvalidate,
+      invalidationsByPath,
+    };
   }
 
   hasCachedRequestChunk(index: number): boolean {
@@ -1138,6 +1185,13 @@ export class RequestGraph extends ContentGraph<
   removeCachedRequestChunkForNode(nodeId: number): void {
     this.cachedRequestChunks.delete(Math.floor(nodeId / this.nodesPerBlob));
   }
+
+  /**
+   * Returns the number of invalidated nodes in the graph.
+   */
+  getInvalidNodeCount(): number {
+    return this.invalidNodeIds.size;
+  }
 }
 
 export default class RequestTracker {
@@ -1261,7 +1315,13 @@ export default class RequestTracker {
     }
   }
 
-  respondToFSEvents(events: Array<Event>, threshold: number): Async<boolean> {
+  respondToFSEvents(
+    events: Array<Event>,
+    threshold: number,
+  ): Promise<{|
+    didInvalidate: boolean,
+    invalidationsByPath: Map<string, number>,
+  |}> {
     return this.graph.respondToFSEvents(events, this.options, threshold);
   }
 
@@ -1472,130 +1532,139 @@ export default class RequestTracker {
       }
     }
 
-    await runCacheImprovements(
-      async (cache) => {
-        await cache.getNativeRef().startWriteTransaction();
-      },
-      () => Promise.resolve(),
-    );
-
     let cacheKey = getCacheKey(this.options);
-    let requestGraphKey = `requestGraph-${cacheKey}`;
-    let snapshotKey = `snapshot-${cacheKey}`;
+    let requestGraphKey = getFeatureFlag('cachePerformanceImprovements')
+      ? `${cacheKey}/RequestGraph`
+      : `requestGraph-${cacheKey}`;
+    let snapshotKey = getFeatureFlag('cachePerformanceImprovements')
+      ? `${cacheKey}/snapshot`
+      : `snapshot-${cacheKey}`;
 
     if (this.options.shouldDisableCache) {
       return;
     }
 
     let total = 0;
-    report({
-      type: 'cache',
-      phase: 'start',
-      total,
-      size: this.graph.nodes.length,
-    });
+    await runCacheImprovements(
+      async (cache) => {
+        await cache.getNativeRef().startWriteTransaction();
+      },
+      () => Promise.resolve(),
+    );
+    try {
+      report({
+        type: 'cache',
+        phase: 'start',
+        total,
+        size: this.graph.nodes.length,
+      });
 
-    let serialisedGraph = this.graph.serialize();
+      let serialisedGraph = this.graph.serialize();
 
-    // Delete an existing request graph cache, to prevent invalid states
-    await this.options.cache.deleteLargeBlob(requestGraphKey);
+      // Delete an existing request graph cache, to prevent invalid states
+      await this.options.cache.deleteLargeBlob(requestGraphKey);
 
-    const serialiseAndSet = async (
-      key: string,
-      // $FlowFixMe serialise input is any type
-      contents: any,
-    ): Promise<void> => {
-      if (signal?.aborted) {
-        throw new Error('Serialization was aborted');
-      }
+      const serialiseAndSet = async (
+        key: string,
+        // $FlowFixMe serialise input is any type
+        contents: any,
+      ): Promise<void> => {
+        if (signal?.aborted) {
+          throw new Error('Serialization was aborted');
+        }
 
-      await runCacheImprovements(
-        (cache) => {
-          instrument(`cache.put(${key})`, () => {
-            cache.getNativeRef().putNoConfirm(key, serialize(contents));
-          });
-          return Promise.resolve();
-        },
-        async () => {
-          await this.options.cache.setLargeBlob(
-            key,
-            serialize(contents),
-            signal
-              ? {
-                  signal: signal,
-                }
-              : undefined,
-          );
-        },
-      );
+        await runCacheImprovements(
+          (cache) => {
+            instrument(
+              `RequestTracker::writeToCache::cache.put(${key})`,
+              () => {
+                cache.getNativeRef().putNoConfirm(key, serialize(contents));
+              },
+            );
+            return Promise.resolve();
+          },
+          async () => {
+            await this.options.cache.setLargeBlob(
+              key,
+              serialize(contents),
+              signal
+                ? {
+                    signal: signal,
+                  }
+                : undefined,
+            );
+          },
+        );
 
-      total += 1;
+        total += 1;
 
-      report({
-        type: 'cache',
-        phase: 'write',
-        total,
-        size: this.graph.nodes.length,
-      });
-    };
+        report({
+          type: 'cache',
+          phase: 'write',
+          total,
+          size: this.graph.nodes.length,
+        });
+      };
 
-    let queue = new PromiseQueue({
-      maxConcurrent: 32,
-    });
+      let queue = new PromiseQueue({
+        maxConcurrent: 32,
+      });
 
-    // Preallocating a sparse array is faster than pushing when N is high enough
-    let cacheableNodes = new Array(serialisedGraph.nodes.length);
-    for (let i = 0; i < serialisedGraph.nodes.length; i += 1) {
-      let node = serialisedGraph.nodes[i];
+      // Preallocating a sparse array is faster than pushing when N is high enough
+      let cacheableNodes = new Array(serialisedGraph.nodes.length);
+      for (let i = 0; i < serialisedGraph.nodes.length; i += 1) {
+        let node = serialisedGraph.nodes[i];
 
-      let resultCacheKey = node?.resultCacheKey;
-      if (
-        node?.type === REQUEST &&
-        resultCacheKey != null &&
-        node?.result != null
-      ) {
-        queue.add(() => serialiseAndSet(resultCacheKey, node.result));
+        let resultCacheKey = node?.resultCacheKey;
+        if (
+          node?.type === REQUEST &&
+          resultCacheKey != null &&
+          node?.result != null
+        ) {
+          queue.add(() => serialiseAndSet(resultCacheKey, node.result));
 
-        // eslint-disable-next-line no-unused-vars
-        let {result: _, ...newNode} = node;
-        cacheableNodes[i] = newNode;
-      } else {
-        cacheableNodes[i] = node;
+          // eslint-disable-next-line no-unused-vars
+          let {result: _, ...newNode} = node;
+          cacheableNodes[i] = newNode;
+        } else {
+          cacheableNodes[i] = node;
+        }
       }
-    }
 
-    let nodeCountsPerBlob = [];
+      let nodeCountsPerBlob = [];
 
-    for (
-      let i = 0;
-      i * this.graph.nodesPerBlob < cacheableNodes.length;
-      i += 1
-    ) {
-      let nodesStartIndex = i * this.graph.nodesPerBlob;
-      let nodesEndIndex = Math.min(
-        (i + 1) * this.graph.nodesPerBlob,
-        cacheableNodes.length,
-      );
+      for (
+        let i = 0;
+        i * this.graph.nodesPerBlob < cacheableNodes.length;
+        i += 1
+      ) {
+        let nodesStartIndex = i * this.graph.nodesPerBlob;
+        let nodesEndIndex = Math.min(
+          (i + 1) * this.graph.nodesPerBlob,
+          cacheableNodes.length,
+        );
 
-      nodeCountsPerBlob.push(nodesEndIndex - nodesStartIndex);
+        nodeCountsPerBlob.push(nodesEndIndex - nodesStartIndex);
 
-      if (!this.graph.hasCachedRequestChunk(i)) {
-        // We assume the request graph nodes are immutable and won't change
-        let nodesToCache = cacheableNodes.slice(nodesStartIndex, nodesEndIndex);
+        if (!this.graph.hasCachedRequestChunk(i)) {
+          // We assume the request graph nodes are immutable and won't change
+          let nodesToCache = cacheableNodes.slice(
+            nodesStartIndex,
+            nodesEndIndex,
+          );
 
-        queue.add(() =>
-          serialiseAndSet(
-            getRequestGraphNodeKey(i, cacheKey),
-            nodesToCache,
-          ).then(() => {
-            // Succeeded in writing to disk, save that we have completed this chunk
-            this.graph.setCachedRequestChunk(i);
-          }),
-        );
+          queue.add(() =>
+            serialiseAndSet(
+              getRequestGraphNodeKey(i, cacheKey),
+              nodesToCache,
+            ).then(() => {
+              // Succeeded in writing to disk, save that we have completed this chunk
+              this.graph.setCachedRequestChunk(i);
+            }),
+          );
+        }
       }
-    }
 
-    try {
       await queue.run();
 
       // Set the request graph after the queue is flushed to avoid writing an invalid state
@@ -1607,7 +1676,7 @@ export default class RequestTracker {
 
       await runCacheImprovements(
         () =>
-          serialiseAndSet(`request_tracker:cache_metadata:${cacheKey}`, {
+          serialiseAndSet(`${cacheKey}/cache_metadata`, {
             version: ATLASPACK_VERSION,
             entries: this.options.entries,
             mode: this.options.mode,
@@ -1628,15 +1697,15 @@ export default class RequestTracker {
     } catch (err) {
       // If we have aborted, ignore the error and continue
       if (!signal?.aborted) throw err;
+    } finally {
+      await runCacheImprovements(
+        async (cache) => {
+          await cache.getNativeRef().commitWriteTransaction();
+        },
+        () => Promise.resolve(),
+      );
     }
 
-    await runCacheImprovements(
-      async (cache) => {
-        await cache.getNativeRef().commitWriteTransaction();
-      },
-      () => Promise.resolve(),
-    );
-
     report({type: 'cache', phase: 'end', total, size: this.graph.nodes.length});
   }
 
@@ -1668,6 +1737,18 @@ export function getWatcherOptions({
 }
 
 function getCacheKey(options) {
+  if (getFeatureFlag('cachePerformanceImprovements')) {
+    const hash = hashString(
+      `${ATLASPACK_VERSION}:${JSON.stringify(options.entries)}:${
+        options.mode
+      }:${options.shouldBuildLazily ? 'lazy' : 'eager'}:${
+        options.watchBackend ?? ''
+      }`,
+    );
+
+    return `RequestTracker/${ATLASPACK_VERSION}/${hash}`;
+  }
+
   return hashString(
     `${ATLASPACK_VERSION}:${JSON.stringify(options.entries)}:${options.mode}:${
       options.shouldBuildLazily ? 'lazy' : 'eager'
@@ -1676,6 +1757,10 @@ function getCacheKey(options) {
 }
 
 function getRequestGraphNodeKey(index: number, cacheKey: string) {
+  if (getFeatureFlag('cachePerformanceImprovements')) {
+    return `${cacheKey}/RequestGraph/nodes/${index}`;
+  }
+
   return `requestGraph-nodes-${index}-${cacheKey}`;
 }
 
@@ -1687,9 +1772,15 @@ export async function readAndDeserializeRequestGraph(
   let bufferLength = 0;
 
   const getAndDeserialize = async (key: string) => {
-    let buffer = await cache.getLargeBlob(key);
-    bufferLength += Buffer.byteLength(buffer);
-    return deserialize(buffer);
+    if (getFeatureFlag('cachePerformanceImprovements')) {
+      const buffer = await cache.getBlob(key);
+      bufferLength += Buffer.byteLength(buffer);
+      return deserialize(buffer);
+    } else {
+      const buffer = await cache.getLargeBlob(key);
+      bufferLength += Buffer.byteLength(buffer);
+      return deserialize(buffer);
+    }
   };
 
   let serializedRequestGraph = await getAndDeserialize(requestGraphKey);
@@ -1722,21 +1813,41 @@ async function loadRequestGraph(options): Async<RequestGraph> {
   }
 
   let cacheKey = getCacheKey(options);
-  let requestGraphKey = `requestGraph-${cacheKey}`;
+  let requestGraphKey = getFeatureFlag('cachePerformanceImprovements')
+    ? `${cacheKey}/RequestGraph`
+    : `requestGraph-${cacheKey}`;
+
   let timeout;
-  const snapshotKey = `snapshot-${cacheKey}`;
+  const snapshotKey = getFeatureFlag('cachePerformanceImprovements')
+    ? `${cacheKey}/snapshot`
+    : `snapshot-${cacheKey}`;
   const snapshotPath = path.join(options.cacheDir, snapshotKey + '.txt');
 
+  const commonMeta = {
+    cacheKey,
+    snapshotKey,
+    cacheKeyOptions: {
+      version: ATLASPACK_VERSION,
+      entries: options.entries,
+      mode: options.mode,
+      shouldBuildLazily: options.shouldBuildLazily,
+      watchBackend: options.watchBackend,
+    },
+  };
+
   logger.verbose({
     origin: '@atlaspack/core',
     message: 'Loading request graph',
     meta: {
-      cacheKey,
-      snapshotKey,
+      ...commonMeta,
     },
   });
 
-  if (await options.cache.hasLargeBlob(requestGraphKey)) {
+  const hasRequestGraphInCache = getFeatureFlag('cachePerformanceImprovements')
+    ? await options.cache.has(requestGraphKey)
+    : await options.cache.hasLargeBlob(requestGraphKey);
+
+  if (hasRequestGraphInCache) {
     try {
       let {requestGraph} = await readAndDeserializeRequestGraph(
         options.cache,
@@ -1767,23 +1878,36 @@ async function loadRequestGraph(options): Async<RequestGraph> {
         origin: '@atlaspack/core',
         message: `File system event count: ${events.length}`,
         meta: {
+          ...commonMeta,
           trackableEvent: 'watcher_events_count',
           watcherEventCount: events.length,
           duration: Date.now() - startTime,
         },
       });
 
-      requestGraph.invalidateUnpredictableNodes();
-      requestGraph.invalidateOnBuildNodes();
-      requestGraph.invalidateEnvNodes(options.env);
-      requestGraph.invalidateOptionNodes(options);
+      if (getFeatureFlag('verboseRequestInvalidationStats')) {
+        const invalidationStats = await invalidateRequestGraph(
+          requestGraph,
+          options,
+          events,
+        );
+
+        logger.verbose({
+          origin: '@atlaspack/core',
+          message: 'Request track loaded from cache',
+          meta: {
+            ...commonMeta,
+            trackableEvent: 'request_tracker_cache_key_hit',
+            invalidationStats,
+          },
+        });
+      } else {
+        requestGraph.invalidateUnpredictableNodes();
+        requestGraph.invalidateOnBuildNodes();
+        requestGraph.invalidateEnvNodes(options.env);
+        requestGraph.invalidateOptionNodes(options);
+      }
 
-      await requestGraph.respondToFSEvents(
-        options.unstableFileInvalidations || events,
-        options,
-        10000,
-        true,
-      );
       return requestGraph;
     } catch (e) {
       // Prevent logging fs events took too long warning
@@ -1800,13 +1924,227 @@ async function loadRequestGraph(options): Async<RequestGraph> {
     message:
       'Cache entry for request tracker was not found, initializing a clean cache.',
     meta: {
-      cacheKey,
-      snapshotKey,
+      ...commonMeta,
+      trackableEvent: 'request_tracker_cache_key_miss',
     },
   });
   return new RequestGraph();
 }
 
+/**
+ * A wrapper around an invalidation type / method
+ */
+type InvalidationFn = {|
+  key: string,
+  fn: () =>
+    | InvalidationDetail
+    | Promise<InvalidationDetail>
+    | void
+    | Promise<void>,
+|};
+
+type InvalidationStats = {|
+  /**
+   * Total number of request graph nodes
+   */
+  nodeCount: number,
+  /**
+   * Number of requests in RequestGraph
+   */
+  requestCount: number,
+  /**
+   * Number of nodes that have been invalidated.
+   */
+  invalidatedCount: number,
+  /**
+   * Percentage of requests that have been invalidated
+   */
+  requestInvalidationRatio: number,
+  /**
+   * Percentage of nodes that have been invalidated
+   */
+  nodeInvalidationRatio: number,
+  /**
+   * Details for each invalidation type
+   */
+  invalidations: InvalidationFnStats[],
+|};
+
+/**
+ * Details about an invalidation.
+ *
+ * If this is a fs events invalidation, this key will contain statistics about invalidations
+ * by path.
+ *
+ * If this is a env or option invalidation, this key will contain the list of changed environment
+ * variables or options.
+ */
+type InvalidationDetail = string[] | FSInvalidationStats;
+
+/**
+ * Number of invalidations for a given file-system event.
+ */
+type FSInvalidation = {|
+  path: string,
+  count: number,
+|};
+
+type FSInvalidationStats = {|
+  /**
+   * This list will be sorted by the number of nodes invalidated and only the top 10 will be
+   * included.
+   */
+  biggestInvalidations: FSInvalidation[],
+|};
+
+/**
+ * Information about a certain cache invalidation type.
+ */
+type InvalidationFnStats = {|
+  /**
+   * Invalidation type, one of:
+   *
+   * - unpredictable
+   * - onBuild
+   * - env
+   * - option
+   * - fsEvents
+   */
+  key: string,
+  /**
+   * Number of invalidated nodes coming from this invalidation type.
+   */
+  count: number,
+  /**
+   * If this is a env or option invalidation, this key will contain the list of changed values.
+   *
+   * If this is a fs events invalidation, this key will contain statistics about invalidations
+   */
+  detail: null | InvalidationDetail,
+  /**
+   * Time in milliseconds it took to run the invalidation.
+   */
+  duration: number,
+|};
+
+/**
+ * Respond to unpredictable, build, environment changes, option changes and file-system events
+ * invalidating RequestGraph nodes.
+ *
+ * Returns the count of nodes invalidated by each invalidation type.
+ */
+export async function invalidateRequestGraph(
+  requestGraph: RequestGraph,
+  options: AtlaspackOptions,
+  events: Event[],
+): Promise<InvalidationStats> {
+  const invalidationFns: InvalidationFn[] = [
+    {
+      key: 'unpredictable',
+      fn: () => requestGraph.invalidateUnpredictableNodes(),
+    },
+    {
+      key: 'onBuild',
+      fn: () => requestGraph.invalidateOnBuildNodes(),
+    },
+    {
+      key: 'env',
+      fn: () => requestGraph.invalidateEnvNodes(options.env),
+    },
+    {
+      key: 'option',
+      fn: () => requestGraph.invalidateOptionNodes(options),
+    },
+    {
+      key: 'fsEvents',
+      fn: () => invalidateRequestGraphFSEvents(requestGraph, options, events),
+    },
+  ];
+
+  const invalidations = [];
+  for (const invalidation of invalidationFns) {
+    invalidations.push(await runInvalidation(requestGraph, invalidation));
+  }
+  const invalidatedCount = invalidations.reduce(
+    (acc, invalidation) => acc + invalidation.count,
+    0,
+  );
+  const requestCount = requestGraph.nodes.reduce(
+    (acc, node) => acc + (node?.type === REQUEST ? 1 : 0),
+    0,
+  );
+  const nodeCount = requestGraph.nodes.length;
+  const nodeInvalidationRatio = invalidatedCount / nodeCount;
+  const requestInvalidationRatio = invalidatedCount / requestCount;
+
+  return {
+    invalidations,
+    nodeCount,
+    requestCount,
+    invalidatedCount,
+    nodeInvalidationRatio,
+    requestInvalidationRatio,
+  };
+}
+
+interface InvalidateRequestGraphFSEventsInput {
+  respondToFSEvents(
+    events: Event[],
+    options: AtlaspackOptions,
+    timeout: number,
+    shouldLog: boolean,
+  ): Promise<{invalidationsByPath: Map<string, number>, ...}>;
+}
+
+/**
+ * Invalidate the request graph based on file-system events.
+ *
+ * Returns statistics about the invalidations.
+ */
+export async function invalidateRequestGraphFSEvents(
+  requestGraph: InvalidateRequestGraphFSEventsInput,
+  options: AtlaspackOptions,
+  events: Event[],
+): Promise<FSInvalidationStats> {
+  const {invalidationsByPath} = await requestGraph.respondToFSEvents(
+    options.unstableFileInvalidations || events,
+    options,
+    10000,
+    true,
+  );
+  const biggestInvalidations =
+    getBiggestFSEventsInvalidations(invalidationsByPath);
+
+  return {
+    biggestInvalidations,
+  };
+}
+
+interface RunInvalidationInput {
+  getInvalidNodeCount(): number;
+}
+
+/**
+ * Runs an invalidation function and reports metrics.
+ */
+export async function runInvalidation(
+  requestGraph: RunInvalidationInput,
+  invalidationFn: InvalidationFn,
+): Promise<InvalidationFnStats> {
+  const start = performance.now();
+  const startInvalidationCount = requestGraph.getInvalidNodeCount();
+  const result = await invalidationFn.fn();
+  const count = requestGraph.getInvalidNodeCount() - startInvalidationCount;
+  const duration = performance.now() - start;
+
+  return {
+    key: invalidationFn.key,
+    count,
+    detail: result ?? null,
+    duration,
+  };
+}
+
 function logErrorOnBailout(
   options: AtlaspackOptions,
   snapshotPath: string,
@@ -1858,3 +2196,19 @@ export function cleanUpOrphans<N, E: number>(graph: Graph<N, E>): NodeId[] {
 
   return removedNodeIds;
 }
+
+/**
+ * Returns paths that invalidated the most nodes
+ */
+export function getBiggestFSEventsInvalidations(
+  invalidationsByPath: Map<string, number>,
+  limit: number = 10,
+): Array<FSInvalidation> {
+  const invalidations = [];
+  for (const [path, count] of invalidationsByPath) {
+    invalidations.push({path, count});
+  }
+  invalidations.sort((a, b) => b.count - a.count);
+
+  return invalidations.slice(0, limit);
+}