polen 0.8.0-next.8 → 0.8.0

package/src/lib/errors/index.ts

@@ -1 +1 @@
-export * as Errors from './errors.js'
+export * as Errors from './errors.ts'

package/src/lib/errors/types.ts

@@ -1,4 +1,4 @@
-import type { ContextualError } from './ContextualError.js'
+import type { ContextualError } from './ContextualError.ts'
 
 export type Cause = Error | ContextualError
 export type Context = object

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[]
@@ -21,15 +47,61 @@ export interface LintResult {
 export const lint = (routes: Route[]): LintResult => {
   const diagnostics: Diagnostic[] = []
 
-  const seen = Idx.create({ toKey: routeToPathExpression })
+  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: {
@@ -58,6 +132,6 @@ export const lint = (routes: Route[]): LintResult => {
 
   return {
     diagnostics,
-    routes: seen.data.array,
+    routes: seen.toArray(),
   }
 }

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