fix(unplugin-dts): stabilize Vue program lifecycle (#488)

* perf(unplugin-dts): optimize watch rebuilds

* chore(ci): diagnose Windows worker exits

* test(unplugin-dts): canonicalize Windows watch paths

* fix(unplugin-dts): stabilize Vue program lifecycle

Author: qmhc

packages/unplugin-dts/src/core/processor/index.ts

@@ -20,6 +20,9 @@ export interface ProgramProcessor {
   ) => ts.ParsedCommandLine,
   createProgram: typeof ts.createProgram,
   createCompilerHost?: (options: ts.CompilerOptions) => VersionedCompilerHost,
+  needsModuleResolutionFallback?: boolean,
+  isInternalSourceFile?: (sourceFile: ts.SourceFile) => boolean,
+  releaseSourceFile?: (program: ts.Program, fileName: string) => void,
 }
 
 export async function loadProgramProcessor(type: 'vue' | 'ts' = 'ts'): Promise<ProgramProcessor> {

packages/unplugin-dts/src/core/processor/vue.ts

@@ -1,4 +1,4 @@
-import { dirname } from 'node:path'
+import { dirname, parse as pathParse, relative } from 'node:path'
 
 import {
   createVueLanguagePlugin,
@@ -8,7 +8,44 @@ import {
 
 import { proxyCreateProgram } from '@volar/typescript'
 import ts from '../ts-loader.cjs'
-import { slash } from '../utils'
+import { normalizePath, resolve, slash } from '../utils'
+
+const internalSourceFiles = new WeakSet<ts.SourceFile>()
+const programSourceFileReleasers = new WeakMap<ts.Program, (fileName: string) => void>()
+interface VueLanguage {
+  scripts: { delete(fileName: string): void },
+}
+const programLanguages = new WeakMap<ts.Program, VueLanguage>()
+let activeLanguage: VueLanguage | undefined
+
+export const needsModuleResolutionFallback = true
+
+interface VueRootPathApi {
+  parse: typeof import('node:path').parse,
+  relative: typeof import('node:path').relative,
+  resolve: typeof import('node:path').resolve,
+}
+
+export function groupVueRootNames(
+  vueRootNames: readonly string[],
+  projectDirectory: string,
+  pathApi: VueRootPathApi = { parse: pathParse, relative, resolve },
+) {
+  projectDirectory = pathApi.resolve(projectDirectory)
+  const projectVolume = pathApi.parse(projectDirectory).root
+  const groups = new Map<string, string[]>()
+
+  for (const rootName of vueRootNames) {
+    const fileName = pathApi.resolve(projectDirectory, rootName)
+    const fileVolume = pathApi.parse(fileName).root
+    const directory = pathApi.relative(projectVolume, fileVolume) ? fileVolume : projectDirectory
+    const files = groups.get(directory) ?? []
+    files.push(fileName)
+    groups.set(directory, files)
+  }
+
+  return [...groups].map(([directory, rootNames]) => ({ directory, rootNames }))
+}
 
 export function createParsedCommandLine(
   _ts: typeof ts,
@@ -42,7 +79,101 @@ export function createParsedCommandLine(
   }
 }
 
-export const createProgram = proxyCreateProgram(ts, ts.createProgram, (ts, options) => {
+function prepareVueProgramOptions(options: ts.CreateProgramOptions) {
+  const originalHost = options.host
+  if (!originalHost) return { options }
+
+  const vueRootNames = options.rootNames.filter(fileName => fileName.endsWith('.vue'))
+
+  const projectDirectory =
+    typeof options.options.configFilePath === 'string'
+      ? dirname(options.options.configFilePath)
+      : originalHost.getCurrentDirectory()
+  const syntheticRoots = new Map<
+    string,
+    { fileName: string, text: string, sourceFile?: ts.SourceFile }
+  >()
+  for (const group of groupVueRootNames(vueRootNames, projectDirectory)) {
+    let sequence = 0
+    let syntheticFileName = resolve(group.directory, '__unplugin_dts_vue_root__.d.ts')
+    while (originalHost.fileExists(syntheticFileName)) {
+      syntheticFileName = resolve(group.directory, `__unplugin_dts_vue_root_${++sequence}__.d.ts`)
+    }
+
+    const text = group.rootNames
+      .map(fileName => {
+        const path = slash(relative(group.directory, fileName))
+        const moduleName = path.startsWith('.') ? path : `./${path}`
+        return `import ${JSON.stringify(moduleName)}`
+      })
+      .join('\n')
+    const canonicalFileName = normalizePath(originalHost.getCanonicalFileName(syntheticFileName))
+    syntheticRoots.set(canonicalFileName, { fileName: syntheticFileName, text })
+  }
+
+  const getSourceFile = originalHost.getSourceFile.bind(originalHost)
+  const fileExists = originalHost.fileExists.bind(originalHost)
+  const readFile = originalHost.readFile.bind(originalHost)
+  const releasedSourceFiles = new Set<string>()
+  const getCanonicalFileName = (fileName: string) =>
+    normalizePath(originalHost.getCanonicalFileName(fileName))
+  const getSyntheticRoot = (fileName: string) => syntheticRoots.get(getCanonicalFileName(fileName))
+  const host: ts.CompilerHost = {
+    ...originalHost,
+    fileExists(fileName) {
+      return !!getSyntheticRoot(fileName) || fileExists(fileName)
+    },
+    readFile(fileName) {
+      return getSyntheticRoot(fileName)?.text ?? readFile(fileName)
+    },
+    getSourceFile(fileName, languageVersionOrOptions, onError, shouldCreateNewSourceFile) {
+      if (releasedSourceFiles.has(getCanonicalFileName(fileName))) return undefined
+
+      const syntheticRoot = getSyntheticRoot(fileName)
+      if (!syntheticRoot) {
+        return getSourceFile(fileName, languageVersionOrOptions, onError, shouldCreateNewSourceFile)
+      }
+
+      if (!syntheticRoot.sourceFile || shouldCreateNewSourceFile) {
+        syntheticRoot.sourceFile = ts.createSourceFile(
+          syntheticRoot.fileName,
+          syntheticRoot.text,
+          languageVersionOrOptions,
+          true,
+          ts.ScriptKind.TS,
+        )
+        internalSourceFiles.add(syntheticRoot.sourceFile)
+      }
+      return syntheticRoot.sourceFile
+    },
+  }
+
+  const preparedOptions: ts.CreateProgramOptions = {
+    ...options,
+    host,
+    rootNames: [...options.rootNames, ...[...syntheticRoots.values()].map(root => root.fileName)],
+  }
+  return {
+    options: preparedOptions,
+    releaseSourceFile(fileName: string) {
+      const canonicalFileName = getCanonicalFileName(fileName)
+      releasedSourceFiles.add(canonicalFileName)
+      try {
+        preparedOptions.host?.getSourceFile(fileName, ts.ScriptTarget.Latest)
+      } finally {
+        releasedSourceFiles.delete(canonicalFileName)
+      }
+    },
+  }
+}
+
+/**
+ * 通过仅存在于 CompilerHost 的声明 root 引入未引用 SFC。
+ *
+ * TypeScript 会在 rootNames 中保留任意扩展文件，却不会主动为它们创建 SourceFile；
+ * 虚拟声明 root 让 Volar 继续使用自身的模块解析和 service-script 生成路径。
+ */
+const createVueProgram = proxyCreateProgram(ts, ts.createProgram, (ts, options) => {
   const { configFilePath } = options.options
   const vueOptions =
     typeof configFilePath === 'string'
@@ -55,5 +186,29 @@ export const createProgram = proxyCreateProgram(ts, ts.createProgram, (ts, optio
     vueOptions,
     id => id,
   )
-  return { languagePlugins: [vueLanguagePlugin] }
+  return {
+    languagePlugins: [vueLanguagePlugin],
+    setup(instance) {
+      activeLanguage = instance
+    },
+  }
 })
+
+export const createProgram = ((options: ts.CreateProgramOptions) => {
+  const prepared = prepareVueProgramOptions(options)
+  const program = createVueProgram(prepared.options)
+  if (activeLanguage) programLanguages.set(program, activeLanguage)
+  if (prepared.releaseSourceFile) {
+    programSourceFileReleasers.set(program, prepared.releaseSourceFile)
+  }
+  return program
+}) as typeof ts.createProgram
+
+export function isInternalSourceFile(sourceFile: ts.SourceFile) {
+  return internalSourceFiles.has(sourceFile)
+}
+
+export function releaseSourceFile(program: ts.Program, fileName: string) {
+  programLanguages.get(program)?.scripts.delete(fileName)
+  programSourceFileReleasers.get(program)?.(fileName)
+}

packages/unplugin-dts/src/core/runtime.ts

@@ -274,10 +274,14 @@ export class Runtime {
     }
     const rawCompilerOptions = content?.raw.compilerOptions || {}
 
-    if (content?.fileNames.find(name => name.endsWith('.vue'))) {
+    if (
+      programProcessor.needsModuleResolutionFallback ||
+      content?.fileNames.find(name => name.endsWith('.vue'))
+    ) {
       // (#277) A patch for Vue
-      // If user don't specify `moduleResolution` in top config file,
-      // declaration of Vue files will be inferred to `any` type.
+      // If user doesn't specify `moduleResolution` in the top config file,
+      // declarations of Vue files can be inferred as `any`, including Vue files
+      // that are reached only through TypeScript roots.
       setModuleResolution(compilerOptions)
     }
 
@@ -578,6 +582,9 @@ export class Runtime {
 
   private rebuildFresh(previousProgram: ts.Program, reason: string) {
     const internals = getRuntimeInternals(this)
+    const previousHost = this.host
+    const previousLogger = this.logger
+    const preserveVueHost = !!internals.programProcessor.releaseSourceFile && reason !== 'config'
     if (
       reason === 'create' ||
       reason === 'delete' ||
@@ -589,7 +596,15 @@ export class Runtime {
       internals.cleanStaleOutputs = true
     }
     const rebuildProgram = this.rebuildProgram
-    const fresh = new Runtime(internals.runtimeOptions, internals.programProcessor)
+    const fresh = new Runtime(
+      preserveVueHost
+        ? {
+          ...internals.runtimeOptions,
+          logger: { info() {}, warn() {}, error() {} },
+        }
+        : internals.runtimeOptions,
+      internals.programProcessor,
+    )
     const freshInternals = getRuntimeInternals(fresh)
     Object.assign(this, fresh)
     Object.defineProperty(this, 'rebuildProgram', {
@@ -600,6 +615,21 @@ export class Runtime {
     })
     internals.projectReferences = freshInternals.projectReferences
     internals.configWatchDirectories = freshInternals.configWatchDirectories
+    if (preserveVueHost) {
+      this.host = previousHost
+      this.logger = previousLogger
+      this.program = internals.programProcessor.createProgram({
+        host: previousHost,
+        rootNames: this.rootNames,
+        options: this.compilerOptions,
+        projectReferences: internals.projectReferences,
+      })
+      this.programSourceFilesByCanonicalName = undefined
+      this.watchDirectoryNames = undefined
+      this.watchTargets = undefined
+      this.refreshDiagnostics()
+    }
+    this.releaseRemovedProgramSourceFiles(previousProgram)
     this.measureProgramReuse(previousProgram, 'fresh', reason, {
       entries: 0,
       hits: 0,
@@ -608,6 +638,22 @@ export class Runtime {
     })
   }
 
+  private releaseRemovedProgramSourceFiles(previousProgram: ts.Program) {
+    const { releaseSourceFile } = getRuntimeInternals(this).programProcessor
+    if (!releaseSourceFile) return
+
+    const currentSourceFiles = new Set(
+      this.program
+        .getSourceFiles()
+        .map(sourceFile => this.getCanonicalFileName(sourceFile.fileName)),
+    )
+    for (const sourceFile of previousProgram.getSourceFiles()) {
+      if (!currentSourceFiles.has(this.getCanonicalFileName(sourceFile.fileName))) {
+        releaseSourceFile(previousProgram, sourceFile.fileName)
+      }
+    }
+  }
+
   private rebuildProgramWithCurrentHost(previousProgram: ts.Program, reason: string) {
     const internals = getRuntimeInternals(this)
     this.program = internals.programProcessor.createProgram({
@@ -620,6 +666,7 @@ export class Runtime {
     this.watchDirectoryNames = undefined
     this.watchTargets = undefined
     this.refreshDiagnostics()
+    this.releaseRemovedProgramSourceFiles(previousProgram)
     this.measureProgramReuse(previousProgram, 'fresh', reason, {
       entries: 0,
       hits: 0,
@@ -748,7 +795,10 @@ export class Runtime {
     }
     if (this.configPath) files.add(normalizePath(this.configPath))
 
+    const { programProcessor } = getRuntimeInternals(this)
     for (const sourceFile of this.program.getSourceFiles()) {
+      if (programProcessor.isInternalSourceFile?.(sourceFile)) continue
+
       if (!this.program.isSourceFileDefaultLibrary(sourceFile)) {
         files.add(normalizePath(sourceFile.fileName))
 
@@ -1024,9 +1074,11 @@ export class Runtime {
       record && emittedFiles.set(path, content)
     }
 
+    const { programProcessor } = getRuntimeInternals(this)
     const sourceFiles = this.program.getSourceFiles()
 
     for (const sourceFile of sourceFiles) {
+      if (programProcessor.isInternalSourceFile?.(sourceFile)) continue
       if (!this.filter(sourceFile.fileName)) continue
 
       if ((copyDtsFiles || bundleTypes) && dtsRE.test(sourceFile.fileName)) {

packages/unplugin-dts/src/core/utils.ts

@@ -433,15 +433,20 @@ export function setModuleResolution(options: CompilerOptions) {
       moduleResolution = ts.ModuleResolutionKind.NodeNext
       break
     default:
-      moduleResolution = ts.version.startsWith('5')
-        ? ts.ModuleResolutionKind.Bundler
-        : ts.ModuleResolutionKind.Classic
+      moduleResolution = resolveESModuleResolution(ts.ModuleResolutionKind)
       break
   }
 
   options.moduleResolution = moduleResolution
 }
 
+export function resolveESModuleResolution(moduleResolutionKind: {
+  Classic: ts.ModuleResolutionKind,
+  Bundler?: ts.ModuleResolutionKind,
+}) {
+  return moduleResolutionKind.Bundler ?? moduleResolutionKind.Classic
+}
+
 export function editSourceMapDir(content: string, fromDir: string, toDir: string) {
   const relativeOutDir = relative(fromDir, toDir)
 

packages/unplugin-dts/tests/runtime-ts6.spec.ts

@@ -1,6 +1,7 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { resolve } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 // typescript-v6 is "npm:typescript@^6" — provides real TS 6 compilation behaviour
@@ -104,4 +105,48 @@ describe('runtime tests (TypeScript 6)', () => {
     expect(content).toContain('foo')
     expect(content.trim()).not.toBe('export { }')
   }, 20_000)
+
+  it('should preserve Vue declarations reached only from a TypeScript root', async () => {
+    tempDir = mkdtempSync(resolve(tmpdir(), 'unplugin-dts-'))
+    mkdirSync(resolve(tempDir, 'src'))
+    symlinkSync(
+      resolve(dirname(fileURLToPath(import.meta.url)), '../../../playground/vue-vite/node_modules'),
+      resolve(tempDir, 'node_modules'),
+      process.platform === 'win32' ? 'junction' : 'dir',
+    )
+    writeFileSync(
+      resolve(tempDir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          target: 'ESNext',
+          module: 'ESNext',
+          strict: true,
+          declaration: true,
+        },
+        files: ['src/index.ts'],
+      }),
+    )
+    writeFileSync(
+      resolve(tempDir, 'src/App.vue'),
+      '<script setup lang="ts">\nconst value = 1\ndefineExpose({ value })\n</script>\n',
+    )
+    writeFileSync(resolve(tempDir, 'src/index.ts'), "export { default as App } from './App.vue'\n")
+
+    const runtime = await Runtime.toInstance({
+      processor: 'vue',
+      root: tempDir,
+      tsconfigPath: 'tsconfig.json',
+    })
+    const declarations = new Map<string, string>()
+    runtime
+      .getProgram()
+      .emit(undefined, (fileName, content) => declarations.set(fileName, content), undefined, true)
+    const vueDeclaration = [...declarations].find(([fileName]) =>
+      fileName.endsWith('App.vue.d.ts'),
+    )?.[1]
+
+    expect(runtime.getDiagnostics()).toEqual([])
+    expect(vueDeclaration).toContain('DefineComponent')
+    expect(vueDeclaration).not.toContain('__VLS_export: any')
+  })
 })