@tanstack/start-plugin-core 1.161.4 → 1.162.0

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

@@ -1,4 +1,4 @@
-import * as path from 'pathe'
+import { getOrCreate, relativizePath } from './utils'
 
 export interface TraceEdge {
   importer: string
@@ -30,21 +30,11 @@ export class ImportGraph {
   readonly entries: Set<string> = new Set()
 
   addEdge(resolved: string, importer: string, specifier?: string): void {
-    let importers = this.reverseEdges.get(resolved)
-    if (!importers) {
-      importers = new Map()
-      this.reverseEdges.set(resolved, importers)
-    }
-    // Last writer wins; good enough for trace display.
-    importers.set(importer, specifier)
-
-    // Maintain forward index
-    let targets = this.forwardEdges.get(importer)
-    if (!targets) {
-      targets = new Set()
-      this.forwardEdges.set(importer, targets)
-    }
-    targets.add(resolved)
+    getOrCreate(this.reverseEdges, resolved, () => new Map()).set(
+      importer,
+      specifier,
+    )
+    getOrCreate(this.forwardEdges, importer, () => new Set()).add(resolved)
   }
 
   /** Convenience for tests/debugging. */
@@ -113,13 +103,13 @@ export function buildTrace(
   const down = new Map<string, { next: string; specifier?: string }>()
 
   const queue: Array<string> = [startNode]
-  let queueIndex = 0
+  let qi = 0
 
   let root: string | null = null
 
-  while (queueIndex < queue.length) {
-    const node = queue[queueIndex++]!
-    const depth = depthByNode.get(node) ?? 0
+  while (qi < queue.length) {
+    const node = queue[qi++]!
+    const depth = depthByNode.get(node)!
     const importers = graph.reverseEdges.get(node)
 
     if (node !== startNode) {
@@ -185,13 +175,29 @@ export interface ViolationInfo {
   }
 }
 
+/**
+ * Suggestion strings for server-only code leaking into client environments.
+ * Used by both `formatViolation` (terminal) and runtime mock modules (browser).
+ */
+export const CLIENT_ENV_SUGGESTIONS = [
+  'Use createServerFn().handler(() => ...) to keep the logic on the server and call it from the client via an RPC bridge',
+  'Use createServerOnlyFn(() => ...) to mark it as server-only (it will throw if accidentally called from the client)',
+  'Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations',
+  'Move the server-only import out of this file into a separate .server.ts module that is not imported by any client code',
+] as const
+
+/**
+ * Suggestion strings for client-only code leaking into server environments.
+ * The JSX-specific suggestion is conditionally prepended by `formatViolation`.
+ */
+export const SERVER_ENV_SUGGESTIONS = [
+  'Use createClientOnlyFn(() => ...) to mark it as client-only (returns undefined on the server)',
+  'Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations',
+  'Move the client-only import out of this file into a separate .client.ts module that is not imported by any server code',
+] as const
+
 export function formatViolation(info: ViolationInfo, root: string): string {
-  const rel = (p: string) => {
-    if (p.startsWith(root)) {
-      return path.relative(root, p)
-    }
-    return p
-  }
+  const rel = (p: string) => relativizePath(p, root)
 
   const relLoc = (p: string, loc?: Loc) => {
     const r = rel(p)
@@ -253,22 +259,11 @@ export function formatViolation(info: ViolationInfo, root: string): string {
 
   // Add suggestions
   if (info.envType === 'client') {
-    // Server-only code leaking into the client environment
     lines.push(`  Suggestions:`)
-    lines.push(
-      `    - Use createServerFn().handler(() => ...) to keep the logic on the server and call it from the client via an RPC bridge`,
-    )
-    lines.push(
-      `    - Use createServerOnlyFn(() => ...) to mark it as server-only (it will throw if accidentally called from the client)`,
-    )
-    lines.push(
-      `    - Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations`,
-    )
-    lines.push(
-      `    - Move the server-only import out of this file into a separate .server.ts module that is not imported by any client code`,
-    )
+    for (const s of CLIENT_ENV_SUGGESTIONS) {
+      lines.push(`    - ${s}`)
+    }
   } else {
-    // Client-only code leaking into the server environment
     const snippetText = info.snippet?.lines.join('\n') ?? ''
     const looksLikeJsx =
       /<[A-Z]/.test(snippetText) ||
@@ -280,15 +275,9 @@ export function formatViolation(info: ViolationInfo, root: string): string {
         `    - Wrap the JSX in <ClientOnly fallback={<Loading />}>...</ClientOnly> so it only renders in the browser after hydration`,
       )
     }
-    lines.push(
-      `    - Use createClientOnlyFn(() => ...) to mark it as client-only (returns undefined on the server)`,
-    )
-    lines.push(
-      `    - Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations`,
-    )
-    lines.push(
-      `    - Move the client-only import out of this file into a separate .client.ts module that is not imported by any server code`,
-    )
+    for (const s of SERVER_ENV_SUGGESTIONS) {
+      lines.push(`    - ${s}`)
+    }
   }
 
   lines.push(``)

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

@@ -26,7 +26,68 @@ export function stripViteQuery(id: string): string {
 /**
  * Strip Vite query parameters and normalize the path in one step.
  * Replaces the repeated `normalizePath(stripViteQuery(id))` pattern.
+ *
+ * Results are memoized because the same module IDs are processed many
+ * times across resolveId, transform, and trace-building hooks.
  */
+const normalizeFilePathCache = new Map<string, string>()
 export function normalizeFilePath(id: string): string {
-  return normalizePath(stripViteQuery(id))
+  let result = normalizeFilePathCache.get(id)
+  if (result === undefined) {
+    result = normalizePath(stripViteQuery(id))
+    normalizeFilePathCache.set(id, result)
+  }
+  return result
+}
+
+/** Clear the memoization cache (call from buildStart to bound growth). */
+export function clearNormalizeFilePathCache(): void {
+  normalizeFilePathCache.clear()
+}
+
+/**
+ * Lightweight regex to extract all import/re-export source strings from
+ * post-transform code.  Matches:
+ *   - `from "..."` / `from '...'`   (static import/export)
+ *   - `import("...")` / `import('...')` (dynamic import)
+ */
+const importSourceRe =
+  /\bfrom\s+(?:"([^"]+)"|'([^']+)')|import\s*\(\s*(?:"([^"]+)"|'([^']+)')\s*\)/g
+
+export function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Get a value from a Map, creating it with `factory` if absent. */
+export function getOrCreate<TKey, TValue>(
+  map: Map<TKey, TValue>,
+  key: TKey,
+  factory: () => TValue,
+): TValue {
+  let value = map.get(key)
+  if (value === undefined) {
+    value = factory()
+    map.set(key, value)
+  }
+  return value
+}
+
+/** Make a path relative to `root`, keeping non-rooted paths as-is. */
+export function relativizePath(p: string, root: string): string {
+  if (!p.startsWith(root)) return p
+  const ch = p.charCodeAt(root.length)
+  // Must be followed by a separator or end-of-string to be a true child
+  if (ch !== 47 && !Number.isNaN(ch)) return p
+  return ch === 47 ? p.slice(root.length + 1) : p.slice(root.length)
+}
+
+export function extractImportSources(code: string): Array<string> {
+  const sources: Array<string> = []
+  let m: RegExpExecArray | null
+  importSourceRe.lastIndex = 0
+  while ((m = importSourceRe.exec(code)) !== null) {
+    const src = m[1] ?? m[2] ?? m[3] ?? m[4]
+    if (src) sources.push(src)
+  }
+  return sources
 }

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

@@ -1,22 +1,16 @@
-import { normalizePath } from 'vite'
-import * as path from 'pathe'
-
 import { resolveViteId } from '../utils'
 import { VITE_ENVIRONMENT_NAMES } from '../constants'
 import { isValidExportName } from './rewriteDeniedImports'
+import { CLIENT_ENV_SUGGESTIONS } from './trace'
+import { relativizePath } from './utils'
 import type { ViolationInfo } from './trace'
 
-// ---------------------------------------------------------------------------
-// Virtual module ID constants
-// ---------------------------------------------------------------------------
-
 export const MOCK_MODULE_ID = 'tanstack-start-import-protection:mock'
 export const RESOLVED_MOCK_MODULE_ID = resolveViteId(MOCK_MODULE_ID)
 
 export const MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:'
 export const RESOLVED_MOCK_EDGE_PREFIX = resolveViteId(MOCK_EDGE_PREFIX)
 
-// Dev-only runtime-diagnostic mock modules (used only by the client rewrite pass)
 export const MOCK_RUNTIME_PREFIX =
   'tanstack-start-import-protection:mock-runtime:'
 export const RESOLVED_MOCK_RUNTIME_PREFIX = resolveViteId(MOCK_RUNTIME_PREFIX)
@@ -24,10 +18,6 @@ export const RESOLVED_MOCK_RUNTIME_PREFIX = resolveViteId(MOCK_RUNTIME_PREFIX)
 export const MARKER_PREFIX = 'tanstack-start-import-protection:marker:'
 export const RESOLVED_MARKER_PREFIX = resolveViteId(MARKER_PREFIX)
 
-// ---------------------------------------------------------------------------
-// Base64url helpers
-// ---------------------------------------------------------------------------
-
 function toBase64Url(input: string): string {
   return Buffer.from(input, 'utf8').toString('base64url')
 }
@@ -36,38 +26,16 @@ function fromBase64Url(input: string): string {
   return Buffer.from(input, 'base64url').toString('utf8')
 }
 
-// ---------------------------------------------------------------------------
-// Mock-runtime module helpers
-// ---------------------------------------------------------------------------
+type MockAccessMode = 'error' | 'warn' | 'off'
 
-export type MockAccessMode = 'error' | 'warn' | 'off'
-
-function makeMockRuntimeModuleId(payload: {
-  env: string
-  importer: string
-  specifier: string
-  trace: Array<string>
-  mode: MockAccessMode
-}): string {
-  return `${MOCK_RUNTIME_PREFIX}${toBase64Url(JSON.stringify(payload))}`
-}
-
-function stripTraceFormatting(
-  trace: Array<{ file: string; line?: number; column?: number }>,
-  root: string,
-): Array<string> {
-  // Keep this very small: runtime warning should show an actionable chain.
-  // Format: relativePath[:line:col]
-  const rel = (p: string) => {
-    if (p.startsWith(root)) return normalizePath(path.relative(root, p))
-    return p
-  }
-  return trace.map((s) => {
-    const file = rel(s.file)
-    if (s.line == null) return file
-    return `${file}:${s.line}:${s.column ?? 1}`
-  })
-}
+/**
+ * Compact runtime suggestion text for browser console, derived from
+ * {@link CLIENT_ENV_SUGGESTIONS} so there's a single source of truth.
+ */
+export const RUNTIME_SUGGESTION_TEXT =
+  'Fix: ' +
+  CLIENT_ENV_SUGGESTIONS.join('. ') +
+  '. To disable these runtime diagnostics, set importProtection.mockAccess: "off".'
 
 export function mockRuntimeModuleIdFromViolation(
   info: ViolationInfo,
@@ -75,81 +43,162 @@ export function mockRuntimeModuleIdFromViolation(
   root: string,
 ): string {
   if (mode === 'off') return MOCK_MODULE_ID
-  // Only emit runtime diagnostics in dev and only on the client environment.
   if (info.env !== VITE_ENVIRONMENT_NAMES.client) return MOCK_MODULE_ID
-  return makeMockRuntimeModuleId({
+
+  const rel = (p: string) => relativizePath(p, root)
+  const trace = info.trace.map((s) => {
+    const file = rel(s.file)
+    if (s.line == null) return file
+    return `${file}:${s.line}:${s.column ?? 1}`
+  })
+
+  const payload = {
     env: info.env,
     importer: info.importer,
     specifier: info.specifier,
-    trace: stripTraceFormatting(info.trace, root),
+    trace,
     mode,
-  })
+  }
+  return `${MOCK_RUNTIME_PREFIX}${toBase64Url(JSON.stringify(payload))}`
 }
 
-// ---------------------------------------------------------------------------
-// Mock-edge module ID builder
-// ---------------------------------------------------------------------------
-
 export function makeMockEdgeModuleId(
   exports: Array<string>,
   source: string,
   runtimeId: string,
 ): string {
-  const payload = {
-    source,
-    exports,
-    runtimeId,
-  }
+  const payload = { source, exports, runtimeId }
   return `${MOCK_EDGE_PREFIX}${toBase64Url(JSON.stringify(payload))}`
 }
 
-// ---------------------------------------------------------------------------
-// Load handler helpers — virtual module source code generators
-// ---------------------------------------------------------------------------
+/**
+ * Generate a recursive Proxy-based mock module.
+ *
+ * When `diagnostics` is provided, the generated code includes a `__report`
+ * function that logs runtime warnings/errors when the mock is actually used
+ * (property access for primitive coercion, calls, construction, sets).
+ *
+ * When `diagnostics` is omitted, the mock is completely silent — suitable
+ * for the shared `MOCK_MODULE_ID` that uses `syntheticNamedExports`.
+ */
+function generateMockCode(diagnostics?: {
+  meta: {
+    env: string
+    importer: string
+    specifier: string
+    trace: Array<unknown>
+  }
+  mode: 'error' | 'warn' | 'off'
+}): string {
+  const fnName = diagnostics ? '__createMock' : 'createMock'
+  const hasDiag = !!diagnostics
 
-export function loadSilentMockModule(): {
-  syntheticNamedExports: boolean
-  code: string
-} {
-  return {
-    // syntheticNamedExports tells Rollup to derive named exports
-    // from the default export. Combined with the Proxy-based mock,
-    // this allows `import { anything } from 'mock'` to work.
-    syntheticNamedExports: true,
-    code: `
-function createMock(name) {
+  const preamble = hasDiag
+    ? `const __meta = ${JSON.stringify(diagnostics.meta)};
+const __mode = ${JSON.stringify(diagnostics.mode)};
+
+const __seen = new Set();
+function __report(action, accessPath) {
+  if (__mode === 'off') return;
+  const key = action + ':' + accessPath;
+  if (__seen.has(key)) return;
+  __seen.add(key);
+
+  const traceLines = Array.isArray(__meta.trace) && __meta.trace.length
+    ? "\\n\\nTrace:\\n" + __meta.trace.map((t, i) => '  ' + (i + 1) + '. ' + String(t)).join('\\n')
+    : '';
+
+  const msg =
+    '[import-protection] Mocked import used in dev client\\n\\n' +
+    'Denied import: "' + __meta.specifier + '"\\n' +
+    'Importer: ' + __meta.importer + '\\n' +
+    'Access: ' + accessPath + ' (' + action + ')' +
+    traceLines +
+    '\\n\\n' + ${JSON.stringify(RUNTIME_SUGGESTION_TEXT)};
+
+  const err = new Error(msg);
+  if (__mode === 'warn') {
+    console.warn(err);
+  } else {
+    console.error(err);
+  }
+}
+`
+    : ''
+
+  // Diagnostic-only traps for primitive coercion, set
+  const diagGetTraps = hasDiag
+    ? `
+      if (prop === Symbol.toPrimitive) {
+        return () => {
+          __report('toPrimitive', name);
+          return '[import-protection mock]';
+        };
+      }
+      if (prop === 'toString' || prop === 'valueOf' || prop === 'toJSON') {
+        return () => {
+          __report(String(prop), name);
+          return '[import-protection mock]';
+        };
+      }`
+    : ''
+
+  const applyBody = hasDiag
+    ? `__report('call', name + '()');
+      return ${fnName}(name + '()');`
+    : `return ${fnName}(name + '()');`
+
+  const constructBody = hasDiag
+    ? `__report('construct', 'new ' + name);
+      return ${fnName}('new ' + name);`
+    : `return ${fnName}('new ' + name);`
+
+  const setTrap = hasDiag
+    ? `
+    set(_target, prop) {
+      __report('set', name + '.' + String(prop));
+      return true;
+    },`
+    : ''
+
+  return `
+${preamble}function ${fnName}(name) {
   const fn = function () {};
   fn.prototype.name = name;
   const children = Object.create(null);
   const proxy = new Proxy(fn, {
-    get(target, prop) {
+    get(_target, prop) {
       if (prop === '__esModule') return true;
       if (prop === 'default') return proxy;
       if (prop === 'caller') return null;
-      if (typeof prop === 'symbol') return undefined;
-      // Thenable support: prevent await from hanging
-      if (prop === 'then') return (fn) => Promise.resolve(fn(proxy));
+      if (prop === 'then') return (f) => Promise.resolve(f(proxy));
       if (prop === 'catch') return () => Promise.resolve(proxy);
-      if (prop === 'finally') return (fn) => { fn(); return Promise.resolve(proxy); };
-      // Memoize child proxies so mock.foo === mock.foo
+      if (prop === 'finally') return (f) => { f(); return Promise.resolve(proxy); };${diagGetTraps}
+      if (typeof prop === 'symbol') return undefined;
       if (!(prop in children)) {
-        children[prop] = createMock(name + '.' + prop);
+        children[prop] = ${fnName}(name + '.' + prop);
       }
       return children[prop];
     },
     apply() {
-      return createMock(name + '()');
+      ${applyBody}
     },
     construct() {
-      return createMock('new ' + name);
-    },
+      ${constructBody}
+    },${setTrap}
   });
   return proxy;
 }
-const mock = createMock('mock');
+const mock = ${fnName}('mock');
 export default mock;
-`,
-  }
+`
+}
+
+export function loadSilentMockModule(): {
+  syntheticNamedExports: boolean
+  code: string
+} {
+  return { syntheticNamedExports: true, code: generateMockCode() }
 }
 
 export function loadMockEdgeModule(encodedPayload: string): { code: string } {
@@ -161,7 +210,8 @@ export function loadMockEdgeModule(encodedPayload: string): { code: string } {
   }
   const names: Array<string> = Array.isArray(payload.exports)
     ? payload.exports.filter(
-        (n): n is string => typeof n === 'string' && isValidExportName(n),
+        (n): n is string =>
+          typeof n === 'string' && n.length > 0 && n !== 'default',
       )
     : []
 
@@ -170,13 +220,33 @@ export function loadMockEdgeModule(encodedPayload: string): { code: string } {
       ? payload.runtimeId
       : MOCK_MODULE_ID
 
-  const exportLines = names.map((n) => `export const ${n} = mock.${n};`)
+  const exportLines: Array<string> = []
+  const stringExports: Array<{ alias: string; name: string }> = []
+
+  for (let i = 0; i < names.length; i++) {
+    const n = names[i]!
+    if (isValidExportName(n)) {
+      exportLines.push(`export const ${n} = mock.${n};`)
+    } else {
+      // ES2022 string-keyed export: use a temp var + re-export with string literal
+      const alias = `__tss_str_${i}`
+      exportLines.push(`const ${alias} = mock[${JSON.stringify(n)}];`)
+      stringExports.push({ alias, name: n })
+    }
+  }
+
+  if (stringExports.length > 0) {
+    const reexports = stringExports
+      .map((s) => `${s.alias} as ${JSON.stringify(s.name)}`)
+      .join(', ')
+    exportLines.push(`export { ${reexports} };`)
+  }
+
   return {
-    code: `
- import mock from ${JSON.stringify(runtimeId)};
-   ${exportLines.join('\n')}
-   export default mock;
-   `,
+    code: `import mock from ${JSON.stringify(runtimeId)};
+${exportLines.join('\n')}
+export default mock;
+`,
   }
 }
 
@@ -206,95 +276,11 @@ export function loadMockRuntimeModule(encodedPayload: string): {
     trace: Array.isArray(payload.trace) ? payload.trace : [],
   }
 
-  return {
-    code: `
-const __meta = ${JSON.stringify(meta)};
-const __mode = ${JSON.stringify(mode)};
-
-const __seen = new Set();
-function __report(action, accessPath) {
-  if (__mode === 'off') return;
-  const key = action + ':' + accessPath;
-  if (__seen.has(key)) return;
-  __seen.add(key);
-
-  const traceLines = Array.isArray(__meta.trace) && __meta.trace.length
-    ? "\\n\\nTrace:\\n" + __meta.trace.map((t, i) => '  ' + (i + 1) + '. ' + String(t)).join('\\n')
-    : '';
-
-  const msg =
-    '[import-protection] Mocked import used in dev client\\n\\n' +
-    'Denied import: "' + __meta.specifier + '"\\n' +
-    'Importer: ' + __meta.importer + '\\n' +
-    'Access: ' + accessPath + ' (' + action + ')' +
-    traceLines +
-    '\\n\\nFix: Remove server-only imports from client code. Use createServerFn().handler(() => ...) to call server logic from the client via RPC, or move the import into a .server.ts file. To disable these runtime diagnostics, set importProtection.mockAccess: "off".';
-
-  const err = new Error(msg);
-  if (__mode === 'warn') {
-    console.warn(err);
-  } else {
-    console.error(err);
-  }
-}
-
-function __createMock(name) {
-  const fn = function () {};
-  fn.prototype.name = name;
-  const children = Object.create(null);
-
-  const proxy = new Proxy(fn, {
-    get(_target, prop) {
-      if (prop === '__esModule') return true;
-      if (prop === 'default') return proxy;
-      if (prop === 'caller') return null;
-      if (prop === 'then') return (f) => Promise.resolve(f(proxy));
-      if (prop === 'catch') return () => Promise.resolve(proxy);
-      if (prop === 'finally') return (f) => { f(); return Promise.resolve(proxy); };
-
-      // Trigger a runtime diagnostic for primitive conversions.
-      if (prop === Symbol.toPrimitive) {
-        return () => {
-          __report('toPrimitive', name);
-          return '[import-protection mock]';
-        };
-      }
-      if (prop === 'toString' || prop === 'valueOf' || prop === 'toJSON') {
-        return () => {
-          __report(String(prop), name);
-          return '[import-protection mock]';
-        };
-      }
-
-      if (typeof prop === 'symbol') return undefined;
-      if (!(prop in children)) {
-        children[prop] = __createMock(name + '.' + prop);
-      }
-      return children[prop];
-    },
-    apply() {
-      __report('call', name + '()');
-      return __createMock(name + '()');
-    },
-    construct() {
-      __report('construct', 'new ' + name);
-      return __createMock('new ' + name);
-    },
-    set(_target, prop) {
-      __report('set', name + '.' + String(prop));
-      return true;
-    },
-  });
-
-  return proxy;
+  return { code: generateMockCode({ meta, mode }) }
 }
 
-const mock = __createMock('mock');
-export default mock;
-`,
-  }
-}
+const MARKER_MODULE_RESULT = { code: 'export {}' } as const
 
 export function loadMarkerModule(): { code: string } {
-  return { code: 'export {}' }
+  return MARKER_MODULE_RESULT
 }