lighthouse 9.6.8 → 10.0.0-dev.20230209

package/core/lib/lh-error.js

@@ -0,0 +1,425 @@
+/**
+ * @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.
+ */
+
+import * as i18n from './i18n/i18n.js';
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /**
+   * @description Error message explaining that the Lighthouse run was not able to collect screenshots through Chrome.
+   * @example {NO_SPEEDLINE_FRAMES} errorCode
+   * */
+  didntCollectScreenshots: `Chrome didn't collect any screenshots during the page load. Please make sure there is content visible on the page, and then try re-running Lighthouse. ({errorCode})`,
+  /**
+   * @description Error message explaining that the performance trace was not able to be recorded for the Lighthouse run.
+   * @example {NO_TRACING_STARTED} errorCode
+   * */
+  badTraceRecording: 'Something went wrong with recording the trace over your page load. Please run Lighthouse again. ({errorCode})',
+  /**
+   * @description Error message explaining that the First Contentful Paint metric was not seen during the page load.
+   * @example {NO_FCP} errorCode
+   * */
+  noFcp: 'The page did not paint any content. Please ensure you keep the browser window in the foreground during the load and try again. ({errorCode})',
+  /**
+   * @description Error message explaining that the Largest Contentful Paint metric was not seen during the page load.
+   * @example {NO_LCP} errorCode
+   * */
+  noLcp: 'The page did not display content that qualifies as a Largest Contentful Paint (LCP). Ensure the page has a valid LCP element and then try again. ({errorCode})',
+  /**
+   * @description Error message explaining that the page loaded too slowly to perform a Lighthouse run.
+   * @example {NO_TTI_CPU_IDLE_PERIOD} errorCode
+   * */
+  pageLoadTookTooLong: 'Your page took too long to load. Please follow the opportunities in the report to reduce your page load time, and then try re-running Lighthouse. ({errorCode})',
+  /** Error message explaining that Lighthouse could not load the requested URL and the steps that might be taken to fix the unreliability. */
+  pageLoadFailed: 'Lighthouse was unable to reliably load the page you requested. Make sure you are testing the correct URL and that the server is properly responding to all requests.',
+  /**
+   * @description Error message explaining that Lighthouse could not load the requested URL and the steps that might be taken to fix the unreliability.
+   * @example {404} statusCode
+   * */
+  pageLoadFailedWithStatusCode: 'Lighthouse was unable to reliably load the page you requested. Make sure you are testing the correct URL and that the server is properly responding to all requests. (Status code: {statusCode})',
+  /**
+   * @description Error message explaining that Lighthouse could not load the requested URL and the steps that might be taken to fix the unreliability.
+   * @example {FAILED_DOCUMENT_REQUEST} errorDetails
+   * */
+  pageLoadFailedWithDetails: 'Lighthouse was unable to reliably load the page you requested. Make sure you are testing the correct URL and that the server is properly responding to all requests. (Details: {errorDetails})',
+  /**
+   * @description Error message explaining that the security certificate of the page Lighthouse observed was invalid, so the URL cannot be accessed. securityMessages will be replaced with one or more strings from the browser explaining what was insecure about the page load.
+   * @example {net::ERR_CERT_DATE_INVALID} securityMessages
+   * */
+  pageLoadFailedInsecure: 'The URL you have provided does not have a valid security certificate. {securityMessages}',
+  /** Error message explaining that Chrome prevented the page from loading and displayed an interstitial screen instead, so the URL cannot be accessed. */
+  pageLoadFailedInterstitial: 'Chrome prevented page load with an interstitial. Make sure you are testing the correct URL and that the server is properly responding to all requests.',
+  /** Error message explaining that Chrome has encountered an error during the Lighthouse run, and that Chrome should be restarted. */
+  internalChromeError: 'An internal Chrome error occurred. Please restart Chrome and try re-running Lighthouse.',
+  /** Error message explaining that fetching the resources of the webpage has taken longer than the maximum time. */
+  requestContentTimeout: 'Fetching resource content has exceeded the allotted time',
+  /**
+   * @description Error message explaining that the webpage is non-HTML, so audits are ill-defined.
+   * @example {application/xml} mimeType
+   * */
+  notHtml: 'The page provided is not HTML (served as MIME type {mimeType}).',
+  /** Error message explaining that the provided URL Lighthouse points to is not valid, and cannot be loaded. */
+  urlInvalid: 'The URL you have provided appears to be invalid.',
+  /**
+   * @description Error message explaining that the Chrome Devtools protocol has exceeded the maximum timeout allowed.
+   * @example {Network.enable} protocolMethod
+   * */
+  protocolTimeout: 'Waiting for DevTools protocol response has exceeded the allotted time. (Method: {protocolMethod})',
+  /** Error message explaining that the requested page could not be resolved by the DNS server. */
+  dnsFailure: 'DNS servers could not resolve the provided domain.',
+  /** Error message explaining that Lighthouse couldn't complete because the page has stopped responding to its instructions. */
+  pageLoadFailedHung: 'Lighthouse was unable to reliably load the URL you requested because the page stopped responding.',
+  /** Error message explaining that Lighthouse timed out while waiting for the initial connection to the Chrome Devtools protocol. */
+  criTimeout: 'Timeout waiting for initial Debugger Protocol connection.',
+  /**
+   * @description Error message explaining that a resource that was required for testing was never collected. "artifactName" will be replaced with the name of the resource that wasn't collected.
+   * @example {WebAppManifest} artifactName
+   * */
+  missingRequiredArtifact: 'Required {artifactName} gatherer did not run.',
+  /**
+   * @description Error message explaining that there was an error while trying to collect a resource that was required for testing. "artifactName" will be replaced with the name of the resource that wasn't collected; "errorMessage" will be replaced with a string description of the error that occurred.
+   * @example {WebAppManifest} artifactName
+   * @example {Manifest invalid} errorMessage
+   * */
+  erroredRequiredArtifact: 'Required {artifactName} gatherer encountered an error: {errorMessage}',
+
+  /**
+   * @description Error message explaining that a feature is unavailable due to an old version of Chrome. "featureName" will be replaced by the name of the feature which is not supported.
+   * @example {Largest Contentful Paint} featureName
+   * */
+  oldChromeDoesNotSupportFeature: 'This version of Chrome is too old to support \'{featureName}\'. Use a newer version to see full results.',
+};
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+
+/**
+ * @typedef LighthouseErrorDefinition
+ * @property {string} code
+ * @property {string} message
+ * @property {RegExp} [pattern]
+ * @property {boolean} [lhrRuntimeError] True if it should appear in the top-level LHR.runtimeError property.
+ */
+
+const LHERROR_SENTINEL = '__LighthouseErrorSentinel';
+const ERROR_SENTINEL = '__ErrorSentinel';
+/**
+ * @typedef {{sentinel: '__LighthouseErrorSentinel', code: string, stack?: string, [p: string]: string|undefined}} SerializedLighthouseError
+ * @typedef {{sentinel: '__ErrorSentinel', message: string, code?: string, stack?: string}} SerializedBaseError
+ */
+
+class LighthouseError extends Error {
+  /**
+   * @param {LighthouseErrorDefinition} errorDefinition
+   * @param {Record<string, string|undefined>=} properties
+   */
+  constructor(errorDefinition, properties) {
+    super(errorDefinition.code);
+    this.name = 'LighthouseError';
+    this.code = errorDefinition.code;
+    // Add additional properties to be ICU replacements in the error string.
+    // `code` is always added as `errorCode` so callers don't need to specify the code multiple times.
+    this.friendlyMessage = str_(errorDefinition.message, {errorCode: this.code, ...properties});
+    this.lhrRuntimeError = !!errorDefinition.lhrRuntimeError;
+    if (properties) Object.assign(this, properties);
+
+    Error.captureStackTrace(this, LighthouseError);
+  }
+
+  /**
+   * @param {string} method
+   * @param {{message: string, data?: string|undefined}} protocolError
+   * @return {Error|LighthouseError}
+   */
+  static fromProtocolMessage(method, protocolError) {
+    // extract all errors with a regex pattern to match against.
+    // if we find one, use the friendly LighthouseError definition
+    const matchedErrorDefinition = Object.values(LighthouseError.errors)
+      .filter(e => e.pattern)
+      .find(e => e.pattern && e.pattern.test(protocolError.message));
+    if (matchedErrorDefinition) {
+      return new LighthouseError(matchedErrorDefinition);
+    }
+
+    // otherwise fallback to building a generic Error
+    let errMsg = `(${method}): ${protocolError.message}`;
+    if (protocolError.data) errMsg += ` (${protocolError.data})`;
+    const error = new Error(`Protocol error ${errMsg}`);
+    return Object.assign(error, {protocolMethod: method, protocolError: protocolError.message});
+  }
+
+  /**
+   * A JSON.stringify replacer to serialize LighthouseErrors and (as a fallback) Errors.
+   * Returns a simplified version of the error object that can be reconstituted
+   * as a copy of the original error at parse time.
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter
+   * @param {Error|LighthouseError} err
+   * @return {SerializedBaseError|SerializedLighthouseError}
+   */
+  static stringifyReplacer(err) {
+    if (err instanceof LighthouseError) {
+      // Remove class props so that remaining values were what was passed in as `properties`.
+      // eslint-disable-next-line no-unused-vars
+      const {name, code, message, friendlyMessage, lhrRuntimeError, stack, ...properties} = err;
+
+      return {
+        sentinel: LHERROR_SENTINEL,
+        code,
+        stack,
+        ...properties,
+      };
+    }
+
+    // Unexpected errors won't be LighthouseErrors, but we want them serialized as well.
+    if (err instanceof Error) {
+      const {message, stack} = err;
+      // @ts-expect-error - code can be helpful for e.g. node errors, so preserve it if it's present.
+      const code = err.code;
+      return {
+        sentinel: ERROR_SENTINEL,
+        message,
+        code,
+        stack,
+      };
+    }
+
+    throw new Error('Invalid value for LighthouseError stringification');
+  }
+
+  /**
+   * A JSON.parse reviver. If any value passed in is a serialized Error or
+   * LighthouseError, the error is recreated as the original object. Otherwise, the
+   * value is passed through unchanged.
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_the_reviver_parameter
+   * @param {string} key
+   * @param {any} possibleError
+   * @return {any}
+   */
+  static parseReviver(key, possibleError) {
+    if (typeof possibleError === 'object' && possibleError !== null) {
+      if (possibleError.sentinel === LHERROR_SENTINEL) {
+        // Include sentinel in destructuring so it doesn't end up in `properties`.
+        // eslint-disable-next-line no-unused-vars
+        const {sentinel, code, stack, ...properties} = /** @type {SerializedLighthouseError} */ (possibleError);
+        const errorDefinition = LighthouseError.errors[/** @type {keyof typeof ERRORS} */ (code)];
+        const lhError = new LighthouseError(errorDefinition, properties);
+        lhError.stack = stack;
+
+        return lhError;
+      }
+
+      if (possibleError.sentinel === ERROR_SENTINEL) {
+        const {message, code, stack} = /** @type {SerializedBaseError} */ (possibleError);
+        const error = new Error(message);
+        Object.assign(error, {code, stack});
+        return error;
+      }
+    }
+
+    return possibleError;
+  }
+}
+
+const ERRORS = {
+  // Screenshot/speedline errors
+  NO_SPEEDLINE_FRAMES: {
+    code: 'NO_SPEEDLINE_FRAMES',
+    message: UIStrings.didntCollectScreenshots,
+    lhrRuntimeError: true,
+  },
+  SPEEDINDEX_OF_ZERO: {
+    code: 'SPEEDINDEX_OF_ZERO',
+    message: UIStrings.didntCollectScreenshots,
+    lhrRuntimeError: true,
+  },
+  NO_SCREENSHOTS: {
+    code: 'NO_SCREENSHOTS',
+    message: UIStrings.didntCollectScreenshots,
+    lhrRuntimeError: true,
+  },
+  INVALID_SPEEDLINE: {
+    code: 'INVALID_SPEEDLINE',
+    message: UIStrings.didntCollectScreenshots,
+    lhrRuntimeError: true,
+  },
+
+  // Trace parsing errors
+  NO_TRACING_STARTED: {
+    code: 'NO_TRACING_STARTED',
+    message: UIStrings.badTraceRecording,
+    lhrRuntimeError: true,
+  },
+  NO_RESOURCE_REQUEST: {
+    code: 'NO_RESOURCE_REQUEST',
+    message: UIStrings.badTraceRecording,
+    lhrRuntimeError: true,
+  },
+  NO_NAVSTART: {
+    code: 'NO_NAVSTART',
+    message: UIStrings.badTraceRecording,
+    lhrRuntimeError: true,
+  },
+  NO_FCP: {
+    code: 'NO_FCP',
+    message: UIStrings.noFcp,
+    lhrRuntimeError: true,
+  },
+  NO_DCL: {
+    code: 'NO_DCL',
+    message: UIStrings.badTraceRecording,
+    lhrRuntimeError: true,
+  },
+  NO_FMP: {
+    code: 'NO_FMP',
+    message: UIStrings.badTraceRecording,
+  },
+  NO_LCP: {
+    code: 'NO_LCP',
+    message: UIStrings.noLcp,
+  },
+  NO_LCP_ALL_FRAMES: {
+    code: 'NO_LCP_ALL_FRAMES',
+    message: UIStrings.noLcp,
+  },
+  UNSUPPORTED_OLD_CHROME: {
+    code: 'UNSUPPORTED_OLD_CHROME',
+    message: UIStrings.oldChromeDoesNotSupportFeature,
+  },
+
+  // TTI calculation failures
+  NO_TTI_CPU_IDLE_PERIOD: {code: 'NO_TTI_CPU_IDLE_PERIOD', message: UIStrings.pageLoadTookTooLong},
+  NO_TTI_NETWORK_IDLE_PERIOD: {
+    code: 'NO_TTI_NETWORK_IDLE_PERIOD',
+    message: UIStrings.pageLoadTookTooLong,
+  },
+
+  // Page load failures
+  NO_DOCUMENT_REQUEST: {
+    code: 'NO_DOCUMENT_REQUEST',
+    message: UIStrings.pageLoadFailed,
+    lhrRuntimeError: true,
+  },
+  /* Used when DevTools reports loading failed. Usually an internal (Chrome) issue.
+   * Requries an additional `errorDetails` field for translation.
+   */
+  FAILED_DOCUMENT_REQUEST: {
+    code: 'FAILED_DOCUMENT_REQUEST',
+    message: UIStrings.pageLoadFailedWithDetails,
+    lhrRuntimeError: true,
+  },
+  /* Used when status code is 4xx or 5xx.
+   * Requires an additional `statusCode` field for translation.
+   */
+  ERRORED_DOCUMENT_REQUEST: {
+    code: 'ERRORED_DOCUMENT_REQUEST',
+    message: UIStrings.pageLoadFailedWithStatusCode,
+    lhrRuntimeError: true,
+  },
+  /* Used when security error prevents page load.
+   * Requires an additional `securityMessages` field for translation.
+   */
+  INSECURE_DOCUMENT_REQUEST: {
+    code: 'INSECURE_DOCUMENT_REQUEST',
+    message: UIStrings.pageLoadFailedInsecure,
+    lhrRuntimeError: true,
+  },
+  /* Used when any Chrome interstitial error prevents page load.
+   */
+  CHROME_INTERSTITIAL_ERROR: {
+    code: 'CHROME_INTERSTITIAL_ERROR',
+    message: UIStrings.pageLoadFailedInterstitial,
+    lhrRuntimeError: true,
+  },
+  /* Used when the page stopped responding and did not finish loading. */
+  PAGE_HUNG: {
+    code: 'PAGE_HUNG',
+    message: UIStrings.pageLoadFailedHung,
+    lhrRuntimeError: true,
+  },
+  /* Used when the page is non-HTML. */
+  NOT_HTML: {
+    code: 'NOT_HTML',
+    message: UIStrings.notHtml,
+    lhrRuntimeError: true,
+  },
+
+  // Protocol internal failures
+  TRACING_ALREADY_STARTED: {
+    code: 'TRACING_ALREADY_STARTED',
+    message: UIStrings.internalChromeError,
+    pattern: /Tracing.*started/,
+    lhrRuntimeError: true,
+  },
+  PARSING_PROBLEM: {
+    code: 'PARSING_PROBLEM',
+    message: UIStrings.internalChromeError,
+    pattern: /Parsing problem/,
+    lhrRuntimeError: true,
+  },
+  READ_FAILED: {
+    code: 'READ_FAILED',
+    message: UIStrings.internalChromeError,
+    pattern: /Read failed/,
+    lhrRuntimeError: true,
+  },
+
+  // URL parsing failures
+  INVALID_URL: {
+    code: 'INVALID_URL',
+    message: UIStrings.urlInvalid,
+  },
+
+  /* Protocol timeout failures
+   * Requires an additional `protocolMethod` field for translation.
+   */
+  PROTOCOL_TIMEOUT: {
+    code: 'PROTOCOL_TIMEOUT',
+    message: UIStrings.protocolTimeout,
+    lhrRuntimeError: true,
+  },
+
+  // DNS failure on main document (no resolution, timed out, etc)
+  DNS_FAILURE: {
+    code: 'DNS_FAILURE',
+    message: UIStrings.dnsFailure,
+    lhrRuntimeError: true,
+  },
+
+  /** A timeout in the initial connection to the debugger protocol. */
+  CRI_TIMEOUT: {
+    code: 'CRI_TIMEOUT',
+    message: UIStrings.criTimeout,
+    lhrRuntimeError: true,
+  },
+
+  /**
+   * Error internal to Runner used when an artifact required for an audit is missing.
+   * Requires an additional `artifactName` field for translation.
+  */
+  MISSING_REQUIRED_ARTIFACT: {
+    code: 'MISSING_REQUIRED_ARTIFACT',
+    message: UIStrings.missingRequiredArtifact,
+  },
+
+  /**
+   * Error internal to Runner used when an artifact required for an audit was an error.
+   * Requires additional `artifactName` and `errorMessage` fields for translation.
+  */
+  ERRORED_REQUIRED_ARTIFACT: {
+    code: 'ERRORED_REQUIRED_ARTIFACT',
+    message: UIStrings.erroredRequiredArtifact,
+  },
+
+  // Hey! When adding a new error type, update lighthouse-result.proto too.
+  // Only necessary for runtime errors, which come from artifacts or pageLoadErrors.
+};
+
+/** @type {Record<keyof typeof ERRORS, LighthouseErrorDefinition>} */
+LighthouseError.errors = ERRORS;
+LighthouseError.NO_ERROR = 'NO_ERROR';
+LighthouseError.UNKNOWN_ERROR = 'UNKNOWN_ERROR';
+
+export {LighthouseError, UIStrings};

