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

package/core/config/config-helpers.d.ts

@@ -0,0 +1,94 @@
+export type GathererConstructor = typeof import('../gather/gatherers/gatherer.js').Gatherer;
+export type Audit = typeof import('../audits/audit.js')['Audit'];
+export type Gatherer = InstanceType<GathererConstructor>;
+/**
+ * // TODO(bckenny): could adopt "jsonified" type to ensure T will survive JSON
+ * round trip: https://github.com/Microsoft/TypeScript/issues/21838
+ * @template T
+ * @param {T} json
+ * @return {T}
+ */
+export function deepClone<T>(json: T): T;
+/**
+ * Deep clone a config, copying over any "live" gatherer or audit that
+ * wouldn't make the JSON round trip.
+ * @param {LH.Config} json
+ * @return {LH.Config}
+ */
+export function deepCloneConfigJson(json: LH.Config): LH.Config;
+/**
+ * Until support of jsdoc templates with constraints, type in config.d.ts.
+ * See https://github.com/Microsoft/TypeScript/issues/24283
+ * @type {LH.Config.Merge}
+ */
+export const mergeConfigFragment: LH.Config.Merge;
+/**
+ * Merge an array of items by a caller-defined key. `mergeConfigFragment` is used to merge any items
+ * with a matching key.
+ *
+ * @template {Record<string, any>} T
+ * @param {Array<T>|null|undefined} baseArray
+ * @param {Array<T>|null|undefined} extensionArray
+ * @param {(item: T) => string} keyFn
+ * @return {Array<T>}
+ */
+export function mergeConfigFragmentArrayByKey<T extends Record<string, any>>(baseArray: T[] | null | undefined, extensionArray: T[] | null | undefined, keyFn: (item: T) => string): T[];
+/**
+ * If any items with identical `path` properties are found in the input array,
+ * merge their `options` properties into the first instance and then discard any
+ * other instances.
+ * @template {{path?: string, options: Record<string, unknown>}} T
+ * @param {T[]} items
+ * @return T[]
+ */
+export function mergeOptionsOfItems<T extends {
+    path?: string | undefined;
+    options: Record<string, unknown>;
+}>(items: T[]): T[];
+/**
+ * @param {LH.Config} config
+ * @param {string | undefined} configDir
+ * @param {{plugins?: string[]} | undefined} flags
+ * @return {Promise<LH.Config>}
+ */
+export function mergePlugins(config: LH.Config, configDir: string | undefined, flags: {
+    plugins?: string[];
+} | undefined): Promise<LH.Config>;
+/**
+ * Take an array of audits and audit paths and require any paths (possibly
+ * relative to the optional `configDir`) using `resolveModule`,
+ * leaving only an array of AuditDefns.
+ * @param {LH.Config['audits']} audits
+ * @param {string=} configDir
+ * @return {Promise<Array<LH.Config.AuditDefn>|null>}
+ */
+export function resolveAuditsToDefns(audits: LH.Config['audits'], configDir?: string | undefined): Promise<Array<LH.Config.AuditDefn> | null>;
+/**
+ * Turns a GathererJson into a GathererDefn which involves a few main steps:
+ *    - Expanding the JSON shorthand the full definition format.
+ *    - `require`ing in the implementation.
+ *    - Creating a gatherer instance from the implementation.
+ * @param {LH.Config.GathererJson} gathererJson
+ * @param {Array<string>} coreGathererList
+ * @param {string=} configDir
+ * @return {Promise<LH.Config.GathererDefn>}
+ */
+export function resolveGathererToDefn(gathererJson: LH.Config.GathererJson, coreGathererList: Array<string>, configDir?: string | undefined): Promise<LH.Config.GathererDefn>;
+/**
+ * Resolves the location of the specified module and returns an absolute
+ * string path to the file. Used for loading custom audits and gatherers.
+ * Throws an error if no module is found.
+ * @param {string} moduleIdentifier
+ * @param {string=} configDir The absolute path to the directory of the config file, if there is one.
+ * @param {string=} category Optional plugin category (e.g. 'audit') for better error messages.
+ * @return {string}
+ * @throws {Error}
+ */
+export function resolveModulePath(moduleIdentifier: string, configDir?: string | undefined, category?: string | undefined): string;
+/**
+ * @param {LH.SharedFlagsSettings} settingsJson
+ * @param {LH.Flags|undefined} overrides
+ * @return {LH.Config.Settings}
+ */
+export function resolveSettings(settingsJson?: LH.SharedFlagsSettings, overrides?: LH.Flags | undefined): LH.Config.Settings;
+//# sourceMappingURL=config-helpers.d.ts.map

