@octanejs/tanstack-start 0.1.0

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

@@ -0,0 +1,376 @@
+import { getOrCreate, normalizeFilePath } from './utils.js';
+import {
+	findOriginalUnsafeUsagePosFromResult,
+	findPostCompileUsagePosFromResult,
+	getImportSpecifierLocationFromResult,
+} from './analysis.js';
+import * as path$1 from 'pathe';
+import { SourceMapConsumer } from 'source-map';
+//#region src/import-protection/sourceLocation.ts
+function buildLineIndex(code) {
+	const offsets = [0];
+	for (let i = 0; i < code.length; i++) if (code.charCodeAt(i) === 10) offsets.push(i + 1);
+	return { offsets };
+}
+function upperBound(values, x) {
+	let lo = 0;
+	let hi = values.length;
+	while (lo < hi) {
+		const mid = (lo + hi) >> 1;
+		if (values[mid] <= x) lo = mid + 1;
+		else hi = mid;
+	}
+	return lo;
+}
+function indexToLineColWithIndex(lineIndex, idx) {
+	const offsets = lineIndex.offsets;
+	const ub = upperBound(offsets, idx);
+	const lineIdx = Math.max(0, ub - 1);
+	const line = lineIdx + 1;
+	const lineStart = offsets[lineIdx] ?? 0;
+	return {
+		line,
+		column0: Math.max(0, idx - lineStart),
+	};
+}
+function indexToLineColumn(lineIndex, idx) {
+	const { line, column0 } = indexToLineColWithIndex(lineIndex, idx);
+	return {
+		line,
+		column: column0 + 1,
+	};
+}
+function normalizeSourceMap(map) {
+	if (!map) return;
+	return {
+		...map,
+		version: Number(map.version),
+		file: map.file ?? '',
+		names: Array.isArray(map.names) ? map.names : [],
+		sourcesContent: map.sourcesContent?.map((value) => value ?? '') ?? void 0,
+	};
+}
+/**
+ * Pick the most-likely original source text for `importerFile` from
+ * a sourcemap that may contain multiple sources.
+ */
+function pickOriginalCodeFromSourcesContent(map, importerFile, root) {
+	if (!map?.sourcesContent || map.sources.length === 0) return;
+	const file = normalizeFilePath(importerFile);
+	const sourceRoot = map.sourceRoot;
+	const fileSeg = file.split('/').filter(Boolean);
+	const resolveBase = sourceRoot ? path$1.resolve(root, sourceRoot) : root;
+	let bestIdx = -1;
+	let bestScore = -1;
+	for (let i = 0; i < map.sources.length; i++) {
+		const content = map.sourcesContent[i];
+		if (typeof content !== 'string') continue;
+		const src = map.sources[i] ?? '';
+		const normalizedSrc = normalizeFilePath(src);
+		if (normalizedSrc === file) return content;
+		let resolved;
+		if (!src) resolved = '';
+		else if (path$1.isAbsolute(src)) resolved = normalizeFilePath(src);
+		else resolved = normalizeFilePath(path$1.resolve(resolveBase, src));
+		if (resolved === file) return content;
+		const normalizedSrcSeg = normalizedSrc.split('/').filter(Boolean);
+		const resolvedSeg =
+			resolved !== normalizedSrc ? resolved.split('/').filter(Boolean) : normalizedSrcSeg;
+		const score = Math.max(
+			segmentSuffixScore(normalizedSrcSeg, fileSeg),
+			segmentSuffixScore(resolvedSeg, fileSeg),
+		);
+		if (score > bestScore) {
+			bestScore = score;
+			bestIdx = i;
+		}
+	}
+	if (bestIdx !== -1 && bestScore >= 1) return map.sourcesContent[bestIdx] ?? void 0;
+	return map.sourcesContent[0] ?? void 0;
+}
+/** Count matching path segments from the end of `aSeg` against `bSeg`. */
+function segmentSuffixScore(aSeg, bSeg) {
+	let score = 0;
+	for (let i = aSeg.length - 1, j = bSeg.length - 1; i >= 0 && j >= 0; i--, j--) {
+		if (aSeg[i] !== bSeg[j]) break;
+		score++;
+	}
+	return score;
+}
+async function mapGeneratedToOriginal(map, generated, fallbackFile) {
+	const fallback = {
+		file: fallbackFile,
+		line: generated.line,
+		column: generated.column0 + 1,
+	};
+	if (!map) return fallback;
+	const consumer = await getSourceMapConsumer(map);
+	if (!consumer) return fallback;
+	try {
+		const orig = consumer.originalPositionFor({
+			line: generated.line,
+			column: generated.column0,
+		});
+		if (orig.line != null && orig.column != null)
+			return {
+				file: orig.source ? normalizeFilePath(orig.source) : fallbackFile,
+				line: orig.line,
+				column: orig.column + 1,
+			};
+	} catch {}
+	return fallback;
+}
+var consumerCache = /* @__PURE__ */ new WeakMap();
+function getOriginalCode(result, importerFile, root) {
+	if (result.originalCode === void 0 && importerFile && root) {
+		const map = result.map;
+		if (map?.sourcesContent)
+			result.originalCode = pickOriginalCodeFromSourcesContent(map, importerFile, root);
+	}
+	return result.originalCode;
+}
+function toRawSourceMap(map) {
+	return {
+		...map,
+		file: map.file ?? '',
+		version: Number(map.version),
+		sourcesContent: map.sourcesContent?.map((s) => s ?? '') ?? [],
+	};
+}
+async function getSourceMapConsumer(map) {
+	const cached = consumerCache.get(map);
+	if (cached) return cached;
+	const promise = (async () => {
+		try {
+			return await new SourceMapConsumer(toRawSourceMap(map));
+		} catch {
+			return null;
+		}
+	})();
+	consumerCache.set(map, promise);
+	return promise;
+}
+/**
+ * Cache for import statement locations with reverse index for O(1)
+ * invalidation by file.  Keys: `${importerFile}::${source}`.
+ */
+var ImportLocCache = class {
+	cache = /* @__PURE__ */ new Map();
+	reverseIndex = /* @__PURE__ */ new Map();
+	has(key) {
+		return this.cache.has(key);
+	}
+	get(key) {
+		return this.cache.get(key);
+	}
+	set(key, value) {
+		this.cache.set(key, value);
+		const file = key.slice(0, key.indexOf('::'));
+		getOrCreate(this.reverseIndex, file, () => /* @__PURE__ */ new Set()).add(key);
+	}
+	clear() {
+		this.cache.clear();
+		this.reverseIndex.clear();
+	}
+	/** Remove all cache entries where the importer matches `file`. */
+	deleteByFile(file) {
+		const keys = this.reverseIndex.get(file);
+		if (keys) {
+			for (const key of keys) this.cache.delete(key);
+			this.reverseIndex.delete(file);
+		}
+	}
+};
+function getOrCreateOriginalTransformResult(result, importerFile, root) {
+	getOriginalCode(result, importerFile, root);
+	if (!result.originalCode) return;
+	if (!result.originalResult) {
+		result.originalResult = {
+			code: result.originalCode,
+			filename: result.filename,
+			map: void 0,
+			originalCode: result.originalCode,
+		};
+		if (result.perf) result.originalResult.perf = result.perf;
+	}
+	return result.originalResult;
+}
+function createImportSpecifierLocationIndex() {
+	return {
+		find(result, source) {
+			if (!result.code.includes(source)) return -1;
+			return getImportSpecifierLocationFromResult(result, source);
+		},
+	};
+}
+/**
+ * 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`.
+ */
+async function findImportStatementLocationFromTransformed(
+	provider,
+	importerId,
+	source,
+	importLocCache,
+	findImportSpecifierLocationIndex,
+) {
+	const importerFile = normalizeFilePath(importerId);
+	const cacheKey = `${importerFile}::${source}`;
+	if (importLocCache.has(cacheKey)) return importLocCache.get(cacheKey) ?? void 0;
+	try {
+		const res = provider.getTransformResult(importerId);
+		if (!res) {
+			importLocCache.set(cacheKey, null);
+			return;
+		}
+		const { map } = res;
+		const lineIndex = res.lineIndex ?? (res.lineIndex = buildLineIndex(res.code));
+		const idx = findImportSpecifierLocationIndex(res, source);
+		if (idx === -1) {
+			importLocCache.set(cacheKey, null);
+			return;
+		}
+		const loc = await mapGeneratedToOriginal(
+			map,
+			indexToLineColWithIndex(lineIndex, idx),
+			importerFile,
+		);
+		importLocCache.set(cacheKey, loc);
+		return loc;
+	} catch {
+		importLocCache.set(cacheKey, null);
+		return;
+	}
+}
+/**
+ * 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.
+ */
+async function findPostCompileUsageLocation(provider, importerId, source) {
+	try {
+		const importerFile = normalizeFilePath(importerId);
+		const res = provider.getTransformResult(importerId);
+		if (!res) return void 0;
+		const { code, map } = res;
+		if (!res.lineIndex) res.lineIndex = buildLineIndex(code);
+		const pos = findPostCompileUsagePosFromResult(res, source);
+		if (!pos) return void 0;
+		return await mapGeneratedToOriginal(map, pos, importerFile);
+	} catch {
+		return;
+	}
+}
+/**
+ * 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`.
+ */
+function findOriginalUsageLocation(provider, importerId, source, envType, root) {
+	try {
+		const importerFile = normalizeFilePath(importerId);
+		const res = provider.getTransformResult(importerId);
+		if (!res) return void 0;
+		const originalResult = getOrCreateOriginalTransformResult(res, importerFile, root);
+		if (!originalResult) return void 0;
+		const pos = envType
+			? findOriginalUnsafeUsagePosFromResult(originalResult, source, envType)
+			: findPostCompileUsagePosFromResult(originalResult, source);
+		if (!pos) return void 0;
+		return {
+			file: importerFile,
+			line: pos.line,
+			column: pos.column0 + 1,
+		};
+	} catch {
+		return;
+	}
+}
+/**
+ * Annotate each trace hop with the location of the import that created the
+ * edge (file:line:col). Skips steps that already have a location.
+ */
+async function addTraceImportLocations(
+	provider,
+	trace,
+	importLocCache,
+	findImportSpecifierLocationIndex,
+) {
+	for (const step of trace) {
+		if (!step.specifier) continue;
+		if (step.line != null && step.column != null) continue;
+		const loc = await findImportStatementLocationFromTransformed(
+			provider,
+			step.file,
+			step.specifier,
+			importLocCache,
+			findImportSpecifierLocationIndex,
+		);
+		if (!loc) continue;
+		step.line = loc.line;
+		step.column = loc.column;
+	}
+}
+/**
+ * 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.
+ */
+function buildCodeSnippet(provider, moduleId, loc, contextLines = 2, root) {
+	try {
+		const importerFile = normalizeFilePath(moduleId);
+		const res = provider.getTransformResult(moduleId);
+		if (!res) return void 0;
+		const sourceCode = getOriginalCode(res, importerFile, root) ?? res.code;
+		const targetLine = loc.line;
+		const targetCol = loc.column;
+		if (targetLine < 1) return void 0;
+		const allLines = sourceCode.split('\n');
+		for (let i = 0; i < allLines.length; i++) {
+			const line = allLines[i];
+			if (line.endsWith('\r')) allLines[i] = line.slice(0, -1);
+		}
+		const wantStart = Math.max(1, targetLine - contextLines);
+		const wantEnd = Math.min(allLines.length, targetLine + contextLines);
+		if (targetLine > allLines.length) return void 0;
+		const lines = allLines.slice(wantStart - 1, wantEnd);
+		const gutterWidth = String(wantEnd).length;
+		const sourceFile = loc.file ?? importerFile;
+		const snippetLines = [];
+		for (let i = 0; i < lines.length; i++) {
+			const ln = wantStart + i;
+			const lineContent = lines[i];
+			const lineNumStr = String(ln).padStart(gutterWidth, ' ');
+			const marker = ln === targetLine ? '>' : ' ';
+			snippetLines.push(`  ${marker} ${lineNumStr} | ${lineContent}`);
+			if (ln === targetLine && targetCol > 0) {
+				const padding = ' '.repeat(targetCol - 1);
+				snippetLines.push(`    ${' '.repeat(gutterWidth)} | ${padding}^`);
+			}
+		}
+		return {
+			lines: snippetLines,
+			highlightLine: targetLine,
+			location: `${sourceFile}:${targetLine}:${targetCol}`,
+		};
+	} catch {
+		return;
+	}
+}
+//#endregion
+export {
+	ImportLocCache,
+	addTraceImportLocations,
+	buildCodeSnippet,
+	buildLineIndex,
+	createImportSpecifierLocationIndex,
+	findImportStatementLocationFromTransformed,
+	findOriginalUsageLocation,
+	findPostCompileUsageLocation,
+	getOrCreateOriginalTransformResult,
+	indexToLineColumn,
+	normalizeSourceMap,
+	pickOriginalCodeFromSourcesContent,
+};

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

