fix(parser): use specific for-await diagnostic (#24856)

## Summary

- add a dedicated diagnostic for invalid `for await` loops
- report “`for await` loops are only allowed…” instead of the generic `await` expression message
- update Babel and TypeScript parser conformance snapshots

## Impact

Users now receive an error that identifies the invalid loop construct directly while retaining the existing guidance to remove `await` or mark the enclosing function `async`.

crates/oxc_parser/src/diagnostics.rs

@@ -360,6 +360,14 @@ parser_diagnostics! {
         .with_help("Either remove this `await` or add the `async` keyword to the enclosing function")
     };
 
+    for_await_statement(span: Span) => {
+        OxcDiagnostic::error(
+            "`for await` loops are only allowed within async functions and at the top levels of modules",
+        )
+        .with_label(span)
+        .with_help("Either remove this `await` or add the `async` keyword to the enclosing function")
+    };
+
     yield_expression(span: Span) => {
         OxcDiagnostic::error("A 'yield' expression is only allowed in a generator body.")
             .with_label(span)

crates/oxc_parser/src/js/statement.rs

@@ -355,7 +355,7 @@ impl<'a, C: Config> ParserImpl<'a, C> {
         // [+Await]
         let r#await = if self.at(Kind::Await) {
             if !self.ctx.has_await() {
-                let error = diagnostics::await_expression(self.cur_token().span());
+                let error = diagnostics::for_await_statement(self.cur_token().span());
                 if self.ctx.has_top_level() {
                     // For `ModuleKind::Unambiguous`, defer the error until we know whether
                     // this is a Module (where for-await is valid at top-level) or Script.

tasks/coverage/snapshots/parser_babel.snap

@@ -764,7 +764,7 @@ Expect to Parse: tasks/coverage/babel/packages/babel-parser/test/fixtures/typesc
    ╰────
   help: Remove parameters except the first one here
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
    ╭─[babel/packages/babel-parser/test/fixtures/core/opts/allowAwaitOutsideFunction-false/input.js:1:5]
  1 │ for await (const i of imports) {}
    ·     ─────
@@ -5586,7 +5586,7 @@ Expect to Parse: tasks/coverage/babel/packages/babel-parser/test/fixtures/typesc
    ╰────
   help: Remove the trailing comma here
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
    ╭─[babel/packages/babel-parser/test/fixtures/es2018/async-generators/for-await-async-context/input.js:2:7]
  1 │ function f() {
  2 │   for await (let x of y);
@@ -8551,7 +8551,7 @@ Expect to Parse: tasks/coverage/babel/packages/babel-parser/test/fixtures/typesc
    ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
    ╭─[babel/packages/babel-parser/test/fixtures/es2022/top-level-await-script/for-await/input.js:1:5]
  1 │ for await (const a of b);
    ·     ─────

tasks/coverage/snapshots/parser_typescript.snap

@@ -3117,7 +3117,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
     ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
    ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:4:7]
  3 │ function normalFunc(p: Promise<number>) {
  4 │   for await (const _ of []);
@@ -3135,7 +3135,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
    ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
     ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:9:7]
   8 │ export function exportedFunc(p: Promise<number>) {
   9 │   for await (const _ of []);
@@ -3153,7 +3153,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
     ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
     ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:14:7]
  13 │ const functionExpression = function(p: Promise<number>) {
  14 │   for await (const _ of []);
@@ -3171,7 +3171,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
     ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
     ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:19:7]
  18 │ const arrowFunc = (p: Promise<number>) => {
  19 │   for await (const _ of []);
@@ -3189,7 +3189,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
     ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
     ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:24:7]
  23 │ function* generatorFunc(p: Promise<number>) {
  24 │   for await (const _ of []);
@@ -3207,7 +3207,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
     ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
     ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:30:9]
  29 │   constructor(p: Promise<number>) {
  30 │     for await (const _ of []);
@@ -3225,7 +3225,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
     ╰────
   help: Either remove this `await` or add the `async` keyword to the enclosing function
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
     ╭─[typescript/tests/cases/compiler/awaitInNonAsyncFunction.ts:34:7]
  33 │   method(p: Promise<number>) {
  34 │   for await (const _ of []);
@@ -24843,7 +24843,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
  4 │     }
    ╰────
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
    ╭─[typescript/tests/cases/conformance/parser/ecmascript2018/forAwait/parser.forAwait.es2018.ts:1:5]
  1 │ for await (const x of y) {
    ·     ─────
@@ -28719,7 +28719,7 @@ Expect Syntax Error: tasks/coverage/typescript/tests/cases/conformance/types/wit
  6 │ 
    ╰────
 
-  × `await` is only allowed within async functions and at the top levels of modules
+  × `for await` loops are only allowed within async functions and at the top levels of modules
    ╭─[typescript/tests/cases/conformance/statements/VariableStatements/usingDeclarations/awaitUsingDeclarationsInForAwaitOf.3.ts:5:5]
  4 │ 
  5 │ for await (await using of x);