package/core/config/config-plugin.d.ts

@@ -0,0 +1,46 @@
+export default ConfigPlugin;
+/**
+ * A set of methods for extracting and validating a Lighthouse plugin config.
+ */
+declare class ConfigPlugin {
+    /**
+     * Extract and validate the list of AuditDefns added by the plugin (or undefined
+     * if no additional audits are being added by the plugin).
+     * @param {unknown} auditsJson
+     * @param {string} pluginName
+     * @return {Array<{path: string}>|undefined}
+     */
+    static _parseAuditsList(auditsJson: unknown, pluginName: string): Array<{
+        path: string;
+    }> | undefined;
+    /**
+     * Extract and validate the list of category AuditRefs added by the plugin.
+     * @param {unknown} auditRefsJson
+     * @param {string} pluginName
+     * @return {Array<LH.Config.AuditRefJson>}
+     */
+    static _parseAuditRefsList(auditRefsJson: unknown, pluginName: string): Array<LH.Config.AuditRefJson>;
+    /**
+     * Extract and validate the category added by the plugin.
+     * @param {unknown} categoryJson
+     * @param {string} pluginName
+     * @return {LH.Config.CategoryJson}
+     */
+    static _parseCategory(categoryJson: unknown, pluginName: string): LH.Config.CategoryJson;
+    /**
+     * Extract and validate groups JSON added by the plugin.
+     * @param {unknown} groupsJson
+     * @param {string} pluginName
+     * @return {Record<string, LH.Config.GroupJson>|undefined}
+     */
+    static _parseGroups(groupsJson: unknown, pluginName: string): Record<string, LH.Config.GroupJson> | undefined;
+    /**
+     * Extracts and validates a config from the provided plugin input, throwing
+     * if it deviates from the expected object shape.
+     * @param {unknown} pluginJson
+     * @param {string} pluginName
+     * @return {LH.Config}
+     */
+    static parsePlugin(pluginJson: unknown, pluginName: string): LH.Config;
+}
+//# sourceMappingURL=config-plugin.d.ts.map

package/core/config/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @param {LH.Config|undefined} config
+ * @param {{configPath?: string}} context
+ * @return {{configWorkingCopy: LH.Config, configDir?: string, configPath?: string}}
+ */
+export function resolveWorkingCopy(config: LH.Config | undefined, context: {
+    configPath?: string | undefined;
+}): {
+    configWorkingCopy: LH.Config;
+    configDir?: string | undefined;
+    configPath?: string | undefined;
+};
+/**
+ * @param {LH.Gatherer.GatherMode} gatherMode
+ * @param {LH.Config=} config
+ * @param {LH.Flags=} flags
+ * @return {Promise<{resolvedConfig: LH.Config.ResolvedConfig, warnings: string[]}>}
+ */
+export function initializeConfig(gatherMode: LH.Gatherer.GatherMode, config?: LH.Config | undefined, flags?: LH.Flags | undefined): Promise<{
+    resolvedConfig: LH.Config.ResolvedConfig;
+    warnings: string[];
+}>;
+/**
+ * @param {LH.Config.ResolvedConfig} resolvedConfig
+ * @return {string}
+ */
+export function getConfigDisplayString(resolvedConfig: LH.Config.ResolvedConfig): string;
+//# sourceMappingURL=config.d.ts.map

package/core/config/constants.d.ts

