From 9c6d43fb9682d7e308371442421a1c5bb167e73e Mon Sep 17 00:00:00 2001
From: Simon Holthausen <simon.holthausen@accso.de>
Date: Fri, 14 Aug 2020 19:33:43 +0200
Subject: [PATCH 1/4] (docs) Overview of the language-tools

and how things work together
---
 docs/README.md            |  1 +
 docs/internal/overview.md | 80 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docs/internal/overview.md

diff --git a/docs/README.md b/docs/README.md
index d5e975e5b..7fe224b91 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -96,3 +96,4 @@ Your default formatter for Svelte files may be wrong. Either it's set to the old
 ## Internals
 
 -   [Notes about deployment](./internal/deployment.md)
+-   [Overview of the language-tools and how things work together](./overview.md)
diff --git a/docs/internal/overview.md b/docs/internal/overview.md
new file mode 100644
index 000000000..0185a2616
--- /dev/null
+++ b/docs/internal/overview.md
@@ -0,0 +1,80 @@
+# Overview of the language-tools and how things work together
+
+The `language-tools` repository is a monorepo containing several packages which are closely related to each other.
+
+-   `svelte2tsx` - transforms Svelte code into JSX/TSX code
+-   `language-server` - a language server adhering to the [LSP](https://microsoft.github.io/language-server-protocol)
+-   `svelte-check` - a command line tool to get diagnostics for Svelte code
+-   `svelte-vscode` - the [Svelte for VSCode](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) extension
+
+This is how they are related:
+
+```
+svelte-vscode |
+              |-> language-server -> svelte2tsx
+svelte-check  |
+```
+
+## language-server overview
+
+As briefly touched already, this is a language-server adhering to the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol).
+The protocol defines the communication between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc.
+
+Our `language-server` can roughly be splitted into four areas:
+
+-   CSS: Provides intellisense for the things inside `<style>`. Internally it mostly forwards stuff to the `vscode-css-languageservice`.
+-   HTML: Provides intellisense for basic HTML tags like `div`, `a` etc. Internally it mostly forwards stuff to the `vscode-html-languageservice`.
+-   Svelte: Provides the diagnostics of the Svelte compiler, does the formatting through `prettier-plugin-svelte` and other cross-cutting concerns like the "Extract Component" refactoring.
+-   TypeScript/JavaScript: Provides intellisense for all JS/TS related stuff. This not only includes code inside `<script>` but also inside the template the moment you use any of the Svelte specifics like bindings or template syntax.
+
+The last area, TS/JS, is where most of the work is done. Svelte is a mix of JavaScript/TypeScript inside `script` and more of it within Svelte's template syntax. To get a holistic view of the file, we need to account for both.
+This is also the reason why preprocessors such as `svelte-preprocess` cannot do type checking because it produces wrong diagnostics. To preprocess the script content, it only gets the content from the script. Think of this situation:
+
+```html
+<script lang="ts">
+    let a: number = 1;
+</script>
+{a}
+```
+
+`svelte-preprocess` only gets `let a = 1` and the diagnostics would output that `a` is never used, which is wrong.
+
+To get that holistic view, we need `svelte2tsx`.
+
+#### svelte2tsx
+
+To get a holistic view of Svelte files, we have two options:
+
+1. Write a language service ourselves who is capable of doing things like auto complete, go to definition, rename etc.
+2. Convert the Svelte code to something an existing language service can process which then does auto complete, go to defintion, rename etc for us.
+
+We chose the second option because TypeScript provides a language service which can do all the heavy lifting for us: We give it some files and then invoke methods like `getQuickInfoAtPosition` for hover info. These files need to be in a format the language service can understand: A form of JavaScript or TypeScript. `svelte2tsx` is the package which does this transformation: Pass in Svelte code and get back JSX or TSX code, depending on whether or not you use TS in Svelte. This code is not runnable in any way and does not actually exist at runtime when you run your app, it purely exists for the intellisense. The code also returns source mappings so we know which position in the original code corresponds to which generated position.
+
+#### Integration of svelte2tsx into the language-server
+
+This example shows how our `language-server` uses `svelte2tsx`:
+
+Svelte file changes:
+
+1. Svelte file comes in
+2. Transform Svelte to TSX/JSX
+3. Pass that result to the TypeScript language service
+
+User wants hover info:
+
+1. User hovers over a component property in the template
+2. Get generated file from original file
+3. Transform the position (line, character) where the user hovers from the original to the generated position
+4. Invoke TypeScript language service's method for hover info with the generated position
+5. Hand back results to user
+
+As you can see, the `language-server` is mostly doing position transformations and then handing the main work off to the TypeScript language service. Sometimes we also need to do post processing of the results and work around quirks.
+
+## svelte-check
+
+As mentioned above, preprocessors cannot do type checking. That's why we added `svelte-check`, a command line tool to get diagnostics for Svelte code.
+The tool is using the `language-server` to do this work. Inside the `language-server` we added an entry point for `svelte-check` which spins up the language server and just executes diagnostics.
+
+## svelte-vscode
+
+This is the [Svelte for VSCode](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) extension most of you probably use. Syntax highlighting is provided through a JSON file which tells VSCode how to tokenize the input. To get all the intellisense capabilities, the extension uses the the `language-server`. VSCode implements the LSP and also provides a node library to do most of the wiring for us. Some things like special refactoring commands ("Extract Component") need some extra glue code, but that's all.

