lighthouse 9.6.7 → 10.0.0

package/.gitattributes

@@ -1,2 +1,5 @@
 *.js eol=lf
-**/locales/*.json linguist-generated=true
+**/locales/*.json linguist-generated=true
+build/** linguist-generated=false
+report/assets/styles.css linguist-generated=false
+report/renderer/components.js linguist-generated=true

package/CONTRIBUTING.md

@@ -8,7 +8,7 @@ We tag issues that are good candidates for those new to the code with [`good fir
 
 ## Follow the coding style
 
-The `.eslintrc.js` file defines all. We use [JSDoc](http://usejsdoc.org/) with [TypeScript `checkJs`](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc). Annotations are encouraged for all contributions.
+The `.eslintrc.cjs` file defines all. We use [JSDoc](http://usejsdoc.org/) with [TypeScript `checkJs`](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc). Annotations are encouraged for all contributions.
 
 ## Learn about the architecture
 
@@ -16,7 +16,7 @@ See [Lighthouse Architecture](./docs/architecture.md), our overview and tour of
 
 ## Contributing a patch
 
-If you have a contribution for our [documentation](https://web.dev/learn/#lighthouse), please submit it in the [web.dev repo](https://github.com/GoogleChrome/web.dev).
+If you have a contribution for our [documentation](https://developer.chrome.com/docs/lighthouse/), please submit it in the [developer.chrome.com repo](https://github.com/GoogleChrome/developer.chrome.com).
 
 1. Submit an issue describing your proposed change.
 1. The maintainers will respond to your issue promptly.
@@ -25,7 +25,7 @@ If you have a contribution for our [documentation](https://web.dev/learn/#lighth
 1. Ensure that your code adheres to the existing style in the sample to which you are contributing.
 1. Submit a pull request.
 
-If you've submitted a number of significant patches, feel free to add yourself in a PR to the project's `AUTHORS` [file](https://github.com/GoogleChrome/lighthouse/blob/master/AUTHORS) in the root of the repo to be recognized for your contributions!
+If you've submitted a number of significant patches, feel free to add yourself in a PR to the project's `AUTHORS` [file](https://github.com/GoogleChrome/lighthouse/blob/main/AUTHORS) in the root of the repo to be recognized for your contributions!
 
 ## Audit PRs
 
@@ -33,13 +33,13 @@ If proposing a new audit for Lighthouse, see the [new audit proposal guide](./do
 
 A PR for a new audit or changing an existing audit almost always needs the following:
 
-1. If new, add the audit to the [default config file](lighthouse-core/config/default-config.js) (or, rarely, one of the other config files) so Lighthouse will run it.
+1. If new, add the audit to the [default config file](core/config/default-config.js) (or, rarely, one of the other config files) so Lighthouse will run it.
 
-1. **Unit tests**: in the matching test file (e.g. tests for `lighthouse-core/audits/my-swell-audit.js` go in `lighthouse-core/test/audits/my-swell-audit-test.js`).
+1. **Unit tests**: in the matching test file (e.g. tests for `core/audits/my-swell-audit.js` go in `core/test/audits/my-swell-audit-test.js`).
 
-1. **Smoke (end-to-end) tests**: search through the [existing test expectations](lighthouse-cli/test/smokehouse/test-definitions/) to see if there's a logical place to add a check for your change, or (as a last resort) add a new smoke test.
+1. **Smoke (end-to-end) tests**: search through the [existing test expectations](cli/test/smokehouse/test-definitions/) to see if there's a logical place to add a check for your change, or (as a last resort) add a new smoke test.
 
-1. Run `yarn update:sample-json` to update the [sample Lighthouse result JSON](lighthouse-core/test/results/sample_v2.json) kept in the repo for testing. This will also pull any strings needed for localization into the correct files.
+1. Run `yarn update:sample-json` to update the [sample Lighthouse result JSON](core/test/results/sample_v2.json) kept in the repo for testing. This will also pull any strings needed for localization into the correct files.
 
 ### Audit `description` Guidelines
 
@@ -68,13 +68,13 @@ It can be tempting to serialize the entire state of the world into the artifact
 
 A PR adding or changing a gatherer almost always needs to include the following:
 
-1. If new, add the gatherer to the [default config file](lighthouse-core/config/default-config.js) (or, rarely, one of the other config files) so Lighthouse will run it.
+1. If new, add the gatherer to the [default config file](core/config/default-config.js) (or, rarely, one of the other config files) so Lighthouse will run it.
 
 1. **Unit tests**: gatherer execution often takes place mostly on the browser side, either through protocol functionality or executing javascript in the test page. This makes gatherers difficult to unit test without extensive mocking, ending up mostly exercising the mocks instead of the actual gatherer.
 
-   As a result, we mostly rely on smoke testing for gatherers. However, if there are parts of a gatherer that naturally lend themselves to unit testing, the new tests would go in the matching test file (e.g. tests for `lighthouse-core/gather/gatherers/reap.js` go in `lighthouse-core/test/gather/gatherers/reap-test.js`).
+   As a result, we mostly rely on smoke testing for gatherers. However, if there are parts of a gatherer that naturally lend themselves to unit testing, the new tests would go in the matching test file (e.g. tests for `core/gather/gatherers/reap.js` go in `core/test/gather/gatherers/reap-test.js`).
 
-1. **Smoke (end-to-end) tests**: search through the [existing test expectations](lighthouse-cli/test/smokehouse/test-definitions/) to see if there's a logical place to add a check for your change, or (as a last resort) add a new smoke test if one is required.
+1. **Smoke (end-to-end) tests**: search through the [existing test expectations](cli/test/smokehouse/test-definitions/) to see if there's a logical place to add a check for your change, or (as a last resort) add a new smoke test if one is required.
 
    It's most important to get true end-to-end coverage, so be sure that audits that consume the new gatherer output are in the expectations. Artifacts can also have expectations for those intermediate results.
 
@@ -87,7 +87,7 @@ A PR adding or changing a gatherer almost always needs to include the following:
 
    This command works for updating `yarn update:sample-artifacts devtoolsLogs` or `traces` as well, but the resulting `sample_v2.json` churn may be extensive and you might be better off editing manually.
 
-1. Run `yarn update:sample-json` to update the [sample Lighthouse result JSON](lighthouse-core/test/results/sample_v2.json) kept in the repo for testing. This will also pull any strings needed for localization into the correct files.
+1. Run `yarn update:sample-json` to update the [sample Lighthouse result JSON](core/test/results/sample_v2.json) kept in the repo for testing. This will also pull any strings needed for localization into the correct files.
 
 ## Protobuf errors
 
@@ -108,7 +108,7 @@ We're using [conventional-commit](https://conventionalcommits.org/) for our comm
 
 > type(scope): message subject
 
-* The `type` must be one of: `new_audit` `core` `tests` `i18n`, `docs` `deps` `report` `cli` `clients` `misc`. (See [`.cz-config`](https://github.com/GoogleChrome/lighthouse/blob/master/.cz-config.js#L13))
+* The `type` must be one of: `new_audit` `core` `tests` `i18n`, `docs` `deps` `report` `cli` `clients` `misc`. (See [`.cz-config`](https://github.com/GoogleChrome/lighthouse/blob/main/.cz-config.js#L13))
 * The `scope` is optional, but recommended. Any string is allowed; it should indicate what the change affects.
 * The `message subject` should be pithy and direct.
 
@@ -128,13 +128,13 @@ accept your pull requests.
 
 ## Tracking Errors
 
-We track our errors in the wild with Sentry. In general, do not worry about wrapping your audits or gatherers in try/catch blocks and reporting every error that could possibly occur; `lighthouse-core/runner.js` and `lighthouse-core/gather/gather-runner.js` already catch and report any errors that occur while running a gatherer or audit, including errors fatal to the entire run. However, there are some situations when you might want to explicitly handle an error and report it to Sentry or wrap it to avoid reporting. Generally, you can interact with Sentry simply by requiring the `lighthouse-core/lib/sentry.js` file and call its methods. The module exports a delegate that will correctly handle the error reporting based on the user's opt-in preference and will simply no-op if they haven't so you don't need to check.
+We track our errors in the wild with Sentry. In general, do not worry about wrapping your audits or gatherers in try/catch blocks and reporting every error that could possibly occur; `core/runner.js` and `core/gather/*-runner.js` already catch and report any errors that occur while running a gatherer or audit, including errors fatal to the entire run. However, there are some situations when you might want to explicitly handle an error and report it to Sentry or wrap it to avoid reporting. Generally, you can interact with Sentry simply by requiring the `core/lib/sentry.js` file and call its methods. The module exports a delegate that will correctly handle the error reporting based on the user's opt-in preference and will simply no-op if they haven't so you don't need to check.
 
 
 #### If you have an expected error that is recoverable but want to track how frequently it happens, *use Sentry.captureException*.
 
 ```js
-const Sentry = require('./lighthouse-core/lib/sentry');
+const Sentry = require('./core/lib/sentry');
 
 try {
   doRiskyThing();
@@ -152,7 +152,7 @@ try {
 NOTE: If the message you're capturing is dynamic/based on user data or you need a stack trace, then create a fake error instead and use `Sentry.captureException` so that the instances will be grouped together in Sentry.
 
 ```js
-const Sentry = require('./lighthouse-core/lib/sentry');
+const Sentry = require('./core/lib/sentry');
 
 if (networkRecords.length === 1) {
   Sentry.captureMessage('Site only had 1 network request', {level: 'info'});

package/build-tracker.config.js

@@ -1,6 +1,5 @@
 // https://buildtracker.dev/docs/installation/#upload-your-builds
 
-'use strict';
 
 module.exports = {
   applicationUrl: 'https://lh-build-tracker.herokuapp.com',

package/cli/bin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @return {Promise<LH.RunnerResult|void>}
+ */
+export function begin(): Promise<LH.RunnerResult | void>;
+//# sourceMappingURL=bin.d.ts.map