@@ -0,0 +1,89 @@
+export interface TraceEdge {
+	importer: string;
+	specifier?: string;
+}
+/**
+ * Per-environment reverse import graph.
+ * Maps a resolved module id to the set of modules that import it.
+ */
+export declare class ImportGraph {
+	/**
+	 * resolvedId -> Map<importer, specifier>
+	 *
+	 * We use a Map instead of a Set of objects so edges dedupe correctly.
+	 */
+	readonly reverseEdges: Map<string, Map<string, string | undefined>>;
+	/**
+	 * Forward-edge index: importer -> Set<resolvedId>.
+	 *
+	 * Maintained alongside reverseEdges so that {@link invalidate} can remove
+	 * all outgoing edges for a file in O(outgoing-edges) instead of scanning
+	 * every reverse-edge map in the graph.
+	 */
+	private readonly forwardEdges;
+	readonly entries: Set<string>;
+	addEdge(resolved: string, importer: string, specifier?: string): void;
+	/** Convenience for tests/debugging. */
+	getEdges(resolved: string): Set<TraceEdge> | undefined;
+	addEntry(id: string): void;
+	clear(): void;
+	invalidate(id: string): void;
+}
+export interface TraceStep {
+	file: string;
+	specifier?: string;
+	line?: number;
+	column?: number;
+}
+export interface Loc {
+	file?: string;
+	line: number;
+	column: number;
+}
+/**
+ * BFS from a node upward through reverse edges to find the shortest
+ * path to an entry module.
+ */
+export declare function buildTrace(
+	graph: ImportGraph,
+	startNode: string,
+	maxDepth?: number,
+): Array<TraceStep>;
+export interface ViolationInfo {
+	env: string;
+	envType: 'client' | 'server';
+	type: 'specifier' | 'file' | 'marker';
+	behavior: 'error' | 'mock';
+	pattern?: string | RegExp;
+	specifier: string;
+	importer: string;
+	importerLoc?: Loc;
+	resolved?: string;
+	trace: Array<TraceStep>;
+	/** Vitest-style code snippet showing the offending usage in the leaf module. */
+	snippet?: {
+		lines: Array<string>;
+		highlightLine: number;
+		location: string;
+	};
+}
+/**
+ * Suggestion strings for server-only code leaking into client environments.
+ * Used by both `formatViolation` (terminal) and runtime mock modules (browser).
+ */
+export declare const CLIENT_ENV_SUGGESTIONS: readonly [
+	'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',
+];
+/**
+ * Suggestion strings for client-only code leaking into server environments.
+ * The JSX-specific suggestion is conditionally prepended by `formatViolation`.
+ */
+export declare const SERVER_ENV_SUGGESTIONS: readonly [
+	'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',
+];
+export declare function formatViolation(info: ViolationInfo, root: string): string;

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

