lighthouse 9.6.8 → 10.0.0-dev.20230210

package/lighthouse-core/fraggle-rock/config/validation.js

@@ -1,313 +0,0 @@
-/**
- * @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.
- */
-'use strict';
-
-const Audit = require('../../audits/audit.js');
-const BaseFRGatherer = require('../gather/base-gatherer.js');
-const i18n = require('../../lib/i18n/i18n.js');
-
-/**
- * @param {LH.Config.GathererDefn | LH.Config.AnyFRGathererDefn} gathererDefn
- * @return {gathererDefn is LH.Config.AnyFRGathererDefn}
- */
-function isFRGathererDefn(gathererDefn) {
-  return 'meta' in gathererDefn.instance;
-}
-
-/**
- * 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}
- */
-function isValidArtifactDependency(dependent, dependency) {
-  const levels = {timespan: 0, snapshot: 1, navigation: 2};
-  const dependentLevel = Math.min(...dependent.instance.meta.supportedModes.map(l => levels[l]));
-  const dependencyLevel = Math.min(...dependency.instance.meta.supportedModes.map(l => levels[l]));
-
-  // A timespan artifact cannot depend on a snapshot/navigation artifact because it might run without a snapshot.
-  if (dependentLevel === levels.timespan) return dependencyLevel === levels.timespan;
-  // A snapshot artifact cannot depend on a timespan/navigation artifact because it might run without a timespan.
-  if (dependentLevel === levels.snapshot) return dependencyLevel === levels.snapshot;
-  // A navigation artifact can depend on anything.
-  return true;
-}
-
-/**
- * Throws if pluginName is invalid or (somehow) collides with a category in the
- * configJSON being added to.
- * @param {LH.Config.Json} configJSON
- * @param {string} pluginName
- */
-function assertValidPluginName(configJSON, pluginName) {
-  if (!pluginName.startsWith('lighthouse-plugin-')) {
-    throw new Error(`plugin name '${pluginName}' does not start with 'lighthouse-plugin-'`);
-  }
-
-  if (configJSON.categories?.[pluginName]) {
-    throw new Error(`plugin name '${pluginName}' not allowed because it is the id of a category already found in config`); // eslint-disable-line max-len
-  }
-}
-
-/**
- * Throws an error if the provided object does not implement the required Fraggle Rock gatherer interface.
- * @param {LH.Config.AnyFRGathererDefn} gathererDefn
- */
-function assertValidFRGatherer(gathererDefn) {
-  const gatherer = gathererDefn.instance;
-  const gathererName = gatherer.name;
-
-  if (typeof gatherer.meta !== 'object') {
-    throw new Error(`${gathererName} gatherer did not provide a meta object.`);
-  }
-
-  if (gatherer.meta.supportedModes.length === 0) {
-    throw new Error(`${gathererName} gatherer did not support any gather modes.`);
-  }
-
-  if (
-    typeof gatherer.getArtifact !== 'function' ||
-    gatherer.getArtifact === BaseFRGatherer.prototype.getArtifact
-  ) {
-    throw new Error(`${gathererName} gatherer did not define a "getArtifact" method.`);
-  }
-}
-
-/**
- * Throws an error if the provided object does not implement the required navigations interface.
- * @param {LH.Config.FRConfig['navigations']} navigationsDefn
- * @return {{warnings: string[]}}
- */
-function assertValidFRNavigations(navigationsDefn) {
-  if (!navigationsDefn || !navigationsDefn.length) return {warnings: []};
-
-  /** @type {string[]} */
-  const warnings = [];
-
-  // Assert that the first navigation has loadFailureMode fatal.
-  const firstNavigation = navigationsDefn[0];
-  if (firstNavigation.loadFailureMode !== 'fatal') {
-    const currentMode = firstNavigation.loadFailureMode;
-    const warning = [
-      `"${firstNavigation.id}" is the first navigation but had a failure mode of ${currentMode}.`,
-      `The first navigation will always be treated as loadFailureMode=fatal.`,
-    ].join(' ');
-
-    warnings.push(warning);
-    firstNavigation.loadFailureMode = 'fatal';
-  }
-
-  // Assert that navigations have unique IDs.
-  const navigationIds = navigationsDefn.map(navigation => navigation.id);
-  const duplicateId = navigationIds.find(
-    (id, i) => navigationIds.slice(i + 1).some(other => id === other)
-  );
-
-  if (duplicateId) {
-    throw new Error(`Navigation must have unique identifiers, but "${duplicateId}" was repeated.`);
-  }
-
-  return {warnings};
-}
-
-/**
- * Throws an error if the provided object does not implement the required properties of an audit
- * definition.
- * @param {LH.Config.AuditDefn} auditDefinition
- */
-function assertValidAudit(auditDefinition) {
-  const {implementation, path: auditPath} = auditDefinition;
-  const auditName = auditPath ||
-    implementation?.meta?.id ||
-    'Unknown audit';
-
-  if (typeof implementation.audit !== 'function' || implementation.audit === Audit.audit) {
-    throw new Error(`${auditName} has no audit() method.`);
-  }
-
-  if (typeof implementation.meta.id !== 'string') {
-    throw new Error(`${auditName} has no meta.id property, or the property is not a string.`);
-  }
-
-  if (!i18n.isStringOrIcuMessage(implementation.meta.title)) {
-    throw new Error(`${auditName} has no meta.title property, or the property is not a string.`);
-  }
-
-  // If it'll have a ✔ or ✖ displayed alongside the result, it should have failureTitle
-  const scoreDisplayMode = implementation.meta.scoreDisplayMode || Audit.SCORING_MODES.BINARY;
-  if (
-    !i18n.isStringOrIcuMessage(implementation.meta.failureTitle) &&
-    scoreDisplayMode === Audit.SCORING_MODES.BINARY
-  ) {
-    throw new Error(`${auditName} has no meta.failureTitle and should.`);
-  }
-
-  if (!i18n.isStringOrIcuMessage(implementation.meta.description)) {
-    throw new Error(
-      `${auditName} has no meta.description property, or the property is not a string.`
-    );
-  } else if (implementation.meta.description === '') {
-    throw new Error(
-      `${auditName} has an empty meta.description string. Please add a description for the UI.`
-    );
-  }
-
-  if (!Array.isArray(implementation.meta.requiredArtifacts)) {
-    throw new Error(
-      `${auditName} has no meta.requiredArtifacts property, or the property is not an array.`
-    );
-  }
-}
-
-/**
- * @param {LH.Config.FRConfig['categories']} categories
- * @param {LH.Config.FRConfig['audits']} audits
- * @param {LH.Config.FRConfig['groups']} groups
- */
-function assertValidCategories(categories, audits, groups) {
-  if (!categories) {
-    return;
-  }
-
-  /** @type {Map<string, LH.Config.AuditDefn>} */
-  const auditsKeyedById = new Map((audits || []).map(audit => {
-    return [audit.implementation.meta.id, audit];
-  }));
-
-  Object.keys(categories).forEach(categoryId => {
-    categories[categoryId].auditRefs.forEach((auditRef, index) => {
-      if (!auditRef.id) {
-        throw new Error(`missing an audit id at ${categoryId}[${index}]`);
-      }
-
-      const audit = auditsKeyedById.get(auditRef.id);
-      if (!audit) {
-        throw new Error(`could not find ${auditRef.id} audit for category ${categoryId}`);
-      }
-
-      const auditImpl = audit.implementation;
-      const isManual = auditImpl.meta.scoreDisplayMode === 'manual';
-      if (categoryId === 'accessibility' && !auditRef.group && !isManual) {
-        throw new Error(`${auditRef.id} accessibility audit does not have a group`);
-      }
-
-      if (auditRef.weight > 0 && isManual) {
-        throw new Error(`${auditRef.id} is manual but has a positive weight`);
-      }
-
-      if (auditRef.group && (!groups || !groups[auditRef.group])) {
-        throw new Error(`${auditRef.id} references unknown group ${auditRef.group}`);
-      }
-    });
-  });
-}
-
-/**
- * Validate the settings after they've been built.
- * @param {LH.Config.Settings} settings
- */
-function assertValidSettings(settings) {
-  if (!settings.formFactor) {
-    throw new Error(`\`settings.formFactor\` must be defined as 'mobile' or 'desktop'. See https://github.com/GoogleChrome/lighthouse/blob/master/docs/emulation.md`);
-  }
-
-  if (!settings.screenEmulation.disabled) {
-    // formFactor doesn't control emulation. So we don't want a mismatch:
-    //   Bad mismatch A: user wants mobile emulation but scoring is configured for desktop
-    //   Bad mismtach B: user wants everything desktop and set formFactor, but accidentally not screenEmulation
-    if (settings.screenEmulation.mobile !== (settings.formFactor === 'mobile')) {
-      throw new Error(`Screen emulation mobile setting (${settings.screenEmulation.mobile}) does not match formFactor setting (${settings.formFactor}). See https://github.com/GoogleChrome/lighthouse/blob/master/docs/emulation.md`);
-    }
-  }
-}
-
-/**
- * Asserts that artifacts are in a valid dependency order that can be computed.
- *
- * @param {Array<LH.Config.NavigationDefn>} navigations
- */
-function assertArtifactTopologicalOrder(navigations) {
-  const availableArtifacts = new Set();
-
-  for (const navigation of navigations) {
-    for (const artifact of navigation.artifacts) {
-      availableArtifacts.add(artifact.id);
-      if (!artifact.dependencies) continue;
-
-      for (const [dependencyKey, {id: dependencyId}] of Object.entries(artifact.dependencies)) {
-        if (availableArtifacts.has(dependencyId)) continue;
-        throwInvalidDependencyOrder(artifact.id, dependencyKey);
-      }
-    }
-  }
-}
-
-/**
- * @param {LH.Config.FRConfig} config
- * @return {{warnings: string[]}}
- */
-function assertValidConfig(config) {
-  const {warnings} = assertValidFRNavigations(config.navigations);
-
-  for (const artifactDefn of config.artifacts || []) {
-    assertValidFRGatherer(artifactDefn.gatherer);
-  }
-
-  for (const auditDefn of config.audits || []) {
-    assertValidAudit(auditDefn);
-  }
-
-  assertValidCategories(config.categories, config.audits, config.groups);
-  assertValidSettings(config.settings);
-  return {warnings};
-}
-
-/**
- * @param {string} artifactId
- * @param {string} dependencyKey
- * @return {never}
- */
-function throwInvalidDependencyOrder(artifactId, dependencyKey) {
-  throw new Error(
-    [
-      `Failed to find dependency "${dependencyKey}" for "${artifactId}" artifact`,
-      `Check that...`,
-      `  1. A gatherer exposes a matching Symbol that satisfies "${dependencyKey}".`,
-      `  2. "${dependencyKey}" is configured to run before "${artifactId}"`,
-    ].join('\n')
-  );
-}
-
-/**
- * @param {string} artifactId
- * @param {string} dependencyKey
- * @return {never}
- */
-function throwInvalidArtifactDependency(artifactId, dependencyKey) {
-  throw new Error(
-    [
-      `Dependency "${dependencyKey}" for "${artifactId}" artifact is invalid.`,
-      `The dependency must be collected before the dependent.`,
-    ].join('\n')
-  );
-}
-
-module.exports = {
-  isFRGathererDefn,
-  isValidArtifactDependency,
-  assertValidPluginName,
-  assertValidFRGatherer,
-  assertValidFRNavigations,
-  assertValidAudit,
-  assertValidCategories,
-  assertValidSettings,
-  assertArtifactTopologicalOrder,
-  assertValidConfig,
-  throwInvalidDependencyOrder,
-  throwInvalidArtifactDependency,
-};

