feat(typemap): refresh from mdn by avivkeller · Pull Request #686 · nodejs/doc-kit

avivkeller · 2026-03-17T17:15:14Z

Fixes #683 by adding an update script that reads directly from MDN.

vercel · 2026-03-17T17:15:20Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Mar 21, 2026 2:51pm

codecov · 2026-03-17T17:16:23Z

Codecov Report

❌ Patch coverage is 26.19048% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.62%. Comparing base (0f69d7b) to head (40018a5).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
scripts/update-type-map.mjs	0.00%	26 Missing ⚠️
src/generators/metadata/utils/transformers.mjs	61.53%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #686      +/-   ##
==========================================
- Coverage   75.95%   75.62%   -0.34%     
==========================================
  Files         149      150       +1     
  Lines       13648    13627      -21     
  Branches     1040     1039       -1     
==========================================
- Hits        10367    10305      -62     
- Misses       3275     3316      +41     
  Partials        6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

This PR addresses incorrect/unstable external type reference URLs by switching metadata type linkification to a refreshed MDN-derived type map, and adds automation to keep that map up to date (fixing cases like the double // in MDN links noted in #683).

Changes:

Replace hardcoded MDN type mappings with a generated typeMap.json consumed by transformTypeToReferenceLink.
Add a script + scheduled GitHub Action workflow to regenerate the type map from MDN browser-compat-data releases.
Remove now-unneeded MDN mapping constants and adjust dependency placement.

Reviewed changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/generators/metadata/utils/transformers.mjs	Switches type resolution to use the new MDN-generated JSON type map.
src/generators/metadata/typeMap.json	Replaces the prior small map with a large MDN-derived mapping of types to canonical URLs.
src/generators/metadata/constants.mjs	Removes MDN-specific constants/mappings that are no longer used.
scripts/update-type-map.mjs	New generator script to fetch MDN browser-compat-data and write `typeMap.json`.
.github/workflows/update-type-map.yml	New scheduled workflow to run the generator and open/update a PR automatically.
package.json	Bumps version and moves `globals` to devDependencies.
package-lock.json	Locks the dependency move + version bump.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

scripts/update-type-map.mjs

src/generators/metadata/typeMap.json

src/generators/metadata/utils/transformers.mjs

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

scripts/update-type-map.mjs

src/generators/metadata/maps/mdn.json

package.json

ovflowd · 2026-03-21T12:07:39Z

scripts/update-type-map.mjs

+
+const compat = JSON.parse(
+  await loadFromURL(
+    'https://github.com/mdn/browser-compat-data/releases/latest/download/data.json'


nit: make this a constant on our shared constants file

What shared constants file? This is a script, not a constant used in prod?

ovflowd · 2026-03-21T12:08:50Z

scripts/update-type-map.mjs

+const creatingMapping = obj =>
+  Object.fromEntries(
+    Object.entries(obj)
+      .map(([k, v]) => [k.toLowerCase(), v.__compat.mdn_url])


is this typed? can you add an inline jsdoc with @see referring where this comes from if anywhere? :3

Yes and no. Yes, there is a typed version, but it's another npm dependency, so we use the URL that the dependency is published from

ovflowd · 2026-03-21T12:09:16Z

scripts/update-type-map.mjs

+};
+
+writeFile(
+  './src/generators/metadata/maps/mdn.json',


nit: if we have destination files as constants in generators, it'd be good to have it here too. But that's a small nit

ovflowd · 2026-03-21T12:09:26Z

scripts/update-type-map.mjs

+
+writeFile(
+  './src/generators/metadata/maps/mdn.json',
+  JSON.stringify(map, null, 2) + '\n'


Why we need an extra line?

Prettier requires files to end with a newline

ovflowd · 2026-03-21T12:09:57Z

src/generators/metadata/utils/transformers.mjs

 } from '../constants.mjs';
 import { slug } from './slugger.mjs';
 import { transformNodesToString } from '../../../utils/unist.mjs';
+import HARDCODED_TYPE_MAP from '../maps/hardcoded.json' with { type: 'json' };


nit: can we call this file something else? like something more intuitive/explanatory?

ovflowd · 2026-03-21T12:12:27Z

src/generators/metadata/index.mjs


  defaultConfiguration: {
-    typeMap: import.meta.resolve('./typeMap.json'),
+    typeMap: import.meta.resolve('./maps/hardcoded.json'),


Where is this used? I don't see references anywhere in the code?

In generate.mjs:

/** * Generates a flattened list of metadata entries from API docs. * * @type {import('./types').Generator['generate']} */ export async function* generate(inputs, worker) { const { metadata: config } = getConfig(); const typeMap = await importFromURL(config.typeMap); // Stream chunks as they complete - allows dependent generators // to start collecting/preparing while we're still processing for await (const chunkResult of worker.stream(inputs, typeMap)) { yield chunkResult.flat(); } }

feat(typemap): refresh from mdn

c164c6f

avivkeller requested a review from a team as a code owner March 17, 2026 17:15

Copilot AI review requested due to automatic review settings March 17, 2026 17:15

vercel bot deployed to Preview March 17, 2026 17:15 View deployment

Copilot started reviewing on behalf of avivkeller March 17, 2026 17:15 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

fixup!

d9768d1

vercel bot deployed to Preview March 17, 2026 17:33 View deployment

fixup!

ae450c9

vercel bot deployed to Preview March 17, 2026 17:34 View deployment

flakey5 approved these changes Mar 17, 2026

View reviewed changes

AugustinMauroy approved these changes Mar 17, 2026

View reviewed changes

ovflowd reviewed Mar 18, 2026

View reviewed changes

scripts/update-type-map.mjs Show resolved Hide resolved

ovflowd reviewed Mar 18, 2026

View reviewed changes

scripts/update-type-map.mjs Outdated Show resolved Hide resolved

ovflowd reviewed Mar 18, 2026

View reviewed changes

src/generators/metadata/maps/mdn.json Show resolved Hide resolved

ovflowd reviewed Mar 18, 2026

View reviewed changes

package.json Outdated Show resolved Hide resolved

fixup!;

40018a5

vercel bot deployed to Preview March 21, 2026 00:28 View deployment

ovflowd reviewed Mar 21, 2026

View reviewed changes

fixup!

5a1aa3e

vercel bot deployed to Preview March 21, 2026 14:51 View deployment

Conversation

avivkeller commented Mar 17, 2026

Uh oh!

vercel bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

vercel bot commented Mar 17, 2026 •

edited

Loading

codecov bot commented Mar 17, 2026 •

edited

Loading

avivkeller Mar 21, 2026 •

edited

Loading

avivkeller Mar 21, 2026 •

edited

Loading