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

package/src/api/content/sidebar.ts

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

@@ -0,0 +1,7 @@
+/**
+ * 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/schema/data-sources/schema-directory/schema-directory.ts

@@ -1,13 +1,14 @@
 import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-import { debug as debugPolen } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
 import type { Schema } from '../../schema.ts'
 import { FileNameExpression } from './file-name-expression/index.ts'
 
-const debug = debugPolen.sub([`schema`, `data-source-schema-directory`])
+// const debug = debugPolen.sub([`schema`, `data-source-schema-directory`])
+const debug = debugPolen.sub(`schema:data-source-schema-directory`)
 
 const defaultPaths = {
   schemaDirectory: `./schema`,

package/src/api/singletons/markdown/markdown.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { parse } from './markdown.js'
+import { parse } from './markdown.ts'
 
 describe(`markdown parser with syntax highlighting`, () => {
   test(`parse highlights code blocks`, async () => {

package/src/api/static/index.ts

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

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

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

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

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