@@ -0,0 +1,86 @@
+export namespace throttling {
+    export { DEVTOOLS_RTT_ADJUSTMENT_FACTOR };
+    export { DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR };
+    export namespace mobileSlow4G {
+        const rttMs: number;
+        const throughputKbps: number;
+        const requestLatencyMs: number;
+        const downloadThroughputKbps: number;
+        const uploadThroughputKbps: number;
+        const cpuSlowdownMultiplier: number;
+    }
+    export namespace mobileRegular3G {
+        const rttMs_1: number;
+        export { rttMs_1 as rttMs };
+        const throughputKbps_1: number;
+        export { throughputKbps_1 as throughputKbps };
+        const requestLatencyMs_1: number;
+        export { requestLatencyMs_1 as requestLatencyMs };
+        const downloadThroughputKbps_1: number;
+        export { downloadThroughputKbps_1 as downloadThroughputKbps };
+        const uploadThroughputKbps_1: number;
+        export { uploadThroughputKbps_1 as uploadThroughputKbps };
+        const cpuSlowdownMultiplier_1: number;
+        export { cpuSlowdownMultiplier_1 as cpuSlowdownMultiplier };
+    }
+    export namespace desktopDense4G {
+        const rttMs_2: number;
+        export { rttMs_2 as rttMs };
+        const throughputKbps_2: number;
+        export { throughputKbps_2 as throughputKbps };
+        const cpuSlowdownMultiplier_2: number;
+        export { cpuSlowdownMultiplier_2 as cpuSlowdownMultiplier };
+        const requestLatencyMs_2: number;
+        export { requestLatencyMs_2 as requestLatencyMs };
+        const downloadThroughputKbps_2: number;
+        export { downloadThroughputKbps_2 as downloadThroughputKbps };
+        const uploadThroughputKbps_2: number;
+        export { uploadThroughputKbps_2 as uploadThroughputKbps };
+    }
+}
+export namespace screenEmulationMetrics {
+    export { MOTOG4_EMULATION_METRICS as mobile };
+    export { DESKTOP_EMULATION_METRICS as desktop };
+}
+export namespace userAgents {
+    export { MOTOG4_USERAGENT as mobile };
+    export { DESKTOP_USERAGENT as desktop };
+}
+/** @type {LH.Config.Settings} */
+export const defaultSettings: LH.Config.Settings;
+/** @type {LH.Config.Pass} */
+export const defaultPassConfig: LH.Config.Pass;
+/** @type {Required<LH.Config.NavigationJson>} */
+export const defaultNavigationConfig: Required<LH.Config.NavigationJson>;
+export namespace nonSimulatedPassConfigOverrides {
+    const pauseAfterFcpMs: number;
+    const pauseAfterLoadMs: number;
+    const networkQuietThresholdMs: number;
+    const cpuQuietThresholdMs: number;
+}
+/**
+ * @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.
+ */
+/**
+ * Adjustments needed for DevTools network throttling to simulate
+ * more realistic network conditions.
+ * @see https://crbug.com/721112
+ * @see https://docs.google.com/document/d/10lfVdS1iDWCRKQXPfbxEn4Or99D64mvNlugP1AQuFlE/edit
+ */
+declare const DEVTOOLS_RTT_ADJUSTMENT_FACTOR: 3.75;
+declare const DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR: 0.9;
+/**
+ * @type {Required<LH.SharedFlagsSettings['screenEmulation']>}
+ */
+declare const MOTOG4_EMULATION_METRICS: Required<LH.SharedFlagsSettings['screenEmulation']>;
+/**
+ * Desktop metrics adapted from emulated_devices/module.json
+ * @type {Required<LH.SharedFlagsSettings['screenEmulation']>}
+ */
+declare const DESKTOP_EMULATION_METRICS: Required<LH.SharedFlagsSettings['screenEmulation']>;
+declare const MOTOG4_USERAGENT: "Mozilla/5.0 (Linux; Android 7.0; Moto G (4)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4695.0 Mobile Safari/537.36 Chrome-Lighthouse";
+declare const DESKTOP_USERAGENT: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4695.0 Safari/537.36 Chrome-Lighthouse";
+export {};
+//# sourceMappingURL=constants.d.ts.map

package/core/config/default-config.d.ts

@@ -0,0 +1,5 @@
+export default defaultConfig;
+/** @type {LH.Config} */
+declare const defaultConfig: LH.Config;
+import * as LH from "../../types/lh.js";
+//# sourceMappingURL=default-config.d.ts.map

package/core/config/default-config.js

@@ -6,6 +6,7 @@
 
 /* eslint-disable max-len */
 
+import * as LH from '../../types/lh.js';
 import * as constants from './constants.js';
 import * as i18n from '../lib/i18n/i18n.js';
 import {metricsToAudits} from './metrics-to-audits.js';

package/core/config/desktop-config.d.ts

@@ -0,0 +1,5 @@
+export default config;
+/** @type {LH.Config} */
+declare const config: LH.Config;
+import * as LH from "../../types/lh.js";
+//# sourceMappingURL=desktop-config.d.ts.map

package/core/config/desktop-config.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 * as constants from './constants.js';
 
 /** @type {LH.Config} */

package/core/config/experimental-config.d.ts

