lighthouse 9.5.0-dev.20230118 → 9.5.0-dev.20230119

package/core/lib/rect-helpers.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+/**
+ * @param {LH.Artifacts.Rect} rect
+ * @param {{x:number, y:number}} point
+ */
+export function rectContainsPoint(rect: LH.Artifacts.Rect, { x, y }: {
+    x: number;
+    y: number;
+}): boolean;
+/**
+ * Returns whether rect2 is contained entirely within rect1;
+ * @param {LH.Artifacts.Rect} rect1
+ * @param {LH.Artifacts.Rect} rect2
+ * @return {boolean}
+ */
+export function rectContains(rect1: LH.Artifacts.Rect, rect2: LH.Artifacts.Rect): boolean;
+/**
+ * @param {{left:number, top:number, right:number, bottom: number}} rect
+ * @return {LH.Artifacts.Rect}
+ */
+export function addRectWidthAndHeight({ left, top, right, bottom }: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}): LH.Artifacts.Rect;
+/**
+ * @param {{x:number, y:number, width:number, height: number}} rect
+ * @return {LH.Artifacts.Rect}
+ */
+export function addRectTopAndBottom({ x, y, width, height }: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): LH.Artifacts.Rect;
+/**
+ * @param {LH.Artifacts.Rect} rect1
+ * @param {LH.Artifacts.Rect} rect2
+ */
+export function getRectOverlapArea(rect1: LH.Artifacts.Rect, rect2: LH.Artifacts.Rect): number;
+/**
+ * @param {LH.Artifacts.Rect} rect
+ * @param {number} centerRectSize
+ */
+export function getRectAtCenter(rect: LH.Artifacts.Rect, centerRectSize: number): import("../../types/lhr/audit-details").default.Rect;
+/**
+ * @param {LH.Artifacts.Rect[]} rects
+ */
+export function getLargestRect(rects: LH.Artifacts.Rect[]): import("../../types/lhr/audit-details").default.Rect;
+/**
+ * @param {LH.Artifacts.Rect} rect
+ */
+export function getRectArea(rect: LH.Artifacts.Rect): number;
+/**
+ * @param {LH.Artifacts.Rect} rect
+ */
+export function getRectCenterPoint(rect: LH.Artifacts.Rect): {
+    x: number;
+    y: number;
+};
+/**
+ * @param {LH.Artifacts.Rect[]} rects
+ */
+export function getBoundingRect(rects: LH.Artifacts.Rect[]): import("../../types/lhr/audit-details").default.Rect;
+/**
+ * Returns a bounding rect for all the passed in rects, with padded with half of
+ * `padding` on all sides.
+ * @param {LH.Artifacts.Rect[]} rects
+ * @param {number} padding
+ * @return {LH.Artifacts.Rect}
+ */
+export function getBoundingRectWithPadding(rects: LH.Artifacts.Rect[], padding: number): LH.Artifacts.Rect;
+/**
+ * @param {LH.Artifacts.Rect} rectA
+ * @param {LH.Artifacts.Rect} rectB
+ * @return {boolean}
+ */
+export function rectsTouchOrOverlap(rectA: LH.Artifacts.Rect, rectB: LH.Artifacts.Rect): boolean;
+/**
+ *
+ * @param {LH.Artifacts.Rect[]} rectListA
+ * @param {LH.Artifacts.Rect[]} rectListB
+ */
+export function allRectsContainedWithinEachOther(rectListA: LH.Artifacts.Rect[], rectListB: LH.Artifacts.Rect[]): boolean;
+/**
+ * @param {LH.Artifacts.Rect[]} rects
+ * @return {LH.Artifacts.Rect[]}
+ */
+export function filterOutRectsContainedByOthers(rects: LH.Artifacts.Rect[]): LH.Artifacts.Rect[];
+/**
+ * @param {LH.Artifacts.Rect[]} rects
+ * @return {LH.Artifacts.Rect[]}
+ */
+export function filterOutTinyRects(rects: LH.Artifacts.Rect[]): LH.Artifacts.Rect[];
+//# sourceMappingURL=rect-helpers.d.ts.map

