@octanejs/tanstack-start 0.1.0

package/src/internal/start-plugin-core/import-protection/constants.js

@@ -0,0 +1,39 @@
+import { SERVER_FN_LOOKUP } from '../constants.js';
+//#region src/import-protection/constants.ts
+var SERVER_FN_LOOKUP_QUERY = `?${SERVER_FN_LOOKUP}`;
+var MOCK_MODULE_ID = 'tanstack-start-import-protection:mock';
+var MOCK_BUILD_PREFIX = 'tanstack-start-import-protection:mock:build:';
+var MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:';
+var MOCK_RUNTIME_PREFIX = 'tanstack-start-import-protection:mock-runtime:';
+var MARKER_PREFIX = 'tanstack-start-import-protection:marker:';
+var IMPORT_PROTECTION_DEBUG =
+	process.env.TSR_IMPORT_PROTECTION_DEBUG === '1' ||
+	process.env.TSR_IMPORT_PROTECTION_DEBUG === 'true';
+var IMPORT_PROTECTION_DEBUG_FILTER = process.env.TSR_IMPORT_PROTECTION_DEBUG_FILTER;
+var KNOWN_SOURCE_EXTENSIONS = new Set([
+	'.ts',
+	'.tsx',
+	'.tsrx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.json',
+]);
+/** Vite's browser-visible prefix for virtual modules (replaces `\0`). */
+var VITE_BROWSER_VIRTUAL_PREFIX = '/@id/__x00__';
+//#endregion
+export {
+	IMPORT_PROTECTION_DEBUG,
+	IMPORT_PROTECTION_DEBUG_FILTER,
+	KNOWN_SOURCE_EXTENSIONS,
+	MARKER_PREFIX,
+	MOCK_BUILD_PREFIX,
+	MOCK_EDGE_PREFIX,
+	MOCK_MODULE_ID,
+	MOCK_RUNTIME_PREFIX,
+	SERVER_FN_LOOKUP_QUERY,
+	VITE_BROWSER_VIRTUAL_PREFIX,
+};

package/src/internal/start-plugin-core/import-protection/defaults.d.ts

@@ -0,0 +1,19 @@
+import { ImportProtectionEnvRules } from '../schema.js';
+export interface DefaultImportProtectionRules {
+	client: Required<ImportProtectionEnvRules>;
+	server: Required<ImportProtectionEnvRules>;
+}
+/**
+ * Returns the default import protection rules.
+ *
+ * All framework variants are always included so that, e.g., a React
+ * project also denies `@tanstack/solid-start/server` imports.
+ */
+export declare function getDefaultImportProtectionRules(): DefaultImportProtectionRules;
+/**
+ * Marker module specifiers that restrict a file to a specific environment.
+ */
+export declare function getMarkerSpecifiers(): {
+	serverOnly: Array<string>;
+	clientOnly: Array<string>;
+};

package/src/internal/start-plugin-core/import-protection/defaults.js

@@ -0,0 +1,34 @@
+import { startFrameworks } from '../types.js';
+import { getStartPackage } from '#tanstack-start/package-names';
+//#region src/import-protection/defaults.ts
+/**
+ * Returns the default import protection rules.
+ *
+ * All framework variants are always included so that, e.g., a React
+ * project also denies `@tanstack/solid-start/server` imports.
+ */
+function getDefaultImportProtectionRules() {
+	return {
+		client: {
+			specifiers: startFrameworks.map((fw) => `${getStartPackage(fw)}/server`),
+			files: ['**/*.server.*'],
+			excludeFiles: ['**/node_modules/**'],
+		},
+		server: {
+			specifiers: [],
+			files: ['**/*.client.*'],
+			excludeFiles: ['**/node_modules/**'],
+		},
+	};
+}
+/**
+ * Marker module specifiers that restrict a file to a specific environment.
+ */
+function getMarkerSpecifiers() {
+	return {
+		serverOnly: startFrameworks.map((fw) => `${getStartPackage(fw)}/server-only`),
+		clientOnly: startFrameworks.map((fw) => `${getStartPackage(fw)}/client-only`),
+	};
+}
+//#endregion
+export { getDefaultImportProtectionRules, getMarkerSpecifiers };

