@tschk/moonshine-compiler 0.4.0 → 0.4.4

package/src/manifest.ts

@@ -1,18 +1,28 @@
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 import type {
   MoonshineManifest,
   RouteArtifact,
   RouteDefinition,
   RuntimeTarget,
+  RenderMode,
+  RendererName,
 } from "@tschk/moonshine-framework";
 import { MANIFEST_VERSION } from "@tschk/moonshine-framework";
 import { analyzeModule } from "./analyze.js";
-import { buildBundles } from "./build.js";
+import { buildBundles, preparePublicAssets } from "./build.js";
 import { classifyRoute } from "./classify.js";
 import { discoverRoutes } from "./discover.js";
 import type { RouteConvention } from "./inherit.js";
-import { toPosix } from "./path.js";
+import { canonicalPath, toPosix } from "./path.js";
 
 export type BuildOptions = {
   projectDir: string;
@@ -21,11 +31,59 @@ export type BuildOptions = {
   programmatic?: RouteDefinition[];
   runtime?: RuntimeTarget;
   convention?: RouteConvention;
+  renderer?: RendererName;
+  requestContext?: boolean;
+  mode?: RenderMode;
 };
 
 function toProjectRelative(projectDir: string, p: string): string {
-  const rel = toPosix(relative(projectDir, resolve(p)));
-  return rel.startsWith("..") ? toPosix(p) : rel || ".";
+  const normalize = (path: string) => (sep === "\\" ? toPosix(path) : path);
+  const rel = normalize(relative(projectDir, resolve(p)));
+  return rel.startsWith("..") ? normalize(p) : rel || ".";
+}
+
+function contains(directory: string, path: string): boolean {
+  const rel = relative(directory, path);
+  return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + sep);
+}
+
+async function validateOutput(
+  projectDir: string,
+  routesDir: string,
+  outDir: string,
+  routes: RouteArtifact[],
+): Promise<void> {
+  const [project, sourceRoutes, output] = await Promise.all(
+    [projectDir, routesDir, outDir].map(canonicalPath),
+  );
+  if (contains(output!, project!))
+    throw new Error("Build output must not contain the project directory");
+  if (contains(output!, sourceRoutes!) || contains(sourceRoutes!, output!))
+    throw new Error("Build output and route source directory must not overlap");
+  const files = new Set(
+    routes
+      .flatMap((route) => [
+        route.file,
+        route.clientFile,
+        route.dataFile,
+        route.errorBoundary,
+        ...(route.layouts ?? []),
+        ...(route.middleware ?? []),
+      ])
+      .filter((file): file is string => Boolean(file)),
+  );
+  for (const file of files) {
+    const [target, parent] = await Promise.all([
+      canonicalPath(file),
+      canonicalPath(dirname(file)),
+    ]);
+    if (
+      contains(outDir, file) ||
+      contains(output!, target) ||
+      contains(output!, join(parent, basename(file)))
+    )
+      throw new Error(`Build output must not contain source file: ${file}`);
+  }
 }
 
 async function resolveFrameworkVersion(): Promise<string> {
@@ -55,12 +113,13 @@ function sortedStringify(value: unknown): string {
 
 function deriveCapabilities(
   routes: RouteArtifact[],
+  native: boolean,
 ): MoonshineManifest["capabilities"] {
   const capabilities: Set<MoonshineManifest["capabilities"][number]> =
     new Set();
-  capabilities.add("streaming");
+  if (!native) capabilities.add("streaming");
   for (const route of routes) {
-    if (route.mode === "island" || route.mode === "spa") {
+    if (route.mode === "island" || (!native && route.mode === "spa")) {
       capabilities.add("islands");
     }
     if (route.runtime === "cloudflare" || route.runtime === "vercel-edge") {
@@ -75,7 +134,10 @@ function deriveCapabilities(
 
 function makeStaticOutput(route: RouteArtifact): string | undefined {
   if (route.mode !== "static") return undefined;
-  if (route.path.includes("*")) return undefined;
+  // Parameterized paths (`:slug`, `:tab?`, `*rest`) cannot be prerendered as
+  // a single file; a slug like `blog-:slug.html` would be served for every
+  // match.
+  if (route.path.includes("*") || route.path.includes(":")) return undefined;
   const slug =
     route.path === "/"
       ? "index"
@@ -92,10 +154,31 @@ export async function buildProject(
   );
   const outDir = resolve(options.outDir ?? join(projectDir, ".moonshine"));
   const runtime = options.runtime ?? "bun";
+  if (options.requestContext && !["bun", "node"].includes(runtime)) {
+    throw new Error(
+      "Request context currently supports only Bun and Node runtimes",
+    );
+  }
 
   const rawRoutes = await discoverRoutes({
     routesDir,
-    programmatic: options.programmatic,
+    programmatic: options.programmatic?.map((route) => ({
+      ...route,
+      file: resolve(projectDir, route.file),
+      ...(route.clientFile && {
+        clientFile: resolve(projectDir, route.clientFile),
+      }),
+      ...(route.dataFile && { dataFile: resolve(projectDir, route.dataFile) }),
+      ...(route.layouts && {
+        layouts: route.layouts.map((file) => resolve(projectDir, file)),
+      }),
+      ...(route.middleware && {
+        middleware: route.middleware.map((file) => resolve(projectDir, file)),
+      }),
+      ...(route.errorBoundary && {
+        errorBoundary: resolve(projectDir, route.errorBoundary),
+      }),
+    })),
     ...(options.convention && { convention: options.convention }),
   });
 
@@ -108,8 +191,38 @@ export async function buildProject(
   const buildRoutes: RouteArtifact[] = [];
   for (let i = 0; i < rawRoutes.length; i++) {
     const route = rawRoutes[i];
+    if (options.requestContext && (route.runtime ?? runtime) !== runtime) {
+      throw new Error(
+        "Request-context routes must match the configured server runtime",
+      );
+    }
     const facts = analyzeModule(route.file, undefined, rawRouteTexts[i]);
-    const decision = classifyRoute({ explicit: route.mode, facts });
+    const decision = classifyRoute({
+      explicit: route.mode ?? options.mode,
+      facts,
+    });
+    if (options.renderer === "native") {
+      if (!["bun", "node", "cloudflare"].includes(route.runtime ?? runtime)) {
+        throw new Error(
+          "Native renderer currently supports only the Bun, Node and Cloudflare runtimes",
+        );
+      }
+      if (decision.mode === "island") {
+        throw new Error(
+          `Native route "${route.path}" cannot use island mode: hydration is not implemented`,
+        );
+      }
+      if ((decision.mode === "spa" || facts.interactive) && !route.clientFile) {
+        throw new Error(
+          `Native interactive route "${route.path}" requires an explicit clientFile`,
+        );
+      }
+      if (route.clientFile && decision.mode !== "spa") {
+        throw new Error(
+          `Native route "${route.path}" with clientFile must use spa mode`,
+        );
+      }
+    }
     buildRoutes.push({
       ...route,
       mode: decision.mode,
@@ -124,6 +237,15 @@ export async function buildProject(
     } as RouteArtifact);
   }
 
+  if (
+    options.renderer === "native" &&
+    new Set(buildRoutes.map((route) => route.runtime)).size > 1
+  ) {
+    throw new Error("Native routes must use one server runtime per build");
+  }
+
+  await validateOutput(projectDir, routesDir, outDir, buildRoutes);
+  const publicAssets = await preparePublicAssets(projectDir, outDir);
   await rm(outDir, { recursive: true, force: true });
   await mkdir(outDir, { recursive: true });
 
@@ -131,12 +253,26 @@ export async function buildProject(
     root: projectDir,
     outDir,
     routes: buildRoutes,
+    renderer: options.renderer,
+    requestContext: options.requestContext,
+    publicAssets,
   });
   const clientFile = bundles.entryFiles.client;
 
   for (const route of buildRoutes) {
     if ((route.mode === "island" || route.mode === "spa") && clientFile) {
-      route.clientEntries = [clientFile];
+      route.clientEntries = [
+        options.renderer === "native"
+          ? bundles.routeClientEntries[route.id]!
+          : clientFile,
+      ];
+    }
+    if (
+      options.renderer === "native" &&
+      Object.hasOwn(bundles.routeClientStyles, route.id) &&
+      bundles.routeClientStyles[route.id]!.length
+    ) {
+      route.clientStyles = bundles.routeClientStyles[route.id];
     }
     route.serverEntry = bundles.entryFiles.server;
   }
@@ -148,9 +284,14 @@ export async function buildProject(
   const manifest: MoonshineManifest = {
     version: MANIFEST_VERSION,
     frameworkVersion: await resolveFrameworkVersion(),
+    ...(options.renderer && { renderer: options.renderer }),
+    ...(options.requestContext && { requestContext: true }),
     routes: buildRoutes.map((route) => ({
       ...route,
       file: toProjectRelative(projectDir, route.file),
+      ...(route.clientFile && {
+        clientFile: toProjectRelative(projectDir, route.clientFile),
+      }),
       ...(route.dataFile && {
         dataFile: toProjectRelative(projectDir, route.dataFile),
       }),
@@ -171,7 +312,10 @@ export async function buildProject(
       ...(bundles.entryFiles.server && { server: bundles.entryFiles.server }),
       ...(clientFile && { client: clientFile }),
     },
-    capabilities: deriveCapabilities(buildRoutes),
+    capabilities: deriveCapabilities(
+      buildRoutes,
+      options.renderer === "native",
+    ),
   };
 
   await writeFile(join(outDir, "manifest.json"), sortedStringify(manifest));

package/src/path.ts

@@ -1,3 +1,19 @@
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
 export function toPosix(p: string): string {
   return p.replace(/\\/g, "/");
 }
+
+/** Resolve existing symlink ancestors even when the final path does not exist yet. */
+export async function canonicalPath(path: string): Promise<string> {
+  const absolute = resolve(path);
+  try {
+    return await realpath(absolute);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const parent = dirname(absolute);
+    if (parent === absolute) throw error;
+    return join(await canonicalPath(parent), basename(absolute));
+  }
+}

package/src/source.ts

@@ -0,0 +1,8 @@
+export { emitCrepusSource, requireCrepusCompiler } from "./crepus-source";
+export {
+  readCrepusGraph,
+  validateNativeRuntimeImport,
+  type CrepusGraph,
+  type CrepusGraphTarget,
+} from "./compile-graph";
+export { publishCrepusGraph } from "./compile-output";

package/test/analyze.test.ts

@@ -1,146 +0,0 @@
-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

@@ -1,99 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { join } from "node:path";
-import { analyzeModule, classifyRoute } from "../src";
-
-const fixtureDir = join(import.meta.dir, "fixtures", "modes");
-
-function fixture(name: string): string {
-  return join(fixtureDir, name);
-}
-
-describe("classifyRoute", () => {
-  test("honors explicit override", () => {
-    const facts = analyzeModule(fixture("static.tsx"));
-    const decision = classifyRoute({ explicit: "island", facts });
-    expect(decision).toEqual({
-      mode: "island",
-      reason: "explicit route configuration",
-    });
-  });
-
-  test("selects api for handler export", () => {
-    const facts = analyzeModule(fixture("api.ts"));
-    expect(facts.exportsHandler).toBe(true);
-    expect(classifyRoute({ facts })).toEqual({
-      mode: "api",
-      reason: "exports request handler",
-    });
-  });
-
-  test("selects spa for root client boundary", () => {
-    const facts = analyzeModule(fixture("client.client.tsx"));
-    expect(facts.clientBoundary).toBe(true);
-    expect(classifyRoute({ facts })).toEqual({
-      mode: "spa",
-      reason: "route root is a client boundary",
-    });
-  });
-
-  test("selects ssr for request-bound loader", () => {
-    const facts = analyzeModule(fixture("loader.ts"));
-    expect(facts.requestBound).toBe(true);
-    expect(facts.exportsLoader).toBe(true);
-    expect(classifyRoute({ facts })).toEqual({
-      mode: "ssr",
-      reason: "uses request-time server data",
-    });
-  });
-
-  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);
-    expect(classifyRoute({ facts })).toEqual({
-      mode: "island",
-      reason: "contains an interactive client subtree",
-    });
-  });
-
-  test("selects static for deterministic module", () => {
-    const facts = analyzeModule(fixture("static.tsx"));
-    expect(classifyRoute({ facts })).toEqual({
-      mode: "static",
-      reason: "deterministic build-time route",
-    });
-  });
-
-  test("falls back to ssr for unresolved dynamic import", () => {
-    const facts = analyzeModule(fixture("unresolved.ts"));
-    expect(facts.unresolvedDynamicImport).toBe(true);
-    expect(classifyRoute({ facts })).toEqual({
-      mode: "ssr",
-      reason: "dynamic behavior could not be resolved safely",
-    });
-  });
-
-  test("produces deterministic output", () => {
-    const path = fixture("static.tsx");
-    const first = classifyRoute({ facts: analyzeModule(path) });
-    const second = classifyRoute({ facts: analyzeModule(path) });
-    expect(JSON.stringify(first)).toBe(JSON.stringify(second));
-  });
-});

package/test/client-process-env.test.ts

@@ -1,73 +0,0 @@
-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";
-
-/**
- * A browser bundle must not carry a bare `process` reference into a page.
- *
- * Client code and its dependencies routinely read `process.env.X`. `process`
- * does not exist in a browser, so the reference throws while the client entry
- * module is still evaluating — before any component renders and before any
- * error boundary can mount. The page stays blank and the console stays empty,
- * which is close to undiagnosable from the outside.
- */
-
-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("client bundle process shim", () => {
-  test("defines globalThis.process before any module code runs", async () => {
-    await buildProject({ projectDir });
-
-    const client = await Bun.file(join(outDir, "public", "client.js")).text();
-
-    expect(client.startsWith("globalThis.process ??= { env: {} };")).toBe(true);
-  });
-
-  test("evaluating the bundle does not throw on a process.env read", async () => {
-    await buildProject({ projectDir });
-
-    const client = await Bun.file(join(outDir, "public", "client.js")).text();
-    // The banner is the whole fix, so assert it actually guards a real read
-    // rather than trusting that the fixture still contains one.
-    expect(client).toContain("process.env");
-
-    // Evaluate the banner in isolation with no ambient `process`, which is what
-    // a browser gives the bundle.
-    const scope: Record<string, unknown> = {};
-    const run = new Function(
-      "globalThis",
-      "return (globalThis.process ??= { env: {} });",
-    );
-    expect(run(scope)).toEqual({ env: {} });
-  });
-
-  test("does not overwrite an environment injected ahead of the bundle", async () => {
-    // Apps prepend their own public values; `??=` must leave those intact.
-    const scope: Record<string, unknown> = { process: { env: { A: "1" } } };
-    const run = new Function(
-      "globalThis",
-      "return (globalThis.process ??= { env: {} });",
-    );
-    expect(run(scope)).toEqual({ env: { A: "1" } });
-  });
-
-  test("the server bundle is left alone", async () => {
-    await buildProject({ projectDir });
-
-    const server = await Bun.file(join(outDir, "dist", "server.js")).text();
-
-    // Bun and Node both have a real `process`; shimming it there would mask
-    // genuine environment problems at runtime.
-    expect(server.startsWith("globalThis.process ??=")).toBe(false);
-  });
-});

package/test/discover.test.ts

@@ -1,76 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { join } from "node:path";
-import { discoverRoutes } from "../src/discover";
-
-const fixtureDir = join(import.meta.dir, "fixtures", "routes");
-
-function layoutPath() {
-  return join(fixtureDir, "+layout.tsx");
-}
-
-function middlewarePath() {
-  return join(fixtureDir, "+middleware.ts");
-}
-
-function errorPath() {
-  return join(fixtureDir, "+error.tsx");
-}
-
-describe("discoverRoutes", () => {
-  test("discovers exact route IDs and paths", async () => {
-    const routes = await discoverRoutes({ routesDir: fixtureDir });
-    expect(routes.map((r) => r.id)).toEqual([
-      "index",
-      "about",
-      "account/[[tab]]",
-      "api/health",
-      "blog/[slug]",
-      "docs/[...path]",
-    ]);
-    expect(routes.map((r) => r.path)).toEqual([
-      "/",
-      "/about",
-      "/account/:tab?",
-      "/api/health",
-      "/blog/:slug",
-      "/docs/*path",
-    ]);
-  });
-
-  test("inherits layout, middleware, and nearest error boundary", async () => {
-    const routes = await discoverRoutes({ routesDir: fixtureDir });
-    for (const route of routes) {
-      expect(route.layouts).toEqual([layoutPath()]);
-      expect(route.middleware).toEqual([middlewarePath()]);
-      expect(route.errorBoundary).toBe(errorPath());
-    }
-  });
-
-  test("pairs a route with its data file", async () => {
-    const routes = await discoverRoutes({ routesDir: fixtureDir });
-    const blog = routes.find((r) => r.id === "blog/[slug]");
-    expect(blog).toBeDefined();
-    expect(blog!.dataFile).toBe(join(fixtureDir, "blog", "[slug].data.ts"));
-  });
-
-  test("marks server files as API mode", async () => {
-    const routes = await discoverRoutes({ routesDir: fixtureDir });
-    const api = routes.find((r) => r.id === "api/health");
-    expect(api).toBeDefined();
-    expect(api!.mode).toBe("api");
-  });
-
-  test("produces deterministic sorted output", async () => {
-    const first = await discoverRoutes({ routesDir: fixtureDir });
-    const second = await discoverRoutes({ routesDir: fixtureDir });
-    expect(JSON.stringify(first)).toBe(JSON.stringify(second));
-    expect(first.map((r) => r.path)).toEqual([
-      "/",
-      "/about",
-      "/account/:tab?",
-      "/api/health",
-      "/blog/:slug",
-      "/docs/*path",
-    ]);
-  });
-});

package/test/fixtures/modes/api.ts

@@ -1,3 +0,0 @@
-export function GET(_request: Request) {
-  return Response.json({ ok: true });
-}