fixup! refactor: migrate from TypeScript to JavaScript

Author: caugner

lint/common/overlap.js

@@ -1,16 +1,23 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
+/**
+ * @import { BrowserName, SupportStatement, SimpleSupportStatement } from '../../types/types.js'
+ * @import { Logger } from '../utils.js'
+ */
+
 import chalk from 'chalk-template';
 import { compareVersions } from 'compare-versions';
 
 import { createStatementGroupKey } from '../utils.js';
 import compareStatements from '../../scripts/lib/compare-statements.js';
 /**
  * Groups statements by group key.
- * @param data The support statements to group.
- * @returns the statement groups
+ * @param {SimpleSupportStatement[]} data The support statements to group.
+ * @returns {Map<string, SimpleSupportStatement[]>} the statement groups
  */
 const groupByStatementKey = (data) => {
+  /** @type {Map<string, SimpleSupportStatement[]>} */
   const groups = new Map();
   for (const support of data) {
     const key = createStatementGroupKey(support);
@@ -25,10 +32,11 @@ const groupByStatementKey = (data) => {
 };
 /**
  * Formats a support statement as a simplified JSON-like version range.
- * @param support The statement to format
- * @returns The formatted range
+ * @param {SimpleSupportStatement} support The statement to format
+ * @returns {string} The formatted range
  */
 const formatRange = (support) => {
+  /** @type {string[]} */
   const result = [];
   if (support.version_added) {
     result.push(`added: ${support.version_added}`);
@@ -40,12 +48,12 @@ const formatRange = (support) => {
 };
 /**
  * Process data and check to make sure there aren't support statements whose version ranges overlap.
- * @param data The data to test
- * @param browser The name of the browser
+ * @param {SupportStatement} data The data to test
+ * @param {BrowserName} browser The name of the browser
  * @param {object} options The check options
- * @param [options.logger] The logger to output errors to
- * @param [options.fix] Whether the statements should be fixed (if possible)
- * @returns the data (with fixes, if specified)
+ * @param {Logger} [options.logger] The logger to output errors to
+ * @param {boolean} [options.fix] Whether the statements should be fixed (if possible)
+ * @returns {SupportStatement} the data (with fixes, if specified)
  */
 export const checkOverlap = (data, browser, { logger, fix = false }) => {
   if (!Array.isArray(data)) {
@@ -57,8 +65,8 @@ export const checkOverlap = (data, browser, { logger, fix = false }) => {
   for (const [groupKey, groupData] of groups.entries()) {
     const statements = groupData.slice().sort(compareStatements).reverse();
     for (let i = 0; i < statements.length - 1; i++) {
-      const current = statements.at(i);
-      const next = statements.at(i + 1);
+      const current = /** @type {SimpleSupportStatement} */ (statements.at(i));
+      const next = /** @type {SimpleSupportStatement} */ (statements.at(i + 1));
       if (!statementsOverlap(current, next)) {
         continue;
       }
@@ -85,9 +93,9 @@ export const checkOverlap = (data, browser, { logger, fix = false }) => {
 };
 /**
  * Checks if the support statements overlap in terms of their version ranges.
- * @param current the current statement.
- * @param next the chronologically following statement.
- * @returns Whether the support statements overlap.
+ * @param {SimpleSupportStatement} current the current statement.
+ * @param {SimpleSupportStatement} next the chronologically following statement.
+ * @returns {boolean} Whether the support statements overlap.
  */
 const statementsOverlap = (current, next) => {
   if (typeof current.version_removed === 'string') {

lint/fixer/browser-order.js

@@ -1,33 +1,47 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
+/**
+ * @import { BrowserName, CompatStatement, SupportBlock } from '../../types/types.js'
+ */
+
 /**
  * Return a new "support_block" object whose first-level properties
  * (browser names) have been ordered according to Array.prototype.sort,
  * and so will be stringified in that order as well. This relies on
  * guaranteed "own" property ordering, which is insertion order for
  * non-integer keys (which is our case).
- * @param key The key of the object
- * @param value The value of the key
- * @returns Value with sorting applied
+ * @param {string} key The key of the object
+ * @param {CompatStatement} value The value of the key
+ * @returns {CompatStatement} Value with sorting applied
  */
 export const orderSupportBlock = (key, value) => {
   if (key === '__compat') {
-    value.support = Object.keys(value.support)
+    value.support = /** @type {BrowserName[]} */ (Object.keys(value.support))
       .sort()
-      .reduce((result, key) => {
-        result[key] = value.support[key];
-        return result;
-      }, {});
+      .reduce(
+        /**
+         * Accumulate browser support in sorted order
+         * @param {SupportBlock} result - Accumulator object
+         * @param {BrowserName} key - Browser name
+         * @returns {SupportBlock} Updated accumulator
+         */
+        (result, key) => {
+          result[key] = value.support[key];
+          return result;
+        },
+        /** @type {SupportBlock} */ ({}),
+      );
   }
   return value;
 };
 /**
  * Perform a fix of the browser order of a __compat.support block within
  * all the data in a specified file.  The function will then automatically
  * write any needed changes back into the file.
- * @param filename The path to the file to fix in-place
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The path to the file to fix in-place
+ * @param {string} actual The current content of the file
+ * @returns {string} expected content of the file
  */
 const fixBrowserOrder = (filename, actual) => {
   if (filename.includes('/browsers/')) {

lint/fixer/common-errors.js

@@ -1,38 +1,48 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
+/**
+ * @import { CompatStatement, SimpleSupportStatement } from '../../types/types.js'
+ */
+
 import { walk } from '../../utils/index.js';
+
 /**
  * Fixes common errors in CompatStatements.
  *
  * - Replaces `browser: { version_added: "mirror" }` with `browser: "mirror"`
  * - Wraps `browser: false` with `browser: `{ version_added: false }`
- * @param compat The compat statement to fix
+ * @param {CompatStatement} compat The compat statement to fix
+ * @returns {void}
  */
 export const fixCommonErrorsInCompatStatement = (compat) => {
   for (const browser of Object.keys(compat.support)) {
-    if (compat.support[browser] === false) {
-      compat.support[browser] = {
+    const browserName =
+      /** @type {import('../../types/types.js').BrowserName} */ (browser);
+    const supportStatement = /** @type {any} */ (compat.support[browserName]);
+    if (supportStatement === false) {
+      compat.support[browserName] = {
         version_added: false,
       };
     } else if (
-      typeof compat.support[browser] === 'object' &&
-      JSON.stringify(compat.support[browser]) === '{"version_added":"mirror"}'
+      typeof supportStatement === 'object' &&
+      JSON.stringify(supportStatement) === '{"version_added":"mirror"}'
     ) {
-      compat.support[browser] = 'mirror';
+      /** @type {any} */ (compat.support)[browserName] = 'mirror';
     }
     if (
       browser == 'ie' &&
-      JSON.stringify(compat.support[browser]) === '{"version_added":false}'
+      JSON.stringify(supportStatement) === '{"version_added":false}'
     ) {
       Reflect.deleteProperty(compat.support, browser);
     }
   }
 };
 /**
  * Update compat data to 'mirror' if the statement matches mirroring
- * @param filename The name of the file to fix
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The name of the file to fix
+ * @param {string} actual The current content of the file
+ * @returns {string} expected content of the file
  */
 const fixCommonErrors = (filename, actual) => {
   if (filename.includes('/browsers/')) {

lint/fixer/descriptions.js

@@ -1,12 +1,14 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
 import testDescriptions, { processData } from '../linter/test-descriptions.js';
 import walk from '../../utils/walk.js';
+
 /**
  * Fixes issues with descriptions
- * @param filename The filename containing compatibility info
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The filename containing compatibility info
+ * @param {string} actual The current content of the file
+ * @returns {string} expected content of the file
  */
 const fixDescriptions = (filename, actual) => {
   if (filename.includes('/browsers/')) {

lint/fixer/feature-order.js

@@ -1,33 +1,48 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
+/**
+ * @import { Identifier } from '../../types/types.js'
+ */
+
 import compareFeatures from '../../scripts/lib/compare-features.js';
+
 /**
  * Return a new feature object whose first-level properties have been
  * ordered according to Array.prototype.sort, and so will be
  * stringified in that order as well. This relies on guaranteed "own"
  * property ordering, which is insertion order for non-integer keys
  * (which is our case).
- * @param _ The key in the object
- * @param value The value of the key
- * @returns The new value
+ * @param {string} _ The key in the object
+ * @param {Identifier} value The value of the key
+ * @returns {Identifier} The new value
  */
 export const orderFeatures = (_, value) => {
   if (value instanceof Object && '__compat' in value) {
     value = Object.keys(value)
       .sort(compareFeatures)
-      .reduce((result, key) => {
-        result[key] = value[key];
-        return result;
-      }, {});
+      .reduce(
+        /**
+         * Accumulate features in sorted order
+         * @param {Identifier} result - Accumulator object
+         * @param {string} key - Feature key
+         * @returns {Identifier} Updated accumulator
+         */
+        (result, key) => {
+          result[key] = value[key];
+          return result;
+        },
+        /** @type {Identifier} */ ({}),
+      );
   }
   return value;
 };
 /**
  * Perform a fix of feature order within all the data in a specified file.
  * The function will then automatically write any needed changes back into the file.
- * @param filename The filename to perform fix upon
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The filename to perform fix upon
+ * @param {string} actual The current content of the file
+ * @returns {string} expected content of the file
  */
 const fixFeatureOrder = (filename, actual) => {
   if (filename.includes('/browsers/')) {

lint/fixer/flags.js

@@ -1,14 +1,20 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
+/**
+ * @import { BrowserName, SupportStatement, SimpleSupportStatement } from '../../types/types.js'
+ */
+
 import testFlags, {
   isIrrelevantFlagData,
   getBasicSupportStatement,
 } from '../linter/test-flags.js';
 import walk from '../../utils/walk.js';
+
 /**
  * Removes irrelevant flags from the compatibility data
- * @param supportData The compatibility statement to test
- * @returns The compatibility statement with all of the flags removed
+ * @param {SupportStatement} supportData The compatibility statement to test
+ * @returns {SupportStatement} The compatibility statement with all of the flags removed
  */
 export const removeIrrelevantFlags = (supportData) => {
   if (typeof supportData === 'string') {
@@ -20,6 +26,7 @@ export const removeIrrelevantFlags = (supportData) => {
     }
     return supportData;
   }
+  /** @type {SimpleSupportStatement[]} */
   const result = [];
   const basicSupport = getBasicSupportStatement(supportData);
   for (const statement of supportData) {
@@ -33,13 +40,15 @@ export const removeIrrelevantFlags = (supportData) => {
   if (result.length == 1) {
     return result[0];
   }
-  return result;
+  return /** @type {[SimpleSupportStatement, SimpleSupportStatement, ...SimpleSupportStatement[]]} */ (
+    result
+  );
 };
 /**
  * Removes irrelevant flags from the compatibility data of a specified file
- * @param filename The filename containing compatibility info
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The filename containing compatibility info
+ * @param {string} actual The current content of the file
+ * @returns {string} expected content of the file
  */
 const fixFlags = (filename, actual) => {
   if (filename.includes('/browsers/')) {
@@ -51,8 +60,11 @@ const fixFlags = (filename, actual) => {
     if (testFlags.exceptions?.includes(feature.path)) {
       continue;
     }
-    for (const [browser, supportData] of Object.entries(
-      feature.compat.support,
+    for (const [
+      browser,
+      supportData,
+    ] of /** @type {[BrowserName, SupportStatement][]} */ (
+      Object.entries(feature.compat.support)
     )) {
       feature.data.__compat.support[browser] =
         removeIrrelevantFlags(supportData);

lint/fixer/links.js

@@ -1,12 +1,14 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
 import { IS_WINDOWS } from '../utils.js';
 import { processData } from '../linter/test-links.js';
+
 /**
  * Fix issues with links throughout the BCD files
- * @param filename The name of the file to fix
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The name of the file to fix
+ * @param {string} actual The current content of the file
+ * @returns {Promise<string>} expected content of the file
  */
 const fixLinks = async (filename, actual) => {
   if (filename.includes('/browsers/')) {

lint/fixer/mdn-urls.js

@@ -1,12 +1,14 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
+
 import testMDNURLs, { processData } from '../linter/test-mdn-urls.js';
 import walk from '../../utils/walk.js';
+
 /**
  * Fixes issues with MDN URLs
- * @param filename The filename containing compatibility info
- * @param actual The current content of the file
- * @returns expected content of the file
+ * @param {string} filename The filename containing compatibility info
+ * @param {string} actual The current content of the file
+ * @returns {Promise<string>} expected content of the file
  */
 const fixMDNURLs = async (filename, actual) => {
   if (filename.includes('/browsers/')) {