package/src/internal/start-plugin-core/import-protection/extensionlessAbsoluteIdResolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonicalize extensionless absolute IDs like `/src/foo.server` to the
+ * physical file when possible.
+ *
+ * Keeps a small cache plus a reverse index so we can invalidate on HMR
+ * updates without clearing the whole map.
+ */
+export declare class ExtensionlessAbsoluteIdResolver {
+	private entries;
+	private keysByDep;
+	clear(): void;
+	/**
+	 * Invalidate any cached entries that might be affected by changes to `id`.
+	 * We invalidate both the file and its containing directory.
+	 */
+	invalidateByFile(id: string): void;
+	resolve(id: string): string;
+	private invalidateDep;
+	private buildDepsForKey;
+	private indexDeps;
+	private deleteKey;
+}

package/src/internal/start-plugin-core/import-protection/extensionlessAbsoluteIdResolver.js

@@ -0,0 +1,94 @@
+import { KNOWN_SOURCE_EXTENSIONS } from './constants.js';
+import { normalizeFilePath } from './utils.js';
+import { basename, dirname, extname, isAbsolute } from 'node:path';
+import { resolveModulePath } from 'exsolve';
+//#region src/import-protection/extensionlessAbsoluteIdResolver.ts
+var FILE_RESOLUTION_EXTENSIONS = [...KNOWN_SOURCE_EXTENSIONS];
+/**
+ * Canonicalize extensionless absolute IDs like `/src/foo.server` to the
+ * physical file when possible.
+ *
+ * Keeps a small cache plus a reverse index so we can invalidate on HMR
+ * updates without clearing the whole map.
+ */
+var ExtensionlessAbsoluteIdResolver = class {
+	entries = /* @__PURE__ */ new Map();
+	keysByDep = /* @__PURE__ */ new Map();
+	clear() {
+		this.entries.clear();
+		this.keysByDep.clear();
+	}
+	/**
+	 * Invalidate any cached entries that might be affected by changes to `id`.
+	 * We invalidate both the file and its containing directory.
+	 */
+	invalidateByFile(id) {
+		const file = normalizeFilePath(id);
+		this.invalidateDep(`file:${file}`);
+		if (isAbsolute(file)) this.invalidateDep(`dir:${dirname(file)}`);
+	}
+	resolve(id) {
+		const key = normalizeFilePath(id);
+		const cached = this.entries.get(key);
+		if (cached) return cached.value;
+		let result = key;
+		let resolvedPhysical;
+		if (isAbsolute(key)) {
+			const ext = extname(key);
+			if (!FILE_RESOLUTION_EXTENSIONS.includes(ext)) {
+				const resolved = resolveModulePath(`./${basename(key)}`, {
+					from: dirname(key),
+					extensions: FILE_RESOLUTION_EXTENSIONS,
+					try: true,
+				});
+				if (resolved) {
+					resolvedPhysical = resolved;
+					result = normalizeFilePath(resolved);
+				}
+			}
+		}
+		const resolvedFile = resolvedPhysical ? normalizeFilePath(resolvedPhysical) : void 0;
+		const deps = this.buildDepsForKey(key, resolvedFile);
+		this.entries.set(key, {
+			value: result,
+			deps,
+		});
+		this.indexDeps(key, deps);
+		return result;
+	}
+	invalidateDep(dep) {
+		const keys = this.keysByDep.get(dep);
+		if (!keys) return;
+		for (const key of Array.from(keys)) this.deleteKey(key);
+	}
+	buildDepsForKey(key, resolvedFile) {
+		const deps = /* @__PURE__ */ new Set();
+		deps.add(`file:${key}`);
+		if (isAbsolute(key)) deps.add(`dir:${dirname(key)}`);
+		if (resolvedFile) deps.add(`file:${resolvedFile}`);
+		return deps;
+	}
+	indexDeps(key, deps) {
+		for (const dep of deps) {
+			let keys = this.keysByDep.get(dep);
+			if (!keys) {
+				keys = /* @__PURE__ */ new Set();
+				this.keysByDep.set(dep, keys);
+			}
+			keys.add(key);
+		}
+	}
+	deleteKey(key) {
+		const entry = this.entries.get(key);
+		this.entries.delete(key);
+		if (!entry) return;
+		for (const dep of entry.deps) {
+			const keys = this.keysByDep.get(dep);
+			if (!keys) continue;
+			keys.delete(key);
+			if (keys.size === 0) this.keysByDep.delete(dep);
+		}
+	}
+};
+//#endregion
+export { ExtensionlessAbsoluteIdResolver };

