@warlock.js/web 5.0.2 → 5.2.0

package/esm/build/discover-pages.mjs

@@ -1,12 +1,16 @@
 import { composeRoutePath } from "../routing/compose-route-path.mjs";
+import { deriveFilesystemRouteName, deriveFilesystemRoutePath } from "../routing/filesystem-route.mjs";
 import { NestedLayoutsNotSupportedError, selectPageLayout } from "../routing/layout-policy.mjs";
 import { deriveFallbackRouteName } from "../routing/route-identity.mjs";
+import { NOT_FOUND_ROUTE_NAME, NOT_FOUND_ROUTE_PATH, NotFoundPageDeclaresRouteError, isNotFoundPageFile } from "../server/not-found-page.mjs";
+import { METADATA_KEYS, OPEN_GRAPH_KEYS, TWITTER_KEYS } from "../metadata.mjs";
+import { assertPageHasDefaultExport } from "./page-default-export.mjs";
 import { NonLiteralRouteExportError, readRouteExports } from "./read-route-exports.mjs";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 import { parse } from "@babel/parser";
 
-//#region ../web/src/build/discover-pages.ts
+//#region web/src/build/discover-pages.ts
 /**
 * Static discovery of the application's page graph — the ONE scan every
 * provider shares.
@@ -29,20 +33,40 @@ import { parse } from "@babel/parser";
 * `route` and each layout's declared `prefix` by PARSING the source
 * ({@link readRouteExports}). It still imports no application module.
 *
-* The route a page is served under is the one the page DECLARES, not the one
-* its directory suggests, so that is the route discovery reports. The
-* composition — EVERY layout `prefix` on the page's path, outermost first, plus
-* the page's own `route` path — and the fallback used when a route omits its
-* name are mirrored from the server's installer (`installPageRoutes`),
-* deliberately and in one direction: build and boot agree because one of them
-* copies the other, not because two conventions were written to match.
+* An explicit `route` export wins. Otherwise the URL is derived from the page's
+* path beneath `src/web`: directories contribute segments, `(groups)` do not,
+* `index.page.tsx` claims its directory, and `[id]` becomes `:id`. A layout
+* `prefix` replaces its own directory segment. The same recipe is emitted to
+* every provider so build and boot cannot drift.
 *
 * Discovery also CLASSIFIES each layout — does its module have a default
 * export, does it export `middleware` — because the layout policy
 * ({@link "../routing/layout-policy.ts"}) owns the rule but may not touch a
 * filesystem to learn the facts the rule needs. That classification is another
 * parse, never an import: a layout is read exactly the way a page's `route` is.
+*
+* And it CHECKS the page's `metadata` keys ({@link UnknownMetadataKeyError}) —
+* see that error and {@link readMetadataKeys} for why a type alone does not
+* close that hole.
 */
+function isDiscoveredRoutablePage(page) {
+	return page.type === "page";
+}
+function isErrorPageFile(file) {
+	return path.basename(file) === "error.page.tsx";
+}
+var DuplicateErrorPageError = class extends Error {
+	constructor(firstFile, secondFile) {
+		super(`Two error pages were found: "${firstFile}" and "${secondFile}". An application may own exactly one \`error.page.tsx\` anywhere beneath src/web.`);
+		this.name = "DuplicateErrorPageError";
+	}
+};
+var ErrorPageDeclaresRouteError = class extends Error {
+	constructor(pageFile) {
+		super(`The error page "${pageFile}" exports \`route\`. error.page.tsx is an error boundary, not a browsable page; remove the route export.`);
+		this.name = "ErrorPageDeclaresRouteError";
+	}
+};
 /** Raised when two pages claim one route name. */
 var DuplicatePageRouteNameError = class extends Error {
 	routeName;
@@ -56,6 +80,19 @@ var DuplicatePageRouteNameError = class extends Error {
 		this.name = "DuplicatePageRouteNameError";
 	}
 };
