Dunqing
d4b4e61cf6
Oxc Transformer supports output down to ES2015, but the contributor guidance did not state that floor and the Rust API docs still listed `es5`. This made plugin-only transform combinations look like supported target configurations. Document the ES2015 floor and require target-dependent regressions to be reproducible through public target selection. Legacy runtime targets may still select available transforms, but do not imply complete compatibility with pre-ES2015 engines. Stacked on #26326. Verified with `cargo fmt --check`, `just doc`, and `cargo test -p oxc_transformer`. `just ready` completed formatting and workspace checks, but stopped in the test phase on the existing Node-version-only `stacktrace_is_correct` snapshot difference (`v25.8.1` locally versus `v26.5.0` recorded). AI assistance was used to investigate the documentation gap, edit the guidance, and run verification. I remain responsible for reviewing and understanding the changes before merge.
2.4 KiB
Coding agent guides for crates/oxc_transformer
Supported output target
Oxc Transformer lowers modern JavaScript to ES2015 (ES6) syntax. It does not
generate complete ES5 output, and es5 is rejected as a target.
A target for an older runtime may still enable the transforms Oxc implements, but the result is not guaranteed to run in a pre-ES2015 environment. Before treating target-dependent behavior as a regression, verify that public target selection can produce the transform combination. Conformance fixtures that enable plugins directly may create unsupported combinations.
Testing transformer behavior
Most transformer behavior regressions should be tested through transform conformance fixtures, not Rust integration tests in this crate.
Use:
tasks/transform_conformance/tests/<transform-name>/test/fixtures/<case-name>/
Each fixture normally contains:
input.js
output.js
Use input.ts, input.tsx, or input.jsx when the regression depends on TypeScript or JSX syntax. The transform options are usually inherited from the nearest options.json.
Run a focused fixture with:
cargo run -p oxc_transform_conformance -- --filter <transform-name>/test/fixtures/<case-name>
Run all transform conformance tests with:
cargo run -p oxc_transform_conformance
If the fixture has an exec.js runtime assertion, include --exec:
cargo run -p oxc_transform_conformance -- --filter <transform-name>/test/fixtures/<case-name> --exec
OXC-specific regressions
When the case is OXC-specific, put it under that transform's local oxc fixture group:
tasks/transform_conformance/tests/<transform-name>/test/fixtures/oxc/<case-name>/
For example, optional chaining regressions belong under:
tasks/transform_conformance/tests/babel-plugin-transform-optional-chaining/test/fixtures/oxc/<case-name>/
with:
input.js
output.js
or input.ts if the case depends on TypeScript syntax. The shared optional chaining options live in:
tasks/transform_conformance/tests/babel-plugin-transform-optional-chaining/test/fixtures/oxc/options.json
When to use crate integration tests
Use crates/oxc_transformer/tests/integrations/ for transformer API behavior, target selection, helper loading, or cross-cutting Rust harness coverage.
Do not add ordinary transform output regressions there when a tasks/transform_conformance fixture can cover the behavior.