feat: introduce Volar.js meta-language by auvred · Pull Request #2315 · flint-fyi/flint

auvred · 2026-02-14T06:31:01Z

PR Checklist

Addresses an existing open issue: fixes 🚀 Feature: Introduce Volar.js meta-language #1853
That issue was marked as status: accepting prs
Steps in CONTRIBUTING.md were taken

Overview

This is a very complex PR and it's even hard to properly explain it in a linear order because things interact in weird ways here, so I'll try to explain it in several steps.

Brief overview:

We have two sets of global variables: in @flint.fyi/typescript-language (used by @flint.fyi/volar-language) and in @flint.fyi/volar-language (used by @flint.fyi/{astro,svelte,vue}-language). These variables are filled in reverse order by downstream packages when imported (@flint.fyi/vue-language -> @flint.fyi/volar-language -> @flint.fyi/typescript-language). Later they're used in normal order (@flint.fyi/typescript-language -> @flint.fyi/volar-language -> @flint.fyi/vue-language).

We have several concepts:

VolarCreateFile - callback which is registered in @flint.fyi/typescript-language from @flint.fyi/volar-language by calling setVolarCreateFile.

Its purpose is to create a Flint's file for an extension language.
VolarLanguagePluginInitializer - contains Volar language plugins and VolarBasedLanguageCreateFile.

Plugin initializers are registered globally when Volar-based Flint language is created.

Every extension language (@flint.fyi/{astro,svelte,vue}-language) provides its own Volar language plugins and VolarBasedLanguageCreateFile.
VolarBasedLanguageCreateFile - function that returns extension language-specific info so that @flint.fyi/volar-language is able to create a Flint file.
Volar-based Flint language - meta language that is used to create actual extension language (e.g., @flint.fyi/vue-language calls createVolarBasedLanguage).
This language is not used anywhere in Flint runtime.

It has two purposes:
- register VolarLanguagePluginInitializer globally
- and provide type-safety for extension language rules
These rules use typescriptLanguage as their language (more on this later).
Volar language - orchestrator of several Volar language plugins and Volar scripts. Both Svelte and Vue plugins can co-exist. Volar language decides which one should handle .svelte and .vue.
Volar language plugin - its responsibility is to generate "service script"
Volar's "source script" - wrapper around file's original source text
Volar's "service script" - wrapper around file's generated virtual text
Volar's "mapping" - maps regions of source text to the corresponding regions of generated virtual text

