refactor: migrate from TypeScript to JavaScript (#28651)

* refactor: migrate from TypeScript to JavaScript

* fix(diff-features): enumerate features with tsx if necessary

* fixup! Merge branch 'main' into un-typescript

* chore(eslint): forbid `@typedef`

* refactor: migrate `@typedef` imports to `@import`

* chore(eslint): enable jsdoc/prefer-import-tag

* refactor: replace `import()` in JSDoc with `@import`

* chore(eslint): refine build ignore

It was also ignoring `scripts/build`.

* chore: run `eslint --fix`

* fixup! refactor: migrate `@typedef` imports to `@import`

* fix(scripts/build): add missing async option

Helps TypeScript to infer the right return type.

* chore(tsconfig): remove unnecessary `include`

* chore(tsconfig): remove `skipLibCheck`

* fix(types): import from `build/types.d.ts`

* fix: resolve newly surfaced type errors

* chore(eslint): remove typescript config/plugins

* chore(deps-dev): remove unused dependencies

* fix(eslint): use latest ecmaVersion

As recommended, see: https://eslint.org/docs/latest/use/configure/language-options#specifying-javascript-options

* chore(tsconfig): include tests in type checking

* chore(lint): remove duplicate type imports

* chore(lint): avoid invalid test value

* chore(lint): fix some types

* fixup! chore(lint): avoid invalid test value

* fixup! chore(lint): fix some types

* chore(utils): add missing test for __compat

* chore(eslint): ignore `import/no-unresolved` errors for `yargs/helpers`

* chore(lint): remove unnessary type annotation

* chore(lint): refine type

* fix(yargs): avoid callback + use parseSync() for proper typing

* chore(scripts/diff-features): specify tsx version

Same as in `package.json` in main.

* fixup! fix(yargs): avoid callback + use parseSync() for proper typing

* fixup! fix(yargs): avoid callback + use parseSync() for proper typing

* chore: use arrow function type syntax

* refactor(lint): extract types to d.ts file

* fix(lint/types): unmark path.{full,category} as optional

* test(lint): fix incomplete paths in test cases

* chore(lint): handle undefined rawdata

* test(lint): add missing version_added field

* chore(types): introduce InternalDataType

* chore(eslint): bring back `@typescript/eslint`

* chore(tsconfig): re-enable skipLibCheck

Otherwise we stumble over web-features type
import without file extension.

* chore(lint): avoid cast to unknown

* chore(eslint): forbid unknown type in JSDoc

* chore(mocha): remove unused mjs extension

* chore(eslint): use jsdoc/recommended-typescript-flavor

* chore(eslint): fix type import

* chore(eslint): ignore no-empty-function once

* chore(eslint): disable duplicate no-unused-vars rule

* chore(eslint): use single no-unused-var + refine

* style(eslint): remove unused vars

* style(eslint): resolve no-unused-vars issue

Author: caugner

.github/workflows/add-push-artifacts.yml

@@ -21,8 +21,8 @@ jobs:
           cache: npm
           package-manager-cache: true
       - run: npm ci
-      - run: npx tsx ./scripts/enumerate-features.ts features.json
-      - run: npx tsx ./scripts/diff-features.ts --no-github --format=json > features.diff.json
+      - run: node ./scripts/enumerate-features.js features.json
+      - run: node ./scripts/diff-features.js --no-github --format=json > features.diff.json
       - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: enumerate-features

.lefthook.yml

@@ -8,7 +8,7 @@ pre-commit:
       stage_fixed: true
 
     - name: eslint
-      glob: "*.{js,jsx,tsx}"
+      glob: "*.js"
       run: npx eslint --fix --cache {staged_files}
       stage_fixed: true
 

.mocharc.json

@@ -1,3 +1,3 @@
 {
-  "extensions": ["ts", "tsx"]
+  "extensions": ["js"]
 }

eslint.config.js

@@ -22,6 +22,7 @@ const compat = new FlatCompat({
 export default [
   {
     ignores: [
+      'eslint.config.js',
       '**/*.json',
       '!*.json',
       '!schemas/*.json',
@@ -31,7 +32,7 @@ export default [
       '**/.editorconfig',
       'package-lock.json',
       'CODE_OF_CONDUCT.md',
-      '**/build/',
+      'build/',
       '**/coverage/',
       '**/types.d.ts',
     ],
@@ -42,8 +43,7 @@ export default [
       'plugin:@typescript-eslint/strict',
       'plugin:@typescript-eslint/stylistic',
       'plugin:import/recommended',
-      'plugin:import/typescript',
-      'plugin:jsdoc/recommended-typescript',
+      'plugin:jsdoc/recommended-typescript-flavor',
     ),
   ),
   {
@@ -64,25 +64,26 @@ export default [
       },
 
       parser: ts.parser,
-      ecmaVersion: 2020,
+      ecmaVersion: 'latest',
       sourceType: 'module',
     },
 
     settings: {
       'import/resolver': {
-        typescript: true,
         node: true,
       },
     },
 
     rules: {
       '@typescript-eslint/no-explicit-any': 'off',
       '@typescript-eslint/no-unused-expressions': 'error',
+      '@typescript-eslint/no-unused-vars': 'off',
 
-      '@typescript-eslint/no-unused-vars': [
+      'no-unused-vars': [
         'error',
         {
-          caughtErrors: 'none',
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
         },
       ],
 
@@ -100,7 +101,17 @@ export default [
       ],
 
       'import/no-named-as-default-member': 'off',
+      'import/no-unresolved': [
+        'error',
+        {
+          ignore: [
+            // https://github.com/import-js/eslint-plugin-import/issues/1810
+            '^yargs/helpers$',
+          ],
+        },
+      ],
       'jsdoc/check-param-names': 'error',
+      'jsdoc/prefer-import-tag': 'error',
       'jsdoc/require-description': 'warn',
 
       'jsdoc/require-jsdoc': [
@@ -117,6 +128,25 @@ export default [
         },
       ],
 
+      'jsdoc/no-restricted-syntax': [
+        'error',
+        {
+          contexts: [
+            {
+              comment:
+                'JsdocBlock:has(JsdocTag[tag="typedef"]:has(JsdocTypeImport))',
+              context: 'any',
+              message: 'Use @import JSDoc instead of @typedef.',
+            },
+            {
+              comment: 'JsdocBlock:has(JsdocTypeName[value="unknown"])',
+              context: 'any',
+              message: 'Avoid using unknown type in JSDoc.',
+            },
+          ],
+        },
+      ],
+
       'jsdoc/require-returns': 'error',
       'jsdoc/require-yields': 'error',
       'linebreak-style': ['error', 'unix'],
@@ -135,7 +165,7 @@ export default [
       'no-lone-blocks': 'error',
       'no-return-assign': 'error',
       'no-self-compare': 'error',
-      'no-unused-expressions': 'off',
+      'no-unused-expressions': 'error',
       'no-useless-call': 'error',
 
       'prefer-arrow-functions/prefer-arrow-functions': [

index.ts index.jsindex.ts renamed to index.js

@@ -1,13 +1,14 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
+/** @import {CompatData} from './types/types.js' */
+
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { fdir } from 'fdir';
 
-import { CompatData } from './types/types.js';
 import extend from './scripts/lib/extend.js';
 import dataFolders from './scripts/lib/data-folders.js';
 import { normalizePath, walk } from './utils/index.js';
@@ -16,23 +17,26 @@ const dirname = fileURLToPath(new URL('.', import.meta.url));
 
 /**
  * Recursively load one or more directories passed as arguments.
- * @param dirs The directories to load
- * @returns All of the browser compatibility data
+ * @param {...string} dirs The directories to load
+ * @returns {Promise<CompatData>} All of the browser compatibility data
  */
-const load = async (...dirs: string[]): Promise<CompatData> => {
+const load = async (...dirs) => {
   const result = {};
 
   for (const dir of dirs) {
-    const paths = new fdir()
-      .withBasePath()
-      .filter((fp) => fp.endsWith('.json'))
-      .crawl(path.join(dirname, dir))
-      .sync() as string[];
+    const paths = /** @type {string[]} */ (
+      new fdir()
+        .withBasePath()
+        .filter((fp) => fp.endsWith('.json'))
+        .crawl(path.join(dirname, dir))
+        .sync()
+    );
 
     for (const fp of paths) {
       try {
         const rawcontents = await fs.readFile(fp);
-        const contents: CompatData = JSON.parse(rawcontents.toString('utf8'));
+        /** @type {CompatData} */
+        const contents = JSON.parse(rawcontents.toString('utf8'));
 
         // Add source_file props
         const walker = walk(undefined, contents);
@@ -42,15 +46,15 @@ const load = async (...dirs: string[]): Promise<CompatData> => {
 
         extend(result, contents);
         /* c8 ignore start */
-      } catch (e) {
+      } catch {
         // Skip invalid JSON. Tests will flag the problem separately.
         continue;
       }
       /* c8 ignore stop */
     }
   }
 
-  return result as CompatData;
+  return /** @type {CompatData} */ (result);
 };
 
 export default await load(...dataFolders);

index.test.ts index.test.jsindex.test.ts renamed to index.test.js

@@ -1,21 +1,22 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-import assert from 'node:assert/strict';
+/** @import {CompatStatement} from './types/types.js' */
 
-import { CompatStatement } from './types/types.js';
+import assert from 'node:assert/strict';
 
 import bcd from './index.js';
 
 describe('Using BCD', () => {
   it('subscript notation', () => {
-    const data: CompatStatement | undefined =
-      bcd['api']['AbortController']['__compat'];
+    /** @type {CompatStatement | undefined} */
+    const data = bcd['api']['AbortController']['__compat'];
     assert.ok(data);
   });
 
   it('dot notation', () => {
-    const data: CompatStatement | undefined = bcd.api.AbortController.__compat;
+    /** @type {CompatStatement | undefined} */
+    const data = bcd.api.AbortController.__compat;
     assert.ok(data);
   });
 });

lint/common/overlap.ts lint/common/overlap.jslint/common/overlap.ts renamed to lint/common/overlap.js

@@ -4,21 +4,20 @@
 import chalk from 'chalk-template';
 import { compareVersions } from 'compare-versions';
 
-import { Logger, createStatementGroupKey } from '../utils.js';
-import {
-  BrowserName,
-  SimpleSupportStatement,
-  SupportStatement,
-} from '../../types/types.js';
+import { createStatementGroupKey } from '../utils.js';
 import compareStatements from '../../scripts/lib/compare-statements.js';
 
+/** @import {Logger} from '../utils.js' */
+/** @import {BrowserName, SimpleSupportStatement, SupportStatement} from '../../types/types.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: SimpleSupportStatement[]) => {
-  const groups = new Map<string, SimpleSupportStatement[]>();
+const groupByStatementKey = (data) => {
+  /** @type {Map<string, SimpleSupportStatement[]>} */
+  const groups = new Map();
 
   for (const support of data) {
     const key = createStatementGroupKey(support);
@@ -34,11 +33,12 @@ const groupByStatementKey = (data: SimpleSupportStatement[]) => {
 
 /**
  * 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: SimpleSupportStatement): string => {
-  const result: string[] = [];
+const formatRange = (support) => {
+  /** @type {string[]} */
+  const result = [];
   if (support.version_added) {
     result.push(`added: ${support.version_added}`);
   }
@@ -51,18 +51,14 @@ const formatRange = (support: SimpleSupportStatement): string => {
 
 /**
  * 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 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 {SupportStatement} data The data to test
+ * @param {BrowserName} browser The name of the browser
+ * @param {object} options The check options
+ * @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: SupportStatement,
-  browser: BrowserName,
-  { logger, fix = false }: { logger?: Logger; fix?: boolean },
-): SupportStatement => {
+export const checkOverlap = (data, browser, { logger, fix = false }) => {
   if (!Array.isArray(data)) {
     // If there's only one statement, skip since this is a linter for multiple statements
     return data;
@@ -76,8 +72,8 @@ export const checkOverlap = (
     const statements = groupData.slice().sort(compareStatements).reverse();
 
     for (let i = 0; i < statements.length - 1; i++) {
-      const current = statements.at(i) as SimpleSupportStatement;
-      const next = statements.at(i + 1) as SimpleSupportStatement;
+      const current = /** @type {SimpleSupportStatement} */ (statements.at(i));
+      const next = /** @type {SimpleSupportStatement} */ (statements.at(i + 1));
 
       if (!statementsOverlap(current, next)) {
         continue;
@@ -109,14 +105,11 @@ export const checkOverlap = (
 
 /**
  * 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: SimpleSupportStatement,
-  next: SimpleSupportStatement,
-): boolean => {
+const statementsOverlap = (current, next) => {
   if (typeof current.version_removed === 'string') {
     // If previous has no removed version, we always have an overlap.