perf(linter/plugins): deserialize comments without AST by overlookmotel · Pull Request #20364 · oxc-project/oxc

overlookmotel · 2026-03-14T01:36:34Z

Previously the entire AST had to be deserialized when calling any comments method. This was purely to get the hashbang property of Program, which has to be added to start of comments array as a Shebang comment.

Usually the AST has to be deserialized anyway in order to visit it, but some rules might early exit and return an empty visitor after checking if a certain comment is present. In those cases, it was extremely wasteful to deserialize the whole AST just to check for hashbang.

Instead, add a Line comment to start of Vec<Comment> on Rust side if a hashbang is present. If there are a lot of comments, this involves shifting them all up which could be expensive, but files with hashbangs are rare, and this change enables other optimizations coming in future PRs that rely on all comments being present in the buffer.

overlookmotel · 2026-03-14T01:36:46Z

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

0-merge - adds this PR to the back of the merge queue
hotfix - for urgent changes, fast-track this PR to the front of the merge queue

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

codspeed-hq · 2026-03-14T01:43:47Z

Merging this PR will not alter performance

✅ 53 untouched benchmarks
⏩ 3 skipped benchmarks¹

_{Comparing om/03-14-perf_linter_plugins_deserialize_comments_without_ast (bf4968e) with main (6eb5b01)²}

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
No successful run was found on om/03-13-refactor_linter_plugins_move_comments_methods_into_own_file (70b2361) during the generation of this report, so main (6eb5b01) was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

Copilot

Pull request overview

This PR optimizes comment deserialization by removing the dependency on the full AST for accessing the hashbang. Instead, the Rust side now inserts the hashbang as a Line comment at position 0 in the comments vector, and the JS side detects and re-labels it as a Shebang comment by checking if the first comment starts at offset 0 and the source begins with #!.

Changes:

Rust: Insert hashbang as a Line comment at the start of the comments Vec in both the linter and NAPI parser paths
JS: Remove AST dependency from initComments(), detect shebang by inspecting the first comment instead
Add oxc_ast dependency to apps/oxlint crate

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
crates/oxc_linter/src/lib.rs	Insert hashbang as Line comment at index 0 in both single-alloc and dual-alloc paths
apps/oxlint/src/js_plugins/parse.rs	Insert hashbang as Line comment at index 0 in NAPI parse path
apps/oxlint/src-js/plugins/comments.ts	Remove AST dependency; detect shebang from first comment + source text
apps/oxlint/Cargo.toml	Add `oxc_ast` workspace dependency
Cargo.lock	Lock file update

overlookmotel · 2026-03-14T12:11:47Z

Rust: Insert hashbang as a Line comment at the start of the comments Vec in both the linter and NAPI parser paths

Just for the record, this is incorrect. This change only affects Oxlint.

graphite-app · 2026-03-14T12:15:39Z

Merge activity

Mar 14, 12:15 PM UTC: overlookmotel added this pull request to the Graphite merge queue.
Mar 14, 12:32 PM UTC: Merged by the Graphite merge queue.

Previously the entire AST had to be deserialized when calling any comments method. This was purely to get the `hashbang` property of `Program`, which has to be added to start of comments array as a `Shebang` comment. Usually the AST has to be deserialized anyway in order to visit it, but some rules might early exit and return an empty visitor after checking if a certain comment is present. In those cases, it was extremely wasteful to deserialize the whole AST just to check for `hashbang`. Instead, add a `Line` comment to start of `Vec<Comment>` on Rust side if a hashbang is present. If there are a lot of comments, this involves shifting them all up which could be expensive, but files with hashbangs are rare, and this change enables other optimizations coming in future PRs that rely on all comments being present in the buffer.

#20364 removed the reliance internally on `hashbang` property being present on `Program`. Now we can remove this field. It's not part of ESTree standard. We include it in `oxc-parser` as a non-standard extension as it can be useful, but in the case of Oxlint, rules written with the alternative `createOnce` API are meant to also be compatible with ESLint, so we can't provided APIs which ESLint doesn't support.

