core(tsc): fix audit details type hierarchy

lighthouse-core/audits/accessibility/axe-audit.js

@@ -44,11 +44,11 @@ class AxeAudit extends Audit {
     const impact = rule && rule.impact;
     const tags = rule && rule.tags;
 
-    /** @type {Array<{node: LH.Audit.DetailsRendererNodeDetailsJSON}>} */
+    /** @type {LH.Audit.Details.Table['items']}>} */
     let items = [];
     if (rule && rule.nodes) {
       items = rule.nodes.map(node => ({
-        node: /** @type {LH.Audit.DetailsRendererNodeDetailsJSON} */ ({
+        node: /** @type {LH.Audit.Details.NodeValue} */ ({
           type: 'node',
           selector: Array.isArray(node.target) ? node.target.join(' ') : '',
           path: node.path,
@@ -58,16 +58,27 @@ class AxeAudit extends Audit {
       }));
     }
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'node', itemType: 'node', text: str_(UIStrings.failingElementsHeader)},
     ];
 
+    /** @type {LH.Audit.Details.Diagnostic|undefined} */
+    let diagnostic;
+    if (impact || tags) {
+      diagnostic = {
+        type: 'diagnostic',
+        impact,
+        tags,
+      };
+    }
+
     return {
       rawValue: typeof rule === 'undefined',
       extendedInfo: {
         value: rule,
       },
-      details: {...Audit.makeTableDetails(headings, items), impact, tags},
+      details: {...Audit.makeTableDetails(headings, items), diagnostic},
     };
   }
 }

lighthouse-core/audits/audit.js

@@ -102,10 +102,10 @@ class Audit {
   }
 
   /**
-   * @param {Array<LH.Audit.Heading>} headings
-   * @param {Array<Object<string, LH.Audit.DetailsItem>>} results
-   * @param {LH.Audit.DetailsRendererDetailsSummary=} summary
-   * @return {LH.Audit.DetailsRendererDetailsJSON}
+   * @param {LH.Audit.Details.Table['headings']} headings
+   * @param {LH.Audit.Details.Table['items']} results
+   * @param {LH.Audit.Details.Table['summary']=} summary
+   * @return {LH.Audit.Details.Table}
    */
   static makeTableDetails(headings, results, summary) {
     if (results.length === 0) {
@@ -126,8 +126,8 @@ class Audit {
   }
 
   /**
-   * @param {Array<LH.Audit.Details.OpportunityColumnHeading>} headings
-   * @param {Array<LH.Audit.Details.OpportunityItem>} items
+   * @param {LH.Audit.Details.Opportunity['headings']} headings
+   * @param {LH.Audit.Details.Opportunity['items']} items
    * @param {number} overallSavingsMs
    * @param {number=} overallSavingsBytes
    * @return {LH.Audit.Details.Opportunity}

lighthouse-core/audits/bootup-time.js

@@ -159,6 +159,7 @@ class BootupTime extends Audit {
 
     const summary = {wastedMs: totalBootupTime};
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: str_(i18n.UIStrings.columnURL)},
       {key: 'total', granularity: 1, itemType: 'ms', text: str_(UIStrings.columnTotal)},

lighthouse-core/audits/byte-efficiency/total-byte-weight.js

@@ -86,6 +86,7 @@ class TotalByteWeight extends ByteEfficiencyAudit {
       context.options.scoreMedian
     );
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: str_(i18n.UIStrings.columnURL)},
       {key: 'totalBytes', itemType: 'bytes', text: str_(i18n.UIStrings.columnSize)},

lighthouse-core/audits/byte-efficiency/uses-long-cache-ttl.js

@@ -237,12 +237,19 @@ class CacheHeaders extends Audit {
         totalWastedBytes += wastedBytes;
         if (url.includes('?')) queryStringCount++;
 
+        // Include cacheControl info (if it exists) per url as a diagnostic.
+        /** @type {LH.Audit.Details.Diagnostic|undefined} */
+        let diagnostic;
+        if (cacheControl) {
+          diagnostic = {
+            type: 'diagnostic',
+            ...cacheControl,
+          };
+        }
+
         results.push({
           url,
-          // Include cacheControl in results, but cast as any so table types
-          // are happy. cacheControl is not shown in the table so this is OK.
-          // TODO(bckenny): fix DetailsItem
-          cacheControl: /** @type {any} */ (cacheControl),
+          diagnostic,
           cacheLifetimeMs: cacheLifetimeInSeconds * 1000,
           cacheHitProbability,
           totalBytes,
@@ -260,6 +267,7 @@ class CacheHeaders extends Audit {
         context.options.scoreMedian
       );
 
+      /** @type {LH.Audit.Details.Table['headings']} */
       const headings = [
         {key: 'url', itemType: 'url', text: str_(i18n.UIStrings.columnURL)},
         // TODO(i18n): pre-compute localized duration

lighthouse-core/audits/critical-request-chains.js

@@ -211,7 +211,7 @@ class CriticalRequestChains extends Audit {
           },
         },
         details: {
-          type: 'criticalrequestchain',
+          type: /** @type {'criticalrequestchain'} */('criticalrequestchain'),
           chains: flattenedChains,
           longestChain,
         },

lighthouse-core/audits/deprecations.js

@@ -45,6 +45,7 @@ class Deprecations extends Audit {
       };
     });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'value', itemType: 'code', text: 'Deprecation / Warning'},
       {key: 'url', itemType: 'url', text: 'URL'},

lighthouse-core/audits/diagnostics.js

@@ -67,7 +67,11 @@ class Diagnostics extends Audit {
     return {
       score: 1,
       rawValue: 1,
-      details: {items: [diagnostics]},
+      details: {
+        type: 'diagnostic',
+        // TODO: Consider not nesting diagnostics under `items`.
+        items: [diagnostics],
+      },
     };
   }
 }

lighthouse-core/audits/dobetterweb/dom-size.js

@@ -101,13 +101,14 @@ class DOMSize extends Audit {
       context.options.scoreMedian
     );
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'statistic', itemType: 'text', text: str_(UIStrings.columnStatistic)},
       {key: 'element', itemType: 'code', text: str_(UIStrings.columnElement)},
       {key: 'value', itemType: 'numeric', text: str_(UIStrings.columnValue)},
     ];
 