From df100a4e13299a6cb414592c40ab1ea557010314 Mon Sep 17 00:00:00 2001
From: Simon Holthausen <simon.holthausen@accso.de>
Date: Fri, 14 Aug 2020 19:39:08 +0200
Subject: [PATCH 2/4] typo

---
 docs/internal/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/internal/overview.md b/docs/internal/overview.md
index 0185a2616..4ee406149 100644
--- a/docs/internal/overview.md
+++ b/docs/internal/overview.md
@@ -45,7 +45,7 @@ To get that holistic view, we need `svelte2tsx`.
 
 To get a holistic view of Svelte files, we have two options:
 
-1. Write a language service ourselves who is capable of doing things like auto complete, go to definition, rename etc.
+1. Write a language service ourselves which is capable of doing things like auto complete, go to definition, rename etc.
 2. Convert the Svelte code to something an existing language service can process which then does auto complete, go to defintion, rename etc for us.
 
 We chose the second option because TypeScript provides a language service which can do all the heavy lifting for us: We give it some files and then invoke methods like `getQuickInfoAtPosition` for hover info. These files need to be in a format the language service can understand: A form of JavaScript or TypeScript. `svelte2tsx` is the package which does this transformation: Pass in Svelte code and get back JSX or TSX code, depending on whether or not you use TS in Svelte. This code is not runnable in any way and does not actually exist at runtime when you run your app, it purely exists for the intellisense. The code also returns source mappings so we know which position in the original code corresponds to which generated position.

From e627cb4d7c7f5f06e90108bfbc0aee1942ce0d4a Mon Sep 17 00:00:00 2001
From: Simon Holthausen <simon.holthausen@accso.de>
Date: Sat, 15 Aug 2020 08:51:05 +0200
Subject: [PATCH 3/4] add note about svelte.config.js

---
 docs/internal/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/internal/overview.md b/docs/internal/overview.md
index 4ee406149..95c293ce2 100644
--- a/docs/internal/overview.md
+++ b/docs/internal/overview.md
@@ -24,7 +24,7 @@ Our `language-server` can roughly be splitted into four areas:
 
 -   CSS: Provides intellisense for the things inside `<style>`. Internally it mostly forwards stuff to the `vscode-css-languageservice`.
 -   HTML: Provides intellisense for basic HTML tags like `div`, `a` etc. Internally it mostly forwards stuff to the `vscode-html-languageservice`.
--   Svelte: Provides the diagnostics of the Svelte compiler, does the formatting through `prettier-plugin-svelte` and other cross-cutting concerns like the "Extract Component" refactoring.
+-   Svelte: Provides the diagnostics of the Svelte compiler. If you use preprocessors, those are invoked beforehand - that's why we need the `svelte.config.js` to know how to preprocess your files. It also does the formatting through `prettier-plugin-svelte` and other cross-cutting concerns like the "Extract Component" refactoring.
 -   TypeScript/JavaScript: Provides intellisense for all JS/TS related stuff. This not only includes code inside `<script>` but also inside the template the moment you use any of the Svelte specifics like bindings or template syntax.
 
 The last area, TS/JS, is where most of the work is done. Svelte is a mix of JavaScript/TypeScript inside `script` and more of it within Svelte's template syntax. To get a holistic view of the file, we need to account for both.

From 3926838e5638d84a9a8d83ce5a3f817dfa048a46 Mon Sep 17 00:00:00 2001
From: Simon Holthausen <simon.holthausen@accso.de>
Date: Mon, 17 Aug 2020 08:07:43 +0200
Subject: [PATCH 4/4] more links, more details on svelte2tsx