@@ -0,0 +1,13 @@
+export default config;
+/**
+ * @license Copyright 2020 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.
+ */
+/**
+ * @fileoverview Config for new audits that aren't quite ready for
+ * being enabled by default.
+ */
+/** @type {LH.Config} */
+declare const config: LH.Config;
+//# sourceMappingURL=experimental-config.d.ts.map

package/core/config/filters.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Filters a config's artifacts, audits, and categories down to the set that supports the specified gather mode.
+ *
+ * @param {LH.Config.ResolvedConfig} resolvedConfig
+ * @param {LH.Gatherer.GatherMode} mode
+ * @return {LH.Config.ResolvedConfig}
+ */
+export function filterConfigByGatherMode(resolvedConfig: LH.Config.ResolvedConfig, mode: LH.Gatherer.GatherMode): LH.Config.ResolvedConfig;
+/**
+ * Filters a config's artifacts, audits, and categories down to the requested set.
+ * Skip audits overrides inclusion via `onlyAudits`/`onlyCategories`.
+ *
+ * @param {LH.Config.ResolvedConfig} resolvedConfig
+ * @param {Pick<LH.Config.Settings, 'onlyAudits'|'onlyCategories'|'skipAudits'>} filters
+ * @return {LH.Config.ResolvedConfig}
+ */
+export function filterConfigByExplicitFilters(resolvedConfig: LH.Config.ResolvedConfig, filters: Pick<LH.Config.Settings, 'onlyAudits' | 'onlyCategories' | 'skipAudits'>): LH.Config.ResolvedConfig;
+/**
+ * Filters an array of artifacts down to the set that supports the specified gather mode.
+ *
+ * @param {LH.Config.ResolvedConfig['artifacts']} artifacts
+ * @param {LH.Gatherer.GatherMode} mode
+ * @return {LH.Config.ResolvedConfig['artifacts']}
+ */
+export function filterArtifactsByGatherMode(artifacts: LH.Config.ResolvedConfig['artifacts'], mode: LH.Gatherer.GatherMode): LH.Config.ResolvedConfig['artifacts'];
+/**
+ * Filters an array of artifacts down to the set that's required by the specified audits.
+ *
+ * @param {LH.Config.ResolvedConfig['artifacts']} artifacts
+ * @param {LH.Config.ResolvedConfig['audits']} audits
+ * @return {LH.Config.ResolvedConfig['artifacts']}
+ */
+export function filterArtifactsByAvailableAudits(artifacts: LH.Config.ResolvedConfig['artifacts'], audits: LH.Config.ResolvedConfig['audits']): LH.Config.ResolvedConfig['artifacts'];
+/**
+ * Filters an array of navigations down to the set supported by the available artifacts.
+ *
+ * @param {LH.Config.ResolvedConfig['navigations']} navigations
+ * @param {Array<LH.Config.AnyArtifactDefn>} availableArtifacts
+ * @return {LH.Config.ResolvedConfig['navigations']}
+ */
+export function filterNavigationsByAvailableArtifacts(navigations: LH.Config.ResolvedConfig['navigations'], availableArtifacts: Array<LH.Config.AnyArtifactDefn>): LH.Config.ResolvedConfig['navigations'];
+/**
+ * Filters an array of audits down to the set that can be computed using only the specified artifacts.
+ *
+ * @param {LH.Config.ResolvedConfig['audits']} audits
+ * @param {Array<LH.Config.AnyArtifactDefn>} availableArtifacts
+ * @return {LH.Config.ResolvedConfig['audits']}
+ */
+export function filterAuditsByAvailableArtifacts(audits: LH.Config.ResolvedConfig['audits'], availableArtifacts: Array<LH.Config.AnyArtifactDefn>): LH.Config.ResolvedConfig['audits'];
+/**
+ * Optional `supportedModes` property can explicitly exclude an audit even if all required artifacts are available.
+ *
+ * @param {LH.Config.ResolvedConfig['audits']} audits
+ * @param {LH.Gatherer.GatherMode} mode
+ * @return {LH.Config.ResolvedConfig['audits']}
+ */
+export function filterAuditsByGatherMode(audits: LH.Config.ResolvedConfig['audits'], mode: LH.Gatherer.GatherMode): LH.Config.ResolvedConfig['audits'];
+/**
+ * Filters a categories object and their auditRefs down to the set that can be computed using
+ * only the specified audits.
+ *
+ * @param {LH.Config.LegacyResolvedConfig['categories']} categories
+ * @param {Array<LH.Config.AuditDefn>} availableAudits
+ * @return {LH.Config.LegacyResolvedConfig['categories']}
+ */
+export function filterCategoriesByAvailableAudits(categories: LH.Config.LegacyResolvedConfig['categories'], availableAudits: Array<LH.Config.AuditDefn>): LH.Config.LegacyResolvedConfig['categories'];
+/**
+ * Filters a categories object and their auditRefs down to the specified category ids.
+ *
+ * @param {LH.Config.LegacyResolvedConfig['categories']} categories
+ * @param {string[] | null | undefined} onlyCategories
+ * @return {LH.Config.LegacyResolvedConfig['categories']}
+ */
+export function filterCategoriesByExplicitFilters(categories: LH.Config.LegacyResolvedConfig['categories'], onlyCategories: string[] | null | undefined): LH.Config.LegacyResolvedConfig['categories'];
+/**
+ * Optional `supportedModes` property can explicitly exclude a category even if some audits are available.
+ *
+ * @param {LH.Config.LegacyResolvedConfig['categories']} categories
+ * @param {LH.Gatherer.GatherMode} mode
+ * @return {LH.Config.LegacyResolvedConfig['categories']}
+ */
+export function filterCategoriesByGatherMode(categories: LH.Config.LegacyResolvedConfig['categories'], mode: LH.Gatherer.GatherMode): LH.Config.LegacyResolvedConfig['categories'];
+//# sourceMappingURL=filters.d.ts.map

