feat(schemas): separate public from internal schema

.gitignore

@@ -10,5 +10,6 @@ yarn.lock
 .nyc_output/
 coverage.lcov
 coverage/
-types/types.d.ts
+/types/internal.d.ts
+/types/public.d.ts
 .DS_Store

.prettierignore

@@ -11,4 +11,5 @@ LICENSE
 /build/
 coverage/
 .features.json
-types.d.ts
+/types/internal.d.ts
+/types/public.d.ts

.vscode/settings.json

@@ -31,5 +31,6 @@
       ],
       "url": "/schemas/browsers.schema.json"
     }
-  ]
+  ],
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

eslint.config.js

@@ -34,7 +34,8 @@ export default [
       'CODE_OF_CONDUCT.md',
       'build/',
       '**/coverage/',
-      '**/types.d.ts',
+      'types/internal.d.ts',
+      'types/public.d.ts',
     ],
   },
   ...fixupConfigRules(
@@ -83,9 +84,7 @@ export default [
       '@typescript-eslint/no-explicit-any': 'off',
       '@typescript-eslint/no-floating-promises': 'error',
       '@typescript-eslint/no-unused-expressions': 'error',
-      '@typescript-eslint/no-unused-vars': 'off',
-
-      'no-unused-vars': [
+      '@typescript-eslint/no-unused-vars': [
         'error',
         {
           argsIgnorePattern: '^_',
@@ -172,6 +171,7 @@ export default [
       'no-return-assign': 'error',
       'no-self-compare': 'error',
       'no-unused-expressions': 'error',
+      'no-unused-vars': 'off', // Using @typescript-eslint/no-unused-vars instead.
       'no-useless-call': 'error',
 
       'prefer-arrow-functions/prefer-arrow-functions': [

index.js

@@ -1,7 +1,7 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-/** @import {CompatData} from './types/types.js' */
+/** @import {InternalCompatData} from './types/index.js' */
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -17,10 +17,12 @@ const dirname = fileURLToPath(new URL('.', import.meta.url));
 
 /**
  * Recursively load one or more directories passed as arguments.
- * @param {...string} dirs The directories to load
- * @returns {Promise<CompatData>} All of the browser compatibility data
+ * @template {keyof InternalCompatData} Dir
+ * @param {...Dir} dirs The directories to load
+ * @returns {Promise<Pick<InternalCompatData, Dir>>} All of the browser compatibility data
  */
 const load = async (...dirs) => {
+  /** @type {Partial<Pick<InternalCompatData, Dir>>} */
   const result = {};
 
   for (const dir of dirs) {
@@ -35,12 +37,13 @@ const load = async (...dirs) => {
     for (const fp of paths) {
       try {
         const rawcontents = await fs.readFile(fp);
-        /** @type {CompatData} */
+        /** @type {InternalCompatData} */
         const contents = JSON.parse(rawcontents.toString('utf8'));
 
         // Add source_file props
         const walker = walk(undefined, contents);
         for (const { compat } of walker) {
+          // @ts-expect-error Need to better reflect transition from internal to public data.
           compat.source_file = normalizePath(path.relative(dirname, fp));
         }
 
@@ -54,7 +57,10 @@ const load = async (...dirs) => {
     }
   }
 
-  return /** @type {CompatData} */ (result);
+  return /** @type {Pick<InternalCompatData, Dir>} */ (result);
 };
 
-export default await load(...dataFolders);
+/** @type {InternalCompatData} */
+const bcd = await load(...dataFolders);
+
+export default bcd;

index.test.js

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

lint/common/overlap.js

@@ -9,15 +9,15 @@ 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' */
+/** @import {BrowserName, InternalSimpleSupportStatement, InternalSupportStatement} from '../../types/index.js' */
 
 /**
  * Groups statements by group key.
- * @param {SimpleSupportStatement[]} data The support statements to group.
- * @returns {Map<string, SimpleSupportStatement[]>} the statement groups
+ * @param {InternalSimpleSupportStatement[]} data The support statements to group.
+ * @returns {Map<string, InternalSimpleSupportStatement[]>} the statement groups
  */
 const groupByStatementKey = (data) => {
-  /** @type {Map<string, SimpleSupportStatement[]>} */
+  /** @type {Map<string, InternalSimpleSupportStatement[]>} */
   const groups = new Map();
 
   for (const support of data) {
@@ -34,7 +34,7 @@ const groupByStatementKey = (data) => {
 
 /**
  * Formats a support statement as a simplified JSON-like version range.
- * @param {SimpleSupportStatement} support The statement to format
+ * @param {InternalSimpleSupportStatement} support The statement to format
  * @returns {string} The formatted range
  */
 const formatRange = (support) => {
@@ -52,12 +52,12 @@ const formatRange = (support) => {
 
 /**
  * Process data and check to make sure there aren't support statements whose version ranges overlap.
- * @param {SupportStatement} data The data to test
+ * @param {InternalSupportStatement} 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)
+ * @returns {InternalSupportStatement} the data (with fixes, if specified)
  */
 export const checkOverlap = (data, browser, { logger, fix = false }) => {
   if (!Array.isArray(data)) {
@@ -73,8 +73,12 @@ export const checkOverlap = (data, browser, { logger, fix = false }) => {
     const statements = groupData.slice().sort(compareStatements).reverse();
 
     for (let i = 0; i < statements.length - 1; i++) {
-      const current = /** @type {SimpleSupportStatement} */ (statements.at(i));
-      const next = /** @type {SimpleSupportStatement} */ (statements.at(i + 1));
+      const current = /** @type {InternalSimpleSupportStatement} */ (
+        statements.at(i)
+      );
+      const next = /** @type {InternalSimpleSupportStatement} */ (
+        statements.at(i + 1)
+      );
 
       if (!statementsOverlap(current, next)) {
         continue;
@@ -106,8 +110,8 @@ export const checkOverlap = (data, browser, { logger, fix = false }) => {
 
 /**
  * Checks if the support statements overlap in terms of their version ranges.
- * @param {SimpleSupportStatement} current the current statement.
- * @param {SimpleSupportStatement} next the chronologically following statement.
+ * @param {InternalSimpleSupportStatement} current the current statement.
+ * @param {InternalSimpleSupportStatement} next the chronologically following statement.
  * @returns {boolean} Whether the support statements overlap.
  */
 const statementsOverlap = (current, next) => {

lint/fixer/browser-order.js

@@ -1,7 +1,7 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-/** @import {BrowserName, CompatStatement, SupportBlock} from '../../types/types.js' */
+/** @import {BrowserName, InternalCompatStatement, InternalSupportBlock} from '../../types/index.js' */
 
 /**
  * Return a new "support_block" object whose first-level properties
@@ -10,8 +10,8 @@
  * guaranteed "own" property ordering, which is insertion order for
  * non-integer keys (which is our case).
  * @param {string} key The key of the object
- * @param {CompatStatement} value The value of the key
- * @returns {CompatStatement} Value with sorting applied
+ * @param {InternalCompatStatement} value The value of the key
+ * @returns {InternalCompatStatement} Value with sorting applied
  */
 export const orderSupportBlock = (key, value) => {
   if (key === '__compat') {
@@ -21,15 +21,15 @@ export const orderSupportBlock = (key, value) => {
       .sort()
       .reduce(
         /**
-         * @param {SupportBlock} result
+         * @param {InternalSupportBlock} result
          * @param {BrowserName} key
-         * @returns {SupportBlock}
+         * @returns {InternalSupportBlock}
          */
         (result, key) => {
           result[key] = value.support[key];
           return result;
         },
-        /** @type {SupportBlock} */ ({}),
+        /** @type {InternalSupportBlock} */ ({}),
       );
   }
   return value;

lint/fixer/common-errors.js

@@ -3,33 +3,33 @@
 
 import { walk } from '../../utils/index.js';
 
-/** @import {CompatStatement} from '../../types/types.js' */
+/** @import {InternalSupportBlock} from '../../types/index.js' */
 
 /**
- * Fixes common errors in CompatStatements.
+ * Fixes common errors in an InternalSupportBlock.
  *
  * - Replaces `browser: { version_added: "mirror" }` with `browser: "mirror"`
  * - Wraps `browser: false` with `browser: `{ version_added: false }`
- * @param {CompatStatement} compat The compat statement to fix
+ * @param {InternalSupportBlock} support The support block to fix
  * @returns {void}
  */
-export const fixCommonErrorsInCompatStatement = (compat) => {
-  for (const browser of Object.keys(compat.support)) {
-    if (compat.support[browser] === false) {
-      compat.support[browser] = {
+export const fixCommonErrorsInSupportBlock = (support) => {
+  for (const browser of Object.keys(support)) {
+    if (support[browser] === false) {
+      support[browser] = {
         version_added: false,
       };
     } else if (
-      typeof compat.support[browser] === 'object' &&
-      JSON.stringify(compat.support[browser]) === '{"version_added":"mirror"}'
+      typeof support[browser] === 'object' &&
+      JSON.stringify(support[browser]) === '{"version_added":"mirror"}'
     ) {
-      compat.support[browser] = 'mirror';
+      support[browser] = 'mirror';
     }
     if (
       browser == 'ie' &&
-      JSON.stringify(compat.support[browser]) === '{"version_added":false}'
+      JSON.stringify(support[browser]) === '{"version_added":false}'
     ) {
-      Reflect.deleteProperty(compat.support, browser);
+      Reflect.deleteProperty(support, browser);
     }
   }
 };
@@ -48,7 +48,7 @@ const fixCommonErrors = (filename, actual) => {
   const bcd = JSON.parse(actual);
 
   for (const { compat } of walk(undefined, bcd)) {
-    fixCommonErrorsInCompatStatement(compat);
+    fixCommonErrorsInSupportBlock(compat.support);
   }
 
   return JSON.stringify(bcd, null, 2);

lint/fixer/common-errors.test.js

@@ -3,13 +3,13 @@
 
 import assert from 'node:assert/strict';
 
-import { fixCommonErrorsInCompatStatement } from './common-errors.js';
+import { fixCommonErrorsInSupportBlock } from './common-errors.js';
 
 /**
  * @import { InternalSupportBlock } from '../../types/index.js'
  */
 
-/** @type {{ input: any; output?: InternalSupportBlock }[]} */
+/** @type {{ input: any; output: InternalSupportBlock }[]} */
 const tests = [
   // Replace unwrapped "false".
   {
@@ -40,14 +40,10 @@ describe('fix -> common errors', () => {
   let i = 1;
   for (const test of tests) {
     it(`Test #${i}`, () => {
-      const input = {
-        support: test.input,
-      };
-      const output = {
-        support: test.output ?? test.input,
-      };
-
-      fixCommonErrorsInCompatStatement(input);
+      const input = test.input;
+      const output = test.output ?? test.input;
+
+      fixCommonErrorsInSupportBlock(input);
 
       assert.deepStrictEqual(input, output);
     });

lint/fixer/feature-order.js

@@ -3,7 +3,7 @@
 
 import compareFeatures from '../../scripts/lib/compare-features.js';
 
-/** @import {Identifier} from '../../types/types.js' */
+/** @import {InternalIdentifier} from '../../types/index.js' */
 
 /**
  * Return a new feature object whose first-level properties have been
@@ -12,24 +12,24 @@ import compareFeatures from '../../scripts/lib/compare-features.js';
  * property ordering, which is insertion order for non-integer keys
  * (which is our case).
  * @param {string} _ The key in the object
- * @param {Identifier} value The value of the key
- * @returns {Identifier} The new value
+ * @param {InternalIdentifier} value The value of the key
+ * @returns {InternalIdentifier} The new value
  */
 export const orderFeatures = (_, value) => {
   if (value instanceof Object && '__compat' in value) {
     value = Object.keys(value)
       .sort(compareFeatures)
       .reduce(
         /**
-         * @param {Identifier} result
+         * @param {InternalIdentifier} result
          * @param {string} key
-         * @returns {Identifier}
+         * @returns {InternalIdentifier}
          */
         (result, key) => {
           result[key] = value[key];
           return result;
         },
-        /** @type {Identifier} */ ({}),
+        /** @type {InternalIdentifier} */ ({}),
       );
   }
   return value;