polen 0.11.0-next.14 → 0.11.0-next.15

package/src/api/content/scan.ts

@@ -1,5 +1,8 @@
 import { FileRouter } from '#lib/file-router'
+import { S } from '#lib/kit-temp/effect'
+import { FileSystem } from '@effect/platform'
 import { Fs, Path, Tree } from '@wollybeard/kit'
+import { Effect, Either } from 'effect'
 import matter from 'gray-matter'
 import { MetadataSchema } from './metadata.js'
 import type { Page } from './page.js'
@@ -14,104 +17,109 @@ export interface ScanResult {
  * Scan a directory for pages and extract metadata from their front matter
  * By default, hidden pages are filtered out from both the pages list and route tree.
  */
-export const scan = async (options: {
+export const scan = (options: {
   dir: string
   glob?: string
   /** Include hidden pages in the result (useful for debugging or admin interfaces) */
   includeHidden?: boolean
-}): Promise<ScanResult> => {
-  // Scan for routes
-  const routeScanResult = await FileRouter.scan({
-    dir: options.dir,
-    glob: options.glob ?? `**/*.{md,mdx}`,
-  })
+}): Effect.Effect<ScanResult, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    // Scan for routes
+    const routeScanResult = yield* FileRouter.scan({
+      dir: options.dir,
+      glob: options.glob ?? `**/*.{md,mdx}`,
+    })
+
+    // Create pages with metadata (id/parentId now come from route)
+    const allPages = yield* Effect.all(
+      routeScanResult.routes.map(route => readRoute(route)),
+    )
+
+    // Apply filtering if needed
+    const pages = options.includeHidden
+      ? allPages
+      : allPages.filter(page => !page.metadata.hidden)
+
+    // Build tree from pages using Tree.fromList
+    // Transform pages to include id/parentId at the top level for Tree.fromList
+    const pagesWithIds = pages.map(page => ({
+      ...page,
+      id: page.route.id,
+      parentId: page.route.parentId,
+    }))
 
-  // Create pages with metadata (id/parentId now come from route)
-  const allPages = await Promise.all(
-    routeScanResult.routes.map(route => readRoute(route)),
-  )
-
-  // Apply filtering if needed
-  const pages = options.includeHidden
-    ? allPages
-    : allPages.filter(page => !page.metadata.hidden)
-
-  // Build tree from pages using Tree.fromList
-  // Transform pages to include id/parentId at the top level for Tree.fromList
-  const pagesWithIds = pages.map(page => ({
-    ...page,
-    id: page.route.id,
-    parentId: page.route.parentId,
-  }))
-
-  // Handle cases where there might be multiple root nodes
-  // If all pages are at root level (no parentId), create a virtual root
-  const hasMultipleRoots = pagesWithIds.filter(p => !p.parentId).length > 1
-
-  let tree: Tree.Tree<Page>
-  if (hasMultipleRoots) {
-    // Create a virtual root node to hold all root-level pages
-    const virtualRoot: Page & { id: string; parentId: null } = {
-      route: {
-        id: `__virtual_root__`,
-        parentId: null,
-        file: {
-          path: {
-            absolute: Path.parse(``),
-            relative: Path.parse(``),
+    // Handle cases where there might be multiple root nodes
+    // If all pages are at root level (no parentId), create a virtual root
+    const hasMultipleRoots = pagesWithIds.filter(p => !p.parentId).length > 1
+
+    let tree: Tree.Tree<Page>
+    if (hasMultipleRoots) {
+      // Create a virtual root node to hold all root-level pages
+      const virtualRoot: Page & { id: string; parentId: null } = {
+        route: {
+          id: `__virtual_root__`,
+          parentId: null,
+          file: {
+            path: {
+              absolute: Path.parse(``),
+              relative: Path.parse(``),
+            },
+          },
+          logical: {
+            path: [],
           },
         },
-        logical: {
-          path: [],
-        },
-      },
-      metadata: { hidden: true },
-      id: `__virtual_root__`,
-      parentId: null,
-    }
+        metadata: { hidden: true },
+        id: `__virtual_root__`,
+        parentId: null,
+      }
 
-    // Update pages to have virtual root as parent if they don't have one
-    const pagesWithVirtualRoot = pagesWithIds.map(page => ({
-      ...page,
-      parentId: page.parentId ?? `__virtual_root__`,
-    }))
+      // Update pages to have virtual root as parent if they don't have one
+      const pagesWithVirtualRoot = pagesWithIds.map(page => ({
+        ...page,
+        parentId: page.parentId ?? `__virtual_root__`,
+      }))
 
-    tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
-  } else {
-    tree = Tree.fromList(pagesWithIds)
-  }
+      tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
+    } else {
+      tree = Tree.fromList(pagesWithIds)
+    }
 
-  return {
-    list: pages,
-    tree,
-    diagnostics: routeScanResult.diagnostics,
-  }
-}
+    return {
+      list: pages,
+      tree,
+      diagnostics: routeScanResult.diagnostics,
+    }
+  })
 
 /**
  * Read a single route file and extract metadata from its front matter
  */
-const readRoute = async (route: FileRouter.Route): Promise<Page> => {
-  const filePath = Path.format(route.file.path.absolute)
-  const fileContent = await Fs.read(filePath)
-
-  // Empty files still get default metadata (not hidden by default)
-  // This allows placeholder pages to exist in the navigation
-  if (!fileContent) {
-    return { route, metadata: { hidden: false } }
-  }
+const readRoute = (route: FileRouter.Route): Effect.Effect<Page, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const filePath = Path.format(route.file.path.absolute)
+    const fileContent = yield* fs.readFileString(filePath).pipe(
+      Effect.mapError(error => new Error(`Failed to read file ${filePath}: ${error}`)),
+    )
+
+    // Empty files still get default metadata (not hidden by default)
+    // This allows placeholder pages to exist in the navigation
+    if (!fileContent) {
+      return { route, metadata: { hidden: false } }
+    }
 
-  // Parse front matter
-  const { data } = matter(fileContent)
+    // Parse front matter
+    const { data } = matter(fileContent)
 
-  // Validate and parse the data
-  const parsed = MetadataSchema.safeParse(data)
+    // Validate and parse the data
+    const parsed = S.decodeUnknownEither(MetadataSchema)(data)
 
-  if (!parsed.success) {
-    // Log warning but continue with defaults
-    console.warn(`Invalid front matter in ${filePath}:`, parsed.error.issues)
-  }
+    if (Either.isLeft(parsed)) {
+      // Log warning but continue with defaults
+      console.warn(`Invalid front matter in ${filePath}:`, parsed.left)
+    }
 
-  const metadata = parsed.success ? parsed.data : { hidden: false }
-  return { route, metadata }
-}
+    const metadata = Either.isRight(parsed) ? parsed.right : { hidden: false }
+    return { route, metadata }
+  })