package/lighthouse-core/fraggle-rock/gather/base-artifacts.js

@@ -1,99 +0,0 @@
-/**
- * @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.
- */
-'use strict';
-
-const log = require('lighthouse-logger');
-const isDeepEqual = require('lodash/isEqual.js');
-const {
-  getBrowserVersion,
-  getBenchmarkIndex,
-  getEnvironmentWarnings,
-} = require('../../gather/driver/environment.js');
-
-/**
- * @param {LH.Config.FRConfig} config
- * @param {LH.Gatherer.FRTransitionalDriver} driver
- * @param {{gatherMode: LH.Gatherer.GatherMode}} context
- * @return {Promise<LH.BaseArtifacts>}
- */
-async function getBaseArtifacts(config, driver, context) {
-  const BenchmarkIndex = await getBenchmarkIndex(driver.executionContext);
-  const {userAgent} = await getBrowserVersion(driver.defaultSession);
-
-  return {
-    // Meta artifacts.
-    fetchTime: new Date().toJSON(),
-    Timing: [],
-    LighthouseRunWarnings: [],
-    settings: config.settings,
-    // Environment artifacts that can always be computed.
-    BenchmarkIndex,
-    HostUserAgent: userAgent,
-    HostFormFactor: userAgent.includes('Android') || userAgent.includes('Mobile') ?
-      'mobile' : 'desktop',
-    // Contextual artifacts whose collection changes based on gather mode.
-    URL: {requestedUrl: '', finalUrl: ''},
-    PageLoadError: null,
-    GatherContext: context,
-    // Artifacts that have been replaced by regular gatherers in Fraggle Rock.
-    Stacks: [],
-    NetworkUserAgent: '',
-    WebAppManifest: null,
-    InstallabilityErrors: {errors: []},
-    traces: {},
-    devtoolsLogs: {},
-  };
-}
-
-/**
- * Deduplicates identical warnings.
- * @param {Array<string | LH.IcuMessage>} warnings
- * @return {Array<string | LH.IcuMessage>}
- */
-function deduplicateWarnings(warnings) {
-  /** @type {Array<string | LH.IcuMessage>} */
-  const unique = [];
-
-  for (const warning of warnings) {
-    if (unique.some(existing => isDeepEqual(warning, existing))) continue;
-    unique.push(warning);
-  }
-
-  return unique;
-}
-
-/**
- * @param {LH.FRBaseArtifacts} baseArtifacts
- * @param {Partial<LH.Artifacts>} gathererArtifacts
- * @return {LH.Artifacts}
- */
-function finalizeArtifacts(baseArtifacts, gathererArtifacts) {
-  const warnings = baseArtifacts.LighthouseRunWarnings
-    .concat(gathererArtifacts.LighthouseRunWarnings || [])
-    .concat(getEnvironmentWarnings({settings: baseArtifacts.settings, baseArtifacts}));
-
-  // Cast to remove the partial from gathererArtifacts.
-  const artifacts = /** @type {LH.Artifacts} */ ({...baseArtifacts, ...gathererArtifacts});
-
-  // Set the post-run meta artifacts.
-  artifacts.Timing = log.getTimeEntries();
-  artifacts.LighthouseRunWarnings = deduplicateWarnings(warnings);
-
-  if (artifacts.PageLoadError && !artifacts.URL.finalUrl) {
-    artifacts.URL.finalUrl = artifacts.URL.requestedUrl;
-  }
-
-  // Check that the runner remembered to mutate the special-case URL artifact.
-  if (!artifacts.URL.requestedUrl) throw new Error('Runner did not set requestedUrl');
-  if (!artifacts.URL.finalUrl) throw new Error('Runner did not set finalUrl');
-
-  return artifacts;
-}
-
-module.exports = {
-  getBaseArtifacts,
-  finalizeArtifacts,
-};