package/core/config/full-config.d.ts

@@ -0,0 +1,9 @@
+export default fullConfig;
+/**
+ * @license Copyright 2017 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.
+ */
+/** @type {LH.Config} */
+declare const fullConfig: LH.Config;
+//# sourceMappingURL=full-config.d.ts.map

package/core/config/lr-desktop-config.d.ts

@@ -0,0 +1,4 @@
+export default config;
+/** @type {LH.Config} */
+declare const config: LH.Config;
+//# sourceMappingURL=lr-desktop-config.d.ts.map

package/core/config/lr-mobile-config.d.ts

@@ -0,0 +1,9 @@
+export default config;
+/**
+ * @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.
+ */
+/** @type {LH.Config} */
+declare const config: LH.Config;
+//# sourceMappingURL=lr-mobile-config.d.ts.map

package/core/config/metrics-to-audits.d.ts

@@ -0,0 +1,19 @@
+export namespace metricsToAudits {
+    export { fcpRelevantAudits };
+    export { lcpRelevantAudits };
+    export { tbtRelevantAudits };
+    export { clsRelevantAudits };
+    export { inpRelevantAudits };
+}
+/**
+ * @license Copyright 2021 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.
+ */
+declare const fcpRelevantAudits: string[];
+declare const lcpRelevantAudits: string[];
+declare const tbtRelevantAudits: string[];
+declare const clsRelevantAudits: string[];
+declare const inpRelevantAudits: string[];
+export {};
+//# sourceMappingURL=metrics-to-audits.d.ts.map

package/core/config/perf-config.d.ts

@@ -0,0 +1,9 @@
+export default perfConfig;
+/**
+ * @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.
+ */
+/** @type {LH.Config} */
+declare const perfConfig: LH.Config;
+//# sourceMappingURL=perf-config.d.ts.map