@@ -0,0 +1,186 @@
+import { getOrCreate, relativizePath } from './utils.js';
+//#region src/import-protection/trace.ts
+/**
+ * Per-environment reverse import graph.
+ * Maps a resolved module id to the set of modules that import it.
+ */
+var ImportGraph = class {
+	/**
+	 * resolvedId -> Map<importer, specifier>
+	 *
+	 * We use a Map instead of a Set of objects so edges dedupe correctly.
+	 */
+	reverseEdges = /* @__PURE__ */ new Map();
+	/**
+	 * Forward-edge index: importer -> Set<resolvedId>.
+	 *
+	 * Maintained alongside reverseEdges so that {@link invalidate} can remove
+	 * all outgoing edges for a file in O(outgoing-edges) instead of scanning
+	 * every reverse-edge map in the graph.
+	 */
+	forwardEdges = /* @__PURE__ */ new Map();
+	entries = /* @__PURE__ */ new Set();
+	addEdge(resolved, importer, specifier) {
+		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) {
+		const importers = this.reverseEdges.get(resolved);
+		if (!importers) return void 0;
+		const out = /* @__PURE__ */ new Set();
+		for (const [importer, specifier] of importers)
+			out.add({
+				importer,
+				specifier,
+			});
+		return out;
+	}
+	addEntry(id) {
+		this.entries.add(id);
+	}
+	clear() {
+		this.reverseEdges.clear();
+		this.forwardEdges.clear();
+		this.entries.clear();
+	}
+	invalidate(id) {
+		const targets = this.forwardEdges.get(id);
+		if (targets) {
+			for (const resolved of targets) this.reverseEdges.get(resolved)?.delete(id);
+			this.forwardEdges.delete(id);
+		}
+		this.reverseEdges.delete(id);
+	}
+};
+/**
+ * BFS from a node upward through reverse edges to find the shortest
+ * path to an entry module.
+ */
+function buildTrace(graph, startNode, maxDepth = 20) {
+	const visited = new Set([startNode]);
+	const depthByNode = new Map([[startNode, 0]]);
+	const down = /* @__PURE__ */ new Map();
+	const queue = [startNode];
+	let qi = 0;
+	let root = null;
+	while (qi < queue.length) {
+		const node = queue[qi++];
+		const depth = depthByNode.get(node);
+		const importers = graph.reverseEdges.get(node);
+		if (node !== startNode) {
+			if (graph.entries.has(node) || !importers || importers.size === 0) {
+				root = node;
+				break;
+			}
+		}
+		if (depth >= maxDepth) continue;
+		if (!importers || importers.size === 0) continue;
+		for (const [importer, specifier] of importers) {
+			if (visited.has(importer)) continue;
+			visited.add(importer);
+			depthByNode.set(importer, depth + 1);
+			down.set(importer, {
+				next: node,
+				specifier,
+			});
+			queue.push(importer);
+		}
+	}
+	if (!root) root = startNode;
+	const trace = [];
+	let current = root;
+	for (let i = 0; i <= maxDepth + 1; i++) {
+		const link = down.get(current);
+		trace.push({
+			file: current,
+			specifier: link?.specifier,
+		});
+		if (!link) break;
+		current = link.next;
+	}
+	return trace;
+}
+/**
+ * Suggestion strings for server-only code leaking into client environments.
+ * Used by both `formatViolation` (terminal) and runtime mock modules (browser).
+ */
+var 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',
+];
+/**
+ * Suggestion strings for client-only code leaking into server environments.
+ * The JSX-specific suggestion is conditionally prepended by `formatViolation`.
+ */
+var 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) => relativizePath(p, root);
+	const relLoc = (p, loc) => {
+		const r = rel(p);
+		const file = loc?.file ? rel(loc.file) : r;
+		return loc ? `${file}:${loc.line}:${loc.column}` : r;
+	};
+	const relTraceStep = (step) => {
+		const file = rel(step.file);
+		if (step.line == null) return file;
+		const col = step.column ?? 1;
+		return `${file}:${step.line}:${col}`;
+	};
+	const lines = [];
+	lines.push(``);
+	lines.push(`[import-protection] Import denied in ${info.envType} environment`);
+	lines.push(``);
+	if (info.type === 'specifier')
+		lines.push(`  Denied by specifier pattern: ${String(info.pattern)}`);
+	else if (info.type === 'file') lines.push(`  Denied by file pattern: ${String(info.pattern)}`);
+	else lines.push(`  Denied by marker: module is restricted to the opposite environment`);
+	lines.push(`  Importer: ${relLoc(info.importer, info.importerLoc)}`);
+	lines.push(`  Import: "${rel(info.specifier)}"`);
+	if (info.resolved) lines.push(`  Resolved: ${rel(info.resolved)}`);
+	if (info.trace.length > 0) {
+		lines.push(``);
+		lines.push(`  Trace:`);
+		for (let i = 0; i < info.trace.length; i++) {
+			const step = info.trace[i];
+			const tag = i === 0 ? ' (entry)' : '';
+			const spec = step.specifier ? ` (import "${rel(step.specifier)}")` : '';
+			lines.push(`    ${i + 1}. ${relTraceStep(step)}${tag}${spec}`);
+		}
+	}
+	if (info.snippet) {
+		lines.push(``);
+		lines.push(`  Code:`);
+		for (const snippetLine of info.snippet.lines) lines.push(snippetLine);
+		lines.push(``);
+		lines.push(`  ${rel(info.snippet.location)}`);
+	}
+	lines.push(``);
+	if (info.envType === 'client') {
+		lines.push(`  Suggestions:`);
+		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));
+		lines.push(`  Suggestions:`);
+		if (looksLikeJsx)
+			lines.push(
+				`    - Wrap the JSX in <ClientOnly fallback={<Loading />}>...</ClientOnly> so it only renders in the browser after hydration`,
+			);
+		for (const s of SERVER_ENV_SUGGESTIONS) lines.push(`    - ${s}`);
+	}
+	lines.push(``);
+	return lines.join('\n');
+}
+//#endregion
+export { CLIENT_ENV_SUGGESTIONS, ImportGraph, buildTrace, formatViolation };