@tanstack/start-plugin-core 1.163.2 → 1.163.4

package/src/import-protection-plugin/postCompileUsage.ts

@@ -1,6 +1,7 @@
 import babel from '@babel/core'
 import * as t from '@babel/types'
-import { parseAst } from '@tanstack/router-utils'
+import { parseImportProtectionAst } from './ast'
+import type { ParsedAst } from './ast'
 
 type UsagePos = { line: number; column0: number }
 
@@ -15,8 +16,13 @@ export function findPostCompileUsagePos(
   code: string,
   source: string,
 ): UsagePos | undefined {
-  const ast = parseAst({ code })
+  return findPostCompileUsagePosFromAst(parseImportProtectionAst(code), source)
+}
 
+function findPostCompileUsagePosFromAst(
+  ast: ParsedAst,
+  source: string,
+): UsagePos | undefined {
   // Collect local names bound from this specifier
   const imported = new Set<string>()
   for (const node of ast.program.body) {

package/src/import-protection-plugin/rewriteDeniedImports.ts

@@ -1,8 +1,11 @@
 import * as t from '@babel/types'
-import { generateFromAst, parseAst } from '@tanstack/router-utils'
+import { generateFromAst } from '@tanstack/router-utils'
 
 import { MOCK_MODULE_ID } from './virtualModules'
 import { getOrCreate } from './utils'
+import { parseImportProtectionAst } from './ast'
+import type { SourceMapLike } from './sourceLocation'
+import type { ParsedAst } from './ast'
 
 export function isValidExportName(name: string): boolean {
   if (name === 'default' || name.length === 0) return false
@@ -34,16 +37,17 @@ export function isValidExportName(name: string): boolean {
   return true
 }
 
-/**
- * Best-effort static analysis of an importer's source to determine which
- * named exports are needed per specifier, to keep native ESM valid in dev.
- */
 export function collectMockExportNamesBySource(
   code: string,
 ): Map<string, Array<string>> {
-  const ast = parseAst({ code })
+  return collectMockExportNamesBySourceFromAst(parseImportProtectionAst(code))
+}
 
+function collectMockExportNamesBySourceFromAst(
+  ast: ParsedAst,
+): Map<string, Array<string>> {
   const namesBySource = new Map<string, Set<string>>()
+  const memberBindingToSource = new Map<string, string>()
   const add = (source: string, name: string) => {
     if (name === 'default' || name.length === 0) return
     getOrCreate(namesBySource, source, () => new Set<string>()).add(name)
@@ -54,6 +58,14 @@ export function collectMockExportNamesBySource(
       if (node.importKind === 'type') continue
       const source = node.source.value
       for (const s of node.specifiers) {
+        if (t.isImportNamespaceSpecifier(s)) {
+          memberBindingToSource.set(s.local.name, source)
+          continue
+        }
+        if (t.isImportDefaultSpecifier(s)) {
+          memberBindingToSource.set(s.local.name, source)
+          continue
+        }
         if (!t.isImportSpecifier(s)) continue
         if (s.importKind === 'type') continue
         const importedName = t.isIdentifier(s.imported)
@@ -76,6 +88,45 @@ export function collectMockExportNamesBySource(
     }
   }
 
+  // For namespace/default imports, collect property names used as
+  // `binding.foo`/`binding?.foo` so mock-edge modules can expose explicit ESM
+  // named exports required by Rolldown/native ESM.
+  if (memberBindingToSource.size > 0) {
+    const visit = (node: t.Node): void => {
+      if (t.isMemberExpression(node)) {
+        const object = node.object
+        if (t.isIdentifier(object)) {
+          const source = memberBindingToSource.get(object.name)
+          if (source) {
+            const property = node.property
+            if (!node.computed && t.isIdentifier(property)) {
+              add(source, property.name)
+            } else if (node.computed && t.isStringLiteral(property)) {
+              add(source, property.value)
+            }
+          }
+        }
+      }
+
+      const keys = t.VISITOR_KEYS[node.type]
+      if (!keys) return
+      for (const key of keys) {
+        const child = (node as unknown as Record<string, unknown>)[key]
+        if (Array.isArray(child)) {
+          for (const item of child) {
+            if (item && typeof item === 'object' && 'type' in item) {
+              visit(item as t.Node)
+            }
+          }
+        } else if (child && typeof child === 'object' && 'type' in child) {
+          visit(child as t.Node)
+        }
+      }
+    }
+
+    visit(ast.program)
+  }
+
   const out = new Map<string, Array<string>>()
   for (const [source, set] of namesBySource) {
     out.set(source, Array.from(set).sort())
@@ -83,6 +134,71 @@ export function collectMockExportNamesBySource(
   return out
 }
 
+/** Collect all valid named export identifiers from the given code. */
+export function collectNamedExports(code: string): Array<string> {
+  return collectNamedExportsFromAst(parseImportProtectionAst(code))
+}
+
+function collectIdentifiersFromPattern(
+  pattern: t.LVal,
+  add: (name: string) => void,
+): void {
+  if (t.isIdentifier(pattern)) {
+    add(pattern.name)
+  } else if (t.isObjectPattern(pattern)) {
+    for (const prop of pattern.properties) {
+      if (t.isRestElement(prop)) {
+        collectIdentifiersFromPattern(prop.argument as t.LVal, add)
+      } else {
+        collectIdentifiersFromPattern(prop.value as t.LVal, add)
+      }
+    }
+  } else if (t.isArrayPattern(pattern)) {
+    for (const elem of pattern.elements) {
+      if (elem) collectIdentifiersFromPattern(elem as t.LVal, add)
+    }
+  } else if (t.isAssignmentPattern(pattern)) {
+    collectIdentifiersFromPattern(pattern.left, add)
+  } else if (t.isRestElement(pattern)) {
+    collectIdentifiersFromPattern(pattern.argument as t.LVal, add)
+  }
+}
+
+function collectNamedExportsFromAst(ast: ParsedAst): Array<string> {
+  const names = new Set<string>()
+  const add = (name: string) => {
+    if (isValidExportName(name)) names.add(name)
+  }
+
+  for (const node of ast.program.body) {
+    if (t.isExportNamedDeclaration(node)) {
+      if (node.exportKind === 'type') continue
+
+      if (node.declaration) {
+        const decl = node.declaration
+        if (t.isFunctionDeclaration(decl) || t.isClassDeclaration(decl)) {
+          if (decl.id?.name) add(decl.id.name)
+        } else if (t.isVariableDeclaration(decl)) {
+          for (const d of decl.declarations) {
+            collectIdentifiersFromPattern(d.id as t.LVal, add)
+          }
+        }
+      }
+
+      for (const s of node.specifiers) {
+        if (!t.isExportSpecifier(s)) continue
+        if (s.exportKind === 'type') continue
+        const exportedName = t.isIdentifier(s.exported)
+          ? s.exported.name
+          : s.exported.value
+        add(exportedName)
+      }
+    }
+  }
+
+  return Array.from(names).sort()
+}
+
 /**
  * Rewrite static imports/re-exports from denied sources using Babel AST transforms.
  *
@@ -105,8 +221,21 @@ export function rewriteDeniedImports(
   id: string,
   deniedSources: Set<string>,
   getMockModuleId: (source: string) => string = () => MOCK_MODULE_ID,
-): { code: string; map?: object | null } | undefined {
-  const ast = parseAst({ code })
+): { code: string; map?: SourceMapLike } | undefined {
+  return rewriteDeniedImportsFromAst(
+    parseImportProtectionAst(code),
+    id,
+    deniedSources,
+    getMockModuleId,
+  )
+}
+
+function rewriteDeniedImportsFromAst(
+  ast: ParsedAst,
+  id: string,
+  deniedSources: Set<string>,
+  getMockModuleId: (source: string) => string = () => MOCK_MODULE_ID,
+): { code: string; map?: SourceMapLike } | undefined {
   let modified = false
   let mockCounter = 0
 
@@ -243,5 +372,8 @@ export function rewriteDeniedImports(
     filename: id,
   })
 
-  return { code: result.code, map: result.map }
+  return {
+    code: result.code,
+    ...(result.map ? { map: result.map as SourceMapLike } : {}),
+  }
 }

package/src/import-protection-plugin/sourceLocation.ts

@@ -1,7 +1,8 @@
 import { SourceMapConsumer } from 'source-map'
 import * as path from 'pathe'
 
-import { escapeRegExp, getOrCreate, normalizeFilePath } from './utils'
+import { findPostCompileUsagePos } from './postCompileUsage'
+import { getOrCreate, normalizeFilePath } from './utils'
 import type { Loc } from './trace'
 import type { RawSourceMap } from 'source-map'
 
@@ -270,36 +271,7 @@ export class ImportLocCache {
   }
 }
 
-// Import specifier search (regex-based)
-
-const importPatternCache = new Map<string, Array<RegExp>>()
-
-export function clearImportPatternCache(): void {
-  importPatternCache.clear()
-}
-
-function findFirstImportSpecifierIndex(code: string, source: string): number {
-  let patterns = importPatternCache.get(source)
-  if (!patterns) {
-    const escaped = escapeRegExp(source)
-    patterns = [
-      new RegExp(`\\bimport\\s+(['"])${escaped}\\1`),
-      new RegExp(`\\bfrom\\s+(['"])${escaped}\\1`),
-      new RegExp(`\\bimport\\s*\\(\\s*(['"])${escaped}\\1\\s*\\)`),
-    ]
-    importPatternCache.set(source, patterns)
-  }
-
-  let best = -1
-  for (const re of patterns) {
-    const m = re.exec(code)
-    if (!m) continue
-    const idx = m.index + m[0].indexOf(source)
-    if (idx === -1) continue
-    if (best === -1 || idx < best) best = idx
-  }
-  return best
-}
+export type FindImportSpecifierIndex = (code: string, source: string) => number
 
 /**
  * Find the location of an import statement in a transformed module
@@ -311,6 +283,7 @@ export async function findImportStatementLocationFromTransformed(
   importerId: string,
   source: string,
   importLocCache: ImportLocCache,
+  findImportSpecifierIndex: FindImportSpecifierIndex,
 ): Promise<Loc | undefined> {
   const importerFile = normalizeFilePath(importerId)
   const cacheKey = `${importerFile}::${source}`
@@ -329,7 +302,7 @@ export async function findImportStatementLocationFromTransformed(
 
     const lineIndex = res.lineIndex ?? buildLineIndex(code)
 
-    const idx = findFirstImportSpecifierIndex(code, source)
+    const idx = findImportSpecifierIndex(code, source)
     if (idx === -1) {
       importLocCache.set(cacheKey, null)
       return undefined
@@ -354,10 +327,6 @@ export async function findPostCompileUsageLocation(
   provider: TransformResultProvider,
   importerId: string,
   source: string,
-  findPostCompileUsagePos: (
-    code: string,
-    source: string,
-  ) => { line: number; column0: number } | undefined,
 ): Promise<Loc | undefined> {
   try {
     const importerFile = normalizeFilePath(importerId)
@@ -391,6 +360,7 @@ export async function addTraceImportLocations(
     column?: number
   }>,
   importLocCache: ImportLocCache,
+  findImportSpecifierIndex: FindImportSpecifierIndex,
 ): Promise<void> {
   for (const step of trace) {
     if (!step.specifier) continue
@@ -400,6 +370,7 @@ export async function addTraceImportLocations(
       step.file,
       step.specifier,
       importLocCache,
+      findImportSpecifierIndex,
     )
     if (!loc) continue
     step.line = loc.line
@@ -435,67 +406,26 @@ export function buildCodeSnippet(
     const res = provider.getTransformResult(moduleId)
     if (!res) return undefined
 
-    const { code: transformedCode, originalCode } = res
-
-    const sourceCode = originalCode ?? transformedCode
+    const sourceCode = res.originalCode ?? res.code
     const targetLine = loc.line // 1-indexed
     const targetCol = loc.column // 1-indexed
 
     if (targetLine < 1) return undefined
 
-    const wantStart = Math.max(1, targetLine - contextLines)
-    const wantEnd = targetLine + contextLines
-
-    // Advance to wantStart
-    let lineNum = 1
-    let pos = 0
-    while (lineNum < wantStart && pos < sourceCode.length) {
-      const ch = sourceCode.charCodeAt(pos)
-      if (ch === 10) {
-        lineNum++
-      } else if (ch === 13) {
-        lineNum++
-        if (
-          pos + 1 < sourceCode.length &&
-          sourceCode.charCodeAt(pos + 1) === 10
-        )
-          pos++
-      }
-      pos++
-    }
-    if (lineNum < wantStart) return undefined
-
-    const lines: Array<string> = []
-    let curLine = wantStart
-    while (curLine <= wantEnd && pos <= sourceCode.length) {
-      // Find end of current line
-      let eol = pos
-      while (eol < sourceCode.length) {
-        const ch = sourceCode.charCodeAt(eol)
-        if (ch === 10 || ch === 13) break
-        eol++
-      }
-      lines.push(sourceCode.slice(pos, eol))
-      curLine++
-      if (eol < sourceCode.length) {
-        if (
-          sourceCode.charCodeAt(eol) === 13 &&
-          eol + 1 < sourceCode.length &&
-          sourceCode.charCodeAt(eol + 1) === 10
-        ) {
-          pos = eol + 2
-        } else {
-          pos = eol + 1
-        }
-      } else {
-        pos = eol + 1
-      }
+    const allLines = sourceCode.split('\n')
+    // Strip trailing \r from \r\n line endings
+    for (let i = 0; i < allLines.length; i++) {
+      const line = allLines[i]!
+      if (line.endsWith('\r')) allLines[i] = line.slice(0, -1)
     }
 
-    if (targetLine > wantStart + lines.length - 1) return undefined
+    const wantStart = Math.max(1, targetLine - contextLines)
+    const wantEnd = Math.min(allLines.length, targetLine + contextLines)
+
+    if (targetLine > allLines.length) return undefined
 
-    const actualEnd = wantStart + lines.length - 1
-    const gutterWidth = String(actualEnd).length
+    const lines = allLines.slice(wantStart - 1, wantEnd)
+    const gutterWidth = String(wantEnd).length
 
     const sourceFile = loc.file ?? importerFile
     const snippetLines: Array<string> = []

package/src/import-protection-plugin/types.ts

@@ -0,0 +1,103 @@
+import type { CompileStartFrameworkOptions, GetConfigFn } from '../types'
+import type { ImportProtectionBehavior } from '../schema'
+import type { CompiledMatcher } from './matchers'
+import type { ImportGraph, ViolationInfo } from './trace'
+import type {
+  ImportLocCache,
+  TransformResult,
+  TransformResultProvider,
+} from './sourceLocation'
+
+/** Compiled deny/exclude patterns for one environment (client or server). */
+export interface EnvRules {
+  specifiers: Array<CompiledMatcher>
+  files: Array<CompiledMatcher>
+  excludeFiles: Array<CompiledMatcher>
+}
+
+export interface PluginConfig {
+  enabled: boolean
+  root: string
+  command: 'build' | 'serve'
+  srcDirectory: string
+  framework: CompileStartFrameworkOptions
+  effectiveBehavior: ImportProtectionBehavior
+  mockAccess: 'error' | 'warn' | 'off'
+  logMode: 'once' | 'always'
+  maxTraceDepth: number
+  compiledRules: {
+    client: EnvRules
+    server: EnvRules
+  }
+  includeMatchers: Array<CompiledMatcher>
+  excludeMatchers: Array<CompiledMatcher>
+  ignoreImporterMatchers: Array<CompiledMatcher>
+  markerSpecifiers: { serverOnly: Set<string>; clientOnly: Set<string> }
+  envTypeMap: Map<string, 'client' | 'server'>
+  onViolation?: (
+    info: ViolationInfo,
+  ) => boolean | void | Promise<boolean | void>
+}
+
+export interface EnvState {
+  graph: ImportGraph
+  mockExportsByImporter: Map<string, Map<string, Array<string>>>
+  resolveCache: Map<string, string | null>
+  resolveCacheByFile: Map<string, Set<string>>
+  importLocCache: ImportLocCache
+  seenViolations: Set<string>
+  serverFnLookupModules: Set<string>
+  transformResultCache: Map<string, TransformResult>
+  transformResultKeysByFile: Map<string, Set<string>>
+  transformResultProvider: TransformResultProvider
+  postTransformImports: Map<string, Set<string>>
+  pendingViolations: Map<string, Array<PendingViolation>>
+  deferredBuildViolations: Array<DeferredBuildViolation>
+}
+
+export interface PendingViolation {
+  info: ViolationInfo
+  /** True when the violation originates from a pre-transform resolveId call
+   * (e.g. server-fn lookup).  These need edge-survival verification because
+   * the Start compiler may strip the import later. */
+  fromPreTransformResolve?: boolean
+}
+
+export interface DeferredBuildViolation {
+  info: ViolationInfo
+  mockModuleId: string
+  checkModuleId?: string
+}
+
+export interface SharedState {
+  fileMarkerKind: Map<string, 'server' | 'client'>
+}
+
+export interface ImportProtectionPluginOptions {
+  getConfig: GetConfigFn
+  framework: CompileStartFrameworkOptions
+  environments: Array<{ name: string; type: 'client' | 'server' }>
+  providerEnvName: string
+}
+
+export type ModuleGraphNode = {
+  id?: string | null
+  url?: string
+  importers: Set<ModuleGraphNode>
+}
+
+export type ViolationReporter = {
+  warn: (msg: string) => void
+  error: (msg: string) => never
+  resolve?: (
+    source: string,
+    importer?: string,
+    options?: {
+      skipSelf?: boolean
+      custom?: Record<string, unknown>
+    },
+  ) => Promise<{ id: string; external?: boolean | 'absolute' } | null>
+  getModuleInfo?: (id: string) => { code?: string | null } | null
+}
+
+export type HandleViolationResult = string | undefined

package/src/import-protection-plugin/utils.ts

@@ -1,5 +1,17 @@
+import {
+  extname,
+  isAbsolute,
+  relative,
+  resolve as resolvePath,
+} from 'node:path'
 import { normalizePath } from 'vite'
 
+import {
+  IMPORT_PROTECTION_DEBUG,
+  IMPORT_PROTECTION_DEBUG_FILTER,
+  KNOWN_SOURCE_EXTENSIONS,
+} from './constants'
+
 export type Pattern = string | RegExp
 
 export function dedupePatterns(patterns: Array<Pattern>): Array<Pattern> {
@@ -14,7 +26,8 @@ export function dedupePatterns(patterns: Array<Pattern>): Array<Pattern> {
   return out
 }
 
-export function stripViteQuery(id: string): string {
+/** Strip both `?query` and `#hash` from a module ID. */
+export function stripQueryAndHash(id: string): string {
   const q = id.indexOf('?')
   const h = id.indexOf('#')
   if (q === -1 && h === -1) return id
@@ -24,8 +37,7 @@ export function stripViteQuery(id: string): string {
 }
 
 /**
- * Strip Vite query parameters and normalize the path in one step.
- * Replaces the repeated `normalizePath(stripViteQuery(id))` pattern.
+ * Strip Vite query/hash parameters and normalize the path in one step.
  *
  * Results are memoized because the same module IDs are processed many
  * times across resolveId, transform, and trace-building hooks.
@@ -34,7 +46,7 @@ const normalizeFilePathCache = new Map<string, string>()
 export function normalizeFilePath(id: string): string {
   let result = normalizeFilePathCache.get(id)
   if (result === undefined) {
-    result = normalizePath(stripViteQuery(id))
+    result = normalizePath(stripQueryAndHash(id))
     normalizeFilePathCache.set(id, result)
   }
   return result
@@ -91,3 +103,110 @@ export function extractImportSources(code: string): Array<string> {
   }
   return sources
 }
+
+/** Log import-protection debug output when debug mode is enabled. */
+export function debugLog(...args: Array<unknown>): void {
+  if (!IMPORT_PROTECTION_DEBUG) return
+  console.warn('[import-protection:debug]', ...args)
+}
+
+/** Check if any value matches the configured debug filter (if present). */
+export function matchesDebugFilter(...values: Array<string>): boolean {
+  const debugFilter = IMPORT_PROTECTION_DEBUG_FILTER
+  if (!debugFilter) return true
+  return values.some((v) => v.includes(debugFilter))
+}
+
+/** Strip `?query` (but not `#hash`) from a module ID. */
+export function stripQuery(id: string): string {
+  const queryIndex = id.indexOf('?')
+  return queryIndex === -1 ? id : id.slice(0, queryIndex)
+}
+
+export function withoutKnownExtension(id: string): string {
+  const ext = extname(id)
+  return KNOWN_SOURCE_EXTENSIONS.has(ext) ? id.slice(0, -ext.length) : id
+}
+
+/**
+ * Check whether `filePath` is contained inside `directory` using a
+ * boundary-safe comparison.  A naïve `filePath.startsWith(directory)`
+ * would incorrectly treat `/app/src2/foo.ts` as inside `/app/src`.
+ */
+export function isInsideDirectory(
+  filePath: string,
+  directory: string,
+): boolean {
+  const rel = relative(resolvePath(directory), resolvePath(filePath))
+  return rel.length > 0 && !rel.startsWith('..') && !isAbsolute(rel)
+}
+
+/**
+ * Decide whether a violation should be deferred for later verification
+ * rather than reported immediately.
+ *
+ * Build mode: always defer — generateBundle checks tree-shaking.
+ * Dev mock mode: always defer — edge-survival verifies whether the Start
+ *   compiler strips the import (factory-safe pattern).  All violation
+ *   types and specifier formats are handled uniformly by the
+ *   edge-survival mechanism in processPendingViolations.
+ * Dev error mode: never defer — throw immediately (no mock fallback).
+ */
+export function shouldDeferViolation(opts: {
+  isBuild: boolean
+  isDevMock: boolean
+}): boolean {
+  return opts.isBuild || opts.isDevMock
+}
+
+export function buildSourceCandidates(
+  source: string,
+  resolved: string | undefined,
+  root: string,
+): Set<string> {
+  const candidates = new Set<string>()
+  const push = (value: string | undefined) => {
+    if (!value) return
+    candidates.add(value)
+    candidates.add(stripQuery(value))
+    candidates.add(withoutKnownExtension(stripQuery(value)))
+  }
+
+  push(source)
+  if (resolved) {
+    push(resolved)
+    const relativeResolved = relativizePath(resolved, root)
+    push(relativeResolved)
+    push(`./${relativeResolved}`)
+    push(`/${relativeResolved}`)
+  }
+
+  return candidates
+}
+
+export function buildResolutionCandidates(id: string): Array<string> {
+  const normalized = normalizeFilePath(id)
+  const stripped = stripQuery(normalized)
+
+  return [...new Set([id, normalized, stripped])]
+}
+
+export function canonicalizeResolvedId(
+  id: string,
+  root: string,
+  resolveExtensionlessAbsoluteId: (value: string) => string,
+): string {
+  const stripped = stripQuery(id)
+  let normalized = normalizeFilePath(stripped)
+
+  if (
+    !isAbsolute(normalized) &&
+    !normalized.startsWith('.') &&
+    !normalized.startsWith('\0') &&
+    !/^[a-zA-Z]+:/.test(normalized)
+  ) {
+    normalized = normalizeFilePath(resolvePath(root, normalized))
+  }
+
+  return resolveExtensionlessAbsoluteId(normalized)
+}