lighthouse 11.6.0 → 11.7.0

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};

package/core/lib/{dependency-graph → lantern}/network-node.d.ts

@@ -1,15 +1,23 @@
-export class NetworkNode extends BaseNode {
+/**
+ * @template [T=any]
+ * @extends {BaseNode<T>}
+ */
+export class NetworkNode<T = any> extends BaseNode<T> {
     /**
-     * @param {LH.Artifacts.NetworkRequest} networkRecord
+     * @param {Lantern.NetworkRequest<T>} networkRequest
      */
-    constructor(networkRecord: LH.Artifacts.NetworkRequest);
+    constructor(networkRequest: Lantern.NetworkRequest<T>);
     /** @private */
-    private _record;
+    private _request;
     get type(): "network";
     /**
-     * @return {LH.Artifacts.NetworkRequest}
+     * @return {Readonly<T>}
      */
-    get record(): NetworkRequest;
+    get record(): Readonly<T>;
+    /**
+     * @return {Lantern.NetworkRequest<T>}
+     */
+    get request(): Lantern.NetworkRequest<T>;
     /**
      * @return {string}
      */
@@ -33,11 +41,10 @@ export class NetworkNode extends BaseNode {
      */
     hasRenderBlockingPriority(): boolean;
     /**
-     * @return {NetworkNode}
+     * @return {NetworkNode<T>}
      */
-    cloneWithoutRelationships(): NetworkNode;
+    cloneWithoutRelationships(): NetworkNode<T>;
 }
 import { BaseNode } from './base-node.js';
-import { NetworkRequest } from '../network-request.js';
-import * as LH from '../../../types/lh.js';
+import * as Lantern from './types/lantern.js';
 //# sourceMappingURL=network-node.d.ts.map

package/core/lib/lantern/network-node.js

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Lantern from './types/lantern.js';
+import {NetworkRequestTypes} from './lantern.js';
+import {BaseNode} from './base-node.js';
+// TODO(15841): bring impl of isNonNetworkRequest inside lantern and remove this.
+import UrlUtils from '../url-utils.js';
+
+/**
+ * @template [T=any]
+ * @extends {BaseNode<T>}
+ */
+class NetworkNode extends BaseNode {
+  /**
+   * @param {Lantern.NetworkRequest<T>} networkRequest
+   */
+  constructor(networkRequest) {
+    super(networkRequest.requestId);
+    /** @private */
+    this._request = networkRequest;
+  }
+
+  get type() {
+    return BaseNode.TYPES.NETWORK;
+  }
+
+  /**
+   * @return {number}
+   */
+  get startTime() {
+    return this._request.rendererStartTime * 1000;
+  }
+
+  /**
+   * @return {number}
+   */
+  get endTime() {
+    return this._request.networkEndTime * 1000;
+  }
+
+  /**
+   * @return {Readonly<T>}
+   */
+  get record() {
+    return /** @type {Required<T>} */ (this._request.record);
+  }
+
+  /**
+   * @return {Lantern.NetworkRequest<T>}
+   */
+  get request() {
+    return this._request;
+  }
+
+  /**
+   * @return {string}
+   */
+  get initiatorType() {
+    return this._request.initiator && this._request.initiator.type;
+  }
+
+  /**
+   * @return {boolean}
+   */
+  get fromDiskCache() {
+    return !!this._request.fromDiskCache;
+  }
+
+  /**
+   * @return {boolean}
+   */
+  get isNonNetworkProtocol() {
+    // The 'protocol' field in devtools a string more like a `scheme`
+    return UrlUtils.isNonNetworkProtocol(this.request.protocol) ||
+      // But `protocol` can fail to be populated if the request fails, so fallback to scheme.
+      UrlUtils.isNonNetworkProtocol(this.request.parsedURL.scheme);
+  }
+
+  /**
+   * Returns whether this network record can be downloaded without a TCP connection.
+   * During simulation we treat data coming in over a network connection separately from on-device data.
+   * @return {boolean}
+   */
+  get isConnectionless() {
+    return this.fromDiskCache || this.isNonNetworkProtocol;
+  }
+
+  /**
+   * @return {boolean}
+   */
+  hasRenderBlockingPriority() {
+    const priority = this._request.priority;
+    const isScript = this._request.resourceType === NetworkRequestTypes.Script;
+    const isDocument = this._request.resourceType === NetworkRequestTypes.Document;
+    const isBlockingScript = priority === 'High' && isScript;
+    const isBlockingHtmlImport = priority === 'High' && isDocument;
+    return priority === 'VeryHigh' || isBlockingScript || isBlockingHtmlImport;
+  }
+
+  /**
+   * @return {NetworkNode<T>}
+   */
+  cloneWithoutRelationships() {
+    const node = new NetworkNode(this._request);
+    node.setIsMainDocument(this._isMainDocument);
+    return node;
+  }
+}
+
+export {NetworkNode};

package/core/lib/lantern/page-dependency-graph.d.ts

@@ -0,0 +1,58 @@
+export type Node = import('./base-node.js').Node;
+export type URLArtifact = Omit<LH.Artifacts['URL'], 'finalDisplayedUrl'>;
+export type NetworkNodeOutput = {
+    nodes: Array<NetworkNode>;
+    idToNodeMap: Map<string, NetworkNode>;
+    urlToNodeMap: Map<string, Array<NetworkNode>>;
+    frameIdToNodeMap: Map<string, NetworkNode | null>;
+};
+export class PageDependencyGraph {
+    /**
+     * @param {Lantern.NetworkRequest} record
+     * @return {Array<string>}
+     */
+    static getNetworkInitiators(record: Lantern.NetworkRequest): Array<string>;
+    /**
+     * @param {Array<Lantern.NetworkRequest>} networkRecords
+     * @return {NetworkNodeOutput}
+     */
+    static getNetworkNodeOutput(networkRecords: Array<Lantern.NetworkRequest>): NetworkNodeOutput;
+    /**
+     * @param {LH.Artifacts.ProcessedTrace} processedTrace
+     * @return {Array<CPUNode>}
+     */
+    static getCPUNodes({ mainThreadEvents }: LH.Artifacts.ProcessedTrace): Array<CPUNode>;
+    /**
+     * @param {NetworkNode} rootNode
+     * @param {NetworkNodeOutput} networkNodeOutput
+     */
+    static linkNetworkNodes(rootNode: NetworkNode, networkNodeOutput: NetworkNodeOutput): void;
+    /**
+     * @param {Node} rootNode
+     * @param {NetworkNodeOutput} networkNodeOutput
+     * @param {Array<CPUNode>} cpuNodes
+     */
+    static linkCPUNodes(rootNode: Node, networkNodeOutput: NetworkNodeOutput, cpuNodes: Array<CPUNode>): void;
+    /**
+     * Removes the given node from the graph, but retains all paths between its dependencies and
+     * dependents.
+     * @param {Node} node
+     */
+    static _pruneNode(node: Node): void;
+    /**
+     * @param {LH.Artifacts.ProcessedTrace} processedTrace
+     * @param {Array<Lantern.NetworkRequest>} networkRecords
+     * @param {URLArtifact} URL
+     * @return {Node}
+     */
+    static createGraph(processedTrace: LH.Artifacts.ProcessedTrace, networkRecords: Array<Lantern.NetworkRequest>, URL: URLArtifact): Node;
+    /**
+     *
+     * @param {Node} rootNode
+     */
+    static printGraph(rootNode: Node, widthInCharacters?: number): void;
+}
+import { NetworkNode } from './network-node.js';
+import * as Lantern from './types/lantern.js';
+import { CPUNode } from './cpu-node.js';
+//# sourceMappingURL=page-dependency-graph.d.ts.map