Previously the entire AST had to be deserialized when calling any comments method. This was purely to get the `hashbang` property of `Program`, which has to be added to start of comments array as a `Shebang` comment. Usually the AST has to be deserialized anyway in order to visit it, but some rules might early exit and return an empty visitor after checking if a certain comment is present. In those cases, it was extremely wasteful to deserialize the whole AST just to check for `hashbang`. Instead, add a `Line` comment to start of `Vec<Comment>` on Rust side if a hashbang is present. If there are a lot of comments, this involves shifting them all up which could be expensive, but files with hashbangs are rare, and this change enables other optimizations coming in future PRs that rely on all comments being present in the buffer.

#20364 removed the reliance internally on `hashbang` property being present on `Program`. Now we can remove this field. It's not part of ESTree standard. We include it in `oxc-parser` as a non-standard extension as it can be useful, but in the case of Oxlint, rules written with the alternative `createOnce` API are meant to also be compatible with ESLint, so we can't provided APIs which ESLint doesn't support.

# Oxlint ### 🚀 Features - c95951f linter/plugins: Implement `sourceCode.markVariableAsUsed` (#20357) (overlookmotel) - 7a2a7d0 linter: Implement `n/handle-callback-err` rule (#19616) (Mikhail Baev) ### 🐛 Bug Fixes - f8fbd6e linter/plugins: Remove `hashbang` property from AST (#20365) (overlookmotel) - 6eb5b01 linter/prefer-await-to-then: Ignore Promise static methods (#20347) (camc314) - a4b61f7 linter: Remove `defineConfig` check (#20308) (camc314) - 3ad7f53 linter/explicit-module-boundary-types: False positive with satisfies expr (#20309) (camc314) - f547401 linter/no-unused-private-class-members: Treat switch discriminants as read (#20307) (camc314) - 1c07b3b diagnostics: Handle `WouldBlock` in stdout writes to prevent panic (#20295) (Boshen) ### ⚡ Performance - e4f7248 linter: Remove unnecessary clone of owned String in drain loop (#20388) (Boshen) - 4a67f1d linter: Eliminate Vec allocation in disable directive matching (#20387) (Boshen) - 618a598 linter/plugins: Add fast path for files with no comments (#20366) (overlookmotel) - b0125c5 linter/plugins: Deserialize comments without AST (#20364) (overlookmotel) - 9cd612f linter/plugins: Recycle comment objects (#20362) (overlookmotel) - bf442f8 linter/plugins: Cheaper `Token` creation (#20360) (overlookmotel) - 5474d0a semantic: V8-style walk-up reference resolution (#20292) (Boshen) - 7946eba linter/plugins: Avoid arguments spread and temp array when merging (#20318) (overlookmotel) - fc7cf8a linter/plugins: Pre-define less CFG merger functions (#20317) (overlookmotel) - 3b9eb28 linter/plugins: Streamline getting/creating visit fn mergers (#20319) (overlookmotel) - f04e850 linter/plugins: Inline binary search functions into call sites (#20312) (overlookmotel) - fe24afe linter/plugins: Apply replace globals TSDown plugin to JS files (#20305) (overlookmotel) - 77cdacc linter/plugins: Use array buffer views for tokens (#20301) (overlookmotel) - 910c941 linter/plugins: Reorder branches in `getTokenByRangeStart` (#20296) (overlookmotel) - af7674c linter/tokens: Avoid extra token value allocation (#20013) (camc314) ### 📚 Documentation - 24490b5 linter: Improve formatting for 80ish rules' docs. (#20411) (connorshea) - 3383523 linter: Improve `--tsconfig` flag docs (#20342) (camc314) # Oxfmt ### 🚀 Features - d22c443 oxfmt: Export `OxfmtConfig` type (#20275) (leaysgur) - a11ecff oxfmt/lsp: Respect `angular` language id as `.component.html` file (#20242) (Sysix) ### 🐛 Bug Fixes - ce65099 formatter: Preserve parentheses around as expression before private field access (#20419) (bab) - f908742 oxfmt: Revert #20326 partially (#20413) (leaysgur) - 4ef93ea formatter: Honor trailing ignore comments after list separators (#19925) (Andreas Lubbe) - 68fb0d0 oxfmt: Skip vite.config.ts which fails to import (#20326) (leaysgur) - 88ee826 oxfmt: Handle literalline for script-in-vue (#20130) (leaysgur) - 1c07b3b diagnostics: Handle `WouldBlock` in stdout writes to prevent panic (#20295) (Boshen) Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