-    /** @type {Array<Object<string, LH.Audit.DetailsItem>>} */
+    /** @type {LH.Audit.Details.Table['items']} */
     const items = [
       {
         statistic: str_(UIStrings.statisticDOMNodes),

lighthouse-core/audits/dobetterweb/external-anchors-use-rel-noopener.js

@@ -55,6 +55,7 @@ class ExternalAnchorsUseRelNoopenerAudit extends Audit {
         };
       });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'href', itemType: 'url', text: 'URL'},
       {key: 'target', itemType: 'text', text: 'Target'},

lighthouse-core/audits/dobetterweb/geolocation-on-start.js

@@ -37,6 +37,7 @@ class GeolocationOnStart extends ViolationAudit {
     // 'Only request geolocation information in response to a user gesture.'
     const results = ViolationAudit.getViolationResults(artifacts, /geolocation/);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: 'URL'},
       {key: 'label', itemType: 'text', text: 'Location'},

lighthouse-core/audits/dobetterweb/js-libraries.js

@@ -32,10 +32,11 @@ class JsLibrariesAudit extends Audit {
   static audit(artifacts) {
     const libDetails = artifacts.JSLibraries.map(lib => ({
       name: lib.name,
-      version: lib.version, // null if not detected
-      npm: lib.npmPkgName || null, // ~70% of libs come with this field
+      version: lib.version || undefined, // null if not detected
+      npm: lib.npmPkgName || undefined, // ~70% of libs come with this field
     }));
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'name', itemType: 'text', text: 'Name'},
       {key: 'version', itemType: 'text', text: 'Version'},

lighthouse-core/audits/dobetterweb/no-document-write.js

@@ -35,6 +35,7 @@ class NoDocWriteAudit extends ViolationAudit {
   static audit(artifacts) {
     const results = ViolationAudit.getViolationResults(artifacts, /document\.write/);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: 'URL'},
       {key: 'label', itemType: 'text', text: 'Location'},

lighthouse-core/audits/dobetterweb/no-vulnerable-libraries.js

@@ -135,7 +135,7 @@ class NoVulnerableLibrariesAudit extends Audit {
     }
 
     let totalVulns = 0;
-    /** @type {Array<{highestSeverity: string, vulnCount: number, detectedLib: LH.Audit.DetailsRendererLinkDetailsJSON}>} */
+    /** @type {Array<{highestSeverity: string, vulnCount: number, detectedLib: LH.Audit.Details.LinkValue}>} */
     const vulnerabilityResults = [];
 
     const libraryVulns = foundLibraries.map(lib => {
@@ -175,6 +175,7 @@ class NoVulnerableLibrariesAudit extends Audit {
       displayValue = `${totalVulns} vulnerability detected`;
     }
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'detectedLib', itemType: 'link', text: 'Library Version'},
       {key: 'vulnCount', itemType: 'text', text: 'Vulnerability Count'},

lighthouse-core/audits/dobetterweb/notification-on-start.js

@@ -36,6 +36,7 @@ class NotificationOnStart extends ViolationAudit {
   static audit(artifacts) {
     const results = ViolationAudit.getViolationResults(artifacts, /notification permission/);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: 'URL'},
       {key: 'label', itemType: 'text', text: 'Location'},

lighthouse-core/audits/dobetterweb/password-inputs-can-be-pasted-into.js

@@ -29,14 +29,15 @@ class PasswordInputsCanBePastedIntoAudit extends Audit {
   static audit(artifacts) {
     const passwordInputsWithPreventedPaste = artifacts.PasswordInputsWithPreventedPaste;
 
-    /** @type {Array<{node: LH.Audit.DetailsRendererNodeDetailsJSON}>} */
+    /** @type {LH.Audit.Details.Table['items']} */
     const items = [];
     passwordInputsWithPreventedPaste.forEach(input => {
       items.push({
         node: {type: 'node', snippet: input.snippet},
       });
     });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'node', itemType: 'node', text: 'Failing Elements'},
     ];

lighthouse-core/audits/dobetterweb/uses-http2.js

@@ -68,6 +68,7 @@ class UsesHTTP2Audit extends Audit {
         displayValue = `${resources.length} request not served via HTTP/2`;
       }
 
+      /** @type {LH.Audit.Details.Table['headings']} */
       const headings = [
         {key: 'url', itemType: 'url', text: 'URL'},
         {key: 'protocol', itemType: 'text', text: 'Protocol'},

lighthouse-core/audits/dobetterweb/uses-passive-event-listeners.js

@@ -36,6 +36,7 @@ class PassiveEventsAudit extends ViolationAudit {
   static audit(artifacts) {
     const results = ViolationAudit.getViolationResults(artifacts, /passive event listener/);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: 'URL'},
       {key: 'label', itemType: 'text', text: 'Location'},

lighthouse-core/audits/errors-in-console.js

@@ -60,6 +60,7 @@ class ErrorLogs extends Audit {
 
     const tableRows = consoleRows.concat(runtimeExRows);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: 'URL'},
       {key: 'description', itemType: 'code', text: 'Description'},

lighthouse-core/audits/font-display.js

@@ -123,6 +123,7 @@ class FontDisplay extends Audit {
         };
       });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'url', text: str_(i18n.UIStrings.columnURL)},
       {key: 'wastedMs', itemType: 'ms', text: str_(i18n.UIStrings.columnWastedMs)},

lighthouse-core/audits/image-aspect-ratio.js

@@ -93,6 +93,7 @@ class ImageAspectRatio extends Audit {
       if (!processed.doRatiosMatch) results.push(processed);
     });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'url', itemType: 'thumbnail', text: ''},
       {key: 'url', itemType: 'url', text: 'URL'},

lighthouse-core/audits/is-on-https.js

@@ -62,6 +62,7 @@ class HTTPS extends Audit {
 
       const items = Array.from(new Set(insecureURLs)).map(url => ({url}));
 
+      /** @type {LH.Audit.Details.Table['headings']} */
       const headings = [
         {key: 'url', itemType: 'url', text: 'Insecure URL'},
       ];

lighthouse-core/audits/main-thread-tasks.js

@@ -41,6 +41,7 @@ class MainThreadTasks extends Audit {
         };
       });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'type', itemType: 'text', text: 'Task Type'},
       {key: 'startTime', itemType: 'ms', granularity: 1, text: 'Start Time'},

