lighthouse 9.5.0-dev.20230117 → 9.5.0-dev.20230119

package/report/test/renderer/performance-category-renderer-test.js

@@ -69,11 +69,10 @@ describe('PerfCategoryRenderer', () => {
       Array.from(timelineElements).map(el => el.id),
       [
         'first-contentful-paint',
-        'interactive',
-        'speed-index',
-        'total-blocking-time',
         'largest-contentful-paint',
+        'total-blocking-time',
         'cumulative-layout-shift',
+        'speed-index',
       ]
     );
   });
@@ -322,11 +321,11 @@ describe('PerfCategoryRenderer', () => {
       expect(url.hash.split('&')).toMatchInlineSnapshot(`
 Array [
   "#FCP=6844",
-  "TTI=8191",
-  "SI=8114",
-  "TBT=1221",
   "LCP=6844",
+  "TBT=1221",
   "CLS=0",
+  "SI=8114",
+  "TTI=8191",
   "FMP=6844",
 ]
 `);
@@ -343,11 +342,11 @@ Array [
         expect(url.hash.split('&')).toMatchInlineSnapshot(`
 Array [
   "#FCP=6844",
-  "TTI=8191",
-  "SI=8114",
-  "TBT=1221",
   "LCP=6844",
+  "TBT=1221",
   "CLS=0.14",
+  "SI=8114",
+  "TTI=8191",
   "FMP=6844",
   "device=mobile",
   "version=6.0.0",

package/report/test-assets/faux-psi.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @param {any} lhr
+ * @param {Element} container
+ */
+declare function renderLHReport(lhr: any, container: Element): Promise<void>;
+/**
+ * @param {LH.Locale} locale
+ */
+declare function swapLhrLocale(locale: LH.Locale): Promise<void>;
+/**
+ * Tweak the LHR to make the desktop and mobile reports easier to identify.
+ * Adjusted: Perf category name and score, and emoji placed on top of key screenshots.
+ * @param {LH.Result} lhr
+ * @param {string} tabId
+ */
+declare function distinguishLHR(lhr: LH.Result, tabId: string): Promise<void>;
+/**
+ * Add 📱 and 💻 emoji on top of screenshot
+ * @param {string} datauri
+ * @param {string} tabId
+ */
+declare function decorateScreenshot(datauri: string, tabId: string): Promise<string>;
+type lighthouseRenderer = typeof import("../clients/bundle.js");
+/**
+ * @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.
+ */
+/** @fileoverview This file exercises two LH reports within the same DOM. */
+/** @typedef {import('../clients/bundle.js')} lighthouseRenderer */
+/** @type {lighthouseRenderer} */
+declare const lighthouseRenderer: lighthouseRenderer;
+declare function wait(ms?: number): Promise<any>;
+//# sourceMappingURL=faux-psi.d.ts.map

package/report/types/augment-dom.d.ts

@@ -10,7 +10,7 @@
  */
 
 // Import to augment querySelector/querySelectorAll with stricter type checking.
-import '../../types/query-selector';
+import '../../types/internal/query-selector';
 
 declare global {
   var CompressionStream: {

package/root.d.ts

@@ -0,0 +1,3 @@
+export const LH_ROOT: string;
+export const lighthouseVersion: any;
+//# sourceMappingURL=root.d.ts.map

package/shared/localization/format.d.ts

@@ -0,0 +1,106 @@
+export type MessageElement = import('intl-messageformat-parser').Element;
+export type ArgumentElement = import('intl-messageformat-parser').ArgumentElement;
+export const DEFAULT_LOCALE: "en-US";
+/** @param {string[]} pathInLHR */
+export function _formatPathAsString(pathInLHR: string[]): string;
+/**
+ * Function to retrieve all 'argumentElement's from an ICU message. An argumentElement
+ * is an ICU element with an argument in it, like '{varName}' or '{varName, number, bytes}'. This
+ * differs from 'messageElement's which are just arbitrary text in a message.
+ *
+ * Notes:
+ *  This function will recursively inspect plural elements for nested argumentElements.
+ *
+ *  We need to find all the elements from the plural format sections, but
+ *  they need to be deduplicated. I.e. "=1{hello {icu}} =other{hello {icu}}"
+ *  the variable "icu" would appear twice if it wasn't de duplicated. And they cannot
+ *  be stored in a set because they are not equal since their locations are different,
+ *  thus they are stored via a Map keyed on the "id" which is the ICU varName.
+ *
+ * @param {Array<MessageElement>} icuElements
+ * @param {Map<string, ArgumentElement>} [seenElementsById]
+ * @return {Map<string, ArgumentElement>}
+ */
+export function collectAllCustomElementsFromICU(icuElements: Array<MessageElement>, seenElementsById?: Map<string, import("intl-messageformat-parser").ArgumentElement> | undefined): Map<string, ArgumentElement>;
+/**
+ * Returns whether `icuMessageOrNot`` is an `LH.IcuMessage` instance.
+ * @param {unknown} icuMessageOrNot
+ * @return {icuMessageOrNot is LH.IcuMessage}
+ */
+export function isIcuMessage(icuMessageOrNot: unknown): icuMessageOrNot is import("../../types/lhr/i18n.js").IcuMessage;
+/**
+ * Get the localized and formatted form of `icuMessageOrRawString` if it's an
+ * LH.IcuMessage, or get it back directly if it's already a string.
+ * Warning: this function throws if `icuMessageOrRawString` is not the expected
+ * type (use function from `createIcuMessageFn` to create a valid LH.IcuMessage)
+ * or `locale` isn't supported (use `lookupLocale` to find a valid locale).
+ * @param {LH.IcuMessage | string} icuMessageOrRawString
+ * @param {LH.Locale} locale
+ * @return {string}
+ */
+export function getFormatted(icuMessageOrRawString: LH.IcuMessage | string, locale: LH.Locale): string;
+/**
+ * @param {LH.Locale} locale
+ * @return {Record<string, string>}
+ */
+export function getRendererFormattedStrings(locale: LH.Locale): Record<string, string>;
+/**
+ * Recursively walk the input object, looking for property values that are
+ * `LH.IcuMessage`s and replace them with their localized values. Primarily
+ * used with the full LHR or a Config as input.
+ * Returns a map of locations that were replaced to the `IcuMessage` that was at
+ * that location.
+ * @param {unknown} inputObject
+ * @param {LH.Locale} locale
+ * @return {LH.Result.IcuMessagePaths}
+ */
+export function replaceIcuMessages(inputObject: unknown, locale: LH.Locale): LH.Result.IcuMessagePaths;
+/**
+ * Returns whether the `requestedLocale` is registered and available for use
+ * @param {LH.Locale} requestedLocale
+ * @return {boolean}
+ */
+export function hasLocale(requestedLocale: LH.Locale): boolean;
+/**
+ * Populate the i18n string lookup dict with locale data
+ * Used when the host environment selects the locale and serves lighthouse the intended locale file
+ * @see https://docs.google.com/document/d/1jnt3BqKB-4q3AE94UWFA0Gqspx8Sd_jivlB7gQMlmfk/edit
+ * @param {LH.Locale} locale
+ * @param {import('./locales').LhlMessages} lhlMessages
+ */
+export function registerLocaleData(locale: LH.Locale, lhlMessages: import('./locales').LhlMessages): void;
+/**
+ * Format string `message` by localizing `values` and inserting them. `message`
+ * is assumed to already be in the given locale.
+ * If you need to localize a messagem `getFormatted` is probably what you want.
+ * @param {string} message
+ * @param {Record<string, string | number>|undefined} values
+ * @param {LH.Locale} locale
+ * @return {string}
+ */
+export function formatMessage(message: string, values: Record<string, string | number> | undefined, locale: LH.Locale): string;
+/**
+ * @param {string} i18nMessageId
+ */
+export function getIcuMessageIdParts(i18nMessageId: string): {
+    filename: string;
+    key: string;
+};
+/**
+ * Returns a list of available locales.
+ *  - if full build, this includes all canonical locales, aliases, and any locale added
+ *      via `registerLocaleData`.
+ *  - if bundled and locale messages have been stripped (locales.js shimmed), this includes
+ *      only DEFAULT_LOCALE and any locales from `registerLocaleData`.
+ * @return {Array<LH.Locale>}
+ */
+export function getAvailableLocales(): Array<LH.Locale>;
+/**
+ * Returns a list of canonical locales, as defined by the existent message files.
+ * In practice, each of these may have aliases in the full list returned by
+ * `getAvailableLocales()`.
+ * TODO: create a CanonicalLocale type
+ * @return {Array<string>}
+ */
+export function getCanonicalLocales(): Array<string>;
+//# sourceMappingURL=format.d.ts.map

package/shared/localization/i18n-module.d.ts

@@ -0,0 +1,4 @@
+import { swapLocale } from "./swap-locale.js";
+import * as format from "./format.js";
+export { swapLocale, format };
+//# sourceMappingURL=i18n-module.d.ts.map

package/shared/localization/locales.d.ts

@@ -0,0 +1,7 @@
+export type Locale = import('../../types/lhr/settings').Locale;
+export type LhlMessages = Record<string, {
+    message: string;
+}>;
+/** @type {Record<Locale, LhlMessages>} */
+export const locales: Record<Locale, LhlMessages>;
+//# sourceMappingURL=locales.d.ts.map

package/shared/localization/swap-flow-locale.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {LH.FlowResult} flowResult
+ * @param {LH.Locale} locale
+ */
+export function swapFlowLocale(flowResult: LH.FlowResult, locale: LH.Locale): any;
+//# sourceMappingURL=swap-flow-locale.d.ts.map

package/shared/localization/swap-locale.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Use the lhr.i18n.icuMessagePaths object to change locales.
+ *
+ * `icuMessagePaths` is an object keyed by `LH.IcuMessage['i18nId']`s. Within each is either
+ * 1) an array of strings, which are just object paths to where that message is used in the LHR
+ * 2) an array of `LH.IcuMessagePath`s which include both a `path` and a `values` object
+ *    which will be used in the replacement within `format.getFormatted()`
+ *
+ * An example:
+    "icuMessagePaths": {
+    "core/audits/metrics/first-contentful-paint.js | title": [
+      "audits[first-contentful-paint].title"
+    ],
+    "core/audits/server-response-time.js | displayValue": [
+      {
+        "values": {
+          "timeInMs": 570.5630000000001
+        },
+        "path": "audits[server-response-time].displayValue"
+      }
+    ],
+    "core/lib/i18n/i18n.js | columnTimeSpent": [
+      "audits[mainthread-work-breakdown].details.headings[1].text",
+      "audits[network-rtt].details.headings[1].text",
+      "audits[network-server-latency].details.headings[1].text"
+    ],
+    ...
+ */
+/**
+ * Returns a new LHR with all strings changed to the new `requestedLocale`.
+ * @param {LH.Result} lhr
+ * @param {LH.Locale} requestedLocale
+ * @return {{lhr: LH.Result, missingIcuMessageIds: string[]}}
+ */
+export function swapLocale(lhr: LH.Result, requestedLocale: LH.Locale): {
+    lhr: LH.Result;
+    missingIcuMessageIds: string[];
+};
+//# sourceMappingURL=swap-locale.d.ts.map

package/shared/type-verifiers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 A collection of general type verification functions for dealing
+ * with external data. If these grow in scope they could be auto-generated with
+ * something like `io-ts`, but it's not worth the complexity yet.
+ */
+/**
+ * Type predicate verifying `val` is an object (excluding `Array` and `null`).
+ * @param {unknown} val
+ * @return {val is Record<string, unknown>}
+ */
+export function isObjectOfUnknownValues(val: unknown): val is Record<string, unknown>;
+/**
+ * Type predicate verifying `val` is an object or an array.
+ * @param {unknown} val
+ * @return {val is Record<string, unknown>|Array<unknown>}
+ */
+export function isObjectOrArrayOfUnknownValues(val: unknown): val is unknown[] | Record<string, unknown>;
+//# sourceMappingURL=type-verifiers.d.ts.map

package/third-party/axe/valid-langs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Determine if a string is a valid language code
+ * @method isValidLang
+ * @memberof axe.utils
+ * @param {String} lang String to test if a valid language code
+ * @returns {Boolean}
+ */
+export function isValidLang(lang: string): boolean;
+//# sourceMappingURL=valid-langs.d.ts.map

package/types/artifacts.d.ts

@@ -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 {Protocol as Crdp} from 'devtools-protocol/types/protocol.js';
+
 import {parseManifest} from '../core/lib/manifest-parser.js';
 import {Simulator} from '../core/lib/dependency-graph/simulator/simulator.js';
 import {LighthouseError} from '../core/lib/lh-error.js';
@@ -12,12 +14,12 @@ import speedline from 'speedline-core';
 import TextSourceMap from '../core/lib/cdt/generated/SourceMap.js';
 import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map.js';
 import type { TaskNode as _TaskNode } from '../core/lib/tracehouse/main-thread-tasks.js';
-import AuditDetails from './lhr/audit-details'
-import Config from './config';
-import Gatherer from './gatherer';
-import {IcuMessage} from './lhr/i18n';
-import LHResult from './lhr/lhr'
-import Protocol from './protocol';
+import AuditDetails from './lhr/audit-details.js'
+import Config from './config.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
+import LHResult from './lhr/lhr.js'
+import Protocol from './protocol.js';
 import Util from './utility-types.js';
 import Audit from './audit.js';
 
@@ -123,7 +125,7 @@ export interface GathererArtifacts extends PublicGathererArtifacts,LegacyBaseArt
   /** Array of all URLs cached in CacheStorage. */
   CacheContents: string[];
   /** CSS coverage information for styles used by page's final state. */
-  CSSUsage: {rules: LH.Crdp.CSS.RuleUsage[], stylesheets: Artifacts.CSSStyleSheetInfo[]};
+  CSSUsage: {rules: Crdp.CSS.RuleUsage[], stylesheets: Artifacts.CSSStyleSheetInfo[]};
   /** The primary log of devtools protocol activity. Used in Fraggle Rock gathering. */
   DevtoolsLog: DevtoolsLog;
   /** Information on the document's doctype(or null if not present), specifically the name, publicId, and systemId.
@@ -149,7 +151,7 @@ export interface GathererArtifacts extends PublicGathererArtifacts,LegacyBaseArt
   InstallabilityErrors: Artifacts.InstallabilityErrors;
   /** JS coverage information for code used during audit. Keyed by script id. */
   // 'url' is excluded because it can be overriden by a magic sourceURL= comment, which makes keeping it a dangerous footgun!
-  JsUsage: Record<string, Omit<LH.Crdp.Profiler.ScriptCoverage, 'url'>>;
+  JsUsage: Record<string, Omit<Crdp.Profiler.ScriptCoverage, 'url'>>;
   /** Parsed version of the page's Web App Manifest, or null if none found. */
   Manifest: Artifacts.Manifest | null;
   /** The URL loaded with interception */
@@ -165,7 +167,7 @@ export interface GathererArtifacts extends PublicGathererArtifacts,LegacyBaseArt
   /** Information on all scripts in the page. */
   Scripts: Artifacts.Script[];
   /** Version information for all ServiceWorkers active after the first page load. */
-  ServiceWorker: {versions: LH.Crdp.ServiceWorker.ServiceWorkerVersion[], registrations: LH.Crdp.ServiceWorker.ServiceWorkerRegistration[]};
+  ServiceWorker: {versions: Crdp.ServiceWorker.ServiceWorkerVersion[], registrations: Crdp.ServiceWorker.ServiceWorkerRegistration[]};
   /** Source maps of scripts executed in the page. */
   SourceMaps: Array<Artifacts.SourceMap>;
   /** Information on detected tech stacks (e.g. JS libraries) used by the page. */
@@ -242,7 +244,7 @@ declare module Artifacts {
   }
 
   interface CSSStyleSheetInfo {
-    header: LH.Crdp.CSS.CSSStyleSheetHeader;
+    header: Crdp.CSS.CSSStyleSheetHeader;
     content: string;
   }
 
@@ -311,7 +313,7 @@ declare module Artifacts {
 
   interface PasswordInputsWithPreventedPaste {node: NodeDetails}
 
-  interface Script extends Omit<LH.Crdp.Debugger.ScriptParsedEvent, 'url'|'embedderName'> {
+  interface Script extends Omit<Crdp.Debugger.ScriptParsedEvent, 'url'|'embedderName'> {
     /**
      * Set by a sourceURL= magic comment if present, otherwise this is the same as the URL.
      * Use this field for presentational purposes only.
@@ -386,7 +388,7 @@ declare module Artifacts {
 
   interface Bundle {
     rawMap: RawSourceMap;
-    script: LH.Artifacts.Script;
+    script: Artifacts.Script;
     map: TextSourceMap;
     sizes: {
       // TODO(cjamcl): Rename to `sources`.
@@ -410,15 +412,15 @@ declare module Artifacts {
     node: NodeDetails
     onclick: string
     listeners?: Array<{
-      type: LH.Crdp.DOMDebugger.EventListener['type']
+      type: Crdp.DOMDebugger.EventListener['type']
     }>
   }
 
   type BFCacheReasonMap = {
-    [key in LH.Crdp.Page.BackForwardCacheNotRestoredReason]?: string[];
+    [key in Crdp.Page.BackForwardCacheNotRestoredReason]?: string[];
   };
 
-  type BFCacheNotRestoredReasonsTree = Record<LH.Crdp.Page.BackForwardCacheNotRestoredReasonType, BFCacheReasonMap>;
+  type BFCacheNotRestoredReasonsTree = Record<Crdp.Page.BackForwardCacheNotRestoredReasonType, BFCacheReasonMap>;
 
   interface BFCacheFailure {
     notRestoredReasonsTree: BFCacheNotRestoredReasonsTree;
@@ -459,10 +461,10 @@ declare module Artifacts {
       cssRule?: {
         type: 'Regular' | 'Inline' | 'Attributes';
         range?: {startLine: number, startColumn: number};
-        parentRule?: {origin: LH.Crdp.CSS.StyleSheetOrigin, selectors: {text: string}[]};
+        parentRule?: {origin: Crdp.CSS.StyleSheetOrigin, selectors: {text: string}[]};
         styleSheetId?: string;
-        stylesheet?: LH.Crdp.CSS.CSSStyleSheetHeader;
-        cssProperties?: Array<LH.Crdp.CSS.CSSProperty>;
+        stylesheet?: Crdp.CSS.CSSStyleSheetHeader;
+        cssProperties?: Array<Crdp.CSS.CSSProperty>;
       }
     }>
   }
@@ -471,7 +473,7 @@ declare module Artifacts {
   type Manifest = ReturnType<typeof parseManifest>;
 
   interface InstallabilityErrors {
-    errors: LH.Crdp.Page.InstallabilityError[];
+    errors: Crdp.Page.InstallabilityError[];
   }
 
   interface ImageElement {
@@ -598,22 +600,22 @@ declare module Artifacts {
   }
 
   interface InspectorIssues {
-    attributionReportingIssue: LH.Crdp.Audits.AttributionReportingIssueDetails[];
-    blockedByResponseIssue: LH.Crdp.Audits.BlockedByResponseIssueDetails[];
-    clientHintIssue: LH.Crdp.Audits.ClientHintIssueDetails[];
-    contentSecurityPolicyIssue: LH.Crdp.Audits.ContentSecurityPolicyIssueDetails[];
-    corsIssue: LH.Crdp.Audits.CorsIssueDetails[];
-    deprecationIssue: LH.Crdp.Audits.DeprecationIssueDetails[];
-    federatedAuthRequestIssue: LH.Crdp.Audits.FederatedAuthRequestIssueDetails[],
-    genericIssue: LH.Crdp.Audits.GenericIssueDetails[];
-    heavyAdIssue: LH.Crdp.Audits.HeavyAdIssueDetails[];
-    lowTextContrastIssue: LH.Crdp.Audits.LowTextContrastIssueDetails[];
-    mixedContentIssue: LH.Crdp.Audits.MixedContentIssueDetails[];
-    navigatorUserAgentIssue: LH.Crdp.Audits.NavigatorUserAgentIssueDetails[];
-    quirksModeIssue: LH.Crdp.Audits.QuirksModeIssueDetails[];
-    cookieIssue: LH.Crdp.Audits.CookieIssueDetails[];
-    sharedArrayBufferIssue: LH.Crdp.Audits.SharedArrayBufferIssueDetails[];
-    twaQualityEnforcement: LH.Crdp.Audits.TrustedWebActivityIssueDetails[];
+    attributionReportingIssue: Crdp.Audits.AttributionReportingIssueDetails[];
+    blockedByResponseIssue: Crdp.Audits.BlockedByResponseIssueDetails[];
+    clientHintIssue: Crdp.Audits.ClientHintIssueDetails[];
+    contentSecurityPolicyIssue: Crdp.Audits.ContentSecurityPolicyIssueDetails[];
+    corsIssue: Crdp.Audits.CorsIssueDetails[];
+    deprecationIssue: Crdp.Audits.DeprecationIssueDetails[];
+    federatedAuthRequestIssue: Crdp.Audits.FederatedAuthRequestIssueDetails[],
+    genericIssue: Crdp.Audits.GenericIssueDetails[];
+    heavyAdIssue: Crdp.Audits.HeavyAdIssueDetails[];
+    lowTextContrastIssue: Crdp.Audits.LowTextContrastIssueDetails[];
+    mixedContentIssue: Crdp.Audits.MixedContentIssueDetails[];
+    navigatorUserAgentIssue: Crdp.Audits.NavigatorUserAgentIssueDetails[];
+    quirksModeIssue: Crdp.Audits.QuirksModeIssueDetails[];
+    cookieIssue: Crdp.Audits.CookieIssueDetails[];
+    sharedArrayBufferIssue: Crdp.Audits.SharedArrayBufferIssueDetails[];
+    twaQualityEnforcement: Crdp.Audits.TrustedWebActivityIssueDetails[];
   }
 
   // Computed artifact types below.
@@ -881,7 +883,7 @@ declare module Artifacts {
     /** Time of the console log in milliseconds since epoch. */
     timestamp: number;
     /** The stack trace of the log/exception, if known. */
-    stackTrace?: LH.Crdp.Runtime.StackTrace;
+    stackTrace?: Crdp.Runtime.StackTrace;
     /** The URL of the log/exception, if known. */
     url?: string;
     /** The script id of the log/exception, if known. */
@@ -912,8 +914,8 @@ declare module Artifacts {
    * deprecations, violations, and more.
    */
   interface ConsoleProtocolLog extends BaseConsoleMessage {
-    source: LH.Crdp.Log.LogEntry['source'],
-    level: LH.Crdp.Log.LogEntry['level'],
+    source: Crdp.Log.LogEntry['source'],
+    level: Crdp.Log.LogEntry['level'],
     eventType: 'protocolLog';
   }
 

package/types/audit.d.ts

@@ -5,12 +5,12 @@
  */
 
 import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map.js';
-import {Artifacts} from './artifacts';
-import AuditDetails from './lhr/audit-details';
-import Config from './config';
-import Gatherer from './gatherer';
-import {IcuMessage} from './lhr/i18n';
-import * as AuditResult from './lhr/audit-result';
+import {Artifacts} from './artifacts.js';
+import AuditDetails from './lhr/audit-details.js';
+import Config from './config.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
+import * as AuditResult from './lhr/audit-result.js';
 import Util from './utility-types.js';
 
 declare module Audit {

package/types/config.d.ts

@@ -6,9 +6,9 @@
  */
 
 import {Audit} from '../core/audits/audit.js';
-import {SharedFlagsSettings, ConfigSettings} from './lhr/settings';
-import Gatherer from './gatherer';
-import {IcuMessage} from './lhr/i18n';
+import {SharedFlagsSettings, ConfigSettings} from './lhr/settings.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
 
 interface ClassOf<T> {
   new (): T;

package/types/externs.d.ts

@@ -4,9 +4,9 @@
  * 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 {Artifacts} from './artifacts';
-import LHResult from './lhr/lhr';
-import {SharedFlagsSettings, OutputMode} from './lhr/settings';
+import {Artifacts} from './artifacts.js';
+import LHResult from './lhr/lhr.js';
+import {SharedFlagsSettings, OutputMode} from './lhr/settings.js';
 
 /**
  * Extends the flags in SharedFlagsSettings with flags used to configure the
@@ -71,6 +71,10 @@ export interface CliFlags extends Flags {
 export interface RunnerResult {
   lhr: LHResult;
   report: string|string[];
+  /**
+   * @internal
+   * WARNING: Some artifacts are not guaranteed to be stable. The structure is subject to change in minor releases.
+   */
   artifacts: Artifacts;
 }
 

package/types/gatherer.d.ts

@@ -4,32 +4,38 @@
  * 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 {NetworkNode as _NetworkNode} from '../core/lib/dependency-graph/network-node';
-import {CPUNode as _CPUNode} from '../core/lib/dependency-graph/cpu-node';
-import {Simulator as _Simulator} from '../core/lib/dependency-graph/simulator/simulator';
-import {Driver} from '../core/legacy/gather/driver';
-import {ExecutionContext} from '../core/gather/driver/execution-context';
-import {Fetcher} from '../core/gather/fetcher';
-import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map';
-
-import {Artifacts, BaseArtifacts, FRBaseArtifacts, GathererArtifacts} from './artifacts';
-import Config from './config';
-import {IcuMessage} from './lhr/i18n';
-import Result from './lhr/lhr';
-import Protocol from './protocol';
-import {Trace, DevtoolsLog} from './artifacts';
+import {Protocol as Crdp} from 'devtools-protocol/types/protocol.js';
+import {ProtocolMapping as CrdpMappings} from 'devtools-protocol/types/protocol-mapping.js';
+
+import {NetworkNode as _NetworkNode} from '../core/lib/dependency-graph/network-node.js';
+import {CPUNode as _CPUNode} from '../core/lib/dependency-graph/cpu-node.js';
+import {Simulator as _Simulator} from '../core/lib/dependency-graph/simulator/simulator.js';
+import {Driver} from '../core/legacy/gather/driver.js';
+import {ExecutionContext} from '../core/gather/driver/execution-context.js';
+import {Fetcher} from '../core/gather/fetcher.js';
+import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map.js';
+
+import {Artifacts, BaseArtifacts, FRBaseArtifacts, GathererArtifacts, DevtoolsLog, Trace} from './artifacts.js';
+import Config from './config.js';
+import {IcuMessage} from './lhr/i18n.js';
+import Result from './lhr/lhr.js';
+import Protocol from './protocol.js';
+import Puppeteer from './puppeteer.js';
+
+type CrdpEvents = CrdpMappings.Events;
+type CrdpCommands = CrdpMappings.Commands;
 
 declare module Gatherer {
   /** The Lighthouse wrapper around a raw CDP session. */
   interface FRProtocolSession {
-    setTargetInfo(targetInfo: LH.Crdp.Target.TargetInfo): void;
+    setTargetInfo(targetInfo: Crdp.Target.TargetInfo): void;
     hasNextProtocolTimeout(): boolean;
     getNextProtocolTimeout(): number;
     setNextProtocolTimeout(ms: number): void;
-    on<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    once<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    off<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    sendCommand<TMethod extends keyof LH.CrdpCommands>(method: TMethod, ...params: LH.CrdpCommands[TMethod]['paramsType']): Promise<LH.CrdpCommands[TMethod]['returnType']>;
+    on<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    once<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    off<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    sendCommand<TMethod extends keyof CrdpCommands>(method: TMethod, ...params: CrdpCommands[TMethod]['paramsType']): Promise<CrdpCommands[TMethod]['returnType']>;
     dispose(): Promise<void>;
   }
 
@@ -53,7 +59,7 @@ declare module Gatherer {
     /** The connection to the page being analyzed. */
     driver: FRTransitionalDriver;
     /** The Puppeteer page handle. Will be undefined in legacy navigation mode. */
-    page?: LH.Puppeteer.Page;
+    page?: Puppeteer.Page;
     /** The set of base artifacts that are always collected. */
     baseArtifacts: FRBaseArtifacts;
     /** The cached results of computed artifacts. */
@@ -149,7 +155,7 @@ declare module Gatherer {
   type AnyFRGathererInstance = FRGathererInstanceExpander<Gatherer.DependencyKey>
 
   namespace Simulation {
-    type GraphNode = import('../core/lib/dependency-graph/base-node').Node;
+    type GraphNode = import('../core/lib/dependency-graph/base-node.js').Node;
     type GraphNetworkNode = _NetworkNode;
     type GraphCPUNode = _CPUNode;
     type Simulator = _Simulator;

package/types/internal/global.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright 2023 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 Most of our files use the global `LH` namespace to access our types.
+ * This file allows us to use the global namespace while iteratively converting files to use direct type imports.
+ * TODO: Remove this file and import all types directly.
+ */
+
+export * from '../lh.js';
+
+export as namespace LH;