package/core/config/validation.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @param {LH.Config.GathererDefn | LH.Config.AnyFRGathererDefn} gathererDefn
+ * @return {gathererDefn is LH.Config.AnyFRGathererDefn}
+ */
+export function isFRGathererDefn(gathererDefn: LH.Config.GathererDefn | LH.Config.AnyFRGathererDefn): gathererDefn is import("../../types/config.js").default.AnyFRGathererDefn;
+/**
+ * Determines if the artifact dependency direction is valid. The dependency's minimum supported mode
+ * must be less than or equal to the dependent's.
+ *
+ * @param {LH.Config.AnyFRGathererDefn} dependent The artifact that depends on the other.
+ * @param {LH.Config.AnyFRGathererDefn} dependency The artifact that is being depended on by the other.
+ * @return {boolean}
+ */
+export function isValidArtifactDependency(dependent: LH.Config.AnyFRGathererDefn, dependency: LH.Config.AnyFRGathererDefn): boolean;
+/**
+ * Throws if pluginName is invalid or (somehow) collides with a category in the
+ * config being added to.
+ * @param {LH.Config} config
+ * @param {string} pluginName
+ */
+export function assertValidPluginName(config: LH.Config, pluginName: string): void;
+/**
+ * Throws an error if the provided object does not implement the required Fraggle Rock gatherer interface.
+ * @param {LH.Config.AnyFRGathererDefn} gathererDefn
+ */
+export function assertValidFRGatherer(gathererDefn: LH.Config.AnyFRGathererDefn): void;
+/**
+ * Throws an error if the provided object does not implement the required navigations interface.
+ * @param {LH.Config.ResolvedConfig['navigations']} navigationsDefn
+ * @return {{warnings: string[]}}
+ */
+export function assertValidFRNavigations(navigationsDefn: LH.Config.ResolvedConfig['navigations']): {
+    warnings: string[];
+};
+/**
+ * Throws an error if the provided object does not implement the required properties of an audit
+ * definition.
+ * @param {LH.Config.AuditDefn} auditDefinition
+ */
+export function assertValidAudit(auditDefinition: LH.Config.AuditDefn): void;
+/**
+ * @param {LH.Config.ResolvedConfig['categories']} categories
+ * @param {LH.Config.ResolvedConfig['audits']} audits
+ * @param {LH.Config.ResolvedConfig['groups']} groups
+ */
+export function assertValidCategories(categories: LH.Config.ResolvedConfig['categories'], audits: LH.Config.ResolvedConfig['audits'], groups: LH.Config.ResolvedConfig['groups']): void;
+/**
+ * Validate the settings after they've been built.
+ * @param {LH.Config.Settings} settings
+ */
+export function assertValidSettings(settings: LH.Config.Settings): void;
+/**
+ * Asserts that artifacts are in a valid dependency order that can be computed.
+ *
+ * @param {Array<LH.Config.NavigationDefn>} navigations
+ */
+export function assertArtifactTopologicalOrder(navigations: Array<LH.Config.NavigationDefn>): void;
+/**
+ * @param {LH.Config.ResolvedConfig} resolvedConfig
+ * @return {{warnings: string[]}}
+ */
+export function assertValidConfig(resolvedConfig: LH.Config.ResolvedConfig): {
+    warnings: string[];
+};
+/**
+ * @param {string} artifactId
+ * @param {string} dependencyKey
+ * @return {never}
+ */
+export function throwInvalidDependencyOrder(artifactId: string, dependencyKey: string): never;
+/**
+ * @param {string} artifactId
+ * @param {string} dependencyKey
+ * @return {never}
+ */
+export function throwInvalidArtifactDependency(artifactId: string, dependencyKey: string): never;
+//# sourceMappingURL=validation.d.ts.map

package/core/gather/base-artifacts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @param {LH.Config.ResolvedConfig} resolvedConfig
+ * @param {LH.Gatherer.FRTransitionalDriver} driver
+ * @param {{gatherMode: LH.Gatherer.GatherMode}} context
+ * @return {Promise<LH.BaseArtifacts>}
+ */
+export function getBaseArtifacts(resolvedConfig: LH.Config.ResolvedConfig, driver: LH.Gatherer.FRTransitionalDriver, context: {
+    gatherMode: LH.Gatherer.GatherMode;
+}): Promise<LH.BaseArtifacts>;
+/**
+ * @param {LH.FRBaseArtifacts} baseArtifacts
+ * @param {Partial<LH.Artifacts>} gathererArtifacts
+ * @return {LH.Artifacts}
+ */
+export function finalizeArtifacts(baseArtifacts: LH.FRBaseArtifacts, gathererArtifacts: Partial<LH.Artifacts>): LH.Artifacts;
+//# sourceMappingURL=base-artifacts.d.ts.map

package/core/gather/base-gatherer.d.ts

