lighthouse 11.6.0-dev.20240306 → 11.6.0-dev.20240307

package/core/computed/load-simulator.d.ts

@@ -1,5 +1,4 @@
 export { LoadSimulatorComputed as LoadSimulator };
-export type SimulationOptions = import('../../types/internal/lantern.js').Lantern.Simulation.Options;
 declare const LoadSimulatorComputed: typeof LoadSimulator & {
     request: (dependencies: {
         devtoolsLog: import("../index.js").DevtoolsLog;
@@ -8,7 +7,6 @@ declare const LoadSimulatorComputed: typeof LoadSimulator & {
         computedCache: Map<string, import("../lib/arbitrary-equality-map.js").ArbitraryEqualityMap>;
     }>) => Promise<Simulator<any>>;
 };
-/** @typedef {import('../../types/internal/lantern.js').Lantern.Simulation.Options} SimulationOptions */
 declare class LoadSimulator {
     /**
      * @param {{devtoolsLog: LH.DevtoolsLog, settings: LH.Audit.Context['settings']}} data

package/core/computed/load-simulator.js

@@ -4,13 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import * as Lantern from '../lib/lantern/types/lantern.js';
 import {makeComputedArtifact} from './computed-artifact.js';
 import * as constants from '../config/constants.js';
 import {Simulator} from '../lib/lantern/simulator/simulator.js';
 import {NetworkAnalysis} from './network-analysis.js';
 
-/** @typedef {import('../../types/internal/lantern.js').Lantern.Simulation.Options} SimulationOptions */
-
 class LoadSimulator {
   /**
    * @param {{devtoolsLog: LH.DevtoolsLog, settings: LH.Audit.Context['settings']}} data
@@ -21,7 +20,7 @@ class LoadSimulator {
     const {throttlingMethod, throttling, precomputedLanternData} = data.settings;
     const networkAnalysis = await NetworkAnalysis.request(data.devtoolsLog, context);
 
-    /** @type {SimulationOptions} */
+    /** @type {Lantern.Simulation.Options} */
     const options = {
       additionalRttByOrigin: networkAnalysis.additionalRttByOrigin,
       serverResponseTimeByOrigin: networkAnalysis.serverResponseTimeByOrigin,

package/core/computed/metrics/lantern-first-contentful-paint.d.ts

@@ -77,6 +77,18 @@ declare class LanternFirstContentfulPaint extends LanternMetric {
          */
         additionalCpuNodesToTreatAsRenderBlocking?: ((arg0: CPUNode) => boolean) | undefined;
     }): Node;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getOptimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getPessimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
 }
 import { LanternMetric } from './lantern-metric.js';
 //# sourceMappingURL=lantern-first-contentful-paint.d.ts.map

package/core/computed/metrics/lantern-first-meaningful-paint.d.ts

@@ -7,6 +7,18 @@ declare const LanternFirstMeaningfulPaintComputed: typeof LanternFirstMeaningful
 };
 /** @typedef {import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>} Node */
 declare class LanternFirstMeaningfulPaint extends LanternMetric {
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getOptimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getPessimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
 }
 import { LanternMetric } from './lantern-metric.js';
 //# sourceMappingURL=lantern-first-meaningful-paint.d.ts.map

package/core/computed/metrics/lantern-interactive.d.ts

@@ -17,6 +17,12 @@ declare class LanternInteractive extends LanternMetric {
      * @return {Node}
      */
     static getPessimisticGraph(dependencyGraph: Node): Node;
+    /**
+     * @param {LH.Gatherer.Simulation.Result} simulationResult
+     * @param {import('../../lib/lantern/metric.js').Extras} extras
+     * @return {LH.Gatherer.Simulation.Result}
+     */
+    static getEstimateFromSimulation(simulationResult: LH.Gatherer.Simulation.Result, extras: import('../../lib/lantern/metric.js').Extras): LH.Gatherer.Simulation.Result;
     /**
      * @param {LH.Gatherer.Simulation.Result['nodeTimings']} nodeTimings
      * @return {number}

package/core/computed/metrics/lantern-interactive.js

@@ -63,7 +63,7 @@ class LanternInteractive extends LanternMetric {
 
   /**
    * @param {LH.Gatherer.Simulation.Result} simulationResult
-   * @param {import('./lantern-metric.js').Extras} extras
+   * @param {import('../../lib/lantern/metric.js').Extras} extras
    * @return {LH.Gatherer.Simulation.Result}
    */
   static getEstimateFromSimulation(simulationResult, extras) {

package/core/computed/metrics/lantern-largest-contentful-paint.d.ts

@@ -15,6 +15,18 @@ declare class LanternLargestContentfulPaint extends LanternMetric {
      * @return {boolean}
      */
     static isNotLowPriorityImageNode(node: Node): boolean;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getOptimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getPessimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
     /**
      * @param {LH.Gatherer.Simulation.Result} simulationResult
      * @return {LH.Gatherer.Simulation.Result}

package/core/computed/metrics/lantern-max-potential-fid.d.ts

@@ -17,6 +17,12 @@ declare class LanternMaxPotentialFID extends LanternMetric {
      * @return {Node}
      */
     static getPessimisticGraph(dependencyGraph: Node): Node;
+    /**
+     * @param {LH.Gatherer.Simulation.Result} simulation
+     * @param {import('../../lib/lantern/metric.js').Extras} extras
+     * @return {LH.Gatherer.Simulation.Result}
+     */
+    static getEstimateFromSimulation(simulation: LH.Gatherer.Simulation.Result, extras: import('../../lib/lantern/metric.js').Extras): LH.Gatherer.Simulation.Result;
     /**
      * @param {LH.Gatherer.Simulation.Result['nodeTimings']} nodeTimings
      * @param {number} fcpTimeInMs

package/core/computed/metrics/lantern-max-potential-fid.js

@@ -41,7 +41,7 @@ class LanternMaxPotentialFID extends LanternMetric {
 
   /**
    * @param {LH.Gatherer.Simulation.Result} simulation
-   * @param {import('./lantern-metric.js').Extras} extras
+   * @param {import('../../lib/lantern/metric.js').Extras} extras
    * @return {LH.Gatherer.Simulation.Result}
    */
   static getEstimateFromSimulation(simulation, extras) {

package/core/computed/metrics/lantern-metric.d.ts

@@ -1,65 +1,6 @@
-export type Node = import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>;
-export type NetworkNode = import('../../lib/lantern/network-node.js').NetworkNode<LH.Artifacts.NetworkRequest>;
-export type Simulator = import('../../lib/lantern/simulator/simulator.js').Simulator;
-export type Extras = {
-    optimistic: boolean;
-    fcpResult?: LH.Artifacts.LanternMetric | undefined;
-    fmpResult?: LH.Artifacts.LanternMetric | undefined;
-    interactiveResult?: LH.Artifacts.LanternMetric | undefined;
-    speedline?: {
-        speedIndex: number;
-    } | undefined;
-};
-/** @typedef {import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>} Node */
-/** @typedef {import('../../lib/lantern/network-node.js').NetworkNode<LH.Artifacts.NetworkRequest>} NetworkNode */
-/** @typedef {import('../../lib/lantern/simulator/simulator.js').Simulator} Simulator */
-/**
- * @typedef Extras
- * @property {boolean} optimistic
- * @property {LH.Artifacts.LanternMetric=} fcpResult
- * @property {LH.Artifacts.LanternMetric=} fmpResult
- * @property {LH.Artifacts.LanternMetric=} interactiveResult
- * @property {{speedIndex: number}=} speedline
- */
-export class LanternMetric {
-    /**
-     * @param {Node} dependencyGraph
-     * @param {function(NetworkNode):boolean=} treatNodeAsRenderBlocking
-     * @return {Set<string>}
-     */
-    static getScriptUrls(dependencyGraph: Node, treatNodeAsRenderBlocking?: ((arg0: NetworkNode) => boolean) | undefined): Set<string>;
-    /**
-     * @return {LH.Gatherer.Simulation.MetricCoefficients}
-     */
-    static get COEFFICIENTS(): import("../../../types/internal/lantern.js").Lantern.Simulation.MetricCoefficients;
-    /**
-     * Returns the coefficients, scaled by the throttling settings if needed by the metric.
-     * Some lantern metrics (speed-index) use components in their estimate that are not
-     * from the simulator. In this case, we need to adjust the coefficients as the target throttling
-     * settings change.
-     *
-     * @param {number} rttMs
-     * @return {LH.Gatherer.Simulation.MetricCoefficients}
-     */
-    static getScaledCoefficients(rttMs: number): LH.Gatherer.Simulation.MetricCoefficients;
-    /**
-     * @param {Node} dependencyGraph
-     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
-     * @return {Node}
-     */
-    static getOptimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
-    /**
-     * @param {Node} dependencyGraph
-     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
-     * @return {Node}
-     */
-    static getPessimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
-    /**
-     * @param {LH.Gatherer.Simulation.Result} simulationResult
-     * @param {Extras} extras
-     * @return {LH.Gatherer.Simulation.Result}
-     */
-    static getEstimateFromSimulation(simulationResult: LH.Gatherer.Simulation.Result, extras: Extras): LH.Gatherer.Simulation.Result;
+export type Extras = import('../../lib/lantern/metric.js').Extras;
+/** @typedef {import('../../lib/lantern/metric.js').Extras} Extras */
+export class LanternMetric extends Metric {
     /**
      * @param {LH.Artifacts.MetricComputationDataInput} data
      * @param {LH.Artifacts.ComputedContext} context
@@ -74,6 +15,5 @@ export class LanternMetric {
      */
     static compute_(data: LH.Artifacts.MetricComputationDataInput, context: LH.Artifacts.ComputedContext): Promise<LH.Artifacts.LanternMetric>;
 }
-import { NetworkRequest } from '../../lib/network-request.js';
-import { ProcessedNavigation } from '../processed-navigation.js';
+import { Metric } from '../../lib/lantern/metric.js';
 //# sourceMappingURL=lantern-metric.d.ts.map

package/core/computed/metrics/lantern-metric.js

@@ -4,93 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {BaseNode} from '../../lib/lantern/base-node.js';
-import {NetworkRequest} from '../../lib/network-request.js';
-import {ProcessedNavigation} from '../processed-navigation.js';
-import {PageDependencyGraph} from '../page-dependency-graph.js';
+import {Metric} from '../../lib/lantern/metric.js';
 import {LoadSimulator} from '../load-simulator.js';
+import {PageDependencyGraph} from '../page-dependency-graph.js';
+import {ProcessedNavigation} from '../processed-navigation.js';
 
-/** @typedef {import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>} Node */
-/** @typedef {import('../../lib/lantern/network-node.js').NetworkNode<LH.Artifacts.NetworkRequest>} NetworkNode */
-/** @typedef {import('../../lib/lantern/simulator/simulator.js').Simulator} Simulator */
-
-/**
- * @typedef Extras
- * @property {boolean} optimistic
- * @property {LH.Artifacts.LanternMetric=} fcpResult
- * @property {LH.Artifacts.LanternMetric=} fmpResult
- * @property {LH.Artifacts.LanternMetric=} interactiveResult
- * @property {{speedIndex: number}=} speedline
- */
-
-class LanternMetric {
-  /**
-   * @param {Node} dependencyGraph
-   * @param {function(NetworkNode):boolean=} treatNodeAsRenderBlocking
-   * @return {Set<string>}
-   */
-  static getScriptUrls(dependencyGraph, treatNodeAsRenderBlocking) {
-    /** @type {Set<string>} */
-    const scriptUrls = new Set();
-
-    dependencyGraph.traverse(node => {
-      if (node.type !== BaseNode.TYPES.NETWORK) return;
-      if (node.record.resourceType !== NetworkRequest.TYPES.Script) return;
-      if (treatNodeAsRenderBlocking?.(node)) {
-        scriptUrls.add(node.record.url);
-      }
-    });
-
-    return scriptUrls;
-  }
-
-  /**
-   * @return {LH.Gatherer.Simulation.MetricCoefficients}
-   */
-  static get COEFFICIENTS() {
-    throw new Error('COEFFICIENTS unimplemented!');
-  }
-
-  /**
-   * Returns the coefficients, scaled by the throttling settings if needed by the metric.
-   * Some lantern metrics (speed-index) use components in their estimate that are not
-   * from the simulator. In this case, we need to adjust the coefficients as the target throttling
-   * settings change.
-   *
-   * @param {number} rttMs
-   * @return {LH.Gatherer.Simulation.MetricCoefficients}
-   */
-  static getScaledCoefficients(rttMs) { // eslint-disable-line no-unused-vars
-    return this.COEFFICIENTS;
-  }
-
-  /**
-   * @param {Node} dependencyGraph
-   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
-   * @return {Node}
-   */
-  static getOptimisticGraph(dependencyGraph, processedNavigation) { // eslint-disable-line no-unused-vars
-    throw new Error('Optimistic graph unimplemented!');
-  }
-
-  /**
-   * @param {Node} dependencyGraph
-   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
-   * @return {Node}
-   */
-  static getPessimisticGraph(dependencyGraph, processedNavigation) { // eslint-disable-line no-unused-vars
-    throw new Error('Pessmistic graph unimplemented!');
-  }
-
-  /**
-   * @param {LH.Gatherer.Simulation.Result} simulationResult
-   * @param {Extras} extras
-   * @return {LH.Gatherer.Simulation.Result}
-   */
-  static getEstimateFromSimulation(simulationResult, extras) { // eslint-disable-line no-unused-vars
-    return simulationResult;
-  }
+/** @typedef {import('../../lib/lantern/metric.js').Extras} Extras */
 
+class LanternMetric extends Metric {
   /**
    * @param {LH.Artifacts.MetricComputationDataInput} data
    * @param {LH.Artifacts.ComputedContext} context
@@ -104,50 +25,11 @@ class LanternMetric {
       throw new Error(`Lantern metrics can only be computed on navigations`);
     }
 
-    const metricName = this.name.replace('Lantern', '');
     const graph = await PageDependencyGraph.request(data, context);
     const processedNavigation = await ProcessedNavigation.request(data.trace, context);
     const simulator = data.simulator || (await LoadSimulator.request(data, context));
 
-    const optimisticGraph = this.getOptimisticGraph(graph, processedNavigation);
-    const pessimisticGraph = this.getPessimisticGraph(graph, processedNavigation);
-
-    /** @type {{flexibleOrdering?: boolean, label?: string}} */
-    let simulateOptions = {label: `optimistic${metricName}`};
-    const optimisticSimulation = simulator.simulate(optimisticGraph, simulateOptions);
-
-    simulateOptions = {label: `optimisticFlex${metricName}`, flexibleOrdering: true};
-    const optimisticFlexSimulation = simulator.simulate(optimisticGraph, simulateOptions);
-
-    simulateOptions = {label: `pessimistic${metricName}`};
-    const pessimisticSimulation = simulator.simulate(pessimisticGraph, simulateOptions);
-
-    const optimisticEstimate = this.getEstimateFromSimulation(
-      optimisticSimulation.timeInMs < optimisticFlexSimulation.timeInMs ?
-        optimisticSimulation : optimisticFlexSimulation, {...extras, optimistic: true}
-    );
-
-    const pessimisticEstimate = this.getEstimateFromSimulation(
-      pessimisticSimulation,
-      {...extras, optimistic: false}
-    );
-
-    const coefficients = this.getScaledCoefficients(simulator.rtt);
-    // Estimates under 1s don't really follow the normal curve fit, minimize the impact of the intercept
-    const interceptMultiplier = coefficients.intercept > 0 ?
-      Math.min(1, optimisticEstimate.timeInMs / 1000) : 1;
-    const timing =
-      coefficients.intercept * interceptMultiplier +
-      coefficients.optimistic * optimisticEstimate.timeInMs +
-      coefficients.pessimistic * pessimisticEstimate.timeInMs;
-
-    return {
-      timing,
-      optimisticEstimate,
-      pessimisticEstimate,
-      optimisticGraph,
-      pessimisticGraph,
-    };
+    return this.compute({simulator, graph, processedNavigation}, extras);
   }
 
   /**

package/core/computed/metrics/lantern-speed-index.d.ts

@@ -17,6 +17,12 @@ declare class LanternSpeedIndex extends LanternMetric {
      * @return {Node}
      */
     static getPessimisticGraph(dependencyGraph: Node): Node;
+    /**
+     * @param {LH.Gatherer.Simulation.Result} simulationResult
+     * @param {import('../../lib/lantern/metric.js').Extras} extras
+     * @return {LH.Gatherer.Simulation.Result}
+     */
+    static getEstimateFromSimulation(simulationResult: LH.Gatherer.Simulation.Result, extras: import('../../lib/lantern/metric.js').Extras): LH.Gatherer.Simulation.Result;
     /**
      * Approximate speed index using layout events from the simulated node timings.
      * The layout-based speed index is the weighted average of the endTime of CPU nodes that contained

package/core/computed/metrics/lantern-speed-index.js

@@ -73,7 +73,7 @@ class LanternSpeedIndex extends LanternMetric {
 
   /**
    * @param {LH.Gatherer.Simulation.Result} simulationResult
-   * @param {import('./lantern-metric.js').Extras} extras
+   * @param {import('../../lib/lantern/metric.js').Extras} extras
    * @return {LH.Gatherer.Simulation.Result}
    */
   static getEstimateFromSimulation(simulationResult, extras) {

package/core/computed/metrics/lantern-total-blocking-time.d.ts

@@ -17,6 +17,12 @@ declare class LanternTotalBlockingTime extends LanternMetric {
      * @return {Node}
      */
     static getPessimisticGraph(dependencyGraph: Node): Node;
+    /**
+     * @param {LH.Gatherer.Simulation.Result} simulation
+     * @param {import('../../lib/lantern/metric.js').Extras} extras
+     * @return {LH.Gatherer.Simulation.Result}
+     */
+    static getEstimateFromSimulation(simulation: LH.Gatherer.Simulation.Result, extras: import('../../lib/lantern/metric.js').Extras): LH.Gatherer.Simulation.Result;
     /**
      * @param {LH.Gatherer.Simulation.Result['nodeTimings']} nodeTimings
      * @param {number} minDurationMs

package/core/computed/metrics/lantern-total-blocking-time.js

@@ -43,7 +43,7 @@ class LanternTotalBlockingTime extends LanternMetric {
 
   /**
    * @param {LH.Gatherer.Simulation.Result} simulation
-   * @param {import('./lantern-metric.js').Extras} extras
+   * @param {import('../../lib/lantern/metric.js').Extras} extras
    * @return {LH.Gatherer.Simulation.Result}
    */
   static getEstimateFromSimulation(simulation, extras) {

package/core/lib/lantern/metric.d.ts

@@ -0,0 +1,71 @@
+export type Node = import('./base-node.js').Node;
+export type NetworkNode = import('./network-node.js').NetworkNode;
+export type Simulator = import('./simulator/simulator.js').Simulator;
+export type Extras = {
+    optimistic: boolean;
+    fcpResult?: LH.Artifacts.LanternMetric | undefined;
+    fmpResult?: LH.Artifacts.LanternMetric | undefined;
+    interactiveResult?: LH.Artifacts.LanternMetric | undefined;
+    speedline?: {
+        speedIndex: number;
+    } | undefined;
+};
+/** @typedef {import('./base-node.js').Node} Node */
+/** @typedef {import('./network-node.js').NetworkNode} NetworkNode */
+/** @typedef {import('./simulator/simulator.js').Simulator} Simulator */
+/**
+ * @typedef Extras
+ * @property {boolean} optimistic
+ * @property {LH.Artifacts.LanternMetric=} fcpResult
+ * @property {LH.Artifacts.LanternMetric=} fmpResult
+ * @property {LH.Artifacts.LanternMetric=} interactiveResult
+ * @property {{speedIndex: number}=} speedline
+ */
+export class Metric {
+    /**
+     * @param {Node} dependencyGraph
+     * @param {function(NetworkNode):boolean=} treatNodeAsRenderBlocking
+     * @return {Set<string>}
+     */
+    static getScriptUrls(dependencyGraph: Node, treatNodeAsRenderBlocking?: ((arg0: NetworkNode) => boolean) | undefined): Set<string>;
+    /**
+     * @return {Lantern.Simulation.MetricCoefficients}
+     */
+    static get COEFFICIENTS(): Lantern.Simulation.MetricCoefficients;
+    /**
+     * Returns the coefficients, scaled by the throttling settings if needed by the metric.
+     * Some lantern metrics (speed-index) use components in their estimate that are not
+     * from the simulator. In this case, we need to adjust the coefficients as the target throttling
+     * settings change.
+     *
+     * @param {number} rttMs
+     * @return {Lantern.Simulation.MetricCoefficients}
+     */
+    static getScaledCoefficients(rttMs: number): Lantern.Simulation.MetricCoefficients;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getOptimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
+    /**
+     * @param {Node} dependencyGraph
+     * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+     * @return {Node}
+     */
+    static getPessimisticGraph(dependencyGraph: Node, processedNavigation: LH.Artifacts.ProcessedNavigation): Node;
+    /**
+     * @param {Lantern.Simulation.Result} simulationResult
+     * @param {Extras} extras
+     * @return {Lantern.Simulation.Result}
+     */
+    static getEstimateFromSimulation(simulationResult: Lantern.Simulation.Result, extras: Extras): Lantern.Simulation.Result;
+    /**
+     * @param {Lantern.Simulation.MetricComputationDataInput} data
+     * @param {Omit<Extras, 'optimistic'>=} extras
+     * @return {Promise<LH.Artifacts.LanternMetric>}
+     */
+    static compute(data: Lantern.Simulation.MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'> | undefined): Promise<LH.Artifacts.LanternMetric>;
+}
+import * as Lantern from './types/lantern.js';
+//# sourceMappingURL=metric.d.ts.map

package/core/lib/lantern/metric.js

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Lantern from './types/lantern.js';
+import {BaseNode} from '../../lib/lantern/base-node.js';
+import {NetworkRequest} from '../../lib/network-request.js';
+
+/** @typedef {import('./base-node.js').Node} Node */
+/** @typedef {import('./network-node.js').NetworkNode} NetworkNode */
+/** @typedef {import('./simulator/simulator.js').Simulator} Simulator */
+
+/**
+ * @typedef Extras
+ * @property {boolean} optimistic
+ * @property {LH.Artifacts.LanternMetric=} fcpResult
+ * @property {LH.Artifacts.LanternMetric=} fmpResult
+ * @property {LH.Artifacts.LanternMetric=} interactiveResult
+ * @property {{speedIndex: number}=} speedline
+ */
+
+class Metric {
+  /**
+   * @param {Node} dependencyGraph
+   * @param {function(NetworkNode):boolean=} treatNodeAsRenderBlocking
+   * @return {Set<string>}
+   */
+  static getScriptUrls(dependencyGraph, treatNodeAsRenderBlocking) {
+    /** @type {Set<string>} */
+    const scriptUrls = new Set();
+
+    dependencyGraph.traverse(node => {
+      if (node.type !== BaseNode.TYPES.NETWORK) return;
+      if (node.record.resourceType !== NetworkRequest.TYPES.Script) return;
+      if (treatNodeAsRenderBlocking?.(node)) {
+        scriptUrls.add(node.record.url);
+      }
+    });
+
+    return scriptUrls;
+  }
+
+  /**
+   * @return {Lantern.Simulation.MetricCoefficients}
+   */
+  static get COEFFICIENTS() {
+    throw new Error('COEFFICIENTS unimplemented!');
+  }
+
+  /**
+   * Returns the coefficients, scaled by the throttling settings if needed by the metric.
+   * Some lantern metrics (speed-index) use components in their estimate that are not
+   * from the simulator. In this case, we need to adjust the coefficients as the target throttling
+   * settings change.
+   *
+   * @param {number} rttMs
+   * @return {Lantern.Simulation.MetricCoefficients}
+   */
+  static getScaledCoefficients(rttMs) { // eslint-disable-line no-unused-vars
+    return this.COEFFICIENTS;
+  }
+
+  /**
+   * @param {Node} dependencyGraph
+   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+   * @return {Node}
+   */
+  static getOptimisticGraph(dependencyGraph, processedNavigation) { // eslint-disable-line no-unused-vars
+    throw new Error('Optimistic graph unimplemented!');
+  }
+
+  /**
+   * @param {Node} dependencyGraph
+   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+   * @return {Node}
+   */
+  static getPessimisticGraph(dependencyGraph, processedNavigation) { // eslint-disable-line no-unused-vars
+    throw new Error('Pessmistic graph unimplemented!');
+  }
+
+  /**
+   * @param {Lantern.Simulation.Result} simulationResult
+   * @param {Extras} extras
+   * @return {Lantern.Simulation.Result}
+   */
+  static getEstimateFromSimulation(simulationResult, extras) { // eslint-disable-line no-unused-vars
+    return simulationResult;
+  }
+
+  /**
+   * @param {Lantern.Simulation.MetricComputationDataInput} data
+   * @param {Omit<Extras, 'optimistic'>=} extras
+   * @return {Promise<LH.Artifacts.LanternMetric>}
+   */
+  static async compute(data, extras) {
+    const {simulator, graph, processedNavigation} = data;
+
+    const metricName = this.name.replace('Lantern', '');
+    const optimisticGraph = this.getOptimisticGraph(graph, processedNavigation);
+    const pessimisticGraph = this.getPessimisticGraph(graph, processedNavigation);
+
+    /** @type {{flexibleOrdering?: boolean, label?: string}} */
+    let simulateOptions = {label: `optimistic${metricName}`};
+    const optimisticSimulation = simulator.simulate(optimisticGraph, simulateOptions);
+
+    simulateOptions = {label: `optimisticFlex${metricName}`, flexibleOrdering: true};
+    const optimisticFlexSimulation = simulator.simulate(optimisticGraph, simulateOptions);
+
+    simulateOptions = {label: `pessimistic${metricName}`};
+    const pessimisticSimulation = simulator.simulate(pessimisticGraph, simulateOptions);
+
+    const optimisticEstimate = this.getEstimateFromSimulation(
+      optimisticSimulation.timeInMs < optimisticFlexSimulation.timeInMs ?
+        optimisticSimulation : optimisticFlexSimulation, {...extras, optimistic: true}
+    );
+
+    const pessimisticEstimate = this.getEstimateFromSimulation(
+      pessimisticSimulation,
+      {...extras, optimistic: false}
+    );
+
+    const coefficients = this.getScaledCoefficients(simulator.rtt);
+    // Estimates under 1s don't really follow the normal curve fit, minimize the impact of the intercept
+    const interceptMultiplier = coefficients.intercept > 0 ?
+      Math.min(1, optimisticEstimate.timeInMs / 1000) : 1;
+    const timing =
+      coefficients.intercept * interceptMultiplier +
+      coefficients.optimistic * optimisticEstimate.timeInMs +
+      coefficients.pessimistic * pessimisticEstimate.timeInMs;
+
+    return {
+      timing,
+      optimisticEstimate,
+      pessimisticEstimate,
+      optimisticGraph,
+      pessimisticGraph,
+    };
+  }
+}
+
+export {Metric};