misc: tighten querySelector types (#12013)

lighthouse-core/lib/page-functions.js

@@ -19,7 +19,11 @@
  * Otherwise, minification will mangle the variable names and break usage.
  */
 
-/** @typedef {HTMLElementTagNameMap & {[id: string]: HTMLElement}} HTMLElementByTagName */
+/**
+ * `typed-query-selector`'s CSS selector parser.
+ * @template {string} T
+ * @typedef {import('typed-query-selector/parser').ParseSelector<T>} ParseSelector
+ */
 
 /* global window document Node ShadowRoot HTMLElement */
 
@@ -98,19 +102,23 @@ function checkTimeSinceLastLongTask() {
  * @template {string} T
  * @param {T} selector Optional simple CSS selector to filter nodes on.
  *     Combinators are not supported.
- * @return {Array<HTMLElementByTagName[T]>}
+ * @return {Array<ParseSelector<T>>}
  */
 function getElementsInDocument(selector) {
   const realMatchesFn = window.__ElementMatches || window.Element.prototype.matches;
-  /** @type {Array<HTMLElement>} */
+  /** @type {Array<ParseSelector<T>>} */
   const results = [];
 
-  /** @param {NodeListOf<HTMLElement>} nodes */
+  /** @param {NodeListOf<Element>} nodes */
   const _findAllElements = nodes => {
     for (let i = 0, el; el = nodes[i]; ++i) {
       if (!selector || realMatchesFn.call(el, selector)) {
-        results.push(el);
+        /** @type {ParseSelector<T>} */
+        // @ts-expect-error - el is verified as matching above, tsc just can't verify it through the .call().
+        const matchedEl = el;
+        results.push(matchedEl);
       }
+
       // If the element has a shadow root, dig deeper.
       if (el.shadowRoot) {
         _findAllElements(el.shadowRoot.querySelectorAll('*'));

types/externs.d.ts

@@ -5,10 +5,8 @@
  */
 
 import _Crdp from 'devtools-protocol/types/protocol';
-import _CrdpMappings from 'devtools-protocol/types/protocol-mapping'
-
-// Import for side effects improving types of querySelector/querySelectorAll.
-import 'typed-query-selector';
+import _CrdpMappings from 'devtools-protocol/types/protocol-mapping';
+import {ParseSelector} from 'typed-query-selector/parser';
 
 declare global {
   // Augment Intl to include
@@ -392,4 +390,10 @@ declare global {
     // Not defined in tsc yet: https://github.com/microsoft/TypeScript/issues/40807
     requestIdleCallback(callback: (deadline: {didTimeout: boolean, timeRemaining: () => DOMHighResTimeStamp}) => void, options?: {timeout: number}): number;
   }
+
+  // Stricter querySelector/querySelectorAll using typed-query-selector.
+  interface ParentNode {
+    querySelector<S extends string>(selector: S): ParseSelector<S> | null;
+    querySelectorAll<S extends string>(selector: S): NodeListOf<ParseSelector<S>>;
+  }
 }