package/lighthouse-core/fraggle-rock/gather/base-gatherer.js

@@ -1,107 +0,0 @@
-/**
- * @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.
- */
-'use strict';
-
-/* eslint-disable no-unused-vars */
-
-/**
- * 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 lighthouse-core/gather/gatherers/gatherer.js for legacy method explanations.
- *
- * @implements {LH.Gatherer.GathererInstance}
- * @implements {LH.Gatherer.FRGathererInstance}
- */
-class FRGatherer {
-  /** @type {LH.Gatherer.GathererMeta} */
-  meta = {supportedModes: []};
-
-  /**
-   * Method to start observing a page for an arbitrary period of time.
-   * @param {LH.Gatherer.FRTransitionalContext} passContext
-   * @return {Promise<void>|void}
-   */
-  startInstrumentation(passContext) { }
-
-  /**
-   * 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) { }
-
-  /**
-   * 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) { }
-
-  /**
-   * Method to end observing a page after an arbitrary period of time.
-   * @param {LH.Gatherer.FRTransitionalContext} passContext
-   * @return {Promise<void>|void}
-   */
-  stopInstrumentation(passContext) { }
-
-  /**
-   * Method to gather results about a page.
-   * @param {LH.Gatherer.FRTransitionalContext} passContext
-   * @return {LH.Gatherer.PhaseResult}
-   */
-  getArtifact(passContext) { }
-
-  /**
-   * Legacy property used to define the artifact ID. In Fraggle Rock, the artifact ID lives on the config.
-   * @return {keyof LH.GathererArtifacts}
-   */
-  get name() {
-    let name = this.constructor.name;
-    // Rollup will mangle class names in an known way–just trim until `$`.
-    if (name.includes('$')) {
-      name = name.substr(0, name.indexOf('$'));
-    }
-    // @ts-expect-error - assume that class name has been added to LH.GathererArtifacts.
-    return name;
-  }
-
-  /**
-   * Legacy method. Called before navigation to target url, roughly corresponds to `startInstrumentation`.
-   * @param {LH.Gatherer.PassContext} passContext
-   * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
-   */
-  async beforePass(passContext) {
-    await this.startInstrumentation({...passContext, dependencies: {}});
-    await this.startSensitiveInstrumentation({...passContext, dependencies: {}});
-  }
-
-  /**
-   * 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) { }
-
-  /**
-   * 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>}
-   */
-  async afterPass(passContext, loadData) {
-    if ('dependencies' in this.meta) {
-      throw Error('Gatherer with dependencies should override afterPass');
-    }
-    await this.stopSensitiveInstrumentation({...passContext, dependencies: {}});
-    await this.stopInstrumentation({...passContext, dependencies: {}});
-    return this.getArtifact({...passContext, dependencies: {}});
-  }
-}
-
-module.exports = FRGatherer;

