core: add type checking to audit and gatherer base classes

lighthouse-core/audits/audit.js

@@ -3,7 +3,6 @@
  * 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.
  */
-// @ts-nocheck
 'use strict';
 
 const statistics = require('../lib/statistics');
@@ -19,14 +18,14 @@ const clampTo2Decimals = val => Math.round(val * 100) / 100;
 
 class Audit {
   /**
-   * @return {!string}
+   * @return {string}
    */
   static get DEFAULT_PASS() {
     return DEFAULT_PASS;
   }
 
   /**
-   * @return {{NUMERIC: string, BINARY: string}}
+   * @return {Audit.ScoringModes}
    */
   static get SCORING_MODES() {
     return {
@@ -36,14 +35,14 @@ class Audit {
   }
 
   /**
-   * @throws {Error}
+   * @return {Audit.Meta}
    */
   static get meta() {
     throw new Error('Audit meta information must be overridden.');
   }
 
   /**
-   * Computes a clamped score between 0 and 100 based on the measured value. Score is determined by
+   * Computes a clamped score between 0 and 1 based on the measured value. Score is determined by
    * considering a log-normal distribution governed by the two control points, point of diminishing
    * returns and the median value, and returning the percentage of sites that have higher value.
    *
@@ -65,9 +64,9 @@ class Audit {
   }
 
   /**
-   * @param {!Audit} audit
+   * @param {typeof Audit} audit
    * @param {string} debugString
-   * @return {!AuditFullResult}
+   * @return {LH.AuditFullResult}
    */
   static generateErrorAuditResult(audit, debugString) {
     return Audit.generateAuditResult(audit, {
@@ -78,10 +77,10 @@ class Audit {
   }
 
   /**
-   * @param {!Audit.Headings} headings
-   * @param {!Array<!Object<string, string>>} results
-   * @param {!DetailsRenderer.DetailsSummary} summary
-   * @return {!DetailsRenderer.DetailsJSON}
+   * @param {Audit.Headings} headings
+   * @param {Array<Object<string, string>>} results
+   * @param {Audit.DetailsRenderer.DetailsSummary} summary
+   * @return {Audit.DetailsRenderer.DetailsJSON}
    */
   static makeTableDetails(headings, results, summary) {
     if (results.length === 0) {
@@ -102,9 +101,9 @@ class Audit {
   }
 
   /**
-   * @param {!Audit} audit
-   * @param {!AuditResult} result
-   * @return {{score: number, scoreDisplayMode: string}}
+   * @param {typeof Audit} audit
+   * @param {LH.AuditResult} result
+   * @return {{score: number, scoreDisplayMode: Audit.ScoringModeValues}}
    */
   static _normalizeAuditScore(audit, result) {
     // Cast true/false to 1/0
@@ -125,9 +124,9 @@ class Audit {
   }
 
   /**
-   * @param {!Audit} audit
-   * @param {!AuditResult} result
-   * @return {!AuditFullResult}
+   * @param {typeof Audit} audit
+   * @param {LH.AuditResult} result
+   * @return {LH.AuditFullResult}
    */
   static generateAuditResult(audit, result) {
     if (typeof result.rawValue === 'undefined') {
@@ -175,6 +174,28 @@ class Audit {
 
 module.exports = Audit;
 
+/**
+ * @typedef {Object} Audit.ScoringModes
+ * @property {'numeric'} NUMERIC
+ * @property {'binary'} BINARY
+ */
+
+/**
+ * @typedef {Audit.ScoringModes[keyof Audit.ScoringModes]} Audit.ScoringModeValues
+ */
+
+/**
+ * @typedef {Object} Audit.Meta
+ * @property {string} name
+ * @property {string} description
+ * @property {string} helpText
+ * @property {Array<string>} requiredArtifacts
+ * @property {string} [failureDescription]
+ * @property {boolean} [informative]
+ * @property {boolean} [manual]
+ * @property {Audit.ScoringModeValues} [scoreDisplayMode]
+ */
+
 /**
  * @typedef {Object} Audit.Heading
  * @property {string} key
@@ -191,5 +212,20 @@ module.exports = Audit;
  * @property {number} results
  * @property {Audit.Headings} headings
  * @property {boolean} passes
- * @property {string=} debugString
+ * @property {string} [debugString]
+ */
+
+// TODO: placeholder typedefs until Details are typed
+/**
+ * @typedef {void} Audit.DetailsRenderer.DetailsSummary
+ * @property {number} [wastedMs]
+ * @property {number} [wastedKb]
+ */
+
+/**
+ * @typedef {object} Audit.DetailsRenderer.DetailsJSON
+ * @property {'table'} type
+ * @property {Array<Audit.Heading>} headings
+ * @property {Array<Object<string, string>>} items
+ * @property {Audit.DetailsRenderer.DetailsSummary} summary
  */

lighthouse-core/gather/gatherers/gatherer.js

@@ -28,28 +28,42 @@ class Gatherer {
 
   /**
    * Called before navigation to target url.
-   * @param {!Object} options
+   * @param {Gatherer.PassContext} passContext
+   * @return {*|!Promise<*>}
    */
-  beforePass(options) { }
+  beforePass(passContext) { }
 
   /**
    * Called after target page is loaded. If a trace is enabled for this pass,
    * the trace is still being recorded.
-   * @param {!Object} options
+   * @param {Gatherer.PassContext} passContext
+   * @return {*|!Promise<*>}
    */
-  pass(options) { }
+  pass(passContext) { }
 
   /**
    * Called after target page is loaded, all gatherer `pass` methods have been
    * executed, and — if generated in this pass — the trace is ended. The trace
    * and record of network activity are provided in `loadData`.
-   * @param {!Object} options
-   * @param {{networkRecords: !Array, trace: {traceEvents: !Array}}} loadData
+   * @param {Gatherer.PassContext} passContext
+   * @param {Gatherer.LoadData} loadData
    * @return {*|!Promise<*>}
    */
-  afterPass(options, loadData) { }
+  afterPass(passContext, loadData) { }
 
   /* eslint-enable no-unused-vars */
 }
 
+/**
+ * @typedef {Object} Gatherer.PassContext
+ * @property {object} options
+ */
+
+/**
+ * @typedef {Object} Gatherer.LoadData
+ * @property {Array<LH.NetworkRequest>} networkRecords
+ * @property {Array<void>} devtoolsLog
+ * @property {{traceEvents: Array<LH.TraceEvent>}} trace
+ */
+
 module.exports = Gatherer;

tsconfig.json

@@ -16,8 +16,10 @@
   },
   "include": [
     "lighthouse-cli/**/*.js",
+    "lighthouse-core/audits/audit.js",
     "lighthouse-core/lib/dependency-graph/**/*.js",
     "lighthouse-core/gather/connections/**/*.js",
+    "lighthouse-core/gather/gatherers/gatherer.js",
     "./typings/externs.d.ts"
   ],
   "exclude": [

typings/externs.d.ts

@@ -4,7 +4,7 @@
  * 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.
  */
 
-export as namespace LH;
+declare namespace LH {
 
   export interface Flags {
     _: string[];
@@ -34,29 +34,30 @@ export interface Flags {
   export interface Config {}
 
   export interface AuditResult {
-  rawValue: boolean | number;
+    rawValue: boolean | number | null;
     displayValue?: string;
     debugString?: string;
     score?: number;
-  optimalValue: number | string;
     extendedInfo?: {value: string};
+    notApplicable?: boolean;
+    error?: boolean;
+    // TODO: define details
+    details?: object;
   }
 
   export interface AuditResults {
     [metric: string]: AuditResult;
   }
 
-export interface AuditFullResult {
-  rawValue: boolean | number;
+  export interface AuditFullResult extends AuditResult {
     displayValue: string;
-  debugString?: string;
     score: number;
-  scoreDisplayMode: string;
-  error?: boolean;
+    scoreDisplayMode: 'numeric' | 'binary';
     description: string;
     name: string;
     helpText?: string;
-  extendedInfo?: {value: string};
+    informative?: boolean;
+    manual?: boolean;
   }
 
   export interface AuditFullResults {
@@ -140,3 +141,4 @@ export interface DevToolsJsonTarget {
     url: string;
     webSocketDebuggerUrl: string;
   }
+}