lighthouse 13.5.0 → 13.6.0-dev.20261028

package/core/computed/lcp-network-record.js

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {makeComputedArtifact} from './computed-artifact.js';
+import {NetworkRecords} from './network-records.js';
+import {ProcessedNavigation} from './processed-navigation.js';
+import {LighthouseError} from '../lib/lh-error.js';
+
+/**
+ * @fileoverview Match the LCP event with the paint event to get the request of the image actually painted.
+ * This could differ from the `ImageElement` associated with the nodeId if e.g. the LCP
+ * was a pseudo-element associated with a node containing a smaller background-image.
+ */
+
+class LCPNetworkRecord {
+  /**
+   * @param {{trace: LH.Trace, devtoolsLog: LH.DevtoolsLog}} data
+   * @param {LH.Artifacts.ComputedContext} context
+   * @return {Promise<LH.Artifacts.NetworkRequest|undefined>}
+   */
+  static async compute_(data, context) {
+    const {trace, devtoolsLog} = data;
+    const networkRecords = await NetworkRecords.request(devtoolsLog, context);
+    const processedNavigation = await ProcessedNavigation.request(trace, context);
+    if (processedNavigation.timings.largestContentfulPaint === undefined) {
+      throw new LighthouseError(LighthouseError.errors.NO_LCP);
+    }
+
+    // Use main-frame-only LCP to match the metric value.
+    const lcpEvent = processedNavigation.largestContentfulPaintEvt;
+    if (!lcpEvent) return;
+
+    const lcpImagePaintEvent = trace.traceEvents.filter(e => {
+      return e.name === 'LargestImagePaint::Candidate' &&
+          e.args.frame === lcpEvent.args.frame &&
+          e.args.data?.DOMNodeId === lcpEvent.args.data?.nodeId &&
+          e.args.data?.size === lcpEvent.args.data?.size;
+    // Get last candidate, in case there was more than one.
+    }).sort((a, b) => b.ts - a.ts)[0];
+
+    const lcpUrl = lcpImagePaintEvent?.args.data?.imageUrl;
+    if (!lcpUrl) return;
+
+    const candidates = networkRecords.filter(record => {
+      return record.url === lcpUrl &&
+          record.finished &&
+          // Same frame as LCP trace event.
+          record.frameId === lcpImagePaintEvent.args.frame &&
+          record.networkRequestTime < (processedNavigation.timestamps.largestContentfulPaint || 0);
+    }).map(record => {
+      // Follow any redirects to find the real image request.
+      while (record.redirectDestination) {
+        record = record.redirectDestination;
+      }
+      return record;
+    }).filter(record => {
+      // Don't select if also loaded by some other means (xhr, etc). `resourceType`
+      // isn't set on redirect _sources_, so have to check after following redirects.
+      return record.resourceType === 'Image' || record.resourceType === 'Media';
+    });
+
+    // If there are still multiple candidates, at this point it appears the page
+    // simply made multiple requests for the image. The first loaded is the best
+    // guess of the request that made the image available for use.
+    return candidates.sort((a, b) => a.networkEndTime - b.networkEndTime)[0];
+  }
+}
+
+const LCPNetworkRecordComputed = makeComputedArtifact(LCPNetworkRecord, ['devtoolsLog', 'trace']);
+export {LCPNetworkRecordComputed as LCPNetworkRecord};
+

package/core/computed/metrics/lantern-metric.js

