@warlock.js/web 5.0.0

package/esm/build/generate-pages-barrel.mjs

@@ -0,0 +1,330 @@
+import { NestedLayoutsNotSupportedError } from "../routing/layout-policy.mjs";
+import { DuplicatePageRouteNameError, discoverPages, discoverWebRoots, isFile, layoutChainFor, toPosix, walkFiles } from "./discover-pages.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "@babel/parser";
+
+//#region ../web/src/build/generate-pages-barrel.ts
+/**
+* The server half of the build→runtime handoff: the generated
+* `<productionDir>/pages.ts` barrel that carries the page graph into the
+* server bundle.
+*
+* The graph itself comes from `discover-pages.ts`, the one scan every provider
+* shares — this module is the BARREL provider and nothing more. It takes the
+* recipe, runs the Vite-switch tripwire over the sources the recipe came from,
+* and writes the file.
+*
+* "Static" means the FILESYSTEM ONLY — discovery globs `*.page.tsx`,
+* `layout.tsx` and `root.tsx` and never imports a single application module,
+* mirroring how the builder already globs (`production-builder.ts:184-242`).
+* The imports happen at BOOT, when the compiled barrel runs, which is what
+* makes a page that throws on import a loud pre-listen failure in production.
+*
+* This is the HEAVY half of the contribution: `contribution.ts` reaches it by
+* dynamic import inside its `generate` hook, so nothing here lands in a
+* connector's static graph.
+*/
+/**
+* Declared BEFORE the patch that reads it. `const` is hoisted but sits in the
+* temporal dead zone, and the patch below is an object literal evaluated at
+* module load — reading this from further down the file would throw.
+*/
+const STYLE_EXTENSIONS = [
+	".css",
+	".scss",
+	".sass",
+	".less",
+	".styl"
+];
+/**
+* The esbuild patch web contributes (spike-settled, contract §3a).
+*
+* NO `process.env.NODE_ENV` define: warlock assigns to `process.env.NODE_ENV`
+* at runtime (`core/src/utils/environment.ts:14`) and a define would turn that
+* assignment into an assignment to a literal.
+*/
+const WEB_ESBUILD_PATCH = {
+	jsx: "automatic",
+	jsxImportSource: "react",
+	define: {
+		"import.meta.env.DEV": "false",
+		"import.meta.env.PROD": "true",
+		"import.meta.env.SSR": "true",
+		"import.meta.env.MODE": "\"production\""
+	},
+	/**
+	* Stylesheets compile to NOTHING in the server bundle, rather than failing it.
+	*
+	* `root.tsx` importing `./app.css` is how Tailwind — and every other CSS
+	* pipeline — is normally wired, so rejecting it meant the framework could not
+	* build a styled application at all. But the server has no use for the bytes:
+	* it renders HTML, and all it ever needs of a stylesheet is a URL to put in a
+	* `<link>`. The CSS itself belongs to the CLIENT bundle, which Vite builds
+	* from the same `root.tsx` and which handles CSS natively.
+	*
+	* So the import stays in the user's source, the server drops it, and Vite
+	* emits the real asset. Nothing is silently lost: a stylesheet that does not
+	* exist still fails the client build, loudly, where it matters.
+	*/
+	loader: Object.fromEntries(STYLE_EXTENSIONS.map((extension) => [extension, "empty"]))
+};
+/** Line appended to section 4 of the generated production entry, after `./routes`. */
+const WEB_ENTRY_IMPORT = "await import(\"./pages\");";
+const REMEDY = "remove the import from this file (move it into a client-only module, or reference the asset by URL instead), or wait for the Vite-based server build, which is the only build that can compile imports like this one";
+const ASSET_EXTENSIONS = [
+	".svg",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".avif",
+	".ico",
+	".woff",
+	".woff2",
+	".ttf",
+	".eot",
+	".mp4",
+	".webm"
+];
+/** Raised by the Vite-switch tripwire. */
+var WebPageGraphUnsupportedImportError = class extends Error {
+	sourceFile;
+	specifier;
+	constructor(sourceFile, specifier, reason) {
+		super(`Cannot build the page graph: "${sourceFile}" ${reason} (${specifier}). Pages are compiled into the server bundle, which supports plain code imports only — static assets, \`?raw\`/\`?url\` queries and \`import.meta.url\` are not supported there. (Stylesheets ARE supported: the server bundle drops them and the client bundle emits them.) To fix: ${REMEDY}.`);
+		this.sourceFile = sourceFile;
+		this.specifier = specifier;
+		this.name = "WebPageGraphUnsupportedImportError";
+	}
+};
+const FROM_SPECIFIER = /\bfrom\s*["']([^"']+)["']/g;
+const BARE_IMPORT = /\bimport\s*["']([^"']+)["']/g;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+/**
+* Blank every comment, preserving byte offsets.
+*
+* The scan below is regex over source text, so without this a specifier written
+* inside a comment is indistinguishable from a real import. That is not
+* hypothetical: documenting this very restriction — writing `import "./app.css"`
+* in a doc comment to explain why it is unsupported — failed the build, and the
+* error then insisted the file imported a stylesheet that it did not import.
+* Removing the real import did not help, because the comment was the match.
+*
+* Comments are replaced with spaces rather than deleted so every subsequent
+* offset, and therefore every line number in anything reported from here,
+* stays exactly where it was.
+*
+* A parse failure is deliberately NOT fatal: this function's job is to find
+* hazards, not to validate syntax. esbuild reports a genuine syntax error far
+* better than we would, and failing here would replace its clear message with a
+* worse one. On a parse failure the raw source is scanned — the pre-existing
+* behaviour, false positives and all.
+*/
+function withoutComments(source) {
+	try {
+		const ast = parse(source, {
+			sourceType: "module",
+			errorRecovery: true,
+			plugins: [
+				"typescript",
+				"jsx",
+				"decorators-legacy"
+			]
+		});
+		let stripped = source;
+		for (const comment of ast.comments ?? []) {
+			const { start, end } = comment;
+			stripped = stripped.slice(0, start) + " ".repeat(end - start) + stripped.slice(end);
+		}
+		return stripped;
+	} catch {
+		return source;
+	}
+}
+/** Expects source whose comments have already been blanked by {@link withoutComments}. */
+function collectSpecifiers(source) {
+	const specifiers = [];
+	for (const pattern of [
+		FROM_SPECIFIER,
+		BARE_IMPORT,
+		DYNAMIC_IMPORT
+	]) {
+		pattern.lastIndex = 0;
+		let match = pattern.exec(source);
+		while (match !== null) {
+			specifiers.push(match[1]);
+			match = pattern.exec(source);
+		}
+	}
+	return specifiers;
+}
+function hazardFor(specifier) {
+	const [base, query] = specifier.split("?", 2);
+	const lowered = base.toLowerCase();
+	if (ASSET_EXTENSIONS.some((extension) => lowered.endsWith(extension))) return "imports a static asset";
+	if (query !== void 0 && /(^|&)(raw|url)(&|=|$)/.test(query)) return "uses a bundler-specific import query";
+}
+/**
+* The Vite-switch tripwire. Fails the build
+* the moment the page graph needs a capability the esbuild server build does
+* not have, naming the file, the specifier and the remedy.
+*
+* LIMITATIONS, stated on purpose — BOTH directions, because stating only one
+* is what made the other one expensive to find:
+*
+* FALSE NEGATIVES. This is a FILE-LEVEL scan of the `.ts`/`.tsx` sources under
+* the discovered web roots — it is not transitive resolution. A page that
+* imports a workspace package which itself imports CSS is not caught here; that
+* failure surfaces at esbuild time instead.
+*
+* FALSE POSITIVES. The scan is regex over source text, so anything that LOOKS
+* like a specifier counts. Comments are blanked first ({@link withoutComments})
+* because a documented example used to fail the build while insisting on an
+* import that was not there. String and template literals are NOT blanked —
+* they cannot be, since real specifiers are string literals — so a specifier
+* inside a template literal (a code sample in a docs page, say) still matches.
+* Rare, and it fails loudly rather than silently, but it is not impossible.
+*/
+function assertNoViteOnlyImports(webRoots, appRoot) {
+	for (const webRoot of webRoots) {
+		const sources = walkFiles(webRoot, (fileName) => fileName.endsWith(".ts") || fileName.endsWith(".tsx"));
+		for (const sourceFile of sources) {
+			const source = withoutComments(fs.readFileSync(sourceFile, "utf-8"));
+			const relative = toPosix(path.relative(appRoot, sourceFile));
+			for (const specifier of collectSpecifiers(source)) {
+				const reason = hazardFor(specifier);
+				if (reason !== void 0) throw new WebPageGraphUnsupportedImportError(relative, specifier, reason);
+			}
+			if (source.includes("import.meta.url")) throw new WebPageGraphUnsupportedImportError(relative, "import.meta.url", "uses `import.meta.url`, whose meaning changes under the bundled server build");
+		}
+	}
+}
+/** `<productionDir>` -> `<file>` as an extensionless, POSIX, relative specifier. */
+function importSpecifierFor(productionDir, file) {
+	const relative = toPosix(path.relative(productionDir, file)).replace(/\.tsx?$/, "");
+	return relative.startsWith(".") ? relative : `./${relative}`;
+}
+function quote(value) {
+	return JSON.stringify(value);
+}
+/** Header of every generated barrel — the banner plus the one runtime import. */
+const BARREL_HEADER = [
+	"// AUTO-GENERATED by @warlock.js/web — do not edit.",
+	"// The page graph, compiled into the server bundle.",
+	"// Route paths are deliberately absent: they are read off each module at boot.",
+	"import { providePageManifest } from \"@warlock.js/web/connector\";"
+];
+/**
+* The barrel written when discovery found no pages at all.
+*
+* No app entry: `root.tsx` is the root every PAGE renders inside, so with zero
+* pages there is nothing for it to wrap and requiring it would fail builds that
+* are legitimately page-free.
+*/
+const EMPTY_BARREL_CONTENTS = [
+	...BARREL_HEADER,
+	"",
+	"// Zero pages were discovered. The empty table is still provided, because that",
+	"// is what tells the boot-time reader \"this bundle WAS built with web, it just",
+	"// has no pages\" — as opposed to a bundle built without web at all, where no",
+	"// barrel runs and the manifest stays absent.",
+	"providePageManifest({ pages: [] });",
+	""
+].join("\n");
+async function writeBarrel(productionDir, contents) {
+	const barrelFile = path.join(productionDir, "pages.ts");
+	await fs.promises.mkdir(productionDir, { recursive: true });
+	await fs.promises.writeFile(barrelFile, contents, "utf-8");
+	return barrelFile;
+}
+/**
+* Discovers the page graph, runs the tripwire, and writes
+* `<productionDir>/pages.ts`.
+*
+* Zero pages is NOT an error, and it is NOT silence either: the barrel is
+* written anyway carrying an empty table, so "configured with web, no pages"
+* reaches the runtime as a fact instead of looking identical to "never built
+* with web". The run also says so out loud (no silent caps). What the caller
+* skips on zero pages is the CLIENT bundle — no pages means nothing to
+* hydrate.
+*/
+async function generatePagesBarrel(options) {
+	const { appRoot, productionDir, clientDir } = options;
+	const srcRoot = path.join(appRoot, options.srcDir ?? "src");
+	const webRoots = discoverWebRoots(srcRoot);
+	const discovered = discoverPages({
+		appRoot,
+		srcDir: options.srcDir
+	});
+	if (discovered.length === 0) {
+		console.log("web configured, 0 pages");
+		return {
+			pageCount: 0,
+			barrelFile: await writeBarrel(productionDir, EMPTY_BARREL_CONTENTS),
+			contents: EMPTY_BARREL_CONTENTS
+		};
+	}
+	assertNoViteOnlyImports(webRoots, appRoot);
+	const appFile = path.join(srcRoot, "web", "root.tsx");
+	if (!isFile(appFile)) throw new Error(`Cannot generate the page barrel: ${discovered.length} page(s) were discovered but the application root component "${toPosix(path.relative(appRoot, appFile))}" does not exist. Every page renders inside it.`);
+	const layoutIdentifiers = /* @__PURE__ */ new Map();
+	const pages = [];
+	for (const [index, page] of discovered.entries()) {
+		const layouts = page.layouts.map((layoutFile) => {
+			let identifier = layoutIdentifiers.get(layoutFile);
+			if (identifier === void 0) {
+				identifier = `l${layoutIdentifiers.size}`;
+				layoutIdentifiers.set(layoutFile, identifier);
+			}
+			return {
+				identifier,
+				sourceFile: layoutFile
+			};
+		});
+		pages.push({
+			identifier: `p${index}`,
+			sourceFile: page.pageFile,
+			layouts
+		});
+	}
+	const importLines = [
+		`import * as app from ${quote(importSpecifierFor(productionDir, appFile))};`,
+		...[...layoutIdentifiers.entries()].map(([layoutFile, identifier]) => `import * as ${identifier} from ${quote(importSpecifierFor(productionDir, layoutFile))};`),
+		...pages.map((page) => `import * as ${page.identifier} from ${quote(importSpecifierFor(productionDir, page.sourceFile))};`)
+	];
+	const relativeToApp = (file) => quote(toPosix(path.relative(appRoot, file)));
+	const pageEntries = pages.map((page) => {
+		const layouts = page.layouts.map((layout) => `{ module: ${layout.identifier}, sourceFile: ${relativeToApp(layout.sourceFile)} }`).join(", ");
+		return [
+			"  {",
+			`    module: ${page.identifier},`,
+			`    sourceFile: ${relativeToApp(page.sourceFile)},`,
+			`    layouts: [${layouts}],`,
+			"  },"
+		].join("\n");
+	});
+	const contents = [
+		...BARREL_HEADER,
+		...importLines,
+		"",
+		"providePageManifest({",
+		`  clientDir: ${quote(clientDir)},`,
+		`  app: { module: app, sourceFile: ${relativeToApp(appFile)} },`,
+		"  pages: [",
+		...pageEntries.map((entry) => entry.split("\n").map((line) => `  ${line}`).join("\n")),
+		"  ],",
+		"});",
+		""
+	].join("\n");
+	return {
+		pageCount: pages.length,
+		barrelFile: await writeBarrel(productionDir, contents),
+		contents
+	};
+}
+
+//#endregion
+export { WEB_ENTRY_IMPORT, WEB_ESBUILD_PATCH, generatePagesBarrel };
+//# sourceMappingURL=generate-pages-barrel.mjs.map

