remove: better usage of oxc ecosystem by AugustinMauroy · Pull Request #926 · nodejs/doc-kit

AugustinMauroy · 2026-07-20T14:56:47Z

Description

main: +-200ms for api-link test
with changes: 150ms api-link for test

So there aren't perf gap we just win on the amount of dependency

also since oxc-parser didn't have loc I had to write small code that do same job once oxc-parser will have loc we will be able to come back

also use esrap recommend by oxc https://oxc.rs/docs/guide/usage/parser.html#print which is lighter

Validation

test should pass

Related Issues

NA

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

cursor · 2026-07-20T14:56:52Z

PR Summary

Medium Risk
Changes how API doc line links and JSX are produced, with intentional behavior tweaks in export/indirect resolution; mistakes would skew documentation anchors or generated page code.

Overview
Dependency and toolchain shift: Drops acorn, estree-util-visit, and estree-util-to-js in favor of oxc-parser and esrap (v1.4.3). Dependabot groups oxc-* and esrap; coverage config excludes more paths including **/__tests__.

Parsing and API links: ast-js now parses with oxc-parser (CommonJS, range) and attaches sourceText on each program. Api-links utilities walk the AST with oxc-parser’s Visitor instead of estree-util-visit, and line numbers come from a new getLineNumber helper using byte range offsets because loc is not available. Export/indirect handling is adjusted (e.g. exports.Buffer = Buffer maps by RHS identifier; prototype assignments record indirects for any identifier RHS; module.exports = Buffer can register constructors).

JSX codegen: jsx-ast and related tests emit TSX via esrap/print with double quotes (rolldown compatibility) instead of estree-util-to-js.

Tests: Adds broad api-links unit tests for extractExports, findDefinitions, and checkIndirectReferences; fixture tests use node:fs globSync instead of tinyglobby.