package/core/lib/lh-trace-processor.d.ts

@@ -0,0 +1,5 @@
+export default LHTraceProcessor;
+declare class LHTraceProcessor extends TraceProcessor {
+}
+import { TraceProcessor } from "../lib/tracehouse/trace-processor.js";
+//# sourceMappingURL=lh-trace-processor.d.ts.map

package/core/lib/lh-trace-processor.js

@@ -0,0 +1,45 @@
+/**
+ * @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.
+ */
+
+import {LighthouseError} from '../lib/lh-error.js';
+import {TraceProcessor} from '../lib/tracehouse/trace-processor.js';
+
+// TraceProcessor throws generic errors, but we'd like our special localized and code-specific LighthouseError
+// objects to be thrown instead.
+class LHTraceProcessor extends TraceProcessor {
+  /**
+   * @return {Error}
+   */
+  static createNoNavstartError() {
+    return new LighthouseError(LighthouseError.errors.NO_NAVSTART);
+  }
+
+  /**
+   * This isn't currently used, but will be when the time origin of trace processing is changed.
+   * @see {TraceProcessor.computeTimeOrigin}
+   * @see https://github.com/GoogleChrome/lighthouse/pull/11253#discussion_r507985527
+   * @return {Error}
+   */
+  static createNoResourceSendRequestError() {
+    return new LighthouseError(LighthouseError.errors.NO_RESOURCE_REQUEST);
+  }
+
+  /**
+   * @return {Error}
+   */
+  static createNoTracingStartedError() {
+    return new LighthouseError(LighthouseError.errors.NO_TRACING_STARTED);
+  }
+
+  /**
+   * @return {Error}
+   */
+  static createNoFirstContentfulPaintError() {
+    return new LighthouseError(LighthouseError.errors.NO_FCP);
+  }
+}
+
+export default LHTraceProcessor;