package/core/lib/script-helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @param {LH.Artifacts.NetworkRequest[]} networkRecords
+ * @param {LH.Artifacts.Script} script
+ * @return {LH.Artifacts.NetworkRequest|undefined}
+ */
+export function getRequestForScript(networkRecords: LH.Artifacts.NetworkRequest[], script: LH.Artifacts.Script): LH.Artifacts.NetworkRequest | undefined;
+/**
+ * @license Copyright 2022 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+/**
+ * @param {LH.Artifacts.Script} script
+ * @return {boolean}
+ */
+export function isInline(script: LH.Artifacts.Script): boolean;
+//# sourceMappingURL=script-helpers.d.ts.map

package/core/lib/sentry.d.ts

@@ -0,0 +1,32 @@
+export namespace Sentry {
+    export { init };
+    export { noop as captureMessage };
+    export { noop as captureBreadcrumb };
+    export { noop as getContext };
+    export const captureException: (error: Error, options: {
+        level?: string | undefined;
+        tags?: {
+            [key: string]: any;
+        } | undefined;
+        extra?: {
+            [key: string]: any;
+        } | undefined;
+    }) => Promise<void>;
+    export function _shouldSample(): boolean;
+}
+export type Breadcrumb = import('@sentry/node').Breadcrumb;
+export type NodeClient = import('@sentry/node').NodeClient;
+export type NodeOptions = import('@sentry/node').NodeOptions;
+export type Severity = import('@sentry/node').Severity;
+/**
+ * When called, replaces noops with actual Sentry implementation.
+ * @param {{url: string, flags: LH.CliFlags, environmentData: NodeOptions}} opts
+ */
+declare function init(opts: {
+    url: string;
+    flags: LH.CliFlags;
+    environmentData: NodeOptions;
+}): Promise<void>;
+declare function noop(): void;
+export {};
+//# sourceMappingURL=sentry.d.ts.map

package/core/lib/stack-packs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Returns all packs that match the stacks found in the page.
+ * @param {LH.Artifacts['Stacks']|undefined} pageStacks
+ * @return {LH.RawIcu<Array<LH.Result.StackPack>>}
+ */
+export function getStackPacks(pageStacks: LH.Artifacts['Stacks'] | undefined): LH.RawIcu<Array<LH.Result.StackPack>>;
+/**
+ * Pairs consisting of a stack pack's ID and the set of stacks needed to be
+ * detected in a page to display that pack's advice.
+ * @type {Array<{packId: string, requiredStacks: Array<string>}>}
+ */
+export const stackPacksToInclude: Array<{
+    packId: string;
+    requiredStacks: Array<string>;
+}>;
+//# sourceMappingURL=stack-packs.d.ts.map

package/core/lib/statistics.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Interpolates the y value at a point x on the line defined by (x0, y0) and (x1, y1)
+ * @param {number} x0
+ * @param {number} y0
+ * @param {number} x1
+ * @param {number} y1
+ * @param {number} x
+ * @return {number}
+ */
+export function linearInterpolation(x0: number, y0: number, x1: number, y1: number, x: number): number;
+/**
+ * Returns the score (1 - percentile) of `value` in a log-normal distribution
+ * specified by the `median` value, at which the score will be 0.5, and a 10th
+ * percentile value, at which the score will be 0.9. The score represents the
+ * amount of the distribution greater than `value`. All values should be in the
+ * same units (e.g. milliseconds). See
+ *   https://www.desmos.com/calculator/o98tbeyt1t
+ * for an interactive view of the relationship between these parameters and the
+ * typical parameterization (location and shape) of the log-normal distribution.
+ * @param {{median: number, p10: number}} parameters
+ * @param {number} value
+ * @return {number}
+ */
+export function getLogNormalScore({ median, p10 }: {
+    median: number;
+    p10: number;
+}, value: number): number;
+//# sourceMappingURL=statistics.d.ts.map

package/core/lib/tappable-rects.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Merge client rects together and remove small ones. This may result in a larger overall
+ * size than that of the individual client rects.
+ * We use this to simulate a finger tap on those targets later on.
+ * @param {LH.Artifacts.Rect[]} clientRects
+ */
+export function getTappableRectsFromClientRects(clientRects: LH.Artifacts.Rect[]): import("../../types/lhr/audit-details.js").default.Rect[];
+//# sourceMappingURL=tappable-rects.d.ts.map

package/core/lib/third-party-web.d.ts

