lighthouse 9.5.0-dev.20221005 → 9.5.0-dev.20221007

package/cli/test/smokehouse/smokehouse.js

@@ -31,7 +31,7 @@
  * @property {Run[]} runs
  */
 
-import assert from 'assert';
+import assert from 'assert/strict';
 
 import log from 'lighthouse-logger';
 

package/core/audits/accessibility/aria-meter-name.js

@@ -17,8 +17,8 @@ const UIStrings = {
   title: 'ARIA `meter` elements have accessible names',
   /** Title of an accessibility audit that evaluates if meter HTML elements do not have accessible names. This title is descriptive of the failing state and is shown to users when there is a failure that needs to be addressed. */
   failureTitle: 'ARIA `meter` elements do not have accessible names.',
-  /** Description of a Lighthouse audit that tells the user *why* they should have accessible names for HTML elements. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
-  description: 'When an element doesn\'t have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to name `meter` elements](https://dequeuniversity.com/rules/axe/4.4/aria-meter-name).',
+  /** Description of a Lighthouse audit that tells the user *why* they should have accessible names for HTML 'meter' elements. This is displayed after a user expands the section to see more. No character length limits. 'Learn how...' becomes link text to additional documentation. */
+  description: 'When a meter element doesn\'t have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to name `meter` elements](https://dequeuniversity.com/rules/axe/4.4/aria-meter-name).',
 };
 
 const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);

package/core/audits/accessibility/aria-tooltip-name.js

@@ -17,8 +17,8 @@ const UIStrings = {
   title: 'ARIA `tooltip` elements have accessible names',
   /** Title of an accessibility audit that evaluates if tooltip HTML elements do not have accessible names. This title is descriptive of the failing state and is shown to users when there is a failure that needs to be addressed. */
   failureTitle: 'ARIA `tooltip` elements do not have accessible names.',
-  /** Description of a Lighthouse audit that tells the user *why* they should have accessible names for HTML elements. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
-  description: 'When an element doesn\'t have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to name `tooltip` elements](https://dequeuniversity.com/rules/axe/4.4/aria-tooltip-name).',
+  /** Description of a Lighthouse audit that tells the user *why* they should have accessible names for HTML 'tooltip' elements. This is displayed after a user expands the section to see more. No character length limits. 'Learn how...' becomes link text to additional documentation. */
+  description: 'When a tooltip element doesn\'t have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to name `tooltip` elements](https://dequeuniversity.com/rules/axe/4.4/aria-tooltip-name).',
 };
 
 const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);

package/core/audits/accessibility/manual/custom-controls-labels.js

@@ -18,7 +18,7 @@ class CustomControlsLabels extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'custom-controls-labels',
-      description: 'Custom interactive controls have associated labels, provided by aria-label or aria-labelledby. [Learn more about custom controls and labels](https://web.dev/custom-controls-labels/).',
+      description: 'Custom interactive controls have associated labels, provided by aria-label or aria-labelledby. [Learn more about custom controls and labels](https://developer.chrome.com/docs/lighthouse/accessibility/custom-controls-labels/).',
       title: 'Custom controls have associated labels',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/custom-controls-roles.js

@@ -18,7 +18,7 @@ class CustomControlsRoles extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'custom-controls-roles',
-      description: 'Custom interactive controls have appropriate ARIA roles. [Learn how to add roles to custom controls](https://web.dev/custom-control-roles/).',
+      description: 'Custom interactive controls have appropriate ARIA roles. [Learn how to add roles to custom controls](https://developer.chrome.com/docs/lighthouse/accessibility/custom-control-roles/).',
       title: 'Custom controls have ARIA roles',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/focus-traps.js

@@ -18,7 +18,7 @@ class FocusTraps extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'focus-traps',
-      description: 'A user can tab into and out of any control or region without accidentally trapping their focus. [Learn how to avoid focus traps](https://web.dev/focus-traps/).',
+      description: 'A user can tab into and out of any control or region without accidentally trapping their focus. [Learn how to avoid focus traps](https://developer.chrome.com/docs/lighthouse/accessibility/focus-traps/).',
       title: 'User focus is not accidentally trapped in a region',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/focusable-controls.js

@@ -18,7 +18,7 @@ class FocusableControls extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'focusable-controls',
-      description: 'Custom interactive controls are keyboard focusable and display a focus indicator. [Learn how to make custom controls focusable](https://web.dev/focusable-controls/).',
+      description: 'Custom interactive controls are keyboard focusable and display a focus indicator. [Learn how to make custom controls focusable](https://developer.chrome.com/docs/lighthouse/accessibility/focusable-controls/).',
       title: 'Interactive controls are keyboard focusable',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/interactive-element-affordance.js

