@tanstack/start-plugin-core 1.162.6 → 1.162.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/dist/esm/import-protection-plugin/plugin.js +74 -17
  2. package/dist/esm/import-protection-plugin/plugin.js.map +1 -1
  3. package/dist/esm/import-protection-plugin/trace.js +1 -1
  4. package/dist/esm/import-protection-plugin/virtualModules.d.ts +7 -0
  5. package/dist/esm/import-protection-plugin/virtualModules.js +4 -0
  6. package/dist/esm/import-protection-plugin/virtualModules.js.map +1 -1
  7. package/dist/esm/schema.d.ts +9 -9
  8. package/dist/esm/schema.js +7 -1
  9. package/dist/esm/schema.js.map +1 -1
  10. package/package.json +3 -3
  11. package/src/import-protection-plugin/INTERNALS.md +290 -0
  12. package/src/import-protection-plugin/plugin.ts +147 -22
  13. package/src/import-protection-plugin/virtualModules.ts +8 -0
  14. package/src/schema.ts +7 -1
package/dist/esm/import-protection-plugin/virtualModules.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"virtualModules.js","sources":["../../../src/import-protection-plugin/virtualModules.ts"],"sourcesContent":["import { resolveViteId } from '../utils'\nimport { VITE_ENVIRONMENT_NAMES } from '../constants'\nimport { isValidExportName } from './rewriteDeniedImports'\nimport { CLIENT_ENV_SUGGESTIONS } from './trace'\nimport { relativizePath } from './utils'\nimport type { ViolationInfo } from './trace'\n\nexport const MOCK_MODULE_ID = 'tanstack-start-import-protection:mock'\nexport const RESOLVED_MOCK_MODULE_ID = resolveViteId(MOCK_MODULE_ID)\n\nexport const MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:'\nexport const RESOLVED_MOCK_EDGE_PREFIX = resolveViteId(MOCK_EDGE_PREFIX)\n\nexport const MOCK_RUNTIME_PREFIX =\n 'tanstack-start-import-protection:mock-runtime:'\nexport const RESOLVED_MOCK_RUNTIME_PREFIX = resolveViteId(MOCK_RUNTIME_PREFIX)\n\nexport const MARKER_PREFIX = 'tanstack-start-import-protection:marker:'\nexport const RESOLVED_MARKER_PREFIX = resolveViteId(MARKER_PREFIX)\n\nfunction toBase64Url(input: string): string {\n return Buffer.from(input, 'utf8').toString('base64url')\n}\n\nfunction fromBase64Url(input: string): string {\n return Buffer.from(input, 'base64url').toString('utf8')\n}\n\ntype MockAccessMode = 'error' | 'warn' | 'off'\n\n/**\n * Compact runtime suggestion text for browser console, derived from\n * {@link CLIENT_ENV_SUGGESTIONS} so there's a single source of truth.\n */\nexport const RUNTIME_SUGGESTION_TEXT =\n 'Fix: ' +\n CLIENT_ENV_SUGGESTIONS.join('. ') +\n '. To disable these runtime diagnostics, set importProtection.mockAccess: \"off\".'\n\nexport function mockRuntimeModuleIdFromViolation(\n info: ViolationInfo,\n mode: MockAccessMode,\n root: string,\n): string {\n if (mode === 'off') return MOCK_MODULE_ID\n if (info.env !== VITE_ENVIRONMENT_NAMES.client) return MOCK_MODULE_ID\n\n const rel = (p: string) => relativizePath(p, root)\n const trace = info.trace.map((s) => {\n const file = rel(s.file)\n if (s.line == null) return file\n return `${file}:${s.line}:${s.column ?? 1}`\n })\n\n const payload = {\n env: info.env,\n importer: info.importer,\n specifier: info.specifier,\n trace,\n mode,\n }\n return `${MOCK_RUNTIME_PREFIX}${toBase64Url(JSON.stringify(payload))}`\n}\n\nexport function makeMockEdgeModuleId(\n exports: Array<string>,\n source: string,\n runtimeId: string,\n): string {\n const payload = { source, exports, runtimeId }\n return `${MOCK_EDGE_PREFIX}${toBase64Url(JSON.stringify(payload))}`\n}\n\n/**\n * Generate a recursive Proxy-based mock module.\n *\n * When `diagnostics` is provided, the generated code includes a `__report`\n * function that logs runtime warnings/errors when the mock is actually used\n * (property access for primitive coercion, calls, construction, sets).\n *\n * When `diagnostics` is omitted, the mock is completely silent — suitable\n * for the shared `MOCK_MODULE_ID` that uses `syntheticNamedExports`.\n */\nfunction generateMockCode(diagnostics?: {\n meta: {\n env: string\n importer: string\n specifier: string\n trace: Array<unknown>\n }\n mode: 'error' | 'warn' | 'off'\n}): string {\n const fnName = diagnostics ? '__createMock' : 'createMock'\n const hasDiag = !!diagnostics\n\n const preamble = hasDiag\n ? `const __meta = ${JSON.stringify(diagnostics.meta)};\nconst __mode = ${JSON.stringify(diagnostics.mode)};\n\nconst __seen = new Set();\nfunction __report(action, accessPath) {\n if (__mode === 'off') return;\n const key = action + ':' + accessPath;\n if (__seen.has(key)) return;\n __seen.add(key);\n\n const traceLines = Array.isArray(__meta.trace) && __meta.trace.length\n ? \"\\\\n\\\\nTrace:\\\\n\" + __meta.trace.map((t, i) => ' ' + (i + 1) + '. ' + String(t)).join('\\\\n')\n : '';\n\n const msg =\n '[import-protection] Mocked import used in dev client\\\\n\\\\n' +\n 'Denied import: \"' + __meta.specifier + '\"\\\\n' +\n 'Importer: ' + __meta.importer + '\\\\n' +\n 'Access: ' + accessPath + ' (' + action + ')' +\n traceLines +\n '\\\\n\\\\n' + ${JSON.stringify(RUNTIME_SUGGESTION_TEXT)};\n\n const err = new Error(msg);\n if (__mode === 'warn') {\n console.warn(err);\n } else {\n console.error(err);\n }\n}\n`\n : ''\n\n // Diagnostic-only traps for primitive coercion, set\n const diagGetTraps = hasDiag\n ? `\n if (prop === Symbol.toPrimitive) {\n return () => {\n __report('toPrimitive', name);\n return '[import-protection mock]';\n };\n }\n if (prop === 'toString' || prop === 'valueOf' || prop === 'toJSON') {\n return () => {\n __report(String(prop), name);\n return '[import-protection mock]';\n };\n }`\n : ''\n\n const applyBody = hasDiag\n ? `__report('call', name + '()');\n return ${fnName}(name + '()');`\n : `return ${fnName}(name + '()');`\n\n const constructBody = hasDiag\n ? `__report('construct', 'new ' + name);\n return ${fnName}('new ' + name);`\n : `return ${fnName}('new ' + name);`\n\n const setTrap = hasDiag\n ? `\n set(_target, prop) {\n __report('set', name + '.' + String(prop));\n return true;\n },`\n : ''\n\n return `\n${preamble}function ${fnName}(name) {\n const fn = function () {};\n fn.prototype.name = name;\n const children = Object.create(null);\n const proxy = new Proxy(fn, {\n get(_target, prop) {\n if (prop === '__esModule') return true;\n if (prop === 'default') return proxy;\n if (prop === 'caller') return null;\n if (prop === 'then') return (f) => Promise.resolve(f(proxy));\n if (prop === 'catch') return () => Promise.resolve(proxy);\n if (prop === 'finally') return (f) => { f(); return Promise.resolve(proxy); };${diagGetTraps}\n if (typeof prop === 'symbol') return undefined;\n if (!(prop in children)) {\n children[prop] = ${fnName}(name + '.' + prop);\n }\n return children[prop];\n },\n apply() {\n ${applyBody}\n },\n construct() {\n ${constructBody}\n },${setTrap}\n });\n return proxy;\n}\nconst mock = ${fnName}('mock');\nexport default mock;\n`\n}\n\nexport function loadSilentMockModule(): {\n syntheticNamedExports: boolean\n code: string\n} {\n return { syntheticNamedExports: true, code: generateMockCode() }\n}\n\nexport function loadMockEdgeModule(encodedPayload: string): { code: string } {\n let payload: { exports?: Array<string>; runtimeId?: string }\n try {\n payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload\n } catch {\n payload = { exports: [] }\n }\n const names: Array<string> = Array.isArray(payload.exports)\n ? payload.exports.filter(\n (n): n is string =>\n typeof n === 'string' && n.length > 0 && n !== 'default',\n )\n : []\n\n const runtimeId: string =\n typeof payload.runtimeId === 'string' && payload.runtimeId.length > 0\n ? payload.runtimeId\n : MOCK_MODULE_ID\n\n const exportLines: Array<string> = []\n const stringExports: Array<{ alias: string; name: string }> = []\n\n for (let i = 0; i < names.length; i++) {\n const n = names[i]!\n if (isValidExportName(n)) {\n exportLines.push(`export const ${n} = mock.${n};`)\n } else {\n // ES2022 string-keyed export: use a temp var + re-export with string literal\n const alias = `__tss_str_${i}`\n exportLines.push(`const ${alias} = mock[${JSON.stringify(n)}];`)\n stringExports.push({ alias, name: n })\n }\n }\n\n if (stringExports.length > 0) {\n const reexports = stringExports\n .map((s) => `${s.alias} as ${JSON.stringify(s.name)}`)\n .join(', ')\n exportLines.push(`export { ${reexports} };`)\n }\n\n return {\n code: `import mock from ${JSON.stringify(runtimeId)};\n${exportLines.join('\\n')}\nexport default mock;\n`,\n }\n}\n\nexport function loadMockRuntimeModule(encodedPayload: string): {\n code: string\n} {\n let payload: {\n mode?: string\n env?: string\n importer?: string\n specifier?: string\n trace?: Array<unknown>\n }\n try {\n payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload\n } catch {\n payload = {}\n }\n\n const mode: 'error' | 'warn' | 'off' =\n payload.mode === 'warn' || payload.mode === 'off' ? payload.mode : 'error'\n\n const meta = {\n env: String(payload.env ?? ''),\n importer: String(payload.importer ?? ''),\n specifier: String(payload.specifier ?? ''),\n trace: Array.isArray(payload.trace) ? payload.trace : [],\n }\n\n return { code: generateMockCode({ meta, mode }) }\n}\n\nconst MARKER_MODULE_RESULT = { code: 'export {}' } as const\n\nexport function loadMarkerModule(): { code: string } {\n return MARKER_MODULE_RESULT\n}\n"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"virtualModules.js","sources":["../../../src/import-protection-plugin/virtualModules.ts"],"sourcesContent":["import { resolveViteId } from '../utils'\nimport { VITE_ENVIRONMENT_NAMES } from '../constants'\nimport { isValidExportName } from './rewriteDeniedImports'\nimport { CLIENT_ENV_SUGGESTIONS } from './trace'\nimport { relativizePath } from './utils'\nimport type { ViolationInfo } from './trace'\n\nexport const MOCK_MODULE_ID = 'tanstack-start-import-protection:mock'\nexport const RESOLVED_MOCK_MODULE_ID = resolveViteId(MOCK_MODULE_ID)\n\n/**\n * Per-violation mock prefix used in build+error mode.\n * Each deferred violation gets a unique ID so we can check which ones\n * survived tree-shaking in `generateBundle`.\n */\nexport const MOCK_BUILD_PREFIX = 'tanstack-start-import-protection:mock:build:'\nexport const RESOLVED_MOCK_BUILD_PREFIX = resolveViteId(MOCK_BUILD_PREFIX)\n\nexport const MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:'\nexport const RESOLVED_MOCK_EDGE_PREFIX = resolveViteId(MOCK_EDGE_PREFIX)\n\nexport const MOCK_RUNTIME_PREFIX =\n 'tanstack-start-import-protection:mock-runtime:'\nexport const RESOLVED_MOCK_RUNTIME_PREFIX = resolveViteId(MOCK_RUNTIME_PREFIX)\n\nexport const MARKER_PREFIX = 'tanstack-start-import-protection:marker:'\nexport const RESOLVED_MARKER_PREFIX = resolveViteId(MARKER_PREFIX)\n\nfunction toBase64Url(input: string): string {\n return Buffer.from(input, 'utf8').toString('base64url')\n}\n\nfunction fromBase64Url(input: string): string {\n return Buffer.from(input, 'base64url').toString('utf8')\n}\n\ntype MockAccessMode = 'error' | 'warn' | 'off'\n\n/**\n * Compact runtime suggestion text for browser console, derived from\n * {@link CLIENT_ENV_SUGGESTIONS} so there's a single source of truth.\n */\nexport const RUNTIME_SUGGESTION_TEXT =\n 'Fix: ' +\n CLIENT_ENV_SUGGESTIONS.join('. ') +\n '. To disable these runtime diagnostics, set importProtection.mockAccess: \"off\".'\n\nexport function mockRuntimeModuleIdFromViolation(\n info: ViolationInfo,\n mode: MockAccessMode,\n root: string,\n): string {\n if (mode === 'off') return MOCK_MODULE_ID\n if (info.env !== VITE_ENVIRONMENT_NAMES.client) return MOCK_MODULE_ID\n\n const rel = (p: string) => relativizePath(p, root)\n const trace = info.trace.map((s) => {\n const file = rel(s.file)\n if (s.line == null) return file\n return `${file}:${s.line}:${s.column ?? 1}`\n })\n\n const payload = {\n env: info.env,\n importer: info.importer,\n specifier: info.specifier,\n trace,\n mode,\n }\n return `${MOCK_RUNTIME_PREFIX}${toBase64Url(JSON.stringify(payload))}`\n}\n\nexport function makeMockEdgeModuleId(\n exports: Array<string>,\n source: string,\n runtimeId: string,\n): string {\n const payload = { source, exports, runtimeId }\n return `${MOCK_EDGE_PREFIX}${toBase64Url(JSON.stringify(payload))}`\n}\n\n/**\n * Generate a recursive Proxy-based mock module.\n *\n * When `diagnostics` is provided, the generated code includes a `__report`\n * function that logs runtime warnings/errors when the mock is actually used\n * (property access for primitive coercion, calls, construction, sets).\n *\n * When `diagnostics` is omitted, the mock is completely silent — suitable\n * for the shared `MOCK_MODULE_ID` that uses `syntheticNamedExports`.\n */\nfunction generateMockCode(diagnostics?: {\n meta: {\n env: string\n importer: string\n specifier: string\n trace: Array<unknown>\n }\n mode: 'error' | 'warn' | 'off'\n}): string {\n const fnName = diagnostics ? '__createMock' : 'createMock'\n const hasDiag = !!diagnostics\n\n const preamble = hasDiag\n ? `const __meta = ${JSON.stringify(diagnostics.meta)};\nconst __mode = ${JSON.stringify(diagnostics.mode)};\n\nconst __seen = new Set();\nfunction __report(action, accessPath) {\n if (__mode === 'off') return;\n const key = action + ':' + accessPath;\n if (__seen.has(key)) return;\n __seen.add(key);\n\n const traceLines = Array.isArray(__meta.trace) && __meta.trace.length\n ? \"\\\\n\\\\nTrace:\\\\n\" + __meta.trace.map((t, i) => ' ' + (i + 1) + '. ' + String(t)).join('\\\\n')\n : '';\n\n const msg =\n '[import-protection] Mocked import used in dev client\\\\n\\\\n' +\n 'Denied import: \"' + __meta.specifier + '\"\\\\n' +\n 'Importer: ' + __meta.importer + '\\\\n' +\n 'Access: ' + accessPath + ' (' + action + ')' +\n traceLines +\n '\\\\n\\\\n' + ${JSON.stringify(RUNTIME_SUGGESTION_TEXT)};\n\n const err = new Error(msg);\n if (__mode === 'warn') {\n console.warn(err);\n } else {\n console.error(err);\n }\n}\n`\n : ''\n\n // Diagnostic-only traps for primitive coercion, set\n const diagGetTraps = hasDiag\n ? `\n if (prop === Symbol.toPrimitive) {\n return () => {\n __report('toPrimitive', name);\n return '[import-protection mock]';\n };\n }\n if (prop === 'toString' || prop === 'valueOf' || prop === 'toJSON') {\n return () => {\n __report(String(prop), name);\n return '[import-protection mock]';\n };\n }`\n : ''\n\n const applyBody = hasDiag\n ? `__report('call', name + '()');\n return ${fnName}(name + '()');`\n : `return ${fnName}(name + '()');`\n\n const constructBody = hasDiag\n ? `__report('construct', 'new ' + name);\n return ${fnName}('new ' + name);`\n : `return ${fnName}('new ' + name);`\n\n const setTrap = hasDiag\n ? `\n set(_target, prop) {\n __report('set', name + '.' + String(prop));\n return true;\n },`\n : ''\n\n return `\n${preamble}function ${fnName}(name) {\n const fn = function () {};\n fn.prototype.name = name;\n const children = Object.create(null);\n const proxy = new Proxy(fn, {\n get(_target, prop) {\n if (prop === '__esModule') return true;\n if (prop === 'default') return proxy;\n if (prop === 'caller') return null;\n if (prop === 'then') return (f) => Promise.resolve(f(proxy));\n if (prop === 'catch') return () => Promise.resolve(proxy);\n if (prop === 'finally') return (f) => { f(); return Promise.resolve(proxy); };${diagGetTraps}\n if (typeof prop === 'symbol') return undefined;\n if (!(prop in children)) {\n children[prop] = ${fnName}(name + '.' + prop);\n }\n return children[prop];\n },\n apply() {\n ${applyBody}\n },\n construct() {\n ${constructBody}\n },${setTrap}\n });\n return proxy;\n}\nconst mock = ${fnName}('mock');\nexport default mock;\n`\n}\n\nexport function loadSilentMockModule(): {\n syntheticNamedExports: boolean\n code: string\n} {\n return { syntheticNamedExports: true, code: generateMockCode() }\n}\n\nexport function loadMockEdgeModule(encodedPayload: string): { code: string } {\n let payload: { exports?: Array<string>; runtimeId?: string }\n try {\n payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload\n } catch {\n payload = { exports: [] }\n }\n const names: Array<string> = Array.isArray(payload.exports)\n ? payload.exports.filter(\n (n): n is string =>\n typeof n === 'string' && n.length > 0 && n !== 'default',\n )\n : []\n\n const runtimeId: string =\n typeof payload.runtimeId === 'string' && payload.runtimeId.length > 0\n ? payload.runtimeId\n : MOCK_MODULE_ID\n\n const exportLines: Array<string> = []\n const stringExports: Array<{ alias: string; name: string }> = []\n\n for (let i = 0; i < names.length; i++) {\n const n = names[i]!\n if (isValidExportName(n)) {\n exportLines.push(`export const ${n} = mock.${n};`)\n } else {\n // ES2022 string-keyed export: use a temp var + re-export with string literal\n const alias = `__tss_str_${i}`\n exportLines.push(`const ${alias} = mock[${JSON.stringify(n)}];`)\n stringExports.push({ alias, name: n })\n }\n }\n\n if (stringExports.length > 0) {\n const reexports = stringExports\n .map((s) => `${s.alias} as ${JSON.stringify(s.name)}`)\n .join(', ')\n exportLines.push(`export { ${reexports} };`)\n }\n\n return {\n code: `import mock from ${JSON.stringify(runtimeId)};\n${exportLines.join('\\n')}\nexport default mock;\n`,\n }\n}\n\nexport function loadMockRuntimeModule(encodedPayload: string): {\n code: string\n} {\n let payload: {\n mode?: string\n env?: string\n importer?: string\n specifier?: string\n trace?: Array<unknown>\n }\n try {\n payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload\n } catch {\n payload = {}\n }\n\n const mode: 'error' | 'warn' | 'off' =\n payload.mode === 'warn' || payload.mode === 'off' ? payload.mode : 'error'\n\n const meta = {\n env: String(payload.env ?? ''),\n importer: String(payload.importer ?? ''),\n specifier: String(payload.specifier ?? ''),\n trace: Array.isArray(payload.trace) ? payload.trace : [],\n }\n\n return { code: generateMockCode({ meta, mode }) }\n}\n\nconst MARKER_MODULE_RESULT = { code: 'export {}' } as const\n\nexport function loadMarkerModule(): { code: string } {\n return MARKER_MODULE_RESULT\n}\n"],"names":[],"mappings":"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"}
package/dist/esm/schema.d.ts CHANGED
@@ -32,7 +32,7 @@ declare const importProtectionOptionsSchema: z.ZodOptional<z.ZodObject<{
32
32
  * - 'off': disable runtime diagnostics
33
33
  */
34
34
  mockAccess: z.ZodOptional<z.ZodEnum<["error", "warn", "off"]>>;
35
- onViolation: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodVoid]>>>;
35
+ onViolation: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodVoid, z.ZodPromise<z.ZodUnion<[z.ZodBoolean, z.ZodVoid]>>]>>>;
36
36
  include: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodType<RegExp, z.ZodTypeDef, RegExp>]>, "many">>;
