feat(unist): simplify and optimize by AugustinMauroy · Pull Request #929 · nodejs/doc-kit

AugustinMauroy · 2026-07-20T21:18:03Z

Description

This PR removes unnecessary unist-util-find-after and unist-util-select dependencies by replacing their usage with existing unist-util-visit traversal logic.

The changes include:

Simplifying AST traversal and section extraction in metadata parsing.
Improving GitHub alert transformation handling and making it more defensive.
Refactoring HAST transformations to better support MDX JSX nodes and improve table handling.
Refactoring syntax highlighting utilities to make code block highlighting and CJS/MJS tabs handling clearer and more maintainable.
Improving type annotation parsing, normalization, and HAST generation.
Adding small AST utility improvements and additional type documentation.

The overall goal is to reduce dependencies, simplify tree processing, and make AST transformations more predictable.

Validation

Validated by:

Running the existing test suite with node --run test.
Running formatting and lint checks with node --run format and node --run lint.

Reviewers should verify:

Markdown metadata parsing still generates the same output, including section boundaries and YAML handling.
GitHub alerts continue to render correctly, including nested alerts.
Tables still receive responsive data-label attributes.
Syntax highlighted code blocks and CJS/MJS switchable examples render correctly.
Type annotations continue to parse, render, and link correctly.

Related Issues

No related issue

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 checked code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

Additional note

pr description as been generated by codex
some idea from codex
updated test as been generated by codex

cursor · 2026-07-20T21:18:08Z

PR Summary

Medium Risk
Touches core doc metadata section boundaries and multiple render pipelines (tables, footnotes, alerts, code blocks, type links); behavior should be equivalent but regressions would affect generated docs site-wide.

Overview
Bumps @node-core/doc-kit to 1.4.3 and removes unist-util-select and unist-util-find-after, replacing them with unist-util-visit and indexed heading walks.

Metadata parsing (parse.mjs) now collects definitions and root-only headings in one pass, then slices sections using stored child indexes instead of findAfter / selectAll.

JSX/HAST transformer visits all node types so Layout is found for MDX; tables get overflow-container wrappers and data-label on body cells by column index; footnotes are spliced from the document root into Layout. A unit test covers table behavior.

GitHub alerts plugin is more defensive (requires parent/index) with clearer marker stripping; behavior unchanged.

Legacy Shiki rehype plugin is refactored into highlightCodeBlock / createCodeTabs without changing the CJS/MJS tab pairing intent.

Type annotation utilities and tests swap selectAll for visit; HAST/mdast/syntax helpers are reorganized with shared normalization/finalize helpers.

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

vercel · 2026-07-20T21:18:09Z

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 9:30pm

codecov · 2026-07-20T21:19:02Z

Codecov Report

❌ Patch coverage is 82.42507% with 129 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.34%. Comparing base (ecbeaa6) to head (b10aa78).

Files with missing lines	Patch %	Lines
src/utils/highlighter.mjs	22.75%	112 Missing ⚠️
src/utils/unist.mjs	77.77%	9 Missing and 1 partial ⚠️
src/generators/jsx-ast/utils/plugins/alerts.mjs	92.98%	4 Missing ⚠️
...c/generators/jsx-ast/utils/plugins/transformer.mjs	97.93%	2 Missing ⚠️
...c/utils/type-annotations/__tests__/remark.test.mjs	95.45%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #929      +/-   ##
==========================================
+ Coverage   84.89%   85.34%   +0.44%     
==========================================
  Files         193      193              
  Lines       17512    17846     +334     
  Branches     1551     1566      +15     
==========================================
+ Hits        14867    15230     +363     
+ Misses       2639     2610      -29     
  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.

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 8d89b04. Configure here.}

github-actions · 2026-07-20T21:20:46Z