@@ -18,7 +18,7 @@ class InteractiveElementAffordance extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'interactive-element-affordance',
-      description: 'Interactive elements, such as links and buttons, should indicate their state and be distinguishable from non-interactive elements. [Learn how to decorate interactive elements with affordance hints](https://web.dev/interactive-element-affordance/).',
+      description: 'Interactive elements, such as links and buttons, should indicate their state and be distinguishable from non-interactive elements. [Learn how to decorate interactive elements with affordance hints](https://developer.chrome.com/docs/lighthouse/accessibility/interactive-element-affordance/).',
       title: 'Interactive elements indicate their purpose and state',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/logical-tab-order.js

@@ -18,7 +18,7 @@ class LogicalTabOrder extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'logical-tab-order',
-      description: 'Tabbing through the page follows the visual layout. Users cannot focus elements that are offscreen. [Learn more about logical tab ordering](https://web.dev/logical-tab-order/).',
+      description: 'Tabbing through the page follows the visual layout. Users cannot focus elements that are offscreen. [Learn more about logical tab ordering](https://developer.chrome.com/docs/lighthouse/accessibility/logical-tab-order/).',
       title: 'The page has a logical tab order',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/managed-focus.js

@@ -18,7 +18,7 @@ class ManagedFocus extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'managed-focus',
-      description: 'If new content, such as a dialog, is added to the page, the user\'s focus is directed to it. [Learn how to direct focus to new content](https://web.dev/managed-focus/).',
+      description: 'If new content, such as a dialog, is added to the page, the user\'s focus is directed to it. [Learn how to direct focus to new content](https://developer.chrome.com/docs/lighthouse/accessibility/managed-focus/).',
       title: 'The user\'s focus is directed to new content added to the page',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/offscreen-content-hidden.js

@@ -19,7 +19,7 @@ class OffscreenContentHidden extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'offscreen-content-hidden',
-      description: 'Offscreen content is hidden with display: none or aria-hidden=true. [Learn how to properly hide offscreen content](https://web.dev/offscreen-content-hidden/).',
+      description: 'Offscreen content is hidden with display: none or aria-hidden=true. [Learn how to properly hide offscreen content](https://developer.chrome.com/docs/lighthouse/accessibility/offscreen-content-hidden/).',
       title: 'Offscreen content is hidden from assistive technology',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/use-landmarks.js

@@ -18,7 +18,7 @@ class UseLandmarks extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'use-landmarks',
-      description: 'Landmark elements (<main>, <nav>, etc.) are used to improve the keyboard navigation of the page for assistive technology. [Learn more about landmark elements](https://web.dev/use-landmarks/).',
+      description: 'Landmark elements (<main>, <nav>, etc.) are used to improve the keyboard navigation of the page for assistive technology. [Learn more about landmark elements](https://developer.chrome.com/docs/lighthouse/accessibility/use-landmarks/).',
       title: 'HTML5 landmark elements are used to improve navigation',
     }, super.partialMeta);
   }

package/core/audits/accessibility/manual/visual-order-follows-dom.js

