feat(schemas)!: separate public from internal schema (#29041)

Add a public schema for `data.json`, separate from the internal
browser/compat file schemas, and refine schema descriptions.

BREAKING CHANGES:

- `CompatStatement.source_file` is now required.
- `BrowserStatement.upstream` is narrowed to `UpstreamBrowserName`,
  a subset of `BrowserName`.

Co-authored-by: Daniel D. Beck <daniel@ddbeck.com>
Co-authored-by: Florian Scholz <fs@florianscholz.com>

Author: 3 people

.github/workflows/test.yml

@@ -133,8 +133,8 @@ jobs:
       - name: Format
         run: |
           # sed command prefixes each line of output with [base] or [pr]
-          cd base/build && npx prettier --write . | sed "s/^/[base] /" &
-          cd pr/build && npx prettier --write . | sed "s/^/[pr] /" &
+          cd base/build && npx prettier --ignore-path /dev/null --write . | sed "s/^/[base] /" &
+          cd pr/build && npx prettier --ignore-path /dev/null --write . | sed "s/^/[pr] /" &
           wait
 
       - name: Diff

.gitignore

@@ -3,12 +3,11 @@ __enumerating__*/
 .idea
 *.log
 /node_modules/
-/build/
-!/scripts/build/
 yarn.lock
 .eslintcache
 .nyc_output/
 coverage.lcov
 coverage/
-types/types.d.ts
+/types/internal.d.ts
+/types/public.d.ts
 .DS_Store

.lefthook.yml

@@ -16,8 +16,10 @@ pre-commit:
       glob: "**/*.json"
       exclude:
         - .vscode/*.json
+        - build/*.json
         - browsers/*.json
         - schemas/*.json
+        - types/*.json
       run: npm run lint:fix {staged_files} && git add lint/common/standard-track-exceptions.txt
       stage_fixed: true
 

.prettierignore

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

build/.gitignore

@@ -0,0 +1,4 @@
+*
+!.gitignore
+!.npmignore
+!tsconfig.json

build/.npmignore

@@ -0,0 +1,3 @@
+.gitignore
+.npmignore
+tsconfig.json

build/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "skipLibCheck": false
+  },
+  "include": ["*.d.ts", "*.d.mts"],
+  "exclude": []
+}

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, InternalCompatStatement} 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,13 +37,16 @@ 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
+        // Add source_file props. The `source_file` field is part of the public
+        // `CompatStatement` shape, not the internal one, so cast at the assignment.
         const walker = walk(undefined, contents);
         for (const { compat } of walker) {
-          compat.source_file = normalizePath(path.relative(dirname, fp));
+          /** @type {InternalCompatStatement & { source_file: string }} */ (
+            compat
+          ).source_file = normalizePath(path.relative(dirname, fp));
         }
 
         extend(result, contents);
@@ -54,7 +59,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);
   });