@tschk/moonshine-compiler 0.3.5 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tschk/moonshine-compiler",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "license": "ISC",
   "type": "module",
   "main": "./src/index.ts",
@@ -15,8 +15,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@tschk/moonshine-framework": "^0.3.5",
-    "@tschk/moonshine-router": "^0.3.5"
+    "@tschk/moonshine-framework": "^0.3.6",
+    "@tschk/moonshine-router": "^0.3.6"
   },
   "devDependencies": {
     "@types/bun": "1.3.14",

package/src/analyze.ts

@@ -22,12 +22,16 @@ const HTTP_METHODS = [
   "HEAD",
 ];
 
-function getSourceFile(file: string, program?: ts.Program): ts.SourceFile {
+function getSourceFile(
+  file: string,
+  program?: ts.Program,
+  sourceText?: string,
+): ts.SourceFile {
   if (program) {
     const source = program.getSourceFile(file);
     if (source) return source;
   }
-  const text = readFileSync(file, "utf8");
+  const text = sourceText ?? readFileSync(file, "utf8");
   const scriptKind = file.endsWith(".tsx")
     ? ts.ScriptKind.TSX
     : ts.ScriptKind.TS;
@@ -48,14 +52,6 @@ function isUseClientDirective(source: ts.SourceFile, node: ts.Node): boolean {
 }
 
 function isExportedName(node: ts.Node, name: string): boolean {
-  const flags = ts.getCombinedModifierFlags(node as ts.Declaration);
-  if (!(flags & ts.ModifierFlags.Export)) return false;
-  if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) {
-    return node.name?.text === name;
-  }
-  if (ts.isVariableDeclaration(node)) {
-    if (ts.isIdentifier(node.name)) return node.name.text === name;
-  }
   if (
     ts.isExportDeclaration(node) &&
     node.exportClause &&
@@ -65,6 +61,16 @@ function isExportedName(node: ts.Node, name: string): boolean {
       if (elem.name.text === name) return true;
     }
   }
+
+  const flags = ts.getCombinedModifierFlags(node as ts.Declaration);
+  if (!(flags & ts.ModifierFlags.Export)) return false;
+
+  if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) {
+    return node.name?.text === name;
+  }
+  if (ts.isVariableDeclaration(node)) {
+    if (ts.isIdentifier(node.name)) return node.name.text === name;
+  }
   return false;
 }
 
@@ -76,14 +82,51 @@ function isExportedHandler(node: ts.Node): boolean {
   return false;
 }
 
+/** Module names that mean "this route reads per-request state". */
+const REQUEST_BOUND_MODULES = new Set(["cookies", "headers", "request"]);
+
+/** Bindings that mean the same thing whatever module they came from. */
+const REQUEST_BOUND_BINDINGS = new Set([
+  "cookies",
+  "headers",
+  "draftMode",
+  "request",
+]);
+
+/**
+ * The last path segment, lowercased, with any extension removed:
+ * `"./lib/Request.ts"` -> `"request"`, `"next/headers"` -> `"headers"`.
+ */
+function moduleTailName(specifier: string): string {
+  const tail = specifier.toLowerCase().split("/").pop() ?? "";
+  return tail.replace(/\.[cm]?[jt]sx?$/, "");
+}
+
+function importedBindingNames(node: ts.ImportDeclaration): string[] {
+  const bindings = node.importClause?.namedBindings;
+  if (!bindings || !ts.isNamedImports(bindings)) return [];
+  return bindings.elements.map(
+    (element) => (element.propertyName ?? element.name).text,
+  );
+}
+
+/**
+ * Whether an import pulls in per-request state, which forces the route to `ssr`.
+ *
+ * This compared the whole specifier with `includes`, so `./lib/request-utils`,
+ * `./headers-config` or any path with a matching substring anywhere demoted a
+ * prerenderable route to per-request rendering — silently, since the route
+ * still worked. The segment is now compared whole, and the imported binding
+ * names are checked too, so `import { cookies } from "@acme/ssr"` is caught
+ * even though nothing in that specifier says so.
+ */
 function isRequestBoundImport(node: ts.Node): boolean {
   if (!ts.isImportDeclaration(node)) return false;
   if (!ts.isStringLiteral(node.moduleSpecifier)) return false;
-  const text = node.moduleSpecifier.text.toLowerCase();
-  return (
-    text.includes("cookies") ||
-    text.includes("headers") ||
-    text.includes("request")
+  if (REQUEST_BOUND_MODULES.has(moduleTailName(node.moduleSpecifier.text)))
+    return true;
+  return importedBindingNames(node).some((name) =>
+    REQUEST_BOUND_BINDINGS.has(name),
   );
 }
 
@@ -119,8 +162,12 @@ function getFileSuffix(file: string): "server" | "client" | undefined {
   return undefined;
 }
 
-export function analyzeModule(file: string, program?: ts.Program): ModuleFacts {
-  const source = getSourceFile(file, program);
+export function analyzeModule(
+  file: string,
+  program?: ts.Program,
+  sourceText?: string,
+): ModuleFacts {
+  const source = getSourceFile(file, program, sourceText);
   const suffix = getFileSuffix(file);
   const facts: ModuleFacts = {
     clientBoundary: suffix === "client",

package/src/build.ts

@@ -63,6 +63,32 @@ function generateServerEntry(
       : ""
   }`);
   }
+  // Layouts, middleware, and error boundaries are route dependencies the server
+  // renders through, so they belong in the bundle alongside the pages. Without
+  // them the renderer falls back to `await import(file)` on their SOURCE paths,
+  // which only resolves where the source tree sits next to the build output —
+  // never in a deployed image, and never on a runtime that cannot resolve a
+  // dynamic import at all. A page would render locally and 500 in production.
+  const supportFiles: string[] = [];
+  for (const route of routes) {
+    for (const file of [
+      ...(route.layouts ?? []),
+      ...(route.middleware ?? []),
+      ...(route.errorBoundary ? [route.errorBoundary] : []),
+    ]) {
+      if (file && !supportFiles.includes(file)) supportFiles.push(file);
+    }
+  }
+  for (let i = 0; i < supportFiles.length; i++) {
+    const file = supportFiles[i]!;
+    imports.push(
+      `import * as support_${i} from "${importPath(buildDir, file)}";`,
+    );
+    // Registered unwrapped: these export a component or middleware, not a route
+    // module with loader/action semantics.
+    moduleBodys.push(`  "${toPosix(file)}": support_${i}`);
+  }
+
   return `${imports.join("\n")}\n\n${moduleHelpers.join("\n")}\n\nconst ${routes.map((_, i) => `module_${i} = makeModule_${i}(route_${i}, ${routes[i]!.dataFile ? `data_${i}` : "undefined"})`).join(";\nconst ")};\n\nexport const routes = {\n${bodies.join(",\n")}\n};\n\nexport const modules = {\n${moduleBodys.join(",\n")}\n};\n`;
 }
 

package/src/discover.ts

@@ -153,15 +153,24 @@ function discoverMoonshine(
   files: string[],
   routesDir: string,
 ): RouteDefinition[] {
-  const fileSet = new Set(files);
   const raw: RouteDefinition[] = [];
+  const dataFiles = new Map<string, string>();
+  const routeFiles: string[] = [];
 
   for (const file of files) {
+    if (isDataFile(file)) {
+      const prefix = file.slice(0, file.lastIndexOf(".data."));
+      if (!dataFiles.has(prefix)) dataFiles.set(prefix, file);
+    } else {
+      routeFiles.push(file);
+    }
+  }
+
+  for (const file of routeFiles) {
     const rel = toPosix(relative(routesDir, file));
     const dir = dirname(rel);
     const name = basename(rel);
 
-    if (isDataFile(name)) continue;
     if (name.startsWith("+")) continue;
 
     const parsed = parseRouteFile(name);
@@ -177,14 +186,8 @@ function discoverMoonshine(
         ? `/${[dirPattern, basePattern].filter(Boolean).join("/")}`
         : "/";
 
-    const dataFile = (() => {
-      const parent = dirname(file);
-      for (const ext of [".data.ts", ".data.tsx"]) {
-        const candidate = join(parent, `${base}${ext}`);
-        if (fileSet.has(candidate)) return candidate;
-      }
-      return undefined;
-    })();
+    const prefix = file.slice(0, file.length - name.length) + base;
+    const dataFile = dataFiles.get(prefix);
 
     const mode: RenderMode | undefined =
       suffix === "server" ? "api" : undefined;

package/src/inherit.ts

@@ -35,15 +35,29 @@ function findSpecial(
   dir: string,
   kind: SpecialKind,
   convention: RouteConvention,
+  cache: Map<string, string | undefined>,
 ): string | undefined {
+  const cacheKey = `${dir}\0${kind}`;
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
+
   const prefix = specialPrefix[convention];
-  if (prefix === null) return undefined;
-  if (!specialKinds[convention].includes(kind)) return undefined;
+  if (prefix === null) {
+    cache.set(cacheKey, undefined);
+    return undefined;
+  }
+  if (!specialKinds[convention].includes(kind)) {
+    cache.set(cacheKey, undefined);
+    return undefined;
+  }
   const base = join(routesDir, dir, `${prefix}${kind}`);
   for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
     const candidate = `${base}${ext}`;
-    if (existsSync(candidate)) return candidate;
+    if (existsSync(candidate)) {
+      cache.set(cacheKey, candidate);
+      return candidate;
+    }
   }
+  cache.set(cacheKey, undefined);
   return undefined;
 }
 
@@ -53,6 +67,7 @@ function applyInheritance(
   convention: RouteConvention,
 ): void {
   const resolvedDir = resolve(routesDir);
+  const cache = new Map<string, string | undefined>();
   for (const route of routes) {
     if (!route.file) continue;
     const rel = toPosix(relative(resolvedDir, resolve(route.file)));
@@ -70,11 +85,29 @@ function applyInheritance(
     let errorBoundary: string | undefined;
 
     for (const ancestor of ancestors) {
-      const layout = findSpecial(resolvedDir, ancestor, "layout", convention);
+      const layout = findSpecial(
+        resolvedDir,
+        ancestor,
+        "layout",
+        convention,
+        cache,
+      );
       if (layout) layouts.push(layout);
-      const mw = findSpecial(resolvedDir, ancestor, "middleware", convention);
+      const mw = findSpecial(
+        resolvedDir,
+        ancestor,
+        "middleware",
+        convention,
+        cache,
+      );
       if (mw) middleware.push(mw);
-      const err = findSpecial(resolvedDir, ancestor, "error", convention);
+      const err = findSpecial(
+        resolvedDir,
+        ancestor,
+        "error",
+        convention,
+        cache,
+      );
       if (err) errorBoundary = err;
     }
 

package/src/manifest.ts

@@ -99,9 +99,16 @@ export async function buildProject(
     ...(options.convention && { convention: options.convention }),
   });
 
+  const rawRouteTexts = await Promise.all(
+    rawRoutes.map((route) =>
+      readFile(route.file, "utf8").catch(() => undefined),
+    ),
+  );
+
   const buildRoutes: RouteArtifact[] = [];
-  for (const route of rawRoutes) {
-    const facts = analyzeModule(route.file);
+  for (let i = 0; i < rawRoutes.length; i++) {
+    const route = rawRoutes[i];
+    const facts = analyzeModule(route.file, undefined, rawRouteTexts[i]);
     const decision = classifyRoute({ explicit: route.mode, facts });
     buildRoutes.push({
       ...route,

package/test/analyze.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { analyzeModule } from "../src/analyze.js";
+
+function analyzeSource(sourceCode: string, filename = "test.tsx") {
+  const program = {
+    getSourceFile: (file: string) => {
+      if (file === filename) {
+        return ts.createSourceFile(
+          filename,
+          sourceCode,
+          ts.ScriptTarget.Latest,
+          true,
+          filename.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+        );
+      }
+      return undefined;
+    },
+  } as unknown as ts.Program;
+
+  return analyzeModule(filename, program);
+}
+
+describe("analyzeModule", () => {
+  test("detects clientBoundary from 'use client' directive", () => {
+    const facts = analyzeSource(
+      "'use client';\nexport default function App() {}",
+    );
+    expect(facts.clientBoundary).toBe(true);
+  });
+
+  test("detects clientBoundary from file suffix", () => {
+    const facts = analyzeSource(
+      "export default function App() {}",
+      "app.client.tsx",
+    );
+    expect(facts.clientBoundary).toBe(true);
+  });
+
+  test("detects serverOnly from file suffix", () => {
+    const facts = analyzeSource(
+      "export default function App() {}",
+      "app.server.tsx",
+    );
+    expect(facts.serverOnly).toBe(true);
+  });
+
+  test("detects exportsHandler from 'handler' export", () => {
+    const facts = analyzeSource("export function handler() {}");
+    expect(facts.exportsHandler).toBe(true);
+  });
+
+  test("detects exportsHandler from HTTP method exports", () => {
+    expect(analyzeSource("export const GET = () => {}").exportsHandler).toBe(
+      true,
+    );
+    expect(analyzeSource("export function POST() {}").exportsHandler).toBe(
+      true,
+    );
+    expect(analyzeSource("export { myFunc as PUT }").exportsHandler).toBe(true);
+  });
+
+  test("does not detect exportsHandler for non-exported methods", () => {
+    const facts = analyzeSource("function GET() {}");
+    expect(facts.exportsHandler).toBe(false);
+  });
+
+  test("detects exportsLoader", () => {
+    const facts = analyzeSource("export const loader = async () => {}");
+    expect(facts.exportsLoader).toBe(true);
+  });
+
+  test("detects exportsAction", () => {
+    const facts = analyzeSource("export function action() {}");
+    expect(facts.exportsAction).toBe(true);
+  });
+
+  test("detects requestBound from specific module imports", () => {
+    expect(
+      analyzeSource("import { anything } from 'next/headers'").requestBound,
+    ).toBe(true);
+    expect(
+      analyzeSource("import { something } from './cookies.ts'").requestBound,
+    ).toBe(true);
+    expect(analyzeSource("import { xyz } from 'request'").requestBound).toBe(
+      true,
+    );
+  });
+
+  test("detects requestBound from specific binding imports", () => {
+    expect(
+      analyzeSource("import { cookies } from 'any-module'").requestBound,
+    ).toBe(true);
+    expect(
+      analyzeSource("import { headers, other } from 'some-module'")
+        .requestBound,
+    ).toBe(true);
+    expect(
+      analyzeSource("import { draftMode } from 'utils'").requestBound,
+    ).toBe(true);
+    expect(analyzeSource("import { request } from 'core'").requestBound).toBe(
+      true,
+    );
+  });
+
+  test("does not detect requestBound for unrelated imports", () => {
+    const facts = analyzeSource("import { useState } from 'react'");
+    expect(facts.requestBound).toBe(false);
+  });
+
+  test("detects interactive from JSX event attributes", () => {
+    const facts = analyzeSource(
+      "export default function Btn() { return <button onClick={() => {}}>Click</button> }",
+    );
+    expect(facts.interactive).toBe(true);
+  });
+
+  test("detects interactive from island calls", () => {
+    expect(analyzeSource("island(Component)").interactive).toBe(true);
+    expect(analyzeSource("myLib.island(Component)").interactive).toBe(true);
+  });
+
+  test("detects unresolvedDynamicImport", () => {
+    const facts = analyzeSource("const moduleName = 'fs'; import(moduleName);");
+    expect(facts.unresolvedDynamicImport).toBe(true);
+  });
+
+  test("does not detect unresolvedDynamicImport for string literals", () => {
+    const facts = analyzeSource("import('fs');");
+    expect(facts.unresolvedDynamicImport).toBe(false);
+  });
+
+  test("returns default facts for empty module", () => {
+    const facts = analyzeSource("");
+    expect(facts).toEqual({
+      clientBoundary: false,
+      serverOnly: false,
+      exportsHandler: false,
+      exportsLoader: false,
+      exportsAction: false,
+      requestBound: false,
+      interactive: false,
+      unresolvedDynamicImport: false,
+    });
+  });
+});

package/test/classify.test.ts

@@ -46,6 +46,24 @@ describe("classifyRoute", () => {
     });
   });
 
+  test("a module whose name merely contains 'request' is not request-bound", () => {
+    // `./request-utils` demoted this route to ssr because the specifier was
+    // compared with `includes`. Nothing broke, it just stopped prerendering.
+    const facts = analyzeModule(fixture("near-miss.tsx"));
+    expect(facts.requestBound).toBe(false);
+    expect(classifyRoute({ facts }).mode).not.toBe("ssr");
+  });
+
+  test("request-bound bindings are caught whatever module they came from", () => {
+    // The specifier says nothing about cookies; the binding does.
+    const facts = analyzeModule(fixture("renamed-source.tsx"));
+    expect(facts.requestBound).toBe(true);
+    expect(classifyRoute({ facts })).toEqual({
+      mode: "ssr",
+      reason: "uses request-time server data",
+    });
+  });
+
   test("selects island for interactive child", () => {
     const facts = analyzeModule(fixture("interactive.tsx"));
     expect(facts.interactive).toBe(true);

package/test/fixtures/modes/near-miss.tsx

@@ -0,0 +1,5 @@
+import { formatRequestId } from "./request-utils";
+
+export default function Page() {
+  return <p>{formatRequestId("abc")}</p>;
+}

package/test/fixtures/modes/renamed-source.tsx

@@ -0,0 +1,5 @@
+import { cookies } from "./ssr-helpers";
+
+export default function Page() {
+  return <p>{cookies().get("session")?.value}</p>;
+}

package/test/fixtures/modes/request-utils.ts

@@ -0,0 +1,3 @@
+export function formatRequestId(value: string): string {
+  return value.trim();
+}

package/test/fixtures/modes/ssr-helpers.ts

@@ -0,0 +1,5 @@
+export function cookies(): {
+  get(name: string): { value: string } | undefined;
+} {
+  return { get: () => ({ value: "session" }) };
+}

package/test/fixtures/project/src/routes/client.client.tsx

@@ -1,7 +1,7 @@
 // Reads process.env deliberately: browsers have no `process`, so this is the
 // shape that used to throw `ReferenceError: process is not defined` while the
 // client entry evaluated, leaving the page blank with no error boundary.
-const apiBase = process.env.MOONSHINE_TEST_API_BASE ?? 'unset';
+const apiBase = process.env.MOONSHINE_TEST_API_BASE ?? "unset";
 
 export default function ClientPage() {
   return <h1>client {apiBase}</h1>;

package/test/inherit.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { mergeRoutes } from "../src/inherit";
+import type { RouteDefinition } from "@tschk/moonshine-framework";
+
+export interface InheritableLayout {
+  id: string;
+  layouts: string[];
+}
+
+describe("mergeRoutes", () => {
+  test("combines nested route definitions with inheritable layouts", () => {
+    const routes: RouteDefinition[] = [
+      { id: "index", path: "/", file: "index.tsx" },
+      { id: "about", path: "/about", file: "about.tsx" },
+      { id: "nested/index", path: "/nested", file: "nested/index.tsx" },
+    ];
+
+    const layouts: InheritableLayout[] = [
+      { id: "index", layouts: ["layout.tsx"] },
+      { id: "about", layouts: ["layout.tsx"] },
+      { id: "nested/index", layouts: ["layout.tsx", "nested/layout.tsx"] },
+    ];
+
+    const merged = mergeRoutes(routes, layouts as unknown as RouteDefinition[]);
+
+    expect(merged.length).toBe(3);
+
+    const indexRoute = merged.find((r) => r.id === "index");
+    expect(indexRoute?.layouts).toEqual(["layout.tsx"]);
+
+    const aboutRoute = merged.find((r) => r.id === "about");
+    expect(aboutRoute?.layouts).toEqual(["layout.tsx"]);
+
+    const nestedRoute = merged.find((r) => r.id === "nested/index");
+    expect(nestedRoute?.layouts).toEqual(["layout.tsx", "nested/layout.tsx"]);
+  });
+
+  test("handles empty layouts gracefully", () => {
+    const routes: RouteDefinition[] = [
+      { id: "index", path: "/", file: "index.tsx" },
+    ];
+    const layouts: InheritableLayout[] = [];
+
+    const merged = mergeRoutes(routes, layouts as unknown as RouteDefinition[]);
+
+    expect(merged.length).toBe(1);
+    const indexRoute = merged.find((r) => r.id === "index");
+    expect(indexRoute?.layouts).toBeUndefined();
+  });
+});

package/test/path.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { toPosix } from "../src/path";
+
+describe("toPosix", () => {
+  test("converts Windows paths to POSIX paths", () => {
+    expect(toPosix("C:\\Users\\John\\Documents\\file.txt")).toBe(
+      "C:/Users/John/Documents/file.txt",
+    );
+  });
+
+  test("preserves already correct POSIX paths", () => {
+    expect(toPosix("/usr/local/bin/node")).toBe("/usr/local/bin/node");
+  });
+
+  test("handles empty strings", () => {
+    expect(toPosix("")).toBe("");
+  });
+
+  test("handles mixed slashes", () => {
+    expect(toPosix("foo\\bar/baz\\qux")).toBe("foo/bar/baz/qux");
+  });
+
+  test("handles consecutive backslashes", () => {
+    expect(toPosix("\\\\server\\share\\folder")).toBe("//server/share/folder");
+  });
+
+  test("handles trailing and leading backslashes", () => {
+    expect(toPosix("\\foo\\bar\\")).toBe("/foo/bar/");
+  });
+});

package/test/server-bundle-support-modules.test.ts

@@ -0,0 +1,68 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildProject } from "../src/manifest";
+
+/**
+ * The server bundle must carry every module the server renders through, not
+ * just the page.
+ *
+ * A page's layout is loaded during server rendering. When it is missing from
+ * `modules`, the renderer falls back to `await import(file)` on the layout's
+ * SOURCE path. That resolves in a checkout, where the source sits beside the
+ * build output, and fails in a deployed image that ships only the build — so
+ * the route renders locally and returns 500 in production. It also fails
+ * outright on runtimes that cannot resolve a dynamic import.
+ */
+
+const projectDir = resolve(import.meta.dir, "fixtures", "project");
+const outDir = join(projectDir, ".moonshine");
+
+function clean() {
+  if (existsSync(outDir)) rmSync(outDir, { recursive: true, force: true });
+}
+
+afterAll(clean);
+
+describe("server bundle support modules", () => {
+  test("registers the layouts its routes render through", async () => {
+    const manifest = await buildProject({ projectDir });
+
+    const layouts = [
+      ...new Set(manifest.routes.flatMap((route) => route.layouts ?? [])),
+    ];
+    expect(layouts.length).toBeGreaterThan(0);
+
+    const { modules } = await import(join(outDir, "dist", "server.js"));
+    // The bundle keys modules by their build-time absolute path, while the
+    // manifest stores them relative to the project.
+    for (const layout of layouts) {
+      expect(Object.keys(modules)).toContain(join(projectDir, layout));
+    }
+  });
+
+  test("a registered layout is the real module, not a route wrapper", async () => {
+    const manifest = await buildProject({ projectDir });
+    const layout = join(
+      projectDir,
+      manifest.routes.flatMap((route) => route.layouts ?? [])[0]!,
+    );
+
+    const { modules } = await import(join(outDir, "dist", "server.js"));
+
+    // Layouts export a component; wrapping them in loader/action semantics
+    // would make the renderer read `default` off the wrong object.
+    expect(modules[layout]).toBeDefined();
+    expect(typeof modules[layout].default).toBe("function");
+  });
+
+  test("still registers pages by id and file", async () => {
+    const manifest = await buildProject({ projectDir });
+    const route = manifest.routes[0]!;
+
+    const { modules } = await import(join(outDir, "dist", "server.js"));
+
+    expect(modules[route.id]).toBeDefined();
+    expect(modules[join(projectDir, route.file)]).toBeDefined();
+  });
+});