perf(start-plugin-core): scan only rebuilt modules for Rsbuild import protection in dev

.changeset/rsbuild-incremental-import-protection.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/start-plugin-core': patch
+---
+
+Speed up Rsbuild import protection. Scans read the imports of only those modules that can report a violation, skip violations that were already reported, and development rebuilds check only rebuilt modules and their importers.

e2e/react-start/import-protection/tests/import-protection.spec.ts

@@ -1,10 +1,11 @@
 import path from 'node:path'
 import fs from 'node:fs'
 import { expect } from '@playwright/test'
-import { test } from '@tanstack/router-e2e-utils'
+import { createHmrFileEditor, test } from '@tanstack/router-e2e-utils'
 import { getViolationArtifactName } from './violations.utils'
 import type { Violation } from './violations.utils'
 import type { Page } from '@playwright/test'
+import type { RsbuildPlugin } from '@rsbuild/core'
 
 const toolchain = process.env.E2E_TOOLCHAIN ?? 'vite'
 const fixtureRoot = path.resolve(import.meta.dirname, '..')
@@ -137,6 +138,185 @@ test.beforeEach(({}, testInfo) => {
   }
 })
 
+test('development rebuilds check changed modules, importers and re-resolved imports', async () => {
+  test.skip(toolchain !== 'rsbuild', 'Rsbuild incremental scan')
+  test.setTimeout(120_000)
+  const [{ createRsbuild }, { pluginReact }, { tanstackStart }] =
+    await Promise.all([
+      import('@rsbuild/core'),
+      import('@rsbuild/plugin-react'),
+      import('@tanstack/react-start/plugin/rsbuild'),
+    ])
+  const sourceDir = path.join(fixtureRoot, 'src/import-protection-hmr')
+  const targetFile = path.join(sourceDir, 'target.ts')
+  const markedFile = path.join(sourceDir, 'marked.ts')
+  const packageFile = path.join(sourceDir, 'package.json')
+  const perfFile = test.info().outputPath('import-protection-perf.json')
+  const target = (label: string) => `import { marked } from './marked'
+import { value } from '#target'
+
+export const label = () => \`${label} \${marked()} \${value}\`
+`
+  const importMap = (file: string) =>
+    JSON.stringify({ imports: { '#target': file } })
+
+  const editor = createHmrFileEditor({
+    rootDir: fixtureRoot,
+    files: { index: 'src/routes/index.tsx' },
+  })
+  await editor.capturePromise
+  const previousPerf = process.env.TSR_IMPORT_PROTECTION_PERF
+  const previousPerfFile = process.env.TSR_IMPORT_PROTECTION_PERF_FILE
+  const clientWarnings: Array<string> = []
+  let compileWaiters: Array<() => void> = []
+  const nextCompile = () =>
+    new Promise<void>((resolve) => {
+      compileWaiters.push(resolve)
+    })
+  const editAndCompile = async (file: string, source: string) => {
+    const compiled = nextCompile()
+    await fs.promises.writeFile(file, source)
+    await compiled
+  }
+  const readCounter = async (name: string) =>
+    (
+      JSON.parse(await fs.promises.readFile(perfFile, 'utf8')) as {
+        counters: Record<string, number | undefined>
+      }
+    ).counters[name] ?? 0
+
+  try {
+    await fs.promises.mkdir(sourceDir, { recursive: true })
+    await fs.promises.writeFile(packageFile, importMap('./safe.ts'))
+    await fs.promises.writeFile(targetFile, target('safe'))
+    await fs.promises.writeFile(
+      markedFile,
+      `export const marked = () => 'plain'\n`,
+    )
+    await fs.promises.writeFile(
+      path.join(sourceDir, 'safe.ts'),
+      `export const value = 'safe'\n`,
+    )
+    await fs.promises.writeFile(
+      path.join(sourceDir, 'secret.server.ts'),
+      `export const value = 'secret'\n`,
+    )
+    await editor.replaceText(
+      'index',
+      `import { createFileRoute, useHydrated } from '@tanstack/react-router'`,
+      `import { createFileRoute, useHydrated } from '@tanstack/react-router'
+import { label } from '../import-protection-hmr/target'
+import '../import-protection-hmr/secret.server'`,
+    )
+    await editor.replaceText(
+      'index',
+      '<h1 data-testid="heading">Import Protection E2E</h1>',
+      '<h1 data-testid="heading">Import Protection E2E</h1>\n      <p>{label()}</p>',
+    )
+    process.env.TSR_IMPORT_PROTECTION_PERF = '1'
+    process.env.TSR_IMPORT_PROTECTION_PERF_FILE = perfFile
+
+    const rsbuild = await createRsbuild({
+      cwd: fixtureRoot,
+      rsbuildConfig: {
+        root: fixtureRoot,
+        plugins: [
+          pluginReact(),
+          tanstackStart(),
+          {
+            name: 'observe-import-protection-rebuilds',
+            setup(api) {
+              api.onAfterEnvironmentCompile(({ environment, stats }) => {
+                if (environment.name === 'client' && stats) {
+                  for (const warning of stats.compilation.warnings) {
+                    clientWarnings.push(warning.message)
+                  }
+                }
+              })
+              api.onAfterDevCompile(() => {
+                const waiters = compileWaiters
+                compileWaiters = []
+                for (const resolve of waiters) {
+                  resolve()
+                }
+              })
+            },
+          } satisfies RsbuildPlugin,
+        ],
+      },
+    })
+    const initialCompile = nextCompile()
+    const server = await rsbuild.createDevServer({ getPortSilently: true })
+    const targetWarnings = () =>
+      clientWarnings.filter((warning) =>
+        warning.includes('Importer: src/import-protection-hmr/target'),
+      )
+    try {
+      await initialCompile
+      expect(targetWarnings()).toEqual([])
+
+      // Already-reported fixture violations don't block the fast path.
+      await editAndCompile(targetFile, target('edited'))
+      expect(targetWarnings()).toEqual([])
+      expect(
+        await readCounter('processAssets.incremental.modules'),
+      ).toBeGreaterThan(0)
+
+      // Rebuilding a module with reported violations doesn't enrich them again.
+      const enriched = await readCounter('violations.enriched')
+      const incremental = await readCounter('processAssets.incremental.modules')
+      const indexCompiled = nextCompile()
+      await editor.replaceText(
+        'index',
+        'Import Protection E2E</h1>',
+        'Import Protection E2E!</h1>',
+      )
+      await indexCompiled
+      expect(await readCounter('violations.enriched')).toBe(enriched)
+      expect(
+        await readCounter('processAssets.incremental.modules'),
+      ).toBeGreaterThan(incremental)
+
+      // Re-pointing the import map rebuilds no module.
+      await editAndCompile(packageFile, importMap('./secret.server.ts'))
+      expect(
+        targetWarnings().some(
+          (warning) =>
+            warning.includes('Import: "#target"') &&
+            warning.includes('secret.server'),
+        ),
+      ).toBe(true)
+
+      await editAndCompile(
+        markedFile,
+        `import '@tanstack/react-start/server-only'\n\nexport const marked = () => 'server'\n`,
+      )
+      expect(
+        clientWarnings.some(
+          (warning) =>
+            warning.includes('marked') &&
+            warning.includes('@tanstack/react-start/server-only'),
+        ),
+      ).toBe(true)
+    } finally {
+      await server.close()
+    }
+  } finally {
+    for (const [name, value] of [
+      ['TSR_IMPORT_PROTECTION_PERF', previousPerf],
+      ['TSR_IMPORT_PROTECTION_PERF_FILE', previousPerfFile],
+    ] as const) {
+      if (value === undefined) {
+        delete process.env[name]
+      } else {
+        process.env[name] = value
+      }
+    }
+    await editor.restoreFiles()
+    await fs.promises.rm(sourceDir, { recursive: true, force: true })
+  }
+})
+
 test('app loads successfully with mock mode', async ({ page }) => {
   await page.goto('/')
   await expect(page.getByTestId('heading')).toContainText(
@@ -234,6 +414,23 @@ for (const mode of ['build', 'dev'] as const) {
   })
 }
 
+for (const mode of ['build', 'dev'] as const) {
+  test(`client violation traces start at the client entry in ${mode}`, async () => {
+    // Rsbuild skips modules outside the app until a scan finds a violation.
+    test.skip(toolchain !== 'rsbuild', 'Rsbuild scan')
+    const violations = (await readViolations(mode)).filter(
+      (v) => v.envType === 'client',
+    )
+
+    expect(violations.length).toBeGreaterThan(0)
+    for (const violation of violations) {
+      expect(violation.trace[0]?.file.replace(/\\/g, '/')).toMatch(
+        /\/default-entry\/client\.tsx$/,
+      )
+    }
+  })
+}
+
 test('deep trace includes full chain', async () => {
   const violations = await readViolations('build')
 

packages/start-plugin-core/src/rsbuild/INTERNALS-import-protection.md

@@ -33,8 +33,9 @@ object:
 
 1. `onBeforeBuild`
 2. `onBeforeDevCompile`
-3. `modifyRspackConfig`
-4. `processAssets(..., { stage: 'report' })`
+3. `onBeforeEnvironmentCompile`
+4. `modifyRspackConfig`
+5. `processAssets(..., { stage: 'report' })`
 
 `modifyRspackConfig` installs both the virtual-modules plugin and the
 environment-scoped import-protection post-loader.
@@ -108,27 +109,46 @@ adapter queues them and flushes during compilation setup.
 
 It reconstructs the final view of the compilation from Rspack data by:
 
-1. snapshotting each module and its outgoing connections
+1. snapshotting each module that can report a violation and its outgoing
+   connections
 2. collecting specifier and file violations plus possible marker modules
 3. deduplicating marker modules and validating their persisted metadata
-4. returning early when no violations remain
-5. building the `ImportGraph` and diagnostic indexes only when needed
+4. with `log: 'once'`, dropping violations this environment already reported,
+   because reporting would discard them after enrichment
+5. returning early when no violations remain
+6. snapshotting the remaining modules and building the `ImportGraph` and
+   diagnostic indexes only when needed
 
 Each `RspackModuleGraphNode` stores a module and its imported modules. Missing and
 errored target modules are skipped.
 Connections are not filtered by `getActiveState()` because inactive connections
 can still carry diagnostic evidence. Duplicate connections to the same target
 module collapse to one.
 
-Snapshotting does not apply source-file eligibility. Intermediate modules remain
-available for entry-to-violation traces, while the scanner applies importer and
-rule checks. Normalized resource ids are used for rules, traces, and diagnostics;
-`resourceResolveData.path` is preferred for original-source lookup.
+Detection snapshots only modules that can report a violation: parseable source
+files that pass the importer checks. In large apps most modules live in
+`node_modules` and fail them, so a clean compilation never reads their
+connections. Normalized resource ids are used for rules, traces, and
+diagnostics; `resourceResolveData.path` is preferred for original-source lookup.
 
-When violations exist, the adapter replays the snapshot to build `ImportGraph`;
-it does not query outgoing connections again. A clean compilation avoids entry
+When violations exist, the adapter snapshots the remaining modules, because
+entry-to-violation traces pass through them, and replays the full snapshot in
+module order to build `ImportGraph`. A clean compilation avoids entry
 traversal, graph indexes, and module-source loading.
 
+A scan is clean when it leaves no violation to report: none were found, or, with
+`log: 'once'`, every one was already reported. In development, a compilation
+that directly follows a clean scan of the same environment first scans only
+`compilation.builtModules`, their direct importers (a rebuilt dependency can
+gain a marker without its importer changing), and entry modules, with the same
+eligibility filter. It falls back to the full scan when it finds an unreported
+violation, when the previous compilation skipped the report stage, or when a
+changed or removed file is not the resource of a rebuilt module. Such files,
+for example `package.json` import maps or `tsconfig.json` paths, can re-resolve
+imports in modules that were not rebuilt. Changed watched directories
+(`compilation.contextDependencies`, such as Tailwind content paths) are ignored
+because the changed files inside them are listed too.
+
 Diagnostic enrichment is lazy. The transform-result provider reads
 `module.originalSource().sourceAndMap()` when available. It gets original code
 from sourcemap `sourcesContent`, then falls back to