feat(typemap): refresh from mdn

Author: avivkeller

.github/workflows/update-type-map.yml

@@ -0,0 +1,44 @@
+name: Update Type Map
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * 0'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  type-map-update:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a90bcbc6539c36a85cdfeb73f7e2f433735f215b # v2.15.0
+        with:
+          egress-policy: audit
+
+      - name: Git Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - run: node scripts/update-type-map.mjs
+
+      - name: Open pull request
+        uses: gr2m/create-or-update-pull-request-action@b65137ca591da0b9f43bad7b24df13050ea45d1b # v1.10.1
+        # Creates a PR or update the Action's existing PR, or
+        # no-op if the base branch is already up-to-date.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          update-pull-request-title-and-body: true
+          branch: chore/update-types
+          body: |
+            Updates the type map
+
+            cc @nodejs/web-infra
+
+            Check this workflow's logs at ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}.
+          commit-message: 'meta: update type map'
+          title: 'meta: update type map'
+          draft: true

.prettierignore

@@ -9,3 +9,6 @@ src/generators/web/template.html
 
 # Output
 out/
+
+# Generated Files
+src/generators/metadata/maps/mdn.json

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@node-core/doc-kit",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nodejs/doc-kit.git"
@@ -37,6 +37,7 @@
     "eslint-plugin-import-x": "^4.16.2",
     "eslint-plugin-jsdoc": "^62.8.0",
     "eslint-plugin-react-x": "^3.0.0",
+    "globals": "~17.3.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
     "prettier": "3.8.1"
@@ -58,7 +59,6 @@
     "estree-util-visit": "^2.0.0",
     "github-slugger": "^2.0.0",
     "glob-parent": "^6.0.2",
-    "globals": "^17.3.0",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
     "lightningcss-wasm": "^1.32.0",

package.json

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url';
+
+// Comparator Constants
+export const BASE =
+  process.env.BASE || fileURLToPath(import.meta.resolve('../base'));
+
+export const HEAD =
+  process.env.HEAD || fileURLToPath(import.meta.resolve('../out'));
+
+export const TITLE =
+  process.env.TITLE || `## \`${process.env.GENERATOR ?? '...'}\` Generator`;
+
+// MDN Constants
+export const MDN_COMPAT_URL =
+  'https://github.com/mdn/browser-compat-data/releases/latest/download/data.json';
+
+export const MDN_TYPE_MAP = fileURLToPath(
+  import.meta.resolve('../src/generators/metadata/maps/mdn.json')
+);

scripts/comparators/constants.mjs

@@ -0,0 +1,20 @@
+import { writeFile } from 'node:fs/promises';
+
+import { MDN_COMPAT_URL, MDN_TYPE_MAP } from './constants.mjs';
+import { loadFromURL } from '../src/utils/url.mjs';
+
+const compat = JSON.parse(await loadFromURL(MDN_COMPAT_URL));
+
+const creatingMapping = obj =>
+  Object.fromEntries(
+    Object.entries(obj)
+      .map(([k, v]) => [k.toLowerCase(), v.__compat.mdn_url])
+      .filter(([, v]) => v)
+  );
+
+const map = {
+  ...creatingMapping(compat.api),
+  ...creatingMapping(compat.javascript.builtins),
+};
+
+writeFile(MDN_TYPE_MAP, JSON.stringify(map, null, 2));

scripts/constants.mjs

@@ -2,8 +2,6 @@
 // we don't need to check it for stability references
 export const IGNORE_STABILITY_STEMS = ['documentation'];
 
-import globals from 'globals';
-
 // These are string replacements specific to Node.js API docs for anchor IDs
 export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /node.js/i, to: 'nodejs' }, // Replace Node.js
@@ -14,21 +12,6 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /^(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
 ];
 
-// This is the base URL of the MDN Web documentation
-export const DOC_MDN_BASE_URL = 'https://developer.mozilla.org/en-US/docs/Web/';
-
-// This is the base URL of the Man7 documentation
-export const DOC_MAN_BASE_URL = 'http://man7.org/linux/man-pages/man';
-
-// This is the base URL for the MDN JavaScript documentation
-export const DOC_MDN_BASE_URL_JS = `${DOC_MDN_BASE_URL}JavaScript/`;
-
-// This is the base URL for the MDN JavaScript primitives documentation
-export const DOC_MDN_BASE_URL_JS_PRIMITIVES = `${DOC_MDN_BASE_URL_JS}Data_structures`;
-
-// This is the base URL for the MDN JavaScript global objects documentation
-export const DOC_MDN_BASE_URL_JS_GLOBALS = `${DOC_MDN_BASE_URL_JS}Reference/Global_Objects/`;
-
 // These are regular expressions used to determine if a given Markdown heading
 // is a specific type of API Doc entry (e.g., Event, Class, Method, etc)
 // and to extract the inner content of said Heading to be used as the API doc entry name
