flamefront 0.0.0 → 0.1.0

package/src/typegen.ts

@@ -0,0 +1,207 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+import type { AppDefinition } from "./index.ts"
+import { setGlobRoot } from "./glob.ts"
+
+/** Directory containing declarations generated for the current application. */
+export const flamefrontTypesDirectory = ".flamefront/types"
+
+/** Declaration file containing the authored route-to-module relationship. */
+export const routeImportMapFile = "route-import-map.d.ts"
+
+/** Declaration file containing the built-in Markdown module shapes. */
+export const markdownModuleTypesFile = "markdown-modules.d.ts"
+
+export interface RouteImportMapGenerationOptions {
+  /** Project root used to resolve project-root route module IDs. */
+  readonly root?: string
+  /** Destination used to calculate relative import specifiers. */
+  readonly outputFile?: string
+}
+
+export interface TypegenProjectOptions {
+  /** Project root containing the route manifest. */
+  readonly root?: string
+  /** Project-root route manifest module, defaulting to `/src/app.ts`. */
+  readonly routes?: string
+  /** Optional declaration destination, relative to `root` unless absolute. */
+  readonly outputFile?: string
+}
+
+export interface RouteImportMapWriteResult {
+  readonly file: string
+  readonly source: string
+  readonly written: boolean
+}
+
+export interface TypegenProjectResult extends RouteImportMapWriteResult {
+  readonly manifest: string
+}
+
+interface AppModule {
+  readonly app?: AppDefinition
+  readonly default?: AppDefinition
+}
+
+let manifestRevision = 0
+
+function outputPath(root: string, outputFile: string | undefined): string {
+  return path.resolve(
+    root,
+    outputFile ?? `${flamefrontTypesDirectory}/${routeImportMapFile}`,
+  )
+}
+
+function manifestPath(root: string, routes: string): string {
+  const relativeRoutes = routes.startsWith("/") ? `.${routes}` : routes
+
+  return path.resolve(root, relativeRoutes)
+}
+
+function cleanRouteEntry(entry: string): string {
+  return entry.split(/[?#]/, 1)[0] ?? entry
+}
+
+function routeImportSpecifier(
+  root: string,
+  outputFile: string,
+  entry: string,
+): string {
+  const routeEntry = cleanRouteEntry(entry)
+  const projectEntry = routeEntry.startsWith("/")
+    ? routeEntry.slice(1)
+    : routeEntry
+  const absoluteEntry = path.resolve(root, projectEntry)
+  const relativeEntry = path
+    .relative(path.dirname(outputFile), absoluteEntry)
+    .split(path.sep)
+    .join("/")
+
+  return relativeEntry.startsWith(".") ? relativeEntry : `./${relativeEntry}`
+}
+
+/**
+ * Generate the declaration-only module augmentation for an authored route
+ * manifest. The module values deliberately remain `typeof import(...)` so
+ * changes to a route module's exports flow through without regenerating this
+ * relationship.
+ */
+export function generateRouteImportMap(
+  app: Pick<AppDefinition, "routes">,
+  options: RouteImportMapGenerationOptions = {},
+): string {
+  const root = path.resolve(options.root ?? process.cwd())
+  const file = outputPath(root, options.outputFile)
+  const entries = app.routes
+    .map(
+      (route) =>
+        `    ${JSON.stringify(route.path)}: typeof import(${JSON.stringify(
+          routeImportSpecifier(root, file, route.entry),
+        )})`,
+    )
+    .join("\n")
+
+  return `// Generated by Flamefront. Do not edit.\ndeclare module "flamefront" {\n  interface RouteImportMap {\n${entries}\n  }\n}\n\nexport {}\n`
+}
+
+/** Generate ambient declarations for Vite Markdown and MDX imports. */
+export function generateMarkdownModuleTypes(): string {
+  return `// Generated by Flamefront. Do not edit.\ndeclare module "*.md" {\n  const html: string\n  export default html\n  export { html }\n  export const frontmatter: Record<string, unknown>\n}\n\ndeclare module "*.mdx" {\n  const Component: unknown\n  export default Component\n  export const frontmatter: Record<string, unknown>\n}\n`
+}
+
+async function readExisting(file: string): Promise<string | undefined> {
+  try {
+    return await readFile(file, "utf8")
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined
+    }
+
+    throw error
+  }
+}
+
+async function writeAtomically(file: string, source: string): Promise<void> {
+  const temporaryFile = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`
+
+  try {
+    await writeFile(temporaryFile, source, "utf8")
+    await rename(temporaryFile, file)
+  } finally {
+    await unlink(temporaryFile).catch(() => undefined)
+  }
+}
+
+/** Write generated declarations only when their contents have changed. */
+export async function writeRouteImportMap(
+  app: Pick<AppDefinition, "routes">,
+  options: RouteImportMapGenerationOptions = {},
+): Promise<RouteImportMapWriteResult> {
+  const root = path.resolve(options.root ?? process.cwd())
+  const file = outputPath(root, options.outputFile)
+  const source = generateRouteImportMap(app, {
+    ...options,
+    root,
+    outputFile: file,
+  })
+  const existing = await readExisting(file)
+
+  const markdownTypesFile = path.join(
+    path.dirname(file),
+    markdownModuleTypesFile,
+  )
+  const markdownTypesSource = generateMarkdownModuleTypes()
+  const existingMarkdownTypes = await readExisting(markdownTypesFile)
+  const routeMapChanged = existing !== source
+  const markdownTypesChanged = existingMarkdownTypes !== markdownTypesSource
+
+  if (routeMapChanged) {
+    await mkdir(path.dirname(file), { recursive: true })
+    await writeAtomically(file, source)
+  }
+
+  if (markdownTypesChanged) {
+    await mkdir(path.dirname(markdownTypesFile), { recursive: true })
+    await writeAtomically(markdownTypesFile, markdownTypesSource)
+  }
+
+  return { file, source, written: routeMapChanged || markdownTypesChanged }
+}
+
+async function loadManifest(
+  root: string,
+  routes: string,
+): Promise<{ app: AppDefinition; manifest: string }> {
+  const manifest = manifestPath(root, routes)
+  const url = pathToFileURL(manifest)
+
+  manifestRevision += 1
+  url.searchParams.set("flamefront-typegen", String(manifestRevision))
+  setGlobRoot(root)
+  const module = (await import(url.href)) as AppModule
+  const app = module.app ?? module.default
+
+  if (!app || typeof app.shell !== "string" || !Array.isArray(app.routes)) {
+    throw new Error(
+      `${manifest} must export an app with a shell and routes array.`,
+    )
+  }
+
+  return { app, manifest }
+}
+
+/** Evaluate the project manifest and generate its route import declarations. */
+export async function generateProjectTypes(
+  options: TypegenProjectOptions = {},
+): Promise<TypegenProjectResult> {
+  const root = path.resolve(options.root ?? process.cwd())
+  const routes = options.routes ?? "/src/app.ts"
+  const loaded = await loadManifest(root, routes)
+  const generated = await writeRouteImportMap(loaded.app, {
+    root,
+    outputFile: options.outputFile,
+  })
+
+  return { ...generated, manifest: loaded.manifest }
+}

package/src/virtual-remix-routes.d.ts

@@ -0,0 +1,35 @@
+declare module "virtual:flamefront/remix-routes" {
+  import type { RouteObject } from "@octanejs/remix-router"
+  import type { RouterDocument as RouterDocumentComponent } from "./octane.tsx"
+  import type {
+    GeneratedRouteMetadata,
+    NormalizedRoutingOptions,
+  } from "./index.ts"
+
+  export const RouterDocument: RouterDocumentComponent
+  export const routes: RouteObject[]
+  export const routing: NormalizedRoutingOptions
+  export const routeMetadata: readonly GeneratedRouteMetadata[]
+  export function preloadRoute(entry: string): Promise<void>
+}
+
+declare module "virtual:flamefront/server-routes" {
+  import type { RouteModule } from "./server.ts"
+
+  export function importRoute(entry: string): Promise<RouteModule>
+}
+
+declare module "virtual:flamefront/server-entry" {
+  import type { RouteDefinition } from "./index.ts"
+  import type {
+    FetchServerEntryOptions,
+    FlamefrontFetchServerEntry,
+  } from "./fetch.ts"
+  import type { FlamefrontServerEntry, SrvxServerEntryOptions } from "./srvx.ts"
+
+  export function createServerEntry<
+    Route extends RouteDefinition = RouteDefinition,
+  >(
+    options: FetchServerEntryOptions<Route> | SrvxServerEntryOptions<Route>,
+  ): FlamefrontFetchServerEntry | FlamefrontServerEntry
+}