From 00bd2c4607ede4fe8282324a482b2ff08c99de0a Mon Sep 17 00:00:00 2001 From: Adam Henson Date: Thu, 2 Jul 2020 10:08:49 -0400 Subject: [PATCH] chore: docs --- node_modules/is-plain-object/index.es.js | 46 +++++++ .../test/fixtures/perf/delayed-element.js | 48 +++++++ .../lighthouse-core/audits/long-tasks.js | 124 ++++++++++++++++++ .../audits/seo/crawlable-anchors.js | 100 ++++++++++++++ .../gather/gatherers/inspector-issues.js | 70 ++++++++++ .../lighthouse/lighthouse-core/lib/lh-env.js | 12 ++ .../lighthouse-core/lib/median-run.js | 93 +++++++++++++ .../lighthouse-core/lib/third-party-web.js | 49 +++++++ 8 files changed, 542 insertions(+) create mode 100644 node_modules/is-plain-object/index.es.js create mode 100644 node_modules/lighthouse/lighthouse-cli/test/fixtures/perf/delayed-element.js create mode 100644 node_modules/lighthouse/lighthouse-core/audits/long-tasks.js create mode 100644 node_modules/lighthouse/lighthouse-core/audits/seo/crawlable-anchors.js create mode 100644 node_modules/lighthouse/lighthouse-core/gather/gatherers/inspector-issues.js create mode 100644 node_modules/lighthouse/lighthouse-core/lib/lh-env.js create mode 100644 node_modules/lighthouse/lighthouse-core/lib/median-run.js create mode 100644 node_modules/lighthouse/lighthouse-core/lib/third-party-web.js diff --git a/node_modules/is-plain-object/index.es.js b/node_modules/is-plain-object/index.es.js new file mode 100644 index 000000000..805ba579d --- /dev/null +++ b/node_modules/is-plain-object/index.es.js @@ -0,0 +1,46 @@ +/*! + * isobject + * + * Copyright (c) 2014-2017, Jon Schlinkert. + * Released under the MIT License. + */ + +function isObject(val) { + return val != null && typeof val === 'object' && Array.isArray(val) === false; +} + +/*! + * is-plain-object + * + * Copyright (c) 2014-2017, Jon Schlinkert. + * Released under the MIT License. + */ + +function isObjectObject(o) { + return isObject(o) === true + && Object.prototype.toString.call(o) === '[object Object]'; +} + +function isPlainObject(o) { + var ctor,prot; + + if (isObjectObject(o) === false) return false; + + // If has modified constructor + ctor = o.constructor; + if (typeof ctor !== 'function') return false; + + // If has modified prototype + prot = ctor.prototype; + if (isObjectObject(prot) === false) return false; + + // If constructor does not have an Object-specific method + if (prot.hasOwnProperty('isPrototypeOf') === false) { + return false; + } + + // Most likely a plain Object + return true; +} + +export default isPlainObject; diff --git a/node_modules/lighthouse/lighthouse-cli/test/fixtures/perf/delayed-element.js b/node_modules/lighthouse/lighthouse-cli/test/fixtures/perf/delayed-element.js new file mode 100644 index 000000000..f267b9c57 --- /dev/null +++ b/node_modules/lighthouse/lighthouse-cli/test/fixtures/perf/delayed-element.js @@ -0,0 +1,48 @@ +/** + * @license Copyright 2020 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. + */ + +/* eslint-disable */ + +/** Create long tasks on the main thread. */ +function stall(ms) { + const start = performance.now(); + while (performance.now() - start < ms) ; +} + +/** Render large number of elements to fill up the backend node cache. */ +async function rerender(iterations) { + const waitForAnimationFrame = () => new Promise(r => requestAnimationFrame(r)) + + for (let i = 0; i < iterations; i++) { + const filler = `
Filler element
`.repeat(4000); + document.body.innerHTML = `
${i} left
${filler}`; + await waitForAnimationFrame() + } +} + +// largest-contentful-paint-element: add the largest element later in page load +// layout-shift-elements: shift down the `

` in the page +setTimeout(() => { + const imgEl = document.createElement('img'); + imgEl.src = '../dobetterweb/lighthouse-480x318.jpg'; + const textEl = document.createElement('span'); + textEl.textContent = 'Sorry!'; + const top = document.getElementById('late-content'); + top.appendChild(imgEl); + top.appendChild(textEl); + + // layout-shift-elements: ensure we can handle missing shift elements + if (window.location.href.includes('?missing')) { + stall(100); // force a long task to ensure we reach the rerendering stage + setTimeout(async () => { + await rerender(20); // rerender a large number of nodes to evict the early layout shift node + document.body.textContent = 'Now it is all gone!'; + }, 50); + } +}, 1000); + +// long-tasks: add a very long task at least 500ms +stall(800); diff --git a/node_modules/lighthouse/lighthouse-core/audits/long-tasks.js b/node_modules/lighthouse/lighthouse-core/audits/long-tasks.js new file mode 100644 index 000000000..94fd5ff3e --- /dev/null +++ b/node_modules/lighthouse/lighthouse-core/audits/long-tasks.js @@ -0,0 +1,124 @@ +/** + * @license Copyright 2020 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. + */ +'use strict'; + +const Audit = require('./audit.js'); +const NetworkRecords = require('../computed/network-records.js'); +const i18n = require('../lib/i18n/i18n.js'); +const MainThreadTasks = require('../computed/main-thread-tasks.js'); +const BootupTime = require('./bootup-time.js'); +const PageDependencyGraph = require('../computed/page-dependency-graph.js'); +const LoadSimulator = require('../computed/load-simulator.js'); + +/** We don't always have timing data for short tasks, if we're missing timing data. Treat it as though it were 0ms. */ +const DEFAULT_TIMING = {startTime: 0, endTime: 0, duration: 0}; + +const UIStrings = { + /** Title of a diagnostic LH audit that provides details on the longest running tasks that occur when the page loads. */ + title: 'Avoid long main-thread tasks', + /** Description of a diagnostic LH audit that shows the user the longest running tasks that occur when the page loads. */ + description: 'Lists the longest tasks on the main thread, ' + + 'useful for identifying worst contributors to input delay. ' + + '[Learn more](https://web.dev/long-tasks-devtools/)', + /** [ICU Syntax] Label identifying the number of long-running CPU tasks that occurred while loading a web page. */ + displayValue: `{itemCount, plural, + =1 {# long task found} + other {# long tasks found} + }`, +}; + +const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings); + +class LongTasks extends Audit { + /** + * @return {LH.Audit.Meta} + */ + static get meta() { + return { + id: 'long-tasks', + scoreDisplayMode: Audit.SCORING_MODES.INFORMATIVE, + title: str_(UIStrings.title), + description: str_(UIStrings.description), + requiredArtifacts: ['traces', 'devtoolsLogs'], + }; + } + + /** + * @param {LH.Artifacts} artifacts + * @param {LH.Audit.Context} context + * @return {Promise} + */ + static async audit(artifacts, context) { + const settings = context.settings || {}; + const trace = artifacts.traces[Audit.DEFAULT_PASS]; + const tasks = await MainThreadTasks.request(trace, context); + const devtoolsLog = artifacts.devtoolsLogs[LongTasks.DEFAULT_PASS]; + const networkRecords = await NetworkRecords.request(devtoolsLog, context); + + /** @type {Map} */ + const taskTimingsByEvent = new Map(); + + if (settings.throttlingMethod === 'simulate') { + const simulatorOptions = {trace, devtoolsLog, settings: context.settings}; + const pageGraph = await PageDependencyGraph.request({trace, devtoolsLog}, context); + const simulator = await LoadSimulator.request(simulatorOptions, context); + const simulation = await simulator.simulate(pageGraph, {label: 'long-tasks-diagnostic'}); + for (const [node, timing] of simulation.nodeTimings.entries()) { + if (node.type !== 'cpu') continue; + taskTimingsByEvent.set(node.event, timing); + } + } else { + for (const task of tasks) { + if (task.unbounded || task.parent) continue; + taskTimingsByEvent.set(task.event, task); + } + } + + const jsURLs = BootupTime.getJavaScriptURLs(networkRecords); + // Only consider up to 20 long, top-level (no parent) tasks that have an explicit endTime + const longtasks = tasks + .map(t => { + const timing = taskTimingsByEvent.get(t.event) || DEFAULT_TIMING; + return {...t, duration: timing.duration, startTime: timing.startTime}; + }) + .filter(t => t.duration >= 50 && !t.unbounded && !t.parent) + .sort((a, b) => b.duration - a.duration) + .slice(0, 20); + + // TODO(beytoven): Add start time that matches with the simulated throttling + const results = longtasks.map(task => ({ + url: BootupTime.getAttributableURLForTask(task, jsURLs), + duration: task.duration, + startTime: task.startTime, + })); + + /** @type {LH.Audit.Details.Table['headings']} */ + const headings = [ + /* eslint-disable max-len */ + {key: 'url', itemType: 'url', text: str_(i18n.UIStrings.columnURL)}, + {key: 'startTime', itemType: 'ms', granularity: 1, text: str_(i18n.UIStrings.columnStartTime)}, + {key: 'duration', itemType: 'ms', granularity: 1, text: str_(i18n.UIStrings.columnDuration)}, + /* eslint-enable max-len */ + ]; + + const tableDetails = Audit.makeTableDetails(headings, results); + + let displayValue; + if (results.length > 0) { + displayValue = str_(UIStrings.displayValue, {itemCount: results.length}); + } + + return { + score: results.length === 0 ? 1 : 0, + notApplicable: results.length === 0, + details: tableDetails, + displayValue, + }; + } +} + +module.exports = LongTasks; +module.exports.UIStrings = UIStrings; diff --git a/node_modules/lighthouse/lighthouse-core/audits/seo/crawlable-anchors.js b/node_modules/lighthouse/lighthouse-core/audits/seo/crawlable-anchors.js new file mode 100644 index 000000000..b97af5b83 --- /dev/null +++ b/node_modules/lighthouse/lighthouse-core/audits/seo/crawlable-anchors.js @@ -0,0 +1,100 @@ +/** + * @license Copyright 2020 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. + */ +'use strict'; + +const Audit = require('../audit.js'); +const i18n = require('../../lib/i18n/i18n.js'); + +const UIStrings = { + /** Title of a Lighthouse audit that provides detail on whether links have potentially-crawlable href attributes. This descriptive title is shown when all links on the page are potentially-crawlable. */ + title: 'Links are crawlable', + /** Descriptive title of a Lighthouse audit that provides detail on whether links have potentially-crawlable href attributes. This descriptive title is shown when there are href attributes which are not crawlable by search engines. */ + failureTitle: 'Links are not crawlable', + /** Description of a Lighthouse audit that tells the user why href attributes on links should be crawlable. This is displayed after a user expands the section to see more. 'Learn More' becomes link text to additional documentation. */ + description: 'Search engines may use `href` attributes on links to crawl websites. Ensure that the `href` attribute of anchor elements links to an appropriate destination, so more pages of the site can be discovered. [Learn More](https://support.google.com/webmasters/answer/9112205)', + /** Label for a column in a data table; entries will be the HTML anchor elements that failed the audit. Anchors are DOM elements that are links. */ + columnFailingLink: 'Uncrawlable Link', +}; + +const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings); + +class CrawlableAnchors extends Audit { + /** + * @return {LH.Audit.Meta} + */ + static get meta() { + return { + id: 'crawlable-anchors', + title: str_(UIStrings.title), + failureTitle: str_(UIStrings.failureTitle), + description: str_(UIStrings.description), + requiredArtifacts: ['AnchorElements'], + }; + } + + /** + * @param {LH.Artifacts} artifacts + * @return {LH.Audit.Product} + */ + static audit({AnchorElements: anchorElements}) { + const failingAnchors = anchorElements.filter(({ + rawHref, + listeners = [], + onclick = '', + name = '', + role = '', + }) => { + onclick = onclick.replace( /\s/g, ''); + rawHref = rawHref.replace( /\s/g, ''); + name = name.trim(); + role = role.trim(); + + if (role.length > 0) return; + + const windowLocationRegExp = /window\.location=/; + const windowOpenRegExp = /window\.open\(/; + const javaScriptVoidRegExp = /javascript:void(\(|)0(\)|)/; + + if (rawHref.startsWith('file:')) return true; + if (windowLocationRegExp.test(onclick)) return true; + if (windowOpenRegExp.test(onclick)) return true; + + const hasClickHandler = listeners.some(({type}) => type === 'click'); + if (hasClickHandler || name.length > 0) return; + + if (rawHref === '') return true; + if (javaScriptVoidRegExp.test(rawHref)) return true; + }); + + /** @type {LH.Audit.Details.Table['headings']} */ + const headings = [{ + key: 'node', + itemType: 'node', + text: str_(UIStrings.columnFailingLink), + }]; + + /** @type {LH.Audit.Details.Table['items']} */ + const itemsToDisplay = failingAnchors.map(anchor => { + return { + node: { + type: 'node', + path: anchor.devtoolsNodePath || '', + selector: anchor.selector || '', + nodeLabel: anchor.nodeLabel || '', + snippet: anchor.outerHTML || '', + }, + }; + }); + + return { + score: Number(failingAnchors.length === 0), + details: Audit.makeTableDetails(headings, itemsToDisplay), + }; + } +} + +module.exports = CrawlableAnchors; +module.exports.UIStrings = UIStrings; diff --git a/node_modules/lighthouse/lighthouse-core/gather/gatherers/inspector-issues.js b/node_modules/lighthouse/lighthouse-core/gather/gatherers/inspector-issues.js new file mode 100644 index 000000000..29a54cf5c --- /dev/null +++ b/node_modules/lighthouse/lighthouse-core/gather/gatherers/inspector-issues.js @@ -0,0 +1,70 @@ +/** + * @license Copyright 2020 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. + */ + +/** + * @fileoverview Capture IssueAdded events + */ + +'use strict'; + +const Gatherer = require('./gatherer.js'); + +class InspectorIssues extends Gatherer { + constructor() { + super(); + /** @type {Array} */ + this._issues = []; + this._onIssueAdded = this.onIssueAdded.bind(this); + } + + /** + * @param {LH.Crdp.Audits.IssueAddedEvent} entry + */ + onIssueAdded(entry) { + this._issues.push(entry.issue); + } + + /** + * @param {LH.Gatherer.PassContext} passContext + */ + async beforePass(passContext) { + const driver = passContext.driver; + driver.on('Audits.issueAdded', this._onIssueAdded); + await driver.sendCommand('Audits.enable'); + } + + /** + * @param {LH.Gatherer.PassContext} passContext + * @param {LH.Gatherer.LoadData} loadData + * @return {Promise} + */ + async afterPass(passContext, loadData) { + const driver = passContext.driver; + const networkRecords = loadData.networkRecords; + + driver.off('Audits.issueAdded', this._onIssueAdded); + await driver.sendCommand('Audits.disable'); + const artifact = { + /** @type {Array} */ + mixedContent: [], + }; + + for (const issue of this._issues) { + if (issue.details.mixedContentIssueDetails) { + const issueDetails = issue.details.mixedContentIssueDetails; + const issueReqId = issueDetails.request && issueDetails.request.requestId; + if (issueReqId && + networkRecords.find(req => req.requestId === issueReqId)) { + artifact.mixedContent.push(issue.details.mixedContentIssueDetails); + } + } + } + + return artifact; + } +} + +module.exports = InspectorIssues; diff --git a/node_modules/lighthouse/lighthouse-core/lib/lh-env.js b/node_modules/lighthouse/lighthouse-core/lib/lh-env.js new file mode 100644 index 000000000..a7aa19572 --- /dev/null +++ b/node_modules/lighthouse/lighthouse-core/lib/lh-env.js @@ -0,0 +1,12 @@ +/** + * @license Copyright 2020 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. + */ +'use strict'; + +module.exports = { + // NODE_ENV is set to test by jest and by smokehouse CLI runner + // CI as a catchall for everything we do in Travis/GitHub Actions + isUnderTest: !!process.env.CI || process.env.NODE_ENV === 'test', +}; diff --git a/node_modules/lighthouse/lighthouse-core/lib/median-run.js b/node_modules/lighthouse/lighthouse-core/lib/median-run.js new file mode 100644 index 000000000..9c2b69e6b --- /dev/null +++ b/node_modules/lighthouse/lighthouse-core/lib/median-run.js @@ -0,0 +1,93 @@ +/** + * @license Copyright 2020 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. + */ +'use strict'; + +/** @param {LH.Result} lhr @param {string} auditName */ +const getNumericValue = (lhr, auditName) => + (lhr.audits[auditName] && lhr.audits[auditName].numericValue) || NaN; + +/** + * @param {Array} numbers + * @return {number} + */ +function getMedianValue(numbers) { + const sorted = numbers.slice().sort((a, b) => a - b); + if (sorted.length % 2 === 1) return sorted[(sorted.length - 1) / 2]; + const lowerValue = sorted[sorted.length / 2 - 1]; + const upperValue = sorted[sorted.length / 2]; + return (lowerValue + upperValue) / 2; +} + +/** + * @param {LH.Result} lhr + * @param {number} medianFcp + * @param {number} medianInteractive + */ +function getMedianSortValue(lhr, medianFcp, medianInteractive) { + const distanceFcp = + medianFcp - getNumericValue(lhr, 'first-contentful-paint'); + const distanceInteractive = + medianInteractive - getNumericValue(lhr, 'interactive'); + + return distanceFcp * distanceFcp + distanceInteractive * distanceInteractive; +} + +/** + * We want the run that's closest to the median of the FCP and the median of the TTI. + * We're using the Euclidean distance for that (https://en.wikipedia.org/wiki/Euclidean_distance). + * We use FCP and TTI because they represent the earliest and latest moments in the page lifecycle. + * We avoid the median of single measures like the performance score because they can still exhibit + * outlier behavior at the beginning or end of load. + * + * @param {Array} runs + * @return {LH.Result} + */ +function computeMedianRun(runs) { + const missingFcp = runs.some(run => + Number.isNaN(getNumericValue(run, 'first-contentful-paint')) + ); + const missingTti = runs.some(run => + Number.isNaN(getNumericValue(run, 'interactive')) + ); + + if (!runs.length) throw new Error('No runs provided'); + if (missingFcp) throw new Error(`Some runs were missing an FCP value`); + if (missingTti) throw new Error(`Some runs were missing a TTI value`); + + const medianFcp = getMedianValue( + runs.map(run => getNumericValue(run, 'first-contentful-paint')) + ); + + const medianInteractive = getMedianValue( + runs.map(run => getNumericValue(run, 'interactive')) + ); + + // Sort by proximity to the medians, breaking ties with the minimum TTI. + const sortedByProximityToMedian = runs + .slice() + .sort( + (a, b) => + getMedianSortValue(a, medianFcp, medianInteractive) - + getMedianSortValue(b, medianFcp, medianInteractive) || + getNumericValue(a, 'interactive') - getNumericValue(b, 'interactive') + ); + + return sortedByProximityToMedian[0]; +} + +/** + * @param {Array} runs + * @return {Array} + */ +function filterToValidRuns(runs) { + return runs + .filter(run => + Number.isFinite(getNumericValue(run, 'first-contentful-paint')) + ) + .filter(run => Number.isFinite(getNumericValue(run, 'interactive'))); +} + +module.exports = {computeMedianRun, filterToValidRuns}; diff --git a/node_modules/lighthouse/lighthouse-core/lib/third-party-web.js b/node_modules/lighthouse/lighthouse-core/lib/third-party-web.js new file mode 100644 index 000000000..4b0cf6079 --- /dev/null +++ b/node_modules/lighthouse/lighthouse-core/lib/third-party-web.js @@ -0,0 +1,49 @@ +/** + * @license Copyright 2020 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. + */ +'use strict'; + +const thirdPartyWeb = require('third-party-web/httparchive-nostats-subset'); + +/** @typedef {import("third-party-web").IEntity} ThirdPartyEntity */ + +/** + * `third-party-web` throws when the passed in string doesn't appear to have any domain whatsoever. + * We pass in some not-so-url-like things, so make the dependent-code simpler by making this call safe. + * @param {string} url + * @return {ThirdPartyEntity|undefined} + */ +function getEntity(url) { + try { + return thirdPartyWeb.getEntity(url); + } catch (_) { + return undefined; + } +} + +/** + * @param {string} url + * @param {ThirdPartyEntity | undefined} mainDocumentEntity + */ +function isThirdParty(url, mainDocumentEntity) { + const entity = getEntity(url); + if (!entity) return false; + if (entity === mainDocumentEntity) return false; + return true; +} + +/** + * @param {string} url + * @param {ThirdPartyEntity | undefined} mainDocumentEntity + */ +function isFirstParty(url, mainDocumentEntity) { + return !isThirdParty(url, mainDocumentEntity); +} + +module.exports = { + getEntity, + isThirdParty, + isFirstParty, +};