@tanstack/start-plugin-core 1.167.35 → 1.169.0

package/src/start-compiler/compiler.ts

@@ -13,6 +13,7 @@ import { handleCreateMiddleware } from './handleCreateMiddleware'
 import { handleCreateIsomorphicFn } from './handleCreateIsomorphicFn'
 import { handleEnvOnlyFn } from './handleEnvOnly'
 import { handleClientOnlyJSX } from './handleClientOnlyJSX'
+import { cleanId } from './utils'
 import type {
   CompilationContext,
   DevServerFnModuleSpecifierEncoder,
@@ -259,6 +260,19 @@ function isNestedDirectCallCandidate(node: t.CallExpression): boolean {
   return calleeName !== undefined && DirectCallFactoryNames.has(calleeName)
 }
 
+function isSimpleDirectCallExpression(node: t.CallExpression): boolean {
+  return (
+    t.isIdentifier(node.callee) ||
+    (t.isMemberExpression(node.callee) &&
+      t.isIdentifier(node.callee.object) &&
+      t.isIdentifier(node.callee.property))
+  )
+}
+
+function isTopLevelDirectCallCandidateNode(node: t.CallExpression): boolean {
+  return isSimpleDirectCallExpression(node)
+}
+
 /**
  * Checks if a CallExpression path is a top-level direct-call candidate.
  * Top-level means the call is the init of a VariableDeclarator at program level.
@@ -272,13 +286,7 @@ function isTopLevelDirectCallCandidate(
   const node = path.node
 
   // Must be a simple identifier call or namespace call
-  const isSimpleCall =
-    t.isIdentifier(node.callee) ||
-    (t.isMemberExpression(node.callee) &&
-      t.isIdentifier(node.callee.object) &&
-      t.isIdentifier(node.callee.property))
-
-  if (!isSimpleCall) {
+  if (!isSimpleDirectCallExpression(node)) {
     return false
   }
 
@@ -294,6 +302,12 @@ function isTopLevelDirectCallCandidate(
   return t.isProgram(path.parentPath.parentPath?.parent)
 }
 
+function isDirectCallCandidateForKind(
+  kind: Exclude<LookupKind, 'ClientOnlyJSX'>,
+): boolean {
+  return LookupSetup[kind].type === 'directCall'
+}
+
 export class StartCompiler {
   private moduleCache = new Map<string, ModuleInfo>()
   private initialized = false
@@ -530,7 +544,6 @@ export class StartCompiler {
 
   /**
    * Extracts bindings and exports from an already-parsed AST.
-   * This is the core logic shared by ingestModule and ingestModuleFromAst.
    */
   private extractModuleInfo(
     ast: ReturnType<typeof parseAst>,
@@ -642,10 +655,105 @@ export class StartCompiler {
   }
 
   public invalidateModule(id: string) {
-    // Note: Resolution caches (resolveIdCache, exportResolutionCache) are only
-    // used in build mode where there's no HMR. In dev mode, caching is disabled,
-    // so we only need to invalidate the moduleCache here.
-    return this.moduleCache.delete(id)
+    const normalizedId = cleanId(id)
+    let hasCachedModule = false
+
+    for (const moduleId of Array.from(this.moduleCache.keys())) {
+      if (cleanId(moduleId) === normalizedId) {
+        this.moduleCache.delete(moduleId)
+        hasCachedModule = true
+      }
+    }
+
+    // Root import metadata is synthetic compiler state and should survive HMR.
+    // The stale dev state lives in per-module resolvedKind memoization.
+    for (const [moduleId, moduleInfo] of this.moduleCache) {
+      if (this.knownRootImports.has(moduleId)) {
+        continue
+      }
+
+      for (const binding of moduleInfo.bindings.values()) {
+        binding.resolvedKind = undefined
+      }
+    }
+
+    // Build-mode caches are cheap to rebuild and may point at removed entries.
+    this.resolveIdCache.clear()
+    this.exportResolutionCache.clear()
+
+    return hasCachedModule
+  }
+
+  public async getTransitiveImporters(id: string): Promise<Set<string>> {
+    const discoveredImporters = new Set<string>()
+    const pendingTargets = [cleanId(id)]
+    const visitedTargets = new Set<string>()
+    const resolveCache = new Map<string, Promise<string | null>>()
+
+    const resolveSource = (source: string, importer: string) => {
+      const cacheKey = `${importer}::${source}`
+      let resolved = resolveCache.get(cacheKey)
+
+      if (!resolved) {
+        resolved = this.resolveIdCached(source, importer)
+        resolveCache.set(cacheKey, resolved)
+      }
+
+      return resolved
+    }
+
+    while (pendingTargets.length > 0) {
+      const targetId = pendingTargets.pop()!
+
+      if (visitedTargets.has(targetId)) {
+        continue
+      }
+
+      visitedTargets.add(targetId)
+
+      const importerIds = await Promise.all(
+        Array.from(this.moduleCache.values()).map(async (moduleInfo) => {
+          if (this.knownRootImports.has(moduleInfo.id)) {
+            return null
+          }
+
+          const moduleId = cleanId(moduleInfo.id)
+
+          if (moduleId === targetId) {
+            return null
+          }
+
+          const importSources = new Set(moduleInfo.reExportAllSources)
+
+          for (const binding of moduleInfo.bindings.values()) {
+            if (binding.type === 'import') {
+              importSources.add(binding.source)
+            }
+          }
+
+          for (const source of importSources) {
+            const resolved = await resolveSource(source, moduleInfo.id)
+
+            if (resolved && cleanId(resolved) === targetId) {
+              return moduleId
+            }
+          }
+
+          return null
+        }),
+      )
+
+      for (const importerId of importerIds) {
+        if (!importerId || discoveredImporters.has(importerId)) {
+          continue
+        }
+
+        discoveredImporters.add(importerId)
+        pendingTargets.push(importerId)
+      }
+    }
+
+    return discoveredImporters
   }
 
   public async compile({
@@ -719,7 +827,10 @@ export class StartCompiler {
         if (declarations) {
           for (const decl of declarations) {
             if (decl.init && t.isCallExpression(decl.init)) {
-              if (isMethodChainCandidate(decl.init, fileKinds)) {
+              if (
+                isMethodChainCandidate(decl.init, fileKinds) ||
+                isTopLevelDirectCallCandidateNode(decl.init)
+              ) {
                 candidateIndices.push(i)
                 break // Only need to mark this statement once
               }
@@ -760,6 +871,11 @@ export class StartCompiler {
                 // Method chain pattern
                 if (isMethodChainCandidate(node, fileKinds)) {
                   candidatePaths.push(path)
+                  return
+                }
+
+                if (isTopLevelDirectCallCandidate(path)) {
+                  candidatePaths.push(path)
                 }
               },
             })
@@ -792,11 +908,14 @@ export class StartCompiler {
             return
           }
 
+          if (isTopLevelDirectCallCandidate(path)) {
+            candidatePaths.push(path)
+            return
+          }
+
           // Pattern 2: Direct call pattern
           if (checkDirectCalls) {
-            if (isTopLevelDirectCallCandidate(path)) {
-              candidatePaths.push(path)
-            } else if (isNestedDirectCallCandidate(node)) {
+            if (isNestedDirectCallCandidate(node)) {
               candidatePaths.push(path)
             }
           }
@@ -845,9 +964,23 @@ export class StartCompiler {
     )
 
     // Filter to valid candidates
-    const validCandidates = resolvedCandidates.filter(({ kind }) =>
-      this.validLookupKinds.has(kind as Exclude<LookupKind, 'ClientOnlyJSX'>),
-    ) as Array<{
+    const validCandidates = resolvedCandidates.filter(({ path, kind }) => {
+      if (
+        !this.validLookupKinds.has(kind as Exclude<LookupKind, 'ClientOnlyJSX'>)
+      ) {
+        return false
+      }
+
+      if (
+        isLookupKind(kind) &&
+        kind !== 'ClientOnlyJSX' &&
+        !isMethodChainCandidate(path.node, fileKinds)
+      ) {
+        return isDirectCallCandidateForKind(kind)
+      }
+
+      return true
+    }) as Array<{
       path: babel.NodePath<t.CallExpression>
       kind: Exclude<LookupKind, 'ClientOnlyJSX'>
     }>
@@ -925,6 +1058,7 @@ export class StartCompiler {
       code,
       env: this.options.env,
       envName: this.options.envName,
+      mode: this.mode,
       root: this.options.root,
       framework: this.options.framework,
       providerEnvName: this.options.providerEnvName,

package/src/start-compiler/handleCreateServerFn.ts

@@ -7,6 +7,20 @@ import type { CompileStartFrameworkOptions } from '../types'
 
 const TSS_SERVERFN_SPLIT_PARAM = 'tss-serverfn-split'
 
+const providerHmrAcceptTemplate = babel.template.statements(
+  `
+if (import.meta.hot) {
+  import.meta.hot.accept(() => {})
+}
+if (import.meta.webpackHot) {
+  import.meta.webpackHot.accept(() => {})
+}
+`,
+  {
+    placeholderPattern: false,
+  },
+)
+
 // ============================================================================
 // Pre-compiled babel templates (compiled once at module load time)
 // ============================================================================
@@ -414,6 +428,10 @@ export function handleCreateServerFn(
         ),
       )
     }
+
+    if (context.mode === 'dev') {
+      context.ast.program.body.push(...providerHmrAcceptTemplate())
+    }
   }
 
   // Notify about discovered functions (only for non-provider files)

package/src/start-compiler/types.ts

@@ -12,6 +12,7 @@ export interface CompilationContext {
   readonly id: string
   readonly env: 'client' | 'server'
   readonly envName: string
+  readonly mode: 'dev' | 'build'
   readonly root: string
   /** The framework being used (e.g., 'react', 'solid') */
   readonly framework: CompileStartFrameworkOptions

package/src/utils.ts

@@ -1,3 +1,9 @@
+import path from 'node:path'
+
+const isWindows: boolean =
+  typeof process !== 'undefined' && process.platform === 'win32'
+const windowsSlashRE = /\\/g
+
 /** Read `build.rollupOptions` or `build.rolldownOptions` from a build config. */
 export function getBundlerOptions(build: any): any {
   return build?.rolldownOptions ?? build?.rollupOptions
@@ -17,3 +23,11 @@ export function createLogger(prefix: string) {
     error: (...args: any) => console.error(label, ...args),
   }
 }
+
+function slash(path: string): string {
+  return path.replace(windowsSlashRE, '/')
+}
+
+export function normalizePath(id: string): string {
+  return path.posix.normalize(isWindows ? slash(id) : id)
+}

package/src/vite/import-protection-plugin/INTERNALS.md

@@ -0,0 +1,187 @@
+# Vite Import Protection - Adapter Internals
+
+## Scope
+
+This document covers the Vite-specific orchestration around the shared
+import-protection core in `src/import-protection/INTERNALS.md`.
+
+Vite owns:
+
+- `resolveId`-first violation discovery
+- dev/build deferral decisions tied to Vite lifecycle hooks
+- the transform-cache plugin and post-transform graph bookkeeping
+- Vite virtual-module id resolution and loading
+- bundle-time survival checks in `generateBundle`
+
+Shared AST analysis, rewrite logic, source extraction, mock export discovery,
+usage lookup, source locations, and mock code generation are described in the
+shared internals doc.
+
+## Plugin Shape
+
+`importProtectionPlugin()` returns two Vite plugins:
+
+1. `tanstack-start-core:import-protection`
+2. `tanstack-start-core:import-protection-transform-cache`
+
+The first plugin owns resolve-time detection and reporting decisions. The
+second plugin owns transformed-result caching, post-transform import graph
+updates, self-denial transforms, and dev pending-violation verification.
+
+## Why Vite Uses Two Plugins
+
+Vite discovers many violations in `resolveId`, but accurate source locations and
+post-transform graph truth require transformed code that only exists later.
+
+So the adapter splits responsibilities:
+
+- `resolveId`: detect, classify, defer/report, substitute mock ids where needed
+- later transform hook: cache transformed code/maps, self-deny files, compute
+  post-transform imports, and process pending violations
+
+## Vite State Model
+
+Per environment, Vite keeps `EnvState` with:
+
+- `graph`
+- `mockExportsByImporter`
+- `resolveCache`
+- `resolveCacheByFile`
+- `importLocCache`
+- `seenViolations`
+- `serverFnLookupModules`
+- `transformResultCache`
+- `transformResultKeysByFile`
+- `transformResultProvider`
+- `postTransformImports`
+- `pendingViolations`
+- `deferredBuildViolations`
+
+Cross-environment shared state is intentionally small:
+
+- `fileMarkerKind`
+
+This is larger than the Rsbuild state model because Vite must bridge resolve-
+time detection with later transform/bundle verification.
+
+## Detection Flow
+
+Vite is `resolveId`-driven.
+
+That means the adapter may see violations before:
+
+- the Start compiler removes safe-boundary imports
+- tree-shaking removes false-positive edges
+- transformed importer code is available
+
+So Vite must decide whether to report immediately or defer.
+
+## Deferral Policy
+
+The shared helper is:
+
+```ts
+shouldDefer = isBuild || isDevMock
+```
+
+Adapter meaning:
+
+- dev + error: report immediately with `ctx.error()`
+- dev + mock: store `pendingViolations`, then verify later from post-transform
+  edges and reachability
+- build + mock/error: store `deferredBuildViolations`, then verify in
+  `generateBundle`
+
+This is the main adapter-specific state machine difference from Rsbuild.
+
+## Dev Strategy
+
+### Dev + Error
+
+Vite throws immediately in `resolveId`.
+
+This is intentionally aggressive and can still produce known barrel false
+positives because there is no tree-shaking in the dev server.
+
+Pre-transform resolve paths like `SERVER_FN_LOOKUP` are silenced in this mode
+because there is no later deferred verification path.
+
+### Dev + Mock
+
+Vite defers all violations into `pendingViolations`.
+
+Later, the transform-cache plugin:
+
+1. caches transformed code and sourcemaps
+2. resolves post-transform imports
+3. records graph edges from transformed code
+4. runs `processPendingViolations()`
+
+Pending verification uses two checks:
+
+1. edge survival after the Start compiler transform
+2. graph reachability from entries using post-transform edges
+
+This is how Vite suppresses many dev false positives without bundling.
+
+## Build Strategy
+
+Vite build uses mock-first, verify-later behavior.
+
+At resolve time it substitutes mocks silently and records deferred violations.
+At `generateBundle`, it checks whether each unique mock id survived tree-
+shaking.
+
+If the mock survived:
+
+- error mode: fail the build
+- mock mode: emit a warning
+
+If the mock was removed, the violation is suppressed as a false positive.
+
+## Self-Denial In Vite
+
+For file-based violations, `resolveId` does not return a virtual mock id.
+Instead it returns the physical file path, and the later transform-cache plugin
+replaces the file contents with a mock module.
+
+This Vite-specific choice exists for two reasons:
+
+- avoid cross-environment cache contamination in shared resolver caches
+- avoid cold-start export-resolution issues when importer AST data is not yet
+  available
+
+## Vite Virtual Modules
+
+The shared mock generators use abstract ids like:
+
+- `\0tanstack-start-import-protection:mock`
+- `\0tanstack-start-import-protection:mock-edge:...`
+- `\0tanstack-start-import-protection:mock-runtime:...`
+- `\0tanstack-start-import-protection:marker:*`
+
+The Vite adapter adds:
+
+- resolved Vite ids via `resolveViteId(...)`
+- support for browser-prefixed ids via `__x00__`
+- `loadResolvedVirtualModule()` for serving the generated code
+
+This id transport is adapter-specific. The generated module contents are shared.
+
+## Warm-Start Considerations
+
+Vite can skip `resolveId` on warm cache hits, so the adapter maintains its own
+graph and transform-result caches to recover enough information for traces and
+pending-violation verification.
+
+Special care is taken not to treat pre-transform lookup edges as authoritative
+reachability edges.
+
+## Practical Maintainer Rule
+
+When changing Vite import protection, ask:
+
+1. Is this really about Vite lifecycle timing or state?
+2. If not, should it move into the shared import-protection core?
+3. If yes, does it belong in resolve-time detection, transform-cache handling,
+   or bundle-time verification?