package/cli/bin.js

@@ -0,0 +1,140 @@
+/**
+ * @license Copyright 2016 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+/**
+ * @fileoverview The relationship between these CLI modules:
+ *
+ *   index.js     : only calls bin.js's begin()
+ *   cli-flags.js : leverages yargs to read argv, outputs LH.CliFlags
+ *   bin.js       : CLI args processing. cwd, list/print commands
+ *   run.js       : chrome-launcher bits, calling core, output to Printer
+ *
+ *   index ---->    bin    ---->      run      ----> printer
+ *                  ⭏  ⭎               ⭏  ⭎
+ *               cli-flags        lh-core/index
+ */
+
+import fs from 'fs';
+import path from 'path';
+import url from 'url';
+
+import log from 'lighthouse-logger';
+
+import * as commands from './commands/commands.js';
+import * as Printer from './printer.js';
+import {getFlags} from './cli-flags.js';
+import {runLighthouse} from './run.js';
+import {askPermission} from './sentry-prompt.js';
+import {LH_ROOT} from '../root.js';
+import {Sentry} from '../core/lib/sentry.js';
+
+const pkg = JSON.parse(fs.readFileSync(LH_ROOT + '/package.json', 'utf-8'));
+
+/**
+ * @return {boolean}
+ */
+function isDev() {
+  return fs.existsSync(path.join(LH_ROOT, '/.git'));
+}
+
+/**
+ * @return {Promise<LH.RunnerResult|void>}
+ */
+async function begin() {
+  const cliFlags = getFlags();
+
+  // Process terminating command
+  if (cliFlags.listAllAudits) {
+    commands.listAudits();
+  }
+
+  // Process terminating command
+  if (cliFlags.listLocales) {
+    commands.listLocales();
+  }
+
+  // Process terminating command
+  if (cliFlags.listTraceCategories) {
+    commands.listTraceCategories();
+  }
+
+  const urlUnderTest = cliFlags._[0];
+
+  /** @type {LH.Config|undefined} */
+  let config;
+  if (cliFlags.configPath) {
+    // Resolve the config file path relative to where cli was called.
+    cliFlags.configPath = path.resolve(process.cwd(), cliFlags.configPath);
+
+    if (cliFlags.configPath.endsWith('.json')) {
+      config = JSON.parse(fs.readFileSync(cliFlags.configPath, 'utf-8'));
+    } else {
+      const configModuleUrl = url.pathToFileURL(cliFlags.configPath).href;
+      config = (await import(configModuleUrl)).default;
+    }
+  } else if (cliFlags.preset) {
+    config = (await import(`../core/config/${cliFlags.preset}-config.js`)).default;
+  }
+
+  if (cliFlags.budgetPath) {
+    cliFlags.budgetPath = path.resolve(process.cwd(), cliFlags.budgetPath);
+    /** @type {Array<LH.Budget>} */
+    const parsedBudget = JSON.parse(fs.readFileSync(cliFlags.budgetPath, 'utf8'));
+    cliFlags.budgets = parsedBudget;
+  }
+
+  // set logging preferences
+  cliFlags.logLevel = 'info';
+  if (cliFlags.verbose) {
+    cliFlags.logLevel = 'verbose';
+  } else if (cliFlags.quiet) {
+    cliFlags.logLevel = 'silent';
+  }
+  log.setLevel(cliFlags.logLevel);
+
+  if (
+    cliFlags.output.length === 1 &&
+    cliFlags.output[0] === Printer.OutputMode.json &&
+    !cliFlags.outputPath
+  ) {
+    cliFlags.outputPath = 'stdout';
+  }
+
+  if (cliFlags.precomputedLanternDataPath) {
+    const lanternDataStr = fs.readFileSync(cliFlags.precomputedLanternDataPath, 'utf8');
+    /** @type {LH.PrecomputedLanternData} */
+    const data = JSON.parse(lanternDataStr);
+    if (!data.additionalRttByOrigin || !data.serverResponseTimeByOrigin) {
+      throw new Error('Invalid precomputed lantern data file');
+    }
+
+    cliFlags.precomputedLanternData = data;
+  }
+
+  // By default, cliFlags.enableErrorReporting is undefined so the user is
+  // prompted. This can be overriden with an explicit flag or by the cached
+  // answer returned by askPermission().
+  if (typeof cliFlags.enableErrorReporting === 'undefined') {
+    cliFlags.enableErrorReporting = await askPermission();
+  }
+  if (cliFlags.enableErrorReporting) {
+    await Sentry.init({
+      url: urlUnderTest,
+      flags: cliFlags,
+      environmentData: {
+        serverName: 'redacted', // prevent sentry from using hostname
+        environment: isDev() ? 'development' : 'production',
+        release: pkg.version,
+      },
+    });
+  }
+
+  return runLighthouse(urlUnderTest, cliFlags, config);
+}
+
+export {
+  begin,
+};

