@vitest/mocker 4.1.10: hoistMocks

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @vitest/mocker.hoistMocks in pkg:npm/%40vitest/mocker@4.1.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/mocker@4.1.10
Demonstrate these symbols/APIs:
  - @vitest/mocker.hoistMocks
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ac4c566268b56c619cd2b4819df2562cf1de96ef5449ee550546aa1e9fe67ed0","constraints":{"executionContext":"node"},"contract":["returns undefined when code contains no hoistable mock statements","hoists vi.mock call and converts static import to dynamic import","hoists vi.hoisted variable declaration above static module imports","supports custom utilsObjectNames and hoistedModule options"],"goal":"verify @vitest/mocker.hoistMocks in pkg:npm/%40vitest/mocker@4.1.10","kind":"HOW","packages":["pkg:npm/%40vitest/mocker@4.1.10"],"schemaVersion":1,"symbols":["@vitest/mocker.hoistMocks"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40vitest/mocker@4.1.10"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/mocker@4.1.10","symbols":["@vitest/mocker.hoistMocks"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-mocker-hoist-mocks",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-mocker-hoist-mocks",
      "version": "1.0.0",
      "dependencies": {
        "@vitest/mocker": "4.1.10"
      }
    },
    "node_modules/@jridgewell/sourcemap-codec": {
      "version": "1.6.0",
      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
      "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
      "license": "MIT"
    },
    "node_modules/@types/estree": {
      "version": "1.0.9",
      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
      "license": "MIT"
    },
    "node_modules/@vitest/mocker": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.10.tgz",
      "integrity": "sha512-v0xaezt+DKEmKfaxg133ldzADrwLGd7Ze1MfQQTYfvs8OqZIwbxyxaYURivwV7sWy5fqn3rH5uOrSp07bp44Ow==",
      "license": "MIT",
      "dependencies": {
        "@vitest/spy": "4.1.10",
        "estree-walker": "^3.0.3",
        "magic-string": "^0.30.21"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      },
      "peerDependencies": {
        "msw": "^2.4.9",
        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
      },
      "peerDependenciesMeta": {
        "msw": {
          "optional": true
        },
        "vite": {
          "optional": true
        }
      }
    },
    "node_modules/@vitest/spy": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.10.tgz",
      "integrity": "sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw==",
      "license": "MIT",
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/estree-walker": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
      "license": "MIT",
      "dependencies": {
        "@types/estree": "^1.0.0"
      }
    },
    "node_modules/magic-string": {
      "version": "0.30.21",
      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
      "license": "MIT",
      "dependencies": {
        "@jridgewell/sourcemap-codec": "^1.5.5"
      }
    }
  }
}