This was referenced Mar 14, 2026

refactor(ast_tools): remove COMMENTS variant modifier from raw transfer codegen #20361

Merged

perf(linter/plugins): recycle comment objects #20362

Merged

This was referenced Mar 14, 2026

refactor(linter/plugins): move comments methods into own file #20363

Merged

fix(linter/plugins): remove hashbang property from AST #20365

Merged

github-actions bot added A-linter Area - Linter A-cli Area - CLI A-linter-plugins Area - Linter JS plugins C-performance Category - Solution not expected to change functional behavior, only performance labels Mar 14, 2026

overlookmotel mentioned this pull request Mar 14, 2026

perf(linter/plugins): add fast path for files with no comments #20366

Merged

overlookmotel marked this pull request as ready for review March 14, 2026 01:46

overlookmotel requested a review from camc314 as a code owner March 14, 2026 01:46

Copilot AI review requested due to automatic review settings March 14, 2026 01:46

Copilot started reviewing on behalf of overlookmotel March 14, 2026 01:46 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

overlookmotel self-assigned this Mar 14, 2026

graphite-app bot added the 0-merge Merge with Graphite Merge Queue label Mar 14, 2026

graphite-app bot force-pushed the om/03-13-refactor_linter_plugins_move_comments_methods_into_own_file branch from 70b2361 to 159c3e2 Compare March 14, 2026 12:17

graphite-app bot force-pushed the om/03-14-perf_linter_plugins_deserialize_comments_without_ast branch from bf4968e to d2cd98d Compare March 14, 2026 12:17

graphite-app bot force-pushed the om/03-13-refactor_linter_plugins_move_comments_methods_into_own_file branch from 159c3e2 to ef41ffa Compare March 14, 2026 12:20

graphite-app bot force-pushed the om/03-14-perf_linter_plugins_deserialize_comments_without_ast branch from d2cd98d to b0125c5 Compare March 14, 2026 12:21

graphite-app bot removed the 0-merge Merge with Graphite Merge Queue label Mar 14, 2026

Base automatically changed from om/03-13-refactor_linter_plugins_move_comments_methods_into_own_file to main March 14, 2026 12:32

graphite-app bot merged commit b0125c5 into main Mar 14, 2026
23 checks passed

graphite-app bot deleted the om/03-14-perf_linter_plugins_deserialize_comments_without_ast branch March 14, 2026 12:33

Boshen mentioned this pull request Mar 16, 2026

release(apps): oxlint v1.56.0 && oxfmt v0.41.0 #20423

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

perf(linter/plugins): deserialize comments without AST#20364

perf(linter/plugins): deserialize comments without AST#20364
graphite-app[bot] merged 1 commit intomainfrom
om/03-14-perf_linter_plugins_deserialize_comments_without_ast

overlookmotel commented Mar 14, 2026 •

edited

Loading

Uh oh!

overlookmotel commented Mar 14, 2026 •

edited

Loading

Uh oh!

codspeed-hq bot commented Mar 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

overlookmotel commented Mar 14, 2026

Uh oh!

graphite-app bot commented Mar 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

codspeed-hq bot commented Mar 14, 2026

Merging this PR will not alter performance

Footnotes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

overlookmotel commented Mar 14, 2026

Uh oh!

graphite-app bot commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

overlookmotel commented Mar 14, 2026 •

edited

Loading

overlookmotel commented Mar 14, 2026 •

edited

Loading

graphite-app bot commented Mar 14, 2026 •

edited

Loading