@torpor/build 0.4.14 → 1.0.0

package/src/site/checkLayoutSlots.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { parse } from "@torpor/view/compile";
+import type Route from "../types/Route";
+import { LAYOUT_ROUTE } from "../types/RouteType";
+import type Site from "./Site";
+import { createApiCallCheck, resolveSpecifier, type RouteCheckIssue } from "./checkRoutes";
+
+/**
+ * The default import of a `.torp` component from a `.ts`/`.js` route file,
+ * e.g. `import component from "@/views/Layout.torp"`.
+ */
+const DEFAULT_TORP_IMPORT_RE = /import\s+[A-Za-z_$][\w$]*\s+from\s*["']([^"']+\.torp)["']/;
+
+/**
+ * Checks that every `_layout` route renders its default `<slot />`.
+ *
+ * The layout engine composes pages by passing each layout (and finally the
+ * page) as the default slot of its parent, so a layout that never renders
+ * `<slot />` drops its entire content: the server renders the layout's own
+ * markup with an empty content area (no error), and the first client-side
+ * navigation that reuses the layout fails on a null slot region.
+ *
+ * Runs at build time (failing the build) and at dev startup. Best-effort and
+ * static: a layout that renders `<slot />` conditionally (inside `@if`)
+ * passes here, and is caught at request time by the server render warning
+ * (see site/layoutSlots.ts).
+ */
+export function checkLayoutSlots(site: Site): RouteCheckIssue[] {
+	const issues: RouteCheckIssue[] = [];
+	for (const route of site.routes) {
+		if (route.type === LAYOUT_ROUTE) {
+			issues.push(...checkLayoutSlot(site, route));
+		}
+	}
+	return issues;
+}
+
+/**
+ * Checks a single layout route's component (the `.torp` route file itself,
+ * or the `.torp` file its `.ts`/`.js` endpoint re-exports as its default
+ * import). Routes without a file (inline endpoints) can't hold a component,
+ * so they are skipped.
+ */
+export function checkLayoutSlot(site: Site, route: Route): RouteCheckIssue[] {
+	if (route.type !== LAYOUT_ROUTE || !route.file) return [];
+
+	const check = createApiCallCheck(site);
+
+	// The component is either the route file itself (.torp) or a .ts/.js
+	// endpoint re-exporting a .torp component as its default export
+	let torpFile = path.join(site.root, route.file);
+	if (!route.file.endsWith(".torp")) {
+		const source = readIfExists(torpFile);
+		if (source === undefined) return [];
+		const match = DEFAULT_TORP_IMPORT_RE.exec(source);
+		if (!match) return [];
+		const resolved = resolveSpecifier(match[1], torpFile, check);
+		if (!resolved) return [];
+		torpFile = resolved;
+	}
+
+	const source = readIfExists(torpFile);
+	if (source === undefined) return [];
+
+	// Parse errors are reported when the file is compiled, not here
+	const parsed = parse(source);
+	if (!parsed.ok || !parsed.template) return [];
+	if (rendersDefaultSlot(parsed.template)) return [];
+
+	return [
+		{
+			file: route.file,
+			line: 1,
+			severity: "error",
+			message:
+				"The layout never renders <slot />, so pages under it render without their content. " +
+				"Every _layout component must render <slot />, or pass it down to a child component " +
+				"it renders.",
+		},
+	];
+}
+
+function readIfExists(file: string): string | undefined {
+	try {
+		if (!existsSync(file) || !statSync(file).isFile()) return undefined;
+		return readFileSync(file, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Walks a parsed template looking for a default `<slot />` anywhere in the
+ * render tree — including nested inside a child component element, which is
+ * how a layout passes the page slot down (e.g. `<Shell><slot /></Shell>`).
+ */
+// HACK: no types on the internal parse tree nodes (same as the prettier plugin)
+function rendersDefaultSlot(template: any): boolean {
+	const component = template.components?.[0];
+	if (!component) return false;
+	return walk(component.markup);
+}
+
+function walk(node: any): boolean {
+	if (
+		(node.type === "element" || node.type === "special") &&
+		node.tagName === "slot" &&
+		!node.attributes?.some((a: any) => a.name === "name")
+	) {
+		return true;
+	}
+	return (node.children ?? []).some(walk);
+}

package/src/site/checkRoutes.ts

@@ -0,0 +1,435 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import type Route from "../types/Route";
+import {
+	ERROR_ROUTE,
+	HOOK_ROUTE,
+	HOOK_SERVER_ROUTE,
+	LAYOUT_ROUTE,
+	LAYOUT_SERVER_ROUTE,
+	PAGE_SERVER_ROUTE,
+	SERVER_ROUTE,
+} from "../types/RouteType";
+import tsconfigAliases, { type AliasEntry } from "../utils/tsconfigAliases";
+import type Site from "./Site";
+
+/**
+ * A problem found in a route file's type annotations by `checkRoutes`.
+ */
+export interface RouteCheckIssue {
+	/** The route file, relative to the site root */
+	file: string;
+	/** 1-based line number of the annotation */
+	line: number;
+	severity: "error" | "warning";
+	message: string;
+}
+
+const ENDPOINT_TYPES = ["PageServerEndPoint", "PageEndPoint", "ServerEndPoint", "ServerHook"];
+
+const USAGE_RE = new RegExp(`\\b(satisfies|as|:)\\s*\\b(${ENDPOINT_TYPES.join("|")})\\b`, "g");
+
+const TYPE_NAME_RE = new RegExp(`^(?:${ENDPOINT_TYPES.join("|")})\\b`);
+
+/**
+ * Checks the route files of a site against their type annotations:
+ *
+ * - Route path annotations (e.g. `PageServerEndPoint<"/posts/[id]">`) must
+ *   match the route derived from the file's location, so types can't silently
+ *   lie when files move
+ * - Exports that widen the endpoint type (`satisfies T as T`, `as T`, or a
+ *   variable annotation) are flagged, because they destroy `PageData` /
+ *   `PageForm` / param inference
+ * - Routes with dynamic params but no route annotation are flagged, because
+ *   their params are loosely typed
+ *
+ * Only `.ts` route files are checked; annotations are matched by the standard
+ * type names (renamed imports are not detected). Best-effort, source-level —
+ * comments mentioning these patterns may produce false positives.
+ */
+export function checkRoutes(site: Site): RouteCheckIssue[] {
+	const issues: RouteCheckIssue[] = [];
+	for (const route of site.routes) {
+		issues.push(...checkRoute(site, route));
+	}
+	return issues;
+}
+
+/**
+ * Checks a single route's file. Returns no issues for routes without a `.ts`
+ * file (`.torp` components, inline endpoints, `.js` files).
+ */
+export function checkRoute(site: Site, route: Route): RouteCheckIssue[] {
+	if (!route.file || !route.file.endsWith(".ts")) return [];
+	let source: string;
+	try {
+		source = readFileSync(path.join(site.root, route.file), "utf8");
+	} catch {
+		return [];
+	}
+	return checkRouteSource(source, route.file, expectedAnnotationPath(route), typeNameFor(route));
+}
+
+/**
+ * Checks a single route file's source. Exported for reuse (e.g. re-checking a
+ * changed file during dev).
+ * @param source The route file's source code
+ * @param file The file path, relative to the site root (used in messages)
+ * @param expected The route path derived from the file's location
+ * @param typeName The endpoint type name conventionally used by this route
+ * type (used in suggestions)
+ */
+export function checkRouteSource(
+	source: string,
+	file: string,
+	expected: string,
+	typeName: string,
+): RouteCheckIssue[] {
+	const issues: RouteCheckIssue[] = [];
+	let sawAnnotation = false;
+	USAGE_RE.lastIndex = 0;
+	for (let m = USAGE_RE.exec(source); m; m = USAGE_RE.exec(source)) {
+		sawAnnotation = true;
+		const kind = m[1];
+		const usedTypeName = m[2];
+		const { routePath, end } = parseTypeArgs(source, m.index + m[0].length);
+		const line = lineOf(source, m.index);
+		if (routePath !== undefined && routePath !== expected) {
+			issues.push({
+				file,
+				line,
+				severity: "error",
+				message: `Route annotation "${routePath}" doesn't match this file's route "${expected}" (derived from its location). Did the file move?`,
+			});
+		}
+		if (kind === "as" || kind === ":") {
+			issues.push({
+				file,
+				line,
+				severity: "warning",
+				message:
+					kind === "as"
+						? `The \`as ${usedTypeName}\` cast widens the exported type, so PageData/PageForm/param inference falls back to loose types. Use \`satisfies ${usedTypeName}${routePathArg(expected, routePath)}\` without a cast instead.`
+						: `The variable annotation widens the exported type, so PageData/PageForm/param inference falls back to loose types. Use \`satisfies ${usedTypeName}${routePathArg(expected, routePath)}\` on the default export instead.`,
+			});
+		} else {
+			const cast = parseAsCast(source, end);
+			if (cast) {
+				issues.push({
+					file,
+					line,
+					severity: "warning",
+					message: `The \`as\` cast after \`satisfies\` widens the exported type, so PageData/PageForm/param inference falls back to loose types. Use \`satisfies ${usedTypeName}${routePathArg(expected, routePath ?? cast.routePath)}\` on its own.`,
+				});
+				if (cast.routePath !== undefined && cast.routePath !== expected) {
+					issues.push({
+						file,
+						line,
+						severity: "error",
+						message: `Route annotation "${cast.routePath}" doesn't match this file's route "${expected}" (derived from its location). Did the file move?`,
+					});
+				}
+				// Skip the `as T` so it isn't reported again as a separate cast
+				USAGE_RE.lastIndex = cast.end;
+			} else if (routePath === undefined && expected.includes("[")) {
+				issues.push({
+					file,
+					line,
+					severity: "warning",
+					message: `No route path on the annotation, so params are loosely typed. Use \`satisfies ${usedTypeName}<"${expected}">\`.`,
+				});
+			}
+		}
+	}
+	if (!sawAnnotation && file.endsWith(".ts") && expected.includes("[")) {
+		issues.push({
+			file,
+			line: 1,
+			severity: "warning",
+			message: `No route annotation, so params are loosely typed. Add \`satisfies ${typeName}<"${expected}">\` to the default export.`,
+		});
+	}
+	return issues;
+}
+
+/**
+ * Prints issues to the console and returns the number of errors.
+ */
+export function reportRouteIssues(issues: RouteCheckIssue[]): number {
+	for (const issue of issues) {
+		console.error(`[torpor] ${issue.severity}: ${issue.file}:${issue.line} ${issue.message}`);
+	}
+	return issues.filter((i) => i.severity === "error").length;
+}
+
+const MAKE_API_RE = /\bmakeApi\s*<\s*(["'])([^"']+)\1\s*,\s*typeof\s+([A-Za-z_$][\w$]*)/g;
+
+const DEFAULT_IMPORT_RE = /\bimport\s+(?:type\s+)?([A-Za-z_$][\w$]*)\s+from\s*(["'])([^"']+)\2/g;
+
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".torpor", ".vite", "coverage"]);
+
+const SOURCE_FILE_RE = /\.(ts|js|torp)$/;
+
+/**
+ * Precomputed state for checking `makeApi` calls: the site root, its route
+ * files keyed by path, and tsconfig path aliases for resolving imports.
+ */
+export interface ApiCallCheck {
+	root: string;
+	routesByFile: Map<string, Route>;
+	aliases: AliasEntry[];
+}
+
+/**
+ * Creates the shared state used by `checkApiCallSource`, so per-file checks
+ * (e.g. re-checking a changed file during dev) don't rebuild it.
+ */
+export function createApiCallCheck(site: Site): ApiCallCheck {
+	const routesByFile = new Map<string, Route>();
+	for (const route of site.routes) {
+		if (route.file) routesByFile.set(route.file.replaceAll("\\", "/"), route);
+	}
+	return { root: site.root, routesByFile, aliases: tsconfigAliases(site.root) };
+}
+
+/**
+ * Checks `makeApi<Route, typeof endpoint>` calls across the site's source
+ * files: the `Route` argument must match the route derived from the imported
+ * endpoint file's location. Calls whose endpoint isn't a type-only import of
+ * a known route file are skipped.
+ */
+export function checkApiCalls(site: Site): RouteCheckIssue[] {
+	const check = createApiCallCheck(site);
+	const issues: RouteCheckIssue[] = [];
+	for (const file of walkSourceFiles(site.root)) {
+		let source: string;
+		try {
+			source = readFileSync(file, "utf8");
+		} catch {
+			continue;
+		}
+		issues.push(...checkApiCallSource(source, file, check));
+	}
+	return issues;
+}
+
+/**
+ * Checks the `makeApi` calls in a single file's source.
+ * @param source The file's source code
+ * @param file The file's absolute path (used to resolve relative imports and
+ * to derive the path shown in messages)
+ * @param check Shared state from `createApiCallCheck`
+ */
+export function checkApiCallSource(
+	source: string,
+	file: string,
+	check: ApiCallCheck,
+): RouteCheckIssue[] {
+	const imports = new Map<string, string>();
+	for (let m = DEFAULT_IMPORT_RE.exec(source); m; m = DEFAULT_IMPORT_RE.exec(source)) {
+		imports.set(m[1], m[3]);
+	}
+	const issues: RouteCheckIssue[] = [];
+	for (let m = MAKE_API_RE.exec(source); m; m = MAKE_API_RE.exec(source)) {
+		const specifier = imports.get(m[3]);
+		if (!specifier) continue;
+		const resolved = resolveSpecifier(specifier, file, check);
+		if (!resolved) continue;
+		const relFile = path.relative(check.root, resolved).replaceAll("\\", "/");
+		const route = check.routesByFile.get(relFile);
+		if (!route) continue;
+		const expected = expectedAnnotationPath(route);
+		if (m[2] !== expected) {
+			issues.push({
+				file: path.relative(check.root, file).replaceAll("\\", "/"),
+				line: lineOf(source, m.index),
+				severity: "error",
+				message: `makeApi route "${m[2]}" doesn't match the endpoint's route "${expected}" (derived from ${relFile}). Did the endpoint move?`,
+			});
+		}
+	}
+	return issues;
+}
+
+/**
+ * Resolves an import specifier to an existing file: relative specifiers are
+ * resolved against the importing file, others against tsconfig path aliases.
+ * Bare module specifiers that match no alias return undefined.
+ */
+export function resolveSpecifier(
+	specifier: string,
+	fromFile: string,
+	check: ApiCallCheck,
+): string | undefined {
+	let candidate: string | undefined;
+	if (specifier.startsWith("./") || specifier.startsWith("../")) {
+		candidate = path.resolve(path.dirname(fromFile), specifier);
+	} else {
+		for (const alias of check.aliases) {
+			if (typeof alias.find === "string") {
+				if (specifier.startsWith(alias.find)) {
+					candidate = path.resolve(alias.replacement, specifier.slice(alias.find.length));
+					break;
+				}
+			} else if (alias.find.test(specifier)) {
+				candidate = specifier.replace(alias.find, alias.replacement);
+				break;
+			}
+		}
+	}
+	if (!candidate) return undefined;
+	const probes = [
+		candidate,
+		`${candidate}.ts`,
+		`${candidate}.js`,
+		path.join(candidate, "index.ts"),
+		path.join(candidate, "index.js"),
+	];
+	for (const probe of probes) {
+		if (existsSync(probe) && statSync(probe).isFile()) return probe;
+	}
+	return undefined;
+}
+
+function walkSourceFiles(root: string): string[] {
+	const files: string[] = [];
+	const visit = (dir: string): void => {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				if (!SKIP_DIRS.has(entry.name)) visit(path.join(dir, entry.name));
+			} else if (
+				entry.isFile() &&
+				SOURCE_FILE_RE.test(entry.name) &&
+				!entry.name.endsWith(".d.ts")
+			) {
+				files.push(path.join(dir, entry.name));
+			}
+		}
+	};
+	visit(root);
+	return files;
+}
+
+/**
+ * The route path a file's annotation should use, derived from its manifest
+ * entry: internal suffixes (`/~server`, `/_layout` etc) are stripped so e.g.
+ * `posts/[id]/+page.server.ts` expects `"/posts/[id]"`.
+ */
+export function expectedAnnotationPath(route: Route): string {
+	let p = route.path;
+	switch (route.type) {
+		case PAGE_SERVER_ROUTE:
+			p = p.replace(/\/~server$/, "");
+			break;
+		case LAYOUT_ROUTE:
+			p = p.replace(/\/_layout$/, "");
+			break;
+		case LAYOUT_SERVER_ROUTE:
+			p = p.replace(/\/_layout\/~server$/, "");
+			break;
+		case HOOK_ROUTE:
+			p = p.replace(/\/_hook$/, "");
+			break;
+		case HOOK_SERVER_ROUTE:
+			p = p.replace(/\/_hook\/~server$/, "");
+			break;
+		case ERROR_ROUTE:
+			p = p.replace(/\/_error$/, "");
+			break;
+	}
+	return p === "" ? "/" : p;
+}
+
+function typeNameFor(route: Route): string {
+	switch (route.type) {
+		case PAGE_SERVER_ROUTE:
+		case LAYOUT_SERVER_ROUTE:
+			return "PageServerEndPoint";
+		case SERVER_ROUTE:
+			return "ServerEndPoint";
+		case HOOK_ROUTE:
+		case HOOK_SERVER_ROUTE:
+			return "ServerHook";
+		default:
+			return "PageEndPoint";
+	}
+}
+
+/**
+ * Parses the type arguments that follow an endpoint type name, returning the
+ * first argument when it is a string literal (the route path), plus the index
+ * after the closing `>` (or after the type name when there are no arguments).
+ */
+function parseTypeArgs(
+	source: string,
+	start: number,
+): { routePath: string | undefined; end: number } {
+	let i = start;
+	while (i < source.length && /\s/.test(source[i])) i++;
+	if (source[i] !== "<") return { routePath: undefined, end: i };
+	i++;
+	let depth = 1;
+	let routePath: string | undefined;
+	let seenComma = false;
+	while (i < source.length) {
+		const c = source[i];
+		if (c === '"' || c === "'") {
+			const quote = c;
+			let j = i + 1;
+			while (j < source.length && source[j] !== quote) {
+				if (source[j] === "\\") j++;
+				j++;
+			}
+			if (routePath === undefined && !seenComma) routePath = source.slice(i + 1, j);
+			i = j + 1;
+			continue;
+		}
+		if (c === "<") depth++;
+		else if (c === ">") {
+			depth--;
+			if (depth === 0) return { routePath, end: i + 1 };
+		} else if (c === "," && routePath === undefined) {
+			seenComma = true;
+		}
+		i++;
+	}
+	return { routePath, end: i };
+}
+
+/**
+ * Parses an `as T`-style cast that follows a `satisfies T` usage, returning
+ * its optional route path argument and the index after the cast.
+ */
+function parseAsCast(
+	source: string,
+	start: number,
+): { routePath: string | undefined; end: number } | undefined {
+	let i = start;
+	while (i < source.length && /\s/.test(source[i])) i++;
+	if (!/^as\b/.test(source.slice(i, i + 3))) return undefined;
+	i += 2;
+	while (i < source.length && /\s/.test(source[i])) i++;
+	if (!TYPE_NAME_RE.test(source.slice(i))) return undefined;
+	i = i + source.slice(i).match(TYPE_NAME_RE)![0].length;
+	return parseTypeArgs(source, i);
+}
+
+function routePathArg(expected: string, actual: string | undefined): string {
+	// Keep the user's own (correct) path when widening a properly-annotated
+	// export; otherwise suggest the path derived from the file's location
+	return `<"${actual ?? expected}">`;
+}
+
+function lineOf(source: string, index: number): number {
+	let line = 1;
+	for (let i = 0; i < index; i++) {
+		if (source[i] === "\n") line++;
+	}
+	return line;
+}

package/src/site/clientEntry.ts

@@ -19,9 +19,8 @@ client.router = router;
 
 // Intercept clicks on links
 window.addEventListener("click", async (e) => {
-	if (e.target && (e.target as HTMLElement).tagName === "A") {
-		const link = e.target as HTMLAnchorElement;
-
+	const link = getLink(e.target);
+	if (link) {
 		if (ignoreAnchorMouseEvent(link, e)) {
 			return;
 		}
@@ -45,9 +44,8 @@ window.addEventListener("mouseover", maybePrefetch);
 window.addEventListener("touchstart", maybePrefetch);
 
 async function maybePrefetch(e: MouseEvent | TouchEvent) {
-	if (e.target && (e.target as HTMLElement).tagName === "A") {
-		const link = e.target as HTMLAnchorElement;
-
+	const link = getLink(e.target);
+	if (link) {
 		if (ignoreAnchorMouseEvent(link, e)) {
 			return;
 		}
@@ -77,16 +75,31 @@ async function maybePrefetch(e: MouseEvent | TouchEvent) {
 	}
 }
 
+function getLink(target: EventTarget | null): HTMLAnchorElement | undefined {
+	// The target may be a child element of the link (e.g. an icon inside it),
+	// so walk up to the nearest actual link. Fragment-only links (href="#...")
+	// are left to the browser's native jump-to-anchor behavior
+	if (!(target instanceof Element)) return;
+	const link = target.closest("a[href]");
+	if (link?.getAttribute("href")?.startsWith("#")) return;
+	return (link as HTMLAnchorElement) ?? undefined;
+}
+
 function ignoreAnchorMouseEvent(link: HTMLAnchorElement, e: MouseEvent | TouchEvent) {
-	// Ignore the event if a modifier key is pressed, or target is not
-	// "_self", or if rel="external"
+	// Ignore the event if it was already handled (e.g. a user handler calling
+	// preventDefault), a modifier key is pressed, the target is not "_self"
+	// (e.g. "_blank"), rel="external", it's a download link, or it's in a
+	// contenteditable region
 	return (
+		e.defaultPrevented ||
 		e.altKey ||
 		e.ctrlKey ||
 		e.metaKey ||
 		e.shiftKey ||
 		(link.target && link.target !== "_self") ||
-		link.rel === "external"
+		link.rel === "external" ||
+		link.hasAttribute("download") ||
+		link.isContentEditable
 	);
 }
 

package/src/site/layoutSlots.ts

@@ -0,0 +1,53 @@
+/**
+ * Layouts are composed by the layout engine passing each layout (and finally
+ * the page) as the default slot of its parent — so every `_layout` component
+ * must render `<slot />`, or pass the default slot down to a child component
+ * it renders. A layout that doesn't drops its entire content: the server
+ * renders the layout's own markup with an empty content area (no error), and
+ * the first client-side navigation that reuses the layout crashes on a null
+ * slot region.
+ *
+ * The static `checkLayoutSlots` check catches this at build/dev time; these
+ * helpers report it at request time for the cases static analysis can't see
+ * (e.g. a `<slot />` rendered conditionally inside `@if`). They are
+ * server-side only — nothing here is imported into the client bundle.
+ */
+
+/**
+ * Returns the path of the outermost layout that never rendered its
+ * `<slot />`, or undefined when every level rendered.
+ *
+ * Slot level j (1-based) is the slot render that layout j - 1 receives: the
+ * root layout (layouts[0]) renders level 1, layout i renders level i + 1,
+ * and level layouts.length renders the page. A broken level makes every
+ * deeper level unreachable, so the first level that never ran identifies
+ * the offending layout.
+ */
+export function findMissingSlotLayout(
+	layouts: readonly { path: string }[],
+	invokedLevels: ReadonlySet<number>,
+): string | undefined {
+	for (let level = 1; level <= layouts.length; level++) {
+		if (!invokedLevels.has(level)) {
+			return layouts[level - 1].path;
+		}
+	}
+	return undefined;
+}
+
+const warnedLayouts = new Set<string>();
+
+/**
+ * Reports a layout that dropped its slot content. The condition is a genuine
+ * rendering bug (the page content is missing from the output), so it is not
+ * dev-gated — but it warns only once per layout path to avoid per-request
+ * noise.
+ */ export function warnMissingSlotContent(layoutPath: string): void {
+	if (warnedLayouts.has(layoutPath)) return;
+	warnedLayouts.add(layoutPath);
+	console.warn(
+		`[torpor] The layout at "${layoutPath}" never rendered <slot />, so the page content ` +
+			`was not included in the render. Every _layout component must render <slot /> (or ` +
+			`pass the default slot down to a child component it renders).`,
+	);
+}