package/core/lib/lighthouse-compatibility.d.ts

@@ -0,0 +1,8 @@
+export type ItemValueType = import('../../types/lhr/audit-details').default.ItemValueType;
+/** @typedef {import('../../types/lhr/audit-details').default.ItemValueType} ItemValueType */
+/**
+ * Upgrades an lhr object in-place to account for changes in the data structure over major versions.
+ * @param {LH.Result} lhr
+ */
+export function upgradeLhrForCompatibility(lhr: LH.Result): void;
+//# sourceMappingURL=lighthouse-compatibility.d.ts.map

package/core/lib/lighthouse-compatibility.js

@@ -0,0 +1,139 @@
+/**
+ * @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.
+ */
+
+import {Util} from '../../shared/util.js';
+
+const SCREENSHOT_PREFIX = 'data:image/jpeg;base64,';
+
+/** @typedef {import('../../types/lhr/audit-details').default.ItemValueType} ItemValueType */
+
+/**
+ * Upgrades an lhr object in-place to account for changes in the data structure over major versions.
+ * @param {LH.Result} lhr
+ */
+function upgradeLhrForCompatibility(lhr) {
+  // If LHR is older (≤3.0.3), it has no locale setting. Set default.
+  if (!lhr.configSettings.locale) {
+    lhr.configSettings.locale = 'en';
+  }
+  if (!lhr.configSettings.formFactor) {
+    // @ts-expect-error fallback handling for emulatedFormFactor
+    lhr.configSettings.formFactor = lhr.configSettings.emulatedFormFactor;
+  }
+
+  lhr.finalDisplayedUrl = Util.getFinalDisplayedUrl(lhr);
+  lhr.mainDocumentUrl = Util.getMainDocumentUrl(lhr);
+
+  for (const audit of Object.values(lhr.audits)) {
+    // Turn 'not-applicable' (LHR <4.0) and 'not_applicable' (older proto versions)
+    // into 'notApplicable' (LHR ≥4.0).
+    // @ts-expect-error tsc rightly flags that these values shouldn't occur.
+    // eslint-disable-next-line max-len
+    if (audit.scoreDisplayMode === 'not_applicable' || audit.scoreDisplayMode === 'not-applicable') {
+      audit.scoreDisplayMode = 'notApplicable';
+    }
+
+    if (audit.details) {
+      // Turn `auditDetails.type` of undefined (LHR <4.2) and 'diagnostic' (LHR <5.0)
+      // into 'debugdata' (LHR ≥5.0).
+      // @ts-expect-error tsc rightly flags that these values shouldn't occur.
+      if (audit.details.type === undefined || audit.details.type === 'diagnostic') {
+        // @ts-expect-error details is of type never.
+        audit.details.type = 'debugdata';
+      }
+
+      // Add the jpg data URL prefix to filmstrip screenshots without them (LHR <5.0).
+      if (audit.details.type === 'filmstrip') {
+        for (const screenshot of audit.details.items) {
+          if (!screenshot.data.startsWith(SCREENSHOT_PREFIX)) {
+            screenshot.data = SCREENSHOT_PREFIX + screenshot.data;
+          }
+        }
+      }
+
+      // Circa 10.0, table items were refactored.
+      if (audit.details.type === 'table') {
+        for (const heading of audit.details.headings) {
+          /** @type {{itemType: ItemValueType|undefined, text: string|undefined}} */
+          // @ts-expect-error
+          const {itemType, text} = heading;
+          if (itemType !== undefined) {
+            heading.valueType = itemType;
+            // @ts-expect-error
+            delete heading.itemType;
+          }
+          if (text !== undefined) {
+            heading.label = text;
+            // @ts-expect-error
+            delete heading.text;
+          }
+
+          // @ts-expect-error
+          const subItemsItemType = heading.subItemsHeading?.itemType;
+          if (heading.subItemsHeading && subItemsItemType !== undefined) {
+            heading.subItemsHeading.valueType = subItemsItemType;
+            // @ts-expect-error
+            delete heading.subItemsHeading.itemType;
+          }
+        }
+      }
+
+      // TODO: convert printf-style displayValue.
+      // Added:   #5099, v3
+      // Removed: #6767, v4
+    }
+  }
+
+  // This backcompat converts old LHRs (<9.0.0) to use the new "hidden" group.
+  // Old LHRs used "no group" to identify audits that should be hidden in performance instead of the "hidden" group.
+  // Newer LHRs use "no group" to identify opportunities and diagnostics whose groups are assigned by details type.
+  const [majorVersion] = lhr.lighthouseVersion.split('.').map(Number);
+  const perfCategory = lhr.categories['performance'];
+  if (majorVersion < 9 && perfCategory) {
+    if (!lhr.categoryGroups) lhr.categoryGroups = {};
+    lhr.categoryGroups['hidden'] = {title: ''};
+    for (const auditRef of perfCategory.auditRefs) {
+      if (!auditRef.group) {
+        auditRef.group = 'hidden';
+      } else if (['load-opportunities', 'diagnostics'].includes(auditRef.group)) {
+        delete auditRef.group;
+      }
+    }
+  }
+
+  // Add some minimal stuff so older reports still work.
+  if (!lhr.environment) {
+    // @ts-expect-error
+    lhr.environment = {benchmarkIndex: 0};
+  }
+  if (!lhr.configSettings.screenEmulation) {
+    // @ts-expect-error
+    lhr.configSettings.screenEmulation = {};
+  }
+  if (!lhr.i18n) {
+    // @ts-expect-error
+    lhr.i18n = {};
+  }
+
+  // In 10.0, full-page-screenshot became a top-level property on the LHR.
+  if (lhr.audits['full-page-screenshot']) {
+    const details = /** @type {LH.Result.FullPageScreenshot=} */ (
+      lhr.audits['full-page-screenshot'].details);
+    if (details) {
+      lhr.fullPageScreenshot = {
+        screenshot: details.screenshot,
+        nodes: details.nodes,
+      };
+    } else {
+      lhr.fullPageScreenshot = null;
+    }
+    delete lhr.audits['full-page-screenshot'];
+  }
+}
+
+export {
+  upgradeLhrForCompatibility,
+};