Utility Functions

/**
 * Normalize URL path by removing hash and file extensions
 * @param {string} path - Raw path to normalize
 * @returns {string} Normalized path
 */
function normalize(path): string;

/**
 * Extract hash fragment from path
 * @param {string} path - Path containing hash fragment  
 * @returns {string|undefined} Hash fragment or undefined
 */
function getHash(path): string | undefined;

/**
 * Ensure .html extension on internal paths
 * @param {string} path - Path to process
 * @returns {string} Path with .html extension
 */
function ensureExt(path): string;

/**
 * Check if path is external URL
 * @param {string} path - Path to check
 * @returns {boolean} True if external URL
 */
function isExternal(path): boolean;

/**
 * Check if path is mailto link
 * @param {string} path - Path to check
 * @returns {boolean} True if mailto link
 */
function isMailto(path): boolean;

/**
 * Check if path is tel link  
 * @param {string} path - Path to check
 * @returns {boolean} True if tel link
 */
function isTel(path): boolean;

import { normalize, isExternal, ensureExt } from '@vuepress/theme-default/util';

// Normalize paths
normalize('/guide/installation.md#setup'); // → '/guide/installation'
normalize('/api.html'); // → '/api'

// Check external links
isExternal('https://github.com'); // → true
isExternal('/internal-page'); // → false

// Ensure extensions
ensureExt('/guide/'); // → '/guide/'  
ensureExt('/api'); // → '/api.html'

/**
 * Check if route matches path (for active link states)
 * @param {object} route - Vue router route object
 * @param {string} path - Path to compare against
 * @returns {boolean} True if route is active for path
 */
function isActive(route, path): boolean;

/**
 * Process navigation link configuration
 * @param {object} linkItem - Navigation link configuration
 * @returns {object} Processed link item with type
 */
function resolveNavLinkItem(linkItem): object;

// Check active state
const route = this.$route;
isActive(route, '/guide/'); // → true if current route matches

// Process nav links
const navItem = resolveNavLinkItem({
  text: 'Guide',
  link: '/guide/',
  items: [...]
}); // → { text: 'Guide', link: '/guide/', type: 'links' }

/**
 * Resolve page object from path and pages array
 * @param {Array} pages - Array of all site pages
 * @param {string} rawPath - Raw path to resolve
 * @param {string} [base] - Base path for resolution
 * @returns {object} Resolved page object
 */
function resolvePage(pages, rawPath, base?): object;

/**
 * Build sidebar navigation structure for current page
 * @param {object} page - Current page object
 * @param {string} regularPath - Regular path of current page
 * @param {object} site - Site data with pages and config
 * @param {string} localePath - Locale path for i18n
 * @returns {Array} Array of sidebar groups and items
 */
function resolveSidebarItems(page, regularPath, site, localePath): Array;

/**
 * Match current path to sidebar configuration
 * @param {string} regularPath - Regular path to match
 * @param {object|Array} config - Sidebar configuration
 * @returns {object} Matching config with base path
 */
function resolveMatchingConfig(regularPath, config): object;

// Resolve page
const page = resolvePage(
  site.pages,
  '/guide/installation',
  '/guide/'
); // → { type: 'page', path: '/guide/installation.html', title: '...' }

// Build sidebar items
const sidebarItems = resolveSidebarItems(
  currentPage,
  '/guide/installation',
  site,
  '/'
); // → [{ type: 'group', title: 'Guide', children: [...] }]

/**
 * Group h3 headers under h2 parent headers
 * @param {Array} headers - Array of header objects
 * @returns {Array} Grouped headers with h3s as children of h2s
 */
function groupHeaders(headers): Array;

const headers = [
  { level: 2, title: 'Getting Started', slug: 'getting-started' },
  { level: 3, title: 'Installation', slug: 'installation' },
  { level: 3, title: 'Configuration', slug: 'configuration' },
  { level: 2, title: 'Advanced', slug: 'advanced' }
];

const grouped = groupHeaders(headers);
// → [
//     { 
//       level: 2, 
//       title: 'Getting Started', 
//       children: [
//         { level: 3, title: 'Installation', slug: 'installation' },
//         { level: 3, title: 'Configuration', slug: 'configuration' }
//       ]
//     },
//     { level: 2, title: 'Advanced', slug: 'advanced' }
//   ]

/** Regex for URL hash fragments (#section) */
const hashRE: RegExp = /#.*$/;

/** Regex for .md and .html file extensions */
const extRE: RegExp = /\.(md|html)$/;

/** Regex for trailing slashes */
const endingSlashRE: RegExp = /\/$/;

/** Regex for external URLs (protocol prefixes) */
const outboundRE: RegExp = /^[a-z]+:/i;

// Test against patterns
hashRE.test('/guide#setup'); // → true
extRE.test('/api.md'); // → true
endingSlashRE.test('/guide/'); // → true
outboundRE.test('https://example.com'); // → true

interface Page {
  /** Unique page key */
  key: string;
  /** Full page path with extension */
  path: string;
  /** Regular path without extension */
  regularPath: string;
  /** Page title */
  title: string;
  /** Frontmatter data */
  frontmatter: object;
  /** Page headers for navigation */
  headers?: Header[];
}

interface Header {
  /** Header level (1-6) */
  level: number;
  /** Header text content */
  title: string;
  /** URL slug for linking */
  slug: string;
  /** Nested child headers */
  children?: Header[];
}

interface SiteData {
  /** All site pages */
  pages: Page[];
  /** Theme configuration */
  themeConfig: object;
}

interface ResolvedPage {
  /** Page type */
  type: 'page' | 'external';
  /** Page path */
  path: string;
  /** Page title */
  title?: string;
  /** Page headers */
  headers?: Header[];
}

interface SidebarGroup {
  /** Group type */
  type: 'group' | 'page' | 'external' | 'auto';
  /** Group title */
  title?: string;
  /** Group path */
  path?: string;
  /** Child items */
  children?: SidebarGroup[];
  /** Whether group can be collapsed */
  collapsable?: boolean;
  /** Sidebar depth */
  sidebarDepth?: number;
  /** Initial open group index */
  initialOpenGroupIndex?: number;
}

interface NavLinkItem {
  /** Link text */
  text: string;
  /** Link URL */
  link?: string;
  /** Nested items for dropdown */
  items?: NavLinkItem[];
  /** Link type */
  type?: 'link' | 'links';
}

// Page resolution with error logging
function resolvePage(pages, rawPath, base) {
  // ... resolution logic ...
  if (!found) {
    console.error(`[vuepress] No matching page found for sidebar item "${rawPath}"`);
    return {};
  }
  return page;
}