vp migrate: Recognize asynchronous assertions awaited through local variables #3131

Description

When running vp migrate, the Vitest v5 migration analyzer reports an unawaited-assertion review item for asynchronous assertions assigned to a local variable, even when that variable is explicitly awaited later in the same test.

This can occur in tests that intentionally inspect the return type of an asynchronous assertion before awaiting it:

import { expect, expectTypeOf, it } from 'vite-plus/test';

it('checks an asynchronous matcher return type', async () => {
  const assertion = expect(Promise.resolve(1)).resolves.toBe(1);

  expectTypeOf(assertion).toEqualTypeOf<Promise<void>>();
  await assertion;
});

The assertion is properly awaited, and the test passes under Vitest v5. However, vp migrate continues to report:

REVIEW [unawaited-assertion] Check that the result of this asynchronous assertion is awaited or returned.

I understand that the migration analyzer intentionally uses conservative static analysis and that REVIEW findings are not necessarily errors. However, this is a straightforward case where the assertion is demonstrably awaited.

Because the warning persists across subsequent migration runs, it adds unnecessary review noise for code that has already been inspected and verified.

It would be useful for the migration analyzer to recognize this pattern or provide a way to acknowledge intentionally retained code without repeatedly reporting the same finding.

Suggested solution

Extend the Vitest v5 migration analyzer to recognize simple cases where an asynchronous assertion's returned promise is assigned to a local const and subsequently awaited or returned within the same function.

For example, the following should not produce an unawaited-assertion review item:

const assertion = expect(Promise.resolve(1)).resolves.toBe(1);
expectTypeOf(assertion).toEqualTypeOf<Promise<void>>();
await assertion;

The analysis could remain intentionally conservative for more complex control flow, reassigned variables, or cases where the promise may not be awaited on every execution path.

This would preserve the existing safety checks while avoiding recurring findings for a common and easily verifiable pattern.

Alternative

An alternative would be to provide a documented mechanism for acknowledging or suppressing specific migration review findings.

For example, a narrowly scoped inline directive or configuration option could allow developers to mark an unawaited-assertion finding as reviewed without disabling the entire Vitest migration analysis.

This could also benefit other migration checks that intentionally report ambiguous cases requiring manual verification.

I would prefer improved recognition of straightforward awaited bindings, but an acknowledgment mechanism would be useful when more complex code cannot be analyzed safely.

Additional context

This was encountered while upgrading a TypeScript application using Vite+ and Vitest v5.

The original test verifies the return types of synchronous and asynchronous DOM matchers. The promise is intentionally retained in a variable so its type can be checked before awaiting it.

Relevant migration analyzer implementation:

https://github.com/voidzero-dev/vite-plus/blob/main/packages/cli/src/migration/vitest-v5/source.ts

The current analyzer appears to determine whether an asynchronous assertion is awaited or returned primarily by examining its immediate AST parent. An assertion assigned to a local variable therefore produces a review item even when the variable is awaited later.

The finding is reported as REVIEW, not BLOCK, and does not prevent migration or successful test execution.

Observed output:

$ vp migrate
VITE+ - The Unified Toolchain for the Web

▲ Vitest v5: 1 review item

  src/testing/matchers.test.ts
    7:21 REVIEW [unawaited-assertion] Check that the result of this asynchronous assertion is awaited or returned.
      Docs: https://vitest.dev/guide/migration/#unawaited-asynchronous-assertions-fail-the-test

The warning persists when rerunning vp migrate after upgrading dependencies and verifying that the tests pass.

This request concerns the usability and precision of Vite+'s migration diagnostics, not a Vitest runtime or assertion failure.

Validations

• Read the Contributing Guidelines.
• Confirm this request is for Vite+ itself and not for Vite, Vitest, tsdown, Rolldown, or Oxc.
• Check that there isn't already an issue requesting the same feature.