@tschk/moonshine-compiler 0.4.1 → 0.4.4

package/src/compile-graph.ts

@@ -0,0 +1,215 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { join, posix, resolve } from "node:path";
+
+export type CrepusGraphTarget = "moonshine-dom" | "moonshine-ssr";
+export type CrepusGraph = {
+  entry: string;
+  files: Array<{ path: string; source: string }>;
+};
+const extensions = [".ts", ".tsx", ".js", ".jsx"];
+const componentExtensions = [".svelte", ".vue"];
+export function validateNativeRuntimeImport(specifier: string): void {
+  if (
+    /^(?:(?:react|react-dom|solid-js|svelte|vue)(?:\/|$)|@vue\/(?:reactivity|runtime-core|runtime-dom|shared|server-renderer)(?:\/|$))/.test(
+      specifier,
+    )
+  )
+    throw new Error(
+      `Unsupported native runtime import ${JSON.stringify(specifier)}; Crepus must lower host primitives to Moonshine or reject them`,
+    );
+}
+function fail(message: string): never {
+  throw new Error(`Invalid Crepus module graph: ${message}`);
+}
+function relativePath(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    !value.includes("\\") &&
+    !value.includes(String.fromCharCode(0)) &&
+    !/^(?:\/|[a-z]:|file:)/i.test(value) &&
+    value
+      .split("/")
+      .every((part) => part !== "" && part !== "." && part !== "..")
+  );
+}
+async function regularFile(directory: string, path: string): Promise<string> {
+  const absolute = resolve(directory, path);
+  let current = resolve(directory);
+  const directoryStat = await lstat(current);
+  if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory())
+    fail("graph directory must be a real directory");
+  const parts = path.split("/");
+  for (let index = 0; index < parts.length; index++) {
+    current = join(current, parts[index]!);
+    const stat = await lstat(current);
+    if (stat.isSymbolicLink()) fail(`symlink: ${path}`);
+    if (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory())
+      fail(`not a regular file: ${path}`);
+  }
+  return readFile(absolute, "utf8");
+}
+
+/** Read only the explicitly inventoried, target-specific compiler module graph. */
+export async function readCrepusGraph(
+  directory: string,
+  target: CrepusGraphTarget,
+): Promise<CrepusGraph | undefined> {
+  const manifestPath = "crepus-module-manifest.json";
+  try {
+    await lstat(join(directory, manifestPath));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  const manifest = JSON.parse(await regularFile(directory, manifestPath));
+  const entry = `CrepusEmit.${target}.ts`;
+  const prefix = `modules/${target}/`;
+  if (
+    !manifest ||
+    manifest.version !== 1 ||
+    manifest.target !== target ||
+    manifest.entry !== entry ||
+    !relativePath(manifest.sourceEntry) ||
+    ![...extensions, ...componentExtensions].includes(
+      posix.extname(manifest.sourceEntry).toLowerCase(),
+    ) ||
+    !Array.isArray(manifest.files)
+  )
+    fail("unsupported manifest schema, version, target or entry");
+  const paths = new Set<string>();
+  for (const path of manifest.files) {
+    if (
+      !relativePath(path) ||
+      (path !== entry && !path.startsWith(prefix)) ||
+      !extensions.includes(posix.extname(path).toLowerCase())
+    )
+      fail(`unsupported file path: ${String(path)}`);
+    if (paths.has(path)) fail(`duplicate file: ${path}`);
+    paths.add(path);
+  }
+  const sourceModule =
+    manifest.sourceModule === undefined
+      ? prefix +
+        (componentExtensions.includes(
+          posix.extname(manifest.sourceEntry).toLowerCase(),
+        )
+          ? manifest.sourceEntry + ".ts"
+          : manifest.sourceEntry)
+      : manifest.sourceModule;
+  if (
+    !relativePath(sourceModule) ||
+    !sourceModule.startsWith(prefix) ||
+    !paths.has(entry) ||
+    !paths.has(sourceModule)
+  )
+    fail("entry or sourceEntry is not listed");
+  if (manifest.assets !== undefined && !Array.isArray(manifest.assets))
+    fail("assets must be an array");
+  const assets = new Map<string, string>();
+  for (const path of manifest.assets ?? []) {
+    if (
+      !relativePath(path) ||
+      !path.startsWith(prefix) ||
+      posix.extname(path) !== ".css" ||
+      paths.has(path) ||
+      assets.has(path)
+    )
+      fail(`unsupported or duplicate CSS asset: ${String(path)}`);
+    assets.set(path, await regularFile(directory, path));
+  }
+  await validateCSSAssets(assets, prefix, directory);
+  const files: CrepusGraph["files"] = [];
+  let sourceReferenced = false;
+  for (const path of paths) {
+    const source = await regularFile(directory, path);
+    const loader = posix.extname(path).slice(1).toLowerCase() as
+      "ts" | "tsx" | "js" | "jsx";
+    const transpiler = new Bun.Transpiler({ loader });
+    transpiler.transformSync(source);
+    for (const dependency of transpiler.scan(source).imports) {
+      const specifier = dependency.path;
+      validateNativeRuntimeImport(specifier);
+      if (
+        specifier.includes("\\") ||
+        specifier.includes(String.fromCharCode(0)) ||
+        /^(?:\/|[a-z]:|file:)/i.test(specifier)
+      )
+        fail(`unsupported import ${JSON.stringify(specifier)} in ${path}`);
+      if (!specifier.startsWith(".")) continue;
+      const base = posix.normalize(posix.join(posix.dirname(path), specifier));
+      if (!base.startsWith(prefix))
+        fail(`import escapes target modules: ${specifier}`);
+      const candidates = assets.has(base)
+        ? [base]
+        : posix.extname(base)
+          ? [base]
+          : extensions.flatMap((extension) => [
+              base + extension,
+              `${base}/index${extension}`,
+            ]);
+      const matches = candidates.filter(
+        (candidate) => paths.has(candidate) || assets.has(candidate),
+      );
+      if (matches.length !== 1)
+        fail(
+          `missing or ambiguous listed import ${JSON.stringify(specifier)} in ${path}`,
+        );
+      if (path === entry && matches[0] === sourceModule)
+        sourceReferenced = true;
+    }
+    files.push({ path, source });
+  }
+  // Legacy manifests cannot identify allocator-remapped SFC entry modules.
+  if (manifest.sourceModule !== undefined && !sourceReferenced)
+    fail("entry does not reference sourceEntry module");
+  files.push(...Array.from(assets, ([path, source]) => ({ path, source })));
+  return { entry, files };
+}
+
+/** Parse CSS with Bun while resolving exclusively from the already checked inventory. */
+async function validateCSSAssets(
+  assets: Map<string, string>,
+  prefix: string,
+  directory: string,
+): Promise<void> {
+  if (!assets.size) return;
+  const root = await realpath(directory);
+  const result = await Bun.build({
+    root,
+    entrypoints: [...assets.keys()].map((path) => join(root, path)),
+    plugins: [
+      {
+        name: "crepus-css-inventory",
+        setup(build) {
+          build.onResolve({ filter: /.*/ }, (args) => {
+            if (args.kind === "entry-point-build") {
+              const path = posix.relative(root, args.path);
+              if (!assets.has(path)) throw new Error("Unlisted CSS entry");
+              return { path, namespace: "crepus-css" };
+            }
+            if (
+              args.kind !== "import-rule" ||
+              !args.path.startsWith(".") ||
+              args.path.includes("\\") ||
+              args.path.includes("\0")
+            )
+              throw new Error(`Unsupported CSS reference: ${args.path}`);
+            const path = posix.normalize(
+              posix.join(posix.dirname(args.importer), args.path),
+            );
+            if (!path.startsWith(prefix) || !assets.has(path))
+              throw new Error(`Unlisted CSS import: ${args.path}`);
+            return { path, namespace: "crepus-css" };
+          });
+          build.onLoad({ filter: /.*/, namespace: "crepus-css" }, (args) => ({
+            contents: assets.get(args.path)!,
+            loader: "css",
+          }));
+        },
+      },
+    ],
+  });
+  if (!result.success)
+    fail(`CSS validation failed: ${result.logs.map(String).join("; ")}`);
+}

package/src/compile-output.ts

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+import type { CrepusGraph } from "./compile-graph";
+
+async function directory(path: string): Promise<void> {
+  try {
+    await mkdir(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  const info = await lstat(path);
+  if (!info.isDirectory() || info.isSymbolicLink())
+    throw new Error(`Unsafe compiled module directory: ${path}`);
+}
+
+/** Publish immutable compiler bytes before atomically switching the public entry. */
+export async function publishCrepusGraph(
+  output: string,
+  graph: CrepusGraph,
+): Promise<void> {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify([graph.entry, graph.files]));
+  const digest = hash.digest("hex");
+  const parent = dirname(output);
+  const generated = join(parent, ".moonshine-compiled");
+  const source = join(generated, basename(output));
+  await directory(generated);
+  await directory(source);
+  const destination = join(source, digest);
+  const staged = await mkdtemp(join(source, ".pending-"));
+  try {
+    for (const file of graph.files) {
+      const path = join(staged, file.path);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, file.source);
+    }
+    try {
+      await rename(staged, destination);
+    } catch (error) {
+      if (
+        !["EEXIST", "ENOTEMPTY"].includes(
+          (error as NodeJS.ErrnoException).code ?? "",
+        )
+      )
+        throw error;
+    }
+    // A pre-existing digest is reusable only when every referenced byte matches.
+    const rootInfo = await lstat(destination);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+      throw new Error(`Unsafe compiled module directory: ${destination}`);
+    for (const file of graph.files) {
+      const parts = file.path.split("/");
+      let path = destination;
+      for (const part of parts) {
+        path = join(path, part);
+        if ((await lstat(path)).isSymbolicLink())
+          throw new Error(`Unsafe compiled module path: ${path}`);
+      }
+      if ((await readFile(path, "utf8")) !== file.source)
+        throw new Error(`Compiled module contents differ: ${path}`);
+    }
+    const entry = graph.files.find((file) => file.path === graph.entry)!;
+    const hasDefault = new Bun.Transpiler({ loader: "ts" })
+      .scan(entry.source)
+      .exports.includes("default");
+    const specifier = JSON.stringify(
+      "./" +
+        relative(parent, join(destination, graph.entry)).split(sep).join("/"),
+    );
+    const facade = `// Generated by moonshine compile; compiler modules are preserved unchanged.\nexport * from ${specifier};\n${hasDefault ? `export { default } from ${specifier};\n` : ""}`;
+    const pending = await mkdtemp(join(parent, ".moonshine-entry-"));
+    try {
+      const path = join(pending, "entry.ts");
+      await writeFile(path, facade);
+      await rename(path, output);
+    } finally {
+      await rm(pending, { recursive: true, force: true });
+    }
+  } finally {
+    await rm(staged, { recursive: true, force: true });
+  }
+}

package/src/crepus-source.ts

@@ -0,0 +1,116 @@
+import { access, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+import {
+  readCrepusGraph,
+  validateNativeRuntimeImport,
+  type CrepusGraph,
+} from "./compile-graph";
+
+export function requireCrepusCompiler(compiler?: string): string {
+  const executable = Bun.which(compiler ?? "crepus");
+  if (!executable)
+    throw new Error(
+      `Crepus compiler not found: ${compiler ?? "crepus"}; install a compiler with native emission or pass --compiler <path>`,
+    );
+  return executable;
+}
+
+/** Delegate source parsing/lowering; never writes inside the source project. */
+export async function emitCrepusSource(
+  abs: string,
+  target: "moonshine-dom" | "moonshine-ssr" | "react",
+  compiler?: string,
+  site?: string,
+): Promise<{
+  source: string;
+  ir?: { version?: number; root?: unknown[] };
+  graph?: CrepusGraph;
+}> {
+  const executable = requireCrepusCompiler(compiler);
+  const root = resolve(site ?? dirname(abs));
+  const entry = relative(root, abs);
+  if (
+    !entry ||
+    entry === ".." ||
+    entry.startsWith(`..${sep}`) ||
+    isAbsolute(entry)
+  )
+    throw new Error("Source must be a file inside --site");
+  const temporary = await mkdtemp(join(tmpdir(), "moonshine-compile-"));
+  try {
+    const child = Bun.spawn(
+      [
+        executable,
+        "web",
+        "build",
+        "--site",
+        root,
+        "--entry",
+        entry.split(sep).join("/"),
+        "--out-dir",
+        temporary,
+        "--emit",
+        target,
+      ],
+      { cwd: root, stdout: "pipe", stderr: "pipe" },
+    );
+    const [code, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    if (code !== 0)
+      throw new Error(
+        `Crepus compilation failed (exit ${code}): ${stderr || stdout}`,
+      );
+    const generated = join(
+      temporary,
+      `CrepusEmit.${target}.` + (target === "react" ? "tsx" : "ts"),
+    );
+    try {
+      await access(generated);
+    } catch {
+      throw new Error(
+        `Crepus compiler did not emit expected file: ${basename(generated)}`,
+      );
+    }
+    const graph =
+      target === "react" ? undefined : await readCrepusGraph(temporary, target);
+    const source = await readFile(generated, "utf8");
+    const transpiler = new Bun.Transpiler({
+      loader: target === "react" ? "tsx" : "ts",
+    });
+    transpiler.transformSync(source);
+    for (const dependency of transpiler.scan(source).imports) {
+      if (target !== "react") validateNativeRuntimeImport(dependency.path);
+      if (
+        !graph &&
+        /^(?:\.{1,2}(?:[\\/]|$)|[\\/]|[a-z]:|file:)/i.test(dependency.path)
+      ) {
+        throw new Error(
+          `Crepus emitted unsupported filesystem import ${JSON.stringify(dependency.path)}; companion modules/assets require an upstream asset contract`,
+        );
+      }
+    }
+    let ir: { version?: number; root?: unknown[] } | undefined;
+    try {
+      ir = JSON.parse(
+        await readFile(join(temporary, "crepus-view-ir.json"), "utf8"),
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    return { source, ir, ...(graph && { graph }) };
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/src/discover.ts

@@ -11,7 +11,7 @@ export type DiscoverOptions = {
   programmatic?: RouteDefinition[];
   /**
    * File-system routing dialect. `moonshine` is the native `src/routes` layout;
-   * the two `next-*` values read an adopted Next app in place.
+   * `next-*` and `waku` read adopted framework routes in place.
    */
   convention?: RouteConvention;
 };
@@ -149,6 +149,31 @@ function discoverNextPages(
   return raw;
 }
 
+/** Waku pages and `_api` endpoints; underscore specials are not pages. */
+function discoverWaku(files: string[], routesDir: string): RouteDefinition[] {
+  const raw: RouteDefinition[] = [];
+  for (const file of files) {
+    const rel = toPosix(relative(routesDir, file));
+    const name = basename(rel);
+    if (!ROUTE_EXT.test(name) || name.startsWith("_")) continue;
+    if (/\.(test|spec|d)\.[jt]sx?$/.test(name)) continue;
+    const base = name.replace(ROUTE_EXT, "");
+    const parts = rel.split("/").slice(0, -1);
+    const api = parts[0] === "_api";
+    const directories = api ? parts.slice(1) : parts;
+    if (directories.some((part) => part.startsWith("_"))) continue;
+    const segments = directories.map(segmentToPattern);
+    if (base !== "index") segments.push(segmentToPattern(base));
+    raw.push({
+      id: rel.replace(ROUTE_EXT, ""),
+      path: segments.length ? `/${segments.join("/")}` : "/",
+      file,
+      ...(api && { mode: "api" as const }),
+    });
+  }
+  return raw;
+}
+
 function discoverMoonshine(
   files: string[],
   routesDir: string,
@@ -219,7 +244,9 @@ export async function discoverRoutes(
       ? discoverNextApp(files, routesDir)
       : convention === "next-pages"
         ? discoverNextPages(files, routesDir)
-        : discoverMoonshine(files, routesDir);
+        : convention === "waku"
+          ? discoverWaku(files, routesDir)
+          : discoverMoonshine(files, routesDir);
 
   const merged = mergeRoutes(
     raw,

package/src/inherit.ts

@@ -1,19 +1,20 @@
 import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import type { RouteDefinition } from "@tschk/moonshine-framework";
-import { createRouteGraph } from "@tschk/moonshine-router";
+import { createRouteGraph } from "@tschk/moonshine-router/graph";
 import { toPosix } from "./path.js";
 
 type SpecialKind = "layout" | "error" | "middleware";
 
 /**
  * Moonshine names co-located specials `+layout.tsx`; the Next App Router names
- * them `layout.tsx`. Only the prefix differs, so one lookup serves both.
+ * them `layout.tsx`, and Waku uses `_layout.tsx`. Only the prefix differs.
  */
-export type RouteConvention = "moonshine" | "next-app" | "next-pages";
+export type RouteConvention = "moonshine" | "next-app" | "next-pages" | "waku";
 
 const specialPrefix: Readonly<Record<RouteConvention, string | null>> = {
   moonshine: "+",
+  waku: "_",
   "next-app": "",
   // The Pages Router has no per-directory specials; `_app` wraps everything.
   "next-pages": null,
@@ -26,6 +27,7 @@ const specialPrefix: Readonly<Record<RouteConvention, string | null>> = {
  */
 const specialKinds: Readonly<Record<RouteConvention, SpecialKind[]>> = {
   moonshine: ["layout", "error", "middleware"],
+  waku: ["layout"],
   "next-app": ["layout"],
   "next-pages": [],
 };
@@ -69,7 +71,8 @@ function applyInheritance(
   const resolvedDir = resolve(routesDir);
   const cache = new Map<string, string | undefined>();
   for (const route of routes) {
-    if (!route.file) continue;
+    if (!route.file || (convention === "waku" && route.mode === "api"))
+      continue;
     const rel = toPosix(relative(resolvedDir, resolve(route.file)));
     const dir = dirname(rel);
     const parts = dir === "." ? [] : dir.split("/").filter(Boolean);