@@ -18,7 +18,7 @@ class VisualOrderFollowsDOM extends ManualAudit {
   static get meta() {
     return Object.assign({
       id: 'visual-order-follows-dom',
-      description: 'DOM order matches the visual order, improving navigation for assistive technology. [Learn more about DOM and visual ordering](https://web.dev/visual-order-follows-dom/).',
+      description: 'DOM order matches the visual order, improving navigation for assistive technology. [Learn more about DOM and visual ordering](https://developer.chrome.com/docs/lighthouse/accessibility/visual-order-follows-dom/).',
       title: 'Visual order on the page follows DOM order',
     }, super.partialMeta);
   }

package/core/config/default-config.js

@@ -38,7 +38,7 @@ const UIStrings = {
   /** Title of the Accessibility category of audits. This section contains audits focused on making web content accessible to all users. Also used as a label of a score gauge; try to limit to 20 characters. */
   a11yCategoryTitle: 'Accessibility',
   /** Description of the Accessibility category. This is displayed at the top of a list of audits focused on making web content accessible to all users. No character length limits. 'improve the accessibility of your web app' becomes link text to additional documentation. */
-  a11yCategoryDescription: 'These checks highlight opportunities to [improve the accessibility of your web app](https://web.dev/lighthouse-accessibility/). Only a subset of accessibility issues can be automatically detected so manual testing is also encouraged.',
+  a11yCategoryDescription: 'These checks highlight opportunities to [improve the accessibility of your web app](https://developer.chrome.com/docs/lighthouse/accessibility/). Only a subset of accessibility issues can be automatically detected so manual testing is also encouraged.',
   /** Description of the Accessibility manual checks category. This description is displayed above a list of accessibility audits that currently have no automated test and so must be verified manually by the user. No character length limits. 'conducting an accessibility review' becomes link text to additional documentation. */
   a11yCategoryManualDescription: 'These items address areas which an automated testing tool cannot cover. Learn more in our guide on [conducting an accessibility review](https://web.dev/how-to-review/).',
   /** Title of the best practices section of the Accessibility category. Within this section are audits with descriptive titles that highlight common accessibility best practices. */

package/core/lib/i18n/README.md

@@ -12,11 +12,11 @@ The collection and translation pipeline:
 ```
  Source files:                                         Locale files:
 +---------------------------+                         +----------------------------------------------
-|                           ++                        | shared/localization/locales/en-US.json |
-| const UIStrings = { ... };|-+                 +---> | shared/localization/locales/en-XL.json |
+|                           ++                        | shared/localization/locales/en-US.json      |
+| const UIStrings = { ... };|-+                 +---> | shared/localization/locales/en-XL.json      |
 |                           |-|                 |     +----------------------------------------------+
 +-----------------------------|                 |     |                                             ||
- +----------------------------|                 |     | shared/localization/locales/*.json     |-<+
+ +----------------------------|                 |     | shared/localization/locales/*.json          |-<+
   +---------------------------+                 |     |                                             || |
                            |                    |     +----------------------------------------------| |
   $ yarn                   |                    |      +---------------------------------------------+ |
@@ -198,11 +198,11 @@ CTC is a name that is distinct and identifies this as the Chrome translation for
 ```json
 {
   "name": {
-    "message": "Message text, with optional placeholders.",
+    "message": "Message text, with optional placeholders, which can be $PLACEHOLDER_TEXT$",
     "description": "Translator-aimed description of the message.",
     "meaning": "Description given when a message is duplicated, in order to give context to the message. Lighthouse uses a copy of the description for this.",
     "placeholders": {
-      "placeholder_name": {
+      "PLACEHOLDER_TEXT": {
         "content": "A string to be placed within the message.",
         "example": "Translator-aimed example of the placeholder string."
       },
@@ -211,6 +211,23 @@ CTC is a name that is distinct and identifies this as the Chrome translation for
 }
 ```
 
+### Collisions
+Collisions happen when two CTC messages have the same `message`. For Lighthouse, there are two relevant collision types in TC:
+  - Allowed: the CTC `message`, `description`, and `placeholders` are exactly the same. These collisions are deduped on the TC side and the translation cost is the same as for a single string.
+  - Disallowed: `message` is the same but one or more of the other properties differ.
+
+When the `message` needs to be the same as another string but another property must differ, that disallowed collision can be fixed by adding a unique `meaning` property to each colliding CTC message. TC will then consider those as separate strings and not a collision.
+
+In Lighthouse, this is done by having a different `description` for the strings, which is then copied to `meaning` in `resolveMessageCollisions()`. `meaning` cannot be manually set.
+
+For instance, the string "Potential Savings" currently refers to both saved KiB and saved milliseconds in different audits. The string is defined twice, each with a different `description` describing the units being saved, in case some locales' translations will use a different word choice depending on the unit.
+
+Internally, TC uses a message ID that's a hash of `message` and `meaning` to check for collisions. Somewhat confusingly, if two messages do have colliding IDs, then `message`, `meaning`, `description`, and `placeholders` are all required to match or an error is thrown. This is why all message properties could cause a collision but `meaning` is the only way to dedupe them.
+
+We treat it as an error if `placeholders` differ between messages in a collision: if there is a need for placeholders to differ, then the strings aren't really the same, and at least the `description` should be changed to explain that context. Placeholders must match in user-controlled data (e.g. if a placeholder has an `@example`, it must be the same example in all instances) and in Lighthouse-controlled data (e.g. the token used to replace it in the CTC `message`, like `$PLACEHOLDER_TEXT$` in the example above).
+
+Finally, identical messages made to not collide by Lighthouse with a `meaning` cost real money and shouldn't be confused with allowed collisions which cost nothing for each additional collision. Fixed collisions are checked against a known list to add a little friction and motivate keeping them few in number. An error is thrown if a collision is fixed that hasn't yet been added to that list.
+
 # Appendix
 
 ##  Appendix A: How runtime string replacement works

package/dist/report/bundle.esm.js

@@ -1661,7 +1661,7 @@ class DOM {
       // Otherwise, append any links found.
       const url = new URL(segment.linkHref);
 
-      const DOCS_ORIGINS = ['https://developers.google.com', 'https://web.dev'];
+      const DOCS_ORIGINS = ['https://developers.google.com', 'https://web.dev', 'https://developer.chrome.com'];
       if (DOCS_ORIGINS.includes(url.origin)) {
         url.searchParams.set('utm_source', 'lighthouse');
         url.searchParams.set('utm_medium', this._lighthouseChannel);