Merge pull request #1932 from microsoft/twoslash_errors

Improve the twoslash error handling code by having more constistent

Author: Orta Therox

packages/ts-twoslasher/README.md

@@ -233,12 +233,6 @@ Turns to:
 >     {
 >       "completions": [
 >         {
->           "name": "memory",
->           "kind": "property",
->           "kindModifiers": "declare",
->           "sortText": "1"
->         },
->         {
 >           "name": "assert",
 >           "kind": "method",
 >           "kindModifiers": "declare",
@@ -287,12 +281,6 @@ Turns to:
 >           "sortText": "1"
 >         },
 >         {
->           "name": "exception",
->           "kind": "method",
->           "kindModifiers": "declare",
->           "sortText": "1"
->         },
->         {
 >           "name": "group",
 >           "kind": "method",
 >           "kindModifiers": "declare",
@@ -536,7 +524,7 @@ Turns to:
 >       "start": 72,
 >       "line": 2,
 >       "character": 0,
->       "renderedMessage": "Type 'Record<string, string>' is not assignable to type 'Record<string, number>'.\n  Index signatures are incompatible.\n    Type 'string' is not assignable to type 'number'.",
+>       "renderedMessage": "Type 'Record<string, string>' is not assignable to type 'Record<string, number>'.\n  'string' index signatures are incompatible.\n    Type 'string' is not assignable to type 'number'.",
 >       "id": "err-2322-72-1"
 >     }
 >   ],
@@ -754,12 +742,18 @@ Turns to:
 >   }
 > var __spreadArray =
 >   (this && this.__spreadArray) ||
->   function (to, from) {
->     for (var i = 0, il = from.length, j = to.length; i < il; i++, j++) to[j] = from[i]
->     return to
+>   function (to, from, pack) {
+>     if (pack || arguments.length === 2)
+>       for (var i = 0, l = from.length, ar; i < l; i++) {
+>         if (ar || !(i in from)) {
+>           if (!ar) ar = Array.prototype.slice.call(from, 0, i)
+>           ar[i] = from[i]
+>         }
+>       }
+>     return to.concat(ar || from)
 >   }
 > export function fn(arr) {
->   var arr2 = __spreadArray([1], __read(arr))
+>   var arr2 = __spreadArray([1], __read(arr), false)
 > }
 > ```
 

packages/ts-twoslasher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript/twoslash",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "license": "MIT",
   "author": "TypeScript team",
   "homepage": "https://github.com/microsoft/TypeScript-Website",

packages/ts-twoslasher/src/index.ts

@@ -10,14 +10,7 @@ type TS = typeof import("typescript")
 type CompilerOptions = import("typescript").CompilerOptions
 type CustomTransformers = import("typescript").CustomTransformers
 
-import {
-  parsePrimitive,
-  cleanMarkdownEscaped,
-  typesToExtension,
-  stringAroundIndex,
-  getIdentifierTextSpans,
-  getClosestWord,
-} from "./utils"
+import { parsePrimitive, cleanMarkdownEscaped, typesToExtension, getIdentifierTextSpans, getClosestWord } from "./utils"
 import { validateInput, validateCodeForErrors } from "./validation"
 
 import { createSystem, createVirtualTypeScriptEnvironment, createFSBackedSystem } from "@typescript/vfs"
@@ -70,6 +63,34 @@ type HighlightPosition = {
   line: number
 }
 
+export class TwoslashError extends Error {
+  public title: string
+  public description: string
+  public recommendation: string
+  public code: string | undefined
+
+  constructor(title: string, description: string, recommendation: string, code?: string | undefined) {
+    let message = `
+## ${title}
+
+${description}
+`
+    if (recommendation) {
+      message += `\n${recommendation}`
+    }
+
+    if (code) {
+      message += `\n${code}`
+    }
+
+    super(message)
+    this.title = title
+    this.description = description
+    this.recommendation = recommendation
+    this.code = code
+  }
+}
+
 function filterHighlightLines(codeLines: string[]): { highlights: HighlightPosition[]; queries: QueryPosition[] } {
   const highlights: HighlightPosition[] = []
   const queries: QueryPosition[] = []
@@ -134,7 +155,12 @@ function getOptionValueFromMap(name: string, key: string, optMap: Map<string, st
   log(`Get ${name} mapped option: ${key} => ${result}`)
   if (result === undefined) {
     const keys = Array.from(optMap.keys() as any)
-    throw new Error(`Invalid value ${key} for ${name}. Allowed values: ${keys.join(",")}`)
+
+    throw new TwoslashError(
+      `Invalid inline compiler value`,
+      `Got ${key} for ${name} but it is not a supported value by the TS compiler.`,
+      `Allowed values: ${keys.join(",")}`
+    )
   }
   return result
 }
@@ -171,7 +197,11 @@ function setOption(name: string, value: string, opts: CompilerOptions, ts: TS) {
     }
   }
 
-  throw new Error(`No compiler setting named '${name}' exists!`)
+  throw new TwoslashError(
+    `Invalid inline compiler flag`,
+    `There isn't a TypeScript compiler flag called '${name}'.`,
+    `This is likely a typo, you can check all the compiler flags in the TSConfig reference, or check the additional Twoslash flags in the npm page for @typescript/twoslash.`
+  )
 }
 
 const booleanConfigRegexp = /^\/\/\s?@(\w+)$/
