flamefront 0.1.0-alpha.0 → 0.1.0

package/src/vite.ts

@@ -1,6 +1,9 @@
 import fs from "node:fs"
 import path from "node:path"
 import { pathToFileURL } from "node:url"
+import { compile as compileOctane } from "octane/compiler"
+import type { Features, HastPluginList, MdastPluginList } from "satteri"
+import vitePluginSatteri, { type MdxOptions } from "vite-plugin-satteri"
 import type {
   AppDefinition,
   GeneratedHydration,
@@ -9,23 +12,56 @@ import type {
   RouteConfig,
   RouteDefinition,
 } from "./index.ts"
-import { generate, parse } from "./babel.ts"
+import { generate, parse, traverse, type Babel } from "./babel.ts"
+import { expandGlob, globDirectory, setGlobRoot } from "./glob.ts"
 import { removeExports } from "./remove-exports.ts"
+import { writeRouteImportMap } from "./typegen.ts"
+import {
+  resolveFlamefrontOutput,
+  type FlamefrontOutputOptions,
+  type ResolvedFlamefrontOutput,
+} from "./output.ts"
+
+export type {
+  FlamefrontAdapter,
+  FlamefrontOutputOptions,
+  FlamefrontTarget,
+  ResolvedFlamefrontOutput,
+} from "./output.ts"
 
 export const remixRoutesId = "virtual:flamefront/remix-routes"
 const resolvedRemixRoutesId = `\0${remixRoutesId}`
 
 export const serverRoutesId = "virtual:flamefront/server-routes"
 const resolvedServerRoutesId = `\0${serverRoutesId}`
+
+export const serverEntryId = "virtual:flamefront/server-entry"
+const resolvedServerEntryId = `\0${serverEntryId}`
 const hydrationRouteId = "/@flamefront/hydration-route.tsrx"
 const resolvedHydrationRoutePrefix = `${hydrationRouteId}?`
+const markdownRouteId = "/@flamefront/markdown-route.tsrx"
+const resolvedMarkdownRoutePrefix = `${markdownRouteId}?`
 const SERVER_ONLY_ROUTE_EXPORTS = ["loader"] as const
 const serverFilePattern = /\.server(?:\.[cm]?[jt]sx?|\.tsrx)$/
 const serverDirectoryPattern = /\/\.server\//
 
-export interface FlamefrontOptions {
+export interface FlamefrontOptions extends FlamefrontOutputOptions {
   /** Project-root route manifest module. */
   readonly routes?: string
+  /** Built-in Markdown and MDX compiler configuration. */
+  readonly markdown?: false | MarkdownOptions
+}
+
+export interface MarkdownOptions {
+  /** Parser feature toggles. GFM and frontmatter are enabled by default. */
+  readonly features?: Features
+  /** MDAST plugins shared by Markdown and MDX entries. */
+  readonly mdastPlugins?: MdastPluginList
+  /** HAST plugins shared by Markdown and MDX entries. */
+  readonly hastPlugins?: HastPluginList
+  /** MDX compiler options; its JSX import source is always `octane`. */
+  readonly mdx?:
+    boolean | Omit<MdxOptions, "jsxImportSource" | "jsx" | "jsxRuntime">
 }
 
 function quote(value: string): string {
@@ -61,10 +97,24 @@ function hydrationComponentId(
   return `${hydrationRouteId}?${parameters}`
 }
 
+function markdownComponentId(entry: string): string {
+  const parameters = new URLSearchParams({
+    entry,
+    "flamefront-markdown": "1",
+  })
+
+  return `${markdownRouteId}?${parameters}`
+}
+
 function browserRouteModuleId(routeDefinition: RouteDefinition): string {
+  const componentEntry =
+    routeDefinition.content === "markdown"
+      ? markdownComponentId(routeDefinition.entry)
+      : routeDefinition.entry
+
   return generatesHydrationBoundary(routeDefinition)
-    ? hydrationComponentId(routeDefinition.entry, routeDefinition.hydration)
-    : routeDefinition.entry
+    ? hydrationComponentId(componentEntry, routeDefinition.hydration)
+    : componentEntry
 }
 
 function generatedRouteId(kind: "layout" | "route", location: string): string {
@@ -99,7 +149,7 @@ function generatedRouteMetadata(
     parent,
     path: config.path,
     render: config.render,
-    navigation: config.render === "static" ? "fragment" : "router",
+    navigation: config.render === "client" ? "router" : "fragment",
     hydration: config.hydration,
   }
 }
@@ -117,7 +167,7 @@ function generateRoutePreloaders(routeTree: readonly RouteConfig[]): string {
         continue
       }
 
-      if (config.render === "static") {
+      if (config.render !== "client") {
         continue
       }
 
@@ -155,33 +205,35 @@ function lazyRoute(
 ): string {
   const { entry } = routeDefinition
   const browserLoader =
-    routeDefinition.render === "static"
-      ? "loadStaticRouteFragment"
-      : "loadRouteData"
-  const browserLoaderExpression = `(args) => ${browserLoader}(args, ${JSON.stringify(routing)})`
+    routeDefinition.render === "client" ? "loadRouteData" : "loadRouteFragment"
+  const browserLoaderExpression =
+    routeDefinition.render === "client"
+      ? `(args) => ${browserLoader}(args, ${JSON.stringify(routing)})`
+      : `(args) => ${browserLoader}(args, ${JSON.stringify(routing)}, ${quote(routeDefinition.render)})`
 
-  if (routeDefinition.render === "static") {
+  if (routeDefinition.render !== "client") {
     const componentId = browserRouteModuleId(routeDefinition)
 
-    return `async () => { if (import.meta.env.SSR) { const [routeModule, componentModule] = await Promise.all([import(${quote(entry)}), import(${quote(componentId)})]); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: routeModule.loader }; } const componentModule = await import(${quote(componentId)}); return { Component: createStaticFragmentRoute({ metadata: ${JSON.stringify(metadata)}, routing: ${JSON.stringify(routing)}, fallbackComponent: componentModule.default }), loader: ${browserLoaderExpression} }; }`
+    return `async () => { if (import.meta.env.SSR) { const [routeModule, componentModule] = await Promise.all([import(${quote(entry)}), import(${quote(componentId)})]); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: routeModule.loader }; } const componentModule = await import(${quote(componentId)}); return { Component: createRouteFragmentRoute({ metadata: ${JSON.stringify(metadata)}, routing: ${JSON.stringify(routing)}, policy: ${quote(routeDefinition.render)}, fallbackComponent: componentModule.default }), loader: ${browserLoaderExpression} }; }`
   }
 
   if (routeDefinition.render === "client") {
-    return `async () => { if (import.meta.env.SSR) return {}; const routeModule = await import(${quote(entry)}); return { Component: createRouteBoundary(routeModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression} }; }`
-  }
+    if (routeDefinition.content === "markdown") {
+      const componentId = browserRouteModuleId(routeDefinition)
 
-  if (!generatesHydrationBoundary(routeDefinition)) {
-    return `async () => { const routeModule = await import(${quote(entry)}); return { Component: createRouteBoundary(routeModule.default, ${JSON.stringify(metadata)}), loader: import.meta.env.SSR ? routeModule.loader : ${browserLoaderExpression} }; }`
-  }
+      return `async () => { if (import.meta.env.SSR) return {}; const componentModule = await import(${quote(componentId)}); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression} }; }`
+    }
 
-  const componentId = hydrationComponentId(entry, routeDefinition.hydration)
+    return `async () => { if (import.meta.env.SSR) return {}; const routeModule = await import(${quote(entry)}); return { Component: createRouteBoundary(routeModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression} }; }`
+  }
 
-  return `async () => { if (import.meta.env.SSR) { const [routeModule, componentModule] = await Promise.all([import(${quote(entry)}), import(${quote(componentId)})]); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: routeModule.loader }; } const componentModule = await import(${quote(componentId)}); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression} }; }`
+  throw new Error(`Unsupported route render mode ${routeDefinition.render}.`)
 }
 
 function collectRouteMetadata(
   routeTree: readonly RouteConfig[],
   shell: string,
+  shellHydration: AppDefinition["shellHydration"],
 ): readonly GeneratedRouteMetadata[] {
   const rootId = "flamefront:shell:root"
   const metadata: GeneratedRouteMetadata[] = [
@@ -191,6 +243,7 @@ function collectRouteMetadata(
       kind: "shell",
       entry: shell,
       navigation: "router",
+      hydration: shellHydration,
     },
   ]
 
@@ -243,12 +296,19 @@ function generateConfigs(
 }
 
 export function generateRemixRoutes(
-  app: Pick<AppDefinition, "shell" | "routeTree" | "routing">,
+  app: Pick<
+    AppDefinition,
+    "shell" | "shellHydration" | "routeTree" | "routing"
+  >,
 ): string {
   const rootId = "flamefront:shell:root"
-  const routeMetadata = collectRouteMetadata(app.routeTree, app.shell)
+  const routeMetadata = collectRouteMetadata(
+    app.routeTree,
+    app.shell,
+    app.shellHydration,
+  )
 
-  return `// Generated by Flamefront.\nimport Shell from ${quote(app.shell)};\nimport { RouterDocument } from 'flamefront/octane/router-document';\nimport { createRouteBoundary, createStaticFragmentRoute } from 'flamefront/fragment';\nimport { loadRouteData, loadStaticRouteFragment } from 'flamefront/remix-router/data';\n\nexport { RouterDocument };\nexport const routing = ${JSON.stringify(app.routing)};\nexport const routeMetadata = ${JSON.stringify(routeMetadata)};\n\nexport const routes = [\n\t{\n\t\tid: ${quote(rootId)},\n\t\tComponent: createRouteBoundary(Shell, ${JSON.stringify(routeMetadata[0])}),\n\t\thandle: { flamefront: ${JSON.stringify(routeMetadata[0])} },\n\t\tchildren: [\n${generateConfigs(app.routeTree, app.routing, 3)}\n\t\t],\n\t},\n];\n\n${generateRoutePreloaders(app.routeTree)}`
+  return `// Generated by Flamefront.\nimport Shell from ${quote(app.shell)};\nimport { RouterDocument } from 'flamefront/octane/router-document';\nimport { createRouteBoundary, createRouteFragmentRoute } from 'flamefront/fragment';\nimport { loadRouteData, loadRouteFragment } from 'flamefront/remix-router/data';\n\nexport { RouterDocument };\nexport const routing = ${JSON.stringify(app.routing)};\nexport const routeMetadata = ${JSON.stringify(routeMetadata)};\n\nexport const routes = [\n\t{\n\t\tid: ${quote(rootId)},\n\t\tComponent: createRouteBoundary(Shell, ${JSON.stringify(routeMetadata[0])}),\n\t\thandle: { flamefront: ${JSON.stringify(routeMetadata[0])} },\n\t\tchildren: [\n${generateConfigs(app.routeTree, app.routing, 3)}\n\t\t],\n\t},\n];\n\n${generateRoutePreloaders(app.routeTree)}`
 }
 
 /** Generate the server-only route-module importer used by loader endpoints. */
@@ -263,6 +323,15 @@ export function generateServerRoutes(
   return `// Generated by Flamefront.\nconst routeModules = {\n${imports}\n};\n\nexport async function importRoute(entry) {\n\tconst importModule = routeModules[entry];\n\tif (!importModule) throw new Error(\`No Vite route module was generated for \${entry}.\`);\n\treturn importModule();\n}\n`
 }
 
+/** Generate the server-entry import selected by `flamefront({...})`. */
+export function generateServerEntry(output: ResolvedFlamefrontOutput): string {
+  if (output.adapter === "srvx") {
+    return `// Generated by Flamefront.\nexport { createSrvxServerEntry as createServerEntry } from "flamefront/srvx";\n`
+  }
+
+  return `// Generated by Flamefront.\nexport { createFetchServerEntry as createServerEntry } from "flamefront/fetch";\n`
+}
+
 function hydrationStrategy(hydration: GeneratedHydration | "none"): {
   readonly importName: string
   readonly expression: string
@@ -297,6 +366,11 @@ function hydrationStrategy(hydration: GeneratedHydration | "none"): {
   }
 }
 
+/** Generate the component adapter used when a route entry exports HTML. */
+export function generateMarkdownRoute(entry: string): string {
+  return `import html from ${quote(entry)};\n\nexport default function MarkdownRoute() @{\n\t<div dangerouslySetInnerHTML={{ __html: html }} />\n}\n`
+}
+
 export function generateHydrationRoute(
   entry: string,
   hydration: GeneratedHydration | "none",
@@ -316,7 +390,9 @@ interface ResolveOptions extends TransformOptions {
 }
 
 interface PluginContext {
-  readonly environment?: { readonly config?: { readonly consumer?: string } }
+  readonly environment?: {
+    readonly config?: { readonly command?: string; readonly consumer?: string }
+  }
   resolve(
     id: string,
     importer: string | undefined,
@@ -346,6 +422,139 @@ function cleanModuleId(id: string): string {
   return id.split("?", 1)[0].replaceAll("\\", "/")
 }
 
+interface ManifestGlobTransform {
+  readonly code: string
+  readonly map: null
+  readonly directories: readonly string[]
+}
+
+interface TextReplacement {
+  readonly end: number
+  readonly start: number
+  readonly text: string
+}
+
+function staticStringArgument(
+  argument: Babel.Node | undefined,
+): string | undefined {
+  if (!argument) {
+    return undefined
+  }
+
+  if (argument.type === "StringLiteral") {
+    return argument.value
+  }
+
+  if (
+    argument.type === "TemplateLiteral" &&
+    argument.expressions.length === 0
+  ) {
+    return argument.quasis[0]?.value.cooked ?? ""
+  }
+
+  return undefined
+}
+
+function transformManifestGlobs(
+  source: string,
+  id: string,
+  root: string,
+): ManifestGlobTransform | null {
+  const ast = parse(source, {
+    sourceFilename: id,
+    sourceType: "module",
+    plugins: ["typescript", "jsx"],
+  })
+  const globBindings = new Set<string>()
+
+  traverse(ast, {
+    ImportDeclaration(path) {
+      if (path.node.source.value !== "flamefront") {
+        return
+      }
+
+      for (const specifier of path.node.specifiers) {
+        if (specifier.type !== "ImportSpecifier") {
+          continue
+        }
+
+        const imported = specifier.imported
+        const importedName =
+          imported.type === "Identifier" ? imported.name : imported.value
+
+        if (importedName === "glob") {
+          globBindings.add(specifier.local.name)
+        }
+      }
+    },
+  })
+
+  if (globBindings.size === 0) {
+    return null
+  }
+
+  const replacements: TextReplacement[] = []
+  const directories = new Set<string>()
+
+  traverse(ast, {
+    CallExpression(path) {
+      const callee = path.node.callee
+
+      if (callee.type !== "Identifier" || !globBindings.has(callee.name)) {
+        return
+      }
+
+      const argument = path.node.arguments[0]
+      const pattern = staticStringArgument(argument)
+
+      if (pattern === undefined) {
+        throw new TypeError(
+          `flamefront glob() in ${id} requires a string-literal pattern.`,
+        )
+      }
+
+      if (
+        typeof argument?.start !== "number" ||
+        typeof argument.end !== "number"
+      ) {
+        throw new TypeError(`flamefront glob() in ${id} has no source range.`)
+      }
+
+      const files = expandGlob(root, pattern)
+
+      replacements.push({
+        start: argument.start,
+        end: argument.end,
+        text: JSON.stringify(files),
+      })
+      directories.add(globDirectory(root, pattern))
+    },
+  })
+
+  if (replacements.length === 0) {
+    return null
+  }
+
+  const code = [...replacements]
+    .sort((left, right) => right.start - left.start)
+    .reduce(
+      (result, replacement) =>
+        `${result.slice(0, replacement.start)}${replacement.text}${result.slice(replacement.end)}`,
+      source,
+    )
+
+  return { code, map: null, directories: [...directories] }
+}
+
+function isPathWithinDirectory(directory: string, candidate: string): boolean {
+  const relative = path.relative(directory, candidate)
+
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  )
+}
+
 function isServerEnvironment(
   context: PluginContext,
   options?: TransformOptions,
@@ -474,10 +683,12 @@ export function removeServerRouteExports(source: string, id = "route.js") {
 }
 
 export function flamefront(options: FlamefrontOptions = {}) {
+  const output = resolveFlamefrontOutput(options)
   let root = process.cwd()
   let serverBuild = false
   let appPromise: Promise<AppDefinition> | undefined
   let manifestRevision = 0
+  let manifestGlobDirectories: readonly string[] = []
   const manifestId = options.routes ?? "/src/app.ts"
   const manifestPath = () =>
     path.resolve(
@@ -488,6 +699,7 @@ export function flamefront(options: FlamefrontOptions = {}) {
     const manifestUrl = new URL(pathToFileURL(manifestPath()))
 
     manifestUrl.searchParams.set("flamefront", String(manifestRevision))
+    setGlobRoot(root)
     appPromise ??= import(manifestUrl.href).then((module) => {
       const app = module.app ?? module.default
 
@@ -507,6 +719,8 @@ export function flamefront(options: FlamefrontOptions = {}) {
     new Set(
       (await loadRoutes()).map((route) => resolveRouteEntry(root, route.entry)),
     )
+  const generateTypes = async () =>
+    writeRouteImportMap(await loadApp(), { root })
   const configureRoot = (config: { readonly root: string }) => {
     root = config.root
   }
@@ -515,7 +729,22 @@ export function flamefront(options: FlamefrontOptions = {}) {
     name: "flamefront:framework-modules",
     enforce: "pre" as const,
     configResolved: configureRoot,
-    handleHotUpdate(context: {
+    async buildStart() {
+      await generateTypes()
+    },
+    transform(source: string, id: string) {
+      if (cleanModuleId(id) !== manifestPath()) {
+        return null
+      }
+
+      const transformed = transformManifestGlobs(source, id, root)
+
+      manifestGlobDirectories = transformed?.directories ?? []
+      return transformed
+        ? { code: transformed.code, map: transformed.map }
+        : null
+    },
+    async handleHotUpdate(context: {
       file: string
       server: {
         moduleGraph: {
@@ -524,13 +753,39 @@ export function flamefront(options: FlamefrontOptions = {}) {
         }
       }
     }) {
-      if (context.file !== manifestPath()) {
+      const manifestChanged = context.file === manifestPath()
+      const globChanged = manifestGlobDirectories.some((directory) =>
+        isPathWithinDirectory(directory, context.file),
+      )
+
+      if (!manifestChanged && !globChanged) {
         return
       }
 
       manifestRevision += 1
       appPromise = undefined
-      for (const moduleId of [resolvedRemixRoutesId, resolvedServerRoutesId]) {
+      try {
+        await generateTypes()
+      } catch {
+        // Keep the previous declarations while an edited manifest is invalid.
+        // Vite will report the manifest error when the virtual route modules
+        // are requested, but a stale type file must not block editing.
+      }
+
+      if (globChanged) {
+        const manifestModule =
+          context.server.moduleGraph.getModuleById(manifestPath())
+
+        if (manifestModule) {
+          context.server.moduleGraph.invalidateModule(manifestModule)
+        }
+      }
+
+      for (const moduleId of [
+        resolvedRemixRoutesId,
+        resolvedServerRoutesId,
+        resolvedServerEntryId,
+      ]) {
         const generatedModule =
           context.server.moduleGraph.getModuleById(moduleId)
 
@@ -553,6 +808,14 @@ export function flamefront(options: FlamefrontOptions = {}) {
         return resolvedServerRoutesId
       }
 
+      if (id === serverEntryId) {
+        return resolvedServerEntryId
+      }
+
+      if (id === "flamefront/entry") {
+        return resolvedServerEntryId
+      }
+
       if (
         id === "./hydration-route.tsrx?octane-hydrate=0" &&
         importer?.startsWith(resolvedHydrationRoutePrefix)
@@ -569,6 +832,10 @@ export function flamefront(options: FlamefrontOptions = {}) {
         return id
       }
 
+      if (id.startsWith(resolvedMarkdownRoutePrefix)) {
+        return id
+      }
+
       if (
         resolveOptions.scan ||
         isServerEnvironment(this, resolveOptions) ||
@@ -619,6 +886,10 @@ export function flamefront(options: FlamefrontOptions = {}) {
         return generateServerRoutes(await loadApp())
       }
 
+      if (id === resolvedServerEntryId) {
+        return generateServerEntry(output)
+      }
+
       if (id.startsWith(resolvedHydrationRoutePrefix)) {
         const parameters = new URLSearchParams(id.slice(id.indexOf("?") + 1))
         const entry = parameters.get("entry")
@@ -636,6 +907,17 @@ export function flamefront(options: FlamefrontOptions = {}) {
         )
       }
 
+      if (id.startsWith(resolvedMarkdownRoutePrefix)) {
+        const parameters = new URLSearchParams(id.slice(id.indexOf("?") + 1))
+        const entry = parameters.get("entry")
+
+        if (!entry) {
+          throw new TypeError("Flamefront Markdown route is missing its entry.")
+        }
+
+        return generateMarkdownRoute(entry)
+      }
+
       return null
     },
   }
@@ -689,5 +971,60 @@ export function flamefront(options: FlamefrontOptions = {}) {
     },
   }
 
-  return [frameworkModulesPlugin, routeModulePlugin] as const
+  const markdownPlugin =
+    options.markdown === false
+      ? undefined
+      : vitePluginSatteri({
+          ...(options.markdown ?? {}),
+          features: {
+            gfm: true,
+            frontmatter: true,
+            ...options.markdown?.features,
+          },
+          mdx:
+            options.markdown?.mdx === false
+              ? false
+              : {
+                  ...(typeof options.markdown?.mdx === "object"
+                    ? options.markdown.mdx
+                    : {}),
+                  jsx: true,
+                  jsxImportSource: "octane",
+                  jsxRuntime: "automatic",
+                },
+        })
+
+  const mdxCompilerPlugin =
+    options.markdown === false || options.markdown?.mdx === false
+      ? undefined
+      : {
+          name: "flamefront:markdown-mdx",
+          async transform(
+            this: PluginContext,
+            source: string,
+            id: string,
+            transformOptions?: TransformOptions,
+          ): Promise<{ code: string; map: object | null } | null> {
+            if (!cleanModuleId(id).endsWith(".mdx")) {
+              return null
+            }
+
+            const server = isServerEnvironment(this, transformOptions)
+            const command = this.environment?.config?.command
+            const compiled = compileOctane(source, id, {
+              dev: command === "serve",
+              hmr: command === "serve" && !server ? "vite" : false,
+              mode: server ? "server" : "client",
+            })
+
+            return { code: compiled.code, map: compiled.map }
+          },
+        }
+
+  return [
+    frameworkModulesPlugin,
+    routeModulePlugin,
+    markdownPlugin,
+    mdxCompilerPlugin,
+  ] as const
 }