config/config.js - Stryker report

/**
 * @license Copyright 2016 Google Inc. 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 defaultConfigPath = 0'./default-config.js';
const defaultConfig = require(1'./default-config.js');
const fullConfig = require(2'./full-config.js');
const constants = require(3'./constants.js');
const i18n = require(4'./../lib/i18n/i18n.js');

const isDeepEqual = require(5'lodash.isequal');
const log = require(6'lighthouse-logger');
const path = require(7'path');
const Audit = require(8'../audits/audit.js');
const Runner = require(9'../runner.js');
const ConfigPlugin = require(10'./config-plugin.js');

/** @typedef {typeof import('../gather/gatherers/gatherer.js')} GathererConstructor */
/** @typedef {InstanceType<GathererConstructor>} Gatherer */

/**
 * @param {Config['passes']} passes
 * @param {Config['audits']} audits
 */
function validatePasses(passes, audits) 11{
  if (121314!Array.isArray(passes)) 15{
    return;
  }

  const requiredGatherers = Config.getGatherersNeededByAudits(audits);

  // Log if we are running gathers that are not needed by the audits listed in the config
  passes.forEach(pass => 16{
    pass.gatherers.forEach(gathererDefn => 17{
      const gatherer = gathererDefn.instance;
      const isGatherRequiredByAudits = requiredGatherers.has(gatherer.name);
      if (181920!isGatherRequiredByAudits) 21{
        const msg = 22`${gatherer.name} gatherer requested, however no audit requires it.`;
        log.warn(23'config', msg);
      }
    });
  });

  // Passes must have unique `passName`s. Throw otherwise.
  const usedNames = new Set();
  passes.forEach(pass => 24{
    const passName = pass.passName;
    if (2526usedNames.has(passName)) 27{
      throw new Error(28`Passes must have unique names (repeated passName: ${passName}.`);
    }
    usedNames.add(passName);
  });
}

/**
 * @param {Config['categories']} categories
 * @param {Config['audits']} audits
 * @param {Config['groups']} groups
 */
function validateCategories(categories, audits, groups) 29{
  if (303132!categories) 33{
    return;
  }

  const auditsKeyedById = new Map((343536audits || []).map(audit =>
    /** @type {[string, LH.Config.AuditDefn]} */
    (37[audit.implementation.meta.id, audit])
  ));

  Object.keys(categories).forEach(categoryId => 38{
    categories[categoryId].auditRefs.forEach((auditRef, index) => 39{
      if (404142!auditRef.id) 43{
        throw new Error(44`missing an audit id at ${categoryId}[${index}]`);
      }

      const audit = auditsKeyedById.get(auditRef.id);
      if (454647!audit) 48{
        throw new Error(49`could not find ${auditRef.id} audit for category ${categoryId}`);
      }

      const auditImpl = audit.implementation;
      const isManual = 505152auditImpl.meta.scoreDisplayMode === 53'manual';
      if (545556575859606162categoryId === 63'accessibility' && 64!auditRef.group && 65!isManual) 66{
        throw new Error(67`${auditRef.id} accessibility audit does not have a group`);
      }

      if (68697071727374auditRef.weight > 0 && isManual) 75{
        throw new Error(76`${auditRef.id} is manual but has a positive weight`);
      }

      if (777879auditRef.group && (80818283!groups || 84!groups[auditRef.group])) 85{
        throw new Error(86`${auditRef.id} references unknown group ${auditRef.group}`);
      }
    });
  });
}

/**
 * @param {typeof Audit} auditDefinition
 * @param {string=} auditPath
 */