package/src/internal/start-plugin-core/import-protection/matchers.d.ts

@@ -0,0 +1,18 @@
+import { Pattern } from './utils.js';
+export interface CompiledMatcher {
+	pattern: Pattern;
+	literal?: string;
+	test: (value: string) => boolean;
+}
+export declare function isLiteralMatcherPattern(pattern: string): boolean;
+/**
+ * Compile a Pattern (string glob or RegExp) into a fast test function.
+ * String patterns use picomatch for full glob support (**, *, ?, braces, etc.).
+ * RegExp patterns are used as-is.
+ */
+export declare function compileMatcher(pattern: Pattern): CompiledMatcher;
+export declare function compileMatchers(patterns: Array<Pattern>): Array<CompiledMatcher>;
+export declare function matchesAny(
+	value: string,
+	matchers: Array<CompiledMatcher>,
+): CompiledMatcher | undefined;

package/src/internal/start-plugin-core/import-protection/matchers.js

@@ -0,0 +1,39 @@
+import picomatch from 'picomatch';
+//#region src/import-protection/matchers.ts
+var globLikePatternRE = /[*?![\]{}()]/;
+function isLiteralMatcherPattern(pattern) {
+	return !globLikePatternRE.test(pattern);
+}
+/**
+ * Compile a Pattern (string glob or RegExp) into a fast test function.
+ * String patterns use picomatch for full glob support (**, *, ?, braces, etc.).
+ * RegExp patterns are used as-is.
+ */
+function compileMatcher(pattern) {
+	if (pattern instanceof RegExp)
+		return {
+			pattern,
+			test: (value) => {
+				pattern.lastIndex = 0;
+				return pattern.test(value);
+			},
+		};
+	if (isLiteralMatcherPattern(pattern))
+		return {
+			pattern,
+			literal: pattern,
+			test: (value) => value === pattern,
+		};
+	return {
+		pattern,
+		test: picomatch(pattern, { dot: true }),
+	};
+}
+function compileMatchers(patterns) {
+	return patterns.map(compileMatcher);
+}
+function matchesAny(value, matchers) {
+	for (const matcher of matchers) if (matcher.test(value)) return matcher;
+}
+//#endregion
+export { compileMatchers, matchesAny };

package/src/internal/start-plugin-core/import-protection/rewrite.d.ts

@@ -0,0 +1,29 @@
+import { SourceMapLike } from './sourceLocation.js';
+/**
+ * Rewrite static imports/re-exports from denied sources using Babel AST transforms.
+ *
+ * Transforms:
+ *   import { a as b, c } from 'denied'
+ * Into:
+ *   import __tss_deny_0 from 'tanstack-start-import-protection:mock'
+ *   const b = __tss_deny_0.a
+ *   const c = __tss_deny_0.c
+ *
+ * Also handles:
+ *   import def from 'denied'        -> import def from mock
+ *   import * as ns from 'denied'    -> import ns from mock
+ *   export { x } from 'denied'      -> export const x = mock.x
+ *   export * from 'denied'          -> removed
+ *   export { x as y } from 'denied' -> export const y = mock.x
+ */
+export declare function rewriteDeniedImports(
+	code: string,
+	id: string,
+	deniedSources: Set<string>,
+	getMockModuleId?: (source: string) => string,
+):
+	| {
+			code: string;
+			map?: SourceMapLike;
+	  }
+	| undefined;

package/src/internal/start-plugin-core/import-protection/rewrite.js

