polen 0.10.0-next.14 → 0.10.0-next.4

package/src/lib/file-router/diagnostic-reporter.ts

@@ -13,10 +13,10 @@ export const reportDiagnostics = (diagnostics: Diagnostic[]) => {
     infos.length > 0 && `${infos.length} info${infos.length === 1 ? '' : 's'}`,
   ].filter(Boolean).join(', ')
 
-  console.warn(`\nPolen found ${summary}:\n`)
+  console.warn(`\n🔍 Polen found ${summary}:\n`)
 
   diagnostics.forEach((diagnostic, index) => {
-    const icon = diagnostic.severity === 'error' ? '✗' : diagnostic.severity === 'warning' ? '⚠' : 'ⓘ'
+    const icon = diagnostic.severity === 'error' ? '❌' : diagnostic.severity === 'warning' ? '⚠️ ' : 'ℹ️ '
     console.warn(`${icon} ${index + 1}. ${diagnostic.message}\n`)
   })
 }

package/src/lib/file-router/file-router.ts

@@ -1,3 +1,5 @@
 export * from './linter.ts'
 export * from './route.ts'
+export * from './scan-tree.ts'
 export * from './scan.ts'
+export * from './sidebar/index.ts'

package/src/lib/file-router/linter.test.ts

@@ -28,8 +28,6 @@ const createRoute = (path: string[], order?: number, isIndex = false): Route =>
         },
       },
     },
-    id: `/project/pages/${path.join('/')}/${name}.md`,
-    parentId: path.length > 1 ? `/project/pages/${path.slice(0, -1).join('/')}` : null,
   }
 }
 

package/src/lib/file-router/route.ts