`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',
...
    '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',
...
    '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	1.36 s	-10.00 ms (-0.73%)
User CPU time	2.83 s	2.65 s	-180.00 ms (-6.36%)
System CPU time	320.00 ms	380.00 ms	+60.00 ms (+18.75%)
Peak resident memory	351.20 MB	356.81 MB	+5.61 MB (+1.60%)

`legacy-html` Generator

Output size

|-|-|-|-|

| buffer.html | 1.09 MB | 1.07 MB | -17.58 KB (-1.58%) |
| fs.html | 1.06 MB | 1.04 MB | -16.77 KB (-1.55%) |
| process.html | 702.32 KB | 688.78 KB | -13.54 KB (-1.93%) |
| crypto.html | 1.09 MB | 1.07 MB | -11.61 KB (-1.04%) |
| http2.html | 770.96 KB | 763.74 KB | -7.21 KB (-0.94%) |
| events.html | 555.98 KB | 549.65 KB | -6.33 KB (-1.14%) |
| stream_iter.html | 464.96 KB | 458.80 KB | -6.15 KB (-1.32%) |
| assert.html | 473.18 KB | 467.02 KB | -6.15 KB (-1.30%) |
| test.html | 928.08 KB | 922.10 KB | -5.98 KB (-0.64%) |
| vm.html | 430.83 KB | 425.73 KB | -5.10 KB (-1.18%) |
| child_process.html | 443.89 KB | 438.79 KB | -5.10 KB (-1.15%) |
| diagnostics_channel.html | 323.68 KB | 318.58 KB | -5.10 KB (-1.57%) |
| stream.html | 854.55 KB | 849.61 KB | -4.94 KB (-0.58%) |
| module.html | 344.89 KB | 340.38 KB | -4.51 KB (-1.31%) |
| worker_threads.html | 402.11 KB | 397.67 KB | -4.44 KB (-1.10%) |
| http.html | 639.60 KB | 636.25 KB | -3.34 KB (-0.52%) |
| quic.html | 424.09 KB | 420.91 KB | -3.18 KB (-0.75%) |
| webstreams.html | 285.51 KB | 282.51 KB | -2.99 KB (-1.05%) |
| v8.html | 338.17 KB | 335.18 KB | -2.99 KB (-0.88%) |
| perf_hooks.html | 360.52 KB | 357.89 KB | -2.64 KB (-0.73%) |
| util.html | 742.60 KB | 740.02 KB | -2.58 KB (-0.35%) |
| async_hooks.html | 224.27 KB | 221.81 KB | -2.46 KB (-1.10%) |
| repl.html | 217.31 KB | 215.03 KB | -2.29 KB (-1.05%) |
| readline.html | 210.90 KB | 208.97 KB | -1.94 KB (-0.92%) |
| async_context.html | 238.19 KB | 236.26 KB | -1.93 KB (-0.81%) |
| zlib.html | 325.42 KB | 323.49 KB | -1.93 KB (-0.59%) |
| ffi.html | 91.43 KB | 89.66 KB | -1.77 KB (-1.93%) |
| sqlite.html | 231.71 KB | 229.95 KB | -1.76 KB (-0.76%) |
| url.html | 331.77 KB | 330.02 KB | -1.76 KB (-0.53%) |
| tls.html | 278.37 KB | 276.96 KB | -1.41 KB (-0.51%) |
| cluster.html | 200.71 KB | 199.31 KB | -1.41 KB (-0.70%) |
| dns.html | 225.69 KB | 224.28 KB | -1.41 KB (-0.62%) |
| vfs.html | 55.59 KB | 54.35 KB | -1.24 KB (-2.22%) |
| https.html | 158.72 KB | 157.49 KB | -1.23 KB (-0.78%) |
| timers.html | 92.44 KB | 91.21 KB | -1.23 KB (-1.33%) |
| net.html | 251.83 KB | 250.77 KB | -1.06 KB (-0.42%) |
| dgram.html | 171.89 KB | 170.83 KB | -1.05 KB (-0.61%) |
| deprecations.html | 288.42 KB | 287.54 KB | -905.00 B (-0.31%) |
| inspector.html | 119.04 KB | 118.16 KB | -903.00 B (-0.74%) |
| modules.html | 157.71 KB | 156.83 KB | -903.00 B (-0.56%) |
| tracing.html | 90.98 KB | 90.10 KB | -900.00 B (-0.97%) |
| packages.html | 152.89 KB | 152.19 KB | -724.00 B (-0.46%) |
| globals.html | 130.85 KB | 130.32 KB | -542.00 B (-0.40%) |
| cli.html | 323.05 KB | 322.52 KB | -541.00 B (-0.16%) |
| string_decoder.html | 41.20 KB | 40.67 KB | -540.00 B (-1.28%) |
| errors.html | 396.07 KB | 395.72 KB | -362.00 B (-0.09%) |
| console.html | 99.20 KB | 98.85 KB | -360.00 B (-0.35%) |
| dtls.html | 87.95 KB | 87.66 KB | -292.00 B (-0.32%) |
| addons.html | 354.98 KB | 354.80 KB | -181.00 B (-0.05%) |
| esm.html | 133.75 KB | 133.57 KB | -181.00 B (-0.13%) |
| single-executable-applications.html | 94.87 KB | 94.70 KB | -181.00 B (-0.19%) |
| webcrypto.html | 360.80 KB | 360.62 KB | -181.00 B (-0.05%) |
| os.html | 89.16 KB | 88.99 KB | -180.00 B (-0.20%) |
| path.html | 99.47 KB | 99.30 KB | -180.00 B (-0.18%) |
| wasi.html | 46.40 KB | 46.22 KB | -180.00 B (-0.38%) |

Performance

Metric	Base	Head	Diff
Elapsed time	20.14 s	19.41 s	-730.00 ms (-3.62%)
User CPU time	62.86 s	65.24 s	+2.38 s (+3.79%)
System CPU time	2.64 s	2.48 s	-160.00 ms (-6.06%)
Peak resident memory	2.17 GB	2.23 GB	+66.08 MB (+2.98%)

`legacy-json` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	9.46 s	8.58 s	-880.00 ms (-9.30%)
User CPU time	27.76 s	26.93 s	-830.00 ms (-2.99%)
System CPU time	1.87 s	1.90 s	+30.00 ms (+1.60%)
Peak resident memory	1.58 GB	1.64 GB	+63.01 MB (+3.89%)

`llms-txt` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	6.87 s	8.40 s	+1.53 s (+22.27%)
User CPU time	19.03 s	23.01 s	+3.98 s (+20.91%)
System CPU time	1.53 s	1.94 s	+410.00 ms (+26.80%)
Peak resident memory	1.71 GB	1.64 GB	-66.90 MB (-3.83%)

`orama-db` Generator

Output size

|-|-|-|-|

| orama-db.json | 8.90 MB | 8.90 MB | +1.00 B (+0.00%) |

Performance

Metric	Base	Head	Diff
Elapsed time	6.63 s	8.35 s	+1.72 s (+25.94%)
User CPU time	19.23 s	25.31 s	+6.08 s (+31.62%)
System CPU time	1.66 s	1.85 s	+190.00 ms (+11.45%)
Peak resident memory	1.82 GB	1.67 GB	-159.46 MB (-8.55%)

`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	76.33 s	-2.74 s (-3.47%)
User CPU time	166.52 s	161.78 s	-4.74 s (-2.85%)
System CPU time	4.79 s	4.83 s	+40.00 ms (+0.84%)
Peak resident memory	5.56 GB	6.30 GB	+755.92 MB (+13.27%)

feat(unist): simplify and optimize

8d89b04

AugustinMauroy requested a review from a team as a code owner July 20, 2026 21:18

cursor Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread src/generators/jsx-ast/utils/plugins/transformer.mjs Outdated

fix: cursor suggestion

b10aa78

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(unist): simplify and optimize#929

feat(unist): simplify and optimize#929
AugustinMauroy wants to merge 2 commits into
mainfrom
optimise-unist-workflow

AugustinMauroy commented Jul 20, 2026

Uh oh!

cursor Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

AugustinMauroy commented Jul 20, 2026

Description

Validation

Related Issues

Check List

Additional note

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!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

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

Output size

Performance

legacy-json Generator

Performance

llms-txt Generator

Performance

orama-db Generator

Output size

Performance

web Generator

Output size

Performance

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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