feat(linter/plugins): handle BOMs

[overlookmotel]

Closes #12526.

Handle BOM on start of files in the same way that ESLint does - do not include it in the source text on JS side, but context.sourceCode.hasBOM evaluates to true.

Method:

• Alter program.source_text to trim off the BOM before passing AST to JS side.
• Add a has_bom flag to RawTransferMetadata.
• Add ability to add an offset in the conversion from UTF-8 to UTF-16 spans.

The result is that the file as it's seen on JS side is as if the BOM didn't exist (except for the hasBOM flag). Spans are converted accordingly in JS-side AST, and converted back when passing diagnostics back to Rust.

[overlookmotel]

• feat(linter/plugins): handle BOMs #18376 👈 (View in Graphite)
• feat(linter/plugins): support source text not being at start of buffer #18375
• main

---

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 hot fixes, skip the queue and merge this PR next

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]

CodSpeed Performance Report

Merging this PR will not alter performance

_{Comparing om/01-22-feat_linter_plugins_handle_boms (1ce13f5) with main (b95a89f)¹}

Summary

✅ 42 untouched benchmarks
⏩ 3 skipped benchmarks²

Footnotes

1. No successful run was found on om/01-21-feat_linter_plugins_support_source_text_not_being_at_start_of_buffer (26d0f46) during the generation of this report, so main (b95a89f) was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

2. 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. ↩

[overlookmotel]

Merge activity

• Jan 22, 2:16 AM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• Jan 22, 2:16 AM UTC: overlookmotel added this pull request to the Graphite merge queue.
• Jan 22, 2:23 AM UTC: Merged by the Graphite merge queue.

[Copilot]

Pull request overview

This PR teaches the raw-transfer pipeline and JS plugin system to correctly handle Unicode BOM at the start of files, matching ESLint semantics: JS-side source text excludes the BOM, context.sourceCode.hasBOM is accurate, and span conversions round-trip correctly between Rust and JS.

Changes:

• Extend RawTransferMetadata (parser and linter) and the raw-transfer generators to carry a has_bom flag and expose its byte offset to JS via new HAS_BOM_FLAG_POS constants.
• Enhance UTF-8→UTF-16 span conversion with an optional leading-byte offset (Utf8ToUtf16::new_with_offset / build_translations), and apply BOM trimming + offset-aware conversion in both the JS-plugin linter path and the parse_raw path.
• Add BOM-focused JS fixtures, a JS plugin to assert hasBOM, and updated conformance snapshots reflecting now-fully-passing unicode-bom and no-irregular-whitespace behavior.

Reviewed changes

Copilot reviewed 16 out of 21 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tasks/ast_tools/src/generators/raw_transfer.rs	Adds has_bom field discovery in raw metadata and generates HAS_BOM_FLAG_POS so JS can read the BOM flag from the transfer buffer.
oxfmtrc.jsonc	Excludes BOM fixture files from formatting to preserve literal BOM bytes in test fixtures.
napi/parser/src/raw_transfer_types.rs	Extends RawTransferMetadata with a has_bom: bool field (initialized to false in parser-only usage).
napi/parser/src/generated/assert_layouts.rs	Updates layout assertions for RawTransferMetadata including the new has_bom field and adjusted padding count.
napi/parser/src-js/generated/constants.js	Regenerates JS constants, adding HAS_BOM_FLAG_POS aligned with the new metadata layout.
crates/oxc_linter/src/lib.rs	Trims a leading BOM from program.source_text, uses Utf8ToUtf16::new_with_offset when BOM is present, and writes has_bom into RawTransferMetadata for JS plugins.
crates/oxc_linter/src/generated/assert_layouts.rs	Updates layout checks for RawTransferMetadata2 to include has_bom and correct padding size.
crates/oxc_ast_visit/src/utf8_to_utf16/translation.rs	Allows build_translations to start with a non-zero UTF-8/UTF-16 difference offset, enabling leading-byte exclusion (e.g., BOM).
crates/oxc_ast_visit/src/utf8_to_utf16/mod.rs	Adds Utf8ToUtf16::new_with_offset, wiring the new offset parameter into translation generation and documenting its BOM use case.
crates/oxc_ast_macros/src/generated/structs.rs	Updates PHF struct field order metadata for RawTransferMetadata/RawTransferMetadata2 to account for the new has_bom field.
apps/oxlint/test/fixtures/bom/plugin.ts	Introduces a JS plugin used in tests to assert context.sourceCode.hasBOM, source text, and spans with and without BOM.
apps/oxlint/test/fixtures/bom/output.snap.md	Adds snapshot output verifying correct BOM handling in messages, source text, and spans across BOM / non-BOM and unicode / non-unicode files.
apps/oxlint/test/fixtures/bom/files/no_bom_unicode.js	Test input: non-BOM JS file including Unicode characters to compare against BOM behavior.
apps/oxlint/test/fixtures/bom/files/no_bom.js	Test input: simple non-BOM JS file for baseline spans and hasBOM behavior.
apps/oxlint/test/fixtures/bom/files/bom_unicode.js	Test input: BOM-prefixed JS file with Unicode characters to validate combined BOM and multi-byte handling.
apps/oxlint/test/fixtures/bom/files/bom.js	Test input: basic BOM-prefixed JS file to validate BOM stripping and span conversion.
apps/oxlint/test/fixtures/bom/.oxlintrc.json	Local linter config enabling the BOM test plugin for the new BOM fixtures.
apps/oxlint/src/js_plugins/parse.rs	Mirrors the linter path: trims BOM, uses Utf8ToUtf16::new_with_offset, and propagates has_bom into RawTransferMetadata for raw parse buffers.
apps/oxlint/src-js/plugins/lint.ts	Reads has_bom via HAS_BOM_FLAG_POS and passes it into setupSourceForFile so context.sourceCode.hasBOM is accurate for JS plugins.
apps/oxlint/src-js/generated/constants.ts	Regenerates TS constants with HAS_BOM_FLAG_POS matching the Rust-side metadata layout.
apps/oxlint/conformance/snapshot.md	Updates conformance statistics, marking no-irregular-whitespace and unicode-bom as fully passing in light of the new BOM handling.

---

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