Import Protection - Shared Internals

Overview

src/import-protection/ contains the adapter-independent core for TanStack Start import protection.

Its current structure is:

• parse module code once per TransformResult
• derive a read-only ImportAnalysis object from that AST
• reuse that analysis for source extraction, import-specifier locations, mock export discovery, named export discovery, and usage lookup
• keep AST mutation in a separate rewrite pass
• keep adapter lifecycle/state-machine behavior outside this directory

The shared layer is responsible for correctness-sensitive logic that must stay aligned between Vite and Rsbuild.

Shared Module Layout

analysis.ts

The central shared analysis module.

It builds and caches ImportAnalysis on TransformResult.analysis.

ImportAnalysis contains:

• parsed AST
• line index
• import sources in source order
• import specifier literal locations
• imported bindings by source
• mock export names by source
• named exports
• usage-position cache

It exposes both result-based and code-based helpers:

• getOrCreateImportAnalysis(result)
• getImportSourcesFromResult(result)
• getImportSources(code)
• getImportSpecifierLocationFromResult(result, source)
• getMockExportNamesBySourceFromResult(result)
• getMockExportNamesBySource(code)
• getNamedExportsFromResult(result)
• getNamedExports(code)
• findPostCompileUsagePosFromResult(result, source)
• findPostCompileUsagePos(code, source)
• findOriginalUnsafeUsagePosFromResult(result, source, envType)
• findOriginalUnsafeUsagePos(code, source, envType)
• isValidExportName(name)

adapterUtils.ts

Contains small adapter-facing shared helpers for decisions that are identical in Vite and Rsbuild.

It currently owns:

• environment type selection from envTypeMap
• environment rule selection from compiledRules
• normalized root-relative path calculation
• importer filtering via include/exclude/ignore/srcDirectory rules

This keeps the adapters from duplicating the same targeting logic while still leaving lifecycle-specific behavior in the adapter implementations.

rewrite.ts

Contains the actual AST mutation pass for denied static imports and re-exports.

It is intentionally separate from analysis.ts.

Why:

• analysis is read-only and cacheable
• rewrite mutates AST structure and generates code/maps
• keeping them separate prevents adapter code from depending on mutation when it only needs inspection

rewriteDeniedImports() rewrites denied static import/re-export edges to mock module imports while preserving explicit bindings expected by the importer.

sourceLocation.ts

Builds source locations and snippets from transformed code plus sourcemaps.

It reuses shared analysis for two important lookups:

• import-specifier positions in transformed code
• post-compile and original-source usage locations

It also owns:

• line-index helpers
• sourcemap normalization
• sourcesContent original-source selection
• import-location caching for traces
• code snippet formatting

virtualModules.ts

Owns the shared mock module generators and payload encoding.

This includes:

• silent mock module code
• runtime diagnostic mock module code
• mock-edge module code with explicit named exports
• self-denial module generation for denied files
• marker module loading

The adapter-specific transport of these modules is not handled here.

defaults.ts, matchers.ts, utils.ts, trace.ts

These remain shared support layers:

• defaults.ts: default deny/marker rules
• matchers.ts: compiled glob/regex matcher utilities
• utils.ts: path normalization, candidate generation, messages, defer logic, generic helpers
• trace.ts: import graph, traces, snippet-aware message formatting

Analysis Lifetime And Cache Model

The key cache decision is: analysis is cached per TransformResult, not globally by source text.

That means:

• Vite can attach analysis to transform-cache results for the current module version
• Rsbuild can attach analysis to transform results rebuilt from compilation or preloaded during transform
• cache invalidation follows the host tool's normal module invalidation model
• long dev/HMR sessions do not accumulate an unbounded process-global AST cache

The analysis object is read-only after creation, except for the internal usageByKey memoization map.

Import Source Extraction

getImportSources() is now AST-driven and returns sources in encountered order.

It includes:

• import ... from 'x'
• export ... from 'x'
• export * from 'x'
• import('x')
• dynamic import call forms supported by Babel's AST shape

Adapter code that needs source extraction should call into analysis.ts directly.

Mock Export Discovery

Mock-edge modules need to know which named exports the importer expects.

analysis.ts derives that from the importer AST by recording:

• named import specifiers
• namespace member access
• default-import member access
• re-export specifiers

This produces mockExportNamesBySource, which is a safe over-approximation of the named exports the adapter should expose on a mock-edge module.

Named Export Discovery

Self-denial needs the denied file's export surface.

getNamedExports() and getNamedExportsFromResult() collect valid named exports from:

• function/class declarations
• variable declarations, including destructuring patterns
• export specifiers and aliases

default is excluded from the named export list because the mock generators handle default export separately.

Usage Lookup And Safe Boundaries

Usage lookup is shared across adapters through analysis.ts.

The walker:

• tracks lexical/program/block/function bindings manually
• respects shadowing across nested scopes, block bindings, function params, and catch params
• treats certain compiler-recognized boundaries as safe when looking for original unsafe usage

Safe boundary recognition is environment-specific:

• client env safe boundaries:
  • createServerFn().handler(...)
  • createMiddleware(...).server(...)
  • createIsomorphicFn().server(...)
  • createServerOnlyFn(...)
• server env safe boundaries:
  • createClientOnlyFn(...)
  • createIsomorphicFn().client(...)

This is the core shared logic that keeps both adapters aligned on cases like boundary-safe, factory-safe, and compiler-leak.

Rewriting Versus Analysis

Analysis and rewrite are intentionally separate.

Reasons:

• adapters frequently need inspection without mutation
• mutation wants a fresh, isolated AST/codegen pass
• read-only analysis is much easier to cache safely
• source-location helpers and usage lookup should not depend on whether a module was rewritten

The intended flow is:

1. build or reuse ImportAnalysis
2. inspect/import-locate/trace as needed
3. if a denied-specifier rewrite is needed, run rewriteDeniedImports()

Adapter Contract

The shared layer deliberately does not decide:

• when a violation is discovered
• when it is reported versus deferred
• how dev/build lifecycle hooks work
• how virtual module ids/files are transported by the bundler
• how final compilation truth is obtained

Those are adapter responsibilities.

The shared layer does provide the primitives both adapters rely on:

• rule helpers
• AST parsing
• analysis
• rewrite
• virtual module code generation
• source locations/snippets
• trace formatting

Maintainer Guidance

When making future import-protection changes:

1. If the behavior is about parsing, source extraction, export discovery, usage lookup, source locations, rewrite mechanics, or mock codegen, it probably belongs in src/import-protection/.
2. If the behavior is about hook timing, deferral, compilation truth, pending queues, or environment-specific virtual-module transport, it probably belongs in the adapter docs/code.
3. Prefer extending ImportAnalysis over adding new one-off parsers or wrapper helpers.
4. Avoid reintroducing global source-text caches; cache on TransformResult instead.