package/esm/build/generate-pages-barrel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-pages-barrel.mjs","names":[],"sources":["../../../../../../../web/src/build/generate-pages-barrel.ts"],"sourcesContent":["/**\n * The server half of the build→runtime handoff: the generated\n * `<productionDir>/pages.ts` barrel that carries the page graph into the\n * server bundle.\n *\n * The graph itself comes from `discover-pages.ts`, the one scan every provider\n * shares — this module is the BARREL provider and nothing more. It takes the\n * recipe, runs the Vite-switch tripwire over the sources the recipe came from,\n * and writes the file.\n *\n * \"Static\" means the FILESYSTEM ONLY — discovery globs `*.page.tsx`,\n * `layout.tsx` and `root.tsx` and never imports a single application module,\n * mirroring how the builder already globs (`production-builder.ts:184-242`).\n * The imports happen at BOOT, when the compiled barrel runs, which is what\n * makes a page that throws on import a loud pre-listen failure in production.\n *\n * This is the HEAVY half of the contribution: `contribution.ts` reaches it by\n * dynamic import inside its `generate` hook, so nothing here lands in a\n * connector's static graph.\n */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { parse } from \"@babel/parser\";\nimport type { ConnectorEsbuildPatch } from \"@warlock.js/core\";\nimport { discoverPages, discoverWebRoots, isFile, toPosix, walkFiles } from \"./discover-pages\";\n\n// Re-exported, not redefined: discovery's helpers were this module's before the\n// split, and the callers that already reach for them here should keep getting\n// the one implementation rather than a copy that can drift from it. The nested\n// layout error re-exports from the layout policy module, the one place that\n// owns layout selection and its error contract.\nexport {\n  discoverPages,\n  discoverWebRoots,\n  DuplicatePageRouteNameError,\n  layoutChainFor,\n} from \"./discover-pages\";\nexport { NestedLayoutsNotSupportedError } from \"../routing/layout-policy\";\nexport type { DiscoveredPage, DiscoverPagesOptions } from \"./discover-pages\";\n\n/**\n * Declared BEFORE the patch that reads it. `const` is hoisted but sits in the\n * temporal dead zone, and the patch below is an object literal evaluated at\n * module load — reading this from further down the file would throw.\n */\nconst STYLE_EXTENSIONS = [\".css\", \".scss\", \".sass\", \".less\", \".styl\"];\n\n/**\n * The esbuild patch web contributes (spike-settled, contract §3a).\n *\n * NO `process.env.NODE_ENV` define: warlock assigns to `process.env.NODE_ENV`\n * at runtime (`core/src/utils/environment.ts:14`) and a define would turn that\n * assignment into an assignment to a literal.\n */\nexport const WEB_ESBUILD_PATCH: ConnectorEsbuildPatch = {\n  jsx: \"automatic\",\n  jsxImportSource: \"react\",\n  define: {\n    \"import.meta.env.DEV\": \"false\",\n    \"import.meta.env.PROD\": \"true\",\n    \"import.meta.env.SSR\": \"true\",\n    \"import.meta.env.MODE\": '\"production\"',\n  },\n  /**\n   * Stylesheets compile to NOTHING in the server bundle, rather than failing it.\n   *\n   * `root.tsx` importing `./app.css` is how Tailwind — and every other CSS\n   * pipeline — is normally wired, so rejecting it meant the framework could not\n   * build a styled application at all. But the server has no use for the bytes:\n   * it renders HTML, and all it ever needs of a stylesheet is a URL to put in a\n   * `<link>`. The CSS itself belongs to the CLIENT bundle, which Vite builds\n   * from the same `root.tsx` and which handles CSS natively.\n   *\n   * So the import stays in the user's source, the server drops it, and Vite\n   * emits the real asset. Nothing is silently lost: a stylesheet that does not\n   * exist still fails the client build, loudly, where it matters.\n   */\n  loader: Object.fromEntries(\n    STYLE_EXTENSIONS.map((extension) => [extension, \"empty\" as const]),\n  ) as ConnectorEsbuildPatch[\"loader\"],\n};\n\n/** Line appended to section 4 of the generated production entry, after `./routes`. */\nexport const WEB_ENTRY_IMPORT = 'await import(\"./pages\");';\n\nconst REMEDY =\n  \"remove the import from this file (move it into a client-only module, or \" +\n  \"reference the asset by URL instead), or wait for the Vite-based server \" +\n  \"build, which is the only build that can compile imports like this one\";\n\nconst ASSET_EXTENSIONS = [\n  \".svg\",\n  \".png\",\n  \".jpg\",\n  \".jpeg\",\n  \".gif\",\n  \".webp\",\n  \".avif\",\n  \".ico\",\n  \".woff\",\n  \".woff2\",\n  \".ttf\",\n  \".eot\",\n  \".mp4\",\n  \".webm\",\n];\n\nexport type GeneratePagesBarrelOptions = {\n  /** Absolute path to the application root (where `package.json` lives). */\n  appRoot: string;\n  /** Absolute path to `.warlock/production` — where the barrel is written. */\n  productionDir: string;\n  /** Source directory name under `appRoot`; defaults to `\"src\"`. */\n  srcDir?: string;\n  /**\n   * App-root-relative POSIX path of the client bundle directory\n   * (`\"dist/client\"`), baked into the manifest for the runtime to read back.\n   * See `PageManifest.clientDir` for why it cannot be derived at boot.\n   *\n   * The CALLER resolves it, from the same `context.options.outdir` the client\n   * build itself writes to, so the two cannot name different directories.\n   */\n  clientDir: string;\n};\n\nexport type GeneratePagesBarrelResult = {\n  /** How many `*.page.tsx` files discovery found across both web roots. */\n  pageCount: number;\n  /** Absolute path of the written barrel. Always written when this runs at all. */\n  barrelFile: string;\n  /** The written barrel source. */\n  contents: string;\n};\n\n/** Raised by the Vite-switch tripwire. */\nexport class WebPageGraphUnsupportedImportError extends Error {\n  public constructor(\n    public readonly sourceFile: string,\n    public readonly specifier: string,\n    reason: string,\n  ) {\n    super(\n      `Cannot build the page graph: \"${sourceFile}\" ${reason} (${specifier}). ` +\n        \"Pages are compiled into the server bundle, which supports plain code imports only — \" +\n        \"static assets, `?raw`/`?url` queries and `import.meta.url` are not supported there. \" +\n        \"(Stylesheets ARE supported: the server bundle drops them and the client bundle emits them.) \" +\n        `To fix: ${REMEDY}.`,\n    );\n    this.name = \"WebPageGraphUnsupportedImportError\";\n  }\n}\n\nconst FROM_SPECIFIER = /\\bfrom\\s*[\"']([^\"']+)[\"']/g;\nconst BARE_IMPORT = /\\bimport\\s*[\"']([^\"']+)[\"']/g;\nconst DYNAMIC_IMPORT = /\\bimport\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)/g;\n\n/**\n * Blank every comment, preserving byte offsets.\n *\n * The scan below is regex over source text, so without this a specifier written\n * inside a comment is indistinguishable from a real import. That is not\n * hypothetical: documenting this very restriction — writing `import \"./app.css\"`\n * in a doc comment to explain why it is unsupported — failed the build, and the\n * error then insisted the file imported a stylesheet that it did not import.\n * Removing the real import did not help, because the comment was the match.\n *\n * Comments are replaced with spaces rather than deleted so every subsequent\n * offset, and therefore every line number in anything reported from here,\n * stays exactly where it was.\n *\n * A parse failure is deliberately NOT fatal: this function's job is to find\n * hazards, not to validate syntax. esbuild reports a genuine syntax error far\n * better than we would, and failing here would replace its clear message with a\n * worse one. On a parse failure the raw source is scanned — the pre-existing\n * behaviour, false positives and all.\n */\nfunction withoutComments(source: string): string {\n  try {\n    const ast = parse(source, {\n      sourceType: \"module\",\n      errorRecovery: true,\n      plugins: [\"typescript\", \"jsx\", \"decorators-legacy\"],\n    });\n\n    let stripped = source;\n\n    for (const comment of ast.comments ?? []) {\n      const { start, end } = comment as { start: number; end: number };\n\n      stripped =\n        stripped.slice(0, start) + \" \".repeat(end - start) + stripped.slice(end);\n    }\n\n    return stripped;\n  } catch {\n    return source;\n  }\n}\n\n/** Expects source whose comments have already been blanked by {@link withoutComments}. */\nfunction collectSpecifiers(source: string): string[] {\n  const specifiers: string[] = [];\n\n  for (const pattern of [FROM_SPECIFIER, BARE_IMPORT, DYNAMIC_IMPORT]) {\n    pattern.lastIndex = 0;\n\n    let match = pattern.exec(source);\n\n    while (match !== null) {\n      specifiers.push(match[1]);\n      match = pattern.exec(source);\n    }\n  }\n\n  return specifiers;\n}\n\nfunction hazardFor(specifier: string): string | undefined {\n  const [base, query] = specifier.split(\"?\", 2);\n  const lowered = base.toLowerCase();\n\n  /*\n    STYLESHEETS ARE NOT A HAZARD — see `loader` in WEB_ESBUILD_PATCH above.\n\n    They used to be rejected here, which meant `import \"./app.css\"` in\n    `root.tsx` — the ordinary way to wire Tailwind or any other CSS pipeline —\n    failed the build outright. The server bundle now compiles them to nothing,\n    because the server only ever needs a stylesheet's URL, and the client bundle\n    that Vite builds from the same sources emits the real asset.\n\n    STYLE_EXTENSIONS is still the single list both halves read from, so the set\n    esbuild stubs and the set this check tolerates cannot drift apart.\n  */\n\n  if (ASSET_EXTENSIONS.some((extension) => lowered.endsWith(extension))) {\n    return \"imports a static asset\";\n  }\n\n  if (query !== undefined && /(^|&)(raw|url)(&|=|$)/.test(query)) {\n    return \"uses a bundler-specific import query\";\n  }\n\n  return undefined;\n}\n\n/**\n * The Vite-switch tripwire. Fails the build\n * the moment the page graph needs a capability the esbuild server build does\n * not have, naming the file, the specifier and the remedy.\n *\n * LIMITATIONS, stated on purpose — BOTH directions, because stating only one\n * is what made the other one expensive to find:\n *\n * FALSE NEGATIVES. This is a FILE-LEVEL scan of the `.ts`/`.tsx` sources under\n * the discovered web roots — it is not transitive resolution. A page that\n * imports a workspace package which itself imports CSS is not caught here; that\n * failure surfaces at esbuild time instead.\n *\n * FALSE POSITIVES. The scan is regex over source text, so anything that LOOKS\n * like a specifier counts. Comments are blanked first ({@link withoutComments})\n * because a documented example used to fail the build while insisting on an\n * import that was not there. String and template literals are NOT blanked —\n * they cannot be, since real specifiers are string literals — so a specifier\n * inside a template literal (a code sample in a docs page, say) still matches.\n * Rare, and it fails loudly rather than silently, but it is not impossible.\n */\nexport function assertNoViteOnlyImports(webRoots: readonly string[], appRoot: string): void {\n  for (const webRoot of webRoots) {\n    const sources = walkFiles(\n      webRoot,\n      (fileName) => fileName.endsWith(\".ts\") || fileName.endsWith(\".tsx\"),\n    );\n\n    for (const sourceFile of sources) {\n      // Comments stripped ONCE, and reused by both checks below: `import.meta.url`\n      // was as blind to comments as the specifier scan was, and mentioning it in\n      // prose — as this very file does — would have failed the build.\n      const source = withoutComments(fs.readFileSync(sourceFile, \"utf-8\"));\n      const relative = toPosix(path.relative(appRoot, sourceFile));\n\n      for (const specifier of collectSpecifiers(source)) {\n        const reason = hazardFor(specifier);\n\n        if (reason !== undefined) {\n          throw new WebPageGraphUnsupportedImportError(relative, specifier, reason);\n        }\n      }\n\n      if (source.includes(\"import.meta.url\")) {\n        throw new WebPageGraphUnsupportedImportError(\n          relative,\n          \"import.meta.url\",\n          \"uses `import.meta.url`, whose meaning changes under the bundled server build\",\n        );\n      }\n    }\n  }\n}\n\n/** `<productionDir>` -> `<file>` as an extensionless, POSIX, relative specifier. */\nfunction importSpecifierFor(productionDir: string, file: string): string {\n  const relative = toPosix(path.relative(productionDir, file)).replace(/\\.tsx?$/, \"\");\n\n  return relative.startsWith(\".\") ? relative : `./${relative}`;\n}\n\nfunction quote(value: string): string {\n  return JSON.stringify(value);\n}\n\ninterface BarrelPage {\n  identifier: string;\n  sourceFile: string;\n  layouts: { identifier: string; sourceFile: string }[];\n}\n\n/** Header of every generated barrel — the banner plus the one runtime import. */\nconst BARREL_HEADER = [\n  \"// AUTO-GENERATED by @warlock.js/web — do not edit.\",\n  \"// The page graph, compiled into the server bundle.\",\n  \"// Route paths are deliberately absent: they are read off each module at boot.\",\n  // The CONNECTOR subpath, never the root barrel: this file is compiled into\n  // the server bundle, and `\"@warlock.js/web\"` would drag React in with it.\n  'import { providePageManifest } from \"@warlock.js/web/connector\";',\n];\n\n/**\n * The barrel written when discovery found no pages at all.\n *\n * No app entry: `root.tsx` is the root every PAGE renders inside, so with zero\n * pages there is nothing for it to wrap and requiring it would fail builds that\n * are legitimately page-free.\n */\nconst EMPTY_BARREL_CONTENTS = [\n  ...BARREL_HEADER,\n  \"\",\n  \"// Zero pages were discovered. The empty table is still provided, because that\",\n  \"// is what tells the boot-time reader \\\"this bundle WAS built with web, it just\",\n  '// has no pages\" — as opposed to a bundle built without web at all, where no',\n  \"// barrel runs and the manifest stays absent.\",\n  \"providePageManifest({ pages: [] });\",\n  \"\",\n].join(\"\\n\");\n\nasync function writeBarrel(productionDir: string, contents: string): Promise<string> {\n  const barrelFile = path.join(productionDir, \"pages.ts\");\n\n  await fs.promises.mkdir(productionDir, { recursive: true });\n  await fs.promises.writeFile(barrelFile, contents, \"utf-8\");\n\n  return barrelFile;\n}\n\n/**\n * Discovers the page graph, runs the tripwire, and writes\n * `<productionDir>/pages.ts`.\n *\n * Zero pages is NOT an error, and it is NOT silence either: the barrel is\n * written anyway carrying an empty table, so \"configured with web, no pages\"\n * reaches the runtime as a fact instead of looking identical to \"never built\n * with web\". The run also says so out loud (no silent caps). What the caller\n * skips on zero pages is the CLIENT bundle — no pages means nothing to\n * hydrate.\n */\nexport async function generatePagesBarrel(\n  options: GeneratePagesBarrelOptions,\n): Promise<GeneratePagesBarrelResult> {\n  const { appRoot, productionDir, clientDir } = options;\n  const srcRoot = path.join(appRoot, options.srcDir ?? \"src\");\n  const webRoots = discoverWebRoots(srcRoot);\n  const discovered = discoverPages({ appRoot, srcDir: options.srcDir });\n\n  if (discovered.length === 0) {\n    console.log(\"web configured, 0 pages\");\n\n    return {\n      pageCount: 0,\n      barrelFile: await writeBarrel(productionDir, EMPTY_BARREL_CONTENTS),\n      contents: EMPTY_BARREL_CONTENTS,\n    };\n  }\n\n  assertNoViteOnlyImports(webRoots, appRoot);\n\n  const appFile = path.join(srcRoot, \"web\", \"root.tsx\");\n\n  if (!isFile(appFile)) {\n    throw new Error(\n      `Cannot generate the page barrel: ${discovered.length} page(s) were discovered but the application root ` +\n        `component \"${toPosix(path.relative(appRoot, appFile))}\" does not exist. Every page renders inside it.`,\n    );\n  }\n\n  const layoutIdentifiers = new Map<string, string>();\n  const pages: BarrelPage[] = [];\n\n  for (const [index, page] of discovered.entries()) {\n    const layouts = page.layouts.map((layoutFile) => {\n      let identifier = layoutIdentifiers.get(layoutFile);\n\n      if (identifier === undefined) {\n        identifier = `l${layoutIdentifiers.size}`;\n        layoutIdentifiers.set(layoutFile, identifier);\n      }\n\n      return { identifier, sourceFile: layoutFile };\n    });\n\n    pages.push({ identifier: `p${index}`, sourceFile: page.pageFile, layouts });\n  }\n\n  const importLines = [\n    `import * as app from ${quote(importSpecifierFor(productionDir, appFile))};`,\n    ...[...layoutIdentifiers.entries()].map(\n      ([layoutFile, identifier]) =>\n        `import * as ${identifier} from ${quote(importSpecifierFor(productionDir, layoutFile))};`,\n    ),\n    ...pages.map(\n      (page) =>\n        `import * as ${page.identifier} from ${quote(importSpecifierFor(productionDir, page.sourceFile))};`,\n    ),\n  ];\n\n  const relativeToApp = (file: string) => quote(toPosix(path.relative(appRoot, file)));\n\n  const pageEntries = pages.map((page) => {\n    const layouts = page.layouts\n      .map((layout) => `{ module: ${layout.identifier}, sourceFile: ${relativeToApp(layout.sourceFile)} }`)\n      .join(\", \");\n\n    return [\n      \"  {\",\n      `    module: ${page.identifier},`,\n      `    sourceFile: ${relativeToApp(page.sourceFile)},`,\n      `    layouts: [${layouts}],`,\n      \"  },\",\n    ].join(\"\\n\");\n  });\n\n  const contents = [\n    ...BARREL_HEADER,\n    ...importLines,\n    \"\",\n    \"providePageManifest({\",\n    `  clientDir: ${quote(clientDir)},`,\n    `  app: { module: app, sourceFile: ${relativeToApp(appFile)} },`,\n    \"  pages: [\",\n    ...pageEntries.map((entry) =>\n      entry\n        .split(\"\\n\")\n        .map((line) => `  ${line}`)\n        .join(\"\\n\"),\n    ),\n    \"  ],\",\n    \"});\",\n    \"\",\n  ].join(\"\\n\");\n\n  return {\n    pageCount: pages.length,\n    barrelFile: await writeBarrel(productionDir, contents),\n    contents,\n  };\n}\n"],"mappings":"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"}

