fix(typecheck): improve error message when tsc outputs help text

packages/vitest/src/typecheck/typechecker.ts

@@ -53,7 +53,7 @@ export class Typechecker {
 
   protected files: string[] = []
 
-  constructor(protected project: TestProject) {}
+  constructor(protected project: TestProject) { }
 
   public setFiles(files: string[]): void {
     this.files = files
@@ -123,6 +123,22 @@ export class Typechecker {
     sourceErrors: TestError[]
     time: number
   }> {
+    // Detect if tsc output is help text instead of error output
+    // This happens when tsconfig.json is missing and tsc can't find any config
+    if (output.includes('The TypeScript Compiler - Version') || output.includes('COMMON COMMANDS')) {
+      const { typecheck } = this.project.config
+      const tsconfigPath = typecheck.tsconfig || 'tsconfig.json'
+      const msg = `TypeScript compiler returned help text instead of type checking results.\n`
+        + `This usually means the tsconfig file was not found.\n\n`
+        + `Possible solutions:\n`
+        + `  1. Ensure '${tsconfigPath}' exists in your project root\n`
+        + `  2. If using a custom tsconfig, verify the path in your Vitest config:\n`
+        + `     test: { typecheck: { tsconfig: 'path/to/tsconfig.json' } }\n`
+        + `  3. Check that the tsconfig file is valid JSON`
+
+      throw new Error(msg)
+    }
+
     const typeErrors = await this.parseTscLikeOutput(output)
     const testFiles = new Set(this.getFiles())
 
@@ -319,6 +335,8 @@ export class Typechecker {
         return
       }
 
+      let resolved = false
+
       child.process.stdout.on('data', (chunk) => {
         dataReceived = true
         this._output += chunk
@@ -343,13 +361,25 @@ export class Typechecker {
         }
       })
 
+      // Also capture stderr for configuration errors like missing tsconfig
+      child.process.stderr?.on('data', (chunk) => {
+        this._output += chunk
+      })
+
       const timeout = setTimeout(
         () => reject(new Error(`${typecheck.checker} spawn timed out`)),
         this.project.config.typecheck.spawnTimeout,
       )
 
+      let winTimeout: NodeJS.Timeout | undefined
+
       function onError(cause: Error) {
+        if (resolved) {
+          return
+        }
         clearTimeout(timeout)
+        clearTimeout(winTimeout)
+        resolved = true
         reject(new Error('Spawning typechecker failed - is typescript installed?', { cause }))
       }
 
@@ -361,11 +391,13 @@ export class Typechecker {
           // on Windows, the process might be spawned but fail to start
           // we wait for a potential error here. if "close" event didn't trigger,
           // we resolve the promise
-          setTimeout(() => {
+          winTimeout = setTimeout(() => {
+            resolved = true
             resolve({ result: child })
           }, 200)
         }
         else {
+          resolved = true
           resolve({ result: child })
         }
       })

test/typescript/test/typecheck-error.test.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { createFile, runInlineTests } from '../../test-utils'
+
+describe('Typechecker Error Handling', () => {
+  it('throws helpful error when tsc outputs help text (missing config)', async () => {
+    // TESTING APPROACH:
+    // We cannot reliably trigger tsc's help text output in normal usage because:
+    // 1. tsc only shows help when called with NO arguments or INVALID arguments
+    // 2. Vitest always calls tsc with proper arguments (--noEmit, --pretty, etc.)
+    // 3. Invalid tsconfig causes ERROR output, not help text
+    //
+    // SOLUTION: Use a test executable that mimics tsc help output
+    // This is NOT a mock (no jest.mock or similar), but a real executable script
+    // that Vitest spawns and executes, validating the error handling logic works.
+
+    // Create a temporary directory for our fake tsc
+    const tmpDir = path.join(os.tmpdir(), `vitest-test-${Date.now()}`)
+
+    // Create fake tsc script - cross-platform executable
+    // Using createFile ensures cleanup even if test fails
+    const fakeTscPath = path.join(tmpDir, 'fake-tsc')
+    const scriptContent = '#!/usr/bin/env node\nconsole.log(\'Version 5.3.3\');\nconsole.log(\'tsc: The TypeScript Compiler - Version 5.3.3\');\nconsole.log(\'\');\nconsole.log(\'COMMON COMMANDS\');\n'
+
+    createFile(fakeTscPath, scriptContent)
+    fs.chmodSync(fakeTscPath, '755')
+
+    const configContent = `import { defineConfig } from 'vitest/config'
+export default defineConfig({
+  test: {
+    typecheck: {
+      enabled: true,
+      checker: '${fakeTscPath.replace(/\\/g, '/')}',
+    },
+  },
+})`
+
+    const { stderr, stdout } = await runInlineTests({
+      'vitest.config.ts': configContent,
+      'example.test-d.ts': 'import { expectTypeOf, test } from \'vitest\'\ntest(\'dummy type test\', () => { expectTypeOf(1).toEqualTypeOf<number>() })',
+    })
+
+    // Assert that Vitest caught the help text and threw the descriptive error
+    const output = stderr + stdout
+    expect(output).toContain('TypeScript compiler returned help text instead of type checking results')
+    expect(output).toContain('This usually means the tsconfig file was not found')
+    expect(output).toContain('Ensure \'tsconfig.json\' exists in your project root')
+  })
+})

test/typescript/test/typechecker.test.ts

@@ -0,0 +1,18 @@
+import { resolve } from 'pathe'
+import { describe, expect, it } from 'vitest'
+import { runVitest } from '../../test-utils'
+
+describe('Typechecker', () => {
+  it('handles non-existing typechecker command gracefully', async () => {
+    const { stderr } = await runVitest({
+      root: resolve(import.meta.dirname, '../fixtures/source-error'),
+      typecheck: {
+        enabled: true,
+        checker: 'non-existing-tsc-command',
+      },
+    })
+
+    // Should show proper error when typechecker doesn't exist
+    expect(stderr).toContain('Spawning typechecker failed')
+  })
+})