polen 0.10.0-next.6 → 0.10.0-next.8

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)
+    }
+  })
+})

package/src/api/content/sidebar.ts

@@ -1,136 +1,283 @@
 import { FileRouter } from '#lib/file-router/index'
-import { Tree } from '@wollybeard/kit'
 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[]
 }
 
 /**
- * Build sidebar from page tree structure
+ * 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 const buildFromPageTree = (pageTree: Tree.Tree<Page>, basePath: FileRouter.Path): Sidebar => {
-  const links: ItemLink[] = []
-  const sections: ItemSection[] = []
-
-  // Process only the children of the root node
-  if (pageTree.root) {
-    for (const child of pageTree.root.children) {
-      processPageNode(child, basePath, [], links, sections)
-    }
-  }
+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 = {}
 
-  const items = [...links, ...sections]
+  // Group pages by their top-level directory
+  const pagesByTopLevelDir = new Map<string, Page[]>()
 
-  return {
-    items,
-  }
-}
+  for (const page of scanResult.list) {
+    const topLevelDir = page.route.logical.path[0]
 
-const processPageNode = (
-  node: Tree.Node<Page>,
-  basePath: FileRouter.Path,
-  parentPath: string[],
-  links: ItemLink[],
-  sections: ItemSection[],
-): void => {
-  const page = node.value
-  const routeName = page.route.logical.path.slice(-1)[0] || 'index'
-  const currentPath = [...parentPath, routeName]
-
-  // If this page has children, treat it as a section
-  if (node.children.length > 0) {
-    const sectionPath = [...basePath, ...currentPath]
-    const sectionPathExp = FileRouter.pathToExpression(sectionPath)
-    const sectionTitle = Str.titlizeSlug(routeName)
-
-    // Check if any child is an index page
-    const hasIndexChild = node.children.some(child => isIndexPage(child.value))
-
-    const section: ItemSection = {
-      type: `ItemSection`,
-      title: sectionTitle,
-      pathExp: sectionPathExp.startsWith('/') ? sectionPathExp.slice(1) : sectionPathExp,
-      isLinkToo: hasIndexChild, // Section is linkable if it has an index page
-      links: [],
+    // 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)
+  }
 
-    // Process all children as links for this section
-    for (const child of node.children) {
-      const childPage = child.value
+  // 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)
+    )
 
-      if (child.children.length > 0) {
-        // This child has children - only collect its descendants, not the child itself
-        collectPagesFromNode(child, basePath, section.links)
-      } else if (!childPage.metadata.hidden && !isIndexPage(childPage)) {
-        // This is a leaf node - add it as a link
-        section.links.push(pageToItemLink(childPage, basePath))
-      }
-    }
+    // Skip directories without index pages
+    if (!hasIndexPage) continue
+
+    const pathExp = `/${topLevelDir}`
+    const sidebar = buildSidebarForDirectory(topLevelDir, pages)
 
-    sections.push(section)
-  } else {
-    // This is a standalone file - add as top-level link
-    if (!page.metadata.hidden && !isIndexPage(page)) {
-      links.push(pageToItemLink(page, basePath))
+    if (sidebar.items.length > 0) {
+      sidebarIndex[pathExp] = sidebar
     }
   }
+
+  return sidebarIndex
 }
 
-const collectPagesFromNode = (
-  node: Tree.Node<Page>,
-  basePath: FileRouter.Path,
-  links: ItemLink[],
-): void => {
-  // Only process children, not the node itself (to avoid double-adding intermediate directories)
-  for (const child of node.children) {
-    const childPage = child.value
-    if (childPage && !childPage.metadata.hidden && !isIndexPage(childPage)) {
-      links.push(pageToItemLink(childPage, basePath))
+/**
+ * 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
     }
 
-    // Recursively process grandchildren
-    if (child.children.length > 0) {
-      collectPagesFromNode(child, basePath, links)
+    // 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)
   }
-}
 
-const pageToItemLink = (page: Page, basePath: FileRouter.Path): ItemLink => {
-  const pagePathExp = FileRouter.routeToPathExpression(page.route)
-  const pageRelative = FileRouter.makeRelativeUnsafe(page.route, basePath)
-  const pageRelativePathExp = FileRouter.routeToPathExpression(pageRelative)
+  // 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
 
-  // Remove leading slash for title generation
-  const titlePath = pageRelativePathExp.startsWith('/') ? pageRelativePathExp.slice(1) : pageRelativePathExp
+    if (orderA !== orderB) return orderA - orderB
 
-  // Use only the last segment for the title
-  const titleSegment = pageRelative.logical.path[pageRelative.logical.path.length - 1] || titlePath
+    // Fall back to alphabetical order
+    return dirA.localeCompare(dirB)
+  })
 
-  return {
-    type: `ItemLink`,
-    pathExp: pagePathExp.startsWith('/') ? pagePathExp.slice(1) : pagePathExp,
-    title: Str.titlizeSlug(titleSegment),
+  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('/'),
+      })
+    }
   }
-}
 
-const isIndexPage = (page: Page): boolean => {
-  return page.route.file.path.relative.name === 'index'
+  return { items }
 }