lighthouse 9.0.0-dev.20211117 → 9.0.0-dev.20211121

package/lighthouse-core/lib/statistics.js

@@ -5,6 +5,12 @@
  */
 'use strict';
 
+// The exact double values for the max and min scores possible in each range.
+const MIN_PASSING_SCORE = 0.90000000000000002220446049250313080847263336181640625;
+const MAX_AVERAGE_SCORE = 0.899999999999999911182158029987476766109466552734375;
+const MIN_AVERAGE_SCORE = 0.5;
+const MAX_FAILING_SCORE = 0.499999999999999944488848768742172978818416595458984375;
+
 /**
  * Approximates the Gauss error function, the probability that a random variable
  * from the standard normal distribution lies within [-x, x]. Moved from
@@ -28,37 +34,6 @@ function erf(x) {
   return sign * (1 - y * Math.exp(-x * x));
 }
 
-/**
- * Creates a log-normal distribution à la traceviewer's statistics package.
- * Specified by providing the median value, at which the score will be 0.5,
- * and the falloff, the initial point of diminishing returns where any
- * improvement in value will yield increasingly smaller gains in score. Both
- * values should be in the same units (e.g. milliseconds). See
- *   https://www.desmos.com/calculator/tx1wcjk8ch
- * for an interactive view of the relationship between these parameters and
- * the typical parameterization (location and shape) of the log-normal
- * distribution.
- * @param {number} median
- * @param {number} falloff
- * @return {{computeComplementaryPercentile: function(number): number}}
- */
-function getLogNormalDistribution(median, falloff) {
-  const location = Math.log(median);
-
-  // The "falloff" value specified the location of the smaller of the positive
-  // roots of the third derivative of the log-normal CDF. Calculate the shape
-  // parameter in terms of that value and the median.
-  const logRatio = Math.log(falloff / median);
-  const shape = Math.sqrt(1 - 3 * logRatio - Math.sqrt((logRatio - 3) * (logRatio - 3) - 8)) / 2;
-
-  return {
-    computeComplementaryPercentile(x) {
-      const standardizedX = (Math.log(x) - location) / (Math.SQRT2 * shape);
-      return (1 - erf(standardizedX)) / 2;
-    },
-  };
-}
-
 /**
  * Returns the score (1 - percentile) of `value` in a log-normal distribution
  * specified by the `median` value, at which the score will be 0.5, and a 10th
@@ -76,24 +51,37 @@ function getLogNormalScore({median, p10}, value) {
   // Required for the log-normal distribution.
   if (median <= 0) throw new Error('median must be greater than zero');
   if (p10 <= 0) throw new Error('p10 must be greater than zero');
-  // Not required, but if p10 > median, it flips around and becomes the p90 point.
+  // Not strictly required, but if p10 > median, it flips around and becomes the p90 point.
   if (p10 >= median) throw new Error('p10 must be less than the median');
 
   // Non-positive values aren't in the distribution, so always 1.
   if (value <= 0) return 1;
 
-  // Closest double to `erfc-1(2 * 1/10)`.
+  // Closest double to `erfc-1(1/5)`.
   const INVERSE_ERFC_ONE_FIFTH = 0.9061938024368232;
 
-  // Shape (σ) is `log(p10/median) / (sqrt(2)*erfc^-1(2 * 1/10))` and
+  // Shape (σ) is `|log(p10/median) / (sqrt(2)*erfc^-1(1/5))|` and
   // standardizedX is `1/2 erfc(log(value/median) / (sqrt(2)*σ))`, so simplify a bit.
-  const xLogRatio = Math.log(value / median);
-  const p10LogRatio = -Math.log(p10 / median); // negate to keep σ positive.
+  const xRatio = Math.max(Number.MIN_VALUE, value / median); // value and median are > 0, so is ratio.
+  const xLogRatio = Math.log(xRatio);
+  const p10Ratio = Math.max(Number.MIN_VALUE, p10 / median); // p10 and median are > 0, so is ratio.
+  const p10LogRatio = -Math.log(p10Ratio); // negate to keep σ positive.
   const standardizedX = xLogRatio * INVERSE_ERFC_ONE_FIFTH / p10LogRatio;
   const complementaryPercentile = (1 - erf(standardizedX)) / 2;
 
-  // Clamp to [0, 1] to avoid any floating-point out-of-bounds issues.
-  return Math.min(1, Math.max(0, complementaryPercentile));
+  // Clamp to avoid floating-point out-of-bounds issues and keep score in expected range.
+  let score;
+  if (value <= p10) {
+    // Passing. Clamp to [0.9, 1].
+    score = Math.max(MIN_PASSING_SCORE, Math.min(1, complementaryPercentile));
+  } else if (value <= median) {
+    // Average. Clamp to [0.5, 0.9).
+    score = Math.max(MIN_AVERAGE_SCORE, Math.min(MAX_AVERAGE_SCORE, complementaryPercentile));
+  } else {
+    // Failing. Clamp to [0, 0.5).
+    score = Math.max(0, Math.min(MAX_FAILING_SCORE, complementaryPercentile));
+  }
+  return score;
 }
 
 /**
@@ -112,6 +100,5 @@ function linearInterpolation(x0, y0, x1, y1, x) {
 
 module.exports = {
   linearInterpolation,
-  getLogNormalDistribution,
   getLogNormalScore,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lighthouse",
-  "version": "9.0.0-dev.20211117",
+  "version": "9.0.0-dev.20211121",
   "description": "Automated auditing, performance metrics, and best practices for the web.",
   "main": "./lighthouse-core/index.js",
   "bin": {

package/report/renderer/api.js

@@ -9,13 +9,15 @@
 import {DOM} from '../renderer/dom.js';
 import {ReportRenderer} from '../renderer/report-renderer.js';
 import {ReportUIFeatures} from '../renderer/report-ui-features.js';
+import {CategoryRenderer} from './category-renderer.js';
+import {DetailsRenderer} from './details-renderer.js';
 
 /**
  * @param {LH.Result} lhr
  * @param {LH.Renderer.Options} opts
  * @return {HTMLElement}
  */