@@ -0,0 +1,184 @@
+import { MOCK_MODULE_ID } from './constants.js';
+import * as t from '@babel/types';
+import { generateFromAst, parseAst } from '@tanstack/router-utils';
+//#region src/import-protection/rewrite.ts
+function getModuleExportName(node) {
+	return t.isIdentifier(node) ? node.name : node.value;
+}
+function toMemberExpressionProperty(name) {
+	return t.isValidIdentifier(name)
+		? {
+				property: t.identifier(name),
+				computed: false,
+			}
+		: {
+				property: t.stringLiteral(name),
+				computed: true,
+			};
+}
+function toModuleExportNameNode(name) {
+	return t.isValidIdentifier(name) ? t.identifier(name) : t.stringLiteral(name);
+}
+function createInternalReexportVarName(localName, mockIndex, usedNames) {
+	const baseName = t.isValidIdentifier(localName)
+		? `__tss_reexport_${localName}`
+		: `__tss_reexport_${mockIndex}`;
+	let candidate = baseName;
+	let suffix = 0;
+	while (usedNames.has(candidate)) {
+		suffix++;
+		candidate = `${baseName}_${suffix}`;
+	}
+	usedNames.add(candidate);
+	return candidate;
+}
+/**
+ * Rewrite static imports/re-exports from denied sources using Babel AST transforms.
+ *
+ * Transforms:
+ *   import { a as b, c } from 'denied'
+ * Into:
+ *   import __tss_deny_0 from 'tanstack-start-import-protection:mock'
+ *   const b = __tss_deny_0.a
+ *   const c = __tss_deny_0.c
+ *
+ * Also handles:
+ *   import def from 'denied'        -> import def from mock
+ *   import * as ns from 'denied'    -> import ns from mock
+ *   export { x } from 'denied'      -> export const x = mock.x
+ *   export * from 'denied'          -> removed
+ *   export { x as y } from 'denied' -> export const y = mock.x
+ */
+function rewriteDeniedImports(code, id, deniedSources, getMockModuleId = () => MOCK_MODULE_ID) {
+	return rewriteDeniedImportsFromAst(
+		parseAst({
+			code,
+			filename: id,
+		}),
+		id,
+		deniedSources,
+		getMockModuleId,
+	);
+}
+function rewriteDeniedImportsFromAst(
+	ast,
+	id,
+	deniedSources,
+	getMockModuleId = () => MOCK_MODULE_ID,
+) {
+	let modified = false;
+	let mockCounter = 0;
+	for (let i = ast.program.body.length - 1; i >= 0; i--) {
+		const node = ast.program.body[i];
+		if (t.isImportDeclaration(node)) {
+			if (node.importKind === 'type') continue;
+			if (!deniedSources.has(node.source.value)) continue;
+			const mockVar = `__tss_deny_${mockCounter++}`;
+			const replacements = [];
+			replacements.push(
+				t.importDeclaration(
+					[t.importDefaultSpecifier(t.identifier(mockVar))],
+					t.stringLiteral(getMockModuleId(node.source.value)),
+				),
+			);
+			for (const specifier of node.specifiers)
+				if (t.isImportDefaultSpecifier(specifier) || t.isImportNamespaceSpecifier(specifier))
+					replacements.push(
+						t.variableDeclaration('const', [
+							t.variableDeclarator(t.identifier(specifier.local.name), t.identifier(mockVar)),
+						]),
+					);
+				else if (t.isImportSpecifier(specifier)) {
+					if (specifier.importKind === 'type') continue;
+					const memberProperty = toMemberExpressionProperty(
+						getModuleExportName(specifier.imported),
+					);
+					replacements.push(
+						t.variableDeclaration('const', [
+							t.variableDeclarator(
+								t.identifier(specifier.local.name),
+								t.memberExpression(
+									t.identifier(mockVar),
+									memberProperty.property,
+									memberProperty.computed,
+								),
+							),
+						]),
+					);
+				}
+			ast.program.body.splice(i, 1, ...replacements);
+			modified = true;
+			continue;
+		}
+		if (t.isExportNamedDeclaration(node) && node.source) {
+			if (node.exportKind === 'type') continue;
+			if (!deniedSources.has(node.source.value)) continue;
+			const mockIndex = mockCounter++;
+			const mockVar = `__tss_deny_${mockIndex}`;
+			const replacements = [];
+			replacements.push(
+				t.importDeclaration(
+					[t.importDefaultSpecifier(t.identifier(mockVar))],
+					t.stringLiteral(getMockModuleId(node.source.value)),
+				),
+			);
+			const usedInternalVars = /* @__PURE__ */ new Set();
+			const exportSpecifiers = [];
+			for (const specifier of node.specifiers)
+				if (t.isExportSpecifier(specifier)) {
+					if (specifier.exportKind === 'type') continue;
+					const localName = getModuleExportName(specifier.local);
+					const exportedName = getModuleExportName(specifier.exported);
+					const memberProperty = toMemberExpressionProperty(localName);
+					const internalVar = createInternalReexportVarName(localName, mockIndex, usedInternalVars);
+					replacements.push(
+						t.variableDeclaration('const', [
+							t.variableDeclarator(
+								t.identifier(internalVar),
+								t.memberExpression(
+									t.identifier(mockVar),
+									memberProperty.property,
+									memberProperty.computed,
+								),
+							),
+						]),
+					);
+					exportSpecifiers.push({
+						localName: internalVar,
+						exportedName,
+					});
+				}
+			if (exportSpecifiers.length > 0)
+				replacements.push(
+					t.exportNamedDeclaration(
+						null,
+						exportSpecifiers.map((s) =>
+							t.exportSpecifier(t.identifier(s.localName), toModuleExportNameNode(s.exportedName)),
+						),
+					),
+				);
+			ast.program.body.splice(i, 1, ...replacements);
+			modified = true;
+			continue;
+		}
+		if (t.isExportAllDeclaration(node)) {
+			if (node.exportKind === 'type') continue;
+			if (!deniedSources.has(node.source.value)) continue;
+			ast.program.body.splice(i, 1);
+			modified = true;
+			continue;
+		}
+	}
+	if (!modified) return void 0;
+	const result = generateFromAst(ast, {
+		sourceMaps: true,
+		sourceFileName: id,
+		filename: id,
+	});
+	return {
+		code: result.code,
+		...(result.map ? { map: result.map } : {}),
+	};
+}
+//#endregion
+export { rewriteDeniedImports };

