@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/dist/_chunks/convention-lint-fRkwVwEH.js

@@ -0,0 +1,893 @@
+import { h as swallow } from "./logger-uLBuGKDI.js";
+import { n as generateRouteMap, t as readFileCached } from "./file-cache-Dw6BJPG7.js";
+import { parseAst } from "vite";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { styleText } from "node:util";
+import { mkdir, writeFile } from "node:fs/promises";
+//#region src/server/utils/mdx-file.ts
+/**
+* MDX file-path detection shared by error/deny rendering paths.
+*
+* MDX status and error files are server components — they cannot be passed
+* as function props across the RSC→client boundary (e.g. to
+* TimberErrorBoundary or ErrorReconstituter) and must be pre-rendered as
+* elements with plain props instead.
+*
+* See design/10-error-handling.md §"Status-Code File Variants".
+*/
+/** MDX/markdown extensions (dotted) — the canonical list, also used by plugins/mdx.ts. */
+var MDX_EXTENSIONS = /* @__PURE__ */ new Set([".mdx", ".md"]);
+/**
+* Check if a file path ends with an MDX/markdown extension.
+*/
+function isMdxFilePath(filePath) {
+	const dotIndex = filePath.lastIndexOf(".");
+	if (dotIndex === -1) return false;
+	return MDX_EXTENSIONS.has(filePath.slice(dotIndex));
+}
+//#endregion
+//#region src/routing/segment-codegen.ts
+/**
+* $segment type generation and directory-to-route mapping.
+*
+* Generates per-route $segment.d.ts files in .timber/types/ that mirror
+* the app/ directory structure. TypeScript's rootDirs feature makes these
+* importable as './$segment' from route files.
+*
+* Design doc: design/41-global-params.md §The $segment Module
+*/
+/**
+* Build a map of absolute filesystem directory → segment info.
+* Used by resolveId to map a $segment import's importer to the correct route,
+* and by writeSegmentTypes to generate per-route $segment.d.ts files.
+*
+* Walks every segment (not just leaves) so layouts and middleware
+* at any depth can import $segment.
+*/
+function buildDirToRouteMap(tree, appDir) {
+	const map = /* @__PURE__ */ new Map();
+	function walk(node, fsPath, treePath) {
+		map.set(fsPath, {
+			route: node.urlPath || "/",
+			segmentPath: treePath || "/"
+		});
+		for (const child of node.children) walk(child, join(fsPath, child.segmentName), `${treePath}/${child.segmentName}`);
+		for (const [slotName, slotNode] of Object.entries(node.slots)) walk(slotNode, join(fsPath, `@${slotName}`), `${treePath}/@${slotName}`);
+	}
+	walk(tree.root, appDir, "");
+	return map;
+}
+/**
+* Generate the full $segment.d.ts content for a segment.
+*/
+function generateSegmentDts(info) {
+	return [
+		`export const ROUTE: '${info.route}';`,
+		`export const SEGMENT_PATH: '${info.segmentPath}';`,
+		""
+	].join("\n");
+}
+/**
+* Generate per-route $segment.d.ts files in .timber/types/ mirroring
+* the app/ directory structure. These files are importable via TypeScript's
+* rootDirs feature.
+*/
+async function writeSegmentTypes(routeTree, appDir, root) {
+	const relative = appDir.slice(root.length + 1);
+	const typesBase = join(root, ".timber", "types", relative);
+	const map = buildDirToRouteMap(routeTree, appDir);
+	const writes = [];
+	for (const [fsDir, info] of map) {
+		const relDir = fsDir.slice(appDir.length);
+		const segmentDir = join(typesBase, relDir);
+		const segmentFile = join(segmentDir, "$segment.d.ts");
+		const content = generateSegmentDts(info);
+		writes.push(mkdir(segmentDir, { recursive: true }).then(() => writeFile(segmentFile, content, "utf-8")));
+	}
+	await Promise.all(writes);
+}
+//#endregion
+//#region src/routing/codegen-write.ts
+/**
+* Route-map codegen writer.
+*
+* Materializes the generated route types on disk: `.timber/timber-routes.d.ts`,
+* `.timber/segment-types.d.ts` (via `writeSegmentTypes`), and the root
+* `timber-env.d.ts` that references them.
+*
+* Lives outside `plugins/routing.ts` because it has two callers with two
+* different failure policies: the dev/build plugin starts the write off the hot
+* path and logs failures, while `timber check` awaits it and treats a failure as
+* fatal — a type check run against absent or stale route types reports errors
+* about code that is fine. One implementation, two policies, so the bytes on
+* disk cannot drift between the two commands.
+*
+* Design docs: 09-typescript.md §"Typed Routes", 18-build-system.md
+*/
+/**
+* Path (relative to the project root) of the generated route map declaration
+* file, and the name of the root file that `/// <reference>`s it.
+*
+* Exported because `timber check` has to answer whether the user's tsconfig
+* pulls these into the program — a question about these exact paths. It derives
+* them from here rather than restating them, so a rename cannot leave the check
+* looking for a file nothing writes.
+*/
+var CODEGEN_OUTPUT = ".timber/timber-routes.d.ts";
+/** Root-level file that references the generated declarations. */
+var ENV_DTS_FILENAME = "timber-env.d.ts";
+/**
+* Content of the timber-env.d.ts file written to the project root.
+*
+* Uses a triple-slash reference so TypeScript auto-discovers the generated
+* route map without the user needing to edit tsconfig.json — same pattern
+* as Next.js's next-env.d.ts.
+*
+* Also references `vite/client` so side-effect imports like
+* `import './globals.css'` type-check without ts(2882), and so
+* `import.meta.env`, `import.meta.hot`, `import.meta.glob`, asset
+* imports (`*.png`, `*.svg`, …), CSS modules, and `?url`/`?raw`/
+* `?inline` query variants all resolve without the user editing
+* tsconfig.json themselves. Next.js's next-env.d.ts plays the same
+* role via `next/types/global`.
+*
+* `vite` is a peer dep of `@timber-js/app`, so the reference always
+* resolves in a correctly-installed project.
+*/
+var TIMBER_ENV_DTS = [
+	"// This file is auto-generated by timber.js. Do not edit.",
+	"// It ensures TypeScript picks up the generated route types and",
+	"// Vite-provided ambient types (CSS, assets, import.meta.env, HMR).",
+	"/* eslint-disable @typescript-eslint/triple-slash-reference */",
+	"/// <reference path=\".timber/timber-routes.d.ts\" />",
+	"/// <reference types=\"vite/client\" />",
+	"/// <reference types=\"react/canary\" />",
+	"/// <reference types=\"react-dom/canary\" />",
+	""
+].join("\n");
+/**
+* Codegen writes that have been started but have not yet landed on disk.
+*
+* `writeRouteCodegen` is deliberately unawaited on the dev/build hot path,
+* which leaves that caller no way to know the files exist yet. Anything that
+* tears down the project root — a build process exiting, a test removing its
+* temp root — then races the writes: `rmSync` empties a directory that a
+* pending `mkdir` immediately recreates, and the removal fails with ENOTEMPTY.
+*
+* Every started write registers here and deregisters when it settles, so
+* `flushCodegenWrites()` can await them instead of guessing at a delay.
+*/
+var pendingCodegenWrites = /* @__PURE__ */ new Set();
+/**
+* Resolve once every codegen write started so far has landed on disk.
+*
+* Safe to call at any time and from anywhere — writes are tracked per process,
+* not per plugin instance, so a caller does not need a handle on the plugin
+* that started them. Never rejects: the tracked copy of each write has its
+* rejection swallowed, so a failing write cannot turn a teardown barrier into
+* an unhandled rejection. Callers that care about failure await the promise
+* `writeRouteCodegen` returned instead.
+*/
+async function flushCodegenWrites() {
+	while (pendingCodegenWrites.size > 0) {
+		const inFlight = [...pendingCodegenWrites];
+		await Promise.all(inFlight);
+		for (const write of inFlight) pendingCodegenWrites.delete(write);
+	}
+}
+/**
+* Write the generated route map, segment types, and the timber-env.d.ts
+* reference file for `tree`.
+*
+* Returns a promise that **rejects** if any write fails. The dev/build plugin
+* does not await it (types are a developer convenience there, not a runtime
+* dependency) and logs instead; `timber check` awaits it and fails the command.
+* Either way the write is registered with `flushCodegenWrites()`.
+*/
+function writeRouteCodegen(tree, appDir, root) {
+	const timberDir = join(root, ".timber");
+	const content = generateRouteMap(tree, {
+		appDir,
+		outputDir: timberDir
+	});
+	const routesPath = join(root, CODEGEN_OUTPUT);
+	const envPath = join(root, ENV_DTS_FILENAME);
+	const done = mkdir(timberDir, { recursive: true }).then(() => Promise.all([
+		writeFile(routesPath, content, "utf-8"),
+		writeFile(envPath, TIMBER_ENV_DTS, "utf-8"),
+		writeSegmentTypes(tree, appDir, root)
+	])).then(() => void 0);
+	const tracked = done.catch(() => void 0);
+	pendingCodegenWrites.add(tracked);
+	tracked.finally(() => pendingCodegenWrites.delete(tracked));
+	return done;
+}
+//#endregion
+//#region src/routing/export-detect.ts
+/**
+* AST-based export detection for route files.
+*
+* Uses Vite's `parseAst` (backed by oxc) to precisely detect named and
+* default exports, replacing the regex-based approach that was fragile
+* with TypeScript syntax (type exports, `as` aliases, comments, etc.).
+*/
+function tryParse(source) {
+	try {
+		return parseAst(source, { lang: "tsx" });
+	} catch {
+		return null;
+	}
+}
+/**
+* Collect all named export identifiers from a parsed program.
+* Handles: `export function X`, `export const X`, `export { X }`,
+* `export { X } from '...'`, `export { Y as X }`.
+*/
+function collectNamedExports(program) {
+	const names = /* @__PURE__ */ new Set();
+	for (const stmt of program.body) {
+		if (stmt.type !== "ExportNamedDeclaration") continue;
+		if (stmt.exportKind === "type") continue;
+		if (stmt.declaration) {
+			if (stmt.declaration.id?.name) names.add(stmt.declaration.id.name);
+			if (stmt.declaration.declarations) {
+				for (const decl of stmt.declaration.declarations) if (decl.id?.name) names.add(decl.id.name);
+			}
+		}
+		if (stmt.specifiers) for (const spec of stmt.specifiers) {
+			if (spec.exportKind === "type") continue;
+			if (spec.exported?.name && spec.exported.name !== "default") names.add(spec.exported.name);
+		}
+	}
+	return names;
+}
+/**
+* The specifier exporting a *runtime* default from this statement, if any.
+*
+* Type-only exports erase, so they are not default exports at runtime — and
+* TypeScript spells that two ways, on two different nodes: `export type { X as
+* default }` marks the **statement**, `export { type X as default }` marks the
+* **specifier**. Both have to be checked, or a type alias reads as a component:
+* a status file whose only default is a type has nothing for the error boundary
+* to receive (the renderer's `mod?.default` skips it), so treating it as one
+* would fail a build over a file that cannot break anything.
+*
+* One implementation because two callers must agree on what "has a default
+* export" means: `hasDefaultExport` decides whether to warn that a page has
+* none, and `fileDefaultExportIsLocalValue` decides whether to fail the build.
+*/
+function defaultSpecifier(stmt) {
+	if (stmt.type !== "ExportNamedDeclaration" || !stmt.specifiers) return null;
+	if (stmt.exportKind === "type") return null;
+	for (const spec of stmt.specifiers) {
+		if (spec.exportKind === "type") continue;
+		if (spec.exported?.name === "default") return spec;
+	}
+	return null;
+}
+/**
+* Check whether a program has a default export.
+* Handles: `export default ...`, `export { X as default }`,
+* `export { default } from '...'`. Type-only defaults do not count —
+* see `defaultSpecifier`.
+*/
+function hasDefaultExport(program) {
+	for (const stmt of program.body) {
+		if (stmt.type === "ExportDefaultDeclaration") return true;
+		if (defaultSpecifier(stmt)) return true;
+	}
+	return false;
+}
+/**
+* Check whether a program has any bare `export * from '...'` declarations.
+* Excludes `export * as X from '...'` (namespace re-exports) since those
+* create a namespace object, not individual top-level exports.
+*/
+function hasStarExport(program) {
+	return program.body.some((stmt) => stmt.type === "ExportAllDeclaration" && !stmt.exported && stmt.exportKind !== "type");
+}
+/**
+* Check if a file has any of the given named exports.
+* Returns the set of matching export names.
+*/
+function fileHasAnyExport(filePath, exportNames) {
+	const matches = /* @__PURE__ */ new Set();
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return matches;
+		const exports = collectNamedExports(program);
+		for (const name of exportNames) if (exports.has(name)) matches.add(name);
+	} catch {}
+	return matches;
+}
+/**
+* Check if a file has a default export.
+* Returns false if the file doesn't exist or can't be parsed.
+*/
+function fileHasDefaultExport(filePath) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		return hasDefaultExport(program);
+	} catch {
+		return false;
+	}
+}
+/** Node types whose value is unambiguously constructed by this module. */
+var FUNCTION_LIKE = /* @__PURE__ */ new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression",
+	"ClassDeclaration",
+	"ClassExpression"
+]);
+/**
+* Expression wrappers that erase at runtime and so cannot change where a value
+* was constructed: `X as T`, `X satisfies T`, `<T>X`, `X!`, `X<T>`, `(X)`.
+*/
+var TRANSPARENT_WRAPPERS = /* @__PURE__ */ new Set([
+	"TSAsExpression",
+	"TSSatisfiesExpression",
+	"TSTypeAssertion",
+	"TSNonNullExpression",
+	"TSInstantiationExpression",
+	"ParenthesizedExpression"
+]);
+/**
+* Strip runtime-transparent wrappers so the node underneath can be classified.
+*
+* Without this, `(() => <h1 />) satisfies React.FC` reads as a
+* `TSSatisfiesExpression` rather than the arrow function it compiles to, and a
+* provably-local component is misread as one whose origin cannot be
+* determined — turning a build error into a warning.
+*/
+function unwrapTransparent(node) {
+	let current = node;
+	while (TRANSPARENT_WRAPPERS.has(current.type) && current.expression) current = current.expression;
+	return current;
+}
+/**
+* Whether `name` is bound at module top level to a function or class written
+* in this file. An imported binding can never match: imports are
+* `ImportDeclaration` specifiers, not function/class/variable declarations,
+* and a module-level name cannot be both.
+*/
+function bindsLocalFunction(program, name) {
+	for (const stmt of program.body) {
+		const decl = stmt.type === "ExportNamedDeclaration" ? stmt.declaration : stmt;
+		if (!decl) continue;
+		if ((decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration") && decl.id?.name === name) return true;
+		if (decl.type === "VariableDeclaration") {
+			for (const d of decl.declarations ?? []) if (d.id?.name === name && d.init && FUNCTION_LIKE.has(unwrapTransparent(d.init).type)) return true;
+		}
+	}
+	return false;
+}
+/**
+* Whether the default export is *provably* a value constructed by this module:
+* `export default function/class/() => {}`, or a name bound to a function or
+* class declared here — whether it leaves via `export default Name` or
+* `export { Name as default }`. Both spellings are the same fact about where
+* the value was built, so both must answer the same way.
+*
+* This is the sound half of "is this a server component?". A file with no
+* `'use client'` directive whose default export is built here is a server
+* component, full stop. Everything else — `export { default } from
+* './client-thing'`, `export default Imported`, `export default memo(X)`,
+* an unparseable file — returns false, because the exported value may have
+* been minted in a module that *does* carry the directive. Callers must not
+* infer "server component" from a missing directive alone.
+*/
+function fileDefaultExportIsLocalValue(filePath) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		for (const stmt of program.body) {
+			if (stmt.type === "ExportDefaultDeclaration") {
+				const decl = stmt.declaration && unwrapTransparent(stmt.declaration);
+				if (!decl) return false;
+				if (FUNCTION_LIKE.has(decl.type)) return true;
+				if (decl.type === "Identifier" && decl.name) return bindsLocalFunction(program, decl.name);
+				return false;
+			}
+			const spec = defaultSpecifier(stmt);
+			if (spec) {
+				if (stmt.source) return false;
+				return spec.local?.name ? bindsLocalFunction(program, spec.local.name) : false;
+			}
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if a file has any `export * from '...'` declarations.
+* Returns false if the file doesn't exist or can't be parsed.
+*/
+function fileHasStarExport(filePath) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		return hasStarExport(program);
+	} catch {
+		return false;
+	}
+}
+function extractLiteralValue(node) {
+	if (!node) return void 0;
+	const n = node;
+	if (n.type === "Literal") return n.value;
+	if (n.type === "UnaryExpression" && n.operator === "-" && n.argument?.type === "Literal") return -n.argument.value;
+	if (n.type === "ArrayExpression") {
+		const elements = n.elements;
+		if (!elements) return void 0;
+		const result = [];
+		for (const el of elements) {
+			const v = extractLiteralValue(el);
+			if (v === void 0) return void 0;
+			result.push(v);
+		}
+		return result;
+	}
+}
+function extractObjectLiteral(node) {
+	if (node.type !== "ObjectExpression") return void 0;
+	const props = node.properties;
+	if (!props) return void 0;
+	const result = {};
+	for (const prop of props) {
+		const p = prop;
+		if (p.type === "SpreadElement") return void 0;
+		if (p.type !== "Property" || p.computed) return void 0;
+		const key = p.key?.type === "Identifier" ? p.key.name : p.key?.type === "Literal" ? String(p.key.value) : void 0;
+		if (!key) return void 0;
+		const value = extractLiteralValue(p.value);
+		if (value === void 0) return void 0;
+		result[key] = value;
+	}
+	return result;
+}
+/**
+* Extract the value of `export const prerender` from a file.
+* Returns undefined if the file doesn't export `prerender` or can't be parsed.
+*
+* Supports:
+*   export const prerender = true;
+*   export const prerender = false;
+*   export const prerender = { ttl: 3600, tags: ['docs'] };
+*/
+function getPrerenderExport(filePath) {
+	if (!existsSync(filePath)) return void 0;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return void 0;
+		for (const stmt of program.body) {
+			if (stmt.type !== "ExportNamedDeclaration") continue;
+			if (stmt.exportKind === "type") continue;
+			if (!stmt.declaration) continue;
+			const decl = stmt.declaration;
+			if (decl.type !== "VariableDeclaration") continue;
+			const declarations = decl.declarations;
+			if (!declarations) continue;
+			for (const d of declarations) {
+				if (d.id?.name !== "prerender" || !d.init) continue;
+				const init = d.init;
+				if (init.type === "Literal" && typeof init.value === "boolean") return init.value;
+				if (init.type === "ObjectExpression") {
+					const obj = extractObjectLiteral(init);
+					if (!obj) return void 0;
+					const result = {};
+					if ("ttl" in obj && typeof obj.ttl === "number") result.ttl = obj.ttl;
+					if ("tags" in obj && Array.isArray(obj.tags) && obj.tags.every((t) => typeof t === "string")) result.tags = obj.tags;
+					return result;
+				}
+				return;
+			}
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+/**
+* Check if a file starts with a specific directive (e.g. "use client").
+* Directives are string literal expression statements at the top of the file.
+*/
+function fileHasDirective(filePath, directive) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		for (const stmt of program.body) {
+			if (stmt.type !== "ExpressionStatement") break;
+			const expr = stmt.expression;
+			if (expr?.type !== "Literal" || typeof expr.value !== "string") break;
+			if (expr.value === directive) return true;
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/routing/convention-lint.ts
+/**
+* Convention linter — validates common misconfigurations in the route tree.
+*
+* Runs at scan time (build and dev startup). Each check produces a warning
+* with the file path, what's wrong, and what to do about it.
+*
+* Most checks are warnings — they don't block the build. The goal is to catch
+* issues that would otherwise produce cryptic runtime behavior (silent 404s,
+* empty pages, confusing React errors).
+*
+* A check emits `level: 'error'` only when the misconfiguration is *proven*
+* (never inferred from an absence the analysis cannot see through) and fatal
+* to rendering. `plugins/routing.ts` turns those into a thrown build error,
+* so a false positive there refuses a working app — see
+* `classifyClientBoundaryFile` for how that bar is met.
+*
+* Design doc: 07-routing.md, 10-error-handling.md
+*/
+/**
+* Run all convention lint checks on a route tree.
+*
+* Returns an array of warnings. Empty array means everything looks good.
+*/
+function lintConventions(tree, appDir) {
+	const warnings = [];
+	checkEmptyApp(tree.root, appDir, warnings);
+	checkRouteExports(tree.root, warnings);
+	checkRootLayout(tree.root, warnings);
+	checkDefaultExports(tree.root, warnings);
+	checkClientLayouts(tree.root, warnings);
+	checkClientBoundaryFiles(tree.root, warnings);
+	if (tree.globalError) checkFileUseClientDirective(tree.globalError, "global-error", warnings);
+	checkWildcardMdxProps(tree.root, warnings);
+	return warnings;
+}
+function checkClientLayouts(node, warnings) {
+	if (node.layout && isScriptExtension(node.layout.extension)) try {
+		const isClient = fileHasDirective(node.layout.filePath, "use client");
+		const isProvablyServer = fileDefaultExportIsLocalValue(node.layout.filePath);
+		if (isClient || !isProvablyServer) {
+			const certainty = isClient ? `This layout is a client component.` : `Timber cannot prove this layout is a server component because its default export comes from another module or an opaque expression.`;
+			warnings.push({
+				id: `CLIENT_LAYOUT_NOT_AUTH_BOUNDARY:${node.layout.filePath}`,
+				summary: isClient ? `Client layout cannot securely suppress server children: ${node.layout.filePath}` : `Layout may resolve to a client component and cannot be trusted as an auth boundary: ${node.layout.filePath}`,
+				details: `  File: ${node.layout.filePath}\n\n  ${certainty}\n  React Flight resolves server content passed to a client layout before the layout runs in the browser.\n  Conditionally omitting children here does not prevent descendant server components from executing or being serialized.\n\n  To fix: Put authorization in access.ts or a provably server layout with a locally defined default component, and keep client components inside that boundary.\n`,
+				level: "warn"
+			});
+		}
+	} catch (err) {
+		swallow(err, `convention-lint: unreadable layout file ${node.layout.filePath}`);
+	}
+	for (const child of node.children) checkClientLayouts(child, warnings);
+	for (const slot of Object.values(node.slots)) checkClientLayouts(slot, warnings);
+}
+/**
+* Warn when the app/ directory has no routable files at all.
+*
+* This catches the "I created app/ but didn't add any pages" case where
+* every request silently 404s with no guidance.
+*/
+function checkEmptyApp(root, appDir, warnings) {
+	if (hasAnyRoutable(root)) return;
+	warnings.push({
+		id: "EMPTY_APP",
+		summary: "No pages or route handlers found in app/",
+		details: `  Directory: ${appDir}\n\n  Your app/ directory has no page.tsx or route.ts files.
+  Every request will return 404.
+
+  To fix: Create app/page.tsx with a default export:
+
+    export default function Home() {
+      return <h1>Hello</h1>;
+    }
+`,
+		level: "warn"
+	});
+}
+/**
+* Check if a segment tree has any routable files (page or route) anywhere.
+*/
+function hasAnyRoutable(node) {
+	if (node.page || node.route) return true;
+	for (const child of node.children) if (hasAnyRoutable(child)) return true;
+	for (const slot of Object.values(node.slots)) if (hasAnyRoutable(slot)) return true;
+	return false;
+}
+/**
+* Check if a segment tree has any page files (not just route handlers).
+* Used by checkRootLayout to avoid false positives for API-only apps (TIM-794).
+* API-only apps (just route.ts handlers) don't need a root layout.
+*/
+function hasAnyPage(node) {
+	if (node.page) return true;
+	for (const child of node.children) if (hasAnyPage(child)) return true;
+	for (const slot of Object.values(node.slots)) if (hasAnyPage(slot)) return true;
+	return false;
+}
+/** HTTP methods that route.ts can export. */
+var HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+];
+/**
+* Warn when a route.ts file doesn't appear to export any recognized HTTP methods.
+*
+* Uses AST-based detection via parseAst for precise matching.
+* Falls back silently when the file can't be parsed (syntax errors produce
+* no spurious warning — the TS compiler will catch those).
+*/
+function checkRouteExports(node, warnings) {
+	if (node.route) {
+		const filePath = node.route.filePath;
+		try {
+			if (fileHasAnyExport(filePath, HTTP_METHODS).size === 0 && !fileHasStarExport(filePath)) {
+				const hint = fileHasDefaultExport(filePath) ? "  It looks like you have a default export. route.ts uses named exports\n  for HTTP methods (GET, POST, etc.), not a default export.\n" : "";
+				warnings.push({
+					id: "ROUTE_NO_METHODS",
+					summary: `route.ts has no HTTP method exports: ${filePath}`,
+					details: `  File: ${filePath}\n\n  route.ts files must export named HTTP method handlers.
+  Without them, the route matches but returns 405 Method Not Allowed.
+
+` + hint + "  Example:\n\n    export function GET(ctx: RouteContext) {\n      return Response.json({ hello: 'world' });\n    }\n",
+					level: "warn"
+				});
+			}
+		} catch (err) {
+			swallow(err, `convention-lint: unreadable route.ts ${filePath}`);
+		}
+	}
+	for (const child of node.children) checkRouteExports(child, warnings);
+	for (const slot of Object.values(node.slots)) checkRouteExports(slot, warnings);
+}
+/**
+* Warn when the root segment has no layout.tsx.
+*
+* Without a root layout, there's no HTML shell (<html>, <body>).
+* The page will render but may have hydration issues or no proper document structure.
+*/
+function checkRootLayout(root, warnings) {
+	if (root.layout) return;
+	if (!hasAnyPage(root)) return;
+	warnings.push({
+		id: "NO_ROOT_LAYOUT",
+		summary: "No root layout.tsx found",
+		details: "  Your app has pages but no root layout.\n  Without app/layout.tsx, pages have no <html> or <body> wrapper.\n\n  To fix: Create app/layout.tsx:\n\n    export default function RootLayout({ children }: { children: React.ReactNode }) {\n      return (\n        <html lang=\"en\">\n          <body>{children}</body>\n        </html>\n      );\n    }\n",
+		level: "warn"
+	});
+}
+/**
+* Warn when page.tsx or layout.tsx files don't have a default export.
+*
+* Without a default export:
+* - page.tsx: the page renders nothing (empty content)
+* - layout.tsx: the layout module loads but has no component to render
+*
+* Uses AST-based detection via parseAst for precise matching. Falls back
+* silently when the file can't be parsed (no spurious warning on syntax errors).
+*/
+function checkDefaultExports(node, warnings) {
+	if (node.page && isScriptExtension(node.page.extension)) checkFileDefaultExport(node.page.filePath, "page", warnings);
+	if (node.layout && isScriptExtension(node.layout.extension)) checkFileDefaultExport(node.layout.filePath, "layout", warnings);
+	for (const child of node.children) checkDefaultExports(child, warnings);
+	for (const slot of Object.values(node.slots)) checkDefaultExports(slot, warnings);
+}
+function isScriptExtension(ext) {
+	return ext === "tsx" || ext === "ts" || ext === "jsx" || ext === "js";
+}
+function checkFileDefaultExport(filePath, fileType, warnings) {
+	try {
+		if (!fileHasDefaultExport(filePath)) warnings.push({
+			id: `NO_DEFAULT_EXPORT:${filePath}`,
+			summary: `${fileType}.tsx has no default export: ${filePath}`,
+			details: `  File: ${filePath}\n\n  ${fileType}.tsx files must export a default React component.\n  Without a default export, the ${fileType === "page" ? "page renders nothing" : "layout has no component to wrap children"}.\n\n  To fix: Add a default export:\n\n    export default function My${fileType === "page" ? "Page" : "Layout"}(${fileType === "layout" ? "{ children }" : ""}) {\n      return ${fileType === "layout" ? "<div>{children}</div>" : "<h1>Hello</h1>"};\n    }\n`,
+			level: "warn"
+		});
+	} catch (err) {
+		swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
+	}
+}
+/**
+* Check every file the renderer hands to `TimberErrorBoundary` as a component
+* prop: `error.tsx`, `global-error.tsx`, and the status-code family
+* (`404.tsx`, `4xx.tsx`, `503.tsx`, …).
+*
+* `TimberErrorBoundary` is a client component, so a server component passed as
+* `fallbackComponent` is a function crossing the RSC → client boundary. React
+* Flight refuses to serialize it, and because the boundary wraps the segment's
+* *children*, the failure hits every page under that segment — not just the
+* error path. The raw message ("Functions cannot be passed directly to Client
+* Components") names neither the file nor the fix (TIM-1329).
+*
+* MDX status files are exempt: they are server components by design and the
+* renderer pre-renders them into `fallbackElement` instead. See TIM-503 and
+* `server/error-boundary-wrapper.ts`.
+*
+* `.json` status files never reach React at all, and are not in `statusFiles`.
+*/
+function checkClientBoundaryFiles(node, warnings) {
+	if (node.error) checkFileUseClientDirective(node.error, "error", warnings);
+	for (const [key, file] of Object.entries(node.statusFiles ?? {})) checkFileUseClientDirective(file, key, warnings);
+	for (const child of node.children) checkClientBoundaryFiles(child, warnings);
+	for (const slot of Object.values(node.slots)) checkClientBoundaryFiles(slot, warnings);
+}
+function classifyClientBoundaryFile(filePath) {
+	if (fileHasDirective(filePath, "use client")) return "client";
+	if (fileDefaultExportIsLocalValue(filePath)) return "server";
+	return "unknown";
+}
+/** Example component name for the fix snippet, keyed by convention name. */
+function exampleComponentName(convention) {
+	if (convention === "global-error") return "GlobalError";
+	if (convention === "error") return "ErrorBoundary";
+	if (convention === "404") return "NotFound";
+	return "StatusPage";
+}
+/**
+* @param file      the route file (its extension decides whether the check applies)
+* @param convention the convention name — `error`, `global-error`, `404`, `4xx`, …
+*/
+function checkFileUseClientDirective(file, convention, warnings) {
+	if (isMdxFilePath(file.filePath)) return;
+	const filePath = file.filePath;
+	const label = `${convention}.${file.extension}`;
+	let verdict;
+	try {
+		verdict = classifyClientBoundaryFile(filePath);
+	} catch (err) {
+		swallow(err, `convention-lint: unreadable ${label} file ${filePath}`);
+		return;
+	}
+	if (verdict === "client") return;
+	const isError = verdict === "server";
+	const name = exampleComponentName(convention);
+	const props = convention === "error" || convention === "global-error" ? "{ error, reset }" : "{ status }";
+	warnings.push({
+		id: `NEEDS_USE_CLIENT:${filePath}`,
+		summary: isError ? `${label} is a server component and must be a client component: ${filePath}` : `${label} may be missing 'use client': ${filePath}`,
+		details: `  File: ${filePath}\n\n  ${label} is handed to timber's error boundary — a client\n  component — as a prop. A server component cannot cross that boundary:
+  React fails with "Functions cannot be passed directly to Client
+  Components", and every page under this segment fails to render.
+
+` + (isError ? `  To fix: Add 'use client' as the first line of the file:
+
+    'use client';
+
+    export default function ${name}(${props}) {\n      return <h1>…</h1>;
+    }
+` : "  This file has no 'use client' directive, and its default export\n  comes from elsewhere, so timber cannot tell which it is. If the\n  module it re-exports starts with 'use client', nothing is wrong\n  and you can ignore this. Otherwise add the directive there.\n"),
+		level: isError ? "error" : "warn"
+	});
+}
+/**
+* Wildcard status file keys in `statusFiles` whose props differ by path.
+* `error` is not here — the scanner stores it in `node.error`, not
+* `node.statusFiles`, and the check handles it separately below.
+*/
+var WILDCARD_MDX_STATUS_KEYS = /* @__PURE__ */ new Set(["4xx", "5xx"]);
+/**
+* Warn when a wildcard MDX status file (`4xx.mdx`, `5xx.mdx`, `error.mdx`)
+* appears to reference `props` in its source.
+*
+* These files are pre-rendered into `fallbackElement` on the error-boundary
+* path, before the error happens, so they receive empty or partial props.
+* On the deny and error-renderer paths they receive the real props. An author
+* writing `{props.status}` gets the number on some paths and `undefined` on
+* others — same source, different output.
+*
+* A text scan for `props` is acceptable here because the check is `level:
+* 'warn'` — a false positive costs a printed line, not a refused build. A
+* sound check would need the MDX compiler, which is optional, async, and
+* scoped to the RSC environment. See TIM-1333.
+*
+* Exact-code MDX files (e.g. `503.mdx`) are unaffected — all four paths
+* agree on their status.
+*/
+function checkWildcardMdxProps(node, warnings) {
+	if (node.statusFiles) {
+		for (const [key, file] of Object.entries(node.statusFiles)) if (WILDCARD_MDX_STATUS_KEYS.has(key) && isMdxFilePath(file.filePath)) checkMdxFileForProps(file.filePath, key, warnings);
+	}
+	if (node.error && isMdxFilePath(node.error.filePath)) checkMdxFileForProps(node.error.filePath, "error", warnings);
+	for (const child of node.children) checkWildcardMdxProps(child, warnings);
+	for (const slot of Object.values(node.slots)) checkWildcardMdxProps(slot, warnings);
+}
+/**
+* Check if an MDX file's source appears to reference `props`.
+*
+* MDX passes a `props` object to the default export function. A reference to
+* `props.status` or `props.dangerouslyPassData` in a wildcard file works on
+* the deny/throw paths but renders `undefined` on the boundary path.
+*/
+function checkMdxFileForProps(filePath, convention, warnings) {
+	let source;
+	try {
+		source = readFileSync(filePath, "utf-8");
+	} catch {
+		return;
+	}
+	if (!/\bprops\b/.test(source)) return;
+	const label = `${convention}.${filePath.endsWith(".md") ? "md" : "mdx"}`;
+	warnings.push({
+		id: `MDX_WILDCARD_PROPS:${filePath}`,
+		summary: `${label} references props, which are empty on the error boundary path: ${filePath}`,
+		details: `  File: ${filePath}\n\n  Wildcard MDX status files (${convention}.mdx) are pre-rendered into\n  fallbackElement before the error occurs. On that path, props are
+  empty${convention === "error" ? "" : " (no status, no dangerouslyPassData)"}. On the deny() and error-renderer\n  paths, props.status resolves correctly.
+
+  If this file uses only static content and "props" appears in prose,
+  this warning is a false positive — ignore it.
+
+  To fix: Use only static content in wildcard MDX status files, or
+  use an exact-code file (e.g. 404.mdx) where all paths agree.
+`,
+		level: "warn"
+	});
+}
+/**
+* Check if the app/ directory exists. Called before scanning.
+* Returns a warning if missing, or null if the directory exists.
+*/
+function checkAppDirExists(appDir) {
+	if (existsSync(appDir)) return null;
+	return {
+		id: "NO_APP_DIR",
+		summary: "No app/ directory found",
+		details: `  Expected: ${appDir}\n\n  timber.js requires an app/ directory for file-system routing.
+  Every request will return 404 until you create it.
+
+  To fix: Create the app/ directory with a page:
+
+    mkdir -p app
+    # Create app/layout.tsx and app/page.tsx
+`,
+		level: "error"
+	};
+}
+var noValidate = { validateStream: false };
+/**
+* Format warnings for terminal output.
+*
+* Groups by severity, uses colors, and includes fix suggestions.
+*/
+function formatConventionWarnings(warnings, options = {}) {
+	const { color = true } = options;
+	const style = (fmt, text) => color ? styleText(fmt, text, noValidate) : text;
+	if (warnings.length === 0) return "";
+	const errors = warnings.filter((w) => w.level === "error");
+	const warns = warnings.filter((w) => w.level === "warn");
+	const lines = [];
+	if (errors.length > 0) {
+		lines.push(`${style(["red", "bold"], "[timber]")} ${style("red", `${errors.length} configuration error${errors.length !== 1 ? "s" : ""}:`)}`);
+		for (const e of errors) {
+			lines.push("");
+			lines.push(`  ${style("red", "✗")} ${e.summary}`);
+			lines.push(style("dim", e.details));
+		}
+	}
+	if (warns.length > 0) {
+		if (errors.length > 0) lines.push("");
+		lines.push(`${style(["yellow", "bold"], "[timber]")} ${style("yellow", `${warns.length} configuration warning${warns.length !== 1 ? "s" : ""}:`)}`);
+		for (const w of warns) {
+			lines.push("");
+			lines.push(`  ${style("yellow", "⚠")} ${w.summary}`);
+			lines.push(style("dim", w.details));
+		}
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { CODEGEN_OUTPUT as a, writeRouteCodegen as c, getPrerenderExport as i, buildDirToRouteMap as l, formatConventionWarnings as n, ENV_DTS_FILENAME as o, lintConventions as r, flushCodegenWrites as s, checkAppDirExists as t, MDX_EXTENSIONS as u };
+
+//# sourceMappingURL=convention-lint-fRkwVwEH.js.map