-export function renderReport(lhr, opts = {}) {
+function renderReport(lhr, opts = {}) {
   const rootEl = document.createElement('article');
   rootEl.classList.add('lh-root', 'lh-vars');
 
@@ -30,3 +32,35 @@ export function renderReport(lhr, opts = {}) {
   features.initFeatures(lhr);
   return rootEl;
 }
+
+/**
+ * @param {LH.ReportResult.Category} category
+ * @param {Parameters<CategoryRenderer['renderCategoryScore']>[2]=} options
+ * @return {DocumentFragment}
+ */
+function renderCategoryScore(category, options) {
+  const dom = new DOM(document, document.documentElement);
+  const detailsRenderer = new DetailsRenderer(dom);
+  const categoryRenderer = new CategoryRenderer(dom, detailsRenderer);
+  return categoryRenderer.renderCategoryScore(category, {}, options);
+}
+
+/**
+ * @param {Blob} blob
+ * @param {string} filename
+ */
+function saveFile(blob, filename) {
+  const dom = new DOM(document, document.documentElement);
+  dom.saveFile(blob, filename);
+}
+
+/**
+ * @param {string} markdownText
+ * @return {Element}
+ */
+function convertMarkdownCodeSnippets(markdownText) {
+  const dom = new DOM(document, document.documentElement);
+  return dom.convertMarkdownCodeSnippets(markdownText);
+}
+
+export {renderReport, renderCategoryScore, saveFile, convertMarkdownCodeSnippets};

package/report/renderer/category-renderer.js

@@ -348,14 +348,28 @@ export class CategoryRenderer {
   /**
    * @param {LH.ReportResult.Category} category
    * @param {Record<string, LH.Result.ReportGroup>} groupDefinitions
-   * @param {{gatherMode: LH.Result.GatherMode}=} options
+   * @param {{gatherMode: LH.Result.GatherMode, omitLabel?: boolean, onPageAnchorRendered?: (link: HTMLAnchorElement) => void}=} options
    * @return {DocumentFragment}
    */
   renderCategoryScore(category, groupDefinitions, options) {
+    let categoryScore;
     if (options && Util.shouldDisplayAsFraction(options.gatherMode)) {
-      return this.renderCategoryFraction(category);
+      categoryScore = this.renderCategoryFraction(category);
+    } else {
+      categoryScore = this.renderScoreGauge(category, groupDefinitions);
+    }
+
+    if (options?.omitLabel) {
+      const label = this.dom.find('.lh-gauge__label,.lh-fraction__label', categoryScore);
+      label.remove();
     }
-    return this.renderScoreGauge(category, groupDefinitions);
+
+    if (options?.onPageAnchorRendered) {
+      const anchor = this.dom.find('a', categoryScore);
+      options.onPageAnchorRendered(anchor);
+    }
+
+    return categoryScore;
   }
 
   /**

package/report/renderer/report-renderer.js

@@ -224,6 +224,7 @@ export class ReportRenderer {
           e.preventDefault();
           destEl.scrollIntoView();
         });
+        this._opts.onPageAnchorRendered?.(gaugeWrapperEl);
       }
 
 

package/report/test/renderer/category-renderer-test.js

@@ -500,6 +500,34 @@ describe('CategoryRenderer', () => {
     });
   });
 
+  describe('renderCategoryScore', () => {
+    it('removes label if omitLabel is true', () => {
+      const options = {omitLabel: true};
+      const categoryScore = renderer.renderCategoryScore(
+        sampleResults.categories.performance,
+        {},
+        options
+      );
+      const label = categoryScore.querySelector('.lh-gauge__label,.lh-fraction__label');
+      assert.ok(!label);
+    });
+
+    it('uses custom callback if present', () => {
+      const options = {
+        onPageAnchorRendered: link => {
+          link.href = '#index=0&anchor=performance';
+        },
+      };
+      const categoryScore = renderer.renderCategoryScore(
+        sampleResults.categories.performance,
+        {},
+        options
+      );
+      const link = categoryScore.querySelector('a');
+      assert.equal(link.hash, '#index=0&anchor=performance');
+    });
+  });
+
   it('renders audits by weight', () => {
     const defaultAuditRef = {
       title: '',

package/report/test/renderer/report-renderer-test.js

@@ -122,6 +122,35 @@ describe('ReportRenderer', () => {
       }
     });
 
+    it('renders score gauges with custom callback', () => {
+      const sampleResultsCopy = JSON.parse(JSON.stringify(sampleResults));
+
+      const opts = {
+        onPageAnchorRendered: link => {
+          const id = link.hash.substring(1);
+          link.hash = `#index=0&anchor=${id}`;
+        },
+      };
+      const container = renderer._dom.document().body;
+      const output = renderer.renderReport(sampleResultsCopy, container, opts);
+      const anchors = output.querySelectorAll('a.lh-gauge__wrapper, a.lh-fraction__wrapper');
+      const hashes = Array.from(anchors).map(anchor => anchor.hash).filter(hash => hash);
+
+      // One set for the sticky header, on set for the gauges at the top.
+      assert.deepStrictEqual(hashes, [
+        '#index=0&anchor=performance',
+        '#index=0&anchor=accessibility',
+        '#index=0&anchor=best-practices',
+        '#index=0&anchor=seo',
+        '#index=0&anchor=pwa',
+        '#index=0&anchor=performance',
+        '#index=0&anchor=accessibility',
+        '#index=0&anchor=best-practices',
+        '#index=0&anchor=seo',
+        '#index=0&anchor=pwa',
+      ]);
+    });
+
     it('renders plugin score gauge', () => {
       const sampleResultsCopy = JSON.parse(JSON.stringify(sampleResults));
       sampleResultsCopy.categories['lighthouse-plugin-someplugin'] = {

package/report/types/report-renderer.d.ts

@@ -17,6 +17,11 @@ declare module Renderer {
 
     /** Disable the topbar UI component */
     omitTopbar?: boolean;
+    /**
+     * Convert report anchor links to a different format.
+     * Flow report uses this to convert `#seo` to `#index=0&anchor=seo`.
+     */
+    onPageAnchorRendered?: (link: HTMLAnchorElement) => void;
   }
 }
 

package/flow-report/src/wrappers/report-renderer.tsx

@@ -1,53 +0,0 @@
-/**
- * @license Copyright 2021 The Lighthouse Authors. 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.
- */
-
-import {createContext, FunctionComponent} from 'preact';
-import {useContext, useMemo} from 'preact/hooks';
-
-import {CategoryRenderer} from '../../../report/renderer/category-renderer';
-import {DetailsRenderer} from '../../../report/renderer/details-renderer';
-import {DOM} from '../../../report/renderer/dom';
-import {ReportRenderer} from '../../../report/renderer/report-renderer';
-
-interface ReportRendererGlobals {
-   dom: DOM,
-   detailsRenderer: DetailsRenderer,
-   categoryRenderer: CategoryRenderer,
-   reportRenderer: ReportRenderer,
-}
-
-const ReportRendererContext = createContext<ReportRendererGlobals|undefined>(undefined);
-
-function useReportRenderer() {
-  const globals = useContext(ReportRendererContext);
-  if (!globals) throw Error('Globals not defined');
-  return globals;
-}
-
-const ReportRendererProvider: FunctionComponent = ({children}) => {
-  const globals = useMemo(() => {
-    // @ts-expect-error Still using legacy
-    const dom = new DOM(document);
-    const detailsRenderer = new DetailsRenderer(dom);
-    const categoryRenderer = new CategoryRenderer(dom, detailsRenderer);
-    const reportRenderer = new ReportRenderer(dom);
-    return {
-      dom,
-      detailsRenderer,
-      categoryRenderer,
-      reportRenderer,
-    };
-  }, []);
-  return (
-    <ReportRendererContext.Provider value={globals}>{children}</ReportRendererContext.Provider>
-  );
-};
-
-export {
-  ReportRendererContext,
-  ReportRendererProvider,
-  useReportRenderer,
-};