polen 0.10.0-next.14 → 0.10.0-next.3

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'

package/src/api/static/manifest.test.ts

@@ -1,106 +0,0 @@
-import { Err, Fs, Path } from '@wollybeard/kit'
-import { afterEach, beforeEach, describe, expect, test } from 'vitest'
-import { buildManifest, type PolenBuildManifest } from './manifest.ts'
-
-describe('validate-build', () => {
-  let testDir: string
-  let manifestPath: string
-
-  beforeEach(async () => {
-    testDir = await Fs.makeTemporaryDirectory()
-    manifestPath = Path.join(testDir, '.polen', 'build.json')
-  })
-
-  afterEach(async () => {
-    if (testDir && await Fs.exists(testDir)) {
-      await Fs.remove(testDir)
-    }
-  })
-
-  describe('readBuildManifest', () => {
-    test('reads valid manifest', async () => {
-      const manifest: PolenBuildManifest = {
-        type: 'ssr',
-        version: '2.1.0',
-        basePath: '/docs/',
-      }
-      await Fs.write({
-        path: manifestPath,
-        content: JSON.stringify(manifest, null, 2),
-      })
-
-      const result = await buildManifest.read(testDir)
-      expect(Err.is(result)).toBe(false)
-      expect(result).toEqual(manifest)
-    })
-
-    test('returns error when manifest does not exist', async () => {
-      // Verify the file doesn't exist
-      const manifestExists = await Fs.exists(manifestPath)
-      expect(manifestExists).toBe(false)
-
-      const result = await buildManifest.read(testDir)
-      expect(Err.is(result)).toBe(true)
-    })
-
-    test('returns error for invalid manifest structure', async () => {
-      await Fs.write({
-        path: manifestPath,
-        content: JSON.stringify({ invalid: 'data' }, null, 2),
-      })
-      const result = await buildManifest.read(testDir)
-      expect(Err.is(result)).toBe(true)
-    })
-
-    test('returns error for invalid build type', async () => {
-      await Fs.write({
-        path: manifestPath,
-        content: JSON.stringify(
-          {
-            type: 'invalid',
-            version: '1.0.0',
-            basePath: '/',
-          },
-          null,
-          2,
-        ),
-      })
-      const result = await buildManifest.read(testDir)
-      expect(Err.is(result)).toBe(true)
-    })
-
-    test('returns error when version is not a string', async () => {
-      await Fs.write({
-        path: manifestPath,
-        content: JSON.stringify(
-          {
-            type: 'ssg',
-            version: 123,
-            basePath: '/',
-          },
-          null,
-          2,
-        ),
-      })
-      const result = await buildManifest.read(testDir)
-      expect(Err.is(result)).toBe(true)
-    })
-
-    test('returns error when basePath is not a string', async () => {
-      await Fs.write({
-        path: manifestPath,
-        content: JSON.stringify(
-          {
-            type: 'ssg',
-            version: '1.0.0',
-            basePath: null,
-          },
-          null,
-          2,
-        ),
-      })
-      const result = await buildManifest.read(testDir)
-      expect(Err.is(result)).toBe(true)
-    })
-  })
-})

package/src/api/static/manifest.ts

@@ -1,16 +0,0 @@
-import { Codec, Resource } from '@wollybeard/kit'
-import { z } from 'zod/v4'
-
-export const PolenBuildManifestSchema = z.object({
-  type: z.enum(['ssg', 'ssr']),
-  version: z.string(),
-  basePath: z.string(),
-}).loose()
-
-export type PolenBuildManifest = z.infer<typeof PolenBuildManifestSchema>
-
-export const buildManifest = Resource.create({
-  name: 'polen-build-manifest',
-  path: '.polen/build.json',
-  codec: Codec.fromZod(PolenBuildManifestSchema),
-})

package/src/api/static/rebase.test.ts