@@ -0,0 +1,32 @@
+declare namespace _default {
+    export { getEntity };
+    export { getProduct };
+    export { isThirdParty };
+    export { isFirstParty };
+}
+export default _default;
+export type ThirdPartyEntity = import("third-party-web").IEntity;
+export type ThirdPartyProduct = import("third-party-web").IProduct;
+/** @typedef {import("third-party-web").IEntity} ThirdPartyEntity */
+/** @typedef {import("third-party-web").IProduct} ThirdPartyProduct */
+/**
+ * @param {string} url
+ * @return {ThirdPartyEntity|undefined}
+ */
+declare function getEntity(url: string): ThirdPartyEntity | undefined;
+/**
+ * @param {string} url
+ * @return {ThirdPartyProduct|undefined}
+ */
+declare function getProduct(url: string): ThirdPartyProduct | undefined;
+/**
+ * @param {string} url
+ * @param {ThirdPartyEntity | undefined} mainDocumentEntity
+ */
+declare function isThirdParty(url: string, mainDocumentEntity: ThirdPartyEntity | undefined): boolean;
+/**
+ * @param {string} url
+ * @param {ThirdPartyEntity | undefined} mainDocumentEntity
+ */
+declare function isFirstParty(url: string, mainDocumentEntity: ThirdPartyEntity | undefined): boolean;
+//# sourceMappingURL=third-party-web.d.ts.map

package/core/lib/timing-trace-saver.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+/**
+ * Generates a chromium trace file from user timing measures
+ * `threadId` can be provided to separate a series of trace events into another thread, useful
+ * if timings do not share the same timeOrigin, but should both be "left-aligned".
+ * Adapted from https://github.com/tdresser/performance-observer-tracing
+ * @param {LH.Artifacts.MeasureEntry[]} entries user timing entries
+ * @param {number=} threadId
+ */
+export function generateTraceEvents(entries: LH.Artifacts.MeasureEntry[], threadId?: number | undefined): import("..").TraceEvent[];
+/**
+ * Writes a trace file to disk
+ * @param {LH.Result} lhr
+ * @return {string}
+ */
+export function createTraceString(lhr: LH.Result): string;
+//# sourceMappingURL=timing-trace-saver.d.ts.map

package/core/lib/tracehouse/cpu-profile-model.d.ts