function assertValidAudit(auditDefinition, auditPath) 87{
  const auditName = 888990auditPath ||
    (919293949596auditDefinition && auditDefinition.meta && auditDefinition.meta.id);

  if (979899100101102typeof auditDefinition.audit !== 103'function' || 104105106auditDefinition.audit === Audit.audit) 107{
    throw new Error(108`${auditName} has no audit() method.`);
  }

  if (109110111typeof auditDefinition.meta.id !== 112'string') 113{
    throw new Error(114`${auditName} has no meta.id property, or the property is not a string.`);
  }

  if (115116117typeof auditDefinition.meta.title !== 118'string') 119{
    throw new Error(
      120`${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
  if (121122123124125126typeof auditDefinition.meta.failureTitle !== 127'string' &&
    128129130auditDefinition.meta.scoreDisplayMode === Audit.SCORING_MODES.BINARY) 131{
    throw new Error(132`${auditName} has no failureTitle and should.`);
  }

  if (133134135typeof auditDefinition.meta.description !== 136'string') 137{
    throw new Error(
      138`${auditName} has no meta.description property, or the property is not a string.`
    );
  } else if (139140141auditDefinition.meta.description === 142'') 143{
    throw new Error(
      144`${auditName} has an empty meta.description string. Please add a description for the UI.`
    );
  }

  if (145146147!Array.isArray(auditDefinition.meta.requiredArtifacts)) 148{
    throw new Error(
      149`${auditName} has no meta.requiredArtifacts property, or the property is not an array.`
    );
  }
}

/**
 * @param {Gatherer} gathererInstance
 * @param {string=} gathererName
 */
function assertValidGatherer(gathererInstance, gathererName) 150{
  gathererName = 151152153154155156gathererName || gathererInstance.name || 157'gatherer';

  if (158159160typeof gathererInstance.beforePass !== 161'function') 162{
    throw new Error(163`${gathererName} has no beforePass() method.`);
  }

  if (164165166typeof gathererInstance.pass !== 167'function') 168{
    throw new Error(169`${gathererName} has no pass() method.`);
  }

  if (170171172typeof gathererInstance.afterPass !== 173'function') 174{
    throw new Error(175`${gathererName} has no afterPass() method.`);
  }
}

/**
 * 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) 176{
  if (177178179!pluginName.startsWith(180'lighthouse-plugin-')) 181{
    throw new Error(182`plugin name '${pluginName}' does not start with 'lighthouse-plugin-'`);
  }

  if (183184185configJSON.categories && configJSON.categories[pluginName]) 186{
    throw new Error(187`plugin name '${pluginName}' not allowed because it is the id of a category already found in config`); // eslint-disable-line max-len
  }
}

/**
 * Creates a settings object from potential flags object by dropping all the properties
 * that don't exist on Config.Settings.
 * @param {Partial<LH.Flags>=} flags
 * @return {RecursivePartial<LH.Config.Settings>}
*/
function cleanFlagsForSettings(flags = {}) 188{
  /** @type {RecursivePartial<LH.Config.Settings>} */
  const settings = {};

  for (const key of Object.keys(flags)) 189{
    // @ts-ignore - intentionally testing some keys not on defaultSettings to discard them.
    if (190191192typeof constants.defaultSettings[key] !== 193'undefined') 194{
      // Cast since key now must be able to index both Flags and Settings.
      const safekey = /** @type {Extract<keyof LH.Flags, keyof LH.Config.Settings>} */ (key);
      settings[safekey] = flags[safekey];
    }
  }

  return settings;
}

/**
 * More widely typed than exposed merge() function, below.
 * @param {Object<string, any>|Array<any>|undefined|null} base
 * @param {Object<string, any>|Array<any>} extension
 * @param {boolean=} overwriteArrays
 */
function _merge(base, extension, overwriteArrays = 195false) 196{
  // If the default value doesn't exist or is explicitly null, defer to the extending value
  if (197198199200201202typeof base === 203'undefined' || 204205206base === null) 207{
    return extension;
  } else if (208209210typeof extension === 211'undefined') 212{
    return base;
  } else if (213214Array.isArray(extension)) 215{
    if (216217overwriteArrays) return extension;
    if (218219220!Array.isArray(base)) throw new TypeError(221`Expected array but got ${typeof base}`);
    const merged = base.slice();
    extension.forEach(item => 222{
      if (223224225!merged.some(candidate => isDeepEqual(candidate, item))) merged.push(item);
    });

    return merged;
  } else if (226227228typeof extension === 229'object') 230{
    if (231232233typeof base !== 234'object') throw new TypeError(235`Expected object but got ${typeof base}`);
    if (236237Array.isArray(base)) throw new TypeError(238'Expected object but got Array');
    Object.keys(extension).forEach(key => 239{
      const localOverwriteArrays = 240241242overwriteArrays ||
        (243244245246247248key === 249'settings' && 250251252typeof base[key] === 253'object');
      base[key] = _merge(base[key], extension[key], localOverwriteArrays);
    });
    return base;
  }

  return extension;
}

/**
 * Until support of jsdoc templates with constraints, type in config.d.ts.
 * See https://github.com/Microsoft/TypeScript/issues/24283
 * @type {LH.Config.Merge}
 */
const merge = _merge;

/**
 * @template T
 * @param {Array<T>} array
 * @return {Array<T>}
 */
function cloneArrayWithPluginSafety(array) 254{
  return array.map(item => 255{
    if (256257258typeof item === 259'object') 260{
      // Return copy of instance and prototype chain (in case item is instantiated class).
      return Object.assign(
        Object.create(
          Object.getPrototypeOf(item)
        ),
        item
      );
    }

    return item;
  });
}

/**
 * // TODO(bckenny): could adopt "jsonified" type to ensure T will survive JSON
 * round trip: https://github.com/Microsoft/TypeScript/issues/21838
 * @template T
 * @param {T} json
 * @return {T}
 */
function deepClone(json) 261{
  return JSON.parse(JSON.stringify(json));
}

/**
 * Deep clone a ConfigJson, copying over any "live" gatherer or audit that
 * wouldn't make the JSON round trip.
 * @param {LH.Config.Json} json
 * @return {LH.Config.Json}
 */
function deepCloneConfigJson(json) 262{
  const cloned = deepClone(json);

  // Copy arrays that could contain plugins to allow for programmatic
  // injection of plugins.
  if (263264265Array.isArray(cloned.passes) && Array.isArray(json.passes)) 266{
    for (let i = 0; 267268269i < cloned.passes.length; 270i++) 271{
      const pass = cloned.passes[i];
      pass.gatherers = cloneArrayWithPluginSafety(272273274json.passes[i].gatherers || []);
    }
  }

  if (275276Array.isArray(json.audits)) 277{
    cloned.audits = cloneArrayWithPluginSafety(json.audits);
  }

  return cloned;
}

/**
 * If any items with identical `path` properties are found in the input array,
 * merge their `options` properties into the first instance and then discard any
 * other instances.
 * Until support of jsdoc templates with constraints, type in config.d.ts.
 * See https://github.com/Microsoft/TypeScript/issues/24283
 * @type {LH.Config.MergeOptionsOfItems}
 */
const mergeOptionsOfItems = (function(items) 278{
  /** @type {Array<{path?: string, options?: Object<string, any>}>} */
  const mergedItems = [];

  for (const item of items) 279{
    const existingItem = 280281282item.path && mergedItems.find(candidate => 283284285candidate.path === item.path);
    if (286287288!existingItem) 289{
      mergedItems.push(item);
      continue;
    }

    existingItem.options = Object.assign({}, existingItem.options, item.options);
  }

  return mergedItems;
});

class Config {
  /**
   * @constructor
   * @implements {LH.Config.Json}
   * @param {LH.Config.Json=} configJSON
   * @param {LH.Flags=} flags
   */
  constructor(configJSON, flags) 290{
    const status = 291{msg: 292'Create config', id: 293'lh:init:config'};
    log.time(status, 294'verbose');
    let configPath = 295296297flags && flags.configPath;

    if (298299300!configJSON) 301{
      configJSON = defaultConfig;
      configPath = path.resolve(__dirname, defaultConfigPath);
    }

    if (302303304configPath && 305!path.isAbsolute(configPath)) 306{
      throw new Error(307'configPath must be an absolute path.');
    }

    // We don't want to mutate the original config object
    configJSON = deepCloneConfigJson(configJSON);

    // Extend the default or full config if specified
    if (308309310configJSON.extends === 311'lighthouse:full') 312{
      const explodedFullConfig = Config.extendConfigJSON(deepCloneConfigJson(defaultConfig),
          deepCloneConfigJson(fullConfig));
      configJSON = Config.extendConfigJSON(explodedFullConfig, configJSON);
    } else if (313314configJSON.extends) 315{
      configJSON = Config.extendConfigJSON(deepCloneConfigJson(defaultConfig), configJSON);
    }

    // The directory of the config path, if one was provided.
    const configDir = configPath ? path.dirname(configPath) : undefined;

    // Validate and merge in plugins (if any).
    configJSON = Config.mergePlugins(configJSON, flags, configDir);

    const settings = Config.initSettings(configJSON.settings, flags);

    // Augment passes with necessary defaults and require gatherers.
    const passesWithDefaults = Config.augmentPassesWithDefaults(configJSON.passes);
    Config.adjustDefaultPassForThrottling(settings, passesWithDefaults);
    const passes = Config.requireGatherers(passesWithDefaults, configDir);

    /** @type {LH.Config.Settings} */
    this.settings = settings;
    /** @type {?Array<LH.Config.Pass>} */
    this.passes = passes;
    /** @type {?Array<LH.Config.AuditDefn>} */
    this.audits = Config.requireAudits(configJSON.audits, configDir);
    /** @type {?Record<string, LH.Config.Category>} */
    this.categories = 316317318configJSON.categories || null;
    /** @type {?Record<string, LH.Config.Group>} */
    this.groups = 319320321configJSON.groups || null;

    Config.filterConfigIfNeeded(this);

    validatePasses(this.passes, this.audits);
    validateCategories(this.categories, this.audits, this.groups);

    // TODO(bckenny): until tsc adds @implements support, assert that Config is a ConfigJson.
    /** @type {LH.Config.Json} */
    const configJson = this; // eslint-disable-line no-unused-vars
    log.timeEnd(status);
  }

  /**
   * Provides a cleaned-up, stringified version of this config. Gatherer and
   * Audit `implementation` and `instance` do not survive this process.
   * @return {string}
   */
  getPrintString() 322{
    const jsonConfig = deepClone(this);

    if (323324jsonConfig.passes) 325{
      for (const pass of jsonConfig.passes) 326{
        for (const gathererDefn of pass.gatherers) 327{
          gathererDefn.implementation = undefined;
          // @ts-ignore Breaking the Config.GathererDefn type.
          gathererDefn.instance = undefined;
          if (328329330Object.keys(gathererDefn.options).length === 0) 331{
            // @ts-ignore Breaking the Config.GathererDefn type.
            gathererDefn.options = undefined;
          }
        }
      }
    }

    if (332333jsonConfig.audits) 334{
      for (const auditDefn of jsonConfig.audits) 335{
        // @ts-ignore Breaking the Config.AuditDefn type.
        auditDefn.implementation = undefined;
        if (336337338Object.keys(auditDefn.options).length === 0) 339{
          // @ts-ignore Breaking the Config.AuditDefn type.
          auditDefn.options = undefined;
        }
      }
    }

    // Printed config is more useful with localized strings.
    i18n.replaceIcuMessageInstanceIds(jsonConfig, jsonConfig.settings.locale);

    return JSON.stringify(jsonConfig, null, 2);
  }

  /**
   * @param {LH.Config.Json} baseJSON The JSON of the configuration to extend
   * @param {LH.Config.Json} extendJSON The JSON of the extensions
   * @return {LH.Config.Json}
   */
  static extendConfigJSON(baseJSON, extendJSON) 340{
    if (341342343extendJSON.passes && baseJSON.passes) 344{
      for (const pass of extendJSON.passes) 345{
        // use the default pass name if one is not specified
        const passName = 346347348pass.passName || constants.defaultPassConfig.passName;
        const basePass = baseJSON.passes.find(candidate => 349350351candidate.passName === passName);

        if (352353354!basePass) 355{
          baseJSON.passes.push(pass);
        } else 356{
          merge(basePass, pass);
        }
      }

      delete extendJSON.passes;
    }

    return merge(baseJSON, extendJSON);
  }

  /**
   * @param {LH.Config.Json} configJSON
   * @param {LH.Flags=} flags
   * @param {string=} configDir
   * @return {LH.Config.Json}
   */
  static mergePlugins(configJSON, flags, configDir) 357{
    const configPlugins = 358359360configJSON.plugins || [];
    const flagPlugins = 361362363(364365366flags && flags.plugins) || [];
    const pluginNames = new Set(367[...configPlugins, ...flagPlugins]);

    for (const pluginName of pluginNames) 368{
      assertValidPluginName(configJSON, pluginName);

      const pluginPath = Config.resolveModule(pluginName, configDir, 369'plugin');
      const rawPluginJson = require(pluginPath);
      const pluginJson = ConfigPlugin.parsePlugin(rawPluginJson, pluginName);

      configJSON = Config.extendConfigJSON(configJSON, pluginJson);
    }

    return configJSON;
  }

  /**
   * @param {LH.Config.Json['passes']} passes
   * @return {?Array<Required<LH.Config.PassJson>>}
   */
  static augmentPassesWithDefaults(passes) 370{
    if (371372373!passes) 374{
      return null;
    }

    const {defaultPassConfig} = constants;
    return passes.map(pass => merge(deepClone(defaultPassConfig), pass));
  }

  /**
   * @param {LH.Config.SettingsJson=} settingsJson
   * @param {LH.Flags=} flags
   * @return {LH.Config.Settings}
   */
  static initSettings(settingsJson = {}, flags) 375{
    // If a locale is requested in flags or settings, use it. A typical CLI run will not have one,
    // however `lookupLocale` will always determine which of our supported locales to use (falling
    // back if necessary).
    const locale = i18n.lookupLocale(376377378(379380381flags && flags.locale) || settingsJson.locale);

    // Fill in missing settings with defaults
    const {defaultSettings} = constants;
    const settingWithDefaults = merge(deepClone(defaultSettings), settingsJson, 382true);

    // Override any applicable settings with CLI flags
    const settingsWithFlags = merge(383384385settingWithDefaults || {}, cleanFlagsForSettings(flags), 386true);

    // Locale is special and comes only from flags/settings/lookupLocale.
    settingsWithFlags.locale = locale;

    return settingsWithFlags;
  }

  /**
   * Expands the audits from user-specified JSON to an internal audit definition format.
   * @param {LH.Config.Json['audits']} audits
   * @return {?Array<{path: string, options?: {}} | {implementation: typeof Audit, path?: string, options?: {}}>}
   */
  static expandAuditShorthand(audits) 387{
    if (388389390!audits) 391{
      return null;
    }

    const newAudits = audits.map(audit => 392{
      if (393394395typeof audit === 396'string') 397{
        // just 'path/to/audit'
        return 398{path: audit, options: {}};
      } else if (399400401402'implementation' in audit && 403404405typeof audit.implementation.audit === 406'function') 407{
        // {implementation: AuditClass, ...}
        return audit;
      } else if (408409410411'path' in audit && 412413414typeof audit.path === 415'string') 416{
        // {path: 'path/to/audit', ...}
        return audit;
      } else if (417418419420'audit' in audit && 421422423typeof audit.audit === 424'function') 425{
        // just AuditClass
        return 426{implementation: audit, options: {}};
      } else 427{
        throw new Error(428429'Invalid Audit type ' + JSON.stringify(audit));
      }
    });

    return newAudits;
  }

  /**
   * Expands the gatherers from user-specified to an internal gatherer definition format.
   *
   * Input Examples:
   *  - 'my-gatherer'
   *  - class MyGatherer extends Gatherer { }
   *  - {instance: myGathererInstance}
   *
   * @param {Array<LH.Config.GathererJson>} gatherers
   * @return {Array<{instance?: Gatherer, implementation?: GathererConstructor, path?: string, options?: {}}>} passes
   */
  static expandGathererShorthand(gatherers) 430{
    const expanded = gatherers.map(gatherer => 431{
      if (432433434typeof gatherer === 435'string') 436{
        // just 'path/to/gatherer'
        return 437{path: gatherer, options: {}};
      } else if (438439440441'implementation' in gatherer || 442'instance' in gatherer) 443{
        // {implementation: GathererConstructor, ...} or {instance: GathererInstance, ...}
        return gatherer;
      } else if (444445446'path' in gatherer) 447{
        // {path: 'path/to/gatherer', ...}
        if (448449450typeof gatherer.path !== 451'string') 452{
          throw new Error(453454'Invalid Gatherer type ' + JSON.stringify(gatherer));
        }
        return gatherer;
      } else if (455456457typeof gatherer === 458'function') 459{
        // just GathererConstructor
        return 460{implementation: gatherer, options: {}};
      } else if (461462463gatherer && 464465466typeof gatherer.beforePass === 467'function') 468{
        // just GathererInstance
        return 469{instance: gatherer, options: {}};
      } else 470{
        throw new Error(471472'Invalid Gatherer type ' + JSON.stringify(gatherer));
      }
    });

    return expanded;
  }

  /**
   * Observed throttling methods (devtools/provided) require at least 5s of quiet for the metrics to
   * be computed. This method adjusts the quiet thresholds to the required minimums if necessary.
   * @param {LH.Config.Settings} settings
   * @param {?Array<Required<LH.Config.PassJson>>} passes
   */
  static adjustDefaultPassForThrottling(settings, passes) 473{
    if (474475476477!passes ||
        (478479480481482483settings.throttlingMethod !== 484'devtools' && 485486487settings.throttlingMethod !== 488'provided')) 489{
      return;
    }

    const defaultPass = passes.find(pass => 490491492pass.passName === 493'defaultPass');
    if (494495496!defaultPass) return;
    const overrides = constants.nonSimulatedPassConfigOverrides;
    defaultPass.pauseAfterLoadMs =
      Math.max(overrides.pauseAfterLoadMs, defaultPass.pauseAfterLoadMs);
    defaultPass.cpuQuietThresholdMs =
      Math.max(overrides.cpuQuietThresholdMs, defaultPass.cpuQuietThresholdMs);
    defaultPass.networkQuietThresholdMs =
      Math.max(overrides.networkQuietThresholdMs, defaultPass.networkQuietThresholdMs);
  }

  /**
   * Filter out any unrequested items from the config, based on requested categories or audits.
   * @param {Config} config
   */
  static filterConfigIfNeeded(config) 497{
    const settings = config.settings;
    if (498499500501502503504!settings.onlyCategories && 505!settings.onlyAudits && 506!settings.skipAudits) 507{
      return;
    }

    // 1. Filter to just the chosen categories/audits
    const {categories, requestedAuditNames} = Config.filterCategoriesAndAudits(config.categories,
      settings);

    // 2. Resolve which audits will need to run
    const audits = 508509510config.audits && config.audits.filter(auditDefn =>
        requestedAuditNames.has(auditDefn.implementation.meta.id));

    // 3. Resolve which gatherers will need to run
    const requiredGathererIds = Config.getGatherersNeededByAudits(audits);

    // 4. Filter to only the neccessary passes
    const passes = Config.generatePassesNeededByGatherers(config.passes, requiredGathererIds);

    config.categories = categories;
    config.audits = audits;
    config.passes = passes;
  }

  /**
   * Filter out any unrequested categories or audits from the categories object.
   * @param {Config['categories']} oldCategories
   * @param {LH.Config.Settings} settings
   * @return {{categories: Config['categories'], requestedAuditNames: Set<string>}}
   */
  static filterCategoriesAndAudits(oldCategories, settings) 511{
    if (512513514!oldCategories) 515{
      return 516{categories: null, requestedAuditNames: new Set()};
    }

    if (517518519settings.onlyAudits && settings.skipAudits) 520{
      throw new Error(521'Cannot set both skipAudits and onlyAudits');
    }

    /** @type {NonNullable<Config['categories']>} */
    const categories = {};
    const filterByIncludedCategory = 522!523!settings.onlyCategories;
    const filterByIncludedAudit = 524!525!settings.onlyAudits;
    const categoryIds = 526527528settings.onlyCategories || [];
    const auditIds = 529530531settings.onlyAudits || [];
    const skipAuditIds = 532533534settings.skipAudits || [];

    // warn if the category is not found
    categoryIds.forEach(categoryId => 535{
      if (536537538!oldCategories[categoryId]) 539{
        log.warn(540'config', 541`unrecognized category in 'onlyCategories': ${categoryId}`);
      }
    });

    // warn if the audit is not found in a category or there are overlaps
    const auditsToValidate = new Set(auditIds.concat(skipAuditIds));
    for (const auditId of auditsToValidate) 542{
      const foundCategory = Object.keys(oldCategories).find(categoryId => 543{
        const auditRefs = oldCategories[categoryId].auditRefs;
        return 544!545!auditRefs.find(candidate => 546547548candidate.id === auditId);
      });

      if (549550551!foundCategory) 552{
        const parentKeyName = skipAuditIds.includes(auditId) ? 553'skipAudits' : 554'onlyAudits';
        log.warn(555'config', 556`unrecognized audit in '${parentKeyName}': ${auditId}`);
      } else if (557558559auditIds.includes(auditId) && categoryIds.includes(foundCategory)) 560{
        log.warn(561'config', 562563`${auditId} in 'onlyAudits' is already included by ` +
            564`${foundCategory} in 'onlyCategories'`);
      }
    }

    const includedAudits = new Set(auditIds);
    skipAuditIds.forEach(id => includedAudits.delete(id));

    Object.keys(oldCategories).forEach(categoryId => 565{
      const category = deepClone(oldCategories[categoryId]);

      if (566567568filterByIncludedCategory && filterByIncludedAudit) 569{
        // If we're filtering to the category and audit whitelist, include the union of the two
        if (570571572!categoryIds.includes(categoryId)) 573{
          category.auditRefs = category.auditRefs.filter(audit => auditIds.includes(audit.id));
        }
      } else if (574575filterByIncludedCategory) 576{
        // If we're filtering to just the category whitelist and the category is not included, skip it
        if (577578579!categoryIds.includes(categoryId)) 580{
          return;
        }
      } else if (581582filterByIncludedAudit) 583{
        category.auditRefs = category.auditRefs.filter(audit => auditIds.includes(audit.id));
      }

      // always filter to the audit blacklist
      category.auditRefs = category.auditRefs.filter(audit => 584!skipAuditIds.includes(audit.id));

      if (585586category.auditRefs.length) 587{
        categories[categoryId] = category;
        category.auditRefs.forEach(audit => includedAudits.add(audit.id));
      }
    });

    return 588{categories, requestedAuditNames: includedAudits};
  }

  /**
   * @param {LH.Config.Json} config
   * @return {Array<{id: string, title: string}>}
   */
  static getCategories(config) 589{
    const categories = config.categories;
    if (590591592!categories) 593{
      return [];
    }

    return Object.keys(categories).map(id => 594{
      const title = categories[id].title;
      return 595{id, title};
    });
  }

  /**
   * From some requested audits, return names of all required artifacts
   * @param {Config['audits']} audits
   * @return {Set<string>}
   */
  static getGatherersNeededByAudits(audits) 596{
    // It's possible we weren't given any audits (but existing audit results), in which case
    // there is no need to do any work here.
    if (597598599!audits) 600{
      return new Set();
    }

    return audits.reduce((list, auditDefn) => 601{
      auditDefn.implementation.meta.requiredArtifacts.forEach(artifact => list.add(artifact));
      return list;
    }, new Set());
  }

  /**
   * Filters to only required passes and gatherers, returning a new passes array.
   * @param {Config['passes']} passes
   * @param {Set<string>} requiredGatherers
   * @return {Config['passes']}
   */
  static generatePassesNeededByGatherers(passes, requiredGatherers) 602{
    if (603604605!passes) 606{
      return null;
    }

    const auditsNeedTrace = requiredGatherers.has(607'traces');
    const filteredPasses = passes.map(pass => 608{
      // remove any unncessary gatherers from within the passes
      pass.gatherers = pass.gatherers.filter(gathererDefn => 609{
        const gatherer = gathererDefn.instance;
        return requiredGatherers.has(gatherer.name);
      });

      // disable the trace if no audit requires a trace
      if (610611612pass.recordTrace && 613!auditsNeedTrace) 614{
        const passName = 615616617pass.passName || 618'unknown pass';
        log.warn(619'config', 620`Trace not requested by an audit, dropping trace in ${passName}`);
        pass.recordTrace = 621false;
      }

      return pass;
    }).filter(pass => 622{
      // remove any passes lacking concrete gatherers, unless they are dependent on the trace
      if (623624pass.recordTrace) return 625true;
      // Always keep defaultPass
      if (626627628pass.passName === 629'defaultPass') return 630true;
      return 631632633634pass.gatherers.length > 0;
    });
    return filteredPasses;
  }

  /**
   * Take an array of audits and audit paths and require any paths (possibly
   * relative to the optional `configDir`) using `Config.resolveModule`,
   * leaving only an array of AuditDefns.
   * @param {LH.Config.Json['audits']} audits
   * @param {string=} configDir
   * @return {Config['audits']}
   */
  static requireAudits(audits, configDir) 635{
    const status = 636{msg: 637'Requiring audits', id: 638'lh:config:requireAudits'};
    log.time(status, 639'verbose');
    const expandedAudits = Config.expandAuditShorthand(audits);
    if (640641642!expandedAudits) 643{
      return null;
    }

    const coreList = Runner.getAuditList();
    const auditDefns = expandedAudits.map(audit => 644{
      let implementation;
      if (645646647'implementation' in audit) 648{
        implementation = audit.implementation;
      } else 649{
        // See if the audit is a Lighthouse core audit.
        const auditPathJs = 650`${audit.path}.js`;
        const coreAudit = coreList.find(a => 651652653a === auditPathJs);
        let requirePath = 654`../audits/${audit.path}`;
        if (655656657!coreAudit) 658{
          // Otherwise, attempt to find it elsewhere. This throws if not found.
          requirePath = Config.resolveModule(audit.path, configDir, 659'audit');
        }
        implementation = /** @type {typeof Audit} */ (require(requirePath));
      }

      return 660{
        implementation,
        path: audit.path,
        options: 661662663audit.options || {},
      };
    });

    const mergedAuditDefns = mergeOptionsOfItems(auditDefns);
    mergedAuditDefns.forEach(audit => assertValidAudit(audit.implementation, audit.path));
    log.timeEnd(status);
    return mergedAuditDefns;
  }

  /**
   * @param {string} path
   * @param {{}=} options
   * @param {Array<string>} coreAuditList
   * @param {string=} configDir
   * @return {LH.Config.GathererDefn}
   */
  static requireGathererFromPath(path, options, coreAuditList, configDir) 664{
    const coreGatherer = coreAuditList.find(a => 665666667a === 668`${path}.js`);

    let requirePath = 669`../gather/gatherers/${path}`;
    if (670671672!coreGatherer) 673{
      // Otherwise, attempt to find it elsewhere. This throws if not found.
      requirePath = Config.resolveModule(path, configDir, 674'gatherer');
    }

    const GathererClass = /** @type {GathererConstructor} */ (require(requirePath));

    return 675{
      instance: new GathererClass(),
      implementation: GathererClass,
      path,
      options: 676677678options || {},
    };
  }

  /**
   * Takes an array of passes with every property now initialized except the
   * gatherers and requires them, (relative to the optional `configDir` if
   * provided) using `Config.resolveModule`, returning an array of full Passes.
   * @param {?Array<Required<LH.Config.PassJson>>} passes
   * @param {string=} configDir
   * @return {Config['passes']}
   */
  static requireGatherers(passes, configDir) 679{
    if (680681682!passes) 683{
      return null;
    }
    const status = 684{msg: 685'Requiring gatherers', id: 686'lh:config:requireGatherers'};
    log.time(status, 687'verbose');

    const coreList = Runner.getGathererList();
    const fullPasses = passes.map(pass => 688{
      const gathererDefns = Config.expandGathererShorthand(pass.gatherers).map(gathererDefn => 689{
        if (690691gathererDefn.instance) 692{
          return 693{
            instance: gathererDefn.instance,
            implementation: gathererDefn.implementation,
            path: gathererDefn.path,
            options: 694695696gathererDefn.options || {},
          };
        } else if (697698gathererDefn.implementation) 699{
          const GathererClass = gathererDefn.implementation;
          return 700{
            instance: new GathererClass(),
            implementation: gathererDefn.implementation,
            path: gathererDefn.path,
            options: 701702703gathererDefn.options || {},
          };
        } else if (704705gathererDefn.path) 706{
          const path = gathererDefn.path;
          const options = gathererDefn.options;
          return Config.requireGathererFromPath(path, options, coreList, configDir);
        } else 707{
          throw new Error(708709'Invalid expanded Gatherer: ' + JSON.stringify(gathererDefn));
        }
      });

      const mergedDefns = mergeOptionsOfItems(gathererDefns);
      mergedDefns.forEach(gatherer => assertValidGatherer(gatherer.instance, gatherer.path));

      return Object.assign(pass, 710{gatherers: mergedDefns});
    });
    log.timeEnd(status);
    return fullPasses;
  }

  /**
   * Resolves the location of the specified module and returns an absolute
   * string path to the file. Used for loading custom audits and gatherers.
   * Throws an error if no module is found.
   * @param {string} moduleIdentifier
   * @param {string=} configDir The absolute path to the directory of the config file, if there is one.
   * @param {string=} category Optional plugin category (e.g. 'audit') for better error messages.
   * @return {string}
   * @throws {Error}
   */
  static resolveModule(moduleIdentifier, configDir, category) 711{
    // First try straight `require()`. Unlikely to be specified relative to this
    // file, but adds support for Lighthouse modules from npm since
    // `require()` walks up parent directories looking inside any node_modules/
    // present. Also handles absolute paths.
    try 712{
      return require.resolve(moduleIdentifier);
    } catch (e) {}

    // See if the module resolves relative to the current working directory.
    // Most useful to handle the case of invoking Lighthouse as a module, since
    // then the config is an object and so has no path.
    const cwdPath = path.resolve(process.cwd(), moduleIdentifier);
    try 713{
      return require.resolve(cwdPath);
    } catch (e) {}

    const errorString = 714715716'Unable to locate ' +
        (category ? 717`${category}: ` : 718'') +
        719`${moduleIdentifier} (tried to require() from '${__dirname}' and load from '${cwdPath}'`;

    if (720721722!configDir) 723{
      throw new Error(724errorString + 725')');
    }

    // Finally, try looking up relative to the config file path. Just like the
    // relative path passed to `require()` is found relative to the file it's
    // in, this allows module paths to be specified relative to the config file.
    const relativePath = path.resolve(configDir, moduleIdentifier);
    try 726{
      return require.resolve(relativePath);
    } catch (requireError) {}

    throw new Error(727errorString + 728` and '${relativePath}')`);
  }
}

module.exports = Config;