Add docs for internal mechanism, and demo for debug (#179)

* Add docs for internal mechanism, and demo for debug

* update

* update

* Update docs/internal-mechanism.md

Co-authored-by: JounQin <[email protected]>

* Update docs/internal-mechanism.md

Co-authored-by: JounQin <[email protected]>

* update

Co-authored-by: JounQin <[email protected]>

Author: ota-meshi

README.md

@@ -194,6 +194,10 @@ Welcome contributing!
 
 Please use GitHub's Issues/PRs.
 
+See also the documentation for the internal mechanism.  
+
+- [internal-mechanism.md](./docs/internal-mechanism.md)
+
 ## :lock: License
 
 See the [LICENSE](LICENSE) file for license rights and limitations (MIT).

docs/AST.md

@@ -550,7 +550,8 @@ interface SvelteHTMLComment extends Node {
 
 ### SvelteReactiveStatement
 
-This node is a reactive statement labeled with `$`.
+This node is a reactive statement labeled with `$`.  
+`SvelteReactiveStatement` is a special node to avoid confusing ESLint check rules with `LabeledStatement`.
 
 ```ts
 interface SvelteReactiveStatement extends Node {

docs/internal-mechanism.md

@@ -0,0 +1,113 @@
+# What the Parser does
+
+The main thing this parser does is parsing the `*.svelte` file and return an AST that can be parsed by ESLint.  
+However, this parser does a few other things for a better experience with ESLint integration.
+
+## Entry Point
+
+This parser parses `*.svelte` via `parseForESLint()` and returns the result to ESLint. This is a requirement for ESLint's custom parser.
+
+See https://eslint.org/docs/latest/developer-guide/working-with-custom-parsers.
+
+## Results
+
+### `ast`
+
+Returns the AST of the parses result.
+
+Script AST is [ESTree] compliant AST by default. However, if you used `@typescript-eslint/parser` as script parser, it may contain [TypeScript AST](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/ast-spec).  
+However, the parser assigns a special node `SvelteReactiveStatement` to the parsed result of `$:`.  
+`SvelteReactiveStatement` is a special node to avoid confusing ESLint check rules with `LabeledStatement`.
+
+[ESTree]: https://github.com/estree/estree
+
+The HTML template part returns a special AST. See [AST.md](./AST.md).
+
+The `Program` node contains `tokens` and `comments`. This is a requirement for ESLint's custom parser.
+
+See https://eslint.org/docs/latest/developer-guide/working-with-custom-parsers#the-ast-specification.
+
+### `services`
+
+This parser returns the `services` returned by the script parser.  
+In particular, typescript-eslint contains important information such as type information in `services`. The parser does not edit the `services`, but there is a trick in parsing the script to get the correct result of the `services` returned by the script parser.
+
+When parsing the script, the parser does not pass only the `<script>` part, but generates virtual script code including the script that converted the HTML template into a script, and lets the script parser parse it.
+
+For example, if you enter `*.svelte` template to listen for input events:
+
+```svelte
+<script lang="ts">
+    function inputHandler () {
+        // process
+    }
+</script>
+<input on:input={inputHandler}>
+```
+
+Parse the following virtual script code as a script:
+
+```ts
+                  
+    function inputHandler () {
+        // process
+    }
+;        
+                               
+(inputHandler)as ((e:'input' extends keyof HTMLElementEventMap?HTMLElementEventMap['input']:CustomEvent<any>)=>void);
+```
+
+This gives the correct type information to the inputHandler when used with `on:input={inputHandler}`.
+
+The script AST for the HTML template is then remapped to the template AST.
+
+You can check what happens to virtual scripts in the Online Demo.  
+https://ota-meshi.github.io/svelte-eslint-parser/virtual-script-code/
+
+### `scopeManager`
+
+This parser returns a ScopeManager instance.  
+ScopeManager is used in variable analysis such as [no-unused-vars](https://eslint.org/docs/latest/rules/no-unused-vars) and [no-undef](https://eslint.org/docs/latest/rules/no-undef) rules.  
+See https://eslint.org/docs/latest/developer-guide/scope-manager-interface for details.
+
+The parser will generate a virtual script so that it can parse the correct scope.  
+For example, when using `{#each}` and `{@const}`:
+
+```svelte
+<script lang="ts">
+    const array = [1, 2, 3]
+</script>
+{#each array as e}
+    {@const ee = e * 2}
+    {ee}
+{/each}
+```
+
+Parse the following virtual script code as a script:
+
+```ts
+                  
+    const array = [1, 2, 3]
+;        
+                  
+                       
+        
+       
+
+Array.from(array).forEach((e)=>{const ee = e * 2;(ee);});
+```
+
+This ensures that the variable `e` defined by `{#each}` is correctly scoped only within `{#each}`.
+
+Also, this parser returns special results for variables used in `$: foo = expression` and `$count` for proper analysis.
+
+It also adds virtual references for variables that are marked specially used in `*.svelte` (e.g. `export let` and `$ref`). This is a hack that is also used in typescript-eslint.  
+https://github.com/typescript-eslint/typescript-eslint/issues/4508#issuecomment-1030508403
+
+You can also check the results [Online DEMO](https://ota-meshi.github.io/svelte-eslint-parser/).
+
+### `visitorKeys`
+
+ESLint custom parsers that provide their own AST require `visitorKeys` to properly traverse the node.
+
+See https://eslint.org/docs/latest/developer-guide/working-with-custom-parsers.

explorer-v2/build-system/pre-build/webpack.config.js

@@ -74,6 +74,19 @@ export default [
 			'svelte/compiler': '$$inject_svelte_compiler$$',
 			espree: '$$inject_espree$$'
 		},
+		module: {
+			rules: [
+				{
+					test: /\/resolve-parser\.js$/u,
+					loader: 'string-replace-loader',
+					options: {
+						search: 'require\\(name\\)',
+						replace: `__non_webpack_require__(name)`,
+						flags: ''
+					}
+				}
+			]
+		},
 		plugins: [
 			new WrapperPlugin({
 				test: /svelte-eslint-parser\.js/,

explorer-v2/build-system/shim/globby.js

@@ -0,0 +1 @@
+export default {};

explorer-v2/build-system/shim/path.js

@@ -1,7 +1,16 @@
 export default {
-	extname
+	extname,
+	isAbsolute,
+	join
 };
 
 export function extname(p) {
 	return /\.[^.]*$/.exec(p)?.[0];
 }
+
+export function isAbsolute() {
+	return false;
+}
+export function join(...args) {
+	return args.join('/');
+}

explorer-v2/build-system/shim/util.js

@@ -2,10 +2,11 @@ export default new Proxy(
 	{},
 	{
 		get(target, key) {
-			console.log(key);
 			if (key === 'inspect') {
 				return {};
 			}
+			// eslint-disable-next-line no-console -- Demo
+			console.log(key);
 			return target[key];
 		}
 	}

explorer-v2/package.json

@@ -13,12 +13,13 @@
 	},
 	"dependencies": {
 		"@fontsource/fira-mono": "^4.2.2",
+		"@typescript-eslint/parser": "^5.30.3",
 		"eslint": "^8.0.0",
 		"eslint-plugin-svelte3": "^4.0.0",
 		"eslint-scope": "^7.0.0",
 		"pako": "^2.0.3",
 		"svelte": "^3.41.0",
-		"svelte-eslint-parser": "file:.."
+		"svelte-eslint-parser": "link:.."
 	},
 	"devDependencies": {
 		"@sveltejs/adapter-static": "^1.0.0-next.13",

explorer-v2/src/lib/Header.svelte

@@ -4,8 +4,15 @@
 	import { base as baseUrl } from '$app/paths';
 
 	function isActive(pathname, path) {
-		return pathname === path || pathname === `${baseUrl}${path}`;
+		const normalizedPathname = pathname.replace(/\/$/u, '');
+		const normalizedPath = path.replace(/\/$/u, '');
+		return (
+			normalizedPathname === normalizedPath || normalizedPathname === `${baseUrl}${normalizedPath}`
+		);
 	}
+
+	// eslint-disable-next-line no-process-env -- ignore
+	const dev = process.env.NODE_ENV !== 'production';
 </script>
 
 <header class="header">
@@ -28,6 +35,13 @@
 		sveltekit:prefetch
 		href="{baseUrl}/scope">Scope</a
 	>
+	{#if dev || isActive($page.url.pathname, `/virtual-script-code`)}
+		<a
+			class="menu"
+			class:active={isActive($page.url.pathname, `/virtual-script-code`)}
+			href="{baseUrl}/virtual-script-code">Virtual Script Code</a
+		>
+	{/if}
 	<div class="debug">
 		$page.url.pathname: {$page.url.pathname}
 		baseUrl: {baseUrl}

explorer-v2/src/lib/MonacoEditor.svelte

@@ -16,6 +16,7 @@
 	export let markers = [];
 	export let rightMarkers = [];
 	export let provideCodeActions = null;
+	export let editorOptions = {};
 
 	export let waiting = null;
 	let rootElement,
@@ -92,7 +93,8 @@
 			renderIndentGuides: true,
 			renderValidationDecorations: 'on',
 			renderWhitespace: 'boundary',
-			scrollBeyondLastLine: false
+			scrollBeyondLastLine: false,
+			...editorOptions
 		};
 
 		if (diffEditor) {