feat(schema)!: align typedefs/linters with schema (#27428)

BREAKING CHANGE: Previously, TypeScript definitions for version fields were inconsistent with the schema. Now, definitions are aligned with the schema:

* `VersionValue` is now `string | false` (previously `string | boolean | null`).
* `version_added` is still `VersionValue` (without `true` or `null`).
* `version_removed`  and `version_last` are now `string` (previously `VersionValue`).

Impact: Consumers may need to update their code handling these fields.

Author: queengooborg

docs/testing.md

@@ -24,18 +24,21 @@ For more information on the schema for browser data, see [`browsers-schema.md`](
 
 ## Generate statistics
 
-To see how changes will affect the statistics of real (either `false` or a version number, as defined in [issue 3555](https://github.com/mdn/browser-compat-data/issues/3555)), true, and null values, you can run `npm run stats [folder]`. This generates a Markdown-formatted table of the percentages of real, true, and null values for the eight primary browsers that browser-compat-data is focusing on. The script also takes an optional argument regarding a specific folder (such as `api` or `javascript`), which will print statistics result for only that folder. Additionally, you can run the script with `--all` to get statistics for all browsers tracked in BCD, not just the primary eight.
+To see how changes will affect the statistics of exact (formerly "real") and ranged values, you can run `npm run stats [folder]`. This generates a Markdown-formatted table of the percentages of exact and ranged values for the eight primary browsers that browser-compat-data is focusing on. The script also takes an optional argument regarding a specific folder (such as `api` or `javascript`), which will print statistics result for only that folder. Additionally, you can run the script with `--all` to get statistics for all browsers tracked in BCD, not just the primary eight.
+
+> [!NOTE]
+> Originally, this script was designed to track "real" (either `false` or a version number, as defined in [issue 3555](https://github.com/mdn/browser-compat-data/issues/3555)), ranged, true, and null values in order to track the progress of a project to eliminate "non-real" (true and null) values. Since the project was completed, the script was simplified to display just exact and ranged values.
 
 ## Traverse features
 
-To find all the entries that are non-real, or of a specified value, you can run `npm run traverse -- [options] [folder]`.
+To find all the entries that are of a specified value, you can run `npm run traverse -- [options] [folder]`.
 
-By default, the script will traverse and print the dotted path to every feature. One or more positional arguments can limit the traversal to a specific folder (for example, `api`). Additional options can limit the features listed to features with data matching specific browser and version values (for example, `--non-real`).
+By default, the script will traverse and print the dotted path to every feature. One or more positional arguments can limit the traversal to a specific folder (for example, `api`). Additional options can limit the features listed to features with data matching specific browser and version values.
 
 Run `npm run traverse -- --help` for a complete list of options and examples.
 
 The `-b` or `--browser` argument may be any browser in the [`browsers/` folder](https://github.com/mdn/browser-compat-data/blob/main/browsers/). This argument may be repeated to traverse multiple browsers. By default, the script will traverse all browsers.
 
-The `-f` or `--filter` argument may be any value accepted by `version_added` or `version_removed`. This argument may be repeated to test multiple values. By default, the script will traverse all features regardless of their value. The `-n` or `--non-real` argument may be included as a convenience alias for `-f null -f true`.
+The `-f` or `--filter` argument may be any value accepted by `version_added` or `version_removed`. This argument may be repeated to test multiple values. By default, the script will traverse all features regardless of their value.
 
-Examples: to search for all Safari entries that are non-real, run `npm run traverse -- -b safari --non-real`. To search for all WebView entries that are marked as `true` in `api` and `javascript`, run `npm run traverse api,javascript -- -b webview_android -f true`. To search for all Firefox entries supported since `10` across all folders, run `npm run traverse -- -b firefox -f 10`.
+Examples: to search for all Safari entries that are not supported, run `npm run traverse -- -b safari -f false`. To search for all WebView entries that are mirroring from upstream in `api` and `javascript`, run `npm run traverse api,javascript -- -b webview_android -f mirror`. To search for all Firefox entries supported since `10` across all folders, run `npm run traverse -- -b firefox -f 10`.

lint/common/overlap.ts

@@ -87,6 +87,7 @@ export const checkOverlap = (
       if (fix) {
         if (
           typeof current.version_removed === 'undefined' &&
+          next.version_added !== false &&
           next.version_added !== 'preview'
         ) {
           current.version_removed = next.version_added;

lint/linter/test-consistency.test.ts

@@ -8,21 +8,14 @@ import { ConsistencyChecker } from './test-consistency.js';
 const check = new ConsistencyChecker();
 
 describe('ConsistencyChecker.getVersionAdded()', () => {
-  it('returns null for non-real values', () => {
-    assert.equal(
-      check.getVersionAdded({ chrome: { version_added: null } }, 'chrome'),
-      null,
-    );
-  });
-
-  it('returns null for "preview" values', () => {
+  it('returns false for "preview" values', () => {
     assert.equal(
       check.getVersionAdded({ chrome: { version_added: 'preview' } }, 'chrome'),
-      null,
+      false,
     );
   });
 
-  it('returns the value for real and ranged values', () => {
+  it('returns the value for exact and ranged values', () => {
     assert.equal(
       check.getVersionAdded({ chrome: { version_added: '12' } }, 'chrome'),
       '12',
@@ -33,7 +26,7 @@ describe('ConsistencyChecker.getVersionAdded()', () => {
     );
   });
 
-  it('returns the earliest real value for an array support statement', () => {
+  it('returns the earliest value for an array support statement', () => {
     assert.equal(
       check.getVersionAdded(
         { chrome: [{ version_added: '≤11' }, { version_added: '101' }] },
@@ -51,19 +44,19 @@ describe('ConsistencyChecker.getVersionAdded()', () => {
         },
         'chrome',
       ),
-      null,
+      false,
     );
     assert.equal(
       check.getVersionAdded(
         {
           chrome: [
-            { version_added: true },
+            { version_added: '20' },
             { version_added: '≤11', flags: [] },
           ],
         },
         'chrome',
       ),
-      null,
+      '20',
     );
     assert.equal(
       check.getVersionAdded(

lint/linter/test-consistency.ts

@@ -22,10 +22,7 @@ import { query } from '../../utils/index.js';
 import mirrorSupport from '../../scripts/build/mirror.js';
 import bcd from '../../index.js';
 
-type ErrorType =
-  | 'unsupported'
-  | 'support_unknown'
-  | 'subfeature_earlier_implementation';
+type ErrorType = 'unsupported' | 'subfeature_earlier_implementation';
 
 interface ConsistencyError {
   path: string[];
@@ -181,53 +178,6 @@ export class ConsistencyChecker {
       }
     });
 
-    // Test whether sub-features are supported when basic support is not implemented
-    // For all unsupported browsers (basic support == false), sub-features should be set to false
-    const supportUnknownInParent = this.extractSupportUnknownBrowsers(
-      data.__compat,
-    );
-    inconsistentSubfeaturesByBrowser = {};
-
-    for (const subfeature of subfeatures) {
-      const supportUnknownInChild = this.extractSupportNotTrueBrowsers(
-        query(subfeature, data).__compat,
-      );
-
-      const browsers = supportUnknownInParent.filter(
-        (x) => !supportUnknownInChild.includes(x),
-      ) as BrowserName[];
-
-      for (const browser of browsers) {
-        inconsistentSubfeaturesByBrowser[browser] =
-          inconsistentSubfeaturesByBrowser[browser] || [];
-        const subfeature_value = this.getVersionAdded(
-          query(subfeature, data).__compat.support,
-          browser,
-        );
-        inconsistentSubfeaturesByBrowser[browser]?.push([
-          subfeature,
-          subfeature_value,
-        ]);
-      }
-    }
-
-    // Add errors
-    Object.keys(inconsistentSubfeaturesByBrowser).forEach((browser) => {
-      const subfeatures =
-        inconsistentSubfeaturesByBrowser[browser as BrowserName];
-      if (subfeatures) {
-        errors.push({
-          type: 'support_unknown',
-          browser: browser as BrowserName,
-          parentValue: this.getVersionAdded(
-            data?.__compat?.support,
-            browser as BrowserName,
-          ),
-          subfeatures,
-        });
-      }
-    });
-
     // Test whether sub-features are supported at an earlier version than basic support
     const supportInParent = this.extractSupportedBrowsersWithVersion(
       data.__compat,
@@ -297,38 +247,10 @@ export class ConsistencyChecker {
       compatData,
       (data) =>
         data.version_added === false ||
-        (typeof data.version_removed !== 'undefined' &&
-          data.version_removed !== false),
-    );
-  }
-
-  /**
-   * Get all of the browsers with unknown support in a feature
-   * @param compatData The compat data to process
-   * @returns The list of browsers with unknown support
-   */
-  extractSupportUnknownBrowsers(compatData?: CompatStatement): BrowserName[] {
-    return this.extractBrowsers(
-      compatData,
-      (data) => data.version_added === null,
+        typeof data.version_removed !== 'undefined',
     );
   }
 
-  /**
-   * Get all of the browsers with either unknown or no support in a feature
-   * @param compatData The compat data to process
-   * @returns The list of browsers with non-truthy (false or null) support
-   */
-  extractSupportNotTrueBrowsers(compatData?: CompatStatement): BrowserName[] {
-    return this.extractBrowsers(
-      compatData,
-      (data) =>
-        data.version_added === false ||
-        data.version_added === null ||
-        (typeof data.version_removed !== 'undefined' &&
-          data.version_removed !== false),
-    );
-  }
   /**
    * Get all of the browsers with a version number in a feature.
    * @param compatData The compat data to process
@@ -354,12 +276,12 @@ export class ConsistencyChecker {
     browser: BrowserName,
   ): VersionValue {
     if (!supportBlock) {
-      return null;
+      return false;
     }
 
     const supportStatement = supportBlock[browser];
     if (!supportStatement) {
-      return null;
+      return false;
     }
 
     if (supportStatement === 'mirror') {
@@ -370,16 +292,15 @@ export class ConsistencyChecker {
     }
 
     /**
-     * A convenience function to squash non-real values and previews into null
+     * A convenience function to squash preview and flag support into `false`
      * @param statement The statement to use
-     * @returns The version number or 'null'
+     * @returns The version number or `false`
      */
     const resolveVersionAddedValue = (
       statement: SimpleSupportStatement,
     ): VersionValue =>
-      [true, false, 'preview', null].includes(statement?.version_added) ||
-      statement.flags
-        ? null
+      statement?.version_added == 'preview' || statement.flags
+        ? false
         : statement?.version_added;
 
     // Handle simple support statements
@@ -388,35 +309,27 @@ export class ConsistencyChecker {
     }
 
     // Handle array support statements
-    let selectedValue: string | boolean | null = null;
+    let selectedValue: string | false = false;
     for (const statement of supportStatement) {
       const resolvedValue = resolveVersionAddedValue(statement);
 
-      if (resolvedValue === null) {
+      if (resolvedValue === false) {
         // We're not going to get a more specific version, so bail out now
         continue;
       }
 
-      if (selectedValue !== null) {
-        if (
-          typeof resolvedValue === 'string' &&
-          typeof selectedValue === 'string'
-        ) {
-          // Earlier value takes precedence
-          const resolvedIsEarlier = compare(
-            resolvedValue.replace('≤', ''),
-            selectedValue.replace('≤', ''),
-            '<',
-          );
-          if (resolvedIsEarlier) {
-            selectedValue = resolvedValue;
-          }
-        } else if (typeof resolvedValue === 'string') {
-          // If selectedValue is bool/null but resolvedValue is string
+      if (
+        typeof resolvedValue === 'string' &&
+        typeof selectedValue === 'string'
+      ) {
+        // Earlier value takes precedence
+        const resolvedIsEarlier = compare(
+          resolvedValue.replace('≤', ''),
+          selectedValue.replace('≤', ''),
+          '<',
+        );
+        if (resolvedIsEarlier) {
           selectedValue = resolvedValue;
-        } else {
-          // If neither are version numbers, assign to the truthiest value
-          selectedValue = selectedValue || resolvedValue;
         }
       } else {
         selectedValue = resolvedValue;
@@ -519,8 +432,6 @@ export default {
         let errorMessage = '';
         if (type == 'unsupported') {
           errorMessage += chalk`No support in {bold ${browser}}, but support is declared in the following sub-feature(s):`;
-        } else if (type == 'support_unknown') {
-          errorMessage += chalk`Unknown support in parent for {bold ${browser}}, but support is declared in the following sub-feature(s):`;
         } else if (type == 'subfeature_earlier_implementation') {
           errorMessage += chalk`Basic support in {bold ${browser}} was declared implemented in a later version ({bold ${parentValue}}) than the following sub-feature(s):`;
         }

schemas/compat-data.schema.json

@@ -22,13 +22,13 @@
           "description": "A string, indicating which browser version removed this feature.",
           "type": "string",
           "pattern": "^(≤?(\\d+)(\\.\\d+)*|preview)$",
-          "tsType": "VersionValue"
+          "tsType": "string"
         },
         "version_last": {
           "description": "A string, indicating the last browser version that supported this feature. This is automatically generated.",
           "type": "string",
           "pattern": "^(≤?(\\d+)(\\.\\d+)*|preview)$",
-          "tsType": "VersionValue"
+          "tsType": "string"
         },
         "prefix": {
           "type": "string",

scripts/build/mirror.ts

@@ -236,13 +236,15 @@ export const bumpSupport = (
     sourceData.version_removed &&
     typeof sourceData.version_removed === 'string'
   ) {
-    newData.version_removed = getMatchingBrowserVersion(
+    const versionRemoved = getMatchingBrowserVersion(
       destination,
       sourceData.version_removed,
     );
 
-    // Ensure that version_removed is not present if it's not applicable, such as when the upstream browser removed the feature in a newer release than a matching downstream browser
-    if (newData.version_removed === false) {
+    if (typeof versionRemoved === 'string') {
+      newData.version_removed = versionRemoved;
+    } else {
+      // Ensure that version_removed is not present if it's not applicable, such as when the upstream browser removed the feature in a newer release than a matching downstream browser
       delete newData.version_removed;
     }
   }

scripts/generate-types.ts

@@ -165,7 +165,7 @@ const compile = async (
   const ts = [
     header,
     await generateBrowserNames(),
-    'export type VersionValue = string | boolean | null;',
+    'export type VersionValue = string | false;',
     transformTS(browserTS, compatTS),
     generateCompatDataTypes(),
   ].join('\n\n');

scripts/statistics.test.ts

@@ -43,24 +43,24 @@ describe('getStats', () => {
   it('should return stats for all browsers when allBrowsers is true', () => {
     const stats = getStats('api', true, bcd);
     assert.deepEqual(stats, {
-      total: { all: 3, range: 1, real: 2 },
-      chrome: { all: 1, range: 0, real: 1 },
-      firefox: { all: 1, range: 1, real: 0 },
-      safari: { all: 1, range: 0, real: 1 },
+      total: { all: 3, range: 1, exact: 2 },
+      chrome: { all: 1, range: 0, exact: 1 },
+      firefox: { all: 1, range: 1, exact: 0 },
+      safari: { all: 1, range: 0, exact: 1 },
     });
   });
 
   it('should return stats for webextensions browsers when folder is "webextensions"', () => {
     const stats = getStats('webextensions', false, bcd);
     assert.deepEqual(stats, {
-      total: { all: 7, range: 1, real: 6 },
-      chrome: { all: 1, range: 1, real: 0 },
-      edge: { all: 1, range: 0, real: 1 },
-      firefox: { all: 1, range: 0, real: 1 },
-      opera: { all: 1, range: 0, real: 1 },
-      safari: { all: 1, range: 0, real: 1 },
-      firefox_android: { all: 1, range: 0, real: 1 },
-      safari_ios: { all: 1, range: 0, real: 1 },
+      total: { all: 7, range: 1, exact: 6 },
+      chrome: { all: 1, range: 1, exact: 0 },
+      edge: { all: 1, range: 0, exact: 1 },
+      firefox: { all: 1, range: 0, exact: 1 },
+      opera: { all: 1, range: 0, exact: 1 },
+      safari: { all: 1, range: 0, exact: 1 },
+      firefox_android: { all: 1, range: 0, exact: 1 },
+      safari_ios: { all: 1, range: 0, exact: 1 },
     });
   });