Fill out the TS Config reference

packages/gatsby-remark-twoslasher-code-blocks/index.js

@@ -1,4 +1,4 @@
-// @ts-enable 
+// // @ts-check
 
 const visit = require('unist-util-visit');
 const {twoslasher} = require(require.resolve("ts-twoslasher"))

packages/gatsby-remark-twoslasher-code-blocks/scripts/test.js

@@ -1,7 +1,7 @@
 var remark = require("remark")
 var visit = require("unist-util-visit")
 
-const { readFileSync }= require("fs")
+const { readFileSync } = require("fs")
 
 var remark = require("remark")
 var visit = require("unist-util-visit")

packages/sandbox/src/startPlayground.ts

@@ -23,7 +23,7 @@ type PlaygroundConfig = {
 
 const languageType = (config: PlaygroundConfig) => config.useJavaScript ? "javascript" : "typescript"
 const monacoLanguageDefaults = (config: PlaygroundConfig) => config.useJavaScript ? monaco.languages.typescript.javascriptDefaults : monaco.languages.typescript.typescriptDefaults
-const monacoLanguageWorker = (config: PlaygroundConfig) => config.useJavaScript ? monaco.languages.typescript.getJavaScriptWorker : monaco.languages.typescript.getTypeScriptWorker
+// const monacoLanguageWorker = (config: PlaygroundConfig) => config.useJavaScript ? monaco.languages.typescript.getJavaScriptWorker : monaco.languages.typescript.getTypeScriptWorker
 
 
 /** Default Monaco settings for playground */

packages/ts-twoslasher/test/README.md

@@ -0,0 +1,10 @@
+### Testing
+
+There are two types of tests:
+
+- Units which are Jest tests, and not unique to this project
+
+- Integration tests where you place a fixture code sample in the right folder and get a response JSON result. There are three folders for tests:
+  - `test/fixtures` - Any test in this file is shown in the README, so they should showcase features - not bugs
+  - `tests/fixtures/throws` - A test which should correctly raise
+  - `tests/fixtures/tests` - All other tests, repros etc

packages/ts-twoslasher/test/fixtures.test.ts

@@ -52,6 +52,25 @@ describe('with fixtures', () => {
     })
   })
 
