internal-mechanism.md

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.
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.

The HTML template part returns a special AST. See 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:

<script lang="ts">
  function inputHandler() {
    // process
  }
</script>

<input on:input={inputHandler} />

Parse the following virtual script code as a script:

function inputHandler() {
  // process
}
function $_render1() {
  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://sveltejs.github.io/svelte-eslint-parser/virtual-script-code/

See also Scope Types section.

scopeManager

This parser returns a ScopeManager instance.
ScopeManager is used in variable analysis such as no-unused-vars and 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}:

<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:

const array = [1, 2, 3];
function $_render1() {
  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.
typescript-eslint/typescript-eslint#4508 (comment)

You can also check the results Online DEMO.

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.

Scope Types

TypeScript's type inference is pretty good, so parsing Svelte as-is gives some wrong type information.

e.g.

export let foo: { bar: number } | null = null;

$: console.log(foo && foo.bar);
                   // ^ never type

(You can see it on TypeScript Online Playground)

In the above code, foo in $: should be object or null in *.svelte, but TypeScript infers that it is null only.

To avoid this problem, the parser generates virtual code and traps statements within $: to function scope. Then restore it to have the correct AST and ScopeManager.

For example:

<script lang="ts">
  export let foo: { bar: number } | null = null;

  $: console.log(foo && foo.bar);

  $: r = foo && foo.bar;

  $: ({ bar: n } = foo || { bar: 42 });
</script>

{foo && foo.bar}

Parse the following virtual script code as a script:

export let foo: { bar: number } | null = null;

$: function $_reactiveStatementScopeFunction1() {
  console.log(foo && foo.bar);
}

$: let r = $_reactiveVariableScopeFunction2();
function $_reactiveVariableScopeFunction2() {
  let $_tmpVar3;
  return ($_tmpVar3 = foo && foo.bar);
}

$: let { bar: n } = $_reactiveVariableScopeFunction4();
function $_reactiveVariableScopeFunction4() {
  let $_tmpVar5;
  return ($_tmpVar5 = foo || { bar: 42 });
}
function $_render6() {
  foo && foo.bar;
}