import type { Payload } from "payload";

/**
 * @deprecated DO NOT USE — hoisting incompatible.
 *
 * Vitest statically hoists `vi.mock()` calls to the top of the file.
 * This helper wraps `vi.mock()` inside a regular function body, so the
 * hoist never fires — the mock is installed too late and the real
 * `payload` module loads before being intercepted.
 *
 * Instead, write at the TOP LEVEL of your test file:
 *
 *     vi.mock("payload", () => ({ getPayload: vi.fn() }));
 *
 *     // then in your test:
 *     const { getPayload } = await import("payload");
 *     (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue(yourStub);
 *
 * This export is preserved only so existing imports don't break and
 * agents searching for it find this warning.
 */
export function mockPayloadModule(impl: Partial<Payload>): void {
  void impl;
  throw new Error(
    "mockPayloadModule is deprecated and broken; see JSDoc. Call vi.mock('payload', ...) at the top of your test file instead.",
  );
}