notes/oxc-transform/diagnostics.md
transformSync() and transform() return structured diagnostics alongside code instead of throwing transform failures (result, sync/async paths). Parser recovery can yield code with severity Error; transform warnings can yield runnable code, while semantic or transform errors can stop code generation (pipeline).
Diagnostics expose severity, message, labels, help, and a rendered codeframe; label offsets are UTF-8 byte offsets copied from Oxc spans (public shape, conversion). Invalid NAPI option values can throw before a transform result exists (NAPI conversion).
Script/CommonJS parsing reports import.meta before later define replacement (parser, diagnostic); emitted code can therefore contain the replacement alongside a stale severity Error.