feat(schemas): separate public from internal schema

.github/workflows/test.yml

@@ -5,7 +5,6 @@ on:
     branches:
       - main
   pull_request:
-  merge_group:
 
 permissions:
   contents: read
@@ -18,11 +17,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+      - name: Setup Node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: ".nvmrc"
           cache: npm
@@ -40,11 +41,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+      - name: Setup Node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: ".nvmrc"
           cache: npm
@@ -58,11 +61,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+      - name: Setup Node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: ".nvmrc"
           cache: npm
@@ -71,3 +76,64 @@ jobs:
       - run: npm ci
 
       - run: npm run unittest
+
+  diff-build:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}-diff-build
+      cancel-in-progress: true
+
+    steps:
+      - name: Determine base ref
+        id: base
+        run: |
+          if [[ "$GITHUB_HEAD_REF" == "release" ]]; then
+            VERSION=$(npm view @mdn/browser-compat-data version)
+            echo "ref=v$VERSION" >> "$GITHUB_OUTPUT"
+            echo "Comparing release branch against published v$VERSION"
+          else
+            echo "ref=$GITHUB_BASE_REF" >> "$GITHUB_OUTPUT"
+            echo "Comparing against base branch: $GITHUB_BASE_REF"
+          fi
+
+      # Base
+
+      - name: Checkout (base)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ steps.base.outputs.ref }}
+          path: base
+          persist-credentials: false
+
+      - name: Checkout (PR)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          path: pr
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version-file: pr/.nvmrc
+          cache: npm
+          cache-dependency-path: |
+            base/package-lock.json
+            pr/package-lock.json
+          package-manager-cache: true
+
+      - name: Install
+        run: |
+          cd base && npm ci | sed "s/^/[base] /" &
+          cd pr && npm ci | sed "s/^/[pr] /" &
+          wait
+
+      - name: Format
+        run: |
+          cd base/build && npx prettier --write . | sed "s/^/[base] /" &
+          cd pr/build && npx prettier --write . | sed "s/^/[pr] /" &
+          wait
+
+      - name: Diff
+        run: git diff --color=always --no-index base/build/ pr/build/ || true

.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(
@@ -77,9 +78,7 @@ export default [
     rules: {
       '@typescript-eslint/no-explicit-any': 'off',
       '@typescript-eslint/no-unused-expressions': 'error',
-      '@typescript-eslint/no-unused-vars': 'off',
-
-      'no-unused-vars': [
+      '@typescript-eslint/no-unused-vars': [
         'error',
         {
           argsIgnorePattern: '^_',
@@ -166,6 +165,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;