Now, the initialization order (I'll use Vue language for illustration, but this applies to Astro and Svelte as well):

User imports @flint.fyi/vue in flint.config.ts
@flint.fyi/vue contains rules that use @flint.fyi/vue-language language
@flint.fyi/vue-language registers .vue extension through @flint.fyi/ts-patch and creates a vueLanguage with createVolarBasedLanguage (it passes VolarLanguagePluginInitializer there)
createVolarBasedLanguage registers VolarLanguagePluginInitializer globally
@flint.fyi/volar-language sets global TS program creation proxy via @flint.fyi/ts-patch
@flint.fyi/volar-language calls setVolarCreateFile exported from @flint.fyi/typescript-language with VolarCreateFile callback
setVolarCreateFile saves this callback globally

At this point initialization is done (linting hasn't started yet!)

Now, @flint.fyi/core starts collecting files for linting:

Since Volar-based Flint language rules specify typescriptLanguage as their language, @flint.fyi/core calls typescriptLanguage.createFile({ filePath: 'myfile.vue' })
typescriptLanguage calls service.openClientFile('myfile.vue')
This creates TS program internally and @flint.fyi/volar-language intercepts program creation via @flint.fyi/ts-patch
It takes VolarLanguagePluginInitializers (including a @flint.fyi/vue-language's one) and evaluates them in order to get two things:
- List of Volar language plugins
- VolarBasedLanguageCreateFile - customizations provided by @flint.fyi/vue-language
Also, it attaches VolarBasedLanguageCreateFile to Volar language plugin (__flintCreateFile), so that later we can access it.
Then, it attaches Volar language to the proxied TS program (__flintVolarLanguage)
At this moment proxied TS program is a fully functioning program that contains .vue files with generated virtual code
typescriptLanguage detects that .vue extension is not natively supported by TypeScript and hands off file creation to the VolarCreateFile callback. Since typescriptLanguage doesn't know anything about attached __flintVolarLanguage and __flintCreateFile properties, it just passes ts.Program and ts.SourceFile to the VolarCreateFile.
VolarCreateFile:
- extracts __flintVolarLanguage from the ts.Program
- extracts "source script", "service script" and "mappings" from Volar language by using ts.SourceFile's file name
- extracts __flintCreateFile from the Volar language plugin attached to the "source script"
- calls __flintCreateFile with ts.Program, ts.SourceFile, Volar language, "source script" and "service script"
__flintCreateFile (provided by @flint.fyi/vue-language) (PR - feat: introduce Vue language #2316):
- parses source text with @vue/compiler-dom in order to get Vue AST
- extracts Flint directives from comments in <template>
- converts Vue parsing errors to Flint diagnostics
- provides extraServices with Vue-specific extras, such as Vue AST (they're passed to rules later)
Now, back to the VolarCreateFile. It returns Flint file with:
- Flint directives from generated virtual text
- adjustReportRange, __volarServices.runVisitors, and __volarServices.getDiagnostics (more on them later)
Now, back to the typescriptLanguage.createFile. It returns file created by VolarCreateFile (with Symbol.dispose to cleanup opened TS file)

At this point we have initialized Flint file.

Now, Flint starts actual linting:

It calls typescriptLanguage.runFileVisitors
typescriptLanguage.runFileVisitors tries to access file.__volarServices. If they're present, it hands off visiting to the __volarServices.runVisitors, otherwise it defaults to common ts.SourceFile visiting.
__volarServices.runVisitors starts visiting ts.SourceFile. Remember that this is generated virtual text ("service script"). In order to avoid doing extra work it visits only statements that contain at least one "mapping" inside them.
When some visitor decides to report an error, it calls ruleRuntime.report
Rule runtime tries to adjust all reported ranges with file.adjustReportRange (if present)
Now a little hack: we want to have an ability to do both:

1. Allow @flint.fyi/ts rules seamlessly report errors on generated virtual text
2. Allow @flint.fyi/vue rules to report errors on source text

Right now we have only one reporting channel: ruleRuntime.report({ message, range }).

So, for case 1., rules just call context.report. However, for case 2., rules call reportSourceCode(context, { message, range }). reportSourceCode is exported from @flint.fyi/volar-language.

reportSourceCode negates the beginning of the range, so that later adjustReportRange can distinguish between case 1. and 2.
If file.adjustReportRange detects that the range is reported on source text, it returns it as-is. Otherwise it uses Volar "mappings" to translate range from "service script" positions to "source script".

That's it!!!

I know that there are a lot of questionable hacks, however given #1253 (comment), we would have to refactor a large part of @flint.fyi/core. We can design this refactor these hacks in mind.

I think it's better to merge these hacks, because I'm tired of re-syncing Vue support with @flint.fyi/core changes every few weeks (a decent portion of this PR has been living locally on my machine since October xD)

Now this should automagically work!!!

import { defineConfig } from '@flint.fyi/core'
import { ts } from '@flint.fyi/ts'
import { svelte } from '@flint.fyi/svelte'
import { vue } from '@flint.fyi/vue'

export default defineConfig({
  use: [
    {
      files: [ts.files, vue.files, svelte.files],
      rules: [
        ts.rules({ anyReturns: true })
      ],
    },
    {
      files: [vue.files],
      rules: [
        vue.rules({ vForKeys: true })
      ],
    },
  ]
})

changeset-bot · 2026-02-14T06:31:05Z

🦋 Changeset detected

Latest commit: 09abd33

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 25 packages

Name	Type
@flint.fyi/core	Patch
@flint.fyi/rule-tester	Patch
@flint.fyi/typescript-language	Patch
@flint.fyi/volar-language	Minor
@flint.fyi/astro	Patch
@flint.fyi/browser	Patch
@flint.fyi/cli	Patch
@flint.fyi/json-language	Patch
@flint.fyi/json	Patch
@flint.fyi/jsx	Patch
@flint.fyi/markdown-language	Patch
@flint.fyi/md	Patch
@flint.fyi/next	Patch
@flint.fyi/node	Patch
@flint.fyi/nuxt	Patch
@flint.fyi/package-json	Patch
@flint.fyi/performance	Patch
@flint.fyi/plugin-flint	Patch
@flint.fyi/react	Patch
@flint.fyi/solid	Patch
@flint.fyi/spelling	Patch
@flint.fyi/text-language	Patch
@flint.fyi/ts	Patch
@flint.fyi/yaml-language	Patch
@flint.fyi/yaml	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-02-14T06:31:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
flint	Ready	Preview, Comment	Mar 9, 2026 10:10am

Added a changeset for the introduction of Volar.js meta-language with patches for several packages.

packages/rule-tester/src/runTestCaseRule.ts

lishaduck · 2026-02-14T15:30:55Z

I'll review the code in a moment (want to rebase the host work first), but initial thoughts:

This is a very complex PR and it's even hard to properly explain it in a linear order because things interact in weird ways here, so I'll try to explain it in several steps.

Obviously I haven't read the code yet to know if you lied in there 😛 but you did a very good job explaining. It made sense as I read and and was a nice and linear. Don't quiz me though (yet).

I know that there are a lot of questionable hacks, however given #1253 (comment), we would have to refactor a large part of @flint.fyi/core. We can design this refactor these hacks in mind.

I think it's better to merge these hacks

Agreed. Haven't looked at it yet but I'm 100% in favor of getting the hacky version in now and rewriting the rest of the codebase to work with #1253 (comment) later.

because I'm tired of re-syncing Vue support with @flint.fyi/core changes every few weeks (a decent portion of this PR has been living locally on my machine since October xD)

I just want to say that's really impressive :)
I know I usually don't have that much patience. Glad it's finally up though!

.changeset/quick-peas-join.md

lishaduck

Only took me 3 weeks to get around to "review[ing] the code in a moment" :)

Looks good! Some of it goes over my head but I tried to leave comments where it seemed like it could be clearer.

I'll just leave these as comments, I don't think they're blocking but I'm not confident enough to go full blown approval yet.

packages/core/src/running/runLintRule.ts

packages/typescript-language/src/language.ts

lishaduck · 2026-03-07T01:43:11Z

packages/volar-language/src/language.ts

+	SourceScript as VolarSourceScript,
+} from "@volar/language-core";
+import type { TypeScriptServiceScript as VolarTypeScriptServiceScript } from "@volar/typescript";
+// eslint-disable-next-line no-restricted-syntax


lol that's funny. Should probably fix that at some point 😅

packages/volar-language/src/language.ts

lishaduck · 2026-03-07T01:46:43Z

packages/volar-language/src/language.ts

+assert(
+	globalTyped._flintVolarLanguageState == null,
+	`Two different versions of ${packageJson.name} are imported: ${packageJson.version} and ${globalTyped._flintVolarLanguageState?.packageVersion}`,
+);


This is the same as in the typescript plugin, b/c they both need to be singletons, correct?

I am mildly worried about 1) peer dependencies conflicts, we could potentially get two different versions with differing peers and 2) actually accessing peers in Yarn/hermetic pnpm, but I think we can see if it's an issue in practice before scrambling. Packaging is complicated 😅

This is the same as in the typescript plugin, b/c they both need to be singletons, correct?

Yeah, these are consequences of relying on singletone patched typescript package and global import side effects.

Maybe we can refactor all of this to use AsyncLocalStorage some day...

And also using different versions of languages because of peer deps mess goes against our TS project service approach, so this is another reason to ban using two versions of the same language.

packages/volar-language/src/language.ts

lishaduck · 2026-03-07T01:57:41Z

packages/volar-language/src/language.ts

+				visitors.SourceFile?.(sourceFile, visitorServices);
+				// Visit only statements that have a mapping to the source code
+				// to avoid doing extra work
+				Statements: for (const statement of sourceFile.statements) {


Don't we have a lint against labels? (this usage doesn't actually seem that problematic to me, just concerned lints might be broken again.

🤔 Both ESLint and Flint are happy

Lol. AI notwithstanding, I think this language feature has become so esoteric that only people who really want it use it...

packages/volar-language/src/language.ts

JoshuaKGoldberg

Glorious. I agree, let's ship. 🚀

auvred · 2026-03-08T06:33:21Z

Btw, @JoshuaKGoldberg, since @flint.fyi/volar-language is a new package and we have trusted publishing set up, you will probably need to manually publish an empty package to NPM before running the release workflow, right?

lishaduck · 2026-03-08T15:10:11Z

packages/typescript-language/src/language.ts

+
+const fileExtToFlintPlugin: Record<string, string> = {
+	".astro": "@flint.fyi/astro",
+	".ember": "@flint.fyi/ember",


Do we intend on having an ember plugin? I was using Ember as an example of a language we probably wouldn't support in-house.

Glint already has Volar plugin, so we can add support for Ember in under 50 LOC https://github.com/auvred/golar/blob/ad32aa1151572251b0b68a2d823d3c0ebab2418a/packages/ember/src/bin.ts

I think it won't hurt?

OOPS, just noticed this: there is no .ember file extension xD. It's .{gts,gjs}

lishaduck · 2026-03-08T15:12:33Z

packages/volar-language/src/language.ts

 ) {
-	// TODO: suggestions, fixes
 	context.report({
 		...report,


Is there anything left to spread then?

data, message, dependencies and so on :)

lishaduck · 2026-03-08T15:13:07Z

packages/volar-language/src/language.ts

 }
+function sourceCodeRange(range: CharacterReportRange): CharacterReportRange {
+	return {
+		begin: -range.begin,


Wait why is it negative if it's an actual range?

Rule runtime tries to adjust all reported ranges with file.adjustReportRange (if present)

Now a little hack: we want to have an ability to do both:

Allow @flint.fyi/ts rules seamlessly report errors on generated virtual text

Allow @flint.fyi/vue rules to report errors on source text
Right now we have only one reporting channel: ruleRuntime.report({ message, range }).
So, for case 1., rules just call context.report. However, for case 2., rules call reportSourceCode(context, { message, range }). reportSourceCode is exported from @flint.fyi/volar-language.
reportSourceCode negates the beginning of the range, so that later adjustReportRange can distinguish between case 1. and 2.

This is a first step, it's later negated back to positive by adjustReportRange

Oh right it's been a bit 😅

lishaduck · 2026-03-08T15:13:24Z

packages/volar-language/package.json

 {
 	"name": "@flint.fyi/volar-language",
-	"version": "0.16.0",
+	"version": "0.0.1",


Good catch 😂

JoshuaKGoldberg · 2026-03-08T21:23:27Z

Btw, @JoshuaKGoldberg, since @flint.fyi/volar-language is a new package and we have trusted publishing set up, you will probably need to manually publish an empty package to NPM before running the release workflow, right?

Mannnn I really don't know what the right strategy is. It's obnoxious. Ludicrous. JoshuaKGoldberg/create-typescript-app#2370 if anybody wants to help me learn these things.

auvred · 2026-03-09T10:19:09Z

Okay, I looked through the changes one more time, and I think it's time to

auvred added 8 commits February 9, 2026 15:56

wip

fd1767f

wip

05eb142

wip

632123e

wip

636826a

wip

c3300e2

rm astro and svelte langs

ce46bbc

cleanup

efa44cc

rm vue language

cb79983

merge main

9d1b55a

This was referenced Feb 14, 2026

WIP: Vue.js support #836

Closed

WIP: linter host, VFS, and other related experiments #1179

Closed

fix lint issues

069fdbf

vercel bot deployed to Preview February 14, 2026 07:13 View deployment

auvred mentioned this pull request Feb 14, 2026

feat: introduce Vue language #2316

Merged

3 tasks

auvred and others added 3 commits February 14, 2026 07:16

changeset

7ca1919

Added a changeset for the introduction of Volar.js meta-language with patches for several packages.

c86a133

abeefe6

vercel bot deployed to Preview February 14, 2026 07:20 View deployment

auvred commented Feb 14, 2026

View reviewed changes

packages/rule-tester/src/runTestCaseRule.ts Outdated Show resolved Hide resolved

michaelfaith reviewed Feb 15, 2026

View reviewed changes

.changeset/quick-peas-join.md Outdated Show resolved Hide resolved

lishaduck reviewed Mar 7, 2026

View reviewed changes

JoshuaKGoldberg approved these changes Mar 7, 2026

View reviewed changes

auvred added 3 commits March 8, 2026 09:05

Merge branch 'main' into volar-language

7606c71

changeset

fcc54db

review comments

16b08c9

lint fix

d5bae69

auvred added 2 commits March 8, 2026 09:48

flint disable directive

f2a567f

pnpm dedupe

ec59a49

vercel bot deployed to Preview March 8, 2026 06:56 View deployment

adjust ranges for fixes and suggestions

52e86c8

vercel bot deployed to Preview March 8, 2026 07:10 View deployment

auvred requested a review from lishaduck March 8, 2026 14:37

lishaduck approved these changes Mar 8, 2026

View reviewed changes

ember -> gjs,gts

64644d3

vercel bot deployed to Preview March 8, 2026 15:29 View deployment

lishaduck mentioned this pull request Mar 8, 2026

💬 Discussion: "Diagnostics" for other languages #1772

Open

auvred added 2 commits March 9, 2026 13:05

Merge branch 'main' into volar-language

eef0ad9

bump tsdown

09abd33

vercel bot deployed to Preview March 9, 2026 10:10 View deployment

auvred merged commit 0702aa2 into main Mar 10, 2026
8 checks passed

auvred deleted the volar-language branch March 10, 2026 18:34

auvred mentioned this pull request Mar 10, 2026

chore(volar-language): switch tsdown's devExports away from @flint.fyi/source #2409

Merged

3 tasks

lishaduck mentioned this pull request Mar 11, 2026

style: prefer nullThrows a bit more #2417

Merged

3 tasks

Conversation

auvred commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

Overview

Uh oh!

changeset-bot bot commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

lishaduck commented Feb 14, 2026

Uh oh!

Uh oh!

lishaduck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lishaduck Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JoshuaKGoldberg left a comment

Choose a reason for hiding this comment

Uh oh!

auvred commented Mar 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg commented Mar 8, 2026

Uh oh!

auvred commented Mar 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

auvred commented Feb 14, 2026 •

edited

Loading

changeset-bot bot commented Feb 14, 2026 •

edited

Loading

vercel bot commented Feb 14, 2026 •

edited

Loading

lishaduck Mar 7, 2026 •

edited

Loading