@@ -36,8 +36,6 @@ export const pathToExpression = (path: Path) => {
 export interface Route {
   logical: RouteLogical
   file: RouteFile
-  id: string // Absolute file path for unique identification
-  parentId: string | null // Parent directory path, null for root-level files
 }
 
 export interface RouteLogical {

package/src/lib/file-router/scan-tree.test.ts

@@ -0,0 +1,189 @@
+import { Tree } from '#lib/tree/index'
+import { describe, expect, test } from 'vitest'
+import type { RouteTreeNode } from './scan-tree.ts'
+
+// Helper to create a mock route tree structure for testing
+const mockRouteTree = (structure: Record<string, any>): RouteTreeNode => {
+  const sortNodes = (nodes: RouteTreeNode[]): RouteTreeNode[] => {
+    return nodes.sort((a, b) => {
+      // If both have orders, sort by order
+      if (a.value.order !== undefined && b.value.order !== undefined) {
+        return a.value.order - b.value.order
+      }
+      // If only one has order, it comes first
+      if (a.value.order !== undefined) return -1
+      if (b.value.order !== undefined) return 1
+      // Otherwise sort alphabetically
+      return a.value.name.localeCompare(b.value.name)
+    })
+  }
+
+  const buildNode = (name: string, value: any): RouteTreeNode => {
+    const parsed = name.match(/^(?<order>\d+)[_-](?<name>.+)$/)
+    const nodeName = parsed?.groups?.[`name`] ?? name
+    const order = parsed?.groups?.[`order`] ? parseInt(parsed.groups[`order`], 10) : undefined
+
+    if (typeof value === 'object' && !value.isFile) {
+      // Directory node
+      const children = Object.entries(value).map(([childName, childValue]) => buildNode(childName, childValue))
+      return Tree.node(
+        { name: nodeName, order, type: 'directory' },
+        sortNodes(children),
+      )
+    } else {
+      // File node - strip extension (but keep 'index' as is)
+      const nameWithoutExtension = nodeName.replace(/\.(md|mdx)$/, '')
+      return Tree.node({ name: nameWithoutExtension, order, type: 'file', route: value })
+    }
+  }
+
+  const children = Object.entries(structure).map(([name, value]) => buildNode(name, value))
+  return Tree.node(
+    { name: 'root', type: 'directory' },
+    sortNodes(children),
+  )
+}
+
+describe('scan-tree structure', () => {
+  test('builds tree from flat file structure', () => {
+    const tree = mockRouteTree({
+      'getting-started.md': { isFile: true },
+      'guide': {
+        'introduction.md': { isFile: true },
+        'basics.md': { isFile: true },
+      },
+      'api': {
+        'reference.md': { isFile: true },
+      },
+    })
+
+    expect(tree.value.name).toBe('root')
+    expect(tree.children).toHaveLength(3)
+
+    const guide = tree.children.find(c => c.value.name === 'guide')
+    expect(guide).toBeDefined()
+    expect(guide!.children).toHaveLength(2)
+  })
+
+  test('handles numbered prefixes on files', () => {
+    const tree = mockRouteTree({
+      '10_getting-started.md': { isFile: true },
+      '20_configuration.md': { isFile: true },
+      '30_advanced.md': { isFile: true },
+    })
+
+    const children = tree.children
+    expect(children[0]!.value).toMatchObject({ name: 'getting-started', order: 10 })
+    expect(children[1]!.value).toMatchObject({ name: 'configuration', order: 20 })
+    expect(children[2]!.value).toMatchObject({ name: 'advanced', order: 30 })
+  })
+
+  test('handles numbered prefixes on directories', () => {
+    const tree = mockRouteTree({
+      '10_guide': {
+        'intro.md': { isFile: true },
+      },
+      '20_api': {
+        'reference.md': { isFile: true },
+      },
+      '05_quickstart': {
+        'index.md': { isFile: true },
+      },
+    })
+
+    const children = tree.children
+    expect(children[0]!.value).toMatchObject({ name: 'quickstart', order: 5 })
+    expect(children[1]!.value).toMatchObject({ name: 'guide', order: 10 })
+    expect(children[2]!.value).toMatchObject({ name: 'api', order: 20 })
+  })
+
+  test('handles mixed numbered and non-numbered items', () => {
+    const tree = mockRouteTree({
+      '10_guide': {
+        'intro.md': { isFile: true },
+      },
+      'troubleshooting': {
+        'common.md': { isFile: true },
+      },
+      '05_quickstart': {
+        'index.md': { isFile: true },
+      },
+      'api': {
+        'reference.md': { isFile: true },
+      },
+    })
+
+    // After sorting: numbered items first (5, 10), then alphabetical (api, troubleshooting)
+    const childNames = tree.children.map(c => c.value.name)
+    expect(childNames).toEqual(['quickstart', 'guide', 'api', 'troubleshooting'])
+  })
+
+  test('handles nested numbered prefixes', () => {
+    const tree = mockRouteTree({
+      '10_guide': {
+        '10_getting-started.md': { isFile: true },
+        '20_basics.md': { isFile: true },
+        'troubleshooting.md': { isFile: true },
+        '05_prerequisites.md': { isFile: true },
+      },
+    })
+
+    const guide = tree.children[0]!
+    expect(guide.value.name).toBe('guide')
+
+    const guideChildNames = guide.children.map(c => c.value.name)
+    expect(guideChildNames).toEqual(['prerequisites', 'getting-started', 'basics', 'troubleshooting'])
+  })
+
+  test('handles index files', () => {
+    const tree = mockRouteTree({
+      'guide': {
+        'index.md': { isFile: true },
+        'intro.md': { isFile: true },
+      },
+    })
+
+    const guide = tree.children[0]!
+    expect(guide.children).toHaveLength(2)
+    expect(guide.children.map(c => c.value.name)).toContain('index')
+    expect(guide.children.map(c => c.value.name)).toContain('intro')
+  })
+
+  test('creates directory nodes with correct type', () => {
+    const tree = mockRouteTree({
+      '10_guide': {
+        'intro.md': { isFile: true },
+      },
+      'api-reference.md': { isFile: true },
+    })
+
+    expect(tree.value.type).toBe('directory')
+
+    const guide = tree.children.find(c => c.value.name === 'guide')
+    expect(guide?.value.type).toBe('directory')
+    expect(guide?.value.order).toBe(10)
+
+    const apiRef = tree.children.find(c => c.value.name === 'api-reference')
+    expect(apiRef?.value.type).toBe('file')
+  })
+
+  test('handles file collisions with same order number - last wins', () => {
+    // This test simulates what would happen if the scanner processes files in order
+    // The mock doesn't actually test the scanner logic but documents expected behavior
+    const tree = mockRouteTree({
+      '10_about.md': { isFile: true, processedFirst: true },
+      '10-about.md': { isFile: true, processedLast: true }, // Same order, same logical name
+    })
+
+    // In the real scanner, only one 'about' node would exist
+    // The test structure above would result in duplicate nodes in our mock
+    // Document the expected behavior: last processed file should win
+    const aboutNodes = tree.children.filter(c => c.value.name === 'about')
+
+    // Note: This mock creates duplicates; real scanner would replace
+    expect(aboutNodes.length).toBeGreaterThan(0)
+
+    // Document that when orders are equal, last file processed wins
+    // This aligns with the linter message about "file processed later is being kept"
+  })
+})

package/src/lib/file-router/scan-tree.ts

@@ -0,0 +1,205 @@
+import { TinyGlobby } from '#dep/tiny-globby/index'
+import { Tree, type TreeNode } from '#lib/tree/index'
+import { Path, Str } from '@wollybeard/kit'
+import type { Diagnostic } from './linter.ts'
+import type { Route, RouteFile } from './route.ts'
+
+//
+// Types
+//
+
+export type RouteTreeNodeType = 'directory' | 'file'
+
+export interface RouteTreeNodeValue {
+  name: string
+  order?: number
+  type: RouteTreeNodeType
+  route?: Route // Only present for file nodes
+}
+
+export type RouteTreeNode = TreeNode<RouteTreeNodeValue>
+
+export interface ScanTreeResult {
+  routeTree: RouteTreeNode
+  diagnostics: Diagnostic[]
+}
+
+//
+// Constants
+//
+
+const conventions = {
+  index: {
+    name: `index`,
+  },
+  numberedPrefix: {
+    pattern: Str.pattern<{ groups: ['order', 'name'] }>(/^(?<order>\d+)[_-](?<name>.+)$/),
+  },
+}
+
+//
+// Helpers
+//
+
+const parseSegment = (segment: string): { name: string; order?: number } => {
+  const match = Str.match(segment, conventions.numberedPrefix.pattern)
+  if (match) {
+    return {
+      name: match.groups.name,
+      order: parseInt(match.groups.order, 10),
+    }
+  }
+  return { name: segment }
+}
+
+const buildRouteTreeFromPaths = async (paths: string[], rootDir: string): Promise<RouteTreeNode> => {
+  // Root node (represents the pages directory itself)
+  const root = Tree.node<RouteTreeNodeValue>({
+    name: 'root',
+    type: 'directory',
+  })
+
+  // Process each file path
+  for (const filePath of paths) {
+    const relativePath = Path.relative(rootDir, filePath)
+
+    // Split the path into segments
+    const segments = relativePath.split(Path.sep).filter(s => s.length > 0)
+    if (segments.length === 0) continue // Skip root directory
+
+    // Navigate/create path in tree
+    let currentNode = root
+
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i]!
+      const isLast = i === segments.length - 1
+
+      // Parse segment for ordering
+      let segmentName = segment
+      // Strip extension for files
+      if (isLast && (segment.endsWith('.md') || segment.endsWith('.mdx'))) {
+        segmentName = segment.replace(/\.(md|mdx)$/, '')
+      }
+      const parsed = parseSegment(segmentName)
+
+      // Find existing child
+      const existingChildIndex = currentNode.children.findIndex(child => child.value.name === parsed.name)
+      let childNode = existingChildIndex >= 0 ? currentNode.children[existingChildIndex] : undefined
+
+      if (!childNode) {
+        // Create new node
+        if (isLast) {
+          // This is a file
+          const route = filePathToRoute(filePath, rootDir)
+          childNode = Tree.node<RouteTreeNodeValue>({
+            name: parsed.name,
+            order: parsed.order,
+            type: 'file',
+            route,
+          })
+        } else {
+          // This is a directory (implicit from file path)
+          childNode = Tree.node<RouteTreeNodeValue>({
+            name: parsed.name,
+            order: parsed.order,
+            type: 'directory',
+          })
+        }
+        currentNode.children.push(childNode)
+      } else if (isLast && childNode.value.type === 'file') {
+        // Handle collision for files with same name
+        // If new file has higher or equal order, replace the existing one (last wins for ties)
+        if (
+          parsed.order !== undefined
+          && (childNode.value.order === undefined || parsed.order >= childNode.value.order)
+        ) {
+          const route = filePathToRoute(filePath, rootDir)
+          const newNode = Tree.node<RouteTreeNodeValue>({
+            name: parsed.name,
+            order: parsed.order,
+            type: 'file',
+            route,
+          })
+          currentNode.children[existingChildIndex] = newNode
+          childNode = newNode
+        }
+        // Otherwise keep the existing node (when existing has higher order)
+      }
+
+      currentNode = childNode
+    }
+  }
+
+  // Sort the tree
+  return sortRouteTree(root)
+}
+
+const sortRouteTree = (tree: RouteTreeNode): RouteTreeNode => {
+  return Tree.sort(tree, (a, b) => {
+    // If both have orders, sort by order
+    if (a.order !== undefined && b.order !== undefined) {
+      return a.order - b.order
+    }
+    // If only one has order, it comes first
+    if (a.order !== undefined) return -1
+    if (b.order !== undefined) return 1
+    // Otherwise sort alphabetically
+    return a.name.localeCompare(b.name)
+  })
+}
+
+//
+// Main scan function
+//
+
+export const scanTree = async (parameters: {
+  dir: string
+  glob?: string
+}): Promise<ScanTreeResult> => {
+  const { dir, glob = `**/*` } = parameters
+
+  // Get all files
+  const filePaths = await TinyGlobby.glob(glob, {
+    absolute: true,
+    cwd: dir,
+    onlyFiles: true,
+  })
+
+  // Build tree structure (directories will be created implicitly)
+  const routeTree = await buildRouteTreeFromPaths(filePaths, dir)
+
+  // TODO: Implement tree-based linting
+  const diagnostics: Diagnostic[] = []
+
+  return {
+    routeTree,
+    diagnostics,
+  }
+}
+
+// Reuse existing route creation logic
+const filePathToRoute = (filePathExpression: string, rootDir: string): Route => {
+  const file: RouteFile = {
+    path: {
+      absolute: Path.parse(filePathExpression),
+      relative: Path.parse(Path.relative(rootDir, filePathExpression)),
+    },
+  }
+
+  const dirPath = Str.split(Str.removeSurrounding(file.path.relative.dir, Path.sep), Path.sep)
+
+  // Parse numbered prefix from filename
+  const prefixMatch = file.path.relative.name.match(conventions.numberedPrefix.pattern)
+  const order = prefixMatch?.groups?.[`order`] ? parseInt(prefixMatch.groups[`order`], 10) : undefined
+  const nameWithoutPrefix = prefixMatch?.groups?.[`name`] ?? file.path.relative.name
+
+  const logical = {
+    path: nameWithoutPrefix === conventions.index.name ? dirPath : dirPath.concat(nameWithoutPrefix),
+    order,
+  }
+
+  return {
+    logical,
+    file,
+  }
+}