37
37
  exclude: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodType<RegExp, z.ZodTypeDef, RegExp>]>, "many">>;
38
38
  client: z.ZodOptional<z.ZodObject<{
@@ -74,7 +74,7 @@ declare const importProtectionOptionsSchema: z.ZodOptional<z.ZodObject<{
74
74
  dev?: "error" | "mock" | undefined;
75
75
  } | undefined;
76
76
  mockAccess?: "error" | "warn" | "off" | undefined;
77
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
77
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
78
78
  include?: (string | RegExp)[] | undefined;
79
79
  ignoreImporters?: (string | RegExp)[] | undefined;
80
80
  maxTraceDepth?: number | undefined;
@@ -95,7 +95,7 @@ declare const importProtectionOptionsSchema: z.ZodOptional<z.ZodObject<{
95
95
  dev?: "error" | "mock" | undefined;
96
96
  } | undefined;
97
97
  mockAccess?: "error" | "warn" | "off" | undefined;
98
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
98
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
99
99
  include?: (string | RegExp)[] | undefined;
100
100
  ignoreImporters?: (string | RegExp)[] | undefined;
101
101
  maxTraceDepth?: number | undefined;
@@ -414,7 +414,7 @@ export declare function parseStartConfig(opts: z.input<typeof tanstackStartOptio
414
414
  dev?: "error" | "mock" | undefined;
415
415
  } | undefined;
416
416
  mockAccess?: "error" | "warn" | "off" | undefined;
417
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
417
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
418
418
  include?: (string | RegExp)[] | undefined;
419
419
  ignoreImporters?: (string | RegExp)[] | undefined;
420
420
  maxTraceDepth?: number | undefined;
@@ -3230,7 +3230,7 @@ declare const tanstackStartOptionsSchema: z.ZodDefault<z.ZodOptional<z.ZodObject
3230
3230
  * - 'off': disable runtime diagnostics
3231
3231
  */
3232
3232
  mockAccess: z.ZodOptional<z.ZodEnum<["error", "warn", "off"]>>;
3233
- onViolation: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodVoid]>>>;
3233
+ onViolation: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodVoid, z.ZodPromise<z.ZodUnion<[z.ZodBoolean, z.ZodVoid]>>]>>>;
3234
3234
  include: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodType<RegExp, z.ZodTypeDef, RegExp>]>, "many">>;
