@tanstack/start-plugin-core 1.160.1 → 1.161.0

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

@@ -0,0 +1,296 @@
+import * as path from 'pathe'
+
+export interface TraceEdge {
+  importer: string
+  specifier?: string
+}
+
+/**
+ * Per-environment reverse import graph.
+ * Maps a resolved module id to the set of modules that import it.
+ */
+export class ImportGraph {
+  /**
+   * resolvedId -> Map<importer, specifier>
+   *
+   * We use a Map instead of a Set of objects so edges dedupe correctly.
+   */
+  readonly reverseEdges: Map<string, Map<string, string | undefined>> =
+    new Map()
+
+  /**
+   * Forward-edge index: importer -> Set<resolvedId>.
+   *
+   * Maintained alongside reverseEdges so that {@link invalidate} can remove
+   * all outgoing edges for a file in O(outgoing-edges) instead of scanning
+   * every reverse-edge map in the graph.
+   */
+  private readonly forwardEdges: Map<string, Set<string>> = new Map()
+
+  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)
+  }
+
+  /** Convenience for tests/debugging. */
+  getEdges(resolved: string): Set<TraceEdge> | undefined {
+    const importers = this.reverseEdges.get(resolved)
+    if (!importers) return undefined
+    const out = new Set<TraceEdge>()
+    for (const [importer, specifier] of importers) {
+      out.add({ importer, specifier })
+    }
+    return out
+  }
+
+  addEntry(id: string): void {
+    this.entries.add(id)
+  }
+
+  clear(): void {
+    this.reverseEdges.clear()
+    this.forwardEdges.clear()
+    this.entries.clear()
+  }
+
+  invalidate(id: string): void {
+    // Remove all outgoing edges (id as importer) using the forward index.
+    const targets = this.forwardEdges.get(id)
+    if (targets) {
+      for (const resolved of targets) {
+        this.reverseEdges.get(resolved)?.delete(id)
+      }
+      this.forwardEdges.delete(id)
+    }
+    // Remove as a target (id as resolved module)
+    this.reverseEdges.delete(id)
+  }
+}
+
+export interface TraceStep {
+  file: string
+  specifier?: string
+  line?: number
+  column?: number
+}
+
+export interface Loc {
+  file?: string
+  line: number
+  column: number
+}
+
+/**
+ * BFS from a node upward through reverse edges to find the shortest
+ * path to an entry module.
+ */
+export function buildTrace(
+  graph: ImportGraph,
+  startNode: string,
+  maxDepth: number = 20,
+): Array<TraceStep> {
+  // BFS upward (startNode -> importers -> ...)
+  const visited = new Set<string>([startNode])
+  const depthByNode = new Map<string, number>([[startNode, 0]])
+
+  // For any importer we visit, store the "down" link back toward startNode.
+  // importer --(specifier)--> next
+  const down = new Map<string, { next: string; specifier?: string }>()
+
+  const queue: Array<string> = [startNode]
+  let queueIndex = 0
+
+  let root: string | null = null
+
+  while (queueIndex < queue.length) {
+    const node = queue[queueIndex++]!
+    const depth = depthByNode.get(node) ?? 0
+    const importers = graph.reverseEdges.get(node)
+
+    if (node !== startNode) {
+      const isEntry =
+        graph.entries.has(node) || !importers || importers.size === 0
+      if (isEntry) {
+        root = node
+        break
+      }
+    }
+
+    if (depth >= maxDepth) {
+      continue
+    }
+
+    if (!importers || importers.size === 0) {
+      continue
+    }
+
+    for (const [importer, specifier] of importers) {
+      if (visited.has(importer)) continue
+      visited.add(importer)
+      depthByNode.set(importer, depth + 1)
+      down.set(importer, { next: node, specifier })
+      queue.push(importer)
+    }
+  }
+
+  // Best-effort: if we never found a root, just start from the original node.
+  if (!root) {
+    root = startNode
+  }
+
+  const trace: Array<TraceStep> = []
+  let current = root
+  for (let i = 0; i <= maxDepth + 1; i++) {
+    const link = down.get(current)
+    trace.push({ file: current, specifier: link?.specifier })
+    if (!link) break
+    current = link.next
+  }
+
+  return trace
+}
+
+export interface ViolationInfo {
+  env: string
+  envType: 'client' | 'server'
+  type: 'specifier' | 'file' | 'marker'
+  behavior: 'error' | 'mock'
+  pattern?: string | RegExp
+  specifier: string
+  importer: string
+  importerLoc?: Loc
+  resolved?: string
+  trace: Array<TraceStep>
+  message: string
+  /** Vitest-style code snippet showing the offending usage in the leaf module. */
+  snippet?: {
+    lines: Array<string>
+    highlightLine: number
+    location: string
+  }
+}
+
+export function formatViolation(info: ViolationInfo, root: string): string {
+  const rel = (p: string) => {
+    if (p.startsWith(root)) {
+      return path.relative(root, p)
+    }
+    return p
+  }
+
+  const relLoc = (p: string, loc?: Loc) => {
+    const r = rel(p)
+    const file = loc?.file ? rel(loc.file) : r
+    return loc ? `${file}:${loc.line}:${loc.column}` : r
+  }
+
+  const relTraceStep = (step: TraceStep): string => {
+    const file = rel(step.file)
+    if (step.line == null) return file
+    const col = step.column ?? 1
+    return `${file}:${step.line}:${col}`
+  }
+
+  const lines: Array<string> = []
+  lines.push(``)
+  lines.push(`[import-protection] Import denied in ${info.envType} environment`)
+  lines.push(``)
+
+  if (info.type === 'specifier') {
+    lines.push(`  Denied by specifier pattern: ${String(info.pattern)}`)
+  } else if (info.type === 'file') {
+    lines.push(`  Denied by file pattern: ${String(info.pattern)}`)
+  } else {
+    lines.push(
+      `  Denied by marker: module is restricted to the opposite environment`,
+    )
+  }
+
+  lines.push(`  Importer: ${relLoc(info.importer, info.importerLoc)}`)
+  lines.push(`  Import: "${rel(info.specifier)}"`)
+  if (info.resolved) {
+    lines.push(`  Resolved: ${rel(info.resolved)}`)
+  }
+
+  if (info.trace.length > 0) {
+    lines.push(``)
+    lines.push(`  Trace:`)
+    for (let i = 0; i < info.trace.length; i++) {
+      const step = info.trace[i]!
+      const isEntry = i === 0
+      const tag = isEntry ? ' (entry)' : ''
+      const spec = step.specifier ? ` (import "${rel(step.specifier)}")` : ''
+      lines.push(`    ${i + 1}. ${relTraceStep(step)}${tag}${spec}`)
+    }
+  }
+
+  if (info.snippet) {
+    lines.push(``)
+    lines.push(`  Code:`)
+    for (const snippetLine of info.snippet.lines) {
+      lines.push(snippetLine)
+    }
+    lines.push(``)
+    lines.push(`  ${rel(info.snippet.location)}`)
+  }
+
+  lines.push(``)
+
+  // 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`,
+    )
+  } else {
+    // Client-only code leaking into the server environment
+    const snippetText = info.snippet?.lines.join('\n') ?? ''
+    const looksLikeJsx =
+      /<[A-Z]/.test(snippetText) ||
+      (/\{.*\(.*\).*\}/.test(snippetText) && /</.test(snippetText))
+
+    lines.push(`  Suggestions:`)
+    if (looksLikeJsx) {
+      lines.push(
+        `    - 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`,
+    )
+  }
+
+  lines.push(``)
+  return lines.join('\n')
+}

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