package/esm/build/read-route-exports.mjs

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import { parse } from "@babel/parser";
+
+//#region ../web/src/build/read-route-exports.ts
+/**
+* Reads a page's `route` export and a layout's `prefix` export STATICALLY —
+* by parsing the source, never by loading the module.
+*
+* The build has to know a page's declared route before anything is built, and
+* the only other way to learn it is to run the page: import the module, let its
+* top-level code execute, and read the binding. That is a different program
+* from the one being built, with the application's own side effects in it. So
+* this module parses instead, and the price of parsing is that the declaration
+* has to be readable without evaluation — a literal. What cannot be read is
+* REFUSED rather than guessed: a wrong route path that builds is worse than a
+* build that stops and says which file to change.
+*
+* `route` and `prefix` are names the page contract reserves, so this reads them
+* out of whichever file it is given and refuses a computed one wherever it
+* appears — a page that exports `prefix`, or a layout that exports `route`, is
+* using a name the framework already owns.
+*
+* Single responsibility, deliberately: this returns values or a typed
+* rejection and decides nothing. What a rejection costs, and when a page is
+* routed at all, belongs to the caller.
+*/
+const EXAMPLES = {
+	route: "export const route = \"/list\"; (or export const route = { path: \"/list\", name: \"shop.list\" };)",
+	prefix: "export const prefix = \"/shop\";"
+};
+/**
+* The one thing an app developer is told when a declaration cannot be read.
+*
+* It names the file, says what was found, says why a literal is required, and
+* shows one — because the reader of this message is someone who wrote perfectly
+* valid TypeScript and needs to know why the build will not take it.
+*/
+var NonLiteralRouteExportError = class extends Error {
+	rejection;
+	constructor(rejection) {
+		const { sourceFile, exportName, detail } = rejection;
+		super(`Cannot read the \`${exportName}\` export of "${sourceFile}": ${detail}. The build reads route declarations without running your application code, so this value has to be written out as a literal. For example: ${EXAMPLES[exportName]}`);
+		this.rejection = rejection;
+		this.name = "NonLiteralRouteExportError";
+	}
+};
+/**
+* `as const`, `satisfies`, a non-null assertion and parentheses all wrap a value
+* without changing it, so reading through them costs nothing and refusing them
+* would reject declarations that are literal in every sense that matters here.
+*/
+function unwrap(node) {
+	switch (node.type) {
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TypeCastExpression":
+		case "ParenthesizedExpression": return unwrap(node.expression);
+		default: return node;
+	}
+}
+/** The string a node denotes, or `undefined` when that needs evaluation to know. */
+function stringLiteralOf(node) {
+	const value = unwrap(node);
+	if (value.type === "StringLiteral") return value.value;
+	if (value.type === "TemplateLiteral" && value.expressions.length === 0) return value.quasis[0]?.value.cooked ?? value.quasis[0]?.value.raw;
+}
+/** A sentence fragment naming what was found, for the developer-facing message. */
+function describe(node) {
+	const value = unwrap(node);
+	switch (value.type) {
+		case "CallExpression":
+		case "OptionalCallExpression":
+		case "NewExpression": return "its value is a function call";
+		case "Identifier": return `its value is the variable \`${value.name}\``;
+		case "MemberExpression":
+		case "OptionalMemberExpression": return "its value is read off another object";
+		case "TemplateLiteral": return "its value is a template literal with an expression in it";
+		case "ConditionalExpression": return "its value depends on a condition";
+		case "BinaryExpression":
+		case "LogicalExpression": return "its value is built by an expression";
+		default: return "its value is computed rather than written out";
+	}
+}
+/**
+* The object form. Unknown keys are IGNORED rather than refused, matching the
+* server, which reads `path` and `name` and lets a page carry whatever else it
+* wants alongside them. A spread is not an unknown key: it can contribute
+* `path` itself, so an object that spreads is an object whose route this cannot
+* claim to have read.
+*/
+function readRouteObject(node) {
+	let routePath;
+	let routeName;
+	for (const property of node.properties) {
+		if (property.type === "SpreadElement") return {
+			ok: false,
+			detail: "the object spreads another value into itself"
+		};
+		if (property.computed) return {
+			ok: false,
+			detail: "one of the object's keys is computed"
+		};
+		const { key } = property;
+		const keyName = key.type === "Identifier" ? key.name : key.type === "StringLiteral" ? key.value : void 0;
+		if (keyName !== "path" && keyName !== "name") continue;
+		if (property.type !== "ObjectProperty") return {
+			ok: false,
+			detail: `\`${keyName}\` is declared as a method`
+		};
+		const value = stringLiteralOf(property.value);
+		if (value === void 0) return {
+			ok: false,
+			detail: `its \`${keyName}\` is not written as a string literal`
+		};
+		if (keyName === "path") routePath = value;
+		else routeName = value;
+	}
+	if (routePath === void 0) return {
+		ok: false,
+		detail: "the object does not declare a `path`"
+	};
+	return {
+		ok: true,
+		route: routeName === void 0 ? { path: routePath } : {
+			path: routePath,
+			name: routeName
+		}
+	};
+}
+/**
+* Parses the source, or THROWS when it cannot be parsed at all.
+*
+* A syntax error is not a rejection, deliberately: nothing about the route
+* declaration is known yet, so telling the developer to write a literal would
+* answer a question they did not ask.
+*/
+function parseSource(sourceFile, source) {
+	try {
+		return parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"],
+			errorRecovery: false
+		});
+	} catch (error) {
+		throw new Error(`Cannot read the route declarations of "${sourceFile}": the file could not be parsed (${error.message}). Fix the syntax error and the build will continue.`);
+	}
+}
+/**
+* Returns the literal `route` and `prefix` this file declares.
+*
+* Absent is not a rejection: a file that declares neither is read successfully
+* with both fields unset, and what THAT means — a page with no public URL, a
+* layout that adds no prefix — is the caller's call to make.
+*
+* `source` is an override for callers that already hold the text; by default
+* the file is read from disk.
+*/
+function readRouteExports(sourceFile, source) {
+	const ast = parseSource(sourceFile, source ?? fs.readFileSync(sourceFile, "utf-8"));
+	const reject = (exportName, detail) => ({
+		ok: false,
+		rejection: {
+			sourceFile,
+			exportName,
+			detail
+		}
+	});
+	let route;
+	let prefix;
+	for (const statement of ast.program.body) {
+		if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
+		for (const specifier of statement.specifiers) {
+			if (specifier.type !== "ExportSpecifier" || specifier.exportKind === "type") continue;
+			const exported = specifier.exported.type === "Identifier" ? specifier.exported.name : specifier.exported.value;
+			if (exported === "route" || exported === "prefix") return reject(exported, "it is exported through an export list rather than declared with `export const`");
+		}
+		const { declaration } = statement;
+		if (declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of declaration.declarations) {
+			if (declarator.id.type !== "Identifier") continue;
+			const declared = declarator.id.name;
+			if (declared !== "route" && declared !== "prefix") continue;
+			if (declarator.init === null || declarator.init === void 0) return reject(declared, "it is declared without a value");
+			if (declared === "prefix") {
+				const value = stringLiteralOf(declarator.init);
+				if (value === void 0) return reject("prefix", describe(declarator.init));
+				prefix = value;
+				continue;
+			}
+			const value = stringLiteralOf(declarator.init);
+			if (value !== void 0) {
+				route = { path: value };
+				continue;
+			}
+			const object = unwrap(declarator.init);
+			if (object.type !== "ObjectExpression") return reject("route", describe(declarator.init));
+			const read = readRouteObject(object);
+			if (!read.ok) return reject("route", read.detail);
+			route = read.route;
+		}
+	}
+	return {
+		ok: true,
+		...route === void 0 ? {} : { route },
+		...prefix === void 0 ? {} : { prefix }
+	};
+}
+
+//#endregion
+export { NonLiteralRouteExportError, readRouteExports };
+//# sourceMappingURL=read-route-exports.mjs.map