@@ -0,0 +1,228 @@
+export type CpuProfile = {
+    id: string;
+    pid: number;
+    tid: number;
+    startTime: number;
+    nodes: Required<LH.TraceCpuProfile>['nodes'];
+    samples: Array<number>;
+    timeDeltas: Array<number>;
+};
+export type ProfilerRange = Required<Required<LH.TraceEvent['args']>['data']>['_syntheticProfilerRange'];
+export type SynthethicEvent = LH.TraceEvent & {
+    args: {
+        data: {
+            _syntheticProfilerRange: ProfilerRange;
+        };
+    };
+};
+export type SynthethicTaskNode = Omit<LH.Artifacts.TaskNode, 'event'> & {
+    event: SynthethicEvent;
+    endEvent: SynthethicEvent;
+};
+/**
+ * @fileoverview
+ *
+ * This model converts the `Profile` and `ProfileChunk` mega trace events from the `disabled-by-default-v8.cpu_profiler`
+ * category into B/E-style trace events that main-thread-tasks.js already knows how to parse into a task tree.
+ *
+ * The V8 CPU profiler measures where time is being spent by sampling the stack (See https://www.jetbrains.com/help/profiler/Profiling_Guidelines__Choosing_the_Right_Profiling_Mode.html
+ * for a generic description of the differences between tracing and sampling).
+ *
+ * A `Profile` event is a record of the stack that was being executed at different sample points in time.
+ * It has a structure like this:
+ *
+ *    nodes: [function A, function B, function C]
+ *    samples: [node with id 2, node with id 1, ...]
+ *    timeDeltas: [4125μs since last sample, 121μs since last sample, ...]
+ *
+ * Note that this is subtly different from the protocol-based Crdp.Profiler.Profile type.
+ *
+ * Helpful prior art:
+ * @see https://cs.chromium.org/chromium/src/third_party/devtools-frontend/src/front_end/sdk/CPUProfileDataModel.js?sq=package:chromium&g=0&l=42
+ * @see https://github.com/v8/v8/blob/99ca333b0efba3236954b823101315aefeac51ab/tools/profile.js
+ * @see https://github.com/jlfwong/speedscope/blob/9ed1eb192cb7e9dac43a5f25bd101af169dc654a/src/import/chrome.ts#L200
+ */
+/**
+ * @typedef CpuProfile
+ * @property {string} id
+ * @property {number} pid
+ * @property {number} tid
+ * @property {number} startTime
+ * @property {Required<LH.TraceCpuProfile>['nodes']} nodes
+ * @property {Array<number>} samples
+ * @property {Array<number>} timeDeltas
+ */
+/** @typedef {Required<Required<LH.TraceEvent['args']>['data']>['_syntheticProfilerRange']} ProfilerRange */
+/** @typedef {LH.TraceEvent & {args: {data: {_syntheticProfilerRange: ProfilerRange}}}} SynthethicEvent */
+/** @typedef {Omit<LH.Artifacts.TaskNode, 'event'> & {event: SynthethicEvent, endEvent: SynthethicEvent}} SynthethicTaskNode */
+export class CpuProfileModel {
+    /**
+     * @param {LH.TraceEvent | undefined} event
+     * @return {event is SynthethicEvent}
+     */
+    static isSyntheticEvent(event: LH.TraceEvent | undefined): event is SynthethicEvent;
+    /**
+     * @param {LH.Artifacts.TaskNode} task
+     * @return {task is SynthethicTaskNode}
+     */
+    static isSyntheticTask(task: LH.Artifacts.TaskNode): task is SynthethicTaskNode;
+    /**
+     * Finds all the tasks that started or ended (depending on `type`) within the provided time range.
+     * Uses a memory index to remember the place in the array the last invocation left off to avoid
+     * re-traversing the entire array, but note that this index might still be slightly off from the
+     * true start position.
+     *
+     * @param {Array<{startTime: number, endTime: number}>} knownTasks
+     * @param {{type: 'startTime'|'endTime', initialIndex: number, earliestPossibleTimestamp: number, latestPossibleTimestamp: number}} options
+     */
+    static _getTasksInRange(knownTasks: Array<{
+        startTime: number;
+        endTime: number;
+    }>, options: {
+        type: 'startTime' | 'endTime';
+        initialIndex: number;
+        earliestPossibleTimestamp: number;
+        latestPossibleTimestamp: number;
+    }): {
+        tasks: {
+            startTime: number;
+            endTime: number;
+        }[];
+        lastIndex: number;
+    };
+    /**
+     * Given a particular time range and a set of known true tasks, find the correct timestamp to use
+     * for a transition between tasks.
+     *
+     * Because the sampling profiler only provides a *range* of start/stop function boundaries, this
+     * method uses knowledge of a known set of tasks to find the most accurate timestamp for a particular
+     * range. For example, if we know that a function ended between 800ms and 810ms, we can use the
+     * knowledge that a toplevel task ended at 807ms to use 807ms as the correct endtime for this function.
+     *
+     * @param {{syntheticTask: SynthethicTaskNode, eventType: 'start'|'end', allEventsAtTs: {naive: Array<SynthethicEvent>, refined: Array<SynthethicEvent>}, knownTaskStartTimeIndex: number, knownTaskEndTimeIndex: number, knownTasksByStartTime: Array<{startTime: number, endTime: number}>, knownTasksByEndTime: Array<{startTime: number, endTime: number}>}} data
+     * @return {{timestamp: number, lastStartTimeIndex: number, lastEndTimeIndex: number}}
+     */
+    static _findEffectiveTimestamp(data: {
+        syntheticTask: SynthethicTaskNode;
+        eventType: 'start' | 'end';
+        allEventsAtTs: {
+            naive: Array<SynthethicEvent>;
+            refined: Array<SynthethicEvent>;
+        };
+        knownTaskStartTimeIndex: number;
+        knownTaskEndTimeIndex: number;
+        knownTasksByStartTime: Array<{
+            startTime: number;
+            endTime: number;
+        }>;
+        knownTasksByEndTime: Array<{
+            startTime: number;
+            endTime: number;
+        }>;
+    }): {
+        timestamp: number;
+        lastStartTimeIndex: number;
+        lastEndTimeIndex: number;
+    };
+    /**
+     * Creates B/E-style trace events from a CpuProfile object created by `collectProfileEvents()`
+     *
+     * @param {CpuProfile} profile
+     * @param {Array<LH.Artifacts.TaskNode>} tasks
+     * @return {Array<LH.TraceEvent>}
+     */
+    static synthesizeTraceEvents(profile: CpuProfile, tasks: Array<LH.Artifacts.TaskNode>): Array<LH.TraceEvent>;
+    /**
+     * Merges the data of all the `ProfileChunk` trace events into a single CpuProfile object for consumption
+     * by `synthesizeTraceEvents()`.
+     *
+     * @param {Array<LH.TraceEvent>} traceEvents
+     * @return {Array<CpuProfile>}
+     */
+    static collectProfileEvents(traceEvents: Array<LH.TraceEvent>): Array<CpuProfile>;
+    /**
+     * @param {CpuProfile} profile
+     */
+    constructor(profile: CpuProfile);
+    _profile: CpuProfile;
+    _nodesById: Map<number, {
+        id: number;
+        callFrame: {
+            functionName: string;
+            url?: string | undefined;
+        };
+        parent?: number | undefined;
+    }>;
+    _activeNodeArraysById: Map<number, number[]>;
+    /**
+     * Initialization function to enable O(1) access to nodes by node ID.
+     * @return {Map<number, CpuProfile['nodes'][0]>}
+     */
+    _createNodeMap(): Map<number, CpuProfile['nodes'][0]>;
+    /**
+     * Initialization function to enable O(1) access to the set of active nodes in the stack by node ID.
+     * @return {Map<number, Array<number>>}
+     */
+    _createActiveNodeArrays(): Map<number, Array<number>>;
+    /**
+     * Returns all the node IDs in a stack when a specific nodeId is at the top of the stack
+     * (i.e. a stack's node ID and the node ID of all of its parents).
+     *
+     * @param {number} nodeId
+     * @return {Array<number>}
+     */
+    _getActiveNodeIds(nodeId: number): Array<number>;
+    /**
+     * Generates the necessary B/E-style trace events for a single transition from stack A to stack B
+     * at the given latest timestamp (includes possible range in event.args.data).
+     *
+     * Example:
+     *
+     *    latestPossibleTimestamp 1234
+     *    previousNodeIds 1,2,3
+     *    currentNodeIds 1,2,4
+     *
+     *    yields [end 3 at ts 1234, begin 4 at ts 1234]
+     *
+     * @param {number} earliestPossibleTimestamp
+     * @param {number} latestPossibleTimestamp
+     * @param {Array<number>} previousNodeIds
+     * @param {Array<number>} currentNodeIds
+     * @return {Array<SynthethicEvent>}
+     */
+    _synthesizeTraceEventsForTransition(earliestPossibleTimestamp: number, latestPossibleTimestamp: number, previousNodeIds: Array<number>, currentNodeIds: Array<number>): Array<SynthethicEvent>;
+    /**
+     * Creates the B/E-style trace events using only data from the profile itself. Each B/E event will
+     * include the actual _range_ the timestamp could have been in its metadata that is used for
+     * refinement later.
+     *
+     * @return {Array<SynthethicEvent>}
+     */
+    _synthesizeNaiveTraceEvents(): Array<SynthethicEvent>;
+    /**
+     * Creates a copy of B/E-style trace events with refined timestamps using knowledge from the
+     * tasks that have definitive timestamps.
+     *
+     * With the sampling profiler we know that a function started/ended _sometime between_ two points,
+     * but not exactly when. Using the information from other tasks gives us more information to be
+     * more precise with timings and allows us to create a valid task tree later on.
+     *
+     * @param {Array<{startTime: number, endTime: number}>} knownTasks
+     * @param {Array<SynthethicTaskNode>} syntheticTasks
+     * @param {Array<SynthethicEvent>} syntheticEvents
+     * @return {Array<SynthethicEvent>}
+     */
+    _refineTraceEventsWithTasks(knownTasks: Array<{
+        startTime: number;
+        endTime: number;
+    }>, syntheticTasks: Array<SynthethicTaskNode>, syntheticEvents: Array<SynthethicEvent>): Array<SynthethicEvent>;
+    /**
+     * Creates B/E-style trace events from a CpuProfile object created by `collectProfileEvents()`.
+     * An optional set of tasks can be passed in to refine the start/end times.
+     *
+     * @param {Array<LH.Artifacts.TaskNode>} [knownTaskNodes]
+     * @return {Array<LH.TraceEvent>}
+     */
+    synthesizeTraceEvents(knownTaskNodes?: import("./main-thread-tasks.js").TaskNode[] | undefined): Array<LH.TraceEvent>;
+}
+//# sourceMappingURL=cpu-profile-model.d.ts.map