---
 .github/ISSUE_TEMPLATE/bug_report.md      |  4 ++
 .github/ISSUE_TEMPLATE/feature_request.md |  4 ++
 .prettierignore                           |  3 +-
 README.md                                 |  2 +
 docs/README.md                            |  2 +-
 docs/internal/overview.md                 | 49 ++++++++++++++++++-----
 6 files changed, 52 insertions(+), 12 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 404e4f455..d933d4de7 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -35,3 +35,7 @@ If applicable, add screenshots to help explain your problem.
 
 **Additional context**
 Add any other context about the problem here.
+
+<!-- Want to help us out? Read this to get started:
+https://github.com/sveltejs/language-tools#development
+-->
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index bbcbbe7d6..e80bc46c4 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -18,3 +18,7 @@ A clear and concise description of any alternative solutions or features you've
 
 **Additional context**
 Add any other context or screenshots about the feature request here.
+
+<!-- Want to help us out? Read this to get started:
+https://github.com/sveltejs/language-tools#development
+-->
\ No newline at end of file
diff --git a/.prettierignore b/.prettierignore
index d7cf4d024..8941ed7db 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,2 +1,3 @@
 packages/svelte2tsx/*.d.ts
-packages/svelte2tsx/test/**
\ No newline at end of file
+packages/svelte2tsx/test/**
+.github/**
\ No newline at end of file
diff --git a/README.md b/README.md
index f3ccbcbe6..f81b25503 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,8 @@ Converts a .svelte file into a legal TypeScript file. Built from [halfnelson/sve
 
 Pull requests are encouraged and always welcome. [Pick an issue](https://github.com/sveltejs/language-tools/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) and help us out!
 
+To get an overview of the internals, [read here](./docs/internal/overview.md).
+
 To install and work on these tools locally:
 
 > Make sure to uninstall the extension from the marketplace to not have it clash with the local one.
diff --git a/docs/README.md b/docs/README.md
index 7fe224b91..ccbd03990 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -96,4 +96,4 @@ Your default formatter for Svelte files may be wrong. Either it's set to the old
 ## Internals
 
 -   [Notes about deployment](./internal/deployment.md)
--   [Overview of the language-tools and how things work together](./overview.md)
+-   [Overview of the language-tools and how things work together](./internal/overview.md)
diff --git a/docs/internal/overview.md b/docs/internal/overview.md
index 95c293ce2..d54b238b6 100644
--- a/docs/internal/overview.md
+++ b/docs/internal/overview.md
@@ -20,12 +20,12 @@ svelte-check  |
 As briefly touched already, this is a language-server adhering to the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol).
 The protocol defines the communication between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc.
 
-Our `language-server` can roughly be splitted into four areas:
+Our `language-server` can roughly be splitted into [four areas](/packages/language-server/src/plugins):
 
 -   CSS: Provides intellisense for the things inside `<style>`. Internally it mostly forwards stuff to the `vscode-css-languageservice`.
--   HTML: Provides intellisense for basic HTML tags like `div`, `a` etc. Internally it mostly forwards stuff to the `vscode-html-languageservice`.
+-   HTML: Provides intellisense for basic HTML tags like `div`, `a` etc. Internally it mostly forwards stuff to the `vscode-html-languageservice`. Svelte-specific template syntax is _NOT_ handled here.
 -   Svelte: Provides the diagnostics of the Svelte compiler. If you use preprocessors, those are invoked beforehand - that's why we need the `svelte.config.js` to know how to preprocess your files. It also does the formatting through `prettier-plugin-svelte` and other cross-cutting concerns like the "Extract Component" refactoring.
--   TypeScript/JavaScript: Provides intellisense for all JS/TS related stuff. This not only includes code inside `<script>` but also inside the template the moment you use any of the Svelte specifics like bindings or template syntax.
+-   TypeScript/JavaScript: Provides intellisense for all JS/TS related stuff. This not only includes code inside `<script>` but also inside the template the moment you use any of the Svelte specifics like bindings or template syntax. `svelte2tsx` is used in here, and only here.
 
 The last area, TS/JS, is where most of the work is done. Svelte is a mix of JavaScript/TypeScript inside `script` and more of it within Svelte's template syntax. To get a holistic view of the file, we need to account for both.
 This is also the reason why preprocessors such as `svelte-preprocess` cannot do type checking because it produces wrong diagnostics. To preprocess the script content, it only gets the content from the script. Think of this situation:
@@ -41,26 +41,55 @@ This is also the reason why preprocessors such as `svelte-preprocess` cannot do
 
 To get that holistic view, we need `svelte2tsx`.
 
-#### svelte2tsx
+### svelte2tsx
 
 To get a holistic view of Svelte files, we have two options:
 
 1. Write a language service ourselves which is capable of doing things like auto complete, go to definition, rename etc.
 2. Convert the Svelte code to something an existing language service can process which then does auto complete, go to defintion, rename etc for us.
 
-We chose the second option because TypeScript provides a language service which can do all the heavy lifting for us: We give it some files and then invoke methods like `getQuickInfoAtPosition` for hover info. These files need to be in a format the language service can understand: A form of JavaScript or TypeScript. `svelte2tsx` is the package which does this transformation: Pass in Svelte code and get back JSX or TSX code, depending on whether or not you use TS in Svelte. This code is not runnable in any way and does not actually exist at runtime when you run your app, it purely exists for the intellisense. The code also returns source mappings so we know which position in the original code corresponds to which generated position.
+We chose the second option because TypeScript provides a language service which can do all the heavy lifting for us: We give it some files and then invoke methods like `getQuickInfoAtPosition` for hover info. These files need to be in a format the language service can understand: A form of JavaScript or TypeScript. `svelte2tsx` is the package which does this transformation: Pass in Svelte code and get back JSX or TSX code, depending on whether or not you use TS in Svelte. `svelte2tsx` uses some [ambient definitions](/packages/svelte2tsx/svelte-shims.d.ts) which are loaded by the language server, to do some of the transformations. It also provides [JSX definitions](/packages/svelte2tsx/svelte-jsx.d.ts) which are recognized by the TypeScript compiler and define intrinsic elements, attributes and events - so if you ever get an error that a DOM attribute is not assignable to a DOM element, it's likely a missing declaration in there.
 
-#### Integration of svelte2tsx into the language-server
+The code generated by `svelte2tsx` is not runnable in any way and does not actually exist at runtime when you run your app, it purely exists for the intellisense. The code also returns source mappings so we know which position in the original code corresponds to which generated position.
+
+### Integration of svelte2tsx into the language-server
 
 This example shows how our `language-server` uses `svelte2tsx`:
 
-Svelte file changes:
+**Svelte file changes:**
 
 1. Svelte file comes in
+
+```html
+<script>
+    export let world = 'name';
+</script>
+
+<h1>hello {world}</h1>
+```
+
 2. Transform Svelte to TSX/JSX
+
+```tsx
+<></>;
+function render() {
+    // -- the transformed script:
+    let world = 'name';
+    // -- the transformed template
+    <>
+        <h1>hello {world}</h1>
+    </>;
+    // -- obtained props, slots and events,
+    //    to get intellisense for this component in other components
+    return { props: { world }, slots: {}, events: {} };
+}
+// -- generate a class
+export default class _World_ extends createSvelte2TsxComponent(__sveltets_partial(render)) {}
+```
+
 3. Pass that result to the TypeScript language service
 
-User wants hover info:
+**User wants hover info:**
 
 1. User hovers over a component property in the template
 2. Get generated file from original file
@@ -73,8 +102,8 @@ As you can see, the `language-server` is mostly doing position transformations a
 ## svelte-check
 
 As mentioned above, preprocessors cannot do type checking. That's why we added `svelte-check`, a command line tool to get diagnostics for Svelte code.
-The tool is using the `language-server` to do this work. Inside the `language-server` we added an entry point for `svelte-check` which spins up the language server and just executes diagnostics.
+The tool is using the `language-server` to do this work. Inside the `language-server` we added an [entry point](/packages/language-server/src/svelte-check.ts) for `svelte-check` which spins up the language server and just executes diagnostics.
 
 ## svelte-vscode
 
-This is the [Svelte for VSCode](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) extension most of you probably use. Syntax highlighting is provided through a JSON file which tells VSCode how to tokenize the input. To get all the intellisense capabilities, the extension uses the the `language-server`. VSCode implements the LSP and also provides a node library to do most of the wiring for us. Some things like special refactoring commands ("Extract Component") need some extra glue code, but that's all.
+This is the [Svelte for VSCode](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) extension most of you probably use. Syntax highlighting is provided through a [JSON file](/packages/svelte-vscode/syntaxes) which tells VSCode how to tokenize the input. To get all the intellisense capabilities, the extension uses the the `language-server`. VSCode implements the LSP and also provides a node library to do most of the wiring for us. Some things like special refactoring commands ("Extract Component") need some extra glue code, but that's all.