@alliance-droid/svelte-docs-system 0.0.1

package/src/lib/configIntegration.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect } from 'vitest';
+import { mergeConfig, validateConfig, DEFAULT_CONFIG } from './config';
+import { parseConfigFile } from './configParser';
+import { createRouteConfig, validateRoute, buildNavLink, isDocsRoute } from './routing';
+import { generateNavigationFromFiles } from './navigationBuilder';
+import { generateCSSVariables, validateTheme, getThemeTemplate } from './themeCustomization';
+
+describe('Configuration System Integration', () => {
+  describe('Full Config Workflow', () => {
+    it('should load and validate a complete configuration', () => {
+      const configContent = JSON.stringify({
+        name: 'My Documentation',
+        docsRoute: '/help',
+        theme: {
+          primary: '#0066cc',
+          secondary: '#ff6b6b',
+        },
+        navigation: {
+          title: 'Help Center',
+          autoGenerate: true,
+        },
+      });
+
+      const parseResult = parseConfigFile(configContent, 'config.json');
+      expect(parseResult.errors).toHaveLength(0);
+
+      const validation = validateConfig(parseResult.config);
+      expect(validation.valid).toBe(true);
+
+      const merged = mergeConfig(parseResult.config);
+      expect(merged.docsRoute).toBe('/help');
+      expect(merged.theme?.primary).toBe('#0066cc');
+    });
+
+    it('should handle config with custom route mount point', () => {
+      const config = mergeConfig({
+        docsRoute: '/guides',
+        docsFolderPath: './guides',
+        basePath: '/guides',
+      });
+
+      expect(config.docsRoute).toBe('/guides');
+      expect(config.basePath).toBe('/guides');
+
+      // Validate the route
+      expect(validateRoute(config.docsRoute!)).toBe(true);
+
+      // Create route config
+      const routeConfig = createRouteConfig(config);
+      expect(routeConfig.docsRoute).toBe('/guides');
+    });
+
+    it('should build correct navigation links with custom route', () => {
+      const config = mergeConfig({ docsRoute: '/help' });
+      const docsRoute = config.docsRoute || '/docs';
+
+      const link1 = buildNavLink('setup', docsRoute);
+      expect(link1).toBe('/help/setup');
+
+      const link2 = buildNavLink('api/overview', docsRoute);
+      expect(link2).toBe('/help/api/overview');
+
+      const link3 = buildNavLink('', docsRoute);
+      expect(link3).toBe('/help');
+    });
+
+    it('should verify routes with custom mount point', () => {
+      const config = mergeConfig({ docsRoute: '/documentation' });
+      const docsRoute = config.docsRoute || '/docs';
+
+      expect(isDocsRoute('/documentation', docsRoute)).toBe(true);
+      expect(isDocsRoute('/documentation/api', docsRoute)).toBe(true);
+      expect(isDocsRoute('/help', docsRoute)).toBe(false);
+    });
+  });
+
+  describe('Theme Configuration Integration', () => {
+    it('should apply theme configuration from config file', () => {
+      const themeConfig = getThemeTemplate('default');
+      const cssVars = generateCSSVariables(themeConfig);
+
+      expect(cssVars['--color-primary']).toBeDefined();
+      expect(cssVars['--color-secondary']).toBeDefined();
+      expect(cssVars['--font-family-body']).toBeDefined();
+    });
+
+    it('should validate custom theme config', () => {
+      const config = mergeConfig({
+        theme: {
+          primary: '#ff0000',
+          secondary: '#00ff00',
+          fontFamily: 'Arial, sans-serif',
+        },
+      });
+
+      const themeValidation = validateTheme(config.theme!);
+      expect(themeValidation.valid).toBe(true);
+    });
+
+    it('should override default theme with config', () => {
+      const config = mergeConfig({
+        theme: {
+          primary: '#custom-color',
+        },
+      });
+
+      expect(config.theme?.primary).toBe('#custom-color');
+      // Should still have default secondary
+      expect(config.theme?.secondary).toBe(DEFAULT_CONFIG.theme?.secondary);
+    });
+
+    it('should generate CSS for theme customization', () => {
+      const darkTheme = getThemeTemplate('dark');
+      const cssVars = generateCSSVariables(darkTheme);
+
+      const stylesheet = Object.entries(cssVars)
+        .map(([key, value]) => `  ${key}: ${value};`)
+        .join('\n');
+
+      expect(stylesheet).toContain('--color-primary');
+      expect(stylesheet).toContain('--font-family');
+    });
+  });
+
+  describe('Navigation Configuration Integration', () => {
+    it('should generate navigation from config', () => {
+      const files = [
+        { path: 'docs/index.md', name: 'index', title: 'Home', isIndex: true },
+        { path: 'docs/setup.md', name: 'setup', title: 'Setup', isIndex: false },
+        { path: 'docs/api/overview.md', name: 'overview', title: 'Overview', isIndex: false },
+        { path: 'docs/api/reference.md', name: 'reference', title: 'Reference', isIndex: false },
+      ];
+
+      const nav = generateNavigationFromFiles(files, '/docs');
+      expect(nav.length).toBeGreaterThan(0);
+
+      // Should have an API section
+      const apiSection = nav.find((s) => s.title.includes('api') || s.title.includes('API'));
+      if (apiSection) {
+        expect(apiSection.items.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should respect exclude patterns in navigation', () => {
+      const configContent = JSON.stringify({
+        navigation: {
+          excludePaths: ['draft', 'private'],
+          autoGenerate: true,
+        },
+      });
+
+      const parseResult = parseConfigFile(configContent, 'config.json');
+      expect(parseResult.errors).toHaveLength(0);
+      expect(parseResult.config.navigation?.excludePaths).toEqual(['draft', 'private']);
+    });
+  });
+
+  describe('Multi-Route Configuration', () => {
+    it('should support switching between different doc routes', () => {
+      // Project 1: /docs route
+      const config1 = mergeConfig({ docsRoute: '/docs' });
+      expect(config1.docsRoute).toBe('/docs');
+      expect(isDocsRoute('/docs/setup', config1.docsRoute!)).toBe(true);
+      expect(isDocsRoute('/help/setup', config1.docsRoute!)).toBe(false);
+
+      // Project 2: /help route
+      const config2 = mergeConfig({ docsRoute: '/help' });
+      expect(config2.docsRoute).toBe('/help');
+      expect(isDocsRoute('/help/setup', config2.docsRoute!)).toBe(true);
+      expect(isDocsRoute('/docs/setup', config2.docsRoute!)).toBe(false);
+
+      // Project 3: /guides route
+      const config3 = mergeConfig({ docsRoute: '/guides' });
+      expect(config3.docsRoute).toBe('/guides');
+      expect(isDocsRoute('/guides/tutorial', config3.docsRoute!)).toBe(true);
+    });
+  });
+
+  describe('End-to-End Configuration Scenario', () => {
+    it('should handle a complete doc system setup', () => {
+      // Simulate loading a config file
+      const configJSON = JSON.stringify({
+        name: 'API Documentation',
+        docsRoute: '/api-docs',
+        docsFolderPath: './docs/api',
+        enableSearch: true,
+        layout: 'full-width',
+        theme: {
+          primary: '#2563eb',
+          secondary: '#dc2626',
+          fontFamily: 'Inter, sans-serif',
+          headingFont: 'Poppins, sans-serif',
+        },
+        navigation: {
+          title: 'API Reference',
+          autoGenerate: true,
+          excludePaths: ['examples', 'draft'],
+        },
+      });
+
+      // Parse the config
+      const parseResult = parseConfigFile(configJSON, 'config.json');
+      expect(parseResult.errors).toHaveLength(0);
+
+      // Validate it
+      const validation = validateConfig(parseResult.config);
+      expect(validation.valid).toBe(true);
+
+      // Merge with defaults
+      const finalConfig = mergeConfig(parseResult.config);
+
+      // Verify all parts work together
+      expect(finalConfig.name).toBe('API Documentation');
+      expect(finalConfig.docsRoute).toBe('/api-docs');
+      expect(finalConfig.enableSearch).toBe(true);
+      expect(finalConfig.layout).toBe('full-width');
+
+      // Verify theme
+      const themeValidation = validateTheme(finalConfig.theme!);
+      expect(themeValidation.valid).toBe(true);
+
+      const cssVars = generateCSSVariables(finalConfig.theme!);
+      expect(cssVars['--color-primary']).toBe('#2563eb');
+      expect(cssVars['--font-family-body']).toBe('Inter, sans-serif');
+
+      // Verify routing
+      const routeConfig = createRouteConfig(finalConfig);
+      expect(validateRoute(routeConfig.docsRoute)).toBe(true);
+
+      // Verify navigation config
+      expect(finalConfig.navigation?.title).toBe('API Reference');
+      expect(finalConfig.navigation?.excludePaths).toEqual(['examples', 'draft']);
+
+      // Verify navigation with custom route
+      const testLink = buildNavLink('endpoints/users', routeConfig.docsRoute);
+      expect(testLink).toBe('/api-docs/endpoints/users');
+
+      // Verify route detection
+      expect(isDocsRoute('/api-docs', routeConfig.docsRoute)).toBe(true);
+      expect(isDocsRoute('/api-docs/endpoints', routeConfig.docsRoute)).toBe(true);
+      expect(isDocsRoute('/docs', routeConfig.docsRoute)).toBe(false);
+    });
+  });
+
+  describe('Configuration Validation Scenarios', () => {
+    it('should reject invalid configurations', () => {
+      const invalidConfigs = [
+        { docsRoute: 123 }, // Not a string
+        { layout: 'invalid-layout' },
+        { defaultTheme: 'blue' }, // Invalid theme value
+        { theme: 'not-an-object' }, // Theme must be object
+      ];
+
+      invalidConfigs.forEach((config) => {
+        const validation = validateConfig(config);
+        expect(validation.valid).toBe(false);
+        expect(validation.errors.length).toBeGreaterThan(0);
+      });
+    });
+
+    it('should provide helpful error messages', () => {
+      const invalidConfig = {
+        layout: 'unknown',
+        defaultTheme: 'invalid',
+      };
+
+      const validation = validateConfig(invalidConfig);
+      expect(validation.errors.length).toBeGreaterThan(0);
+      expect(validation.errors.some((e) => e.includes('layout') || e.includes('defaultTheme'))).toBe(true);
+    });
+  });
+});

package/src/lib/configLoader.ts

@@ -0,0 +1,231 @@
+/**
+ * Configuration loader and manager
+ * Loads, validates, and manages the docs system configuration
+ */
+
+import type { ConfigOptions } from './config';
+import { DEFAULT_CONFIG, mergeConfig, validateConfig } from './config';
+import { parseConfigFile, loadConfigFile, parseFrontmatter } from './configParser';
+import { createRouteConfig, validateRoute } from './routing';
+import { validateTheme } from './themeCustomization';
+import { validateNavigation } from './navigationBuilder';
+
+export interface ConfigLoadResult {
+  success: boolean;
+  config: ConfigOptions;
+  errors: string[];
+  warnings: string[];
+  source: 'default' | 'loaded' | 'merged';
+}
+
+/**
+ * Load configuration from a file
+ */
+export async function loadConfiguration(
+  configPath: string = '/docs/_config.json'
+): Promise<ConfigLoadResult> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  let userConfig: ConfigOptions = {};
+
+  // Try to load the config file
+  const result = await loadConfigFile(configPath);
+
+  if (result.errors.length > 0 && !configPath.includes('_config')) {
+    // If it's not a standard config file, it might not exist - that's ok
+    errors.push(...result.errors);
+  } else if (result.errors.length > 0) {
+    // For standard config file, log errors but continue with defaults
+    warnings.push(...result.errors);
+  } else {
+    userConfig = result.config;
+  }
+
+  // Validate the loaded config
+  const validation = validateConfig(userConfig);
+  if (!validation.valid) {
+    warnings.push(...validation.errors);
+  }
+
+  // Validate sub-configs
+  if (userConfig.theme) {
+    const themeValidation = validateTheme(userConfig.theme);
+    if (!themeValidation.valid) {
+      warnings.push(`Theme validation errors: ${themeValidation.errors.join(', ')}`);
+    }
+  }
+
+  if (userConfig.navigation) {
+    const navValidation = validateNavigation(userConfig.navigation);
+    if (!navValidation.valid) {
+      warnings.push(`Navigation validation errors: ${navValidation.errors.join(', ')}`);
+    }
+  }
+
+  // Validate route
+  if (userConfig.docsRoute && !validateRoute(userConfig.docsRoute)) {
+    errors.push(`Invalid docsRoute: ${userConfig.docsRoute}`);
+  }
+
+  // Merge with defaults
+  const finalConfig = mergeConfig(userConfig, DEFAULT_CONFIG);
+
+  // Validate final config
+  const finalValidation = validateConfig(finalConfig);
+  if (!finalValidation.valid) {
+    errors.push(...finalValidation.errors);
+  }
+
+  const success = errors.length === 0;
+
+  return {
+    success,
+    config: finalConfig,
+    errors,
+    warnings,
+    source: success ? 'loaded' : warnings.length > 0 ? 'merged' : 'default',
+  };
+}
+
+/**
+ * Load and cache configuration (for browser environment)
+ */
+let cachedConfig: ConfigOptions | null = null;
+let configLoadPromise: Promise<ConfigLoadResult> | null = null;
+
+export async function getConfiguration(configPath: string = '/docs/_config.json'): Promise<ConfigOptions> {
+  if (cachedConfig) {
+    return cachedConfig;
+  }
+
+  if (!configLoadPromise) {
+    configLoadPromise = loadConfiguration(configPath);
+  }
+
+  const result = await configLoadPromise;
+  cachedConfig = result.config;
+  return result.config;
+}
+
+/**
+ * Clear configuration cache (useful for testing or reloading)
+ */
+export function clearConfigCache(): void {
+  cachedConfig = null;
+  configLoadPromise = null;
+}
+
+/**
+ * Parse frontmatter from markdown content and merge with config
+ */
+export function parseMarkdownFrontmatter(content: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+  errors: string[];
+} {
+  const result = parseFrontmatter(content);
+
+  if (result.error) {
+    return {
+      frontmatter: {},
+      body: result.body,
+      errors: [result.error],
+    };
+  }
+
+  return {
+    frontmatter: result.frontmatter || {},
+    body: result.body,
+    errors: [],
+  };
+}
+
+/**
+ * Validate a custom config object
+ */
+export function validateCustomConfig(config: unknown): { valid: boolean; errors: string[] } {
+  const validation = validateConfig(config);
+
+  if (!validation.valid) {
+    return validation;
+  }
+
+  const cfg = config as ConfigOptions;
+  const errors: string[] = [];
+
+  // Additional validations
+  if (cfg.theme) {
+    const themeValidation = validateTheme(cfg.theme);
+    if (!themeValidation.valid) {
+      errors.push(`Theme: ${themeValidation.errors.join(', ')}`);
+    }
+  }
+
+  if (cfg.navigation) {
+    const navValidation = validateNavigation(cfg.navigation);
+    if (!navValidation.valid) {
+      errors.push(`Navigation: ${navValidation.errors.join(', ')}`);
+    }
+  }
+
+  if (cfg.docsRoute && !validateRoute(cfg.docsRoute)) {
+    errors.push(`Invalid docsRoute: ${cfg.docsRoute}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Create a configuration from minimal user input
+ */
+export function createMinimalConfig(options: Partial<ConfigOptions> = {}): ConfigOptions {
+  return mergeConfig(options, DEFAULT_CONFIG);
+}
+
+/**
+ * Export configuration as JSON
+ */
+export function exportConfigAsJSON(config: ConfigOptions): string {
+  return JSON.stringify(config, null, 2);
+}
+
+/**
+ * Export configuration as YAML
+ */
+export function exportConfigAsYAML(config: ConfigOptions): string {
+  const lines: string[] = [];
+
+  function addValue(key: string, value: unknown, indent: number = 0): void {
+    const indentStr = '  '.repeat(indent);
+
+    if (value === null || value === undefined) {
+      return;
+    }
+
+    if (typeof value === 'string') {
+      lines.push(`${indentStr}${key}: ${value}`);
+    } else if (typeof value === 'boolean' || typeof value === 'number') {
+      lines.push(`${indentStr}${key}: ${value}`);
+    } else if (Array.isArray(value)) {
+      lines.push(`${indentStr}${key}:`);
+      value.forEach((item, idx) => {
+        if (typeof item === 'object') {
+          addValue(`- `, item, indent + 1);
+        } else {
+          lines.push(`${indentStr}  - ${item}`);
+        }
+      });
+    } else if (typeof value === 'object') {
+      lines.push(`${indentStr}${key}:`);
+      Object.entries(value).forEach(([k, v]) => {
+        addValue(k, v, indent + 1);
+      });
+    }
+  }
+
+  Object.entries(config).forEach(([key, value]) => {
+    addValue(key, value);
+  });
+
+  return lines.join('\n');
+}