package/esm/build/read-route-exports.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-route-exports.mjs","names":[],"sources":["../../../../../../../web/src/build/read-route-exports.ts"],"sourcesContent":["/**\n * Reads a page's `route` export and a layout's `prefix` export STATICALLY —\n * by parsing the source, never by loading the module.\n *\n * The build has to know a page's declared route before anything is built, and\n * the only other way to learn it is to run the page: import the module, let its\n * top-level code execute, and read the binding. That is a different program\n * from the one being built, with the application's own side effects in it. So\n * this module parses instead, and the price of parsing is that the declaration\n * has to be readable without evaluation — a literal. What cannot be read is\n * REFUSED rather than guessed: a wrong route path that builds is worse than a\n * build that stops and says which file to change.\n *\n * `route` and `prefix` are names the page contract reserves, so this reads them\n * out of whichever file it is given and refuses a computed one wherever it\n * appears — a page that exports `prefix`, or a layout that exports `route`, is\n * using a name the framework already owns.\n *\n * Single responsibility, deliberately: this returns values or a typed\n * rejection and decides nothing. What a rejection costs, and when a page is\n * routed at all, belongs to the caller.\n */\nimport fs from \"node:fs\";\nimport { parse } from \"@babel/parser\";\n\n/**\n * The AST types are derived from `parse`'s own return type rather than imported\n * from `@babel/types`: the parser resolves its own copy of that package, and a\n * node from one copy is not assignable to the identically-shaped type from the\n * other. Reading the types off the function that produced the nodes cannot\n * disagree with it.\n */\ntype Statement = ReturnType<typeof parse>[\"program\"][\"body\"][number];\ntype Expression = Extract<Statement, { type: \"ExpressionStatement\" }>[\"expression\"];\ntype ObjectExpression = Extract<Expression, { type: \"ObjectExpression\" }>;\ntype ObjectProperty = Extract<ObjectExpression[\"properties\"][number], { type: \"ObjectProperty\" }>;\n\n/**\n * Anything that can appear where a value is expected — an expression, or one of\n * the destructuring patterns that are legal in an object literal's value slot\n * and are never a literal string.\n */\ntype ValueNode = ObjectProperty[\"value\"];\n\n/**\n * A declared route, normalised. The bare-string form (`route = \"/list\"`) and\n * the object form (`route = { path: \"/list\" }`) reach the caller identically,\n * because the server resolves them identically — `name` is absent exactly when\n * the source omitted it, which is the caller's signal to derive one.\n */\nexport type DeclaredRoute = { path: string; name?: string };\n\n/** Which export could not be read, from which file, and what was found instead. */\nexport type RouteExportsRejection = {\n  sourceFile: string;\n  exportName: \"route\" | \"prefix\";\n  /** A sentence fragment naming the form that was found, e.g. \"its value is a function call\". */\n  detail: string;\n};\n\nexport type RouteExportsReadResult =\n  | { ok: true; route?: DeclaredRoute; prefix?: string }\n  | { ok: false; rejection: RouteExportsRejection };\n\nconst EXAMPLES: Record<\"route\" | \"prefix\", string> = {\n  route: 'export const route = \"/list\"; (or export const route = { path: \"/list\", name: \"shop.list\" };)',\n  prefix: 'export const prefix = \"/shop\";',\n};\n\n/**\n * The one thing an app developer is told when a declaration cannot be read.\n *\n * It names the file, says what was found, says why a literal is required, and\n * shows one — because the reader of this message is someone who wrote perfectly\n * valid TypeScript and needs to know why the build will not take it.\n */\nexport class NonLiteralRouteExportError extends Error {\n  public constructor(public readonly rejection: RouteExportsRejection) {\n    const { sourceFile, exportName, detail } = rejection;\n\n    super(\n      `Cannot read the \\`${exportName}\\` export of \"${sourceFile}\": ${detail}. The build reads ` +\n        \"route declarations without running your application code, so this value has to be \" +\n        `written out as a literal. For example: ${EXAMPLES[exportName]}`,\n    );\n\n    this.name = \"NonLiteralRouteExportError\";\n  }\n}\n\n/**\n * `as const`, `satisfies`, a non-null assertion and parentheses all wrap a value\n * without changing it, so reading through them costs nothing and refusing them\n * would reject declarations that are literal in every sense that matters here.\n */\nfunction unwrap(node: ValueNode): ValueNode {\n  switch (node.type) {\n    case \"TSAsExpression\":\n    case \"TSSatisfiesExpression\":\n    case \"TSNonNullExpression\":\n    case \"TypeCastExpression\":\n    case \"ParenthesizedExpression\":\n      return unwrap(node.expression);\n    default:\n      return node;\n  }\n}\n\n/** The string a node denotes, or `undefined` when that needs evaluation to know. */\nfunction stringLiteralOf(node: ValueNode): string | undefined {\n  const value = unwrap(node);\n\n  if (value.type === \"StringLiteral\") return value.value;\n\n  // A template with no substitutions is a string spelled with backticks.\n  if (value.type === \"TemplateLiteral\" && value.expressions.length === 0) {\n    return value.quasis[0]?.value.cooked ?? value.quasis[0]?.value.raw;\n  }\n\n  return undefined;\n}\n\n/** A sentence fragment naming what was found, for the developer-facing message. */\nfunction describe(node: ValueNode): string {\n  const value = unwrap(node);\n\n  switch (value.type) {\n    case \"CallExpression\":\n    case \"OptionalCallExpression\":\n    case \"NewExpression\":\n      return \"its value is a function call\";\n    case \"Identifier\":\n      return `its value is the variable \\`${value.name}\\``;\n    case \"MemberExpression\":\n    case \"OptionalMemberExpression\":\n      return \"its value is read off another object\";\n    case \"TemplateLiteral\":\n      return \"its value is a template literal with an expression in it\";\n    case \"ConditionalExpression\":\n      return \"its value depends on a condition\";\n    case \"BinaryExpression\":\n    case \"LogicalExpression\":\n      return \"its value is built by an expression\";\n    default:\n      return \"its value is computed rather than written out\";\n  }\n}\n\ntype ObjectRead = { ok: true; route: DeclaredRoute } | { ok: false; detail: string };\n\n/**\n * The object form. Unknown keys are IGNORED rather than refused, matching the\n * server, which reads `path` and `name` and lets a page carry whatever else it\n * wants alongside them. A spread is not an unknown key: it can contribute\n * `path` itself, so an object that spreads is an object whose route this cannot\n * claim to have read.\n */\nfunction readRouteObject(node: ObjectExpression): ObjectRead {\n  let routePath: string | undefined;\n  let routeName: string | undefined;\n\n  for (const property of node.properties) {\n    if (property.type === \"SpreadElement\") {\n      return { ok: false, detail: \"the object spreads another value into itself\" };\n    }\n\n    if (property.computed) {\n      return { ok: false, detail: \"one of the object's keys is computed\" };\n    }\n\n    const { key } = property;\n    const keyName =\n      key.type === \"Identifier\" ? key.name : key.type === \"StringLiteral\" ? key.value : undefined;\n\n    if (keyName !== \"path\" && keyName !== \"name\") continue;\n\n    if (property.type !== \"ObjectProperty\") {\n      return { ok: false, detail: `\\`${keyName}\\` is declared as a method` };\n    }\n\n    const value = stringLiteralOf(property.value);\n\n    if (value === undefined) {\n      return { ok: false, detail: `its \\`${keyName}\\` is not written as a string literal` };\n    }\n\n    if (keyName === \"path\") routePath = value;\n    else routeName = value;\n  }\n\n  if (routePath === undefined) {\n    return { ok: false, detail: \"the object does not declare a `path`\" };\n  }\n\n  return {\n    ok: true,\n    route: routeName === undefined ? { path: routePath } : { path: routePath, name: routeName },\n  };\n}\n\n/**\n * Parses the source, or THROWS when it cannot be parsed at all.\n *\n * A syntax error is not a rejection, deliberately: nothing about the route\n * declaration is known yet, so telling the developer to write a literal would\n * answer a question they did not ask.\n */\nfunction parseSource(sourceFile: string, source: string) {\n  try {\n    return parse(source, {\n      sourceType: \"module\",\n      // Every file this reads is a page or a layout, i.e. `.tsx`.\n      plugins: [\"typescript\", \"jsx\"],\n      errorRecovery: false,\n    });\n  } catch (error) {\n    throw new Error(\n      `Cannot read the route declarations of \"${sourceFile}\": the file could not be parsed ` +\n        `(${(error as Error).message}). Fix the syntax error and the build will continue.`,\n    );\n  }\n}\n\n/**\n * Returns the literal `route` and `prefix` this file declares.\n *\n * Absent is not a rejection: a file that declares neither is read successfully\n * with both fields unset, and what THAT means — a page with no public URL, a\n * layout that adds no prefix — is the caller's call to make.\n *\n * `source` is an override for callers that already hold the text; by default\n * the file is read from disk.\n */\nexport function readRouteExports(sourceFile: string, source?: string): RouteExportsReadResult {\n  const text = source ?? fs.readFileSync(sourceFile, \"utf-8\");\n  const ast = parseSource(sourceFile, text);\n\n  const reject = (exportName: \"route\" | \"prefix\", detail: string): RouteExportsReadResult => ({\n    ok: false,\n    rejection: { sourceFile, exportName, detail },\n  });\n\n  let route: DeclaredRoute | undefined;\n  let prefix: string | undefined;\n\n  for (const statement of ast.program.body) {\n    if (statement.type !== \"ExportNamedDeclaration\" || statement.exportKind === \"type\") continue;\n\n    // `export { route }` hides the value behind a binding this cannot follow\n    // without resolving scope — and following it across modules is exactly the\n    // evaluation this reader exists to avoid.\n    for (const specifier of statement.specifiers) {\n      if (specifier.type !== \"ExportSpecifier\" || specifier.exportKind === \"type\") continue;\n\n      const exported =\n        specifier.exported.type === \"Identifier\"\n          ? specifier.exported.name\n          : specifier.exported.value;\n\n      if (exported === \"route\" || exported === \"prefix\") {\n        return reject(\n          exported,\n          \"it is exported through an export list rather than declared with `export const`\",\n        );\n      }\n    }\n\n    const { declaration } = statement;\n\n    if (declaration?.type !== \"VariableDeclaration\") continue;\n\n    for (const declarator of declaration.declarations) {\n      if (declarator.id.type !== \"Identifier\") continue;\n\n      const declared = declarator.id.name;\n\n      if (declared !== \"route\" && declared !== \"prefix\") continue;\n\n      if (declarator.init === null || declarator.init === undefined) {\n        return reject(declared, \"it is declared without a value\");\n      }\n\n      if (declared === \"prefix\") {\n        const value = stringLiteralOf(declarator.init);\n\n        if (value === undefined) return reject(\"prefix\", describe(declarator.init));\n\n        prefix = value;\n        continue;\n      }\n\n      const value = stringLiteralOf(declarator.init);\n\n      if (value !== undefined) {\n        route = { path: value };\n        continue;\n      }\n\n      const object = unwrap(declarator.init);\n\n      if (object.type !== \"ObjectExpression\") return reject(\"route\", describe(declarator.init));\n\n      const read = readRouteObject(object);\n\n      if (!read.ok) return reject(\"route\", read.detail);\n\n      route = read.route;\n    }\n  }\n\n  return {\n    ok: true,\n    ...(route === undefined ? {} : { route }),\n    ...(prefix === undefined ? {} : { prefix }),\n  };\n}\n"],"mappings":"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"}