+/** Raised when two different page files resolve to one effective URL. */
+var DuplicatePageRoutePathError = class extends Error {
+	routePath;
+	firstFile;
+	secondFile;
+	constructor(routePath, firstFile, secondFile) {
+		super(`Two pages resolve to the same route path "${routePath}": "${firstFile}" and "${secondFile}". Each URL may identify exactly one page. Rename or move one file, or give one page an explicit route with a different path.`);
+		this.routePath = routePath;
+		this.firstFile = firstFile;
+		this.secondFile = secondFile;
+		this.name = "DuplicatePageRoutePathError";
+	}
+};
 function toPosix(value) {
 	return value.replace(/\\/g, "/");
 }
@@ -74,27 +111,18 @@ function isFile(candidate) {
 	}
 }
 /**
-* The two page roots: the global `src/web/**` tree and each
-* module's `src/app/<module>/web/**` tree. Both are optional; a project with
-* neither has zero pages, which is a legal empty state.
+* The page root. It is optional; a project without it has zero pages, which is
+* a legal empty state.
 */
 function discoverWebRoots(srcRoot) {
-	const roots = [];
-	const globalRoot = path.join(srcRoot, "web");
-	if (isDirectory(globalRoot)) roots.push(globalRoot);
-	const appDir = path.join(srcRoot, "app");
-	if (isDirectory(appDir)) for (const entry of fs.readdirSync(appDir, { withFileTypes: true }).sort(byName)) {
-		if (!entry.isDirectory()) continue;
-		const moduleWebRoot = path.join(appDir, entry.name, "web");
-		if (isDirectory(moduleWebRoot)) roots.push(moduleWebRoot);
-	}
-	return roots;
+	const webRoot = path.join(srcRoot, "web");
+	return isDirectory(webRoot) ? [webRoot] : [];
 }
 function byName(left, right) {
 	return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
 }
 /**
-* The subject list: every `*.page.tsx` under BOTH web roots, one call for the
+* The subject list: every `*.page.tsx` under the page root, one call for the
 * whole graph.
 *
 * Unlike {@link discoverPages}, this reads no `route` or `prefix` export and
@@ -179,26 +207,238 @@ function assertUniqueRouteNames(pages, appRoot) {
 		fileByRouteName.set(page.routeName, relative);
 	}
 }
-/** Raised when a `*.page.tsx` declares no `route` export. */
-var MissingRouteExportError = class extends Error {
+/**
+* A page's declared `route.path` is a choice its author made deliberately, so
+* two pages that both declare the same path are the author's call, not an
+* accident — {@link assertUniqueRouteNames} is what keeps each of them
+* reachable by name. What this refuses is a COLLISION NOBODY CHOSE: at least
+* one side's path is filesystem-derived, which is exactly the case a rename
+* or a new file can produce without anyone noticing two pages now answer the
+* same URL. The reserved not-found path (`"*"`) is never a candidate here
+* either way — it identifies no browsable URL, and {@link assertUniqueRouteNames}
+* already refuses a second `404.page.tsx` by its own reserved name.
+*/
+function assertUniqueRoutePaths(pages, appRoot, explicitFiles) {
+	const fileByRoutePath = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		if (page.routePath === "*") continue;
+		const existing = fileByRoutePath.get(page.routePath);
+		const relative = toPosix(path.relative(appRoot, page.pageFile));
+		if (existing !== void 0 && !(explicitFiles.has(existing) && explicitFiles.has(relative))) throw new DuplicatePageRoutePathError(page.routePath, existing, relative);
+		if (existing === void 0) fileByRoutePath.set(page.routePath, relative);
+	}
+}
+/**
+* Raised when a page's `metadata` export declares a key nothing reads.
+*
+* THE POINT OF THIS ERROR IS THE UNANNOTATED CASE. A page that writes
+* `export const metadata: PageMetadata = { tittle: "x" }` is already refused by
+* TypeScript, and if that were the whole story this class would not need to
+* exist. But the annotation is optional, nobody writes it, and
+* `export const metadata = { tittle: "x" }` is a perfectly well-typed program:
+* the compiler infers `{ tittle: string }`, has nothing to check it against, and
+* says nothing. The page is then served with no `<title>` — not a wrong title, a
+* missing one — and no error is raised anywhere, at build or at runtime, ever.
+*
+* So the check lives HERE instead, at the gate every page already passes
+* through: a page that silently omits requested metadata is worse than a build
+* that stops and says which line to fix.
+*
+* The alternative considered and rejected was a `defineMetadata({...})` wrapper,
+* which would infer the type for free. It also puts framework ceremony in every
+* page, and a page is meant to be two lines of framework surface (canon
+* `6ea0662f`). The gate gets the same safety without spending that.
+*/
+var UnknownMetadataKeyError = class extends Error {
 	pageFile;
-	constructor(pageFile) {
-		super(`"${pageFile}" is a page file but declares no \`route\` export. A page with no route is a page the dev server would still serve and production would 404 on, so the build refuses it instead. For example: export const route = "/list";`);
+	unknownKeys;
+	constructor(pageFile, unknownKeys) {
+		const findings = unknownKeys.map(({ container, key, line, suggestion }) => {
+			const where = `line ${line}: \`${container}.${key}\` — no such key.`;
+			return suggestion === void 0 ? where : `${where} Did you mean \`${suggestion}\`?`;
+		}).join("\n  ");
+		super(`The \`metadata\` export of "${pageFile}" declares a key nothing reads:\n  ${findings}\nNothing writes an unknown key to \`<head>\`, so the tag it was meant to produce would simply be absent from every response, with no error at build time or at runtime. The build refuses it here instead.
+  Known keys: ${METADATA_KEYS.join(", ")}.\n  Inside \`openGraph\`: ${OPEN_GRAPH_KEYS.join(", ")}.\n  Inside \`twitter\`: ${TWITTER_KEYS.join(", ")}.\nAnnotating the export — \`export const metadata: PageMetadata = { … }\` — gets you the same list as autocomplete in the editor, before the build runs.`);
 		this.pageFile = pageFile;
-		this.name = "MissingRouteExportError";
+		this.unknownKeys = unknownKeys;
+		this.name = "UnknownMetadataKeyError";
 	}
 };
+/** `as const`, `satisfies`, `!` and parentheses wrap a value without changing it. */
+function unwrapValue(node) {
+	switch (node.type) {
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TypeCastExpression":
+		case "ParenthesizedExpression": return unwrapValue(node.expression);
+		default: return node;
+	}
+}
+/** Levenshtein distance — small strings, so the plain two-row table is the whole cost. */
+function editDistance(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let row = 1; row <= left.length; row++) {
+		const current = [row];
+		for (let column = 1; column <= right.length; column++) {
+			const substitution = previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1);
+			current[column] = Math.min(substitution, previous[column] + 1, current[column - 1] + 1);
+		}
+		previous = current;
+	}
+	return previous[right.length];
+}
+/**
+* The known key the written one was probably meant to be.
+*
+* Two edits, because that covers the typos this exists for — `tittle`,
+* `descriptoin`, `keywrods` — without reaching so far that `image` gets
+* suggested for `alt`. Case is ignored first, so `Title` resolves exactly.
+*/
+function suggestKey(written, known) {
+	const lowered = written.toLowerCase();
+	const sameLetters = known.find((candidate) => candidate.toLowerCase() === lowered);
+	if (sameLetters !== void 0) return sameLetters;
+	let best;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const candidate of known) {
+		const distance = editDistance(lowered, candidate.toLowerCase());
+		if (distance < bestDistance) {
+			best = candidate;
+			bestDistance = distance;
+		}
+	}
+	return bestDistance <= 2 ? best : void 0;
+}
+/** The name an object key denotes, or `undefined` when knowing it needs evaluation. */
+function propertyKeyName(property) {
+	if (property.computed) return void 0;
+	const { key } = property;
+	if (key.type === "Identifier") return key.name;
+	if (key.type === "StringLiteral") return key.value;
+}
+/** The nested objects that carry a key set of their own. */
+const NESTED_METADATA_KEYS = {
+	openGraph: OPEN_GRAPH_KEYS,
+	twitter: TWITTER_KEYS
+};
+/**
+* Every unknown key in one metadata object literal, and in the `openGraph` /
+* `twitter` literals inside it.
+*
+* A SPREAD does not suppress the check, unlike the route reader's rule: a
+* spread can only ADD keys, and no value it contributes can make a key written
+* out beside it correct. A COMPUTED key is skipped — its name is not knowable
+* without running the page, and refusing what cannot be read would fail builds
+* that are fine. Both are silence in the narrow places where the parse genuinely
+* does not know, and the annotation is the second net there.
+*/
+function collectUnknownKeys(object, allowed, container, into) {
+	for (const property of object.properties) {
+		if (property.type === "SpreadElement") continue;
+		const key = propertyKeyName(property);
+		if (key === void 0) continue;
+		if (!allowed.includes(key)) {
+			const suggestion = suggestKey(key, allowed);
+			into.push({
+				container,
+				key,
+				line: property.loc?.start.line ?? 0,
+				...suggestion === void 0 ? {} : { suggestion }
+			});
+			continue;
+		}
+		const nested = container === "metadata" ? NESTED_METADATA_KEYS[key] : void 0;
+		if (nested === void 0 || property.type !== "ObjectProperty") continue;
+		const value = unwrapValue(property.value);
+		if (value.type === "ObjectExpression") collectUnknownKeys(value, nested, `${container}.${key}`, into);
+	}
+}
+/**
+* Every object literal a function form RETURNS, without descending into
+* functions nested inside it — a callback's return value is not the metadata.
+*
+* A generic walk rather than a statement-by-statement one because a `return` is
+* legal anywhere a statement is: inside an `if`, a `switch`, a `try`. Enumerating
+* the statement types that may contain one is a list that is wrong the moment
+* the language grows.
+*/
+function collectReturnedObjects(node, into) {
+	if (node === null || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (const item of node) collectReturnedObjects(item, into);
+		return;
+	}
+	const candidate = node;
+	if (candidate.type === "FunctionDeclaration" || candidate.type === "FunctionExpression" || candidate.type === "ArrowFunctionExpression" || candidate.type === "ObjectMethod" || candidate.type === "ClassMethod") return;
+	if (candidate.type === "ReturnStatement") {
+		if (candidate.argument === null || candidate.argument === void 0) return;
+		const returned = unwrapValue(candidate.argument);
+		if (returned.type === "ObjectExpression") into.push(returned);
+		return;
+	}
+	for (const value of Object.values(node)) collectReturnedObjects(value, into);
+}
+/** The metadata object literals one `metadata` export declares, if any can be seen at all. */
+function metadataObjectsOf(init) {
+	const value = unwrapValue(init);
+	if (value.type === "ObjectExpression") return [value];
+	if (value.type === "ArrowFunctionExpression" || value.type === "FunctionExpression") {
+		const body = unwrapValue(value.body);
+		if (body.type === "ObjectExpression") return [body];
+		const returned = [];
+		collectReturnedObjects(value.body, returned);
+		return returned;
+	}
+	return [];
+}
+/**
+* The unknown keys a page's `metadata` export declares, read by PARSING — the
+* same rule the rest of this module lives by, and the reason this check can run
+* before anything is built.
+*
+* Empty for a page with no `metadata` export, for one whose metadata is a value
+* this file cannot see into, and for a correct one.
+*/
+function readMetadataKeys(pageFile, source) {
+	let program;
+	try {
+		program = parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"],
+			errorRecovery: false
+		}).program;
+	} catch (error) {
+		throw new Error(`Cannot read the \`metadata\` export of "${pageFile}": the file could not be parsed (${error.message}). Fix the syntax error and the build will continue.`);
+	}
+	const unknownKeys = [];
+	for (const statement of program.body) {
+		if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
+		const { declaration } = statement;
+		if (declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of declaration.declarations) {
+			if (declarator.id.type !== "Identifier" || declarator.id.name !== "metadata") continue;
+			if (declarator.init === null || declarator.init === void 0) continue;
+			for (const object of metadataObjectsOf(declarator.init)) collectUnknownKeys(object, METADATA_KEYS, "metadata", unknownKeys);
+		}
+	}
+	return unknownKeys;
+}
 /**
 * The declared exports of one file, or a thrown
 * {@link NonLiteralRouteExportError} when they cannot be read without running
 * the application. Layouts are read once per run and remembered: a layout is
 * the nearest one for every page beside it, and parsing it once per page would
 * be the same answer bought repeatedly.
+*
+* `source` is the file's text when the caller already holds it — the page loop
+* reads each page once and spends that read on both the route declarations and
+* the metadata check, rather than opening the same file twice.
 */