@@ -40,7 +40,7 @@ async function getComputationDataParamsFromTrace(data, context) {
   const traceEngineResult = await TraceEngineResult.request(data, context);
   const frameId = traceEngineResult.data.Meta.mainFrameId;
   const navigation =
-    traceEngineResult.data.Meta.mainFrameNavigations[0];
+    traceEngineResult.data.Meta.mainFrameNavigations.at(-1);
   if (!navigation) {
     throw new Error(`Lantern metrics could not be calculated due to missing navigation id`);
   }

package/core/computed/metrics/lcp-breakdown.js

@@ -9,7 +9,7 @@ import {LighthouseError} from '../../lib/lh-error.js';
 import {LargestContentfulPaint} from './largest-contentful-paint.js';
 import {ProcessedNavigation} from '../processed-navigation.js';
 import {TimeToFirstByte} from './time-to-first-byte.js';
-import {LCPImageRecord} from '../lcp-image-record.js';
+import {LCPNetworkRecord} from '../lcp-network-record.js';
 import {NavigationInsights} from '../navigation-insights.js';
 
 /**
@@ -32,7 +32,7 @@ class LCPBreakdown {
 
       const {timing: ttfb} = await TimeToFirstByte.request(data, context);
 
-      const lcpRecord = await LCPImageRecord.request(data, context);
+      const lcpRecord = await LCPNetworkRecord.request(data, context);
       if (!lcpRecord) {
         return {ttfb};
       }
@@ -42,15 +42,15 @@ class LCPBreakdown {
       const throttleRatio = metricLcp / observedLcp;
 
       const unclampedLoadStart = (lcpRecord.networkRequestTime - timeOrigin) * throttleRatio;
-      const loadDelay = Math.max(ttfb, Math.min(unclampedLoadStart, metricLcp));
+      const loadStart = Math.max(ttfb, Math.min(unclampedLoadStart, metricLcp));
 
       const unclampedLoadEnd = (lcpRecord.networkEndTime - timeOrigin) * throttleRatio;
-      const loadDuration = Math.max(loadDelay, Math.min(unclampedLoadEnd, metricLcp));
+      const loadEnd = Math.max(loadStart, Math.min(unclampedLoadEnd, metricLcp));
 
       return {
         ttfb,
-        loadDelay,
-        loadDuration,
+        loadDelay: loadStart - ttfb,
+        loadDuration: loadEnd - loadStart,
       };
     }
 

package/core/computed/metrics/time-to-first-byte.js

@@ -6,6 +6,7 @@
 
 import {calculateDocFirstByteTs} from '@paulirish/trace_engine/models/trace/insights/Common.js';
 
+import {Helpers} from '../../lib/trace-engine.js';
 import {makeComputedArtifact} from '../computed-artifact.js';
 import {NavigationMetric} from './navigation-metric.js';
 import {MainResource} from '../main-resource.js';
@@ -52,15 +53,16 @@ class TimeToFirstByte extends NavigationMetric {
       await NavigationInsights.request({trace, settings, SourceMaps, HostDPR}, context);
     const lcpBreakdown = navInsights.model.LCPBreakdown;
 
+    const navigationId = Helpers.Trace.navigationIDForEvent(navInsights.navigation);
+
     // Defer to LCP breakdown, but if there's no LCP fallback to manual calculation.
     if (lcpBreakdown && !(lcpBreakdown instanceof Error) && lcpBreakdown.subparts) {
       return {
         timing: lcpBreakdown.subparts.ttfb.range / 1000,
         timestamp: lcpBreakdown.subparts.ttfb.max,
       };
-    } else if (navInsights.navigation?.args.data?.navigationId) {
-      const request = traceEngineResult.data.NetworkRequests.byId.get(
-        navInsights.navigation.args.data.navigationId);
+    } else if (navInsights.navigation && navigationId) {
+      const request = traceEngineResult.data.NetworkRequests.byId.get(navigationId);
       if (!request) {
         throw new Error();
       }

package/core/computed/navigation-insights.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import {Helpers} from '../lib/trace-engine.js';
 import {makeComputedArtifact} from './computed-artifact.js';
 import {ProcessedTrace} from './processed-trace.js';
 import {TraceEngineResult} from './trace-engine-result.js';
@@ -26,8 +27,8 @@ class NavigationInsights {
     const navigationId = processedTrace.timeOriginEvt.args.data?.navigationId;
     if (!navigationId) throw new Error('No navigationId found');
 
-    const navInsights = [...traceEngineResult.insights.values()]
-        .find(insightSet => insightSet.navigation?.args.data?.navigationId === navigationId);
+    const navInsights = [...traceEngineResult.insights.values()].find(insightSet =>
+      Helpers.Trace.navigationIDForEvent(insightSet.navigation) === navigationId);
     if (!navInsights) throw new Error('No navigations insights found');
 
     return navInsights;

package/core/computed/page-dependency-graph.js

@@ -11,6 +11,26 @@ import {ProcessedTrace} from './processed-trace.js';
 import {NetworkRecords} from './network-records.js';
 import {TraceEngineResult} from './trace-engine-result.js';
 
+/**
+ * ResourceSendRequest URLs in the trace retain #hash fragments, whereas CDP
+ * Network.requestWillBeSent, Page.frameNavigated, initiator.url, documentURL,
+ * and V8 script events strip #hash fragments, and Lantern's NetworkAnalyzer
+ * requires request.url not to have a fragment.
+ * TODO: Remove once @paulirish/trace_engine includes the fix in LanternComputationData.
+ * @param {string} urlStr
+ * @return {string}
+ */
+function stripUrlHash(urlStr) {
+  if (!urlStr.includes('#')) return urlStr;
+  try {
+    const url = new URL(urlStr);
+    url.hash = '';
+    return url.href;
+  } catch {
+    return urlStr;
+  }
+}
+
 class PageDependencyGraph {
   /**
    * @param {{trace: LH.Trace, devtoolsLog: LH.DevtoolsLog, settings: LH.Audit.Context['settings'], URL: LH.Artifacts['URL'], SourceMaps: LH.Artifacts['SourceMaps'], HostDPR: LH.Artifacts['HostDPR'], fromTrace: boolean}} data
@@ -27,7 +47,41 @@ class PageDependencyGraph {
     if (data.fromTrace) {
       const traceEngineResult =
         await TraceEngineResult.request({trace, settings, SourceMaps, HostDPR}, context);
-      const parsedTrace = traceEngineResult.data;
+      let parsedTrace = traceEngineResult.data;
+      if (parsedTrace.NetworkRequests.byTime.some(
+        r => r.args.data.url.includes('#') ||
+          r.args.data.redirects.some(red => red.url.includes('#'))
+      )) {
+        const byTime = parsedTrace.NetworkRequests.byTime.map(request => {
+          const url = stripUrlHash(request.args.data.url);
+          const redirects = request.args.data.redirects.map(redirect => ({
+            ...redirect,
+            url: stripUrlHash(redirect.url),
+          }));
+          if (url === request.args.data.url &&
+              redirects.every((red, i) => red.url === request.args.data.redirects[i].url)) {
+            return request;
+          }
+          return {
+            ...request,
+            args: {
+              ...request.args,
+              data: {
+                ...request.args.data,
+                url,
+                redirects,
+              },
+            },
+          };
+        });
+        parsedTrace = {
+          ...parsedTrace,
+          NetworkRequests: {
+            ...parsedTrace.NetworkRequests,
+            byTime,
+          },
+        };
+      }
       const requests =
         Lantern.TraceEngineComputationData.createNetworkRequests(trace, parsedTrace);
       const graph =
@@ -36,10 +90,6 @@ class PageDependencyGraph {
       return graph;
     }
 
-    // TODO: currently the trace version has no requests that failed, or requests that have "Preflight".
-    //       so the following gets the devtools log version _closer_ to the exact same results as the trace.
-    // const lanternRequests = networkRecords.map(NetworkRequest.asLanternNetworkRequest).filter(r => !r.failed && r.resourceType !== 'Preflight');
-
     const lanternRequests = networkRecords.map(NetworkRequest.asLanternNetworkRequest);
     return Lantern.Graph.PageDependencyGraph.createGraph(mainThreadEvents, lanternRequests, URL);
   }

package/core/computed/speedline.js

@@ -20,13 +20,10 @@ class Speedline {
     // speedline() may throw without a promise, so we resolve immediately
     // to get in a promise chain.
     return ProcessedTrace.request(trace, context).then(processedTrace => {
-      // Use a shallow copy of traceEvents so speedline can sort as it pleases.
-      // See https://github.com/GoogleChrome/lighthouse/issues/2333
-      const traceEvents = trace.traceEvents.slice();
       // Force use of timeOrigin as reference point for speedline
       // See https://github.com/GoogleChrome/lighthouse/issues/2095
       const timeOrigin = processedTrace.timestamps.timeOrigin;
-      return speedline(traceEvents, {
+      return speedline(trace.traceEvents, {
         timeOrigin,
         fastMode: true,
         include: 'speedIndex',
@@ -46,7 +43,25 @@ class Speedline {
         throw new LighthouseError(LighthouseError.errors.SPEEDINDEX_OF_ZERO);
       }
 
-      return speedline;
+      // Evict the ~1 MB per-frame decoded RGBA buffers and histograms cached inside
+      // speedline-core's frame closures, keeping only the getters Lighthouse uses.
+      // TODO(https://github.com/paulirish/speedline/issues/122): Upstream to speedline-core
+      // so `frame()` in `lib/frame.js` does not cache `_parsedImage` on frame closures.
+      const frames = speedline.frames.map(frame => {
+        const imgBuff = frame.getImage();
+        const timeStamp = frame.getTimeStamp();
+        const isProgressInterpolated = frame.isProgressInterpolated();
+        return {
+          getImage: () => imgBuff,
+          getTimeStamp: () => timeStamp,
+          isProgressInterpolated: () => isProgressInterpolated,
+        };
+      });
+
+      return {
+        ...speedline,
+        frames,
+      };
     });
   }
 }

package/core/computed/trace-engine-result.js

@@ -7,6 +7,7 @@
 import log from 'lighthouse-logger';
 
 import * as i18n from '../lib/i18n/i18n.js';
+import * as Lantern from '../lib/lantern/lantern.js';
 import * as TraceEngine from '../lib/trace-engine.js';
 import {makeComputedArtifact} from './computed-artifact.js';
 import {CumulativeLayoutShift} from './metrics/cumulative-layout-shift.js';
@@ -26,7 +27,9 @@ class TraceEngineResult {
    * @return {Promise<LH.Artifacts.TraceEngineResult>}
    */
   static async runTraceEngine(_traceEvents, settings, SourceMaps, HostDPR) {
-    const processor = new TraceEngine.TraceProcessor(TraceEngine.TraceHandlers);
+    const config = TraceEngine.Types.Configuration.defaults();
+    config.enableSoftNavigation = false;
+    const processor = new TraceEngine.TraceProcessor(TraceEngine.TraceHandlers, config);
     const traceEvents =
       /** @type {import('@paulirish/trace_engine').Types.Events.Event[]} */ (_traceEvents);
 
@@ -66,8 +69,20 @@ class TraceEngineResult {
     });
     if (!processor.data) throw new Error('No data');
     if (!processor.insights) throw new Error('No insights');
-    this.localizeInsights(processor.insights);
-    return {data: processor.data, insights: processor.insights};
+    const data = processor.data;
+    const insights = processor.insights;
+    this.localizeInsights(insights);
+
+    // Release intermediate handler state retained in module-level TraceHandlers singletons
+    // and static Lantern simulation node timings after trace processing completes.
+    for (const handler of Object.values(TraceEngine.TraceHandlers)) {
+      handler.reset();
+    }
+    if (!process.env.LANTERN_DEBUG) {
+      Lantern.Simulation.Simulator.allNodeTimings.clear();
+    }
+
+    return {data, insights};
   }
 
   /**
@@ -236,8 +251,9 @@ class TraceEngineResult {
     const layoutShiftEvents = new Set(
       CumulativeLayoutShift.getLayoutShiftEvents(processedTrace).map(e => e.event));
 
-    // Avoid modifying the input array.
-    const traceEvents = [...data.trace.traceEvents];
+    // Avoid modifying the input array, copying only if an event is modified.
+    let traceEvents = data.trace.traceEvents;
+    let copied = false;
     for (let i = 0; i < traceEvents.length; i++) {
       let event = traceEvents[i];
       if (event.name !== 'LayoutShift') continue;
@@ -245,6 +261,10 @@ class TraceEngineResult {
 
       const isConsidered = layoutShiftEvents.has(event);
       if (event.args.data.had_recent_input && isConsidered) {
+        if (!copied) {
+          traceEvents = [...traceEvents];
+          copied = true;
+        }
         event = JSON.parse(JSON.stringify(event));
         // @ts-expect-error impossible for data to be missing.
         event.args.data.had_recent_input = false;

package/core/computed/unused-css.js

@@ -66,8 +66,21 @@ class UnusedCSS {
     let usedUncompressedBytes = 0;
     const totalUncompressedBytes = stylesheetInfo.content.length;
 
-    for (const usedRule of stylesheetInfo.usedRules) {
-      usedUncompressedBytes += usedRule.endOffset - usedRule.startOffset;
+    // CSS rule usage tracking can return overlapping ranges (e.g. a nested rule inside its
+    // parent rule's range) or duplicate ranges (parent rules are emitted once per used child rule).
+    // Sort and merge overlapping ranges so used bytes are only counted once.
+    const usedRules = stylesheetInfo.usedRules
+      .slice()
+      .sort((a, b) => a.startOffset - b.startOffset);
+
+    let lastEndOffset = -1;
+    for (const usedRule of usedRules) {
+      if (usedRule.endOffset <= lastEndOffset) {
+        continue;
+      }
+      const startOffset = Math.max(usedRule.startOffset, lastEndOffset);
+      usedUncompressedBytes += usedRule.endOffset - startOffset;
+      lastEndOffset = usedRule.endOffset;
     }
 
     const compressedSize = estimateCompressedContentSize(

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

@@ -1,6 +1,8 @@
 export type GathererConstructor = typeof import("../gather/base-gatherer.js").default;
 export type Audit = typeof import("../audits/audit.js")["Audit"];
 export type Gatherer = InstanceType<GathererConstructor>;
+/** @type {Map<string, Promise<any>>} */
+export const bundledModules: Map<string, Promise<any>>;
 /**
  * // TODO(bckenny): could adopt "jsonified" type to ensure T will survive JSON
  * round trip: https://github.com/Microsoft/TypeScript/issues/21838
@@ -33,6 +35,9 @@ export const mergeConfigFragment: LH.Config.Merge;
  * @return {Array<T>}
  */
 export function mergeConfigFragmentArrayByKey<T extends Record<string, any>>(baseArray: Array<T> | null | undefined, extensionArray: Array<T> | null | undefined, keyFn: (item: T) => string): Array<T>;
+/** @typedef {typeof import('../gather/base-gatherer.js').default} GathererConstructor */
+/** @typedef {typeof import('../audits/audit.js')['Audit']} Audit */
+/** @typedef {InstanceType<GathererConstructor>} Gatherer */
 /**
  * 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

package/core/config/config-helpers.js

@@ -7,15 +7,13 @@ import path from 'path';
 import {createRequire} from 'module';
 import url from 'url';
 
-import {isEqual} from 'lodash-es';
-
 import * as LH from '../../types/lh.js';
 import * as constants from './constants.js';
 import ConfigPlugin from './config-plugin.js';
 import {Runner} from '../runner.js';
 import * as i18n from '../lib/i18n/i18n.js';
 import * as validation from './validation.js';
-import {getModuleDirectory} from '../../shared/esm-utils.js';
+import {isEqual} from '../lib/arbitrary-equality-map.js';
 
 const require = createRequire(import.meta.url);
 
@@ -23,21 +21,6 @@ const require = createRequire(import.meta.url);
 /** @typedef {typeof import('../audits/audit.js')['Audit']} Audit */
 /** @typedef {InstanceType<GathererConstructor>} Gatherer */
 
-function isBundledEnvironment() {
-  // If we're in DevTools or LightRider, we are definitely bundled.
-  // TODO: refactor and delete `global.isDevtools`.
-  if (global.isDevtools || global.isLightrider) return true;
-
-  try {
-    // Not foolproof, but `lighthouse-logger` is a dependency of lighthouse that should always be resolvable.
-    // `require.resolve` will only throw in atypical/bundled environments.
-    require.resolve('lighthouse-logger');
-    return false;
-  } catch (err) {
-    return true;
-  }
-}
-
 /**
  * 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
@@ -226,6 +209,8 @@ async function requireWrapper(requirePath) {
   let module;
   if (bundledModules.has(requirePath)) {
     module = await bundledModules.get(requirePath);
+  } else if (bundledModules.size > 0) {
+    throw new Error(`Unable to locate module '${requirePath}' in bundled Lighthouse`);
   } else if (requirePath.match(/\.(js|mjs|cjs)$/)) {
     module = await import(requirePath);
   } else {
@@ -285,18 +270,12 @@ function requireAudit(auditPath, coreAuditList, configDir) {
   const coreAudit = coreAuditList.find(a => a === auditPathJs);
   let requirePath = `../audits/${auditPath}`;
   if (!coreAudit) {
-    if (isBundledEnvironment()) {
+    if (bundledModules.has(auditPath)) {
       // This is for plugin bundling.
       requirePath = auditPath;
     } else {
       // Otherwise, attempt to find it elsewhere. This throws if not found.
-      const absolutePath = resolveModulePath(auditPath, configDir, 'audit');
-      if (isBundledEnvironment()) {
-        // Use a relative path so bundler can easily expose it.
-        requirePath = path.relative(getModuleDirectory(import.meta), absolutePath);
-      } else {
-        requirePath = absolutePath;
-      }
+      requirePath = resolveModulePath(auditPath, configDir, 'audit');
     }
   }
 
@@ -370,11 +349,16 @@ async function mergePlugins(config, configDir, flags) {
   const flagPlugins = flags?.plugins || [];
   const pluginNames = new Set([...configPlugins, ...flagPlugins]);
 
+  const configLocales = config.locales;
+  if (configLocales) {
+    delete config.locales;
+  }
+
   for (const pluginName of pluginNames) {
     validation.assertValidPluginName(config, pluginName);
 
     // In bundled contexts, `resolveModulePath` will fail, so use the raw pluginName directly.
-    const pluginPath = isBundledEnvironment() ?
+    const pluginPath = bundledModules.has(pluginName) ?
         pluginName :
         resolveModulePath(pluginName, configDir, 'plugin');
     const rawPluginJson = await requireWrapper(pluginPath);
@@ -383,6 +367,10 @@ async function mergePlugins(config, configDir, flags) {
     config = mergeConfigFragment(config, pluginJson);
   }
 
+  if (configLocales) {
+    config.locales = mergeConfigFragment(config.locales, configLocales);
+  }
+
   return config;
 }
 
@@ -513,7 +501,7 @@ function resolveModulePath(moduleIdentifier, configDir, category) {
   const errorString = 'Unable to locate ' + (category ? `${category}: ` : '') +
     `\`${moduleIdentifier}\`.
      Tried to resolve the module from these locations:
-       ${getModuleDirectory(import.meta)}
+       ${import.meta.dirname}
        ${cwdPath}`;
 
   if (!configDir) {
@@ -606,6 +594,7 @@ function deepCloneConfigJson(json) {
 }
 
 export {
+  bundledModules,
   deepClone,
   deepCloneConfigJson,
   mergeConfigFragment,

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

@@ -34,6 +34,13 @@ declare class ConfigPlugin {
      * @return {Record<string, LH.Config.GroupJson>|undefined}
      */
     static _parseGroups(groupsJson: unknown, pluginName: string): Record<string, LH.Config.GroupJson> | undefined;
+    /**
+     * Extract and validate locales JSON added by the plugin.
+     * @param {unknown} localesJson
+     * @param {string} pluginName
+     * @return {NonNullable<LH.Config['locales']>|undefined}
+     */
+    static _parseLocales(localesJson: unknown, pluginName: string): NonNullable<LH.Config["locales"]> | undefined;
     /**
      * Extracts and validates a config from the provided plugin input, throwing
      * if it deviates from the expected object shape.

package/core/config/config-plugin.js

@@ -215,6 +215,53 @@ class ConfigPlugin {
     return parsedGroupsJson;
   }
 
+  /**
+   * Extract and validate locales JSON added by the plugin.
+   * @param {unknown} localesJson
+   * @param {string} pluginName
+   * @return {NonNullable<LH.Config['locales']>|undefined}
+   */
+  static _parseLocales(localesJson, pluginName) {
+    if (localesJson === undefined) {
+      return undefined;
+    }
+
+    if (!isObjectOfUnknownProperties(localesJson)) {
+      throw new Error(`${pluginName} locales json is not defined as an object.`);
+    }
+
+    /** @type {NonNullable<LH.Config['locales']>} */
+    const parsedLocalesJson = {};
+    for (const [locale, localeMessagesJson] of Object.entries(localesJson)) {
+      if (!isObjectOfUnknownProperties(localeMessagesJson)) {
+        throw new Error(`${pluginName} has a locale (${locale}) not defined as an object.`);
+      }
+
+      /** @type {Record<string, {message: string}>} */
+      const parsedMessages = {};
+      for (const [icuMessageId, messageEntry] of Object.entries(localeMessagesJson)) {
+        if (!isObjectOfUnknownProperties(messageEntry)) {
+          throw new Error(
+            `${pluginName} has a locale message (${icuMessageId}) not defined as an object.`
+          );
+        }
+
+        const {message, ...invalidRest} = messageEntry;
+        assertNoExcessProperties(invalidRest, pluginName, 'locale message');
+
+        if (typeof message !== 'string') {
+          throw new Error(`${pluginName} has an invalid locale message (${icuMessageId}).`);
+        }
+
+        parsedMessages[icuMessageId] = {message};
+      }
+
+      parsedLocalesJson[/** @type {LH.Locale} */ (locale)] = parsedMessages;
+    }
+
+    return parsedLocalesJson;
+  }
+
   /**
    * Extracts and validates a config from the provided plugin input, throwing
    * if it deviates from the expected object shape.
@@ -233,6 +280,7 @@ class ConfigPlugin {
       audits: pluginAuditsJson,
       category: pluginCategoryJson,
       groups: pluginGroupsJson,
+      locales: pluginLocalesJson,
       ...invalidRest
     } = pluginJson;
 
@@ -244,6 +292,7 @@ class ConfigPlugin {
         [pluginName]: ConfigPlugin._parseCategory(pluginCategoryJson, pluginName),
       },
       groups: ConfigPlugin._parseGroups(pluginGroupsJson, pluginName),
+      locales: ConfigPlugin._parseLocales(pluginLocalesJson, pluginName),
     };
   }
 }

package/core/config/config.js

@@ -28,11 +28,10 @@ import {
   mergeConfigFragment,
   mergeConfigFragmentArrayByKey,
 } from './config-helpers.js';
-import {getModuleDirectory} from '../../shared/esm-utils.js';
 import * as format from '../../shared/localization/format.js';
 
 const defaultConfigPath = path.join(
-  getModuleDirectory(import.meta),
+  import.meta.dirname,
   '../../config/default-config.js'
 );
 
@@ -164,6 +163,7 @@ async function resolveArtifactsToDefns(artifacts, configDir) {
       id: artifactJson.id,
       gatherer,
       dependencies: resolveArtifactDependencies(artifactJson, gatherer, artifactDefnsBySymbol),
+      alwaysGather: artifactJson.alwaysGather,
     };
 
     const symbol = artifact.gatherer.instance.meta.symbol;
@@ -230,6 +230,14 @@ async function initializeConfig(gatherMode, config, flags = {}) {
   configWorkingCopy = resolveExtensions(configWorkingCopy);
   configWorkingCopy = await mergePlugins(configWorkingCopy, configDir, flags);
 
+  if (configWorkingCopy.locales) {
+    for (const [locale, lhlMessages] of Object.entries(configWorkingCopy.locales)) {
+      if (lhlMessages) {
+        format.registerLocaleData(/** @type {LH.Locale} */ (locale), lhlMessages);
+      }
+    }
+  }
+
   const settings = resolveSettings(configWorkingCopy.settings || {}, flags);
   overrideSettingsForGatherMode(settings, gatherMode);
   overrideThrottlingWindows(settings);