package/src/lib/file-router/scan.ts

@@ -1,7 +1,9 @@
 import { TinyGlobby } from '#dep/tiny-globby/index'
+import { Tree } from '#lib/tree/index'
 import { Path, Str } from '@wollybeard/kit'
 import { type Diagnostic, lint } from './linter.ts'
-import { type Route, type RouteFile, type RouteLogical } from './route.ts'
+import { type Route, type RouteFile, type RouteLogical, routeToPathExpression } from './route.ts'
+import { scanTree } from './scan-tree.ts'
 
 //
 //
@@ -45,21 +47,21 @@ export const scan = async (parameters: {
   dir: string
   glob?: string
 }): Promise<ScanResult> => {
-  const { dir, glob = `**/*.{md,mdx}` } = parameters
-
-  // Get all files directly
-  const filePaths = await TinyGlobby.glob(glob, {
-    absolute: true,
-    cwd: dir,
-    onlyFiles: true,
+  // Use tree-based scanner
+  const treeResult = await scanTree(parameters)
+
+  // Flatten tree to get routes
+  const routes: Route[] = []
+  Tree.visit(treeResult.routeTree, (node) => {
+    if (node.value.type === 'file' && node.value.route) {
+      routes.push(node.value.route)
+    }
   })
 
-  // Convert to routes
-  const routes = filePaths.map(filePath => filePathToRoute(filePath, dir))
-
   // Apply linting
   const lintResult = lint(routes)
 
+  // Routes are already sorted by the tree structure
   return lintResult
 }
 
@@ -72,28 +74,14 @@ export const filePathToRoute = (filePathExpression: string, rootDir: string): Ro
   }
   const logical = filePathToRouteLogical(file.path.relative)
 
-  // Generate id and parentId for tree building
-  const id = filePathExpression // Use absolute path as unique ID
-  const relativePath = Path.relative(rootDir, filePathExpression)
-  const parentDir = Path.dirname(relativePath)
-  const parentId = parentDir === '.' ? null : Path.join(rootDir, parentDir)
-
   return {
     logical,
     file,
-    id,
-    parentId,
   }
 }
 
 export const filePathToRouteLogical = (filePath: Path.Parsed): RouteLogical => {
-  const dirSegments = Str.split(Str.removeSurrounding(filePath.dir, Path.sep), Path.sep)
-
-  // Parse numbered prefixes from directory segments
-  const dirPath = dirSegments.map(segment => {
-    const prefixMatch = Str.match(segment, conventions.numberedPrefix.pattern)
-    return prefixMatch?.groups.name ?? segment
-  })
+  const dirPath = Str.split(Str.removeSurrounding(filePath.dir, Path.sep), Path.sep)
 
   // Parse numbered prefix from filename
   const prefixMatch = Str.match(filePath.name, conventions.numberedPrefix.pattern)

package/src/lib/file-router/sidebar/index.ts

@@ -0,0 +1,3 @@
+export * as SidebarTree from './sidebar-tree.ts'
+// Re-export SidebarTree as Sidebar for backward compatibility
+export * as Sidebar from './sidebar-tree.ts'

package/src/lib/file-router/sidebar/sidebar-tree.test.ts

@@ -0,0 +1,123 @@
+import { Tree } from '#lib/tree/index'
+import { describe, expect, test } from 'vitest'
+import type { RouteTreeNode, RouteTreeNodeValue } from '../scan-tree.ts'
+import { buildFromTree } from './sidebar-tree.ts'
+
+// Helper to create mock routes
+const mockRoute = (path: string[]) => ({
+  logical: { path },
+  file: {
+    path: {
+      absolute: { root: '/', dir: '/', base: 'file.md', ext: '.md', name: 'file' },
+      relative: { root: '', dir: '', base: 'file.md', ext: '.md', name: 'file' },
+    },
+  },
+})
+
+// Helper to create file node
+const fileNode = (name: string, route: any): RouteTreeNode =>
+  Tree.node<RouteTreeNodeValue>({ name, type: 'file', route })
+
+// Helper to create directory node
+const dirNode = (name: string, children: RouteTreeNode[] = []): RouteTreeNode =>
+  Tree.node<RouteTreeNodeValue>({ name, type: 'directory' }, children)
+
+describe('sidebar-tree', () => {
+  test('builds sidebar from simple tree', () => {
+    const tree = dirNode('root', [
+      fileNode('getting-started', mockRoute(['getting-started'])),
+      dirNode('guide', [
+        fileNode('introduction', mockRoute(['guide', 'introduction'])),
+        fileNode('basics', mockRoute(['guide', 'basics'])),
+      ]),
+    ])
+
+    const sidebar = buildFromTree(tree, [])
+
+    expect(sidebar.items).toHaveLength(2)
+    expect(sidebar.items[0]).toMatchObject({
+      type: 'ItemLink',
+      pathExp: 'getting-started',
+      title: 'Getting Started',
+    })
+    const section = sidebar.items[1]
+    expect(section).toBeDefined()
+    expect(section!.type).toBe('ItemSection')
+    if (section!.type === 'ItemSection') {
+      expect(section).toMatchObject({
+        type: 'ItemSection',
+        title: 'Guide',
+        pathExp: 'guide',
+        isLinkToo: false,
+      })
+      expect(section!.links).toHaveLength(2)
+    }
+  })
+
+  test('handles index files correctly', () => {
+    const tree = dirNode('root', [
+      dirNode('guide', [
+        fileNode('index', mockRoute(['guide'])),
+        fileNode('introduction', mockRoute(['guide', 'introduction'])),
+      ]),
+    ])
+
+    const sidebar = buildFromTree(tree, [])
+
+    expect(sidebar.items).toHaveLength(1)
+    const section = sidebar.items[0]
+    expect(section).toBeDefined()
+    expect(section!.type).toBe('ItemSection')
+    if (section!.type === 'ItemSection') {
+      expect(section).toMatchObject({
+        type: 'ItemSection',
+        title: 'Guide',
+        pathExp: 'guide',
+        isLinkToo: true, // Should be true because of index file
+      })
+      expect(section!.links).toHaveLength(1) // Only introduction, not index
+    }
+  })
+
+  test('respects node ordering from tree', () => {
+    const tree = dirNode('root', [
+      Tree.node<RouteTreeNodeValue>({ name: 'quickstart', order: 5, type: 'file', route: mockRoute(['quickstart']) }),
+      Tree.node<RouteTreeNodeValue>({ name: 'guide', order: 10, type: 'file', route: mockRoute(['guide']) }),
+      fileNode('api', mockRoute(['api'])),
+      fileNode('troubleshooting', mockRoute(['troubleshooting'])),
+    ])
+
+    const sidebar = buildFromTree(tree, [])
+
+    // Tree should already be sorted, so sidebar should maintain that order
+    const titles = sidebar.items.map(item => item.title)
+    expect(titles).toEqual(['Quickstart', 'Guide', 'Api', 'Troubleshooting'])
+  })
+
+  test('handles nested directories', () => {
+    const tree = dirNode('root', [
+      dirNode('guide', [
+        fileNode('intro', mockRoute(['guide', 'intro'])),
+        dirNode('advanced', [
+          fileNode('performance', mockRoute(['guide', 'advanced', 'performance'])),
+          fileNode('optimization', mockRoute(['guide', 'advanced', 'optimization'])),
+        ]),
+      ]),
+    ])
+
+    const sidebar = buildFromTree(tree, [])
+
+    expect(sidebar.items).toHaveLength(1)
+    const guideSection = sidebar.items[0]
+    expect(guideSection).toBeDefined()
+    expect(guideSection!.type).toBe('ItemSection')
+    if (guideSection!.type === 'ItemSection') {
+      expect(guideSection!.links).toHaveLength(3) // intro + 2 from advanced subdirectory
+
+      const navTitles = guideSection!.links.map(nav => nav.title)
+      expect(navTitles).toContain('Intro')
+      expect(navTitles).toContain('Performance')
+      expect(navTitles).toContain('Optimization')
+    }
+  })
+})