polen 0.9.1-next.1 → 0.10.0-next.10

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

@@ -0,0 +1,72 @@
+import { Fs, Path } from '@wollybeard/kit'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { Content } from './$.ts'
+
+describe('content', () => {
+  let testDir: string
+
+  beforeEach(async () => {
+    testDir = await Fs.makeTemporaryDirectory()
+  })
+
+  afterEach(async () => {
+    if (testDir && await Fs.exists(testDir)) {
+      await Fs.remove(testDir)
+    }
+  })
+
+  describe('MetadataSchema', () => {
+    test('validates metadata correctly', () => {
+      const valid = Content.MetadataSchema.safeParse({
+        description: 'Test page description',
+        hidden: true,
+      })
+      expect(valid.success).toBe(true)
+      expect(valid.data).toEqual({
+        description: 'Test page description',
+        hidden: true,
+      })
+    })
+
+    test('applies default values', () => {
+      const result = Content.MetadataSchema.safeParse({
+        description: 'Just a description',
+      })
+      expect(result.success).toBe(true)
+      expect(result.data?.hidden).toBe(false)
+    })
+
+    test('rejects invalid values', () => {
+      const result = Content.MetadataSchema.safeParse({
+        hidden: 'not a boolean',
+        invalid_field: 123,
+      })
+      expect(result.success).toBe(false)
+    })
+  })
+
+  describe('scan', () => {
+    test('scans directory and extracts metadata', async () => {
+      const filePath = Path.join(testDir, 'page.md')
+      await Fs.write({
+        path: filePath,
+        content: `---
+description: Page description
+---
+Content`,
+      })
+
+      const result = await Content.scan({
+        dir: testDir,
+        glob: '**/*.md',
+      })
+
+      expect(result.list).toHaveLength(1)
+      expect(result.list[0]?.metadata).toEqual({
+        description: 'Page description',
+        hidden: false,
+      })
+      expect(result.diagnostics).toEqual([])
+    })
+  })
+})

package/src/api/content/$.ts

@@ -0,0 +1 @@
+export * as Content from './$$.ts'

package/src/api/content/metadata.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4'
+
+/**
+ * Schema for validating front matter content
+ */
+export const MetadataSchema = z.object({
+  description: z.string().optional(),
+  hidden: z.boolean().default(false),
+})
+
+export type Metadata = z.infer<typeof MetadataSchema>

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

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { createNavbar } from './navbar.ts'
+import type { Page } from './page.ts'
+
+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 },
+})
+
+describe('createNavbar', () => {
+  it('returns empty for empty input', () => {
+    expect(createNavbar([])).toEqual([])
+  })
+
+  it('excludes hidden pages', () => {
+    const pages = [createPage(['visible'], 'index', false), createPage(['hidden'], 'index', true)]
+    const result = createNavbar(pages)
+    expect(result).toEqual([{ pathExp: '/visible', title: 'Visible' }])
+  })
+
+  it('includes directories with index pages', () => {
+    const pages = [createPage(['guide'], 'index'), createPage(['guide', 'intro'], 'intro')]
+    const result = createNavbar(pages)
+    expect(result).toEqual([{ pathExp: '/guide', title: 'Guide' }])
+  })
+
+  it('excludes directories without index pages', () => {
+    const pages = [createPage(['guide', 'intro'], 'intro')]
+    const result = createNavbar(pages)
+    expect(result).toEqual([])
+  })
+
+  it('includes single top-level pages', () => {
+    const pages = [createPage(['about'], 'about')]
+    const result = createNavbar(pages)
+    expect(result).toEqual([{ pathExp: '/about', title: 'About' }])
+  })
+
+  it('sorts results alphabetically', () => {
+    const pages = [createPage(['zebra'], 'zebra'), createPage(['alpha'], 'alpha')]
+    const result = createNavbar(pages)
+    expect(result[0]!.title).toBe('Alpha')
+    expect(result[1]!.title).toBe('Zebra')
+  })
+})

package/src/api/content/navbar.ts

@@ -0,0 +1,61 @@
+import { Str } from '@wollybeard/kit'
+import type { Page } from './page.ts'
+
+export interface NavbarItem {
+  pathExp: string
+  title: string
+}
+
+/**
+ * Generate navbar items from a list of pages
+ */
+export const createNavbar = (pages: Page[]): NavbarItem[] => {
+  const navbarItems: NavbarItem[] = []
+
+  // Group pages by their top-level directory/segment
+  const topLevelGroups = new Map<string, Page[]>()
+
+  pages.forEach(page => {
+    // Skip hidden pages
+    if (page.metadata.hidden) return
+
+    const firstSegment = page.route.logical.path[0]
+    if (firstSegment) {
+      if (!topLevelGroups.has(firstSegment)) {
+        topLevelGroups.set(firstSegment, [])
+      }
+      topLevelGroups.get(firstSegment)!.push(page)
+    }
+  })
+
+  // Add each top-level group to navbar
+  topLevelGroups.forEach((pages, segment) => {
+    // For directories, check if there's an index page
+    const indexPage = pages.find(p =>
+      p.route.logical.path.length === 1
+      && p.route.file.path.relative.name === 'index'
+    )
+
+    // For single non-index files at top level
+    const singlePage = pages.length === 1 && pages[0]!.route.logical.path.length === 1
+      && pages[0]!.route.file.path.relative.name !== 'index'
+
+    // Include in navbar if:
+    // 1. It's a directory with an index page, OR
+    // 2. It's a single top-level page (not index)
+    if (indexPage || singlePage) {
+      const title = Str.titlizeSlug(segment)
+      const pathExp = `/${segment}`
+
+      navbarItems.push({
+        pathExp,
+        title,
+      })
+    }
+  })
+
+  // Sort navbar items alphabetically for consistency
+  navbarItems.sort((a, b) => a.title.localeCompare(b.title))
+
+  return navbarItems
+}

package/src/api/content/page.ts

@@ -0,0 +1,12 @@
+import type { FileRouter } from '#lib/file-router/index'
+import type { Metadata } from './metadata.ts'
+
+export type { Metadata }
+
+/**
+ * A route with its associated metadata
+ */
+export interface Page {
+  route: FileRouter.Route
+  metadata: Metadata
+}

package/src/api/content/scan.ts

@@ -0,0 +1,117 @@
+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

@@ -0,0 +1,297 @@
+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)
+    }
+  })
+})