+  readdirSync(join(fixturesFolder, 'tests')).forEach(fixtureName => {
+    const fixture = join(fixturesFolder, 'tests', fixtureName)
+    if (lstatSync(fixture).isDirectory()) {
+      return
+    }
+
+    // if(!fixtureName.includes("compiler_fl")) return
+    it('Hidden Fixtures: ' + fixtureName, () => {
+      const resultName = parse(fixtureName).name + '.json'
+      const result = join(resultsFolder, 'tests', resultName)
+
+      const file = readFileSync(fixture, 'utf8')
+
+      const fourslashed = twoslasher(file, extname(fixtureName).substr(1))
+      const jsonString = format(JSON.stringify(fourslashed), { parser: 'json' })
+      expect(jsonString).toMatchFile(result)
+    })
+  })
+
   const throwingFixturesFolder = join(__dirname, 'fixtures', 'throws')
 
   readdirSync(throwingFixturesFolder).forEach(fixtureName => {

packages/ts-twoslasher/test/fixtures/compiler_errors.ts

@@ -5,4 +5,4 @@ function fn(s) {
   console.log(s.subtr(3))
 }
 
-fn(42);
+fn(42)

packages/ts-twoslasher/test/fixtures/tests/cut_files.ts

@@ -1,4 +1,4 @@
 // Hello should not appear in the staticQuickInfos
-const hello = "world"
+const hello = 'world'
 // ---cut---
-const bye = "globe"
+const bye = 'globe'

packages/ts-twoslasher/test/fixtures/tests/hidden_emit.ts

@@ -0,0 +1,4 @@
+// @showEmit
+// @removeComments: true
+/** The translation of 'Hello world' into Portuguese */
+export declare const helloWorldPTBR = 'Olá Mundo'

packages/ts-twoslasher/test/results/tests/hidden_emit.json

@@ -0,0 +1,9 @@
+{
+  "code": "",
+  "extension": "js",
+  "highlights": [],
+  "queries": [],
+  "staticQuickInfos": [],
+  "errors": [],
+  "playgroundURL": "https://www.typescriptlang.org/play/#code/Q"
+}

packages/tsconfig-reference/README.md

@@ -36,3 +36,17 @@ yarn workspace tsconfig-reference run generate-json
 
 yarn workspace tsconfig-reference run generate-markdown
 ```
+
+You can validate any codeblocks which use twoslasher via the script:
+
+```sh
+yarn workspace tsconfig-reference run test
+
+# or to just run the linter without a build
+yarn workspace tsconfig-reference run lint
+
+# or to just one one linter
+yarn workspace tsconfig-reference run lint resolveJson
+```
+
+You can debug twoslash by setting the environment var `DEBUG="*"` in all of these too.

packages/tsconfig-reference/copy/en/categories/Advanced_Options_6178.md

@@ -2,4 +2,4 @@
 display: "Advanced"
 ---
 
-Additional Checks Copy
+Flags which help with debugging 

packages/tsconfig-reference/copy/en/categories/Basic_Options_6172.md

@@ -1,5 +1,5 @@
 ---
-display: "Basic Options"
+display: "Project Options"
 ---
 
-Additional Checks Copy
+These settings are used to define the runtime expectations of your project, how and where you want the JavaScript to be emitted and the level of integration you want with existing JavaScript code.

packages/tsconfig-reference/copy/en/categories/Command_line_Options_6171.md

@@ -1,5 +1,3 @@
 ---
 display: "Command Line"
 ---
-
-Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Experimental_Options_6177.md

@@ -2,4 +2,8 @@
 display: "Experimental"
 ---
 
-Additional Checks Copy
+TypeScript strives to only include features which are confirmed to be added into the JavaScript language. 
+
+There have been cases where a feature is compelling enough to be an exception to that rule, and these live as experimental compiler flags. 
+It is possible that a version of these features may be different when/if they are added to the JavaScript language, and thus are considered risky.
+

packages/tsconfig-reference/copy/en/categories/Project_Files_0.md

@@ -1,5 +1,5 @@
 ---
-display: "Project File Inclusion"
+display: "File Inclusion"
 ---
 
-
+These settings help you ensure that TypeScript picks up the right files.

packages/tsconfig-reference/copy/en/categories/Source_Map_Options_6175.md

@@ -2,4 +2,7 @@
 display: "Source Maps"
 ---
 
-Additional Checks Copy
+In order to provide rich debugging tools and crash reports which make sense to developers, TypeScript supports
+emitting additional files which conform to the JavaScript Source Map standards. 
+
+These are emitted as `.map` files which live alongside the file they represent.

packages/tsconfig-reference/copy/en/categories/Strict_Type_Checking_Options_6173.md

@@ -2,4 +2,12 @@
 display: "Strict Checks"
 ---
 
-Additional Checks Copy
+TypeScript supports a spectrum of JavaScript patterns, TypeScript patterns and strives for backwards compatibility with them all.
+
+Upgrading to a new version of TypeScript can uncover two types of errors:
+
+- Errors which already exist in your codebase, TypeScript has uncovered because the language has become refined it's understanding of JavaScript.
+- A new suite of errors which tackle a whole new problem domain.
+
+TypeScript will usually add a compiler flag for the latter set of errors, and by default these are not enabled. 
+If you  want to ensure that your codebase is as correct as possible, then use the option [`strict`](#strict) to opt-in to every possible improvement as they are built. 

packages/tsconfig-reference/copy/en/options/allowJs.md

@@ -2,4 +2,41 @@
 display: "Allow JS"
 ---
 
-Allow javascript files to be compiled.
+Allow JavaScript files to be imported inside your project, instead of just `.ts` and `.tsx` files. For example, this JS file:
+
+```js twoslasher
+// @filename: card.js
+export const defaultCardDeck = "Heart"
+```
+
+When imported into a TypeScript file will raise an error:
+
+```ts twoslasher
+// @errors: 2307
+// @filename: card.js
+module.exports.defaultCardDeck = "Heart"
+
+// ---cut---
+// @filename: index.ts
+import { defaultCardDeck } from "./card"
+
+console.log(defaultCardDeck)
+```
+
+Imports fine with `allowJs` enabled:
+
+```ts twoslasher
+// @filename: card.js
+/// <reference types="node" />
+
+module.exports.defaultCardDeck = "Heart"
+
+// ---cut---
+// @allowJs
+// @filename: index.ts
+import { defaultCardDeck } from "./card"
+
+console.log(defaultCardDeck)
+```
+
+This flag can be used as a way to incrementally add TypeScript files into JS projects by allowing the `.ts` and `.tsx` files to live along-side existing JavaScript files.

packages/tsconfig-reference/copy/en/options/allowSyntheticDefaultImports.md

@@ -2,4 +2,21 @@
 display: "Allow Synthetic Default Imports"
 ---
 
-Allow default imports from modules with no default export. This does not affect code emit, just typechecking.
+When set to true, `allowSyntheticDefaultImports` let's you write an import like:
+
+```ts
+import React from "react"
+```
+
+instead of:
+
+```ts
+import * as React from "react"
+```
+
+When the module **does not** specify a default export.
+
+This does not affect the JavaScript emitted by TypeScript, it only for the type checking. 
+This option brings the behavior of TypeScript in-line with Babel, where extra code is emitted to make using a default export of a module more ergonomic.
+
+

packages/tsconfig-reference/copy/en/options/allowUmdGlobalAccess.md

@@ -2,4 +2,6 @@
 display: "Allow Umd Global Access"
 ---
 
-Allow accessing UMD globals from modules.
+When set to true, `allowUmdGlobalAccess` lets you access UMD exports as globals from inside module files. A module file is a file that has imports and/or exports. Without this flag, using an export from a UMD module requires an import declaration.
+
+An example use case for this flag would be a web project where you know the particular library (like jQuery or Lodash) will always be available at runtime, but you can’t access it with an import.

packages/tsconfig-reference/copy/en/options/allowUnreachableCode.md

@@ -2,10 +2,24 @@
 display: "Allow Unreachable Code"
 ---
 
-Disables warnings about unreachable code.
-These warnings are only about code which is provably unreachable due to syntactic construction, like the example below.
+Set to false to disable warnings about unreachable code.
+These warnings are only about code which is provably unreachable due to the use of JavaScript syntax, for example:
 
 ```ts
+function fn(n: number) {
+   if (n > 5) {
+      return true;
+   } else {
+      return false;
+   }
+   return true;
+}
+```
+
+With `"allowUnreachableCode": false`:
+
+```ts twoslasher
+// @errors: 7027
 // @allowUnreachableCode: false
 function fn(n: number) {
    if (n > 5) {
@@ -17,4 +31,4 @@ function fn(n: number) {
 }
 ```
 
-TypeScript doesn't error on the basis of code which *appears* to be unreachable due to type analysis.
+This does not affect errors on the basis of code which *appears* to be unreachable due to type analysis.

packages/tsconfig-reference/copy/en/options/allowUnusedLabels.md

@@ -2,16 +2,18 @@
 display: "Allow Unused Labels"
 ---
 
-Disables warnings about unused labels.
+Set to false to disable warnings about unused labels.
+
 Labels are very rare in JavaScript and typically indicate an attempt to write an object literal:
 
-```ts
+```ts twoslash
+// @errors: 7028
 // @allowUnusedLabels: false
-function f(a: number) {
-   // Forgot 'return' statement!
-   if (a > 10)
+function verifyAge(age: number) {
+   // Forgot 'return' statement
+   if (age > 18)
    {
-       m: 0
+       verified: true
    }
 }
 ```

packages/tsconfig-reference/copy/en/options/alwaysStrict.md

@@ -2,4 +2,6 @@
 display: "Always Strict"
 ---
 
-Parse in strict mode and emit "use strict" for each source file.
+Ensures that your files are parsed in the ECMAScript strict mode, and emit "use strict" for each source file. 
+
+[ECMAScript strict](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) mode was introduced in ES5 and provides behavior tweaks to the runtime of the JavaScript engine to improve performance, and makes a set of errors throw instead of silently ignoring them. 

packages/tsconfig-reference/copy/en/options/baseUrl.md

@@ -2,4 +2,25 @@
 display: "Base Url"
 ---
 
-Base directory to resolve non-absolute module names.
+Lets you set a base directory to resolve non-absolute module names. 
+
+You can define a root folder where you can do absolute file resolution. E.g.
+
+```
+baseUrl
+├── ex.ts
+├── hello
+│   └── world.ts
+└── tsconfig.json
+```
+
+With `"baseUrl": "./"` inside this project TypeScript will look for files starting at the same folder as the `tsconfig.json`.
+
+```ts
+import { helloWorld } from "hello/world"
+
+console.log(helloWorld)
+```
+
+If you get tired of imports always looking like `"../"` or `"./"`. Or needing
+to change as you move files, this is a great way to fix that.

packages/tsconfig-reference/copy/en/options/charset.md

@@ -2,7 +2,5 @@
 display: "Charset"
 ---
 
-> ❌ **Deprecated:** This option does nothing.
-
 In prior versions of TypeScript, this controlled what encoding was used when reading text files from disk.
 Today, TypeScript assumes UTF-8 encoding, but will correctly detect UTF-16 (BE and LE) or UTF-8 BOMs.