3235
3235
  exclude: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodType<RegExp, z.ZodTypeDef, RegExp>]>, "many">>;
3236
3236
  client: z.ZodOptional<z.ZodObject<{
@@ -3272,7 +3272,7 @@ declare const tanstackStartOptionsSchema: z.ZodDefault<z.ZodOptional<z.ZodObject
3272
3272
  dev?: "error" | "mock" | undefined;
3273
3273
  } | undefined;
3274
3274
  mockAccess?: "error" | "warn" | "off" | undefined;
3275
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
3275
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
3276
3276
  include?: (string | RegExp)[] | undefined;
3277
3277
  ignoreImporters?: (string | RegExp)[] | undefined;
3278
3278
  maxTraceDepth?: number | undefined;
@@ -3293,7 +3293,7 @@ declare const tanstackStartOptionsSchema: z.ZodDefault<z.ZodOptional<z.ZodObject
3293
3293
  dev?: "error" | "mock" | undefined;
3294
3294
  } | undefined;
3295
3295
  mockAccess?: "error" | "warn" | "off" | undefined;
3296
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
3296
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
3297
3297
  include?: (string | RegExp)[] | undefined;
3298
3298
  ignoreImporters?: (string | RegExp)[] | undefined;
3299
3299
  maxTraceDepth?: number | undefined;
