polen 0.8.0-next.9 → 0.8.0

package/src/lib/favicon/index.ts

@@ -1 +1 @@
-export * as Favicon from './favicon.js'
+export * as Favicon from './favicon.ts'

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

@@ -0,0 +1,22 @@
+import type { Diagnostic } from './linter.ts'
+
+export const reportDiagnostics = (diagnostics: Diagnostic[]) => {
+  if (diagnostics.length === 0) return
+
+  const errors = diagnostics.filter(d => d.severity === 'error')
+  const warnings = diagnostics.filter(d => d.severity === 'warning')
+  const infos = diagnostics.filter(d => d.severity === 'info')
+
+  const summary = [
+    errors.length > 0 && `${errors.length} error${errors.length === 1 ? '' : 's'}`,
+    warnings.length > 0 && `${warnings.length} warning${warnings.length === 1 ? '' : 's'}`,
+    infos.length > 0 && `${infos.length} info${infos.length === 1 ? '' : 's'}`,
+  ].filter(Boolean).join(', ')
+
+  console.warn(`\n🔍 Polen found ${summary}:\n`)
+
+  diagnostics.forEach((diagnostic, index) => {
+    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.js'
-export * from './route.js'
-export * from './scan.js'
+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/index.test.ts

@@ -1,7 +1,7 @@
 import { Fn } from '@wollybeard/kit'
 import { describe, expect } from 'vitest'
-import { test } from '../../../tests/unit/helpers/test.js'
-import { FileRouter } from './index.js'
+import { test } from '../../../tests/unit/helpers/test.ts'
+import { FileRouter } from './index.ts'
 
 /* Note
 

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

@@ -1 +1 @@
-export * as FileRouter from './file-router.js'
+export * as FileRouter from './file-router.ts'

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

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'vitest'
+import { lint } from './linter.js'
+import type { Route } from './route.js'
+
+const createRoute = (path: string[], order?: number, isIndex = false): Route => {
+  const name = isIndex ? 'index' : path[path.length - 1]!
+
+  return {
+    logical: {
+      path,
+      order,
+    },
+    file: {
+      path: {
+        relative: {
+          root: '',
+          dir: path.slice(0, -1).join('/'),
+          base: `${name}.md`,
+          ext: '.md',
+          name: name, // Always use the base name, not the prefixed name
+        },
+        absolute: {
+          root: '/',
+          dir: `/project/pages/${path.slice(0, -1).join('/')}`,
+          base: `${name}.md`,
+          ext: '.md',
+          name: name,
+        },
+      },
+    },
+  }
+}
+
+describe('linter', () => {
+  test('warns about numbered prefix on index files', () => {
+    const routes: Route[] = [
+      createRoute(['docs'], 10, true), // 10_index.md
+      createRoute(['docs', 'getting-started']),
+    ]
+
+    const result = lint(routes)
+
+    expect(result.diagnostics).toHaveLength(1)
+    expect(result.diagnostics[0]).toMatchObject({
+      message: expect.stringContaining('Numbered prefix on index file has no effect'),
+      file: expect.objectContaining({
+        path: expect.objectContaining({
+          relative: expect.objectContaining({
+            name: 'index',
+          }),
+        }),
+      }),
+      order: 10,
+    })
+  })
+
+  test('no warning for index files without numbered prefix', () => {
+    const routes: Route[] = [
+      createRoute(['docs'], undefined, true), // index.md
+      createRoute(['docs', 'getting-started']),
+    ]
+
+    const result = lint(routes)
+
+    expect(result.diagnostics).toHaveLength(0)
+  })
+
+  test('warns about numbered prefix conflicts', () => {
+    const routes: Route[] = [
+      createRoute(['about'], 10), // 10_about.md
+      createRoute(['about'], 20), // 20_about.md
+    ]
+
+    const result = lint(routes)
+
+    expect(result.diagnostics).toHaveLength(1)
+    expect(result.diagnostics[0]).toMatchObject({
+      message: expect.stringContaining('conflicting routes due to numbered prefixes'),
+      kept: expect.objectContaining({ order: 20 }),
+      dropped: expect.objectContaining({ order: 10 }),
+    })
+  })
+
+  test('warns about index/literal conflicts', () => {
+    const routes: Route[] = [
+      createRoute(['docs'], undefined, true), // docs/index.md
+      createRoute(['docs']), // docs.md
+    ]
+
+    const result = lint(routes)
+
+    expect(result.diagnostics).toHaveLength(1)
+    expect(result.diagnostics[0]).toMatchObject({
+      message: expect.stringContaining('conflicting routes'),
+      literal: expect.any(Object),
+      index: expect.any(Object),
+    })
+  })
+
+  test('warns about numbered prefix conflicts with same order number', () => {
+    const routes: Route[] = [
+      createRoute(['about'], 10), // 10_about.md
+      createRoute(['about'], 10), // 10-about.md (same order)
+    ]
+
+    const result = lint(routes)
+
+    expect(result.diagnostics).toHaveLength(1)
+    expect(result.diagnostics[0]).toMatchObject({
+      message: expect.stringContaining('Both files have the same order number (10)'),
+      kept: expect.objectContaining({ order: 10 }),
+      dropped: expect.objectContaining({ order: 10 }),
+    })
+  })
+})

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

@@ -1,9 +1,13 @@
 import { Idx, Path } from '@wollybeard/kit'
-import { type Route, type RouteFile, routeIsFromIndexFile, routeToPathExpression } from './route.js'
+import { type Route, type RouteFile, routeIsFromIndexFile, routeToPathExpression } from './route.ts'
 
-export type Diagnostic = DiagnosticIndexConflict
+export type DiagnosticSeverity = 'error' | 'warning' | 'info'
+
+export type Diagnostic = DiagnosticIndexConflict | DiagnosticNumberedPrefixConflict | DiagnosticNumberedPrefixOnIndex
 
 export interface DiagnosticIndexConflict {
+  type: 'index-conflict'
+  severity: DiagnosticSeverity
   message: string
   literal: {
     file: RouteFile
@@ -13,6 +17,28 @@ export interface DiagnosticIndexConflict {
   }
 }
 
+export interface DiagnosticNumberedPrefixConflict {
+  type: 'numbered-prefix-conflict'
+  severity: DiagnosticSeverity
+  message: string
+  kept: {
+    file: RouteFile
+    order: number
+  }
+  dropped: {
+    file: RouteFile
+    order: number
+  }
+}
+
+export interface DiagnosticNumberedPrefixOnIndex {
+  type: 'numbered-prefix-on-index'
+  severity: DiagnosticSeverity
+  message: string
+  file: RouteFile
+  order: number
+}
+
 export interface LintResult {
   diagnostics: Diagnostic[]
   routes: Route[]
@@ -23,13 +49,59 @@ export const lint = (routes: Route[]): LintResult => {
 
   const seen = Idx.create({ key: routeToPathExpression })
 
-  // ━ Check for conflict between index and literal.
-  //   Note: There is no other way for paths to conflict so we safely assuming the cause is index+literal.
+  // ━ Check for numbered prefix on index files
+  for (const route of routes) {
+    if (routeIsFromIndexFile(route) && route.logical.order !== undefined) {
+      const diagnostic: DiagnosticNumberedPrefixOnIndex = {
+        type: 'numbered-prefix-on-index',
+        severity: 'warning',
+        message: `Numbered prefix on index file has no effect. The file:\n  ${
+          Path.format(route.file.path.relative)
+        }\n\nhas a numbered prefix (${route.logical.order}_) which doesn't affect ordering since index files represent their parent directory.`,
+        file: route.file,
+        order: route.logical.order,
+      }
+      diagnostics.push(diagnostic)
+    }
+  }
+
+  // ━ Check for conflicts
   for (const route of routes) {
     // Detect
     const seenRoute = seen.get(route)
 
     if (seenRoute) {
+      // Check if it's a numbered prefix conflict
+      if (seenRoute.logical.order !== undefined && route.logical.order !== undefined) {
+        // Handle numbered prefix conflict - keep the one with higher order
+        const [kept, dropped] = seenRoute.logical.order > route.logical.order ? [seenRoute, route] : [route, seenRoute]
+
+        if (dropped === seenRoute) {
+          seen.set(kept)
+        }
+
+        const orderMessage = kept.logical.order === dropped.logical.order
+          ? `Both files have the same order number (${kept.logical.order}). The file processed later is being kept based on processing order.`
+          : `The file with lower order number (${dropped.logical.order}) is being dropped in favor of the one with higher order (${kept.logical.order}).`
+
+        const diagnostic: DiagnosticNumberedPrefixConflict = {
+          type: 'numbered-prefix-conflict',
+          severity: 'error',
+          // dprint-ignore
+          message: `Your files represent conflicting routes due to numbered prefixes. This file:\n  ${Path.format(kept.file.path.relative)}\n\nconflicts with this file:\n\n  ${Path.format(dropped.file.path.relative)}.\n\n${orderMessage}`,
+          kept: {
+            file: kept.file,
+            order: kept.logical.order!,
+          },
+          dropped: {
+            file: dropped.file,
+            order: dropped.logical.order!,
+          },
+        }
+        diagnostics.push(diagnostic)
+        continue
+      }
+
       // Fix - ignore the index
       const [index, literal] = routeIsFromIndexFile(route) ? [route, seenRoute] : [seenRoute, route]
       if (seenRoute === index) {
@@ -38,6 +110,8 @@ export const lint = (routes: Route[]): LintResult => {
 
       // Report
       const diagnostic: DiagnosticIndexConflict = {
+        type: 'index-conflict',
+        severity: 'error',
         // dprint-ignore
         message: `Your files represent conflicting routes. This index file route:\n  ${Path.format(index.file.path.relative)}\n\nconflicts with this literal file route:\n\n  ${Path.format(literal.file.path.relative)}.\n\nYour index route is being ignored.`,
         literal: {

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

@@ -1,4 +1,4 @@
-import { arrayEquals } from '#lib/kit-temp.js'
+import { arrayEquals } from '#lib/kit-temp'
 import { type Path } from '@wollybeard/kit'
 
 //
@@ -40,6 +40,7 @@ export interface Route {
 
 export interface RouteLogical {
   path: Path
+  order?: number
 }
 
 export interface RouteFile {

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.js'
+
+// 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.js'
+import type { Route, RouteFile } from './route.js'
+
+//
+// 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,
+  }
+}