package/src/api/content/sidebar.ts

@@ -101,7 +101,7 @@ export type SidebarIndex = Record<string, Sidebar>
  *
  * @example
  * ```ts
- * const scanResult = await Content.scan({ dir: './pages' })
+ * const scanResult = await Effect.runPromise(Content.scan({ dir: './pages' }))
  * const sidebars = buildSidebarIndex(scanResult)
  * // Returns: {
  * //   '/guide': { items: [...] },

package/src/api/iso/schema/constants.ts

@@ -14,6 +14,7 @@ export const VERSION_UNKNOWN_FALLBACK = `unknown`
 
 /**
  * Convert a date to a version string in YYYY-MM-DD format
+ * @deprecated revisions have native id concept now
  */
 export const dateToVersionString = (date: Date): string => {
   return date.toLocaleDateString('en-CA')

package/src/api/iso/schema/routing.ts

@@ -1,8 +1,9 @@
 import { Grafaid } from '#lib/grafaid'
-import { VERSION_LATEST } from './constants.js'
+import { Schema } from '#lib/schema/$'
+import { Version } from '#lib/version/$'
 
 export interface ReferencePathParts {
-  version?: string
+  version?: Version.Version
   type?: string
   field?: string
 }
@@ -21,24 +22,25 @@ export const createReferencePath = (parts: ReferencePathParts): string => {
  * Create a base path for reference pages based on the current version
  * Used for sidebar navigation and other UI components that need version-aware paths
  */
-export const createReferenceBasePath = (version?: string): string => {
+export const createReferenceBasePath = (version?: Version.Version): string => {
   return joinSegmentsAndPaths(segmentLiterals.reference, createReferenceVersionPath(version))
 }
 
 export const segmentLiterals = {
   reference: 'reference',
   version: 'version',
+  changelog: 'changelog',
 }
 
 /**
  * Create a base path for reference pages based on the current version
  * Used for sidebar navigation and other UI components that need version-aware paths
  */
-export const createReferenceVersionPath = (version?: string): string => {
+export const createReferenceVersionPath = (version?: Version.Version): string => {
   if (version === undefined) return ''
-  return version === VERSION_LATEST
-    ? ``
-    : `/${segmentLiterals.version}/${version}`
+  // VERSION_LATEST is not used with the Version type anymore
+  // Just use the version string directly
+  return `/${segmentLiterals.version}/${Version.toString(version)}`
 }
 
 export const joinSegmentsAndPaths = (
@@ -92,7 +94,7 @@ export type ReferenceViewType =
   | 'field-missing' // Field not found on type
 
 export interface ReferenceViewParams {
-  schema: import('graphql').GraphQLSchema
+  schema: Schema.Schema
   type?: string
   field?: string
 }
@@ -109,7 +111,7 @@ export const getReferenceViewType = (params: ReferenceViewParams): ReferenceView
   }
 
   // Check if type exists
-  const type = schema.getType(typeName)
+  const type = schema.definition.getType(typeName)
   if (!type) {
     return 'type-missing'
   }
@@ -140,3 +142,20 @@ export const getReferenceViewType = (params: ReferenceViewParams): ReferenceView
 export const isMissingView = (viewType: ReferenceViewType): viewType is 'type-missing' | 'field-missing' => {
   return viewType === 'type-missing' || viewType === 'field-missing'
 }
+
+/**
+ * Create a URL to the changelog for a specific revision date
+ * @param revisionDate - The date string from the revision (format: YYYY-MM-DD)
+ * @param currentVersion - The current version being viewed (optional)
+ * @returns URL path to the changelog with anchor to the specific date
+ */
+export const createChangelogUrl = (revisionDate: string, schema: Schema.Schema): string => {
+  // Create base changelog path with version if needed
+  const version = Schema.getVersion(schema)
+  const changelogBase = version
+    ? joinSegmentsAndPaths(segmentLiterals.changelog, segmentLiterals.version, Version.toString(version))
+    : `/${segmentLiterals.changelog}`
+
+  // Add anchor for the specific date
+  return `${changelogBase}#${revisionDate}`
+}