@@ -0,0 +1,32 @@
+import { normalizePath } from 'vite'
+
+export type Pattern = string | RegExp
+
+export function dedupePatterns(patterns: Array<Pattern>): Array<Pattern> {
+  const out: Array<Pattern> = []
+  const seen = new Set<string>()
+  for (const p of patterns) {
+    const key = typeof p === 'string' ? `s:${p}` : `r:${p.toString()}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(p)
+  }
+  return out
+}
+
+export function stripViteQuery(id: string): string {
+  const q = id.indexOf('?')
+  const h = id.indexOf('#')
+  if (q === -1 && h === -1) return id
+  if (q === -1) return id.slice(0, h)
+  if (h === -1) return id.slice(0, q)
+  return id.slice(0, Math.min(q, h))
+}
+
+/**
+ * Strip Vite query parameters and normalize the path in one step.
+ * Replaces the repeated `normalizePath(stripViteQuery(id))` pattern.
+ */
+export function normalizeFilePath(id: string): string {
+  return normalizePath(stripViteQuery(id))
+}

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

@@ -0,0 +1,300 @@
+import { normalizePath } from 'vite'
+import * as path from 'pathe'
+
+import { resolveViteId } from '../utils'
+import { VITE_ENVIRONMENT_NAMES } from '../constants'
+import { isValidExportName } from './rewriteDeniedImports'
+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)
+
+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')
+}
+
+function fromBase64Url(input: string): string {
+  return Buffer.from(input, 'base64url').toString('utf8')
+}
+
+// ---------------------------------------------------------------------------
+// Mock-runtime module helpers
+// ---------------------------------------------------------------------------
+
+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}`
+  })
+}
+
+export function mockRuntimeModuleIdFromViolation(
+  info: ViolationInfo,
+  mode: MockAccessMode,
+  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({
+    env: info.env,
+    importer: info.importer,
+    specifier: info.specifier,
+    trace: stripTraceFormatting(info.trace, root),
+    mode,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Mock-edge module ID builder
+// ---------------------------------------------------------------------------
+
+export function makeMockEdgeModuleId(
+  exports: Array<string>,
+  source: string,
+  runtimeId: string,
+): string {
+  const payload = {
+    source,
+    exports,
+    runtimeId,
+  }
+  return `${MOCK_EDGE_PREFIX}${toBase64Url(JSON.stringify(payload))}`
+}
+
+// ---------------------------------------------------------------------------
+// Load handler helpers — virtual module source code generators
+// ---------------------------------------------------------------------------
+
+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 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 (typeof prop === 'symbol') return undefined;
+      // Thenable support: prevent await from hanging
+      if (prop === 'then') return (fn) => Promise.resolve(fn(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 in children)) {
+        children[prop] = createMock(name + '.' + prop);
+      }
+      return children[prop];
+    },
+    apply() {
+      return createMock(name + '()');
+    },
+    construct() {
+      return createMock('new ' + name);
+    },
+  });
+  return proxy;
+}
+const mock = createMock('mock');
+export default mock;
+`,
+  }
+}
+
+export function loadMockEdgeModule(encodedPayload: string): { code: string } {
+  let payload: { exports?: Array<string>; runtimeId?: string }
+  try {
+    payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload
+  } catch {
+    payload = { exports: [] }
+  }
+  const names: Array<string> = Array.isArray(payload.exports)
+    ? payload.exports.filter(
+        (n): n is string => typeof n === 'string' && isValidExportName(n),
+      )
+    : []
+
+  const runtimeId: string =
+    typeof payload.runtimeId === 'string' && payload.runtimeId.length > 0
+      ? payload.runtimeId
+      : MOCK_MODULE_ID
+
+  const exportLines = names.map((n) => `export const ${n} = mock.${n};`)
+  return {
+    code: `
+ import mock from ${JSON.stringify(runtimeId)};
+   ${exportLines.join('\n')}
+   export default mock;
+   `,
+  }
+}
+
+export function loadMockRuntimeModule(encodedPayload: string): {
+  code: string
+} {
+  let payload: {
+    mode?: string
+    env?: string
+    importer?: string
+    specifier?: string
+    trace?: Array<unknown>
+  }
+  try {
+    payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload
+  } catch {
+    payload = {}
+  }
+
+  const mode: 'error' | 'warn' | 'off' =
+    payload.mode === 'warn' || payload.mode === 'off' ? payload.mode : 'error'
+
+  const meta = {
+    env: String(payload.env ?? ''),
+    importer: String(payload.importer ?? ''),
+    specifier: String(payload.specifier ?? ''),
+    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;
+}
+
+const mock = __createMock('mock');
+export default mock;
+`,
+  }
+}
+
+export function loadMarkerModule(): { code: string } {
+  return { code: 'export {}' }
+}

package/src/plugin.ts

@@ -17,6 +17,7 @@ import {
 } from './output-directory'
 import { postServerBuild } from './post-server-build'
 import { startCompilerPlugin } from './start-compiler-plugin/plugin'
+import { importProtectionPlugin } from './import-protection-plugin/plugin'
 import type {
   GetConfigFn,
   ResolvedStartConfig,
@@ -376,6 +377,12 @@ export function TanStackStartVitePluginCore(
       generateFunctionId: startPluginOpts?.serverFns?.generateFunctionId,
       providerEnvName: serverFnProviderEnv,
     }),
+    importProtectionPlugin({
+      getConfig,
+      framework: corePluginOpts.framework,
+      environments,
+      providerEnvName: serverFnProviderEnv,
+    }),
     tanStackStartRouter(startPluginOpts, getConfig, corePluginOpts),
     loadEnvPlugin(),
     startManifestPlugin({