From 332ddcf3e802c4bf75177a0f98c0a85c086886f2 Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Tue, 17 Apr 2018 14:00:42 -0700 Subject: [PATCH 1/6] core(lhr): lhr-lite proposed typings --- typings/lhr-lite.d.ts | 130 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 typings/lhr-lite.d.ts diff --git a/typings/lhr-lite.d.ts b/typings/lhr-lite.d.ts new file mode 100644 index 000000000000..ef50f83974cb --- /dev/null +++ b/typings/lhr-lite.d.ts @@ -0,0 +1,130 @@ +/** + * @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 global { + module LH { + /** + * The lightweight version of Lighthouse results. + */ + export interface ResultLite { + /** The URL that was supplied to Lighthouse and initially navigated to. */ + requestedUrl: string; + /** The post-redirects URL that Lighthouse loaded. */ + finalUrl: string; + /** The ISO-8601 timestamp of when the results were generated. */ + fetchedAt: string; + /** The version of Lighthouse with which these results were generated. */ + lighthouseVersion: string; + /** An object containing the results of the audits. */ + audits: Record; + /** An object containing the top-level categories, their overall scores, and reference to member audits. */ + categories?: Record; + /** Descriptions of the audit groups referenced by AuditRefs. */ + categoryGroups?: Record; + } + + // ResultLite namespace + export module ResultLite { + export interface Category { + /** The human-friendly name of the category. */ + title: string; + /** A description of what this category is about (e.g. these help you validate your PWA). */ + description: string; + /** The overall score of the category, the weighted average of all its audits. */ + score: number; + /** An array of references to all the audit members of this category. */ + auditRefs: AuditRef[]; + /** An optional description for manual audits within this category. */ + manualDescription?: string; + } + + /** + * A reference to an audit result, with weighting and grouping information + * for its place in this category. + */ + export interface AuditRef { + /** Matches a key in the top-level `audits` object. */ + auditId: string; + /** The weight of the audit's score in the overall category score. */ + weight: number; + /** Optional grouping within the category. Matches the key in the top-level `categoryGroups` object. */ + groupId?: string; + } + + export interface CategoryGroup { + /** The human-friendly name of the category. */ + title: string; + /** A brief description of the purpose of the display group. */ + description: string; + } + + export interface Audit { + /** The brief description of the audit. The text can change depending on if the audit passed or failed. */ + title: string; + /** A more detailed description that describes why the audit is important and links to Lighthouse documentation on the audit; markdown links supported. */ + description: string; + /** The scored value determined by the audit, in the range `0-1`. */ + score: number; + /** + * A string identifying how the score should be interpreted: + * 'binary': pass/fail audit (0 and 1 are only possible scores). + * 'numeric': scores of 0-1 (map to displayed scores of 0-100). + * 'informative': the audit is an FYI only, and can't be interpreted as pass/fail. Ignore the score. + * 'notApplicable': the audit turned out to not apply to the page. Ignore the score. + * 'manual': The audit exists only to tell you to review something yourself. Ignore the score. + */ + scoreDisplayMode: 'binary' | 'numeric' | 'informative' | 'notApplicable' | 'manual'; + /** Extra information provided by some types of audits. */ + details?: AuditDetails; + /** Error message from any exception thrown while running this audit. */ + errorMessage?: string; + } + + export type AuditDetails = AuditMetricDetails | AuditOpportunityDetails | AuditTableDetails; + + export interface AuditMetricDetails { + type: 'opportunity'; + /** The value of the metric expressed in milliseconds. */ + timespanMs?: number; + } + + export interface AuditOpportunityDetails { + type: 'metric'; + wastedMs: number + wastedBytes?: number + } + + export interface AuditTableDetails { + type: 'table'; + headings: AuditTableHeadings[]; + rows: AuditTableRow[]; + } + + export interface AuditTableHeadings { + key: string; + label: string; + valueType: 'url' | 'text' | 'link' | 'timespanMs'; + } + + export type AuditTableRow = WastedBytesDetailsRow | WastedTimeDetailsRow; + + export interface WastedBytesDetailsRow { + url: string; + wastedBytes?: number; + totalBytes?: number; + } + + export interface WastedTimeDetailsRow { + url: string; + wastedMs: number; + totalBytes?: number; + } + } + } +} + +// empty export to keep file a module +export {} From 4c1c3a7374dec8f9b2fa2da8bd9c0ab45fdec9b6 Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Tue, 17 Apr 2018 14:15:57 -0700 Subject: [PATCH 2/6] switcheroo --- typings/lhr-lite.d.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/typings/lhr-lite.d.ts b/typings/lhr-lite.d.ts index ef50f83974cb..1d042e061839 100644 --- a/typings/lhr-lite.d.ts +++ b/typings/lhr-lite.d.ts @@ -86,24 +86,24 @@ declare global { export type AuditDetails = AuditMetricDetails | AuditOpportunityDetails | AuditTableDetails; export interface AuditMetricDetails { - type: 'opportunity'; + type: 'metric'; /** The value of the metric expressed in milliseconds. */ timespanMs?: number; } export interface AuditOpportunityDetails { - type: 'metric'; + type: 'opportunity'; wastedMs: number wastedBytes?: number } export interface AuditTableDetails { type: 'table'; - headings: AuditTableHeadings[]; + headings: AuditColumnHeading[]; rows: AuditTableRow[]; } - export interface AuditTableHeadings { + export interface AuditColumnHeading { key: string; label: string; valueType: 'url' | 'text' | 'link' | 'timespanMs'; From 8a405a33d5176b7143201209f659e347d892ee6a Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Tue, 17 Apr 2018 14:22:12 -0700 Subject: [PATCH 3/6] opportunities also table --- typings/lhr-lite.d.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/typings/lhr-lite.d.ts b/typings/lhr-lite.d.ts index 1d042e061839..e1105e802f00 100644 --- a/typings/lhr-lite.d.ts +++ b/typings/lhr-lite.d.ts @@ -95,6 +95,8 @@ declare global { type: 'opportunity'; wastedMs: number wastedBytes?: number + headings: AuditColumnHeading[]; + rows: AuditTableRow[]; } export interface AuditTableDetails { From e20b98b45cb570ae3a3ea03313d5123865e88264 Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Tue, 17 Apr 2018 14:46:37 -0700 Subject: [PATCH 4/6] feedback --- typings/lhr-lite.d.ts | 71 ++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 38 deletions(-) diff --git a/typings/lhr-lite.d.ts b/typings/lhr-lite.d.ts index e1105e802f00..7bc4f79d37f3 100644 --- a/typings/lhr-lite.d.ts +++ b/typings/lhr-lite.d.ts @@ -75,54 +75,49 @@ declare global { * 'informative': the audit is an FYI only, and can't be interpreted as pass/fail. Ignore the score. * 'notApplicable': the audit turned out to not apply to the page. Ignore the score. * 'manual': The audit exists only to tell you to review something yourself. Ignore the score. + * 'error': There was an error while running the object (check `errorMessage` for details). Ignore the score. */ - scoreDisplayMode: 'binary' | 'numeric' | 'informative' | 'notApplicable' | 'manual'; + scoreDisplayMode: 'binary' | 'numeric' | 'informative' | 'notApplicable' | 'manual' | 'error'; + /** An explanation of audit-related issues encountered on the test page. */ + explanation?: string; /** Extra information provided by some types of audits. */ - details?: AuditDetails; + details?: Audit.MetricDetails | Audit.OpportunityDetails; /** Error message from any exception thrown while running this audit. */ errorMessage?: string; } - export type AuditDetails = AuditMetricDetails | AuditOpportunityDetails | AuditTableDetails; + export module Audit { + export interface MetricDetails { + type: 'metric'; + /** The value of the metric expressed in milliseconds. */ + timespanMs?: number; + } - export interface AuditMetricDetails { - type: 'metric'; - /** The value of the metric expressed in milliseconds. */ - timespanMs?: number; - } - - export interface AuditOpportunityDetails { - type: 'opportunity'; - wastedMs: number - wastedBytes?: number - headings: AuditColumnHeading[]; - rows: AuditTableRow[]; - } - - export interface AuditTableDetails { - type: 'table'; - headings: AuditColumnHeading[]; - rows: AuditTableRow[]; - } - - export interface AuditColumnHeading { - key: string; - label: string; - valueType: 'url' | 'text' | 'link' | 'timespanMs'; - } + export interface OpportunityDetails { + type: 'opportunity'; + wastedMs: number + wastedBytes?: number + headings: ColumnHeading[]; + items: (WastedBytesDetailsItem | WastedTimeDetailsItem)[]; + } - export type AuditTableRow = WastedBytesDetailsRow | WastedTimeDetailsRow; + export interface ColumnHeading { + key: string; + label: string; + valueType: 'url' | 'timespanMs' | 'bytes'; + } - export interface WastedBytesDetailsRow { - url: string; - wastedBytes?: number; - totalBytes?: number; - } + export interface WastedBytesDetailsItem { + url: string; + wastedBytes?: number; + totalBytes?: number; + } - export interface WastedTimeDetailsRow { - url: string; - wastedMs: number; - totalBytes?: number; + export interface WastedTimeDetailsItem { + url: string; + wastedMs: number; + totalBytes?: number; + } } } } From 2aaea82769bad86be97860991c1f71bd8b0e6697 Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Tue, 17 Apr 2018 18:17:38 -0700 Subject: [PATCH 5/6] always categories --- typings/lhr-lite.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typings/lhr-lite.d.ts b/typings/lhr-lite.d.ts index 7bc4f79d37f3..e8ee719b35f7 100644 --- a/typings/lhr-lite.d.ts +++ b/typings/lhr-lite.d.ts @@ -21,7 +21,7 @@ declare global { /** An object containing the results of the audits. */ audits: Record; /** An object containing the top-level categories, their overall scores, and reference to member audits. */ - categories?: Record; + categories: Record; /** Descriptions of the audit groups referenced by AuditRefs. */ categoryGroups?: Record; } From 102c5852623735dac1c0d7091fa5cf26d8a5755b Mon Sep 17 00:00:00 2001 From: Brendan Kenny Date: Fri, 20 Apr 2018 13:18:23 -0700 Subject: [PATCH 6/6] remove groups; add null as score option --- typings/lhr-lite.d.ts | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/typings/lhr-lite.d.ts b/typings/lhr-lite.d.ts index e8ee719b35f7..2a9f310376db 100644 --- a/typings/lhr-lite.d.ts +++ b/typings/lhr-lite.d.ts @@ -22,8 +22,6 @@ declare global { audits: Record; /** An object containing the top-level categories, their overall scores, and reference to member audits. */ categories: Record; - /** Descriptions of the audit groups referenced by AuditRefs. */ - categoryGroups?: Record; } // ResultLite namespace @@ -50,15 +48,6 @@ declare global { auditId: string; /** The weight of the audit's score in the overall category score. */ weight: number; - /** Optional grouping within the category. Matches the key in the top-level `categoryGroups` object. */ - groupId?: string; - } - - export interface CategoryGroup { - /** The human-friendly name of the category. */ - title: string; - /** A brief description of the purpose of the display group. */ - description: string; } export interface Audit { @@ -66,16 +55,16 @@ declare global { title: string; /** A more detailed description that describes why the audit is important and links to Lighthouse documentation on the audit; markdown links supported. */ description: string; - /** The scored value determined by the audit, in the range `0-1`. */ - score: number; + /** The scored value determined by the audit, in the range `0-1`, or null if `scoreDisplayMode` indicates not scored. */ + score: number | null; /** * A string identifying how the score should be interpreted: * 'binary': pass/fail audit (0 and 1 are only possible scores). * 'numeric': scores of 0-1 (map to displayed scores of 0-100). - * 'informative': the audit is an FYI only, and can't be interpreted as pass/fail. Ignore the score. - * 'notApplicable': the audit turned out to not apply to the page. Ignore the score. - * 'manual': The audit exists only to tell you to review something yourself. Ignore the score. - * 'error': There was an error while running the object (check `errorMessage` for details). Ignore the score. + * 'informative': the audit is an FYI only, and can't be interpreted as pass/fail. Score is null and should be ignored. + * 'notApplicable': the audit turned out to not apply to the page. Score is null and should be ignored. + * 'manual': The audit exists only to tell you to review something yourself. Score is null and should be ignored. + * 'error': There was an error while running the object (check `errorMessage` for details). Score is null and should be ignored. */ scoreDisplayMode: 'binary' | 'numeric' | 'informative' | 'notApplicable' | 'manual' | 'error'; /** An explanation of audit-related issues encountered on the test page. */