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

packages/vitest/src/typecheck/typechecker.ts

@@ -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'
+      throw new Error(
+        `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`,
+      )
+    }
+
     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/typechecker.test.ts

@@ -0,0 +1,95 @@
+import type { TestProject } from '../../../packages/vitest/src/node/project'
+import { describe, expect, it } from 'vitest'
+import { Typechecker } from '../../../packages/vitest/src/typecheck/typechecker'
+
+describe('Typechecker', () => {
+  it('detects tsc help text and throws clear error', async () => {
+    // Create a minimal mock project
+    const mockProject = {
+      config: {
+        root: '/fake/root',
+        typecheck: {
+          tsconfig: 'custom-tsconfig.json',
+        },
+      },
+    } as unknown as TestProject
+
+    const typechecker = new Typechecker(mockProject)
+    typechecker.setFiles([])
+
+    // Simulate tsc outputting help text (what happens when tsconfig is missing)
+    const tscHelpOutput = `tsc: The TypeScript Compiler - Version 5.9.3
+
+COMMON COMMANDS
+
+  tsc
+  Compiles the current project (tsconfig.json in the working directory.)
+
+  tsc app.ts util.ts
+  Ignoring tsconfig.json, compiles the specified files with default compiler options.`
+
+    // The prepareResults method should detect help text and throw a clear error
+    await expect(
+      // @ts-expect-error - accessing protected method for testing
+      typechecker.prepareResults(tscHelpOutput),
+    ).rejects.toThrow('TypeScript compiler returned help text instead of type checking results')
+
+    try {
+      // @ts-expect-error - accessing protected method for testing
+      await typechecker.prepareResults(tscHelpOutput)
+    }
+    catch (error: any) {
+      // Verify error message contains helpful information
+      expect(error.message).toContain('This usually means the tsconfig file was not found')
+      expect(error.message).toContain('custom-tsconfig.json')
+      expect(error.message).toContain('Possible solutions:')
+    }
+  })
+
+  it('detects help text with "COMMON COMMANDS" marker', async () => {
+    const mockProject = {
+      config: {
+        root: '/fake/root',
+        typecheck: {},
+      },
+    } as unknown as TestProject
+
+    const typechecker = new Typechecker(mockProject)
+    typechecker.setFiles([])
+
+    // Help text might only contain COMMON COMMANDS without version
+    const tscHelpOutput = `COMMON COMMANDS
+
+  tsc
+  Compiles the current project (tsconfig.json in the working directory.)`
+
+    await expect(
+      // @ts-expect-error - accessing protected method for testing
+      typechecker.prepareResults(tscHelpOutput),
+    ).rejects.toThrow('TypeScript compiler returned help text')
+  })
+
+  it('does not throw error for normal tsc output', async () => {
+    const mockProject = {
+      config: {
+        root: '/fake/root',
+        typecheck: {},
+      },
+    } as unknown as TestProject
+
+    const typechecker = new Typechecker(mockProject)
+    typechecker.setFiles([])
+
+    // Normal tsc error output (not help text)
+    const normalTscOutput = `test.ts(5,10): error TS2322: Type 'string' is not assignable to type 'number'.`
+
+    // Should not throw for normal tsc errors
+    // Note: This will process the output normally
+    const result = await
+    // @ts-expect-error - accessing protected method for testing
+    typechecker.prepareResults(normalTscOutput)
+
+    expect(result).toBeDefined()
+    expect(result.files).toBeDefined()
+  })
+})