package/core/lib/tracehouse/main-thread-tasks.d.ts

@@ -0,0 +1,162 @@
+export type TaskGroup = import('./task-groups.js').TaskGroup;
+export type TaskNode = {
+    event: LH.TraceEvent;
+    endEvent: LH.TraceEvent | undefined;
+    children: TaskNode[];
+    parent: TaskNode | undefined;
+    /**
+     * Indicates that the task had an endTime that was inferred rather than specified in the trace. i.e. in the source trace this task was unbounded.
+     */
+    unbounded: boolean;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    selfTime: number;
+    attributableURLs: string[];
+    group: TaskGroup;
+};
+export type PriorTaskData = {
+    timers: Map<string, TaskNode>;
+    xhrs: Map<string, TaskNode>;
+    frameURLsById: Map<string, string>;
+    lastTaskURLs: string[];
+};
+/**
+ * @fileoverview
+ *
+ * This artifact converts the array of raw trace events into an array of hierarchical
+ * tasks for easier consumption and bottom-up analysis.
+ *
+ * Events are easily produced but difficult to consume. They're a mixture of start/end markers, "complete" events, etc.
+ * @see https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
+ *
+ * LH's TaskNode is an artifact that fills in the gaps a trace event leaves behind.
+ * i.e. when did it end? which events are children/parents of this one?
+ *
+ * Each task will have its group/classification, start time, end time,
+ * duration, and self time computed. Each task will potentially have a parent, children, and an
+ * attributableURL for the script that was executing/forced this execution.
+ */
+/** @typedef {import('./task-groups.js').TaskGroup} TaskGroup */
+/**
+ * @typedef TaskNode
+ * @prop {LH.TraceEvent} event
+ * @prop {LH.TraceEvent|undefined} endEvent
+ * @prop {TaskNode[]} children
+ * @prop {TaskNode|undefined} parent
+ * @prop {boolean} unbounded Indicates that the task had an endTime that was inferred rather than specified in the trace. i.e. in the source trace this task was unbounded.
+ * @prop {number} startTime
+ * @prop {number} endTime
+ * @prop {number} duration
+ * @prop {number} selfTime
+ * @prop {string[]} attributableURLs
+ * @prop {TaskGroup} group
+ */
+/** @typedef {{timers: Map<string, TaskNode>, xhrs: Map<string, TaskNode>, frameURLsById: Map<string, string>, lastTaskURLs: string[]}} PriorTaskData */
+export class MainThreadTasks {
+    /**
+     * @param {LH.TraceEvent} event
+     * @param {LH.TraceEvent} [endEvent]
+     * @return {TaskNode}
+     */
+    static _createNewTaskNode(event: LH.TraceEvent, endEvent?: LH.TraceEvent | undefined): TaskNode;
+    /**
+     *
+     * @param {TaskNode} currentTask
+     * @param {number} stopTs
+     * @param {PriorTaskData} priorTaskData
+     * @param {Array<LH.TraceEvent>} reverseEventsQueue
+     */
+    static _assignAllTimersUntilTs(currentTask: TaskNode, stopTs: number, priorTaskData: PriorTaskData, reverseEventsQueue: Array<LH.TraceEvent>): void;
+    /**
+     * This function takes the start and end events from a thread and creates tasks from them.
+     * We do this by iterating through the start and end event arrays simultaneously. For each start
+     * event we attempt to find its end event.
+     *
+     * Because of this matching of start/end events and the need to be mutating our end events queue,
+     * we reverse the array to more efficiently `.pop()` them off rather than `.shift()` them off.
+     * While it's true the worst case runtime here is O(n^2), ~99.999% of the time the reverse loop is O(1)
+     * because the overwhelmingly common case is that end event for a given start event is simply the very next event in our queue.
+     *
+     * @param {LH.TraceEvent[]} taskStartEvents
+     * @param {LH.TraceEvent[]} taskEndEvents
+     * @param {number} traceEndTs
+     * @return {TaskNode[]}
+     */
+    static _createTasksFromStartAndEndEvents(taskStartEvents: LH.TraceEvent[], taskEndEvents: LH.TraceEvent[], traceEndTs: number): TaskNode[];
+    /**
+     * This function iterates through the tasks to set the `.parent`/`.children` properties of tasks
+     * according to their implied nesting structure. If any of these relationships seem impossible based on
+     * the timestamps, this method will throw.
+     *
+     * @param {TaskNode[]} sortedTasks
+     * @param {LH.TraceEvent[]} timerInstallEvents
+     * @param {PriorTaskData} priorTaskData
+     */
+    static _createTaskRelationships(sortedTasks: TaskNode[], timerInstallEvents: LH.TraceEvent[], priorTaskData: PriorTaskData): void;
+    /**
+     * This function takes the raw trace events sorted in increasing timestamp order and outputs connected task nodes.
+     * To create the task heirarchy we make several passes over the events.
+     *
+     *    1. Create three arrays of X/B events, E events, and TimerInstall events.
+     *    2. Create tasks for each X/B event, throwing if a matching E event cannot be found for a given B.
+     *    3. Sort the tasks by ↑ startTime, ↓ duration.
+     *    4. Match each task to its parent, throwing if there is any invalid overlap between tasks.
+     *    5. Sort the tasks once more by ↑ startTime, ↓ duration in case they changed during relationship creation.
+     *
+     * @param {LH.TraceEvent[]} mainThreadEvents
+     * @param {PriorTaskData} priorTaskData
+     * @param {number} traceEndTs
+     * @return {TaskNode[]}
+     */
+    static _createTasksFromEvents(mainThreadEvents: LH.TraceEvent[], priorTaskData: PriorTaskData, traceEndTs: number): TaskNode[];
+    /**
+     * @param {TaskNode} task
+     * @param {TaskNode|undefined} parent
+     * @return {number}
+     */
+    static _computeRecursiveSelfTime(task: TaskNode, parent: TaskNode | undefined): number;
+    /**
+     * @param {TaskNode} task
+     * @param {string[]} parentURLs
+     * @param {string[]} allURLsInTree
+     * @param {PriorTaskData} priorTaskData
+     */
+    static _computeRecursiveAttributableURLs(task: TaskNode, parentURLs: string[], allURLsInTree: string[], priorTaskData: PriorTaskData): void;
+    /**
+     * @param {TaskNode} task
+     * @param {Array<string>} urls
+     */
+    static _setRecursiveEmptyAttributableURLs(task: TaskNode, urls: Array<string>): void;
+    /**
+     * @param {TaskNode} task
+     * @param {TaskGroup} [parentGroup]
+     */
+    static _computeRecursiveTaskGroup(task: TaskNode, parentGroup?: import("./task-groups.js").TaskGroup | undefined): void;
+    /**
+     * @param {LH.TraceEvent[]} mainThreadEvents
+     * @param {Array<{id: string, url: string}>} frames
+     * @param {number} traceEndTs
+     * @param {number} [traceStartTs] Optional time-0 ts for tasks. Tasks before this point will have negative start/end times. Defaults to the first task found.
+     * @return {TaskNode[]}
+     */
+    static getMainThreadTasks(mainThreadEvents: LH.TraceEvent[], frames: Array<{
+        id: string;
+        url: string;
+    }>, traceEndTs: number, traceStartTs?: number | undefined): TaskNode[];
+    /**
+     * Prints an artistic rendering of the task tree for easier debugability.
+     *
+     * @param {TaskNode[]} tasks
+     * @param {{printWidth?: number, startTime?: number, endTime?: number, taskLabelFn?: (node: TaskNode) => string}} options
+     * @return {string}
+     */
+    static printTaskTreeToDebugString(tasks: TaskNode[], options?: {
+        printWidth?: number | undefined;
+        startTime?: number | undefined;
+        endTime?: number | undefined;
+        taskLabelFn?: ((node: TaskNode) => string) | undefined;
+    }): string;
+}
+import * as LH from "../../../types/lh.js";
+//# sourceMappingURL=main-thread-tasks.d.ts.map

package/core/lib/tracehouse/main-thread-tasks.js

@@ -4,6 +4,7 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
+import * as LH from '../../../types/lh.js';
 import {taskGroups, taskNameToGroup} from './task-groups.js';
 
 /**