lighthouse 9.6.8 → 10.0.0

package/types/audit.d.ts

@@ -4,13 +4,14 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import ArbitraryEqualityMap = require('../lighthouse-core/lib/arbitrary-equality-map.js');
-import {Artifacts} from './artifacts';
-import AuditDetails from './lhr/audit-details';
-import Config from './config';
-import Gatherer from './gatherer';
-import {FormattedIcu, IcuMessage} from './lhr/i18n';
-import * as AuditResult from './lhr/audit-result';
+import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map.js';
+import {Artifacts} from './artifacts.js';
+import AuditDetails from './lhr/audit-details.js';
+import Config from './config.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
+import * as AuditResult from './lhr/audit-result.js';
+import Util from './utility-types.js';
 
 declare module Audit {
   export import Details = AuditDetails;
@@ -18,7 +19,7 @@ declare module Audit {
   export type ScoreDisplayMode = AuditResult.ScoreDisplayMode;
   export type ScoreDisplayModes = AuditResult.ScoreDisplayModes;
 
-  type Context = Immutable<{
+  type Context = Util.Immutable<{
     /** audit options */
     options: Record<string, any>;
     settings: Config.Settings;

package/types/config.d.ts

@@ -5,39 +5,38 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import Audit = require('../lighthouse-core/audits/audit.js');
-import {SharedFlagsSettings, ConfigSettings} from './lhr/settings';
-import Gatherer from './gatherer';
-import {IcuMessage} from './lhr/i18n';
+import {Audit} from '../core/audits/audit.js';
+import {SharedFlagsSettings, ConfigSettings} from './lhr/settings.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
 
 interface ClassOf<T> {
   new (): T;
 }
 
-declare module Config {
-  /**
-   * The pre-normalization Lighthouse Config format.
-   */
-  interface Json {
-    extends?: 'lighthouse:default' | string;
-    settings?: SharedFlagsSettings;
-    audits?: Config.AuditJson[] | null;
-    categories?: Record<string, CategoryJson> | null;
-    groups?: Record<string, Config.GroupJson> | null;
-    plugins?: Array<string>;
-
-    // Fraggle Rock Only
-    artifacts?: ArtifactJson[] | null;
-    navigations?: NavigationJson[] | null;
-
-    // Legacy Only
-    passes?: PassJson[] | null;
-  }
+/**
+ * The Lighthouse Config format.
+ */
+interface Config {
+  extends?: 'lighthouse:default' | string;
+  settings?: SharedFlagsSettings;
+  audits?: Config.AuditJson[] | null;
+  categories?: Record<string, Config.CategoryJson> | null;
+  groups?: Record<string, Config.GroupJson> | null;
+  plugins?: Array<string>;
+
+  // Fraggle Rock Only
+  artifacts?: Config.ArtifactJson[] | null;
+
+  // Legacy Only
+  passes?: Config.PassJson[] | null;
+}
 
+declare module Config {
   /**
-   * The normalized and fully resolved config.
+   * The normalized and fully resolved legacy config.
    */
-  interface Config {
+  interface LegacyResolvedConfig {
     settings: Settings;
     passes: Pass[] | null;
     audits: AuditDefn[] | null;
@@ -46,9 +45,9 @@ declare module Config {
   }
 
   /**
-   * The normalized and fully resolved Fraggle Rock config.
+   * The normalized and fully resolved config.
    */
-  interface FRConfig {
+  interface ResolvedConfig {
     settings: Settings;
     artifacts: AnyArtifactDefn[] | null;
     navigations: NavigationDefn[] | null;
@@ -57,17 +56,6 @@ declare module Config {
     groups: Record<string, Group> | null;
   }
 
-  /**
-   * Additional information about the context in which a Fraggle Rock config should be interpreted.
-   * This information is typically set by the CLI or other channel integrations.
-   */
-  interface FRContext {
-    configPath?: string;
-    settingsOverrides?: SharedFlagsSettings & Pick<LH.Flags, 'plugins'>;
-    skipAboutBlank?: boolean;
-    logLevel?: string;
-  }
-
   interface SharedPassNavigationJson {
     /**
      * Controls the behavior when the navigation fails to complete (due to server error, no FCP, etc).

package/types/externs.d.ts

@@ -4,103 +4,9 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {Artifacts} from './artifacts';
-import LHResult from './lhr/lhr';
-import {SharedFlagsSettings, OutputMode} from './lhr/settings';
-
-declare global {
-  // Augment Intl to include
-  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales
-  namespace Intl {
-    var getCanonicalLocales: (locales?: string | Array<string>) => Array<string>;
-  }
-
-  interface Window {
-    // Cached native functions/objects for use in case the page overwrites them.
-    // See: `executionContext.cacheNativesOnNewDocument`.
-    __nativePromise: PromiseConstructor;
-    __nativePerformance: Performance;
-    __nativeFetch: typeof fetch,
-    __nativeURL: typeof URL;
-    __ElementMatches: Element['matches'];
-
-    /** Used for monitoring long tasks in the test page. */
-    ____lastLongTask?: number;
-
-    /** Used by FullPageScreenshot gatherer. */
-    __lighthouseNodesDontTouchOrAllVarianceGoesAway: Map<Element, string>;
-    __lighthouseExecutionContextId?: number;
-
-    /** Injected into the page when the `--debug` flag is used. */
-    continueLighthouseRun(): void;
-
-    // Not defined in tsc yet: https://github.com/microsoft/TypeScript/issues/40807
-    requestIdleCallback(callback: (deadline: {didTimeout: boolean, timeRemaining: () => DOMHighResTimeStamp}) => void, options?: {timeout: number}): number;
-  }
-
-  /** Make properties K in T optional. */
-  type MakeOptional<T, K extends keyof T> = {
-    [P in Exclude<keyof T, K>]: T[P]
-  } & {
-    [P in K]+?: T[P]
-  }
-
-  /** An object with the keys in the union K mapped to themselves as values. */
-  type SelfMap<K extends string> = {
-    [P in K]: P;
-  };
-
-  /** Make optional all properties on T and any properties on object properties of T. */
-  type RecursivePartial<T> =
-    // Recurse into arrays and tuples: elements aren't (newly) optional, but any properties they have are.
-    T extends (infer U)[] ? RecursivePartial<U>[] :
-    // Recurse into objects: properties and any of their properties are optional.
-    T extends object ? {[P in keyof T]?: RecursivePartial<T[P]>} :
-    // Strings, numbers, etc. (terminal types) end here.
-    T;
-
-  /** Recursively makes all properties of T read-only. */
-  type Immutable<T> =
-    T extends Function ? T :
-    T extends Array<infer R> ? ImmutableArray<R> :
-    T extends Map<infer K, infer V> ? ImmutableMap<K, V> :
-    T extends Set<infer M> ? ImmutableSet<M> :
-    T extends object ? ImmutableObject<T> :
-    T
-
-  // Intermediate immutable types. Prefer e.g. Immutable<Set<T>> over direct use.
-  type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
-  type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
-  type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
-  type ImmutableObject<T> = {
-    readonly [K in keyof T]: Immutable<T[K]>;
-  };
-
-  /**
-   * Exclude void from T
-   */
-  type NonVoid<T> = T extends void ? never : T;
-
-  /** Remove properties K from T. */
-  type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
-
-  /** Obtain the type of the first parameter of a function. */
-  type FirstParamType<T extends (arg1: any, ...args: any[]) => any> =
-    T extends (arg1: infer P, ...args: any[]) => any ? P : never;
-
-  /**
-   * If `S` is a kebab-style string `S`, convert to camelCase.
-   */
-  type KebabToCamelCase<S> =
-    S extends `${infer T}-${infer U}` ?
-    `${T}${Capitalize<KebabToCamelCase<U>>}` :
-    S
-
-  /** Returns T with any kebab-style property names rewritten as camelCase. */
-  type CamelCasify<T> = {
-    [K in keyof T as KebabToCamelCase<K>]: T[K];
-  }
-}
+import {Artifacts} from './artifacts.js';
+import LHResult from './lhr/lhr.js';
+import {SharedFlagsSettings, OutputMode} from './lhr/settings.js';
 
 /**
  * Extends the flags in SharedFlagsSettings with flags used to configure the
@@ -147,10 +53,8 @@ export interface CliFlags extends Flags {
   verbose: boolean;
   /** A flag to enable logLevel 'silent'. */
   quiet: boolean;
-  /** A flag to print the normalized config for the given config and options, then exit. */
-  printConfig: boolean;
-  /** Use the new Fraggle Rock navigation runner to gather CLI results. */
-  fraggleRock: boolean;
+  /** Use the legacy navigation runner to gather CLI results. */
+  legacyNavigation: boolean;
   /** Path to the file where precomputed lantern data should be read from. */
   precomputedLanternDataPath?: string;
   /** Path to the file where precomputed lantern data should be written to. */
@@ -167,6 +71,10 @@ export interface CliFlags extends Flags {
 export interface RunnerResult {
   lhr: LHResult;
   report: string|string[];
+  /**
+   * @internal
+   * WARNING: Some artifacts are not guaranteed to be stable. The structure is subject to change in minor releases.
+   */
   artifacts: Artifacts;
 }
 

package/types/gatherer.d.ts

@@ -4,36 +4,38 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import _NetworkNode = require('../lighthouse-core/lib/dependency-graph/network-node');
-import _CPUNode = require('../lighthouse-core/lib/dependency-graph/cpu-node');
-import _Simulator = require('../lighthouse-core/lib/dependency-graph/simulator/simulator');
-import Driver = require('../lighthouse-core/gather/driver');
-import ExecutionContext = require('../lighthouse-core/gather/driver/execution-context');
-import Fetcher = require('../lighthouse-core/gather/fetcher');
-import ArbitraryEqualityMap = require('../lighthouse-core/lib/arbitrary-equality-map');
-
-import {Artifacts, BaseArtifacts, FRBaseArtifacts, GathererArtifacts} from './artifacts';
-import Config from './config';
-import {IcuMessage} from './lhr/i18n';
-import Result from './lhr/lhr';
-import Protocol from './protocol';
-import {Trace, DevtoolsLog} from './artifacts';
+import {Protocol as Crdp} from 'devtools-protocol/types/protocol.js';
+import {ProtocolMapping as CrdpMappings} from 'devtools-protocol/types/protocol-mapping.js';
+
+import {NetworkNode as _NetworkNode} from '../core/lib/dependency-graph/network-node.js';
+import {CPUNode as _CPUNode} from '../core/lib/dependency-graph/cpu-node.js';
+import {Simulator as _Simulator} from '../core/lib/dependency-graph/simulator/simulator.js';
+import {Driver} from '../core/legacy/gather/driver.js';
+import {ExecutionContext} from '../core/gather/driver/execution-context.js';
+import {Fetcher} from '../core/gather/fetcher.js';
+import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map.js';
+
+import {Artifacts, BaseArtifacts, FRBaseArtifacts, GathererArtifacts, DevtoolsLog, Trace} from './artifacts.js';
+import Config from './config.js';
+import {IcuMessage} from './lhr/i18n.js';
+import Result from './lhr/lhr.js';
+import Protocol from './protocol.js';
+import Puppeteer from './puppeteer.js';
+
+type CrdpEvents = CrdpMappings.Events;
+type CrdpCommands = CrdpMappings.Commands;
 
 declare module Gatherer {
   /** The Lighthouse wrapper around a raw CDP session. */
   interface FRProtocolSession {
-    setTargetInfo(targetInfo: LH.Crdp.Target.TargetInfo): void;
+    setTargetInfo(targetInfo: Crdp.Target.TargetInfo): void;
     hasNextProtocolTimeout(): boolean;
     getNextProtocolTimeout(): number;
     setNextProtocolTimeout(ms: number): void;
-    on<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    once<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    addProtocolMessageListener(callback: (payload: Protocol.RawEventMessage) => void): void
-    removeProtocolMessageListener(callback: (payload: Protocol.RawEventMessage) => void): void
-    addSessionAttachedListener(callback: (session: FRProtocolSession) => void): void
-    removeSessionAttachedListener(callback: (session: FRProtocolSession) => void): void
-    off<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    sendCommand<TMethod extends keyof LH.CrdpCommands>(method: TMethod, ...params: LH.CrdpCommands[TMethod]['paramsType']): Promise<LH.CrdpCommands[TMethod]['returnType']>;
+    on<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    once<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    off<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    sendCommand<TMethod extends keyof CrdpCommands>(method: TMethod, ...params: CrdpCommands[TMethod]['paramsType']): Promise<CrdpCommands[TMethod]['returnType']>;
     dispose(): Promise<void>;
   }
 
@@ -42,16 +44,22 @@ declare module Gatherer {
     defaultSession: FRProtocolSession;
     executionContext: ExecutionContext;
     fetcher: Fetcher;
+    url: () => Promise<string>;
+    targetManager: {
+      rootSession(): FRProtocolSession;
+      on(event: 'protocolevent', callback: (payload: Protocol.RawEventMessage) => void): void
+      off(event: 'protocolevent', callback: (payload: Protocol.RawEventMessage) => void): void
+    };
   }
 
   /** The limited context interface shared between pre and post Fraggle Rock Lighthouse. */
   interface FRTransitionalContext<TDependencies extends DependencyKey = DefaultDependenciesKey> {
-    /** The URL of the page that is currently active. Might be `about:blank` in the before phases */
-    url: string;
     /** The gather mode Lighthouse is currently in. */
     gatherMode: GatherMode;
     /** The connection to the page being analyzed. */
     driver: FRTransitionalDriver;
+    /** The Puppeteer page handle. Will be undefined in legacy navigation mode. */
+    page?: Puppeteer.Page;
     /** The set of base artifacts that are always collected. */
     baseArtifacts: FRBaseArtifacts;
     /** The cached results of computed artifacts. */
@@ -65,7 +73,7 @@ declare module Gatherer {
   interface FRGatherResult {
     artifacts: Artifacts;
     runnerOptions: {
-      config: Config.FRConfig;
+      resolvedConfig: Config.ResolvedConfig;
       computedCache: Map<string, ArbitraryEqualityMap>
     }
   }
@@ -147,7 +155,7 @@ declare module Gatherer {
   type AnyFRGathererInstance = FRGathererInstanceExpander<Gatherer.DependencyKey>
 
   namespace Simulation {
-    type GraphNode = import('../lighthouse-core/lib/dependency-graph/base-node').Node;
+    type GraphNode = import('../core/lib/dependency-graph/base-node.js').Node;
     type GraphNetworkNode = _NetworkNode;
     type GraphCPUNode = _CPUNode;
     type Simulator = _Simulator;

package/types/internal/cssstyle.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+declare module 'cssstyle/lib/parsers.js' {
+  interface TYPES {
+    INTEGER: 1;
+    NUMBER: 2;
+    LENGTH: 3;
+    PERCENT: 4;
+    URL: 5;
+    COLOR: 6;
+    STRING: 7;
+    ANGLE: 8;
+    KEYWORD: 9;
+    NULL_OR_EMPTY_STR: 10;
+  }
+
+  export var TYPES: TYPES;
+  export function valueType(val: any): TYPES[keyof TYPES] | undefined;
+}

package/types/internal/global.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright 2023 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+/**
+ * @fileoverview Most of our files use the global `LH` namespace to access our types.
+ * This file allows us to use the global namespace while iteratively converting files to use direct type imports.
+ * TODO: Remove this file and import all types directly.
+ */
+
+export * from '../lh.js';
+
+export as namespace LH;

package/types/internal/lighthouse-logger.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright 2017 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.
+ */
+
+declare module 'lighthouse-logger' {
+  interface Status {
+    msg: string;
+    id: string;
+    args?: any[];
+  }
+  export function setLevel(level: string): void;
+  export function isVerbose(): boolean;
+  export function formatProtocol(prefix: string, data: Object, level?: string): void;
+  export function log(title: string, ...args: any[]): void;
+  export function warn(title: string, ...args: any[]): void;
+  export function error(title: string, ...args: any[]): void;
+  export function verbose(title: string, ...args: any[]): void;
+  export function time(status: Status, level?: string): void;
+  export function timeEnd(status: Status, level?: string): void;
+  export function reset(): string;
+  export const cross: string;
+  export const dim: string;
+  export const tick: string;
+  export const bold: string;
+  export const purple: string;
+  export function redify(message: any): string;
+  export function greenify(message: any): string;
+  /** Retrieves and clears all stored time entries */
+  export function takeTimeEntries(): PerformanceEntry[];
+  export function getTimeEntries(): PerformanceEntry[];
+  export const events: import('events').EventEmitter;
+}

package/types/internal/lookup-closest-locale.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+type Locale = import('../lhr/settings.js').Locale;
+
+declare module 'lookup-closest-locale' {
+  function lookupClosestLocale(locale: string[]|string|undefined, available: Record<Locale, any>): Locale|undefined;
+
+  export = lookupClosestLocale;
+}

package/types/internal/node.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+declare global {
+  var isDevtools: boolean | undefined;
+  var isLightrider: boolean | undefined;
+
+  // Augment Intl to include
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales
+  namespace Intl {
+    var getCanonicalLocales: (locales?: string | Array<string>) => Array<string>;
+  }
+
+  // Some functions defined in node are stringified and run in the browser.
+  // Ensure those functions are working with the correct browser environment.
+  interface Window {
+    // Cached native functions/objects for use in case the page overwrites them.
+    // See: `executionContext.cacheNativesOnNewDocument`.
+    __nativePromise: PromiseConstructor;
+    __nativePerformance: Performance;
+    __nativeFetch: typeof fetch,
+    __nativeURL: typeof URL;
+    __ElementMatches: Element['matches'];
+    __HTMLElementBoundingClientRect: HTMLElement['getBoundingClientRect'];
+
+    /** Used for monitoring long tasks in the test page. */
+    ____lastLongTask?: number;
+
+    /** Used by FullPageScreenshot gatherer. */
+    __lighthouseNodesDontTouchOrAllVarianceGoesAway: Map<Element, string>;
+    __lighthouseExecutionContextUniqueIdentifier?: number;
+
+    /** Injected into the page when the `--debug` flag is used. */
+    continueLighthouseRun(): void;
+
+    // Not defined in tsc yet: https://github.com/microsoft/TypeScript/issues/40807
+    requestIdleCallback(callback: (deadline: {didTimeout: boolean, timeRemaining: () => DOMHighResTimeStamp}) => void, options?: {timeout: number}): number;
+  }
+}
+
+export {};

package/types/internal/query-selector.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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.
+ */
+
+/**
+ * @fileoverview Stricter querySelector/querySelectorAll using typed-query-selector.
+ */
+
+import {ParseSelectorToTagNames} from 'typed-query-selector/parser.js';
+
+/** Merge properties of the types in union `T`. Where properties overlap, property types becomes the union of the two (or more) possible types. */
+type MergeTypes<T> = {
+  [K in (T extends unknown ? keyof T : never)]: T extends Record<K, infer U> ? U : never;
+};
+
+// Helper types for strict querySelector/querySelectorAll that includes the overlap
+// between HTML and SVG node names (<a>, <script>, etc).
+// see https://github.com/GoogleChrome/lighthouse/issues/12011
+type HtmlAndSvgElementTagNameMap = MergeTypes<HTMLElementTagNameMap|SVGElementTagNameMap> & {
+  // Fall back to Element (base of HTMLElement and SVGElement) if no specific tag name matches.
+  [id: string]: Element;
+};
+type QuerySelectorParse<I extends string> = ParseSelectorToTagNames<I> extends infer TagNames ?
+  TagNames extends Array<string> ?
+    HtmlAndSvgElementTagNameMap[TagNames[number]] :
+    Element: // Fall back for queries typed-query-selector fails to parse, e.g. `'[alt], [aria-label]'`.
+  never;
+
+declare global {
+  interface ParentNode {
+    querySelector<S extends string>(selector: S): QuerySelectorParse<S> | null;
+    querySelectorAll<S extends string>(selector: S): NodeListOf<QuerySelectorParse<S>>;
+  }
+}

package/types/internal/smokehouse.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license Copyright 2019 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {Artifacts} from '../artifacts.js';
+import Config from '../config.js';
+import LHResult from '../lhr/lhr.js';
+
+declare global {
+  module Smokehouse {
+    interface ExpectedLHR {
+      audits: Record<string, any>;
+      requestedUrl: string;
+      finalDisplayedUrl: string | RegExp;
+      userAgent?: string | RegExp;
+      runWarnings?: any;
+      runtimeError?: {
+        code?: any;
+        message?: any;
+      };
+      timing?: {
+        entries?: any
+      };
+      fullPageScreenshot?: any;
+    }
+
+    export type ExpectedRunnerResult = {
+      lhr: ExpectedLHR,
+      artifacts?: Partial<Record<keyof Artifacts|'_maxChromiumVersion'|'_minChromiumVersion', any>>
+      networkRequests?: any;
+    }
+
+    export interface TestDfn {
+      /** Identification of test. Can be used for group selection (e.g. `yarn smoke pwa` will run all tests with `id.includes('pwa')`). */
+      id: string;
+      /** Expected test results. */
+      expectations: ExpectedRunnerResult;
+      /** An optional custom config. If none is present, uses the default Lighthouse config. */
+      config?: Config;
+      /** If test is performance sensitive, set to true so that it won't be run parallel to other tests. */
+      runSerially?: boolean;
+    }
+
+    /**
+     * A TestDefn type that's compatible with the old array of `expectations` type and the current TestDefn type.
+     * COMPAT: remove when no long needed.
+     * @deprecated
+     */
+    export type BackCompatTestDefn =
+      Omit<Smokehouse.TestDfn, 'expectations'> &
+      {expectations: Smokehouse.ExpectedRunnerResult | Array<Smokehouse.ExpectedRunnerResult>}
+
+    export type LighthouseRunner =
+      {runnerName?: string} & ((url: string, config?: Config, runnerOptions?: {isDebug?: boolean; useLegacyNavigation?: boolean}) => Promise<{lhr: LHResult, artifacts: Artifacts, log: string}>);
+
+    export interface SmokehouseOptions {
+      /** If true, performs extra logging from the test runs. */
+      isDebug?: boolean;
+      /** If true, use the legacy navigation runner. */
+      useLegacyNavigation?: boolean;
+      /** Manually set the number of jobs to run at once. `1` runs all tests serially. */
+      jobs?: number;
+      /** The number of times to retry failing tests before accepting. Defaults to 0. */
+      retries?: number;
+      /** A function that runs Lighthouse with the given options. Defaults to running Lighthouse via the CLI. */
+      lighthouseRunner?: LighthouseRunner;
+      /** A function that gets a list of URLs requested to the server since the last fetch. */
+      takeNetworkRequestUrls?: () => string[];
+      /** A function run once before all smoke tests. */
+      setup?: () => Promise<void>;
+    }
+
+    export interface SmokehouseLibOptions extends SmokehouseOptions {
+      urlFilterRegex?: RegExp;
+      skip?: (test: TestDfn, expectation: ExpectedRunnerResult) => string | false;
+      modify?: (test: TestDfn, expectation: ExpectedRunnerResult) => void;
+      /** String of form `shardNumber/shardTotal`, e.g. `'1/4'`. */
+      shardArg: string | undefined;
+    }
+  }
+}