@@ -76,60 +59,5 @@ export const DOC_API_HEADING_TYPES = [
 // This regex is used to match basic TypeScript generic types (e.g., Promise<string>)
 export const TYPE_GENERIC_REGEX = /^([^<]+)<([^>]+)>$/;
 
-// This is a mapping for types within the Markdown content and their respective
-// JavaScript primitive types within the MDN JavaScript docs
-// @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Data_structures#primitive_values
-export const DOC_TYPES_MAPPING_PRIMITIVES = {
-  null: 'null',
-  undefined: 'undefined',
-  boolean: 'boolean',
-  number: 'number',
-  bigint: 'bigint',
-  string: 'string',
-  symbol: 'symbol',
-  integer: 'number',
-};
-
-// This is a mapping for types within the Markdown content and their respective
-// JavaScript globals types within the MDN JavaScript docs
-// @see DOC_MDN_BASE_URL_JS_GLOBALS
-export const DOC_TYPES_MAPPING_GLOBALS = {
-  // This is updated with every ES-spec, so, as long as the
-  // `globals` package is up-to-date, so will our globals list.
-  ...Object.fromEntries(Object.keys(globals.builtin).map(e => [e, e])),
-  AsyncGeneratorFunction: 'AsyncGeneratorFunction',
-  AsyncIterator: 'AsyncIterator',
-  AsyncFunction: 'AsyncFunction',
-  TypedArray: 'TypedArray',
-  ErrorEvent: 'ErrorEvent',
-  'WebAssembly.Instance': 'WebAssembly/Instance',
-};
-
-// This is a mapping for miscellaneous types within the Markdown content and their respective
-// external reference on appropriate 3rd-party vendors/documentation sites.
-export const DOC_TYPES_MAPPING_OTHER = {
-  any: `${DOC_MDN_BASE_URL_JS_PRIMITIVES}#Data_types`,
-  this: `${DOC_MDN_BASE_URL_JS}Reference/Operators/this`,
-
-  ArrayBufferView: `${DOC_MDN_BASE_URL}/API/ArrayBufferView`,
-
-  AsyncIterable: 'https://tc39.github.io/ecma262/#sec-asynciterable-interface',
-
-  'Module Namespace Object':
-    'https://tc39.github.io/ecma262/#sec-module-namespace-exotic-objects',
-
-  Iterable: `${DOC_MDN_BASE_URL_JS}Reference/Iteration_protocols#The_iterable_protocol`,
-
-  CloseEvent: `${DOC_MDN_BASE_URL}/API/CloseEvent`,
-  EventSource: `${DOC_MDN_BASE_URL}/API/EventSource`,
-  MessageEvent: `${DOC_MDN_BASE_URL}/API/MessageEvent`,
-
-  DOMException: `${DOC_MDN_BASE_URL}/API/DOMException`,
-  Storage: `${DOC_MDN_BASE_URL}/API/Storage`,
-  WebSocket: `${DOC_MDN_BASE_URL}/API/WebSocket`,
-
-  FormData: `${DOC_MDN_BASE_URL}API/FormData`,
-  Headers: `${DOC_MDN_BASE_URL}/API/Headers`,
-  Response: `${DOC_MDN_BASE_URL}/API/Response`,
-  Request: `${DOC_MDN_BASE_URL}/API/Request`,
-};
+// This is the base URL of the Man7 documentation
+export const DOC_MAN_BASE_URL = 'http://man7.org/linux/man-pages/man';

scripts/update-type-map.mjs

@@ -1,8 +1,8 @@
 'use strict';
 
 import { parseApiDoc } from './utils/parse.mjs';
+import { parseTypeMap } from '../../parsers/json.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
-import { importFromURL } from '../../utils/url.mjs';
 
 /**
  * Process a chunk of API doc files in a worker thread.
@@ -28,7 +28,7 @@ export async function processChunk(fullInput, itemIndices, typeMap) {
 export async function* generate(inputs, worker) {
   const { metadata: config } = getConfig();
 
-  const typeMap = await importFromURL(config.typeMap);
+  const typeMap = await parseTypeMap(config.typeMap);
 
   // Stream chunks as they complete - allows dependent generators
   // to start collecting/preparing while we're still processing

src/generators/metadata/constants.mjs

@@ -16,9 +16,5 @@ export default createLazyGenerator({
 
   dependsOn: 'ast',
 
-  defaultConfiguration: {
-    typeMap: import.meta.resolve('./typeMap.json'),
-  },
-
   hasParallelProcessor: true,
 });