@tanstack/start-plugin-core 1.161.4 → 1.162.0

package/dist/esm/import-protection-plugin/trace.js

@@ -1,4 +1,4 @@
-import * as path from "pathe";
+import { getOrCreate, relativizePath } from "./utils.js";
 class ImportGraph {
   /**
    * resolvedId -> Map<importer, specifier>
@@ -16,18 +16,11 @@ class ImportGraph {
   forwardEdges = /* @__PURE__ */ new Map();
   entries = /* @__PURE__ */ new Set();
   addEdge(resolved, importer, specifier) {
-    let importers = this.reverseEdges.get(resolved);
-    if (!importers) {
-      importers = /* @__PURE__ */ new Map();
-      this.reverseEdges.set(resolved, importers);
-    }
-    importers.set(importer, specifier);
-    let targets = this.forwardEdges.get(importer);
-    if (!targets) {
-      targets = /* @__PURE__ */ new Set();
-      this.forwardEdges.set(importer, targets);
-    }
-    targets.add(resolved);
+    getOrCreate(this.reverseEdges, resolved, () => /* @__PURE__ */ new Map()).set(
+      importer,
+      specifier
+    );
+    getOrCreate(this.forwardEdges, importer, () => /* @__PURE__ */ new Set()).add(resolved);
   }
   /** Convenience for tests/debugging. */
   getEdges(resolved) {
@@ -63,11 +56,11 @@ function buildTrace(graph, startNode, maxDepth = 20) {
   const depthByNode = /* @__PURE__ */ new Map([[startNode, 0]]);
   const down = /* @__PURE__ */ new Map();
   const queue = [startNode];
-  let queueIndex = 0;
+  let qi = 0;
   let root = 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) {
       const isEntry = graph.entries.has(node) || !importers || importers.size === 0;
@@ -103,13 +96,19 @@ function buildTrace(graph, startNode, maxDepth = 20) {
   }
   return trace;
 }
+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"
+];
+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"
+];
 function formatViolation(info, root) {
-  const rel = (p) => {
-    if (p.startsWith(root)) {
-      return path.relative(root, p);
-    }
-    return p;
-  };
+  const rel = (p) => relativizePath(p, root);
   const relLoc = (p, loc) => {
     const r = rel(p);
     const file = loc?.file ? rel(loc.file) : r;
@@ -162,18 +161,9 @@ function formatViolation(info, root) {
   lines.push(``);
   if (info.envType === "client") {
     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 {
     const snippetText = info.snippet?.lines.join("\n") ?? "";
     const looksLikeJsx = /<[A-Z]/.test(snippetText) || /\{.*\(.*\).*\}/.test(snippetText) && /</.test(snippetText);
@@ -183,21 +173,17 @@ function formatViolation(info, root) {
         `    - 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(``);
   return lines.join("\n");
 }
 export {
+  CLIENT_ENV_SUGGESTIONS,
   ImportGraph,
+  SERVER_ENV_SUGGESTIONS,
   buildTrace,
   formatViolation
 };

package/dist/esm/import-protection-plugin/trace.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace.js","sources":["../../../src/import-protection-plugin/trace.ts"],"sourcesContent":["import * as path from 'pathe'\n\nexport interface TraceEdge {\n  importer: string\n  specifier?: string\n}\n\n/**\n * Per-environment reverse import graph.\n * Maps a resolved module id to the set of modules that import it.\n */\nexport class ImportGraph {\n  /**\n   * resolvedId -> Map<importer, specifier>\n   *\n   * We use a Map instead of a Set of objects so edges dedupe correctly.\n   */\n  readonly reverseEdges: Map<string, Map<string, string | undefined>> =\n    new Map()\n\n  /**\n   * Forward-edge index: importer -> Set<resolvedId>.\n   *\n   * Maintained alongside reverseEdges so that {@link invalidate} can remove\n   * all outgoing edges for a file in O(outgoing-edges) instead of scanning\n   * every reverse-edge map in the graph.\n   */\n  private readonly forwardEdges: Map<string, Set<string>> = new Map()\n\n  readonly entries: Set<string> = new Set()\n\n  addEdge(resolved: string, importer: string, specifier?: string): void {\n    let importers = this.reverseEdges.get(resolved)\n    if (!importers) {\n      importers = new Map()\n      this.reverseEdges.set(resolved, importers)\n    }\n    // Last writer wins; good enough for trace display.\n    importers.set(importer, specifier)\n\n    // Maintain forward index\n    let targets = this.forwardEdges.get(importer)\n    if (!targets) {\n      targets = new Set()\n      this.forwardEdges.set(importer, targets)\n    }\n    targets.add(resolved)\n  }\n\n  /** Convenience for tests/debugging. */\n  getEdges(resolved: string): Set<TraceEdge> | undefined {\n    const importers = this.reverseEdges.get(resolved)\n    if (!importers) return undefined\n    const out = new Set<TraceEdge>()\n    for (const [importer, specifier] of importers) {\n      out.add({ importer, specifier })\n    }\n    return out\n  }\n\n  addEntry(id: string): void {\n    this.entries.add(id)\n  }\n\n  clear(): void {\n    this.reverseEdges.clear()\n    this.forwardEdges.clear()\n    this.entries.clear()\n  }\n\n  invalidate(id: string): void {\n    // Remove all outgoing edges (id as importer) using the forward index.\n    const targets = this.forwardEdges.get(id)\n    if (targets) {\n      for (const resolved of targets) {\n        this.reverseEdges.get(resolved)?.delete(id)\n      }\n      this.forwardEdges.delete(id)\n    }\n    // Remove as a target (id as resolved module)\n    this.reverseEdges.delete(id)\n  }\n}\n\nexport interface TraceStep {\n  file: string\n  specifier?: string\n  line?: number\n  column?: number\n}\n\nexport interface Loc {\n  file?: string\n  line: number\n  column: number\n}\n\n/**\n * BFS from a node upward through reverse edges to find the shortest\n * path to an entry module.\n */\nexport function buildTrace(\n  graph: ImportGraph,\n  startNode: string,\n  maxDepth: number = 20,\n): Array<TraceStep> {\n  // BFS upward (startNode -> importers -> ...)\n  const visited = new Set<string>([startNode])\n  const depthByNode = new Map<string, number>([[startNode, 0]])\n\n  // For any importer we visit, store the \"down\" link back toward startNode.\n  // importer --(specifier)--> next\n  const down = new Map<string, { next: string; specifier?: string }>()\n\n  const queue: Array<string> = [startNode]\n  let queueIndex = 0\n\n  let root: string | null = null\n\n  while (queueIndex < queue.length) {\n    const node = queue[queueIndex++]!\n    const depth = depthByNode.get(node) ?? 0\n    const importers = graph.reverseEdges.get(node)\n\n    if (node !== startNode) {\n      const isEntry =\n        graph.entries.has(node) || !importers || importers.size === 0\n      if (isEntry) {\n        root = node\n        break\n      }\n    }\n\n    if (depth >= maxDepth) {\n      continue\n    }\n\n    if (!importers || importers.size === 0) {\n      continue\n    }\n\n    for (const [importer, specifier] of importers) {\n      if (visited.has(importer)) continue\n      visited.add(importer)\n      depthByNode.set(importer, depth + 1)\n      down.set(importer, { next: node, specifier })\n      queue.push(importer)\n    }\n  }\n\n  // Best-effort: if we never found a root, just start from the original node.\n  if (!root) {\n    root = startNode\n  }\n\n  const trace: Array<TraceStep> = []\n  let current = root\n  for (let i = 0; i <= maxDepth + 1; i++) {\n    const link = down.get(current)\n    trace.push({ file: current, specifier: link?.specifier })\n    if (!link) break\n    current = link.next\n  }\n\n  return trace\n}\n\nexport interface ViolationInfo {\n  env: string\n  envType: 'client' | 'server'\n  type: 'specifier' | 'file' | 'marker'\n  behavior: 'error' | 'mock'\n  pattern?: string | RegExp\n  specifier: string\n  importer: string\n  importerLoc?: Loc\n  resolved?: string\n  trace: Array<TraceStep>\n  message: string\n  /** Vitest-style code snippet showing the offending usage in the leaf module. */\n  snippet?: {\n    lines: Array<string>\n    highlightLine: number\n    location: string\n  }\n}\n\nexport function formatViolation(info: ViolationInfo, root: string): string {\n  const rel = (p: string) => {\n    if (p.startsWith(root)) {\n      return path.relative(root, p)\n    }\n    return p\n  }\n\n  const relLoc = (p: string, loc?: Loc) => {\n    const r = rel(p)\n    const file = loc?.file ? rel(loc.file) : r\n    return loc ? `${file}:${loc.line}:${loc.column}` : r\n  }\n\n  const relTraceStep = (step: TraceStep): string => {\n    const file = rel(step.file)\n    if (step.line == null) return file\n    const col = step.column ?? 1\n    return `${file}:${step.line}:${col}`\n  }\n\n  const lines: Array<string> = []\n  lines.push(``)\n  lines.push(`[import-protection] Import denied in ${info.envType} environment`)\n  lines.push(``)\n\n  if (info.type === 'specifier') {\n    lines.push(`  Denied by specifier pattern: ${String(info.pattern)}`)\n  } else if (info.type === 'file') {\n    lines.push(`  Denied by file pattern: ${String(info.pattern)}`)\n  } else {\n    lines.push(\n      `  Denied by marker: module is restricted to the opposite environment`,\n    )\n  }\n\n  lines.push(`  Importer: ${relLoc(info.importer, info.importerLoc)}`)\n  lines.push(`  Import: \"${rel(info.specifier)}\"`)\n  if (info.resolved) {\n    lines.push(`  Resolved: ${rel(info.resolved)}`)\n  }\n\n  if (info.trace.length > 0) {\n    lines.push(``)\n    lines.push(`  Trace:`)\n    for (let i = 0; i < info.trace.length; i++) {\n      const step = info.trace[i]!\n      const isEntry = i === 0\n      const tag = isEntry ? ' (entry)' : ''\n      const spec = step.specifier ? ` (import \"${rel(step.specifier)}\")` : ''\n      lines.push(`    ${i + 1}. ${relTraceStep(step)}${tag}${spec}`)\n    }\n  }\n\n  if (info.snippet) {\n    lines.push(``)\n    lines.push(`  Code:`)\n    for (const snippetLine of info.snippet.lines) {\n      lines.push(snippetLine)\n    }\n    lines.push(``)\n    lines.push(`  ${rel(info.snippet.location)}`)\n  }\n\n  lines.push(``)\n\n  // Add suggestions\n  if (info.envType === 'client') {\n    // Server-only code leaking into the client environment\n    lines.push(`  Suggestions:`)\n    lines.push(\n      `    - Use createServerFn().handler(() => ...) to keep the logic on the server and call it from the client via an RPC bridge`,\n    )\n    lines.push(\n      `    - Use createServerOnlyFn(() => ...) to mark it as server-only (it will throw if accidentally called from the client)`,\n    )\n    lines.push(\n      `    - Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations`,\n    )\n    lines.push(\n      `    - Move the server-only import out of this file into a separate .server.ts module that is not imported by any client code`,\n    )\n  } else {\n    // Client-only code leaking into the server environment\n    const snippetText = info.snippet?.lines.join('\\n') ?? ''\n    const looksLikeJsx =\n      /<[A-Z]/.test(snippetText) ||\n      (/\\{.*\\(.*\\).*\\}/.test(snippetText) && /</.test(snippetText))\n\n    lines.push(`  Suggestions:`)\n    if (looksLikeJsx) {\n      lines.push(\n        `    - Wrap the JSX in <ClientOnly fallback={<Loading />}>...</ClientOnly> so it only renders in the browser after hydration`,\n      )\n    }\n    lines.push(\n      `    - Use createClientOnlyFn(() => ...) to mark it as client-only (returns undefined on the server)`,\n    )\n    lines.push(\n      `    - Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations`,\n    )\n    lines.push(\n      `    - Move the client-only import out of this file into a separate .client.ts module that is not imported by any server code`,\n    )\n  }\n\n  lines.push(``)\n  return lines.join('\\n')\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"trace.js","sources":["../../../src/import-protection-plugin/trace.ts"],"sourcesContent":["import { getOrCreate, relativizePath } from './utils'\n\nexport interface TraceEdge {\n  importer: string\n  specifier?: string\n}\n\n/**\n * Per-environment reverse import graph.\n * Maps a resolved module id to the set of modules that import it.\n */\nexport class ImportGraph {\n  /**\n   * resolvedId -> Map<importer, specifier>\n   *\n   * We use a Map instead of a Set of objects so edges dedupe correctly.\n   */\n  readonly reverseEdges: Map<string, Map<string, string | undefined>> =\n    new Map()\n\n  /**\n   * Forward-edge index: importer -> Set<resolvedId>.\n   *\n   * Maintained alongside reverseEdges so that {@link invalidate} can remove\n   * all outgoing edges for a file in O(outgoing-edges) instead of scanning\n   * every reverse-edge map in the graph.\n   */\n  private readonly forwardEdges: Map<string, Set<string>> = new Map()\n\n  readonly entries: Set<string> = new Set()\n\n  addEdge(resolved: string, importer: string, specifier?: string): void {\n    getOrCreate(this.reverseEdges, resolved, () => new Map()).set(\n      importer,\n      specifier,\n    )\n    getOrCreate(this.forwardEdges, importer, () => new Set()).add(resolved)\n  }\n\n  /** Convenience for tests/debugging. */\n  getEdges(resolved: string): Set<TraceEdge> | undefined {\n    const importers = this.reverseEdges.get(resolved)\n    if (!importers) return undefined\n    const out = new Set<TraceEdge>()\n    for (const [importer, specifier] of importers) {\n      out.add({ importer, specifier })\n    }\n    return out\n  }\n\n  addEntry(id: string): void {\n    this.entries.add(id)\n  }\n\n  clear(): void {\n    this.reverseEdges.clear()\n    this.forwardEdges.clear()\n    this.entries.clear()\n  }\n\n  invalidate(id: string): void {\n    // Remove all outgoing edges (id as importer) using the forward index.\n    const targets = this.forwardEdges.get(id)\n    if (targets) {\n      for (const resolved of targets) {\n        this.reverseEdges.get(resolved)?.delete(id)\n      }\n      this.forwardEdges.delete(id)\n    }\n    // Remove as a target (id as resolved module)\n    this.reverseEdges.delete(id)\n  }\n}\n\nexport interface TraceStep {\n  file: string\n  specifier?: string\n  line?: number\n  column?: number\n}\n\nexport interface Loc {\n  file?: string\n  line: number\n  column: number\n}\n\n/**\n * BFS from a node upward through reverse edges to find the shortest\n * path to an entry module.\n */\nexport function buildTrace(\n  graph: ImportGraph,\n  startNode: string,\n  maxDepth: number = 20,\n): Array<TraceStep> {\n  // BFS upward (startNode -> importers -> ...)\n  const visited = new Set<string>([startNode])\n  const depthByNode = new Map<string, number>([[startNode, 0]])\n\n  // For any importer we visit, store the \"down\" link back toward startNode.\n  // importer --(specifier)--> next\n  const down = new Map<string, { next: string; specifier?: string }>()\n\n  const queue: Array<string> = [startNode]\n  let qi = 0\n\n  let root: string | null = null\n\n  while (qi < queue.length) {\n    const node = queue[qi++]!\n    const depth = depthByNode.get(node)!\n    const importers = graph.reverseEdges.get(node)\n\n    if (node !== startNode) {\n      const isEntry =\n        graph.entries.has(node) || !importers || importers.size === 0\n      if (isEntry) {\n        root = node\n        break\n      }\n    }\n\n    if (depth >= maxDepth) {\n      continue\n    }\n\n    if (!importers || importers.size === 0) {\n      continue\n    }\n\n    for (const [importer, specifier] of importers) {\n      if (visited.has(importer)) continue\n      visited.add(importer)\n      depthByNode.set(importer, depth + 1)\n      down.set(importer, { next: node, specifier })\n      queue.push(importer)\n    }\n  }\n\n  // Best-effort: if we never found a root, just start from the original node.\n  if (!root) {\n    root = startNode\n  }\n\n  const trace: Array<TraceStep> = []\n  let current = root\n  for (let i = 0; i <= maxDepth + 1; i++) {\n    const link = down.get(current)\n    trace.push({ file: current, specifier: link?.specifier })\n    if (!link) break\n    current = link.next\n  }\n\n  return trace\n}\n\nexport interface ViolationInfo {\n  env: string\n  envType: 'client' | 'server'\n  type: 'specifier' | 'file' | 'marker'\n  behavior: 'error' | 'mock'\n  pattern?: string | RegExp\n  specifier: string\n  importer: string\n  importerLoc?: Loc\n  resolved?: string\n  trace: Array<TraceStep>\n  message: string\n  /** Vitest-style code snippet showing the offending usage in the leaf module. */\n  snippet?: {\n    lines: Array<string>\n    highlightLine: number\n    location: string\n  }\n}\n\n/**\n * Suggestion strings for server-only code leaking into client environments.\n * Used by both `formatViolation` (terminal) and runtime mock modules (browser).\n */\nexport const CLIENT_ENV_SUGGESTIONS = [\n  'Use createServerFn().handler(() => ...) to keep the logic on the server and call it from the client via an RPC bridge',\n  'Use createServerOnlyFn(() => ...) to mark it as server-only (it will throw if accidentally called from the client)',\n  'Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations',\n  'Move the server-only import out of this file into a separate .server.ts module that is not imported by any client code',\n] as const\n\n/**\n * Suggestion strings for client-only code leaking into server environments.\n * The JSX-specific suggestion is conditionally prepended by `formatViolation`.\n */\nexport const SERVER_ENV_SUGGESTIONS = [\n  'Use createClientOnlyFn(() => ...) to mark it as client-only (returns undefined on the server)',\n  'Use createIsomorphicFn().client(() => ...).server(() => ...) to provide separate client and server implementations',\n  'Move the client-only import out of this file into a separate .client.ts module that is not imported by any server code',\n] as const\n\nexport function formatViolation(info: ViolationInfo, root: string): string {\n  const rel = (p: string) => relativizePath(p, root)\n\n  const relLoc = (p: string, loc?: Loc) => {\n    const r = rel(p)\n    const file = loc?.file ? rel(loc.file) : r\n    return loc ? `${file}:${loc.line}:${loc.column}` : r\n  }\n\n  const relTraceStep = (step: TraceStep): string => {\n    const file = rel(step.file)\n    if (step.line == null) return file\n    const col = step.column ?? 1\n    return `${file}:${step.line}:${col}`\n  }\n\n  const lines: Array<string> = []\n  lines.push(``)\n  lines.push(`[import-protection] Import denied in ${info.envType} environment`)\n  lines.push(``)\n\n  if (info.type === 'specifier') {\n    lines.push(`  Denied by specifier pattern: ${String(info.pattern)}`)\n  } else if (info.type === 'file') {\n    lines.push(`  Denied by file pattern: ${String(info.pattern)}`)\n  } else {\n    lines.push(\n      `  Denied by marker: module is restricted to the opposite environment`,\n    )\n  }\n\n  lines.push(`  Importer: ${relLoc(info.importer, info.importerLoc)}`)\n  lines.push(`  Import: \"${rel(info.specifier)}\"`)\n  if (info.resolved) {\n    lines.push(`  Resolved: ${rel(info.resolved)}`)\n  }\n\n  if (info.trace.length > 0) {\n    lines.push(``)\n    lines.push(`  Trace:`)\n    for (let i = 0; i < info.trace.length; i++) {\n      const step = info.trace[i]!\n      const isEntry = i === 0\n      const tag = isEntry ? ' (entry)' : ''\n      const spec = step.specifier ? ` (import \"${rel(step.specifier)}\")` : ''\n      lines.push(`    ${i + 1}. ${relTraceStep(step)}${tag}${spec}`)\n    }\n  }\n\n  if (info.snippet) {\n    lines.push(``)\n    lines.push(`  Code:`)\n    for (const snippetLine of info.snippet.lines) {\n      lines.push(snippetLine)\n    }\n    lines.push(``)\n    lines.push(`  ${rel(info.snippet.location)}`)\n  }\n\n  lines.push(``)\n\n  // Add suggestions\n  if (info.envType === 'client') {\n    lines.push(`  Suggestions:`)\n    for (const s of CLIENT_ENV_SUGGESTIONS) {\n      lines.push(`    - ${s}`)\n    }\n  } else {\n    const snippetText = info.snippet?.lines.join('\\n') ?? ''\n    const looksLikeJsx =\n      /<[A-Z]/.test(snippetText) ||\n      (/\\{.*\\(.*\\).*\\}/.test(snippetText) && /</.test(snippetText))\n\n    lines.push(`  Suggestions:`)\n    if (looksLikeJsx) {\n      lines.push(\n        `    - Wrap the JSX in <ClientOnly fallback={<Loading />}>...</ClientOnly> so it only renders in the browser after hydration`,\n      )\n    }\n    for (const s of SERVER_ENV_SUGGESTIONS) {\n      lines.push(`    - ${s}`)\n    }\n  }\n\n  lines.push(``)\n  return lines.join('\\n')\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/import-protection-plugin/utils.d.ts

@@ -1,8 +1,12 @@
 export type Pattern = string | RegExp;
 export declare function dedupePatterns(patterns: Array<Pattern>): Array<Pattern>;
 export declare function stripViteQuery(id: string): string;
-/**
- * Strip Vite query parameters and normalize the path in one step.
- * Replaces the repeated `normalizePath(stripViteQuery(id))` pattern.
- */
 export declare function normalizeFilePath(id: string): string;
+/** Clear the memoization cache (call from buildStart to bound growth). */
+export declare function clearNormalizeFilePathCache(): void;
+export declare function escapeRegExp(s: string): string;
+/** Get a value from a Map, creating it with `factory` if absent. */
+export declare function getOrCreate<TKey, TValue>(map: Map<TKey, TValue>, key: TKey, factory: () => TValue): TValue;
+/** Make a path relative to `root`, keeping non-rooted paths as-is. */
+export declare function relativizePath(p: string, root: string): string;
+export declare function extractImportSources(code: string): Array<string>;

package/dist/esm/import-protection-plugin/utils.js

@@ -18,12 +18,54 @@ function stripViteQuery(id) {
   if (h === -1) return id.slice(0, q);
   return id.slice(0, Math.min(q, h));
 }
+const normalizeFilePathCache = /* @__PURE__ */ new Map();
 function normalizeFilePath(id) {
-  return normalizePath(stripViteQuery(id));
+  let result = normalizeFilePathCache.get(id);
+  if (result === void 0) {
+    result = normalizePath(stripViteQuery(id));
+    normalizeFilePathCache.set(id, result);
+  }
+  return result;
+}
+function clearNormalizeFilePathCache() {
+  normalizeFilePathCache.clear();
+}
+const importSourceRe = /\bfrom\s+(?:"([^"]+)"|'([^']+)')|import\s*\(\s*(?:"([^"]+)"|'([^']+)')\s*\)/g;
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function getOrCreate(map, key, factory) {
+  let value = map.get(key);
+  if (value === void 0) {
+    value = factory();
+    map.set(key, value);
+  }
+  return value;
+}
+function relativizePath(p, root) {
+  if (!p.startsWith(root)) return p;
+  const ch = p.charCodeAt(root.length);
+  if (ch !== 47 && !Number.isNaN(ch)) return p;
+  return ch === 47 ? p.slice(root.length + 1) : p.slice(root.length);
+}
+function extractImportSources(code) {
+  const sources = [];
+  let m;
+  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;
 }
 export {
+  clearNormalizeFilePathCache,
   dedupePatterns,
+  escapeRegExp,
+  extractImportSources,
+  getOrCreate,
   normalizeFilePath,
+  relativizePath,
   stripViteQuery
 };
 //# sourceMappingURL=utils.js.map

package/dist/esm/import-protection-plugin/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../../src/import-protection-plugin/utils.ts"],"sourcesContent":["import { normalizePath } from 'vite'\n\nexport type Pattern = string | RegExp\n\nexport function dedupePatterns(patterns: Array<Pattern>): Array<Pattern> {\n  const out: Array<Pattern> = []\n  const seen = new Set<string>()\n  for (const p of patterns) {\n    const key = typeof p === 'string' ? `s:${p}` : `r:${p.toString()}`\n    if (seen.has(key)) continue\n    seen.add(key)\n    out.push(p)\n  }\n  return out\n}\n\nexport function stripViteQuery(id: string): string {\n  const q = id.indexOf('?')\n  const h = id.indexOf('#')\n  if (q === -1 && h === -1) return id\n  if (q === -1) return id.slice(0, h)\n  if (h === -1) return id.slice(0, q)\n  return id.slice(0, Math.min(q, h))\n}\n\n/**\n * Strip Vite query parameters and normalize the path in one step.\n * Replaces the repeated `normalizePath(stripViteQuery(id))` pattern.\n */\nexport function normalizeFilePath(id: string): string {\n  return normalizePath(stripViteQuery(id))\n}\n"],"names":[],"mappings":";AAIO,SAAS,eAAe,UAA0C;AACvE,QAAM,MAAsB,CAAA;AAC5B,QAAM,2BAAW,IAAA;AACjB,aAAW,KAAK,UAAU;AACxB,UAAM,MAAM,OAAO,MAAM,WAAW,KAAK,CAAC,KAAK,KAAK,EAAE,SAAA,CAAU;AAChE,QAAI,KAAK,IAAI,GAAG,EAAG;AACnB,SAAK,IAAI,GAAG;AACZ,QAAI,KAAK,CAAC;AAAA,EACZ;AACA,SAAO;AACT;AAEO,SAAS,eAAe,IAAoB;AACjD,QAAM,IAAI,GAAG,QAAQ,GAAG;AACxB,QAAM,IAAI,GAAG,QAAQ,GAAG;AACxB,MAAI,MAAM,MAAM,MAAM,GAAI,QAAO;AACjC,MAAI,MAAM,GAAI,QAAO,GAAG,MAAM,GAAG,CAAC;AAClC,MAAI,MAAM,GAAI,QAAO,GAAG,MAAM,GAAG,CAAC;AAClC,SAAO,GAAG,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;AACnC;AAMO,SAAS,kBAAkB,IAAoB;AACpD,SAAO,cAAc,eAAe,EAAE,CAAC;AACzC;"}
+{"version":3,"file":"utils.js","sources":["../../../src/import-protection-plugin/utils.ts"],"sourcesContent":["import { normalizePath } from 'vite'\n\nexport type Pattern = string | RegExp\n\nexport function dedupePatterns(patterns: Array<Pattern>): Array<Pattern> {\n  const out: Array<Pattern> = []\n  const seen = new Set<string>()\n  for (const p of patterns) {\n    const key = typeof p === 'string' ? `s:${p}` : `r:${p.toString()}`\n    if (seen.has(key)) continue\n    seen.add(key)\n    out.push(p)\n  }\n  return out\n}\n\nexport function stripViteQuery(id: string): string {\n  const q = id.indexOf('?')\n  const h = id.indexOf('#')\n  if (q === -1 && h === -1) return id\n  if (q === -1) return id.slice(0, h)\n  if (h === -1) return id.slice(0, q)\n  return id.slice(0, Math.min(q, h))\n}\n\n/**\n * Strip Vite query parameters and normalize the path in one step.\n * Replaces the repeated `normalizePath(stripViteQuery(id))` pattern.\n *\n * Results are memoized because the same module IDs are processed many\n * times across resolveId, transform, and trace-building hooks.\n */\nconst normalizeFilePathCache = new Map<string, string>()\nexport function normalizeFilePath(id: string): string {\n  let result = normalizeFilePathCache.get(id)\n  if (result === undefined) {\n    result = normalizePath(stripViteQuery(id))\n    normalizeFilePathCache.set(id, result)\n  }\n  return result\n}\n\n/** Clear the memoization cache (call from buildStart to bound growth). */\nexport function clearNormalizeFilePathCache(): void {\n  normalizeFilePathCache.clear()\n}\n\n/**\n * Lightweight regex to extract all import/re-export source strings from\n * post-transform code.  Matches:\n *   - `from \"...\"` / `from '...'`   (static import/export)\n *   - `import(\"...\")` / `import('...')` (dynamic import)\n */\nconst importSourceRe =\n  /\\bfrom\\s+(?:\"([^\"]+)\"|'([^']+)')|import\\s*\\(\\s*(?:\"([^\"]+)\"|'([^']+)')\\s*\\)/g\n\nexport function escapeRegExp(s: string): string {\n  return s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n}\n\n/** Get a value from a Map, creating it with `factory` if absent. */\nexport function getOrCreate<TKey, TValue>(\n  map: Map<TKey, TValue>,\n  key: TKey,\n  factory: () => TValue,\n): TValue {\n  let value = map.get(key)\n  if (value === undefined) {\n    value = factory()\n    map.set(key, value)\n  }\n  return value\n}\n\n/** Make a path relative to `root`, keeping non-rooted paths as-is. */\nexport function relativizePath(p: string, root: string): string {\n  if (!p.startsWith(root)) return p\n  const ch = p.charCodeAt(root.length)\n  // Must be followed by a separator or end-of-string to be a true child\n  if (ch !== 47 && !Number.isNaN(ch)) return p\n  return ch === 47 ? p.slice(root.length + 1) : p.slice(root.length)\n}\n\nexport function extractImportSources(code: string): Array<string> {\n  const sources: Array<string> = []\n  let m: RegExpExecArray | null\n  importSourceRe.lastIndex = 0\n  while ((m = importSourceRe.exec(code)) !== null) {\n    const src = m[1] ?? m[2] ?? m[3] ?? m[4]\n    if (src) sources.push(src)\n  }\n  return sources\n}\n"],"names":[],"mappings":";AAIO,SAAS,eAAe,UAA0C;AACvE,QAAM,MAAsB,CAAA;AAC5B,QAAM,2BAAW,IAAA;AACjB,aAAW,KAAK,UAAU;AACxB,UAAM,MAAM,OAAO,MAAM,WAAW,KAAK,CAAC,KAAK,KAAK,EAAE,SAAA,CAAU;AAChE,QAAI,KAAK,IAAI,GAAG,EAAG;AACnB,SAAK,IAAI,GAAG;AACZ,QAAI,KAAK,CAAC;AAAA,EACZ;AACA,SAAO;AACT;AAEO,SAAS,eAAe,IAAoB;AACjD,QAAM,IAAI,GAAG,QAAQ,GAAG;AACxB,QAAM,IAAI,GAAG,QAAQ,GAAG;AACxB,MAAI,MAAM,MAAM,MAAM,GAAI,QAAO;AACjC,MAAI,MAAM,GAAI,QAAO,GAAG,MAAM,GAAG,CAAC;AAClC,MAAI,MAAM,GAAI,QAAO,GAAG,MAAM,GAAG,CAAC;AAClC,SAAO,GAAG,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;AACnC;AASA,MAAM,6CAA6B,IAAA;AAC5B,SAAS,kBAAkB,IAAoB;AACpD,MAAI,SAAS,uBAAuB,IAAI,EAAE;AAC1C,MAAI,WAAW,QAAW;AACxB,aAAS,cAAc,eAAe,EAAE,CAAC;AACzC,2BAAuB,IAAI,IAAI,MAAM;AAAA,EACvC;AACA,SAAO;AACT;AAGO,SAAS,8BAAoC;AAClD,yBAAuB,MAAA;AACzB;AAQA,MAAM,iBACJ;AAEK,SAAS,aAAa,GAAmB;AAC9C,SAAO,EAAE,QAAQ,uBAAuB,MAAM;AAChD;AAGO,SAAS,YACd,KACA,KACA,SACQ;AACR,MAAI,QAAQ,IAAI,IAAI,GAAG;AACvB,MAAI,UAAU,QAAW;AACvB,YAAQ,QAAA;AACR,QAAI,IAAI,KAAK,KAAK;AAAA,EACpB;AACA,SAAO;AACT;AAGO,SAAS,eAAe,GAAW,MAAsB;AAC9D,MAAI,CAAC,EAAE,WAAW,IAAI,EAAG,QAAO;AAChC,QAAM,KAAK,EAAE,WAAW,KAAK,MAAM;AAEnC,MAAI,OAAO,MAAM,CAAC,OAAO,MAAM,EAAE,EAAG,QAAO;AAC3C,SAAO,OAAO,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM;AACnE;AAEO,SAAS,qBAAqB,MAA6B;AAChE,QAAM,UAAyB,CAAA;AAC/B,MAAI;AACJ,iBAAe,YAAY;AAC3B,UAAQ,IAAI,eAAe,KAAK,IAAI,OAAO,MAAM;AAC/C,UAAM,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC;AACvC,QAAI,IAAK,SAAQ,KAAK,GAAG;AAAA,EAC3B;AACA,SAAO;AACT;"}

package/dist/esm/import-protection-plugin/virtualModules.d.ts

@@ -7,7 +7,12 @@ export declare const MOCK_RUNTIME_PREFIX = "tanstack-start-import-protection:moc
 export declare const RESOLVED_MOCK_RUNTIME_PREFIX: string;
 export declare const MARKER_PREFIX = "tanstack-start-import-protection:marker:";
 export declare const RESOLVED_MARKER_PREFIX: string;
-export type MockAccessMode = 'error' | 'warn' | 'off';
+type MockAccessMode = 'error' | 'warn' | 'off';
+/**
+ * Compact runtime suggestion text for browser console, derived from
+ * {@link CLIENT_ENV_SUGGESTIONS} so there's a single source of truth.
+ */
+export declare const RUNTIME_SUGGESTION_TEXT: string;
 export declare function mockRuntimeModuleIdFromViolation(info: ViolationInfo, mode: MockAccessMode, root: string): string;
 export declare function makeMockEdgeModuleId(exports: Array<string>, source: string, runtimeId: string): string;
 export declare function loadSilentMockModule(): {
@@ -23,3 +28,4 @@ export declare function loadMockRuntimeModule(encodedPayload: string): {
 export declare function loadMarkerModule(): {
     code: string;
 };
+export {};

package/dist/esm/import-protection-plugin/virtualModules.js

@@ -1,8 +1,8 @@
-import { normalizePath } from "vite";
-import * as path from "pathe";
 import { resolveViteId } from "../utils.js";
 import { VITE_ENVIRONMENT_NAMES } from "../constants.js";
 import { isValidExportName } from "./rewriteDeniedImports.js";
+import { CLIENT_ENV_SUGGESTIONS } from "./trace.js";
+import { relativizePath } from "./utils.js";
 const MOCK_MODULE_ID = "tanstack-start-import-protection:mock";
 const RESOLVED_MOCK_MODULE_ID = resolveViteId(MOCK_MODULE_ID);
 const MOCK_EDGE_PREFIX = "tanstack-start-import-protection:mock-edge:";
@@ -17,118 +17,34 @@ function toBase64Url(input) {
 function fromBase64Url(input) {
   return Buffer.from(input, "base64url").toString("utf8");
 }
-function makeMockRuntimeModuleId(payload) {
-  return `${MOCK_RUNTIME_PREFIX}${toBase64Url(JSON.stringify(payload))}`;
-}
-function stripTraceFormatting(trace, root) {
-  const rel = (p) => {
-    if (p.startsWith(root)) return normalizePath(path.relative(root, p));
-    return p;
-  };
-  return trace.map((s) => {
+const RUNTIME_SUGGESTION_TEXT = "Fix: " + CLIENT_ENV_SUGGESTIONS.join(". ") + '. To disable these runtime diagnostics, set importProtection.mockAccess: "off".';
+function mockRuntimeModuleIdFromViolation(info, mode, root) {
+  if (mode === "off") return MOCK_MODULE_ID;
+  if (info.env !== VITE_ENVIRONMENT_NAMES.client) return MOCK_MODULE_ID;
+  const rel = (p) => 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}`;
   });
-}
-function mockRuntimeModuleIdFromViolation(info, mode, root) {
-  if (mode === "off") return MOCK_MODULE_ID;
-  if (info.env !== VITE_ENVIRONMENT_NAMES.client) return MOCK_MODULE_ID;
-  return makeMockRuntimeModuleId({
+  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))}`;
 }
 function makeMockEdgeModuleId(exports, source, runtimeId) {
-  const payload = {
-    source,
-    exports,
-    runtimeId
-  };
+  const payload = { source, exports, runtimeId };
   return `${MOCK_EDGE_PREFIX}${toBase64Url(JSON.stringify(payload))}`;
 }
-function loadSilentMockModule() {
-  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;
-`
-  };
-}
-function loadMockEdgeModule(encodedPayload) {
-  let payload;
-  try {
-    payload = JSON.parse(fromBase64Url(encodedPayload));
-  } catch {
-    payload = { exports: [] };
-  }
-  const names = Array.isArray(payload.exports) ? payload.exports.filter(
-    (n) => typeof n === "string" && isValidExportName(n)
-  ) : [];
-  const runtimeId = 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;
-   `
-  };
-}
-function loadMockRuntimeModule(encodedPayload) {
-  let payload;
-  try {
-    payload = JSON.parse(fromBase64Url(encodedPayload));
-  } catch {
-    payload = {};
-  }
-  const mode = 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)};
+function generateMockCode(diagnostics) {
+  const fnName = diagnostics ? "__createMock" : "createMock";
+  const hasDiag = !!diagnostics;
+  const preamble = hasDiag ? `const __meta = ${JSON.stringify(diagnostics.meta)};
+const __mode = ${JSON.stringify(diagnostics.mode)};
 
 const __seen = new Set();
 function __report(action, accessPath) {
@@ -147,7 +63,7 @@ function __report(action, accessPath) {
     '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".';
+    '\\n\\n' + ${JSON.stringify(RUNTIME_SUGGESTION_TEXT)};
 
   const err = new Error(msg);
   if (__mode === 'warn') {
@@ -156,22 +72,8 @@ function __report(action, accessPath) {
     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.
+` : "";
+  const diagGetTraps = hasDiag ? `
       if (prop === Symbol.toPrimitive) {
         return () => {
           __report('toPrimitive', name);
@@ -183,38 +85,104 @@ function __createMock(name) {
           __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) {
+      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); };${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() {
-      __report('call', name + '()');
-      return __createMock(name + '()');
+      ${applyBody}
     },
     construct() {
-      __report('construct', 'new ' + name);
-      return __createMock('new ' + name);
-    },
-    set(_target, prop) {
-      __report('set', name + '.' + String(prop));
-      return true;
-    },
+      ${constructBody}
+    },${setTrap}
   });
-
   return proxy;
 }
-
-const mock = __createMock('mock');
+const mock = ${fnName}('mock');
+export default mock;
+`;
+}
+function loadSilentMockModule() {
+  return { syntheticNamedExports: true, code: generateMockCode() };
+}
+function loadMockEdgeModule(encodedPayload) {
+  let payload;
+  try {
+    payload = JSON.parse(fromBase64Url(encodedPayload));
+  } catch {
+    payload = { exports: [] };
+  }
+  const names = Array.isArray(payload.exports) ? payload.exports.filter(
+    (n) => typeof n === "string" && n.length > 0 && n !== "default"
+  ) : [];
+  const runtimeId = typeof payload.runtimeId === "string" && payload.runtimeId.length > 0 ? payload.runtimeId : MOCK_MODULE_ID;
+  const exportLines = [];
+  const stringExports = [];
+  for (let i = 0; i < names.length; i++) {
+    const n = names[i];
+    if (isValidExportName(n)) {
+      exportLines.push(`export const ${n} = mock.${n};`);
+    } else {
+      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;
 `
   };
 }
+function loadMockRuntimeModule(encodedPayload) {
+  let payload;
+  try {
+    payload = JSON.parse(fromBase64Url(encodedPayload));
+  } catch {
+    payload = {};
+  }
+  const mode = 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: generateMockCode({ meta, mode }) };
+}
+const MARKER_MODULE_RESULT = { code: "export {}" };
 function loadMarkerModule() {
-  return { code: "export {}" };
+  return MARKER_MODULE_RESULT;
 }
 export {
   MARKER_PREFIX,
@@ -225,6 +193,7 @@ export {
   RESOLVED_MOCK_EDGE_PREFIX,
   RESOLVED_MOCK_MODULE_ID,
   RESOLVED_MOCK_RUNTIME_PREFIX,
+  RUNTIME_SUGGESTION_TEXT,
   loadMarkerModule,
   loadMockEdgeModule,
   loadMockRuntimeModule,