@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

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

@@ -0,0 +1,590 @@
+import { t as writeFileAtomic } from "./write-file-atomic-D1qWqHb4.js";
+import { a as fileHasDefaultExport, c as getCsrfExport, i as fileHasAnyExport, o as fileHasDirective, r as fileDefaultExportIsLocalValue, s as fileHasStarExport } from "./scanner-DmqdxzbW.js";
+import { v as swallow } from "./logger-BP0LN6vP.js";
+import { t as generateRouteMap } from "./codegen-Bps1sLKJ.js";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { styleText } from "node:util";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+//#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(() => writeFileAtomic(segmentFile, content)));
+	}
+	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()`.
+*/
+/**
+* Write `timber-env.d.ts` only when its content differs.
+*
+* Its content is constant per timber version, so almost every call is a no-op
+* — and a file that is not rewritten cannot be read half-written. It is not
+* replaced atomically because it lives in the user's project root, often
+* committed: a rename would turn a symlink into a regular file, reset its
+* permissions, and a process killed mid-write would leave a temp file next to
+* their source. The in-place write happens only on first run or a timber
+* upgrade.
+*/
+async function writeEnvDts(envPath) {
+	if (await readFile(envPath, "utf-8").catch(() => null) !== TIMBER_ENV_DTS) await writeFile(envPath, TIMBER_ENV_DTS, "utf-8");
+}
+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([
+		writeFileAtomic(routesPath, content),
+		writeEnvDts(envPath),
+		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/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);
+	checkSlotMiddleware(tree.root, warnings);
+	checkCsrfExports(tree.root, warnings);
+	if (tree.proxy) checkCsrfExport(tree.proxy, "proxy.ts", warnings);
+	if (tree.globalError) checkCsrfExport(tree.globalError, "global-error", 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);
+}
+/** Single-file segment conventions other than route.ts. */
+var NON_ROUTE_FILE_KEYS = [
+	"page",
+	"layout",
+	"middleware",
+	"access",
+	"error",
+	"default",
+	"denied"
+];
+/**
+* Fail the build on a `csrf` export the CSRF gate would not honor.
+*
+* Both findings are proven from source, and both are fatal in the sense
+* the error level requires: the developer wrote an exemption that silently
+* does nothing, so a legitimate cross-site POST they meant to accept gets
+* a 403 in production, or they believe a page or action is exempt when
+* the gate still protects it. The exemption exists only on route.ts —
+* server actions always get the check (design/08 §"Per-route exemption").
+* A `'use server'` module cannot export it at all: plugin-rsc rejects every
+* non-async-function export there.
+*/
+function checkCsrfExports(node, warnings) {
+	if (node.route) checkCsrfExport(node.route, "route.ts", warnings);
+	for (const key of NON_ROUTE_FILE_KEYS) {
+		const file = node[key];
+		if (file) checkCsrfExport(file, key, warnings);
+	}
+	for (const [name, file] of Object.entries(node.statusFiles ?? {})) checkCsrfExport(file, name, warnings);
+	for (const [name, file] of Object.entries(node.metadataRoutes ?? {})) checkCsrfExport(file, name, warnings);
+	for (const child of node.children) checkCsrfExports(child, warnings);
+	for (const slot of Object.values(node.slots)) checkCsrfExports(slot, warnings);
+}
+function checkCsrfExport(file, convention, warnings) {
+	if (!isScriptExtension(file.extension)) return;
+	const found = getCsrfExport(file.filePath);
+	if (found === "absent") return;
+	const isRoute = convention === "route.ts";
+	if (isRoute && found === "exempt") return;
+	warnings.push({
+		id: `CSRF_EXPORT_INVALID:${file.filePath}`,
+		summary: isRoute ? `route.ts csrf export must be exactly \`export const csrf = false\`: ${file.filePath}` : `\`csrf\` can only be exported from route.ts, not ${convention}: ${file.filePath}`,
+		details: `  File: ${file.filePath}\n\n` + (isRoute ? "  The CSRF gate reads this export from source before any module loads, so only\n  the literal form counts. Other values, `let`, and re-exports are not read.\n\n  To fix: write `export const csrf = false;` in this file, or remove the export.\n" : "  The per-route CSRF exemption applies only to route.ts handlers. Pages, layouts\n  and server actions always get the CSRF check.\n\n  To fix: remove the export. To accept a cross-site POST, handle it in a route.ts\n  that exports `const csrf = false`.\n"),
+		level: "error"
+	});
+}
+/**
+* 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).
+*
+* `.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 (!isScriptExtension(file.extension)) 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"
+	});
+}
+/**
+* Error when middleware.ts appears inside a parallel slot subtree.
+*
+* Middleware is collected from the main matched segment chain only
+* (route-matcher.ts `collectMiddlewareChain`). The slot resolver never
+* walks `middleware` on its matched chain, so a middleware.ts under any
+* `@slot/` directory silently never executes. `access.ts` in slot chains
+* DOES run (via SlotAccessGate), making the asymmetry invisible unless
+* you know to look.
+*
+* This is a build error rather than a warning: the file provably cannot
+* run and its presence misleads the author into thinking the slot is
+* middleware-protected.
+*
+* See design/07-routing.md §"Parallel Routes"
+*/
+function checkSlotMiddleware(node, warnings) {
+	for (const [slotName, slotRoot] of Object.entries(node.slots)) collectSlotMiddleware(slotRoot, slotName, warnings);
+	for (const child of node.children) checkSlotMiddleware(child, warnings);
+}
+/**
+* Walk a slot subtree and report every middleware.ts found.
+*/
+function collectSlotMiddleware(node, slotName, warnings) {
+	if (node.middleware) warnings.push({
+		id: `SLOT_MIDDLEWARE:${node.middleware.filePath}`,
+		summary: `middleware.ts inside slot @${slotName} never executes: ${node.middleware.filePath}`,
+		details: `  File: ${node.middleware.filePath}\n\n  Middleware is collected from the main route chain only.\n  The slot resolver does not run middleware — this file is silently dead.\n  (access.ts in slots does run via SlotAccessGate; middleware.ts does not.)\n\n  To fix: Move the middleware logic into access.ts for slot-scoped auth,\n  or into a middleware.ts on the main route chain outside the slot.\n`,
+		level: "error"
+	});
+	for (const child of node.children) collectSlotMiddleware(child, slotName, warnings);
+	for (const [nestedSlotName, nestedSlot] of Object.entries(node.slots)) collectSlotMiddleware(nestedSlot, nestedSlotName, warnings);
+}
+/**
+* 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 { ENV_DTS_FILENAME as a, buildDirToRouteMap as c, CODEGEN_OUTPUT as i, formatConventionWarnings as n, flushCodegenWrites as o, lintConventions as r, writeRouteCodegen as s, checkAppDirExists as t };
+
+//# sourceMappingURL=convention-lint-DLmhGsRS.js.map