package/src/api/routes/$$.ts

@@ -0,0 +1 @@
+export * from './manifest/$.js'

package/src/api/routes/$.ts

@@ -0,0 +1 @@
+export * as Routes from './$$.js'

package/src/api/routes/manifest/$$.ts

@@ -0,0 +1 @@
+export * from './manifest.js'

package/src/api/routes/manifest/$.ts

@@ -0,0 +1 @@
+export * as Manifest from './$$.js'

package/src/api/routes/manifest/manifest.ts

@@ -0,0 +1,61 @@
+import { Resource } from '#lib/kit-temp/$$'
+import { S } from '#lib/kit-temp/effect'
+import { FileSystem } from '@effect/platform'
+import { NodeFileSystem } from '@effect/platform-node'
+import { Effect } from 'effect'
+
+/**
+ * Schema for the routes manifest generated during build.
+ * This manifest contains all concrete routes that need to be generated for SSG.
+ */
+export const RoutesManifestSchema = S.Struct({
+  version: S.String,
+  timestamp: S.String,
+  totalRoutes: S.Number,
+  routes: S.Array(S.String),
+})
+
+export type RoutesManifest = S.Schema.Type<typeof RoutesManifestSchema>
+
+/**
+ * Resource for reading and writing the routes manifest.
+ * The manifest is stored as routes.manifest.json in the build assets directory.
+ */
+const routesManifestResource = Resource.create({
+  name: 'routes-manifest',
+  path: 'routes.manifest.json',
+  schema: RoutesManifestSchema,
+})
+
+/**
+ * Get a routes manifest from the specified directory.
+ *
+ * @param directory - The directory containing the routes.manifest.json file
+ * @returns Effect resolving to the routes manifest
+ */
+export const get = (directory: string): Effect.Effect<RoutesManifest, Error, FileSystem.FileSystem> => {
+  return routesManifestResource.read(directory).pipe(
+    Effect.catchAll(error =>
+      Effect.fail(
+        new Error(
+          `Failed to load routes manifest from ${directory}/routes.manifest.json. Ensure the build has completed successfully. ${error.message}`,
+        ),
+      )
+    ),
+  )
+}
+
+/**
+ * Write a routes manifest to the specified directory.
+ *
+ * @param manifest - The routes manifest to write
+ * @param directory - The directory where to write the routes.manifest.json file
+ */
+export const write = (
+  manifest: RoutesManifest,
+  directory: string,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  return routesManifestResource.write(manifest, directory).pipe(
+    Effect.catchAll(error => Effect.fail(new Error(`Failed to write routes manifest: ${error.message}`))),
+  )
+}

package/src/api/schema/$$.ts

@@ -0,0 +1,7 @@
+export * from '../iso/schema/constants.js'
+export * as Routing from '../iso/schema/routing.js'
+export * as ConfigSchema from './config-schema.js'
+export * from './config.js'
+export * from './input-source/$.js'
+export * from './input-sources/$.js'
+export * from './load.js'