lighthouse-core/audits/mainthread-work-breakdown.js

@@ -105,6 +105,7 @@ class MainThreadWorkBreakdown extends Audit {
       };
     });
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'groupLabel', itemType: 'text', text: str_(UIStrings.columnCategory)},
       {key: 'duration', itemType: 'ms', granularity: 1, text: str_(i18n.UIStrings.columnTimeSpent)},

lighthouse-core/audits/metrics.js

@@ -108,8 +108,12 @@ class Metrics extends Audit {
       }
     }
 
-    /** @type {MetricsDetails} */
-    const details = {items: [metrics]};
+    /** @type {LH.Audit.Details.Diagnostic} */
+    const details = {
+      type: 'diagnostic',
+      // TODO: Consider not nesting metrics under `items`.
+      items: [metrics],
+    };
 
     return {
       score: 1,
@@ -155,6 +159,4 @@ class Metrics extends Audit {
  * @property {number} observedSpeedIndexTs
  */
 
-/** @typedef {{items: [UberMetricsItem]}} MetricsDetails */
-
 module.exports = Metrics;

lighthouse-core/audits/mixed-content.js

@@ -129,6 +129,7 @@ class MixedContent extends Audit {
       const displayValue = `${Util.formatNumber(upgradeableResources.length)}
           ${upgradeableResources.length === 1 ? 'request' : 'requests'}`;
 
+      /** @type {LH.Audit.Details.Table['headings']} */
       const headings = [
         {key: 'fullUrl', itemType: 'url', text: 'URL'},
       ];

lighthouse-core/audits/multi-check-audit.js

@@ -41,7 +41,13 @@ class MultiCheckAudit extends Audit {
       });
     }
 
-    const details = {items: [detailsItem]};
+    // Include the detailed pass/fail checklist as a diagnostic.
+    /** @type {LH.Audit.Details.Diagnostic} */
+    const details = {
+      type: 'diagnostic',
+      // TODO: Consider not nesting detailsItem under `items`.
+      items: [detailsItem],
+    };
 
     // If we fail, share the failures
     if (result.failures.length > 0) {

lighthouse-core/audits/network-requests.js

@@ -53,6 +53,7 @@ class NetworkRequests extends Audit {
         };
       });
 