{
  "name": "sample-mocker-hoist-mocks",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@vitest/mocker": "4.1.10"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @vitest/mocker.hoistMocks in pkg:npm/%40vitest/mocker@4.1.10",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40vitest/mocker@4.1.10"
  ],
  "symbols": [
    "@vitest/mocker.hoistMocks"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import { hoistMocks } from '@vitest/mocker/transforms';
import assert from 'node:assert';

// Contract 1: returns undefined when code contains no hoistable mock statements
{
  const code = `const greeting = "hello world";\nconsole.log(greeting);`;
  const result = hoistMocks(code, 'clean.js', () => ({ type: 'Program', body: [] }));
  assert.strictEqual(result, undefined, 'Must return undefined when no mock method calls are present');
}

// Contract 2: hoists vi.mock call and converts static import to dynamic import
{
  const code = `\nimport { calculate } from './calc.js';\nvi.mock('./calc.js', () => ({ calculate: () => 100 }));\nconsole.log(calculate());`;
  const importStart = code.indexOf("import { calculate }");
  const importEnd = code.indexOf("from './calc.js';") + "from './calc.js';".length;
  const mockStart = code.indexOf("vi.mock(");
  const mockEnd = code.indexOf("100 }));") + "100 }));".length;

  const ast = {
    type: 'Program',
    start: 0,
    end: code.length,
    body: [
      {
        type: 'ImportDeclaration',
        start: importStart,
        end: importEnd,
        specifiers: [
          {
            type: 'ImportSpecifier',
            imported: { type: 'Identifier', name: 'calculate' },
            local: { type: 'Identifier', name: 'calculate' }
          }
        ],
        source: {
          type: 'Literal',
          value: './calc.js',
          start: code.indexOf("'./calc.js'"),
          end: code.indexOf("'./calc.js'") + "'./calc.js'".length
        }
      },
      {
        type: 'ExpressionStatement',
        start: mockStart,
        end: mockEnd,
        expression: {
          type: 'CallExpression',
          start: mockStart,
          end: mockEnd,
          callee: {
            type: 'MemberExpression',
            object: { type: 'Identifier', name: 'vi' },
            property: { type: 'Identifier', name: 'mock' }
          },
          arguments: [
            {
              type: 'Literal',
              value: './calc.js',
              start: code.lastIndexOf("'./calc.js'"),
              end: code.lastIndexOf("'./calc.js'") + "'./calc.js'".length
            }
          ]
        }
      }
    ]
  };

  const result = hoistMocks(code, 'math.test.js', () => ast);
  assert(result !== undefined, 'Result must be a MagicString instance');
  const transformed = result.toString();
  assert(transformed.includes('import { vi } from "vitest"'), 'Must prepend vitest import for vi helper');
  assert(transformed.includes("vi.mock('./calc.js'"), 'Must retain vi.mock definition');
  assert(transformed.includes('const __vi_import_0__ = await import("./calc.js");'), 'Must transform static import into dynamic import');
}

// Contract 3: hoists vi.hoisted variable declaration above static module imports
{
  const code = `\nimport { getUser } from './user.js';\nconst mockUser = vi.hoisted(() => ({ id: 1 }));\nvi.mock('./user.js', () => ({ getUser: () => mockUser }));`;
  const importStart = code.indexOf("import { getUser }");
  const importEnd = code.indexOf("from './user.js';") + "from './user.js';".length;
  const hoistedStart = code.indexOf("const mockUser");
  const hoistedEnd = code.indexOf("({ id: 1 }));") + "({ id: 1 }));".length;
  const hoistedCallStart = code.indexOf("vi.hoisted");
  const hoistedCallEnd = hoistedEnd - 1;
  const mockStart = code.indexOf("vi.mock(");
  const mockEnd = code.indexOf("mockUser }));") + "mockUser }));".length;

  const ast = {
    type: 'Program',
    start: 0,
    end: code.length,
    body: [
      {
        type: 'ImportDeclaration',
        start: importStart,
        end: importEnd,
        specifiers: [
          {
            type: 'ImportSpecifier',
            imported: { type: 'Identifier', name: 'getUser' },
            local: { type: 'Identifier', name: 'getUser' }
          }
        ],
        source: {
          type: 'Literal',
          value: './user.js'
        }
      },
      {
        type: 'VariableDeclaration',
        kind: 'const',
        start: hoistedStart,
        end: hoistedEnd,
        declarations: [
          {
            type: 'VariableDeclarator',
            start: hoistedStart + 6,
            end: hoistedEnd,
            id: { type: 'Identifier', name: 'mockUser' },
            init: {
              type: 'CallExpression',
              start: hoistedCallStart,
              end: hoistedCallEnd,
              callee: {
                type: 'MemberExpression',
                object: { type: 'Identifier', name: 'vi' },
                property: { type: 'Identifier', name: 'hoisted' }
              },
              arguments: []
            }
          }
        ]
      },
      {
        type: 'ExpressionStatement',
        start: mockStart,
        end: mockEnd,
        expression: {
          type: 'CallExpression',
          start: mockStart,
          end: mockEnd,
          callee: {
            type: 'MemberExpression',
            object: { type: 'Identifier', name: 'vi' },
            property: { type: 'Identifier', name: 'mock' }
          },
          arguments: [
            {
              type: 'Literal',
              value: './user.js'
            }
          ]
        }
      }
    ]
  };

  const result = hoistMocks(code, 'user.test.js', () => ast);
  assert(result !== undefined, 'Result must be defined');
  const transformed = result.toString();
  const hoistedIndex = transformed.indexOf('const mockUser = vi.hoisted');
  const importIndex = transformed.indexOf('const __vi_import_0__ = await import');
  assert(hoistedIndex !== -1 && importIndex !== -1 && hoistedIndex < importIndex, 'vi.hoisted declaration must be placed before dynamic imports');
}

// Contract 4: supports custom utilsObjectNames and hoistedModule options
{
  const code = `\nimport { config } from './config.js';\ncustomHelper.unmock('./config.js');`;
  const importStart = code.indexOf("import { config }");
  const importEnd = code.indexOf("from './config.js';") + "from './config.js';".length;
  const mockStart = code.indexOf("customHelper.unmock(");
  const mockEnd = code.indexOf("('./config.js');") + "('./config.js');".length;

  const ast = {
    type: 'Program',
    start: 0,
    end: code.length,
    body: [
      {
        type: 'ImportDeclaration',
        start: importStart,
        end: importEnd,
        specifiers: [
          {
            type: 'ImportSpecifier',
            imported: { type: 'Identifier', name: 'config' },
            local: { type: 'Identifier', name: 'config' }
          }
        ],
        source: {
          type: 'Literal',
          value: './config.js'
        }
      },
      {
        type: 'ExpressionStatement',
        start: mockStart,
        end: mockEnd,
        expression: {
          type: 'CallExpression',
          start: mockStart,
          end: mockEnd,
          callee: {
            type: 'MemberExpression',
            object: { type: 'Identifier', name: 'customHelper' },
            property: { type: 'Identifier', name: 'unmock' }
          },
          arguments: [
            {
              type: 'Literal',
              value: './config.js'
            }
          ]
        }
      }
    ]
  };

  const result = hoistMocks(code, 'custom.test.js', () => ast, {
    regexpHoistable: /customHelper\.unmock\(/,
    utilsObjectNames: ['customHelper'],
    hoistedModule: 'custom-framework'
  });
  assert(result !== undefined, 'Result must be defined');
  const transformed = result.toString();
  assert(transformed.includes('import { customHelper } from "custom-framework"'), 'Must import custom utility name from specified custom module');
  assert(transformed.includes("customHelper.unmock('./config.js')"), 'Must hoist custom unmock call');
}

console.log('Contract tests passed: @vitest/mocker.hoistMocks');