package/src/internal/start-plugin-core/import-protection/sourceLocation.d.ts

@@ -0,0 +1,170 @@
+import { ImportAnalysis } from './analysis.js';
+import { Loc } from './trace.js';
+import { ParseAstResult } from '@tanstack/router-utils';
+/**
+ * Minimal source-map shape used throughout the import-protection plugin.
+ */
+export interface SourceMapLike {
+	file?: string;
+	sourceRoot?: string;
+	version: number | string;
+	sources: Array<string>;
+	names: Array<string>;
+	sourcesContent?: Array<string | null>;
+	mappings: string;
+}
+export interface ImportProtectionPerfRecorder {
+	count: (name: string, value?: number) => void;
+	time: (name: string, startedAt: number) => void;
+}
+export interface TransformResult {
+	code: string;
+	filename?: string;
+	map: SourceMapLike | undefined;
+	originalCode: string | undefined;
+	originalResult?: TransformResult;
+	/** Precomputed line index for `code` (index → line/col). */
+	lineIndex?: LineIndex;
+	parsedAst?: ParseAstResult;
+	analysis?: ImportAnalysis;
+	perf?: ImportProtectionPerfRecorder;
+}
+/**
+ * Provides the transformed code and composed sourcemap for a module.
+ *
+ * Populated from a late-running transform hook. By the time `resolveId`
+ * fires for an import, the importer has already been fully transformed.
+ */
+export interface TransformResultProvider {
+	getTransformResult: (id: string) => TransformResult | undefined;
+}
+export interface ImportSpecifierLocationIndex {
+	find: FindImportSpecifierLocationIndex;
+}
+export type LineIndex = {
+	offsets: Array<number>;
+};
+export declare function buildLineIndex(code: string): LineIndex;
+export declare function indexToLineColumn(
+	lineIndex: LineIndex,
+	idx: number,
+): {
+	line: number;
+	column: number;
+};
+export declare function normalizeSourceMap(map: SourceMapLike | null | undefined):
+	| {
+			version: number;
+			file: string;
+			sourceRoot?: string;
+			sources: Array<string>;
+			names: Array<string>;
+			sourcesContent?: Array<string>;
+			mappings: string;
+	  }
+	| undefined;
+/**
+ * Pick the most-likely original source text for `importerFile` from
+ * a sourcemap that may contain multiple sources.
+ */
+export declare function pickOriginalCodeFromSourcesContent(
+	map: SourceMapLike | undefined,
+	importerFile: string,
+	root: string,
+): string | undefined;
+export type ImportLocEntry = {
+	file?: string;
+	line: number;
+	column: number;
+};
+/**
+ * Cache for import statement locations with reverse index for O(1)
+ * invalidation by file.  Keys: `${importerFile}::${source}`.
+ */
+export declare class ImportLocCache {
+	private cache;
+	private reverseIndex;
+	has(key: string): boolean;
+	get(key: string): ImportLocEntry | null | undefined;
+	set(key: string, value: ImportLocEntry | null): void;
+	clear(): void;
+	/** Remove all cache entries where the importer matches `file`. */
+	deleteByFile(file: string): void;
+}
+export type FindImportSpecifierLocationIndex = (result: TransformResult, source: string) => number;
+export declare function getOrCreateOriginalTransformResult(
+	result: TransformResult,
+	importerFile?: string,
+	root?: string,
+): TransformResult | undefined;
+export declare function createImportSpecifierLocationIndex(): ImportSpecifierLocationIndex;
+/**
+ * Find the location of an import statement in a transformed module
+ * by searching the post-transform code and mapping back via sourcemap.
+ * Results are cached in `importLocCache`.
+ */
+export declare function findImportStatementLocationFromTransformed(
+	provider: TransformResultProvider,
+	importerId: string,
+	source: string,
+	importLocCache: ImportLocCache,
+	findImportSpecifierLocationIndex: FindImportSpecifierLocationIndex,
+): Promise<Loc | undefined>;
+/**
+ * Find the first post-compile usage location for a denied import specifier.
+ * Best-effort: searches transformed code for non-import uses of imported
+ * bindings and maps back to original source via sourcemap.
+ */
+export declare function findPostCompileUsageLocation(
+	provider: TransformResultProvider,
+	importerId: string,
+	source: string,
+): Promise<Loc | undefined>;
+/**
+ * Best-effort original-source usage lookup for cases where a later transform
+ * removes or rewrites the import from emitted code but preserves the original
+ * source in `sourcesContent`.
+ */
+export declare function findOriginalUsageLocation(
+	provider: TransformResultProvider,
+	importerId: string,
+	source: string,
+	envType?: 'client' | 'server',
+	root?: string,
+): Loc | undefined;
+/**
+ * Annotate each trace hop with the location of the import that created the
+ * edge (file:line:col). Skips steps that already have a location.
+ */
+export declare function addTraceImportLocations(
+	provider: TransformResultProvider,
+	trace: Array<{
+		file: string;
+		specifier?: string;
+		line?: number;
+		column?: number;
+	}>,
+	importLocCache: ImportLocCache,
+	findImportSpecifierLocationIndex: FindImportSpecifierLocationIndex,
+): Promise<void>;
+export interface CodeSnippet {
+	/** Source lines with line numbers, e.g. `["  6 | import { getSecret } from './secret.server'", ...]` */
+	lines: Array<string>;
+	/** The highlighted line (1-indexed original line number) */
+	highlightLine: number;
+	/** Clickable file:line reference */
+	location: string;
+}
+/**
+ * Build a vitest-style code snippet showing lines surrounding a location.
+ *
+ * Prefers `originalCode` from the sourcemap's sourcesContent; falls back
+ * to transformed code when unavailable.
+ */
+export declare function buildCodeSnippet(
+	provider: TransformResultProvider,
+	moduleId: string,
+	loc: Loc,
+	contextLines?: number,
+	root?: string,
+): CodeSnippet | undefined;