@@ -460,12 +490,18 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
           const quickInfo = ls.getQuickInfoAtPosition(filename, position)
 
           // prettier-ignore
-          let text = `Could not get LSP result: ${stringAroundIndex(env.getSourceFile(filename)!.text, position)}`
-          let docs = undefined
+          let text: string
+          let docs: string | undefined
 
           if (quickInfo && quickInfo.displayParts) {
             text = quickInfo.displayParts.map(dp => dp.text).join("")
             docs = quickInfo.documentation ? quickInfo.documentation.map(d => d.text).join("<br/>") : undefined
+          } else {
+            throw new TwoslashError(
+              `Invalid QuickInfo query`,
+              `The request on line ${q.line} in ${filename} for quickinfo via ^? returned no from the compiler.`,
+              `This is likely that the x positioning is off.`
+            )
           }
 
           const queryResult: PartialQueryResults = {
@@ -480,9 +516,13 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
         }
 
         case "completion": {
-          const quickInfo = ls.getCompletionsAtPosition(filename, position - 1, {})
-          if (!quickInfo && !handbookOptions.noErrorValidation) {
-            throw new Error(`Twoslash: The ^| query at line ${q.line} in ${filename} did not return any completions`)
+          const completions = ls.getCompletionsAtPosition(filename, position - 1, {})
+          if (!completions && !handbookOptions.noErrorValidation) {
+            throw new TwoslashError(
+              `Invalid completion query`,
+              `The request on line ${q.line} in ${filename} for completions via ^| returned no completions from the compiler.`,
+              `This is likely that the positioning is off.`
+            )
           }
 
           const word = getClosestWord(sourceFile.text, position - 1)
@@ -491,7 +531,7 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
 
           const queryResult: PartialCompletionResults = {
             kind: "completions",
-            completions: quickInfo?.entries || [],
+            completions: completions?.entries || [],
             completionPrefix: lastDot,
             line: q.line - i,
             offset: q.offset,
@@ -548,7 +588,13 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
 
     const source = env.sys.readFile(file)!
     const sourceFile = env.getSourceFile(file)
-    if (!sourceFile) throw new Error(`No sourcefile found for ${file} in twoslash`)
+    if (!sourceFile) {
+      throw new TwoslashError(
+        `Could not find a  TypeScript sourcefile for '${file}' in the Twoslash vfs`,
+        `It's a little hard to provide useful advice on this error. Maybe you imported something which the compiler doesn't think is a source file?`,
+        ``
+      )
+    }
 
     // Get all of the interesting quick info popover
     if (!handbookOptions.showEmit) {
@@ -618,7 +664,7 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
 
   // A validator that error codes are mentioned, so we can know if something has broken in the future
   if (!handbookOptions.noErrorValidation && relevantErrors.length) {
-    validateCodeForErrors(relevantErrors, handbookOptions, extension, originalCode)
+    validateCodeForErrors(relevantErrors, handbookOptions, extension, originalCode, fsRoot)
   }
 
   let errors: TwoSlashReturn["errors"] = []
@@ -655,7 +701,11 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
     if (!emitSource && !compilerOptions.outFile) {
       const allFiles = filenames.join(", ")
       // prettier-ignore
-      throw new Error(`Cannot find the corresponding **source** file for ${emitFilename} (looking for: ${emitSourceFilename} in the vfs) - in ${allFiles}`)
+      throw new TwoslashError(
+        `Could not find source file to show the emit for`,
+        `Cannot find the corresponding **source** file  ${emitFilename} for completions via ^| returned no quickinfo from the compiler.`,
+        `Looked for: ${emitSourceFilename} in the vfs - which contains: ${allFiles}`
+      )
     }
 
     // Allow outfile, in which case you need any file.
@@ -670,8 +720,11 @@ export function twoslasher(code: string, extension: string, options: TwoSlashOpt
 
     if (!file) {
       const allFiles = output.outputFiles.map(o => o.name).join(", ")
-      // prettier-ignore
-      throw new Error(`Cannot find the file ${handbookOptions.showEmittedFile} (looking for: ${fsRoot + handbookOptions.showEmittedFile} in the vfs) - in ${allFiles}`)
+      throw new TwoslashError(
+        `Cannot find the output file in the Twoslash VFS`,
+        `Looking for ${handbookOptions.showEmittedFile} in the Twoslash vfs after compiling`,
+        `Looked for" ${fsRoot + handbookOptions.showEmittedFile} in the vfs - which contains ${allFiles}.`
+      )
     }
 
     code = file.text

packages/ts-twoslasher/src/utils.ts

@@ -1,3 +1,5 @@
+import { TwoslashError } from "./"
+
 export function escapeHtml(text: string) {
   return text.replace(/</g, "&lt;")
 }
@@ -31,7 +33,11 @@ export function parsePrimitive(value: string, type: string): any {
       return value.toLowerCase() === "true" || value.length === 0
   }
 
-  throw new Error(`Unknown primitive type ${type} with - ${value}`)
+  throw new TwoslashError(
+    `Unknown primitive value in compiler flag`,
+    `The only recognized primitives are number, string and boolean. Got ${type} with ${value}.`,
+    `This is likely a typo.`
+  )
 }
 
 export function cleanMarkdownEscaped(code: string) {
@@ -41,23 +47,24 @@ export function cleanMarkdownEscaped(code: string) {
 }
 
 export function typesToExtension(types: string) {
-  switch (types) {
-    case "js":
-      return "js"
-    case "javascript":
-      return "js"
-    case "ts":
-      return "ts"
-    case "typescript":
-      return "ts"
-    case "tsx":
-      return "tsx"
-    case "jsx":
-      return "jsx"
-    case "jsn":
-      return "json"
+  const map: Record<string, string> = {
+    js: "js",
+    javascript: "js",
+    ts: "ts",
+    typescript: "ts",
+    tsx: "tsx",
+    jsx: "jsx",
+    json: "json",
+    jsn: "json",
   }
-  throw new Error("Cannot handle the file extension:" + types)
+
+  if (map[types]) return map[types]
+
+  throw new TwoslashError(
+    `Unknown TypeScript extension given to Twoslash`,
+    `Received ${types} but Twoslash only accepts: ${Object.keys(map)} `,
+    ``
+  )
 }
 
 export function getIdentifierTextSpans(ts: typeof import("typescript"), sourceFile: import("typescript").SourceFile) {