@@ -0,0 +1,72 @@
+export default FRGatherer;
+/**
+ * Base class for all gatherers supporting both Fraggle Rock and the legacy flow.
+ * Most extending classes should implement the Fraggle Rock API and let this class handle translation.
+ * See core/gather/gatherers/gatherer.js for legacy method explanations.
+ *
+ * @implements {LH.Gatherer.GathererInstance}
+ * @implements {LH.Gatherer.FRGathererInstance}
+ */
+declare class FRGatherer implements LH.Gatherer.GathererInstance, LH.Gatherer.FRGathererInstance {
+    /** @type {LH.Gatherer.GathererMeta} */
+    meta: LH.Gatherer.GathererMeta;
+    /**
+     * Method to start observing a page for an arbitrary period of time.
+     * @param {LH.Gatherer.FRTransitionalContext} passContext
+     * @return {Promise<void>|void}
+     */
+    startInstrumentation(passContext: LH.Gatherer.FRTransitionalContext): Promise<void> | void;
+    /**
+     * Method to start observing a page when the measurements are very sensitive and
+     * should observe as little Lighthouse-induced work as possible.
+     * @param {LH.Gatherer.FRTransitionalContext} passContext
+     * @return {Promise<void>|void}
+     */
+    startSensitiveInstrumentation(passContext: LH.Gatherer.FRTransitionalContext): Promise<void> | void;
+    /**
+     * Method to stop observing a page when the measurements are very sensitive and
+     * should observe as little Lighthouse-induced work as possible.
+     *
+     * @param {LH.Gatherer.FRTransitionalContext} passContext
+     * @return {Promise<void>|void}
+     */
+    stopSensitiveInstrumentation(passContext: LH.Gatherer.FRTransitionalContext): Promise<void> | void;
+    /**
+     * Method to end observing a page after an arbitrary period of time.
+     * @param {LH.Gatherer.FRTransitionalContext} passContext
+     * @return {Promise<void>|void}
+     */
+    stopInstrumentation(passContext: LH.Gatherer.FRTransitionalContext): Promise<void> | void;
+    /**
+     * Method to gather results about a page.
+     * @param {LH.Gatherer.FRTransitionalContext} passContext
+     * @return {LH.Gatherer.PhaseResult}
+     */
+    getArtifact(passContext: LH.Gatherer.FRTransitionalContext): LH.Gatherer.PhaseResult;
+    /**
+     * Legacy property used to define the artifact ID. In Fraggle Rock, the artifact ID lives on the config.
+     * @return {keyof LH.GathererArtifacts}
+     */
+    get name(): keyof LH.GathererArtifacts;
+    /**
+     * Legacy method. Called before navigation to target url, roughly corresponds to `startInstrumentation`.
+     * @param {LH.Gatherer.PassContext} passContext
+     * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
+     */
+    beforePass(passContext: LH.Gatherer.PassContext): Promise<LH.Gatherer.PhaseResultNonPromise>;
+    /**
+     * Legacy method. Should never be used by a Fraggle Rock gatherer, here for compat only.
+     * @param {LH.Gatherer.PassContext} passContext
+     * @return {LH.Gatherer.PhaseResult}
+     */
+    pass(passContext: LH.Gatherer.PassContext): LH.Gatherer.PhaseResult;
+    /**
+     * Legacy method. Roughly corresponds to `stopInstrumentation` or `getArtifact` depending on type of gatherer.
+     * @param {LH.Gatherer.PassContext} passContext
+     * @param {LH.Gatherer.LoadData} loadData
+     * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
+     */
+    afterPass(passContext: LH.Gatherer.PassContext, loadData: LH.Gatherer.LoadData): Promise<LH.Gatherer.PhaseResultNonPromise>;
+}
+import * as LH from "../../types/lh.js";
+//# sourceMappingURL=base-gatherer.d.ts.map

package/core/gather/base-gatherer.js

@@ -4,6 +4,8 @@
  * 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';
+
 /* eslint-disable no-unused-vars */
 
 /**

package/core/gather/driver/dom.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolves a backend node ID (from a trace event, protocol, etc) to the object ID for use with
+ * `Runtime.callFunctionOn`. `undefined` means the node could not be found.
+ *
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @param {number} backendNodeId
+ * @return {Promise<string|undefined>}
+ */
+export function resolveNodeIdToObjectId(session: LH.Gatherer.FRProtocolSession, backendNodeId: number): Promise<string | undefined>;
+/**
+ * Resolves a proprietary devtools node path (created from page-function.js) to the object ID for use
+ * with `Runtime.callFunctionOn`. `undefined` means the node could not be found.
+ * Requires `DOM.getDocument` to have been called since the object's creation or it will always be `undefined`.
+ *
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @param {string} path
+ * @return {Promise<string|undefined>}
+ */
+export function resolveDevtoolsNodePathToObjectId(session: LH.Gatherer.FRProtocolSession, path: string): Promise<string | undefined>;
+//# sourceMappingURL=dom.d.ts.map