@life-and-dev/mdsite 0.0.3

package/mdsite-nuxt/app/composables/useNavigationTree.ts

@@ -0,0 +1,174 @@
+import type { MinimalTreeNode } from '../../scripts/generate-indices'
+
+export interface TreeNode {
+  id: string
+  title: string
+  path: string
+  order: number
+  children: TreeNode[]
+  parent?: TreeNode
+  externalUrl?: string
+  isExternal?: boolean
+  isSeparator?: boolean
+  isHeader?: boolean
+  isPrimary?: boolean  // Marks primary menu items (string/array syntax, not aliases)
+  description?: string
+  keywords?: string[]
+}
+
+/**
+ * Generate cache key that changes every hour
+ * This ensures menu changes are picked up within 1 hour
+ */
+function getCacheKey(): string {
+  const now = new Date()
+  const hourTimestamp = Math.floor(now.getTime() / (1000 * 60 * 60)) // Changes every hour
+  return `navigation-tree-${hourTimestamp}`
+}
+
+/**
+ * Build hierarchical navigation tree from @nuxt/content collection
+ */
+export function useNavigationTree() {
+  // Use useState for server-side rendering and client hydration
+  // Cache key changes hourly to pick up menu structure changes
+  const tree = useState<TreeNode | null>(getCacheKey(), () => null)
+  // Use useState for loading state to prevent duplicate fetches across components
+  const isLoading = useState<boolean>(`${getCacheKey()}-loading`, () => false)
+
+  /**
+   * Load navigation tree from pre-built JSON file
+   * Uses cached tree if available to avoid rebuilding on every navigation
+   * Prevents concurrent fetches when multiple components mount simultaneously
+   */
+  async function loadTree() {
+    // Return if already loaded OR currently loading (prevents race condition)
+    if (tree.value !== null || isLoading.value) {
+      return
+    }
+
+    isLoading.value = true
+    try {
+      // Fetch pre-built navigation JSON
+      const minimalNodes = await $fetch<MinimalTreeNode[]>('/_navigation.json')
+
+      // Convert to TreeNode format with parent references
+      tree.value = buildTreeFromMinimalNodes(minimalNodes)
+    } catch (error) {
+      console.error('Error loading navigation tree:', error)
+      tree.value = null
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Find node by path in tree
+   */
+  function findNodeByPath(path: string, node: TreeNode | null = tree.value): TreeNode | null {
+    if (!node) return null
+    if (node.path === path) return node
+
+    for (const child of node.children) {
+      const found = findNodeByPath(path, child)
+      if (found) return found
+    }
+
+    return null
+  }
+
+  /**
+   * Find primary node by path in tree (only returns nodes with isPrimary=true)
+   */
+  function findPrimaryNodeByPath(path: string, node: TreeNode | null = tree.value): TreeNode | null {
+    if (!node) return null
+    if (node.path === path && node.isPrimary) return node
+
+    for (const child of node.children) {
+      const found = findPrimaryNodeByPath(path, child)
+      if (found) return found
+    }
+
+    return null
+  }
+
+  /**
+   * Get all ancestor paths for a given path
+   */
+  function getAncestorPaths(path: string): string[] {
+    const segments = path.split('/').filter(Boolean)
+    const ancestors: string[] = ['/']
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      ancestors.push('/' + segments.slice(0, i + 1).join('/'))
+    }
+
+    return ancestors
+  }
+
+  /**
+   * Get sibling nodes at the same level
+   */
+  function getSiblings(nodePath: string): TreeNode[] {
+    const node = findNodeByPath(nodePath)
+    if (!node || !node.parent) return []
+    return node.parent.children.filter(child => child.path !== nodePath)
+  }
+
+  return {
+    tree,
+    isLoading,
+    loadTree,
+    findNodeByPath,
+    findPrimaryNodeByPath,
+    getAncestorPaths,
+    getSiblings
+  }
+}
+
+/**
+ * Convert MinimalTreeNode array to TreeNode with parent references
+ */
+function buildTreeFromMinimalNodes(minimalNodes: MinimalTreeNode[]): TreeNode {
+  const { siteName } = useSiteConfig()
+  // Create root node
+  const root: TreeNode = {
+    id: 'root',
+    title: siteName || 'Home',
+    path: '/',
+    order: -1,
+    children: []
+  }
+
+  // Recursively convert minimal nodes to TreeNode format
+  function convertNode(minimalNode: MinimalTreeNode, parent: TreeNode, order: number): TreeNode {
+    const node: TreeNode = {
+      id: minimalNode.id,
+      title: minimalNode.title,
+      path: minimalNode.path,
+      order,
+      children: [],
+      parent,
+      description: minimalNode.description,
+      isPrimary: minimalNode.isPrimary,
+      isExternal: minimalNode.type === 'external',
+      isSeparator: minimalNode.type === 'separator',
+      isHeader: minimalNode.type === 'header',
+      externalUrl: minimalNode.type === 'external' ? minimalNode.path : undefined
+    }
+
+    // Recursively convert children
+    if (minimalNode.children) {
+      node.children = minimalNode.children.map((child, index) =>
+        convertNode(child, node, index)
+      )
+    }
+
+    return node
+  }
+
+  // Convert all top-level nodes
+  root.children = minimalNodes.map((node, index) => convertNode(node, root, index))
+
+  return root
+}

package/mdsite-nuxt/app/composables/useSearchIndex.ts

@@ -0,0 +1,47 @@
+import type { SearchIndexEntry } from '../../scripts/generate-indices'
+
+/**
+ * Fetch and cache search index from pre-built JSON file
+ * Uses useState to prevent duplicate fetches across component instances
+ */
+export function useSearchIndex() {
+  // Cache search index using useState (shared across all components)
+  const searchIndex = useState<SearchIndexEntry[] | null>('search-index', () => null)
+  const isLoading = useState<boolean>('search-index-loading', () => false)
+
+  /**
+   * Load search index from pre-built JSON file
+   * Cached result prevents duplicate fetches
+   */
+  async function loadSearchIndex(): Promise<SearchIndexEntry[]> {
+    // Return cached index if available
+    if (searchIndex.value !== null) {
+      return searchIndex.value
+    }
+
+    // Return empty array if already loading (prevents race condition)
+    if (isLoading.value) {
+      return []
+    }
+
+    isLoading.value = true
+
+    try {
+      const index = await $fetch<SearchIndexEntry[]>('/_search-index.json')
+      searchIndex.value = index
+      return index
+    } catch (error) {
+      console.error('Error loading search index:', error)
+      searchIndex.value = []
+      return []
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  return {
+    searchIndex,
+    isLoading,
+    loadSearchIndex
+  }
+}

package/mdsite-nuxt/app/composables/useSearchRelevance.test.ts

@@ -0,0 +1,255 @@
+/**
+ * Unit tests for search relevance scoring
+ */
+
+import { describe, it, expect } from 'vitest'
+import { calculateRelevanceScore, sortByRelevance, FIELD_WEIGHTS, MATCH_QUALITY } from './useSearchRelevance'
+import type { SearchableFields } from './useSearchRelevance'
+
+describe('useSearchRelevance', () => {
+  describe('calculateRelevanceScore', () => {
+    it('should score title matches higher than description matches', () => {
+      const titleMatch: SearchableFields = {
+        title: 'Church',
+        description: 'About the kingdom',
+        path: '/church',
+      }
+
+      const descriptionMatch: SearchableFields = {
+        title: 'Kingdom',
+        description: 'About the church',
+        path: '/kingdom',
+      }
+
+      const titleScore = calculateRelevanceScore(titleMatch, 'church')
+      const descScore = calculateRelevanceScore(descriptionMatch, 'church')
+
+      expect(titleScore).toBeGreaterThan(descScore)
+    })
+
+    it('should score exact matches higher than partial matches', () => {
+      const exactMatch: SearchableFields = {
+        title: 'Church',
+        path: '/church',
+      }
+
+      const partialMatch: SearchableFields = {
+        title: 'Church History',
+        path: '/church-history',
+      }
+
+      const exactScore = calculateRelevanceScore(exactMatch, 'church')
+      const partialScore = calculateRelevanceScore(partialMatch, 'church')
+
+      expect(exactScore).toBeGreaterThan(partialScore)
+    })
+
+    it('should score startsWith matches higher than contains matches', () => {
+      const startsWithMatch: SearchableFields = {
+        title: 'Dark Ages',
+        path: '/dark-ages',
+      }
+
+      const containsMatch: SearchableFields = {
+        title: 'The Dark Period',
+        path: '/dark-period',
+      }
+
+      const startsScore = calculateRelevanceScore(startsWithMatch, 'dark')
+      const containsScore = calculateRelevanceScore(containsMatch, 'dark')
+
+      expect(startsScore).toBeGreaterThan(containsScore)
+    })
+
+    it('should score keyword matches appropriately', () => {
+      const keywordMatch: SearchableFields = {
+        title: 'History',
+        keywords: ['Constantine', 'Rome', 'Empire'],
+        path: '/history',
+      }
+
+      const score = calculateRelevanceScore(keywordMatch, 'constantine')
+      expect(score).toBeGreaterThan(0)
+      expect(score).toBeLessThan(FIELD_WEIGHTS.title * MATCH_QUALITY.exact)
+    })
+
+    it('should add bonus for multi-field matches', () => {
+      const singleFieldMatch: SearchableFields = {
+        title: 'Church',
+        description: 'About the kingdom',
+        path: '/church',
+      }
+
+      const multiFieldMatch: SearchableFields = {
+        title: 'Church',
+        description: 'About the church',
+        path: '/church',
+      }
+
+      const singleScore = calculateRelevanceScore(singleFieldMatch, 'church')
+      const multiScore = calculateRelevanceScore(multiFieldMatch, 'church')
+
+      expect(multiScore).toBeGreaterThan(singleScore)
+    })
+
+    it('should penalize deep paths', () => {
+      const shallowPage: SearchableFields = {
+        title: 'Church',
+        path: '/church',
+      }
+
+      const deepPage: SearchableFields = {
+        title: 'Church',
+        path: '/kingdom/church/history/constantine',
+      }
+
+      const shallowScore = calculateRelevanceScore(shallowPage, 'church')
+      const deepScore = calculateRelevanceScore(deepPage, 'church')
+
+      expect(shallowScore).toBeGreaterThan(deepScore)
+    })
+
+    it('should handle case-insensitive matching', () => {
+      const page: SearchableFields = {
+        title: 'CHURCH',
+        path: '/church',
+      }
+
+      const lowerScore = calculateRelevanceScore(page, 'church')
+      const upperScore = calculateRelevanceScore(page, 'CHURCH')
+      const mixedScore = calculateRelevanceScore(page, 'ChUrCh')
+
+      expect(lowerScore).toEqual(upperScore)
+      expect(upperScore).toEqual(mixedScore)
+    })
+
+    it('should return 0 for non-matching pages', () => {
+      const page: SearchableFields = {
+        title: 'Kingdom',
+        description: 'About the kingdom',
+        path: '/kingdom',
+      }
+
+      const score = calculateRelevanceScore(page, 'church')
+      expect(score).toEqual(0)
+    })
+
+    it('should handle pages with missing fields', () => {
+      const minimalPage: SearchableFields = {
+        title: 'Church',
+      }
+
+      const score = calculateRelevanceScore(minimalPage, 'church')
+      expect(score).toBeGreaterThan(0)
+    })
+
+    it('should score excerpt matches lowest', () => {
+      const excerptMatch: SearchableFields = {
+        title: 'Kingdom',
+        excerpt: 'church',
+        path: '/kingdom',
+      }
+
+      const titleMatch: SearchableFields = {
+        title: 'Church',
+        path: '/church',
+      }
+
+      const excerptScore = calculateRelevanceScore(excerptMatch, 'church')
+      const titleScore = calculateRelevanceScore(titleMatch, 'church')
+
+      expect(titleScore).toBeGreaterThan(excerptScore)
+    })
+  })
+
+  describe('sortByRelevance', () => {
+    it('should sort results by score descending', () => {
+      const pages: SearchableFields[] = [
+        { title: 'History of the Church', path: '/history' },
+        { title: 'Church', path: '/church' },
+        { title: 'Kingdom', description: 'About the church', path: '/kingdom' },
+      ]
+
+      const sorted = sortByRelevance(pages, 'church')
+
+      expect(sorted.length).toBe(3)
+      // Exact title match should be first
+      expect(sorted[0]?.title).toBe('Church')
+      // Title startsWith match should be second
+      expect(sorted[1]?.title).toBe('History of the Church')
+      // Description match should be last
+      expect(sorted[2]?.title).toBe('Kingdom')
+    })
+
+    it('should use alphabetical tie-breaking', () => {
+      const pages: SearchableFields[] = [
+        { title: 'Zebra Church', path: '/zebra' },
+        { title: 'Alpha Church', path: '/alpha' },
+        { title: 'Beta Church', path: '/beta' },
+      ]
+
+      const sorted = sortByRelevance(pages, 'church')
+
+      expect(sorted.length).toBe(3)
+      // All have same score, should be alphabetical
+      expect(sorted[0]?.title).toBe('Alpha Church')
+      expect(sorted[1]?.title).toBe('Beta Church')
+      expect(sorted[2]?.title).toBe('Zebra Church')
+    })
+
+    it('should handle empty results', () => {
+      const pages: SearchableFields[] = []
+      const sorted = sortByRelevance(pages, 'church')
+      expect(sorted).toEqual([])
+    })
+
+    it('should handle custom title getter', () => {
+      interface CustomPage extends SearchableFields {
+        customTitle: string
+      }
+
+      const pages: CustomPage[] = [
+        { customTitle: 'Zebra', title: 'A', path: '/zebra' },
+        { customTitle: 'Alpha', title: 'Z', path: '/alpha' },
+      ]
+
+      const sorted = sortByRelevance(
+        pages,
+        'page',
+        (page) => (page as CustomPage).customTitle
+      )
+
+      expect(sorted.length).toBe(2)
+      // Should use customTitle for alphabetical sorting
+      expect(sorted[0]?.customTitle).toBe('Alpha')
+      expect(sorted[1]?.customTitle).toBe('Zebra')
+    })
+
+    it('should prioritize relevance over alphabetical order', () => {
+      const pages: SearchableFields[] = [
+        { title: 'Zebra Church Article', path: '/zebra' },
+        { title: 'Church', path: '/church' },
+      ]
+
+      const sorted = sortByRelevance(pages, 'church')
+
+      expect(sorted.length).toBe(2)
+      // Exact match should win despite being alphabetically later
+      expect(sorted[0]?.title).toBe('Church')
+      expect(sorted[1]?.title).toBe('Zebra Church Article')
+    })
+  })
+
+  describe('field weight constants', () => {
+    it('should have correct field weight hierarchy', () => {
+      expect(FIELD_WEIGHTS.title).toBeGreaterThan(FIELD_WEIGHTS.keywords)
+      expect(FIELD_WEIGHTS.keywords).toBeGreaterThan(FIELD_WEIGHTS.description)
+      expect(FIELD_WEIGHTS.description).toBeGreaterThan(FIELD_WEIGHTS.excerpt)
+    })
+
+    it('should have correct match quality multipliers', () => {
+      expect(MATCH_QUALITY.exact).toBeGreaterThan(MATCH_QUALITY.startsWith)
+      expect(MATCH_QUALITY.startsWith).toBeGreaterThan(MATCH_QUALITY.contains)
+    })
+  })
+})

package/mdsite-nuxt/app/composables/useSearchRelevance.ts

@@ -0,0 +1,207 @@
+/**
+ * Search relevance scoring system
+ *
+ * Calculates relevance scores for search results based on:
+ * - Field weights (title > keywords > description > excerpt)
+ * - Match quality (exact > startsWith > contains)
+ * - Position bonus (matches at start of field)
+ * - Path depth penalty (prefer top-level pages)
+ * - Multi-field match bonus
+ */
+
+// Field weight constants
+export const FIELD_WEIGHTS = {
+  title: 10,
+  keywords: 7,
+  description: 3,
+  excerpt: 1,
+} as const
+
+// Match quality multipliers
+export const MATCH_QUALITY = {
+  exact: 3,
+  startsWith: 2,
+  contains: 1,
+} as const
+
+// Scoring bonuses/penalties
+const POSITION_BONUS = 2  // Bonus for match at start of field
+const MULTI_FIELD_BONUS = 3  // Bonus when query matches multiple fields
+const DEPTH_PENALTIES = {
+  root: 0,      // /page
+  shallow: -1,  // /church/history (1-2 levels)
+  deep: -2,     // /church/history/subsection (3+ levels)
+} as const
+
+export interface SearchableFields {
+  title?: string
+  description?: string
+  excerpt?: string
+  keywords?: string[]
+  path?: string
+}
+
+export interface FieldMatchResult {
+  field: keyof typeof FIELD_WEIGHTS
+  score: number
+  matchType: keyof typeof MATCH_QUALITY
+}
+
+/**
+ * Determine match quality for a field value
+ */
+function getMatchQuality(fieldValue: string, query: string): keyof typeof MATCH_QUALITY | null {
+  const fieldLower = fieldValue.toLowerCase()
+  const queryLower = query.toLowerCase()
+
+  if (fieldLower === queryLower) {
+    return 'exact'
+  }
+  if (fieldLower.startsWith(queryLower)) {
+    return 'startsWith'
+  }
+  if (fieldLower.includes(queryLower)) {
+    return 'contains'
+  }
+
+  return null
+}
+
+/**
+ * Calculate score for a single field match
+ */
+function calculateFieldScore(
+  fieldValue: string,
+  query: string,
+  fieldName: keyof typeof FIELD_WEIGHTS
+): number {
+  const matchType = getMatchQuality(fieldValue, query)
+  if (!matchType) return 0
+
+  const baseWeight = FIELD_WEIGHTS[fieldName]
+  const qualityMultiplier = MATCH_QUALITY[matchType]
+
+  // Calculate base score with quality multiplier
+  let score = baseWeight * qualityMultiplier
+
+  // Add position bonus if match is at start
+  const fieldLower = fieldValue.toLowerCase()
+  const queryLower = query.toLowerCase()
+  if (fieldLower.startsWith(queryLower)) {
+    score += POSITION_BONUS
+  }
+
+  return score
+}
+
+/**
+ * Calculate depth penalty based on path structure
+ */
+function calculateDepthPenalty(path: string): number {
+  const segments = path.split('/').filter(Boolean)
+  const depth = segments.length
+
+  if (depth <= 1) return DEPTH_PENALTIES.root
+  if (depth <= 2) return DEPTH_PENALTIES.shallow
+  return DEPTH_PENALTIES.deep
+}
+
+/**
+ * Calculate relevance score for a page
+ */
+export function calculateRelevanceScore(page: SearchableFields, query: string): number {
+  const queryLower = query.toLowerCase()
+  const matches: FieldMatchResult[] = []
+  let totalScore = 0
+
+  // Score title match
+  if (page.title) {
+    const score = calculateFieldScore(page.title, query, 'title')
+    if (score > 0) {
+      matches.push({ field: 'title', score, matchType: getMatchQuality(page.title, query)! })
+      totalScore += score
+    }
+  }
+
+  // Score description match
+  if (page.description) {
+    const score = calculateFieldScore(page.description, query, 'description')
+    if (score > 0) {
+      matches.push({ field: 'description', score, matchType: getMatchQuality(page.description, query)! })
+      totalScore += score
+    }
+  }
+
+  // Score excerpt match
+  if (page.excerpt) {
+    const score = calculateFieldScore(page.excerpt, query, 'excerpt')
+    if (score > 0) {
+      matches.push({ field: 'excerpt', score, matchType: getMatchQuality(page.excerpt, query)! })
+      totalScore += score
+    }
+  }
+
+  // Score keywords match (take highest scoring keyword)
+  if (page.keywords && page.keywords.length > 0) {
+    let maxKeywordScore = 0
+    for (const keyword of page.keywords) {
+      const score = calculateFieldScore(keyword, query, 'keywords')
+      if (score > maxKeywordScore) {
+        maxKeywordScore = score
+      }
+    }
+    if (maxKeywordScore > 0) {
+      matches.push({ field: 'keywords', score: maxKeywordScore, matchType: 'contains' })
+      totalScore += maxKeywordScore
+    }
+  }
+
+  // Add multi-field bonus if query matches in 2+ fields
+  if (matches.length >= 2) {
+    totalScore += MULTI_FIELD_BONUS
+  }
+
+  // Apply depth penalty
+  if (page.path) {
+    totalScore += calculateDepthPenalty(page.path)
+  }
+
+  return Math.max(0, totalScore)  // Ensure non-negative
+}
+
+/**
+ * Sort search results by relevance score
+ */
+export function sortByRelevance<T extends SearchableFields>(
+  results: T[],
+  query: string,
+  getTitleFn: (item: T) => string = (item) => item.title || ''
+): T[] {
+  // Calculate scores for all results
+  const scored = results.map(item => ({
+    item,
+    score: calculateRelevanceScore(item, query),
+  }))
+
+  // Sort by score (descending), then alphabetically by title
+  scored.sort((a, b) => {
+    if (b.score !== a.score) {
+      return b.score - a.score
+    }
+    return getTitleFn(a.item).localeCompare(getTitleFn(b.item))
+  })
+
+  return scored.map(s => s.item)
+}
+
+/**
+ * Composable for search relevance scoring
+ */
+export function useSearchRelevance() {
+  return {
+    calculateRelevanceScore,
+    sortByRelevance,
+    FIELD_WEIGHTS,
+    MATCH_QUALITY,
+  }
+}