+      /** @type {LH.Audit.Details.Table['headings']} */
       const headings = [
         {key: 'url', itemType: 'url', text: 'URL'},
         {key: 'startTime', itemType: 'ms', granularity: 1, text: 'Start Time'},

lighthouse-core/audits/network-rtt.js

@@ -59,6 +59,7 @@ class NetworkRTT extends Audit {
 
     results.sort((a, b) => b.rtt - a.rtt);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'origin', itemType: 'text', text: str_(i18n.UIStrings.columnURL)},
       {key: 'rtt', itemType: 'ms', granularity: 1, text: str_(i18n.UIStrings.columnTimeSpent)},

lighthouse-core/audits/network-server-latency.js

@@ -57,6 +57,7 @@ class NetworkServerLatency extends Audit {
 
     results.sort((a, b) => b.serverReponseTime - a.serverReponseTime);
 
+    /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'origin', itemType: 'text', text: str_(i18n.UIStrings.columnURL)},
       {key: 'serverReponseTime', itemType: 'ms', granularity: 1,

lighthouse-core/audits/predictive-perf.js

@@ -90,7 +90,11 @@ class PredictivePerf extends Audit {
       score,
       rawValue: values.roughEstimateOfTTI,
       displayValue: Util.formatMilliseconds(values.roughEstimateOfTTI),
-      details: {items: [values]},
+      details: {
+        type: 'diagnostic',
+        // TODO: Consider not nesting values under `items`.
+        items: [values],
+      },
     };
   }
 }