@@ -1,229 +0,0 @@
-import { Fs, Path } from '@wollybeard/kit'
-import { afterEach, beforeEach, describe, expect, test } from 'vitest'
-import { rebase, type RebasePlan } from './rebase.ts'
-
-const testDir = 'temp/rebase-test'
-
-const createTestBuild = async (dir: string, basePath: string = '/') => {
-  await Fs.makeDirectory(dir)
-
-  // Create Polen build manifest
-  const polenDir = Path.join(dir, '.polen')
-  await Fs.makeDirectory(polenDir)
-
-  const manifest = {
-    type: 'ssg' as const,
-    version: '1.0.0',
-    basePath,
-  }
-
-  await Fs.write({
-    path: Path.join(polenDir, 'build.json'),
-    content: JSON.stringify(manifest, null, 2),
-  })
-
-  // Create some HTML files
-  await Fs.write({
-    path: Path.join(dir, 'index.html'),
-    content: `<!DOCTYPE html>
-<html>
-<head>
-  <base href="${basePath}">
-  <title>Test</title>
-</head>
-<body>
-  <h1>Test Page</h1>
-</body>
-</html>`,
-  })
-
-  // Create nested HTML file
-  const nestedDir = Path.join(dir, 'docs')
-  await Fs.makeDirectory(nestedDir)
-
-  await Fs.write({
-    path: Path.join(nestedDir, 'page.html'),
-    content: `<!DOCTYPE html>
-<html>
-<head>
-  <title>Nested</title>
-</head>
-<body>
-  <h1>Nested Page</h1>
-</body>
-</html>`,
-  })
-}
-
-describe('rebase', () => {
-  beforeEach(async () => {
-    await Fs.remove(testDir)
-  })
-
-  afterEach(async () => {
-    await Fs.remove(testDir)
-  })
-
-  test('mutate mode updates base paths in place', async () => {
-    const buildDir = Path.join(testDir, 'build')
-    await createTestBuild(buildDir, '/old/')
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      newBasePath: '/new/',
-      changeMode: 'mutate',
-    }
-
-    await rebase(plan)
-
-    // Check updated manifest
-    const manifest = await Fs.readJson(Path.join(buildDir, '.polen', 'build.json'))
-    expect(manifest).toMatchObject({
-      type: 'ssg',
-      version: '1.0.0',
-      basePath: '/new/',
-    })
-
-    // Check updated HTML file
-    const indexContent = await Fs.read(Path.join(buildDir, 'index.html'))
-    expect(indexContent).toContain('<base href="/new/">')
-
-    // Check nested HTML file (should have base tag inserted)
-    const nestedContent = await Fs.read(Path.join(buildDir, 'docs', 'page.html'))
-    expect(nestedContent).toContain('<base href="/new/">')
-  })
-
-  test('copy mode creates new build with updated base paths', async () => {
-    const buildDir = Path.join(testDir, 'build')
-    const copyDir = Path.join(testDir, 'copy')
-
-    await createTestBuild(buildDir, '/old/')
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      targetPath: copyDir,
-      newBasePath: '/new/',
-      changeMode: 'copy',
-    }
-
-    await rebase(plan)
-
-    // Original should be unchanged
-    const originalManifest = await Fs.readJson(Path.join(buildDir, '.polen', 'build.json'))
-    expect(originalManifest).toMatchObject({
-      basePath: '/old/',
-    })
-
-    // Copy should be updated
-    const copyManifest = await Fs.readJson(Path.join(copyDir, '.polen', 'build.json'))
-    expect(copyManifest).toMatchObject({
-      basePath: '/new/',
-    })
-
-    const copyIndexContent = await Fs.read(Path.join(copyDir, 'index.html'))
-    expect(copyIndexContent).toContain('<base href="/new/">')
-  })
-
-  test('throws error for invalid base path', async () => {
-    const buildDir = Path.join(testDir, 'build')
-    await createTestBuild(buildDir)
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      newBasePath: 'invalid-path',
-      changeMode: 'mutate',
-    }
-
-    await expect(rebase(plan)).rejects.toThrow('Invalid base path: invalid-path')
-  })
-
-  test('throws error when source is not a Polen build', async () => {
-    const buildDir = Path.join(testDir, 'not-polen')
-    await Fs.makeDirectory(buildDir)
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      newBasePath: '/new/',
-      changeMode: 'mutate',
-    }
-
-    await expect(rebase(plan)).rejects.toThrow('Polen build manifest not found')
-  })
-
-  test('throws error when copy target exists and is not empty', async () => {
-    const buildDir = Path.join(testDir, 'build')
-    const copyDir = Path.join(testDir, 'copy')
-
-    await createTestBuild(buildDir)
-
-    // Create non-empty target
-    await Fs.makeDirectory(copyDir)
-    await Fs.write({
-      path: Path.join(copyDir, 'existing.txt'),
-      content: 'existing file',
-    })
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      targetPath: copyDir,
-      newBasePath: '/new/',
-      changeMode: 'copy',
-    }
-
-    await expect(rebase(plan)).rejects.toThrow('Target path already exists and is not empty')
-  })
-
-  test('handles HTML file without existing base tag', async () => {
-    const buildDir = Path.join(testDir, 'build')
-    await createTestBuild(buildDir)
-
-    // Create HTML without base tag
-    await Fs.write({
-      path: Path.join(buildDir, 'no-base.html'),
-      content: `<!DOCTYPE html>
-<html>
-<head>
-  <title>No Base</title>
-</head>
-<body>
-  <h1>No Base Tag</h1>
-</body>
-</html>`,
-    })
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      newBasePath: '/new/',
-      changeMode: 'mutate',
-    }
-
-    await rebase(plan)
-
-    const content = await Fs.read(Path.join(buildDir, 'no-base.html'))
-    expect(content).toContain('<base href="/new/">')
-  })
-
-  test('throws error for HTML file without head tag', async () => {
-    const buildDir = Path.join(testDir, 'build')
-    await createTestBuild(buildDir)
-
-    // Create invalid HTML without head
-    await Fs.write({
-      path: Path.join(buildDir, 'invalid.html'),
-      content: `<!DOCTYPE html>
-<html>
-<body>
-  <h1>Invalid HTML</h1>
-</body>
-</html>`,
-    })
-
-    const plan: RebasePlan = {
-      sourcePath: buildDir,
-      newBasePath: '/new/',
-      changeMode: 'mutate',
-    }
-
-    await expect(rebase(plan)).rejects.toThrow('Could not find <head> tag in HTML file')
-  })
-})