-function readDeclarations(sourceFile, cache) {
+function readDeclarations(sourceFile, cache, source) {
 	let result = cache.get(sourceFile);
 	if (result === void 0) {
-		result = readRouteExports(sourceFile);
+		result = readRouteExports(sourceFile, source);
 		cache.set(sourceFile, result);
 	}
 	if (!result.ok) throw new NonLiteralRouteExportError(result.rejection);
@@ -254,17 +494,18 @@ function readLayoutShape(layoutFile, cache) {
 	return shape;
 }
 /**
-* Scans both web roots and returns the pages in a defined total order.
+* Scans the page root and returns the pages in a defined total order.
 *
 * Zero pages is a legal result, not an error: a project may be configured
 * with web and have nothing to serve yet. What is an error is a `*.page.tsx`
-* with no `route` export, which is refused rather than silently omitted — an
-* artefact that leaves a page out is a page the dev server still serves and
-* production 404s on; two pages claiming one route name, which this refuses
+* with a route or metadata export that cannot be read statically; two pages
+* claiming one effective path or route name, which this refuses
 * to return at all — the alternative is an artefact in which one of them is
 * silently unreachable; a `route` or `prefix` that cannot be read without
 * running the application, which is refused before any page is reported at
-* all; and a page whose layout chain holds more than one RENDERING layout, which
+* all; a `metadata` export declaring a key nothing reads, which no compiler
+* catches unless the page opted into the type and which otherwise serves a page
+* with a silently missing tag; and a page whose layout chain holds more than one RENDERING layout, which
 * the production installer would refuse anyway — discovery refuses it first so
 * that artefact is never produced.
 */
@@ -278,9 +519,27 @@ function discoverPages(options) {
 	const layoutShapes = /* @__PURE__ */ new Map();
 	const relativeToApp = (file) => toPosix(path.relative(appRoot, file));
 	const pages = [];
+	const explicitRouteFiles = /* @__PURE__ */ new Set();
+	let errorPage;
 	for (const webRoot of webRoots) for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(".page.tsx"))) {
-		const { route } = readDeclarations(pageFile, declarations);
-		if (route === void 0) throw new MissingRouteExportError(relativeToApp(pageFile));
+		const pageSource = fs.readFileSync(pageFile, "utf-8");
+		assertPageHasDefaultExport(relativeToApp(pageFile), pageSource);
+		const { route } = readDeclarations(pageFile, declarations, pageSource);
+		if (isErrorPageFile(pageFile)) {
+			if (route !== void 0) throw new ErrorPageDeclaresRouteError(relativeToApp(pageFile));
+			if (errorPage !== void 0) throw new DuplicateErrorPageError(relativeToApp(errorPage.pageFile), relativeToApp(pageFile));
+			errorPage = {
+				type: "error",
+				pageFile,
+				webRoot,
+				...hasAppFile ? { appFile } : {}
+			};
+			continue;
+		}
+		const isNotFoundPage = isNotFoundPageFile(pageFile);
+		if (isNotFoundPage && route !== void 0) throw new NotFoundPageDeclaresRouteError(relativeToApp(pageFile));
+		const unknownMetadataKeys = readMetadataKeys(relativeToApp(pageFile), pageSource);
+		if (unknownMetadataKeys.length > 0) throw new UnknownMetadataKeyError(relativeToApp(pageFile), unknownMetadataKeys);
 		const layouts = layoutChainFor(pageFile, webRoot);
 		const shapes = layouts.map((layoutFile) => readLayoutShape(layoutFile, layoutShapes));
 		const selection = selectPageLayout(layouts.map((layout, index) => ({
@@ -290,24 +549,39 @@ function discoverPages(options) {
 		if (selection.type === "rejected") throw new NestedLayoutsNotSupportedError(relativeToApp(pageFile), selection.layouts.map(relativeToApp));
 		const middlewareLayouts = layouts.filter((_, index) => shapes[index].hasMiddleware);
 		const layoutPrefix = layouts.reduce((composed, layoutFile) => composeRoutePath(composed, readDeclarations(layoutFile, declarations).prefix ?? "/"), "/");
+		const relativePageFile = toPosix(path.relative(webRoot, pageFile));
+		const layoutPrefixes = Object.fromEntries(layouts.flatMap((layoutFile) => {
+			const prefix = readDeclarations(layoutFile, declarations).prefix;
+			if (prefix === void 0) return [];
+			return [[toPosix(path.relative(webRoot, path.dirname(layoutFile))), prefix]];
+		}));
+		const effectiveRoutePath = isNotFoundPage ? "*" : route ? composeRoutePath(layoutPrefix, route.path) : deriveFilesystemRoutePath({
+			pageFile: relativePageFile,
+			layoutPrefixes
+		});
+		if (!isNotFoundPage && route !== void 0) explicitRouteFiles.add(relativeToApp(pageFile));
 		pages.push({
-			routeName: route.name ?? deriveFallbackRouteName({
+			type: "page",
+			routeName: isNotFoundPage ? NOT_FOUND_ROUTE_NAME : route?.name ?? (route ? deriveFallbackRouteName({
 				routePath: route.path,
 				sourceFile: relativeToApp(pageFile)
-			}),
-			routePath: composeRoutePath(layoutPrefix, route.path),
+			}) : deriveFilesystemRouteName(relativePageFile)),
+			routePath: effectiveRoutePath,
 			pageFile,
 			webRoot,
-			layouts,
-			middlewareLayouts,
+			layouts: isNotFoundPage ? [] : layouts,
+			middlewareLayouts: isNotFoundPage ? [] : middlewareLayouts,
 			...hasAppFile ? { appFile } : {}
 		});
 	}
+	if (errorPage !== void 0) pages.push(errorPage);
 	pages.sort(comparePages);
-	assertUniqueRouteNames(pages, appRoot);
+	const routablePages = pages.filter(isDiscoveredRoutablePage);
+	assertUniqueRoutePaths(routablePages, appRoot, explicitRouteFiles);
+	assertUniqueRouteNames(routablePages, appRoot);
 	return pages;
 }
 
 //#endregion
-export { DuplicatePageRouteNameError, discoverPageFiles, discoverPages, discoverWebRoots, isFile, layoutChainFor, toPosix, walkFiles };
+export { DuplicatePageRouteNameError, ErrorPageDeclaresRouteError, discoverPageFiles, discoverPages, discoverWebRoots, isDiscoveredRoutablePage, isErrorPageFile, isFile, layoutChainFor, toPosix, walkFiles };
 //# sourceMappingURL=discover-pages.mjs.map