polen 0.10.0-next.13 → 0.10.0-next.3

package/src/api/content/scan.ts

@@ -1,117 +0,0 @@
-import { FileRouter } from '#lib/file-router/index'
-import { Fs, Path, Tree } from '@wollybeard/kit'
-import matter from 'gray-matter'
-import { MetadataSchema } from './metadata.ts'
-import type { Page } from './page.ts'
-
-export interface ScanResult {
-  list: Page[]
-  tree: Tree.Tree<Page>
-  diagnostics: FileRouter.Diagnostic[]
-}
-
-/**
- * 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: {
-  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}',
-  })
-
-  // 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(''),
-          },
-        },
-        logical: {
-          path: [],
-        },
-      },
-      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__',
-    }))
-
-    tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
-  } else {
-    tree = Tree.fromList(pagesWithIds)
-  }
-
-  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 } }
-  }
-
-  // Parse front matter
-  const { data } = matter(fileContent)
-
-  // Validate and parse the data
-  const parsed = MetadataSchema.safeParse(data)
-
-  if (!parsed.success) {
-    // Log warning but continue with defaults
-    console.warn(`Invalid front matter in ${filePath}:`, parsed.error.issues)
-  }
-
-  const metadata = parsed.success ? parsed.data : { hidden: false }
-  return { route, metadata }
-}

package/src/api/content/sidebar.test.ts

@@ -1,297 +0,0 @@
-import * as fc from 'fast-check'
-import { describe, expect, it } from 'vitest'
-import type { Page } from './page.ts'
-import type { ScanResult } from './scan.ts'
-import { buildSidebarIndex, type Item, type SidebarIndex } from './sidebar.ts'
-
-// Generators
-const pathSegmentArb = fc.stringMatching(/^[a-z][a-z0-9-]{0,19}$/)
-const fileNameArb = fc.oneof(fc.constant('index'), pathSegmentArb)
-const pathArb = fc.array(pathSegmentArb, { minLength: 1, maxLength: 4 })
-
-const pageArb: fc.Arbitrary<Page> = fc.record({
-  route: fc.record({
-    id: fc.string(),
-    parentId: fc.oneof(fc.constant(null), fc.string()),
-    logical: fc.record({
-      path: pathArb,
-      order: fc.option(fc.integer({ min: 0, max: 100 }), { nil: undefined }),
-    }),
-    file: fc.record({
-      path: fc.record({
-        absolute: fc.record({
-          root: fc.constant('/'),
-          dir: fc.string(),
-          base: fc.string(),
-          ext: fc.constant('.md'),
-          name: fileNameArb,
-        }),
-        relative: fc.record({
-          root: fc.constant(''),
-          dir: fc.string(),
-          base: fc.string(),
-          ext: fc.constant('.md'),
-          name: fileNameArb,
-        }),
-      }),
-    }),
-  }),
-  metadata: fc.record({
-    description: fc.option(fc.string(), { nil: undefined }),
-    hidden: fc.boolean(),
-  }),
-})
-
-const scanResultArb: fc.Arbitrary<ScanResult> = fc.record({
-  list: fc.array(pageArb, { maxLength: 50 }),
-  tree: fc.constant({ root: null }), // Tree isn't used in the new implementation
-  diagnostics: fc.constant([]),
-})
-
-describe('buildSidebarIndex properties', () => {
-  it('never includes hidden pages in any sidebar', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result = buildSidebarIndex(scanResult)
-
-        // Collect all page paths that appear in sidebars
-        const allSidebarPaths = new Set<string>()
-
-        for (const sidebar of Object.values(result)) {
-          for (const item of sidebar.items) {
-            if (item.type === 'ItemLink') {
-              allSidebarPaths.add(item.pathExp)
-            } else {
-              allSidebarPaths.add(item.pathExp)
-              for (const link of item.links) {
-                allSidebarPaths.add(link.pathExp)
-              }
-            }
-          }
-        }
-
-        // Check that no hidden page appears in sidebars
-        const hiddenPagePaths = scanResult.list
-          .filter(page => page.metadata.hidden)
-          .map(page => page.route.logical.path.join('/'))
-
-        for (const hiddenPath of hiddenPagePaths) {
-          expect(allSidebarPaths.has(hiddenPath)).toBe(false)
-        }
-
-        return true
-      }),
-    )
-  })
-
-  it('only creates sidebars for directories with index pages', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result = buildSidebarIndex(scanResult)
-
-        // Every sidebar key should correspond to a directory with an index page
-        for (const sidebarPath of Object.keys(result)) {
-          const topLevelDir = sidebarPath.slice(1) // Remove leading '/'
-
-          const hasIndexPage = scanResult.list.some(page =>
-            page.route.logical.path.length === 1
-            && page.route.logical.path[0] === topLevelDir
-            && page.route.file.path.relative.name === 'index'
-            && !page.metadata.hidden
-          )
-
-          expect(hasIndexPage).toBe(true)
-        }
-
-        return true
-      }),
-    )
-  })
-
-  it('all items have valid non-empty titles and paths', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result = buildSidebarIndex(scanResult)
-
-        for (const sidebar of Object.values(result)) {
-          for (const item of sidebar.items) {
-            // Check item has required fields
-            expect(item.title).toBeTruthy()
-            expect(item.title.length).toBeGreaterThan(0)
-            expect(item.pathExp).toBeTruthy()
-            expect(item.pathExp.length).toBeGreaterThan(0)
-
-            if (item.type === 'ItemSection') {
-              expect(typeof item.isLinkToo).toBe('boolean')
-              expect(Array.isArray(item.links)).toBe(true)
-
-              // Check all links in section
-              for (const link of item.links) {
-                expect(link.type).toBe('ItemLink')
-                expect(link.title).toBeTruthy()
-                expect(link.title.length).toBeGreaterThan(0)
-                expect(link.pathExp).toBeTruthy()
-                expect(link.pathExp.length).toBeGreaterThan(0)
-              }
-            }
-          }
-        }
-
-        return true
-      }),
-    )
-  })
-
-  it('sections marked as linkable have corresponding index pages', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result = buildSidebarIndex(scanResult)
-
-        for (const sidebar of Object.values(result)) {
-          for (const item of sidebar.items) {
-            if (item.type === 'ItemSection' && item.isLinkToo) {
-              // This section should have an index page
-              const hasIndexPage = scanResult.list.some(page =>
-                page.route.logical.path.join('/') === item.pathExp
-                && page.route.file.path.relative.name === 'index'
-                && !page.metadata.hidden
-              )
-
-              expect(hasIndexPage).toBe(true)
-            }
-          }
-        }
-
-        return true
-      }),
-    )
-  })
-
-  it('no duplicate paths within a sidebar', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result = buildSidebarIndex(scanResult)
-
-        for (const sidebar of Object.values(result)) {
-          const paths = new Set<string>()
-
-          for (const item of sidebar.items) {
-            if (item.type === 'ItemLink') {
-              expect(paths.has(item.pathExp)).toBe(false)
-              paths.add(item.pathExp)
-            } else {
-              expect(paths.has(item.pathExp)).toBe(false)
-              paths.add(item.pathExp)
-
-              for (const link of item.links) {
-                expect(paths.has(link.pathExp)).toBe(false)
-                paths.add(link.pathExp)
-              }
-            }
-          }
-        }
-
-        return true
-      }),
-    )
-  })
-
-  it('deterministic - same input produces same output', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result1 = buildSidebarIndex(scanResult)
-        const result2 = buildSidebarIndex(scanResult)
-
-        expect(JSON.stringify(result1)).toBe(JSON.stringify(result2))
-        return true
-      }),
-    )
-  })
-
-  it('preserves hierarchical relationships', () => {
-    fc.assert(
-      fc.property(scanResultArb, (scanResult) => {
-        const result = buildSidebarIndex(scanResult)
-
-        // For each sidebar, verify that all items belong to that top-level directory
-        for (const [sidebarPath, sidebar] of Object.entries(result)) {
-          const expectedPrefix = sidebarPath.slice(1) // Remove leading '/'
-
-          const checkPath = (pathExp: string) => {
-            const segments = pathExp.split('/')
-            expect(segments[0]).toBe(expectedPrefix)
-          }
-
-          for (const item of sidebar.items) {
-            checkPath(item.pathExp)
-
-            if (item.type === 'ItemSection') {
-              for (const link of item.links) {
-                checkPath(link.pathExp)
-              }
-            }
-          }
-        }
-
-        return true
-      }),
-    )
-  })
-})
-
-// Keep a few specific scenario tests for regression
-describe('buildSidebarIndex specific scenarios', () => {
-  const createPage = (path: string[], fileName = 'index', hidden = false): Page => ({
-    route: {
-      id: path.join('/'),
-      parentId: path.length > 1 ? path.slice(0, -1).join('/') : null,
-      logical: { path },
-      file: {
-        path: {
-          absolute: { root: '/', dir: `/pages/${path.join('/')}`, base: `${fileName}.md`, ext: '.md', name: fileName },
-          relative: { root: '', dir: path.join('/'), base: `${fileName}.md`, ext: '.md', name: fileName },
-        },
-      },
-    },
-    metadata: { description: undefined, hidden },
-  })
-
-  it('handles empty input', () => {
-    const scanResult: ScanResult = {
-      list: [],
-      tree: { root: null },
-      diagnostics: [],
-    }
-    const result = buildSidebarIndex(scanResult)
-    expect(result).toEqual({})
-  })
-
-  it('creates sections for nested directories with index pages', () => {
-    const pages = [
-      createPage(['guide'], 'index'),
-      createPage(['guide', 'advanced'], 'index'),
-      createPage(['guide', 'advanced', 'tips'], 'tips'),
-      createPage(['guide', 'advanced', 'patterns'], 'patterns'),
-    ]
-
-    const scanResult: ScanResult = {
-      list: pages,
-      tree: { root: null },
-      diagnostics: [],
-    }
-
-    const result = buildSidebarIndex(scanResult)
-
-    expect(result['/guide']).toBeDefined()
-    expect(result['/guide']!.items).toHaveLength(1)
-
-    const section = result['/guide']!.items[0]
-    expect(section?.type).toBe('ItemSection')
-
-    if (section?.type === 'ItemSection') {
-      expect(section.title).toBe('Advanced')
-      expect(section.isLinkToo).toBe(true)
-      expect(section.links).toHaveLength(2)
-    }
-  })
-})

package/src/api/content/sidebar.ts

@@ -1,283 +0,0 @@
-import { FileRouter } from '#lib/file-router/index'
-import { Str } from '@wollybeard/kit'
-import type { Page } from './page.ts'
-import type { ScanResult } from './scan.ts'
-
-/**
- * Represents a complete sidebar structure with navigation items.
- * This is the main data structure used to render sidebars in the UI.
- */
-export interface Sidebar {
-  /** Array of navigation items that can be either direct links or sections containing multiple links */
-  items: Item[]
-}
-
-/**
- * A sidebar navigation item that can be either a direct link or a section containing multiple links.
- * @see {@link ItemLink} for direct navigation links
- * @see {@link ItemSection} for grouped navigation sections
- */
-export type Item = ItemLink | ItemSection
-
-/**
- * A direct navigation link in the sidebar.
- * Used for pages that don't have child pages.
- *
- * @example
- * ```ts
- * const link: ItemLink = {
- *   type: 'ItemLink',
- *   title: 'Getting Started',
- *   pathExp: 'guide/getting-started'
- * }
- * ```
- */
-export interface ItemLink {
-  /** Discriminator for TypeScript union types */
-  type: `ItemLink`
-  /** Display title for the link (e.g., "Getting Started") */
-  title: string
-  /** Path expression relative to the base path, without leading slash (e.g., "guide/getting-started") */
-  pathExp: string
-}
-
-/**
- * A collapsible section in the sidebar that groups related links.
- * Used for directories that contain multiple pages.
- *
- * @example
- * ```ts
- * const section: ItemSection = {
- *   type: 'ItemSection',
- *   title: 'Guide',
- *   pathExp: 'guide',
- *   isLinkToo: true, // Has an index page
- *   links: [
- *     { type: 'ItemLink', title: 'Installation', pathExp: 'guide/installation' },
- *     { type: 'ItemLink', title: 'Configuration', pathExp: 'guide/configuration' }
- *   ]
- * }
- * ```
- */
-export interface ItemSection {
-  /** Discriminator for TypeScript union types */
-  type: `ItemSection`
-  /** Display title for the section (e.g., "Guide", "API Reference") */
-  title: string
-  /** Path expression for the section's index page, if it exists (e.g., "guide") */
-  pathExp: string
-  /** Whether this section also acts as a link (true if the directory has an index page) */
-  isLinkToo: boolean
-  /** Child navigation links within this section */
-  links: ItemLink[]
-}
-
-/**
- * A mapping of route paths to their corresponding sidebar structures.
- * Used to store different sidebars for different sections of a site.
- *
- * @example
- * ```ts
- * const sidebarIndex: SidebarIndex = {
- *   '/guide': { items: [...] },     // Sidebar for /guide section
- *   '/api': { items: [...] },       // Sidebar for /api section
- *   '/reference': { items: [...] }  // Sidebar for /reference section
- * }
- * ```
- */
-export type SidebarIndex = Record<string, Sidebar>
-
-/**
- * Builds sidebars for all top-level directories that contain both an index page and nested content.
- *
- * This function analyzes a scan result to identify which directories should have sidebars.
- * A directory gets a sidebar if it meets these criteria:
- * 1. It's a top-level directory (e.g., /guide, /api, /docs)
- * 2. It has an index page (e.g., /guide/index.md)
- * 3. It has nested pages (e.g., /guide/getting-started.md, /guide/configuration.md)
- *
- * @param scanResult - The result of scanning pages, containing both a flat list and tree structure
- * @returns A mapping of route paths to sidebar structures
- *
- * @example
- * ```ts
- * const scanResult = await Content.scan({ dir: './pages' })
- * const sidebars = buildSidebarIndex(scanResult)
- * // Returns: {
- * //   '/guide': { items: [...] },
- * //   '/api': { items: [...] }
- * // }
- * ```
- */
-export const buildSidebarIndex = (scanResult: ScanResult): SidebarIndex => {
-  const sidebarIndex: SidebarIndex = {}
-
-  // Group pages by their top-level directory
-  const pagesByTopLevelDir = new Map<string, Page[]>()
-
-  for (const page of scanResult.list) {
-    const topLevelDir = page.route.logical.path[0]
-
-    // Skip pages that are not in a directory or are hidden
-    if (!topLevelDir || page.metadata.hidden) continue
-
-    if (!pagesByTopLevelDir.has(topLevelDir)) {
-      pagesByTopLevelDir.set(topLevelDir, [])
-    }
-    pagesByTopLevelDir.get(topLevelDir)!.push(page)
-  }
-
-  // Build sidebar for each directory that has an index page
-  for (const [topLevelDir, pages] of pagesByTopLevelDir) {
-    const hasIndexPage = pages.some(page =>
-      page.route.logical.path.length === 1
-      && FileRouter.routeIsFromIndexFile(page.route)
-    )
-
-    // Skip directories without index pages
-    if (!hasIndexPage) continue
-
-    const pathExp = `/${topLevelDir}`
-    const sidebar = buildSidebarForDirectory(topLevelDir, pages)
-
-    if (sidebar.items.length > 0) {
-      sidebarIndex[pathExp] = sidebar
-    }
-  }
-
-  return sidebarIndex
-}
-
-/**
- * Builds a sidebar for a specific directory from its pages
- */
-const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar => {
-  const items: Item[] = []
-
-  // Group pages by their immediate parent path
-  const pagesByParent = new Map<string, Page[]>()
-
-  for (const page of pages) {
-    // Skip the index page at the top level directory
-    if (page.route.logical.path.length === 1 && FileRouter.routeIsFromIndexFile(page.route)) {
-      continue
-    }
-
-    // Get the immediate parent path (e.g., for ['guide', 'advanced', 'tips'], parent is ['guide', 'advanced'])
-    const parentPath = page.route.logical.path.slice(0, -1).join('/')
-
-    if (!pagesByParent.has(parentPath)) {
-      pagesByParent.set(parentPath, [])
-    }
-    pagesByParent.get(parentPath)!.push(page)
-  }
-
-  // Process top-level pages (direct children of the directory)
-  const topLevelPages = pagesByParent.get(topLevelDir) || []
-
-  // Sort pages by their directory order (extracted from file path)
-  const sortedTopLevelPages = [...topLevelPages].sort((a, b) => {
-    // For sections, we need to look at the directory name in the file path
-    const dirA = a.route.file.path.relative.dir.split('/').pop() || ''
-    const dirB = b.route.file.path.relative.dir.split('/').pop() || ''
-
-    // Extract order from directory names like "10_b", "20_c"
-    const orderMatchA = dirA.match(/^(\d+)[_-]/)
-    const orderMatchB = dirB.match(/^(\d+)[_-]/)
-
-    const orderA = orderMatchA ? parseInt(orderMatchA[1]!, 10) : Number.MAX_SAFE_INTEGER
-    const orderB = orderMatchB ? parseInt(orderMatchB[1]!, 10) : Number.MAX_SAFE_INTEGER
-
-    if (orderA !== orderB) return orderA - orderB
-
-    // Fall back to alphabetical order
-    return dirA.localeCompare(dirB)
-  })
-
-  for (const page of sortedTopLevelPages) {
-    const pageName = page.route.logical.path[page.route.logical.path.length - 1]!
-    const childPath = page.route.logical.path.join('/')
-    const childPages = pagesByParent.get(childPath) || []
-
-    if (childPages.length > 0 || FileRouter.routeIsFromIndexFile(page.route)) {
-      // This is a section (has children or is an index page for a subdirectory)
-      const hasIndex = FileRouter.routeIsFromIndexFile(page.route)
-
-      const section: ItemSection = {
-        type: 'ItemSection',
-        title: Str.titlizeSlug(pageName),
-        pathExp: childPath,
-        isLinkToo: hasIndex,
-        links: [],
-      }
-
-      // Add direct children as links (sorted by order)
-      const sortedChildPages = [...childPages].sort((a, b) => {
-        const orderA = a.route.logical.order ?? Number.MAX_SAFE_INTEGER
-        const orderB = b.route.logical.order ?? Number.MAX_SAFE_INTEGER
-        return orderA - orderB
-      })
-
-      for (const childPage of sortedChildPages) {
-        if (!FileRouter.routeIsFromIndexFile(childPage.route)) {
-          section.links.push({
-            type: 'ItemLink',
-            title: Str.titlizeSlug(childPage.route.logical.path[childPage.route.logical.path.length - 1]!),
-            pathExp: childPage.route.logical.path.join('/'),
-          })
-        }
-      }
-
-      // Also add any deeper descendants as flat links
-      const allDescendants: Page[] = []
-      for (const [parentPath, pagesInParent] of pagesByParent) {
-        // Check if this path is a descendant (but not direct child)
-        if (parentPath.startsWith(childPath + '/')) {
-          for (const descendantPage of pagesInParent) {
-            if (!FileRouter.routeIsFromIndexFile(descendantPage.route)) {
-              allDescendants.push(descendantPage)
-            }
-          }
-        }
-      }
-
-      // Sort all descendants by their full path order
-      allDescendants.sort((a, b) => {
-        // Compare paths segment by segment, considering order at each level
-        const pathA = a.route.logical.path
-        const pathB = b.route.logical.path
-        const minLength = Math.min(pathA.length, pathB.length)
-
-        for (let i = 0; i < minLength; i++) {
-          const segmentCompare = pathA[i]!.localeCompare(pathB[i]!)
-          if (segmentCompare !== 0) return segmentCompare
-        }
-
-        return pathA.length - pathB.length
-      })
-
-      for (const descendantPage of allDescendants) {
-        section.links.push({
-          type: 'ItemLink',
-          title: Str.titlizeSlug(
-            descendantPage.route.logical.path[descendantPage.route.logical.path.length - 1]!,
-          ),
-          pathExp: descendantPage.route.logical.path.join('/'),
-        })
-      }
-
-      if (section.links.length > 0 || section.isLinkToo) {
-        items.push(section)
-      }
-    } else {
-      // This is a simple link
-      items.push({
-        type: 'ItemLink',
-        title: Str.titlizeSlug(pageName),
-        pathExp: page.route.logical.path.join('/'),
-      })
-    }
-  }
-
-  return { items }
-}

package/src/api/content/utils.ts

@@ -1,7 +0,0 @@
-/**
- * Check if a file path represents a page file (markdown or MDX)
- */
-export const isPageFile = (filePath: string, pagesDirectory: string): boolean => {
-  return (filePath.endsWith(`.md`) || filePath.endsWith(`.mdx`))
-    && filePath.includes(pagesDirectory)
-}

package/src/api/static/index.ts

@@ -1 +0,0 @@
-export * as Static from './static.ts'