package/cli/cli-flags.d.ts

@@ -0,0 +1,258 @@
+/**
+ * @param {string=} manualArgv
+ * @param {{noExitOnFailure?: boolean}=} options
+ * @return {LH.CliFlags}
+ */
+export function getFlags(manualArgv?: string | undefined, options?: {
+    noExitOnFailure?: boolean;
+} | undefined): LH.CliFlags;
+/**
+ * @param {string=} manualArgv
+ */
+export function getYargsParser(manualArgv?: string | undefined): yargs.Argv<yargs.Omit<yargs.Omit<yargs.Omit<yargs.Omit<yargs.Omit<yargs.Omit<yargs.Omit<yargs.Omit<{
+    _: string[] | undefined;
+} & {
+    "cli-flags-path": unknown;
+}, "verbose" | "quiet"> & yargs.InferredOptionTypes<{
+    verbose: {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+    quiet: {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+}>, "port" | "screenEmulation" | "emulatedUserAgent" | "hostname" | "preset" | "save-assets" | "list-all-audits" | "list-locales" | "list-trace-categories" | "debug-navigation" | "legacy-navigation" | "additional-trace-categories" | "config-path" | "chrome-flags" | "form-factor" | "max-wait-for-load" | "enable-error-reporting" | "gather-mode" | "audit-mode" | "only-audits" | "only-categories" | "skip-audits" | "budget-path" | "disable-full-page-screenshot"> & yargs.InferredOptionTypes<{
+    'save-assets': {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+    'list-all-audits': {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+    'list-locales': {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+    'list-trace-categories': {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+    'debug-navigation': {
+        type: "boolean";
+        describe: string;
+    };
+    'legacy-navigation': {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+    'additional-trace-categories': {
+        type: "string";
+        describe: string;
+    };
+    'config-path': {
+        type: "string";
+        describe: string;
+    };
+    preset: {
+        type: "string";
+        describe: string;
+    };
+    'chrome-flags': {
+        type: "string";
+        default: string;
+        describe: string;
+    };
+    port: {
+        type: "number";
+        default: number;
+        describe: string;
+    };
+    hostname: {
+        type: "string";
+        default: string;
+        describe: string;
+    };
+    'form-factor': {
+        type: "string";
+        describe: string;
+    };
+    screenEmulation: {
+        describe: string;
+        coerce: typeof coerceScreenEmulation;
+    };
+    emulatedUserAgent: {
+        type: "string";
+        coerce: typeof coerceOptionalStringBoolean;
+        describe: string;
+    };
+    'max-wait-for-load': {
+        type: "number";
+        describe: string;
+    };
+    'enable-error-reporting': {
+        type: "boolean";
+        describe: string;
+    };
+    'gather-mode': {
+        alias: string;
+        coerce: typeof coerceOptionalStringBoolean;
+        describe: string;
+    };
+    'audit-mode': {
+        alias: string;
+        coerce: typeof coerceOptionalStringBoolean;
+        describe: string;
+    };
+    'only-audits': {
+        array: true;
+        type: "string";
+        coerce: typeof splitCommaSeparatedValues;
+        describe: string;
+    };
+    'only-categories': {
+        array: true;
+        type: "string";
+        coerce: typeof splitCommaSeparatedValues;
+        describe: string;
+    };
+    'skip-audits': {
+        array: true;
+        type: "string";
+        coerce: typeof splitCommaSeparatedValues;
+        describe: string;
+    };
+    'budget-path': {
+        type: "string";
+        describe: string;
+    };
+    'disable-full-page-screenshot': {
+        type: "boolean";
+        describe: string;
+    };
+}>, "output" | "view" | "output-path"> & yargs.InferredOptionTypes<{
+    output: {
+        type: "array";
+        default: readonly ["html"];
+        coerce: typeof coerceOutput;
+        describe: string;
+    };
+    'output-path': {
+        type: "string";
+        coerce: typeof coerceOutputPath;
+        describe: string;
+    };
+    view: {
+        type: "boolean";
+        default: boolean;
+        describe: string;
+    };
+}>, "locale" | "blocked-url-patterns" | "disable-storage-reset" | "throttling-method"> & yargs.InferredOptionTypes<{
+    locale: {
+        coerce: typeof coerceLocale;
+        describe: string;
+    };
+    'blocked-url-patterns': {
+        array: true;
+        type: "string";
+        describe: string;
+    };
+    'disable-storage-reset': {
+        type: "boolean";
+        describe: string;
+    };
+    'throttling-method': {
+        type: "string";
+        describe: string;
+    };
+}> & {
+    throttling: import("../types/lh.js").ThrottlingSettings | undefined;
+}, "channel" | "plugins" | "extra-headers" | "precomputed-lantern-data-path" | "lantern-data-output-path" | "chrome-ignore-default-flags"> & yargs.InferredOptionTypes<{
+    'extra-headers': {
+        coerce: typeof coerceExtraHeaders;
+        describe: string;
+    };
+    'precomputed-lantern-data-path': {
+        type: "string";
+        describe: string;
+    };
+    'lantern-data-output-path': {
+        type: "string";
+        describe: string;
+    };
+    plugins: {
+        array: true;
+        type: "string";
+        coerce: typeof splitCommaSeparatedValues;
+        describe: string;
+    };
+    channel: {
+        type: "string";
+        default: string;
+    };
+    'chrome-ignore-default-flags': {
+        type: "boolean";
+        default: boolean;
+    };
+}>, "form-factor"> & {
+    "form-factor": "mobile" | "desktop" | undefined;
+}, "throttling-method"> & {
+    "throttling-method": "devtools" | "simulate" | "provided" | undefined;
+}, "preset"> & {
+    preset: "desktop" | "experimental" | "perf" | undefined;
+}>;
+import yargs from "yargs";
+/**
+ * Take yarg's unchecked object value and ensure it is a proper LH.screenEmulationSettings.
+ * @param {unknown} value
+ * @return {Partial<LH.ScreenEmulationSettings>|undefined}
+ */
+declare function coerceScreenEmulation(value: unknown): Partial<LH.ScreenEmulationSettings> | undefined;
+/**
+ * @param {unknown} value
+ * @return {boolean|string|undefined}
+ */
+declare function coerceOptionalStringBoolean(value: unknown): boolean | string | undefined;
+/**
+ * Support comma-separated values for some array flags by splitting on any ',' found.
+ * @param {Array<string>=} strings
+ * @return {Array<string>=}
+ */
+declare function splitCommaSeparatedValues(strings?: Array<string> | undefined): Array<string> | undefined;
+/**
+ * Coerce output CLI input to `LH.SharedFlagsSettings['output']` or throw if not possible.
+ * @param {Array<unknown>} values
+ * @return {Array<LH.OutputMode>}
+ */
+declare function coerceOutput(values: Array<unknown>): Array<LH.OutputMode>;
+/**
+ * Verifies outputPath is something we can actually write to.
+ * @param {unknown=} value
+ * @return {string=}
+ */
+declare function coerceOutputPath(value?: unknown | undefined): string | undefined;
+/**
+ * Verifies value is a string, then coerces type to LH.Locale for convenience. However, don't
+ * allowlist specific locales. Why? So we can support the user who requests 'es-MX' (unsupported)
+ * and we'll fall back to 'es' (supported).
+ * @param {unknown} value
+ * @return {LH.Locale|undefined}
+ */
+declare function coerceLocale(value: unknown): LH.Locale | undefined;
+/**
+ * `--extra-headers` comes in as a JSON string or a path to a JSON string, but the flag value
+ * needs to be the parsed object. Load file (if necessary) and returns the parsed object.
+ * @param {unknown} value
+ * @return {LH.SharedFlagsSettings['extraHeaders']}
+ */
+declare function coerceExtraHeaders(value: unknown): LH.SharedFlagsSettings['extraHeaders'];
+export {};
+//# sourceMappingURL=cli-flags.d.ts.map