From 7540df00f994cab039eedb6ab7bcb212a8e91d9c Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Thu, 15 Mar 2018 18:15:59 -0700 Subject: [PATCH 1/3] misc(tsc): reorganize and expose external interfaces --- lighthouse-cli/bin.js | 1 - lighthouse-core/audits/audit.js | 76 +++--------------- lighthouse-core/gather/gatherers/gatherer.js | 20 +---- .../simulator/network-analyzer.js | 6 +- lighthouse-core/report/v2/renderer/util.js | 2 +- package.json | 2 +- tsconfig.json | 2 +- typings/audit.d.ts | 79 +++++++++++++++++++ typings/externs.d.ts | 33 +------- typings/gatherer.d.ts | 17 ++++ yarn.lock | 6 +- 11 files changed, 121 insertions(+), 123 deletions(-) create mode 100644 typings/audit.d.ts create mode 100644 typings/gatherer.d.ts diff --git a/lighthouse-cli/bin.js b/lighthouse-cli/bin.js index d2542fb6d338..3b3acd528bbd 100644 --- a/lighthouse-cli/bin.js +++ b/lighthouse-cli/bin.js @@ -16,7 +16,6 @@ const runLighthouse = require('./run').runLighthouse; const log = require('lighthouse-logger'); // @ts-ignore const perfOnlyConfig = require('../lighthouse-core/config/perf.json'); -// @ts-ignore const mixedContentConfig = require('../lighthouse-core/config/mixed-content.js'); // @ts-ignore const pkg = require('../package.json'); diff --git a/lighthouse-core/audits/audit.js b/lighthouse-core/audits/audit.js index 7f84ccc76fed..a57e41d07900 100644 --- a/lighthouse-core/audits/audit.js +++ b/lighthouse-core/audits/audit.js @@ -25,7 +25,7 @@ class Audit { } /** - * @return {Audit.ScoringModes} + * @return {LH.Audit.ScoringModes} */ static get SCORING_MODES() { return { @@ -35,7 +35,7 @@ class Audit { } /** - * @return {Audit.Meta} + * @return {LH.Audit.Meta} */ static get meta() { throw new Error('Audit meta information must be overridden.'); @@ -66,7 +66,7 @@ class Audit { /** * @param {typeof Audit} audit * @param {string} debugString - * @return {LH.AuditFullResult} + * @return {LH.Audit.Result} */ static generateErrorAuditResult(audit, debugString) { return Audit.generateAuditResult(audit, { @@ -77,10 +77,10 @@ class Audit { } /** - * @param {Audit.Headings} headings + * @param {Array} headings * @param {Array>} results - * @param {Audit.DetailsRenderer.DetailsSummary} summary - * @return {Audit.DetailsRenderer.DetailsJSON} + * @param {LH.Audit.DetailsRendererDetailsSummary} summary + * @return {LH.Audit.DetailsRendererDetailsJSON} */ static makeTableDetails(headings, results, summary) { if (results.length === 0) { @@ -102,8 +102,8 @@ class Audit { /** * @param {typeof Audit} audit - * @param {LH.AuditResult} result - * @return {{score: number, scoreDisplayMode: Audit.ScoringModeValues}} + * @param {LH.Audit.Product} result + * @return {{score: number, scoreDisplayMode: LH.Audit.ScoringModeValue}} */ static _normalizeAuditScore(audit, result) { // Cast true/false to 1/0 @@ -125,8 +125,8 @@ class Audit { /** * @param {typeof Audit} audit - * @param {LH.AuditResult} result - * @return {LH.AuditFullResult} + * @param {LH.Audit.Product} result + * @return {LH.Audit.Result} */ static generateAuditResult(audit, result) { if (typeof result.rawValue === 'undefined') { @@ -173,59 +173,3 @@ 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} requiredArtifacts - * @property {string} [failureDescription] - * @property {boolean} [informative] - * @property {boolean} [manual] - * @property {Audit.ScoringModeValues} [scoreDisplayMode] - */ - -/** - * @typedef {Object} Audit.Heading - * @property {string} key - * @property {string} itemType - * @property {string} text - */ - -/** - * @typedef {Array} Audit.Headings - */ - -/** - * @typedef {Object} Audit.HeadingsResult - * @property {number} results - * @property {Audit.Headings} headings - * @property {boolean} passes - * @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} headings - * @property {Array>} items - * @property {Audit.DetailsRenderer.DetailsSummary} summary - */ diff --git a/lighthouse-core/gather/gatherers/gatherer.js b/lighthouse-core/gather/gatherers/gatherer.js index 529a75e38fcb..fc8e3047dd47 100644 --- a/lighthouse-core/gather/gatherers/gatherer.js +++ b/lighthouse-core/gather/gatherers/gatherer.js @@ -28,7 +28,7 @@ class Gatherer { /** * Called before navigation to target url. - * @param {Gatherer.PassContext} passContext + * @param {LH.Gatherer.PassContext} passContext * @return {*|!Promise<*>} */ beforePass(passContext) { } @@ -36,7 +36,7 @@ class Gatherer { /** * Called after target page is loaded. If a trace is enabled for this pass, * the trace is still being recorded. - * @param {Gatherer.PassContext} passContext + * @param {LH.Gatherer.PassContext} passContext * @return {*|!Promise<*>} */ pass(passContext) { } @@ -45,8 +45,8 @@ class Gatherer { * 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 {Gatherer.PassContext} passContext - * @param {Gatherer.LoadData} loadData + * @param {LH.Gatherer.PassContext} passContext + * @param {LH.Gatherer.LoadData} loadData * @return {*|!Promise<*>} */ afterPass(passContext, loadData) { } @@ -54,16 +54,4 @@ class Gatherer { /* eslint-enable no-unused-vars */ } -/** - * @typedef {Object} Gatherer.PassContext - * @property {object} options - */ - -/** - * @typedef {Object} Gatherer.LoadData - * @property {Array} networkRecords - * @property {Array} devtoolsLog - * @property {{traceEvents: Array}} trace - */ - module.exports = Gatherer; diff --git a/lighthouse-core/lib/dependency-graph/simulator/network-analyzer.js b/lighthouse-core/lib/dependency-graph/simulator/network-analyzer.js index f81e7e547c43..efd7b5862f1f 100644 --- a/lighthouse-core/lib/dependency-graph/simulator/network-analyzer.js +++ b/lighthouse-core/lib/dependency-graph/simulator/network-analyzer.js @@ -7,7 +7,7 @@ const INITIAL_CWD = 14 * 1024; -module.exports = class NetworkAnalyzer { +class NetworkAnalyzer { /** * @return {string} */ @@ -303,7 +303,9 @@ module.exports = class NetworkAnalyzer { const estimatesByOrigin = NetworkAnalyzer._estimateResponseTimeByOrigin(records, rttByOrigin); return NetworkAnalyzer.summarize(estimatesByOrigin); } -}; +} + +module.exports = NetworkAnalyzer; /** * @typedef NetworkAnalyzer.Summary diff --git a/lighthouse-core/report/v2/renderer/util.js b/lighthouse-core/report/v2/renderer/util.js index 0e3d67fe5271..2c9a0b91488a 100644 --- a/lighthouse-core/report/v2/renderer/util.js +++ b/lighthouse-core/report/v2/renderer/util.js @@ -118,7 +118,7 @@ class Util { /** * @param {!URL} parsedUrl - * @param {{numPathParts: (number|undefined), preserveQuery: (boolean|undefined), preserveHost: (boolean|undefined)}=} options + * @param {{numPathParts?: number, preserveQuery?: boolean, preserveHost?: boolean}=} options * @return {string} */ static getURLDisplayName(parsedUrl, options) { diff --git a/package.json b/package.json index 2bf81a0d18c7..2039ee647b4a 100644 --- a/package.json +++ b/package.json @@ -77,7 +77,7 @@ "mocha": "^3.2.0", "npm-run-posix-or-windows": "^2.0.2", "sinon": "^2.3.5", - "typescript": "2.7.2", + "typescript": "^2.8.0-rc", "zone.js": "^0.7.3" }, "dependencies": { diff --git a/tsconfig.json b/tsconfig.json index ffbecdb2de06..b29a8e2972b8 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -20,7 +20,7 @@ "lighthouse-core/lib/dependency-graph/**/*.js", "lighthouse-core/gather/connections/**/*.js", "lighthouse-core/gather/gatherers/gatherer.js", - "./typings/externs.d.ts" + "./typings/*.d.ts" ], "exclude": [ "lighthouse-cli/test/**/*.js" diff --git a/typings/audit.d.ts b/typings/audit.d.ts new file mode 100644 index 000000000000..f1844ba4c081 --- /dev/null +++ b/typings/audit.d.ts @@ -0,0 +1,79 @@ +/** + * @license Copyright 2018 Google Inc. 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 namespace LH.Audit { + export interface ScoringModes { + NUMERIC: 'numeric'; + BINARY: 'binary'; + } + + export type ScoringModeValue = Audit.ScoringModes[keyof Audit.ScoringModes]; + + export interface Meta { + name: string; + description: string; + helpText: string; + requiredArtifacts: Array; + failureDescription?: string; + informative?: boolean; + manual?: boolean; + scoreDisplayMode?: Audit.ScoringModeValue; + } + + export interface Heading { + key: string; + itemType: string; + text: string; + } + + export interface HeadingsResult { + results: number; + headings: Array; + passes: boolean; + debugString?: string; + } + + // TODO: placeholder typedefs until Details are typed + export interface DetailsRendererDetailsSummary { + wastedMs?: number; + wastedKb?: number; + } + + // TODO: placeholder typedefs until Details are typed + export interface DetailsRendererDetailsJSON { + type: 'table'; + headings: Array; + items: Array<{[x: string]: string}>; + summary: DetailsRendererDetailsSummary; + } + + export interface Product { + rawValue: boolean | number | null; + displayValue?: string; + debugString?: string; + score?: number; + extendedInfo?: {value: string}; + notApplicable?: boolean; + error?: boolean; + // TODO: define details + details?: object; + } + + export interface Result extends Product { + displayValue: string; + score: number; + scoreDisplayMode: ScoringModeValue; + description: string; + name: string; + helpText?: string; + informative?: boolean; + manual?: boolean; + } + + export interface Results { + [metric: string]: Result; + } +} diff --git a/typings/externs.d.ts b/typings/externs.d.ts index 668fbc6634f2..3f494619c06e 100644 --- a/typings/externs.d.ts +++ b/typings/externs.d.ts @@ -33,40 +33,9 @@ declare namespace LH { export interface Config {} - export interface AuditResult { - rawValue: boolean | number | null; - displayValue?: string; - debugString?: string; - score?: number; - extendedInfo?: {value: string}; - notApplicable?: boolean; - error?: boolean; - // TODO: define details - details?: object; - } - - export interface AuditResults { - [metric: string]: AuditResult; - } - - export interface AuditFullResult extends AuditResult { - displayValue: string; - score: number; - scoreDisplayMode: 'numeric' | 'binary'; - description: string; - name: string; - helpText?: string; - informative?: boolean; - manual?: boolean; - } - - export interface AuditFullResults { - [metric: string]: AuditFullResult; - } - export interface Results { url: string; - audits: AuditFullResults; + audits: LH.Audit.Results; lighthouseVersion: string; artifacts?: Object; initialUrl: string; diff --git a/typings/gatherer.d.ts b/typings/gatherer.d.ts new file mode 100644 index 000000000000..ca2f627df85b --- /dev/null +++ b/typings/gatherer.d.ts @@ -0,0 +1,17 @@ +/** + * @license Copyright 2018 Google Inc. 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 namespace LH.Gatherer { + export interface PassContext { + options: object; + } + + export interface LoadData { + networkRecords: Array; + devtoolsLog: Array; + trace: {trraceEvents: Array} + } +} diff --git a/yarn.lock b/yarn.lock index a11787a6994c..292a06935c3c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4097,9 +4097,9 @@ typedarray@^0.0.6: version "0.0.6" resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777" -typescript@2.7.2: - version "2.7.2" - resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.7.2.tgz#2d615a1ef4aee4f574425cdff7026edf81919836" +typescript@^2.8.0-rc: + version "2.8.0-rc" + resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.8.0-rc.tgz#a0256b7d1d39fb7493ba0403f55e95d31e8bc374" uglify-js@^2.6: version "2.7.3" From 0b56457224903a9ae65cea039860aef3afc8c9cf Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Fri, 16 Mar 2018 12:55:21 -0700 Subject: [PATCH 2/3] fix closure and feedback --- lighthouse-core/report/v2/renderer/util.js | 6 ++++-- typings/audit.d.ts | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/lighthouse-core/report/v2/renderer/util.js b/lighthouse-core/report/v2/renderer/util.js index 2c9a0b91488a..be9b718889bb 100644 --- a/lighthouse-core/report/v2/renderer/util.js +++ b/lighthouse-core/report/v2/renderer/util.js @@ -118,11 +118,13 @@ class Util { /** * @param {!URL} parsedUrl - * @param {{numPathParts?: number, preserveQuery?: boolean, preserveHost?: boolean}=} options + * @param {{numPathParts: (number|undefined), preserveQuery: (boolean|undefined), preserveHost: (boolean|undefined)}=} options * @return {string} */ static getURLDisplayName(parsedUrl, options) { - options = options || {}; + // Closure optional properties aren't optional in tsc, so fallback needs undefined values. + options = options || {numPathParts: undefined, preserveQuery: undefined, + preserveHost: undefined}; const numPathParts = options.numPathParts !== undefined ? options.numPathParts : 2; const preserveQuery = options.preserveQuery !== undefined ? options.preserveQuery : true; const preserveHost = options.preserveHost || false; diff --git a/typings/audit.d.ts b/typings/audit.d.ts index f1844ba4c081..6f131d2e9818 100644 --- a/typings/audit.d.ts +++ b/typings/audit.d.ts @@ -39,7 +39,7 @@ declare namespace LH.Audit { // TODO: placeholder typedefs until Details are typed export interface DetailsRendererDetailsSummary { wastedMs?: number; - wastedKb?: number; + wastedBytes?: number; } // TODO: placeholder typedefs until Details are typed From 9501cba0391684a4fe928d0d537afb6ee4ee63e3 Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Fri, 16 Mar 2018 15:16:23 -0700 Subject: [PATCH 3/3] break inheritance between audit product and audit result --- typings/audit.d.ts | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/typings/audit.d.ts b/typings/audit.d.ts index 6f131d2e9818..167415dc92aa 100644 --- a/typings/audit.d.ts +++ b/typings/audit.d.ts @@ -50,6 +50,7 @@ declare namespace LH.Audit { summary: DetailsRendererDetailsSummary; } + // Type returned by Audit.audit(). Only rawValue is required. export interface Product { rawValue: boolean | number | null; displayValue?: string; @@ -62,15 +63,23 @@ declare namespace LH.Audit { details?: object; } - export interface Result extends Product { + /* Audit result returned in Lighthouse report. All audits offer a description and score of 0-1 */ + export interface Result { + rawValue: boolean | number | null; displayValue: string; + debugString?: string; score: number; scoreDisplayMode: ScoringModeValue; description: string; + extendedInfo?: {value: string}; + notApplicable?: boolean; + error?: boolean; name: string; helpText?: string; informative?: boolean; manual?: boolean; + // TODO: define details + details?: object; } export interface Results {