perf(unplugin-dts): optimize watch rebuilds (#487)

* perf(unplugin-dts): optimize watch rebuilds

* chore(ci): diagnose Windows worker exits

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

Author: qmhc

docs/en/usage.md

@@ -192,6 +192,75 @@ await build({
 })
 ```
 
+## Watch Mode
+
+Keep source directories separate from bundler and declaration output directories. This is the
+recommended layout for watch mode because a bundler can observe source-tree additions, deletions,
+and renames without also watching generated files:
+
+```text
+project/
+├── src/
+│   └── index.ts
+├── dist/
+└── types/
+```
+
+Vite, Webpack, and Rspack can discover newly added files that match your TypeScript configuration
+when the recursive source watch does not resolve into generated output. If an output directory is
+the source directory, or a realpath/symlink makes it overlap existing sources, the plugin fails
+closed: exact existing source files remain watched, but an unreferenced file addition may require a
+watcher restart. This prevents generated files from creating a rebuild loop.
+
+When Webpack or Rspack starts from a clean project and creates nested output directories, Watchpack
+may perform one initial compensating rebuild. Generated output is ignored after that bootstrap, so
+steady-state source additions, deletions, and renames do not form an output feedback loop.
+
+After a source is deleted or renamed, the plugin removes declaration paths that it wrote during the
+previous build but that are absent from the current complete output snapshot. Other files in the
+output directory are left unchanged.
+
+Pure Rollup watch cannot safely register a watched source directory that also contains its outputs
+without help from the calling configuration. In that layout, an unreferenced new file may not
+trigger a rebuild. Prefer moving sources into `src/`. If changing the layout is not possible,
+configure all generated output directories as ignored before calling `rollup.watch` and explicitly
+watch the type source directory:
+
+```js
+import { resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { defineConfig } from 'rollup'
+import typescript from '@rollup/plugin-typescript'
+import dts from 'unplugin-dts/rollup'
+
+const projectRoot = resolve(fileURLToPath(import.meta.url), '..')
+const outputDir = resolve(projectRoot, 'dist')
+
+const watchTypeRoot = {
+  name: 'watch-type-root',
+  buildStart() {
+    if (this.meta.watchMode) this.addWatchFile(projectRoot)
+  },
+}
+
+export default defineConfig({
+  input: resolve(projectRoot, 'index.ts'),
+  output: { dir: outputDir, format: 'es' },
+  watch: {
+    chokidar: {
+      ignored: path => path === outputDir || path.startsWith(`${outputDir}${sep}`),
+    },
+  },
+  plugins: [watchTypeRoot, typescript(), dts({ root: projectRoot })],
+})
+```
+
+If declarations use a different directory, or you have multiple outputs, include every generated
+directory in the ignored predicate. Rolldown currently does not discover unreferenced files created
+after watch starts through a directory `addWatchFile`. Import or reference the new file from an
+existing watched module, or restart the watcher after adding, deleting, or renaming such files.
+
 ## Bundling Types
 
 By default, the generated declaration files follow the source structure.

docs/zh/usage.md

@@ -192,6 +192,69 @@ await build({
 })
 ```
 
+## Watch 模式
+
+推荐将源码目录与 bundler、声明文件的输出目录分开。这样构建工具可以监听源码树中的新增、
+删除和重命名，又不会同时监听生成文件：
+
+```text
+project/
+├── src/
+│   └── index.ts
+├── dist/
+└── types/
+```
+
+当递归源码监听不会解析到生成输出时，Vite、Webpack 和 Rspack 可以发现符合 TypeScript
+配置的新文件。如果输出目录就是源码目录，或者 realpath/symlink 使它与已有源码重叠，插件会
+采用 fail-close：继续精确监听已有源码，但新增未引用文件后可能需要重启 watcher。这可以避免
+生成文件形成重新构建循环。
+
+当 Webpack 或 Rspack 从干净项目启动并创建嵌套输出目录时，Watchpack 可能执行一次初始补偿
+构建。bootstrap 完成后生成输出会被忽略，因此稳态下的源码新增、删除和重命名不会形成输出
+反馈循环。
+
+源码删除或重命名后，插件会清理上一轮由自身写出、但已不在当前完整输出快照中的声明路径；
+输出目录中的其他文件不会被清理。
+
+纯 Rollup watch 无法在没有调用方配合的情况下安全监听同时包含输出的源码目录。这种布局下，
+新增但未被引用的文件可能不会触发重新构建。优先将源码移入 `src/`。如果暂时不能调整布局，
+请在调用 `rollup.watch` 前忽略所有生成目录，并显式监听类型源码目录：
+
+```js
+import { resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { defineConfig } from 'rollup'
+import typescript from '@rollup/plugin-typescript'
+import dts from 'unplugin-dts/rollup'
+
+const projectRoot = resolve(fileURLToPath(import.meta.url), '..')
+const outputDir = resolve(projectRoot, 'dist')
+
+const watchTypeRoot = {
+  name: 'watch-type-root',
+  buildStart() {
+    if (this.meta.watchMode) this.addWatchFile(projectRoot)
+  },
+}
+
+export default defineConfig({
+  input: resolve(projectRoot, 'index.ts'),
+  output: { dir: outputDir, format: 'es' },
+  watch: {
+    chokidar: {
+      ignored: path => path === outputDir || path.startsWith(`${outputDir}${sep}`),
+    },
+  },
+  plugins: [watchTypeRoot, typescript(), dts({ root: projectRoot })],
+})
+```
+
+如果声明文件使用不同目录，或配置了多个输出目录，需要在 ignored 判断中覆盖每一个生成目录。
+Rolldown 当前无法通过目录 `addWatchFile` 发现 watch 启动后创建的未引用文件。请从已有的受监听
+模块中导入或引用新文件，或者在新增、删除、重命名这类文件后重启 watcher。
+
 ## 打包类型
 
 默认情况下，生成的类型文件会跟随源文件的结构。

packages/unplugin-dts/package.json

@@ -123,6 +123,7 @@
     "@volar/typescript": "^2.4.26",
     "compare-versions": "^6.1.1",
     "debug": "^4.4.0",
+    "glob-to-regexp": "0.4.1",
     "kolorist": "^1.8.0",
     "local-pkg": "^1.1.1",
     "magic-string": "^0.30.17",

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

@@ -0,0 +1,130 @@
+import { performance } from 'node:perf_hooks'
+
+export type BuildHook = 'buildStart' | 'watchChange' | 'transform' | 'writeBundle'
+
+interface BuildInterval {
+  hook: BuildHook,
+  start: number,
+  end: number,
+}
+
+interface BuildIntervalToken {
+  hook: BuildHook,
+  start: number,
+  generation: number,
+}
+
+export interface BuildTimingSummary {
+  wallMs: number,
+  attributedMs: number,
+  unattributedMs: number,
+  buildStartMs: number,
+  watchChangeMs: number,
+  transformSumMs: number,
+  transformUnionMs: number,
+  transformMaxConcurrency: number,
+  transformOverlapMs: number,
+  writeBundleMs: number,
+}
+
+function measureIntervals(intervals: readonly BuildInterval[]) {
+  if (intervals.length === 0) {
+    return { sum: 0, union: 0, maxConcurrency: 0 }
+  }
+
+  const sum = intervals.reduce((total, interval) => total + interval.end - interval.start, 0)
+  const points = intervals.flatMap(interval => [
+    { time: interval.start, delta: 1 },
+    { time: interval.end, delta: -1 },
+  ])
+
+  points.sort((left, right) => {
+    if (left.time === right.time) return left.delta - right.delta
+    return left.time - right.time
+  })
+
+  let active = 0
+  let maxConcurrency = 0
+  let previous = points[0].time
+  let union = 0
+
+  for (const point of points) {
+    if (active > 0) union += point.time - previous
+    active += point.delta
+    maxConcurrency = Math.max(maxConcurrency, active)
+    previous = point.time
+  }
+
+  return { sum, union, maxConcurrency }
+}
+
+/**
+ * 跟踪一次声明构建周期内的插件 hook 区间。
+ *
+ * 逐次耗时之和只用于解释工作量；用户可感知耗时使用单调时钟墙钟，
+ * 并发 transform 的归因使用区间并集，避免重复计算重叠时间。
+ */
+export class BuildTimeTracker {
+  private readonly now: () => number
+  private generation = 0
+  private cycleStart = 0
+  private intervals: BuildInterval[] = []
+
+  constructor(now: () => number = () => performance.now()) {
+    this.now = now
+    this.reset()
+  }
+
+  reset(start = this.now()) {
+    this.generation++
+    this.cycleStart = start
+    this.intervals = []
+  }
+
+  begin(hook: BuildHook): BuildIntervalToken {
+    return { hook, start: this.now(), generation: this.generation }
+  }
+
+  end(token: BuildIntervalToken) {
+    if (token.generation !== this.generation) return
+
+    const end = this.now()
+    this.intervals.push({ hook: token.hook, start: token.start, end })
+  }
+
+  async track<T>(hook: BuildHook, action: () => Promise<T>): Promise<T> {
+    const interval = this.begin(hook)
+
+    try {
+      return await action()
+    } finally {
+      this.end(interval)
+    }
+  }
+
+  getIntervals(): readonly BuildInterval[] {
+    return [...this.intervals].sort((left, right) => left.start - right.start)
+  }
+
+  summarize(end = this.now()): BuildTimingSummary {
+    const intervals = this.getIntervals()
+    const all = measureIntervals(intervals)
+    const phase = (hook: BuildHook) =>
+      measureIntervals(intervals.filter(interval => interval.hook === hook))
+    const transforms = phase('transform')
+    const wallMs = Math.max(0, end - this.cycleStart)
+
+    return {
+      wallMs,
+      attributedMs: all.union,
+      unattributedMs: Math.max(0, wallMs - all.union),
+      buildStartMs: phase('buildStart').union,
+      watchChangeMs: phase('watchChange').union,
+      transformSumMs: transforms.sum,
+      transformUnionMs: transforms.union,
+      transformMaxConcurrency: transforms.maxConcurrency,
+      transformOverlapMs: transforms.sum - transforms.union,
+      writeBundleMs: phase('writeBundle').union,
+    }
+  }
+}

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

@@ -1,12 +1,25 @@
 import type ts from 'typescript'
 
+export interface SourceFileCacheStats {
+  entries: number,
+  hits: number,
+  misses: number,
+  invalidations: number,
+}
+
+export interface VersionedCompilerHost extends ts.CompilerHost {
+  invalidateSourceFile: (fileName: string) => void,
+  getSourceFileCacheStats: () => SourceFileCacheStats,
+}
+
 export interface ProgramProcessor {
   createParsedCommandLine: (
     _ts: typeof ts,
     host: ts.ParseConfigHost,
     configPath: string
   ) => ts.ParsedCommandLine,
   createProgram: typeof ts.createProgram,
+  createCompilerHost?: (options: ts.CompilerOptions) => VersionedCompilerHost,
 }
 
 export async function loadProgramProcessor(type: 'vue' | 'ts' = 'ts'): Promise<ProgramProcessor> {