@@ -3610,7 +3610,7 @@ declare const tanstackStartOptionsSchema: z.ZodDefault<z.ZodOptional<z.ZodObject
3610
3610
  dev?: "error" | "mock" | undefined;
3611
3611
  } | undefined;
3612
3612
  mockAccess?: "error" | "warn" | "off" | undefined;
3613
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
3613
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
3614
3614
  include?: (string | RegExp)[] | undefined;
3615
3615
  ignoreImporters?: (string | RegExp)[] | undefined;
3616
3616
  maxTraceDepth?: number | undefined;
@@ -3927,7 +3927,7 @@ declare const tanstackStartOptionsSchema: z.ZodDefault<z.ZodOptional<z.ZodObject
3927
3927
  dev?: "error" | "mock" | undefined;
3928
3928
  } | undefined;
3929
3929
  mockAccess?: "error" | "warn" | "off" | undefined;
3930
- onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void) | undefined;
3930
+ onViolation?: ((args_0: any, ...args: unknown[]) => boolean | void | Promise<boolean | void>) | undefined;
3931
3931
  include?: (string | RegExp)[] | undefined;
3932
3932
  ignoreImporters?: (string | RegExp)[] | undefined;
3933
3933
  maxTraceDepth?: number | undefined;
package/dist/esm/schema.js CHANGED
@@ -26,7 +26,13 @@ const importProtectionOptionsSchema = z.object({
26
26
  * - 'off': disable runtime diagnostics
27
27
  */
28
28
  mockAccess: z.enum(["error", "warn", "off"]).optional(),
29
- onViolation: z.function().args(z.any()).returns(z.union([z.boolean(), z.void()])).optional(),
29
+ onViolation: z.function().args(z.any()).returns(
30
+ z.union([
31
+ z.boolean(),
32
+ z.void(),
33
+ z.promise(z.union([z.boolean(), z.void()]))
34
+ ])
35
+ ).optional(),
30
36
  include: z.array(patternSchema).optional(),
31
37
  exclude: z.array(patternSchema).optional(),
32
38
  client: importProtectionEnvRulesSchema.optional(),
package/dist/esm/schema.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"schema.js","sources":["../../src/schema.ts"],"sourcesContent":["import path from 'node:path'\nimport { z } from 'zod'\nimport { configSchema, getConfig } from '@tanstack/router-plugin'\nimport type { TanStackStartVitePluginCoreOptions } from './types'\n\nconst tsrConfig = configSchema\n .omit({ autoCodeSplitting: true, target: true, verboseFileRoutes: true })\n .partial()\n\n// --- Import Protection Schema ---\n\nconst patternSchema = z.union([z.string(), z.instanceof(RegExp)])\n\nconst importProtectionBehaviorSchema = z.enum(['error', 'mock'])\n\nconst importProtectionEnvRulesSchema = z.object({\n specifiers: z.array(patternSchema).optional(),\n files: z.array(patternSchema).optional(),\n})\n\nconst importProtectionOptionsSchema = z\n .object({\n enabled: z.boolean().optional(),\n behavior: z\n .union([\n importProtectionBehaviorSchema,\n z.object({\n dev: importProtectionBehaviorSchema.optional(),\n build: importProtectionBehaviorSchema.optional(),\n }),\n ])\n .optional(),\n /**\n * In `behavior: 'mock'`, control whether mocked imports emit a runtime\n * console diagnostic when accessed.\n *\n * - 'error': console.error(new Error(...)) (default)\n * - 'warn': console.warn(new Error(...))\n * - 'off': disable runtime diagnostics\n */\n mockAccess: z.enum(['error', 'warn', 'off']).optional(),\n onViolation: z\n .function()\n .args(z.any())\n .returns(z.union([z.boolean(), z.void()]))\n .optional(),\n include: z.array(patternSchema).optional(),\n exclude: z.array(patternSchema).optional(),\n client: importProtectionEnvRulesSchema.optional(),\n server: importProtectionEnvRulesSchema.optional(),\n ignoreImporters: z.array(patternSchema).optional(),\n maxTraceDepth: z.number().optional(),\n log: z.enum(['once', 'always']).optional(),\n })\n .optional()\n\nexport function parseStartConfig(\n opts: z.input<typeof tanstackStartOptionsSchema>,\n corePluginOpts: TanStackStartVitePluginCoreOptions,\n root: string,\n) {\n const options = tanstackStartOptionsSchema.parse(opts)\n\n const srcDirectory = options.srcDirectory\n\n const routesDirectory = path.resolve(\n root,\n srcDirectory,\n options.router.routesDirectory ?? 'routes',\n )\n\n const generatedRouteTree = path.resolve(\n root,\n srcDirectory,\n options.router.generatedRouteTree ?? 'routeTree.gen.ts',\n )\n\n return {\n ...options,\n router: {\n ...options.router,\n ...getConfig(\n {\n ...options.router,\n routesDirectory,\n generatedRouteTree,\n },\n root,\n ),\n target: corePluginOpts.framework,\n },\n }\n}\n\nconst pageSitemapOptionsSchema = z.object({\n exclude: z.boolean().optional(),\n priority: z.number().min(0).max(1).optional(),\n changefreq: z\n .enum(['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never'])\n .optional(),\n lastmod: z.union([z.string(), z.date()]).optional(),\n alternateRefs: z\n .array(\n z.object({\n href: z.string(),\n hreflang: z.string(),\n }),\n )\n .optional(),\n images: z\n .array(\n z.object({\n loc: z.string(),\n caption: z.string().optional(),\n title: z.string().optional(),\n }),\n )\n .optional(),\n news: z\n .object({\n publication: z.object({\n name: z.string(),\n language: z.string(),\n }),\n publicationDate: z.union([z.string(), z.date()]),\n title: z.string(),\n })\n .optional(),\n})\n\nconst pageBaseSchema = z.object({\n path: z.string(),\n sitemap: pageSitemapOptionsSchema.optional(),\n fromCrawl: z.boolean().optional(),\n})\n\nconst pagePrerenderOptionsSchema = z.object({\n enabled: z.boolean().optional(),\n outputPath: z.string().optional(),\n autoSubfolderIndex: z.boolean().optional(),\n crawlLinks: z.boolean().optional(),\n retryCount: z.number().optional(),\n retryDelay: z.number().optional(),\n onSuccess: z\n .function()\n .args(\n z.object({\n page: pageBaseSchema,\n html: z.string(),\n }),\n )\n .returns(z.any())\n .optional(),\n headers: z.record(z.string(), z.string()).optional(),\n})\n\nconst spaSchema = z.object({\n enabled: z.boolean().optional().default(true),\n maskPath: z.string().optional().default('/'),\n prerender: pagePrerenderOptionsSchema\n .optional()\n .default({})\n .transform((opts) => ({\n outputPath: opts.outputPath ?? '/_shell',\n crawlLinks: false,\n retryCount: 0,\n ...opts,\n enabled: true,\n })),\n})\n\nconst pageSchema = pageBaseSchema.extend({\n prerender: pagePrerenderOptionsSchema.optional(),\n})\n\nconst tanstackStartOptionsSchema = z\n .object({\n srcDirectory: z.string().optional().default('src'),\n start: z\n .object({\n entry: z.string().optional(),\n })\n .optional()\n .default({}),\n router: z\n .object({\n entry: z.string().optional(),\n basepath: z.string().optional(),\n })\n .and(tsrConfig.optional().default({}))\n .optional()\n .default({}),\n client: z\n .object({\n entry: z.string().optional(),\n base: z.string().optional().default('/_build'),\n })\n .optional()\n .default({}),\n server: z\n .object({\n entry: z.string().optional(),\n build: z\n .object({\n staticNodeEnv: z.boolean().optional().default(true),\n })\n .optional()\n .default({}),\n })\n .optional()\n .default({}),\n serverFns: z\n .object({\n base: z.string().optional().default('/_serverFn'),\n generateFunctionId: z\n .function()\n .args(\n z.object({\n filename: z.string(),\n functionName: z.string(),\n }),\n )\n .returns(z.string().optional())\n .optional(),\n })\n .optional()\n .default({}),\n pages: z.array(pageSchema).optional().default([]),\n sitemap: z\n .object({\n enabled: z.boolean().optional().default(true),\n host: z.string().optional(),\n outputPath: z.string().optional().default('sitemap.xml'),\n })\n .optional(),\n prerender: z\n .object({\n enabled: z.boolean().optional(),\n concurrency: z.number().optional(),\n filter: z.function().args(pageSchema).returns(z.any()).optional(),\n failOnError: z.boolean().optional(),\n autoStaticPathsDiscovery: z.boolean().optional(),\n maxRedirects: z.number().min(0).optional(),\n })\n .and(pagePrerenderOptionsSchema.optional())\n .optional(),\n spa: spaSchema.optional(),\n vite: z\n .object({ installDevServerMiddleware: z.boolean().optional() })\n .optional(),\n importProtection: importProtectionOptionsSchema,\n })\n .optional()\n .default({})\n\nexport type Page = z.infer<typeof pageSchema>\n\nexport type TanStackStartInputConfig = z.input<\n typeof tanstackStartOptionsSchema\n>\nexport type TanStackStartOutputConfig = ReturnType<typeof parseStartConfig>\n\nexport type ImportProtectionBehavior = z.infer<\n typeof importProtectionBehaviorSchema\n>\nexport type ImportProtectionEnvRules = z.infer<\n typeof importProtectionEnvRulesSchema\n>\nexport type ImportProtectionOptions = z.input<\n typeof importProtectionOptionsSchema\n>\n"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"schema.js","sources":["../../src/schema.ts"],"sourcesContent":["import path from 'node:path'\nimport { z } from 'zod'\nimport { configSchema, getConfig } from '@tanstack/router-plugin'\nimport type { TanStackStartVitePluginCoreOptions } from './types'\n\nconst tsrConfig = configSchema\n .omit({ autoCodeSplitting: true, target: true, verboseFileRoutes: true })\n .partial()\n\n// --- Import Protection Schema ---\n\nconst patternSchema = z.union([z.string(), z.instanceof(RegExp)])\n\nconst importProtectionBehaviorSchema = z.enum(['error', 'mock'])\n\nconst importProtectionEnvRulesSchema = z.object({\n specifiers: z.array(patternSchema).optional(),\n files: z.array(patternSchema).optional(),\n})\n\nconst importProtectionOptionsSchema = z\n .object({\n enabled: z.boolean().optional(),\n behavior: z\n .union([\n importProtectionBehaviorSchema,\n z.object({\n dev: importProtectionBehaviorSchema.optional(),\n build: importProtectionBehaviorSchema.optional(),\n }),\n ])\n .optional(),\n /**\n * In `behavior: 'mock'`, control whether mocked imports emit a runtime\n * console diagnostic when accessed.\n *\n * - 'error': console.error(new Error(...)) (default)\n * - 'warn': console.warn(new Error(...))\n * - 'off': disable runtime diagnostics\n */\n mockAccess: z.enum(['error', 'warn', 'off']).optional(),\n onViolation: z\n .function()\n .args(z.any())\n .returns(\n z.union([\n z.boolean(),\n z.void(),\n z.promise(z.union([z.boolean(), z.void()])),\n ]),\n )\n .optional(),\n include: z.array(patternSchema).optional(),\n exclude: z.array(patternSchema).optional(),\n client: importProtectionEnvRulesSchema.optional(),\n server: importProtectionEnvRulesSchema.optional(),\n ignoreImporters: z.array(patternSchema).optional(),\n maxTraceDepth: z.number().optional(),\n log: z.enum(['once', 'always']).optional(),\n })\n .optional()\n\nexport function parseStartConfig(\n opts: z.input<typeof tanstackStartOptionsSchema>,\n corePluginOpts: TanStackStartVitePluginCoreOptions,\n root: string,\n) {\n const options = tanstackStartOptionsSchema.parse(opts)\n\n const srcDirectory = options.srcDirectory\n\n const routesDirectory = path.resolve(\n root,\n srcDirectory,\n options.router.routesDirectory ?? 'routes',\n )\n\n const generatedRouteTree = path.resolve(\n root,\n srcDirectory,\n options.router.generatedRouteTree ?? 'routeTree.gen.ts',\n )\n\n return {\n ...options,\n router: {\n ...options.router,\n ...getConfig(\n {\n ...options.router,\n routesDirectory,\n generatedRouteTree,\n },\n root,\n ),\n target: corePluginOpts.framework,\n },\n }\n}\n\nconst pageSitemapOptionsSchema = z.object({\n exclude: z.boolean().optional(),\n priority: z.number().min(0).max(1).optional(),\n changefreq: z\n .enum(['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never'])\n .optional(),\n lastmod: z.union([z.string(), z.date()]).optional(),\n alternateRefs: z\n .array(\n z.object({\n href: z.string(),\n hreflang: z.string(),\n }),\n )\n .optional(),\n images: z\n .array(\n z.object({\n loc: z.string(),\n caption: z.string().optional(),\n title: z.string().optional(),\n }),\n )\n .optional(),\n news: z\n .object({\n publication: z.object({\n name: z.string(),\n language: z.string(),\n }),\n publicationDate: z.union([z.string(), z.date()]),\n title: z.string(),\n })\n .optional(),\n})\n\nconst pageBaseSchema = z.object({\n path: z.string(),\n sitemap: pageSitemapOptionsSchema.optional(),\n fromCrawl: z.boolean().optional(),\n})\n\nconst pagePrerenderOptionsSchema = z.object({\n enabled: z.boolean().optional(),\n outputPath: z.string().optional(),\n autoSubfolderIndex: z.boolean().optional(),\n crawlLinks: z.boolean().optional(),\n retryCount: z.number().optional(),\n retryDelay: z.number().optional(),\n onSuccess: z\n .function()\n .args(\n z.object({\n page: pageBaseSchema,\n html: z.string(),\n }),\n )\n .returns(z.any())\n .optional(),\n headers: z.record(z.string(), z.string()).optional(),\n})\n\nconst spaSchema = z.object({\n enabled: z.boolean().optional().default(true),\n maskPath: z.string().optional().default('/'),\n prerender: pagePrerenderOptionsSchema\n .optional()\n .default({})\n .transform((opts) => ({\n outputPath: opts.outputPath ?? '/_shell',\n crawlLinks: false,\n retryCount: 0,\n ...opts,\n enabled: true,\n })),\n})\n\nconst pageSchema = pageBaseSchema.extend({\n prerender: pagePrerenderOptionsSchema.optional(),\n})\n\nconst tanstackStartOptionsSchema = z\n .object({\n srcDirectory: z.string().optional().default('src'),\n start: z\n .object({\n entry: z.string().optional(),\n })\n .optional()\n .default({}),\n router: z\n .object({\n entry: z.string().optional(),\n basepath: z.string().optional(),\n })\n .and(tsrConfig.optional().default({}))\n .optional()\n .default({}),\n client: z\n .object({\n entry: z.string().optional(),\n base: z.string().optional().default('/_build'),\n })\n .optional()\n .default({}),\n server: z\n .object({\n entry: z.string().optional(),\n build: z\n .object({\n staticNodeEnv: z.boolean().optional().default(true),\n })\n .optional()\n .default({}),\n })\n .optional()\n .default({}),\n serverFns: z\n .object({\n base: z.string().optional().default('/_serverFn'),\n generateFunctionId: z\n .function()\n .args(\n z.object({\n filename: z.string(),\n functionName: z.string(),\n }),\n )\n .returns(z.string().optional())\n .optional(),\n })\n .optional()\n .default({}),\n pages: z.array(pageSchema).optional().default([]),\n sitemap: z\n .object({\n enabled: z.boolean().optional().default(true),\n host: z.string().optional(),\n outputPath: z.string().optional().default('sitemap.xml'),\n })\n .optional(),\n prerender: z\n .object({\n enabled: z.boolean().optional(),\n concurrency: z.number().optional(),\n filter: z.function().args(pageSchema).returns(z.any()).optional(),\n failOnError: z.boolean().optional(),\n autoStaticPathsDiscovery: z.boolean().optional(),\n maxRedirects: z.number().min(0).optional(),\n })\n .and(pagePrerenderOptionsSchema.optional())\n .optional(),\n spa: spaSchema.optional(),\n vite: z\n .object({ installDevServerMiddleware: z.boolean().optional() })\n .optional(),\n importProtection: importProtectionOptionsSchema,\n })\n .optional()\n .default({})\n\nexport type Page = z.infer<typeof pageSchema>\n\nexport type TanStackStartInputConfig = z.input<\n typeof tanstackStartOptionsSchema\n>\nexport type TanStackStartOutputConfig = ReturnType<typeof parseStartConfig>\n\nexport type ImportProtectionBehavior = z.infer<\n typeof importProtectionBehaviorSchema\n>\nexport type ImportProtectionEnvRules = z.infer<\n typeof importProtectionEnvRulesSchema\n>\nexport type ImportProtectionOptions = z.input<\n typeof importProtectionOptionsSchema\n>\n"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/start-plugin-core",
3
- "version": "1.162.6",
3
+ "version": "1.162.7",
4
4
  "description": "Modern and scalable routing for React applications",
5
5
  "author": "Tanner Linsley",
6
6
  "license": "MIT",
@@ -61,10 +61,10 @@
61
61
  "xmlbuilder2": "^4.0.3",
62
62
  "zod": "^3.24.2",
63
63
  "@tanstack/router-core": "1.162.6",
64
- "@tanstack/router-generator": "1.162.6",
65
64
  "@tanstack/router-plugin": "1.162.6",
66
- "@tanstack/router-utils": "1.161.4",
67
65
  "@tanstack/start-client-core": "1.162.6",
66
+ "@tanstack/router-utils": "1.161.4",
67
+ "@tanstack/router-generator": "1.162.6",
68
68
  "@tanstack/start-server-core": "1.162.6"
69
69
  },
70
70
  "devDependencies": {
package/src/import-protection-plugin/INTERNALS.md ADDED
@@ -0,0 +1,290 @@
1
+ # Import Protection Plugin — Internal Technical Documentation
2
+
3
+ ## Overview
4
+
5
+ The import protection plugin prevents server-only code from leaking into client
6
+ bundles (and vice versa). It operates as a Vite plugin that intercepts module
7
+ resolution, detects violations, and either errors or replaces the offending
8
+ module with a safe mock.
9
+
10
+ The plugin must handle **two axes of configuration**:
11
+
12
+ | | **Dev** (`vite dev`) | **Build** (`vite build`) |
13
+ | --------- | -------------------------------------------------------------------- | -------------------------------------------------------------- |
14
+ | **Error** | `ctx.error()` immediately in `resolveId` | Defer to `generateBundle`; error if mock survived tree-shaking |
15
+ | **Mock** | Defer to transform-cache; warn if reachable via post-transform graph | Defer to `generateBundle`; warn if mock survived tree-shaking |
16
+
17
+ ## Plugin Architecture
18
+
19
+ `importProtectionPlugin()` returns **three** Vite plugins:
20
+
21
+ ### 1. `tanstack-start-core:import-protection` (enforce: `'pre'`)
22
+
23
+ The main enforcement plugin. Hooks: `applyToEnvironment`, `configResolved`,
24
+ `configureServer`, `buildStart`, `hotUpdate`, `resolveId`, `load`, and
25
+ `generateBundle`. All violation detection starts in `resolveId`.
26
+
27
+ ### 2. `tanstack-start-core:import-protection-transform-cache`
28
+
29
+ Runs after all `enforce: 'pre'` hooks (including the Start compiler). Caches
30
+ transformed code and composed sourcemaps for accurate source-location mapping
31
+ in violation messages. Also resolves post-transform imports and triggers
32
+ `processPendingViolations()` for the dev mock deferral path.
33
+
34
+ ### 3. `tanstack-start-core:import-protection-mock-rewrite` (enforce: `'pre'`, dev only)
35
+
36
+ Records expected named exports per importer so that dev mock-edge modules can
37
+ provide explicit ESM named exports. Only active in dev + mock mode.
38
+
39
+ ## Violation Types
40
+
41
+ | Type | Trigger | Example |
42
+ | ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
43
+ | `file` | Resolved path matches a deny glob (e.g. `**/*.server.*`) | `import './db.server'` in client env |
44
+ | `specifier` | Import specifier matches a deny pattern | `import '@tanstack/react-start/server'` in client env |
45
+ | `marker` | File imports `'server-only'` or `'client-only'` marker, then is loaded in the wrong env | File with `import 'server-only'` resolved in client env |
46
+
47
+ ## The False-Positive Problem
48
+
49
+ ### Barrel re-exports
50
+
51
+ A common pattern:
52
+
53
+ ```text
54
+ db/index.ts → export { getUsers } from './db.server'
55
+ export { userColumns } from './shared'
56
+
57
+ route.tsx → import { getUsers, userColumns } from '../db'
58
+ // getUsers used only in createServerFn().handler()
59
+ // userColumns used in JSX
60
+ ```
61
+
62
+ At `resolveId` time, `db/index.ts` imports `./db.server` — the plugin sees a
63
+ `.server` file imported in the client environment. But the Start compiler strips
64
+ the `getUsers` usage from the client bundle (it's inside a server fn handler),
65
+ and Rollup's tree-shaking then eliminates the `./db.server` dependency entirely.
66
+
67
+ **No server code actually leaks.** But without deferral, the plugin fires at
68
+ `resolveId` time — before tree-shaking — producing a false positive.
69
+
70
+ ### Pre-transform resolves (server-fn-lookup)
71
+
72
+ During dev, Vite's `fetchModule(?SERVER_FN_LOOKUP)` call triggers resolves for
73
+ analysing a module's exports. These are tracked via `serverFnLookupModules` and
74
+ `isPreTransformResolve`, and violations are silenced for them.
75
+
76
+ ## Violation Handling Flow
77
+
78
+ ### Central functions
79
+
80
+ - **`handleViolation()`**: Formats + reports (or silences) the violation. Returns
81
+ a mock module ID (or `{ id, syntheticNamedExports }` in build) so `resolveId`
82
+ can substitute the offending import. May also return `undefined` (suppressed by
83
+ `onViolation` or silent+error in dev) or throw via `ctx.error()` (dev+error).
84
+ - **`reportOrDeferViolation()`**: Dispatch layer. Either defers (stores for later
85
+ verification) or reports immediately, depending on `shouldDefer`.
86
+
87
+ ### `shouldDefer` logic
88
+
89
+ ```ts
90
+ shouldDefer = (isDevMock && !isPreTransformResolve) || isBuild
91
+ ```
92
+
93
+ - **Dev mock**: Defer to `pendingViolations` → verify via post-transform graph
94
+ reachability in `processPendingViolations()`.
95
+ - **Build (both mock and error)**: Defer to `deferredBuildViolations` → verify
96
+ via tree-shaking survival in `generateBundle`.
97
+
98
+ All three violation types (file, specifier, AND marker) are deferred in build
99
+ mode. Marker violations through barrels can also be false positives — e.g., if
100
+ `foo.ts` has `import 'server-only'` and is re-exported through a barrel but
101
+ never used in client code, tree-shaking eliminates `foo.ts` entirely. To enable
102
+ `generateBundle` tracking for markers, `resolveId` returns the unique build
103
+ mock ID instead of the marker module. This is transparent because marker imports
104
+ are bare (`import 'server-only'` — no bindings), and the mock module is equally
105
+ side-effect-free.
106
+
107
+ ## Dev Mode Strategy
108
+
109
+ ### Dev + Error
110
+
111
+ Violations fire immediately via `ctx.error()` in `resolveId`. No tree-shaking
112
+ is available, so false positives for barrel patterns are expected and accepted.
113
+ (Dev + error is typically used only during explicit validation.)
114
+
115
+ ### Dev + Mock
116
+
117
+ 1. `resolveId` calls `handleViolation({ silent: true })` — no warning emitted.
118
+ 2. The mock module ID is returned so the dev server can serve a Proxy-based
119
+ mock instead of the real server module.
120
+ 3. The violation is stored in `pendingViolations` keyed by the importer's file
121
+ path.
122
+ 4. The transform-cache plugin, after resolving post-transform imports, calls
123
+ `processPendingViolations()`.
124
+ 5. `processPendingViolations()` checks graph reachability from entry points
125
+ using only post-transform edges. If the violating importer is reachable
126
+ → confirm (warn). If unreachable → discard. If unknown → keep pending.
127
+
128
+ This approach can't fully eliminate barrel false-positives in dev because
129
+ there's no tree-shaking. The barrel's import of `.server` always resolves,
130
+ and the barrel is reachable. This is a known and accepted limitation.
131
+
132
+ ### Dev mock modules
133
+
134
+ In dev, each violation gets a **per-importer mock edge module** that:
135
+
136
+ - Explicitly exports the names the importer expects (extracted by the
137
+ mock-rewrite plugin).
138
+ - Delegates to a **runtime mock module** that contains a recursive Proxy and
139
+ optional runtime diagnostics (console warnings when mocked values are used).
140
+
141
+ This differs from build mode, where `syntheticNamedExports: true` lets Rollup
142
+ handle named export resolution from the silent mock.
143
+
144
+ ## Build Mode Strategy
145
+
146
+ ### The "mock first, verify later" pattern
147
+
148
+ Both mock and error build modes follow the same pattern:
149
+
150
+ 1. **`resolveId`**: Call `handleViolation({ silent: true })`. Generate a
151
+ **unique per-violation mock module ID** (`\0tanstack-start-import-protection:mock:build:N`).
152
+ Store the violation + mock ID in `env.deferredBuildViolations`. Return the
153
+ mock ID so Rollup substitutes the offending import.
154
+
155
+ 2. **`load`**: Return a silent Proxy-based mock module (same code as
156
+ `RESOLVED_MOCK_MODULE_ID`) with `syntheticNamedExports: true`.
157
+
158
+ 3. **Tree-shaking**: Rollup processes the bundle normally. If no binding from
159
+ the mock module is actually used at runtime, the mock module is eliminated.
160
+
161
+ 4. **`generateBundle`**: Inspect the output chunks. For each deferred violation,
162
+ check whether its unique mock module ID appears in any chunk's `modules`.
163
+ - **Survived** → real violation (the import wasn't tree-shaken away).
164
+ - Error mode: `ctx.error()` — fail the build.
165
+ - Mock mode: `ctx.warn()` — emit a warning.
166
+ - **Eliminated** → false positive (tree-shaking removed it). Suppress
167
+ silently.
168
+
169
+ ### Why unique mock IDs per violation?
170
+
171
+ The original `RESOLVED_MOCK_MODULE_ID` is a single shared virtual module used
172
+ for all mock-mode violations. If multiple violations are deferred, we need to
173
+ know _which specific ones_ survived tree-shaking. A shared ID would tell us
174
+ "something survived" but not which violation it corresponds to. The unique IDs
175
+ (`...mock:build:0`, `...mock:build:1`, etc.) provide this granularity.
176
+
177
+ ### Why mocking doesn't affect tree-shaking
178
+
179
+ From the consumer's perspective, the import bindings are identical whether they
180
+ point to the real module or the mock. Rollup tree-shakes based on binding usage,
181
+ not module content. If a binding from the barrel's re-export of `.server` is
182
+ unused after the Start compiler strips server fn handlers, tree-shaking
183
+ eliminates it regardless of whether it points to real DB code or a Proxy mock.
184
+
185
+ ### Per-environment operation
186
+
187
+ `generateBundle` runs once per Vite environment (client, SSR, etc.). Each
188
+ environment has its own `EnvState` with its own `deferredBuildViolations` array.
189
+ The check only inspects chunks from THAT environment's bundle, ensuring correct
190
+ per-environment verification.
191
+
192
+ ## Marker violations vs. file/specifier violations
193
+
194
+ | | Marker | File / Specifier |
195
+ | ----------------------------- | --------------------------------------------------- | -------------------------------------------- |
196
+ | **What triggers it** | The _importer_ has a conflicting directive | The _import target_ matches a deny rule |
197
+ | **resolveId returns (dev)** | Marker module ID (`RESOLVED_MARKER_*`) \* | Mock edge module ID (per-importer) |
198
+ | **resolveId returns (build)** | Unique build mock ID (same as file/specifier) | Unique build mock ID |
199
+ | **Can be tree-shaken away?** | Yes — if the importer is eliminated by tree-shaking | Yes — if no binding from the target survives |
200
+ | **Deferred in build?** | Yes — deferred to `generateBundle` | Yes — deferred to `generateBundle` |
201
+ | **Deferred in dev mock?** | Yes — deferred to pending graph | Yes — deferred to pending graph |
202
+
203
+ \* In dev mock, `handleViolation` internally returns a mock edge module ID
204
+ (stored as the deferred result in `pendingViolations`), but `resolveId` ignores
205
+ it for markers and falls through to return the marker module ID. The mock edge
206
+ ID is only used for deferral bookkeeping, not for module resolution.
207
+
208
+ ## State Management
209
+
210
+ ### `EnvState` (per Vite environment)
211
+
212
+ Key fields for violation handling:
213
+
214
+ - `seenViolations: Set<string>` — deduplication of logged violations.
215
+ - `pendingViolations: Map<string, Array<PendingViolation>>` — dev mock
216
+ deferral. Keyed by importer file path.
217
+ - `deferredBuildViolations: Array<DeferredBuildViolation>` — build mode
218
+ deferral. Each entry has `{ info, mockModuleId }`.
219
+
220
+ Per-build/watch iteration, `buildStart` clears `pendingViolations` and resets
221
+ `deferredBuildViolations` so deferred entries don't leak across rebuilds.
222
+
223
+ - `graph: ImportGraph` — import dependency graph for reachability checks.
224
+ - `serverFnLookupModules: Set<string>` — modules transitively loaded during
225
+ server-fn analysis (false-positive suppression).
226
+
227
+ ### `SharedState` (cross-environment)
228
+
229
+ - `fileMarkerKind: Map<string, 'server' | 'client'>` — cached per-file marker
230
+ detection. A file's directive is inherent to the file, not the environment.
231
+
232
+ ## Virtual Module IDs
233
+
234
+ | ID Pattern | Usage |
235
+ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
236
+ | `\0tanstack-start-import-protection:mock` | Shared silent mock (dev mock only) |
237
+ | `\0tanstack-start-import-protection:mock:build:N` | Per-violation build mock (unique counter) |
238
+ | `\0tanstack-start-import-protection:mock-edge:BASE64` | Per-importer dev mock with explicit named exports |
239
+ | `\0tanstack-start-import-protection:mock-runtime:BASE64` | Runtime diagnostic mock (dev client, console warnings) |
240
+ | `\0tanstack-start-import-protection:marker:*` | Marker module (empty `export {}`). Suffixed `server-only` or `client-only`; derived from `MARKER_PREFIX` in `plugin.ts` |
241
+
242
+ ## Key Design Decisions
243
+
244
+ ### Why not just skip `.server` resolves in barrels?
245
+
246
+ The plugin doesn't know at `resolveId` time whether the barrel's re-export will
247
+ survive tree-shaking. It can't inspect the consumer's usage — it only sees the
248
+ barrel importing `.server`. Skipping it would miss real violations where the
249
+ barrel's `.server` re-export IS used in client code.
250
+
251
+ ### How marker violations are deferred in build
252
+
253
+ Marker violations normally resolve to `RESOLVED_MARKER_*` (empty `export {}`),
254
+ not a mock. To enable `generateBundle` tracking, in build mode `resolveId`
255
+ returns the unique build mock ID instead of the marker module. This works
256
+ because:
257
+
258
+ 1. The marker import is bare (`import 'server-only'` — no bindings), so
259
+ swapping the resolution to a mock module is transparent.
260
+ 2. The mock module is side-effect-free, just like the marker module.
261
+ 3. If the importer file survives tree-shaking, the mock module survives →
262
+ `generateBundle` fires the violation. If the importer is tree-shaken away
263
+ (e.g., barrel re-export of a marker-protected file that's never used), the
264
+ mock is eliminated → violation suppressed.
265
+
266
+ ### Why accept false positives in dev?
267
+
268
+ Dev mode uses Vite's ESM dev server — no bundling, no tree-shaking. The barrel
269
+ file's import of `.server` always resolves and is always reachable from entry
270
+ points. The graph-reachability check in `processPendingViolations` can only
271
+ eliminate violations where the _importer_ becomes unreachable after the Start
272
+ compiler transforms it, not where individual bindings are unused.
273
+
274
+ This is an accepted trade-off: dev mock mode warns about potential issues,
275
+ build mode provides definitive answers via tree-shaking.
276
+
277
+ ## E2E Test Structure
278
+
279
+ Tests live in `e2e/react-start/import-protection/`:
280
+
281
+ - **Mock mode** (default): `globalSetup` builds the app, captures build warnings
282
+ to `violations.build.json`, starts a dev server capturing to
283
+ `violations.dev.json`. Tests read these JSON files and assert.
284
+ - **Error mode** (`BEHAVIOR=error`): `globalSetup` runs the build expecting
285
+ failure, captures exit code + output. Tests assert the build failed with the
286
+ expected violation.
287
+ - **False-positive test**: The `barrel-reexport` test case verifies that a barrel
288
+ re-exporting from both a `.server` file and a marker-protected file (`foo.ts`
289
+ with `import 'server-only'`), where all server-only bindings are tree-shaken
290
+ away, produces **zero** violations in the build log.