^{Reviewed by Cursor Bugbot for commit 9b7806f. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-07-20T14:56:52Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 20, 2026 10:27pm

codecov · 2026-07-20T14:57:53Z

Codecov Report

❌ Patch coverage is 99.48980% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 77.24%. Comparing base (ecbeaa6) to head (9b7806f).

Files with missing lines	Patch %	Lines
src/generators/api-links/utils/extractExports.mjs	98.64%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #926      +/-   ##
==========================================
- Coverage   84.89%   77.24%   -7.66%     
==========================================
  Files         193      127      -66     
  Lines       17512     9475    -8037     
  Branches     1551      700     -851     
==========================================
- Hits        14867     7319    -7548     
+ Misses       2639     2150     -489     
  Partials        6        6

☔ View full report in Codecov by Harness.
📢 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.

github-actions · 2026-07-20T14:59:33Z

`api-links` Generator

Output

apilinks.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    'Agent.defaultMaxSockets': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L291',
    'Buffer.alloc': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L435',
    'Buffer.allocUnsafe': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L449',
    'Buffer.allocUnsafeSlow': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L461',
...
    'Buffer[kIsEncodingSymbol]': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L611',
+   'EventEmitter.EventEmitter': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L209',
+   'EventEmitter.captureRejectionSymbol': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L224',
+   'EventEmitter.errorMonitor': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L246',
+   'EventEmitter.init': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L332',
+   'EventEmitter.setMaxListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L304',
+   'EventEmitter.usingDomains': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L222',
+   'Module.SourceMap': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L34',
+   'Module.constants': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L25',
+   'Module.enableCompileCache': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L26',
+   'Module.findPackageJSON': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L27',
+   'Module.findSourceMap': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L33',
+   'Module.flushCompileCache': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L28',
+   'Module.getCompileCacheDir': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L29',
+   'Module.getSourceMapsSupport': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L35',
+   'Module.register': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L24',
+   'Module.setSourceMapsSupport': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L36',
+   'Module.stripTypeScriptTypes': 'https://github.com/nodejs/node/blob/HEAD/lib/module.js#L30',
    'Stream.Duplex': 'https://github.com/nodejs/node/blob/HEAD/lib/stream.js#L105',
    'Stream.PassThrough': 'https://github.com/nodejs/node/blob/HEAD/lib/stream.js#L107',
    'Stream.Readable': 'https://github.com/nodejs/node/blob/HEAD/lib/stream.js#L63',
    'Stream.Stream': 'https://github.com/nodejs/node/blob/HEAD/lib/stream.js#L144',
    'Stream.Transform': 'https://github.com/nodejs/node/blob/HEAD/lib/stream.js#L106',
...
    'agent.addRequest': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L356',
+   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L326',
-   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L295',
    'agent.createSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L427',
    'agent.destroy': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L660',
+   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L484',
-   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L325',
    'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L616',
    'agent.removeSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L555',
    'agent.reuseSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L652',
    'assert.assert': 'https://github.com/nodejs/node/blob/HEAD/lib/assert.js#L185',
    'asyncResource.asyncId': 'https://github.com/nodejs/node/blob/HEAD/lib/async_hooks.js#L243',
...
    'dynamiclibrary.getFunctions': 'https://github.com/nodejs/node/blob/HEAD/lib/ffi.js#L111',
+   'eventemitter._events': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L256',
+   'eventemitter._eventsCount': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L257',
+   'eventemitter._maxListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L258',
+   'eventemitter.addListener': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L615',
+   'eventemitter.emit': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L489',
+   'eventemitter.eventNames': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L872',
+   'eventemitter.getMaxListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L420',
+   'eventemitter.listenerCount': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L835',
+   'eventemitter.listeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L814',
+   'eventemitter.off': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L734',
+   'eventemitter.on': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L619',
+   'eventemitter.once': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L651',
+   'eventemitter.prependListener': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L628',
+   'eventemitter.prependOnceListener': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L665',
+   'eventemitter.rawListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L824',
+   'eventemitter.removeAllListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L743',
+   'eventemitter.removeListener': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L679',
+   'eventemitter.setMaxListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L404',
+   'eventemitter[kCapture]': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L233',
    'events.EventEmitter': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L209',
    'events.getEventListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L933',
    'events.getMaxListeners': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L962',
    'events.listenerCount': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L980',
    'events.on': 'https://github.com/nodejs/node/blob/HEAD/lib/events.js#L1085',
...
    'server._emitCloseIfDrained': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2776',
+   'server._listen2': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2193',
-   'server._listen2': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2278',
    'server._setupWorker': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2825',
    'server.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2596',
+   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2729',
+   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L120',
+   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L122',
-   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L671',
-   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L681',
-   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L693',
    'server.getConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2691',
    'server.listen': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2398',
    'server.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2834',
+   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L124',
-   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L709',
    'server.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2843',
+   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2769',
-   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L677',
    'server[kDeserialize]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2319',
    'server[kTransferList]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2292',
    'server[kTransfer]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2297',
+   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2798',
-   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L716',
    'serverresponse._finish': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L246',
    'serverresponse._implicitHeader': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L403',
    'serverresponse.assignSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L296',
    'serverresponse.detachSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L307',
    'serverresponse.statusCode': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L269',

Performance

Metric	Base	Head	Diff
Elapsed time	1.37 s	880.00 ms	-490.00 ms (-35.77%)
User CPU time	2.83 s	1.90 s	-930.00 ms (-32.86%)
System CPU time	320.00 ms	230.00 ms	-90.00 ms (-28.13%)
Peak resident memory	351.20 MB	336.84 MB	-14.36 MB (-4.09%)

`legacy-html` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	20.14 s	19.15 s	-990.00 ms (-4.92%)
User CPU time	62.86 s	60.00 s	-2.86 s (-4.55%)
System CPU time	2.64 s	2.57 s	-70.00 ms (-2.65%)
Peak resident memory	2.17 GB	2.25 GB	+78.28 MB (+3.52%)

`legacy-json` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	9.46 s	10.09 s	+630.00 ms (+6.66%)
User CPU time	27.76 s	27.26 s	-500.00 ms (-1.80%)
System CPU time	1.87 s	1.95 s	+80.00 ms (+4.28%)
Peak resident memory	1.58 GB	1.68 GB	+100.96 MB (+6.24%)

`llms-txt` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	6.87 s	9.01 s	+2.14 s (+31.15%)
User CPU time	19.03 s	25.08 s	+6.05 s (+31.79%)
System CPU time	1.53 s	1.80 s	+270.00 ms (+17.65%)
Peak resident memory	1.71 GB	1.58 GB	-130.01 MB (-7.44%)

`orama-db` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	6.63 s	9.15 s	+2.52 s (+38.01%)
User CPU time	19.23 s	24.25 s	+5.02 s (+26.11%)
System CPU time	1.66 s	1.92 s	+260.00 ms (+15.66%)
Peak resident memory	1.82 GB	1.68 GB	-148.95 MB (-7.98%)

`web` Generator

Output size

|-|-|-|-|

| all.html | 21.28 MB | 21.28 MB | -202.00 B (-0.00%) |

Performance

Metric	Base	Head	Diff
Elapsed time	79.07 s	72.13 s	-6.94 s (-8.78%)
User CPU time	166.52 s	148.69 s	-17.83 s (-10.71%)
System CPU time	4.79 s	4.45 s	-340.00 ms (-7.10%)
Peak resident memory	5.56 GB	5.77 GB	+216.49 MB (+3.80%)

This reverts commit 6f6ba88.

overlookmotel · 2026-07-20T18:12:52Z

Hi. I'm one of Oxc's core team.

I'd recommend using Visitor provided by oxc-parser over oxc-walker if you can. oxc-walker has some features that Visitor doesn't, but Visitor is much faster, so it's preferred if you can use it.

https://npmx.dev/package/oxc-parser#user-content-example

AugustinMauroy · 2026-07-20T18:48:04Z

thanks @overlookmotel for your input there. and any more info around loc ?

avivkeller · 2026-07-20T19:32:34Z

+  sourceText
 ) {
  if (!exports.identifiers.includes(node.id.name)) {
-    // Function isn't exported, not relevant to us


Why are all these comments removed?

like mister bean said "magics" I mean it's an error from my side while working on that

avivkeller · 2026-07-20T19:33:49Z

-import { jsx, toJs } from 'estree-util-to-js';
+import { print } from 'esrap';
+import tsx from 'esrap/languages/tsx';


Does estree-util-to-js not support oxc?

If we change that, it should be a separate discussion, IMO

yeah is it but esrap is much more smaller 183,9 ko and estree-util-to-js is 529,6 ko. and it's look little bit quicker (based on tests I didn't get why benchmark GH comment is updated)

avivkeller · 2026-07-20T19:34:00Z

+    const { code } = print(
+      content,
+      tsx({
+        // SUPER IMPORTANT: use double instead roldown will fail on certain unicode


yeah if you didn't set this option it's will break. for certain unicode

[PARSE_ERROR] Invalid Unicode escape sequence - in \0virtual:crypto.jsx at 44577..44578

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3319391. Configure here.}

avivkeller

We can't rely on oxc until they provide native bindings for all the platforms in Node.js's CI, or we don't build the docs on those platforms.

AugustinMauroy added 2 commits July 20, 2026 16:49

remove: acorn and use oxc-parser

3665509

Update package-lock.json

d385c36

AugustinMauroy requested a review from a team as a code owner July 20, 2026 14:56

vercel Bot deployed to Preview July 20, 2026 15:09 View deployment

cursor Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread src/generators/api-links/utils/extractExports.mjs

try to optimize

6f6ba88

AugustinMauroy force-pushed the remove-acorn branch from e309de1 to 6f6ba88 Compare July 20, 2026 15:17

vercel Bot deployed to Preview July 20, 2026 15:19 View deployment

cursor Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread src/generators/api-links/utils/extractExports.mjs

Comment thread src/generators/api-links/utils/extractExports.mjs Outdated

Revert "try to optimize"

6f20da7

This reverts commit 6f6ba88.

vercel Bot deployed to Preview July 20, 2026 15:21 View deployment

use oxc-walker

714cb0f

vercel Bot deployed to Preview July 20, 2026 15:40 View deployment

replace estree-util-to-js to esrap

aa1a145

vercel Bot had a problem deploying to Preview July 20, 2026 17:29 Failure

Update generate.mjs

2af8ed0

AugustinMauroy changed the title ~~remove: acorn and use oxc-parser~~ remove: better usage of oxc ecosystem Jul 20, 2026

vercel Bot deployed to Preview July 20, 2026 18:47 View deployment

remove usage of oxc-walker

37fafb8

vercel Bot deployed to Preview July 20, 2026 19:01 View deployment

avivkeller reviewed Jul 20, 2026

View reviewed changes

AugustinMauroy added 2 commits July 20, 2026 22:11

Update findDefinitions.mjs

f74f38a

Update dependabot.yml

70ce7bb

vercel Bot deployed to Preview July 20, 2026 20:13 View deployment

improve test coverage

3319391

vercel Bot deployed to Preview July 20, 2026 22:19 View deployment

cursor Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread src/generators/ast-js/generate.mjs

Update utils.test.mjs

9b7806f

vercel Bot deployed to Preview July 20, 2026 22:27 View deployment

avivkeller requested changes Jul 21, 2026

View reviewed changes

Uh oh!

Conversation

AugustinMauroy commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

cursor Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

api-links Generator

Output

Performance

legacy-html Generator

Performance

legacy-json Generator

Performance

llms-txt Generator

Performance

orama-db Generator

Performance

web Generator

Output size

Performance

Uh oh!

Uh oh!

Uh oh!

Uh oh!

overlookmotel commented Jul 20, 2026

Uh oh!

AugustinMauroy commented Jul 20, 2026

Uh oh!

avivkeller Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Jul 20, 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!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

AugustinMauroy commented Jul 20, 2026 •

edited

Loading

cursor Bot commented Jul 20, 2026 •

edited

Loading

vercel Bot commented Jul 20, 2026 •

edited

Loading

codecov Bot commented Jul 20, 2026 •

edited

Loading

github-actions Bot commented Jul 20, 2026 •

edited

Loading

`api-links` Generator

`legacy-html` Generator

`legacy-json` Generator

`llms-txt` Generator

`orama-db` Generator

`web` Generator

AugustinMauroy Jul 20, 2026 •

edited

Loading