package/lighthouse-core/fraggle-rock/gather/driver.js

@@ -1,88 +0,0 @@
-/**
- * @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.
- */
-'use strict';
-
-const log = require('lighthouse-logger');
-const ProtocolSession = require('./session.js');
-const ExecutionContext = require('../../gather/driver/execution-context.js');
-const Fetcher = require('../../gather/fetcher.js');
-
-/** @return {*} */
-const throwNotConnectedFn = () => {
-  throw new Error('Session not connected');
-};
-
-/** @type {LH.Gatherer.FRProtocolSession} */
-const defaultSession = {
-  setTargetInfo: throwNotConnectedFn,
-  hasNextProtocolTimeout: throwNotConnectedFn,
-  getNextProtocolTimeout: throwNotConnectedFn,
-  setNextProtocolTimeout: throwNotConnectedFn,
-  on: throwNotConnectedFn,
-  once: throwNotConnectedFn,
-  off: throwNotConnectedFn,
-  addProtocolMessageListener: throwNotConnectedFn,
-  removeProtocolMessageListener: throwNotConnectedFn,
-  addSessionAttachedListener: throwNotConnectedFn,
-  removeSessionAttachedListener: throwNotConnectedFn,
-  sendCommand: throwNotConnectedFn,
-  dispose: throwNotConnectedFn,
-};
-
-/** @implements {LH.Gatherer.FRTransitionalDriver} */
-class Driver {
-  /**
-   * @param {import('puppeteer').Page} page
-   */
-  constructor(page) {
-    this._page = page;
-    /** @type {LH.Gatherer.FRProtocolSession|undefined} */
-    this._session = undefined;
-    /** @type {ExecutionContext|undefined} */
-    this._executionContext = undefined;
-    /** @type {Fetcher|undefined} */
-    this._fetcher = undefined;
-
-    this.defaultSession = defaultSession;
-  }
-
-  /** @return {LH.Gatherer.FRTransitionalDriver['executionContext']} */
-  get executionContext() {
-    if (!this._executionContext) return throwNotConnectedFn();
-    return this._executionContext;
-  }
-
-  /** @return {Fetcher} */
-  get fetcher() {
-    if (!this._fetcher) return throwNotConnectedFn();
-    return this._fetcher;
-  }
-
-  /** @return {Promise<string>} */
-  async url() {
-    return this._page.url();
-  }
-
-  /** @return {Promise<void>} */
-  async connect() {
-    if (this._session) return;
-    const status = {msg: 'Connecting to browser', id: 'lh:driver:connect'};
-    log.time(status);
-    const session = await this._page.target().createCDPSession();
-    this._session = this.defaultSession = new ProtocolSession(session);
-    this._executionContext = new ExecutionContext(this._session);
-    this._fetcher = new Fetcher(this._session, this._executionContext);
-    log.timeEnd(status);
-  }
-
-  /** @return {Promise<void>} */
-  async disconnect() {
-    if (!this._session) return;
-    await this._session.dispose();
-  }
-}
-
-module.exports = Driver;